@astryxdesign/cli 0.4.3 → 0.4.4-canary.0f4d45f

package/clients/cli/commands/build-theme.multi.test.mjs

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for `astryx theme build <a> <b> …` — several themes per
+ * invocation (kt-lc9s).
+ *
+ * The load-bearing guarantee is equivalence: one invocation over N theme files
+ * must write exactly the bytes N serial invocations write. Everything else here
+ * guards the edges that only exist once the argument is variadic — the JSON
+ * envelope, --check across a set, --out (which names one file), and fail-fast.
+ *
+ * `astryx theme build` needs a compiled @astryxdesign/core, so this suite
+ * builds core once via the shared ensureCoreBuilt() helper.
+ */
+
+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 THEMES = {
+  'alpha.mjs': `export default { name: 'alpha', tokens: { '--color-bg': '#ffffff' } };\n`,
+  'beta.mjs': `export default { name: 'beta', tokens: { '--color-bg': '#010203' } };\n`,
+  'gamma.mjs': `export default { name: 'gamma', tokens: { '--color-bg': '#ff00ff' } };\n`,
+};
+const FILES = Object.keys(THEMES);
+const OUTPUTS = ['alpha', 'beta', 'gamma'].flatMap(n => [
+  `${n}.css`,
+  `${n}.js`,
+  `${n}.d.ts`,
+]);
+
+/** A fresh temp dir holding the three theme sources. */
+function themeDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-multi-'));
+  for (const [name, source] of Object.entries(THEMES)) {
+    fs.writeFileSync(path.join(dir, name), source);
+  }
+  dirs.push(dir);
+  return dir;
+}
+
+/** @type {string[]} */
+let dirs;
+
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+beforeEach(() => {
+  dirs = [];
+});
+afterEach(() => {
+  for (const dir of dirs) fs.rmSync(dir, {recursive: true, force: true});
+});
+
+describe('theme build with several files', () => {
+  it('writes byte-identical output to one invocation per theme', async () => {
+    const serial = themeDir();
+    for (const file of FILES) {
+      const r = await runCli(['theme', 'build', file], serial);
+      expect(r.status).toBe(0);
+    }
+
+    const batch = themeDir();
+    const r = await runCli(['theme', 'build', ...FILES], batch);
+    expect(r.status).toBe(0);
+
+    for (const output of OUTPUTS) {
+      const one = fs.readFileSync(path.join(serial, output), 'utf8');
+      const many = fs.readFileSync(path.join(batch, output), 'utf8');
+      expect({output, content: many}).toEqual({output, content: one});
+    }
+  }, 120_000);
+
+  it('reports every theme in one theme.build.batch envelope', async () => {
+    const dir = themeDir();
+    const r = await runCli(['--json', 'theme', 'build', ...FILES], dir);
+    expect(r.status).toBe(0);
+
+    const envelope = JSON.parse(r.stdout);
+    expect(envelope.type).toBe('theme.build.batch');
+    expect(envelope.data.count).toBe(3);
+    expect(envelope.data.results.map(x => x.file)).toEqual(FILES);
+    expect(envelope.data.results.map(x => x.receipt.data.name)).toEqual([
+      'alpha',
+      'beta',
+      'gamma',
+    ]);
+    expect(envelope.data.results[0].receipt.type).toBe('theme.build');
+  }, 120_000);
+
+  it('keeps the bare theme.build envelope for a single file', async () => {
+    const dir = themeDir();
+    const r = await runCli(['--json', 'theme', 'build', 'alpha.mjs'], dir);
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout).type).toBe('theme.build');
+  }, 120_000);
+
+  it('--check passes when every theme is current and fails when one drifts', async () => {
+    const dir = themeDir();
+    expect((await runCli(['theme', 'build', ...FILES], dir)).status).toBe(0);
+
+    const fresh = await runCli(['theme', 'build', ...FILES, '--check'], dir);
+    expect(fresh.status).toBe(0);
+
+    // Drift one committed output rather than its source: the harness runs the
+    // CLI in-process, where jiti would serve a re-read theme file from its
+    // module cache.
+    fs.writeFileSync(path.join(dir, 'beta.css'), '/* hand-edited */\n');
+    const drifted = await runCli(['theme', 'build', ...FILES, '--check'], dir);
+    expect(drifted.status).toBe(1);
+    expect(drifted.stdout + drifted.stderr).toMatch(/beta\.css/);
+  }, 120_000);
+
+  it('rejects --out with more than one theme', async () => {
+    const dir = themeDir();
+    const r = await runCli(
+      ['theme', 'build', 'alpha.mjs', 'beta.mjs', '--out', 'one.css'],
+      dir,
+    );
+    expect(r.status).toBe(1);
+    expect(r.stderr).toMatch(/--out takes a single output path/);
+    expect(fs.existsSync(path.join(dir, 'one.css'))).toBe(false);
+  }, 120_000);
+
+  it('stops at the first failure and names the theme that failed', async () => {
+    const dir = themeDir();
+    fs.writeFileSync(
+      path.join(dir, 'beta.mjs'),
+      `export default { tokens: { '--color-bg': '#010203' } };\n`,
+    );
+    const r = await runCli(['theme', 'build', ...FILES], dir);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toMatch(/beta\.mjs: Theme must have a name/);
+    expect(fs.existsSync(path.join(dir, 'alpha.css'))).toBe(true);
+    expect(fs.existsSync(path.join(dir, 'gamma.css'))).toBe(false);
+  }, 120_000);
+
+  it('tells the user a quoted glob was never expanded', async () => {
+    const dir = themeDir();
+    const r = await runCli(['theme', 'build', '*.mjs'], dir);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toMatch(/expanded by your shell/);
+  }, 120_000);
+});

package/clients/cli/commands/build-theme.watch.test.mjs

@@ -156,4 +156,71 @@ describe('theme build --watch', () => {
     expect(exited).toBe(true);
     expect(stdout).toMatch(/Stopped watching/);
   }, 30_000);
+
+  it('watches every file it was given and rebuilds only the one that changed', async () => {
+    const first = path.join(tmpDir, 'w1.mjs');
+    const second = path.join(tmpDir, 'w2.mjs');
+    fs.writeFileSync(
+      first,
+      `export default { name: 'w1', tokens: { '--color-bg': '#ffffff' } };\n`,
+    );
+    fs.writeFileSync(
+      second,
+      `export default { name: 'w2', tokens: { '--color-bg': '#eeeeee' } };\n`,
+    );
+
+    const child = spawn(
+      process.execPath,
+      [CLI_BIN, 'theme', 'build', 'w1.mjs', 'w2.mjs', '--watch'],
+      {cwd: tmpDir, env: {...process.env, FORCE_COLOR: '0'}},
+    );
+    let stdout = '';
+    child.stdout.on('data', d => (stdout += d.toString()));
+    child.stderr.on('data', d => (stdout += d.toString()));
+
+    try {
+      const built = await waitFor(
+        () =>
+          fs.existsSync(path.join(tmpDir, 'w1.css')) &&
+          fs.existsSync(path.join(tmpDir, 'w2.css')),
+      );
+      expect(built).toBe(true);
+      await waitFor(() => /Watching w1\.mjs, w2\.mjs/.test(stdout));
+      const firstCssBefore = fs.readFileSync(path.join(tmpDir, 'w1.css'), 'utf-8');
+
+      const changed = `export default { name: 'w2', tokens: { '--color-bg': '#010203' } };\n`;
+      fs.writeFileSync(second, changed);
+
+      const rebuilt = await waitFor(
+        () => {
+          try {
+            if (
+              fs
+                .readFileSync(path.join(tmpDir, 'w2.css'), 'utf-8')
+                .includes('#010203')
+            ) {
+              return true;
+            }
+          } catch {
+            // CSS mid-write; fall through to re-touch.
+          }
+          try {
+            fs.writeFileSync(second, changed);
+          } catch {
+            // Re-touch failed (e.g. dir mid-teardown); the next poll retries.
+          }
+          return false;
+        },
+        {timeout: 20000, interval: 200},
+      );
+      expect(rebuilt).toBe(true);
+      expect(stdout).toMatch(/rebuilding w2\.mjs/);
+      expect(stdout).not.toMatch(/rebuilding w1\.mjs/);
+      expect(fs.readFileSync(path.join(tmpDir, 'w1.css'), 'utf-8')).toBe(
+        firstCssBefore,
+      );
+    } finally {
+      child.kill('SIGINT');
+    }
+  }, 30_000);
 });

package/clients/cli/commands/discover.broken-integration.test.mjs

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover` and `astryx search` against an integration whose
+ * manifest fails to load.
+ *
+ * A manifest authored against a removed API throws on import, contributes
+ * nothing, and used to leave discover reporting "No integrations configured."
+ * — the package simply vanished. These drive the real CLI in-process against a
+ * hermetic project (astryx.config.mjs + a throwing astryx.integration.mjs under
+ * node_modules) and pin the loud behavior.
+ */
+
+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 {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const CORE_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../core',
+);
+
+let tmpDir;
+let project;
+
+/**
+ * Configure `@test/broken` with a manifest that throws at import. Calling an
+ * undeclared factory stands in for the real failure this came from: a 0.2.x
+ * manifest still calling `createIntegration`, which 0.3.0 removed.
+ */
+function buildBrokenIntegration() {
+  const intDir = path.join(project, 'node_modules', '@test', 'broken');
+  fs.mkdirSync(path.join(intDir, 'components'), {recursive: true});
+  fs.writeFileSync(
+    path.join(intDir, 'package.json'),
+    JSON.stringify({name: '@test/broken', version: '1.2.3'}),
+  );
+  fs.writeFileSync(
+    path.join(intDir, 'astryx.integration.mjs'),
+    `export default createIntegration({components: './components'});\n`,
+  );
+  fs.writeFileSync(
+    path.join(project, 'astryx.config.mjs'),
+    `export default {integrations: ['@test/broken']};\n`,
+  );
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-broken-'));
+  project = path.join(tmpDir, 'project');
+  fs.mkdirSync(project, {recursive: true});
+  fs.writeFileSync(
+    path.join(project, 'package.json'),
+    JSON.stringify({name: 'proj', version: '1.0.0'}),
+  );
+  buildBrokenIntegration();
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('astryx discover with a manifest that fails to load', () => {
+  it('warns on stderr and does not claim nothing is configured', async () => {
+    const {status, stdout, stderr} = await runCli(['discover'], {cwd: project});
+
+    expect(status).toBe(0);
+    expect(stderr).toContain(
+      'Warning: @test/broken has 1 integration issue(s). ' +
+        'Run: astryx validate-integration @test/broken',
+    );
+    expect(stdout).not.toContain('No integrations configured.');
+    expect(stdout).toContain('No external components found in configured integrations.');
+  });
+
+  it('reports meta.configured=true in --json, with the nudge suppressed', async () => {
+    const {status, stdout, stderr} = await runCli(['discover', '--json'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).meta).toEqual({configured: true});
+    expect(stderr).not.toContain('integration issue');
+  });
+});
+
+describe('astryx search with a manifest that fails to load', () => {
+  // search needs a resolvable @astryxdesign/core; without one it errors out
+  // before it can list anything, which is not the case under test.
+  beforeEach(() => {
+    const scope = path.join(project, 'node_modules', '@astryxdesign');
+    fs.mkdirSync(scope, {recursive: true});
+    fs.symlinkSync(CORE_DIR, path.join(scope, 'core'), 'dir');
+  });
+
+  it('warns on stderr, and suppresses the nudge under --json', async () => {
+    const {status, stderr} = await runCli(['search', 'button'], {cwd: project});
+
+    expect(status).toBe(0);
+    expect(stderr).toContain(
+      'Warning: @test/broken has 1 integration issue(s). ' +
+        'Run: astryx validate-integration @test/broken',
+    );
+
+    const asJson = await runCli(['search', 'button', '--json'], {cwd: project});
+    expect(asJson.status).toBe(0);
+    expect(asJson.stderr).not.toContain('integration issue');
+  }, 30_000);
+});

package/clients/cli/commands/discover.mjs

@@ -15,6 +15,8 @@ import {jsonOut} from '../../../foundation/response/json.mjs';
 import {emit, section, text, record, records, list, code} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {discover as discoverApi} from '../../../api/discover/discover.mjs';
+import {Project} from '../../../foundation/config/project.mjs';
+import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as discoverCommand} from './discover.doc.mjs';
@@ -41,6 +43,16 @@ export function registerDiscover(program) {
       const zh = program.opts().zh || false;
       const run = getCliInvocation();
 
+      // Non-blocking nudge: if any configured integration has validation
+      // issues, print one compact line to stderr pointing at
+      // validate-integration. Best-effort; suppressed in --json mode.
+      try {
+        const project = await Project.load(process.cwd());
+        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+      } catch {
+        // Never let the nudge break the command.
+      }
+
       let result;
       try {
         result = await discoverApi(query, {components: options.components, lang, zh});

package/clients/cli/commands/search.mjs

@@ -26,6 +26,8 @@ import {emit, section, text, records} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {search as searchApi} from '../../../api/search/search.mjs';
+import {Project} from '../../../foundation/config/project.mjs';
+import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
 import {doc as searchCommand} from './search.doc.mjs';
 import {doc as searchFn} from '../../../api/search/search.doc.mjs';
 
@@ -41,6 +43,13 @@ export function registerSearch(program) {
     ) => {
       const json = program.opts().json || false;
 
+      try {
+        const project = await Project.load(process.cwd());
+        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+      } catch {
+        // Never let the nudge break the command.
+      }
+
       // Parse --limit to a number; the API validates it (positive integer) and
       // throws ERR_INVALID_ARGUMENT, so we pass NaN through rather than
       // pre-rejecting with a generic code here.

package/clients/cli/commands/template-cdn.behavior.test.mjs

@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CLI behavior for `astryx template --cdn`.
+ *
+ * The API leaf is covered by api/template/cdn/cdn.test.mjs; what is only
+ * reachable here is the terminal binding — that the flag short-circuits the
+ * family's name resolution, which message the user sees, and the JSON envelope.
+ * A receipt read at the wrong depth (`result.written` instead of
+ * `result.data.written`) writes the file and then reports a skip, and no unit
+ * test of the leaf can see it.
+ */
+
+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';
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-cli-template-cdn-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'tmp', private: true}),
+  );
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+const read = f => fs.readFileSync(path.join(tmpDir, f), 'utf-8');
+
+describe('astryx template --cdn', () => {
+  it('writes the page and says it wrote it', async () => {
+    const {status, stdout} = await runCli(['template', '--cdn'], {cwd: tmpDir});
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Wrote cdn\.template\.html/);
+    expect(stdout).not.toMatch(/already exists/);
+    expect(read('cdn.template.html')).toMatch(/<script type="importmap">/);
+  });
+
+  it('leaves an existing file alone, and says that instead', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'cdn.template.html'), '<!-- mine -->\n');
+
+    const {status, stdout} = await runCli(['template', '--cdn'], {cwd: tmpDir});
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/already exists/);
+    expect(read('cdn.template.html')).toBe('<!-- mine -->\n');
+  });
+
+  it('replaces it with --overwrite', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'cdn.template.html'), '<!-- mine -->\n');
+
+    const {status} = await runCli(['template', '--cdn', '--overwrite'], {
+      cwd: tmpDir,
+    });
+
+    expect(status).toBe(0);
+    expect(read('cdn.template.html')).toMatch(/importmap/);
+  });
+
+  it('writes to the path given to the flag', async () => {
+    const {status} = await runCli(['template', '--cdn', 'public/demo.html'], {
+      cwd: tmpDir,
+    });
+
+    expect(status).toBe(0);
+    expect(read(path.join('public', 'demo.html'))).toMatch(/importmap/);
+  });
+
+  it('returns a template.cdn envelope under --json', async () => {
+    const {status, stdout} = await runCli(['--json', 'template', '--cdn'], {
+      cwd: tmpDir,
+    });
+
+    expect(status).toBe(0);
+    const payload = JSON.parse(stdout);
+    expect(payload.type).toBe('template.cdn');
+    expect(payload.data).toEqual({
+      path: 'cdn.template.html',
+      version: expect.stringMatching(/^\d+\.\d+\.\d+/),
+      written: true,
+      reason: null,
+    });
+  });
+
+  it('refuses a path that escapes the project', async () => {
+    const {status, stderr} = await runCli(
+      ['template', '--cdn', '../escaped.html'],
+      {cwd: tmpDir},
+    );
+
+    expect(status).toBe(1);
+    expect(stderr).toMatch(/outside the project root/);
+    expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.html'))).toBe(
+      false,
+    );
+  });
+
+  // The flag exists because the positional cannot: `template cdn` would resolve
+  // `cdn` against everything discoverAll() finds, so a template with that id
+  // would shadow the starter page. The flag answers before discovery runs.
+  it('does not shadow, or get shadowed by, a discovered template id', async () => {
+    const {status, stderr} = await runCli(['template', 'cdn'], {cwd: tmpDir});
+
+    expect(status).toBe(1);
+    expect(stderr).toMatch(/Unknown template "cdn"/);
+    expect(fs.existsSync(path.join(tmpDir, 'cdn.template.html'))).toBe(false);
+  });
+});

package/clients/cli/commands/template.doc.mjs

@@ -18,7 +18,9 @@ export const doc = {
   description:
     'One entry point for the template family: with no name it lists the discovered ' +
     'templates; with a name it shows the source or a layout skeleton, or scaffolds it ' +
-    'into the project at a target path. Narrow an ambiguous name with --type and/or --package.',
+    'into the project at a target path. Narrow an ambiguous name with --type and/or --package. ' +
+    '--cdn writes the no-build-step CDN starter page, which ships as an asset rather than as ' +
+    'a discovered template.',
   fn: 'template',
   args: [
     {name: 'name', param: 'name', required: false},
@@ -43,6 +45,12 @@ export const doc = {
       description:
         'Show layout skeleton with spatial annotations (padding, gap, nesting)',
     },
+    {
+      flag: '--cdn [path]',
+      param: 'options.cdn',
+      description:
+        'Write the no-build-step CDN starter page (default: cdn.template.html)',
+    },
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
@@ -55,9 +63,11 @@ export const doc = {
       label: 'Scaffold into the app',
       cli: 'astryx template dashboard ./src/app',
     },
+    {label: 'CDN starter page', cli: 'astryx template --cdn'},
+    {label: 'CDN starter page, elsewhere', cli: 'astryx template --cdn public/demo.html'},
   ],
   exitCodes: [
-    {code: 0, when: 'success'},
+    {code: 0, when: 'success, including a CDN page left untouched because it already exists'},
     {
       code: 1,
       when: 'unknown or ambiguous template, no source, a path escape, or an existing target without --overwrite',

package/clients/cli/commands/template.mjs

@@ -41,7 +41,8 @@ export {discoverTemplates, listTemplates} from '../../../api/template/template.m
  *   import('../../../api/template/template.type.mjs').TemplateListResponse |
  *   import('../../../api/template/template.type.mjs').TemplateShowResponse |
  *   import('../../../api/template/template.type.mjs').TemplateSkeletonResponse |
- *   import('../../../api/template/template.type.mjs').TemplateCopyResponse
+ *   import('../../../api/template/template.type.mjs').TemplateCopyResponse |
+ *   import('../../../api/template/template.type.mjs').TemplateCdnResponse
  * )} TemplateResponse
  */
 
@@ -55,7 +56,7 @@ export function registerTemplate(program) {
       /**
        * @param {string | undefined} name
        * @param {string | undefined} targetPath
-       * @param {{list?: boolean, type?: string, package?: string, skeleton?: boolean, overwrite?: boolean}} options
+       * @param {{list?: boolean, type?: string, package?: string, skeleton?: boolean, cdn?: boolean | string, overwrite?: boolean}} options
        */
       async (name, targetPath, options) => {
       const json = program.opts().json || false;
@@ -83,7 +84,8 @@ export function registerTemplate(program) {
         name &&
         targetPath &&
         !options.list &&
-        !options.skeleton
+        !options.skeleton &&
+        !options.cdn
       ) {
         const collision = await detectTemplateCollision(name, targetPath);
         if (collision && !options.overwrite) {
@@ -103,6 +105,7 @@ export function registerTemplate(program) {
           await templateApi(name, {
             list: options.list,
             skeleton: options.skeleton,
+            cdn: options.cdn,
             type: /** @type {'page' | 'block' | undefined} */ (options.type),
             package: options.package,
             targetPath,
@@ -147,6 +150,7 @@ export function registerTemplate(program) {
                 `${run} template <id> --skeleton        Layout reference`,
                 `${run} template --list --type block    List only blocks`,
                 `${run} template --list --package <pkg> List from one package`,
+                `${run} template --cdn                 CDN starter page, no build step`,
               ].join('\n'),
             ),
           );
@@ -179,6 +183,23 @@ export function registerTemplate(program) {
           );
           break;
         }
+
+        case 'template.cdn': {
+          if (!result.data.written) {
+            emit(
+              text(`[skip] ${result.data.path} already exists — left as is.`),
+              text('Pass --overwrite to replace it with a fresh copy.'),
+            );
+            break;
+          }
+          emit(
+            text(`[ok] Wrote ${result.data.path}`),
+            text(
+              `Open it in a browser — no bundler, no install, no build step. Every CDN URL is pinned to ${result.data.version}, and the annotations mark the parts that are load-bearing.`,
+            ),
+          );
+          break;
+        }
       }
     },
   });

package/clients/cli/commands/theme-build.doc.mjs

@@ -14,17 +14,19 @@ export const doc = {
   name: 'theme build',
   displayName: 'astryx theme build',
   namespace: 'cli',
-  summary: 'Compile a defineTheme file to CSS + JS',
+  summary: 'Compile one or more defineTheme files to CSS + JS',
   description:
     'Compiles a file that calls defineTheme() into a scoped CSS file, a JS module, and ' +
-    'type declarations: the exact CSS the <Theme> runtime emits. With --check it writes ' +
+    'type declarations: the exact CSS the <Theme> runtime emits. Takes any number of theme ' +
+    'files and compiles them in one process, in argument order, stopping at the first ' +
+    'failure — an app with several themes does not need a shell loop. With --check it writes ' +
     'nothing and instead reports whether the committed outputs have drifted from source. ' +
     'When a separate build step emits the icon registry, --icons-specifier declares the ' +
     'fully specified module path that the generated JS should import.',
   fn: 'themeBuild',
-  args: [{name: 'file', param: 'file', required: true}],
+  args: [{name: 'files', param: 'file', required: true, variadic: true}],
   options: [
-    {flag: '-o, --out <path>', param: 'options.out', description: 'Output CSS file path'},
+    {flag: '-o, --out <path>', param: 'options.out', description: 'Output CSS file path (single theme only)'},
     {
       flag: '--icons-specifier <specifier>',
       param: 'options.iconsSpecifier',
@@ -33,7 +35,7 @@ export const doc = {
     },
     {
       flag: '-w, --watch',
-      description: 'Rebuild automatically when the theme file changes (Ctrl-C to stop)',
+      description: 'Rebuild automatically when a theme file changes (Ctrl-C to stop)',
     },
     {
       flag: '-c, --check',
@@ -47,6 +49,10 @@ export const doc = {
       label: 'Build to a CSS file',
       cli: 'astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css',
     },
+    {
+      label: 'Build every theme in a directory',
+      cli: 'astryx theme build ./src/themes/*.ts',
+    },
     {
       label: 'Check for drift (CI)',
       cli: 'astryx theme build ./src/themes/ocean.ts --check',

package/clients/cli/lib/json-shim.test.mjs

@@ -61,7 +61,7 @@ describe('--json shim: --help renders JSON envelope', () => {
     expect(parsed.apiVersion).toBe(1);
     expect(parsed.type).toBe('help');
     expect(parsed.data.command).toBe('astryx theme build');
-    expect(parsed.data.usage).toMatch(/<file>/);
+    expect(parsed.data.usage).toMatch(/<files\.\.\.>/);
   });
 });
 

package/clients/cli/lib/manifest.mjs

@@ -70,9 +70,10 @@ export const RESPONSE_TYPES = {
     'template.show',
     'template.skeleton',
     'template.copy',
+    'template.cdn',
   ],
   hook: ['hook.list', 'hook.detail', 'hook.detail.params'],
-  'theme build': ['theme.build', 'theme.build.check'],
+  'theme build': ['theme.build', 'theme.build.check', 'theme.build.batch'],
   'theme list': ['theme.list'],
   'theme add': ['theme.list', 'theme.add'],
   'theme template': ['theme.template'],
@@ -103,7 +104,7 @@ const EXAMPLES = {
   ],
   build: ['astryx build', 'astryx build "analytics dashboard" --json'],
   swizzle: ['astryx swizzle XDSButton'],
-  template: ['astryx template --json', 'astryx template dashboard ./src/app'],
+  template: ['astryx template --json', 'astryx template dashboard ./src/app', 'astryx template --cdn'],
   hook: ['astryx hook', 'astryx hook useFocusTrap --json'],
   'theme build': [
     'astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css',