@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/api/theme/theme.type.mjs

@@ -6,23 +6,23 @@
  * directly (functions own their types); the public `@astryxdesign/cli/api`
  * surface re-exports them via types/theme.d.ts, so consumers see the same names.
  *
- * Invocation                                 -> type discriminator
+ * Invocation                                  -> type discriminator
  * ------------------------------------------------------------------
- * xds --json theme build <file>             -> theme.build
- * xds --json theme build <file> --check     -> theme.build.check
- * xds --json theme build <a> <b> …          -> theme.build.batch
- * xds --json theme list                     -> theme.list
- * xds --json theme add <slug>               -> theme.add
- * xds --json theme template                 -> theme.template
- * xds --json theme targets [filter]         -> theme.targets
- * xds --json theme palette generate <file>  -> theme.palette.generate
- * (file not found / parse error)            -> CLIError
+ * astryx --json theme build <file>            -> theme.build
+ * astryx --json theme build <file> --check    -> theme.build.check
+ * astryx --json theme build <a> <b> …         -> theme.build.batch
+ * astryx --json theme list                    -> theme.list
+ * astryx --json theme add <slug>              -> theme.add
+ * astryx --json theme template                -> theme.template
+ * astryx --json theme targets [filter]        -> theme.targets
+ * astryx --json theme palette generate <file> -> theme.palette.generate
+ * (file not found / parse error)              -> CLIError
  *
  * @position api — colocated typedefs for api/theme/{theme,build,add,list,template,targets,_adapter}
  */
 
 /**
- * xds --json theme build <file>
+ * astryx --json theme build <file>
  * @typedef {object} ThemeBuildResponse
  * @property {'theme.build'} type
  * `warnings` are defects the theme author should fix. `notices` are advisories
@@ -32,14 +32,14 @@
  */
 
 /**
- * xds --json theme build <file> --check
+ * astryx --json theme build <file> --check
  * @typedef {object} ThemeBuildCheckResponse
  * @property {'theme.build.check'} type
  * @property {{name: string, upToDate: boolean, stale: Array<{path: string, reason: 'missing' | 'outdated'}>, checked: string[]}} data
  */
 
 /**
- * xds --json theme build <a> <b> … — several themes in one invocation. Each
+ * astryx --json theme build <a> <b> … — several themes in one invocation. Each
  * result carries the file as it was passed and the receipt a single-file build
  * would have returned (null when that theme produced no CSS). One file still
  * returns the bare theme.build / theme.build.check envelope.
@@ -59,21 +59,21 @@
  */
 
 /**
- * xds --json theme list
+ * astryx --json theme list
  * @typedef {object} ThemeListResponse
  * @property {'theme.list'} type
  * @property {ThemeListEntry[]} data
  */
 
 /**
- * xds --json theme add <slug>
+ * astryx --json theme add <slug>
  * @typedef {object} ThemeAddResponse
  * @property {'theme.add'} type
  * @property {{slug: string, displayName: string, maintained: boolean, package: string, outputDir: string, entry: string, exportName: string, files: string[]}} data
  */
 
 /**
- * xds --json theme template
+ * astryx --json theme template
  * `written: false` with `reason: 'exists'` is a success: the command is safe to
  * re-run, and an edited template is the consumer's file to keep.
  * @typedef {object} ThemeTemplateResponse
@@ -95,19 +95,19 @@
  */
 
 /**
- * xds --json theme targets [filter]
+ * astryx --json theme targets [filter]
  * @typedef {object} ThemeTargetsResponse
  * @property {'theme.targets'} type
  * @property {{filter: string | null, componentCount: number, targets: ThemeTargetEntry[]}} data
  */
 
 /**
- * A generated palette candidate. The palette is still subject to author review
- * and is not connected to runtime theme values.
+ * A color an author pins at one stop of one mode, constraining generation.
  * @typedef {object} TonalPaletteAnchor
  * @property {'light' | 'dark'} mode Mode containing the anchored stop.
  * @property {number} stop Existing requested stop where the anchor applies.
- * @property {string} color
+ * @property {string} color sRGB hex the stop is pulled toward: three or six
+ * digits, with or without `#`; the generator normalizes it.
  * @property {'exact' | 'bounded' | 'flexible'} policy `exact` preserves the
  * chosen color at that stop; `bounded` permits adjustment within `maxDeltaE`;
  * `flexible` treats the color as guidance and blends toward it.
@@ -116,12 +116,16 @@
  */
 
 /**
+ * One requested family: a seed color and the constraints applied to its ramp.
  * @typedef {object} TonalPaletteFamilyInput
- * @property {string} id
- * @property {string} seed
- * @property {string} [name]
- * @property {'chromatic' | 'neutral'} [kind]
- * @property {TonalPaletteAnchor[]} [anchors]
+ * @property {string} id Lower-kebab-case key for the family in the generated
+ * palette. `black` and `white` are reserved for the standalone values.
+ * @property {string} seed sRGB hex the ramp is generated from: three or six
+ * digits, with or without `#`; the generator normalizes it.
+ * @property {string} [name] Display name for review artifacts; defaults to `id`.
+ * @property {'chromatic' | 'neutral'} [kind] `neutral` derives the ramp from
+ * `neutralProfile` instead of the seed hue; defaults to `chromatic`.
+ * @property {TonalPaletteAnchor[]} [anchors] Colors pinned at specific stops.
  */
 
 /**
@@ -130,6 +134,9 @@
  * @property {number} [vibrancy] Chroma control from 0 (most muted) through 50
  * (default) to 100 (most vivid).
  * @property {'neutral-v1' | 'warm-v1' | 'cool-v1' | 'custom'} [neutralProfile]
+ * Hue treatment for `neutral` families: `neutral-v1` is fully achromatic,
+ * `warm-v1` and `cool-v1` add a slight tint, and `custom` derives the hue from
+ * the family's own seed. Defaults to `neutral-v1`.
  * @property {'light-only' | 'dark-only' | 'light-and-dark'} [modeStrategy]
  * @property {number[]} [stops] Ordered stops shared by every requested family;
  * defaults to 0 through 100 in increments of 5. Decimal stops are supported,
@@ -137,6 +144,8 @@
  */
 
 /**
+ * A generated palette candidate. The palette is still subject to author review
+ * and is not connected to runtime theme values.
  * @typedef {object} TonalPaletteCandidate
  * @property {1} schemaVersion
  * @property {'candidate'} status
@@ -148,10 +157,68 @@
  */
 
 /**
- * xds --json theme palette generate <config>
+ * Per-ramp evidence recorded for one family in one mode.
+ * @typedef {object} TonalPaletteRampDiagnostics
+ * @property {boolean} monotonic Whether luminance rises across every stop.
+ * @property {number} minimumAdjacentDeltaE Smallest perceptual gap between
+ * neighboring stops; a small value means two stops read as one color.
+ * @property {number} maximumAdjacentDeltaE Largest gap between neighboring stops.
+ * @property {number} maximumHueDrift Largest hue distance, in degrees, between
+ * a stop and the family's reference hue.
+ * @property {'blue-to-purple' | 'yellow-to-brown' | null} hueIdentityRisk Named
+ * drift the ramp is at risk of, or `null`.
+ * @property {number[]} gamutMappedStops Stops whose ideal color fell outside
+ * sRGB and was mapped back into it.
+ * @property {Array<TonalPaletteAnchor & {generatedColor: string, deltaE: number}>} anchors
+ * Each anchor with the color the stop received after its policy was applied
+ * and the perceptual distance that color still has from the requested target.
+ */
+
+/**
+ * Cross-family evidence for one mode, sampled at the stop nearest 50.
+ * @typedef {object} TonalPaletteCoordinationDiagnostics
+ * @property {'light' | 'dark'} mode Mode these samples come from.
+ * @property {number} stop Sampled stop.
+ * @property {[string, string] | null} closestFamilies The two chromatic
+ * families hardest to tell apart, or `null` with fewer than two.
+ * @property {number | null} minimumFamilyDeltaE Perceptual distance between them.
+ * @property {string | null} strongestFamily Most saturated family at this stop.
+ * @property {string | null} weakestFamily Least saturated family at this stop.
+ * @property {number | null} chromaRatio Strongest chroma over weakest; a large
+ * ratio means the families are unbalanced.
+ */
+
+/**
+ * The request as the generator resolved it, with every default filled in.
+ * @typedef {object} TonalPaletteNormalizedRequest
+ * @property {'astryx-oklch-v1'} recipe
+ * @property {number} vibrancy
+ * @property {'neutral-v1' | 'warm-v1' | 'cool-v1' | 'custom'} neutralProfile
+ * @property {'light-only' | 'dark-only' | 'light-and-dark'} modeStrategy
+ * @property {number[]} stops
+ * @property {Array<{id: string, name: string, seed: string, kind: 'chromatic' | 'neutral', anchors: TonalPaletteAnchor[]}>} families
+ */
+
+/**
+ * The detached receipt written beside a candidate. It records what was asked
+ * for and what the generator observed, so a candidate can be traced back to
+ * its request without rerunning generation.
+ * @typedef {object} TonalPaletteGenerationReceipt
+ * @property {1} schemaVersion
+ * @property {'astryx-oklch-v1'} recipe Recipe that produced the candidate.
+ * @property {string} candidateSha256 SHA-256 over the candidate bytes as written.
+ * @property {{version: string, sha256: string}} [preview] Present when preview
+ * content was generated for the request, even if no file was written because
+ * the target already exists.
+ * @property {TonalPaletteNormalizedRequest} request
+ * @property {{families: Record<string, {light?: TonalPaletteRampDiagnostics, dark?: TonalPaletteRampDiagnostics}>, coordination: TonalPaletteCoordinationDiagnostics[]}} diagnostics
+ */
+
+/**
+ * astryx --json theme palette generate <config>
  * @typedef {object} ThemePaletteGenerateResponse
  * @property {'theme.palette.generate'} type
- * @property {{recipe: 'astryx-oklch-v1', status: 'candidate', familyCount: number, stopCount: number, modes: string[], output: string | null, receipt: string | null, preview: string | null, written: boolean, reason: 'exists' | null, candidate: TonalPaletteCandidate, generationReceipt: Record<string, unknown>}} data
+ * @property {{recipe: 'astryx-oklch-v1', status: 'candidate', familyCount: number, stopCount: number, modes: string[], output: string | null, receipt: string | null, preview: string | null, written: boolean, reason: 'exists' | null, candidate: TonalPaletteCandidate, generationReceipt: TonalPaletteGenerationReceipt}} data
  */
 
 // Make this a module so the @typedefs above are importable as types via

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>',
@@ -70,10 +71,10 @@ 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: 'a theme file to copy is missing'},
     {
       code: 'ERR_FILE_EXISTS',
       when: 'a destination exists and overwrite is not set',

package/api/theme/themeBuild.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'themeBuild',
+  namespace: 'cli/api',
   displayName: 'themeBuild()',
   summary: 'Compile a defineTheme file to CSS + JS + type declarations.',
   description:
@@ -73,7 +74,7 @@ export const doc = {
     {
       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',
@@ -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',
@@ -102,7 +106,7 @@ export const doc = {
     },
     {
       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: [

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.',
+    '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.',
   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.',
+    '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.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeListAvailable(options?: {cwd?: string, package?: string}): Promise<ThemeListResponse>',
@@ -21,7 +22,8 @@ export const doc = {
     {
       name: 'options.cwd',
       type: 'string',
-      description: 'Project directory whose installed integrations contribute themes.',
+      description:
+        'Project directory whose installed integrations contribute themes.',
     },
     {
       name: 'options.package',
@@ -39,7 +41,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:

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:

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: [
     {
@@ -51,7 +52,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();'},
     {

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;