An open source design system that's fully customizable and agent ready
TypeScript
Compact the generated agent-docs block (#7124)
Joey58e62bc493a4
diff --git a/.changeset/compact-agent-docs-block.md b/.changeset/compact-agent-docs-block.mdnew file mode 100644index 0000000000..feb4f8970b--- /dev/null+++ b/.changeset/compact-agent-docs-block.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] Compact the generated agent-docs block: fewer lines, same behavioral coverage++@josephfarinadiff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjsindex 2fe56539f9..c1c91f50ef 100644--- a/packages/cli/foundation/agent-docs/agent-docs.mjs+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs@@ -424,58 +424,57 @@ export function generateCompressedIndex(// Required setup — components ship precompiled CSS; without these imports// everything renders unstyled. Theme is optional (a default ships in astryx.css).- lines.push('SETUP (once, in your app entry e.g. main.tsx) — without these, components render unstyled:');+ lines.push('SETUP (once, in app entry e.g. main.tsx) — without these, components render unstyled:');lines.push(' import "@astryxdesign/core/reset.css";');lines.push(' import "@astryxdesign/core/astryx.css";');lines.push('');// Workflow — `build` is the front door, and every page starts from the- // template it names.- lines.push('WORKFLOW — start every page from a template. Never lay out a page from scratch:');- lines.push('1. `astryx build "<idea>"` — START HERE: names the [page] template to start from (always one: the closest match, or the app shell), two other templates, and the [block]s + [component]s for parts it lacks. No args = full playbook.');- lines.push('2. `astryx template <name> <path>` — scaffold that template into your project. Keep its frame, gap and padding; replace its data, copy and sections; delete sections you do not need.');- lines.push('3. `astryx template <Block>` for a part the template lacks; `astryx component <Name>` for props + examples before you use or change a component.');- lines.push('Changing a page you already have? Keep it: skip step 2 and add blocks and components inside its sections.');+ // template it names. build/template/component are covered here, so they are+ // intentionally omitted from the command reference below.+ lines.push('WORKFLOW — start every page from a template, never from scratch:');+ lines.push('1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.');+ lines.push('2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.');+ lines.push('3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.');+ lines.push('Changing an existing page? Keep it: skip step 2 and add blocks/components inside its sections.');lines.push('');// Rules — the top error-preventers.lines.push('RULES:');- lines.push('- No <div> — components do all layout/spacing, page frame included.');- lines.push('- Frame first: the template you scaffold sets the page frame. Read `astryx docs layout` for the principles — region widths, breakpoint behavior.');- lines.push('- Dense data = rows (Table, List/Item), never Card-wrapped list items; Card is for standalone widgets. Status = StatusDot/Token; Badge = counts only.');+ lines.push('- No <div> — components handle all layout and spacing.');+ lines.push('- Read `astryx docs layout` before changing a template\'s frame.');+ lines.push('- Dense data = rows (Table, List/Item), not Card-wrapped lists. Badge = counts only.');// Styling guidance tailored to the project's configured system — never// recommend a path that isn't compiled here (xstyle needs the StyleX compiler;// utilities need Tailwind). Tokens are always the source of truth.if (stylingSystem === 'stylex') {- lines.push('- Custom styling: component props first; else the xstyle prop / StyleX tokens (@astryxdesign/core/theme/tokens.stylex). No raw hex/px.');+ lines.push('- Style with component props first, then the xstyle prop / StyleX tokens. No raw hex/px.');} else if (stylingSystem === 'tailwind') {- lines.push('- Custom styling: component props first; else Tailwind utilities backed by tokens (bg-surface, text-primary, rounded-lg) via tailwind-theme.css. No raw hex/px.');+ lines.push('- Style with component props first, then Tailwind utilities backed by tokens. No raw hex/px.');} else {- lines.push("- Custom styling: component props first; else style/className with tokens — var(--color-*|--spacing-*|--radius-*). No raw hex/px. (No StyleX/Tailwind compiler here — don't use xstyle/utility classes.)");+ lines.push("- Style with component props first, then tokens (var(--color-*|--spacing-*|--radius-*)). No raw hex/px. No StyleX/Tailwind compiler here — don't use xstyle/utility classes.");}- lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent belongs in the theme. Run `astryx theme list`, install a package, and `theme add <slug> --import` to import its built theme through the generated app module. Extend that theme to customize it. Use `theme eject <slug>` only to fork source and `astryx theme template` for a new theme — never override --color-* in :root.');+ lines.push('- Palettes and custom colors go through the theme, never :root overrides. See `astryx docs theme`.');// Self-check — post-generation pass. Validated via vibe tests (internal/vibe-tests/// prompt-purity-test): on complex multi-step UIs the rules above alone still leave raw// CSS in ~11-13% of runs; a re-read-and-fix pass cuts that ~4x at negligible token cost.- // The fix names the sanctioned escape hatch for the configured system.const selfCheckFix = {stylex:- 'replace any className=, style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded #hex/px with the component or the xstyle prop + a token',+ 'replace any className=, style={{…}}, raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or the xstyle prop + a token',tailwind:- 'replace any style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded/arbitrary value (e.g. bg-[#fff], p-[13px]) with the component or a token-backed utility',- css: 'replace any raw <div>/<span> layout, imported .css/@apply, or hardcoded value (#hex, 16px) with the component or a token (var(--color-*|--spacing-*|…))',+ 'replace any style={{…}}, raw <div>/<span>, imported .css/@apply, or hardcoded/arbitrary value (bg-[#fff], p-[13px]) with the component or a token-backed utility',+ css: 'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token',};lines.push(- `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. Confirm the page kept its template's frame, gap and padding. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,+ `- SELF-CHECK: re-read the file; ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}.`,);lines.push('');- // Command reference — build/template/component are covered in WORKFLOW above.- lines.push('MORE CLI:');- lines.push(' search "<query>" find any component / hook / doc / template / block / theme');- lines.push(' discover <words> integrations you could add, and the ones you have');- lines.push(` component --list ${componentCount} components by category`);- lines.push(' template --list page + block recipes');+ // build/template/component are covered in WORKFLOW above and intentionally+ // omitted here. `astryx help` is the full reference.+ lines.push('`astryx help` lists every command. Key ones beyond the workflow:');+ lines.push(' search "<query>" find any component / hook / doc / template');+ lines.push(' discover <words> integrations you could add');const docsDir = path.join(CLI_ROOT, 'assets', 'docs');const resolvedTopics =topics ??@@ -488,11 +487,14 @@ export function generateCompressedIndex(.sort(): []);if (resolvedTopics.length > 0) {- lines.push(` docs <topic> ${resolvedTopics.join(', ')}`);+ // Show key topics inline, point at `astryx docs` for the full list.+ const keyTopics = ['getting-started', 'principles', 'tokens', 'theme'];+ const shown = keyTopics.filter(t => resolvedTopics.includes(t));+ const suffix = resolvedTopics.length > shown.length ? ' …' : '';+ lines.push(` docs <topic> ${shown.join(', ')}${suffix} (\`astryx docs\` lists all)`);}- lines.push(' docs cli commands, API reference, integration authoring (one level at a time)');- lines.push(' swizzle <Name> eject component source for deep customization');- lines.push(' upgrade --from <old version> --apply run after any Astryx or integration dependency bump');+ lines.push(' docs cli commands, API reference, integration authoring');+ lines.push(' upgrade --from <old version> --apply run after a dependency bump');const appendCount = agentDocs.reduce((count, contribution) => count + contribution.append.length,0,diff --git a/packages/cli/foundation/agent-docs/agent-docs.test.mjs b/packages/cli/foundation/agent-docs/agent-docs.test.mjsindex 797ca865a4..2b87ba05eb 100644--- a/packages/cli/foundation/agent-docs/agent-docs.test.mjs+++ b/packages/cli/foundation/agent-docs/agent-docs.test.mjs@@ -43,14 +43,14 @@ describe('generateCompressedIndex', () => {it('includes theme nudge rule', () => {const result = generateCompressedIndex('1.0.0');- expect(result).toMatch(/astryx theme/);- expect(result).toMatch(/never override --color-/);+ expect(result).toMatch(/astryx docs theme/);+ expect(result).toMatch(/never :root/);});it('sends frame choice to the layout doc rather than naming a shell', () => {const result = generateCompressedIndex('1.0.0');- const frameRule = result.split('\n').find(l => l.includes('Frame first'));- expect(frameRule).toContain('astryx docs layout');+ const frameRule = result.split('\n').find(l => l.includes('astryx docs layout'));+ expect(frameRule).toBeDefined();expect(result).not.toMatch(/AppShell/);expect(frameRule).not.toMatch(/https?:/);});@@ -60,24 +60,22 @@ describe('generateCompressedIndex', () => {const workflow = lines.findIndex(l => l.startsWith('WORKFLOW'));expect(lines[workflow]).toMatch(/start every page from a template/);expect(lines[workflow + 1]).toMatch(/^1\. `astryx build /);- expect(lines[workflow + 2]).toMatch(/^2\. `astryx template <name> <path>`/);+ expect(lines[workflow + 2]).toMatch(/^2\. .*keep its frame, gap and padding/);expect(lines.join('\n')).not.toMatch(/reference code/);});it('includes the post-generation self-check rule', () => {const result = generateCompressedIndex('1.0.0');- expect(result).toContain('SELF-CHECK before you finish');+ expect(result).toContain('SELF-CHECK');expect(result).toMatch(/re-read the file/);- expect(result).toMatch(/don't hand-roll CSS/);+ expect(result).toMatch(/component or a token/);});it('tailors the self-check to the styling system (xstyle for StyleX, not className for Tailwind)', () => {- // StyleX path: className/inline style are veers; the fix is the xstyle prop + a tokenconst stylex = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});const stylexSelfCheck = stylex.split('\n').find(l => l.includes('SELF-CHECK'));expect(stylexSelfCheck).toMatch(/xstyle/);expect(stylexSelfCheck).toMatch(/className=/);- // className IS the system in Tailwind — it must NOT be flaggedconst tailwind = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});const tailwindSelfCheck = tailwind.split('\n').find(l => l.includes('SELF-CHECK'));expect(tailwindSelfCheck).toBeDefined();@@ -86,10 +84,11 @@ describe('generateCompressedIndex', () => {it('defaults to the CSS-variable styling path (no compiler)', () => {const result = generateCompressedIndex('1.0.0');- expect(result).toMatch(/style\/className with tokens/);- expect(result).toMatch(/var\(--color-\*/);+ expect(result).toMatch(/tokens.*var\(--color-/);// Must NOT push xstyle when no StyleX compiler is present.expect(result).not.toMatch(/xstyle prop/);+ // Must warn that no compiler is present.+ expect(result).toMatch(/No StyleX\/Tailwind compiler/);});it('recommends xstyle when StyleX is configured', () => {@@ -99,23 +98,22 @@ describe('generateCompressedIndex', () => {it('recommends Tailwind utilities when Tailwind is configured', () => {const result = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});- expect(result).toMatch(/Tailwind utilities backed by tokens/);- expect(result).toMatch(/tailwind-theme\.css/);+ expect(result).toMatch(/Tailwind utilities/);});it('includes upgrade command and migration rule', () => {const result = generateCompressedIndex('1.0.0');// `upgrade --apply` alone stops with "Missing required --from".expect(result).toContain('upgrade --from <old version> --apply');- expect(result).toMatch(/after any Astryx or integration dependency bump/);+ expect(result).toMatch(/after a dependency bump/);});it('points agents at discover for integrations they could add', () => {const result = generateCompressedIndex('1.0.0');// Without this line no surface an agent reads names `discover`, and agents// look for a theme in the package registry instead.- expect(result).toMatch(/^ {2}discover <words> {3}integrations you could add, and the ones you have$/m);- expect(result).toMatch(/^ {2}search "<query>" .*\/ theme$/m);+ expect(result).toMatch(/^ {2}discover <words> {3}integrations you could add$/m);+ expect(result).toMatch(/^ {2}search "<query>"/m);});it('states the invocation once in the CLI header (yarn)', () => {@@ -144,20 +142,14 @@ describe('generateCompressedIndex', () => {);}- it('names the hyphenated topics, which the scan used to drop', () => {- // The fallback scan matched `\w+`, which does not match `-`, so five real- // topics were missing from every block ever written. An agent cannot ask- // for a topic it was never told about, and `getting-started` — the one it- // should reach for first — was one of them.+ it('keeps hyphenated key topics visible and points at astryx docs for the rest', () => {+ // The compact block shows key topics inline; the full list is via+ // `astryx docs`. `getting-started` is a hyphenated key topic that the old+ // \w+ scan used to drop — it must stay visible.const line = topicLine(generateCompressedIndex('1.0.0'));- for (const topic of [- 'getting-started',- 'browser-support',- 'styling-libraries',- 'working-with-ai',- ]) {- expect(line).toContain(topic);- }+ expect(line).toContain('getting-started');+ expect(line).toContain('principles');+ expect(line).toContain('astryx docs');});it('points to the CLI docs tree on a line of its own', () => {@@ -165,19 +157,22 @@ describe('generateCompressedIndex', () => {// the topic line no longer names it; the tree's entry point does.const block = generateCompressedIndex('1.0.0');expect(block).toContain(- ' docs cli commands, API reference, integration authoring (one level at a time)',+ ' docs cli commands, API reference, integration authoring',);expect(topicLine(block)).not.toContain('cli-integrations');});- it('lists the topics it is given, so an integration’s reach the agent', () => {+ it('shows key topics from the given list and points at astryx docs for the rest', () => {const line = topicLine(generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),);- expect(line).toContain('tokens, deploying');- // The project's catalog replaces the built-in scan rather than adding to it:- // a topic an integration replaced must not also be listed under its old name.+ // 'tokens' is a key topic present in the given list, so it appears inline.+ expect(line).toContain('tokens');+ // The project's catalog replaces the built-in scan: a built-in topic not+ // in the given list must not appear.expect(line).not.toContain('typography');+ // Agents reach the full list via 'astryx docs'.+ expect(line).toContain('astryx docs');});it('omits the line entirely when the project has no topics', () => {diff --git a/packages/cli/foundation/agent-docs/app-theme-workflow.test.mjs b/packages/cli/foundation/agent-docs/app-theme-workflow.test.mjsindex 51e8978069..610cbc1090 100644--- a/packages/cli/foundation/agent-docs/app-theme-workflow.test.mjs+++ b/packages/cli/foundation/agent-docs/app-theme-workflow.test.mjs@@ -4,13 +4,10 @@ import {describe, expect, it} from 'vitest';import {generateCompressedIndex} from './agent-docs.mjs';describe('generated agent docs app-theme workflow', () => {- it('keeps the add, extend, and eject guidance together', () => {+ it('points agents at the theme doc and guards :root overrides', () => {const result = generateCompressedIndex('1.0.0');- expect(result).toContain('theme add <slug> --import');- expect(result).toContain('generated app module');- expect(result).toContain('Extend that theme');- expect(result).toContain('theme eject <slug>` only to fork source');- expect(result).toContain('never override --color-');+ expect(result).toContain('astryx docs theme');+ expect(result).toContain('never :root overrides');});});diff --git a/packages/cli/test/docs-graph.test.mjs b/packages/cli/test/docs-graph.test.mjsindex 5c4d7b9e39..0f0fe5c224 100644--- a/packages/cli/test/docs-graph.test.mjs+++ b/packages/cli/test/docs-graph.test.mjs@@ -562,14 +562,17 @@ describe('the docs graph', () => {for (const each of shownCommands(block)) {if (!shown.has(each)) shown.set(each, 'the agent prompt in AGENTS.md');}- // The block `astryx init` writes into an app's AGENTS.md. Its MORE CLI+ // The block `astryx init` writes into an app's AGENTS.md. Its key-commands// lines are bare subcommands, each followed by its description.const appBlock = generateCompressedIndex('0.0.0', {invocation: 'npx astryx'});for (const each of shownCommands(appBlock)) {if (!shown.has(each)) shown.set(each, 'the agent block astryx init writes');}- const more = (appBlock.split('MORE CLI:')[1] ?? '').split(/\n\s*\n/)[0];- const bare = [...more.matchAll(/^ {2}(\S.*?)(?: {3,}|$)/gm)].map(m => `astryx ${m[1]}`);+ // The compact block lists key commands after a prose lead-in, indented by+ // two spaces. build/template/component are intentionally omitted because+ // they are covered in the WORKFLOW section above the command list.+ const keySection = (appBlock.split('Key ones beyond the workflow:')[1] ?? '').split(/\n\s*\n/)[0];+ const bare = [...keySection.matchAll(/^ {2}(\S.*?)(?: {3,}|$)/gm)].map(m => `astryx ${m[1]}`);expect(bare.length).toBeGreaterThan(3);for (const each of bare) {if (!shown.has(each)) shown.set(each, 'the agent block astryx init writes');