@astryxdesign/cli 0.4.1 → 0.4.2-canary.464a445

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.464a445",
   "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.464a445",
+    "@astryxdesign/core": "0.4.2-canary.464a445",
+    "@astryxdesign/lab": "0.4.2-canary.464a445",
+    "@astryxdesign/theme-neutral": "0.4.2-canary.464a445",
     "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.464a445",
+    "@astryxdesign/core": "0.4.2-canary.464a445",
+    "@astryxdesign/lab": "0.4.2-canary.464a445",
+    "@astryxdesign/theme-neutral": "0.4.2-canary.464a445",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {