@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme add',
   displayName: 'astryx theme add',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Scaffold a theme into your project as editable source',
   description:
     "Copies a bundled or installed integration theme's source into your project so you own it. " +
@@ -28,7 +28,8 @@ export const doc = {
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description: 'Overwrite existing files without prompting',
+      description:
+        'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',
     },
     {flag: '--list', description: 'List available themes'},
     {
@@ -40,7 +41,7 @@ export const doc = {
   examples: [
     {label: 'Scaffold a theme', cli: 'astryx theme add matcha'},
     {
-      label: 'Select an integration theme',
+      label: 'Pick the owner when two packages ship the same slug',
       cli: 'astryx theme add ocean --package @acme/themes',
     },
   ],
@@ -48,7 +49,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown or ambiguous theme, a path escape, a missing catalog file, or an existing file without --overwrite',
+      when: 'unknown or ambiguous theme, a path escape, a missing descriptor or source, or an existing file without --overwrite',
     },
   ],
   related: ['theme list', 'theme build'],

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme build',
   displayName: 'astryx theme build',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Compile standalone themes or one keyed theme family',
   description:
     'Compiles defineTheme() sources through the same theme pipeline into scoped CSS, ' +
@@ -28,34 +28,35 @@ export const doc = {
     {
       flag: '--family',
       description:
-        'Build the selected extension family into one keyed CSS, JS, and declaration set',
+        'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
     },
     {
       flag: '--family-key <key>',
       description:
-        'Lower-kebab filename stem required with --family; must differ from every member name',
+        'Lower-kebab filename stem required with --family and refused without it; must differ from every member name (ERR_THEME_INVALID)',
     },
     {
       flag: '-o, --out <path>',
       param: 'options.out',
-      description: 'Output CSS file path (single theme only)',
+      description:
+        'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
     },
     {
       flag: '--icons-specifier <specifier>',
       param: 'options.iconsSpecifier',
       description:
-        'Override the icon-registry import in the generated JS module (for example, ./icons.mjs)',
+        "Override the icon-registry import in the generated JS module, for example ./icons.mjs (default: the specifier in the theme source's own import). With --family it applies to every member's icon import",
     },
     {
       flag: '-w, --watch',
       description:
-        'Rebuild automatically when a theme file changes (Ctrl-C to stop)',
+        'Rebuild automatically when a theme file changes (Ctrl-C to stop). Refused with --check, --family, or --json (ERR_THEME_INVALID)',
     },
     {
       flag: '-c, --check',
       param: 'options.check',
       description:
-        'Verify the committed outputs match the source without writing; exit non-zero if stale',
+        'Verify the committed outputs match the source without writing; exit non-zero if stale. Composes with --family and several files; refused with --watch (ERR_THEME_INVALID)',
     },
   ],
   examples: [

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme list',
   displayName: 'astryx theme list',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List themes available to add',
   description:
     'Lists themes bundled with this CLI and source themes contributed by installed integrations, ' +
@@ -37,7 +37,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'the bundled-theme manifest or an installed theme catalog cannot be read',
+      when: 'a bundled or installed theme descriptor cannot be read',
     },
   ],
   related: ['theme add', 'theme build'],

package/clients/cli/commands/theme-palette-generate.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'theme palette generate',
   displayName: 'astryx theme palette generate',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Generate an OKLCH palette candidate for human review',
   description:
     'Reads an explicit JSON request and runs the versioned astryx-oklch-v1 recipe. ' +
@@ -18,7 +18,11 @@ export const doc = {
     'Without --out it prints a preview. With --out it writes a candidate file and detached ' +
     'receipt. --preview writes a standardized, self-contained HTML review artifact. ' +
     'TypeScript output is directly importable and contains no generator dependency. ' +
-    'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit.',
+    'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit. ' +
+    'When used in a theme integration, keep the palette request under the theme slug, ' +
+    'write the candidate and receipt under that same slug, import the candidate from the theme source, ' +
+    'and keep all three inside the theme directory: `astryx theme add` copies that whole ' +
+    'directory into the consumer project, so nothing else has to list them.',
   fn: 'themePaletteGenerate',
   args: [{name: 'config', param: 'configPath', required: true}],
   options: [
@@ -31,26 +35,27 @@ export const doc = {
     {
       flag: '--preview <path>',
       param: 'options.preview',
-      description: 'Write a standardized self-contained HTML preview',
+      description: 'Write a self-contained HTML preview page; the path must end in .html',
     },
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description: 'Replace existing candidate and receipt files',
+      description:
+        'Replace existing candidate, receipt, and preview files. Without it, if any of them exists, nothing is written',
     },
   ],
   examples: [
     {
       label: 'Preview candidate JSON',
-      cli: 'astryx theme palette generate palette.config.json',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json',
     },
     {
       label: 'Write candidate and receipt',
-      cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts',
     },
     {
       label: 'Write candidate, receipt, and review preview',
-      cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts --preview ocean.palette.html',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts --preview themes/ocean/tokens/ocean.palette.html',
     },
   ],
   exitCodes: [

package/clients/cli/commands/theme-palette-generate.test.mjs

@@ -132,4 +132,23 @@ describe('astryx theme palette generate', () => {
       code: 'ERR_PALETTE_GENERATION',
     });
   });
+
+  it('returns ERR_WRITE_FAILED for an output path it cannot use', async () => {
+    fs.writeFileSync(path.join(temporaryDirectory, 'blocker'), '');
+    const {status, stdout} = await runCli(
+      [
+        '--json',
+        'theme',
+        'palette',
+        'generate',
+        'palette.config.json',
+        '--out',
+        'blocker/ocean.palette.ts',
+      ],
+      {cwd: temporaryDirectory},
+    );
+
+    expect(status).toBe(1);
+    expect(JSON.parse(stdout)).toMatchObject({code: 'ERR_WRITE_FAILED'});
+  });
 });

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

@@ -5,11 +5,10 @@ export const doc = {
   type: 'command',
   name: 'theme palette',
   displayName: 'astryx theme palette',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Create and work with theme-owned color palettes',
   description:
-    'Palette authoring tools. The initial generate command creates reviewable candidates. ' +
-    'Palette inspection and diagnostic commands are intentionally deferred to follow-up work.',
+    'Palette authoring tools. generate writes a palette candidate for you to review before a theme uses it.',
   subcommands: ['generate'],
   examples: [
     {

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

@@ -17,8 +17,9 @@ describe('astryx theme targets', () => {
     const {status, stdout} = await runCli(['theme', 'targets', 'Switch']);
 
     expect(status).toBe(0);
-    expect(stdout).toMatch(/^switch\s+Switch\s+size\s+checked, disabled$/m);
-    expect(stdout).toMatch(/^switch-thumb\s+Switch\s+size\s+checked$/m);
+    // Inline layout: key  component - props - states - className
+    expect(stdout).toMatch(/^switch\s+Switch - size - checked, disabled - astryx-switch$/m);
+    expect(stdout).toMatch(/^switch-thumb\s+Switch - size - checked - astryx-switch-thumb$/m);
     expect(stdout).toMatch(/4 across 1 component/);
   });
 
@@ -28,7 +29,7 @@ describe('astryx theme targets', () => {
     expect(status).toBe(0);
     expect(stdout).toMatch(/^popover\s{2,}Popover/m);
     expect(stdout).toMatch(
-      /^popover-surface \[deprecated; use popover\]\s{2,}Popover/m,
+      /^popover-surface\s{2,}Popover - astryx-popover-surface - deprecated; use popover$/m,
     );
   });
 

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

@@ -13,15 +13,15 @@ export const doc = {
   type: 'command',
   name: 'theme targets',
   displayName: 'astryx theme targets',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List the component theming targets a theme can override',
   description:
     'Prints every `defineTheme` components key across the system: the stable class it paints, ' +
     'the component that declares it, and the props and states that are legal override keys ' +
     'under it. This is the whole themeable surface in one command: what auditing a theme, or ' +
     'answering "which key paints this pixel?", used to need one `astryx component <Name>` per ' +
-    'component to assemble. Pass a component name to scope it; pass any substring to search ' +
-    'keys. `--json` for a list a repo can lint its own theme against.',
+    'component to assemble. Pass a component name to scope it; pass any other text to search ' +
+    'target keys, classes, and components. `--json` for a list a repo can lint its own theme against.',
   fn: 'themeTargets',
   args: [{name: 'filter', param: 'filter', required: false}],
   examples: [

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

@@ -82,4 +82,16 @@ describe('astryx theme template', () => {
     expect(stderr).toMatch(/outside the project root/);
     expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.ts'))).toBe(false);
   });
+
+  it('fails a write with ERR_WRITE_FAILED under --json', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'blocker'), '');
+
+    const {status, stdout} = await runCli(
+      ['--json', 'theme', 'template', 'blocker/theme.ts'],
+      {cwd: tmpDir},
+    );
+
+    expect(status).toBe(1);
+    expect(JSON.parse(stdout).code).toBe('ERR_WRITE_FAILED');
+  });
 });

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme template',
   displayName: 'astryx theme template',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Write the annotated theme template into your project',
   description:
     'Writes theme.template.ts: the annotated reference for the whole theme surface, covering every ' +
@@ -36,7 +36,7 @@ export const doc = {
   ],
   exitCodes: [
     {code: 0, when: 'success, including when an existing file was left untouched'},
-    {code: 1, when: 'the target path escapes the project'},
+    {code: 1, when: 'the target path escapes the project, or the file cannot be written'},
   ],
   related: ['theme add', 'theme list', 'theme build'],
 };

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

@@ -12,8 +12,9 @@ export const doc = {
   type: 'command',
   name: 'theme',
   displayName: 'astryx theme',
-  namespace: 'cli',
-  summary: 'Theme tools: build, export, and manage themes',
+  namespace: 'cli/commands',
+  summary:
+    'Create and build themes: add a shipped one, compile to CSS, or list what a theme can override',
   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), ' +

package/clients/cli/commands/upgrade.ascii-output.test.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` human output is plain ASCII on every path: the codemod
+ * list, up to date, an empty range, a dry run, and an apply that runs a
+ * post-codemod hook and refreshes the agent docs.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {generateCompressedIndex} from '../../../foundation/agent-docs/agent-docs.mjs';
+
+const NON_ASCII = /[\u0080-\uFFFF]/;
+
+let tmpDir;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(tmpDir, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+/**
+ * Output lines (stdout and stderr) that contain a non-ASCII character.
+ * @param {string[]} args
+ */
+async function nonAsciiLines(args) {
+  const r = await runCli(args, {cwd: tmpDir});
+  expect(r.status).toBe(0);
+  return `${r.stdout}\n${r.stderr}`
+    .split('\n')
+    .filter(line => NON_ASCII.test(line));
+}
+
+beforeEach(() => {
+  // Repo-local so the config module can be imported under Vitest.
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-upgrade-ascii-'));
+  write('package.json', JSON.stringify({name: 'consumer', private: true}));
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
+  );
+  write(
+    'src/panel.tsx',
+    "import {useResizable} from '@astryxdesign/core';\n" +
+      'export const usePanel = () => useResizable({defaultSize: 250, minSizePx: 200});\n',
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('upgrade human output is ASCII', () => {
+  it('lists codemods', async () => {
+    expect(await nonAsciiLines(['upgrade', '--list'])).toEqual([]);
+  });
+
+  it('reports up to date and a missing agent-docs block', async () => {
+    expect(await nonAsciiLines(['upgrade', '--from', '0.6.0'])).toEqual([]);
+  });
+
+  it('reports a range with no codemods', async () => {
+    expect(
+      await nonAsciiLines(['upgrade', '--from', '0.6.0', '--force']),
+    ).toEqual([]);
+  });
+
+  it('previews and applies codemods, runs a hook, and refreshes agent docs', async () => {
+    write(
+      'astryx.config.mjs',
+      `export default {hooks: {postCodemod: [{name: 'noop', buildCommand: () => ({command: ${JSON.stringify(process.execPath)}, args: ['-e', '0']})}]}};\n`,
+    );
+    write('AGENTS.md', `# Agents\n\n${generateCompressedIndex('0.5.0')}\n`);
+
+    expect(await nonAsciiLines(['upgrade', '--from', '0.5.0'])).toEqual([]);
+    expect(
+      await nonAsciiLines(['upgrade', '--from', '0.5.0', '--apply']),
+    ).toEqual([]);
+    expect(fs.readFileSync(path.join(tmpDir, 'src/panel.tsx'), 'utf8')).toContain(
+      'minSize: 200',
+    );
+  });
+});

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

@@ -12,13 +12,15 @@ export const doc = {
   type: 'command',
   name: 'upgrade',
   displayName: 'astryx upgrade',
-  namespace: 'cli',
-  summary: 'Migrate versions and update ShadCN-copied compositions',
+  namespace: 'cli/commands',
+  summary:
+    'Update your code after upgrading Astryx, and refresh ShadCN-copied components',
   description:
     'Migrates project source from a previous Astryx version to the installed one by ' +
     'running the registered codemods, and refreshes the fully rendered managed ' +
     'agent-docs block when Core or configured integration guidance changes. ' +
     'Dry-run by default. --apply writes codemod and receipt changes, runs hooks, then refreshes agent docs. ' +
+    'Anything a post-codemod hook prints goes to stderr, so stdout carries only the result. ' +
     'ShadCN-copied compositions are checked automatically during a normal upgrade, or alone with --registry.',
   fn: 'upgrade',
   options: [
@@ -26,12 +28,13 @@ export const doc = {
       flag: '--from <version>',
       param: 'options.from',
       description:
-        'Previous version before the dependency upgrade; required unless --list or --registry is set',
+        'Previous version before the dependency upgrade; required unless --list or --registry is set. ' +
+        'The target is the installed @astryxdesign/core version, or legacy @xds/core when @astryxdesign/core is not installed',
     },
     {
       flag: '--apply',
       param: 'options.apply',
-      description: 'Write changes to disk (default: dry-run)',
+      description: 'Write changes to disk; without it, the run is a dry run',
       default: false,
     },
     {
@@ -44,7 +47,9 @@ export const doc = {
     {
       flag: '--codemod <name>',
       param: 'options.codemod',
-      description: 'Run a specific transform only',
+      description:
+        'Run only the named codemod. Optional codemods run only when named here; a normal run skips them. ' +
+        'Also skips the check of ShadCN-copied compositions. An unknown name exits 1 with ERR_UNKNOWN_CODEMOD when the version range has codemods',
     },
     {
       flag: '--skip-codemod <name...>',
@@ -53,10 +58,10 @@ export const doc = {
         'Exclude named codemods (repeatable). Re-run past a failed codemod by skipping it.',
     },
     {
-      flag: '--integration <package-or-file>',
+      flag: '--integration <package>',
       param: 'options.integration',
       description:
-        'Explicit integration package name or integration file path (repeatable)',
+        'Explicit integration specifier (repeatable). Resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.',
       default: [],
     },
     {
@@ -68,20 +73,24 @@ export const doc = {
     {
       flag: '--install-deps',
       param: 'options.installDeps',
-      description: 'Auto-install jscodeshift without prompting',
+      description:
+        'Install jscodeshift when it is missing. Without it, a missing jscodeshift fails the command with ERR_DEP_MISSING',
       default: false,
     },
     {
       flag: '--registry',
       param: 'options.registry',
       description:
-        'Only reconcile ShadCN-copied compositions; --from is not required',
+        'Only update ShadCN-copied compositions from their install receipts: unchanged files are updated, ' +
+        'edits that do not overlap are merged, and conflicts are left untouched; --from is not required. ' +
+        'Combining it with --list, --from, --force, --codemod, --skip-codemod, --integration or --install-deps exits 1 with ERR_INVALID_ARGUMENT',
       default: false,
     },
     {
       flag: '--list',
       param: 'options.list',
-      description: 'List available codemods',
+      description:
+        'List available codemods and do nothing else. Every other flag is ignored, except --registry, which is refused (exit 1)',
       default: false,
     },
   ],
@@ -94,11 +103,73 @@ export const doc = {
     {label: 'Apply a migration', cli: 'astryx upgrade --from 0.1.0 --apply'},
   ],
   exitCodes: [
-    {code: 0, when: 'success (including dry-run previews)'},
+    {code: 0, when: 'success, including complete dry-run previews'},
     {
       code: 1,
-      when: 'missing or invalid --from, a --path escape, an unknown codemod, a codemod failure, or unresolved registry items',
+      when:
+        'missing or invalid --from, --registry with --list or a migration flag, a --path escape, ' +
+        'no installed @astryxdesign/core (or legacy @xds/core), jscodeshift missing and not installed by --install-deps, ' +
+        'an astryx.config that fails validation and that no pending config codemod repairs, ' +
+        'an unreadable or invalid protection declaration, a protected file that still requires a codemod change, ' +
+        'an unknown codemod, a codemod or post-codemod hook failure, or unresolved registry items',
     },
   ],
   related: ['init', 'doctor'],
+  notes: [
+    {type: 'heading', level: 3, text: 'Protected files'},
+    {
+      type: 'prose',
+      text:
+        'Codemods never write to a file your project marks as generated, vendored, or ignored. ' +
+        'upgrade reads these marks from the files on disk, so the answer is the same with any version control, or none. ' +
+        'A file is protected when:',
+    },
+    {
+      type: 'list',
+      style: 'unordered',
+      items: [
+        'a `.gitattributes` file marks it `linguist-generated` or `linguist-vendored`',
+        'its leading comment says `@generated`, `@partially-generated`, or `Code generated ... DO NOT EDIT.`',
+        'a `.gitignore`, or the `.hgignore` at the project root, excludes it',
+        'it is an installed dependency (such as anything in `node_modules`), is inside `.git`, `.hg`, or `.sl`, is a symbolic link, or is outside the project',
+      ],
+    },
+    {
+      type: 'prose',
+      text:
+        'Rules work as they do in Git: a later rule wins, so `linguist-generated=false` or a `!` line in an ignore file ' +
+        'returns a file to normal handling. A folder name such as `dist` or `generated` protects nothing by itself. ' +
+        'If a protection file cannot be read or parsed, upgrade stops with ERR_CODEMOD_PROTECTION_SOURCE before it writes anything.',
+    },
+    {
+      type: 'code',
+      lang: 'text',
+      code:
+        '# .gitattributes\n' +
+        'generated/** linguist-generated=true\n' +
+        'vendor/** linguist-vendored=true\n' +
+        '\n' +
+        '# A later rule returns one authored file to normal handling\n' +
+        'generated/hand-authored.ts linguist-generated=false',
+    },
+    {
+      type: 'prose',
+      text:
+        'When a codemod would change a protected file, upgrade makes the change only in memory and leaves the file as it is. ' +
+        'The rest of the upgrade goes ahead. With --apply, your other files are written, then upgrade runs the ' +
+        '`hooks.postCodemod` commands from astryx.config (see `astryx docs authoring config`) and checks the protected ' +
+        'files again. If one still needs the change, the run is incomplete: it exits 1, prints ' +
+        'ERR_CODEMOD_PROTECTED with each file and the rule that protects it, and does not refresh the agent docs. ' +
+        'Regenerate or edit those files, then run the same upgrade again. A dry run reports the same files and writes nothing.',
+    },
+    {
+      type: 'prose',
+      text:
+        'With --json, the receipt says `complete: false` and `errorCode: "ERR_CODEMOD_PROTECTED"`. `modifiedFiles` lists the files ' +
+        'upgrade changed (or would change), and `protectedFiles` lists each blocked file with its `reasons`, `declarations` ' +
+        '(the rules that protect it), `codemods`, and `commands`. A generated file can name the command that rebuilds it on a ' +
+        '`Command:` line in its header, such as `// Command: pnpm run gen:panel`; upgrade prints it as ' +
+        '`Regenerate with: <command>` and lists it in `commands`.',
+    },
+  ],
 };