@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/theme/themeAdd.doc.mjs

@@ -44,6 +44,7 @@ export const doc = {
       type: 'string',
       description:
         'Project directory used for integration discovery and target paths.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.package',
@@ -57,11 +58,6 @@ export const doc = {
       description:
         'Copy receipt with slug, displayName, maintained flag, owner package, outputDir, entry, exportName, and files.',
     },
-    {
-      type: 'theme.list',
-      description:
-        'The CLI list affordance routes a bare `astryx theme add` or `--list` to themeListAvailable() and returns every available theme with its owner.',
-    },
   ],
   throws: [
     {
@@ -74,7 +70,10 @@ export const doc = {
       when: 'the selected installed package has a blocking integration or theme-descriptor error',
     },
     {code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
-    {code: 'ERR_NO_SOURCE', when: 'a theme file to copy is missing'},
+    {
+      code: 'ERR_NO_SOURCE',
+      when: 'the bundled theme descriptors cannot be read, or a theme file to copy is missing',
+    },
     {
       code: 'ERR_FILE_EXISTS',
       when: 'a destination exists and overwrite is not set',
@@ -82,12 +81,12 @@ export const doc = {
     {code: 'ERR_WRITE_FAILED', when: 'writing files fails'},
   ],
   examples: [
-    {label: 'Copy a bundled theme', code: "await themeAdd('ocean');"},
+    {label: 'Copy a bundled theme', code: "await themeAdd('butter');"},
     {
-      label: 'Copy an integration theme',
-      code: "await themeAdd('ocean', {package: '@acme/themes'});",
+      label: 'Name the owner package and the destination',
+      code: "await themeAdd('butter', {package: '@astryxdesign/cli', targetPath: 'src/brand-theme'});",
     },
   ],
   command: 'theme add',
-  related: ['themeList', 'listThemes'],
+  related: ['themeListAvailable', 'themeTemplate', 'listThemes'],
 };

package/api/theme/themeBuild.doc.mjs

@@ -14,14 +14,13 @@ export const doc = {
   name: 'themeBuild',
   namespace: 'cli/api',
   displayName: 'themeBuild()',
-  summary: 'Compile a defineTheme file to CSS + JS + type declarations.',
+  summary:
+    'Compile a defineTheme() file to scoped CSS, a JS module, and type declarations, or check committed outputs for drift in CI.',
   description:
-    'The compiler behind `astryx theme build`. Reads a file that calls defineTheme() and, ' +
-    "via @astryxdesign/core's shared generator (the single source of truth, so the build " +
-    'emits the exact CSS the <Theme> runtime does), writes a scoped CSS file, a JS module ' +
-    'that re-exports the built theme, and a .d.ts (plus an optional .variants.d.ts when the ' +
-    'theme adds custom prop values). When another build step emits the icon registry, ' +
-    '{iconsSpecifier} declares the fully specified module path for the generated JS import. ' +
+    'The compiler behind `astryx theme build`. Reads a file that calls defineTheme() and ' +
+    'writes a scoped CSS file, a JS module that re-exports the built theme, and a .d.ts ' +
+    '(plus an optional .variants.d.ts when the theme adds custom prop values). It uses ' +
+    "@astryxdesign/core's own generator, so the CSS matches what the <Theme> runtime emits. " +
     'With {check: true} it writes nothing and instead compares ' +
     'each output against disk, returning the drift: the CI guard for committed, generated theme CSS.',
   importPath: '@astryxdesign/cli/api',
@@ -48,7 +47,7 @@ export const doc = {
       name: 'options.out',
       type: 'string',
       description:
-        'Override the output CSS path; the sibling .js and .d.ts derive from it. A relative path must stay within cwd.',
+        'Override the output CSS path. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file. A relative path must stay within cwd.',
     },
     {
       name: 'options.check',
@@ -61,13 +60,14 @@ export const doc = {
       name: 'options.iconsSpecifier',
       type: 'string',
       description:
-        'Override the icon-registry import specifier in the generated JS module, for example ./icons.mjs. When omitted, the source specifier is preserved.',
+        'Override the import specifier of the icon registry in the generated JS module, for example ./icons.mjs. Takes effect only when the theme sets icons: to a named import; when omitted, the source specifier is kept.',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description:
-        'Directory the theme file and @astryxdesign/core resolve against.',
+        'Directory the theme file, a relative out path, and the returned output paths resolve against.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -79,7 +79,7 @@ export const doc = {
     {
       type: 'theme.build.check',
       description:
-        'The {check: true} receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: "missing" | "outdated"}), and the full list of checked paths. Writes nothing.',
+        'The {check: true} receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: "missing" | "outdated"}), and the full list of checked paths. Writes nothing. Resolves to null, like a normal build, when the theme produces no CSS.',
     },
   ],
   throws: [
@@ -102,7 +102,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_INCOMPATIBLE',
-      when: 'the selected theme carries ordered-adaptation intent but the installed @astryxdesign/core does not export generateAdaptationCSS (upgrade core)',
+      when: 'the installed @astryxdesign/core does not export generateAdaptationCSS and the theme either declares ordered adaptations or has lineage whose adaptation use could not be observed (upgrade core)',
     },
     {
       code: 'ERR_WRITE_FAILED',
@@ -124,5 +124,5 @@ export const doc = {
     },
   ],
   command: 'theme build',
-  related: ['themeAdd', 'themeList', 'listThemes'],
+  related: ['themeTemplate', 'themeAdd', 'themeListAvailable', 'listThemes'],
 };

package/api/theme/themeList.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   displayName: 'themeList()',
   summary: 'List themes bundled with this CLI build.',
   description:
-    'Projects the bundled typed theme descriptors into a synchronous theme.list envelope. This preserves the original programmatic API contract. The CLI command uses themeListAvailable() so installed integrations also appear.',
+    'Synchronous list of the themes bundled with the CLI. It does not include themes from installed integrations; use themeListAvailable() for the list `astryx theme list` shows.',
   importPath: '@astryxdesign/cli/api',
   signature: 'themeList(): ThemeListResponse',
   keywords: ['theme', 'list', 'themes', 'bundled', 'available'],

package/api/theme/themeListAvailable.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   displayName: 'themeListAvailable()',
   summary: 'List bundled and installed integration themes.',
   description:
-    'Loads Project for the requested directory, combines the CLI bundle with source themes from installed integrations, and projects each entry with its owner package. An unreadable project configuration degrades to the bundled descriptors.',
+    'Lists the bundled themes plus source themes from integrations installed in cwd, each with its owner package. If the project configuration cannot be read, it falls back to the bundled themes.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeListAvailable(options?: {cwd?: string, package?: string}): Promise<ThemeListResponse>',
@@ -24,6 +24,7 @@ export const doc = {
       type: 'string',
       description:
         'Project directory whose installed integrations contribute themes.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.package',

package/api/theme/themePaletteGenerate.doc.mjs

@@ -27,30 +27,34 @@ export const doc = {
     {
       name: 'configPath',
       type: 'string',
-      description: 'JSON generation request, resolved within cwd.',
+      description:
+        'Path to a JSON file holding a TonalPaletteGenerationInput (the object generateTonalPalette() takes), resolved within cwd.',
       required: true,
     },
     {
       name: 'options.out',
       type: 'string',
       description:
-        'Optional candidate JSON destination. A sibling .receipt.json path is derived from it.',
+        'Where to write the candidate: a path ending in .ts (a TypeScript module) or .json. A sibling <name>.receipt.json is written next to it.',
     },
     {
       name: 'options.preview',
       type: 'string',
-      description: 'Optional path for a self-contained HTML review artifact.',
+      description:
+        'Optional path, ending in .html, for a self-contained HTML review page.',
     },
     {
       name: 'options.overwrite',
       type: 'boolean',
-      description: 'Replace existing candidate and receipt files.',
+      description:
+        "Replace existing candidate, receipt and preview files. Without it, if any target exists, nothing is written and the result has written: false, reason: 'exists'.",
       default: 'false',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description: 'Directory used to resolve the input and output paths.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -64,17 +68,20 @@ export const doc = {
     {code: 'ERR_FILE_NOT_FOUND', when: 'the config file does not exist'},
     {
       code: 'ERR_PALETTE_GENERATION',
-      when: 'the request, seed, stop layout, mode, or anchor constraint is invalid',
+      when: 'the config is not valid JSON; the request, seed, stop layout, mode or anchor is invalid; out does not end in .ts or .json; or preview does not end in .html',
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
       when: 'an input or output path escapes cwd, or output would replace input',
     },
-    {code: 'ERR_WRITE_FAILED', when: 'the candidate pair cannot be written'},
+    {
+      code: 'ERR_WRITE_FAILED',
+      when: 'the candidate, receipt or preview file cannot be written',
+    },
   ],
   examples: [
     {
-      label: 'Preview a candidate',
+      label: 'Generate a candidate without writing files',
       code: "themePaletteGenerate('palette.config.json');",
     },
     {
@@ -83,5 +90,5 @@ export const doc = {
     },
   ],
   command: 'theme palette generate',
-  related: ['themeBuild', 'themeTemplate'],
+  related: ['generateTonalPalette', 'themeBuild', 'themeTemplate'],
 };

package/api/theme/themeTargets.doc.mjs

@@ -22,7 +22,7 @@ export const doc = {
     'Same source as the Theming table `astryx component <Name>` prints ' +
     '(the component docs), so the list cannot drift from the components, and `theme build` ' +
     'validates overrides against this exact set. A filter naming a component gives that ' +
-    "component's set; anything else is a substring search over the keys.",
+    "component's set; anything else is a case-insensitive substring search over each target's key, class and component.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeTargets(filter?: string, ctx?: {cwd?: string}): Promise<ThemeTargetsResponse>',
@@ -41,13 +41,14 @@ export const doc = {
       name: 'filter',
       type: 'string',
       description:
-        'A component name (exact, case-insensitive) or a substring of a target key. Omit for the whole surface.',
+        'A component name (exact, case-insensitive), or a substring of a target key, class or component. Omit for the whole surface.',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description:
         "Directory the project's @astryxdesign/core is resolved from.",
+      default: 'process.cwd()',
     },
   ],
   returns: [

package/api/theme/themeTemplate.doc.mjs

@@ -43,6 +43,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory the target path resolves against.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -64,5 +65,5 @@ export const doc = {
     },
   ],
   command: 'theme template',
-  related: ['themeAdd', 'themeBuild', 'themeList'],
+  related: ['themeAdd', 'themeBuild', 'themeListAvailable', 'themeTargets'],
 };

package/api/upgrade/run/files-changed.test.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The upgrade receipt counts a file once when a core codemod AND an
+ * integration codemod both change it: `filesChanged` is the union of the two
+ * runners' files, while `transformsApplied` adds their changes.
+ *
+ * Uses a real consumer under a repo-local temp dir (Vite blocks dynamic import
+ * of config and integration modules from /tmp), the real core registry, and an
+ * installed integration whose code codemod stamps the same file.
+ */
+
+import {describe, it, expect, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {upgrade} from '../upgrade.mjs';
+import {
+  latestVersion,
+  versions,
+  getTransformsBetween,
+} from '../../../assets/codemods/registry.mjs';
+
+const SLOW = 60_000;
+
+/** The registry version whose manifest ships the authoring migration. */
+async function authoringTier() {
+  const all = await getTransformsBetween('0.0.0', latestVersion);
+  const tier = all.find(({transforms}) =>
+    transforms.some(t => t.name === 'migrate-authoring-imports'),
+  );
+  if (!tier) throw new Error('no registry version ships the authoring migration');
+  return tier.version;
+}
+
+/**
+ * A consumer with installed core at the registry's latest version and one
+ * old-surface file that the core authoring codemods rewrite.
+ * @param {string} dir
+ * @param {{integrationCodemod: boolean}} options
+ */
+function seed(dir, {integrationCodemod}) {
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'consumer', version: '1.0.0'}),
+  );
+  const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+  fs.mkdirSync(core, {recursive: true});
+  fs.writeFileSync(
+    path.join(core, 'package.json'),
+    JSON.stringify({name: '@astryxdesign/core', version: latestVersion}),
+  );
+  fs.mkdirSync(path.join(dir, 'src'), {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'src', 'Button.doc.mjs'),
+    [
+      "import {createComponentDoc} from '@astryxdesign/core/authoring';",
+      "export default createComponentDoc({name: 'Button', props: []});",
+      '',
+    ].join('\n'),
+  );
+  if (!integrationCodemod) return;
+  fs.writeFileSync(
+    path.join(dir, 'astryx.config.mjs'),
+    "export default {integrations: ['@acme/widgets']};\n",
+  );
+  const pkg = path.join(dir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(path.join(pkg, 'codemods', latestVersion), {recursive: true});
+  fs.writeFileSync(
+    path.join(pkg, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkg, 'astryx.integration.mjs'),
+    "export default {codemods: './codemods'};\n",
+  );
+  fs.writeFileSync(
+    path.join(pkg, 'codemods', latestVersion, 'acme-stamp.mjs'),
+    "export default {type: 'code', title: 'Stamp', transform: file => (file.source.includes('// acme') ? null : `${file.source}// acme\\n`)};\n",
+  );
+}
+
+describe('upgrade receipt — filesChanged across core and integration codemods', () => {
+  /** @type {string[]} */
+  const dirs = [];
+  afterEach(() => {
+    for (const dir of dirs.splice(0)) fs.rmSync(dir, {recursive: true, force: true});
+  });
+
+  /** @param {{integrationCodemod: boolean}} options */
+  async function run(options) {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-files-changed-'));
+    dirs.push(dir);
+    seed(dir, options);
+    const tier = await authoringTier();
+    const from = versions[versions.indexOf(tier) - 1];
+    const res = await upgrade({from, path: 'src'}, {cwd: dir});
+    expect(res.type).toBe('upgrade.run');
+    return res.data;
+  }
+
+  it('counts a file changed by both a core and an integration codemod once', async () => {
+    const coreOnly = await run({integrationCodemod: false});
+    expect(coreOnly.filesChanged).toBe(1);
+    expect(coreOnly.transformsApplied).toBeGreaterThan(0);
+
+    const both = await run({integrationCodemod: true});
+    expect(both.integrations).toEqual(['@acme/widgets']);
+    expect(both.filesChanged).toBe(1);
+    expect(both.transformsApplied).toBe(coreOnly.transformsApplied + 1);
+  }, SLOW);
+});

package/api/upgrade/run/run.mjs

@@ -137,6 +137,12 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   }
   const apply = options.apply ?? false;
 
+  // One fact about the resolved source directory, captured before anything
+  // runs. `--path` defaults to `./src`, so a project laid out as `app/` (or a
+  // typo) skips every code codemod; without this the receipt is byte-identical
+  // to a clean, fully migrated project.
+  const sourcePathFound = fs.existsSync(path_);
+
   const currentVersion = /** @type {string} */ (options.from);
   const installed = detectInstalledTargetVersion(cwd);
   if (!installed) {
@@ -282,6 +288,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
             refreshed: false,
             action: 'none',
           },
+          sourcePathFound,
           filesChanged: coreResult?.totalFilesChanged ?? 0,
           transformsApplied: coreResult?.totalTransformsApplied ?? 0,
           modifiedFiles: uniqueFiles(coreResult?.changedFiles).map(file =>
@@ -407,6 +414,12 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
       refreshed: false,
       action: 'none',
     }),
+    // A missing source directory is the one way this command can migrate
+    // nothing and still look complete: every codemod is skipped, filesChanged
+    // stays 0, and errors stays empty. The receipt carries the fact so a
+    // machine consumer can tell "nothing needed changing" from "nothing was
+    // ever read" — the human text says so via the runner's own error line.
+    sourcePathFound,
   };
 
   let integrationResult = null;
@@ -437,9 +450,11 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
 
   const registryResult = await reconcileCompositions();
 
-  const mergedFilesChanged =
-    (coreResult?.totalFilesChanged ?? 0) +
-    (integrationResult?.totalFilesChanged ?? 0);
+  // A file a core codemod AND an integration codemod both changed is one file.
+  const mergedFilesChanged = new Set([
+    ...(coreResult?.changedFiles ?? []),
+    ...(integrationResult?.changedFiles ?? []),
+  ]).size;
   const mergedTransformsApplied =
     (coreResult?.totalTransformsApplied ?? 0) +
     (integrationResult?.totalTransformsApplied ?? 0);
@@ -640,12 +655,16 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   }
 
   const registryOk = receipt.registryCompositions?.ok ?? true;
+  const done = apply ? 'Upgrade complete' : 'Dry run complete';
   logger.log(
     protectedFiles.length > 0
       ? 'Upgrade incomplete: protected changes remain\n'
-      : registryOk
-        ? (apply ? 'Upgrade complete' : 'Dry run complete') + '\n'
-        : 'Upgrade finished with unresolved registry items\n',
+      : !registryOk
+        ? 'Upgrade finished with unresolved registry items\n'
+        : sourcePathFound
+          ? done + '\n'
+          : `${done}, but ${path.relative(cwd, path_) || '.'} does not exist, so no source files were scanned. ` +
+            `Pass --path <your source directory> if your code does not live in ./src.\n`,
   );
   return {
     type: 'upgrade.run',

package/api/upgrade/run/run.test.mjs

@@ -3,7 +3,8 @@
 /**
  * @file Colocated tests for the upgrade.run leaf — the --path scan dir must be
  * confined to cwd (upgrade rewrites source in place with --apply, so an escaping
- * or out-of-tree path must be rejected).
+ * or out-of-tree path must be rejected), and the receipt must say whether that
+ * dir existed at all.
  */
 
 import {describe, it, expect, beforeEach, afterEach} from 'vitest';
@@ -51,3 +52,46 @@ describe('upgrade.run — --path confinement', () => {
     ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
   }, SLOW);
 });
+
+describe('upgrade.run — sourcePathFound', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-srcpath-'));
+    seedProject(dir);
+  });
+  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  // The receipt for a project whose source lives somewhere other than ./src was
+  // byte-identical to a fully migrated one: exit 0, filesChanged 0, errors [].
+  // The only signal was a human log line --json suppresses by design.
+  it('reports false when the resolved source directory is missing, and still counts nothing', async () => {
+    fs.rmSync(path.join(dir, 'src'), {recursive: true, force: true});
+    fs.mkdirSync(path.join(dir, 'app'), {recursive: true});
+    fs.writeFileSync(path.join(dir, 'app', 'index.ts'), 'const x = 1;\n');
+
+    const res = await upgrade({from: '0.0.1', apply: true}, {cwd: dir});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.sourcePathFound).toBe(false);
+    expect(res.data.filesChanged).toBe(0);
+    expect(res.data.errors).toEqual([]);
+  }, SLOW);
+
+  it('reports true for a source directory that exists', async () => {
+    const res = await upgrade({from: '0.0.1', apply: true}, {cwd: dir});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.sourcePathFound).toBe(true);
+  }, SLOW);
+
+  it('follows --path, so the right directory under another name reports true', async () => {
+    fs.rmSync(path.join(dir, 'src'), {recursive: true, force: true});
+    fs.mkdirSync(path.join(dir, 'app'), {recursive: true});
+    fs.writeFileSync(path.join(dir, 'app', 'index.ts'), 'const x = 1;\n');
+
+    const res = await upgrade({from: '0.0.1', path: 'app'}, {cwd: dir});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.sourcePathFound).toBe(true);
+  }, SLOW);
+});

package/api/upgrade/upgrade.doc.mjs

@@ -13,19 +13,16 @@ export const doc = {
   name: 'upgrade',
   namespace: 'cli/api',
   displayName: 'upgrade()',
-  summary: 'Run version migrations and reconcile copied compositions.',
+  summary:
+    'After bumping @astryxdesign/core, migrate project source with codemods and update copied compositions.',
   description:
-    'Migrates project source from a previous Astryx version to the currently ' +
-    'installed one by running the registered codemods, and compares the fully ' +
-    'rendered managed agent-docs block on every migration path, including ' +
-    'same-Core integration guidance changes; list and registry-only modes do not ' +
-    'run migration reconciliation. Dry-run previews without writing; `apply` ' +
-    'writes the prepared block only after selected codemods and hooks succeed. ' +
-    'Core codemods run before ' +
-    'the config is loaded so a config codemod can repair an otherwise-invalid ' +
-    'astryx.config. Copied compositions carry adjacent receipts with exact canonical and format-specific install bases; upgrade ' +
-    'compares those installed bases with the matching registry release, updates pristine ' +
-    'files, merges non-overlapping edits, and leaves conflicting originals untouched.',
+    'Runs the codemods between `from` and the installed Core version, then refreshes the ' +
+    'managed agent-docs block. Dry-run by default; `apply` writes changes only after the ' +
+    'selected codemods and hooks succeed. Config codemods run before astryx.config is ' +
+    'loaded, so they can repair an invalid config. Also updates copied compositions from ' +
+    'their install receipts: unchanged files are updated, non-overlapping edits are merged, ' +
+    'and conflicts are left untouched. `list` only lists codemods; `registry` only updates ' +
+    'copied compositions.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'upgrade(options?: UpgradeOptions, ctx?: {cwd?: string}): Promise<UpgradeListResponse | UpgradeRegistryResponse | UpgradeStatusResponse | UpgradeRunResponse>',
@@ -42,7 +39,7 @@ export const doc = {
       name: 'options.from',
       type: 'string',
       description:
-        'Version before the dependency bump. Required unless `list` or `registry` is set.',
+        'Version before the dependency bump; the target is the installed @astryxdesign/core (or legacy @xds/core). Required unless `list` or `registry` is set.',
     },
     {
       name: 'options.apply',
@@ -55,11 +52,13 @@ export const doc = {
       type: 'boolean',
       description:
         'Run codemods even when `from` is at/after the installed version.',
+      default: 'false',
     },
     {
       name: 'options.codemod',
       type: 'string',
-      description: 'Run a single named transform instead of the full set.',
+      description:
+        'Run only this codemod. Optional codemods run only when named here. Setting it also skips copied-composition reconciliation.',
     },
     {
       name: 'options.skipCodemod',
@@ -83,23 +82,26 @@ export const doc = {
       type: 'boolean',
       description:
         'Install jscodeshift when it is missing; otherwise a missing jscodeshift throws ERR_DEP_MISSING.',
+      default: 'false',
     },
     {
       name: 'options.registry',
       type: 'boolean',
       description:
-        'Reconcile copied compositions from their install receipts without requiring `from`.',
+        'Only reconcile copied compositions from their install receipts; `from` is not required. Cannot be combined with `list`, `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`.',
       default: 'false',
     },
     {
       name: 'options.list',
       type: 'boolean',
       description: 'Return the available codemods instead of running any.',
+      default: 'false',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description: 'Directory to run the upgrade in.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -116,36 +118,36 @@ export const doc = {
     {
       type: 'upgrade.status',
       description:
-        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). Each carries the agent-docs summary and, when found, the copied-composition registry summary.',
+        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary.',
     },
     {
       type: 'upgrade.run',
       description:
-        'The terminal run receipt: from/to versions, codemod count, integrations processed, agent-docs and registry summaries, modifiedFiles, protectedFiles, declinedCandidates, and completion state. A protected required change returns complete: false with ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
+        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), sourcePathFound (false when the resolved `path` does not exist, so nothing was scanned), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
     },
   ],
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: '`from` is missing (and neither `list` nor `registry` is set), or the project config fails strict validation and no pending config codemod can repair it',
+      when: '`from` is missing (and neither `list` nor `registry` is set); `list` and `registry` are both set; `registry` is combined with `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`; an `integration` specifier is invalid or not installed; or astryx.config fails to load or validate and no pending config codemod repairs it',
     },
     {code: 'ERR_INVALID_VERSION', when: '`from` is not a valid semver string'},
     {code: 'ERR_PATH_TRAVERSAL', when: '`path` resolves outside cwd'},
     {
       code: 'ERR_VERSION_DETECT',
-      when: 'the installed @astryxdesign/core version cannot be detected',
+      when: 'neither @astryxdesign/core nor legacy @xds/core is installed in cwd; with `registry`, only when copied-composition receipts exist and @astryxdesign/core is not installed',
     },
     {
       code: 'ERR_DEP_MISSING',
-      when: 'jscodeshift is required but could not be installed',
+      when: 'jscodeshift is missing and `installDeps` is not set, or installing it failed',
     },
     {
       code: 'ERR_UNKNOWN_CODEMOD',
-      when: 'a `codemod` name matches no registered codemod',
+      when: 'the version range has codemods but none remain selected: `codemod` names no codemod in the range, or `skipCodemod` excludes all of them',
     },
     {
       code: 'ERR_CODEMOD_FAILED',
-      when: 'one or more codemods failed, or a post-codemod hook failed',
+      when: 'one or more codemods failed, or a post-codemod hook failed, and no protected file still needs a change (otherwise an upgrade.run receipt with complete: false is returned)',
     },
     {
       code: 'ERR_CODEMOD_PROTECTION_SOURCE',

package/api/upgrade/upgrade.type.d.mts

@@ -168,6 +168,7 @@ export type UpgradeRunResponse = {
         integrations: string[];
         agentDocsRefreshed: boolean;
         agentDocs: AgentDocsSummary;
+        sourcePathFound: boolean;
         registryCompositions?: RegistryCompositionSummary | undefined;
         complete?: boolean | undefined;
         errorCode?: "ERR_CODEMOD_PROTECTED" | undefined;