feat(publish): Add --dry-run and --json flag to yarn npm publish (#6850)

## What's the problem this PR addresses?

Addresses #6849 

## How did you fix it?

Full disclosure, used Github Copilot Agent Mode to generate most of this
PR here --> Saadnajmi#2
Since then, lots more manual edits on my side. I took some spirit from
#3404 and `pack.ts` to determine
how to print paths and when to call `report.reportInfo` vs
`report.reportJson`.

This adds a couple of flags to `yarn npm publish`, so that it matches
other package managers like `pnpm` and `bun`, and is thus easier for
tools like `nx release` to use (see
nrwl/nx#29242 ). We add

 - `--dry-run` (Bails out right before the final publish to NPM)
 - `--json` (This takes advantage of StreamReports JSON config)
 
 Using both flags together looks something like this:
 
 ```shell
sanajmi@Mac foo % yarn npm publish --dry-run       
➤ YN0000: README.md
➤ YN0000: bar.js
➤ YN0000: package.json
➤ YN0000: xyz.js
➤ YN0000: [DRY RUN] Package would be published to
https://registry.yarnpkg.com with tag latest
➤ YN0000: Done in 0s 13ms

sanajmi@Mac foo % yarn npm publish --dry-run --json
{"file":"README.md"}
{"file":"bar.js"}
{"file":"package.json"}
{"file":"xyz.js"}

{"name":"foo","version":"1.0.0","registry":"https://registry.yarnpkg.com","tag":"latest","files":["README.md","bar.js","package.json","xyz.js"],"access":null,"dryRun":true,"published":false,"message":"[DRY
RUN] Package would be published to https://registry.yarnpkg.com with tag
latest","provenance":false,"gitHead":"d4f82af6fdb7f2f81c5910535900c5ad8a70a019"}
 ```

## Checklist

- [x] I have read the [Contributing
Guide](https://yarnpkg.com/advanced/contributing).

(TODO)

<!-- See
https://yarnpkg.com/advanced/contributing#preparing-your-pr-to-be-released
for more details. -->
<!-- Check with `yarn version check` and fix with `yarn version check
-i` -->
- [ ] I have set the packages that need to be released for my changes to
be effective.

<!-- The "Testing chores" workflow validates that your PR follows our
guidelines. -->
<!-- If it doesn't pass, click on it to see details as to what your PR
might be missing. -->
- [ ] I will check that all automated PR checks pass before the PR gets
reviewed.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Saadnajmi <[email protected]>

Author: Saadnajmi

.yarn/versions/4c28a2b4.yml

@@ -0,0 +1,23 @@
+releases:
+  "@yarnpkg/cli": patch
+  "@yarnpkg/plugin-npm-cli": minor
+
+declined:
+  - "@yarnpkg/plugin-compat"
+  - "@yarnpkg/plugin-constraints"
+  - "@yarnpkg/plugin-dlx"
+  - "@yarnpkg/plugin-essentials"
+  - "@yarnpkg/plugin-init"
+  - "@yarnpkg/plugin-interactive-tools"
+  - "@yarnpkg/plugin-nm"
+  - "@yarnpkg/plugin-pack"
+  - "@yarnpkg/plugin-patch"
+  - "@yarnpkg/plugin-pnp"
+  - "@yarnpkg/plugin-pnpm"
+  - "@yarnpkg/plugin-stage"
+  - "@yarnpkg/plugin-typescript"
+  - "@yarnpkg/plugin-version"
+  - "@yarnpkg/plugin-workspace-tools"
+  - "@yarnpkg/builder"
+  - "@yarnpkg/core"
+  - "@yarnpkg/doctor"

packages/acceptance-tests/pkg-tests-specs/sources/commands/publish.test.ts

@@ -2,6 +2,7 @@ import {npath, xfs} from '@yarnpkg/fslib';
 
 const {
   tests: {testIf},
+  misc,
 } = require(`pkg-tests-core`);
 
 const {
@@ -89,6 +90,41 @@ describe(`publish`, () =>   {
     });
   }));
 
+  test(`should support --dry-run flag`, makeTemporaryEnv({
+    name: `dry-run-test`,
+    version: `1.0.0`,
+  }, async ({path, run, source}) => {
+    await run(`install`);
+
+    const {stdout} = await run(`npm`, `publish`, `--dry-run`, `--tolerate-republish`);
+    expect(stdout).toContain(`[DRY RUN]`);
+  }));
+
+  test(`should support --json flag`, makeTemporaryEnv({
+    name: `json-test`,
+    version: `1.0.0`,
+  }, async ({path, run, source}) => {
+    await run(`install`);
+
+    const {stdout} = await run(`npm`, `publish`, `--json`, `--dry-run`, `--tolerate-republish`);
+    const jsonObjects = misc.parseJsonStream(stdout);
+    const result = jsonObjects.find((obj: any) => obj.name && obj.version);
+
+    expect(result).toBeDefined();
+    expect(result).toHaveProperty(`name`, `json-test`);
+    expect(result).toHaveProperty(`version`, `1.0.0`);
+    expect(result).toHaveProperty(`dryRun`, true);
+    expect(result).toHaveProperty(`registry`);
+    expect(result).toHaveProperty(`published`, false);
+    expect(result).toHaveProperty(`message`);
+
+    expect(result).toHaveProperty(`tag`);
+    expect(result).toHaveProperty(`provenance`);
+
+    expect(result).toHaveProperty(`files`);
+    expect(Array.isArray(result.files)).toBe(true);
+  }));
+
   testIf(
     () => !!process.env.ACTIONS_ID_TOKEN_REQUEST_URL,
     `should publish a package with a valid provenance statement`,

packages/plugin-npm-cli/sources/commands/npm/publish.ts

@@ -1,5 +1,6 @@
 import {BaseCommand, WorkspaceRequiredError}                                                    from '@yarnpkg/cli';
 import {Configuration, MessageName, Project, ReportError, StreamReport, scriptUtils, miscUtils} from '@yarnpkg/core';
+import {npath}                                                                                  from '@yarnpkg/fslib';
 import {npmConfigUtils, npmHttpUtils, npmPublishUtils}                                          from '@yarnpkg/plugin-npm';
 import {packUtils}                                                                              from '@yarnpkg/plugin-pack';
 import {Command, Option, Usage, UsageError}                                                     from 'clipanion';
@@ -46,6 +47,14 @@ export default class NpmPublishCommand extends BaseCommand {
     description: `Generate provenance for the package. Only available in GitHub Actions and GitLab CI. Can be set globally through the \`npmPublishProvenance\` setting or the \`YARN_NPM_CONFIG_PROVENANCE\` environment variable, or per-package through the \`publishConfig.provenance\` field in package.json.`,
   });
 
+  dryRun = Option.Boolean(`-n,--dry-run`, false, {
+    description: `Show what would be published without actually publishing`,
+  });
+
+  json = Option.Boolean(`--json`, false, {
+    description: `Output the result in JSON format`,
+  });
+
   async execute() {
     const configuration = await Configuration.find(this.context.cwd, this.context.plugins);
     const {project, workspace} = await Project.find(configuration, this.context.cwd);
@@ -69,6 +78,7 @@ export default class NpmPublishCommand extends BaseCommand {
     const report = await StreamReport.start({
       configuration,
       stdout: this.context.stdout,
+      json: this.json,
     }, async report => {
       // Not an error if --tolerate-republish is set
       if (this.tolerateRepublish) {
@@ -84,7 +94,15 @@ export default class NpmPublishCommand extends BaseCommand {
             throw new ReportError(MessageName.REMOTE_INVALID, `Registry returned invalid data for - missing "versions" field`);
 
           if (Object.hasOwn(registryData.versions, version)) {
-            report.reportWarning(MessageName.UNNAMED, `Registry already knows about version ${version}; skipping.`);
+            const warning = `Registry already knows about version ${version}; skipping.`;
+            report.reportWarning(MessageName.UNNAMED, warning);
+            report.reportJson({
+              name: ident.name,
+              version,
+              registry,
+              warning,
+              skipped: true,
+            });
             return;
           }
         } catch (err) {
@@ -99,28 +117,38 @@ export default class NpmPublishCommand extends BaseCommand {
       await packUtils.prepareForPack(workspace, {report}, async () => {
         const files = await packUtils.genPackList(workspace);
 
-        for (const file of files)
-          report.reportInfo(null, file);
+        for (const file of files) {
+          report.reportInfo(null, npath.fromPortablePath(file));
+          report.reportJson({file: npath.fromPortablePath(file)});
+        }
 
         const pack = await packUtils.genPackStream(workspace, files);
         const buffer = await miscUtils.bufferStream(pack);
 
         const gitHead = await npmPublishUtils.getGitHead(workspace.cwd);
 
         let provenance = false;
+        let provenanceMessage = ``;
         if (workspace.manifest.publishConfig && `provenance` in workspace.manifest.publishConfig) {
           provenance = Boolean(workspace.manifest.publishConfig.provenance);
-          if (provenance) {
-            report.reportInfo(null, `Generating provenance statement because \`publishConfig.provenance\` field is set.`);
-          } else {
-            report.reportInfo(null, `Skipping provenance statement because \`publishConfig.provenance\` field is set to false.`);
-          }
+          provenanceMessage = provenance
+            ? `Generating provenance statement because \`publishConfig.provenance\` field is set.`
+            : `Skipping provenance statement because \`publishConfig.provenance\` field is set to false.`;
         } else if (this.provenance) {
           provenance = true;
-          report.reportInfo(null, `Generating provenance statement because \`--provenance\` flag is set.`);
+          provenanceMessage = `Generating provenance statement because \`--provenance\` flag is set.`;
         } else if (configuration.get(`npmPublishProvenance`)) {
           provenance = true;
-          report.reportInfo(null, `Generating provenance statement because \`npmPublishProvenance\` setting is set.`);
+          provenanceMessage = `Generating provenance statement because \`npmPublishProvenance\` setting is set.`;
+        }
+
+        if (provenanceMessage) {
+          report.reportInfo(null, provenanceMessage);
+          report.reportJson({
+            type: `provenance`,
+            enabled: provenance,
+            provenanceMessage,
+          });
         }
 
         const body = await npmPublishUtils.makePublishBody(workspace, buffer, {
@@ -131,16 +159,34 @@ export default class NpmPublishCommand extends BaseCommand {
           provenance,
         });
 
-        await npmHttpUtils.put(npmHttpUtils.getIdentUrl(ident), body, {
-          configuration,
+        if (!this.dryRun) {
+          await npmHttpUtils.put(npmHttpUtils.getIdentUrl(ident), body, {
+            configuration,
+            registry,
+            ident,
+            otp: this.otp,
+            jsonResponse: true,
+          });
+        }
+
+        const finalMessage = this.dryRun
+          ? `[DRY RUN] Package would be published to ${registry} with tag ${this.tag}`
+          : `Package archive published`;
+
+        report.reportInfo(MessageName.UNNAMED, finalMessage);
+        report.reportJson({
+          name: ident.name,
+          version,
           registry,
-          ident,
-          otp: this.otp,
-          jsonResponse: true,
+          tag: this.tag || `latest`,
+          files: files.map(f => npath.fromPortablePath(f)),
+          access: this.access || null,
+          dryRun: this.dryRun,
+          published: !this.dryRun,
+          message: finalMessage,
+          provenance: Boolean(provenance),
         });
       });
-
-      report.reportInfo(MessageName.UNNAMED, `Package archive published`);
     });
 
     return report.exitCode();