Skip to content

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

TypeScript

refactor(cli): split build into api/build leaf shape (#4483)

Joeyd3d70198a195
diff --git a/.changeset/cli-build-leaves.md b/.changeset/cli-build-leaves.md
new file mode 100644
index 0000000000..221818446f
--- /dev/null
+++ b/.changeset/cli-build-leaves.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[refactor] CLI: `build` reorganized into the `api/build` leaf shape — `build.mjs` is now a dispatcher + barrel that routes no-query → `build.help` (`api/build/help/help.mjs`) and a query → `build.kit` (`api/build/kit/kit.mjs`), with each leaf projecting its single `{type, data}` envelope. Pure reorganization: the `build` export, the `./api` barrel, and the CLI consumer are unchanged, and the `--json` and human output stay byte-identical for existing usage.
+@josephfarina
diff --git a/packages/cli/api/build/build.mjs b/packages/cli/api/build/build.mjs
index 812239987c..8a728f879d 100644
--- a/packages/cli/api/build/build.mjs
+++ b/packages/cli/api/build/build.mjs
@@ -1,40 +1,23 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file build API — the "assemble a page" assistant, as data.
+ * @file build API — dispatcher + barrel for the "assemble a page" assistant.
*
* `build()` with no query signals the workflow playbook (`build.help`). With a
* query it runs the unified search and groups the results into a composition
- * KIT (`build.kit`): the closest page templates, the blocks that cover parts,
- * and the domain components to fill gaps, plus the always-on frame + foundation.
+ * KIT (`build.kit`). Each shape is projected by its own leaf; this file only
+ * routes to the leaves and re-exports them, keeping the SAME `build` export so
+ * api/index.mjs and the CLI consumer stay unchanged.
*
- * The kit carries RAW `SearchResultEntry` objects and static name arrays only —
- * never pre-formatted command strings. All CLI prefixing (formatCliCommand /
- * getCliInvocation) and the section prose live in the command renderer, so the
- * JSON shape stays package-manager-agnostic and stable across environments.
+ * no query → build.help (api/build/help/help.mjs)
+ * a query → build.kit (api/build/kit/kit.mjs)
*/
-import {search} from '../search/search.mjs';
+import {buildHelp} from './help/help.mjs';
+import {buildKit} from './kit/kit.mjs';
-/** A page at/above this score is a confident direct match. */
-const PAGE_DIRECT = 95;
-/** Below this a page is too weak to offer even as a layout reference. */
-const PAGE_FLOOR = 50;
-/** Below this a block/domain-component match is incidental noise. */
-const DOMAIN_FLOOR = 55;
-
-/**
- * Always-surfaced primitives. Every page needs a shell + layout/typography/
- * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
- * so search alone never returns them. Kept here (not the renderer) because they
- * are ALSO used to exclude these names from the idea-specific `domain` group.
- */
-const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
-const FOUNDATION = [
- 'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
- 'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
-];
-const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+// Barrel: surface the leaves alongside the dispatcher for the fractal shape.
+export {buildHelp, buildKit};
/**
* The page-building assistant. No query → the playbook signal; a query → the
@@ -46,47 +29,7 @@ const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
*/
export async function build(query, options = {}) {
if (!query || !String(query).trim()) {
- return {type: 'build.help', data: {playbook: true}};
+ return buildHelp();
}
-
- const {cwd = process.cwd(), type, limit = 60} = options;
- // search()'s JSDoc @returns widens results to object[]; the SearchResponse
- // shape is the contract (api.d.ts). Cast locally rather than tightening the
- // search @returns (a separate follow-up).
- const result = /** @type {import('../../types/search').SearchResponse} */ (
- await search(query, {cwd, type, limit})
- );
- const results = result.data.results;
-
- const pages = results
- .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
- .slice(0, 3);
- const blocks = results
- .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
- .slice(0, 5);
- const domain = results
- .filter(
- r =>
- (r.domain === 'component' || r.domain === 'hook') &&
- r.score >= DOMAIN_FLOOR &&
- !ALWAYS.has(r.name),
- )
- .slice(0, 6);
- const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
-
- return {
- type: 'build.kit',
- data: {
- query: result.data.query,
- // Distinguishes "search found nothing" (renderer shows "No matches")
- // from a weak-but-non-empty result set (renderer still shows the kit).
- hasResults: results.length > 0,
- directMatch,
- pages,
- blocks,
- domain,
- frame: FRAME,
- foundation: FOUNDATION,
- },
- };
+ return buildKit(query, options);
}
diff --git a/packages/cli/api/build/help/help.mjs b/packages/cli/api/build/help/help.mjs
new file mode 100644
index 0000000000..5f6ff3842c
--- /dev/null
+++ b/packages/cli/api/build/help/help.mjs
@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build.help leaf — the "how to build a page" playbook signal.
+ *
+ * `build` with no query returns this envelope: a pure marker that the command
+ * renderer expands into the workflow playbook prose. It carries no data beyond
+ * `playbook: true`, so the JSON shape stays environment-agnostic and stable.
+ */
+
+/**
+ * The page-building playbook signal (emitted when `build` runs with no query).
+ *
+ * @returns {import('../../../types/build').BuildHelpResponse}
+ */
+export function buildHelp() {
+ return {type: 'build.help', data: {playbook: true}};
+}
diff --git a/packages/cli/api/build/kit/kit.mjs b/packages/cli/api/build/kit/kit.mjs
new file mode 100644
index 0000000000..9880aff4f1
--- /dev/null
+++ b/packages/cli/api/build/kit/kit.mjs
@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build.kit leaf — the grouped composition kit for an idea.
+ *
+ * Runs the unified search for the query and groups the results into a
+ * composition KIT: the closest page templates, the blocks that cover parts,
+ * and the domain components to fill gaps, plus the always-on frame + foundation.
+ *
+ * The kit carries RAW `SearchResultEntry` objects and static name arrays only —
+ * never pre-formatted command strings. All CLI prefixing (formatCliCommand /
+ * getCliInvocation) and the section prose live in the command renderer, so the
+ * JSON shape stays package-manager-agnostic and stable across environments.
+ */
+
+import {search} from '../../search/search.mjs';
+
+/** A page at/above this score is a confident direct match. */
+const PAGE_DIRECT = 95;
+/** Below this a page is too weak to offer even as a layout reference. */
+const PAGE_FLOOR = 50;
+/** Below this a block/domain-component match is incidental noise. */
+const DOMAIN_FLOOR = 55;
+
+/**
+ * Always-surfaced primitives. Every page needs a shell + layout/typography/
+ * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
+ * so search alone never returns them. Kept here (not the renderer) because they
+ * are ALSO used to exclude these names from the idea-specific `domain` group.
+ */
+const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
+const FOUNDATION = [
+ 'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
+ 'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
+];
+const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+
+/**
+ * The grouped composition kit for what you're building.
+ *
+ * @param {string} query what you're building (e.g. "analytics dashboard")
+ * @param {{cwd?: string, type?: import('../../../types/search').SearchDomain, limit?: number}} [options]
+ * @returns {Promise<import('../../../types/build').BuildKitResponse>}
+ */
+export async function buildKit(query, options = {}) {
+ const {cwd = process.cwd(), type, limit = 60} = options;
+ // search()'s JSDoc @returns widens results to object[]; the SearchResponse
+ // shape is the contract (api.d.ts). Cast locally rather than tightening the
+ // search @returns (a separate follow-up).
+ const result = /** @type {import('../../../types/search').SearchResponse} */ (
+ await search(query, {cwd, type, limit})
+ );
+ const results = result.data.results;
+
+ const pages = results
+ .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
+ .slice(0, 3);
+ const blocks = results
+ .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
+ .slice(0, 5);
+ const domain = results
+ .filter(
+ r =>
+ (r.domain === 'component' || r.domain === 'hook') &&
+ r.score >= DOMAIN_FLOOR &&
+ !ALWAYS.has(r.name),
+ )
+ .slice(0, 6);
+ const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
+
+ return {
+ type: 'build.kit',
+ data: {
+ query: result.data.query,
+ // Distinguishes "search found nothing" (renderer shows "No matches")
+ // from a weak-but-non-empty result set (renderer still shows the kit).
+ hasResults: results.length > 0,
+ directMatch,
+ pages,
+ blocks,
+ domain,
+ frame: FRAME,
+ foundation: FOUNDATION,
+ },
+ };
+}