@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/api/upgrade/upgrade.doc.mjs

@@ -11,19 +11,18 @@ export const doc = {
   type: 'function',
   kind: 'api',
   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 path, including same-Core ' +
-    'integration guidance changes. 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>',
@@ -40,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',
@@ -53,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',
@@ -68,7 +69,7 @@ export const doc = {
       name: 'options.integration',
       type: 'string[]',
       description:
-        'Explicit integration package names / file paths to process.',
+        'Explicit integration specifiers to process. Resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.',
     },
     {
       name: 'options.path',
@@ -79,24 +80,28 @@ export const doc = {
     {
       name: 'options.installDeps',
       type: 'boolean',
-      description: 'Auto-install jscodeshift without prompting.',
+      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: [
@@ -113,36 +118,40 @@ 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, the codemod count, integrations processed, the agent-docs summary, an optional copied-composition registry summary, and (apply mode) filesChanged, transformsApplied, and any per-codemod errors.',
+        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), 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',
+      when: 'a working-tree protection declaration cannot be read or parsed before writes begin',
     },
   ],
   examples: [

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

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json upgrade --list
+ * astryx --json upgrade --list
  */
 export type UpgradeListResponse = {
     type: "upgrade.list";
@@ -12,6 +12,10 @@ export type UpgradeListEntry = {
     name: string;
     title: string;
     version: string;
+    /**
+     * True when the codemod runs only if named with `--codemod`.
+     */
+    optional: boolean;
 };
 /**
  * State of the managed agent-docs block (`<!-- ASTRYX:START --> … END -->`)
@@ -121,14 +125,39 @@ export type RegistryCompositionSummary = {
     items: RegistryCompositionItemSummary[];
 };
 /**
- * xds --json upgrade --registry [--apply]
+ * astryx --json upgrade --registry [--apply]
  */
 export type UpgradeRegistryResponse = {
     type: "upgrade.registry";
     data: RegistryCompositionSummary;
 };
 /**
- * xds --json upgrade [--apply]
+ * A required codemod change blocked by effective working-tree protection.
+ */
+export type ProtectedCodemodFile = {
+    /**
+     * Project-relative path.
+     */
+    file: string;
+    /**
+     * Codemods that still require a change.
+     */
+    codemods: string[];
+    /**
+     * Protection categories (generated, vendored, ignored, and hard boundaries).
+     */
+    reasons: string[];
+    /**
+     * Effective declarations that protect the file.
+     */
+    declarations: string[];
+    /**
+     * Exact regeneration commands found in generated headers, when present.
+     */
+    commands: string[];
+};
+/**
+ * astryx --json upgrade [--apply]
  */
 export type UpgradeRunResponse = {
     type: "upgrade.run";
@@ -140,7 +169,16 @@ export type UpgradeRunResponse = {
         agentDocsRefreshed: boolean;
         agentDocs: AgentDocsSummary;
         registryCompositions?: RegistryCompositionSummary | undefined;
+        complete?: boolean | undefined;
+        errorCode?: "ERR_CODEMOD_PROTECTED" | undefined;
         filesChanged?: number | undefined;
+        modifiedFiles?: string[] | undefined;
+        protectedFiles?: ProtectedCodemodFile[] | undefined;
+        declinedCandidates?: {
+            file: string;
+            location?: string;
+            reason: string;
+        }[] | undefined;
         transformsApplied?: number | undefined;
         errors?: {
             file: string;
@@ -150,7 +188,7 @@ export type UpgradeRunResponse = {
     };
 };
 /**
- * xds --json upgrade — short-circuit status results.
+ * astryx --json upgrade — short-circuit status results.
  *
  * - `up_to_date`: `--from` is >= installed target and `--force` was not passed.
  * - `no_codemods`: no codemods (core or integration) apply to the range.
@@ -211,7 +249,7 @@ export type UpgradeOptions = {
      */
     skipCodemod?: string[] | undefined;
     /**
-     * Explicit integration package names / file paths.
+     * Explicit integration specifiers resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.
      */
     integration?: string[] | undefined;
     /**

package/api/upgrade/upgrade.type.mjs

@@ -4,17 +4,17 @@
  * @file Colocated types for the `upgrade` command — source of truth for the
  * upgrade command JSON responses. Re-exported by `types/upgrade.d.ts`.
  *
- * Invocation                                 -> type discriminator
+ * Invocation                                   -> type discriminator
  * ------------------------------------------------------------------
- * xds --json upgrade --list                 -> upgrade.list
- * xds --json upgrade [--apply]              -> upgrade.run
- * xds --json upgrade --registry [--apply]   -> upgrade.registry
- * xds --json upgrade (status short-circuit) -> upgrade.status
- * (version detection failure)               -> CLIError
+ * astryx --json upgrade --list                 -> upgrade.list
+ * astryx --json upgrade [--apply]              -> upgrade.run
+ * astryx --json upgrade --registry [--apply]   -> upgrade.registry
+ * astryx --json upgrade (status short-circuit) -> upgrade.status
+ * (version detection failure)                  -> CLIError
  */
 
 /**
- * xds --json upgrade --list
+ * astryx --json upgrade --list
  * @typedef {object} UpgradeListResponse
  * @property {'upgrade.list'} type
  * @property {UpgradeListEntry[]} data
@@ -25,6 +25,7 @@
  * @property {string} name
  * @property {string} title
  * @property {string} version
+ * @property {boolean} optional True when the codemod runs only if named with `--codemod`.
  */
 
 /**
@@ -88,14 +89,24 @@
  */
 
 /**
- * xds --json upgrade --registry [--apply]
+ * astryx --json upgrade --registry [--apply]
  * @typedef {object} UpgradeRegistryResponse
  * @property {'upgrade.registry'} type
  * @property {RegistryCompositionSummary} data
  */
 
 /**
- * xds --json upgrade [--apply]
+ * A required codemod change blocked by effective working-tree protection.
+ * @typedef {object} ProtectedCodemodFile
+ * @property {string} file Project-relative path.
+ * @property {string[]} codemods Codemods that still require a change.
+ * @property {string[]} reasons Protection categories (generated, vendored, ignored, and hard boundaries).
+ * @property {string[]} declarations Effective declarations that protect the file.
+ * @property {string[]} commands Exact regeneration commands found in generated headers, when present.
+ */
+
+/**
+ * astryx --json upgrade [--apply]
  * @typedef {object} UpgradeRunResponse
  * @property {'upgrade.run'} type
  * @property {object} data
@@ -106,13 +117,18 @@
  * @property {boolean} data.agentDocsRefreshed
  * @property {AgentDocsSummary} data.agentDocs
  * @property {RegistryCompositionSummary} [data.registryCompositions]
- * @property {number} [data.filesChanged] Total files changed across core + integration codemods (apply mode).
- * @property {number} [data.transformsApplied] Total transforms that reported a change.
+ * @property {boolean} [data.complete] False when protected required changes remain.
+ * @property {'ERR_CODEMOD_PROTECTED'} [data.errorCode] Stable incomplete-result code when complete is false.
+ * @property {number} [data.filesChanged] Distinct files changed across core + integration codemods (apply mode). One file that four codemods each changed counts once.
+ * @property {string[]} [data.modifiedFiles] Project-relative files changed or previewed.
+ * @property {ProtectedCodemodFile[]} [data.protectedFiles] Protected files that still require a codemod change after regeneration.
+ * @property {Array<{file: string, location?: string, reason: string}>} [data.declinedCandidates] Candidates left unchanged because proof was insufficient.
+ * @property {number} [data.transformsApplied] Total codemod changes. A code or config codemod counts once for each file it changed, so one file changed by four of them counts four times; a project codemod counts once, however many files it writes.
  * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed.
  */
 
 /**
- * xds --json upgrade — short-circuit status results.
+ * astryx --json upgrade — short-circuit status results.
  *
  * - `up_to_date`: `--from` is >= installed target and `--force` was not passed.
  * - `no_codemods`: no codemods (core or integration) apply to the range.
@@ -135,7 +151,7 @@
  * @property {boolean} [force] Run codemods even if `from` >= installed.
  * @property {string} [codemod] Run a single named transform.
  * @property {string[]} [skipCodemod] Exclude named codemods (re-run past a failure).
- * @property {string[]} [integration] Explicit integration package names / file paths.
+ * @property {string[]} [integration] Explicit integration specifiers resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.
  * @property {string} [path] Source directory to scan (default `./src`).
  * @property {boolean} [installDeps] Auto-install jscodeshift without prompting.
  * @property {boolean} [registry] Reconcile only ShadCN-copied compositions; `from` is not required.

package/assets/codemods/__tests__/registry.test.mjs

@@ -28,6 +28,7 @@ describe('registry', () => {
         '0.4.0',
         '0.5.0',
         '0.6.0',
+        '0.6.4',
       ]);
     });
   });