@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/api/theme/listThemes.doc.mjs

@@ -9,25 +9,26 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'listThemes',
+  namespace: 'cli/api',
   displayName: 'listThemes()',
-  summary: 'Read the CLI bundled-theme manifest.',
+  summary: 'Read the CLI bundled-theme descriptors.',
   description:
-    'Reads templates/themes/manifest.json and returns its raw entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
+    'Reads the typed same-stem descriptors under templates/themes and returns normalized entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
   importPath: '@astryxdesign/cli/api',
   signature: 'listThemes(): BundledTheme[]',
-  keywords: ['theme', 'themes', 'manifest', 'bundled', 'adapter', 'list'],
+  keywords: ['theme', 'themes', 'descriptor', 'bundled', 'adapter', 'list'],
   params: [],
   returns: [
     {
       type: 'BundledTheme[]',
       description:
-        'The bundled manifest entries: slug, displayName, description, maintained, entry, exportName, and files.',
+        'The normalized bundled descriptor entries: slug, displayName, description, maintained, entry, exportName, and files.',
     },
   ],
   throws: [
     {
       code: 'ERR_NO_SOURCE',
-      when: 'the bundled catalog is missing, invalid, or references missing source files',
+      when: 'the bundled descriptors are missing, invalid, or have missing source files',
     },
   ],
   examples: [

package/api/theme/template/template.test.mjs

@@ -13,6 +13,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import {themeTemplate as publicThemeTemplate} from '../../index.mjs';
 import {themeTemplate, THEME_TEMPLATE_DEFAULT_PATH} from './template.mjs';
 import {isErrorCode} from '../../../foundation/response/error-codes.mjs';
 
@@ -25,6 +26,10 @@ afterEach(() => {
 });
 
 describe('themeTemplate()', () => {
+  it('is available through the public API entry point', () => {
+    expect(publicThemeTemplate).toBe(themeTemplate);
+  });
+
   it('writes the template and returns a theme.template receipt', () => {
     const res = themeTemplate({cwd: tmpDir});
 

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:

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: [
     {

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;

package/api/upgrade/_adapter.mjs

@@ -19,7 +19,10 @@ import * as path from 'node:path';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 import {ensureJscodeshift} from '../../assets/codemods/ensure-jscodeshift.mjs';
-import {getTransformsBetween, latestVersion} from '../../assets/codemods/registry.mjs';
+import {
+  getTransformsBetween,
+  latestVersion,
+} from '../../assets/codemods/registry.mjs';
 import {runCodemods} from '../../assets/codemods/runner.mjs';
 import {
   discoverIntegrationCodemods,
@@ -32,17 +35,15 @@ import {
   renderAgentDocsBlock,
 } from '../../foundation/agent-docs/agent-docs.mjs';
 import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
-import {Project} from '../../foundation/config/project.mjs';
-import {
-  loadIntegrations,
-  markProviderConflicts,
-} from '../../foundation/integrations/integrations.mjs';
+import {Project, providerLedgerOf} from '../../foundation/config/project.mjs';
+import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
+import {resolveProviders} from '../../foundation/integrations/provider-resolution.mjs';
 import {warnOnIntegrationIssues} from '../../foundation/integrations/integration-warnings.mjs';
 import {logger} from '../logger.mjs';
 
 // Re-exported for the run leaf's lightweight agent-docs inspection path
 // (config_fixable short-circuit, where the full render cannot load config).
-export { inspectAgentDocs };
+export {inspectAgentDocs};
 
 const execFileAsync = promisify(execFile);
 
@@ -291,7 +292,13 @@ export async function collectAllCodemods() {
   );
   for (const {version, transforms} of manifests) {
     for (const {name, meta, optional} of transforms) {
-      codemods.push({name, title: meta.title, version, pr: meta.pr, optional: !!optional});
+      codemods.push({
+        name,
+        title: meta.title,
+        version,
+        pr: meta.pr,
+        optional: !!optional,
+      });
     }
   }
   return codemods;
@@ -322,33 +329,36 @@ export async 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 async function runCoreCodemods(versionManifests, {apply, path: srcPath, codemod, skipCodemods}) {
+export async function runCoreCodemods(
+  versionManifests,
+  {apply, path: srcPath, codemod, skipCodemods, root, protection, silent},
+) {
   return runCodemods(versionManifests, {
     apply,
     path: srcPath,
     codemod,
     skipCodemods,
-    silent: logger.silent,
+    silent: silent ?? logger.silent,
+    root,
+    protection,
   });
 }
 
-/**
- * One installed package at one version; two specs that reach it share this.
- * @param {{name: string, version?: string}} integration
- * @returns {string}
- */
-function packageIdentity(integration) {
-  return `${integration.name}\u0000${integration.version ?? ''}`;
-}
-
 /**
  * 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 async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // The CLI debug preflight may already have imported this config before core
@@ -360,23 +370,38 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // Configured packages come from Project, which has already resolved provider
   // identity over configured, autolinked, and local packages. Loading them
   // again here would let upgrade run codemods from a package Project set aside.
-  const configured = project.loadedIntegrations.filter(
-    integration =>
-      !integration.__autolinked && configuredSpecs.has(integration.__spec),
-  );
+  // Autolinked packages and the package being authored join only as claimants:
+  // every other command uses them for their provider IDs, but upgrade has
+  // never run their codemods.
+  const candidates = project.loadedIntegrations.flatMap(integration => {
+    const source =
+      !integration.__autolinked && configuredSpecs.has(integration.__spec)
+        ? /** @type {const} */ ('configured')
+        : integration.__autolinked
+          ? /** @type {const} */ ('autolinked')
+          : integration.__local
+            ? /** @type {const} */ ('local')
+            : null;
+    return source == null
+      ? []
+      : [{source, integration, spec: integration.__spec}];
+  });
   // A package that lists itself runs its installed copy's released codemods,
-  // never the work in progress being authored, so that copy stands in for it.
+  // never the work in progress being authored; the resolver puts that copy in
+  // its place. Naming the package being authored with --integration asks for
+  // the installed copy too.
   const local = project.loadedIntegrations.find(
     integration => integration.__local,
   );
-  const selfListed = local != null && configured.includes(local);
-  if (local != null && selfListed && project.configPath) {
-    const installed = await loadIntegrations([local.__spec], {
-      cwd: path.dirname(project.configPath),
-      resolveProviders: false,
-    });
-    configured.splice(configured.indexOf(local), 1, ...installed);
-  }
+  const selfListed =
+    local != null && !local.__autolinked && configuredSpecs.has(local.__spec);
+  const installed =
+    local != null && selfListed && project.configPath
+      ? await loadIntegrations([local.__spec], {
+          cwd: path.dirname(project.configPath),
+          resolveProviders: false,
+        })
+      : [];
   const extraSpecs = uniqueFiles(extraIntegrationSpecs ?? []).filter(
     spec => !configuredSpecs.has(spec),
   );
@@ -384,38 +409,23 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
     extraSpecs.length === 0
       ? []
       : await loadIntegrations(extraSpecs, {resolveProviders: false});
-  // Naming the package being authored with --integration asks for its
-  // installed copy too, so the local package must not claim against it.
-  const localStandsIn =
-    local != null &&
-    (selfListed || extras.some(extra => extra.name === local.name));
-  // Autolinked packages and the package being authored join the pass only as
-  // claimants: every other command uses them for their provider IDs, but
-  // upgrade has never run their codemods and still does not. An extra that
-  // names one of them opts it in, so the extra stands in for that claimant.
-  const extraIdentities = new Set(extras.map(packageIdentity));
-  const claimantsOnly = project.loadedIntegrations.filter(
-    integration =>
-      (integration.__autolinked || (integration.__local && !localStandsIn)) &&
-      !extraIdentities.has(packageIdentity(integration)),
-  );
-  const resolved = markProviderConflicts([
-    ...configured,
-    ...claimantsOnly,
-    ...extras,
-  ]);
-  // Claimants leave by package directory, not object identity: the pass can
-  // return one as a new conflict entry, and upgrade must not warn that a
-  // package every other command uses contributes nothing.
-  const claimantDirs = new Set(
-    claimantsOnly.map(integration => integration.__packageDir),
+  const {integrations, ledger} = resolveProviders(
+    [
+      ...candidates,
+      ...installed.map(integration => ({
+        source: /** @type {const} */ ('installed'),
+        integration,
+        spec: integration.__spec,
+      })),
+      ...extras.map(integration => ({
+        source: /** @type {const} */ ('extra'),
+        integration,
+        spec: integration.__spec,
+      })),
+    ],
+    {codemods: true, prior: providerLedgerOf(project)},
   );
-  const integrations = resolved.filter(
-    integration =>
-      integration.__packageDir == null ||
-      !claimantDirs.has(integration.__packageDir),
-  );
-  return {postCodemodHooks, integrations};
+  return {postCodemodHooks, integrations, ledger};
 }
 
 /**
@@ -450,7 +460,10 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {
     try {
       const byVersion = await discoverIntegrationCodemods([integration]);
       for (const [version, rawList] of byVersion) {
-        const list = /** @type {Array<import('../../authoring/codemod/type').CodemodEntry>} */ (/** @type {unknown} */ (rawList));
+        const list =
+          /** @type {Array<import('../../authoring/codemod/type').CodemodEntry>} */ (
+            /** @type {unknown} */ (rawList)
+          );
         const existing = integrationCodemodsByVersion.get(version);
         if (existing) existing.push(...list);
         else integrationCodemodsByVersion.set(version, [...list]);
@@ -467,9 +480,21 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {
 /**
  * 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 async function runIntegrationCodemodsStep(versionGroups, {apply, path: srcPath, codemod, skipCodemods}) {
+export async function runIntegrationCodemodsStep(
+  versionGroups,
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    root,
+    protection,
+    contents,
+    silent,
+  },
+) {
   const jscodeshift = (await import('jscodeshift')).default;
   return runIntegrationCodemods(versionGroups, {
     apply,
@@ -477,6 +502,9 @@ export async function runIntegrationCodemodsStep(versionGroups, {apply, path: sr
     codemod,
     skipCodemods,
     jscodeshift,
-    silent: logger.silent,
+    silent: silent ?? logger.silent,
+    root,
+    protection,
+    contents,
   });
 }