@astryxdesign/cli 0.2.0 → 0.3.0

package/api/docs/docs.mjs

@@ -30,9 +30,9 @@ export {list, detail, sectionLeaf as section};
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
  * @returns {Promise<
- *   import('../../types/docs').DocsListResponse |
- *   import('../../types/docs').DocsDetailResponse |
- *   import('../../types/docs').DocsDetailSectionResponse
+ *   import('./docs.type.mjs').DocsListResponse |
+ *   import('./docs.type.mjs').DocsDetailResponse |
+ *   import('./docs.type.mjs').DocsDetailSectionResponse
  * >}
  */
 export async function docs(topic, section, options = {}) {

package/api/docs/docs.test.mjs

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Dispatcher-level tests for docs() — the argument-shape routing that
+ * sits above the list/detail/section leaves. The leaves have their own tests;
+ * this pins the router: docs() -> list, docs(topic) -> detail,
+ * docs(topic, section) -> section, plus the unknown-topic/section error codes.
+ * Runs against the real CLI-bundled docs (no cwd/project needed).
+ */
+
+import {describe, it, expect} from 'vitest';
+import {docs} from './docs.mjs';
+import {AstryxError} from '../error.mjs';
+
+const SLOW = 30_000;
+
+describe('docs() dispatcher routing', () => {
+  it('no topic -> docs.list', async () => {
+    const r = await docs();
+    expect(r.type).toBe('docs.list');
+    expect(Array.isArray(r.data)).toBe(true);
+    expect(r.data.length).toBeGreaterThan(0);
+  }, SLOW);
+
+  it('empty topic -> docs.list (falsy topic routes to list)', async () => {
+    expect((await docs('')).type).toBe('docs.list');
+  }, SLOW);
+
+  it('topic only -> docs.detail', async () => {
+    const {data} = await docs();
+    const topic = data[0].topic;
+    const r = await docs(topic);
+    expect(r.type).toBe('docs.detail');
+  }, SLOW);
+
+  it('topic + section -> docs.detail.section', async () => {
+    const {data} = await docs();
+    let routed = null;
+    for (const {topic} of data) {
+      const detail = await docs(topic);
+      const sections = detail.data.sections;
+      if (Array.isArray(sections) && sections.length > 0) {
+        routed = await docs(topic, sections[0].title);
+        break;
+      }
+    }
+    expect(routed).not.toBeNull();
+    expect(routed.type).toBe('docs.detail.section');
+  }, SLOW);
+
+  it('unknown topic -> ERR_UNKNOWN_TOPIC', async () => {
+    await expect(docs('zzz-not-a-real-topic')).rejects.toBeInstanceOf(AstryxError);
+    await expect(docs('zzz-not-a-real-topic')).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_TOPIC',
+    });
+  }, SLOW);
+
+  it('known topic + unknown section -> ERR_UNKNOWN_SECTION', async () => {
+    const {data} = await docs();
+    const topic = data[0].topic;
+    await expect(docs(topic, 'zzz-not-a-real-section')).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_SECTION',
+    });
+  }, SLOW);
+
+  it('non-string topic -> ERR_UNKNOWN_TOPIC (not a raw TypeError)', async () => {
+    for (const bad of [123, {}, ['tokens'], true]) {
+      const err = await docs(/** @type {any} */ (bad)).catch(e => e);
+      expect(err).toBeInstanceOf(AstryxError);
+      expect(err.code).toBe('ERR_UNKNOWN_TOPIC');
+    }
+  }, SLOW);
+
+  it('non-string section -> ERR_UNKNOWN_SECTION (not a raw TypeError)', async () => {
+    const {data} = await docs();
+    const topic = data[0].topic;
+    for (const bad of [456, {}, ['x']]) {
+      const err = await docs(topic, /** @type {any} */ (bad)).catch(e => e);
+      expect(err).toBeInstanceOf(AstryxError);
+      expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    }
+  }, SLOW);
+});

package/api/docs/docs.type.d.mts

@@ -0,0 +1,36 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * xds --json docs
+ */
+export type DocsListResponse = {
+    type: "docs.list";
+    data: DocsListEntry[];
+};
+export type DocsListEntry = {
+    topic: string;
+    description: string;
+};
+/**
+ * xds --json docs <topic>
+ */
+export type DocsDetailResponse = {
+    type: "docs.detail";
+    data: import("@astryxdesign/cli/authoring").ReferenceDoc;
+};
+/**
+ * xds --json docs <topic> <section>
+ */
+export type DocsDetailSectionResponse = {
+    type: "docs.detail.section";
+    data: import("@astryxdesign/cli/authoring").ReferenceSection;
+};
+/**
+ * Options for `docs()`.
+ */
+export type DocsOptions = {
+    lang?: string | undefined;
+    zh?: boolean | undefined;
+    dense?: boolean | undefined;
+};

package/api/docs/docs.type.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated types for the `docs` command — source of truth for the docs
+ *   command JSON responses. `types/docs.d.ts` re-exports these.
+ *
+ *   Invocation                          -> type discriminator
+ *   ------------------------------------------------------------
+ *   xds --json docs                     -> docs.list
+ *   xds --json docs <topic>             -> docs.detail
+ *   xds --json docs <topic> <section>   -> docs.detail.section
+ *   (unknown topic/section)             -> CLIError
+ */
+
+/**
+ * xds --json docs
+ * @typedef {object} DocsListResponse
+ * @property {'docs.list'} type
+ * @property {DocsListEntry[]} data
+ */
+
+/**
+ * @typedef {object} DocsListEntry
+ * @property {string} topic
+ * @property {string} description
+ */
+
+/**
+ * xds --json docs <topic>
+ * @typedef {object} DocsDetailResponse
+ * @property {'docs.detail'} type
+ * @property {import('@astryxdesign/cli/authoring').ReferenceDoc} data
+ */
+
+/**
+ * xds --json docs <topic> <section>
+ * @typedef {object} DocsDetailSectionResponse
+ * @property {'docs.detail.section'} type
+ * @property {import('@astryxdesign/cli/authoring').ReferenceSection} data
+ */
+
+/**
+ * Options for `docs()`.
+ * @typedef {object} DocsOptions
+ * @property {string} [lang]
+ * @property {boolean} [zh]
+ * @property {boolean} [dense]
+ */
+
+export {};

package/api/docs/list/list.d.mts

@@ -0,0 +1,7 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
+ */
+export function list(): Promise<import("../docs.type.mjs").DocsListResponse>;

package/api/docs/list/list.mjs

@@ -3,7 +3,7 @@
 /**
  * @file docs.list leaf — enumerate the available reference-doc topics.
  *
- * @input Reads packages/cli/docs/{topic}.doc.mjs via the shared adapter's
+ * @input Reads packages/cli/assets/docs/{topic}.doc.mjs via the shared adapter's
  *   topic discovery. Each topic's English `description` is read directly; the
  *   listing never applies --dense/--zh overlays.
  * @output { type: 'docs.list', data: DocsListEntry[] } — one entry per topic,
@@ -15,11 +15,11 @@ import {pathToFileURL} from 'node:url';
 import {discoverTopics} from '../_adapter.mjs';
 
 /**
- * @returns {Promise<import('../../../types/docs').DocsListResponse>}
+ * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
  */
 export async function list() {
   const topics = discoverTopics();
-  /** @type {Array<import('../../../types/docs').DocsListEntry>} */
+  /** @type {Array<import('../docs.type.mjs').DocsListEntry>} */
   const entries = [];
   for (const [name, docPath] of Object.entries(topics)) {
     try {

package/api/docs/react-version-sync.test.mjs

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Keeps the documented React version requirement in sync with the peer
+ * dependency range declared by @astryxdesign/core (issue #4575: users must be
+ * able to discover the React 19 requirement without reading package.json).
+ *
+ * Runs against the real packages/core package.json, not mocks.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {docs as gettingStarted} from '../../assets/docs/getting-started.doc.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+
+// Every place that names the supported React version. The docsite hero
+// (apps/docsite/src/app/(site)/page.tsx) is deliberately not asserted —
+// landing-page copy is a design call — but it names the version today, so
+// sweep it whenever these assertions send you updating the rest.
+const SURFACES =
+  'update every surface that names the supported React version: README.md ' +
+  '(repo root), packages/core/README.md, ' +
+  'packages/cli/assets/docs/getting-started.doc.mjs, and the docsite hero ' +
+  'in apps/docsite/src/app/(site)/page.tsx';
+
+describe('documented React version matches the core peer dependency', () => {
+  const coreDir = findCoreDir();
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(coreDir, 'package.json'), 'utf-8'),
+  );
+  const reactRange = pkg.peerDependencies?.react;
+  if (typeof reactRange !== 'string') {
+    throw new Error(
+      '@astryxdesign/core no longer declares a react peer dependency; ' +
+        `${SURFACES}, then teach this test the new contract`,
+    );
+  }
+  const match = /\d+/.exec(reactRange);
+  if (!match) {
+    throw new Error(
+      `cannot read a major version from the react peer range "${reactRange}"; ` +
+        `${SURFACES}, then teach this test the new contract`,
+    );
+  }
+  const major = match[0];
+  // "React 19" but not "React 190"; also matches "React 19+".
+  const namesTheMajor = new RegExp(`React ${major}(?!\\d)`);
+
+  it('core declares matching react and react-dom peer ranges', () => {
+    expect(
+      pkg.peerDependencies['react-dom'],
+      `react and react-dom peer ranges diverged; if that is intentional, ${SURFACES}`,
+    ).toBe(reactRange);
+  });
+
+  it(`root README names React ${major}`, () => {
+    const readme = fs.readFileSync(path.join(REPO_ROOT, 'README.md'), 'utf-8');
+    expect(readme, SURFACES).toMatch(namesTheMajor);
+  });
+
+  it(`@astryxdesign/core README names React ${major}`, () => {
+    const readme = fs.readFileSync(path.join(coreDir, 'README.md'), 'utf-8');
+    expect(readme, SURFACES).toMatch(namesTheMajor);
+  });
+
+  it(`getting-started guide names React ${major} in prose`, () => {
+    const prose = gettingStarted.sections
+      .flatMap(section => section.content)
+      .filter(block => block.type === 'prose')
+      .map(block => block.text)
+      .join('\n');
+    expect(prose, SURFACES).toMatch(namesTheMajor);
+  });
+});

package/api/doctor/doctor.d.mts

@@ -0,0 +1,137 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Check 1 — running Node version meets the CLI's minimum.
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkNodeVersion(ctx: DoctorContext): DoctorCheck;
+/**
+ * Check 2 — @astryxdesign/core is installed and resolvable from the project.
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkCoreInstalled(ctx: DoctorContext): DoctorCheck;
+/**
+ * Check 3 — installed @astryxdesign/core is in step with @astryxdesign/cli (major/minor drift).
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkVersionAlignment(ctx: DoctorContext): DoctorCheck;
+/**
+ * Check 4 — at least one @astryxdesign/theme-* is installed and a theme is wired.
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkThemes(ctx: DoctorContext): DoctorCheck;
+/**
+ * Check 5 — astryx.config.mjs (if present) loads and has a valid shape.
+ * @param {DoctorContext} ctx
+ * @returns {Promise<DoctorCheck>}
+ */
+export function checkConfig(ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * Check 6 — agent docs exist and contain the Astryx section markers.
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkAgentDocs(ctx: DoctorContext): DoctorCheck;
+/**
+ * Check 7 — @astryxdesign/core peer dependencies are satisfied by installed packages.
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkPeerDeps(ctx: DoctorContext): DoctorCheck;
+/**
+ * Check 8 — report the detected package manager (informational).
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkPackageManager(ctx: DoctorContext): DoctorCheck;
+/**
+ * Run all diagnostic checks and return a structured report.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Directory to diagnose (default: process.cwd()).
+ * @returns {Promise<DoctorReport>}
+ */
+export function runChecks(options?: {
+    cwd?: string | undefined;
+}): Promise<DoctorReport>;
+/**
+ * Programmatic API: run the doctor and return the same envelope shape that
+ * `astryx doctor --json` emits.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @returns {Promise<{type: 'doctor', data: DoctorReport}>}
+ */
+export function doctor(options?: {
+    cwd?: string | undefined;
+}): Promise<{
+    type: "doctor";
+    data: DoctorReport;
+}>;
+/**
+ * Ordered list of synchronous check functions. Append here to add a check.
+ * (checkConfig is async and is awaited separately by {@link runChecks}.)
+ * @type {Array<(ctx: DoctorContext) => DoctorCheck>}
+ */
+export const SYNC_CHECKS: Array<(ctx: DoctorContext) => DoctorCheck>;
+export type DoctorStatus = "pass" | "warn" | "fail" | "info";
+export type DoctorCheck = {
+    /**
+     * - Stable machine-readable id (e.g. 'node-version').
+     */
+    id: string;
+    /**
+     * - Human-readable check name.
+     */
+    label: string;
+    status: DoctorStatus;
+    /**
+     * - One-line result summary.
+     */
+    message: string;
+    /**
+     * - Actionable remediation, present when not 'pass'.
+     */
+    fix?: string | undefined;
+};
+export type DoctorReport = {
+    checks: DoctorCheck[];
+    summary: {
+        pass: number;
+        warn: number;
+        fail: number;
+        info: number;
+    };
+};
+export type DoctorContext = {
+    /**
+     * - Directory to diagnose.
+     */
+    cwd: string;
+    /**
+     * - Running Node version.
+     */
+    nodeVersion: string;
+    /**
+     * - Resolved core package directory, or null.
+     */
+    coreDir: string | null;
+    /**
+     * - Resolved astryx.config.mjs path, or null.
+     */
+    configPath: string | null;
+    /**
+     * - theme value read from config, or null.
+     */
+    configTheme: string | null;
+    /**
+     * - Error thrown while resolving the config
+     * path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
+     */
+    configError?: Error | null | undefined;
+};

package/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, getCliInvocation} from '../../utils/package-manager.mjs';
-import {findConfigPath, Project} from '../../lib/project.mjs';
-import {semverCompare} from '../../utils/semver.mjs';
+import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/node-version.mjs';
+import {CLI_ROOT, findCoreDir} from '../../foundation/fs/paths.mjs';
+import {detectPackageManager, getCliInvocation} from '../../foundation/env/package-manager.mjs';
+import {findConfigPath, Project} from '../../foundation/config/project.mjs';
+import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
 
 const _require = createRequire(import.meta.url);
 
@@ -52,6 +52,8 @@ const _require = createRequire(import.meta.url);
  * @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.
+ * @property {Error|null} [configError] - Error thrown while resolving the config
+ *   path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
  */
 
 /* ── helpers ──────────────────────────────────────────────────────────── */
@@ -213,6 +215,22 @@ export function checkVersionAlignment(ctx) {
     };
   }
 
+  // A monorepo/linked install often pins a non-semver range like `workspace:*`
+  // or `link:...`. `'workspace:*'.split('.').map(Number)` yields NaN, and
+  // `NaN !== cliMajor` is always true — that produced a spurious drift WARN
+  // with a `NaN.undefined.x` fix string. If either version isn't real semver,
+  // there's nothing to compare: skip.
+  if (!isValidSemver(coreVersion) || !isValidSemver(cliVersion)) {
+    return {
+      id: 'version-alignment',
+      label: '@astryxdesign/core <-> @astryxdesign/cli alignment',
+      status: 'info',
+      message:
+        `Skipped — @astryxdesign/core v${coreVersion} / @astryxdesign/cli ` +
+        `v${cliVersion} are not both comparable semver.`,
+    };
+  }
+
   const [coreMajor, coreMinor] = coreVersion.split('.').map(Number);
   const [cliMajor, cliMinor] = cliVersion.split('.').map(Number);
   const drift = coreMajor !== cliMajor || coreMinor !== cliMinor;
@@ -282,6 +300,17 @@ export function checkThemes(ctx) {
  * @returns {Promise<DoctorCheck>}
  */
 export async function checkConfig(ctx) {
+  // A resolution error (e.g. multiple astryx.config.* files) is exactly the
+  // kind of setup problem doctor should report — not crash on.
+  if (ctx.configError) {
+    return {
+      id: 'config',
+      label: 'astryx.config.mjs',
+      status: 'fail',
+      message: ctx.configError.message,
+      fix: 'Keep exactly one astryx.config.{ts,mjs,js} at your project root.',
+    };
+  }
   if (!ctx.configPath) {
     return {
       id: 'config',
@@ -407,30 +436,53 @@ export function checkPeerDeps(ctx) {
   }
 
   const missing = [];
+  /** @type {Array<{name: string, want: string, have: string}>} */
+  const mismatched = [];
   for (const name of peerNames) {
-    let present = false;
+    const want = peers[name];
+    let pkgJsonPath;
     try {
-      _require.resolve(`${name}/package.json`, {paths: [ctx.cwd]});
-      present = true;
+      pkgJsonPath = _require.resolve(`${name}/package.json`, {paths: [ctx.cwd]});
     } catch {
-      // Some packages don't expose package.json — try resolving the entry.
+      // package.json isn't exported — fall back to entry resolution for
+      // presence only (we then can't read the version to range-check it).
       try {
         _require.resolve(name, {paths: [ctx.cwd]});
-        present = true;
       } catch {
-        // Still unresolved — leave present at its initial false.
+        missing.push(`${name}@${want}`);
       }
+      continue;
+    }
+    // Present and version-readable: verify it actually satisfies the range,
+    // not just that the package exists (a bare `npm install` can resolve an
+    // out-of-range version from a stale consumer range and still "look" fine).
+    const have = pkgVersion(path.dirname(pkgJsonPath));
+    if (have && !satisfiesRange(have, want)) {
+      mismatched.push({name, want, have});
     }
-    if (!present) missing.push(`${name}@${peers[name]}`);
   }
 
-  if (missing.length > 0) {
+  if (missing.length > 0 || mismatched.length > 0) {
+    const problems = [];
+    if (missing.length) problems.push(`missing: ${missing.join(', ')}`);
+    if (mismatched.length) {
+      problems.push(
+        `out of range: ${mismatched
+          .map(m => `${m.name}@${m.have} (needs ${m.want})`)
+          .join(', ')}`,
+      );
+    }
+    // Pin the required range for anything wrong so the hint fixes it even when a
+    // stale consumer range would otherwise resolve an incompatible version.
+    // Quote targets containing shell metacharacters (e.g. `react@>=19.0.0`).
+    const quote = (/** @type {string} */ s) => (/[<>|() ]/.test(s) ? `'${s}'` : s);
+    const targets = [...missing, ...mismatched.map(m => `${m.name}@${m.want}`)].map(quote);
     return {
       id: 'peer-deps',
       label: '@astryxdesign/core peer dependencies',
       status: 'warn',
-      message: `Missing peer dependencies: ${missing.join(', ')}.`,
-      fix: `Install the required peers, e.g. \`npm install ${missing.map(m => m.split('@')[0]).join(' ')}\`.`,
+      message: `Peer dependency issues — ${problems.join('; ')}.`,
+      fix: `Install compatible peers: \`npm install ${targets.join(' ')}\`.`,
     };
   }
 
@@ -485,7 +537,16 @@ export const SYNC_CHECKS = [
 export async function runChecks(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const coreDir = findCoreDir(cwd);
-  const configPath = findConfigPath(cwd);
+  // findConfigPath throws when multiple config files coexist. That's a
+  // misconfiguration doctor exists to report — catch it and surface it through
+  // checkConfig as a FAIL rather than crashing the whole diagnostic engine.
+  let configPath = null;
+  let configError = null;
+  try {
+    configPath = findConfigPath(cwd);
+  } catch (err) {
+    configError = /** @type {Error} */ (err);
+  }
 
   // Resolve a possible theme key from config (best-effort; never throws).
   let configTheme = null;
@@ -504,6 +565,7 @@ export async function runChecks(options = {}) {
     coreDir,
     configPath,
     configTheme,
+    configError,
   };
 
   /** @type {DoctorCheck[]} */