@astryxdesign/cli 0.1.8-canary.0c4d8d7 → 0.1.8-canary.0db5dfd

package/{src → cli}/commands/template.mjs

@@ -6,16 +6,44 @@
 
 import * as path from 'node:path';
 import * as fs from 'node:fs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {template as templateApi} from '../api/template.mjs';
-import {Project} from '../lib/project.mjs';
-import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
-import {getCliInvocation} from '../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {template as templateApi} from '../../api/template/template.mjs';
+import {Project} from '../../lib/project.mjs';
+import {warnOnIntegrationIssues} from '../../lib/integration-warnings.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
 
-export {discoverTemplates, listTemplates} from '../api/template.mjs';
+export {discoverTemplates, listTemplates} from '../../api/template/template.mjs';
 
+/**
+ * A template entry as produced by the discover* helpers in api/template.mjs.
+ * The api layer returns these as `object[]`; this local shape captures the
+ * fields the command consumes. Remove once api/template.mjs exports a precise
+ * type for its discovered templates.
+ * @typedef {object} DiscoveredTemplate
+ * @property {'page' | 'block'} type
+ * @property {string} dirName
+ * @property {string} name
+ * @property {string} filePath
+ */
+
+/**
+ * The discriminated response returned by the template API. The api layer
+ * currently declares `{type: string, data: unknown}`; narrow it here to the
+ * precise union so the switch below type-checks. Replace with the api's own
+ * return type once it is tightened.
+ * @typedef {(
+ *   import('../../types/template').TemplateListResponse |
+ *   import('../../types/template').TemplateShowResponse |
+ *   import('../../types/template').TemplateSkeletonResponse |
+ *   import('../../types/template').TemplateCopyResponse
+ * )} TemplateResponse
+ */
+
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerTemplate(program) {
   program
     .command('template [name] [path]')
@@ -25,7 +53,13 @@ export function registerTemplate(program) {
     .option('--package <pkg>', 'Narrow to templates from a specific package')
     .option('--skeleton', 'Show layout skeleton with spatial annotations (padding, gap, nesting)')
     .option('-f, --overwrite', 'Overwrite existing files without prompting')
-    .action(async (name, targetPath, options) => {
+    .action(
+      /**
+       * @param {string | undefined} name
+       * @param {string | undefined} targetPath
+       * @param {{list?: boolean, type?: string, package?: string, skeleton?: boolean, overwrite?: boolean}} options
+       */
+      async (name, targetPath, options) => {
       const json = program.opts().json || false;
       const run = getCliInvocation();
 
@@ -34,7 +68,12 @@ export function registerTemplate(program) {
       // validate-integration. Best-effort; suppressed in --json mode.
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+        await warnOnIntegrationIssues(
+          /** @type {Array<import('../../lib/integrations.mjs').LoadedIntegration>} */ (
+            project.loadedIntegrations
+          ),
+          {json},
+        );
       } catch {
         // Never let the nudge break the command.
       }
@@ -59,20 +98,24 @@ export function registerTemplate(program) {
         }
       }
 
+      /** @type {TemplateResponse} */
       let result;
       try {
-        result = await templateApi(name, {
-          list: options.list,
-          skeleton: options.skeleton,
-          type: options.type,
-          package: options.package,
-          targetPath,
-          cwd: process.cwd(),
-        });
+        result = /** @type {TemplateResponse} */ (
+          await templateApi(name, {
+            list: options.list,
+            skeleton: options.skeleton,
+            type: /** @type {'page' | 'block' | undefined} */ (options.type),
+            package: options.package,
+            targetPath,
+            cwd: process.cwd(),
+          })
+        );
       } catch (e) {
         // template API throws structured errors with {name, reason} suggestions —
         // pass them through untouched so the CLI envelope matches the API.
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
         return;
       }
 
@@ -82,6 +125,7 @@ export function registerTemplate(program) {
         case 'template.list': {
           const pages = result.data.filter(t => t.type === 'page');
           const blocks = result.data.filter(t => t.type === 'block');
+          /** @param {import('../../types/template').TemplateListEntry} t */
           const renderEntry = t => {
             const status = t.isReady ? '' : ' (WIP)';
             const pkg =
@@ -139,12 +183,19 @@ export function registerTemplate(program) {
  * Path-safety enforcement happens inside the API; here we only need
  * enough precision to check existence — a false negative just means the
  * API will catch the issue and abort.
+ *
+ * @param {string} name
+ * @param {string} targetPath
+ * @returns {Promise<string | null>}
  */
 async function detectTemplateCollision(name, targetPath) {
-  const {discoverTemplates} = await import('../api/template.mjs');
+  const {discoverTemplates} = await import('../../api/template/template.mjs');
+  /** @type {DiscoveredTemplate[]} */
   let templates;
   try {
-    templates = await discoverTemplates(process.cwd());
+    templates = /** @type {DiscoveredTemplate[]} */ (
+      await discoverTemplates(process.cwd())
+    );
   } catch {
     return null;
   }
@@ -157,7 +208,7 @@ async function detectTemplateCollision(name, targetPath) {
   const resolved = path.resolve(process.cwd(), targetPath);
 
   // File-arg branch: targetPath looks like `./foo.tsx`.
-  const {isFilePathArg} = await import('../utils/path-safety.mjs');
+  const {isFilePathArg} = await import('../../utils/path-safety.mjs');
   let dest;
   if (isFilePathArg(targetPath)) {
     dest = resolved;

package/{src → cli}/commands/template.path-safety.test.mjs

@@ -18,7 +18,7 @@ let templateApi;
 
 beforeEach(async () => {
   tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-paths-'));
-  templateApi = (await import('../api/template.mjs')).template;
+  templateApi = (await import('../../api/template/template.mjs')).template;
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
@@ -57,7 +57,7 @@ describe('template path safety', () => {
     fs.mkdirSync(cwd, {recursive: true});
 
     // Use a real template name from the discovered set.
-    const {discoverTemplates} = await import('../api/template.mjs');
+    const {discoverTemplates} = await import('../../api/template/template.mjs');
     const all = await discoverTemplates();
     const page = all.find(t => t.type === 'page');
     if (!page) {

package/{src → cli}/commands/upgrade.integration-policy.test.mjs

@@ -26,7 +26,7 @@ let errCalls;
 let exitCode;
 
 const codemodModuleUrl = pathToFileURL(
-  path.resolve(process.cwd(), 'packages/cli/src/codemod.mjs'),
+  path.resolve(process.cwd(), 'packages/cli/authoring/codemod.mjs'),
 ).href;
 
 beforeEach(() => {

package/{src → cli}/commands/upgrade.mjs

@@ -40,23 +40,23 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
-import * as p from '../lib/term-log.mjs';
-import {ensureJscodeshift} from '../codemods/ensure-jscodeshift.mjs';
-import {getTransformsBetween, latestVersion} from '../codemods/registry.mjs';
-import {runCodemods} from '../codemods/runner.mjs';
+import * as p from '../../lib/term-log.mjs';
+import {ensureJscodeshift} from '../../codemods/ensure-jscodeshift.mjs';
+import {getTransformsBetween, latestVersion} from '../../codemods/registry.mjs';
+import {runCodemods} from '../../codemods/runner.mjs';
 import {
   discoverIntegrationCodemods,
   selectIntegrationCodemods,
-} from '../codemods/integration-discovery.mjs';
-import {runIntegrationCodemods} from '../codemods/integration-runner.mjs';
-import {installAgentDocs, inspectAgentDocs} from './agent-docs.mjs';
-import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
-import {isValidSemver, semverGte} from '../utils/semver.mjs';
-import {jsonOut, jsonError} from '../lib/json.mjs';
-import {Project} from '../lib/project.mjs';
-import {loadIntegrations} from '../lib/integrations.mjs';
-import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+} from '../../codemods/integration-discovery.mjs';
+import {runIntegrationCodemods} from '../../codemods/integration-runner.mjs';
+import {installAgentDocs, inspectAgentDocs} from '../../lib/agent-docs/agent-docs.mjs';
+import {getCliInvocation, formatCliCommand} from '../../utils/package-manager.mjs';
+import {isValidSemver, semverGte} from '../../utils/semver.mjs';
+import {jsonOut, jsonError} from '../../lib/json.mjs';
+import {Project} from '../../lib/project.mjs';
+import {loadIntegrations} from '../../lib/integrations.mjs';
+import {warnOnIntegrationIssues} from '../../lib/integration-warnings.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -82,8 +82,18 @@ function detectInstalledTargetVersion() {
   return null;
 }
 
+/**
+ * @param {(string | null | undefined | false)[] | undefined} files
+ * @returns {string[]}
+ */
 function uniqueFiles(files) {
-  return [...new Set((files ?? []).filter(Boolean))];
+  return [
+    ...new Set(
+      (files ?? []).filter(
+        /** @returns {f is string} */ f => Boolean(f),
+      ),
+    ),
+  ];
 }
 
 /**
@@ -95,7 +105,7 @@ function uniqueFiles(files) {
  * In apply mode the commands run in order via execFile; a nonzero exit (or a
  * buildCommand throw) fails the upgrade.
  *
- * @param {import('../types/config').PostCodemodHook[]} hooks
+ * @param {import('../../types/config').PostCodemodHook[]} hooks
  * @param {{packageDir: string, files: string[], apply: boolean}} context
  * @param {boolean} silent
  */
@@ -126,14 +136,18 @@ async function runPostCodemodHooks(hooks, context, silent) {
       continue;
     }
 
-    await execFileAsync(cmd.command, cmd.args ?? [], {
-      cwd: cmd.options?.cwd ?? packageDir,
-      timeout: cmd.options?.timeout ?? 300_000,
-      stdio: 'pipe',
-      encoding: 'utf-8',
-      ...cmd.options,
-      env: {...process.env, ...(cmd.options?.env ?? {})},
-    });
+    await execFileAsync(
+      cmd.command,
+      cmd.args ?? [],
+      /** @type {import('node:child_process').ExecFileOptions & {encoding: 'utf-8'}} */ ({
+        cwd: cmd.options?.cwd ?? packageDir,
+        timeout: cmd.options?.timeout ?? 300_000,
+        stdio: 'pipe',
+        encoding: 'utf-8',
+        ...cmd.options,
+        env: {...process.env, ...(cmd.options?.env ?? {})},
+      }),
+    );
     log.success(`Post-codemod hook ${label} completed.`);
   }
 }
@@ -156,11 +170,11 @@ async function runPostCodemodHooks(hooks, context, silent) {
  * - `current` — every block already matches the installed version: stay silent.
  *
  * @param {{cwd: string, installedVersion: string, apply: boolean, json: boolean}} ctx
- * @returns {import('../types/upgrade').AgentDocsSummary}
+ * @returns {import('../../types/upgrade').AgentDocsSummary}
  */
 export function refreshAgentDocs({cwd, installedVersion, apply, json}) {
   const inspection = inspectAgentDocs(cwd, installedVersion);
-  /** @type {import('../types/upgrade').AgentDocsSummary} */
+  /** @type {import('../../types/upgrade').AgentDocsSummary} */
   const summary = {
     status: inspection.status,
     installedVersion,
@@ -235,8 +249,27 @@ export function refreshAgentDocs({cwd, installedVersion, apply, json}) {
   return summary;
 }
 
+/**
+ * A single core transform entry as produced by the registry manifests. The
+ * registry's declared return type omits the optional `optional` flag and the
+ * `pr`/`codemodType` meta fields that the transform modules actually carry;
+ * this local shape captures what the upgrade command reads. Remove once
+ * codemods/registry.mjs declares these fields on its return type.
+ * @typedef {object} CoreTransformEntry
+ * @property {string} name
+ * @property {import('../../types/codemod').CodemodTransform} transform
+ * @property {{title: string, description?: string, pr?: string, codemodType?: string}} meta
+ * @property {boolean} [optional]
+ */
+
+/**
+ * A version-scoped group of core transforms from the registry.
+ * @typedef {{version: string, transforms: CoreTransformEntry[]}} CoreVersionManifest
+ */
+
 /**
  * Register the `upgrade` command (codemod-driven version migration).
+ * @param {import('commander').Command} program
  */
 export function registerUpgrade(program) {
   program
@@ -260,6 +293,10 @@ export function registerUpgrade(program) {
     .option(
       '--integration <package-or-file>',
       'Explicit integration package name or integration file path (repeatable)',
+      /**
+       * @param {string} value
+       * @param {string[]} previous
+       */
       (value, previous) => [...(previous ?? []), value],
       [],
     )
@@ -270,7 +307,21 @@ export function registerUpgrade(program) {
       false,
     )
     .option('--list', 'List available codemods', false)
-    .action(async options => {
+    .action(
+      /**
+       * @param {{
+       *   list?: boolean,
+       *   from?: string,
+       *   apply: boolean,
+       *   force?: boolean,
+       *   codemod?: string,
+       *   skipCodemod?: string[],
+       *   integration?: string[],
+       *   path: string,
+       *   installDeps?: boolean,
+       * }} options
+       */
+      async options => {
       const json = program.opts().json || false;
       if (!json) p.intro('Upgrade');
 
@@ -301,7 +352,9 @@ export function registerUpgrade(program) {
         // over every version and re-walked getTransformsBetween('0.0.0', v),
         // so each codemod was printed once per release that included it
         // (31 unique × 9 ≈ 201 lines on the current registry).
-        const manifests = await getTransformsBetween('0.0.0', latestVersion);
+        const manifests = /** @type {CoreVersionManifest[]} */ (
+          await getTransformsBetween('0.0.0', latestVersion)
+        );
         for (const {version, transforms} of manifests) {
           for (const {name, meta, optional} of transforms) {
             codemods.push({
@@ -333,7 +386,8 @@ export function registerUpgrade(program) {
         return;
       }
 
-      const currentVersion = options.from;
+      // Guarded above: reaching here means --from passed isValidSemver, so it's a string.
+      const currentVersion = /** @type {string} */ (options.from);
       const installed = detectInstalledTargetVersion();
       if (!installed) {
         const msg =
@@ -400,9 +454,9 @@ export function registerUpgrade(program) {
       // Resolve CORE transforms from the registry. These do not need the loaded
       // config. Integration codemods are discovered later, AFTER the config
       // loads successfully (they require a valid config to resolve).
-      const versionManifests = [
+      const versionManifests = /** @type {CoreVersionManifest[]} */ ([
         ...(await getTransformsBetween(currentVersion, targetVersion)),
-      ];
+      ]);
 
       // Does the selected core set include >=1 CONFIG codemod? A config codemod
       // is the established convention `meta.codemodType === 'config'` (see
@@ -470,6 +524,15 @@ export function registerUpgrade(program) {
         skipCodemods,
         silent: json,
       });
+      // runCodemods returns either a success accounting or a
+      // {ok: false, reason} sentinel (e.g. source_path_missing). Narrow to the
+      // success shape so downstream property reads type-check; the sentinel
+      // branch collapses to null and the `?? 0`/`?? []` fallbacks below treat
+      // it as "no files changed", matching the existing runtime behavior.
+      const coreResult =
+        codemodResult && 'totalFilesChanged' in codemodResult
+          ? codemodResult
+          : null;
 
       // STEP 4 — Load the consumer's config (STRICT validation; unchanged). On
       // --apply this now sees the repaired config the core codemod just wrote.
@@ -477,8 +540,11 @@ export function registerUpgrade(program) {
       // here. Wrap in a graceful dry-run catch (see below).
       // Assigned inside the try below; every catch branch returns, so these
       // are always set before any later read.
+      /** @type {Array<import('../../lib/integrations.mjs').LoadedIntegration>} */
       let integrations;
+      /** @type {import('../../types/config').PostCodemodHook[]} */
       let postCodemodHooks;
+      /** @type {Array<{version: string, codemods: import('../../types/codemod').CodemodEntry[]}>} */
       let integrationVersionGroups;
       try {
         const project = await Project.load(process.cwd());
@@ -489,6 +555,7 @@ export function registerUpgrade(program) {
         ]);
         integrations = await loadIntegrations(integrationSpecs);
       } catch (err) {
+        const configErr = /** @type {Error} */ (err);
         // GRACEFUL DRY-RUN CATCH. A config that fails strict validation is the
         // EXPECTED, fixable case ONLY when we are in dry-run AND a pending core
         // config codemod just PREVIEWED a change to the config — i.e. the very
@@ -499,7 +566,7 @@ export function registerUpgrade(program) {
         // gate and aborts below — preserving the strictness contract.) This is
         // the reason this PR reorders the pipeline.
         const codemodWouldFixConfig =
-          hasCoreConfigCodemod && (codemodResult?.totalFilesChanged ?? 0) > 0;
+          hasCoreConfigCodemod && (coreResult?.totalFilesChanged ?? 0) > 0;
         if (!options.apply && codemodWouldFixConfig) {
           const codemodFlags = coreConfigCodemodNames
             .map(name => `--codemod ${name}`)
@@ -518,7 +585,7 @@ export function registerUpgrade(program) {
               status: 'config_fixable',
               from: currentVersion,
               to: targetVersion,
-              configError: err.message,
+              configError: configErr.message,
               configCodemods: coreConfigCodemodNames,
               suggestedCommand,
               message: guidance,
@@ -539,11 +606,11 @@ export function registerUpgrade(program) {
         // refresh already ran (it's independent of config), so surface it.
         if (json)
           return jsonError(
-            err.message,
-            {agentDocs},
+            configErr.message,
+            /** @type {import('../../types/base').Suggestion[]} */ (/** @type {unknown} */ ({agentDocs})),
             ERROR_CODES.ERR_INVALID_ARGUMENT,
           );
-        p.log.error(err.message);
+        p.log.error(configErr.message);
         p.outro('Aborted');
         process.exitCode = 1;
         return;
@@ -574,12 +641,21 @@ export function registerUpgrade(program) {
       // hard-failing the upgrade. An EXECUTION-time failure (a transform
       // throwing) is handled later by the codemod-error gate, which still
       // aborts the upgrade.
+      /** @type {Map<string, Array<import('../../types/codemod').CodemodEntry>>} */
       const integrationCodemodsByVersion = new Map();
       for (const integration of integrations) {
         if (!integration?.codemods) continue;
         try {
           const byVersion = await discoverIntegrationCodemods([integration]);
-          for (const [version, list] of byVersion) {
+          for (const [version, rawList] of byVersion) {
+            // discoverIntegrationCodemods declares `codemod: object` (loose); the
+            // runtime entries carry the full CodemodEntry.codemod shape. Narrow
+            // to the map's element type. Report: integration-discovery.mjs's
+            // @returns should declare CodemodEntry instead of the loose object.
+            const list =
+              /** @type {Array<import('../../types/codemod').CodemodEntry>} */ (
+                /** @type {unknown} */ (rawList)
+              );
             const existing = integrationCodemodsByVersion.get(version);
             if (existing) existing.push(...list);
             else integrationCodemodsByVersion.set(version, [...list]);
@@ -589,11 +665,14 @@ export function registerUpgrade(program) {
           // above surfaces the underlying issue. Best-effort, non-blocking.
         }
       }
-      integrationVersionGroups = selectIntegrationCodemods(
-        integrationCodemodsByVersion,
-        currentVersion,
-        targetVersion,
-      );
+      integrationVersionGroups =
+        /** @type {Array<{version: string, codemods: import('../../types/codemod').CodemodEntry[]}>} */ (
+          selectIntegrationCodemods(
+            integrationCodemodsByVersion,
+            currentVersion,
+            targetVersion,
+          )
+        );
       const hasIntegrationCodemods = integrationVersionGroups.some(
         g => g.codemods.length > 0,
       );
@@ -630,7 +709,7 @@ export function registerUpgrade(program) {
       if (totalTransforms === 0 && totalOptional === 0) {
         const msg = `Codemod "${options.codemod}" not found. Use --list to see available codemods.`;
         if (json)
-          return jsonError(msg, {agentDocs}, ERROR_CODES.ERR_UNKNOWN_CODEMOD);
+          return jsonError(msg, /** @type {import('../../types/base').Suggestion[]} */ (/** @type {unknown} */ ({agentDocs})), ERROR_CODES.ERR_UNKNOWN_CODEMOD);
         p.log.error(msg);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -647,6 +726,26 @@ export function registerUpgrade(program) {
         }
       }
 
+      /**
+       * Terminal upgrade receipt. NOTE: the shape emitted here (with
+       * `integrations`, `filesChanged`, `transformsApplied`, `errors`) is what
+       * the command has always produced and what upgrade.test/config-ordering
+       * assert on; it does NOT match `UpgradeRunResponse.data` in
+       * types/upgrade.d.ts (which declares a stale `depsUpdated` field and omits
+       * these). The jsonOut call below is cast to bridge that drift. See the
+       * report: types/upgrade.d.ts needs reconciling with the real envelope.
+       * @type {{
+       *   from: string,
+       *   to: string,
+       *   codemods: number,
+       *   integrations: string[],
+       *   agentDocsRefreshed: boolean,
+       *   agentDocs: import('../../types/upgrade').AgentDocsSummary,
+       *   filesChanged?: number,
+       *   transformsApplied?: number,
+       *   errors?: Array<{file: string, codemod: string, error: string}>,
+       * }}
+       */
       const receipt = {
         from: currentVersion,
         to: targetVersion,
@@ -679,17 +778,17 @@ export function registerUpgrade(program) {
       // Merge core + integration codemod results into a single accounting so
       // hooks, receipts, and error gating see both.
       const mergedFilesChanged =
-        (codemodResult?.totalFilesChanged ?? 0) +
+        (coreResult?.totalFilesChanged ?? 0) +
         (integrationResult?.totalFilesChanged ?? 0);
       const mergedTransformsApplied =
-        (codemodResult?.totalTransformsApplied ?? 0) +
+        (coreResult?.totalTransformsApplied ?? 0) +
         (integrationResult?.totalTransformsApplied ?? 0);
       const mergedWrittenFiles = [
-        ...(codemodResult?.writtenFiles ?? []),
+        ...(coreResult?.writtenFiles ?? []),
         ...(integrationResult?.writtenFiles ?? []),
       ];
       const mergedErrors = [
-        ...(codemodResult?.errors ?? []),
+        ...(coreResult?.errors ?? []),
         ...(integrationResult?.errors ?? []),
       ];
 
@@ -714,13 +813,14 @@ export function registerUpgrade(program) {
             json,
           );
         } catch (err) {
+          const hookErr = /** @type {Error} */ (err);
           if (json)
             return jsonError(
-              `Post-codemod hook failed: ${err.message}`,
-              {receipt},
+              `Post-codemod hook failed: ${hookErr.message}`,
+              /** @type {import('../../types/base').Suggestion[]} */ (/** @type {unknown} */ ({receipt})),
               ERROR_CODES.ERR_CODEMOD_FAILED,
             );
-          p.log.error(`Post-codemod hook failed: ${err.message}`);
+          p.log.error(`Post-codemod hook failed: ${hookErr.message}`);
           p.outro('Upgrade failed');
           process.exitCode = 1;
           return;
@@ -738,7 +838,7 @@ export function registerUpgrade(program) {
       if (receipt.errors?.length > 0) {
         const msg = `Upgrade completed with ${receipt.errors.length} codemod error${receipt.errors.length === 1 ? '' : 's'}.`;
         if (json) {
-          return jsonError(msg, {receipt}, ERROR_CODES.ERR_CODEMOD_FAILED);
+          return jsonError(msg, /** @type {import('../../types/base').Suggestion[]} */ (/** @type {unknown} */ ({receipt})), ERROR_CODES.ERR_CODEMOD_FAILED);
         }
         p.outro('Upgrade failed');
         process.exitCode = 1;
@@ -746,7 +846,15 @@ export function registerUpgrade(program) {
       }
 
       if (json) {
-        return jsonOut('upgrade.run', receipt);
+        // The emitted receipt intentionally differs from UpgradeRunResponse.data
+        // (see the typedef note above and the report): cast to the declared
+        // envelope shape until types/upgrade.d.ts is reconciled.
+        return jsonOut(
+          'upgrade.run',
+          /** @type {import('../../types/upgrade').UpgradeRunResponse['data']} */ (
+            /** @type {unknown} */ (receipt)
+          ),
+        );
       }
       p.outro(options.apply ? 'Upgrade complete' : 'Dry run complete');
     });

package/{src → cli}/commands/upgrade.test.mjs

@@ -6,7 +6,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import {Command} from 'commander';
 import {registerUpgrade} from './upgrade.mjs';
-import {generateCompressedIndex} from './agent-docs.mjs';
+import {generateCompressedIndex} from '../../lib/agent-docs/agent-docs.mjs';
 
 let tmpDir;
 let originalCwd;