@astryxdesign/cli 0.2.0 → 0.3.0

package/clients/cli/cli-exit-codes.test.mjs

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file End-to-end exit-code policy tests.
+ *
+ * Spawns the CLI as a subprocess and asserts the exit code (and JSON
+ * envelope shape, where applicable) for every error path the policy
+ * covers. This is the test that catches CI-script-breaking regressions:
+ * if a future change accidentally restores `exit 0` on a user-visible
+ * error, this file fires.
+ *
+ * Policy under test (see lib/cli-error.mjs for full doc-block):
+ *   - Any user-visible error → exit 1 (both modes).
+ *   - Help/version/empty → exit 0.
+ *   - --json and non-JSON exit with the same code for the same case.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+/** Shorthand for asserting the exit code. */
+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}`,
+  ).toBe(code);
+  return r;
+}
+
+/** Parse the stdout of a --json invocation as a JSON envelope. */
+function parseEnvelope(r) {
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    throw new Error(`stdout was not JSON:\n${r.stdout}\n--- stderr ---\n${r.stderr}`);
+  }
+}
+
+// ─── Error paths: must exit 1 ────────────────────────────────────────────────
+
+describe('exit codes — error paths (human mode → exit 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', async () => {
+    const r = await expectExit(['theme', 'bogus'], 1);
+    expect(r.stderr).toMatch(/unknown subcommand/i);
+  });
+
+  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', async () => {
+    const r = await expectExit(['hook', 'bogus'], 1);
+    expect(r.stderr).toMatch(/no hook named/i);
+  });
+
+  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', 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', 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', 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', 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', 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);
+  });
+});
+
+// ─── Success paths: must exit 0 (positive controls) ──────────────────────────
+
+describe('exit codes — success paths (exit 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', async () => {
+    await expectExit(['--help'], 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', async () => {
+    await expectExit(['component'], 0);
+  });
+
+  it('astryx component Button → exit 0', async () => {
+    await expectExit(['component', 'Button'], 0);
+  });
+
+  it('astryx docs (list mode) → exit 0', async () => {
+    await expectExit(['docs'], 0);
+  });
+
+  it('astryx theme (no subcommand) → exit 0, shows help', async () => {
+    // Bare theme without a subcommand is a help-display case → exit 0.
+    await expectExit(['theme'], 0);
+  });
+
+  it('astryx hook (list mode) → exit 0', async () => {
+    await expectExit(['hook'], 0);
+  });
+});
+
+// ─── Mode parity: same case must exit the same in both modes ────────────────
+
+describe('exit codes — JSON / non-JSON parity', () => {
+  const cases = [
+    ['bogus-cmd'],
+    ['component', 'bogus'],
+    ['hook', 'bogus'],
+    ['docs', 'bogus'],
+  ];
+
+  for (const args of cases) {
+    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);
+    });
+  }
+});

package/clients/cli/commands/blog.mjs

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file blog command — read the Astryx blog from the published feed.
+ *
+ * A normal, agent-facing command: it appears in `--help` + the manifest and
+ * supports `--json`. It reads the blog the same way any feed reader would — over
+ * the public RSS feed — and prints a post's plaintext (.txt) variant. Nothing
+ * about the blog's structure has to change for this to work; the CLI is just a
+ * consumer of the feed.
+ *
+ *   astryx blog                    List posts from the feed
+ *   astryx blog <slug>             Print a post as plaintext
+ *   astryx blog --json             Structured list/detail envelope
+ */
+
+import {getRunPrefix} from '../../../foundation/env/package-manager.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, record, records, code} from '../formatters/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {blog as blogApi} from '../../../api/blog/blog.mjs';
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerBlog(program) {
+  program
+    .command('blog [slug]')
+    .description('Read the Astryx blog from the published feed')
+    .action(async (/** @type {string | undefined} */ slug) => {
+      const run = getRunPrefix();
+      /** @type {import('../../../api/blog/blog.type.mjs').BlogListResponse | import('../../../api/blog/blog.type.mjs').BlogDetailResponse} */
+      let result;
+      try {
+        result = await blogApi(slug);
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {
+          suggestions: err.suggestions || [],
+          code: err.code,
+        });
+        return;
+      }
+
+      if (program.opts().json) {
+        jsonOut(result);
+        return;
+      }
+
+      if (result.type === 'blog.list') {
+        const {feedUrl, posts} = result.data;
+        if (posts.length === 0) {
+          emit(
+            section('Astryx blog', `feed: ${feedUrl}`),
+            text('No posts found in the feed.'),
+          );
+          return;
+        }
+        // One record per post — fields mirror the JSON post shape; empty
+        // fields (type/textUrl) are skipped by record().
+        emit(
+          section('Astryx blog', `feed: ${feedUrl}`),
+          records(posts, {fields: ['slug', 'title', 'type', 'textUrl']}),
+          text(`Read one: ${run} astryx blog <slug>`),
+        );
+      } else {
+        // blog.detail — the feed URL, then the post body emitted verbatim
+        // (code() so article typography/spacing isn't ASCII-normalized).
+        emit(record({feed: result.data.feedUrl}), code(result.data.text));
+      }
+    });
+}

package/clients/cli/commands/blog.test.mjs

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CLI wiring for `blog` now that it's a normal, json-enabled command.
+ *
+ * Drives the real program in-process (runCli) with `fetch` stubbed so nothing
+ * hits the network. Asserts the --json envelopes, the unchanged human output,
+ * and that blog is no longer rejected by the --json gate. The offline parsing
+ * logic is covered by api/blog/blog.test.mjs.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {SITE_URL} from '../../../api/blog/_site.mjs';
+
+const FEED = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <item>
+      <title>How Astryx works</title>
+      <link>${SITE_URL}/blog/how-astryx-works</link>
+      <category>engineering</category>
+      <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
+      <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
+    </item>
+  </channel>
+</rss>`;
+
+const FEED_URL = `${SITE_URL}/rss.xml`;
+const TXT_URL = `${SITE_URL}/blog/how-astryx-works.txt`;
+const POST_TEXT = '# How Astryx works\n\nThe body of the post.';
+
+/** @param {Record<string, {status: number, body: string}>} routes */
+function stubFetch(routes) {
+  return vi.fn(async url => {
+    const r = routes[String(url)];
+    if (!r) return {ok: false, status: 404, text: async () => 'not found'};
+    return {ok: r.status < 400, status: r.status, text: async () => r.body};
+  });
+}
+
+beforeEach(() => {
+  vi.stubGlobal(
+    'fetch',
+    stubFetch({
+      [FEED_URL]: {status: 200, body: FEED},
+      [TXT_URL]: {status: 200, body: POST_TEXT},
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('blog CLI — json-enabled', () => {
+  it('blog --json emits a valid blog.list envelope', async () => {
+    const {status, stdout} = await runCli(['blog', '--json']);
+    expect(status).toBe(0);
+    const env = JSON.parse(stdout);
+    expect(env.apiVersion).toBeDefined();
+    expect(env.type).toBe('blog.list');
+    expect(Array.isArray(env.data.posts)).toBe(true);
+    expect(env.data.posts[0].slug).toBe('how-astryx-works');
+  });
+
+  it('blog <slug> --json emits a blog.detail envelope with the post text', async () => {
+    const {status, stdout} = await runCli(['blog', 'how-astryx-works', '--json']);
+    expect(status).toBe(0);
+    const env = JSON.parse(stdout);
+    expect(env.type).toBe('blog.detail');
+    expect(env.data.text).toBe(POST_TEXT);
+  });
+
+  it('is no longer rejected by the --json gate (blog is now supported)', async () => {
+    const {status, stdout} = await runCli(['blog', '--json']);
+    expect(status).toBe(0);
+    // A gated/unsupported command would emit an { error } envelope + exit 1.
+    expect(JSON.parse(stdout).error).toBeUndefined();
+  });
+
+  it('blog (non-json) still prints the human feed listing', async () => {
+    const {status, stdout} = await runCli(['blog']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Astryx blog/);
+    expect(stdout).toMatch(/feed:/);
+    expect(stdout).toMatch(/how-astryx-works/);
+  });
+
+  it('surfaces the API error code and exits non-zero for an unknown slug (--json)', async () => {
+    const {status, stdout} = await runCli(['blog', 'no-such-post', '--json']);
+    expect(status).not.toBe(0);
+    const env = JSON.parse(stdout);
+    expect(env.error).toBeDefined();
+    expect(env.code).toBe('ERR_UNKNOWN_POST');
+  });
+});

package/clients/cli/commands/build-theme.color-scheme.test.mjs

@@ -0,0 +1,131 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for the `color-scheme` declaration `astryx theme build`
+ * emits alongside `light-dark()` token output (see #3658).
+ *
+ * `astryx theme build` injects a `color-scheme` declaration into
+ * `@layer astryx-theme` whenever the generated CSS contains `light-dark()`,
+ * so LightningCSS/browsers can resolve it. That declaration must mirror
+ * reset.css's own `html[data-theme]` -> `color-scheme` mapping (a bare
+ * `:root { color-scheme: light dark; }` alone permanently pins the page to
+ * "light dark", defeating `<Theme mode="light|dark">` forcing regardless of
+ * `@layer astryx-theme` being declared after `@layer reset` in layer order):
+ *
+ *   :root { color-scheme: light dark; }
+ *   html[data-theme="light"] { color-scheme: light; }
+ *   html[data-theme="dark"] { color-scheme: dark; }
+ *
+ * Themes that never use `light-dark()` have no `color-scheme` ambiguity to
+ * resolve, so none of the three rules should be emitted for them.
+ *
+ * Building `astryx theme build` requires a compiled @astryxdesign/core (there is no in-CLI
+ * fallback generator), so this suite builds core once in beforeAll via the
+ * shared ensureCoreBuilt() helper — which serializes concurrent Vitest workers
+ * behind a lock — to stay self-sufficient regardless of CI job ordering.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {ensureCoreBuilt} from './ensure-core-built.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 writeTheme(dir, name, tokens) {
+  fs.mkdirSync(dir, {recursive: true});
+  // The CLI writes <basename>.css next to the source file, so use the
+  // theme name as the filename for unambiguous fixtures.
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(
+    file,
+    `export default { name: ${JSON.stringify(name)}, tokens: ${JSON.stringify(tokens)} };\n`,
+  );
+  return file;
+}
+
+// `astryx theme build` imports the compiled @astryxdesign/core/theme entry. Build core
+// once if it isn't already present so the suite works in any CI job.
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-color-scheme-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build color-scheme output', () => {
+  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
+    // injection in build-theme.mjs (it checks the generated CSS for the
+    // literal substring). `defineTheme.test.ts` already covers the separate
+    // [light, dark] tuple -> light-dark() conversion; this fixture writes
+    // the string directly so this test stays focused on the CLI's own
+    // color-scheme decision, not on that conversion.
+    const themeFile = writeTheme(themesDir, 'with-light-dark', {
+      '--color-accent': 'light-dark(#0077B6, #48CAE4)',
+    });
+
+    const result = await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+
+    const cssPath = path.join(themesDir, 'with-light-dark.css');
+    expect(fs.existsSync(cssPath)).toBe(true);
+    const css = fs.readFileSync(cssPath, 'utf-8');
+
+    expect(css).toContain('light-dark(#0077B6, #48CAE4)');
+
+    // All 3 rules must be present...
+    expect(css).toContain(COLOR_SCHEME_ROOT_DECL);
+    expect(css).toContain(COLOR_SCHEME_LIGHT_DECL);
+    expect(css).toContain(COLOR_SCHEME_DARK_DECL);
+
+    // ...and specifically inside @layer astryx-theme, not @layer reset (the
+    // declaration must sit alongside the light-dark() token/component output
+    // it resolves, not the zero-specificity prose defaults).
+    const themeLayerStart = css.indexOf('@layer astryx-theme');
+    expect(themeLayerStart).toBeGreaterThanOrEqual(0);
+    const themeLayerBody = css.slice(themeLayerStart);
+    expect(themeLayerBody).toContain(COLOR_SCHEME_ROOT_DECL);
+    expect(themeLayerBody).toContain(COLOR_SCHEME_LIGHT_DECL);
+    expect(themeLayerBody).toContain(COLOR_SCHEME_DARK_DECL);
+  });
+
+  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 = await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+
+    const cssPath = path.join(themesDir, 'no-light-dark.css');
+    expect(fs.existsSync(cssPath)).toBe(true);
+    const css = fs.readFileSync(cssPath, 'utf-8');
+
+    expect(css).not.toContain('light-dark(');
+    expect(css).not.toContain(COLOR_SCHEME_ROOT_DECL);
+    expect(css).not.toContain(COLOR_SCHEME_LIGHT_DECL);
+    expect(css).not.toContain(COLOR_SCHEME_DARK_DECL);
+  });
+});

package/clients/cli/commands/build-theme.import-path.test.mjs

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for `astryx theme build` install-instructions import paths.
+ *
+ * Covers the relDir-empty case: when the output directory equals the current
+ * working directory, the relative dir is an empty string. Previously this
+ * produced a double-slash import path like `from './/<name>'`. The build now
+ * collapses the prefix to `./` so the emitted import is `from './<name>'`.
+ *
+ * Also covers the non-empty subdir case (`./<sub>/<name>`) to guard against
+ * regressions in the opposite direction.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+function writeTheme(dir, name) {
+  fs.mkdirSync(dir, {recursive: true});
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(
+    file,
+    `export default { name: ${JSON.stringify(name)}, tokens: { '--color-bg': '#fff' } };\n`,
+  );
+  return file;
+}
+
+// `astryx theme build` imports the compiled @astryxdesign/core/theme entry (there is no
+// in-CLI fallback generator). Build core once if it isn't already present so
+// the suite works in any CI job, regardless of job ordering.
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-import-path-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build install-instructions import path', () => {
+  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 = await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    // No double slash anywhere in the install instructions.
+    expect(result.stdout).not.toContain('.//');
+    // Import + css + link paths all use the clean ./<name> form.
+    expect(result.stdout).toContain("from './cwd-theme'");
+    expect(result.stdout).toContain("import './cwd-theme.css'");
+    expect(result.stdout).toContain('href="./cwd-theme.css"');
+  });
+
+  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 = await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).not.toContain('.//');
+    expect(result.stdout).toContain("from './themes/sub-theme'");
+    expect(result.stdout).toContain("import './themes/sub-theme.css'");
+    expect(result.stdout).toContain('href="./themes/sub-theme.css"');
+  });
+
+  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 = await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).not.toContain('.//');
+    // The leading src/ is dropped, but themes/ocean/ is kept (people need it).
+    expect(result.stdout).toContain("from './themes/ocean/ocean'");
+    expect(result.stdout).toContain("import './themes/ocean/ocean.css'");
+    expect(result.stdout).not.toContain('./src/');
+  });
+});