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

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

@@ -1,46 +1,26 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file build command — the page-building assistant.
+ * @file build command — thin wrapper around api/build.
  *
- * Two modes:
- *   astryx build                  → the PLAYBOOK: how to build a page with Astryx
- *   astryx build "<what>"         → a COMPOSITION KIT for what you're building:
- *                                   the closest page template (scaffold or layout
- *                                   reference), the blocks that cover parts, and
- *                                   the components to fill gaps, plus a one-line
- *                                   "Compose:" suggestion.
+ *   astryx build                  → the PLAYBOOK (how to build a page)
+ *   astryx build "<what>"         → a COMPOSITION KIT (closest page template,
+ *                                   blocks, components) with a recommended START.
  *
- * `build` is the opinionated "assemble a page" verb. For a neutral lookup across
- * the whole CLI, use `astryx search <query>` instead.
+ * All grouping/scoring lives in api/build; this file only parses flags and
+ * renders. Command strings are prefixed for the caller's package manager here
+ * (never in the API payload) via formatCliCommand/getCliInvocation.
  */
 
-import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {search as searchApi} from '../api/search.mjs';
-
-/** A page scoring at/above this is confident enough to call a direct match. */
-const PAGE_DIRECT = 95;
-/** Below this a page is too weak to even offer as a layout reference. */
-const PAGE_FLOOR = 50;
-/** Below this a block/domain-component match is incidental noise, not surfaced. */
-const DOMAIN_FLOOR = 55;
+import {getCliInvocation, formatCliCommand} from '../../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {build as buildApi} from '../../api/build/build.mjs';
 
 /**
- * Always-surfaced primitives. Every page needs a shell + layout/typography/
- * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
- * so search alone never returns them. We list them unconditionally so an agent
- * composing from scratch has the whole kit (esp. off-template).
+ * Print the build playbook (shown when `build` is run with no query).
+ * @param {string} run - The CLI invocation prefix (e.g. `npx astryx`).
  */
-const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
-const FOUNDATION = [
-  'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
-  'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
-];
-const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
-
-/** Print the build playbook (shown when `build` is run with no query). */
 function printPlaybook(run) {
   const lines = [
     '',
@@ -71,6 +51,9 @@ function printPlaybook(run) {
   for (const l of lines) humanLog(l);
 }
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerBuild(program) {
   program
     .command('build [query]')
@@ -78,18 +61,19 @@ export function registerBuild(program) {
     .option('--type <domain>', 'Filter the kit to one domain (component|hook|template)')
     .option('--limit <n>', 'Max candidates to draw from (default 60)')
     .option('--detail', 'Verbose output (include import paths and match reason)')
-    .action(async (query, options) => {
+    .action(async (/** @type {string | undefined} */ query, /** @type {{type?: import('../../types/search').SearchDomain, limit?: string, detail?: boolean}} */ options) => {
       const run = getCliInvocation();
       const json = program.opts().json || false;
 
-      // No query → print the playbook (the "how to build" skill).
+      // No query → the playbook. Still routed through the API for the envelope.
       if (!query || !String(query).trim()) {
-        if (json) return jsonOut('build.help', {playbook: true});
+        const result = await buildApi(undefined, {cwd: process.cwd()});
+        if (json) return jsonOut(result.type, result.data);
         printPlaybook(run);
         return;
       }
 
-      // Default to a deep pool so each role section has candidates after grouping.
+      // Arg validation stays in the CLI.
       let limit = 60;
       if (options.limit != null) {
         const parsed = Number.parseInt(options.limit, 10);
@@ -100,19 +84,24 @@ export function registerBuild(program) {
         limit = parsed;
       }
 
+      /** @type {import('../../types/build').BuildKitResponse} */
       let result;
       try {
-        result = await searchApi(query, {cwd: process.cwd(), type: options.type, limit});
+        result = /** @type {import('../../types/build').BuildKitResponse} */ (
+          await buildApi(query, {cwd: process.cwd(), type: options.type, limit})
+        );
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions});
         return;
       }
 
       if (json) return jsonOut(result.type, result.data);
 
-      const {query: q, results} = result.data;
+      const {query: q, hasResults, directMatch, pages, blocks, domain, frame, foundation} =
+        result.data;
 
-      if (results.length === 0) {
+      if (!hasResults) {
         humanLog('');
         humanLog(`No matches for "${q}".`);
         humanLog(`Try a broader term, or browse: ${run} component --list`);
@@ -120,20 +109,7 @@ export function registerBuild(program) {
         return;
       }
 
-      // ── Group results by role (the build kit) ──────────────────────
-      const pages = results
-        .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
-        .slice(0, 3);
-      const blocks = results
-        .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
-        .slice(0, 5);
-      // Idea-specific atoms = matched components/hooks MINUS the always-on kit.
-      const domain = results
-        .filter(r => (r.domain === 'component' || r.domain === 'hook') && r.score >= DOMAIN_FLOOR && !ALWAYS.has(r.name))
-        .slice(0, 6);
-      const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
-
-      const printItem = (r, label) => {
+      const printItem = (/** @type {import('../../types/search').SearchResultEntry} */ r, /** @type {string} */ label) => {
         const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
         humanLog('');
         humanLog(`  [${label}] ${display}`);
@@ -167,7 +143,7 @@ export function registerBuild(program) {
 
       // FRAME — always (the page shell).
       humanLog('');
-      humanLog(`FRAME — page shell (always): ${FRAME.join(', ')}`);
+      humanLog(`FRAME — page shell (always): ${frame.join(', ')}`);
       humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} component AppShell`);
 
       // BLOCKS — idea-specific composed patterns.
@@ -186,7 +162,7 @@ export function registerBuild(program) {
 
       // FOUNDATION — always (layout/typography/actions).
       humanLog('');
-      humanLog(`FOUNDATION — always available (layout/text/actions): ${FOUNDATION.join(' ')}`);
+      humanLog(`FOUNDATION — always available (layout/text/actions): ${foundation.join(' ')}`);
 
       // SETUP — so it renders / stays on-system.
       humanLog('');

package/{src → cli}/commands/component/index.mjs

@@ -6,27 +6,47 @@
  * Global options: --detail full|compact|brief, --lang en|zh|dense
  */
 
-import {findCoreDir} from '../../utils/paths.mjs';
+import {findCoreDir} from '../../../utils/paths.mjs';
 import {
   resolveImportPath,
-} from '../../lib/component-discovery.mjs';
+} from '../../../lib/component-discovery.mjs';
 import {
   formatFull,
   formatCompact,
   formatBrief,
   formatProps,
   formatBriefAll,
-} from '../../lib/component-format.mjs';
-import {resolveTheme} from '../../lib/resolve-theme.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 {component as componentApi} from '../../api/component.mjs';
-import {findRelatedBlocks} from '../../api/template.mjs';
-import {Project} from '../../lib/project.mjs';
-import {warnOnIntegrationIssues} from '../../lib/integration-warnings.mjs';
+} from '../../../lib/component-format.mjs';
+import {resolveTheme} from '../../../lib/resolve-theme.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 {component as componentApi} from '../../../api/component/component.mjs';
+import {findRelatedBlocks} from '../../../api/template/template.mjs';
+import {Project} from '../../../lib/project.mjs';
+import {warnOnIntegrationIssues} from '../../../lib/integration-warnings.mjs';
 
+/**
+ * The api layer's component() widens its return to `{type: string, data: unknown}`,
+ * so annotate the command-local result with the precise discriminated union from
+ * src/types/component to get narrowing + typed data.
+ *
+ * @typedef {(
+ *   | import('../../../types/component').ComponentListResponse
+ *   | import('../../../types/component').ComponentBriefResponse
+ *   | import('../../../types/component').ComponentFullResponse
+ *   | import('../../../types/component').ComponentDetailResponse
+ *   | import('../../../types/component').ComponentDetailPropsResponse
+ *   | import('../../../types/component').ComponentDetailSourceResponse
+ *   | import('../../../types/component').ComponentDetailShowcaseResponse
+ *   | import('../../../types/component').ComponentDetailBlocksResponse
+ * )} ComponentResult
+ */
+
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerComponent(program) {
   program
     .command('component [name]')
@@ -38,7 +58,7 @@ export function registerComponent(program) {
     .option('--showcase', 'Print showcase source code')
     .option('--blocks', 'List example blocks: showcase, examples, and related')
     .option('--package <name>', 'Scope lookup to an external package (e.g. @acme/xds-widgets)')
-    .action(async (name, options) => {
+    .action(async (/** @type {string | undefined} */ name, /** @type {{list?: boolean, category?: string, props?: boolean, source?: boolean, showcase?: boolean, blocks?: boolean, package?: string}} */ options) => {
       const run = getCliInvocation();
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
@@ -67,9 +87,10 @@ export function registerComponent(program) {
         // Never let the nudge break the command.
       }
 
+      /** @type {ComponentResult} */
       let result;
       try {
-        result = await componentApi(name, {
+        result = /** @type {ComponentResult} */ (await componentApi(name, {
           cwd: process.cwd(),
           list: options.list,
           category: options.category,
@@ -80,16 +101,19 @@ export function registerComponent(program) {
           blocks: options.blocks,
           detail,
           lang, zh, dense,
-        });
+        }));
       } 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;
       }
 
       if (json) return jsonOut(result.type, result.data);
 
       // ── Text output ────────────────────────────────────────────
-      const coreDir = findCoreDir(process.cwd());
+      // The api layer already resolved against core (result exists), so core is
+      // present on this path; narrow away the null branch findCoreDir allows.
+      const coreDir = /** @type {string} */ (findCoreDir(process.cwd()));
       const themeData = resolveTheme(process.cwd());
 
       switch (result.type) {
@@ -101,6 +125,7 @@ export function registerComponent(program) {
           const CORE_PKG = '@astryxdesign/core';
           // Names that appear under more than one package across the whole
           // listing — these must always be package-qualified to disambiguate.
+          /** @type {Map<string, Set<string>>} */
           const nameCounts = new Map();
           for (const items of Object.values(result.data)) {
             for (const item of items) {
@@ -109,7 +134,9 @@ export function registerComponent(program) {
               nameCounts.set(item.name, set);
             }
           }
+          /** @param {string} n */
           const isCollision = n => (nameCounts.get(n)?.size ?? 0) > 1;
+          /** @param {import('../../../types/component').ComponentListEntry} item */
           const pkgSuffix = item => {
             if (item.package !== CORE_PKG) return `  [${item.package}]`;
             if (isCollision(item.name)) return `  [${item.package}]`;
@@ -251,8 +278,8 @@ export function registerComponent(program) {
 
 // Re-export lib functions for backward compatibility
 // (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)
-export {discoverComponents, discoverExternalComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../lib/component-discovery.mjs';
-export {discoverExternalPackages} from '../../utils/paths.mjs';
-export {loadDocs} from '../../lib/component-loader.mjs';
-export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
-export {levenshteinDistance, findClosestComponents, searchComponents} from '../../lib/string-utils.mjs';
+export {discoverComponents, discoverExternalComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../../lib/component-discovery.mjs';
+export {discoverExternalPackages} from '../../../utils/paths.mjs';
+export {loadDocs} from '../../../lib/component-loader.mjs';
+export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../../lib/component-format.mjs';
+export {levenshteinDistance, findClosestComponents, searchComponents} from '../../../lib/string-utils.mjs';

package/{src → cli}/commands/component-ownership.test.mjs

@@ -10,7 +10,7 @@ import {
   findIntegrationComponentDoc,
   findIntegrationComponentSource,
   CORE_PACKAGE,
-} from '../lib/component-discovery.mjs';
+} from '../../lib/component-discovery.mjs';
 
 // The api `component()` reads integrations via Project.load(). In the vitest
 // environment, Vite's `server.fs.allow` only permits loading modules from
@@ -20,12 +20,12 @@ import {
 // produces) while keeping the integration's `components` dir on disk under
 // node_modules so its `.doc.mjs` files load normally.
 const projectLoadMock = vi.fn();
-vi.mock('../lib/project.mjs', () => ({
+vi.mock('../../lib/project.mjs', () => ({
   Project: {load: (...args) => projectLoadMock(...args)},
 }));
 
 // Import the api AFTER the mock is registered.
-const {component} = await import('../api/component.mjs');
+const {component} = await import('../../api/component/component.mjs');
 
 let tmpDir;
 

package/{src → cli}/commands/component-package.test.mjs

@@ -4,7 +4,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {component} from '../api/component.mjs';
+import {component} from '../../api/component/component.mjs';
 
 // These tests create a minimal monorepo fixture with:
 // - packages/core (symlinked to real @astryxdesign/core for loadDocs compatibility)

package/{src → cli}/commands/component-resolution.test.mjs

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {component} from '../api/component.mjs';
-import {findShowcase, findRelatedBlocks} from '../api/template.mjs';
+import {component} from '../../api/component/component.mjs';
+import {findShowcase, findRelatedBlocks} from '../../api/template/template.mjs';
 
 const CWD = {cwd: '.'};
 

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

@@ -10,18 +10,26 @@
  *   astryx discover searchterm                Search across all packages
  */
 
-import {formatFull, formatBrief, formatCompact} from '../lib/component-format.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {discover as discoverApi} from '../api/discover.mjs';
-import {getCliInvocation} from '../utils/package-manager.mjs';
+import {formatFull, formatBrief, formatCompact} from '../../lib/component-format.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {discover as discoverApi} from '../../api/discover/discover.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerDiscover(program) {
   program
     .command('discover [query]')
     .description('Discover external packages and components')
     .option('--components', 'List components only')
-    .action(async (query, options) => {
+    .action(
+      /**
+       * @param {string | undefined} query
+       * @param {{components?: boolean}} options
+       */
+      async (query, options) => {
       const detail = program.opts().detail || 'full';
       const json = program.opts().json || false;
       const lang = program.opts().lang || null;
@@ -32,7 +40,8 @@ export function registerDiscover(program) {
       try {
         result = await discoverApi(query, {components: options.components, lang, zh});
       } 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;
       }
 
@@ -40,7 +49,7 @@ export function registerDiscover(program) {
         // Forward optional meta (e.g. configured flag for discover.list) as a
         // sibling of data via jsonOut, so the envelope still carries
         // apiVersion and goes through the single sanctioned emit path.
-        return jsonOut(result.type, result.data, result.meta);
+        return jsonOut(result.type, result.data, 'meta' in result ? result.meta : undefined);
       }
 
       switch (result.type) {

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

@@ -12,13 +12,18 @@
  *   astryx docs <topic> <section>        Print one section
  */
 
-import {getCliInvocation} from '../utils/package-manager.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {docs as docsApi} from '../api/docs.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {docs as docsApi} from '../../api/docs/docs.mjs';
 
 // ─── Formatting ──────────────────────────────────────────────────────────────
 
+/**
+ * @param {string[]} headers
+ * @param {string[][]} rows
+ * @returns {string}
+ */
 function formatTable(headers, rows) {
   const widths = headers.map((h, i) =>
     Math.max(h.length, ...rows.map(r => (r[i] || '').length)),
@@ -31,15 +36,28 @@ function formatTable(headers, rows) {
   return `${head}\n${sep}\n${body}`;
 }
 
+/**
+ * @param {string[]} headers
+ * @param {string[][]} rows
+ * @returns {string}
+ */
 function formatTableCompact(headers, rows) {
   return rows.map(r => r.join(' = ')).join('\n');
 }
 
+/**
+ * @param {import('../../../core/src/docs-types').ContentBlock} block
+ * @param {'full' | 'compact' | 'brief'} detail
+ * @returns {string | null}
+ */
 function formatBlock(block, detail) {
   switch (block.type) {
     case 'prose':
       return block.text;
 
+    case 'heading':
+      return `${'#'.repeat(block.level || 3)} ${block.text}`;
+
     case 'code':
       if (detail === 'compact' || detail === 'brief') return null;
       {
@@ -57,7 +75,7 @@ function formatBlock(block, detail) {
       return formatTable(block.headers, block.rows);
 
     case 'list': {
-      const prefix = block.style === 'ordered' ? (i) => `${i + 1}. `
+      const prefix = block.style === 'ordered' ? (/** @type {number} */ i) => `${i + 1}. `
         : block.style === 'dont' ? () => '❌ '
         : block.style === 'do' ? () => '✓ '
         : () => '- ';
@@ -69,6 +87,11 @@ function formatBlock(block, detail) {
   }
 }
 
+/**
+ * @param {import('../../../core/src/docs-types').ReferenceSection} section
+ * @param {'full' | 'compact' | 'brief'} detail
+ * @returns {string}
+ */
 function formatSection(section, detail) {
   const blocks = section.content
     .map(b => formatBlock(b, detail))
@@ -83,6 +106,11 @@ function formatSection(section, detail) {
   return `${heading}\n\n${blocks.join('\n\n')}`;
 }
 
+/**
+ * @param {import('../../../core/src/docs-types').ReferenceDoc} docs
+ * @param {'full' | 'compact' | 'brief'} detail
+ * @returns {string}
+ */
 function formatReferenceFull(docs, detail) {
   if (detail === 'brief') {
     const header = `${docs.title}: ${docs.description}`;
@@ -100,11 +128,14 @@ function formatReferenceFull(docs, detail) {
 
 // ─── Command ─────────────────────────────────────────────────────────────────
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerDocs(program) {
   program
     .command('docs [topic] [section]')
     .description('Print reference docs')
-    .action(async (topic, section) => {
+    .action(async (/** @type {string | undefined} */ topic, /** @type {string | undefined} */ section) => {
       const run = getCliInvocation();
       const lang = program.opts().lang || null;
       const zh = program.opts().zh || false;
@@ -118,7 +149,8 @@ export function registerDocs(program) {
       } catch (e) {
         // docs 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;
       }
 

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

@@ -71,7 +71,7 @@ describe('hyphenated doc filenames', () => {
   });
 
   it('returns docs.detail via API for hyphenated topic', async () => {
-    const {docs: docsApi} = await import('../api/docs.mjs');
+    const {docs: docsApi} = await import('../../api/docs/docs.mjs');
     const result = await docsApi('getting-started');
     expect(result.type).toBe('docs.detail');
     expect(result.data).toBeDefined();

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

@@ -10,8 +10,8 @@
  * as a CI gate.
  */
 
-import {runChecks} from '../api/doctor.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
+import {runChecks} from '../../api/doctor/doctor.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
 
 /** Status → human glyph (monochrome, matching the rest of the CLI). */
 const GLYPH = {
@@ -23,7 +23,7 @@ const GLYPH = {
 
 /**
  * Render the report as a human-readable checklist.
- * @param {import('../api/doctor.mjs').DoctorReport} report
+ * @param {import('../../api/doctor/doctor.mjs').DoctorReport} report
  */
 function printHuman(report) {
   humanLog('astryx doctor — diagnosing your setup\n');

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

@@ -19,8 +19,8 @@ import {
   checkAgentDocs,
   checkPeerDeps,
   checkPackageManager,
-} from '../api/doctor.mjs';
-import {MIN_NODE_VERSION} from '../lib/node-version.mjs';
+} from '../../api/doctor/doctor.mjs';
+import {MIN_NODE_VERSION} from '../../lib/node-version.mjs';
 
 let tmpDir;
 let logCalls;

package/{src → cli}/commands/ensure-core-built.mjs

@@ -40,6 +40,7 @@ const BUILD_TIMEOUT_MS = 180_000;
 const STALE_LOCK_MS = BUILD_TIMEOUT_MS + 20_000;
 const POLL_MS = 250;
 
+/** @param {number} ms */
 function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -67,7 +68,7 @@ function tryAcquire() {
     fs.mkdirSync(LOCK_DIR);
     return true;
   } catch (err) {
-    if (err.code !== 'EEXIST') {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code !== 'EEXIST') {
       throw err;
     }
     if (lockIsStale()) {
@@ -76,7 +77,7 @@ function tryAcquire() {
         fs.mkdirSync(LOCK_DIR);
         return true;
       } catch (retryErr) {
-        if (retryErr.code !== 'EEXIST') {
+        if (/** @type {NodeJS.ErrnoException} */ (retryErr).code !== 'EEXIST') {
           throw retryErr;
         }
       }

package/{src → cli}/commands/external-showcase.test.mjs

@@ -4,7 +4,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {findShowcase, findRelatedBlocks} from '../api/template.mjs';
+import {findShowcase, findRelatedBlocks} from '../../api/template/template.mjs';
 
 // These tests verify that findShowcase and findRelatedBlocks can discover
 // blocks from external packages that declare xds.blocks in package.json.