@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src/api → api/component}/component.mjs

@@ -9,8 +9,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {findCoreDir, discoverExternalPackages} from '../utils/paths.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {findCoreDir, discoverExternalPackages} from '../../utils/paths.mjs';
 import {
   CORE_PACKAGE,
   discoverComponents,
@@ -22,24 +22,46 @@ import {
   findIntegrationComponentDoc,
   findIntegrationComponentSource,
   resolveImportPath,
-} from '../lib/component-discovery.mjs';
-import {Project} from '../lib/project.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {searchComponents} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {findShowcase, findRelatedBlocks} from './template.mjs';
+} from '../../lib/component-discovery.mjs';
+import {Project} from '../../lib/project.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {searchComponents} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {findShowcase, findRelatedBlocks} from '../template/template.mjs';
+
+/**
+ * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
+ * which is either a single-component or multi-component doc; this loose view
+ * captures the fields the API reads across both forms.
+ * @typedef {object} LoadedComponentDoc
+ * @property {string} [name]
+ * @property {string} [description]
+ * @property {any[]} [props]
+ * @property {any[]} [components]
+ * @property {{description?: string}} [usage]
+ * @property {any} [theming]
+ */
+
+/**
+ * Options object for `loadDocs`, matching its declared parameter shape (used
+ * as a cast target so `lang` (which the API may hold as `string|null`) type
+ * checks against `loadDocs`'s `lang?: string`).
+ * @typedef {{zh?: boolean, dense?: boolean, lang?: string}} LoadDocsOpts
+ */
 
 /**
  * Load the configured integrations for `cwd`, swallowing any config errors so
  * component discovery never hard-fails on a malformed/absent integration. An
  * empty list means "core only".
  * @param {string} cwd
- * @returns {Promise<Array<{name: string, components?: string, issuesUrl?: string}>>}
+ * @returns {Promise<import('../../lib/integrations.mjs').LoadedIntegration[]>}
  */
 async function loadIntegrationsSafely(cwd) {
   try {
     const project = await Project.load(cwd);
-    return project.loadedIntegrations;
+    return /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
+      project.loadedIntegrations
+    );
   } catch {
     return [];
   }
@@ -47,7 +69,7 @@ async function loadIntegrationsSafely(cwd) {
 
 /**
  * Resolve a loaded integration by package name.
- * @param {Array<{name: string}>} loadedIntegrations
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration[]} loadedIntegrations
  * @param {string} packageName
  */
 function findLoadedIntegration(loadedIntegrations, packageName) {
@@ -133,7 +155,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              const docs = await loadDocs(readme, {zh, lang});
+              const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang})));
               entries.push({name: comp, description: docs.usage?.description || docs.description || '', import: resolveImportPath(coreDir, comp)});
             } catch {
               entries.push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});
@@ -151,7 +173,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              entries.push(await loadDocs(readme, {zh, lang, dense}));
+              entries.push(await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang, dense})));
             } catch {
               entries.push({name: `XDS${comp}`, description: ''});
             }
@@ -173,7 +195,7 @@ export async function component(name, options = {}) {
 
     // All components — merge core + external packages with grouped subcategories
     if (detail === 'compact') {
-      /** @type {Record<string, Array<import('../types/component').ComponentBriefEntry>>} */
+      /** @type {Record<string, Array<import('../../types/component').ComponentBriefEntry>>} */
       const result = {};
       for (const [cat, comps] of Object.entries(components)) {
         result[cat] = [];
@@ -181,7 +203,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              const docs = await loadDocs(readme, {zh, lang});
+              const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang})));
               result[cat].push({name: comp, description: docs.usage?.description || docs.description || '', import: resolveImportPath(coreDir, comp)});
             } catch {
               result[cat].push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});
@@ -203,7 +225,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              result[cat].push(await loadDocs(readme, {zh, lang, dense}));
+              result[cat].push(await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang, dense})));
             } catch {
               result[cat].push({name: `XDS${comp}`, description: ''});
             }
@@ -238,7 +260,7 @@ export async function component(name, options = {}) {
         const groupLabel = rec.group ?? integration.name;
         const key = `${groupLabel} (${integration.name})`;
         if (!byGroup.has(key)) byGroup.set(key, []);
-        byGroup.get(key).push({name: rec.name, package: integration.name});
+        byGroup.get(key)?.push({name: rec.name, package: integration.name});
       }
       for (const [key, members] of byGroup) {
         members.sort((a, b) => a.name.localeCompare(b.name));
@@ -334,14 +356,14 @@ export async function component(name, options = {}) {
    * `package`, the resolved `import` specifier, and `sourceAvailable` (whether
    * a swizzleable source file exists for the owner). Existing doc fields
    * (name, usage, props, …) are preserved.
-   * @param {object} docs
+   * @param {LoadedComponentDoc} docs
    * @param {{package: string, sourcePath: string|null}} owner
    * @param {string} componentName
    */
   function withOwnership(docs, owner, componentName) {
     const importSpec =
       owner.package === CORE_PACKAGE
-        ? resolveImportPath(coreDir, componentName)
+        ? resolveImportPath(/** @type {string} */ (coreDir), componentName)
         : `${owner.package}/${componentName}`;
     return {
       ...docs,
@@ -368,7 +390,7 @@ export async function component(name, options = {}) {
         }
         return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
       }
-      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
         return {type: 'component.detail.props', data: p};
@@ -389,7 +411,7 @@ export async function component(name, options = {}) {
         }
         return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
       }
-      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
         return {type: 'component.detail.props', data: p};
@@ -420,7 +442,7 @@ export async function component(name, options = {}) {
 
     const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);
     if (extDocPath && extDocPath.endsWith('.doc.mjs')) {
-      const docs = await loadDocs(extDocPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(extDocPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
 
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
@@ -461,7 +483,7 @@ export async function component(name, options = {}) {
     if (showcase) {
       throw new AstryxError(`No showcase found for "${name}"`, undefined, ERROR_CODES.ERR_NO_SHOWCASE);
     }
-    const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+    const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
     if (props) {
       const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
       return {type: 'component.detail.props', data: p};
@@ -546,12 +568,12 @@ export async function component(name, options = {}) {
     throw new AstryxError(`No .doc.mjs found for "${resolvedName}". The component needs a typed doc file.`, undefined, ERROR_CODES.ERR_NO_DOC);
   }
 
-  const docs = await loadDocs(readmePath, {zh, dense, lang});
+  const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readmePath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
 
   // ── Blocks mode ──────────────────────────────────────────────
   if (blocks) {
     const allBlocks = await findRelatedBlocks(dirName);
-    const toEntry = (b) => ({
+    const toEntry = (/** @type {any} */ b) => ({
       name: b.dirName,
       displayName: b.name,
       description: b.description,
@@ -561,7 +583,7 @@ export async function component(name, options = {}) {
 
     // Examples: blocks in the component's own directory, or
     // componentsUsed match for sub-components without a directory.
-    const ownDir = allBlocks.filter(b => path.basename(b.category) === dirName);
+    const ownDir = allBlocks.filter((/** @type {any} */ b) => path.basename(b.category) === dirName);
     const examples = ownDir.length > 0
       ? ownDir
       : allBlocks.filter(b => b.componentsUsed?.some(c => c === dirName));
@@ -595,6 +617,7 @@ export async function component(name, options = {}) {
     : null;
 
   if (matchingComponent) {
+    /** @type {LoadedComponentDoc & {parentDoc?: string, import?: string}} */
     const scoped = {
       name: dirName,
       description: matchingComponent.description,

package/{src/api → api/discover}/discover.mjs

@@ -4,28 +4,37 @@
  * @file Programmatic API for the discover command.
  */
 
-import {Project} from '../lib/project.mjs';
+import {Project} from '../../lib/project.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
-} from '../lib/package-scanner.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+} from '../../lib/package-scanner.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
+/**
+ * @typedef {import('../../lib/package-scanner.mjs').ScannedPackage} ScannedPackage
+ */
+
+/**
+ * @param {unknown} docs
+ * @returns {string | null}
+ */
 function validateDocs(docs) {
   if (!docs || typeof docs !== 'object')
     return 'docs export is missing or not an object';
-  if (typeof docs.name !== 'string' || !docs.name)
+  const d = /** @type {Record<string, any>} */ (docs);
+  if (typeof d.name !== 'string' || !d.name)
     return 'docs.name is missing or not a string';
-  if (!docs.usage || typeof docs.usage.description !== 'string')
+  if (!d.usage || typeof d.usage.description !== 'string')
     return 'docs.usage.description is missing or not a string';
-  if (docs.props && !Array.isArray(docs.props))
+  if (d.props && !Array.isArray(d.props))
     return 'docs.props must be an array';
-  if (docs.components && !Array.isArray(docs.components))
+  if (d.components && !Array.isArray(d.components))
     return 'docs.components must be an array';
-  if (docs.usage?.bestPractices && !Array.isArray(docs.usage.bestPractices))
+  if (d.usage?.bestPractices && !Array.isArray(d.usage.bestPractices))
     return 'docs.usage.bestPractices must be an array';
   return null;
 }
@@ -36,11 +45,21 @@ function validateDocs(docs) {
  * @param {boolean} [options.components]
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
- * @returns {Promise<{type: string, data: unknown}>}
+ * @returns {Promise<
+ *   import('../../types/discover').DiscoverListResponse |
+ *   import('../../types/discover').DiscoverDetailResponse |
+ *   import('../../types/discover').DiscoverDetailDocResponse |
+ *   import('../../types/discover').DiscoverSearchResponse
+ * >}
  */
 export async function discover(query, options = {}) {
   const {lang = null, zh = false} = options;
   const project = await Project.load();
+  const loadedIntegrations =
+    /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
+      project.loadedIntegrations
+    );
+  /** @param {ScannedPackage} pkg */
   const toEntry = pkg => ({
     name: pkg.name,
     category: pkg.category,
@@ -52,7 +71,7 @@ export async function discover(query, options = {}) {
 
   // External packages come from configured integrations that declare a
   // components root. Each becomes a scannable package keyed by its docsDir.
-  const explicitPackages = project.loadedIntegrations
+  const explicitPackages = loadedIntegrations
     .filter(integration => integration.components)
     .map(integration => ({
       name: integration.name,
@@ -64,7 +83,10 @@ export async function discover(query, options = {}) {
     return {type: 'discover.list', data: [], meta: {configured: false}};
   }
 
-  const packages = scanAllPackages([], explicitPackages);
+  const packages = scanAllPackages(
+    [],
+    /** @type {ScannedPackage[]} */ (/** @type {unknown} */ (explicitPackages)),
+  );
 
   if (packages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: true}};
@@ -105,7 +127,7 @@ export async function discover(query, options = {}) {
     return await loadAndValidate(exact, {lang, zh});
   }
 
-  const substringMatches = [];
+  const substringMatches = /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
   for (const pkg of packages) {
     for (const comp of pkg.components) {
       if (comp.toLowerCase().includes(lower)) {
@@ -134,7 +156,7 @@ export async function discover(query, options = {}) {
   }
 
   // Fuzzy fallback
-  const allComponents = [];
+  const allComponents = /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
   for (const pkg of packages) {
     for (const comp of pkg.components) {
       allComponents.push({pkg, comp});
@@ -167,6 +189,13 @@ export async function discover(query, options = {}) {
   );
 }
 
+/**
+ * @param {ScannedPackage[]} packages
+ * @param {string} compName
+ * @param {string} pkgName
+ * @param {{lang?: string|null, zh?: boolean}} opts
+ * @returns {Promise<import('../../types/discover').DiscoverDetailDocResponse>}
+ */
 async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   const pkg = packages.find(p => p.name === pkgName);
   if (!pkg)
@@ -202,13 +231,21 @@ async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   return await loadAndValidate(result, {lang, zh});
 }
 
+/**
+ * @param {{docPath: string, componentName: string, pkg: ScannedPackage}} result
+ * @param {{lang?: string|null, zh?: boolean}} opts
+ * @returns {Promise<import('../../types/discover').DiscoverDetailDocResponse>}
+ */
 async function loadAndValidate(result, {lang, zh}) {
   let docs;
   try {
-    docs = await loadDocs(result.docPath, {zh, lang});
+    docs = await loadDocs(
+      result.docPath,
+      /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}),
+    );
   } catch (e) {
     throw new AstryxError(
-      `Failed to load docs for ${result.componentName}: ${e.message}`,
+      `Failed to load docs for ${result.componentName}: ${/** @type {any} */ (e).message}`,
       undefined,
       ERROR_CODES.ERR_INVALID_DOC,
     );

package/{src/api → api/docs}/docs.mjs

@@ -7,13 +7,17 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {CLI_ROOT} from '../utils/paths.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const DOCS_DIR = path.join(CLI_ROOT, 'docs');
 
+/**
+ * @returns {Record<string, string>}
+ */
 function discoverTopics() {
+  /** @type {Record<string, string>} */
   const topics = {};
   if (!fs.existsSync(DOCS_DIR)) return topics;
   for (const file of fs.readdirSync(DOCS_DIR)) {
@@ -23,6 +27,11 @@ function discoverTopics() {
   return topics;
 }
 
+/**
+ * @param {string} docPath
+ * @param {{lang?: string|null}} [opts]
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
+ */
 async function loadReferenceDocs(docPath, {lang} = {}) {
   const mod = await import(pathToFileURL(docPath).href);
   const docs = mod.docs;
@@ -45,6 +54,7 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   // printed the colour table under a "Spacing" heading (#2182). An overlay may
   // now cover any subset of sections, in any order; sections it does not name
   // keep their base content.
+  /** @type {Map<string, any>} */
   const bySection = new Map();
   for (const ts of translation.sections ?? []) {
     if (ts?.section != null) bySection.set(ts.section, ts);
@@ -53,32 +63,43 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   return {
     ...docs,
     description: translation.description || docs.description,
-    sections: docs.sections.map(section => {
-      const ts = bySection.get(section.title);
-      if (!ts) return section;
-      return {
-        ...section,
-        title: ts.title || section.title,
-        content: section.content.map((block, bi) => {
-          const tb = ts.content?.[bi];
-          if (!tb) return block;
-          if (tb.type === 'prose' && block.type === 'prose') return {...block, text: tb.text};
-          if (tb.type === 'list' && block.type === 'list') return {...block, items: tb.items};
-          return block;
-        }),
-      };
-    }),
+    sections: docs.sections.map(
+      (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ section) => {
+        const ts = bySection.get(section.title);
+        if (!ts) return section;
+        return {
+          ...section,
+          title: ts.title || section.title,
+          content: section.content.map(
+            (
+              /** @type {import('../../../core/src/docs-types').ContentBlock} */ block,
+              /** @type {number} */ bi,
+            ) => {
+              const tb = ts.content?.[bi];
+              if (!tb) return block;
+              if (tb.type === 'prose' && block.type === 'prose') return {...block, text: tb.text};
+              if (tb.type === 'list' && block.type === 'list') return {...block, items: tb.items};
+              return block;
+            },
+          ),
+        };
+      },
+    ),
   };
 }
 
 /**
  * Resolve token-ref blocks by inlining the referenced section's table.
  * This allows section docs to reference token tables without duplicating data.
+ * @param {import('../../types/docs').DocsDetailResponse['data']} docsData
+ * @param {Record<string, string>} topics
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
  */
 async function resolveTokenRefs(docsData, topics) {
   const resolved = {...docsData, sections: [...docsData.sections]};
   for (let si = 0; si < resolved.sections.length; si++) {
     const section = resolved.sections[si];
+    /** @type {import('../../../core/src/docs-types').ContentBlock[]} */
     const newContent = [];
     for (const block of section.content) {
       if (block.type === 'token-ref') {
@@ -90,7 +111,8 @@ async function resolveTokenRefs(docsData, topics) {
         const refMod = await import(pathToFileURL(refPath).href);
         const refDocs = refMod.docs;
         const refSection = refDocs.sections.find(
-          s => s.title.toLowerCase() === block.section.toLowerCase(),
+          (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ s) =>
+            s.title.toLowerCase() === block.section.toLowerCase(),
         );
         if (!refSection) {
           newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});
@@ -125,7 +147,11 @@ async function resolveTokenRefs(docsData, topics) {
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
- * @returns {Promise<{type: string, data: unknown}>}
+ * @returns {Promise<
+ *   import('../../types/docs').DocsListResponse |
+ *   import('../../types/docs').DocsDetailResponse |
+ *   import('../../types/docs').DocsDetailSectionResponse
+ * >}
  */
 export async function docs(topic, section, options = {}) {
   const {lang = null, zh = false, dense = false} = options;
@@ -133,7 +159,7 @@ export async function docs(topic, section, options = {}) {
   const topics = discoverTopics();
 
   if (!topic) {
-    /** @type {Array<import('../types/docs').DocsListEntry>} */
+    /** @type {Array<import('../../types/docs').DocsListEntry>} */
     const entries = [];
     for (const [name, docPath] of Object.entries(topics)) {
       try {

package/{src/api → api/doctor}/doctor.mjs

@@ -24,11 +24,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {createRequire} from 'node:module';
 
-import {MIN_NODE_VERSION, isNodeVersionSupported} from '../lib/node-version.mjs';
-import {CLI_ROOT, findCoreDir} from '../utils/paths.mjs';
-import {detectPackageManager} from '../utils/package-manager.mjs';
-import {findConfigPath, Project} from '../lib/project.mjs';
-import {semverCompare} from '../utils/semver.mjs';
+import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../lib/node-version.mjs';
+import {CLI_ROOT, findCoreDir} from '../../utils/paths.mjs';
+import {detectPackageManager, getCliInvocation} from '../../utils/package-manager.mjs';
+import {findConfigPath, Project} from '../../lib/project.mjs';
+import {semverCompare} from '../../utils/semver.mjs';
 
 const _require = createRequire(import.meta.url);
 
@@ -49,7 +49,7 @@ const _require = createRequire(import.meta.url);
  * @typedef {object} DoctorContext
  * @property {string} cwd - Directory to diagnose.
  * @property {string} nodeVersion - Running Node version.
- * @property {string|null} coreDir - Resolved @astryxdesign/core directory, or null.
+ * @property {string|null} coreDir - Resolved core package directory, or null.
  * @property {string|null} configPath - Resolved astryx.config.mjs path, or null.
  * @property {string|null} configTheme - theme value read from config, or null.
  */
@@ -104,6 +104,7 @@ function findNodeModules(startDir) {
  */
 function findThemePackages(cwd) {
   const nm = findNodeModules(cwd);
+  /** @type {Array<{name: string, version: string|null}>} */
   const found = [];
   if (!nm) return found;
   const scopeDir = path.join(nm, '@astryxdesign');
@@ -317,7 +318,7 @@ export async function checkConfig(ctx) {
       id: 'config',
       label: 'astryx.config.mjs',
       status: 'fail',
-      message: `astryx.config.mjs failed to load: ${err.message}`,
+      message: `astryx.config.mjs failed to load: ${/** @type {any} */ (err).message}`,
       fix: 'Fix the syntax/runtime error in astryx.config.mjs so it imports cleanly.',
     };
   }
@@ -343,7 +344,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'info',
       message: 'No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.',
-      fix: 'Generate agent docs with `astryx init --features agents`.',
+      fix: `Generate agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
     };
   }
 
@@ -365,7 +366,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
-      fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',
+      fix: `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
     };
   }
 
@@ -490,7 +491,8 @@ export async function runChecks(options = {}) {
   let configTheme = null;
   try {
     const project = await Project.load(cwd);
-    configTheme = project.config?.theme ?? null;
+    configTheme =
+      /** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
   } catch {
     // Best-effort: a missing/invalid config leaves configTheme null.
   }
@@ -504,6 +506,7 @@ export async function runChecks(options = {}) {
     configTheme,
   };
 
+  /** @type {DoctorCheck[]} */
   const checks = [];
   // checkConfig is async; run it in its declared slot (after themes).
   for (const fn of SYNC_CHECKS) {

package/{src/api → api}/error.mjs

@@ -14,7 +14,7 @@
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 
 export class AstryxError extends Error {
-  /** @type {Array<{name: string, reason: string}> | undefined} */
+  /** @type {import('../types/base').Suggestion[] | undefined} */
   suggestions;
 
   /**
@@ -26,7 +26,7 @@ export class AstryxError extends Error {
 
   /**
    * @param {string} message
-   * @param {Array<{name: string, reason: string}>} [suggestions]
+   * @param {import('../types/base').Suggestion[]} [suggestions]
    * @param {string} [code] - Stable error code. Defaults to ERR_UNKNOWN.
    */
   constructor(message, suggestions, code) {

package/{src/api → api/hook}/hook.mjs

@@ -7,12 +7,12 @@
  * The CLI command handler is a thin wrapper around this function.
  */
 
-import {findCoreDir} from '../utils/paths.mjs';
-import {discoverHooks, findHookDoc, getAllHookNames} from '../lib/hook-discovery.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {findCoreDir} from '../../utils/paths.mjs';
+import {discoverHooks, findHookDoc, getAllHookNames} from '../../lib/hook-discovery.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 /**
  * @param {string} [name]
@@ -72,7 +72,7 @@ export async function hook(name, options = {}) {
           const docPath = findHookDoc(coreDir, hookName);
           if (docPath) {
             try {
-              const docs = await loadDocs(docPath, {zh, lang});
+              const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
               entries.push({
                 name: hookName,
                 description: docs.usage?.description || '',
@@ -94,7 +94,7 @@ export async function hook(name, options = {}) {
           const docPath = findHookDoc(coreDir, hookName);
           if (docPath) {
             try {
-              entries.push(await loadDocs(docPath, {zh, lang}));
+              entries.push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
             } catch {
               entries.push({name: hookName});
             }
@@ -119,7 +119,7 @@ export async function hook(name, options = {}) {
           const docPath = findHookDoc(coreDir, hookName);
           if (docPath) {
             try {
-              const docs = await loadDocs(docPath, {zh, lang});
+              const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
               result[cat].push({
                 name: hookName,
                 description: docs.usage?.description || '',
@@ -145,7 +145,7 @@ export async function hook(name, options = {}) {
           const docPath = findHookDoc(coreDir, hookName);
           if (docPath) {
             try {
-              result[cat].push(await loadDocs(docPath, {zh, lang}));
+              result[cat].push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
             } catch {
               result[cat].push({name: hookName});
             }
@@ -186,7 +186,7 @@ export async function hook(name, options = {}) {
     );
   }
 
-  const docs = await loadDocs(docPath, {zh, lang});
+  const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
 
   if (params) {
     return {type: 'hook.detail.params', data: docs.params || []};