Skip to content

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

TypeScript

test(cli): run CLI suites in-process (harness + rollout + e2e smoke) (#4440)

Joeycc64dacfce91
diff --git a/packages/cli/api/template/discover-integration-templates.test.mjs b/packages/cli/api/template/discover-integration-templates.test.mjs
new file mode 100644
index 0000000000..45390c0381
--- /dev/null
+++ b/packages/cli/api/template/discover-integration-templates.test.mjs
@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression coverage for integration-template discovery error surfacing.
+ *
+ * discoverIntegrationTemplates() used to wrap Project.load() in a bare
+ * `catch {}` that silently dropped a broken astryx.config — hiding both the
+ * user's config error AND any unexpected bug. It now records the failure in the
+ * TemplateDiscoveryError channel that discoverAllWithErrors() exposes. The
+ * no-error variant (discoverAll, used by `astryx template`) still ignores it,
+ * so the command's behavior is unchanged; these tests lock the surfacing.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {discoverAllWithErrors} from './template.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-tmpl-errors-'));
+});
+
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('discoverAllWithErrors — config-load failures are surfaced, not swallowed', () => {
+ it('records an astryx.config error when the config cannot load', async () => {
+ // Two configs → findConfigPath throws "Multiple Astryx config files",
+ // which Project.load propagates. Previously swallowed by a bare catch {};
+ // now it must appear in the errors channel.
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.config.mjs'),
+ 'export default {integrations: []};\n',
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.config.js'),
+ 'module.exports = {integrations: []};\n',
+ );
+
+ const {errors} = await discoverAllWithErrors(tmpDir);
+ const configErr = errors.find(e => e.package === 'astryx.config');
+ expect(configErr).toBeDefined();
+ expect(configErr.message).toMatch(/Multiple Astryx config files/i);
+ });
+
+ it('records no config error for a clean project with no config', async () => {
+ // Baseline: no config → Project.load returns an empty project, so nothing
+ // is recorded against astryx.config (the common case must stay quiet).
+ const {errors} = await discoverAllWithErrors(tmpDir);
+ expect(errors.find(e => e.package === 'astryx.config')).toBeUndefined();
+ });
+});
diff --git a/packages/cli/api/template/template.mjs b/packages/cli/api/template/template.mjs
index 001a6e0548..1604a47620 100644
--- a/packages/cli/api/template/template.mjs
+++ b/packages/cli/api/template/template.mjs
@@ -444,9 +444,19 @@ async function discoverIntegrationTemplates(cwd = process.cwd()) {
/** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
project.loadedIntegrations
);
- } catch {
- // Config load failures are surfaced elsewhere (discover/doctor); here we
- // simply contribute no integration templates.
+ } catch (err) {
+ // A broken astryx.config (or an integration that fails to load) can't
+ // contribute templates. Record it as a discovery error instead of
+ // swallowing it silently: a bare `catch {}` also hides unexpected bugs.
+ // discoverAll (the no-error variant that `astryx template` uses) and
+ // Project.templates() both discard this errors array, so the template
+ // command's behavior is unchanged — the full config-error UX still lives
+ // in `discover`/`doctor` via Project.issues(). Only callers that opt into
+ // errors (discoverAllWithErrors) now see the signal.
+ errors.push({
+ package: 'astryx.config',
+ message: err instanceof Error ? err.message : String(err),
+ });
return {templates, errors};
}
diff --git a/packages/cli/cli/cli-exit-codes.test.mjs b/packages/cli/cli/cli-exit-codes.test.mjs
index 4fc4a8b290..a72903556a 100644
--- a/packages/cli/cli/cli-exit-codes.test.mjs
+++ b/packages/cli/cli/cli-exit-codes.test.mjs
@@ -16,25 +16,11 @@
*/
import {describe, it, expect} from 'vitest';
-import {spawnSync} from 'node:child_process';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
-
-function runCli(args) {
- return spawnSync(process.execPath, [CLI, ...args], {
- encoding: 'utf8',
- timeout: 20_000,
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0', CI: ''},
- });
-}
+import {runCli} from '../test-utils/run-cli.mjs';
/** Shorthand for asserting the exit code. */
-function expectExit(args, code) {
- const r = runCli(args);
+async function expectExit(args, code) {
+ const r = await runCli(args);
expect(
r.status,
`xds ${args.join(' ')} should exit ${code}, got ${r.status}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`,
@@ -54,62 +40,62 @@ function parseEnvelope(r) {
// ─── Error paths: must exit 1 ────────────────────────────────────────────────
describe('exit codes — error paths (human mode → exit 1)', () => {
- it('astryx bogus-cmd → exit 1', () => {
- const r = expectExit(['bogus-cmd'], 1);
+ it('astryx bogus-cmd → exit 1', async () => {
+ const r = await expectExit(['bogus-cmd'], 1);
expect(r.stderr).toMatch(/unknown command/i);
});
- it('astryx theme bogus → exit 1', () => {
- const r = expectExit(['theme', 'bogus'], 1);
+ it('astryx theme bogus → exit 1', async () => {
+ const r = await expectExit(['theme', 'bogus'], 1);
expect(r.stderr).toMatch(/unknown subcommand/i);
});
- it('astryx component bogus → exit 1', () => {
- const r = expectExit(['component', 'bogus'], 1);
+ it('astryx component bogus → exit 1', async () => {
+ const r = await expectExit(['component', 'bogus'], 1);
expect(r.stderr).toMatch(/no component named/i);
});
- it('astryx hook bogus → exit 1', () => {
- const r = expectExit(['hook', 'bogus'], 1);
+ it('astryx hook bogus → exit 1', async () => {
+ const r = await expectExit(['hook', 'bogus'], 1);
expect(r.stderr).toMatch(/no hook named/i);
});
- it('astryx docs bogus → exit 1', () => {
- const r = expectExit(['docs', 'bogus'], 1);
+ it('astryx docs bogus → exit 1', async () => {
+ const r = await expectExit(['docs', 'bogus'], 1);
expect(r.stderr).toMatch(/unknown topic/i);
});
- it('astryx --bogus-flag → exit 1', () => {
- const r = expectExit(['--bogus-flag'], 1);
+ it('astryx --bogus-flag → exit 1', async () => {
+ const r = await expectExit(['--bogus-flag'], 1);
// Commander's unknown-option message goes to stderr.
expect(r.stderr).toMatch(/unknown option/i);
});
});
describe('exit codes — error paths (--json → exit 1, valid envelope)', () => {
- it('astryx bogus-cmd --json → exit 1, error envelope', () => {
- const r = expectExit(['bogus-cmd', '--json'], 1);
+ it('astryx bogus-cmd --json → exit 1, error envelope', async () => {
+ const r = await expectExit(['bogus-cmd', '--json'], 1);
const env = parseEnvelope(r);
expect(env.apiVersion).toBe(1);
expect(env.error).toMatch(/unknown command/i);
});
- it('astryx component bogus --json → exit 1, error envelope', () => {
- const r = expectExit(['component', 'bogus', '--json'], 1);
+ it('astryx component bogus --json → exit 1, error envelope', async () => {
+ const r = await expectExit(['component', 'bogus', '--json'], 1);
const env = parseEnvelope(r);
expect(env.apiVersion).toBe(1);
expect(env.error).toMatch(/no component named/i);
});
- it('astryx hook bogus --json → exit 1, error envelope', () => {
- const r = expectExit(['hook', 'bogus', '--json'], 1);
+ it('astryx hook bogus --json → exit 1, error envelope', async () => {
+ const r = await expectExit(['hook', 'bogus', '--json'], 1);
const env = parseEnvelope(r);
expect(env.apiVersion).toBe(1);
expect(env.error).toMatch(/no hook named/i);
});
- it('astryx docs bogus --json → exit 1, error envelope', () => {
- const r = expectExit(['docs', 'bogus', '--json'], 1);
+ it('astryx docs bogus --json → exit 1, error envelope', async () => {
+ const r = await expectExit(['docs', 'bogus', '--json'], 1);
const env = parseEnvelope(r);
expect(env.apiVersion).toBe(1);
expect(env.error).toMatch(/unknown topic/i);
@@ -119,40 +105,40 @@ describe('exit codes — error paths (--json → exit 1, valid envelope)', () =>
// ─── Success paths: must exit 0 (positive controls) ──────────────────────────
describe('exit codes — success paths (exit 0)', () => {
- it('astryx (no args) → exit 0, prints help', () => {
- const r = expectExit([], 0);
+ it('astryx (no args) → exit 0, prints help', async () => {
+ const r = await expectExit([], 0);
// Help should land on stdout (Commander default for help()).
expect(r.stdout + r.stderr).toMatch(/Usage:/);
});
- it('astryx --help → exit 0', () => {
- expectExit(['--help'], 0);
+ it('astryx --help → exit 0', async () => {
+ await expectExit(['--help'], 0);
});
- it('astryx --version → exit 0, prints a version', () => {
- const r = expectExit(['--version'], 0);
+ it('astryx --version → exit 0, prints a version', async () => {
+ const r = await expectExit(['--version'], 0);
expect(r.stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
});
- it('astryx component (list mode) → exit 0', () => {
- expectExit(['component'], 0);
+ it('astryx component (list mode) → exit 0', async () => {
+ await expectExit(['component'], 0);
});
- it('astryx component Button → exit 0', () => {
- expectExit(['component', 'Button'], 0);
+ it('astryx component Button → exit 0', async () => {
+ await expectExit(['component', 'Button'], 0);
});
- it('astryx docs (list mode) → exit 0', () => {
- expectExit(['docs'], 0);
+ it('astryx docs (list mode) → exit 0', async () => {
+ await expectExit(['docs'], 0);
});
- it('astryx theme (no subcommand) → exit 0, shows help', () => {
+ it('astryx theme (no subcommand) → exit 0, shows help', async () => {
// Bare theme without a subcommand is a help-display case → exit 0.
- expectExit(['theme'], 0);
+ await expectExit(['theme'], 0);
});
- it('astryx hook (list mode) → exit 0', () => {
- expectExit(['hook'], 0);
+ it('astryx hook (list mode) → exit 0', async () => {
+ await expectExit(['hook'], 0);
});
});
@@ -167,9 +153,9 @@ describe('exit codes — JSON / non-JSON parity', () => {
];
for (const args of cases) {
- it(`xds ${args.join(' ')} — exit code matches with and without --json`, () => {
- const human = runCli(args);
- const jsonRun = runCli([...args, '--json']);
+ it(`xds ${args.join(' ')} — exit code matches with and without --json`, async () => {
+ const human = await runCli(args);
+ const jsonRun = await runCli([...args, '--json']);
expect(jsonRun.status).toBe(human.status);
expect(jsonRun.status).toBe(1);
});
diff --git a/packages/cli/cli/commands/build-theme.color-scheme.test.mjs b/packages/cli/cli/commands/build-theme.color-scheme.test.mjs
index 0ca6c20edd..48369aff80 100644
--- a/packages/cli/cli/commands/build-theme.color-scheme.test.mjs
+++ b/packages/cli/cli/commands/build-theme.color-scheme.test.mjs
@@ -26,38 +26,16 @@
*/
import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
-import {execFileSync} 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';
import {ensureCoreBuilt} from './ensure-core-built.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+import {runCli} from '../../test-utils/run-cli.mjs';
const COLOR_SCHEME_ROOT_DECL = ':root { color-scheme: light dark; }';
const COLOR_SCHEME_LIGHT_DECL = 'html[data-theme="light"] { color-scheme: light; }';
const COLOR_SCHEME_DARK_DECL = 'html[data-theme="dark"] { color-scheme: dark; }';
-function runCli(args, cwd) {
- try {
- const out = execFileSync('node', [CLI_BIN, ...args], {
- cwd,
- encoding: 'utf-8',
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0'},
- });
- return {code: 0, stdout: out, stderr: ''};
- } catch (e) {
- return {
- code: e.status ?? 1,
- stdout: e.stdout?.toString() ?? '',
- stderr: e.stderr?.toString() ?? '',
- };
- }
-}
-
function writeTheme(dir, name, tokens) {
fs.mkdirSync(dir, {recursive: true});
// The CLI writes <basename>.css next to the source file, so use the
@@ -85,7 +63,7 @@ afterEach(() => {
});
describe('theme build color-scheme output', () => {
- it('emits the mode-aware color-scheme rules in @layer astryx-theme for a light-dark() theme', () => {
+ it('emits the mode-aware color-scheme rules in @layer astryx-theme for a light-dark() theme', async () => {
const project = path.join(tmpDir, 'project');
const themesDir = path.join(project, 'themes');
// A raw light-dark() token value is what triggers the color-scheme
@@ -98,7 +76,7 @@ describe('theme build color-scheme output', () => {
'--color-accent': 'light-dark(#0077B6, #48CAE4)',
});
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -127,14 +105,14 @@ describe('theme build color-scheme output', () => {
expect(themeLayerBody).toContain(COLOR_SCHEME_DARK_DECL);
});
- it('omits all color-scheme rules for a theme with no light-dark() tokens', () => {
+ it('omits all color-scheme rules for a theme with no light-dark() tokens', async () => {
const project = path.join(tmpDir, 'project');
const themesDir = path.join(project, 'themes');
const themeFile = writeTheme(themesDir, 'no-light-dark', {
'--color-accent': '#0077B6',
});
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(project, themeFile)],
project,
);
diff --git a/packages/cli/cli/commands/build-theme.import-path.test.mjs b/packages/cli/cli/commands/build-theme.import-path.test.mjs
index 0178ea2997..b5200e2911 100644
--- a/packages/cli/cli/commands/build-theme.import-path.test.mjs
+++ b/packages/cli/cli/commands/build-theme.import-path.test.mjs
@@ -13,33 +13,11 @@
*/
import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
-import {execFileSync} 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';
import {ensureCoreBuilt} from './ensure-core-built.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-
-function runCli(args, cwd) {
- try {
- const out = execFileSync('node', [CLI_BIN, ...args], {
- cwd,
- encoding: 'utf-8',
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0'},
- });
- return {code: 0, stdout: out, stderr: ''};
- } catch (e) {
- return {
- code: e.status ?? 1,
- stdout: e.stdout?.toString() ?? '',
- stderr: e.stderr?.toString() ?? '',
- };
- }
-}
+import {runCli} from '../../test-utils/run-cli.mjs';
function writeTheme(dir, name) {
fs.mkdirSync(dir, {recursive: true});
@@ -67,13 +45,13 @@ afterEach(() => {
});
describe('theme build install-instructions import path', () => {
- it('emits bare ./<name> specifiers (no double slash) when out dir equals cwd', () => {
+ it('emits bare ./<name> specifiers (no double slash) when out dir equals cwd', async () => {
// Source theme lives directly in the project root, so the output dir
// is the cwd and the relative dir is an empty string.
const project = path.join(tmpDir, 'project');
const themeFile = writeTheme(project, 'cwd-theme');
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -87,11 +65,11 @@ describe('theme build install-instructions import path', () => {
expect(result.stdout).toContain('href="./cwd-theme.css"');
});
- it('keeps the subdir in the import path for a non-src subdirectory build', () => {
+ it('keeps the subdir in the import path for a non-src subdirectory build', async () => {
const project = path.join(tmpDir, 'project');
const themeFile = writeTheme(path.join(project, 'themes'), 'sub-theme');
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -103,14 +81,14 @@ describe('theme build install-instructions import path', () => {
expect(result.stdout).toContain('href="./themes/sub-theme.css"');
});
- it('strips a leading src/ from the import path (relative to a file in src/)', () => {
+ it('strips a leading src/ from the import path (relative to a file in src/)', async () => {
const project = path.join(tmpDir, 'project');
const themeFile = writeTheme(
path.join(project, 'src', 'themes', 'ocean'),
'ocean',
);
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(project, themeFile)],
project,
);
diff --git a/packages/cli/cli/commands/build-theme.path-safety.test.mjs b/packages/cli/cli/commands/build-theme.path-safety.test.mjs
index 186cb32fcb..3668b87176 100644
--- a/packages/cli/cli/commands/build-theme.path-safety.test.mjs
+++ b/packages/cli/cli/commands/build-theme.path-safety.test.mjs
@@ -8,36 +8,14 @@
* - Theme name with `/` is rejected with a clear error (vs. ENOENT).
* - Multi-file write is atomic: if one file fails, none are left behind.
*
- * Runs the CLI via execFileSync against a tiny synthetic theme file.
+ * Runs the CLI in-process (shared runCli harness) against a tiny synthetic theme file.
*/
import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import {execFileSync} 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_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-
-function runCli(args, cwd) {
- try {
- const out = execFileSync('node', [CLI_BIN, ...args], {
- cwd,
- encoding: 'utf-8',
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0'},
- });
- return {code: 0, stdout: out, stderr: ''};
- } catch (e) {
- return {
- code: e.status ?? 1,
- stdout: e.stdout?.toString() ?? '',
- stderr: e.stderr?.toString() ?? '',
- };
- }
-}
+import {runCli} from '../../test-utils/run-cli.mjs';
function writeTheme(dir, name) {
fs.mkdirSync(dir, {recursive: true});
@@ -61,7 +39,7 @@ afterEach(() => {
});
describe('theme build path safety', () => {
- it('rejects a theme name containing ../ traversal and writes no JS outside the input dir', () => {
+ it('rejects a theme name containing ../ traversal and writes no JS outside the input dir', async () => {
const project = path.join(tmpDir, 'project');
const themesDir = path.join(project, 'themes');
const outside = path.join(tmpDir, 'outside');
@@ -69,7 +47,7 @@ describe('theme build path safety', () => {
const themeFile = writeTheme(themesDir, '../../escaped');
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -83,13 +61,13 @@ describe('theme build path safety', () => {
expect(fs.readdirSync(outside)).toEqual([]);
});
- it('rejects a theme name containing /', () => {
+ it('rejects a theme name containing /', async () => {
const project = path.join(tmpDir, 'project');
const themesDir = path.join(project, 'themes');
const themeFile = writeTheme(themesDir, 'bad/name');
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -102,13 +80,13 @@ describe('theme build path safety', () => {
expect(fs.existsSync(path.join(themesDir, 'bad', 'name.js'))).toBe(false);
});
- it('does not leave partial output (no CSS without JS) on a sanitized rejection', () => {
+ it('does not leave partial output (no CSS without JS) on a sanitized rejection', async () => {
const project = path.join(tmpDir, 'project');
const themesDir = path.join(project, 'themes');
const themeFile = writeTheme(themesDir, '../leak');
- runCli(['theme', 'build', path.relative(project, themeFile)], project);
+ await runCli(['theme', 'build', path.relative(project, themeFile)], project);
// Neither the CSS nor any sibling JS should have been written.
const entries = fs.readdirSync(themesDir).sort();
diff --git a/packages/cli/cli/commands/build-theme.prose.test.mjs b/packages/cli/cli/commands/build-theme.prose.test.mjs
index d09c35b208..31c98502e7 100644
--- a/packages/cli/cli/commands/build-theme.prose.test.mjs
+++ b/packages/cli/cli/commands/build-theme.prose.test.mjs
@@ -24,33 +24,11 @@
*/
import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
-import {execFileSync} 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';
import {ensureCoreBuilt} from './ensure-core-built.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-
-function runCli(args, cwd) {
- try {
- const out = execFileSync('node', [CLI_BIN, ...args], {
- cwd,
- encoding: 'utf-8',
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0'},
- });
- return {code: 0, stdout: out, stderr: ''};
- } catch (e) {
- return {
- code: e.status ?? 1,
- stdout: e.stdout?.toString() ?? '',
- stderr: e.stderr?.toString() ?? '',
- };
- }
-}
+import {runCli} from '../../test-utils/run-cli.mjs';
function writeTheme(dir, name) {
fs.mkdirSync(dir, {recursive: true});
@@ -79,12 +57,12 @@ afterEach(() => {
});
describe('theme build prose output', () => {
- it('always emits prose mappings in @layer reset', () => {
+ it('always emits prose mappings in @layer reset', async () => {
const project = path.join(tmpDir, 'project');
const themesDir = path.join(project, 'themes');
const themeFile = writeTheme(themesDir, 'with-prose');
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -117,8 +95,8 @@ describe('theme build prose output', () => {
expect(css.indexOf(':where(p)')).toBeLessThan(themeIndex);
});
- it('has no --no-prose flag (prose is non-optional)', () => {
- const result = runCli(['theme', 'build', '--help'], process.cwd());
+ it('has no --no-prose flag (prose is non-optional)', async () => {
+ const result = await runCli(['theme', 'build', '--help'], process.cwd());
// The flag was removed; build always emits prose to match the runtime.
expect(result.stdout + result.stderr).not.toContain('--no-prose');
});
diff --git a/packages/cli/cli/commands/build-theme.variants.test.mjs b/packages/cli/cli/commands/build-theme.variants.test.mjs
index 479d52d67b..93d0b6c89f 100644
--- a/packages/cli/cli/commands/build-theme.variants.test.mjs
+++ b/packages/cli/cli/commands/build-theme.variants.test.mjs
@@ -23,33 +23,11 @@
*/
import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
-import {execFileSync} 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';
import {ensureCoreBuilt} from './ensure-core-built.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-
-function runCli(args, cwd) {
- try {
- const out = execFileSync('node', [CLI_BIN, ...args], {
- cwd,
- encoding: 'utf-8',
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0'},
- });
- return {code: 0, stdout: out, stderr: ''};
- } catch (e) {
- return {
- code: e.status ?? 1,
- stdout: e.stdout?.toString() ?? '',
- stderr: e.stderr?.toString() ?? '',
- };
- }
-}
+import {runCli} from '../../test-utils/run-cli.mjs';
function writeTheme(dir, contents) {
fs.mkdirSync(dir, {recursive: true});
@@ -76,7 +54,7 @@ afterEach(() => {
});
describe('theme build custom-variant augmentations', () => {
- it('targets the real (un-prefixed) core interface for a custom variant', () => {
+ it('targets the real (un-prefixed) core interface for a custom variant', async () => {
const themeFile = writeTheme(
tmpDir,
`export default {
@@ -88,7 +66,7 @@ describe('theme build custom-variant augmentations', () => {
};\n`,
);
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(tmpDir, themeFile)],
tmpDir,
);
@@ -106,7 +84,7 @@ describe('theme build custom-variant augmentations', () => {
expect(dts).not.toMatch(/XDSButtonVariantMap/);
});
- it('skips props with no augmentation point (Button size, Heading type)', () => {
+ it('skips props with no augmentation point (Button size, Heading type)', async () => {
const themeFile = writeTheme(
tmpDir,
`export default {
@@ -122,7 +100,7 @@ describe('theme build custom-variant augmentations', () => {
};\n`,
);
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(tmpDir, themeFile)],
tmpDir,
);
@@ -140,7 +118,7 @@ describe('theme build custom-variant augmentations', () => {
expect(dts).not.toContain("declare module '@astryxdesign/core/Heading'");
});
- it('does not emit a .variants.d.ts when every custom value is non-augmentable', () => {
+ it('does not emit a .variants.d.ts when every custom value is non-augmentable', async () => {
const themeFile = writeTheme(
tmpDir,
`export default {
@@ -152,7 +130,7 @@ describe('theme build custom-variant augmentations', () => {
};\n`,
);
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(tmpDir, themeFile)],
tmpDir,
);
@@ -162,7 +140,7 @@ describe('theme build custom-variant augmentations', () => {
).toBe(false);
});
- it('references the variants file from the main .d.ts so the augmentation loads', () => {
+ it('references the variants file from the main .d.ts so the augmentation loads', async () => {
const themeFile = writeTheme(
tmpDir,
`export default {
@@ -174,7 +152,7 @@ describe('theme build custom-variant augmentations', () => {
};\n`,
);
- const result = runCli(
+ const result = await runCli(
['theme', 'build', path.relative(tmpDir, themeFile)],
tmpDir,
);
diff --git a/packages/cli/cli/commands/detail-levels.test.mjs b/packages/cli/cli/commands/detail-levels.test.mjs
index 690df46a6a..e0bf7c5731 100644
--- a/packages/cli/cli/commands/detail-levels.test.mjs
+++ b/packages/cli/cli/commands/detail-levels.test.mjs
@@ -16,40 +16,27 @@
* duplicated `compact`.
*/
-import {describe, it, expect} from 'vitest';
-import {spawnSync} from 'node:child_process';
+import {describe, it, expect, beforeAll} from 'vitest';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
+import {runCli} from '../../test-utils/run-cli.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
// Repo root holds packages/core, which findCoreDir() walks up to locate.
const REPO_ROOT = path.resolve(__dirname, '../../../..');
-function runCli(args) {
- const res = spawnSync('node', [CLI_BIN, ...args], {
- cwd: REPO_ROOT,
- encoding: 'utf-8',
- timeout: 60_000,
- // component.full JSON can exceed the default 1MB stdout buffer.
- maxBuffer: 64 * 1024 * 1024,
- });
- return {
- status: res.status,
- stdout: res.stdout || '',
- stderr: res.stderr || '',
- };
-}
-
-function listOutputs(cmd) {
- const brief = runCli([cmd, '--list', '--detail', 'brief']).stdout;
- const compact = runCli([cmd, '--list', '--detail', 'compact']).stdout;
- const full = runCli([cmd, '--list', '--detail', 'full']).stdout;
+async function listOutputs(cmd) {
+ const brief = (await runCli([cmd, '--list', '--detail', 'brief'], REPO_ROOT)).stdout;
+ const compact = (await runCli([cmd, '--list', '--detail', 'compact'], REPO_ROOT)).stdout;
+ const full = (await runCli([cmd, '--list', '--detail', 'full'], REPO_ROOT)).stdout;
return {brief, compact, full};
}
describe('--detail level ordering: component --list', () => {
- const {brief, compact, full} = listOutputs('component');
+ let brief, compact, full;
+ beforeAll(async () => {
+ ({brief, compact, full} = await listOutputs('component'));
+ }, 60_000);
it('produces strictly increasing output size: brief < compact < full', () => {
expect(brief.length).toBeGreaterThan(0);
@@ -82,8 +69,8 @@ describe('--detail level ordering: component --list', () => {
expect(full).toMatch(/children/);
});
- it('full --json returns a valid component.full envelope', () => {
- const {stdout} = runCli(['component', '--list', '--detail', 'full', '--json']);
+ it('full --json returns a valid component.full envelope', async () => {
+ const {stdout} = await runCli(['component', '--list', '--detail', 'full', '--json'], REPO_ROOT);
const parsed = JSON.parse(stdout);
expect(parsed.type).toBe('component.full');
expect(parsed.apiVersion).toBe(1);
@@ -92,7 +79,10 @@ describe('--detail level ordering: component --list', () => {
});
describe('--detail level ordering: hook --list', () => {
- const {brief, compact, full} = listOutputs('hook');
+ let brief, compact, full;
+ beforeAll(async () => {
+ ({brief, compact, full} = await listOutputs('hook'));
+ }, 60_000);
it('produces strictly increasing output size: brief < compact < full', () => {
expect(brief.length).toBeGreaterThan(0);
@@ -123,8 +113,8 @@ describe('--detail level ordering: hook --list', () => {
expect(full).toMatch(/import \{/);
});
- it('full --json returns a valid hook.full envelope', () => {
- const {stdout} = runCli(['hook', '--list', '--detail', 'full', '--json']);
+ it('full --json returns a valid hook.full envelope', async () => {
+ const {stdout} = await runCli(['hook', '--list', '--detail', 'full', '--json'], REPO_ROOT);
const parsed = JSON.parse(stdout);
expect(parsed.type).toBe('hook.full');
expect(parsed.apiVersion).toBe(1);
diff --git a/packages/cli/cli/commands/import-hint-correctness.test.mjs b/packages/cli/cli/commands/import-hint-correctness.test.mjs
index 925613d99e..182579d5e1 100644
--- a/packages/cli/cli/commands/import-hint-correctness.test.mjs
+++ b/packages/cli/cli/commands/import-hint-correctness.test.mjs
@@ -14,7 +14,6 @@
*/
import {describe, it, expect} from 'vitest';
-import {execFileSync} from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
@@ -24,29 +23,11 @@ import {
findComponentSource,
} from './component/index.mjs';
import {findCoreDir} from '../../utils/paths.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
const REPO_ROOT = path.resolve(__dirname, '../../../..');
-function runCli(args) {
- try {
- const out = execFileSync('node', [CLI_BIN, ...args], {
- cwd: REPO_ROOT,
- encoding: 'utf-8',
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0'},
- });
- return {code: 0, stdout: out, stderr: ''};
- } catch (e) {
- return {
- code: e.status ?? 1,
- stdout: e.stdout?.toString() ?? '',
- stderr: e.stderr?.toString() ?? '',
- };
- }
-}
-
describe('import hint correctness', () => {
const coreDir = findCoreDir();
const pkg = JSON.parse(
@@ -120,8 +101,8 @@ describe('import hint correctness', () => {
];
for (const {name, expected} of representative) {
- it(`npx astryx component ${name} --detail brief shows ${expected}`, () => {
- const result = runCli(['component', name, '--detail', 'brief']);
+ it(`npx astryx component ${name} --detail brief shows ${expected}`, async () => {
+ const result = await runCli(['component', name, '--detail', 'brief'], REPO_ROOT);
expect(result.code).toBe(0);
expect(result.stdout).toContain(expected);
});
@@ -132,8 +113,8 @@ describe('import hint correctness', () => {
const representative = ['Button', 'Theme', 'Table', 'CheckboxInput'];
for (const name of representative) {
- it(`npx astryx component ${name} (full) includes import statement`, () => {
- const result = runCli(['component', name]);
+ it(`npx astryx component ${name} (full) includes import statement`, async () => {
+ const result = await runCli(['component', name], REPO_ROOT);
expect(result.code).toBe(0);
// The PR adds: **Import:** `import {XDS...} from '...';`
expect(result.stdout).toMatch(/import\s*\{/);
diff --git a/packages/cli/cli/commands/init.behavior.test.mjs b/packages/cli/cli/commands/init.behavior.test.mjs
new file mode 100644
index 0000000000..b252aee3e1
--- /dev/null
+++ b/packages/cli/cli/commands/init.behavior.test.mjs
@@ -0,0 +1,124 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Behavior coverage for `astryx init`.
+ *
+ * init.next-steps.test.mjs covers the pure getNextSteps() copy; this file
+ * covers what the COMMAND actually does — the file writes, feature flags,
+ * agent presets, idempotency, and error exits — by driving the real program
+ * in-process (test-utils/run-cli.mjs) against a throwaway cwd. init reads
+ * process.cwd(), which the harness sets to the temp dir per run.
+ *
+ * These lock the non-interactive contract: `astryx init` never prompts, is
+ * safe to re-run, writes the tool-agnostic AGENTS.md by default, and fails
+ * loudly (non-zero) only on bad input.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const MARKER_START = '<!-- ASTRYX:START -->';
+
+let tmpDir;
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-init-behavior-'));
+});
+
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} rel */
+const read = rel => fs.readFileSync(path.join(tmpDir, rel), 'utf8');
+/** @param {string} rel */
+const exists = rel => fs.existsSync(path.join(tmpDir, rel));
+
+describe('astryx init — default (no flags)', () => {
+ it('installs the tool-agnostic AGENTS.md cheat sheet and prints next steps', async () => {
+ const {status, stdout} = await runCli(['init'], {cwd: tmpDir});
+ expect(status).toBe(0);
+ expect(exists('AGENTS.md')).toBe(true);
+ expect(read('AGENTS.md')).toContain(MARKER_START);
+ // The non-interactive default always emits the getting-started guidance.
+ expect(stdout).toMatch(/Next steps:/);
+ });
+
+ it('is non-interactive: exits cleanly with no TTY and no prompt text', async () => {
+ const {status, stdout, stderr} = await runCli(['init'], {cwd: tmpDir});
+ expect(status).toBe(0);
+ // A prompt would ask a question; the non-interactive contract forbids it.
+ expect(stdout).not.toMatch(/\?\s*$/m);
+ expect(stderr).not.toMatch(/prompt|inquirer/i);
+ });
+
+ it('is idempotent: re-running keeps a single Astryx block (no duplication)', async () => {
+ await runCli(['init'], {cwd: tmpDir});
+ await runCli(['init'], {cwd: tmpDir});
+ const contents = read('AGENTS.md');
+ const blocks = contents.split(MARKER_START).length - 1;
+ expect(blocks).toBe(1);
+ });
+});
+
+describe('astryx init --features', () => {
+ it('--features agents writes AGENTS.md only', async () => {
+ const {status} = await runCli(['init', '--features', 'agents'], {cwd: tmpDir});
+ expect(status).toBe(0);
+ expect(exists('AGENTS.md')).toBe(true);
+ });
+
+ it('--features theme writes no files and points at the theme workflow', async () => {
+ const {status, stdout} = await runCli(['init', '--features', 'theme'], {cwd: tmpDir});
+ expect(status).toBe(0);
+ expect(fs.readdirSync(tmpDir)).toEqual([]);
+ expect(stdout).toMatch(/theme/i);
+ });
+
+ it('rejects an unknown feature with exit 1 and a helpful message', async () => {
+ const {status, stderr} = await runCli(['init', '--features', 'bogus'], {cwd: tmpDir});
+ expect(status).toBe(1);
+ expect(stderr).toMatch(/Unknown features: bogus/);
+ expect(stderr).toMatch(/agents, theme, template/);
+ // A rejected run must not have written anything.
+ expect(fs.readdirSync(tmpDir)).toEqual([]);
+ });
+
+ it('--all installs every feature (AGENTS.md present, exit 0)', async () => {
+ const {status} = await runCli(['init', '--all'], {cwd: tmpDir});
+ expect(status).toBe(0);
+ expect(exists('AGENTS.md')).toBe(true);
+ });
+});
+
+describe('astryx init --agent <preset>', () => {
+ it('--agent claude targets .claude/CLAUDE.md', async () => {
+ const {status} = await runCli(['init', '--agent', 'claude'], {cwd: tmpDir});
+ expect(status).toBe(0);
+ expect(exists('.claude/CLAUDE.md')).toBe(true);
+ expect(read('.claude/CLAUDE.md')).toContain(MARKER_START);
+ });
+
+ it('--agent all creates both the AGENTS.md and Claude defaults', async () => {
+ const {status} = await runCli(['init', '--agent', 'all'], {cwd: tmpDir});
+ expect(status).toBe(0);
+ expect(exists('AGENTS.md')).toBe(true);
+ expect(exists('.claude/CLAUDE.md')).toBe(true);
+ });
+});
+
+describe('astryx init --remove-agents', () => {
+ it('removes the Astryx section it previously installed', async () => {
+ await runCli(['init', '--features', 'agents'], {cwd: tmpDir});
+ expect(exists('AGENTS.md')).toBe(true);
+
+ const {status, stdout} = await runCli(['init', '--remove-agents'], {cwd: tmpDir});
+ expect(status).toBe(0);
+ expect(stdout).toMatch(/removed/i);
+ // AGENTS.md was created solely by us and is now empty → deleted.
+ expect(exists('AGENTS.md')).toBe(false);
+ });
+});
diff --git a/packages/cli/cli/commands/json-contract.test.mjs b/packages/cli/cli/commands/json-contract.test.mjs
index 73364d58f7..ba4200f998 100644
--- a/packages/cli/cli/commands/json-contract.test.mjs
+++ b/packages/cli/cli/commands/json-contract.test.mjs
@@ -3,21 +3,19 @@
/**
* @file Integration tests for the global --json contract.
*
- * These tests spawn the CLI as a subprocess (the only way to exercise
- * Commander hooks end-to-end) in a tmp directory, then assert:
+ * These drive the REAL program IN-PROCESS (createProgram + parseAsync via the
+ * shared runCli harness), which exercises Commander's preAction hooks, the
+ * --json gate, and process.exit end-to-end without a per-assertion subprocess.
+ * Assertions:
*
* 1. Commands NOT on the JSON_SUPPORTED allowlist reject --json BEFORE
* running any side effects (no files written, exit 1, valid JSON
* error envelope on stdout).
- *
- * 2. Commands ON the allowlist emit valid JSON envelopes for their
- * common code paths (success and error).
- *
- * 3. The --version --json variant emits a structured envelope.
- *
- * Spawning a real subprocess (vs. importing program.mjs) is essential
- * because Commander's preAction hooks and process.exit calls only fire
- * during a real .parse() against argv.
+ * 2. Commands ON the allowlist emit valid JSON envelopes for their common
+ * code paths (success and error).
+ * 3. The --version --json variant emits a structured envelope. This one is
+ * intercepted at the bin argv layer (before Commander), so it is the sole
+ * case that must spawn the real binary.
*/
import {describe, it, expect, beforeEach, afterEach} from 'vitest';
@@ -26,21 +24,19 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import {fileURLToPath} from 'node:url';
+import {runCli} from '../../test-utils/run-cli.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-function runCli(args, {cwd} = {}) {
+// `--version --json` is handled at the bin argv layer (before Commander ever
+// runs), so it can only be exercised by spawning the real binary.
+function runCliSpawn(args) {
const res = spawnSync('node', [CLI_BIN, ...args], {
- cwd: cwd || process.cwd(),
encoding: 'utf-8',
timeout: 20_000,
});
- return {
- status: res.status,
- stdout: res.stdout || '',
- stderr: res.stderr || '',
- };
+ return {status: res.status, stdout: res.stdout || '', stderr: res.stderr || ''};
}
function parseJson(stdout) {
@@ -61,11 +57,11 @@ afterEach(() => {
});
describe('--json contract: rejects before side effects', () => {
- it('astryx init --json --features agents does not write agent docs', () => {
+ it('astryx init --json --features agents does not write agent docs', async () => {
const before = fs.readdirSync(tmpDir);
expect(before).toEqual([]);
- const {status, stdout} = runCli(['init', '--json', '--features', 'agents'], {cwd: tmpDir});
+ const {status, stdout} = await runCli(['init', '--json', '--features', 'agents'], {cwd: tmpDir});
// 1. Exit code must be non-zero.
expect(status).toBe(1);
@@ -84,15 +80,15 @@ describe('--json contract: rejects before side effects', () => {
expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
});
- it('astryx init --json --all does not write any files', () => {
- const {status, stdout} = runCli(['init', '--json', '--all'], {cwd: tmpDir});
+ it('astryx init --json --all does not write any files', async () => {
+ const {status, stdout} = await runCli(['init', '--json', '--all'], {cwd: tmpDir});
expect(status).toBe(1);
parseJson(stdout); // valid JSON
expect(fs.readdirSync(tmpDir)).toEqual([]);
});
- it('astryx theme --json (parent, no subcommand) rejects without printing help', () => {
- const {status, stdout, stderr} = runCli(['theme', '--json'], {cwd: tmpDir});
+ it('astryx theme --json (parent, no subcommand) rejects without printing help', async () => {
+ const {status, stdout, stderr} = await runCli(['theme', '--json'], {cwd: tmpDir});
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.error).toMatch(/theme/);
@@ -101,15 +97,15 @@ describe('--json contract: rejects before side effects', () => {
expect(stderr).not.toMatch(/Usage:/);
});
- it('astryx postinstall --json rejects (hidden command not on allowlist)', () => {
- const {status, stdout} = runCli(['postinstall', '--json'], {cwd: tmpDir});
+ it('astryx postinstall --json rejects (hidden command not on allowlist)', async () => {
+ const {status, stdout} = await runCli(['postinstall', '--json'], {cwd: tmpDir});
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed).toHaveProperty('error');
});
- it('error envelope is { error, suggestions? } — never { type, data }', () => {
- const {stdout} = runCli(['init', '--json'], {cwd: tmpDir});
+ it('error envelope is { error, suggestions? } — never { type, data }', async () => {
+ const {stdout} = await runCli(['init', '--json'], {cwd: tmpDir});
const parsed = parseJson(stdout);
expect(parsed).toHaveProperty('error');
expect(parsed).not.toHaveProperty('type');
@@ -119,7 +115,7 @@ describe('--json contract: rejects before side effects', () => {
describe('--json contract: supported commands emit valid envelopes', () => {
it('astryx --version --json emits { type: "version", data: { version } }', () => {
- const {status, stdout} = runCli(['--version', '--json']);
+ const {status, stdout} = runCliSpawn(['--version', '--json']);
expect(status).toBe(0);
const parsed = parseJson(stdout);
expect(parsed.type).toBe('version');
@@ -127,8 +123,8 @@ describe('--json contract: supported commands emit valid envelopes', () => {
expect(typeof parsed.data.version).toBe('string');
});
- it('astryx --json (no subcommand) emits a help envelope', () => {
- const {status, stdout} = runCli(['--json']);
+ it('astryx --json (no subcommand) emits a help envelope', async () => {
+ const {status, stdout} = await runCli(['--json']);
expect(status).toBe(0);
const parsed = parseJson(stdout);
expect(parsed.type).toBe('help');
@@ -136,15 +132,15 @@ describe('--json contract: supported commands emit valid envelopes', () => {
expect(Array.isArray(parsed.data.jsonSupported)).toBe(true);
});
- it('astryx upgrade --json --list returns the codemod list', () => {
- const {status, stdout} = runCli(['upgrade', '--json', '--list'], {cwd: tmpDir});
+ it('astryx upgrade --json --list returns the codemod list', async () => {
+ const {status, stdout} = await runCli(['upgrade', '--json', '--list'], {cwd: tmpDir});
expect(status).toBe(0);
const parsed = parseJson(stdout);
expect(parsed.type).toBe('upgrade.list');
expect(Array.isArray(parsed.data)).toBe(true);
});
- it('astryx upgrade --json (already up to date) emits upgrade.status', () => {
+ it('astryx upgrade --json (already up to date) emits upgrade.status', async () => {
// Force a no-op range: from > installed target.
const coreDir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
fs.mkdirSync(coreDir, {recursive: true});
@@ -153,7 +149,7 @@ describe('--json contract: supported commands emit valid envelopes', () => {
JSON.stringify({name: '@astryxdesign/core', version: '0.0.1'}, null, 2),
);
- const {status, stdout} = runCli(
+ const {status, stdout} = await runCli(
['upgrade', '--json', '--from', '99.0.0'],
{cwd: tmpDir},
);
@@ -165,8 +161,8 @@ describe('--json contract: supported commands emit valid envelopes', () => {
expect(parsed.data.to).toBe('0.0.1');
});
- it('astryx discover --json (no config) includes meta.configured=false', () => {
- const {status, stdout} = runCli(['discover', '--json'], {cwd: tmpDir});
+ it('astryx discover --json (no config) includes meta.configured=false', async () => {
+ const {status, stdout} = await runCli(['discover', '--json'], {cwd: tmpDir});
expect(status).toBe(0);
const parsed = parseJson(stdout);
expect(parsed.type).toBe('discover.list');
@@ -174,24 +170,24 @@ describe('--json contract: supported commands emit valid envelopes', () => {
expect(parsed.meta).toEqual({configured: false});
});
- it('astryx template --json emits a typed envelope', () => {
- const {status, stdout} = runCli(['template', '--json'], {cwd: tmpDir});
+ it('astryx template --json emits a typed envelope', async () => {
+ const {status, stdout} = await runCli(['template', '--json'], {cwd: tmpDir});
expect(status).toBe(0);
const parsed = parseJson(stdout);
expect(parsed.type).toBe('template.list');
expect(Array.isArray(parsed.data)).toBe(true);
});
- it('astryx docs --json emits a typed envelope', () => {
- const {status, stdout} = runCli(['docs', '--json'], {cwd: tmpDir});
+ it('astryx docs --json emits a typed envelope', async () => {
+ const {status, stdout} = await runCli(['docs', '--json'], {cwd: tmpDir});
expect(status).toBe(0);
const parsed = parseJson(stdout);
expect(parsed.type).toMatch(/^docs\./);
});
- it('astryx doctor --json emits a doctor envelope with checks + summary', () => {
+ it('astryx doctor --json emits a doctor envelope with checks + summary', async () => {
// Run in a bare tmp dir → @astryxdesign/core won't resolve → a FAIL → exit 1.
- const {status, stdout} = runCli(['doctor', '--json'], {cwd: tmpDir});
+ const {status, stdout} = await runCli(['doctor', '--json'], {cwd: tmpDir});
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.type).toBe('doctor');
diff --git a/packages/cli/cli/commands/search.test.mjs b/packages/cli/cli/commands/search.test.mjs
index 62bcf06d61..c9440ed39e 100644
--- a/packages/cli/cli/commands/search.test.mjs
+++ b/packages/cli/cli/commands/search.test.mjs
@@ -11,13 +11,12 @@
*/
import {describe, it, expect} from 'vitest';
-import {spawnSync} from 'node:child_process';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {search, scoreCandidate, SEARCH_DOMAINS} from '../../api/search/search.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
// Run against the monorepo root so @astryxdesign/core is discoverable.
const REPO_ROOT = path.resolve(__dirname, '../../../..');
const OPTS = {cwd: REPO_ROOT};
@@ -29,15 +28,6 @@ const OPTS = {cwd: REPO_ROOT};
// the vitest per-test timeout. Give both the same generous scan budget.
const SCAN_TIMEOUT = 30_000;
-function runCli(args) {
- const res = spawnSync('node', [CLI_BIN, ...args], {
- cwd: REPO_ROOT,
- encoding: 'utf-8',
- timeout: 30_000,
- });
- return {status: res.status, stdout: res.stdout || '', stderr: res.stderr || ''};
-}
-
describe('search() API — ranking', () => {
it('ranks an exact component name match first', async () => {
const {data} = await search('button', OPTS);
@@ -161,29 +151,29 @@ describe('scoreCandidate()', () => {
});
describe('search CLI — exit codes + JSON contract', () => {
- it('exits 0 for a successful search', () => {
- const r = runCli(['search', 'button']);
+ it('exits 0 for a successful search', async () => {
+ const r = await runCli(['search', 'button'], REPO_ROOT);
expect(r.status).toBe(0);
});
- it('exits 0 for a no-match query (valid empty result, not failure)', () => {
- const r = runCli(['search', 'zzqqxx_no_match']);
+ it('exits 0 for a no-match query (valid empty result, not failure)', async () => {
+ const r = await runCli(['search', 'zzqqxx_no_match'], REPO_ROOT);
expect(r.status).toBe(0);
expect(r.stdout).toContain('No results');
});
- it('exits 1 for an invalid --type', () => {
- const r = runCli(['search', 'x', '--type', 'bogus']);
+ it('exits 1 for an invalid --type', async () => {
+ const r = await runCli(['search', 'x', '--type', 'bogus'], REPO_ROOT);
expect(r.status).toBe(1);
});
- it('exits 1 for an invalid --limit', () => {
- const r = runCli(['search', 'x', '--limit', '0']);
+ it('exits 1 for an invalid --limit', async () => {
+ const r = await runCli(['search', 'x', '--limit', '0'], REPO_ROOT);
expect(r.status).toBe(1);
});
- it('emits a valid --json envelope', () => {
- const r = runCli(['--json', 'search', 'button']);
+ it('emits a valid --json envelope', async () => {
+ const r = await runCli(['--json', 'search', 'button'], REPO_ROOT);
expect(r.status).toBe(0);
const parsed = JSON.parse(r.stdout);
expect(parsed.apiVersion).toBe(1);
@@ -193,16 +183,16 @@ describe('search CLI — exit codes + JSON contract', () => {
expect(parsed.data.results[0].name).toBe('Button');
});
- it('emits a valid --json envelope with empty results for no match', () => {
- const r = runCli(['--json', 'search', 'zzqqxx_no_match']);
+ it('emits a valid --json envelope with empty results for no match', async () => {
+ const r = await runCli(['--json', 'search', 'zzqqxx_no_match'], REPO_ROOT);
expect(r.status).toBe(0);
const parsed = JSON.parse(r.stdout);
expect(parsed.type).toBe('search');
expect(parsed.data.results).toEqual([]);
});
- it('shows the follow-up command hint in human output', () => {
- const r = runCli(['search', 'button']);
+ it('shows the follow-up command hint in human output', async () => {
+ const r = await runCli(['search', 'button'], REPO_ROOT);
expect(r.stdout).toContain('astryx component Button');
expect(r.stdout).toContain('[component]');
});
diff --git a/packages/cli/cli/commands/setup-nudge.test.mjs b/packages/cli/cli/commands/setup-nudge.test.mjs
index 814aa91a54..5923a11f2a 100644
--- a/packages/cli/cli/commands/setup-nudge.test.mjs
+++ b/packages/cli/cli/commands/setup-nudge.test.mjs
@@ -13,15 +13,12 @@
*/
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';
import {isAstryxInitialized} from '../../lib/agent-docs/agent-docs.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI = path.resolve(__dirname, '..', '..', 'bin', 'astryx.mjs');
const MARKER = '<!-- ASTRYX:START -->';
const NUDGE = /finish setup and install the Astryx agent prompt/;
@@ -39,15 +36,6 @@ function write(rel, body) {
fs.writeFileSync(p, body);
}
-function run(args, cwd = tmp) {
- return spawnSync(process.execPath, [CLI, ...args], {
- cwd,
- encoding: 'utf8',
- timeout: 30_000,
- env: {...process.env, FORCE_COLOR: '0'},
- });
-}
-
describe('isAstryxInitialized — centralized setup check (one place)', () => {
it('is false in an empty project', () => {
expect(isAstryxInitialized(tmp)).toBe(false);
@@ -76,33 +64,33 @@ describe('isAstryxInitialized — centralized setup check (one place)', () => {
describe('enforcement layer 3 — per-command setup nudge', () => {
const asProject = () => write('package.json', '{"name":"t"}');
- it('nudges on stderr after a command when not set up', () => {
+ it('nudges on stderr after a command when not set up', async () => {
asProject();
- const r = run(['docs', 'tokens']);
+ const r = await runCli(['docs', 'tokens'], tmp);
expect(r.stderr).toMatch(NUDGE);
});
- it('is suppressed in --json (machine mode stays clean), stdout valid JSON', () => {
+ it('is suppressed in --json (machine mode stays clean), stdout valid JSON', async () => {
asProject();
- const r = run(['--json', 'docs', 'tokens']);
+ const r = await runCli(['--json', 'docs', 'tokens'], tmp);
// --json is machine output with a clean stdout+stderr contract; the human
// nudge must NOT leak into it (json-shim: error envelopes have empty stderr).
expect(r.stderr).not.toMatch(NUDGE);
expect(() => JSON.parse(r.stdout)).not.toThrow();
});
- it('is quiet once set up (marker present)', () => {
+ it('is quiet once set up (marker present)', async () => {
asProject();
write('AGENTS.md', MARKER);
- expect(run(['docs', 'tokens']).stderr).not.toMatch(NUDGE);
+ expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
});
- it('is quiet outside a project (no package.json)', () => {
- expect(run(['docs', 'tokens']).stderr).not.toMatch(NUDGE);
+ it('is quiet outside a project (no package.json)', async () => {
+ expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
});
- it('does not nudge for the installer command itself', () => {
+ it('does not nudge for the installer command itself', async () => {
asProject();
- expect(run(['init']).stderr).not.toMatch(NUDGE);
+ expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);
});
});
diff --git a/packages/cli/cli/commands/swizzle.path-safety.test.mjs b/packages/cli/cli/commands/swizzle.path-safety.test.mjs
index d9d6b97374..7fcbcb62ef 100644
--- a/packages/cli/cli/commands/swizzle.path-safety.test.mjs
+++ b/packages/cli/cli/commands/swizzle.path-safety.test.mjs
@@ -3,20 +3,16 @@
/**
* @file Path-traversal regression tests for `astryx swizzle --output`.
*
- * Spawns the CLI bin with a fake monorepo as cwd and asserts that
+ * Runs the CLI in-process with a fake monorepo as cwd and asserts that
* `--output ../escaped` is rejected with a clear error AND that no
* file is created outside the project root.
*/
import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import {execFileSync} 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_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+import {runCli} from '../../test-utils/run-cli.mjs';
// Build a minimal fake monorepo: <root>/project/ contains a
// node_modules/@astryxdesign/core/src/Button so findCoreDir succeeds, and
@@ -38,24 +34,6 @@ function buildFakeRepo(tmpDir) {
return {project, outside};
}
-function runCli(args, cwd) {
- try {
- const out = execFileSync('node', [CLI_BIN, ...args], {
- cwd,
- encoding: 'utf-8',
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0'},
- });
- return {code: 0, stdout: out, stderr: ''};
- } catch (e) {
- return {
- code: e.status ?? 1,
- stdout: e.stdout?.toString() ?? '',
- stderr: e.stderr?.toString() ?? '',
- };
- }
-}
-
let tmpDir;
beforeEach(() => {
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-swizzle-paths-'));
@@ -65,10 +43,10 @@ afterEach(() => {
});
describe('swizzle path safety', () => {
- it('rejects --output with ../ traversal and writes no file outside root', () => {
+ it('rejects --output with ../ traversal and writes no file outside root', async () => {
const {project, outside} = buildFakeRepo(tmpDir);
- const result = runCli(
+ const result = await runCli(
['swizzle', 'Button', '--output', '../outside-project'],
project,
);
@@ -82,11 +60,11 @@ describe('swizzle path safety', () => {
expect(fs.existsSync(escaped)).toBe(false);
});
- it('rejects --output with absolute path', () => {
+ it('rejects --output with absolute path', async () => {
const {project} = buildFakeRepo(tmpDir);
const absTarget = path.join(tmpDir, 'absolute-target');
- const result = runCli(
+ const result = await runCli(
['swizzle', 'Button', '--output', absTarget],
project,
);
@@ -96,7 +74,7 @@ describe('swizzle path safety', () => {
expect(fs.existsSync(absTarget)).toBe(false);
});
- it('requires --overwrite in non-interactive mode when files already exist', () => {
+ it('requires --overwrite in non-interactive mode when files already exist', async () => {
const {project} = buildFakeRepo(tmpDir);
const outDir = path.join(project, 'components', 'astryx', 'Button');
fs.mkdirSync(outDir, {recursive: true});
@@ -104,7 +82,7 @@ describe('swizzle path safety', () => {
fs.writeFileSync(existingPath, '// my customizations\n');
// Use --json to force non-interactive mode.
- const result = runCli(
+ const result = await runCli(
['--json', 'swizzle', 'Button'],
project,
);
diff --git a/packages/cli/cli/commands/swizzle.routing.test.mjs b/packages/cli/cli/commands/swizzle.routing.test.mjs
index 40051eb32e..d19eff6b4e 100644
--- a/packages/cli/cli/commands/swizzle.routing.test.mjs
+++ b/packages/cli/cli/commands/swizzle.routing.test.mjs
@@ -4,7 +4,7 @@
* @file Integration-routing tests for `astryx swizzle`.
*
* `rewriteImports` is unit-tested in swizzle.test.mjs. These tests exercise the
- * end-to-end command behavior by spawning the CLI bin against hermetic
+ * end-to-end command behavior by running the CLI in-process against hermetic
* fixtures: a fake @astryxdesign/core under node_modules plus, for the
* integration cases, a configured integration package (astryx.config.mjs +
* astryx.integration.mjs + a `components` dir) — all under node_modules so the
@@ -12,14 +12,10 @@
*/
import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import {execFileSync} 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_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+import {runCli} from '../../test-utils/run-cli.mjs';
/**
* Build a fake @astryxdesign/core under <project>/node_modules with a single
@@ -108,24 +104,6 @@ function writeProjectPackageJson(project, extra = {}) {
);
}
-function runCli(args, cwd) {
- try {
- const out = execFileSync('node', [CLI_BIN, ...args], {
- cwd,
- encoding: 'utf-8',
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {...process.env, FORCE_COLOR: '0'},
- });
- return {code: 0, stdout: out, stderr: ''};
- } catch (e) {
- return {
- code: e.status ?? 1,
- stdout: e.stdout?.toString() ?? '',
- stderr: e.stderr?.toString() ?? '',
- };
- }
-}
-
let tmpDir;
let project;
beforeEach(() => {
@@ -138,7 +116,7 @@ afterEach(() => {
});
describe('swizzle — core feedback routing via config', () => {
- it('routes core feedback to config.issuesUrl when set', () => {
+ it('routes core feedback to config.issuesUrl when set', async () => {
buildFakeCore(project);
writeProjectPackageJson(project);
fs.writeFileSync(
@@ -146,7 +124,7 @@ describe('swizzle — core feedback routing via config', () => {
`export default {issuesUrl: 'https://github.com/acme/ds/issues'};\n`,
);
- const result = runCli(['--json', 'swizzle', 'Button', '-f'], project);
+ const result = await runCli(['--json', 'swizzle', 'Button', '-f'], project);
expect(result.code).toBe(0);
const env = JSON.parse(result.stdout);
expect(env.type).toBe('swizzle.copy');
@@ -161,11 +139,11 @@ describe('swizzle — core feedback routing via config', () => {
expect(out).toContain(`from './helper'`);
});
- it('falls back to the default issues URL when config has none', () => {
+ it('falls back to the default issues URL when config has none', async () => {
buildFakeCore(project);
writeProjectPackageJson(project);
- const result = runCli(['--json', 'swizzle', 'Button', '-f'], project);
+ const result = await runCli(['--json', 'swizzle', 'Button', '-f'], project);
expect(result.code).toBe(0);
const env = JSON.parse(result.stdout);
expect(env.data.feedback.issuesUrl).toBe(
@@ -175,12 +153,12 @@ describe('swizzle — core feedback routing via config', () => {
});
describe('swizzle — integration-owned components', () => {
- it('copies the component dir (excluding test/doc), rewrites escaping imports to the owner package, routes feedback to the integration issuesUrl', () => {
+ it('copies the component dir (excluding test/doc), rewrites escaping imports to the owner package, routes feedback to the integration issuesUrl', async () => {
buildFakeCore(project);
writeProjectPackageJson(project);
buildIntegration(project, {issuesUrl: 'https://example.com/meta/issues'});
- const result = runCli(['--json', 'swizzle', 'MetaAppShell', '-f'], project);
+ const result = await runCli(['--json', 'swizzle', 'MetaAppShell', '-f'], project);
expect(result.code).toBe(0);
const env = JSON.parse(result.stdout);
expect(env.type).toBe('swizzle.copy');
@@ -200,12 +178,12 @@ describe('swizzle — integration-owned components', () => {
expect(out).toContain(`from './sibling'`);
});
- it('omits the feedback note when the integration ships no issuesUrl', () => {
+ it('omits the feedback note when the integration ships no issuesUrl', async () => {
buildFakeCore(project);
writeProjectPackageJson(project);
buildIntegration(project, {issuesUrl: null});
- const result = runCli(['--json', 'swizzle', 'MetaAppShell', '-f'], project);
+ const result = await runCli(['--json', 'swizzle', 'MetaAppShell', '-f'], project);
expect(result.code).toBe(0);
const env = JSON.parse(result.stdout);
expect(env.type).toBe('swizzle.copy');
@@ -215,7 +193,7 @@ describe('swizzle — integration-owned components', () => {
});
describe('swizzle — ambiguous ownership', () => {
- it('errors when a name is owned by core + an integration and no --package is given', () => {
+ it('errors when a name is owned by core + an integration and no --package is given', async () => {
buildFakeCore(project);
writeProjectPackageJson(project);
// Integration also provides "Button" (collides with core).
@@ -224,7 +202,7 @@ describe('swizzle — ambiguous ownership', () => {
componentName: 'Button',
});
- const result = runCli(['--json', 'swizzle', 'Button', '-f'], project);
+ const result = await runCli(['--json', 'swizzle', 'Button', '-f'], project);
expect(result.code).not.toBe(0);
const env = JSON.parse(result.stdout);
expect(env.code).toBe('ERR_AMBIGUOUS_COMPONENT');
@@ -233,7 +211,7 @@ describe('swizzle — ambiguous ownership', () => {
expect(pkgs).toContain('@test/meta');
});
- it('--package resolves an ambiguous name to the integration', () => {
+ it('--package resolves an ambiguous name to the integration', async () => {
buildFakeCore(project);
writeProjectPackageJson(project);
buildIntegration(project, {
@@ -241,7 +219,7 @@ describe('swizzle — ambiguous ownership', () => {
componentName: 'Button',
});
- const result = runCli(
+ const result = await runCli(
['--json', 'swizzle', 'Button', '--package', '@test/meta', '-f'],
project,
);
@@ -255,7 +233,7 @@ describe('swizzle — ambiguous ownership', () => {
expect(out).toContain(`from '@test/meta/utils'`);
});
- it('--package resolves an ambiguous name to core', () => {
+ it('--package resolves an ambiguous name to core', async () => {
buildFakeCore(project);
writeProjectPackageJson(project);
buildIntegration(project, {
@@ -263,7 +241,7 @@ describe('swizzle — ambiguous ownership', () => {
componentName: 'Button',
});
- const result = runCli(
+ const result = await runCli(
['--json', 'swizzle', 'Button', '--package', '@astryxdesign/core', '-f'],
project,
);
@@ -311,18 +289,18 @@ function buildStyleXCore(project) {
}
describe('swizzle — StyleX build setup note (#3373)', () => {
- it('reports usesStyleX and prints a setup note for StyleX components', () => {
+ it('reports usesStyleX and prints a setup note for StyleX components', async () => {
buildStyleXCore(project);
writeProjectPackageJson(project);
// JSON payload carries the machine-readable flag.
- const jsonResult = runCli(['--json', 'swizzle', 'Styled', '-f'], project);
+ const jsonResult = await runCli(['--json', 'swizzle', 'Styled', '-f'], project);
expect(jsonResult.code).toBe(0);
const env = JSON.parse(jsonResult.stdout);
expect(env.data.usesStyleX).toBe(true);
// Human output surfaces the compiler requirement + Next.js caveat.
- const humanResult = runCli(['swizzle', 'Styled', '-f'], project);
+ const humanResult = await runCli(['swizzle', 'Styled', '-f'], project);
expect(humanResult.code).toBe(0);
expect(humanResult.stdout).toMatch(/StyleX compiler/i);
expect(humanResult.stdout).toMatch(/unstyled/i);
@@ -330,16 +308,16 @@ describe('swizzle — StyleX build setup note (#3373)', () => {
expect(humanResult.stdout).toMatch(/astryx docs styling/);
});
- it('does not print the StyleX note for components without StyleX', () => {
+ it('does not print the StyleX note for components without StyleX', async () => {
buildStyleXCore(project);
writeProjectPackageJson(project);
- const jsonResult = runCli(['--json', 'swizzle', 'Plain', '-f'], project);
+ const jsonResult = await runCli(['--json', 'swizzle', 'Plain', '-f'], project);
expect(jsonResult.code).toBe(0);
const env = JSON.parse(jsonResult.stdout);
expect(env.data.usesStyleX).toBe(false);
- const humanResult = runCli(['swizzle', 'Plain', '-f'], project);
+ const humanResult = await runCli(['swizzle', 'Plain', '-f'], project);
expect(humanResult.code).toBe(0);
expect(humanResult.stdout).not.toMatch(/StyleX compiler/i);
});
diff --git a/packages/cli/cli/e2e-smoke.test.mjs b/packages/cli/cli/e2e-smoke.test.mjs
new file mode 100644
index 0000000000..f0adf244aa
--- /dev/null
+++ b/packages/cli/cli/e2e-smoke.test.mjs
@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Real-binary e2e smoke — the process boundary the in-process harness
+ * cannot cover.
+ *
+ * Every other CLI suite now drives the program IN-PROCESS via
+ * test-utils/run-cli.mjs (createProgram + parseAsync), which is fast and
+ * deterministic but deliberately bypasses `bin/astryx.mjs`: the Node-version
+ * preflight gate, the realpath-based `importSrc` module resolution, the real
+ * `process.exit` code, and the top-level try/catch error boundary. This file is
+ * the small, high-signal counterweight that spawns the ACTUAL binary and asserts
+ * the things only a real process can prove:
+ *
+ * - the bin boots and a happy command exits 0;
+ * - a real command's output reaches stdout across the process boundary;
+ * - failures produce a NON-ZERO real exit code (not just process.exitCode);
+ * - the --json error boundary emits a valid envelope on stdout end-to-end;
+ * - Commander parse errors route through handleCommanderError in the REAL
+ * bin — i.e. the harness's in-process replica of that path matches reality.
+ *
+ * Keep this SMALL. Behavior/coverage of individual commands lives in their
+ * in-process suites; this only guards the boundary. Do not grow it into a
+ * per-command spawn suite (that flakiness is exactly what the rollout removed).
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
+
+/** Spawn the real binary. Returns the raw exit status + captured streams. */
+function spawnCli(args) {
+ const res = spawnSync(process.execPath, [CLI_BIN, ...args], {
+ encoding: 'utf8',
+ timeout: 30_000,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ // Deterministic output: no color, and don't let a CI env flip behavior.
+ env: {...process.env, FORCE_COLOR: '0', CI: ''},
+ });
+ return {
+ status: res.status,
+ stdout: res.stdout || '',
+ stderr: res.stderr || '',
+ };
+}
+
+describe('e2e smoke: real binary boots + exits (happy paths)', () => {
+ it('astryx --version boots and exits 0 with a semver', () => {
+ const {status, stdout} = spawnCli(['--version']);
+ expect(status).toBe(0);
+ expect(stdout).toMatch(/\d+\.\d+\.\d+/);
+ });
+
+ it('astryx template --list runs a real command and prints to stdout (exit 0)', () => {
+ // `template` is bundled with the CLI (no compiled core needed), so this
+ // exercises the full command-load path through the real bin without a build.
+ const {status, stdout} = spawnCli(['template', '--list']);
+ expect(status).toBe(0);
+ expect(stdout.trim().length).toBeGreaterThan(0);
+ });
+});
+
+describe('e2e smoke: real binary error boundary + exit codes', () => {
+ it('unknown command exits non-zero with a stderr message', () => {
+ const {status, stderr} = spawnCli(['definitely-not-a-real-command']);
+ expect(status).not.toBe(0);
+ expect(stderr).toMatch(/unknown command/i);
+ });
+
+ it('init --json is rejected with a real exit 1 + JSON error envelope on stdout', () => {
+ // Proves the whole chain across the process boundary: bin boots → Commander
+ // runs → preAction --json gate rejects init → error envelope on stdout →
+ // process really exits 1 (not merely process.exitCode set in-process).
+ const {status, stdout} = spawnCli(['init', '--json']);
+ expect(status).toBe(1);
+ const parsed = JSON.parse(stdout);
+ expect(parsed).toHaveProperty('error');
+ expect(parsed).not.toHaveProperty('type');
+ });
+
+ it('a Commander parse error routes through handleCommanderError in the real bin', () => {
+ // `theme build` with no <file> fails at parse time (missing argument) BEFORE
+ // any command action or core load. In --json mode the real bin must convert
+ // that CommanderError into a valid envelope on stdout with a mapped ERR_
+ // code and exit 1 — the exact path run-cli.mjs replicates in-process.
+ const {status, stdout} = spawnCli(['theme', 'build', '--json']);
+ expect(status).toBe(1);
+ const parsed = JSON.parse(stdout);
+ expect(parsed).toHaveProperty('error');
+ expect(parsed.code).toMatch(/^ERR_/);
+ });
+});
diff --git a/packages/cli/cli/index.mjs b/packages/cli/cli/index.mjs
index ca0cbbd0a9..ef3a72e68c 100644
--- a/packages/cli/cli/index.mjs
+++ b/packages/cli/cli/index.mjs
@@ -5,6 +5,11 @@
*
* Registers all commands via lazy loading. If one command fails to load
* (bad import, syntax error), the other commands still work.
+ *
+ * The program is built by {@link createProgram} — a factory so tests can drive
+ * a FRESH program in-process (via parseAsync) instead of spawning `node
+ * bin/astryx.mjs` per assertion. `bin/astryx.mjs` and legacy importers use the
+ * eager {@link program} singleton, which is just `await createProgram()`.
*/
import {Command, Option} from 'commander';
@@ -29,7 +34,8 @@ const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'
// Intercept `xds --version --json` (or `-V --json`) before Commander processes
// the version flag and exits. Commander's built-in version handler prints the
// raw version string and calls process.exit, bypassing our hooks — so the
-// only correct place to JSON-ify it is here.
+// only correct place to JSON-ify it is here. (Bin-time only: guarded on argv,
+// so importing this module in tests is a no-op.)
const _argv = process.argv.slice(2);
if (
(_argv.includes('--version') || _argv.includes('-V')) &&
@@ -40,8 +46,6 @@ if (
process.exit(0);
}
-export const program = new Command();
-
/**
* Allowlist of fully-qualified command names that natively support --json.
* Subcommands are listed by their full path (parent + leaf), e.g. "theme build".
@@ -72,208 +76,23 @@ export const JSON_SUPPORTED = new Set([
'layout grammar',
]);
-program
- .name('astryx')
- .description('Design system CLI — components, themes, and tooling')
- .version(pkg.version)
- .option('--zh', 'Output docs in Chinese Simplified')
- .option('--dense', 'Output docs in compressed dense format (token-efficient)')
- .addOption(
- new Option(
- '--lang <locale>',
- 'Output docs in specified language/format (en, zh, dense)',
- ).choices(['en', 'zh', 'dense']),
- )
- .addOption(
- new Option('--detail <level>', 'Output detail level (full, compact, brief)')
- .choices(['full', 'compact', 'brief'])
- .default('full'),
- )
- .option(
- '--json',
- 'Output as typed JSON. Success envelope: { type, data }. Error envelope: { error, suggestions? }.',
- )
- .addHelpCommand('help', 'Show all commands')
- .action((options, cmd) => {
- // If Commander handed us a positional that didn't match any subcommand,
- // treat it as "unknown command" — exit 1 with a helpful suggestion.
- // This is the bare-invocation handler; if cmd.args has content here,
- // none of the registered subcommands matched.
- const extras = (cmd && cmd.args) || [];
- if (extras.length > 0) {
- const unknown = String(extras[0]);
- const known = (program.commands || [])
- .filter((c) => !(/** @type {any} */ (c)._hidden) && c.name() !== 'help')
- .map((c) => c.name());
- const close = known
- .map((name) => ({name, distance: levenshteinDistance(unknown.toLowerCase(), name.toLowerCase())}))
- .filter((s) => s.distance <= 3)
- .sort((a, b) => a.distance - b.distance)
- .slice(0, 3)
- .map((s) => ({name: s.name, reason: 'did you mean this?'}));
- // If we have close matches, surface those. Otherwise list all known commands
- // so callers (including AI agents) can see what's available.
- const suggestions = close.length > 0
- ? close
- : known.map((name) => ({name, reason: 'available command'}));
- cliError(`unknown command '${unknown}'`, {suggestions, code: ERROR_CODES.ERR_UNKNOWN_COMMAND});
- return;
- }
-
- // `xds` (no subcommand) — print help, or emit a JSON envelope when --json.
- if (program.opts().json) {
- // Emit the full capability manifest so an agent can drive the entire
- // CLI from one call — no need to scrape `--help` text. We derive this
- // from Commander metadata (commands, args, flags) and layer on the
- // JSON_SUPPORTED allowlist + per-command response types. See
- // lib/manifest.mjs.
- //
- // Backwards-compat: the envelope keeps `type: 'help'` and the original
- // shallow fields (`name`, `version`, `commands` as a string[] of names,
- // `jsonSupported`) that earlier consumers read. The richer, structured
- // surface is embedded under `data.manifest` (and is also available
- // standalone via `astryx manifest --json` as `type: 'manifest'`).
- process.__xdsJsonHandled = true;
- const manifest = buildManifest(program, {
- jsonSupported: JSON_SUPPORTED,
- version: pkg.version,
- });
- console.log(JSON.stringify({
- apiVersion: API_VERSION,
- type: 'help',
- data: {
- name: manifest.name,
- version: manifest.version,
- // Original flat list of command names (string[]) — kept for compat.
- commands: manifest.commands.map((c) => c.name),
- jsonSupported: manifest.jsonSupported,
- // Enriched, self-describing surface (the full manifest payload).
- manifest,
- },
- }, null, 2));
- return;
- }
- program.help();
- });
-
/**
* Compute the fully qualified command name, e.g. "theme build" or "swizzle".
* @param {import('commander').Command} actionCommand
+ * @param {import('commander').Command} root the root program
* @returns {string}
*/
-function fullCommandName(actionCommand) {
+function fullCommandName(actionCommand, root) {
const parts = [];
/** @type {import('commander').Command | null} */
let cmd = actionCommand;
- while (cmd && cmd !== program) {
+ while (cmd && cmd !== root) {
parts.unshift(cmd.name());
cmd = cmd.parent;
}
return parts.join(' ');
}
-/**
- * Pre-action hook: gate --json BEFORE any command body runs.
- *
- * If --json is set on a command that is not on the JSON_SUPPORTED allowlist,
- * emit a structured error envelope and exit 1 — without running the command's
- * action (so no filesystem mutations, no interactive prompts, no spawned processes).
- *
- * This is the single source of truth for "command does not support --json".
- * Individual commands should NOT re-check this; they may assume that if their
- * action runs with --json, they are responsible for emitting an envelope on
- * every code path.
- */
-program.hook('preAction', (thisCommand, actionCommand) => {
- if (!program.opts().json) return;
- // Engage global JSON mode so humanLog()/humanWarn() across commands become
- // no-ops — stdout now carries only the JSON envelope.
- setJsonMode(true);
- // The root program's own action (no subcommand) is handled directly in
- // its action handler — let it through. fullCommandName is '' there.
- if (actionCommand === program) return;
- const fullName = fullCommandName(actionCommand);
- if (JSON_SUPPORTED.has(fullName)) return;
- process.__xdsJsonHandled = true;
- console.log(JSON.stringify({
- apiVersion: API_VERSION,
- error: `JSON output is not supported for the '${fullName}' command`,
- code: ERROR_CODES.ERR_INVALID_OPTION,
- }, null, 2));
- process.exit(1);
-});
-
-/**
- * Belt-and-suspenders postAction: if a "supported" command somehow forgot
- * to emit a JSON envelope on a code path, surface that as a structured error
- * rather than silent stdout corruption. This should never fire in practice;
- * if it does, it's a bug in the command implementation.
- */
-program.hook('postAction', (thisCommand, actionCommand) => {
- if (!program.opts().json) return;
- if (process.__xdsJsonHandled) return;
- const fullName = fullCommandName(actionCommand);
- console.log(JSON.stringify({
- apiVersion: API_VERSION,
- error: `Internal: '${fullName}' completed without emitting a JSON envelope`,
- }, null, 2));
- process.exit(1);
-});
-
-/**
- * Post-action hook: print update hint after any command output.
- * Only fires for commands that produce output agents read (component, docs, etc.).
- * Suppressed when --json is active to avoid contaminating stdout.
- */
-const UPDATE_HINT_COMMANDS = new Set(['component', 'docs']);
-program.hook('postAction', (thisCommand, actionCommand) => {
- if (program.opts().json) return;
- try {
- if (UPDATE_HINT_COMMANDS.has(actionCommand.name())) {
- const hint = checkForUpdate();
- if (hint) {
- console.error(`\n${hint}`);
- }
- }
- } catch {
- // Never let update check break the CLI
- }
-});
-
-/**
- * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
- * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
- * the user/agent that setup is missing.
- *
- * Uses `preAction` (not postAction) so it fires for EVERY valid command — even
- * ones whose action errors or calls process.exit (postAction is skipped then).
- *
- * Suppressed in --json: that is machine output with a strict clean stdout+stderr
- * contract (json-shim.test: "error envelopes have empty stderr"), and --json
- * consumers parse stdout, not stderr — a stderr nudge would not reach them anyway.
- * The core/cli postinstall layers already nudge at install time regardless of
- * --json; a machine-readable nudge could later be an envelope field. Also skipped
- * for the installer commands themselves and outside a project (no package.json).
- */
-const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
-program.hook('preAction', (thisCommand, actionCommand) => {
- try {
- if (program.opts().json) return; // machine mode — keep --json output clean
- if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
- const cwd = process.cwd();
- if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
- if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
- // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
- // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
- // one-off, or `<pm> astryx` when installed — never the bare `npx astryx` footgun.
- console.error(
- `\nNext step: run \`${getCliInvocation(cwd)} init\` to finish setup and install the Astryx agent prompt.`,
- );
- } catch {
- // Never let the nudge break a command.
- }
-});
-
/**
* Command registry — each command is lazy-loaded so a broken command
* doesn't take down the entire CLI.
@@ -301,59 +120,257 @@ const commands = [
},
];
-for (const cmd of commands) {
- try {
- const mod = await import(cmd.path);
- mod[cmd.register](program);
- } catch (e) {
- // Command fails to load but CLI still works
- program
- .command(cmd.name)
- .description(`(failed to load: ${/** @type {any} */ (e).message})`)
- .action(() => {
- console.error(`Command "${cmd.name}" failed to load:`);
- console.error(/** @type {any} */ (e).message);
- process.exit(1);
- });
- }
-}
+const UPDATE_HINT_COMMANDS = new Set(['component', 'docs']);
+const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+
+/**
+ * Build a fresh, fully-wired Astryx CLI program (root options, hooks, all
+ * commands, manifest/postinstall, json-shim). Async because commands are
+ * lazy-imported. Each call returns an independent Command so tests can
+ * parseAsync repeatedly without commander state leaking between runs.
+ *
+ * @returns {Promise<import('commander').Command>}
+ */
+export async function createProgram() {
+ const program = new Command();
+
+ program
+ .name('astryx')
+ .description('Design system CLI — components, themes, and tooling')
+ .version(pkg.version)
+ .option('--zh', 'Output docs in Chinese Simplified')
+ .option('--dense', 'Output docs in compressed dense format (token-efficient)')
+ .addOption(
+ new Option(
+ '--lang <locale>',
+ 'Output docs in specified language/format (en, zh, dense)',
+ ).choices(['en', 'zh', 'dense']),
+ )
+ .addOption(
+ new Option('--detail <level>', 'Output detail level (full, compact, brief)')
+ .choices(['full', 'compact', 'brief'])
+ .default('full'),
+ )
+ .option(
+ '--json',
+ 'Output as typed JSON. Success envelope: { type, data }. Error envelope: { error, suggestions? }.',
+ )
+ .addHelpCommand('help', 'Show all commands')
+ .action((options, cmd) => {
+ // If Commander handed us a positional that didn't match any subcommand,
+ // treat it as "unknown command" — exit 1 with a helpful suggestion.
+ // This is the bare-invocation handler; if cmd.args has content here,
+ // none of the registered subcommands matched.
+ const extras = (cmd && cmd.args) || [];
+ if (extras.length > 0) {
+ const unknown = String(extras[0]);
+ const known = (program.commands || [])
+ .filter((c) => !(/** @type {any} */ (c)._hidden) && c.name() !== 'help')
+ .map((c) => c.name());
+ const close = known
+ .map((name) => ({name, distance: levenshteinDistance(unknown.toLowerCase(), name.toLowerCase())}))
+ .filter((s) => s.distance <= 3)
+ .sort((a, b) => a.distance - b.distance)
+ .slice(0, 3)
+ .map((s) => ({name: s.name, reason: 'did you mean this?'}));
+ // If we have close matches, surface those. Otherwise list all known commands
+ // so callers (including AI agents) can see what's available.
+ const suggestions = close.length > 0
+ ? close
+ : known.map((name) => ({name, reason: 'available command'}));
+ cliError(`unknown command '${unknown}'`, {suggestions, code: ERROR_CODES.ERR_UNKNOWN_COMMAND});
+ return;
+ }
-// Capability manifest — a single, self-describing view of the whole CLI so
-// agents can discover every command, argument, flag, and response type without
-// scraping `--help`. `astryx manifest --json` is the dedicated surface; the bare
-// `xds --json` embeds the same payload under data.manifest for convenience.
-program
- .command('manifest')
- .description('Print the full CLI capability manifest (use with --json)')
- .action(() => {
- const manifest = buildManifest(program, {
- jsonSupported: JSON_SUPPORTED,
- version: pkg.version,
+ // `xds` (no subcommand) — print help, or emit a JSON envelope when --json.
+ if (program.opts().json) {
+ // Emit the full capability manifest so an agent can drive the entire
+ // CLI from one call — no need to scrape `--help` text. We derive this
+ // from Commander metadata (commands, args, flags) and layer on the
+ // JSON_SUPPORTED allowlist + per-command response types. See
+ // lib/manifest.mjs.
+ //
+ // Backwards-compat: the envelope keeps `type: 'help'` and the original
+ // shallow fields (`name`, `version`, `commands` as a string[] of names,
+ // `jsonSupported`) that earlier consumers read. The richer, structured
+ // surface is embedded under `data.manifest` (and is also available
+ // standalone via `astryx manifest --json` as `type: 'manifest'`).
+ process.__xdsJsonHandled = true;
+ const manifest = buildManifest(program, {
+ jsonSupported: JSON_SUPPORTED,
+ version: pkg.version,
+ });
+ console.log(JSON.stringify({
+ apiVersion: API_VERSION,
+ type: 'help',
+ data: {
+ name: manifest.name,
+ version: manifest.version,
+ // Original flat list of command names (string[]) — kept for compat.
+ commands: manifest.commands.map((c) => c.name),
+ jsonSupported: manifest.jsonSupported,
+ // Enriched, self-describing surface (the full manifest payload).
+ manifest,
+ },
+ }, null, 2));
+ return;
+ }
+ program.help();
});
- if (program.opts().json) {
- process.__xdsJsonHandled = true;
- console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest}, null, 2));
- return;
+
+ /**
+ * Pre-action hook: gate --json BEFORE any command body runs.
+ *
+ * If --json is set on a command that is not on the JSON_SUPPORTED allowlist,
+ * emit a structured error envelope and exit 1 — without running the command's
+ * action (so no filesystem mutations, no interactive prompts, no spawned processes).
+ *
+ * This is the single source of truth for "command does not support --json".
+ * Individual commands should NOT re-check this; they may assume that if their
+ * action runs with --json, they are responsible for emitting an envelope on
+ * every code path.
+ */
+ program.hook('preAction', (thisCommand, actionCommand) => {
+ if (!program.opts().json) return;
+ // Engage global JSON mode so humanLog()/humanWarn() across commands become
+ // no-ops — stdout now carries only the JSON envelope.
+ setJsonMode(true);
+ // The root program's own action (no subcommand) is handled directly in
+ // its action handler — let it through. fullCommandName is '' there.
+ if (actionCommand === program) return;
+ const fullName = fullCommandName(actionCommand, program);
+ if (JSON_SUPPORTED.has(fullName)) return;
+ process.__xdsJsonHandled = true;
+ console.log(JSON.stringify({
+ apiVersion: API_VERSION,
+ error: `JSON output is not supported for the '${fullName}' command`,
+ code: ERROR_CODES.ERR_INVALID_OPTION,
+ }, null, 2));
+ process.exit(1);
+ });
+
+ /**
+ * Belt-and-suspenders postAction: if a "supported" command somehow forgot
+ * to emit a JSON envelope on a code path, surface that as a structured error
+ * rather than silent stdout corruption. This should never fire in practice;
+ * if it does, it's a bug in the command implementation.
+ */
+ program.hook('postAction', (thisCommand, actionCommand) => {
+ if (!program.opts().json) return;
+ if (process.__xdsJsonHandled) return;
+ const fullName = fullCommandName(actionCommand, program);
+ console.log(JSON.stringify({
+ apiVersion: API_VERSION,
+ error: `Internal: '${fullName}' completed without emitting a JSON envelope`,
+ }, null, 2));
+ process.exit(1);
+ });
+
+ /**
+ * Post-action hook: print update hint after any command output.
+ * Only fires for commands that produce output agents read (component, docs, etc.).
+ * Suppressed when --json is active to avoid contaminating stdout.
+ */
+ program.hook('postAction', (thisCommand, actionCommand) => {
+ if (program.opts().json) return;
+ try {
+ if (UPDATE_HINT_COMMANDS.has(actionCommand.name())) {
+ const hint = checkForUpdate();
+ if (hint) {
+ console.error(`\n${hint}`);
+ }
+ }
+ } catch {
+ // Never let update check break the CLI
}
- // Human-readable summary. Agents should use --json.
- console.log(`\n${manifest.name} v${manifest.version} — ${manifest.commands.length} commands\n`);
- for (const c of manifest.commands) {
- const tag = c.json ? ' [--json]' : '';
- console.log(` ${c.name}${tag}`);
- if (c.description) console.log(` ${c.description}`);
+ });
+
+ /**
+ * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
+ * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
+ * the user/agent that setup is missing.
+ *
+ * Uses `preAction` (not postAction) so it fires for EVERY valid command — even
+ * ones whose action errors or calls process.exit (postAction is skipped then).
+ *
+ * Suppressed in --json: that is machine output with a strict clean stdout+stderr
+ * contract (json-shim.test: "error envelopes have empty stderr"), and --json
+ * consumers parse stdout, not stderr — a stderr nudge would not reach them anyway.
+ * The core/cli postinstall layers already nudge at install time regardless of
+ * --json; a machine-readable nudge could later be an envelope field. Also skipped
+ * for the installer commands themselves and outside a project (no package.json).
+ */
+ program.hook('preAction', (thisCommand, actionCommand) => {
+ try {
+ if (program.opts().json) return; // machine mode — keep --json output clean
+ if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
+ const cwd = process.cwd();
+ if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
+ if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
+ // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
+ // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
+ // one-off, or `<pm> astryx` when installed — never the bare `npx astryx` footgun.
+ console.error(
+ `\nNext step: run \`${getCliInvocation(cwd)} init\` to finish setup and install the Astryx agent prompt.`,
+ );
+ } catch {
+ // Never let the nudge break a command.
}
- console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
});
-// Hidden command used by package.json postinstall scripts
-program
- .command('postinstall', {hidden: true})
- .action(() => {
- const r = getCliInvocation();
- const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));
- const W = 49; // inner width of the box
- const line = (/** @type {string} */ s) => ` │ ${pad(s, W)}│`;
- console.log(`
+ for (const cmd of commands) {
+ try {
+ const mod = await import(cmd.path);
+ mod[cmd.register](program);
+ } catch (e) {
+ // Command fails to load but CLI still works
+ program
+ .command(cmd.name)
+ .description(`(failed to load: ${/** @type {any} */ (e).message})`)
+ .action(() => {
+ console.error(`Command "${cmd.name}" failed to load:`);
+ console.error(/** @type {any} */ (e).message);
+ process.exit(1);
+ });
+ }
+ }
+
+ // Capability manifest — a single, self-describing view of the whole CLI so
+ // agents can discover every command, argument, flag, and response type without
+ // scraping `--help`. `astryx manifest --json` is the dedicated surface; the bare
+ // `xds --json` embeds the same payload under data.manifest for convenience.
+ program
+ .command('manifest')
+ .description('Print the full CLI capability manifest (use with --json)')
+ .action(() => {
+ const manifest = buildManifest(program, {
+ jsonSupported: JSON_SUPPORTED,
+ version: pkg.version,
+ });
+ if (program.opts().json) {
+ process.__xdsJsonHandled = true;
+ console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest}, null, 2));
+ return;
+ }
+ // Human-readable summary. Agents should use --json.
+ console.log(`\n${manifest.name} v${manifest.version} — ${manifest.commands.length} commands\n`);
+ for (const c of manifest.commands) {
+ const tag = c.json ? ' [--json]' : '';
+ console.log(` ${c.name}${tag}`);
+ if (c.description) console.log(` ${c.description}`);
+ }
+ console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
+ });
+
+ // Hidden command used by package.json postinstall scripts
+ program
+ .command('postinstall', {hidden: true})
+ .action(() => {
+ const r = getCliInvocation();
+ const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));
+ const W = 49; // inner width of the box
+ const line = (/** @type {string} */ s) => ` │ ${pad(s, W)}│`;
+ console.log(`
╭${'─'.repeat(W + 2)}╮
${line('')}
${line(' Design system installed!')}
@@ -372,11 +389,20 @@ ${line(` ${r} template Add a page template`)}
${line('')}
╰${'─'.repeat(W + 2)}╯
`);
- });
+ });
+
+ // Install the JSON shim AFTER all commands are registered so we can
+ // patch outputHelp on every command (root + subcommands). The shim
+ // extends the --json contract to cover Commander's parse-time short
+ // circuits (parse errors, unknown options, --help, unknown commands).
+ // See packages/cli/lib/json-shim.mjs for the rationale.
+ installJsonShim(program);
-// Install the JSON shim AFTER all commands are registered so we can
-// patch outputHelp on every command (root + subcommands). The shim
-// extends the --json contract to cover Commander's parse-time short
-// circuits (parse errors, unknown options, --help, unknown commands).
-// See packages/cli/lib/json-shim.mjs for the rationale.
-installJsonShim(program);
+ return program;
+}
+
+/**
+ * Eager singleton program for `bin/astryx.mjs` and legacy importers. Tests
+ * should call {@link createProgram} to get an isolated instance.
+ */
+export const program = await createProgram();
diff --git a/packages/cli/lib/error-codes.test.mjs b/packages/cli/lib/error-codes.test.mjs
index 7e639e2a55..56a6900dbe 100644
--- a/packages/cli/lib/error-codes.test.mjs
+++ b/packages/cli/lib/error-codes.test.mjs
@@ -15,26 +15,8 @@
*/
import {describe, it, expect} from 'vitest';
-import {spawnSync} from 'node:child_process';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
import {ERROR_CODES, isErrorCode, allErrorCodes} from './error-codes.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');
-
-function runCli(args, {cwd} = {}) {
- const res = spawnSync('node', [CLI_BIN, ...args], {
- cwd: cwd || process.cwd(),
- encoding: 'utf-8',
- timeout: 20_000,
- });
- return {
- status: res.status,
- stdout: res.stdout || '',
- stderr: res.stderr || '',
- };
-}
+import {runCli} from '../test-utils/run-cli.mjs';
/** Parse the JSON envelope from stdout. Throws if stdout isn't clean JSON. */
function envelope(stdout) {
@@ -110,8 +92,8 @@ describe('error codes: end-to-end JSON envelopes', () => {
];
for (const {name, args, code} of cases) {
- it(`${name} → ${code}`, () => {
- const {status, stdout} = runCli(args);
+ it(`${name} → ${code}`, async () => {
+ const {status, stdout} = await runCli(args);
expect(status).toBe(1);
const env = envelope(stdout);
expect(env).toHaveProperty('apiVersion');
@@ -122,8 +104,8 @@ describe('error codes: end-to-end JSON envelopes', () => {
});
}
- it('every error envelope carries a code (even unmatched paths fall back to ERR_UNKNOWN)', () => {
- const {stdout} = runCli(['component', 'Bogus', '--json']);
+ it('every error envelope carries a code (even unmatched paths fall back to ERR_UNKNOWN)', async () => {
+ const {stdout} = await runCli(['component', 'Bogus', '--json']);
const env = envelope(stdout);
expect(typeof env.code).toBe('string');
expect(env.code.length).toBeGreaterThan(0);
@@ -131,8 +113,8 @@ describe('error codes: end-to-end JSON envelopes', () => {
});
describe('error codes: human mode stays clean', () => {
- it('the code is NOT printed in the human-facing error line', () => {
- const {status, stderr, stdout} = runCli(['component', 'Bogus']);
+ it('the code is NOT printed in the human-facing error line', async () => {
+ const {status, stderr, stdout} = await runCli(['component', 'Bogus']);
expect(status).toBe(1);
// Human output goes to stderr and must not leak the machine code.
expect(stderr).toContain('No component named');
@@ -140,11 +122,11 @@ describe('error codes: human mode stays clean', () => {
expect(stdout).not.toContain('ERR_UNKNOWN_COMPONENT');
});
- it('unknown subcommand exits 1 in human mode (code carried internally)', () => {
+ it('unknown subcommand exits 1 in human mode (code carried internally)', async () => {
// `theme` is not JSON-capable, so this path is human-only; we assert the
// failure surfaces with exit 1 and a helpful message. The stable
// ERR_UNKNOWN_SUBCOMMAND code rides along on the cliError call.
- const {status, stderr} = runCli(['theme', 'bogus-sub']);
+ const {status, stderr} = await runCli(['theme', 'bogus-sub']);
expect(status).toBe(1);
expect(stderr).toContain("unknown subcommand 'theme bogus-sub'");
expect(stderr).not.toContain('ERR_UNKNOWN_SUBCOMMAND');
diff --git a/packages/cli/lib/json-shim.test.mjs b/packages/cli/lib/json-shim.test.mjs
index 3094a27da7..cd2e2f40e1 100644
--- a/packages/cli/lib/json-shim.test.mjs
+++ b/packages/cli/lib/json-shim.test.mjs
@@ -20,32 +20,15 @@
*/
import {describe, it, expect} from 'vitest';
-import {spawnSync} from 'node:child_process';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');
-
-function runCli(args) {
- const res = spawnSync('node', [CLI_BIN, ...args], {
- encoding: 'utf-8',
- timeout: 20_000,
- });
- return {
- status: res.status,
- stdout: res.stdout || '',
- stderr: res.stderr || '',
- };
-}
+import {runCli} from '../test-utils/run-cli.mjs';
function parseJson(stdout) {
return JSON.parse(stdout);
}
describe('--json shim: --help renders JSON envelope', () => {
- it('astryx --help --json emits a help envelope (not raw text), exit 0', () => {
- const {status, stdout, stderr} = runCli(['--help', '--json']);
+ it('astryx --help --json emits a help envelope (not raw text), exit 0', async () => {
+ const {status, stdout, stderr} = await runCli(['--help', '--json']);
expect(status).toBe(0);
expect(stderr).toBe('');
const parsed = parseJson(stdout);
@@ -59,8 +42,8 @@ describe('--json shim: --help renders JSON envelope', () => {
expect(subNames).toContain('theme');
});
- it('astryx component --help --json emits a subcommand help envelope', () => {
- const {status, stdout} = runCli(['component', '--help', '--json']);
+ it('astryx component --help --json emits a subcommand help envelope', async () => {
+ const {status, stdout} = await runCli(['component', '--help', '--json']);
expect(status).toBe(0);
const parsed = parseJson(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -71,8 +54,8 @@ describe('--json shim: --help renders JSON envelope', () => {
expect(flags).toContain('--list');
});
- it('astryx theme build --help --json emits a nested subcommand help envelope', () => {
- const {status, stdout} = runCli(['theme', 'build', '--help', '--json']);
+ it('astryx theme build --help --json emits a nested subcommand help envelope', async () => {
+ const {status, stdout} = await runCli(['theme', 'build', '--help', '--json']);
expect(status).toBe(0);
const parsed = parseJson(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -83,8 +66,8 @@ describe('--json shim: --help renders JSON envelope', () => {
});
describe('--json shim: parse errors emit JSON error envelope', () => {
- it('astryx theme build --json (missing required arg) emits error envelope, exit 1', () => {
- const {status, stdout} = runCli(['theme', 'build', '--json']);
+ it('astryx theme build --json (missing required arg) emits error envelope, exit 1', async () => {
+ const {status, stdout} = await runCli(['theme', 'build', '--json']);
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -92,8 +75,8 @@ describe('--json shim: parse errors emit JSON error envelope', () => {
expect(parsed.error).toMatch(/file/i);
});
- it('astryx --bogus-flag --json (unknown option) emits error envelope, exit 1', () => {
- const {status, stdout} = runCli(['--bogus-flag', '--json']);
+ it('astryx --bogus-flag --json (unknown option) emits error envelope, exit 1', async () => {
+ const {status, stdout} = await runCli(['--bogus-flag', '--json']);
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -101,8 +84,8 @@ describe('--json shim: parse errors emit JSON error envelope', () => {
expect(parsed.error).toMatch(/--bogus-flag/);
});
- it('astryx component --json --bogus-flag (unknown option on subcmd) emits error envelope, exit 1', () => {
- const {status, stdout} = runCli(['component', '--json', '--bogus-flag']);
+ it('astryx component --json --bogus-flag (unknown option on subcmd) emits error envelope, exit 1', async () => {
+ const {status, stdout} = await runCli(['component', '--json', '--bogus-flag']);
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -111,8 +94,8 @@ describe('--json shim: parse errors emit JSON error envelope', () => {
});
describe('--json shim: unknown subcommand emits error envelope', () => {
- it('astryx bogus-cmd --json emits error envelope, exit 1 (not exit 0 + help)', () => {
- const {status, stdout} = runCli(['bogus-cmd', '--json']);
+ it('astryx bogus-cmd --json emits error envelope, exit 1 (not exit 0 + help)', async () => {
+ const {status, stdout} = await runCli(['bogus-cmd', '--json']);
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -126,8 +109,8 @@ describe('--json shim: unknown subcommand emits error envelope', () => {
});
describe('--json shim: invalid --detail choice', () => {
- it('astryx --detail bogus --json emits a single error envelope, exit 1', () => {
- const {status, stdout} = runCli(['--detail', 'bogus', '--json']);
+ it('astryx --detail bogus --json emits a single error envelope, exit 1', async () => {
+ const {status, stdout} = await runCli(['--detail', 'bogus', '--json']);
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -142,8 +125,8 @@ describe('--json shim: invalid --detail choice', () => {
});
describe('--json shim: invalid --lang choice', () => {
- it('astryx docs color --lang fr --json emits a single error envelope, exit 1', () => {
- const {status, stdout} = runCli(['docs', 'color', '--lang', 'fr', '--json']);
+ it('astryx docs color --lang fr --json emits a single error envelope, exit 1', async () => {
+ const {status, stdout} = await runCli(['docs', 'color', '--lang', 'fr', '--json']);
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -154,55 +137,55 @@ describe('--json shim: invalid --lang choice', () => {
expect(topLevelBraces).toBe(1);
});
- it('astryx docs color --lang fr (no --json) writes to stderr and exits 1', () => {
- const {status, stdout, stderr} = runCli(['docs', 'color', '--lang', 'fr']);
+ it('astryx docs color --lang fr (no --json) writes to stderr and exits 1', async () => {
+ const {status, stdout, stderr} = await runCli(['docs', 'color', '--lang', 'fr']);
expect(status).toBe(1);
expect(stdout).toBe('');
expect(stderr).toMatch(/--lang/);
});
- it('astryx docs color --lang zh is accepted (exit 0)', () => {
- const {status} = runCli(['docs', 'color', '--lang', 'zh']);
+ it('astryx docs color --lang zh is accepted (exit 0)', async () => {
+ const {status} = await runCli(['docs', 'color', '--lang', 'zh']);
expect(status).toBe(0);
});
- it('astryx docs color --lang en is accepted (exit 0)', () => {
- const {status} = runCli(['docs', 'color', '--lang', 'en']);
+ it('astryx docs color --lang en is accepted (exit 0)', async () => {
+ const {status} = await runCli(['docs', 'color', '--lang', 'en']);
expect(status).toBe(0);
});
});
describe('--json shim: non-JSON behavior is preserved', () => {
- it('astryx theme build (no --json, missing arg) writes to stderr and exits 1', () => {
- const {status, stdout, stderr} = runCli(['theme', 'build']);
+ it('astryx theme build (no --json, missing arg) writes to stderr and exits 1', async () => {
+ const {status, stdout, stderr} = await runCli(['theme', 'build']);
expect(status).toBe(1);
expect(stdout).toBe('');
expect(stderr).toMatch(/missing required argument/i);
});
- it('astryx --bogus-flag (no --json) writes to stderr and exits 1', () => {
- const {status, stdout, stderr} = runCli(['--bogus-flag']);
+ it('astryx --bogus-flag (no --json) writes to stderr and exits 1', async () => {
+ const {status, stdout, stderr} = await runCli(['--bogus-flag']);
expect(status).toBe(1);
expect(stdout).toBe('');
expect(stderr).toMatch(/unknown option/i);
});
- it('astryx bogus-cmd (no --json) writes to stderr and exits 1', () => {
- const {status, stdout, stderr} = runCli(['bogus-cmd']);
+ it('astryx bogus-cmd (no --json) writes to stderr and exits 1', async () => {
+ const {status, stdout, stderr} = await runCli(['bogus-cmd']);
expect(status).toBe(1);
expect(stdout).toBe('');
expect(stderr).toMatch(/unknown command/i);
});
- it('astryx --detail bogus (no --json) writes to stderr and exits 1', () => {
- const {status, stdout, stderr} = runCli(['--detail', 'bogus']);
+ it('astryx --detail bogus (no --json) writes to stderr and exits 1', async () => {
+ const {status, stdout, stderr} = await runCli(['--detail', 'bogus']);
expect(status).toBe(1);
expect(stdout).toBe('');
expect(stderr).toMatch(/--detail/);
});
- it('astryx --help (no --json) writes raw help text to stdout, exit 0', () => {
- const {status, stdout, stderr} = runCli(['--help']);
+ it('astryx --help (no --json) writes raw help text to stdout, exit 0', async () => {
+ const {status, stdout, stderr} = await runCli(['--help']);
expect(status).toBe(0);
expect(stdout).toMatch(/^Usage: astryx/);
expect(stderr).toBe('');
@@ -210,7 +193,7 @@ describe('--json shim: non-JSON behavior is preserved', () => {
});
describe('--json shim: stdout discipline under --json', () => {
- it('all error envelopes have empty stderr (no leak of legacy "error: ..." line)', () => {
+ it('all error envelopes have empty stderr (no leak of legacy "error: ..." line)', async () => {
const cases = [
['theme', 'build', '--json'],
['--bogus-flag', '--json'],
@@ -219,7 +202,7 @@ describe('--json shim: stdout discipline under --json', () => {
['docs', 'color', '--lang', 'fr', '--json'],
];
for (const args of cases) {
- const {stderr} = runCli(args);
+ const {stderr} = await runCli(args);
expect(stderr, `stderr should be empty for: ${args.join(' ')}`).toBe('');
}
});
diff --git a/packages/cli/lib/manifest.test.mjs b/packages/cli/lib/manifest.test.mjs
index a722c1f188..488e781b25 100644
--- a/packages/cli/lib/manifest.test.mjs
+++ b/packages/cli/lib/manifest.test.mjs
@@ -15,14 +15,9 @@
*/
import {describe, it, expect} from 'vitest';
-import {spawnSync} from 'node:child_process';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
import {program, JSON_SUPPORTED} from '../cli/index.mjs';
import {buildManifest, RESPONSE_TYPES} from './manifest.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');
+import {runCli} from '../test-utils/run-cli.mjs';
const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
@@ -138,14 +133,9 @@ describe('manifest: shape', () => {
});
});
-function runCli(args) {
- const res = spawnSync('node', [CLI_BIN, ...args], {encoding: 'utf-8', timeout: 20_000});
- return {status: res.status, stdout: res.stdout || '', stderr: res.stderr || ''};
-}
-
describe('manifest: e2e', () => {
- it('astryx manifest --json emits a valid manifest envelope', () => {
- const {status, stdout} = runCli(['manifest', '--json']);
+ it('astryx manifest --json emits a valid manifest envelope', async () => {
+ const {status, stdout} = await runCli(['manifest', '--json']);
expect(status).toBe(0);
const parsed = JSON.parse(stdout);
expect(parsed.apiVersion).toBe(1);
@@ -157,8 +147,8 @@ describe('manifest: e2e', () => {
expect(names).toContain('manifest');
});
- it('bare xds --json stays backwards-compatible AND embeds the manifest', () => {
- const {status, stdout} = runCli(['--json']);
+ it('bare xds --json stays backwards-compatible AND embeds the manifest', async () => {
+ const {status, stdout} = await runCli(['--json']);
expect(status).toBe(0);
const parsed = JSON.parse(stdout);
// Back-compat: still type:'help' with name/version/commands(names)/jsonSupported
diff --git a/packages/cli/test-utils/run-cli.mjs b/packages/cli/test-utils/run-cli.mjs
new file mode 100644
index 0000000000..5367e5cdf2
--- /dev/null
+++ b/packages/cli/test-utils/run-cli.mjs
@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file In-process CLI test harness.
+ *
+ * Drives the REAL Astryx program — all commands, the preAction --json gate, the
+ * hooks, and the json-shim — via createProgram() + parseAsync, instead of
+ * spawning `node bin/astryx.mjs` per assertion. That makes CLI suites fast and
+ * deterministic (no per-test Node cold-start to starve under parallel load).
+ *
+ * Drop-in for the per-file spawn helpers: returns `{status, code, stdout,
+ * stderr}` (both `status` and `code` are the exit code — the spawnSync helpers
+ * read `.status`, the execFileSync ones read `.code`). Accepts the cwd either
+ * positionally (`runCli(args, dir)`, the execFileSync convention) or as an
+ * option (`runCli(args, {cwd})`, the spawnSync convention). It IS async
+ * (command actions are async), so call sites use `await runCli(...)`.
+ *
+ * The real bin bootstrap + true process boundary are covered separately by a
+ * small e2e smoke that still spawns the binary.
+ */
+
+import {format} from 'node:util';
+import {createProgram} from '../cli/index.mjs';
+import {setJsonMode} from '../lib/json.mjs';
+import {handleCommanderError} from '../lib/json-shim.mjs';
+
+/** Thrown by the trapped process.exit to unwind parseAsync with the exit code. */
+class ExitSignal extends Error {
+ /** @param {number} code */
+ constructor(code) {
+ super(`process.exit(${code})`);
+ this.name = 'ExitSignal';
+ /** @type {number} */
+ this.code = code;
+ }
+}
+
+/**
+ * Run the Astryx CLI in-process and capture its observable surface.
+ *
+ * @param {string[]} args argv after `astryx` (e.g. `['component', '--list']`)
+ * @param {string | {cwd?: string}} [cwdOrOpts] cwd (positional) or `{cwd}`
+ * @returns {Promise<{status: number, code: number, stdout: string, stderr: string}>}
+ */
+export async function runCli(args, cwdOrOpts) {
+ const cwd =
+ typeof cwdOrOpts === 'string' ? cwdOrOpts : cwdOrOpts && cwdOrOpts.cwd;
+ const program = await createProgram();
+ // Commander's own exits (parse errors, --help, --version, unknown option)
+ // throw a CommanderError instead of calling process.exit.
+ program.exitOverride();
+
+ /** @type {string[]} */
+ const out = [];
+ /** @type {string[]} */
+ const err = [];
+ const origLog = console.log;
+ const origError = console.error;
+ const origStdout = process.stdout.write;
+ const origStderr = process.stderr.write;
+ const origExit = process.exit;
+ const origCwd = process.cwd();
+ const origArgv = process.argv;
+
+ let status = 0;
+
+ // Capture at the console.* layer: Vitest replaces console.log/console.error
+ // with its own collectors, so the CLI's output never reaches the raw streams —
+ // patching process.stdout.write alone captures nothing. `format(...)` + "\n"
+ // reproduces console.log's own formatting so parseJson(stdout) sees exactly
+ // the envelope the binary would print. Direct stream writes (rare) are also
+ // captured for fidelity.
+ console.log = (/** @type {unknown[]} */ ...a) => {
+ out.push(format(...a) + '\n');
+ };
+ console.error = (/** @type {unknown[]} */ ...a) => {
+ err.push(format(...a) + '\n');
+ };
+ // @ts-expect-error - test-only monkeypatch
+ process.stdout.write = c => {
+ out.push(typeof c === 'string' ? c : c.toString());
+ return true;
+ };
+ // @ts-expect-error - test-only monkeypatch
+ process.stderr.write = c => {
+ err.push(typeof c === 'string' ? c : c.toString());
+ return true;
+ };
+ // @ts-expect-error - test-only monkeypatch
+ process.exit = code => {
+ throw new ExitSignal(Number(code) || 0);
+ };
+
+ // Reset the global CLI/JSON-contract state so runs never bleed into each other.
+ setJsonMode(false);
+ process.exitCode = 0;
+ process.__xdsJsonHandled = false;
+
+ // The json-shim detects --json partly via process.argv: Commander parse
+ // errors and --help fire BEFORE the preAction hook engages setJsonMode, so
+ // the shim falls back to an argv scan (exactly as the real bin does). Present
+ // the same argv the binary would see so those short-circuit paths behave
+ // identically in-process.
+ process.argv = ['node', 'astryx', ...args];
+
+ if (cwd) process.chdir(cwd);
+ try {
+ await program.parseAsync(['node', 'astryx', ...args]);
+ // Text-mode error paths set process.exitCode rather than calling exit.
+ if (status === 0 && process.exitCode) status = Number(process.exitCode) || 0;
+ } catch (e) {
+ if (e instanceof ExitSignal) {
+ status = e.code;
+ } else if (
+ e &&
+ typeof e === 'object' &&
+ typeof (/** @type {any} */ (e).code) === 'string' &&
+ /** @type {any} */ (e).code.startsWith('commander.')
+ ) {
+ // CommanderError from exitOverride() (parse error / --help / --version).
+ // Mirror bin/astryx.mjs's error boundary: route it through the JSON shim
+ // so --json consumers get a valid envelope (with the mapped ERR_ code)
+ // and non-JSON callers keep Commander's stderr line. handleCommanderError
+ // calls process.exit, which our trap re-raises as an ExitSignal.
+ try {
+ handleCommanderError(e);
+ status = /** @type {any} */ (e).exitCode ?? 1;
+ } catch (e2) {
+ if (e2 instanceof ExitSignal) status = e2.code;
+ else throw e2;
+ }
+ } else if (
+ e &&
+ typeof e === 'object' &&
+ typeof (/** @type {any} */ (e).exitCode) === 'number'
+ ) {
+ // Any other error carrying an exit code — preserve it.
+ status = /** @type {any} */ (e).exitCode;
+ } else {
+ throw e; // genuine unexpected error — surface it
+ }
+ } finally {
+ if (cwd) process.chdir(origCwd);
+ process.argv = origArgv;
+ console.log = origLog;
+ console.error = origError;
+ process.stdout.write = origStdout;
+ process.stderr.write = origStderr;
+ process.exit = origExit;
+ process.exitCode = 0;
+ setJsonMode(false);
+ }
+
+ return {status, code: status, stdout: out.join(''), stderr: err.join('')};
+}