@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/clients/cli/commands/theme-add.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme add',
   displayName: 'astryx theme add',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Scaffold a theme into your project as editable source',
   description:
     "Copies a bundled or installed integration theme's source into your project so you own it. " +
@@ -28,7 +28,8 @@ export const doc = {
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description: 'Overwrite existing files without prompting',
+      description:
+        'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',
     },
     {flag: '--list', description: 'List available themes'},
     {
@@ -48,7 +49,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown or ambiguous theme, a path escape, a missing catalog file, or an existing file without --overwrite',
+      when: 'unknown or ambiguous theme, a path escape, a missing descriptor or source, or an existing file without --overwrite',
     },
   ],
   related: ['theme list', 'theme build'],

package/clients/cli/commands/theme-build.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme build',
   displayName: 'astryx theme build',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Compile standalone themes or one keyed theme family',
   description:
     'Compiles defineTheme() sources through the same theme pipeline into scoped CSS, ' +
@@ -28,34 +28,35 @@ export const doc = {
     {
       flag: '--family',
       description:
-        'Build the selected extension family into one keyed CSS, JS, and declaration set',
+        'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
     },
     {
       flag: '--family-key <key>',
       description:
-        'Lower-kebab filename stem required with --family; must differ from every member name',
+        'Lower-kebab filename stem required with --family and refused without it; must differ from every member name (ERR_THEME_INVALID)',
     },
     {
       flag: '-o, --out <path>',
       param: 'options.out',
-      description: 'Output CSS file path (single theme only)',
+      description:
+        'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
     },
     {
       flag: '--icons-specifier <specifier>',
       param: 'options.iconsSpecifier',
       description:
-        'Override the icon-registry import in the generated JS module (for example, ./icons.mjs)',
+        "Override the icon-registry import in the generated JS module, for example ./icons.mjs (default: the specifier in the theme source's own import). With --family it applies to every member's icon import",
     },
     {
       flag: '-w, --watch',
       description:
-        'Rebuild automatically when a theme file changes (Ctrl-C to stop)',
+        'Rebuild automatically when a theme file changes (Ctrl-C to stop). Refused with --check, --family, or --json (ERR_THEME_INVALID)',
     },
     {
       flag: '-c, --check',
       param: 'options.check',
       description:
-        'Verify the committed outputs match the source without writing; exit non-zero if stale',
+        'Verify the committed outputs match the source without writing; exit non-zero if stale. Composes with --family and several files; refused with --watch (ERR_THEME_INVALID)',
     },
   ],
   examples: [

package/clients/cli/commands/theme-list.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme list',
   displayName: 'astryx theme list',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List themes available to add',
   description:
     'Lists themes bundled with this CLI and source themes contributed by installed integrations, ' +
@@ -37,7 +37,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'the bundled-theme manifest or an installed theme catalog cannot be read',
+      when: 'a bundled or installed theme descriptor cannot be read',
     },
   ],
   related: ['theme add', 'theme build'],

package/clients/cli/commands/theme-palette-generate.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'theme palette generate',
   displayName: 'astryx theme palette generate',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Generate an OKLCH palette candidate for human review',
   description:
     'Reads an explicit JSON request and runs the versioned astryx-oklch-v1 recipe. ' +
@@ -18,7 +18,11 @@ export const doc = {
     'Without --out it prints a preview. With --out it writes a candidate file and detached ' +
     'receipt. --preview writes a standardized, self-contained HTML review artifact. ' +
     'TypeScript output is directly importable and contains no generator dependency. ' +
-    'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit.',
+    'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit. ' +
+    'When used in a theme integration, keep the palette request under the theme slug, ' +
+    'write the candidate and receipt under that same slug, import the candidate from the theme source, ' +
+    'and keep all three inside the theme directory: `astryx theme add` copies that whole ' +
+    'directory into the consumer project, so nothing else has to list them.',
   fn: 'themePaletteGenerate',
   args: [{name: 'config', param: 'configPath', required: true}],
   options: [
@@ -42,15 +46,15 @@ export const doc = {
   examples: [
     {
       label: 'Preview candidate JSON',
-      cli: 'astryx theme palette generate palette.config.json',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json',
     },
     {
       label: 'Write candidate and receipt',
-      cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts',
     },
     {
       label: 'Write candidate, receipt, and review preview',
-      cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts --preview ocean.palette.html',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts --preview themes/ocean/tokens/ocean.palette.html',
     },
   ],
   exitCodes: [

package/clients/cli/commands/theme-palette-generate.test.mjs

@@ -132,4 +132,23 @@ describe('astryx theme palette generate', () => {
       code: 'ERR_PALETTE_GENERATION',
     });
   });
+
+  it('returns ERR_WRITE_FAILED for an output path it cannot use', async () => {
+    fs.writeFileSync(path.join(temporaryDirectory, 'blocker'), '');
+    const {status, stdout} = await runCli(
+      [
+        '--json',
+        'theme',
+        'palette',
+        'generate',
+        'palette.config.json',
+        '--out',
+        'blocker/ocean.palette.ts',
+      ],
+      {cwd: temporaryDirectory},
+    );
+
+    expect(status).toBe(1);
+    expect(JSON.parse(stdout)).toMatchObject({code: 'ERR_WRITE_FAILED'});
+  });
 });

package/clients/cli/commands/theme-palette.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'theme palette',
   displayName: 'astryx theme palette',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Create and work with theme-owned color palettes',
   description:
     'Palette authoring tools. The initial generate command creates reviewable candidates. ' +

package/clients/cli/commands/theme-targets.behavior.test.mjs

@@ -17,8 +17,9 @@ describe('astryx theme targets', () => {
     const {status, stdout} = await runCli(['theme', 'targets', 'Switch']);
 
     expect(status).toBe(0);
-    expect(stdout).toMatch(/^switch\s+Switch\s+size\s+checked, disabled$/m);
-    expect(stdout).toMatch(/^switch-thumb\s+Switch\s+size\s+checked$/m);
+    // Inline layout: key  component - props - states - className
+    expect(stdout).toMatch(/^switch\s+Switch - size - checked, disabled - astryx-switch$/m);
+    expect(stdout).toMatch(/^switch-thumb\s+Switch - size - checked - astryx-switch-thumb$/m);
     expect(stdout).toMatch(/4 across 1 component/);
   });
 
@@ -28,7 +29,7 @@ describe('astryx theme targets', () => {
     expect(status).toBe(0);
     expect(stdout).toMatch(/^popover\s{2,}Popover/m);
     expect(stdout).toMatch(
-      /^popover-surface \[deprecated; use popover\]\s{2,}Popover/m,
+      /^popover-surface\s{2,}Popover - astryx-popover-surface - deprecated; use popover$/m,
     );
   });
 

package/clients/cli/commands/theme-targets.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme targets',
   displayName: 'astryx theme targets',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List the component theming targets a theme can override',
   description:
     'Prints every `defineTheme` components key across the system: the stable class it paints, ' +

package/clients/cli/commands/theme-template.behavior.test.mjs

@@ -82,4 +82,16 @@ describe('astryx theme template', () => {
     expect(stderr).toMatch(/outside the project root/);
     expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.ts'))).toBe(false);
   });
+
+  it('fails a write with ERR_WRITE_FAILED under --json', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'blocker'), '');
+
+    const {status, stdout} = await runCli(
+      ['--json', 'theme', 'template', 'blocker/theme.ts'],
+      {cwd: tmpDir},
+    );
+
+    expect(status).toBe(1);
+    expect(JSON.parse(stdout).code).toBe('ERR_WRITE_FAILED');
+  });
 });

package/clients/cli/commands/theme-template.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme template',
   displayName: 'astryx theme template',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Write the annotated theme template into your project',
   description:
     'Writes theme.template.ts: the annotated reference for the whole theme surface, covering every ' +
@@ -36,7 +36,7 @@ export const doc = {
   ],
   exitCodes: [
     {code: 0, when: 'success, including when an existing file was left untouched'},
-    {code: 1, when: 'the target path escapes the project'},
+    {code: 1, when: 'the target path escapes the project, or the file cannot be written'},
   ],
   related: ['theme add', 'theme list', 'theme build'],
 };

package/clients/cli/commands/theme.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'theme',
   displayName: 'astryx theme',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Theme tools: build, export, and manage themes',
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +

package/clients/cli/commands/upgrade.ascii-output.test.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` human output is plain ASCII on every path: the codemod
+ * list, up to date, an empty range, a dry run, and an apply that runs a
+ * post-codemod hook and refreshes the agent docs.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {generateCompressedIndex} from '../../../foundation/agent-docs/agent-docs.mjs';
+
+const NON_ASCII = /[\u0080-\uFFFF]/;
+
+let tmpDir;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(tmpDir, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+/**
+ * Output lines (stdout and stderr) that contain a non-ASCII character.
+ * @param {string[]} args
+ */
+async function nonAsciiLines(args) {
+  const r = await runCli(args, {cwd: tmpDir});
+  expect(r.status).toBe(0);
+  return `${r.stdout}\n${r.stderr}`
+    .split('\n')
+    .filter(line => NON_ASCII.test(line));
+}
+
+beforeEach(() => {
+  // Repo-local so the config module can be imported under Vitest.
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-upgrade-ascii-'));
+  write('package.json', JSON.stringify({name: 'consumer', private: true}));
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
+  );
+  write(
+    'src/panel.tsx',
+    "import {useResizable} from '@astryxdesign/core';\n" +
+      'export const usePanel = () => useResizable({defaultSize: 250, minSizePx: 200});\n',
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('upgrade human output is ASCII', () => {
+  it('lists codemods', async () => {
+    expect(await nonAsciiLines(['upgrade', '--list'])).toEqual([]);
+  });
+
+  it('reports up to date and a missing agent-docs block', async () => {
+    expect(await nonAsciiLines(['upgrade', '--from', '0.6.0'])).toEqual([]);
+  });
+
+  it('reports a range with no codemods', async () => {
+    expect(
+      await nonAsciiLines(['upgrade', '--from', '0.6.0', '--force']),
+    ).toEqual([]);
+  });
+
+  it('previews and applies codemods, runs a hook, and refreshes agent docs', async () => {
+    write(
+      'astryx.config.mjs',
+      `export default {hooks: {postCodemod: [{name: 'noop', buildCommand: () => ({command: ${JSON.stringify(process.execPath)}, args: ['-e', '0']})}]}};\n`,
+    );
+    write('AGENTS.md', `# Agents\n\n${generateCompressedIndex('0.5.0')}\n`);
+
+    expect(await nonAsciiLines(['upgrade', '--from', '0.5.0'])).toEqual([]);
+    expect(
+      await nonAsciiLines(['upgrade', '--from', '0.5.0', '--apply']),
+    ).toEqual([]);
+    expect(fs.readFileSync(path.join(tmpDir, 'src/panel.tsx'), 'utf8')).toContain(
+      'minSize: 200',
+    );
+  });
+});

package/clients/cli/commands/upgrade.doc.mjs

@@ -12,13 +12,14 @@ export const doc = {
   type: 'command',
   name: 'upgrade',
   displayName: 'astryx upgrade',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Migrate versions and update ShadCN-copied compositions',
   description:
     'Migrates project source from a previous Astryx version to the installed one by ' +
     'running the registered codemods, and refreshes the fully rendered managed ' +
     'agent-docs block when Core or configured integration guidance changes. ' +
     'Dry-run by default. --apply writes codemod and receipt changes, runs hooks, then refreshes agent docs. ' +
+    'Anything a post-codemod hook prints goes to stderr, so stdout carries only the result. ' +
     'ShadCN-copied compositions are checked automatically during a normal upgrade, or alone with --registry.',
   fn: 'upgrade',
   options: [
@@ -26,7 +27,8 @@ export const doc = {
       flag: '--from <version>',
       param: 'options.from',
       description:
-        'Previous version before the dependency upgrade; required unless --list or --registry is set',
+        'Previous version before the dependency upgrade; required unless --list or --registry is set. ' +
+        'The target is the installed @astryxdesign/core version, or legacy @xds/core when @astryxdesign/core is not installed',
     },
     {
       flag: '--apply',
@@ -44,7 +46,9 @@ export const doc = {
     {
       flag: '--codemod <name>',
       param: 'options.codemod',
-      description: 'Run a specific transform only',
+      description:
+        'Run only the named codemod. Optional codemods run only when named here; a normal run skips them. ' +
+        'Also skips the check of ShadCN-copied compositions. An unknown name exits 1 with ERR_UNKNOWN_CODEMOD when the version range has codemods',
     },
     {
       flag: '--skip-codemod <name...>',
@@ -53,10 +57,10 @@ export const doc = {
         'Exclude named codemods (repeatable). Re-run past a failed codemod by skipping it.',
     },
     {
-      flag: '--integration <package-or-file>',
+      flag: '--integration <package>',
       param: 'options.integration',
       description:
-        'Explicit integration package name or integration file path (repeatable)',
+        'Explicit integration specifier (repeatable). Resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.',
       default: [],
     },
     {
@@ -68,20 +72,23 @@ export const doc = {
     {
       flag: '--install-deps',
       param: 'options.installDeps',
-      description: 'Auto-install jscodeshift without prompting',
+      description:
+        'Install jscodeshift when it is missing. Without it, a missing jscodeshift fails the command with ERR_DEP_MISSING',
       default: false,
     },
     {
       flag: '--registry',
       param: 'options.registry',
       description:
-        'Only reconcile ShadCN-copied compositions; --from is not required',
+        'Only reconcile ShadCN-copied compositions; --from is not required. ' +
+        'Combining it with --list, --from, --force, --codemod, --skip-codemod, --integration or --install-deps exits 1 with ERR_INVALID_ARGUMENT',
       default: false,
     },
     {
       flag: '--list',
       param: 'options.list',
-      description: 'List available codemods',
+      description:
+        'List available codemods and do nothing else. Every other flag is ignored, except --registry, which is refused (exit 1)',
       default: false,
     },
   ],
@@ -94,10 +101,15 @@ export const doc = {
     {label: 'Apply a migration', cli: 'astryx upgrade --from 0.1.0 --apply'},
   ],
   exitCodes: [
-    {code: 0, when: 'success (including dry-run previews)'},
+    {code: 0, when: 'success, including complete dry-run previews'},
     {
       code: 1,
-      when: 'missing or invalid --from, a --path escape, an unknown codemod, a codemod failure, or unresolved registry items',
+      when:
+        'missing or invalid --from, --registry with --list or a migration flag, a --path escape, ' +
+        'no installed @astryxdesign/core (or legacy @xds/core), jscodeshift missing and not installed by --install-deps, ' +
+        'an astryx.config that fails validation and that no pending config codemod repairs, ' +
+        'an unreadable or invalid protection declaration, a protected file that still requires a codemod change, ' +
+        'an unknown codemod, a codemod or post-codemod hook failure, or unresolved registry items',
     },
   ],
   related: ['init', 'doctor'],

package/clients/cli/commands/upgrade.file-protection.test.mjs

@@ -0,0 +1,228 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file End-to-end protection and regeneration behavior for `astryx upgrade`.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const CLI = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'bin',
+  'astryx.mjs',
+);
+let root;
+
+function write(relative, contents) {
+  const file = path.join(root, relative);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, contents);
+  return file;
+}
+
+function run(args) {
+  const result = spawnSync(
+    process.execPath,
+    [CLI, '--json', 'upgrade', ...args],
+    {
+      cwd: root,
+      encoding: 'utf8',
+      timeout: 60_000,
+      env: {...process.env, FORCE_COLOR: '0', CI: ''},
+    },
+  );
+  return {...result, envelope: JSON.parse(result.stdout)};
+}
+
+function seed({hook = false} = {}) {
+  write('package.json', JSON.stringify({name: 'consumer', private: true}));
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
+  );
+  write('.gitattributes', 'generated/** linguist-generated=true\n');
+  const source =
+    "import {useResizable} from '@astryxdesign/core';\n" +
+    'export const usePanel = () => useResizable({minSizePx: 200});\n';
+  write('src/owned.tsx', source);
+  write('generated/panel.tsx', `// @generated\n${source}`);
+  write(
+    'astryx.config.mjs',
+    hook
+      ? `export default {hooks: {postCodemod: [{name: 'regenerate', buildCommand: () => ({command: process.execPath, args: ['-e', ${JSON.stringify("const fs=require('node:fs');const p='generated/panel.tsx';const s=fs.readFileSync(p,'utf8');fs.writeFileSync(p,s.replaceAll('minSizePx','minSize')); ")} ]})}]}};\n`
+      : 'export default {};\n',
+  );
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-protected-upgrade-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+const ARGS = [
+  '--from',
+  '0.5.0',
+  '--codemod',
+  'rename-resizable-pixel-bounds',
+  '--path',
+  '.',
+];
+
+describe('upgrade protected-file contract', () => {
+  it('reports the same protected candidate in dry-run and apply while retaining owned edits', () => {
+    seed();
+
+    const dry = run(ARGS);
+    expect(dry.status).toBe(1);
+    expect(dry.envelope).toMatchObject({
+      type: 'upgrade.run',
+      data: {
+        complete: false,
+        errorCode: 'ERR_CODEMOD_PROTECTED',
+        modifiedFiles: ['src/owned.tsx'],
+        protectedFiles: [
+          {
+            file: 'generated/panel.tsx',
+            reasons: ['generated'],
+            declarations: expect.arrayContaining([
+              'linguist-generated in .gitattributes:1',
+              '@generated in the leading comment block',
+            ]),
+          },
+        ],
+      },
+    });
+    expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+      'minSizePx',
+    );
+
+    const applied = run([...ARGS, '--apply']);
+    expect(applied.status).toBe(1);
+    expect(applied.envelope.data.protectedFiles).toEqual(
+      dry.envelope.data.protectedFiles,
+    );
+    expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+      'minSize: 200',
+    );
+    expect(
+      fs.readFileSync(path.join(root, 'generated/panel.tsx'), 'utf8'),
+    ).toContain('minSizePx');
+  });
+
+  it('preserves a protected config migration when strict config loading fails', () => {
+    write('package.json', JSON.stringify({name: 'consumer', private: true}));
+    write(
+      'node_modules/@astryxdesign/core/package.json',
+      JSON.stringify({name: '@astryxdesign/core', version: '0.1.3'}),
+    );
+    write(
+      'astryx.config.mjs',
+      `// @generated\nexport default {layout: {components: {KpiCard: '@/KpiCard'}}};\n`,
+    );
+    write('src/index.ts', 'export {};\n');
+
+    const result = run([
+      '--from',
+      '0.1.2',
+      '--codemod',
+      'migrate-layout-components-to-experimental',
+      '--path',
+      'src',
+      '--apply',
+    ]);
+
+    expect(result.status).toBe(1);
+    expect(result.envelope).toMatchObject({
+      type: 'upgrade.run',
+      data: {
+        complete: false,
+        errorCode: 'ERR_CODEMOD_PROTECTED',
+        protectedFiles: [expect.objectContaining({file: 'astryx.config.mjs'})],
+      },
+    });
+    expect(
+      fs.readFileSync(path.join(root, 'astryx.config.mjs'), 'utf8'),
+    ).toContain('layout');
+  });
+
+  it('fails before writes when a protection declaration cannot be parsed', () => {
+    seed();
+    write('.hgignore', 'syntax: regexp\n[bad\n');
+
+    const result = run([...ARGS, '--apply']);
+
+    expect(result.status).toBe(1);
+    expect(result.envelope).toMatchObject({
+      code: 'ERR_CODEMOD_PROTECTION_SOURCE',
+    });
+    expect(result.envelope.error).toContain('.hgignore');
+    expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+      'minSizePx',
+    );
+  });
+
+  it('preserves protected-file facts when regeneration fails', () => {
+    seed();
+    write(
+      'astryx.config.mjs',
+      `export default {hooks: {postCodemod: [{name: 'regenerate', buildCommand: () => ({command: process.execPath, args: ['-e', 'process.exit(7)']})}]}};\n`,
+    );
+
+    const applied = run([...ARGS, '--apply']);
+
+    expect(applied.status).toBe(1);
+    expect(applied.envelope).toMatchObject({
+      type: 'upgrade.run',
+      data: {
+        complete: false,
+        errorCode: 'ERR_CODEMOD_PROTECTED',
+        protectedFiles: [
+          expect.objectContaining({file: 'generated/panel.tsx'}),
+        ],
+        errors: [
+          expect.objectContaining({
+            codemod: 'post-codemod-hook',
+            error: expect.stringContaining('Post-codemod hook failed'),
+          }),
+        ],
+      },
+    });
+  });
+
+  it('runs declared regeneration and clears a generated-file block after reevaluation', () => {
+    seed({hook: true});
+
+    const applied = run([...ARGS, '--apply']);
+
+    expect(applied.status, applied.stderr).toBe(0);
+    expect(applied.envelope).toMatchObject({
+      type: 'upgrade.run',
+      data: {
+        complete: true,
+        modifiedFiles: ['src/owned.tsx', 'generated/panel.tsx'],
+        protectedFiles: [],
+        declinedCandidates: [],
+      },
+    });
+    expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+      'minSize: 200',
+    );
+    expect(
+      fs.readFileSync(path.join(root, 'generated/panel.tsx'), 'utf8'),
+    ).toContain('minSize: 200');
+
+    const second = run([...ARGS, '--apply']);
+    expect(second.status, second.stderr).toBe(0);
+    expect(second.envelope.data.complete).toBe(true);
+    expect(second.envelope.data.filesChanged).toBe(0);
+  });
+});