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.mdnew file mode 100644index 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.+@josephfarinadiff --git a/packages/cli/api/build/build.mjs b/packages/cli/api/build/build.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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,+ },+ };+}