@astryxdesign/cli 0.4.1 → 0.4.2-canary.356d2f9

package/clients/cli/commands/build-theme.font-warning.test.mjs

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file End-to-end test for the `astryx theme build` font-loading warning
+ * (#5015). A theme that names webfont families gets, AFTER the install
+ * instructions, a stdout notice naming the fonts plus the copy-pasteable
+ * fix — the Google Fonts <link> pair and a self-hosted @font-face with
+ * font-display: swap — and still exits 0 (it is a warning, not an error).
+ * Themes that only name generics or known system stacks get none of it.
+ */
+
+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, source) {
+  fs.mkdirSync(dir, {recursive: true});
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(file, source);
+  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, regardless of job ordering.
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-fonts-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build font-loading warning', () => {
+  it('prints the unloaded fonts and the <link>/@font-face fix after the install instructions', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(
+      project,
+      'fonty',
+      `export default {
+  name: 'fonty',
+  typography: {
+    body: {family: 'Space Grotesk', fallbacks: 'Arial, sans-serif'},
+    code: {family: 'JetBrains Mono'},
+  },
+};\n`,
+    );
+
+    const result = await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    // The install instructions still come out intact…
+    expect(result.stdout).toContain("from './fonty'");
+    // …followed by the warning naming the theme and every unloaded family…
+    expect(result.stdout).toContain('names fonts it does not load');
+    expect(result.stdout).toContain('"Space Grotesk"');
+    expect(result.stdout).toContain('"JetBrains Mono"');
+    // …and the copy-pasteable fix, both flavors.
+    expect(result.stdout).toContain(
+      '<link rel="preconnect" href="https://fonts.googleapis.com"',
+    );
+    expect(result.stdout).toContain('family=Space+Grotesk');
+    expect(result.stdout).toContain('family=JetBrains+Mono');
+    expect(result.stdout).toContain('display=swap');
+    expect(result.stdout).toContain('@font-face');
+    expect(result.stdout).toContain('font-display: swap');
+    expect(result.stdout).toContain('astryx docs typography');
+    // The one-line summaries follow the CLI's stream contract: warnings on
+    // stderr, like the override-validation warnings in the same build.
+    expect(result.stderr).toContain('Font "Space Grotesk"');
+    expect(result.stderr).toContain('Font "JetBrains Mono"');
+  });
+
+  it('keeps --json stdout one valid envelope: warnings inside, snippet suppressed', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(
+      project,
+      'fonty',
+      `export default { name: 'fonty', tokens: { '--font-family-body': '"Space Grotesk", sans-serif' } };\n`,
+    );
+
+    const result = await runCli(
+      ['--json', 'theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    // The whole stdout must parse — any human snippet leaking into --json
+    // mode corrupts the envelope, so this asserts the "JSON is always JSON"
+    // contract, not just substring presence.
+    const envelope = JSON.parse(result.stdout);
+    expect(envelope.type).toBe('theme.build');
+    expect(envelope.data.warnings).toEqual(
+      expect.arrayContaining([expect.stringContaining('Font "Space Grotesk"')]),
+    );
+    expect(result.stdout).not.toContain('fonts.googleapis.com');
+    // Human one-liners are silenced too — machine mode stays quiet.
+    expect(result.stderr).not.toContain('Font "');
+  });
+
+  it('prints nothing font-related for a theme of generics and system stacks', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(
+      project,
+      'sys',
+      `export default {
+  name: 'sys',
+  tokens: {
+    '--color-bg': '#fff',
+    '--font-family-body': 'Helvetica, Arial, sans-serif',
+    '--font-family-code': 'ui-monospace',
+  },
+};\n`,
+    );
+
+    const result = await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("from './sys'");
+    expect(result.stdout).not.toContain('names fonts it does not load');
+    expect(result.stdout).not.toContain('fonts.googleapis.com');
+    expect(result.stdout).not.toContain('@font-face');
+    expect(result.stderr).not.toContain('Font "');
+  });
+});

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

@@ -30,6 +30,7 @@ import {logger} from '../../../api/logger.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {themeAdd} from '../../../api/theme/add/add.mjs';
+import {themeTemplate} from '../../../api/theme/template/template.mjs';
 import {themeList} from '../../../api/theme/list/list.mjs';
 import {themeBuild, importSpecifier} from '../../../api/theme/build/build.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
@@ -37,9 +38,11 @@ import {doc as themeGroup} from './theme.doc.mjs';
 import {doc as themeBuildCommand} from './theme-build.doc.mjs';
 import {doc as themeListCommand} from './theme-list.doc.mjs';
 import {doc as themeAddCommand} from './theme-add.doc.mjs';
+import {doc as themeTemplateCommand} from './theme-template.doc.mjs';
 import {doc as themeBuildFn} from '../../../api/theme/themeBuild.doc.mjs';
 import {doc as themeListFn} from '../../../api/theme/themeList.doc.mjs';
 import {doc as themeAddFn} from '../../../api/theme/themeAdd.doc.mjs';
+import {doc as themeTemplateFn} from '../../../api/theme/themeTemplate.doc.mjs';
 
 /**
  * Path to this CLI's real entry (clients/cli/bin/astryx.mjs), resolved from
@@ -363,4 +366,51 @@ export function registerTheme(program) {
       );
     },
   });
+
+  defineCommand(theme, themeTemplateCommand, {
+    fn: themeTemplateFn,
+    action: (
+      /** @type {string | undefined} */ targetPath,
+      /** @type {{overwrite?: boolean}} */ options,
+    ) => {
+      const json = program.opts().json || false;
+
+      /** @type {import('../../../api/theme/theme.type.mjs').ThemeTemplateResponse} */
+      let result;
+      try {
+        result = themeTemplate({
+          targetPath,
+          overwrite: options.overwrite,
+          cwd: process.cwd(),
+        });
+      } catch (e) {
+        const err =
+          /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {
+          suggestions: err.suggestions || [],
+          code: err.code,
+        });
+        return;
+      }
+
+      if (json) return jsonOut(result);
+
+      const invocation = getCliInvocation(process.cwd());
+      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.`),
+        );
+        return;
+      }
+      emit(
+        text(`[ok] Wrote ${result.data.path}`),
+        text(
+          'It documents every defineTheme field, the token families, and the component override syntax. ' +
+            'Copy what you need into your own theme file, then delete it.',
+        ),
+        code(`${invocation} theme build ${result.data.path}`),
+      );
+    },
+  });
 }

package/clients/cli/commands/init.behavior.test.mjs

@@ -71,13 +71,24 @@ describe('astryx init --features', () => {
     expect(exists('AGENTS.md')).toBe(true);
   });
 
-  it('--features theme writes no files and points at the theme workflow', async () => {
+  it('--features theme writes the annotated theme template', async () => {
     const {status, stdout} = await runCli(['init', '--features', 'theme'], {cwd: tmpDir});
     expect(status).toBe(0);
-    expect(fs.readdirSync(tmpDir)).toEqual([]);
+    expect(exists('theme.template.ts')).toBe(true);
+    expect(read('theme.template.ts')).toMatch(/defineTheme/);
+    expect(read('theme.template.ts')).not.toMatch(/Copyright \(c\) Meta Platforms/);
     expect(stdout).toMatch(/theme/i);
   });
 
+  it('--features theme never clobbers an existing theme.template.ts', async () => {
+    // Someone's edited copy outranks ours; re-running init must be safe.
+    fs.writeFileSync(path.join(tmpDir, 'theme.template.ts'), '// mine\n');
+    const {status, stdout} = await runCli(['init', '--features', 'theme'], {cwd: tmpDir});
+    expect(status).toBe(0);
+    expect(read('theme.template.ts')).toBe('// mine\n');
+    expect(stdout).toMatch(/already exists/);
+  });
+
   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);

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

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CLI behavior for `astryx theme template`.
+ *
+ * The API leaf is covered by api/theme/template/template.test.mjs; what is only
+ * reachable here is the terminal binding — which message the user sees, and the
+ * JSON envelope. The first version of this command read `result.written`
+ * instead of `result.data.written`, so it wrote the file and then told the user
+ * it had skipped: a receipt read at the wrong depth is invisible to a unit test
+ * of the leaf.
+ */
+
+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-theme-template-'));
+  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 theme template', () => {
+  it('writes the template and says it wrote it', async () => {
+    const {status, stdout} = await runCli(['theme', 'template'], {cwd: tmpDir});
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Wrote theme\.template\.ts/);
+    expect(stdout).not.toMatch(/already exists/);
+    expect(read('theme.template.ts')).toMatch(/defineTheme/);
+  });
+
+  it('leaves an existing file alone, and says that instead', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'theme.template.ts'), '// mine\n');
+
+    const {status, stdout} = await runCli(['theme', 'template'], {cwd: tmpDir});
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/already exists/);
+    expect(read('theme.template.ts')).toBe('// mine\n');
+  });
+
+  it('replaces it with --overwrite', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'theme.template.ts'), '// mine\n');
+
+    const {status} = await runCli(['theme', 'template', '--overwrite'], {cwd: tmpDir});
+
+    expect(status).toBe(0);
+    expect(read('theme.template.ts')).toMatch(/defineTheme/);
+  });
+
+  it('returns a theme.template envelope under --json', async () => {
+    const {status, stdout} = await runCli(['--json', 'theme', 'template'], {cwd: tmpDir});
+
+    expect(status).toBe(0);
+    const payload = JSON.parse(stdout);
+    expect(payload.type).toBe('theme.template');
+    expect(payload.data).toEqual({
+      path: 'theme.template.ts',
+      written: true,
+      reason: null,
+    });
+  });
+
+  it('refuses a path that escapes the project', async () => {
+    const {status, stderr} = await runCli(['theme', 'template', '../escaped.ts'], {
+      cwd: tmpDir,
+    });
+
+    expect(status).toBe(1);
+    expect(stderr).toMatch(/outside the project root/);
+    expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.ts'))).toBe(false);
+  });
+});

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

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx theme template`. The terminal binding of the
+ * `themeTemplate()` function (referenced via `fn`); its args/flags map to that
+ * function's params so a converter can build Commander config + --help from one
+ * source of truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'theme template',
+  displayName: 'astryx theme template',
+  namespace: 'cli',
+  summary: 'Write the annotated theme template into your project',
+  description:
+    'Writes theme.template.ts: the annotated reference for the whole theme surface — every ' +
+    'defineTheme field, the token families, the component override syntax, and how a theme is ' +
+    'consumed — naming the CLI command that prints the authoritative reference for each. Read ' +
+    'it, copy what you need into your own theme file, delete it. Use `theme add <slug>` instead ' +
+    'to start from a theme we ship. Leaves an existing file untouched unless --overwrite.',
+  fn: 'themeTemplate',
+  args: [{name: 'path', param: 'options.targetPath', required: false}],
+  options: [
+    {
+      flag: '-f, --overwrite',
+      param: 'options.overwrite',
+      description: 'Replace an existing file',
+    },
+  ],
+  examples: [
+    {label: 'Write it at the project root', cli: 'astryx theme template'},
+    {label: 'Somewhere else', cli: 'astryx theme template src/themes/starter.ts'},
+  ],
+  exitCodes: [
+    {code: 0, when: 'success, including when an existing file was left untouched'},
+    {code: 1, when: 'the target path escapes the project'},
+  ],
+  related: ['theme add', 'theme list', 'theme build'],
+};

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

@@ -17,8 +17,8 @@ export const doc = {
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +
     'subcommand list; the work happens in the subcommands: compile a theme (build), ' +
-    'scaffold one into your project (add), or list the bundled themes (list).',
-  subcommands: ['build', 'add', 'list'],
+    'scaffold one into your project (add), start a custom one from the annotated template (template), or list the bundled themes (list).',
+  subcommands: ['build', 'add', 'list', 'template'],
   examples: [
     {label: 'List bundled themes', cli: 'astryx theme list'},
     {label: 'Scaffold a theme', cli: 'astryx theme add matcha'},

package/clients/cli/index.mjs

@@ -69,6 +69,7 @@ export const JSON_SUPPORTED = new Set([
   'theme build',
   'theme list',
   'theme add',
+  'theme template',
   'upgrade',
   'manifest',
   'doctor',

package/clients/cli/lib/manifest.mjs

@@ -75,6 +75,7 @@ export const RESPONSE_TYPES = {
   'theme build': ['theme.build', 'theme.build.check'],
   'theme list': ['theme.list'],
   'theme add': ['theme.list', 'theme.add'],
+  'theme template': ['theme.template'],
   upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
   manifest: ['manifest'],
   doctor: ['doctor'],
@@ -113,6 +114,7 @@ const EXAMPLES = {
     'astryx theme add matcha',
     'astryx theme add matcha ./src/themes/matcha',
   ],
+  'theme template': ['astryx theme template', 'astryx theme template --json'],
   upgrade: ['astryx upgrade --json'],
   manifest: ['astryx manifest --json', 'astryx --json'],
   doctor: ['astryx doctor', 'astryx doctor --json'],

package/foundation/agent-docs/agent-docs.mjs

@@ -354,7 +354,7 @@ export function generateCompressedIndex(version, {coreDir, invocation = getCliIn
   } else {
     lines.push("- Custom styling: component props first; else style/className with tokens — var(--color-*|--spacing-*|--radius-*). No raw hex/px. (No StyleX/Tailwind compiler here — don't use xstyle/utility classes.)");
   }
-  lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent via `astryx theme` — never override --color-* in :root.');
+  lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent belongs in the theme (`astryx theme list` / `theme add <slug>`, or `astryx theme template` for a custom one) — never override --color-* in :root.');
   // Self-check — post-generation pass. Validated via vibe tests (internal/vibe-tests/
   // prompt-purity-test): on complex multi-step UIs the rules above alone still leave raw
   // CSS in ~11-13% of runs; a re-read-and-fix pass cuts that ~4x at negligible token cost.

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

@@ -183,6 +183,11 @@ export const doc = {
       description:
         'A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.',
     },
+    {
+      value: 'theme.template',
+      description:
+        'A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.',
+    },
 
     // upgrade
     {

package/foundation/text/copyright-header.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Remove the leading Meta copyright header, preserving any BOM/shebang before
+ * it. Returns the source unchanged when the header is absent.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+export function stripCopyrightHeader(source: string): string;

package/foundation/text/copyright-header.mjs

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Strips our repo's copyright header from files we scaffold into someone
+ * else's project.
+ *
+ * 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.
+ *
+ * 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
+ * cannot import CLI internals), so a change to the header format has to land in
+ * both.
+ */
+
+/**
+ * Matches our header at the very start of a file, with the leading BOM and/or
+ * shebang captured so they survive the strip.
+ */
+const META_COPYRIGHT_HEADER_RE =
+  /^(\uFEFF?(?:#![^\r\n]*(?:\r?\n))?)\/\/ 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.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+export function stripCopyrightHeader(source) {
+  return source.replace(META_COPYRIGHT_HEADER_RE, '$1');
+}

package/foundation/text/copyright-header.test.mjs

@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the shared copyright-header stripper.
+ *
+ * Two commands copy repo files into a consumer's project (`theme add`,
+ * `init --features theme`); this is what keeps our boilerplate out of their
+ * tree. The BOM/shebang cases are the ones worth pinning — a naive strip
+ * corrupts the file rather than merely leaving a stray comment.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {stripCopyrightHeader} from './copyright-header.mjs';
+
+const HEADER = '// Copyright (c) Meta Platforms, Inc. and affiliates.\n';
+
+describe('stripCopyrightHeader', () => {
+  it('removes the header and the blank line after it', () => {
+    expect(stripCopyrightHeader(`${HEADER}\nexport const a = 1;\n`)).toBe(
+      'export const a = 1;\n',
+    );
+  });
+
+  it('removes it with no blank line after', () => {
+    expect(stripCopyrightHeader(`${HEADER}export const a = 1;\n`)).toBe(
+      'export const a = 1;\n',
+    );
+  });
+
+  it('keeps a shebang, which must stay on line 1', () => {
+    expect(stripCopyrightHeader(`#!/usr/bin/env node\n${HEADER}\nrun();\n`)).toBe(
+      '#!/usr/bin/env node\nrun();\n',
+    );
+  });
+
+  it('keeps a BOM', () => {
+    expect(stripCopyrightHeader(`\uFEFF${HEADER}\nexport const a = 1;\n`)).toBe(
+      '\uFEFFexport const a = 1;\n',
+    );
+  });
+
+  it('handles CRLF line endings', () => {
+    expect(
+      stripCopyrightHeader(
+        '// Copyright (c) Meta Platforms, Inc. and affiliates.\r\n\r\nexport const a = 1;\r\n',
+      ),
+    ).toBe('export const a = 1;\r\n');
+  });
+
+  it('leaves a file without the header alone', () => {
+    expect(stripCopyrightHeader('export const a = 1;\n')).toBe('export const a = 1;\n');
+  });
+
+  it('only strips at the top — a mention further down is content', () => {
+    const source = `export const a = 1;\n${HEADER}`;
+    expect(stripCopyrightHeader(source)).toBe(source);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.4.1",
+  "version": "0.4.2-canary.356d2f9",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -84,10 +84,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.4.2-canary.356d2f9",
+    "@astryxdesign/core": "0.4.2-canary.356d2f9",
+    "@astryxdesign/lab": "0.4.2-canary.356d2f9",
+    "@astryxdesign/theme-neutral": "0.4.2-canary.356d2f9",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -105,10 +105,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.4.2-canary.356d2f9",
+    "@astryxdesign/core": "0.4.2-canary.356d2f9",
+    "@astryxdesign/lab": "0.4.2-canary.356d2f9",
+    "@astryxdesign/theme-neutral": "0.4.2-canary.356d2f9",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {