An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): recommend --skeleton in the build kit payload, not just the prose (#6255)
Ernest6ee849a77334
diff --git a/.changeset/build-kit-skeleton-command.md b/.changeset/build-kit-skeleton-command.mdnew file mode 100644index 0000000000..ba12c298d4--- /dev/null+++ b/.changeset/build-kit-skeleton-command.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] build: recommend `template <name> --skeleton` in the kit payload when the top page is not a direct match, matching what the renderer already tells a human++@ernesttdiff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjsindex 1e1b238628..a6c81c2668 100644--- a/packages/cli/api/build/build.test.mjs+++ b/packages/cli/api/build/build.test.mjs@@ -198,6 +198,43 @@ describe('build kit — a thin kit says what to try next', () => {expect(r.data.hint).toBeTruthy();});+ it('recommends reading the layout, not scaffolding it, on a loose match', async () => {+ // The kit already decides this: `directMatch` false means the top page is+ // a reference, and the renderer says so in prose. The page's `command` is+ // what a program reads instead of that prose, so it has to agree — before+ // this it still said `template <name>`, the scaffold.+ const r = await build('notifications', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ expect(r.data.directMatch).toBe(false);+ expect(r.data.pages.length).toBeGreaterThan(0);+ for (const page of r.data.pages) {+ expect(page.command).toMatch(/--skeleton$/);+ }+ });++ it('recommends scaffolding on a direct match', async () => {+ const r = await build('contact form', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ expect(r.data.directMatch).toBe(true);+ expect(r.data.pages.length).toBeGreaterThan(0);+ for (const page of r.data.pages) {+ expect(page.command).not.toMatch(/--skeleton/);+ }+ });++ it('keeps the recommendation package-manager-agnostic', async () => {+ // Appending a flag must not turn into prefixing an invocation; that stays+ // the renderer's job.+ const r = await build('notifications', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ for (const page of r.data.pages) {+ expect(page.command).not.toMatch(/^(pnpm|npm|yarn|bun|npx)\b/);+ }+ });+it('keeps recovery commands bare, for the caller to render', async () => {// The API cannot know how a project invokes the CLI. A baked-in `astryx// component --list` does not resolve in a pnpm workspace.diff --git a/packages/cli/api/build/build.type.mjs b/packages/cli/api/build/build.type.mjsindex 886c6350f2..dac858ec60 100644--- a/packages/cli/api/build/build.type.mjs+++ b/packages/cli/api/build/build.type.mjs@@ -29,7 +29,7 @@* @property {boolean} data.hasResults False when search returned nothing (renderer shows "No matches").* @property {number} data.matchCount Total ranked search matches for the query — counted before the search `limit`, the kit's score floors, and its per-group caps, so it is never a cap read back.* @property {boolean} data.directMatch True when the top page template is a confident direct match.- * @property {import('../search/search.type.mjs').SearchResultEntry[]} data.pages Closest page templates (≤3).+ * @property {import('../search/search.type.mjs').SearchResultEntry[]} data.pages Closest page templates (≤3). Each entry's `command` carries `--skeleton` when `directMatch` is false, so it recommends reading the layout rather than scaffolding it.* @property {import('../search/search.type.mjs').SearchResultEntry[]} data.blocks Drop-in block patterns covering parts of the idea (≤5).* @property {import('../search/search.type.mjs').SearchResultEntry[]} data.domain Idea-specific components/hooks (≤6), excluding frame/foundation.* @property {string[]} data.frame Always-on page-shell component names.diff --git a/packages/cli/api/build/kit/kit.mjs b/packages/cli/api/build/kit/kit.mjsindex 3b76534891..ecea1e8319 100644--- a/packages/cli/api/build/kit/kit.mjs+++ b/packages/cli/api/build/kit/kit.mjs@@ -11,6 +11,11 @@* 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.+ *+ * The one adjustment it makes is on a page's `command`: when the top page is+ * not a direct match the kit appends `--skeleton`, so the field agrees with+ * the recommendation the kit itself computed. That is still not prefixing —+ * the invocation stays the renderer's job.*/import {search} from '../../search/search.mjs';@@ -132,6 +137,31 @@ export async function buildKit(query, options = {}) {.slice(0, 6);const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;+ /**+ * On a loose match, recommend reading the layout rather than scaffolding it.+ *+ * A page entry's `command` is what a caller runs next, and it was always the+ * scaffold command — `template <name>` — even when the kit had just decided+ * the top page was NOT a direct match. The renderer already says the right+ * thing to a human in that case: RECOMMENDED START prints+ * `template <name> --skeleton` and the PAGE TEMPLATES heading reads "use as+ * a layout reference". But prose is not what a program reads. A JSON caller+ * takes `command` and gets the scaffold, so the two audiences were given+ * opposite advice from the same kit.+ *+ * That matters most for the caller least able to notice. `template <name>`+ * emits the whole page, and an agent handed a full template it did not quite+ * ask for tends to adapt it anyway — which is how a request for one thing+ * comes back as a competent version of another. `--skeleton` gives the+ * layout without the invitation.+ *+ * Copied rather than mutated: these entries come from `search()` and are not+ * this function's to modify.+ */+ const recommendedPages = directMatch+ ? pages+ : pages.map(page => ({...page, command: `${page.command} --skeleton`}));+// What to try when the kit comes back thin. Keyword search over a design// system misses in a predictable way — the reader's words and the package's// often do not overlap — so name the two commands that browse rather than@@ -160,7 +190,7 @@ export async function buildKit(query, options = {}) {hasResults: matchCount > 0,matchCount,directMatch,- pages,+ pages: recommendedPages,blocks,domain,frame: FRAME,