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

package/api/theme/themeAdd.doc.mjs

@@ -9,10 +9,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeAdd',
+  namespace: 'cli/api',
   displayName: 'themeAdd()',
   summary: 'Copy an available theme into a project as editable source.',
   description:
-    'Resolves a theme from the CLI bundle or an installed integration and copies every catalog-listed source file into the consumer project. Writes are staged and existing files require explicit overwrite. Duplicate slugs fail closed until the caller selects an owner package.',
+    "Resolves a theme from the CLI bundle or an installed integration and copies it into the consumer project: a bundled theme's source files, or an integration theme's complete directory with its descriptor. Writes are staged and existing files require explicit overwrite. Duplicate slugs fail closed until the caller selects an owner package.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeAdd(slug: string, options?: {targetPath?: string, overwrite?: boolean, cwd?: string, package?: string}): Promise<ThemeAddResponse>',
@@ -43,6 +44,7 @@ export const doc = {
       type: 'string',
       description:
         'Project directory used for integration discovery and target paths.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.package',
@@ -56,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: [
     {
@@ -70,10 +67,13 @@ export const doc = {
     {code: 'ERR_AMBIGUOUS_THEME', when: 'more than one package owns the slug'},
     {
       code: 'ERR_THEME_INVALID',
-      when: 'the selected installed package has a blocking integration or theme-catalog error',
+      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 catalog-listed source file 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',
@@ -81,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

@@ -12,15 +12,15 @@ export const doc = {
   type: 'function',
   kind: 'api',
   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',
@@ -47,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',
@@ -60,25 +60,26 @@ 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: [
     {
       type: 'theme.build',
       description:
-        'Build receipt: theme name, token- and component-override counts, output size in KB, the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}, and validation warnings—including exact canonical replacements for deprecated component target keys. Resolves to null instead when the theme produced no CSS (nothing to build).',
+        'Build receipt {name, tokenCount, componentCount, sizeKB, outputs, warnings, notices}: the theme name; how many tokens (portable plus theme-local) and component targets it overrides; the CSS size in KB; the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}; warnings, the defects the author should fix, including exact canonical replacements for deprecated component target keys and declarations the generator dropped; and notices, advisories about a correct theme, such as a font it names but does not load. Resolves to null instead when the theme produced no CSS (nothing to build).',
     },
     {
       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: [
@@ -87,10 +88,13 @@ export const doc = {
       code: 'ERR_THEME_LOAD',
       when: 'the file cannot be loaded or parsed into a defineTheme() result',
     },
-    {code: 'ERR_THEME_INVALID', when: 'the resolved theme has no name'},
+    {
+      code: 'ERR_THEME_INVALID',
+      when: 'the resolved theme is invalid, for example it has no name, or a custom Heading type has no standalone rule with a declaration the compiler can emit',
+    },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the theme name contains a path separator or traversal marker',
+      when: 'the theme name contains a path separator or traversal marker, or a relative `out` path resolves outside cwd (including through a symlink)',
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
@@ -98,11 +102,11 @@ 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',
-      when: 'writing the outputs fails (staged temp files are rolled back)',
+      when: 'creating the output directory or writing the outputs fails (staged temp files are rolled back)',
     },
   ],
   examples: [
@@ -120,5 +124,5 @@ export const doc = {
     },
   ],
   command: 'theme build',
-  related: ['themeAdd', 'themeList', 'listThemes'],
+  related: ['themeTemplate', 'themeAdd', 'themeListAvailable', 'listThemes'],
 };

package/api/theme/themeList.doc.mjs

@@ -9,10 +9,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeList',
+  namespace: 'cli/api',
   displayName: 'themeList()',
   summary: 'List themes bundled with this CLI build.',
   description:
-    'Projects the bundled-theme manifest 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'],
@@ -27,9 +28,11 @@ export const doc = {
   throws: [
     {
       code: 'ERR_NO_SOURCE',
-      when: 'the bundled-theme manifest cannot be read or parsed',
+      when: 'the bundled theme descriptors cannot be read or parsed',
     },
   ],
-  examples: [{label: 'List bundled themes', code: 'const {data} = themeList();'}],
+  examples: [
+    {label: 'List bundled themes', code: 'const {data} = themeList();'},
+  ],
   related: ['themeListAvailable', 'themeAdd', 'listThemes'],
 };

package/api/theme/themeListAvailable.doc.mjs

@@ -9,10 +9,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeListAvailable',
+  namespace: 'cli/api',
   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 catalog.',
+    '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>',
@@ -21,7 +22,9 @@ export const doc = {
     {
       name: 'options.cwd',
       type: 'string',
-      description: 'Project directory whose installed integrations contribute themes.',
+      description:
+        'Project directory whose installed integrations contribute themes.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.package',
@@ -39,7 +42,7 @@ export const doc = {
   throws: [
     {
       code: 'ERR_NO_SOURCE',
-      when: 'the CLI bundled-theme manifest cannot be read or parsed',
+      when: 'the CLI bundled-theme descriptors cannot be read or parsed',
     },
   ],
   examples: [

package/api/theme/themePaletteGenerate.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themePaletteGenerate',
+  namespace: 'cli/api',
   displayName: 'themePaletteGenerate()',
   summary: 'Generate an author-reviewable palette candidate from JSON input.',
   description:
@@ -26,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: [
@@ -63,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');",
     },
     {
@@ -82,5 +90,5 @@ export const doc = {
     },
   ],
   command: 'theme palette generate',
-  related: ['themeBuild', 'themeTemplate'],
+  related: ['generateTonalPalette', 'themeBuild', 'themeTemplate'],
 };

package/api/theme/themeTargets.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeTargets',
+  namespace: 'cli/api',
   displayName: 'themeTargets()',
   summary: 'List every component theming target a theme can override.',
   description:
@@ -21,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>',
@@ -40,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

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeTemplate',
+  namespace: 'cli/api',
   displayName: 'themeTemplate()',
   summary: 'Write the annotated theme template into a project.',
   description:
@@ -23,7 +24,7 @@ export const doc = {
     '`overwrite`, so it is safe to re-run.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'themeTemplate(options?: {targetPath?: string, overwrite?: boolean, cwd?: string}): ThemeNewResponse',
+    'themeTemplate(options?: {targetPath?: string, overwrite?: boolean, cwd?: string}): ThemeTemplateResponse',
   keywords: ['theme', 'template', 'starter', 'defineTheme', 'scaffold', 'reference', 'tokens'],
   params: [
     {
@@ -42,6 +43,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory the target path resolves against.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -51,7 +53,10 @@ export const doc = {
         'Receipt: 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, not a failure.',
     },
   ],
-  throws: [{code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'}],
+  throws: [
+    {code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
+    {code: 'ERR_WRITE_FAILED', when: 'the template file cannot be written'},
+  ],
   examples: [
     {label: 'Write it at the project root', code: 'themeTemplate();'},
     {
@@ -60,5 +65,5 @@ export const doc = {
     },
   ],
   command: 'theme template',
-  related: ['themeAdd', 'themeBuild', 'themeList'],
+  related: ['themeAdd', 'themeBuild', 'themeListAvailable', 'themeTargets'],
 };

package/api/upgrade/_adapter.d.mts

@@ -104,18 +104,27 @@ export function ensureCodemodDeps({ installDeps }?: {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
  */
-export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods }: {
+export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent }: {
     apply: boolean;
     path: string;
     codemod?: string;
     skipCodemods: Set<string>;
+    root?: string;
+    protection?: {
+        root: string;
+        classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
+    };
+    silent?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;
     totalValidationBlocked: number;
+    changedFiles: string[];
     writtenFiles: string[];
+    stagedContents: Map<string, string>;
+    protectedFiles: import("../../authoring/codemod/type").CodemodRunResult["protectedFiles"];
     errors: Array<{
         file: string;
         codemod: string;
@@ -139,13 +148,21 @@ export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply
 /**
  * Load the consumer project's config + integrations. Throws on invalid config;
  * the run leaf decides between the config_fixable preview and a hard abort.
+ *
+ * Provider identity is resolved by the same resolver Project uses, on top of
+ * Project's ledger, under the codemod policy: a package that lists itself runs
+ * its installed copy's released codemods, never the work in progress being
+ * authored, and autolinked and local packages claim provider IDs without
+ * running codemods.
+ *
  * @param {string} cwd
  * @param {string[]} [extraIntegrationSpecs] explicit `--integration` specs
- * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]}>}
+ * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[], ledger: import('../../foundation/integrations/provider-resolution.mjs').ProviderLedger}>}
  */
 export function loadProjectContext(cwd: string, extraIntegrationSpecs?: string[]): Promise<{
     postCodemodHooks: import("../../authoring/config/type").PostCodemodHook[];
     integrations: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[];
+    ledger: import("../../foundation/integrations/provider-resolution.mjs").ProviderLedger;
 }>;
 /**
  * Non-blocking nudge for integration validation issues. Never throws (a broken
@@ -171,20 +188,30 @@ export function selectIntegrationCodemodsFor(integrations: Array<import("../../f
 /**
  * Run the file-based INTEGRATION codemods (config codemods first, then code).
  * @param {Array<{version: string, codemods: import('../../authoring/codemod/type').CodemodEntry[]}>} versionGroups
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>, silent?: boolean}} options
  */
 export function runIntegrationCodemodsStep(versionGroups: Array<{
     version: string;
     codemods: import("../../authoring/codemod/type").CodemodEntry[];
-}>, { apply, path: srcPath, codemod, skipCodemods }: {
+}>, { apply, path: srcPath, codemod, skipCodemods, root, protection, contents, silent, }: {
     apply: boolean;
     path: string;
     codemod?: string;
     skipCodemods: Set<string>;
+    root?: string;
+    protection?: {
+        root: string;
+        classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
+    };
+    contents?: Map<string, string>;
+    silent?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;
+    changedFiles: string[];
     writtenFiles: string[];
+    stagedContents: Map<string, string>;
+    protectedFiles: import("../../authoring/codemod/type").CodemodRunResult["protectedFiles"];
     errors: Array<{
         file: string;
         codemod: string;