An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): the global skill gives a concrete build workflow (#7893)
Joeybe423330bc38
diff --git a/.changeset/cli-skill-build-workflow.md b/.changeset/cli-skill-build-workflow.mdnew file mode 100644index 0000000000..4ecf5d42ef--- /dev/null+++ b/.changeset/cli-skill-build-workflow.md@@ -0,0 +1,8 @@+---+'@astryxdesign/cli': patch+'@astryxdesign/core': patch+---++[fix] The agent guide that global mode writes to the home folder now says how to build, not only how to find things. It tells agents to work in a project folder (creating one if there is none) with `@astryxdesign/core` and `@astryxdesign/cli` added to a new project or one without Core, or, in a project that already has `@astryxdesign/core`, the CLI at the same version, and `astryx init` run there, then gives the same template-first workflow and self-check the project agent docs give, and ends with building the project and delivering that build. Before, agents that found the right template could still build the page with a tool that cannot install packages and deliver a page with no Astryx in it. The guide stays version-free and names only commands every release keeps. The project agent docs are unchanged, and so is what `@astryxdesign/core`'s install script prints: its copy of the shared agent-docs file only gains the same workflow lines.++@josephfarinadiff --git a/docs/specs/AST-081-global-mode/spec.md b/docs/specs/AST-081-global-mode/spec.mdindex 0234b29ab3..ba45187f7b 100644--- a/docs/specs/AST-081-global-mode/spec.md+++ b/docs/specs/AST-081-global-mode/spec.md@@ -403,6 +403,11 @@ works on is `spec:AST-040` FR9's.start with `astryx search`; it names no version, no release-specificcommand or prop, and only entry points every release keeps (`search`,`docs`, `component`, and the like), so an older copy never misleads.+ It also gives the build route the project agent docs give, through their+ shared workflow wording: work in a project folder, new or existing, adding+ `@astryxdesign/core` and `@astryxdesign/cli`, or, where the project already+ installs Core, the CLI at that Core's version; run `astryx init` there; then+ start from a template, check, and deliver the built project.- The computer-level text is one file, `.agents/skills/astryx/SKILL.md` inthe home folder, which most agent tools read. The computer-level agentfiles table below names each other folder it reaches: a folder link to itsdiff --git a/packages/cli/foundation/agent-docs/agent-doc-state.mjs b/packages/cli/foundation/agent-docs/agent-doc-state.mjsindex d9b6d38b80..9b02eced3a 100644--- a/packages/cli/foundation/agent-docs/agent-doc-state.mjs+++ b/packages/cli/foundation/agent-docs/agent-doc-state.mjs@@ -34,6 +34,26 @@ export const CURSOR_RULES = '.cursorrules';export const HERMES_DOT_MD = '.hermes.md';export const HERMES_MD = 'HERMES.md';+/**+ * The page workflow every Astryx agent text gives, written with the command+ * name `astryx`: the project agent docs and the computer-level skill both+ * render these lines, so the two never drift.+ */+export const WORKFLOW_TITLE =+ 'WORKFLOW — start every page from a template, never from scratch:';+export const WORKFLOW_STEPS = Object.freeze([+ '1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.',+ '2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.',+ '3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.',+]);++/**+ * The self-check's fix for a project with no StyleX or Tailwind compiler,+ * and for an agent outside a project.+ */+export const SELF_CHECK_CSS =+ 'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token';+export const MARKER_START = '<!-- ASTRYX:START -->';export const MARKER_END = '<!-- ASTRYX:END -->';// Legacy markers — read during migration so the script finds existing XDS blocks@@ -91,7 +111,9 @@ export function holdsAstryxBlock(content) {while (at !== -1) {const from = at + marker.length;const end = content.indexOf('<!--', from);- const inner = (end === -1 ? content.slice(from) : content.slice(from, end)).trim();+ const inner = (+ end === -1 ? content.slice(from) : content.slice(from, end)+ ).trim();if (!/^@\S+$/.test(inner)) return true;at = content.indexOf(marker, from);}@@ -153,7 +175,7 @@ export function isAstryxPromptInReach(startDir = process.cwd()) {* @returns {string | null}*/function findRepositoryRoot(start) {- for (let dir = start; ; ) {+ for (let dir = start; ;) {if (fs.existsSync(path.join(dir, '.git'))) return dir;const parent = path.dirname(dir);if (parent === dir) return null;diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjsindex 700283d6f1..192746a09a 100644--- a/packages/cli/foundation/agent-docs/agent-docs.mjs+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs@@ -58,6 +58,9 @@ import {discoverAgentDocs,isAstryxInitialized,isAstryxPromptInReach,+ SELF_CHECK_CSS,+ WORKFLOW_STEPS,+ WORKFLOW_TITLE,} from './agent-doc-state.mjs';// The agent-doc locations, markers, and the setup-state predicates@@ -762,10 +765,7 @@ export function generateCompressedIndex(// Workflow — `build` is the front door, and every page starts from the// 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(WORKFLOW_TITLE, ...WORKFLOW_STEPS);lines.push('Changing an existing page? Keep it: skip step 2 and add blocks/components inside its sections.');lines.push('');@@ -793,7 +793,7 @@ export function generateCompressedIndex('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>, 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',+ css: SELF_CHECK_CSS,};lines.push(`- SELF-CHECK: re-read the file; ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}.`,diff --git a/packages/cli/foundation/agent-docs/computer-agent-text.mjs b/packages/cli/foundation/agent-docs/computer-agent-text.mjsindex 188c71455c..fedd842340 100644--- a/packages/cli/foundation/agent-docs/computer-agent-text.mjs+++ b/packages/cli/foundation/agent-docs/computer-agent-text.mjs@@ -43,7 +43,13 @@ import {createHash} from 'node:crypto';import {cliDoor} from '../env/cli-command.mjs';import {astryxCommandsOnSearchPath} from '../env/search-path.mjs';import {samePath} from '../fs/path-compare.mjs';-import {MARKER_START, MARKER_END} from './agent-doc-state.mjs';+import {+ MARKER_START,+ MARKER_END,+ SELF_CHECK_CSS,+ WORKFLOW_STEPS,+ WORKFLOW_TITLE,+} from './agent-doc-state.mjs';/** The command the computer-level text uses when no host door is set. */export const COMPUTER_COMMAND = 'astryx';@@ -175,6 +181,15 @@ function bodyLines(run) {`Its docs, components, templates, and themes are all reachable through \`${run}\`. Start with \`${run} search '<what you need>'\`.`,`Then read \`${run} component <Name>\` or \`${run} docs <topic>\`, not the package's files.`,"In a project, the project's version of Astryx answers automatically.",+ // How to build, which discovery alone leaves to the agent's own page+ // route: in a project, from the template, with the project agent docs'+ // own workflow lines.+ // A project that already installs Core gets the CLI at that version, as+ // the CLI's own hint for that state says, never a newer CLI beside it.+ `To build UI, work in a project folder (create one if there is none). Add \`@astryxdesign/core\` and \`@astryxdesign/cli\` to a new project or one without \`@astryxdesign/core\`; to a project that already has \`@astryxdesign/core\`, add \`@astryxdesign/cli\` at the same version. Run \`${run} init\` there and follow the agent docs it writes.`,+ WORKFLOW_TITLE,+ ...WORKFLOW_STEPS.map(step => step.replaceAll('`astryx ', `\`${run} `)),+ `Before you deliver, re-read each file; ${SELF_CHECK_CSS}. Then build the project and deliver that build, not a description of it.`,];}diff --git a/packages/cli/foundation/agent-docs/computer-agent-text.test.mjs b/packages/cli/foundation/agent-docs/computer-agent-text.test.mjsindex 6adaacc21d..94d5af147c 100644--- a/packages/cli/foundation/agent-docs/computer-agent-text.test.mjs+++ b/packages/cli/foundation/agent-docs/computer-agent-text.test.mjs@@ -27,7 +27,13 @@ import {renderComputerAgentText,writeComputerAgentText,} from './computer-agent-text.mjs';-import {MARKER_END, MARKER_START} from './agent-doc-state.mjs';+import {+ MARKER_END,+ MARKER_START,+ SELF_CHECK_CSS,+ WORKFLOW_STEPS,+ WORKFLOW_TITLE,+} from './agent-doc-state.mjs';import {runWithCliDoor} from '../env/cli-command.mjs';import {runCli} from '../../test-utils/run-cli.mjs';import {parse as parseYaml} from 'yaml';@@ -123,12 +129,27 @@ describe('renderComputerAgentText', () => {it('stays short, and tells agents to read docs through the CLI', () => {const text = renderComputerAgentText({command: 'astryx'});- expect(text.split('\n').length).toBeLessThanOrEqual(15);+ expect(text.split('\n').length).toBeLessThanOrEqual(22);expect(text).toContain("Then read `astryx component <Name>` or `astryx docs <topic>`, not the package's files.",);});+ // Discovery alone leaves the build to the agent's own page route, which+ // may not install packages; the skill names the route and the project+ // agent docs' own workflow lines.+ it('gives the build workflow: a project with Astryx installed and init run, the shared template steps, then check and deliver the build', () => {+ const text = renderComputerAgentText({command: 'astryx'});+ expect(text).toContain(+ 'To build UI, work in a project folder (create one if there is none). Add `@astryxdesign/core` and `@astryxdesign/cli` to a new project or one without `@astryxdesign/core`; to a project that already has `@astryxdesign/core`, add `@astryxdesign/cli` at the same version. Run `astryx init` there and follow the agent docs it writes.',+ );+ for (const line of [WORKFLOW_TITLE, ...WORKFLOW_STEPS]) {+ expect(text).toContain(line);+ }+ expect(text).toContain(`re-read each file; ${SELF_CHECK_CSS}.`);+ expect(text).toContain('deliver that build');+ });+it("uses the host's door when one is set", () => {const text = runWithCliDoor('acme astryx', () => renderComputerAgentText());expect(text).toContain("`acme astryx search '<what you need>'`");diff --git a/packages/core/scripts/agent-doc-state.mjs b/packages/core/scripts/agent-doc-state.mjsindex e4eccd5b0d..9b17e16705 100644--- a/packages/core/scripts/agent-doc-state.mjs+++ b/packages/core/scripts/agent-doc-state.mjs@@ -44,6 +44,26 @@ export const CURSOR_RULES = '.cursorrules';export const HERMES_DOT_MD = '.hermes.md';export const HERMES_MD = 'HERMES.md';+/**+ * The page workflow every Astryx agent text gives, written with the command+ * name `astryx`: the project agent docs and the computer-level skill both+ * render these lines, so the two never drift.+ */+export const WORKFLOW_TITLE =+ 'WORKFLOW — start every page from a template, never from scratch:';+export const WORKFLOW_STEPS = Object.freeze([+ '1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.',+ '2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.',+ '3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.',+]);++/**+ * The self-check's fix for a project with no StyleX or Tailwind compiler,+ * and for an agent outside a project.+ */+export const SELF_CHECK_CSS =+ 'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token';+export const MARKER_START = '<!-- ASTRYX:START -->';export const MARKER_END = '<!-- ASTRYX:END -->';// Legacy markers — read during migration so the script finds existing XDS blocks@@ -101,7 +121,9 @@ export function holdsAstryxBlock(content) {while (at !== -1) {const from = at + marker.length;const end = content.indexOf('<!--', from);- const inner = (end === -1 ? content.slice(from) : content.slice(from, end)).trim();+ const inner = (+ end === -1 ? content.slice(from) : content.slice(from, end)+ ).trim();if (!/^@\S+$/.test(inner)) return true;at = content.indexOf(marker, from);}@@ -163,7 +185,7 @@ export function isAstryxPromptInReach(startDir = process.cwd()) {* @returns {string | null}*/function findRepositoryRoot(start) {- for (let dir = start; ; ) {+ for (let dir = start; ;) {if (fs.existsSync(path.join(dir, '.git'))) return dir;const parent = path.dirname(dir);if (parent === dir) return null;