@astryxdesign/cli 0.4.5 → 0.4.6-canary.cea9ecd

package/api/docs/integrationDocs.test.mjs

@@ -0,0 +1,208 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file End-to-end tests for integration-contributed doc topics: a scaffolded
+ * consumer project whose configured integration ships a `docs` root, read back
+ * through the public surfaces — `docs()`, `search()`, and the agent-docs block.
+ *
+ * The unit-level rules (what a docs root contributes, what the catalog does
+ * with `replaces`/`extends`) are covered in
+ * foundation/discovery/docs-discovery.test.mjs. What is pinned here is that a
+ * contributed topic is indistinguishable from a built-in one at the surfaces
+ * an agent actually reads.
+ *
+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
+ * dynamically import a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {docs} from './docs.mjs';
+import {search} from '../search/search.mjs';
+import {loadDocsCatalog} from './_adapter.mjs';
+import {AstryxError} from '../error.mjs';
+
+const SLOW = 30_000;
+
+let tmpDir;
+
+/** A minimal, valid topic. */
+function topic(fields) {
+  return {
+    type: 'generic',
+    name: 'deploying',
+    title: 'Deploying',
+    description: 'How to ship an app built with Acme widgets.',
+    category: 'guide',
+    sections: [
+      {title: 'Overview', content: [{type: 'prose', text: 'Push the button.'}]},
+    ],
+    ...fields,
+  };
+}
+
+/**
+ * A consumer project that configures one integration, optionally with a docs
+ * root holding the given topics.
+ * @param {Record<string, object|string>} [topics] file name → doc
+ * @param {{config?: string}} [options]
+ */
+function scaffold(topics, {config} = {}) {
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    config ?? "export default {integrations: ['@acme/widgets']};\n",
+  );
+
+  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(pkgDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default ${JSON.stringify(topics ? {docs: './docs'} : {})};\n`,
+  );
+
+  if (topics) {
+    const docsDir = path.join(pkgDir, 'docs');
+    fs.mkdirSync(docsDir, {recursive: true});
+    for (const [file, doc] of Object.entries(topics)) {
+      fs.writeFileSync(
+        path.join(docsDir, file),
+        typeof doc === 'string'
+          ? doc
+          : `export const docs = ${JSON.stringify(doc, null, 2)};\n`,
+      );
+    }
+  }
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-integration-docs-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration-contributed topics', () => {
+  it('lists and reads like a built-in topic, naming its owner', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    const entry = listed.data.find(t => t.topic === 'deploying');
+    expect(entry).toMatchObject({
+      topic: 'deploying',
+      description: 'How to ship an app built with Acme widgets.',
+      package: '@acme/widgets',
+    });
+    // The built-in topics keep their own owner.
+    expect(listed.data.find(t => t.topic === 'tokens').package).toBe('@astryxdesign/cli');
+
+    const detail = await docs('deploying', undefined, {cwd: tmpDir});
+    expect(detail.type).toBe('docs.detail');
+    expect(detail.data.sections[0].content[0].text).toBe('Push the button.');
+
+    const section = await docs('deploying', 'overview', {cwd: tmpDir});
+    expect(section.data.title).toBe('Overview');
+  }, SLOW);
+
+  it('is invisible to a project that does not configure the integration', async () => {
+    scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {};\n'});
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    expect(listed.data.some(t => t.topic === 'deploying')).toBe(false);
+  }, SLOW);
+
+  it('serves the replacement of a built-in topic, and says what it replaced', async () => {
+    scaffold({
+      'getting-started.doc.mjs': topic({
+        name: 'getting-started',
+        replaces: 'getting-started',
+        title: 'Getting started',
+        description: 'Install Acme widgets.',
+        sections: [
+          {title: 'Install', content: [{type: 'prose', text: 'yarn add @acme/widgets'}]},
+        ],
+      }),
+    });
+
+    const detail = await docs('getting-started', undefined, {cwd: tmpDir});
+    expect(detail.data.sections.map(s => s.title)).toEqual(['Install']);
+    expect(detail.data.sections[0].content[0].text).toBe('yarn add @acme/widgets');
+
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    const entries = listed.data.filter(t => t.topic === 'getting-started');
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      package: '@acme/widgets',
+      replaces: 'getting-started',
+    });
+  }, SLOW);
+
+  it('keeps the replaced name resolving when the replacement renames it', async () => {
+    scaffold({
+      'setup.doc.mjs': topic({name: 'setup', replaces: 'getting-started'}),
+    });
+    const byOldName = await docs('getting-started', undefined, {cwd: tmpDir});
+    const byNewName = await docs('setup', undefined, {cwd: tmpDir});
+    expect(byOldName.data.name).toBe('setup');
+    expect(byNewName.data.name).toBe('setup');
+  }, SLOW);
+
+  it('merges an extension into the topic it extends', async () => {
+    const builtin = await docs('theme');
+    const baseSectionTitle = builtin.data.sections[0].title;
+    scaffold({
+      'theme-internal.doc.mjs': topic({
+        name: 'theme-internal',
+        extends: 'theme',
+        sections: [
+          {title: baseSectionTitle, content: [{type: 'prose', text: 'Use the Acme theme.'}]},
+          {title: 'Acme themes', content: [{type: 'prose', text: 'Three of them.'}]},
+        ],
+      }),
+    });
+
+    const extended = await docs('theme', undefined, {cwd: tmpDir});
+    // The extension is not a topic of its own.
+    expect((await docs(undefined, undefined, {cwd: tmpDir})).data.some(
+      t => t.topic === 'theme-internal',
+    )).toBe(false);
+    expect(extended.data.sections[0].content[0].text).toBe('Use the Acme theme.');
+    expect(extended.data.sections.at(-1).title).toBe('Acme themes');
+    // Everything the extension did not name is still the base doc's.
+    expect(extended.data.sections.length).toBe(builtin.data.sections.length + 1);
+  }, SLOW);
+
+  it('offers the contributed topics as suggestions on an unknown one', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+    await expect(docs('nope-not-a-topic', undefined, {cwd: tmpDir})).rejects.toBeInstanceOf(
+      AstryxError,
+    );
+    try {
+      await docs('nope-not-a-topic', undefined, {cwd: tmpDir});
+    } catch (err) {
+      expect(err.suggestions.map(s => s.name)).toContain('deploying');
+    }
+  }, SLOW);
+
+  it('indexes a contributed topic in search', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+    const {data} = await search('deploying', {cwd: tmpDir, type: 'doc'});
+    expect(data.results[0]).toMatchObject({
+      domain: 'doc',
+      name: 'deploying',
+      command: 'astryx docs deploying',
+    });
+  }, SLOW);
+
+  it("falls back to the CLI's own topics when the project config is unreadable", async () => {
+    scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {integrations: 42};\n'});
+    const catalog = await loadDocsCatalog(tmpDir);
+    expect(catalog.resolve('tokens')).toBeTruthy();
+    expect(catalog.resolve('deploying')).toBeUndefined();
+  }, SLOW);
+});

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

@@ -2,6 +2,10 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
+ * @param {object} [options]
+ * @param {string} [options.cwd]
  * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
  */
-export function list(): Promise<import("../docs.type.mjs").DocsListResponse>;
+export function list({ cwd }?: {
+    cwd?: string | undefined;
+}): Promise<import("../docs.type.mjs").DocsListResponse>;

package/api/docs/list/list.mjs

@@ -3,31 +3,47 @@
 /**
  * @file docs.list leaf — enumerate the available reference-doc topics.
  *
- * @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,
- *   in filesystem-discovery order, matching `xds --json docs`.
+ * @input The project's doc catalog (built-in topics plus the ones configured
+ *   integrations contribute), via the shared adapter. A built-in topic's
+ *   English `description` is read from its file; a contributed topic already
+ *   carries the one discovery read. The listing never applies --dense/--zh
+ *   overlays.
+ * @output { type: 'docs.list', data: DocsListEntry[] } — one entry per topic in
+ *   read order, each naming the package that owns it, matching
+ *   `astryx --json docs`.
  * @position Leaf under api/docs. Sibling of detail; both share _adapter.mjs.
  */
 
 import {pathToFileURL} from 'node:url';
-import {discoverTopics} from '../_adapter.mjs';
+import {loadDocsCatalog} from '../_adapter.mjs';
 
 /**
+ * @param {object} [options]
+ * @param {string} [options.cwd]
  * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
  */
-export async function list() {
-  const topics = discoverTopics();
+export async function list({cwd} = {}) {
+  const catalog = await loadDocsCatalog(cwd);
   /** @type {Array<import('../docs.type.mjs').DocsListEntry>} */
   const entries = [];
-  for (const [name, docPath] of Object.entries(topics)) {
-    try {
-      const mod = await import(pathToFileURL(docPath).href);
-      entries.push({topic: name, description: mod.docs.description});
-    } catch {
-      entries.push({topic: name, description: ''});
+  for (const entry of catalog.entries()) {
+    let description = entry.description ?? '';
+    if (entry.description == null) {
+      try {
+        const mod = await import(pathToFileURL(entry.path).href);
+        description = (mod.docs ?? mod.default)?.description ?? '';
+      } catch {
+        description = '';
+      }
     }
+    /** @type {import('../docs.type.mjs').DocsListEntry} */
+    const listed = {
+      topic: entry.name,
+      description,
+      package: entry.package,
+    };
+    if (entry.replaces != null) listed.replaces = entry.replaces;
+    entries.push(listed);
   }
   return {type: 'docs.list', data: entries};
 }

package/api/init/run/run.mjs

@@ -20,6 +20,7 @@ import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
 import {PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {installAgentDocs} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {loadDocsCatalog} from '../../docs/_adapter.mjs';
 import {themeTemplate} from '../../theme/template/template.mjs';
 import {listTemplates} from '../../template/template.mjs';
 import {AstryxError} from '../../error.mjs';
@@ -71,7 +72,7 @@ export function getNextSteps(invocation) {
  * @param {string} invocation
  * @param {import('../init.type.mjs').InitRunData} data
  */
-function applyAgents(cwd, options, invocation, data) {
+async function applyAgents(cwd, options, invocation, data) {
   // Validate --agent up front (a hard error, not a swallowed install failure).
   // ERR_UNKNOWN_AGENT was defined but never wired — a typo like `--agent claud`
   // otherwise silently fell back to writing AGENTS.md. Mirrors --features.
@@ -88,7 +89,11 @@ function applyAgents(cwd, options, invocation, data) {
         ? options.agentDocsPath
         : [options.agentDocsPath]
       : undefined;
-    const written = installAgentDocs(cwd, {agent: options.agent, paths});
+    // The block names the topics the agent can read, and an integration's
+    // topics are part of that set — resolved here rather than inside
+    // installAgentDocs, which is sync and cannot load a project.
+    const topics = (await loadDocsCatalog(cwd)).names();
+    const written = installAgentDocs(cwd, {agent: options.agent, paths, topics});
     data.docsWritten = written;
     logger.log(`✓ AI agent docs installed → ${written.join(', ')}`);
   } catch (err) {
@@ -248,7 +253,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
       nextSteps: false,
     };
     for (const feature of features) {
-      if (feature === 'agents') applyAgents(cwd, options, invocation, data);
+      if (feature === 'agents') await applyAgents(cwd, options, invocation, data);
       if (feature === 'theme') applyTheme(cwd, invocation, data);
       if (feature === 'template') {
         applyTemplate(cwd, {templateName: options.templateName}, invocation, data);
@@ -272,7 +277,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     templatePath: null,
     nextSteps: true,
   };
-  applyAgents(cwd, options, invocation, data);
+  await applyAgents(cwd, options, invocation, data);
   logger.log('');
   logger.log(
     `  Tip: \`${invocation} init --all\` also points you to the theme and page-building workflows.`,

package/api/integration/validate-integration.mjs

@@ -18,7 +18,7 @@
  * error) so `validate-integration` can stay exit-0 in a non-integration dir.
  *
  * The on-disk contribution validators themselves (roots + codemods/templates/
- * components, behind `validateLoadedIntegration`) live in
+ * components/docs, behind `validateLoadedIntegration`) live in
  * `foundation/integrations/validate-contributions.mjs`, because foundation also
  * runs them: `Project` collects integration issues and `integration-warnings`
  * nudges about them on ordinary commands. This file re-exports
@@ -158,6 +158,7 @@ async function validateAtPackageDir(packageDir, identity) {
     components: resolveRoot(manifest.components),
     templates: resolveRoot(manifest.templates),
     codemods: resolveRoot(manifest.codemods),
+    docs: resolveRoot(manifest.docs),
     issuesUrl: manifest.issuesUrl,
     __spec: identity.name,
     __packageDir: packageDir,

package/api/integration/validate-integration.type.d.mts

@@ -12,6 +12,7 @@ export type LoadedIntegration = {
     components?: string | undefined;
     templates?: string | undefined;
     codemods?: string | undefined;
+    docs?: string | undefined;
     issuesUrl?: string | undefined;
     __spec: string;
     __packageDir: string;

package/api/integration/validate-integration.type.mjs

@@ -17,6 +17,7 @@
  * @property {string} [components]
  * @property {string} [templates]
  * @property {string} [codemods]
+ * @property {string} [docs]
  * @property {string} [issuesUrl]
  * @property {string} __spec
  * @property {string} __packageDir

package/api/search/search.mjs

@@ -30,10 +30,8 @@
  * sorts above an incidental mention.
  */
 
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {findCoreDir, CLI_ROOT} from '../../foundation/fs/paths.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
   findComponentReadme,
@@ -42,11 +40,10 @@ import {
 import {discoverHooks, findHookDoc} from '../../foundation/discovery/hook-discovery.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
+import {loadDocsCatalog, loadTopicDoc} from '../docs/_adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
-const DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs');
-
 /**
  * A search candidate gathered from one content domain. Extra underscore-
  * prefixed fields carry domain-specific payload used only by {@link toResult}.
@@ -424,17 +421,31 @@ async function gatherHooks(coreDir) {
 
 /**
  * Build doc-topic candidates: topic name + description + section prose.
+ *
+ * Reads the project's catalog rather than the CLI's own docs directory, so a
+ * topic an integration contributed (or replaced) is searchable exactly like a
+ * built-in one — otherwise the replacement is served by `astryx docs` but
+ * invisible to the command whose job is finding it.
+ * @param {string} cwd
  * @returns {Promise<Candidate[]>}
  */
-async function gatherDocs() {
-  if (!fs.existsSync(DOCS_DIR)) return [];
+async function gatherDocs(cwd) {
   /** @type {Candidate[]} */
   const candidates = [];
-  for (const file of fs.readdirSync(DOCS_DIR)) {
-    const match = file.match(/^([\w-]+)\.doc\.mjs$/);
-    if (!match) continue;
-    const topic = match[1];
-    const doc = await loadModuleDoc(path.join(DOCS_DIR, file));
+  let entries;
+  try {
+    entries = (await loadDocsCatalog(cwd)).entries();
+  } catch {
+    return candidates;
+  }
+  for (const entry of entries) {
+    let doc = null;
+    try {
+      doc = await loadTopicDoc(entry);
+    } catch {
+      // A topic that cannot be loaded is reported by the commands that own
+      // integration issues; search just cannot index it.
+    }
     let description = '';
     /** @type {string[]} */
     const prose = [];
@@ -449,11 +460,11 @@ async function gatherDocs() {
     }
     candidates.push({
       domain: 'doc',
-      name: topic,
+      name: entry.name,
       keywords: [],
       description,
       prose,
-      _title: doc?.title || topic,
+      _title: doc?.title || entry.title || entry.name,
     });
   }
   return candidates;
@@ -602,7 +613,7 @@ export async function search(query, options = {}) {
   const [components, hooks, docTopics, templates] = await Promise.all([
     wants('component') ? gatherComponents(coreDir) : [],
     wants('hook') ? gatherHooks(coreDir) : [],
-    wants('doc') ? gatherDocs() : [],
+    wants('doc') ? gatherDocs(cwd) : [],
     wants('template') ? gatherTemplates(cwd) : [],
   ]);
 

package/api/upgrade/_adapter.d.mts

@@ -52,13 +52,13 @@ export function runPostCodemodHooks(hooks: import("../../authoring/config/type")
  * EVERY upgrade path, including the no-codemods short-circuits (#4168).
  *
  * @param {{cwd: string, installedVersion: string, apply: boolean}} ctx
- * @returns {import('./upgrade.type.mjs').AgentDocsSummary}
+ * @returns {Promise<import('./upgrade.type.mjs').AgentDocsSummary>}
  */
 export function refreshAgentDocs({ cwd, installedVersion, apply }: {
     cwd: string;
     installedVersion: string;
     apply: boolean;
-}): import("./upgrade.type.mjs").AgentDocsSummary;
+}): Promise<import("./upgrade.type.mjs").AgentDocsSummary>;
 /**
  * Every registered codemod (oldest→newest) for `upgrade --list`. Registry walk
  * + flatten; nothing is run.

package/api/upgrade/_adapter.mjs

@@ -27,6 +27,7 @@ import {
 } from '../../assets/codemods/integration-discovery.mjs';
 import {runIntegrationCodemods} from '../../assets/codemods/integration-runner.mjs';
 import {installAgentDocs, inspectAgentDocs} from '../../foundation/agent-docs/agent-docs.mjs';
+import {loadDocsCatalog} from '../docs/_adapter.mjs';
 import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 import {Project} from '../../foundation/config/project.mjs';
 import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
@@ -145,9 +146,9 @@ export async function runPostCodemodHooks(hooks, context) {
  * EVERY upgrade path, including the no-codemods short-circuits (#4168).
  *
  * @param {{cwd: string, installedVersion: string, apply: boolean}} ctx
- * @returns {import('./upgrade.type.mjs').AgentDocsSummary}
+ * @returns {Promise<import('./upgrade.type.mjs').AgentDocsSummary>}
  */
-export function refreshAgentDocs({cwd, installedVersion, apply}) {
+export async function refreshAgentDocs({cwd, installedVersion, apply}) {
   const inspection = inspectAgentDocs(cwd, installedVersion);
   /** @type {import('./upgrade.type.mjs').AgentDocsSummary} */
   const summary = {
@@ -186,7 +187,10 @@ export function refreshAgentDocs({cwd, installedVersion, apply}) {
 
   // Apply: rewrite only files that already carry a marker (onlyReplace).
   try {
-    const written = installAgentDocs(cwd, {onlyReplace: true});
+    const written = installAgentDocs(cwd, {
+      onlyReplace: true,
+      topics: (await loadDocsCatalog(cwd)).names(),
+    });
     summary.refreshed = written.length > 0;
     summary.files = written;
     if (summary.refreshed) {

package/api/upgrade/run/run.mjs

@@ -90,7 +90,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
 
   // Sync the managed agent-docs block FIRST — it documents the installed library
   // independent of codemods, so refresh on every path (issue #4168).
-  const agentDocs = refreshAgentDocs({cwd, installedVersion: targetVersion, apply: apply || false});
+  const agentDocs = await refreshAgentDocs({cwd, installedVersion: targetVersion, apply: apply || false});
 
   if (!options.force && semverGte(currentVersion, targetVersion)) {
     return statusUpToDate({from: currentVersion, to: targetVersion, agentDocs});