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

package/{src/commands → lib/agent-docs}/agent-docs.test.mjs

@@ -16,6 +16,8 @@ import {
   removeXdsBlock,
   discoverAgentDocs,
   resolveAgentPaths,
+  parseBlockVersion,
+  inspectAgentDocs,
 } from './agent-docs.mjs';
 
 let tmpDir;
@@ -88,17 +90,24 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/after any @astryxdesign\/core bump/);
   });
 
-  it('states the runPrefix once in the CLI header', () => {
-    const result = generateCompressedIndex('1.0.0', {runPrefix: 'yarn'});
+  it('states the invocation once in the CLI header (yarn)', () => {
+    const result = generateCompressedIndex('1.0.0', {invocation: 'yarn astryx'});
     expect(result).toContain('yarn astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
 
-  it('uses pnpm exec prefix', () => {
-    const result = generateCompressedIndex('1.0.0', {runPrefix: 'pnpm exec'});
+  it('uses the pnpm exec invocation', () => {
+    const result = generateCompressedIndex('1.0.0', {invocation: 'pnpm exec astryx'});
     expect(result).toContain('pnpm exec astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
+
+  it('uses the scoped package for one-off (uninstalled) runs so agents never hit the bare name', () => {
+    const result = generateCompressedIndex('1.0.0', {invocation: 'npx @astryxdesign/cli'});
+    expect(result).toContain('npx @astryxdesign/cli <cmd>');
+    // The header defines the mapping; the bare "run every command as `npx astryx`" footgun must be absent.
+    expect(result).not.toContain('npx astryx <cmd>');
+  });
 });
 
 describe('detectStylingSystem', () => {
@@ -389,18 +398,37 @@ describe('installAgentDocs', () => {
     );
   }
 
-  it('creates .claude/CLAUDE.md when no agent docs exist', () => {
+  it('creates AGENTS.md when no agent docs exist (tool-agnostic default)', () => {
     setupCorePackage(tmpDir);
 
     const written = installAgentDocs(tmpDir);
 
-    expect(written).toEqual(['.claude/CLAUDE.md']);
-    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);
-    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
-    const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
+    expect(written).toEqual(['AGENTS.md']);
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
+    // Must NOT create the Claude-specific file by default.
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toContain('# AGENTS.md');
     expect(content).toContain('<!-- ASTRYX:START -->');
   });
 
+  it('defaults to AGENTS.md but writes .claude/CLAUDE.md only when --agent claude is explicit', () => {
+    // Default (no agent): tool-agnostic AGENTS.md, never the Claude file.
+    setupCorePackage(tmpDir);
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md']);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+
+    // Explicit Claude: the Claude-specific file, in a fresh project.
+    const claudeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-claude-'));
+    setupCorePackage(claudeDir);
+    try {
+      expect(installAgentDocs(claudeDir, {agent: 'claude'})).toEqual(['.claude/CLAUDE.md']);
+      expect(fs.existsSync(path.join(claudeDir, 'AGENTS.md'))).toBe(false);
+    } finally {
+      fs.rmSync(claudeDir, {recursive: true, force: true});
+    }
+  });
+
   it('injects into CLAUDE.md at root when it exists', () => {
     setupCorePackage(tmpDir);
     fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');
@@ -517,12 +545,13 @@ describe('installAgentDocs', () => {
     expect(content).toContain('Other rules.');
   });
 
-  it('onlyReplace: does not create default .claude/CLAUDE.md when nothing exists', () => {
+  it('onlyReplace: does not create the default AGENTS.md when nothing exists', () => {
     setupCorePackage(tmpDir);
 
     const written = installAgentDocs(tmpDir, {onlyReplace: true});
 
     expect(written).toEqual([]);
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
     expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
   });
 });
@@ -602,3 +631,87 @@ describe('resolveAgentPaths', () => {
     expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});
   });
 });
+
+describe('parseBlockVersion', () => {
+  it('reads the version from the header of a generated block', () => {
+    expect(parseBlockVersion(generateCompressedIndex('1.2.3'))).toBe('1.2.3');
+  });
+
+  it('reads prerelease versions', () => {
+    expect(parseBlockVersion('Astryx v1.2.3-beta.4 · 10 components')).toBe(
+      '1.2.3-beta.4',
+    );
+  });
+
+  it('returns null when no versioned header is present', () => {
+    expect(parseBlockVersion('<!-- XDS:START -->\nold\n<!-- XDS:END -->')).toBeNull();
+    expect(parseBlockVersion('')).toBeNull();
+    expect(parseBlockVersion(undefined)).toBeNull();
+  });
+});
+
+describe('inspectAgentDocs', () => {
+  function writeBlock(rel, version) {
+    const filePath = path.join(tmpDir, rel);
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    fs.writeFileSync(filePath, `# Doc\n\n${generateCompressedIndex(version)}\n`);
+  }
+
+  it('reports missing when no agent docs exist at all', () => {
+    const res = inspectAgentDocs(tmpDir, '1.0.0');
+    expect(res.status).toBe('missing');
+    expect(res.files).toEqual([]);
+    expect(res.staleFiles).toEqual([]);
+  });
+
+  it('reports missing when agent files exist but carry no Astryx marker', () => {
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nHand-written notes.\n');
+    expect(inspectAgentDocs(tmpDir, '1.0.0').status).toBe('missing');
+  });
+
+  it('reports current when the only block matches the installed version', () => {
+    writeBlock('AGENTS.md', '1.0.0');
+    const res = inspectAgentDocs(tmpDir, '1.0.0');
+    expect(res.status).toBe('current');
+    expect(res.staleFiles).toEqual([]);
+    expect(res.blockVersions).toEqual([]);
+  });
+
+  it('reports stale (with the old version) when the block is behind', () => {
+    writeBlock('AGENTS.md', '1.0.0');
+    const res = inspectAgentDocs(tmpDir, '2.0.0');
+    expect(res.status).toBe('stale');
+    expect(res.staleFiles).toEqual(['AGENTS.md']);
+    expect(res.blockVersions).toEqual(['1.0.0']);
+    expect(res.installedVersion).toBe('2.0.0');
+  });
+
+  it('treats a legacy XDS block as stale even with no parseable version', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\n<!-- XDS:START -->\nlegacy index\n<!-- XDS:END -->\n',
+    );
+    const res = inspectAgentDocs(tmpDir, '1.0.0');
+    expect(res.status).toBe('stale');
+    expect(res.files[0].legacy).toBe(true);
+    expect(res.blockVersions).toEqual([]);
+  });
+
+  it('is stale if ANY marked file is behind (mixed current + stale)', () => {
+    writeBlock('AGENTS.md', '2.0.0');
+    writeBlock('CLAUDE.md', '1.0.0');
+    const res = inspectAgentDocs(tmpDir, '2.0.0');
+    expect(res.status).toBe('stale');
+    expect(res.staleFiles).toEqual(['CLAUDE.md']);
+  });
+
+  it('defaults the installed version to the core package when omitted', () => {
+    const coreDir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(coreDir, {recursive: true});
+    fs.writeFileSync(path.join(coreDir, 'package.json'), JSON.stringify({version: '3.0.0'}));
+    writeBlock('AGENTS.md', '3.0.0');
+    const res = inspectAgentDocs(tmpDir);
+    expect(res.installedVersion).toBe('3.0.0');
+    expect(res.status).toBe('current');
+  });
+});

package/{src/lib → lib}/cli-error.mjs

@@ -55,8 +55,8 @@ import {ERROR_CODES} from './error-codes.mjs';
 
 /**
  * Suggestion object — matches the shape used by API errors and the JSON
- * envelope's `suggestions` field.
- * @typedef {{name: string, reason?: string}} Suggestion
+ * envelope's `suggestions` field. Canonical definition lives in types/base.
+ * @typedef {import('../types/base').Suggestion} Suggestion
  */
 
 /**

package/{src/lib → lib}/component-discovery.mjs

@@ -77,12 +77,15 @@ const HIDDEN_RE = /(?:^|\n) {0,4}hidden:\s*true/;
 /**
  * Read the `group`, `hiddenComponents`, and `hidden` fields from a
  * component's .doc.mjs file (synchronous).
+ * @param {string} docPath
+ * @returns {{group: string | null, hiddenComponents: Set<string>, hidden: boolean}}
  */
 function readDocMeta(docPath) {
   try {
     const content = fs.readFileSync(docPath, 'utf-8');
     const groupMatch = GROUP_RE.exec(content);
     const hiddenCompsMatch = HIDDEN_COMPONENTS_RE.exec(content);
+    /** @type {Set<string>} */
     const hiddenSet = new Set();
     if (hiddenCompsMatch) {
       for (const m of hiddenCompsMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {
@@ -109,13 +112,20 @@ function readDocMeta(docPath) {
  *
  * Keys are sorted alphabetically (groups and ungrouped components interleaved).
  * Components within each group are also sorted alphabetically.
+ * @param {string} coreDir
+ * @returns {Record<string, string[]>}
  */
 export function discoverComponents(coreDir) {
   const srcDir = path.join(coreDir, 'src');
   /** @type {Map<string, string|null>} componentName → group */
   const componentGroups = new Map();
 
+  /**
+   * @param {string} dirPath
+   * @returns {string[]}
+   */
   function collectXDSFiles(dirPath) {
+    /** @type {string[]} */
     const results = [];
     if (!fs.existsSync(dirPath)) return results;
     const entries = fs.readdirSync(dirPath, {withFileTypes: true});
@@ -185,7 +195,7 @@ export function discoverComponents(coreDir) {
   for (const [name, group] of componentGroups) {
     if (group) {
       if (!groups.has(group)) groups.set(group, []);
-      groups.get(group).push(name);
+      groups.get(group)?.push(name);
     } else {
       ungrouped.push(name);
     }
@@ -220,6 +230,9 @@ export function discoverComponents(coreDir) {
  * Find the .doc.mjs file for a component.
  * For sub-components (e.g. StackItem), returns the parent's .doc.mjs
  * if the sub-component is documented there.
+ * @param {string} coreDir
+ * @param {string} name
+ * @returns {string | null}
  */
 export function findComponentReadme(coreDir, name) {
   const srcDir = path.join(coreDir, 'src');
@@ -278,6 +291,9 @@ export function findComponentReadme(coreDir, name) {
  * `useResizable.ts`), so `.ts` candidates are searched alongside `.tsx`. Without
  * this, deriving the import path for a `.ts`-authored function falls back to the
  * bare `@astryxdesign/core` root instead of its tree-shakeable subpath.
+ * @param {string} coreDir
+ * @param {string} name
+ * @returns {string | null}
  */
 export function findComponentSource(coreDir, name) {
   const srcDir = path.join(coreDir, 'src');
@@ -292,6 +308,10 @@ export function findComponentSource(coreDir, name) {
     `${name}.ts`,
   ];
 
+  /**
+   * @param {string} dirPath
+   * @returns {string | null}
+   */
   function searchDir(dirPath) {
     if (!fs.existsSync(dirPath)) return null;
     const entries = fs.readdirSync(dirPath, {withFileTypes: true});
@@ -337,6 +357,9 @@ export function findComponentSource(coreDir, name) {
 /**
  * Compute the Levenshtein (edit) distance between two strings.
  * Used for fuzzy-matching component names. Dependency-free.
+ * @param {string} coreDir
+ * @param {string} componentName
+ * @returns {string}
  */
 export function resolveImportPath(coreDir, componentName) {
   const srcDir = path.join(coreDir, 'src');
@@ -376,11 +399,15 @@ export function resolveImportPath(coreDir, componentName) {
  * Scans for *.doc.mjs files and returns their names as a flat array.
  *
  * @deprecated Use discoverExternalComponentsGrouped for group-aware discovery.
+ * @param {string} docsDir
+ * @returns {string[]}
  */
 export function discoverExternalComponents(docsDir) {
   if (!fs.existsSync(docsDir)) return [];
+  /** @type {string[]} */
   const components = [];
 
+  /** @param {string} dirPath */
   function scanDir(dirPath) {
     const entries = fs.readdirSync(dirPath, {withFileTypes: true});
     for (const entry of entries) {
@@ -405,6 +432,8 @@ export function discoverExternalComponents(docsDir) {
  * Returns a Record<string, string[]> matching the shape of discoverComponents():
  * - Grouped components: `{ 'App Chrome': ['AppShell', 'SideNav', 'TopNav'] }`
  * - Ungrouped components: `{ 'Diff': ['Diff'] }`
+ * @param {string} docsDir
+ * @returns {Record<string, string[]>}
  */
 export function discoverExternalComponentsGrouped(docsDir) {
   if (!fs.existsSync(docsDir)) return {};
@@ -412,6 +441,7 @@ export function discoverExternalComponentsGrouped(docsDir) {
   /** @type {Map<string, string|null>} componentName → group */
   const componentGroups = new Map();
 
+  /** @param {string} dirPath */
   function scanDir(dirPath) {
     const entries = fs.readdirSync(dirPath, {withFileTypes: true});
     for (const entry of entries) {
@@ -440,7 +470,7 @@ export function discoverExternalComponentsGrouped(docsDir) {
   for (const [name, group] of componentGroups) {
     if (group) {
       if (!groups.has(group)) groups.set(group, []);
-      groups.get(group).push(name);
+      groups.get(group)?.push(name);
     } else {
       ungrouped.push(name);
     }
@@ -472,11 +502,18 @@ export function discoverExternalComponentsGrouped(docsDir) {
 /**
  * Find a component's doc file in an external package's docs directory.
  * Returns the path to {Name}.doc.mjs or null.
+ * @param {string} docsDir
+ * @param {string} name
+ * @returns {string | null}
  */
 export function findExternalComponentDoc(docsDir, name) {
   if (!fs.existsSync(docsDir)) return null;
   const target = `${name}.doc.mjs`;
 
+  /**
+   * @param {string} dirPath
+   * @returns {string | null}
+   */
   function scanDir(dirPath) {
     const entries = fs.readdirSync(dirPath, {withFileTypes: true});
     for (const entry of entries) {
@@ -538,6 +575,7 @@ export function discoverIntegrationComponents(integration) {
   /** @type {Map<string, {name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>} */
   const byName = new Map();
 
+  /** @param {string} dirPath */
   function scanDir(dirPath) {
     const entries = fs.readdirSync(dirPath, {withFileTypes: true});
     for (const entry of entries) {
@@ -582,6 +620,10 @@ export function findIntegrationComponentDoc(integration, name) {
   const componentsDir = integration?.components;
   if (!componentsDir || !fs.existsSync(componentsDir)) return null;
 
+  /**
+   * @param {string} dirPath
+   * @returns {string | null}
+   */
   function scanDir(dirPath) {
     const entries = fs.readdirSync(dirPath, {withFileTypes: true});
     // Exact same-stem match (precedence order) first in this dir.