@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

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);
+  });
+});

package/clients/cli/commands/upgrade.flag-help.test.mjs

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` documents how its flags interact and when it exits 1,
+ * and behaves as documented. Option text is read from the generated manifest
+ * (the same strings `--help` prints); exit codes from the CommandDoc.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {doc as upgradeDoc} from './upgrade.doc.mjs';
+
+const SLOW = 30_000;
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-flags-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+  fs.mkdirSync(path.join(tmpDir, 'src'));
+  fs.writeFileSync(path.join(tmpDir, 'src', 'index.ts'), 'const foo = 1;\n');
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} name @param {string} version */
+function installPackage(name, version) {
+  const dir = path.join(tmpDir, 'node_modules', ...name.split('/'));
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name, version}));
+}
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  fs.mkdirSync(path.dirname(path.join(tmpDir, rel)), {recursive: true});
+  fs.writeFileSync(path.join(tmpDir, rel), body);
+}
+
+/**
+ * upgrade's option descriptions from the manifest, keyed by long flag.
+ * @returns {Promise<Record<string, string>>}
+ */
+async function upgradeOptions() {
+  const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
+  const upgrade = JSON.parse(stdout).data.commands.find(
+    (/** @type {{name: string}} */ c) => c.name === 'upgrade',
+  );
+  return Object.fromEntries(
+    upgrade.options.map((/** @type {{flag: string, description: string}} */ o) => [
+      o.flag.match(/--[a-z-]+/)?.[0],
+      o.description,
+    ]),
+  );
+}
+
+/** @param {string[]} args */
+async function upgradeJson(args) {
+  const result = await runCli(['--json', 'upgrade', ...args], tmpDir);
+  return {status: result.status, envelope: JSON.parse(result.stdout)};
+}
+
+const exit1 = () => upgradeDoc.exitCodes?.find(e => e.code === 1)?.when ?? '';
+
+const MIGRATION_FLAGS = [
+  ['--from', '0.5.0'],
+  ['--force'],
+  ['--codemod', 'x'],
+  ['--skip-codemod', 'x'],
+  ['--integration', 'x'],
+  ['--install-deps'],
+];
+
+describe('astryx upgrade flag interactions', () => {
+  it('--list: help says it ignores every other flag but --registry, and it does', async () => {
+    const options = await upgradeOptions();
+    expect(options['--list']).toMatch(/Every other flag is ignored, except --registry/);
+
+    installPackage('@astryxdesign/core', '0.6.0');
+    const listed = await upgradeJson([
+      '--list',
+      '--from',
+      'bogus',
+      '--codemod',
+      'bogus',
+      '--apply',
+      '--path',
+      '../outside',
+    ]);
+    expect(listed.status).toBe(0);
+    expect(listed.envelope.type).toBe('upgrade.list');
+
+    const refused = await upgradeJson(['--list', '--registry']);
+    expect(refused.status).toBe(1);
+    expect(refused.envelope.code).toBe('ERR_INVALID_ARGUMENT');
+  }, SLOW);
+
+  it('--registry: help names every flag it refuses, and each exits 1', async () => {
+    const options = await upgradeOptions();
+    for (const [flag] of MIGRATION_FLAGS) expect(options['--registry']).toContain(flag);
+    expect(options['--registry']).toContain('--list');
+    expect(options['--registry']).toContain('ERR_INVALID_ARGUMENT');
+
+    for (const flag of MIGRATION_FLAGS) {
+      const {status, envelope} = await upgradeJson(['--registry', ...flag]);
+      expect(status, flag[0]).toBe(1);
+      expect(envelope.code, flag[0]).toBe('ERR_INVALID_ARGUMENT');
+    }
+  }, SLOW);
+
+  it('--codemod: help says it runs optional codemods and skips the composition check, and it does', async () => {
+    const options = await upgradeOptions();
+    expect(options['--codemod']).toMatch(/Optional codemods run only when named here/);
+    expect(options['--codemod']).toMatch(/skips the check of ShadCN-copied compositions/);
+
+    installPackage('@astryxdesign/core', '0.0.15');
+    // An unreadable receipt leaves a registry item unresolved.
+    write('src/components/.astryx/broken.json', '{}');
+
+    const normal = await upgradeJson(['--from', '0.0.14']);
+    expect(normal.status).toBe(1);
+    expect(normal.envelope.data.registryCompositions.invalid).toBe(1);
+
+    // 0.0.15 ships one optional codemod, which only runs when named.
+    const named = await upgradeJson(['--from', '0.0.14', '--codemod', 'migrate-theme-selectors-to-data-attrs']);
+    expect(named.status).toBe(0);
+    expect(named.envelope.data.codemods).toBe(1);
+    expect(named.envelope.data.registryCompositions).toBeUndefined();
+    expect(normal.envelope.data.codemods).toBe(6);
+  }, SLOW);
+
+  it('--from: help names the legacy @xds/core target, which upgrade falls back to', async () => {
+    const options = await upgradeOptions();
+    expect(options['--from']).toMatch(/legacy @xds\/core/);
+
+    installPackage('@xds/core', '0.0.20');
+    const {status, envelope} = await upgradeJson(['--from', '0.0.19']);
+    expect(status).toBe(0);
+    expect(envelope.data.to).toBe('0.0.20');
+  }, SLOW);
+});
+
+describe('astryx upgrade exit codes', () => {
+  it('lists a missing core, which exits 1 in both modes', async () => {
+    expect(exit1()).toMatch(/no installed @astryxdesign\/core/);
+    const text = await runCli(['upgrade', '--from', '0.5.0'], tmpDir);
+    const json = await upgradeJson(['--from', '0.5.0']);
+    expect(text.status).toBe(1);
+    expect(json.status).toBe(1);
+    expect(json.envelope.code).toBe('ERR_VERSION_DETECT');
+  }, SLOW);
+
+  it('lists an astryx.config no codemod repairs, which exits 1', async () => {
+    expect(exit1()).toMatch(/astryx\.config that fails validation/);
+    installPackage('@astryxdesign/core', '0.6.0');
+    write('astryx.config.mjs', "export default {theme: 'neutral'};\n");
+    const {status, envelope} = await upgradeJson(['--from', '0.5.0']);
+    expect(status).toBe(1);
+    expect(envelope.code).toBe('ERR_INVALID_ARGUMENT');
+  }, SLOW);
+
+  it('lists a post-codemod hook failure, which exits 1', async () => {
+    expect(exit1()).toMatch(/post-codemod hook failure/);
+    installPackage('@astryxdesign/core', '0.6.0');
+    write(
+      'src/panel.tsx',
+      "import {useResizable} from '@astryxdesign/core';\nexport const r = () => useResizable({minSizePx: 200});\n",
+    );
+    write(
+      'astryx.config.mjs',
+      "export default {hooks: {postCodemod: [{buildCommand: () => { throw new Error('formatter crashed'); }}]}};\n",
+    );
+    const {status, envelope} = await upgradeJson(['--from', '0.5.0']);
+    expect(status).toBe(1);
+    expect(envelope.code).toBe('ERR_CODEMOD_FAILED');
+    expect(envelope.error).toMatch(/Post-codemod hook failed/);
+  }, SLOW);
+
+  it('lists a missing jscodeshift and the refused flag combinations', () => {
+    expect(exit1()).toMatch(/jscodeshift missing and not installed/);
+    expect(exit1()).toMatch(/--registry with --list or a migration flag/);
+  });
+});

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

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Subprocess test: a post-codemod hook that prints must not corrupt the
+ * `upgrade --json` envelope. Stdout carries exactly one envelope; the hook's
+ * output goes to stderr.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
+
+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);
+}
+
+/** @param {string[]} args */
+function runCli(args) {
+  return spawnSync(process.execPath, [CLI, ...args], {
+    cwd: tmpDir,
+    encoding: 'utf8',
+    timeout: 60_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: {...process.env, FORCE_COLOR: '0', CI: ''},
+  });
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-hook-output-'));
+  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',
+  );
+  write(
+    'astryx.config.mjs',
+    'export default {hooks: {postCodemod: [{name: "noisy", buildCommand: ({files}) => {\n' +
+      '  console.log("hook saw " + files.join(","));\n' +
+      '  process.stdout.write("hook raw write\\n");\n' +
+      '  return null;\n' +
+      '}}]}};\n',
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('upgrade post-codemod hook output', () => {
+  it('keeps --json stdout to one envelope and sends hook output to stderr', () => {
+    const r = runCli([
+      '--json',
+      'upgrade',
+      '--from',
+      '0.5.0',
+      '--codemod',
+      'rename-resizable-pixel-bounds',
+      '--apply',
+    ]);
+
+    expect(r.signal).toBeNull();
+    expect(r.status).toBe(0);
+    const envelope = JSON.parse(r.stdout);
+    expect(envelope.type).toBe('upgrade.run');
+    expect(envelope.data.filesChanged).toBe(1);
+    expect(r.stderr).toContain('hook saw src/panel.tsx');
+    expect(r.stderr).toContain('hook raw write');
+    expect(fs.readFileSync(path.join(tmpDir, 'src/panel.tsx'), 'utf8')).toContain(
+      'minSize: 200',
+    );
+  });
+});

package/clients/cli/commands/upgrade.mjs

@@ -13,6 +13,7 @@
  */
 
 import {jsonOut, jsonError} from '../../../foundation/response/json.mjs';
+import {emit, section, records} from '../formatters/index.mjs';
 import {logger} from '../../../api/logger.mjs';
 import {AstryxError} from '../../../api/error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
@@ -33,27 +34,45 @@ export function registerUpgrade(program) {
        */
       async options => {
         const json = program.opts().json || false;
-        logger.setSilent(json);
+        const isList = Boolean(options.list);
+        // Silence the logger for --list so the handler renders from the
+        // result (parity with --json), and for --json as before.
+        // Re-enable on error so handled failures still print.
+        logger.setSilent(json || isList);
 
         /** @type {import('../../../api/upgrade/upgrade.type.mjs').UpgradeListResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRegistryResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeStatusResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRunResponse} */
         let result;
         try {
           result = await upgradeApi(options, {cwd: process.cwd()});
         } catch (e) {
-          // Handled failures throw AstryxError: --json emits the structured
-          // envelope (byte-identical to the old inline jsonError) + exits 1;
-          // human mode already saw the error line + outro via the logger, so we
-          // just set the exit code. Anything else is unexpected — let the
-          // top-level boundary in bin/astryx.mjs format it as before.
+          // Re-enable the logger so the error is visible in text mode.
+          // For --list the logger was silent; for other modes the API
+          // already printed the error before throwing.
+          logger.setSilent(json);
           if (e instanceof AstryxError) {
             if (json) jsonError(e.message, undefined, e.code);
-            else process.exitCode = 1;
+            else {
+              // The logger was silent only for --list; replay the error there.
+              // Non-list failures were already printed by the API.
+              if (isList) logger.error(e.message);
+              process.exitCode = 1;
+            }
             return NO_RESULT_SET;
           }
           throw e;
         }
 
         if (json) jsonOut(result);
+        else if (result.type === 'upgrade.list') {
+          // Render the list from the result, not the API logger, so the text
+          // carries the same fields the JSON does (name, title, version, optional).
+          emit(
+            section('Available codemods'),
+            records(result.data, {
+              fields: ['name', 'title', 'version', 'optional'],
+            }),
+          );
+        }
 
         const registrySummary =
           result.type === 'upgrade.registry'
@@ -65,6 +84,9 @@ export function registerUpgrade(program) {
                 ? result.data.registryCompositions
                 : undefined;
         if (registrySummary && !registrySummary.ok) process.exitCode = 1;
+        if (result.type === 'upgrade.run' && result.data.complete === false) {
+          process.exitCode = 1;
+        }
 
         // `--list` is the one lookup here: which migrations exist for the
         // range. Everything else migrates the project — an effect, reported by