@astryxdesign/cli 0.4.2 → 0.4.3-canary.07f9998

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',

package/clients/cli/lib/manifest.test.mjs

@@ -146,8 +146,10 @@ describe('manifest: shape', () => {
     const component = allEntries.find((c) => c.name === 'component');
     expect(component.arguments.map((a) => a.name)).toContain('name');
     const themeBuild = allEntries.find((c) => c.name === 'theme build');
-    expect(themeBuild.arguments.map((a) => a.name)).toContain('file');
-    expect(themeBuild.arguments.find((a) => a.name === 'file').required).toBe(true);
+    expect(themeBuild.arguments.map((a) => a.name)).toContain('files');
+    const files = themeBuild.arguments.find((a) => a.name === 'files');
+    expect(files.required).toBe(true);
+    expect(files.variadic).toBe(true);
   });
 });
 

package/foundation/fs/path-safety.mjs

@@ -154,9 +154,9 @@ export function sanitizeName(name, options = {}) {
     );
   }
 
-  if (name === '.' || name === '..' || name.startsWith('..')) {
+  if (name === '.' || name === '..' || name.startsWith('.')) {
     throw new PathSafetyError(
-      `Invalid ${label} "${name}": must not be '.' or start with '..'.`,
+      `Invalid ${label} "${name}": must not start with '.'.`,
       'NAME_TRAVERSAL',
     );
   }

package/foundation/fs/path-safety.test.mjs

@@ -91,6 +91,13 @@ describe('sanitizeName', () => {
     expect(() => sanitizeName('.')).toThrow(PathSafetyError);
   });
 
+  it('rejects dotfile names (.env, .htaccess) that could create hidden files', () => {
+    expect(() => sanitizeName('.env')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.htaccess')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.bashrc')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.gitignore')).toThrow(PathSafetyError);
+  });
+
   it('rejects NUL bytes', () => {
     expect(() => sanitizeName('foo\0bar')).toThrow(PathSafetyError);
   });

package/foundation/integrations/integration-warnings.test.mjs

@@ -68,6 +68,23 @@ describe('warnOnIntegrationIssues', () => {
     expect(errLines).toHaveLength(0);
   });
 
+  it('warns for a manifest that failed to load, which declares no roots', async () => {
+    // loadIntegrations records __loadError and no contribution roots, so every
+    // on-disk check finds nothing — without the load error itself counting as
+    // an issue, a stale manifest is silent everywhere.
+    const integration = {
+      ...loaded({name: '@acme/stale'}),
+      __loadError: 'createIntegration is not a function',
+    };
+    await warnOnIntegrationIssues([integration], {json: false});
+
+    expect(errLines).toHaveLength(1);
+    expect(errLines[0]).toBe(
+      'Warning: @acme/stale has 1 integration issue(s). ' +
+        'Run: astryx validate-integration @acme/stale',
+    );
+  });
+
   it('emits nothing for an integration with no issues', async () => {
     // Existing components root with no broken contributions → no issues.
     const componentsRoot = path.join(tmpDir, 'components');

package/foundation/integrations/validate-contributions.mjs

@@ -149,6 +149,13 @@ export async function validateLoadedIntegration(loaded) {
   /** @type {Issue[]} */
   const issues = [];
   if (!loaded || typeof loaded !== 'object') return issues;
+  // A manifest that threw on import (or failed the schema) carries a load-error
+  // marker and no contribution roots, so every check below would find nothing
+  // and report a clean integration — which is how a stale manifest used to go
+  // silently invisible. The load error IS the issue.
+  if (loaded.__loadError) {
+    return [issueError('integration_error', loaded.__loadError)];
+  }
   checkRoots(
     {
       components: loaded.components,

package/foundation/response/response-types.doc.mjs

@@ -150,6 +150,12 @@ export const doc = {
         'A scaffold receipt: template id, output directory, written file name, and file count.',
     },
 
+    {
+      value: 'template.cdn',
+      description:
+        'A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.',
+    },
+
     // hook
     {
       value: 'hook.list',
@@ -173,6 +179,11 @@ export const doc = {
       description:
         'The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing | outdated}), and the full list of checked paths. Writes nothing.',
     },
+    {
+      value: 'theme.build.batch',
+      description:
+        'Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme\'s theme.build (or theme.build.check) envelope, or null when it produced no CSS.',
+    },
     {
       value: 'theme.list',
       description:

package/foundation/text/copyright-header.mjs

@@ -6,9 +6,9 @@
  *
  * Every file in this repo carries the Meta copyright header, and several
  * commands copy repo files out verbatim — `theme add` (bundled theme sources),
- * `init --features theme` (the annotated theme template). A consumer's own
- * source tree should not inherit our boilerplate, and their lint may well
- * reject it.
+ * `init --features theme` (the annotated theme template), `template --cdn` (the
+ * CDN starter page). A consumer's own source tree should not inherit our
+ * boilerplate, and their lint may well reject it.
  *
  * SYNC: the same regex is applied by apps/docsite/src/lib/codeExamples.ts for
  * rendered code samples. That copy lives in a different package (the docsite
@@ -23,6 +23,11 @@
 const META_COPYRIGHT_HEADER_RE =
   /^(\uFEFF?(?:#![^\r\n]*(?:\r?\n))?)\/\/ Copyright \(c\) Meta Platforms, Inc\. and affiliates\.\r?\n(?:\r?\n)*/;
 
+/** The same header in HTML comment syntax, as scripts/add-copyright.sh writes
+ *  it into the .html assets we scaffold. */
+const META_COPYRIGHT_HEADER_HTML_RE =
+  /^(\uFEFF?)<!-- Copyright \(c\) Meta Platforms, Inc\. and affiliates\. -->\r?\n(?:\r?\n)*/;
+
 /**
  * Remove the leading Meta copyright header, preserving any BOM/shebang before
  * it. Returns the source unchanged when the header is absent.
@@ -31,5 +36,7 @@ const META_COPYRIGHT_HEADER_RE =
  * @returns {string}
  */
 export function stripCopyrightHeader(source) {
-  return source.replace(META_COPYRIGHT_HEADER_RE, '$1');
+  return source
+    .replace(META_COPYRIGHT_HEADER_RE, '$1')
+    .replace(META_COPYRIGHT_HEADER_HTML_RE, '$1');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.4.2",
+  "version": "0.4.3-canary.07f9998",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -25,6 +25,9 @@
     "agent-docs"
   ],
   "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "bin": {
     "astryx": "./clients/cli/bin/astryx.mjs",
     "cli": "./clients/cli/bin/astryx.mjs"
@@ -84,10 +87,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.4.3-canary.07f9998",
+    "@astryxdesign/core": "0.4.3-canary.07f9998",
+    "@astryxdesign/lab": "0.4.3-canary.07f9998",
+    "@astryxdesign/theme-neutral": "0.4.3-canary.07f9998",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -105,10 +108,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.4.3-canary.07f9998",
+    "@astryxdesign/core": "0.4.3-canary.07f9998",
+    "@astryxdesign/lab": "0.4.3-canary.07f9998",
+    "@astryxdesign/theme-neutral": "0.4.3-canary.07f9998",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {