fix(cli): wire onNotice so migration prose is suppressed under --json, and share the whole-stdout envelope parser

Review feedback on #313:

1. init.ts's comment claimed this diff matches the verify/test convention
   of routing --json prose off stdout, but ensureTasklessDirectory(cwd) was
   called with no onNotice, so its migration notice always fell back to an
   unconditional console.error regardless of --json. verify.ts actually
   SUPPRESSES that notice entirely under --json (its info already lives on
   the envelope), matching EnsureOptions.onNotice's own doc comment. Wired
   the same onNotice here so the code matches what the comment says, added
   a regression test asserting stderr carries nothing about the migration
   under --json, and mutation-checked it (dropping the !json guard fails
   the new test; restoring it passes).

2. no-implicit-migration.test.ts's four JSON.parse(stdout.trim()) call
   sites (from a prior commit widening them off the old blind .at(-1) read)
   are now a single parseEnvelope<T> helper, documented the same way
   migrated-envelope.test.ts's version is, so the reasoning for whole-string
   parsing isn't duplicated four times without its rationale attached.
   Mutation-checked: reintroducing the original init --json stdout-prose bug
   fails both init --json tests in this file through the shared helper.

Author: theCodeDrift

packages/cli/src/commands/init.ts

@@ -257,9 +257,7 @@ async function runNonInteractive(
   // This per-target summary is not on that envelope (it is finer-grained than
   // `migrated`/`commandsInstalled`), so rather than drop it, it goes to
   // stderr — visible to a person watching the terminal, invisible to a
-  // machine consumer parsing stdout. Matches `ensureTasklessDirectory`'s own
-  // default (`runMigrations` falls back to `console.error`) and the
-  // `verify`/`test` convention of routing prose off stdout under `--json`.
+  // machine consumer parsing stdout.
   const log = options.json ? console.error : console.log;
   // Sampled BEFORE the directory is created, and that order is the whole
   // point. `ensureTasklessDirectory` mkdir -p's, so afterwards a pre-existing
@@ -274,7 +272,24 @@ async function runNonInteractive(
   // can report what a migration moved. `check`, `verify` and `test` used to
   // carry this on their own envelopes and refuse rather than migrate now, so
   // the field followed the behaviour rather than being dropped.
-  const migrated = await ensureTasklessDirectory(cwd);
+  //
+  // The migration notice is suppressed entirely under `--json`, rather than
+  // moved to stderr like the per-target summary above: unlike that summary,
+  // this information IS already on the envelope, as `migrated`, so printing
+  // it a second time would just be noise. This is the actual `verify`/`test`
+  // convention (`verify.ts`'s `onNotice: (message) => { if (!json)
+  // console.error(message); }`), and the case `EnsureOptions.onNotice`'s own
+  // doc comment describes: "callers that emit `--json` should pass a
+  // callback that suppresses output under that flag: the same information is
+  // on the envelope's `migrated` field". Omitting `onNotice` here, as before,
+  // left it on the default fallback (unconditional `console.error`), which
+  // never corrupts stdout but doesn't suppress the duplicate under `--json`
+  // either — the gap a reviewer of this PR caught.
+  const migrated = await ensureTasklessDirectory(cwd, {
+    onNotice: (message: string) => {
+      if (!options.json) console.error(message);
+    },
+  });
   if (wasNewProject) {
     // A project this CLI just created has no entries to walk: everything the
     // ledger describes is already true of the scaffold it wrote.

packages/cli/test/migrated-envelope.test.ts

@@ -129,6 +129,26 @@ describe("who migrates, and who refuses", () => {
     expectSeededMigration(envelope.migrated);
   });
 
+  it("init --json reports the migration on stdout and stays silent about it on stderr", async () => {
+    // The migration notice duplicates the envelope's `migrated` field, so
+    // under `--json` it is suppressed rather than moved to stderr - unlike
+    // the per-target install summary, which stderr DOES carry under `--json`
+    // because that detail has no field of its own. Catches a regression that
+    // routes this notice back through the unconditional `console.error`
+    // fallback `ensureTasklessDirectory` uses when no `onNotice` is passed.
+    await seedVersion3();
+
+    const { stderr } = await runCli([
+      "init",
+      "--no-interactive",
+      "--json",
+      "-d",
+      temporaryDirectory,
+    ]);
+
+    expect(stderr).not.toContain("Migrat");
+  });
+
   it("init --json omits the field when nothing migrated", async () => {
     // Absence is the signal, so a consumer never reads empty arrays to decide.
     await seedVersion3();

packages/cli/test/no-implicit-migration.test.ts

@@ -57,6 +57,21 @@ async function runCli(
   }
 }
 
+/**
+ * Parse `--json` stdout as the WHOLE envelope, not just its last line.
+ *
+ * The earlier shape of every call site here was
+ * `JSON.parse(stdout.trim().split("\n").at(-1) ?? "{}")`, and that is exactly
+ * why `init --json` printing prose ahead of its envelope (#279) went
+ * undetected: a helper that only ever reads the last line cannot fail on
+ * anything printed before it. `JSON.parse` on the trimmed whole string fails
+ * loudly the moment stdout carries a second thing, whichever end it lands on
+ * — do not narrow this back to a last-line read.
+ */
+function parseEnvelope<T>(stdout: string): T {
+  return JSON.parse(stdout.trim()) as T;
+}
+
 const FLAT_RULE =
   "id: no-eval\nlanguage: TypeScript\nseverity: error\nmessage: no eval\nrule:\n  pattern: eval($A)\n";
 
@@ -114,10 +129,10 @@ describe("a reporting command never migrates", () => {
     "%s --json carries the code an agent branches on",
     async (command) => {
       const { stdout } = await runCli([command, "--json", "-d", directory]);
-      const envelope = JSON.parse(stdout.trim()) as {
+      const envelope = parseEnvelope<{
         ok?: boolean;
         code?: string;
-      };
+      }>(stdout);
       expect(envelope.ok).toBe(false);
       // Distinct from SCAFFOLD_VERSION_MISMATCH, which is the opposite
       // direction and asks the caller to upgrade the CLI instead.
@@ -231,9 +246,9 @@ describe("a reporting command never migrates", () => {
       directory,
     ]);
 
-    const envelope = JSON.parse(stdout.trim()) as {
+    const envelope = parseEnvelope<{
       migrated?: { from: number; to: number };
-    };
+    }>(stdout);
     expect(envelope.migrated?.from).toBe(3);
     expect(envelope.migrated?.to).toBe(LATEST_SCHEMA_VERSION);
     await expect(
@@ -278,11 +293,11 @@ describe("a manifest that cannot be parsed", () => {
     "%s --json reports the file, not a version it guessed",
     async (command) => {
       const { stdout } = await runCli([command, "--json", "-d", directory]);
-      const envelope = JSON.parse(stdout.trim()) as {
+      const envelope = parseEnvelope<{
         ok?: boolean;
         code?: string;
         message?: string;
-      };
+      }>(stdout);
       expect(envelope.ok).toBe(false);
       expect(envelope.code).toBe("SCAFFOLD_MANIFEST_UNREADABLE");
       expect(envelope.message).toContain("taskless.json");
@@ -331,9 +346,9 @@ describe("a manifest that cannot be parsed", () => {
         "-d",
         bare,
       ]);
-      const envelope = JSON.parse(stdout.trim()) as {
+      const envelope = parseEnvelope<{
         migrated?: { from: number; to: number };
-      };
+      }>(stdout);
       expect(envelope.migrated?.from).toBe(0);
       expect(envelope.migrated?.to).toBe(LATEST_SCHEMA_VERSION);
     } finally {