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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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 JSONexpect(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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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)/jsonSupporteddiff --git a/packages/cli/test-utils/run-cli.mjs b/packages/cli/test-utils/run-cli.mjsnew file mode 100644index 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('')};+}