feat(nuxt-doctor): wire --push flag to push privacy-stripped findings to the SaaS

Mirrors the vue-doctor --push implementation, adjusted for the Nuxt
audit pipeline:
  --push                 POST findings to the SaaS after the audit
  --push-url <url>       Endpoint (default: https://app.the-doctor.report/api/v1/findings)
  --api-key <key>        API key for the x-api-key header

The push runs after the audit and after the reporter renders. The
audit's exit code is unaffected by push failure: 5xx, network errors,
and abort timeouts all log a warning but do not flip the exit code.

9 e2e tests in tests/push.integration.test.ts use a real local HTTP
server (http.createServer().listen(0)) to capture the request and
assert the 6-field privacy boundary, the x-api-key header, the URL,
the CI env forwarding, and the singular/plural wording in the
success log.

Signed-off-by: Vinayak Kulkarni <19776877+vinayakkulkarni@users.noreply.github.com>

Author: vinayakkulkarni

packages/nuxt-doctor/README.md

@@ -59,6 +59,10 @@ nuxt-doctor --score
 | `--no-respect-inline-disables` | Surface findings even inside `doctor-disable` comments.                                                                |
 | `--threshold <n>`              | Minimum passing score, integer `0`–`100`.                                                                              |
 | `--score`                      | Print only the numeric score, for piping.                                                                              |
+| `--push`                       | After the audit, POST privacy-stripped findings to the SaaS. Requires `--api-key`. Negatable with `--no-push`.         |
+| `--no-push`                    | Skip the SaaS push (default).                                                                                          |
+| `--push-url <url>`             | SaaS endpoint for `--push` (default: `https://app.the-doctor.report/api/v1/findings`).                                 |
+| `--api-key <key>`              | API key for the SaaS, sent as the `x-api-key` header.                                                                  |
 | `--annotations`                | Emit GitHub Actions `::error::` / `::warning::` lines.                                                                 |
 | `--ci`                         | Auto-enable CI behavior (annotations on GitHub Actions).                                                               |
 | `--no-ci`                      | Disable CI auto-detection even when a CI env is set.                                                                   |

packages/nuxt-doctor/src/cli.ts

@@ -17,6 +17,7 @@ import {
   mergeCliOverrides,
   normalizeInitAnswers,
   planInit,
+  pushFindings,
   renderVerboseTrace,
   scoreDiagnostics,
   type AuditReport,
@@ -296,6 +297,9 @@ interface CliFlags {
   prComment?: string | true;
   fix?: boolean;
   fixExclude?: string | string[];
+  push?: boolean;
+  pushUrl: string;
+  apiKey?: string;
 }
 
 interface PreparedOptions {
@@ -493,6 +497,42 @@ function emitReport(
   }
 }
 
+async function maybePushFindings(
+  report: AuditReport,
+  flags: CliFlags,
+): Promise<void> {
+  if (flags.push !== true) return;
+  if (!flags.apiKey) {
+    process.stderr.write(
+      'nuxt-doctor: --push enabled but --api-key is not set; skipping push (no findings were sent).\n',
+    );
+    return;
+  }
+  const url = flags.pushUrl;
+  const project: string = 'nuxt-doctor';
+  const result = await pushFindings({
+    project,
+    score: report.score,
+    errorCount: report.errorCount,
+    warnCount: report.warnCount,
+    infoCount: report.infoCount,
+    diagnostics: report.diagnostics,
+    url,
+    apiKey: flags.apiKey,
+  });
+  if (result.ok) {
+    process.stderr.write(
+      `nuxt-doctor: pushed ${report.diagnostics.length} finding${report.diagnostics.length === 1 ? '' : 's'} to ${url} (HTTP ${result.status}).\n`,
+    );
+  } else {
+    const detail =
+      result.status !== undefined ? ` (HTTP ${result.status})` : '';
+    process.stderr.write(
+      `nuxt-doctor: --push failed${detail}: ${result.error}. Audit exit code is unchanged.\n`,
+    );
+  }
+}
+
 async function runProjectAudits(
   rootDir: string,
   flags: CliFlags,
@@ -714,6 +754,21 @@ export async function run(argv: string[] = process.argv): Promise<number> {
       '--fix-exclude <ruleId>',
       'Mark a rule as not-auto-fixable (repeatable). Note: oxlint applies built-in fixes globally, so this is enforced only for doctor plugin fixes; built-in vue/* fixes still apply.',
     )
+    .option(
+      '--push',
+      'After the audit, POST privacy-stripped findings to the SaaS. Requires --api-key. Negatable with --no-push.',
+    )
+    .option(
+      '--push-url <url>',
+      'SaaS endpoint for --push (default: https://app.the-doctor.report/api/v1/findings)',
+      {
+        default: 'https://app.the-doctor.report/api/v1/findings',
+      },
+    )
+    .option(
+      '--api-key <key>',
+      'API key for the SaaS (sent as the x-api-key header for both --score-mode and --push).',
+    )
     .action(async (path: string | undefined, flags: CliFlags) => {
       const reporter = resolveFormat(flags);
       if (flags.failOn !== undefined && !isFailOnLevel(flags.failOn)) {
@@ -806,10 +861,10 @@ export async function run(argv: string[] = process.argv): Promise<number> {
         }
         if (flags.score) {
           process.stdout.write(`${report.score}\n`);
-          process.exitCode = report.exitCode;
-          return;
+        } else {
+          emitReport(report, reporter, flags);
         }
-        emitReport(report, reporter, flags);
+        await maybePushFindings(report, flags);
         process.exitCode = report.exitCode;
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);