Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(docsite): search panel runs the CLI's own search (#7830)

Joeyd6ee72b7997a
diff --git a/.changeset/search-reuses-gathered-catalog.md b/.changeset/search-reuses-gathered-catalog.md
new file mode 100644
index 0000000000..5ce101d55b
--- /dev/null
+++ b/.changeset/search-reuses-gathered-catalog.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `search()` from `@astryxdesign/cli/api` answers faster when one process searches again: it reuses the components, docs, templates and themes it gathered for the same folder and `type` while no file it read, and no folder it listed, has changed since (a linked workspace package included). To see those reads, the first such search in a process wraps `node:fs`'s read functions for that process; outside a search they behave exactly as before. Results are unchanged. Short-lived runs are unaffected: each `astryx search` command gathers once, as before.
+
+@josephfarina
diff --git a/apps/docsite/next.config.mjs b/apps/docsite/next.config.mjs
index 16f15b1036..de34c14a3b 100644
--- a/apps/docsite/next.config.mjs
+++ b/apps/docsite/next.config.mjs
@@ -38,6 +38,34 @@ const stagesStaticApps =
/** @type {import('next').NextConfig} */
const nextConfig = {
cacheComponents: true,
+ // The search API (app/api/search) runs `astryx search` itself. The CLI stays
+ // an external module (see webpack below), so its code and dependencies are
+ // traced as installed; these are the files it reads from disk at run time:
+ // its docs and templates, and each documented package's docs and sources.
+ outputFileTracingIncludes: {
+ '/api/search': [
+ './astryx.config.mjs',
+ '../../packages/cli/package.json',
+ '../../packages/cli/{api,assets,authoring,clients,foundation,host}/**/*',
+ '../../packages/core/package.json',
+ '../../packages/core/src/**/*',
+ // Integrations resolve through the site's node_modules, so they are
+ // traced at that path.
+ './node_modules/@astryxdesign/{lab,charts,richtext,vega}/{package.json,astryx.integration.mjs}',
+ './node_modules/@astryxdesign/{lab,charts,richtext,vega}/{src,blocks,docs,dist}/**/*',
+ ],
+ },
+ // Packages the CLI imports for other commands but a search never loads
+ // (bundlers, compilers, browsers, test runners), and built output it never
+ // reads. Leaving them out keeps the search function small; the parity test
+ // and a traced-files-only build hold it to `astryx search`.
+ outputFileTracingExcludes: {
+ '/api/search': [
+ '../../node_modules/.pnpm/{esbuild,@esbuild+*,typescript,playwright,playwright-core,vite,rolldown,@rolldown+*,flow-parser,esprima,tsx,vitest,@vitest+*,chai,@testing-library+*}@*/**',
+ '../../packages/*/dist/**',
+ './src/**',
+ ],
+ },
// Sandbox exports trailing-slash directories; Next's automatic slash
// redirect runs before rewrites. Vercel deployments preserve those URLs;
// local builds keep the docsite's existing canonical redirects.
@@ -120,6 +148,14 @@ const nextConfig = {
];
},
webpack: (config, {isServer, webpack}) => {
+ // The search API loads the CLI as installed, never bundled: the CLI reads
+ // its docs, templates and the installed packages from disk.
+ if (isServer) {
+ config.externals = [
+ ...[config.externals ?? []].flat(),
+ {'@astryxdesign/cli/api': 'module @astryxdesign/cli/api'},
+ ];
+ }
// Webpack's CSS @import resolver doesn't follow package.json "exports".
// Map each theme's /theme.css subpath to the actual dist file.
const themesDir = resolve(import.meta.dirname, '../../packages/themes');
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index aa738c4bb6..8592ca8386 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -36,6 +36,7 @@ import {
mergeFlatTopics,
namespacePage,
routeSlug,
+ sectionAnchors,
withCliCommands,
withoutResolvedTokens,
} from './docs-pages.mjs';
@@ -58,6 +59,7 @@ import {
} from '../src/lib/integrationTargets.mjs';
import {expandWorkspaceDirs} from '../../../scripts/lib/workspace-globs.mjs';
import {projectThemingDoc} from './lib/theming-doc.mjs';
+import {searchLinkTables} from '../src/lib/searchLinks.mjs';
import {collectBlogImages} from './lib/blog-images.mjs';
import {
buildTypeDefinitionIndex,
@@ -1999,6 +2001,46 @@ export const docRedirects: Record<string, string> = ${JSON.stringify(docRedirect
return {docTopics, docsCount: docTopics.length};
}
+/**
+ * The tables the search panel opens a CLI search result through
+ * (src/lib/searchLinks.mjs): this build's doc pages, redirects, section
+ * anchors, component and template pages, and the page each block shows on.
+ * The search API (app/api/search/route.ts) reads them.
+ */
+function generateSearchLinks({
+ docTopics,
+ allComponents,
+ templates,
+ blocks,
+ packages,
+}) {
+ const docRedirects = JSON.parse(
+ fs.readFileSync(path.join(OUT_DIR, 'docRedirects.json'), 'utf-8'),
+ );
+ const tables = searchLinkTables({
+ docTopics,
+ docRedirects,
+ components: Object.values(allComponents)
+ .flat()
+ .map(c => c.name),
+ templates: templates.map(t => t.slug),
+ blocks,
+ // The package pages /docs/[topic] serves; theme packages show on /themes.
+ packagePages: packages
+ .map(p => p.name)
+ .filter(name => !name.startsWith('@astryxdesign/theme-'))
+ .map(name => name.replace('@astryxdesign/', '')),
+ sectionAnchors,
+ });
+ fs.writeFileSync(
+ path.join(OUT_DIR, 'searchLinks.json'),
+ `${JSON.stringify(tables)}\n`,
+ );
+ console.log(
+ ` wrote ${path.relative(REPO_ROOT, path.join(OUT_DIR, 'searchLinks.json'))}`,
+ );
+}
+
async function generateThemeRegistry(packages) {
console.log('Generating theme registry...');
const themePackages = packages.filter(p =>
@@ -2528,7 +2570,8 @@ async function main() {
const {blocks, blockCount} = await generateBlockRegistry();
generatePackageStyles(packages, blocks, allComponents);
const {templates, templateCount} = await generateTemplateRegistry();
- const {docsCount} = await generateDocsRegistry();
+ const {docTopics, docsCount} = await generateDocsRegistry();
+ generateSearchLinks({docTopics, allComponents, templates, blocks, packages});
const {blogPostCount} = await generateBlogRegistry();
const shadcnCounts = generateShadcnRegistryForTarget({
target: DOCSITE_TARGET,
diff --git a/apps/docsite/src/__tests__/cli-search.test.ts b/apps/docsite/src/__tests__/cli-search.test.ts
new file mode 100644
index 0000000000..57006d0885
--- /dev/null
+++ b/apps/docsite/src/__tests__/cli-search.test.ts
@@ -0,0 +1,324 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The site's search answers what `astryx search` answers.
+ *
+ * The search panel asks the site's search API (app/api/search/route.ts),
+ * which calls the CLI's `search()`. These tests hold it to the CLI: for a
+ * fixed list of public, made-up queries, the API's results are the results
+ * `astryx search --json` prints from this site's project, in the same order;
+ * every result opens a page the site has; and the panel keeps the CLI's order.
+ */
+
+import {execFile} from 'node:child_process';
+import path from 'node:path';
+import {promisify} from 'node:util';
+import {describe, expect, it} from 'vitest';
+import type {SearchResponse} from '@astryxdesign/cli/api';
+import {GET} from '../app/api/search/route';
+import {searchResultHref} from '../lib/searchLinks.mjs';
+import type {SearchLinkTables} from '../lib/searchLinks.mjs';
+import {
+ createCliSearchSource,
+ searchTarget,
+ toSearchItem,
+} from '../lib/cliSearchSource';
+import type {SiteSearchResult} from '../lib/cliSearchTypes';
+import docsiteConfig from '../../astryx.config.mjs';
+import {docTopics, docRedirects} from '../generated/docsRegistry';
+import {packages} from '../generated/packageRegistry';
+import admittedRecord from '../generated/integrationPackages.json';
+import linkTables from '../generated/searchLinks.json';
+
+const run = promisify(execFile);
+const ROOT = path.resolve(import.meta.dirname, '../..');
+const ASTRYX = path.join(ROOT, 'node_modules', '.bin', 'astryx');
+const links = linkTables as SearchLinkTables;
+const SLOW = 120_000;
+
+/** Public, made-up queries across every domain. */
+const QUERIES = [
+ 'button',
+ 'date picker',
+ 'dark mode',
+ 'how do I theme my app',
+ 'sidebar layout',
+ 'table with sorting',
+ 'modal dialog',
+ 'tokens spacing',
+ 'toast notification',
+ 'login form',
+ 'useMediaQuery',
+ 'chart',
+];
+
+/** What the site's API answers for a query. */
+async function api(query: string) {
+ const response = await GET(
+ new Request(`http://site/api/search?q=${encodeURIComponent(query)}`),
+ );
+ expect(response.status).toBe(200);
+ return (await response.json()) as SearchResponse & {
+ data: {results: SiteSearchResult[]};
+ };
+}
+
+// The API answers for the packages this build documents. On canary that is
+// every configured integration, the same set `astryx search` reads here.
+const documentsEveryIntegration =
+ docsiteConfig.integrations.length === admittedRecord.packages.length;
+
+describe('site search = astryx search', () => {
+ it.skipIf(!documentsEveryIntegration)(
+ 'answers each query with the results `astryx search --json` prints',
+ async () => {
+ const printed = await Promise.all(
+ QUERIES.map(async query => {
+ const {stdout} = await run(ASTRYX, ['search', query, '--json'], {
+ cwd: ROOT,
+ maxBuffer: 16 * 1024 * 1024,
+ });
+ return JSON.parse(stdout) as SearchResponse;
+ }),
+ );
+ for (const [i, query] of QUERIES.entries()) {
+ const {data} = await api(query);
+ expect(data.results.length, query).toBeGreaterThan(0);
+ const {results: siteResults, ...rest} = data;
+ const results = siteResults as SiteSearchResult[];
+ const {results: cliResults, ...cliRest} = printed[i].data;
+ expect(rest, query).toEqual(cliRest);
+ expect(
+ results.map(
+ ({href: _href, siteTitle: _siteTitle, ...result}) => result,
+ ),
+ query,
+ ).toEqual(cliResults);
+ }
+ },
+ SLOW,
+ );
+
+ it('refuses an empty or overlong query', async () => {
+ for (const q of ['', ' ', 'x'.repeat(201)]) {
+ const response = await GET(
+ new Request(`http://site/api/search?q=${encodeURIComponent(q)}`),
+ );
+ expect(response.status).toBe(400);
+ }
+ });
+});
+
+describe('site search links', () => {
+ const pages = new Set([
+ ...docTopics.map(topic => topic.topic),
+ ...packages
+ .map(p => p.name)
+ .filter(name => !name.startsWith('@astryxdesign/theme-'))
+ .map(name => name.replace('@astryxdesign/', '')),
+ ]);
+ const redirectTargets = new Set(Object.values(docRedirects));
+ const components = new Set(links.components);
+ const templates = new Set(links.templates);
+
+ /** Whether the site serves this path. */
+ const served = (href: string): boolean => {
+ if (['/components', '/templates', '/themes', '/docs'].includes(href)) {
+ return true;
+ }
+ if (redirectTargets.has(href)) {
+ return true;
+ }
+ const [pathname] = href.split('#');
+ const [, area, slug] = pathname.split('/');
+ if (area === 'components') {
+ return components.has(slug);
+ }
+ if (area === 'templates') {
+ return templates.has(slug);
+ }
+ if (area === 'docs') {
+ return pages.has(slug);
+ }
+ return false;
+ };
+
+ it(
+ 'opens a page the site has for every result of every query',
+ async () => {
+ for (const query of QUERIES) {
+ for (const result of (await api(query)).data.results) {
+ expect(
+ served(result.href),
+ `${query}: ${result.domain} ${result.name} -> ${result.href}`,
+ ).toBe(true);
+ }
+ }
+ },
+ SLOW,
+ );
+
+ it("opens a section at its own guide's anchor when a page repeats its key", () => {
+ // A namespace page holds several guides' sections, and section keys are
+ // unique only within a guide. Group the guide-keyed entries by page and
+ // key: each guide's copy must open its own anchor.
+ const byKey = new Map<string, {starts: Set<string>; hrefs: Set<string>}>();
+ for (const [key, href] of Object.entries(links.anchors)) {
+ const [guide, section] = key.split('#');
+ const page = href.split('#')[0];
+ const target = links.redirects[guide];
+ if (!target || target.split('#')[0] !== page) {
+ continue;
+ }
+ const group = `${page} ${section}`;
+ if (!byKey.has(group)) {
+ byKey.set(group, {starts: new Set(), hrefs: new Set()});
+ }
+ // A namespace with no text of its own starts where its first guide does.
+ byKey.get(group)!.starts.add(target);
+ byKey.get(group)!.hrefs.add(href);
+ }
+ const repeated = [...byKey.entries()].filter(([, v]) => v.starts.size > 1);
+ expect(
+ repeated.length,
+ 'a page that repeats a section key',
+ ).toBeGreaterThan(0);
+ for (const [group, {starts, hrefs}] of repeated) {
+ expect(hrefs.size, group).toBe(starts.size);
+ }
+ });
+
+ it("opens an integration's example block on its component page", () => {
+ const blocks = Object.entries(links.blocks).filter(([key]) =>
+ key.startsWith('-astryxdesign-'),
+ );
+ expect(blocks.length).toBeGreaterThan(0);
+ for (const [key, page] of blocks) {
+ const [, pkg, name] = /^-astryxdesign-([a-z]+)-(.+)$/.exec(key)!;
+ expect(
+ searchResultHref(
+ {
+ domain: 'template',
+ kind: 'block',
+ name,
+ package: `@astryxdesign/${pkg}`,
+ },
+ links,
+ ),
+ key,
+ ).toBe(page);
+ }
+ });
+
+ it(
+ 'titles doc results the way the site does, never with the docs-tree path',
+ async () => {
+ for (const query of [
+ 'authoring',
+ 'how do I theme my app',
+ 'tokens spacing',
+ ]) {
+ for (const result of (await api(query)).data.results) {
+ if (result.domain !== 'doc') continue;
+ expect(result.siteTitle, `${query}: ${result.name}`).toBeTruthy();
+ expect(result.siteTitle).not.toMatch(/Unorganized/);
+ }
+ }
+ },
+ SLOW,
+ );
+
+ it('opens a doc section at its anchor', () => {
+ const href = searchResultHref(
+ {domain: 'doc', name: 'author-a-theme', section: 'palette'},
+ links,
+ );
+ expect(href).toMatch(/^\/docs\/theme#/);
+ });
+});
+
+describe('search panel order', () => {
+ it(
+ 'keeps the CLI order: no groups, one item per place',
+ async () => {
+ const {data} = await api('button');
+ const urls: string[] = [];
+ const source = createCliSearchSource(async url => {
+ urls.push(url);
+ return new Response(JSON.stringify({data}));
+ });
+ expect(source.bootstrap()).toEqual([]);
+ const items = await source.search('button');
+ expect(urls).toEqual(['/api/search?q=button']);
+ const results = data.results as SiteSearchResult[];
+ const firstPerPlace = results.filter(
+ (result, i) =>
+ results.findIndex(other => other.href === result.href) === i,
+ );
+ expect(items.map(item => item.auxiliaryData.name)).toEqual(
+ firstPerPlace.map(result => result.name),
+ );
+ expect(new Set(items.map(item => item.id)).size).toBe(items.length);
+ for (const item of items) {
+ expect(item.auxiliaryData).not.toHaveProperty('group');
+ expect(source.item(item.id)).toBe(item);
+ }
+ expect(toSearchItem(data.results[0], 0).label).toBeTruthy();
+ },
+ SLOW,
+ );
+
+ it(
+ 'lists each place once, with a label no other row has',
+ async () => {
+ for (const query of ['dark mode', 'authoring', 'tokens spacing']) {
+ const {data} = await api(query);
+ const source = createCliSearchSource(
+ async () => new Response(JSON.stringify({data})),
+ );
+ const items = await source.search(query);
+ const hrefs = items.map(item => item.auxiliaryData.href);
+ expect(new Set(hrefs).size, `${query}: ${hrefs}`).toBe(hrefs.length);
+ const docLabels = items
+ .filter(item => item.auxiliaryData.domain === 'doc')
+ .map(item => item.label);
+ expect(new Set(docLabels).size, `${query}: ${docLabels}`).toBe(
+ docLabels.length,
+ );
+ }
+ },
+ SLOW,
+ );
+
+ it('reports a selection by what it opens, as the registries name it', () => {
+ expect(searchTarget('/components/Button')).toEqual({
+ item: 'Button',
+ type: 'component',
+ });
+ expect(searchTarget('/docs/theme#dark-mode')).toEqual({
+ item: 'theme',
+ type: 'doc',
+ });
+ expect(searchTarget('/templates/login')).toEqual({
+ item: 'login',
+ type: 'template',
+ });
+ expect(searchTarget('/themes')).toEqual({item: 'themes', type: 'theme'});
+ });
+
+ it('sends only the last query typed', async () => {
+ const urls: string[] = [];
+ const source = createCliSearchSource(async (url, init) => {
+ urls.push(url);
+ if (init.signal?.aborted) {
+ throw new Error('aborted');
+ }
+ return new Response(JSON.stringify({data: {results: []}}));
+ });
+ const first = source.search('bu');
+ const second = source.search('button');
+ expect(await first).toEqual([]);
+ await second;
+ expect(urls).toEqual(['/api/search?q=button']);
+ });
+});
diff --git a/apps/docsite/src/__tests__/component-sidebar-data.test.ts b/apps/docsite/src/__tests__/component-sidebar-data.test.ts
new file mode 100644
index 0000000000..b187c3d90f
--- /dev/null
+++ b/apps/docsite/src/__tests__/component-sidebar-data.test.ts
@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Component sidebar grouping: ready families stay unified, and canary-only
+ * packages are grouped by package with their components marked not ready.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {components} from '../generated/componentRegistry';
+import {packages} from '../generated/packageRegistry';
+import {
+ flattenComponentSidebarEntries,
+ getComponentSidebarData,
+} from '../components/componentSidebarData';
+
+describe('component sidebar data', () => {
+ it('marks canary-only package components not ready, and every other one ready', () => {
+ const entries = flattenComponentSidebarEntries();
+ const canaryPackages = new Set(
+ packages.filter(pkg => pkg.canaryOnly).map(pkg => pkg.name),
+ );
+ const canaryEntries = entries.filter(entry =>
+ canaryPackages.has(entry.packageName),
+ );
+
+ expect(canaryEntries.length).toBeGreaterThan(0);
+ expect(canaryEntries.every(entry => !entry.isReady)).toBe(true);
+ expect(
+ entries
+ .filter(entry => !canaryPackages.has(entry.packageName))
+ .every(entry => entry.isReady),
+ ).toBe(true);
+ });
+
+ it('keeps ready families unified and groups canary components by package', () => {
+ const {componentItems, canaryCategories} = getComponentSidebarData();
+ const readyGroups = componentItems.filter(item => item.type === 'group');
+
+ expect(readyGroups.filter(group => group.label === 'Chat')).toHaveLength(1);
+ expect(
+ readyGroups
+ .find(group => group.label === 'Chat')
+ ?.entries.every(entry => entry.isReady),
+ ).toBe(true);
+
+ // One canary category per canary-only package with components; a
+ // configured integration that is a stable release joins the ready view.
+ expect(canaryCategories.map(category => category.displayName)).toEqual(
+ packages
+ .filter(pkg => pkg.canaryOnly && components[pkg.name]?.length)
+ .map(pkg => pkg.displayName)
+ .sort((a, b) => a.localeCompare(b)),
+ );
+ const chartEntries = canaryCategories.flatMap(category =>
+ category.componentItems.flatMap(item =>
+ item.type === 'entry' || item.label !== 'Charts' ? [] : item.entries,
+ ),
+ );
+ expect(chartEntries.map(entry => entry.name)).toEqual(
+ expect.arrayContaining(['Chart', 'ChartSwatch', 'ChartBar', 'ChartLine']),
+ );
+ expect(chartEntries.every(entry => !entry.isReady)).toBe(true);
+
+ const lab = canaryCategories.find(
+ category => category.displayName === 'Lab',
+ );
+ const threeD = lab?.componentItems.find(
+ item => item.type === 'group' && item.label === '3D',
+ );
+ expect(threeD?.displayName).toBe('3D');
+ });
+});
diff --git a/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts b/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts
index bcdc747be9..3aeffc2fa4 100644
--- a/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts
+++ b/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts
@@ -25,36 +25,34 @@ const [
{GET: getLlmsTxt},
{GET: getRss},
{POST: postMcp},
+ {GET: getSearch},
{CURRENT_TARGET},
{components},
{blocks},
{templates},
{docTopics},
{blogPosts},
- {packages},
{showcaseRegistry},
{exampleRegistry},
{shadcnRegistryIsPreview, shadcnRegistryOrigin},
{flattenComponentSidebarEntries},
- {buildSearchPaletteItems},
] = await Promise.all([
import('../app/robots'),
import('../app/sitemap'),
import('../app/llms.txt/route'),
import('../app/rss.xml/route'),
import('../app/mcp/route'),
+ import('../app/api/search/route'),
import('../lib/docsVersions'),
import('../generated/componentRegistry'),
import('../generated/blockRegistry'),
import('../generated/templateRegistry'),
import('../generated/docsRegistry'),
import('../generated/blogRegistry'),
- import('../generated/packageRegistry'),
import('../generated/showcaseRegistry'),
import('../generated/exampleRegistry'),
import('../generated/shadcnRegistry'),
import('../components/componentSidebarData'),
- import('../components/searchPaletteData'),
]);
const FORBIDDEN_DISCOVERY_PATTERNS = [
@@ -193,18 +191,6 @@ describeHiddenProduction('hidden production ShadCN discovery', () => {
href: entry.href,
label: entry.displayName,
}));
- const search = buildSearchPaletteItems({
- components,
- packages,
- docTopics,
- templates,
- }).map(item => ({
- id: item.id,
- label: item.label,
- group: item.auxiliaryData.group,
- keywords: item.auxiliaryData.keywords,
- }));
-
expectNoShadcnPromotion(
docTopics.map(topic => ({topic: topic.topic, title: topic.title})),
'docs navigation',
@@ -214,9 +200,28 @@ describeHiddenProduction('hidden production ShadCN discovery', () => {
'blog indexes',
);
expectNoShadcnPromotion(sidebar, 'component navigation');
- expectNoShadcnPromotion(search, 'global search');
});
+ it('keeps the site search (astryx search) free of registry promotion', async () => {
+ // Like the MCP search below, it may name ShadCN only inside the CLI's own
+ // docs (the migration guide); it never points at the registry.
+ const response = await getSearch(
+ new Request('http://site/api/search?q=shadcn%20registry%20install'),
+ );
+ const {data} = (await response.json()) as {
+ data: {results: Array<Record<string, unknown>>};
+ };
+ expectNoRegistryDiscovery(data, 'site search');
+ for (const result of data.results) {
+ if (/shadcn/i.test(JSON.stringify(result))) {
+ expect(result).toMatchObject({
+ domain: 'doc',
+ package: '@astryxdesign/cli',
+ });
+ }
+ }
+ }, 60_000);
+
it('keeps sitemap, RSS, and llms.txt clean', async () => {
const sitemapEntries = await sitemap();
const rss = await (await getRss()).text();
diff --git a/apps/docsite/src/__tests__/search-palette.test.ts b/apps/docsite/src/__tests__/search-palette.test.ts
deleted file mode 100644
index 552d9abb23..0000000000
--- a/apps/docsite/src/__tests__/search-palette.test.ts
+++ /dev/null
@@ -1,149 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Search palette data tests.
- *
- * Validates that the global docsite command palette indexes the same component
- * links as the sidebar.
- */
-
-import {describe, it, expect} from 'vitest';
-import {components} from '../generated/componentRegistry';
-import {packages} from '../generated/packageRegistry';
-import {docTopics} from '../generated/docsRegistry';
-import {templateMetadata as templates} from '../generated/templateMetadataRegistry';
-import {
- flattenComponentSidebarEntries,
- getComponentSidebarData,
-} from '../components/componentSidebarData';
-import {
- buildSearchPaletteItems,
- getSearchItemKeywords,
-} from '../components/searchPaletteData';
-
-function buildItems() {
- return buildSearchPaletteItems({
- components,
- packages,
- docTopics,
- templates,
- });
-}
-
-function searchItems(query: string) {
- const lower = query.toLowerCase().trim();
- return buildItems().filter(
- item =>
- item.label.toLowerCase().includes(lower) ||
- getSearchItemKeywords(item).some(kw => kw.toLowerCase().includes(lower)),
- );
-}
-
-describe('SearchPalette data', () => {
- it('uses the sidebar entries as the command palette component set', () => {
- const componentIds = buildItems()
- .filter(item =>
- ['Component', 'Canary component'].includes(item.auxiliaryData.group),
- )
- .map(item => item.id);
- const sidebarIds = flattenComponentSidebarEntries().map(
- entry => entry.href,
- );
-
- expect(new Set(componentIds).size).toBe(componentIds.length);
- expect(new Set(componentIds)).toEqual(new Set(sidebarIds));
- expect(componentIds).toContain('/components/DropdownMenu');
- expect(componentIds).toContain('/components/DropdownMenuItem');
- expect(componentIds).toContain('/components/CommandPalette');
- expect(componentIds).toContain('/components/Table');
- });
-
- it('includes canary-only component packages with canary metadata', () => {
- const entries = flattenComponentSidebarEntries();
- const items = buildItems();
- const canaryPackages = new Set(
- packages.filter(pkg => pkg.canaryOnly).map(pkg => pkg.name),
- );
- const canaryEntries = entries.filter(entry =>
- canaryPackages.has(entry.packageName),
- );
-
- expect(canaryEntries.length).toBeGreaterThan(0);
- expect(canaryEntries.every(entry => !entry.isReady)).toBe(true);
- expect(
- canaryEntries.every(entry => {
- const item = items.find(item => item.id === entry.href);
- return (
- item?.auxiliaryData.isReady === false &&
- item.auxiliaryData.group === 'Canary component'
- );
- }),
- ).toBe(true);
- expect(
- entries
- .filter(entry => !canaryPackages.has(entry.packageName))
- .every(entry => entry.isReady),
- ).toBe(true);
- });
-
- it('keeps ready families unified and groups canary components by package', () => {
- const {componentItems, canaryCategories} = getComponentSidebarData();
- const readyGroups = componentItems.filter(item => item.type === 'group');
-
- expect(readyGroups.filter(group => group.label === 'Chat')).toHaveLength(1);
- expect(
- readyGroups
- .find(group => group.label === 'Chat')
- ?.entries.every(entry => entry.isReady),
- ).toBe(true);
-
- // One canary category per canary-only package with components; a
- // configured integration that is a stable release joins the ready view.
- expect(canaryCategories.map(category => category.displayName)).toEqual(
- packages
- .filter(pkg => pkg.canaryOnly && components[pkg.name]?.length)
- .map(pkg => pkg.displayName)
- .sort((a, b) => a.localeCompare(b)),
- );
- const chartEntries = canaryCategories.flatMap(category =>
- category.componentItems.flatMap(item =>
- item.type === 'entry' || item.label !== 'Charts' ? [] : item.entries,
- ),
- );
- expect(chartEntries.map(entry => entry.name)).toEqual(
- expect.arrayContaining(['Chart', 'ChartSwatch', 'ChartBar', 'ChartLine']),
- );
- expect(chartEntries.every(entry => !entry.isReady)).toBe(true);
-
- const lab = canaryCategories.find(
- category => category.displayName === 'Lab',
- );
- const threeD = lab?.componentItems.find(
- item => item.type === 'group' && item.label === '3D',
- );
- expect(threeD?.displayName).toBe('3D');
- });
-
- it('finds Dropdown Menu by spaced display name and PascalCase API name', () => {
- const items = buildItems();
- const dropdown = items.find(item => item.id === '/components/DropdownMenu');
- expect(dropdown?.label).toBe('Dropdown Menu');
-
- expect(searchItems('dropdown menu').map(item => item.id)).toContain(
- '/components/DropdownMenu',
- );
- expect(searchItems('DropdownMenu').map(item => item.id)).toContain(
- '/components/DropdownMenu',
- );
- });
-
- it('finds AppShell when searching for app shell with a space', () => {
- const items = buildItems();
- const appShell = items.find(item => item.id === '/components/AppShell');
- expect(appShell?.label).toBe('App Shell');
-
- expect(searchItems('app shell').map(item => item.id)).toContain(
- '/components/AppShell',
- );
- });
-});
diff --git a/apps/docsite/src/app/api/search/route.ts b/apps/docsite/src/app/api/search/route.ts
new file mode 100644
index 0000000000..5041c2c4ff
--- /dev/null
+++ b/apps/docsite/src/app/api/search/route.ts
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file GET /api/search?q=<query>: `astryx search <query>`, run by the site.
+ * @input The query, as `astryx search` takes it.
+ * @output The CLI's search response, each result with the site path it opens.
+ * @position Called by the search panel (lib/cliSearchSource.ts).
+ *
+ * The site's search is the CLI's: this calls `search()` from
+ * `@astryxdesign/cli/api`, the function behind `astryx search --json`, in this
+ * site's project, so the panel gives the CLI's results in the CLI's order and
+ * every change to the CLI's search reaches the site. Nothing here ranks.
+ */
+
+import {search} from '@astryxdesign/cli/api';
+import {
+ searchResultHref,
+ searchResultTitle,
+} from '../../../lib/searchLinks.mjs';
+import type {SearchLinkTables} from '../../../lib/searchLinks.mjs';
+import links from '../../../generated/searchLinks.json';
+import admitted from '../../../generated/integrationPackages.json';
+import docsiteConfig from '../../../../astryx.config.mjs';
+
+/** Packages this build documents: Core, the CLI's docs and themes, and the
+ * integrations it admits (canary: all configured; latest: stable ones). */
+const DOCUMENTED = new Set([
+ '@astryxdesign/core',
+ '@astryxdesign/cli',
+ ...admitted.packages,
+]);
+
+/** Whether this build leaves out an integration the site's project has. */
+const FILTERED = docsiteConfig.integrations.some(
+ (name: string) => !DOCUMENTED.has(name),
+);
+
+/** How many results the panel shows: `astryx search`'s default. */
+const LIMIT = 20;
+
+/** Longest query the API accepts. */
+const MAX_QUERY = 200;
+
+export async function GET(request: Request): Promise<Response> {
+ const query = new URL(request.url).searchParams.get('q')?.trim() ?? '';
+ if (query === '' || query.length > MAX_QUERY) {
+ return Response.json(
+ {error: `q must be 1 to ${MAX_QUERY} characters`},
+ {status: 400},
+ );
+ }
+ // When this build leaves out an integration, ask for every match, drop
+ // that integration's, then count and cut to the panel's 20; otherwise this
+ // is exactly `astryx search <query>`.
+ const response = await search(query, {
+ cwd: process.cwd(),
+ ...(FILTERED ? {limit: Number.MAX_SAFE_INTEGER} : {}),
+ });
+ const kept = FILTERED
+ ? response.data.results.filter(
+ result => result.package == null || DOCUMENTED.has(result.package),
+ )
+ : response.data.results;
+ const matchCount = FILTERED ? kept.length : response.data.matchCount;
+ const results = kept.slice(0, LIMIT).map(result => {
+ const href = searchResultHref(result, links as SearchLinkTables);
+ const siteTitle = searchResultTitle(
+ result,
+ href,
+ links as SearchLinkTables,
+ );
+ return {...result, href, ...(siteTitle ? {siteTitle} : {})};
+ });
+ return Response.json(
+ {...response, data: {...response.data, matchCount, results}},
+ {
+ // A query's answer changes only when the site is rebuilt.
+ headers: {'Cache-Control': 'public, max-age=300, s-maxage=86400'},
+ },
+ );
+}
diff --git a/apps/docsite/src/components/SearchPalette.tsx b/apps/docsite/src/components/SearchPalette.tsx
index f65e4dfc22..acb7f2686e 100644
--- a/apps/docsite/src/components/SearchPalette.tsx
+++ b/apps/docsite/src/components/SearchPalette.tsx
@@ -6,60 +6,38 @@ import {useMemo, useCallback} from 'react';
import {useRouter} from 'next/navigation';
import {CommandPalette} from '@astryxdesign/core/CommandPalette';
import {Text} from '@astryxdesign/core/Text';
-import {createStaticSource} from '@astryxdesign/core/Typeahead';
-import {components} from '../generated/componentRegistry';
-import {packages} from '../generated/packageRegistry';
-import {docTopics} from '../generated/docsRegistry';
-import {templateMetadata} from '../generated/templateMetadataRegistry';
import {trackSearch} from '../lib/analytics';
import {
- buildSearchPaletteItems,
- getSearchItemKeywords,
-} from './searchPaletteData';
+ createCliSearchSource,
+ resultKind,
+ searchTarget,
+} from '../lib/cliSearchSource';
interface SearchPaletteProps {
isOpen: boolean;
onOpenChange: (open: boolean) => void;
}
+/**
+ * The site's search: `astryx search`, run by the site's search API
+ * (app/api/search/route.ts), so it answers what the CLI answers.
+ */
export function SearchPalette({isOpen, onOpenChange}: SearchPaletteProps) {
const router = useRouter();
- // Component items come from the same grouped registry as the sidebar so
- // sidebar and command palette navigation stay in lockstep.
- const searchSource = useMemo(() => {
- const items = buildSearchPaletteItems({
- components,
- packages,
- docTopics,
- templates: templateMetadata,
- });
-
- return createStaticSource(items, {
- keywords: getSearchItemKeywords,
- });
- }, []);
+ const searchSource = useMemo(() => createCliSearchSource(), []);
const handleValueChange = useCallback(
- (value: string) => {
- if (value && value.startsWith('/')) {
- // Determine type from path prefix
- const type = value.startsWith('/components/')
- ? 'component'
- : value.startsWith('/templates/')
- ? 'template'
- : value.startsWith('/themes/')
- ? 'theme'
- : value.startsWith('/docs/')
- ? 'doc'
- : 'page';
- const item = value.split('/').pop() || value;
- trackSearch({target: 'select', item, type});
- router.push(value);
- onOpenChange(false);
+ (id: string) => {
+ const result = searchSource.item(id)?.auxiliaryData;
+ if (!result) {
+ return;
}
+ trackSearch({target: 'select', ...searchTarget(result.href)});
+ router.push(result.href);
+ onOpenChange(false);
},
- [router, onOpenChange],
+ [searchSource, router, onOpenChange],
);
return (
@@ -67,7 +45,15 @@ export function SearchPalette({isOpen, onOpenChange}: SearchPaletteProps) {
isOpen={isOpen}
onOpenChange={onOpenChange}
searchSource={searchSource}
- renderItem={item => <Text type="inherit">{item.label}</Text>}
+ renderItem={item => (
+ <Text type="inherit">
+ {item.label}
+ <Text type="supporting" color="secondary">
+ {' '}
+ {resultKind(item.auxiliaryData)}
+ </Text>
+ </Text>
+ )}
label="Search docs, components, and templates"
value=""
onValueChange={handleValueChange}
diff --git a/apps/docsite/src/components/searchPaletteData.ts b/apps/docsite/src/components/searchPaletteData.ts
deleted file mode 100644
index fc0bfc412f..0000000000
--- a/apps/docsite/src/components/searchPaletteData.ts
+++ /dev/null
@@ -1,128 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import type {SearchableItem} from '@astryxdesign/core/Typeahead';
-import type {ComponentEntry} from '../generated/componentRegistry';
-import type {PackageMeta} from '../generated/packageRegistry';
-import type {DocTopic} from '../generated/docsRegistry';
-import type {TemplateMetadataEntry} from '../generated/templateMetadataRegistry';
-import {flattenComponentSidebarEntries} from './componentSidebarData';
-
-export interface SearchItemAuxiliaryData {
- group: string;
- keywords: string[];
- isReady: boolean;
-}
-
-export interface SearchItem extends SearchableItem<SearchItemAuxiliaryData> {
- id: string;
- label: string;
- auxiliaryData: SearchItemAuxiliaryData;
-}
-
-interface SearchPaletteDataInput {
- components: Record<string, ComponentEntry[]>;
- packages: PackageMeta[];
- docTopics: DocTopic[];
- templates: TemplateMetadataEntry[];
-}
-
-function uniqueKeywords(keywords: Array<string | null | undefined>): string[] {
- return [...new Set(keywords.filter((kw): kw is string => Boolean(kw)))];
-}
-
-function splitWords(value: string): string {
- return value.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ');
-}
-
-export function getSearchItemKeywords(item: SearchItem): string[] {
- return [
- item.auxiliaryData.group,
- splitWords(item.label),
- ...item.auxiliaryData.keywords.flatMap(keyword => [
- keyword,
- splitWords(keyword),
- ]),
- ];
-}
-
-export function buildSearchPaletteItems({
- components,
- packages,
- docTopics,
- templates,
-}: SearchPaletteDataInput): SearchItem[] {
- const items: SearchItem[] = [];
- const componentLookup = new Map<string, ComponentEntry>();
-
- for (const entries of Object.values(components)) {
- for (const comp of entries) {
- componentLookup.set(comp.name, comp);
- }
- }
-
- for (const entry of flattenComponentSidebarEntries()) {
- const comp = componentLookup.get(entry.name);
- items.push({
- id: entry.href,
- label: entry.displayName,
- auxiliaryData: {
- group: entry.isReady ? 'Component' : 'Canary component',
- isReady: entry.isReady,
- keywords: uniqueKeywords([
- entry.name,
- entry.displayName,
- entry.packageName,
- entry.isReady ? null : 'canary',
- comp?.moduleName,
- ...(comp?.keywords ?? []),
- ]),
- },
- });
- }
-
- for (const pkg of packages) {
- const isTheme = pkg.name.includes('theme-');
- // All themes share the single /themes surface — the per-theme
- // dynamic route was removed in favor of state-driven selection.
- // Search results for theme packages all land on /themes with
- // Neutral as the default seed; users browse to the specific
- // theme they want via the sidebar picker.
- items.push({
- id: isTheme
- ? '/themes'
- : `/docs/${pkg.name.replace('@astryxdesign/', '')}`,
- label: pkg.displayName,
- auxiliaryData: {
- group: pkg.canaryOnly ? 'Canary package' : 'Package',
- isReady: !pkg.canaryOnly,
- keywords: uniqueKeywords([pkg.name, pkg.displayName]),
- },
- });
- }
-
- for (const doc of docTopics) {
- items.push({
- id: `/docs/${doc.topic}`,
- label: doc.title,
- auxiliaryData: {
- group: doc.category === 'guide' ? 'Guide' : 'Foundations',
- isReady: true,
- keywords: uniqueKeywords([doc.topic, doc.title, doc.category]),
- },
- });
- }
-
- for (const tmpl of templates) {
- items.push({
- id: `/templates/${tmpl.slug}`,
- label: tmpl.name,
- auxiliaryData: {
- group: 'Template',
- isReady: true,
- keywords: uniqueKeywords([tmpl.slug, tmpl.name, tmpl.category]),
- },
- });
- }
-
- return items;
-}
diff --git a/apps/docsite/src/lib/cliSearchSource.ts b/apps/docsite/src/lib/cliSearchSource.ts
new file mode 100644
index 0000000000..92c00bed14
--- /dev/null
+++ b/apps/docsite/src/lib/cliSearchSource.ts
@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The search panel's source: each query goes to the site's search API
+ * (app/api/search/route.ts), which runs `astryx search`, and its results come
+ * back in the CLI's order.
+ * @position Consumed by SearchPalette.tsx.
+ *
+ * Items carry no `group`, since CommandPalette orders grouped items by group
+ * and the CLI's order is the answer. Each place on the site is listed once.
+ */
+
+import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';
+import type {SiteSearchResult} from './cliSearchTypes';
+
+export interface CliSearchItem extends SearchableItem<SiteSearchResult> {
+ id: string;
+ label: string;
+ auxiliaryData: SiteSearchResult;
+}
+
+/**
+ * What a selected result opens, as the site's registries name it: the page's
+ * type and its identifier (component name, template slug, doc topic).
+ */
+export function searchTarget(href: string): {item: string; type: string} {
+ const [pathname] = href.split('#');
+ const [, area = '', slug = ''] = pathname.split('/');
+ const type =
+ area === 'components'
+ ? 'component'
+ : area === 'templates'
+ ? 'template'
+ : area === 'themes'
+ ? 'theme'
+ : area === 'docs'
+ ? 'doc'
+ : 'page';
+ return {item: slug || area || 'home', type};
+}
+
+/** The kind a result is, as the panel labels it. */
+export function resultKind(result: SiteSearchResult): string {
+ switch (result.domain) {
+ case 'component':
+ return 'Component';
+ case 'hook':
+ return 'Hook';
+ case 'doc':
+ return 'Docs';
+ case 'template':
+ return result.kind === 'block' ? 'Block' : 'Template';
+ case 'theme':
+ return 'Theme';
+ default:
+ return result.domain;
+ }
+}
+
+/** The panel item for one result, in the order the CLI gave it. */
+export function toSearchItem(
+ result: SiteSearchResult,
+ position: number,
+): CliSearchItem {
+ const label =
+ result.domain === 'doc'
+ ? (result.siteTitle ?? result.title ?? result.name)
+ : (result.displayName ?? result.name);
+ return {
+ // Two results can open the same page (sections, blocks), so the id is
+ // the position, never the link.
+ id: `${position}:${result.domain}:${result.name}${result.section ? `#${result.section}` : ''}`,
+ label,
+ auxiliaryData: result,
+ };
+}
+
+/** How long typing must pause before a query is sent. */
+const DEBOUNCE_MS = 120;
+
+/**
+ * A SearchSource that answers with `astryx search`, through the site's API.
+ * @param fetchSearch - Fetches one query's response; the site passes `fetch`.
+ */
+export function createCliSearchSource(
+ fetchSearch: (url: string, init: RequestInit) => Promise<Response> = (
+ url,
+ init,
+ ) => fetch(url, init),
+): SearchSource<CliSearchItem> & {
+ item(id: string): CliSearchItem | undefined;
+} {
+ // The items of the newest answer, by id, for the panel's selection.
+ let shown = new Map<string, CliSearchItem>();
+ let inFlight: AbortController | null = null;
+
+ return {
+ bootstrap() {
+ return [];
+ },
+ async search(query) {
+ if (query.trim() === '') {
+ return [];
+ }
+ inFlight?.abort();
+ const controller = new AbortController();
+ inFlight = controller;
+ try {
+ await new Promise((resolve, reject) => {
+ const timer = setTimeout(resolve, DEBOUNCE_MS);
+ controller.signal.addEventListener('abort', () => {
+ clearTimeout(timer);
+ reject(controller.signal.reason);
+ });
+ });
+ const response = await fetchSearch(
+ `/api/search?q=${encodeURIComponent(query)}`,
+ {signal: controller.signal},
+ );
+ if (!response.ok) {
+ throw new Error(`search: HTTP ${response.status}`);
+ }
+ const body = (await response.json()) as {
+ data: {results: SiteSearchResult[]};
+ };
+ // Two results can open the same place on the site (a topic and the
+ // page that shows it): the panel lists each place once, at its
+ // first result, keeping the CLI's order.
+ const opened = new Set<string>();
+ const items = body.data.results
+ .filter(result => {
+ if (opened.has(result.href)) return false;
+ opened.add(result.href);
+ return true;
+ })
+ .map(toSearchItem);
+ shown = new Map(items.map(item => [item.id, item]));
+ return items;
+ } catch (error) {
+ if (!controller.signal.aborted) {
+ console.error(error);
+ }
+ return [];
+ }
+ },
+ item(id) {
+ return shown.get(id);
+ },
+ cancel() {
+ inFlight?.abort();
+ inFlight = null;
+ },
+ };
+}
diff --git a/apps/docsite/src/lib/cliSearchTypes.ts b/apps/docsite/src/lib/cliSearchTypes.ts
new file mode 100644
index 0000000000..e2c42f9e74
--- /dev/null
+++ b/apps/docsite/src/lib/cliSearchTypes.ts
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {SearchResultEntry} from '@astryxdesign/cli/api';
+
+/** One `astryx search` result, with the site path it opens and, for a doc,
+ * the title the site shows for it. */
+export type SiteSearchResult = SearchResultEntry & {
+ href: string;
+ siteTitle?: string;
+};
diff --git a/apps/docsite/src/lib/searchLinks.mjs b/apps/docsite/src/lib/searchLinks.mjs
new file mode 100644
index 0000000000..43a14f535f
--- /dev/null
+++ b/apps/docsite/src/lib/searchLinks.mjs
@@ -0,0 +1,236 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Where a search result opens on the site.
+ * @input A result of the CLI's search (`search()` from `@astryxdesign/cli/api`)
+ * and the site's link tables, built with the site by searchLinkTables().
+ * @output The site path the result opens: a component, template, theme, or
+ * doc page, with the anchor of a doc section.
+ * @position Shared by scripts/generate-data.mjs (builds the tables) and the
+ * site's search API (reads them). Plain JS so both can import it.
+ *
+ * The CLI answers with docs-tree routes and section keys, but the site shows
+ * each root namespace as one page with anchors, folds some topics into
+ * another page, and redirects old slugs (scripts/docs-pages.mjs). So a doc
+ * result opens through the pages and redirects the site generated, never by
+ * building `/docs/<route>`.
+ */
+
+/**
+ * @typedef {object} SearchLinkTables
+ * @property {string[]} pages - Every doc page slug.
+ * @property {Record<string, string>} redirects - Slug -> where its text is shown.
+ * @property {Record<string, string>} anchors - `<guide slug>#<section key>`
+ * (or `<page>#<section key>`) -> the path of that section, with its anchor.
+ * @property {string[]} components - Component and hook names with a page.
+ * @property {string[]} templates - Page template slugs with a page.
+ * @property {Record<string, string>} blocks - Block name -> the page that shows it.
+ * @property {Record<string, string>} titles - A doc page's path, or a
+ * section's path with its anchor, -> the title the site shows for it.
+ */
+
+/**
+ * The anchor ids of a page's sections, as the page's outline builds them.
+ * @callback SectionAnchors
+ * @param {Array<{title: string, content?: unknown[]}>} sections
+ * @returns {string[]}
+ */
+
+/**
+ * The tables a result's link is read from.
+ * @param {object} site
+ * @param {Array<{topic: string, title?: string, sections?: Array<{id?: string, title: string}>}>} site.docTopics
+ * @param {Record<string, string>} site.docRedirects
+ * @param {string[]} site.components
+ * @param {string[]} site.templates
+ * @param {Array<{name: string, dirName: string, exampleFor: string | null}>} site.blocks
+ * @param {string[]} site.packagePages - Slugs of package pages (`cli` for
+ * @astryxdesign/cli), which /docs/<slug> also serves.
+ * @param {SectionAnchors} site.sectionAnchors
+ * @returns {SearchLinkTables}
+ */
+export function searchLinkTables(site) {
+ /** @type {Record<string, string>} */
+ const anchors = {};
+ /** @type {Record<string, string>} */
+ const titles = {};
+ // A namespace page (and a merged page) holds the sections of several
+ // guides, and a section key is unique only within its guide. Each guide's
+ // slug redirects to its first section, so the redirects give each guide's
+ // range of sections on the page: a section is keyed by the guide that owns
+ // it, `<guide slug>#<section key>`, the way search names it.
+ /** @type {Map<string, Array<[number, string]>>} page -> [first section index, guide slug] */
+ const starts = new Map();
+ const pageAnchors = new Map(
+ site.docTopics.map(page => [
+ page.topic,
+ site.sectionAnchors(/** @type {any} */ (page.sections ?? [])),
+ ]),
+ );
+ for (const [slug, target] of Object.entries(site.docRedirects)) {
+ const match = /^\/docs\/([^#]+)#(.+)$/.exec(target);
+ if (!match) continue;
+ const index = pageAnchors.get(match[1])?.indexOf(match[2]) ?? -1;
+ if (index < 0) continue;
+ if (!starts.has(match[1])) starts.set(match[1], []);
+ starts.get(match[1])?.push([index, slug]);
+ }
+ for (const page of site.docTopics) {
+ const ids = pageAnchors.get(page.topic) ?? [];
+ const guides = (starts.get(page.topic) ?? []).sort((a, b) => a[0] - b[0]);
+ titles[`/docs/${page.topic}`] = page.title ?? page.topic;
+ (page.sections ?? []).forEach((section, i) => {
+ titles[`/docs/${page.topic}#${ids[i]}`] =
+ `${page.title ?? page.topic} › ${section.title}`;
+ if (!section.id) return;
+ // The guides whose range holds this section: the latest start at or
+ // before it (two slugs can share a start: a namespace with no text of
+ // its own and its first guide).
+ const at = guides.filter(([start]) => start <= i);
+ const owner = at.length ? at[at.length - 1][0] : -1;
+ const keys = [
+ `${page.topic}#${section.id}`,
+ ...at
+ .filter(([start]) => start === owner)
+ .map(([, slug]) => `${slug}#${section.id}`),
+ ];
+ for (const key of keys) {
+ if (!Object.hasOwn(anchors, key))
+ anchors[key] = `/docs/${page.topic}#${ids[i]}`;
+ }
+ });
+ }
+ const components = new Set(site.components);
+ const templates = new Set(site.templates);
+ /** @type {Record<string, string>} */
+ const blocks = {};
+ for (const block of site.blocks) {
+ const owner = block.exampleFor;
+ const href =
+ owner && components.has(owner)
+ ? `/components/${owner}`
+ : owner && templates.has(owner)
+ ? `/templates/${owner}`
+ : null;
+ // Search names a block by its file name, which a Core block's dirName is.
+ if (href)
+ for (const name of [block.dirName, block.name]) blocks[name] ??= href;
+ }
+ return {
+ pages: [
+ ...new Set([
+ ...site.docTopics.map(page => page.topic),
+ ...site.packagePages,
+ ]),
+ ].sort(),
+ redirects: site.docRedirects,
+ anchors,
+ components: [...components].sort(),
+ templates: [...templates].sort(),
+ blocks,
+ titles,
+ };
+}
+
+/** @type {WeakMap<SearchLinkTables, {pages: Set<string>, components: Set<string>, templates: Set<string>}>} */
+const sets = new WeakMap();
+
+/** @param {SearchLinkTables} tables */
+function setsOf(tables) {
+ let hit = sets.get(tables);
+ if (!hit) {
+ hit = {
+ pages: new Set(tables.pages),
+ components: new Set(tables.components),
+ templates: new Set(tables.templates),
+ };
+ sets.set(tables, hit);
+ }
+ return hit;
+}
+
+/**
+ * The page a docs-tree route or topic opens: its own page, the page a
+ * redirect shows it on, else the nearest route above it that has one.
+ * @param {string} route
+ * @param {SearchLinkTables} tables
+ * @returns {string}
+ */
+function docPage(route, tables) {
+ const {pages} = setsOf(tables);
+ for (let at = route; at; at = at.slice(0, Math.max(0, at.lastIndexOf('/')))) {
+ const slug = at.replaceAll('/', '-');
+ if (pages.has(slug)) return `/docs/${slug}`;
+ if (Object.hasOwn(tables.redirects, slug)) return tables.redirects[slug];
+ }
+ return '/docs';
+}
+
+/**
+ * The site path a search result opens.
+ * @param {{domain: string, name: string, package?: string, section?: string, kind?: string}} result
+ * @param {SearchLinkTables} tables
+ * @returns {string}
+ */
+export function searchResultHref(result, tables) {
+ const {components, templates} = setsOf(tables);
+ switch (result.domain) {
+ case 'component':
+ case 'hook':
+ return components.has(result.name)
+ ? `/components/${result.name}`
+ : '/components';
+ case 'template':
+ if (result.kind === 'block') {
+ // A Core block's page is keyed by its name; an integration's by
+ // `<package>-<name>`, as the site names its folder.
+ for (const key of [
+ result.name,
+ `${result.package ?? ''}-${result.name}`.replace(
+ /[^a-zA-Z0-9_-]/g,
+ '-',
+ ),
+ ]) {
+ if (Object.hasOwn(tables.blocks, key)) return tables.blocks[key];
+ }
+ return '/templates';
+ }
+ return templates.has(result.name)
+ ? `/templates/${result.name}`
+ : '/templates';
+ case 'theme':
+ return '/themes';
+ case 'doc': {
+ if (result.section) {
+ // The section where its own guide shows it, else on its page.
+ const own = `${result.name.replaceAll('/', '-')}#${result.section}`;
+ if (Object.hasOwn(tables.anchors, own)) return tables.anchors[own];
+ }
+ const page = docPage(result.name, tables);
+ if (!result.section) return page;
+ const slug = page.replace(/^\/docs\/?/, '').replace(/#.*$/, '');
+ const key = `${slug}#${result.section}`;
+ return Object.hasOwn(tables.anchors, key) ? tables.anchors[key] : page;
+ }
+ default:
+ return '/';
+ }
+}
+
+/**
+ * The title the site shows for a doc result: the title of the page, and of
+ * the section, its link opens, as the sidebar and page outline name them.
+ * Other results keep the CLI's name.
+ * @param {{domain: string, name: string, section?: string, title?: string}} result
+ * @param {string} href - searchResultHref of the result.
+ * @param {SearchLinkTables} tables
+ * @returns {string | undefined}
+ */
+export function searchResultTitle(result, href, tables) {
+ if (result.domain !== 'doc') return undefined;
+ // The page, or the page and section, the result's link opens.
+ if (Object.hasOwn(tables.titles, href)) return tables.titles[href];
+ // A doc with no page of its own (an API or command reference) keeps the
+ // CLI's title, without the docs tree's placeholder level for unfiled docs.
+ return result.title?.replace(/^Unorganized › /, '');
+}
diff --git a/docs/specs/AST-033/spec.md b/docs/specs/AST-033/spec.md
index 72cff51896..2b76792d0d 100644
--- a/docs/specs/AST-033/spec.md
+++ b/docs/specs/AST-033/spec.md
@@ -6,8 +6,8 @@ id: spec:AST-033
authority: current
archive_reason: null
superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-09-29
+approved_by: josephfarina
+approved_at: 2026-10-21
phase: accepted
owners: [cixzhang]
affects_architecture: []
@@ -38,7 +38,8 @@ affects_consumer_docs: [docsite]
"FR19",
"FR20",
"FR21",
- "DEC-7"
+ "DEC-7",
+ "DEC-8"
]
}
}
@@ -85,13 +86,17 @@ for each bug.
readiness state, availability rule, or visibility rule. When no current upstream
owner defines a needed fact, the Docsite reports or routes that authority gap
rather than deciding it in view code.
-- **FR2 — Projections preserve catalog facts.** Gallery, sidebar, search, direct
+- **FR2 — Projections preserve catalog facts.** Gallery, sidebar, direct
routes, detail pages, preview, playground handoff, and Docsite API projections
MUST derive membership and canonical item facts from the generated registries. A
surface MAY define local display order, shorten labels, or derive display-only
groups from canonical fields with a deterministic fallback. Those presentation
choices MUST NOT change catalog membership or be exported or reused as canonical
- taxonomy.
+ taxonomy. Site search answers with the CLI's own search: the site's search
+ endpoint calls `search()` from the CLI package the site builds with and returns
+ its results in the CLI's order, so the site and `astryx search` give one answer.
+ The generated registries stay the source for the pages and links those results
+ open.
- **FR3 — Availability and visibility are separate projections.** Availability
means that a named Docsite operation has the source, loader, route, or handoff
required to present an admitted item on the current content line. Visibility means
@@ -118,7 +123,11 @@ for each bug.
docs, and Docsite-authored content remain workspace-backed on both targets where
the pipeline currently declares that boundary. A projection MUST NOT describe
workspace-backed content as release-pinned merely because the build target is
- `latest`.
+ `latest`. Site search is workspace-backed on both targets: it runs the CLI the
+ site builds with, over the workspace docs and packages that CLI reads, the same
+ source as the site's CLI reference pages. On `latest` it leaves out
+ integrations without published docs, and a result whose page is not published
+ links to the nearest published index page.
- **FR6 — Canary status is projected once at the owning level.** A surface SHOULD
group canary status at the package or category level when children share it,
instead of repeating a marker on every item. The install command, search result,
@@ -309,7 +318,7 @@ exact source already serving those public surfaces.
| Contract | Verification | Representative states | Mutation or failure expectation |
| --------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory | package, component, template, theme; gallery, sidebar, search, direct route, preview, playground | a local map changes membership or a canonical item fact, or availability and visibility collapse into one projection |
+| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory; search endpoint parity with `astryx search --json` | package, component, template, theme; gallery, sidebar, search, direct route, preview, playground | a local map changes membership or a canonical item fact, or availability and visibility collapse into one projection |
| FR4–FR6 | latest/canary generation and projection tests | stable package, canary-only package, ready/unready item, overview-hidden item, invalid integration metadata | latest exposes canary package docs, workspace-backed content is called release-pinned, a second readiness state appears, or projections disagree |
| FR7–FR9 | navigation-family checks plus real-browser navigation/history tests | direct link, modified click, new tab, deep link, primary selection, secondary tab/filter, canonicalization, Back/Forward | Docsite misclassifies a destination, canonical identity diverges, primary selections replace one another, or secondary state clutters history |
| FR10–FR12 | selection/transition tests plus real-browser visible-content checks | initial open, reopen, deep link, direct selection, pending previous/next, close, supersede, reject, unmount | header/body/actions disagree, stale content paints without its owning pending state, or obsolete selection work commits after supersession |
@@ -331,6 +340,8 @@ creating another catalog.
Rejected: page-owned item lists, parallel membership/classification maps, and a
generator inventing product policy absent an upstream owner.
+Site search is governed by DEC-8.
+
### DEC-2 — Browser history follows semantic weight
**Reference:** `spec:AST-033/DEC-2`
@@ -411,6 +422,20 @@ Rejected: continuing a second stable-app build on `gh-pages`, silently dropping
old bookmarks, automatically redirecting every old deep path without recovery
choice, and using the compatibility origin for visual or test evidence.
+### DEC-8 — Site search uses the CLI's search
+
+**Reference:** `spec:AST-033/DEC-8`
+**Decider:** `josephfarina`, `2026-10-21`
+
+Maintainer decision: site search uses the CLI's search instead of a separate index
+derived from the registries, and reads the workspace docs the site builds with on
+every target, so each search improvement reaches the live site. One ranking implementation means every search
+improvement reaches the site with no copy to keep in sync. A parity test holds the
+endpoint equal to `astryx search --json` for the site's project.
+
+Rejected: a site-owned index or ranking, and a browser copy of the CLI's search
+data that has to track every CLI release.
+
## Open questions
None.
diff --git a/packages/cli/api/search/_adapter.mjs b/packages/cli/api/search/_adapter.mjs
index c75aa08d42..30aa50660f 100644
--- a/packages/cli/api/search/_adapter.mjs
+++ b/packages/cli/api/search/_adapter.mjs
@@ -7,7 +7,9 @@
*/
import {readFileSync} from 'node:fs';
+import * as path from 'node:path';
import {requireCoreDir} from '../../foundation/fs/paths.mjs';
+import {recordReads, unchangedSince} from '../../foundation/fs/read-record.mjs';
import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
import {coreDirOrThrow} from '../error.mjs';
import {CORELESS_DOMAINS} from './_query.mjs';
@@ -91,6 +93,43 @@ export async function gatherCandidates(options) {
};
}
+/**
+ * @typedef {Awaited<ReturnType<typeof gatherCandidates>>} Gathered
+ * @type {Map<string, {reads: Map<string, string>, value: Promise<Gathered>}>}
+ */
+const gathered = new Map();
+
+/**
+ * gatherCandidates, reused within one process: a later search in the same
+ * folder, for the same `type`, ranks the candidates an earlier search
+ * gathered when none of the files that gather read, and none of the folders
+ * it listed or probed, changed since (each is checked by its change time and
+ * size, so an edited doc in a linked package is seen on the next call). A
+ * long-running caller (a docs site's search, an agent harness) then pays the
+ * gather once. A one-shot `astryx search` gathers once, as before.
+ * @param {{cwd?: string, type?: string}} options
+ * @returns {Promise<Gathered>}
+ */
+export async function gatherCandidatesReused(options) {
+ const cwd = path.resolve(options.cwd ?? process.cwd());
+ const key = `${cwd}\0${options.type ?? ''}`;
+ const hit = gathered.get(key);
+ if (hit && unchangedSince(hit.reads)) return hit.value;
+ /** @type {Map<string, string>} */
+ const seen = new Map();
+ const value = recordReads(seen, () => gatherCandidates({...options, cwd}));
+ try {
+ await value;
+ } catch (error) {
+ if (gathered.get(key)?.value === value) gathered.delete(key);
+ throw error;
+ }
+ // Each path's state was taken as it was first read, so an edit made while
+ // the gather ran shows as a change on the next call.
+ gathered.set(key, {reads: seen, value});
+ return value;
+}
+
/**
* @typedef {{w: number[], mu: number[], sd: number[]}} SearcherWeights
* @typedef {object} SearchData
diff --git a/packages/cli/api/search/_adapter.test.mjs b/packages/cli/api/search/_adapter.test.mjs
new file mode 100644
index 0000000000..499b245fdb
--- /dev/null
+++ b/packages/cli/api/search/_adapter.test.mjs
@@ -0,0 +1,173 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for search's adapter: a long-running caller reuses the gathered
+ * candidates while their inputs are unchanged (gatherCandidatesReused), and
+ * gathers again when an input changes or for another folder or `type`.
+ *
+ * Whether inputs changed is read-record's answer (tested in
+ * read-record.test.mjs). Other tests running at the same time change shared
+ * folders a gather reads (the temp folder, the repository root), so here the
+ * reuse case holds that answer at "unchanged", and every other case only
+ * checks that a change forces a new gather, which concurrent changes cannot
+ * undo.
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as readRecord from '../../foundation/fs/read-record.mjs';
+import {gatherCandidates, gatherCandidatesReused} from './_adapter.mjs';
+
+vi.mock('../../foundation/fs/read-record.mjs', async original => {
+ const real = /** @type {typeof readRecord} */ (await original());
+ return {...real, unchangedSince: vi.fn(real.unchangedSince)};
+});
+const unchangedSince = vi.mocked(readRecord.unchangedSince);
+
+const SLOW = 60_000;
+
+/** A folder with only a package.json: a docs search there reads the CLI's docs. */
+function scratchProject() {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gather-reuse-'));
+ fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"app"}');
+ return dir;
+}
+
+describe('gatherCandidatesReused', () => {
+ it(
+ 'reuses the gathered candidates while the inputs are unchanged',
+ async () => {
+ const cwd = scratchProject();
+ const first = await gatherCandidatesReused({cwd, type: 'doc'});
+ unchangedSince.mockReturnValueOnce(true);
+ expect(await gatherCandidatesReused({cwd, type: 'doc'})).toBe(first);
+ expect(first.all.length).toBeGreaterThan(0);
+ // The same candidates a fresh gather finds.
+ expect(JSON.parse(JSON.stringify(first))).toEqual(
+ JSON.parse(JSON.stringify(await gatherCandidates({cwd, type: 'doc'}))),
+ );
+ },
+ SLOW,
+ );
+
+ it(
+ 'gathers again when an input file changes',
+ async () => {
+ const cwd = scratchProject();
+ const first = await gatherCandidatesReused({cwd, type: 'doc'});
+ const later = new Date(Date.now() + 5_000);
+ fs.utimesSync(path.join(cwd, 'package.json'), later, later);
+ expect(await gatherCandidatesReused({cwd, type: 'doc'})).not.toBe(first);
+ fs.writeFileSync(
+ path.join(cwd, 'astryx.config.mjs'),
+ 'export default {};\n',
+ );
+ expect(await gatherCandidatesReused({cwd, type: 'doc'})).not.toBe(first);
+ },
+ SLOW,
+ );
+
+ it(
+ 'keeps one entry per folder and type',
+ async () => {
+ const cwd = scratchProject();
+ const docs = await gatherCandidatesReused({cwd, type: 'doc'});
+ const themes = await gatherCandidatesReused({cwd, type: 'theme'});
+ expect(themes).not.toBe(docs);
+ expect(themes.all.every(c => c.domain === 'theme')).toBe(true);
+ expect(
+ await gatherCandidatesReused({cwd: scratchProject(), type: 'doc'}),
+ ).not.toBe(docs);
+ },
+ SLOW,
+ );
+
+ it(
+ 'gathers again when a file the gather read changes, in a linked package too',
+ async () => {
+ // A consumer whose integration is a symlink to a package folder
+ // elsewhere, as a workspace package is.
+ const dir = fs.mkdtempSync(
+ path.join(process.cwd(), '.astryx-gather-reuse-'),
+ );
+ const pkg = fs.mkdtempSync(
+ path.join(os.tmpdir(), 'astryx-linked-widgets-'),
+ );
+ try {
+ fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"consumer"}');
+ fs.writeFileSync(
+ path.join(dir, 'astryx.config.mjs'),
+ "export default { integrations: ['@acme/widgets'] };\n",
+ );
+ fs.mkdirSync(
+ path.join(dir, 'node_modules', '@astryxdesign', 'core', 'src'),
+ {
+ recursive: true,
+ },
+ );
+ fs.mkdirSync(path.join(pkg, 'components'));
+ fs.writeFileSync(
+ path.join(pkg, 'package.json'),
+ '{"name":"@acme/widgets","version":"1.0.0"}',
+ );
+ fs.writeFileSync(
+ path.join(pkg, 'astryx.integration.mjs'),
+ "export default { components: './components' };\n",
+ );
+ fs.writeFileSync(
+ path.join(pkg, 'components', 'FancyGizmo.doc.mjs'),
+ `export default {
+ type: 'component',
+ name: 'FancyGizmo',
+ keywords: ['gizmo'],
+ usage: {description: 'A fancy part.'},
+ props: [],
+ };\n`,
+ );
+ fs.writeFileSync(
+ path.join(pkg, 'components', 'FancyGizmo.tsx'),
+ 'export function FancyGizmo() { return null; }\n',
+ );
+ fs.mkdirSync(path.join(dir, 'node_modules', '@acme'));
+ fs.symlinkSync(
+ pkg,
+ path.join(dir, 'node_modules', '@acme', 'widgets'),
+ 'dir',
+ );
+ const options = {cwd: dir, type: 'component'};
+ const first = await gatherCandidatesReused(options);
+ expect(first.all.map(c => c.name)).toContain('FancyGizmo');
+
+ // A new component in the linked package: its folder changed.
+ fs.writeFileSync(
+ path.join(pkg, 'components', 'TinySprocket.doc.mjs'),
+ `export default {
+ type: 'component',
+ name: 'TinySprocket',
+ keywords: ['sprocket'],
+ usage: {description: 'A small part.'},
+ props: [],
+ };\n`,
+ );
+ fs.writeFileSync(
+ path.join(pkg, 'components', 'TinySprocket.tsx'),
+ 'export function TinySprocket() { return null; }\n',
+ );
+ const second = await gatherCandidatesReused(options);
+ expect(second).not.toBe(first);
+ expect(second.all.map(c => c.name)).toContain('TinySprocket');
+
+ // An edited file the gather read: the linked package's manifest.
+ const later = new Date(Date.now() + 5_000);
+ fs.utimesSync(path.join(pkg, 'package.json'), later, later);
+ expect(await gatherCandidatesReused(options)).not.toBe(second);
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ fs.rmSync(pkg, {recursive: true, force: true});
+ }
+ },
+ SLOW,
+ );
+});
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index 1f57a9db5b..e116468b3d 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -15,7 +15,11 @@
*/
import {withListingCache} from '../../foundation/fs/listing-cache.mjs';
-import {gatherCandidates, loadSearchData} from './_adapter.mjs';
+import {
+ gatherCandidates,
+ gatherCandidatesReused,
+ loadSearchData,
+} from './_adapter.mjs';
import {rankLexical} from './_lexical.mjs';
import {checkSearchArgs} from './_result.mjs';
import {runTree} from '../../foundation/route/route.mjs';
@@ -56,7 +60,7 @@ export async function search(query, options = {}) {
await runTree(
SEARCH_TREE,
{query, options},
- {...(await gatherCandidates(options)), data: loadSearchData()},
+ {...(await gatherCandidatesReused(options)), data: loadSearchData()},
)
),
options.cwd ?? process.cwd(),
diff --git a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
index 2c1fb39b79..2b18a26663 100644
--- a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
+++ b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
@@ -331,6 +331,10 @@ const RUNNERS = {
'require.cache',
],
},
+ 'foundation/fs/read-record.mjs': {
+ runs: "nothing; it wraps node:fs's read calls to record the paths an operation reads, and republishes them to ESM imports",
+ sites: ['module.syncBuiltinESMExports'],
+ },
'foundation/fs/paths.mjs': {
runs: "Yarn's pnpapi, under Plug'n'Play, to find an installed package",
sites: ['require(pnpapi)'],
diff --git a/packages/cli/foundation/fs/read-record.mjs b/packages/cli/foundation/fs/read-record.mjs
new file mode 100644
index 0000000000..5387ff7874
--- /dev/null
+++ b/packages/cli/foundation/fs/read-record.mjs
@@ -0,0 +1,131 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Which files and folders an operation read, so a long-running caller
+ * can tell whether its inputs changed since.
+ *
+ * @input An operation run inside `recordReads(seen, fn)`.
+ * @output `seen` gets every file whose content the operation read through fs
+ * and every folder it listed or probed, each with its state when first
+ * read; `unchangedSince(seen)` says whether all are still in that state.
+ * @position Used by search's adapter to reuse a gathered catalog only while
+ * it is exact. Outside `recordReads` nothing is recorded and every fs call
+ * behaves as before.
+ */
+
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {createRequire, syncBuiltinESMExports} from 'node:module';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+/**
+ * The paths the running operation touched: every file it read and every
+ * folder it listed or probed.
+ * @type {AsyncLocalStorage<Map<string, string>>}
+ */
+const reads = new AsyncLocalStorage();
+
+/** node:fs's module object, whose functions every import of it shares. */
+const fs = createRequire(import.meta.url)('node:fs');
+
+/** The fs reads whose path argument is recorded. */
+const RECORDED = [
+ 'readFileSync',
+ 'readdirSync',
+ 'statSync',
+ 'lstatSync',
+ 'existsSync',
+ 'realpathSync',
+ 'accessSync',
+ 'openSync',
+];
+
+/** The reads that see a file's content, so the file itself is checked. */
+const CONTENT_READS = new Set(['readFileSync', 'openSync']);
+
+let recording = false;
+
+/** fs.statSync as loaded, before installRecorder wraps it. */
+const statSyncRaw = fs.statSync;
+
+/**
+ * Wrap fs's read calls once so that, inside `reads.run`, each path they are
+ * given is added to that run's set. Outside a run they behave exactly as
+ * before.
+ */
+function installRecorder() {
+ if (recording) return;
+ recording = true;
+ for (const name of RECORDED) {
+ const original = fs[name];
+ if (typeof original !== 'function') continue;
+ /**
+ * @this {unknown}
+ * @param {...any} args
+ */
+ const wrapped = function (...args) {
+ const seen = reads.getStore();
+ const target = args[0];
+ if (seen && (typeof target === 'string' || target instanceof URL)) {
+ const file =
+ typeof target === 'string'
+ ? path.resolve(target)
+ : fileURLToPath(target);
+ // A file read is checked itself; a probe or listing is checked by its
+ // folder, whose time changes when an entry is added, removed or
+ // renamed.
+ const checked =
+ CONTENT_READS.has(name) || name === 'readdirSync'
+ ? file
+ : path.dirname(file);
+ // Its state is taken when it is first read, before the read, so a
+ // change made while the operation runs shows as a change afterwards.
+ if (!seen.has(checked)) seen.set(checked, stateOf(checked));
+ }
+ return original.apply(this, args);
+ };
+ Object.assign(wrapped, original);
+ fs[name] = wrapped;
+ }
+ // ESM imports of node:fs see the wrapped functions too.
+ syncBuiltinESMExports();
+}
+
+/**
+ * One path's state: its change time and size, or that it is absent.
+ * @param {string} file
+ * @returns {string}
+ */
+function stateOf(file) {
+ try {
+ const stat = statSyncRaw(file);
+ return `${stat.mtimeMs}\0${stat.size}`;
+ } catch {
+ return '-';
+ }
+}
+
+/**
+ * Whether every recorded path is still in the state it had when it was read.
+ * @param {Map<string, string>} recorded - From recordReads.
+ * @returns {boolean}
+ */
+export function unchangedSince(recorded) {
+ for (const [file, state] of recorded) {
+ if (stateOf(file) !== state) return false;
+ }
+ return true;
+}
+
+/**
+ * Run `fn`, adding to `seen` each path it reads, with that path's state when
+ * it was first read (see the file header).
+ * @template T
+ * @param {Map<string, string>} seen
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function recordReads(seen, fn) {
+ installRecorder();
+ return reads.run(seen, fn);
+}
diff --git a/packages/cli/foundation/fs/read-record.test.mjs b/packages/cli/foundation/fs/read-record.test.mjs
new file mode 100644
index 0000000000..67675c7e7c
--- /dev/null
+++ b/packages/cli/foundation/fs/read-record.test.mjs
@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for read-record: which paths an operation read, and whether
+ * any changed since, including a change made while the operation ran.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {recordReads, unchangedSince} from './read-record.mjs';
+
+function scratch() {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-read-record-'));
+ const file = path.join(dir, 'doc.txt');
+ fs.writeFileSync(file, 'one');
+ return {dir, file};
+}
+
+describe('recordReads', () => {
+ it('records a read file and a listed folder, and sees them unchanged', () => {
+ const {dir, file} = scratch();
+ /** @type {Map<string, string>} */
+ const seen = new Map();
+ recordReads(seen, () => {
+ fs.readFileSync(file, 'utf8');
+ fs.readdirSync(dir);
+ });
+ expect([...seen.keys()]).toEqual(expect.arrayContaining([file, dir]));
+ expect(unchangedSince(seen)).toBe(true);
+ });
+
+ it('sees an edit made after the operation', () => {
+ const {file} = scratch();
+ /** @type {Map<string, string>} */
+ const seen = new Map();
+ recordReads(seen, () => fs.readFileSync(file, 'utf8'));
+ const later = new Date(Date.now() + 5_000);
+ fs.writeFileSync(file, 'two, longer');
+ fs.utimesSync(file, later, later);
+ expect(unchangedSince(seen)).toBe(false);
+ });
+
+ it('sees an edit made while the operation ran, after the file was read', () => {
+ const {file} = scratch();
+ /** @type {Map<string, string>} */
+ const seen = new Map();
+ recordReads(seen, () => {
+ fs.readFileSync(file, 'utf8');
+ const later = new Date(Date.now() + 5_000);
+ fs.writeFileSync(file, 'edited mid-run');
+ fs.utimesSync(file, later, later);
+ });
+ expect(unchangedSince(seen)).toBe(false);
+ });
+
+ it('sees a file added to a folder it probed', () => {
+ const {dir} = scratch();
+ /** @type {Map<string, string>} */
+ const seen = new Map();
+ recordReads(seen, () => fs.existsSync(path.join(dir, 'missing.txt')));
+ const later = new Date(Date.now() + 5_000);
+ fs.writeFileSync(path.join(dir, 'missing.txt'), 'now here');
+ fs.utimesSync(dir, later, later);
+ expect(unchangedSince(seen)).toBe(false);
+ });
+
+ it('records nothing outside an operation', () => {
+ const {file} = scratch();
+ /** @type {Map<string, string>} */
+ const seen = new Map();
+ recordReads(seen, () => {});
+ fs.readFileSync(file, 'utf8');
+ expect(seen.size).toBe(0);
+ });
+});