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

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

@@ -7,21 +7,54 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {createJiti} from 'jiti';
-import {loadModuleWithSchema} from '../lib/module-loader.mjs';
-import {TemplateEnvelopeSchema} from '../schemas/template-schema.mjs';
-import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
+import {loadModuleWithSchema} from '../../lib/module-loader.mjs';
+import {TemplateEnvelopeSchema} from '../../schemas/template-schema.mjs';
+import {CLI_ROOT, discoverExternalPackages} from '../../utils/paths.mjs';
 import {
   assertWithin,
   isFilePathArg,
   PathSafetyError,
-} from '../utils/path-safety.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {Project} from '../lib/project.mjs';
+} from '../../utils/path-safety.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {Project} from '../../lib/project.mjs';
 
 /** Identity used for core (built-in) templates in package-scoped listings. */
 const CORE_PACKAGE = '@astryxdesign/core';
 
+/**
+ * A discovered template (page or block), normalized across core, external, and
+ * integration sources. Not every source populates every field, so
+ * source-specific extras (`aspectRatio`, `isShowcase`, `package`) are optional.
+ * @typedef {object} DiscoveredTemplate
+ * @property {'page'|'block'} type
+ * @property {string} dirName
+ * @property {string} name
+ * @property {string} description
+ * @property {string} [category]
+ * @property {boolean} [isReady]
+ * @property {boolean} [scaffold]
+ * @property {number} [aspectRatio]
+ * @property {string[]} [componentsUsed]
+ * @property {boolean} [isShowcase]
+ * @property {string} filePath
+ * @property {string} docPath
+ * @property {string} [package]
+ */
+
+/**
+ * An integration-template discovery error.
+ * @typedef {object} TemplateDiscoveryError
+ * @property {string} package
+ * @property {string} [template]
+ * @property {string} message
+ */
+
+/**
+ * The loaded metadata object from a template spec (loose — authored shape).
+ * @typedef {Record<string, any> | undefined | null} TemplateDocModule
+ */
+
 /**
  * Canonical basename suffixes for template-spec files, in precedence order.
  * A template spec exports a `createBlockTemplate`/`createPageTemplate` result
@@ -60,6 +93,7 @@ function matchedTemplateSuffix(file) {
  */
 const TEMPLATE_SUFFIX_RE = /\.(template|doc)\.(ts|mjs|js)$/;
 
+/** @type {ReturnType<typeof createJiti> | undefined} */
 let jitiInstance;
 /** Lazily-created jiti for loading `.ts` template specs (JSX-capable). */
 function getJiti() {
@@ -69,7 +103,6 @@ function getJiti() {
   return jitiInstance;
 }
 
-
 /**
  * Load an integration template doc module and validate it against the template
  * envelope at the load boundary. Default export only — `.ts` via jiti,
@@ -145,7 +178,7 @@ export function stripTemplateAssetRefs(source) {
  * native dynamic import. Returns null if the file does not exist.
  *
  * @param {string} docPath absolute path to the spec file
- * @returns {Promise<Record<string, unknown> | undefined | null>}
+ * @returns {Promise<TemplateDocModule>}
  */
 async function loadDocModule(docPath) {
   if (!fs.existsSync(docPath)) return null;
@@ -159,6 +192,7 @@ async function loadDocModule(docPath) {
 export {discoverAll as discoverTemplates};
 
 export function listTemplates() {
+  /** @type {string[]} */
   const all = [];
   if (fs.existsSync(PAGES_DIR)) {
     all.push(
@@ -171,7 +205,13 @@ export function listTemplates() {
   return all.sort();
 }
 
+/**
+ * @param {string} dir
+ * @param {RegExp} pattern
+ * @returns {string[]}
+ */
 function findDocFiles(dir, pattern) {
+  /** @type {string[]} */
   const results = [];
   if (!fs.existsSync(dir)) return results;
   for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
@@ -205,6 +245,7 @@ async function discoverPages() {
     .readdirSync(PAGES_DIR, {withFileTypes: true})
     .filter(e => e.isDirectory());
 
+  /** @type {DiscoveredTemplate[]} */
   const templates = [];
   for (const dir of dirs) {
     const dirPath = path.join(PAGES_DIR, dir.name);
@@ -228,9 +269,11 @@ async function discoverPages() {
 
 async function discoverBlocks() {
   const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);
+  /** @type {DiscoveredTemplate[]} */
   const blocks = [];
   for (const docPath of docFiles) {
     const suffix = matchedTemplateSuffix(docPath);
+    if (!suffix) continue;
     const basename = path.basename(docPath, suffix);
     const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
     if (!fs.existsSync(tsxPath)) continue;
@@ -262,6 +305,7 @@ async function discoverBlocks() {
  */
 async function discoverExternalBlocks(cwd = process.cwd()) {
   const externals = discoverExternalPackages(cwd);
+  /** @type {DiscoveredTemplate[]} */
   const blocks = [];
 
   for (const ext of externals) {
@@ -269,6 +313,7 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
     const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);
     for (const docPath of docFiles) {
       const suffix = matchedTemplateSuffix(docPath);
+      if (!suffix) continue;
       const basename = path.basename(docPath, suffix);
       const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
       if (!fs.existsSync(tsxPath)) continue;
@@ -297,6 +342,7 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
 /**
  * Discover all blocks — core + external packages.
  * @param {string} [cwd]
+ * @returns {Promise<DiscoveredTemplate[]>}
  */
 async function discoverAllBlocks(cwd = process.cwd()) {
   const [core, external] = await Promise.all([
@@ -306,6 +352,10 @@ async function discoverAllBlocks(cwd = process.cwd()) {
   return [...core, ...external];
 }
 
+/**
+ * @param {string} [cwd]
+ * @returns {Promise<DiscoveredTemplate[]>}
+ */
 async function discoverAll(cwd = process.cwd()) {
   const [pages, blocks, integration] = await Promise.all([
     discoverPages(),
@@ -323,7 +373,7 @@ async function discoverAll(cwd = process.cwd()) {
  * when the caller wants to warn about malformed integration templates.
  *
  * @param {string} [cwd]
- * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
 async function discoverAllWithErrors(cwd = process.cwd()) {
   const [pages, blocks, integration] = await Promise.all([
@@ -348,8 +398,10 @@ export {discoverAllWithErrors};
  * @returns {string[]}
  */
 function findIntegrationDocFiles(root) {
+  /** @type {string[]} */
   const results = [];
   if (!fs.existsSync(root)) return results;
+  /** @param {string} dir */
   const walk = dir => {
     for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
       const full = path.join(dir, entry.name);
@@ -377,16 +429,21 @@ function findIntegrationDocFiles(root) {
  * template is skipped (recorded in `errors`).
  *
  * @param {string} [cwd]
- * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
 async function discoverIntegrationTemplates(cwd = process.cwd()) {
+  /** @type {DiscoveredTemplate[]} */
   const templates = [];
+  /** @type {TemplateDiscoveryError[]} */
   const errors = [];
 
   let loadedIntegrations;
   try {
     const project = await Project.load(cwd);
-    loadedIntegrations = project.loadedIntegrations;
+    loadedIntegrations =
+      /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
+        project.loadedIntegrations
+      );
   } catch {
     // Config load failures are surfaced elsewhere (discover/doctor); here we
     // simply contribute no integration templates.
@@ -409,10 +466,12 @@ async function discoverIntegrationTemplates(cwd = process.cwd()) {
  * than thrown. Exposed for `validate-integration`.
  *
  * @param {{name?: string, __spec?: string, templates?: string}} integration
- * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
 export async function discoverIntegrationTemplatesForOne(integration) {
+  /** @type {DiscoveredTemplate[]} */
   const templates = [];
+  /** @type {TemplateDiscoveryError[]} */
   const errors = [];
 
   const root = integration?.templates;
@@ -421,6 +480,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
 
   for (const docPath of findIntegrationDocFiles(root)) {
     const suffix = matchedTemplateSuffix(docPath);
+    if (!suffix) continue;
     const id = path
       .relative(root, docPath)
       .slice(0, -suffix.length)
@@ -444,7 +504,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
       errors.push({
         package: pkgLabel,
         template: id,
-        message: `Template "${id}" failed to load: ${err.message}`,
+        message: `Template "${id}" failed to load: ${/** @type {any} */ (err).message}`,
       });
       continue;
     }
@@ -480,10 +540,15 @@ export async function discoverIntegrationTemplatesForOne(integration) {
   return {templates, errors};
 }
 
+/**
+ * @param {string} componentName
+ * @param {string} [cwd]
+ * @returns {Promise<DiscoveredTemplate[]>}
+ */
 export async function findRelatedBlocks(componentName, cwd) {
   const blocks = await discoverAllBlocks(cwd);
   return blocks.filter(b =>
-    b.componentsUsed.some(c => c.toLowerCase() === componentName.toLowerCase()),
+    (b.componentsUsed ?? []).some(c => c.toLowerCase() === componentName.toLowerCase()),
   );
 }
 
@@ -506,7 +571,7 @@ export async function findShowcase(componentName, cwd, options) {
     return true;
   });
 
-  const toResult = b => ({
+  const toResult = (/** @type {DiscoveredTemplate} */ b) => ({
     name: b.name,
     aspectRatio: b.aspectRatio,
     filePath: b.filePath,
@@ -515,14 +580,14 @@ export async function findShowcase(componentName, cwd, options) {
 
   // Priority 1: own directory (components/Badge/ for "Badge")
   const dirMatch = showcases.find(b => {
-    const catDir = path.basename(b.category).toLowerCase();
+    const catDir = path.basename(b.category ?? '').toLowerCase();
     return catDir === lc;
   });
   if (dirMatch) return toResult(dirMatch);
 
   // Priority 2: componentsUsed in any directory (ClickableCard in Card/)
   const usedMatch = showcases.find(b =>
-    b.componentsUsed.some(c => c.toLowerCase() === lc),
+    (b.componentsUsed ?? []).some(c => c.toLowerCase() === lc),
   );
   if (usedMatch) return toResult(usedMatch);
 
@@ -540,6 +605,10 @@ const UBIQUITOUS = new Set([
   'Icon',
 ]);
 
+/**
+ * @param {string} pagePath
+ * @returns {string[]}
+ */
 export function extractComponents(pagePath) {
   const src = fs.readFileSync(pagePath, 'utf-8');
   // Match JSX opening tags, e.g. `<Section` or the legacy `<XDSSection`.
@@ -548,6 +617,7 @@ export function extractComponents(pagePath) {
   // JSX-tag boundary keeps this precise (avoids matching imports/comments/
   // identifiers) while remaining prefix-agnostic.
   const tagRegex = /<(XDS)?([A-Z]\w+)/g;
+  /** @type {string[]} */
   const matches = [];
   let m;
   while ((m = tagRegex.exec(src)) !== null) {
@@ -617,10 +687,11 @@ const SPATIAL_PROPS = [
  * @returns {string[]}
  */
 function extractSpatialAttrs(tagText) {
+  /** @type {string[]} */
   const attrs = [];
   for (const name of SPATIAL_PROPS) {
     const eqMatch = tagText.match(new RegExp(`\\b${name}\\s*=\\s*`));
-    if (eqMatch) {
+    if (eqMatch && eqMatch.index != null) {
       const start = eqMatch.index;
       let i = eqMatch.index + eqMatch[0].length;
       const rest = tagText.slice(i);
@@ -662,13 +733,19 @@ function extractSpatialAttrs(tagText) {
   return attrs;
 }
 
+/**
+ * @param {string} source
+ * @returns {string}
+ */
 function extractSkeleton(source) {
   const lines = source.split('\n');
+  /** @type {string[]} */
   const out = [];
   let depth = 0;
   let capturing = false;
   let inDefaultExport = false;
   const MAX_LINES = 35;
+  /** @type {string[]} */
   const depthStack = [];
 
   for (let i = 0; i < lines.length; i++) {

package/{src/api → api/theme}/theme-add.mjs

@@ -8,10 +8,10 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {CLI_ROOT} from '../utils/paths.mjs';
-import {assertWithin, PathSafetyError} from '../utils/path-safety.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {assertWithin, PathSafetyError} from '../../utils/path-safety.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const THEMES_DIR = path.join(CLI_ROOT, 'templates', 'themes');
 const MANIFEST_PATH = path.join(THEMES_DIR, 'manifest.json');
@@ -21,19 +21,39 @@ const MANIFEST_PATH = path.join(THEMES_DIR, 'manifest.json');
 const META_COPYRIGHT_HEADER_RE =
   /^(\uFEFF?(?:#![^\r\n]*(?:\r?\n))?)\/\/ Copyright \(c\) Meta Platforms, Inc\. and affiliates\.\r?\n(?:\r?\n)*/;
 
+/**
+ * A single bundled theme entry from `templates/themes/manifest.json`.
+ * @typedef {object} BundledTheme
+ * @property {string} slug
+ * @property {string} displayName
+ * @property {string} description
+ * @property {boolean} maintained
+ * @property {string} entry
+ * @property {string} exportName
+ * @property {string[]} files
+ */
+
+/**
+ * @param {string} source
+ * @returns {string}
+ */
 function stripCopyrightHeader(source) {
   return source.replace(META_COPYRIGHT_HEADER_RE, '$1');
 }
 
-/** Parsed `themes` array from the bundle manifest (empty if not generated). */
+/**
+ * Parsed `themes` array from the bundle manifest (empty if not generated).
+ * @returns {BundledTheme[]}
+ */
 export function listThemes() {
   if (!fs.existsSync(MANIFEST_PATH)) return [];
+  /** @type {{themes?: BundledTheme[]}} */
   let manifest;
   try {
     manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf-8'));
   } catch (err) {
     throw new AstryxError(
-      `Theme bundle manifest is unreadable (${MANIFEST_PATH}): ${err.message}`,
+      `Theme bundle manifest is unreadable (${MANIFEST_PATH}): ${/** @type {any} */ (err).message}`,
       undefined,
       ERROR_CODES.ERR_NO_SOURCE,
     );
@@ -41,12 +61,20 @@ export function listThemes() {
   return Array.isArray(manifest.themes) ? manifest.themes : [];
 }
 
+/**
+ * @param {string} [slug]
+ * @returns {BundledTheme | undefined}
+ */
 function findTheme(slug) {
   if (!slug) return undefined;
   const lc = String(slug).toLowerCase();
   return listThemes().find(t => t.slug.toLowerCase() === lc);
 }
 
+/**
+ * @param {string} slug
+ * @returns {string}
+ */
 function defaultTargetDir(slug) {
   return path.join('src', 'themes', slug);
 }
@@ -160,7 +188,7 @@ export async function themeAdd(slug, options = {}) {
       }
     }
     throw new AstryxError(
-      `Failed to write theme files: ${err.message}`,
+      `Failed to write theme files: ${/** @type {any} */ (err).message}`,
       undefined,
       ERROR_CODES.ERR_WRITE_FAILED,
     );

package/{src → authoring}/codemod.mjs

@@ -65,12 +65,12 @@ export const CodemodEnvelopeSchema = z.discriminatedUnion('type', [
  * Define a file-transforming codemod. Stamp-only: returns the definition with
  * `type: 'code'` injected. Validation happens at the load boundary.
  *
- * @template {import('./types/codemod').AstryxCodemodDef} T
+ * @template {import('../types/codemod').AstryxCodemodDef} T
  * @param {T} def
- * @returns {import('./types/codemod').AstryxCodemod}
+ * @returns {import('../types/codemod').AstryxCodemod}
  */
 export function createCodemod(def) {
-  return /** @type {import('./types/codemod').AstryxCodemod} */ ({
+  return /** @type {import('../types/codemod').AstryxCodemod} */ ({
     ...def,
     type: 'code',
   });
@@ -81,12 +81,12 @@ export function createCodemod(def) {
  * returns the definition with `type: 'config'` injected. Validation happens at
  * the load boundary.
  *
- * @template {import('./types/codemod').AstryxConfigCodemodDef} T
+ * @template {import('../types/codemod').AstryxConfigCodemodDef} T
  * @param {T} def
- * @returns {import('./types/codemod').AstryxConfigCodemod}
+ * @returns {import('../types/codemod').AstryxConfigCodemod}
  */
 export function createConfigCodemod(def) {
-  return /** @type {import('./types/codemod').AstryxConfigCodemod} */ ({
+  return /** @type {import('../types/codemod').AstryxConfigCodemod} */ ({
     ...def,
     type: 'config',
   });

package/{src → authoring}/config.test.mjs

@@ -6,7 +6,7 @@ import {createIntegration} from './integration.mjs';
 import {
   AstryxConfigSchema,
   AstryxIntegrationSchema,
-} from './lib/config-schema.mjs';
+} from '../lib/config-schema.mjs';
 
 // createConfig/createIntegration are now pure typed-identity helpers: they
 // return their argument unchanged and perform NO runtime validation. Validation

package/{src → authoring}/doc.mjs

@@ -24,4 +24,4 @@ export {
   StampedDocSchema,
   LegacyDocSchema,
   ComponentDocSchema,
-} from './schemas/doc-schema.mjs';
+} from '../schemas/doc-schema.mjs';

package/{src → authoring}/doc.test.mjs

@@ -12,7 +12,7 @@ import {
   FunctionDocKindSchema,
   GenericDocKindSchema,
 } from './doc.mjs';
-import {loadComponentDoc} from './lib/component-loader.mjs';
+import {loadComponentDoc} from '../lib/component-loader.mjs';
 
 // The factories are stamp-only (like createConfig / createBlockTemplate): they
 // inject a `type` discriminant and are otherwise identity, performing NO

package/{src → authoring}/template.mjs

@@ -12,4 +12,4 @@
  */
 
 export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
-export {BaseTemplateSchema, TemplateEnvelopeSchema} from './schemas/template-schema.mjs';
+export {BaseTemplateSchema, TemplateEnvelopeSchema} from '../schemas/template-schema.mjs';

package/bin/astryx.mjs

@@ -13,21 +13,22 @@
 // `node-version.mjs` is intentionally dependency-free so it loads on the
 // unsupported runtimes this guard protects against.
 //
-// Sibling `src/` modules are resolved by this bin's REAL path. When the CLI is
-// installed as a package, `npx astryx` runs this file through the
-// `node_modules/.bin/astryx` symlink, and some Node versions resolve relative
-// specifiers from the symlink's directory (→ `node_modules/src/...`) rather
-// than the real package — breaking bare `../src/...` imports with a cryptic
-// ERR_MODULE_NOT_FOUND. realpath-ing `import.meta.url` makes these imports
-// resolve correctly however the bin is invoked (symlink, copy, or Windows
-// shim). Uses only built-ins, so the version gate below still runs first.
+// Sibling package modules (e.g. `cli/`, `lib/`) are resolved by this bin's REAL
+// path. When the CLI is installed as a package, `npx astryx` runs this file
+// through the `node_modules/.bin/astryx` symlink, and some Node versions resolve
+// relative specifiers from the symlink's directory rather than the real package
+// — breaking bare `../…` imports with a cryptic ERR_MODULE_NOT_FOUND.
+// realpath-ing `import.meta.url` makes these imports resolve correctly however
+// the bin is invoked (symlink, copy, or Windows shim). Uses only built-ins, so
+// the version gate below still runs first.
 import {fileURLToPath, pathToFileURL} from 'node:url';
 import {realpathSync} from 'node:fs';
 import {dirname, join} from 'node:path';
 
 const binDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+/** @param {string} rel */
 const importSrc = rel =>
-  import(pathToFileURL(join(binDir, '..', 'src', rel)).href);
+  import(pathToFileURL(join(binDir, '..', rel)).href);
 
 const {isNodeVersionSupported, unsupportedNodeMessage} =
   await importSrc('lib/node-version.mjs');
@@ -54,7 +55,7 @@ if (!isNodeVersionSupported(process.versions.node)) {
 
 // Imports that transitively load `styleText` must happen AFTER the gate above,
 // so they are dynamically imported here rather than at the top of the module.
-const {program} = await importSrc('index.mjs');
+const {program} = await importSrc('cli/index.mjs');
 const {isJsonMode, toErrorEnvelope} = await importSrc('lib/json.mjs');
 const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
 
@@ -72,6 +73,7 @@ function inJsonMode() {
   return isJsonMode() || process.argv.slice(2).includes('--json');
 }
 
+/** @param {unknown} err */
 function handleFatal(err) {
   // CommanderError (parse errors, --help, unknown command) routes
   // through the JSON shim so that a --json consumer always gets a

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

@@ -13,11 +13,44 @@
  *   astryx blog <slug>             Print a post as plaintext
  */
 
-import {getRunPrefix} from '../utils/package-manager.mjs';
-import {humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {blog as blogApi} from '../api/blog.mjs';
+import {getRunPrefix} from '../../utils/package-manager.mjs';
+import {humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {blog as blogApi} from '../../api/blog/blog.mjs';
 
+/**
+ * @typedef {object} BlogPost
+ * @property {string} slug
+ * @property {string} title
+ * @property {string} [description]
+ * @property {string} [date]
+ * @property {string} [type]
+ * @property {string[]} [authors]
+ * @property {string} [link]
+ * @property {string | null} [textUrl]
+ */
+
+/**
+ * @typedef {object} BlogListData
+ * @property {string} feedUrl
+ * @property {BlogPost[]} posts
+ */
+
+/**
+ * @typedef {BlogPost & {feedUrl: string, text: string}} BlogDetailData
+ */
+
+/**
+ * @typedef {(
+ *   | {type: 'blog.list', data: BlogListData}
+ *   | {type: 'blog.detail', data: BlogDetailData}
+ * )} BlogResult
+ */
+
+/**
+ * @param {BlogListData} data
+ * @param {string} run
+ */
 function formatList({feedUrl, posts}, run) {
   const lines = [`\nAstryx blog · feed: ${feedUrl}\n`];
   if (posts.length === 0) {
@@ -35,17 +68,25 @@ function formatList({feedUrl, posts}, run) {
   return lines.join('\n');
 }
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerBlog(program) {
   program
     .command('blog [slug]', {hidden: true})
     .description('Read the Astryx blog from the published feed')
-    .action(async slug => {
+    .action(async (/** @type {string | undefined} */ slug) => {
       const run = getRunPrefix();
+      /** @type {BlogResult} */
       let result;
       try {
-        result = await blogApi(slug);
+        result = /** @type {BlogResult} */ (await blogApi(slug));
       } catch (e) {
-        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;
       }