fix(cli): keep the --write hunks in meta.ts small; pin the failure exits

The human report keeps its indentation (a --write failure exits from inside
the try, and the catch rethrows an oclif exit), so a later merge of main
reconciles cleanly. The pins hold that --write writes exactly the applied set,
that semantic TODOs are listed as the dry run lists them (not a pinned
listing), and that both failure exits leave no file half-written.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RWZbGvPFcRKvUqASZtunCU

Author: claude

.changeset/9591-migrate-meta-write.md

@@ -7,7 +7,7 @@
 Clause-②: yes (widening)
 
 - A new flag on the authored-source mode: `os migrate meta --from N --write`. Without it nothing changes: the dry run, its report and its `--json` payload are what they were, and `--out` still writes its snapshot.
-- What it writes: each mechanical change the chain applied (`applied`), at a site it traces to one object or array literal in one project file — through `define*` calls and `<spec export>.create(…)` factories, module-level `const` bindings, relative imports and re-exports, and `Object.values()` over a namespace import — when the loaded value matches that literal and nothing else references the bindings on the way. Only that site's bytes change: a renamed key keeps its value and its comments, a removed key takes its own line(s), and every other byte (comments, formatting, key order) stays as it was.
+- What it writes: each mechanical change the chain applied (`applied`), at a site it traces to one object or array literal in one project file — through `define*` calls and the `.create(…)` factories `@objectstack/spec` exports, module-level `const` bindings, relative imports and re-exports, and `Object.values()` over a namespace import — when the loaded value matches that literal and nothing else references the bindings on the way. Only that site's bytes change: a renamed key keeps its value and its comments, a removed key takes its own line(s), and every other byte (comments, formatting, key order) stays as it was.
 - What it refuses, each change listed with the reason (`--json`: `write.manual[].kind`): `computed`, `helper`, `spread`, `shared`, `outside-project`, `mismatch`, `injected`, `unspellable`, `layout` and `unattributed`; and `entangled`, because a conversion's edits are written whole or not at all.
 - What it never writes: the semantic changes (`todos`), which stay listed exactly as before, and a site a conversion declines, for which no mechanical change exists.
 - After writing it re-runs the chain over the written sources. Unless the re-run applies exactly the changes it left, it restores every file it wrote and exits 1.

packages/cli/src/commands/migrate/meta.ts

@@ -741,7 +741,6 @@ export default class MigrateMeta extends Command {
 
     if (!flags.json) printHeader('Migrate · meta');
 
-    let exitCode = 0;
     try {
       if (!flags.json) printStep('Loading configuration…');
       // `authoredSource`: read the config as the author WROTE it, not as the
@@ -789,7 +788,6 @@ export default class MigrateMeta extends Command {
             json: Boolean(flags.json),
           })
         : undefined;
-      if (write && write.status !== 'written') exitCode = 1;
 
       if (flags.json) {
         await emitJson({
@@ -826,35 +824,41 @@ export default class MigrateMeta extends Command {
               duration: timer.elapsed(),
             });
         if (flags.out) writeFileSync(resolve(flags.out), JSON.stringify(result.stack, null, 2));
-      } else {
-        printInfo(`Config: ${chalk.white(absolutePath)}`);
-        // State this build's protocol major in the protocol's own units.
-        // `PROTOCOL_VERSION` is that major padded to a semver ('17.0.0'), never
-        // the installed package version -- printed as a bare semver under the
-        // word "runtime" it read as one, so on a 17.3.0 install the operator saw
-        // an apparent downgrade next to the real package versions of the same
-        // upgrade session. The fact itself is worth keeping: with `--to` below
-        // this build's major it is the only line saying where the runtime
-        // actually stands. So it is relabelled and de-padded, not dropped.
-        printInfo(`Chain:  protocol ${fromMajor} → ${toMajor} (this runtime implements protocol ${PROTOCOL_MAJOR})`);
-        console.log('');
-
-        // The verdict and the refusals lead, then the applied edits, then the
-        // semantic notices — see printMigrationReport for why, and for what it
-        // must never do to a notice.
-        printMigrationReport({
-          result,
-          normalized,
-          schemaValid: parsed.success,
-          refusals: parsed.success ? [] : parsed.error.issues,
-          dataMigrations,
-          step: flags.step,
-          ...(flags.out ? { out: resolve(flags.out) } : {}),
-          ...(write ? { write } : {}),
-          elapsed: timer.display(),
-        });
+        if (write && write.status !== 'written') this.exit(1);
+        return;
       }
+
+      printInfo(`Config: ${chalk.white(absolutePath)}`);
+      // State this build's protocol major in the protocol's own units.
+      // `PROTOCOL_VERSION` is that major padded to a semver ('17.0.0'), never
+      // the installed package version -- printed as a bare semver under the
+      // word "runtime" it read as one, so on a 17.3.0 install the operator saw
+      // an apparent downgrade next to the real package versions of the same
+      // upgrade session. The fact itself is worth keeping: with `--to` below
+      // this build's major it is the only line saying where the runtime
+      // actually stands. So it is relabelled and de-padded, not dropped.
+      printInfo(`Chain:  protocol ${fromMajor} → ${toMajor} (this runtime implements protocol ${PROTOCOL_MAJOR})`);
+      console.log('');
+
+      // The verdict and the refusals lead, then the applied edits, then the
+      // semantic notices — see printMigrationReport for why, and for what it
+      // must never do to a notice.
+      printMigrationReport({
+        result,
+        normalized,
+        schemaValid: parsed.success,
+        refusals: parsed.success ? [] : parsed.error.issues,
+        dataMigrations,
+        step: flags.step,
+        ...(flags.out ? { out: resolve(flags.out) } : {}),
+        ...(write ? { write } : {}),
+        elapsed: timer.display(),
+      });
+      // A write refused or undone is a failed run, reported above.
+      if (write && write.status !== 'written') this.exit(1);
     } catch (error: any) {
+      // `this.exit()` throws; a `--write` failure exits from inside the try.
+      if (typeof error?.oclif?.exit === 'number') throw error;
       if (error instanceof MigrationFloorError) {
         if (flags.json) {
           await emitJson({ error: 'unsupported_from_major', message: error.message }, 0, { compact: true });
@@ -874,9 +878,6 @@ export default class MigrateMeta extends Command {
       if (!isReportedError(error)) printError(error.message || String(error));
       this.exit(1);
     }
-    // Decided inside, exited outside: `this.exit()` throws, and the catch above
-    // would report that throw as a bare "EEXIT: 1".
-    if (exitCode !== 0) this.exit(exitCode);
   }
 
   /**

packages/cli/test/migrate-meta-write.test.ts

@@ -31,7 +31,7 @@
  */
 
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
-import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
 import { createRequire } from 'node:module';
@@ -42,9 +42,27 @@ import MigrateMeta from '../src/commands/migrate/meta.js';
 import {
   planAuthoredSourceWrite,
   verifyAuthoredSourceWrite,
+  type AuthoredSourceWritePlan,
   type CodemodRefusalKind,
 } from '../src/utils/authored-source-codemod.js';
 
+/**
+ * A seam between planning and writing, for the two failure exits: the command
+ * runs the real planner, and a test may act on the plan before the write.
+ */
+const hooks = vi.hoisted(() => ({ afterPlan: undefined as undefined | ((plan: AuthoredSourceWritePlan) => void) }));
+vi.mock('../src/utils/authored-source-codemod.js', async (importActual) => {
+  const actual = await importActual<typeof import('../src/utils/authored-source-codemod.js')>();
+  return {
+    ...actual,
+    planAuthoredSourceWrite: async (input: Parameters<typeof actual.planAuthoredSourceWrite>[0]) => {
+      const plan = await actual.planAuthoredSourceWrite(input);
+      hooks.afterPlan?.(plan);
+      return plan;
+    },
+  };
+});
+
 const CLI_ROOT = resolve(fileURLToPath(import.meta.url), '..', '..');
 const CODEMOD_SOURCE = resolve(fileURLToPath(import.meta.url), '..', '..', 'src', 'utils', 'authored-source-codemod.ts');
 const RUN_TIMEOUT = 120_000;
@@ -352,12 +370,20 @@ describe('os migrate meta --write over per-artifact modules', () => {
     expect(at['views[0].list.bordered']).toBe('src/views/ticket.view.ts:10');
   });
 
-  it('never writes a semantic TODO: the manual list is the dry run\'s, unchanged', () => {
+  it('writes the applied set and nothing else: every site it reports is an applied entry', () => {
+    // What `--write` writes or leaves is exactly the chain's `applied` set —
+    // never a semantic TODO, which the planner is not even handed.
+    expect(sites([...firstJson.write.written, ...firstJson.write.manual])).toEqual(sites(firstJson.applied));
+  });
+
+  it('never writes a semantic TODO, and lists them as the dry run does', () => {
+    // Relative to the dry run of the same build, not a pinned listing: which
+    // notices the default list carries is the chain's business, not --write's.
     expect(firstJson.todos.map((t: any) => t.id)).toEqual(dry.todos.map((t: any) => t.id));
-    expect(firstJson.todos.length).toBeGreaterThan(0);
-    // The declined `compareTo` arm keeps its bytes and its schema refusal.
+    // The `compareTo` arm the conversion declines has no mechanical change, so
+    // its bytes stay — and the schema still refuses it, as before the write.
     expect(readFileSync(join(dir, 'src/dashboards/kpi.dashboard.ts'), 'utf8')).toContain("compareTo: { offset: '7d' }");
-    expect(firstJson.todos.map((t: any) => t.id)).toContain('dashboard-widget-compareto-offset');
+    expect(firstJson.schemaValid).toBe(false);
   });
 
   it('is idempotent: a second run applies nothing and writes nothing', async () => {
@@ -461,6 +487,49 @@ describe('os migrate meta --write adds a key where the conversion adds one', ()
   }, RUN_TIMEOUT);
 });
 
+// ── the two failure exits: nothing is left half-written ─────────────────────
+
+describe('os migrate meta --write fails closed', () => {
+  it('writes nothing, and exits 1, when a file changed after it was read', async () => {
+    const dir = writeProject(PROJECT);
+    let touched = '';
+    hooks.afterPlan = (plan) => {
+      touched = plan.rewrites[0]!.path;
+      writeFileSync(touched, `${readFileSync(touched, 'utf8')}// edited meanwhile\n`);
+    };
+    let run: Run;
+    try {
+      run = await runMeta(dir, ['--write', '--json']);
+    } finally {
+      hooks.afterPlan = undefined;
+    }
+    expect(run.exitCode).toBe(1);
+    const payload = json(run);
+    expect(payload.write.status).toBe('unwritten');
+    expect(payload.write.error).toMatch(/changed on disk/);
+    const rel = relative(realpathSync(dir), touched).split('\\').join('/');
+    expect(snapshot(dir)).toEqual({ ...PROJECT, [rel]: `${PROJECT[rel]}// edited meanwhile\n` });
+  }, RUN_TIMEOUT);
+
+  it('restores every file, and exits 1, when the re-run disagrees with its report', async () => {
+    const dir = writeProject(PROJECT);
+    // A report claiming one more site left by hand than the chain will find.
+    hooks.afterPlan = (plan) => {
+      plan.manual.push({ application: applied('nowhere.at.all', 'probe-phantom'), refusal: { kind: 'computed', reason: 'r' } });
+    };
+    let run: Run;
+    try {
+      run = await runMeta(dir, ['--write']);
+    } finally {
+      hooks.afterPlan = undefined;
+    }
+    expect(run.exitCode).toBe(1);
+    expect(run.stdout).toContain('every one was restored to its previous bytes');
+    expect(run.stdout).toContain('no longer converted: nowhere.at.all (probe-phantom)');
+    expect(snapshot(dir)).toEqual(PROJECT);
+  }, RUN_TIMEOUT);
+});
+
 // ── 5: the refusals a real project produces ─────────────────────────────────
 
 const REFUSALS: Record<string, string> = {