Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(cli): state upgrade's exit codes and flag interactions (#6590)

Joey1ce127b85b2f
diff --git a/.changeset/cli-spec-upgrade-doc-exit-codes.md b/.changeset/cli-spec-upgrade-doc-exit-codes.md
new file mode 100644
index 0000000000..e676ec0def
--- /dev/null
+++ b/.changeset/cli-spec-upgrade-doc-exit-codes.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] `astryx upgrade --help` and the manifest now state how its flags combine: `--list` ignores every other flag, `--registry` refuses `--list` and the migration flags, and `--codemod` is the only way to run an optional codemod and also skips the ShadCN composition check. The `--from` help names the legacy `@xds/core` fallback, and the documented exit codes now include a missing core, a missing jscodeshift, an invalid `astryx.config`, a post-codemod hook failure and the refused flag combinations.
+
+@josephfarina
diff --git a/packages/cli/clients/cli/commands/upgrade.doc.mjs b/packages/cli/clients/cli/commands/upgrade.doc.mjs
index acb8c6040f..de60d7a4fb 100644
--- a/packages/cli/clients/cli/commands/upgrade.doc.mjs
+++ b/packages/cli/clients/cli/commands/upgrade.doc.mjs
@@ -26,7 +26,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 +45,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...>',
@@ -76,13 +79,15 @@ export const doc = {
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,
},
],
@@ -98,7 +103,11 @@ export const doc = {
{code: 0, when: 'success (including 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 unknown codemod, a codemod or post-codemod hook failure, or unresolved registry items',
},
],
related: ['init', 'doctor'],
diff --git a/packages/cli/clients/cli/commands/upgrade.flag-help.test.mjs b/packages/cli/clients/cli/commands/upgrade.flag-help.test.mjs
new file mode 100644
index 0000000000..3406a91a7e
--- /dev/null
+++ b/packages/cli/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/);
+ });
+});