Skip to content

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.md
new file mode 100644
index 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
+
+@ernestt
diff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjs
index 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.mjs
index 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.mjs
index 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,