An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): a thin build kit says what to try instead of looking empty (#5938)
Joey030fd6761218
diff --git a/.changeset/build-thin-kit-hint.md b/.changeset/build-thin-kit-hint.mdnew file mode 100644index 0000000000..5e0efdb574--- /dev/null+++ b/.changeset/build-thin-kit-hint.md@@ -0,0 +1,17 @@+---+'@astryxdesign/cli': patch+---++[fix] A thin `build` kit now says what to try instead of looking empty.++`build "quantum flux capacitor telemetry"` returned one incidental component and the always-on frame list, and said nothing else. An agent reading that does not conclude its wording was wrong — it concludes the package has nothing and falls back on its own memory of what Astryx contains, which is the failure `build` exists to prevent.++Below three offerable results the kit carries a `hint` naming the two commands that browse rather than search, and saying plainly that this is keyword matching, not semantic. The threshold counts what SURVIVED the score floors, not what search returned: `hasResults` is already true for a query that matched things and then filtered them all out, and that is the case most likely to be misread.++`hint` is structured — `{reason, commands}` with bare subcommands — not a sentence with commands baked into it. The API cannot know how a project invokes the CLI, and a hardcoded `astryx component --list` does not resolve in a pnpm workspace, where every other command in this output renders as `pnpm exec astryx`. The renderer formats them through `formatCliCommand`, so they are runnable as printed, and a JSON caller gets the parts rather than prose to re-parse.++`hint` is present only when it applies, so a healthy kit is byte-identical to before. The CLI renders it last, as a `FEW MATCHES` section listed in the legend's section order, so it is the line the reader leaves with.++Split out of #5320 at review request. Public response doc (`build.doc.mjs`) and the `BuildKitResponse` type both updated.++@josephfarinadiff --git a/packages/cli/api/build/build.doc.mjs b/packages/cli/api/build/build.doc.mjsindex 76fe5e72f2..3d9fbc1646 100644--- a/packages/cli/api/build/build.doc.mjs+++ b/packages/cli/api/build/build.doc.mjs@@ -59,7 +59,7 @@ export const doc = {{type: 'build.kit',description:- 'The grouped composition kit: the echoed query, hasResults/matchCount/directMatch fields, the closest page templates (≤3), drop-in block patterns (≤5), idea-specific components/hooks (≤6), and the always-on frame + foundation component-name arrays.',+ 'The grouped composition kit: the echoed query, hasResults/matchCount/directMatch fields, the closest page templates (≤3), drop-in block patterns (≤5), idea-specific components/hooks (≤6), and the always-on frame + foundation component-name arrays. Carries `hint` only when the kit came back thin — what to try instead, so a caller does not read a near-empty kit as "the package has nothing".',},],throws: [diff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjsindex bb86a74c5a..debaac6973 100644--- a/packages/cli/api/build/build.test.mjs+++ b/packages/cli/api/build/build.test.mjs@@ -148,3 +148,47 @@ describe('build kit — coverage gates the pages group', () => {for (const p of r.data.pages) expect(p.queryTerms).toBe(1);});});++describe('build kit — a thin kit says what to try next', () => {+ it('hints when the kit comes back nearly empty', async () => {+ // An agent reading a near-empty kit does not conclude "my wording was+ // wrong" — it concludes the package has nothing and falls back on its own+ // memory of Astryx, which is the failure `build` exists to prevent.+ const r = await build('quantum flux capacitor telemetry', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ expect(r.data.pages.length + r.data.blocks.length + r.data.domain.length).toBeLessThan(3);+ expect(r.data.hint?.reason).toMatch(/keyword search/i);+ expect(r.data.hint?.commands).toEqual(['component --list', 'template --list']);+ });++ it('carries no hint when the kit is healthy', async () => {+ const r = await build('dashboard', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ expect(r.data.hint).toBeUndefined();+ });++ it('hints for a matched-then-filtered query: hasResults true, nothing offerable', async () => {+ // The case most likely to be misread, and the reason the threshold counts+ // what SURVIVED the floors rather than what search returned.+ const r = await build('blockchain', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ expect(r.data.hasResults).toBe(true);+ expect(r.data.pages.length + r.data.blocks.length + r.data.domain.length).toBe(0);+ expect(r.data.hint).toBeTruthy();+ });++ 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.+ const r = await build('quantum flux capacitor telemetry', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ for (const c of r.data.hint?.commands ?? []) {+ expect(c).not.toMatch(/^astryx\b/);+ expect(c).not.toMatch(/pnpm|npx|yarn|bun/);+ }+ });+});diff --git a/packages/cli/api/build/build.type.mjs b/packages/cli/api/build/build.type.mjsindex bad56fcb65..ed7854abf4 100644--- a/packages/cli/api/build/build.type.mjs+++ b/packages/cli/api/build/build.type.mjs@@ -34,6 +34,7 @@* @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.* @property {string[]} data.foundation Always-on layout/typography/action component names.+ * @property {{reason: string, commands: string[]}} [data.hint] Present only when the kit is thin. `reason` says why, `commands` are bare subcommands (e.g. `component --list`) for the caller to render with its own invocation — so a reader is never handed a command that does not resolve in their project.*//**diff --git a/packages/cli/api/build/kit/kit.mjs b/packages/cli/api/build/kit/kit.mjsindex decbd2a966..85f0c37fef 100644--- a/packages/cli/api/build/kit/kit.mjs+++ b/packages/cli/api/build/kit/kit.mjs@@ -35,6 +35,15 @@ const DOMAIN_FLOOR = 55;* not the same claim as matching three.*/const PAGE_COVERAGE = 0.5;+/**+ * Fewer offerable results than this and the kit says how to look further.+ *+ * Three is the point below which a kit stops being a starting point. An agent+ * that reads a near-empty kit does not conclude "my wording was wrong" — it+ * concludes the package has nothing and falls back on its own memory of what+ * Astryx contains, which is exactly the failure `build` exists to prevent.+ */+const THIN_KIT = 3;/*** Always-surfaced primitives. Every page needs a shell + layout/typography/@@ -115,6 +124,24 @@ export async function buildKit(query, options = {}) {.slice(0, 6);const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;+ // 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+ // search, and say plainly that this is not semantic matching.+ //+ // STRUCTURED, not prose: `commands` are bare subcommands, because the API+ // cannot know how the caller invokes the CLI. Baking `astryx component+ // --list` into the text hands a pnpm-workspace reader a command that does+ // not resolve — the same defect `getCliInvocation` exists to prevent, and+ // the renderer applies it. A JSON caller gets the parts, not a sentence.+ const hint =+ pages.length + blocks.length + domain.length < THIN_KIT+ ? {+ reason: 'Few matches. This is keyword search, not semantic — try other wordings.',+ commands: ['component --list', 'template --list'],+ }+ : undefined;+return {type: 'build.kit',data: {@@ -129,6 +156,7 @@ export async function buildKit(query, options = {}) {domain,frame: FRAME,foundation: FOUNDATION,+ hint,},};}diff --git a/packages/cli/clients/cli/commands/build.mjs b/packages/cli/clients/cli/commands/build.mjsindex c9b5472e8e..f172a106b5 100644--- a/packages/cli/clients/cli/commands/build.mjs+++ b/packages/cli/clients/cli/commands/build.mjs@@ -132,6 +132,7 @@ export function registerBuild(program) {domain,frame,foundation,+ hint,} = result.data;recordResultSummary([...pages, ...blocks, ...domain], {directMatch,@@ -189,6 +190,9 @@ export function registerBuild(program) {if (blocks.length) sectionsOrder.push('BLOCKS');if (domain.length) sectionsOrder.push('DOMAIN COMPONENTS');sectionsOrder.push('FRAME + FOUNDATION');+ // The legend promises the complete order, so a section emitted after it+ // has to be in it.+ if (hint) sectionsOrder.push('FEW MATCHES');/** @type {import('../formatters/index.mjs').Block[]} */const out = [@@ -239,6 +243,21 @@ export function registerBuild(program) {}),);+ // Last, so it is the line the reader leaves with — and only when the kit+ // was thin enough that "the package has nothing" is the wrong conclusion.+ // The commands arrive bare and are rendered through the project's own+ // invocation, so they are runnable as printed.+ if (hint) {+ out.push(+ section(+ 'FEW MATCHES',+ `${hint.reason}\nBrowse instead:\n${hint.commands+ .map(c => formatCliCommand(c))+ .join('\n')}`,+ ),+ );+ }+emit(...out);},});