@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/api/build/help/help.mjs

@@ -1,18 +1,81 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file build.help leaf — the "how to build a page" playbook signal.
+ * @file build.help leaf — the "how to build a page" playbook.
  *
- * `build` with no query returns this envelope: a pure marker that the command
- * renderer expands into the workflow playbook prose. It carries no data beyond
- * `playbook: true`, so the JSON shape stays environment-agnostic and stable.
+ * `build` with no query returns this envelope. The playbook is data — steps,
+ * rules, and related lookups — so a `--json` or programmatic caller gets the
+ * same guidance the terminal shows. Commands are bare subcommands with no
+ * package-manager prefix, which keeps the JSON environment-agnostic; the CLI
+ * renders each one with the caller's invocation, as it does build.kit's
+ * `hint.commands`.
+ *
+ * The workflow starts every page from a template, because a template already
+ * has the frame, spacing, and section rhythm that a page composed from
+ * components has to rediscover.
  */
 
 /**
- * The page-building playbook signal (emitted when `build` runs with no query).
+ * The page-building playbook (emitted when `build` runs with no query).
  *
  * @returns {import('../build.type.mjs').BuildHelpResponse}
  */
 export function buildHelp() {
-  return {type: 'build.help', data: {playbook: true}};
+  return {
+    type: 'build.help',
+    data: {
+      playbook: true,
+      title: 'How to build a page with Astryx',
+      steps: [
+        {
+          title: 'Find the page template to start from',
+          commands: [{command: 'build "<what you\'re building>"'}],
+          returns:
+            'the [page] template to start from (always one: the closest match, or the app shell when nothing matches), the next two templates, and the [block]s and [component]s for the parts it lacks',
+        },
+        {
+          title: 'Scaffold that template into your project',
+          commands: [
+            {
+              command: 'template <name> <path>',
+              purpose: 'write the page template to <path>',
+            },
+          ],
+        },
+        {
+          title: 'Adapt it: keep its frame and spacing, replace its content',
+          commands: [
+            {
+              command: 'template <BlockName>',
+              purpose:
+                'print a block to put inside a section, for a part the template lacks',
+            },
+            {
+              command: 'component <Name>',
+              purpose: 'read props before you change a component',
+            },
+          ],
+        },
+      ],
+      rules: [
+        'Start every page from a page template. Never lay out a page from scratch.',
+        'Changing a page you already have? Keep it. Add blocks and components inside its sections.',
+        "Keep the template's page frame, gap, and padding values. Replace its data, copy, and sections.",
+        'No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
+        'No style={{}} — use component props, and design tokens for values.',
+        'Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
+      ],
+      related: [
+        {
+          command: 'template --list --type page',
+          purpose: 'every page template',
+        },
+        {command: 'docs tokens', purpose: 'the design tokens'},
+        {
+          command: 'search <query>',
+          purpose: 'a neutral lookup of any component, doc, or template',
+        },
+      ],
+    },
+  };
 }

package/api/build/kit/kit.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * The grouped composition kit for what you're building.
+ * The page template to start from, and the kit around it.
  *
  * @param {string} query what you're building (e.g. "analytics dashboard")
  * @param {{cwd?: string, type?: import('../../search/search.type.mjs').SearchDomain, limit?: number}} [options]
@@ -13,3 +13,6 @@ export function buildKit(query: string, options?: {
     type?: import("../../search/search.type.mjs").SearchDomain;
     limit?: number;
 }): Promise<import("../build.type.mjs").BuildKitResponse>;
+export type SearchResultEntry = import("../../search/search.type.mjs").SearchResultEntry;
+export type BuildStart = import("../build.type.mjs").BuildStart;
+export type PageTemplate = import("../_adapter.mjs").PageTemplate;

package/api/build/kit/kit.mjs

@@ -1,44 +1,60 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file build.kit leaf — the grouped composition kit and raw match count.
+ * @file build.kit leaf — the page template to start from, and the kit around it.
  *
- * Runs the unified search for the query and groups the results into a
- * composition KIT: the closest page templates, the blocks that cover parts,
- * and the domain components to fill gaps, plus the always-on frame + foundation.
+ * Every kit names a page template to START from: the page the page ranker
+ * (rank.mjs) puts first when it has the evidence to lead, else the app shell.
+ * The ranker is the only thing that picks the start, so one noisy signal —
+ * search matching "site" to a gallery's "side" — cannot choose the page. A
+ * template carries the page frame, the spacing, and the section rhythm; a page
+ * composed from components carries none of that, so the kit never recommends
+ * composing from scratch while a template exists. Next to the start it names
+ * the ranker's next two templates, then groups the unified search into the
+ * blocks that cover parts and the domain components to fill gaps, plus the
+ * always-on frame + foundation names. `pages` and `directMatch` keep search's
+ * own view for callers that read them.
  *
  * The kit carries RAW `SearchResultEntry` objects and static name arrays only —
  * 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 —
+ * Two commands are the kit's own: `start.command`, the scaffold (`astryx
+ * template <id> --type page <path>`, with `<path>` a placeholder), and the `--skeleton`
+ * a page entry carries when it is not a direct match, so a loose page reads
+ * as a layout preview rather than the thing to build. Neither is prefixing —
  * the invocation stays the renderer's job.
  */
 
 import {search} from '../../search/search.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {getResultCoverage} from '../../search/coverage.mjs';
+import {loadPageTemplates} from '../_adapter.mjs';
+import {pickAlternatives, pickStart, rankPages} from './rank.mjs';
 
 /** A page at/above this score is a confident direct match. */
 const PAGE_DIRECT = 95;
-/** Below this a page is too weak to offer even as a layout reference. */
+/** Below this a page is too weak to offer at all. */
 const PAGE_FLOOR = 50;
-/** Below this a block/domain-component match is incidental noise. */
-const DOMAIN_FLOOR = 55;
 /**
- * How much of a multi-word query a result must cover to be offered as a PAGE.
- *
- * Score alone cannot carry this. A page's keywords include every component its
- * source renders, so `build "actionable warning banner"` scored `login`,
- * `contact-form` and `documentation-design` at 95 apiece — an exact keyword hit
- * (90) on "banner" alone, plus the coverage garnish, lands exactly on
- * PAGE_DIRECT. Three pages that are not warnings, presented as a direct match,
- * because each happens to render a Banner somewhere.
+ * Below this a block/domain-component match is incidental noise. A single
+ * description word in a multi-word idea scores 50 plus at most 7.5 of coverage
+ * garnish, so it stays below; a name or keyword hit clears it. `build "weekly
+ * brief"` used to offer Toast, Popover and TextInput because their
+ * descriptions say "brief".
+ */
+const DOMAIN_FLOOR = 60;
+/**
+ * How much of a multi-word query a page must cover to be offered on breadth.
  *
- * Coverage has to gate rather than garnish: matching one of three concepts is
- * not the same claim as matching three.
+ * Score alone cannot carry this. A page's derived keywords include every
+ * component its source renders, so `build "actionable warning banner"` once
+ * scored `login`, `contact-form` and `documentation-design` at 95 apiece — an
+ * exact hit on "banner" alone, plus the coverage garnish. Matching one of
+ * three concepts is not the same claim as matching three.
  */
 const PAGE_COVERAGE = 0.5;
 /**
@@ -50,12 +66,21 @@ const PAGE_COVERAGE = 0.5;
  * Astryx contains, which is exactly the failure `build` exists to prevent.
  */
 const THIN_KIT = 3;
+/**
+ * Where a page starts when no page template matched: the first of these the
+ * project can scaffold. A top nav over empty, full-width content is the least
+ * opinionated frame that still has navigation; `blank` is the floor, with no
+ * chrome at all. Either one still hands the reader a page frame and its
+ * padding, which composing from components does not.
+ */
+const FALLBACK_STARTS = ['shell-top-nav', 'blank'];
 
 /**
  * Always-surfaced primitives. Every page needs a shell + layout/typography/
  * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
  * so search alone never returns them. Kept here (not the renderer) because they
  * are ALSO used to exclude these names from the idea-specific `domain` group.
+ * Every page template already uses them.
  */
 const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
 const FOUNDATION = [
@@ -75,7 +100,90 @@ const FOUNDATION = [
 const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
 
 /**
- * The grouped composition kit for what you're building.
+ * @typedef {import('../../search/search.type.mjs').SearchResultEntry} SearchResultEntry
+ * @typedef {import('../build.type.mjs').BuildStart} BuildStart
+ * @typedef {import('../_adapter.mjs').PageTemplate} PageTemplate
+ */
+
+/**
+ * A page template as the kit names it: the command that selects exactly that
+ * template, scaffolding into `<path>`, a placeholder for the file or folder to
+ * write it to.
+ * @param {PageTemplate} t
+ */
+const asTemplate = t => ({
+  name: t.name,
+  displayName: t.displayName,
+  description: t.description,
+  command: `${t.command} <path>`,
+});
+
+/**
+ * The template to start from: the ready page the ranker puts first when it
+ * has the evidence to lead, else the first fallback shell the project can
+ * scaffold. Null only when the project has no page template to offer at all.
+ *
+ * `direct` means two independent signals agree: the ranker's pick is also
+ * search's direct match. The ranker sees only ready templates, so a template
+ * still marked not ready is never the start; when search matched one directly
+ * the reason names it, so the reader knows why the kit starts elsewhere.
+ *
+ * @param {import('./rank.mjs').RankedPage[]} ranked
+ * @param {SearchResultEntry[]} pages
+ * @param {boolean} directMatch
+ * @param {PageTemplate[]} catalog
+ * @returns {Omit<BuildStart, 'alternatives'> | null}
+ */
+function chooseStart(ranked, pages, directMatch, catalog) {
+  const direct = directMatch ? pages[0].name : null;
+  const unready =
+    direct && !catalog.some(t => t.name === direct) ? direct : null;
+  // The reason never denies a match the same response reports: a direct
+  // match the ranker outweighed is named, and so are the loose page matches
+  // search listed when the kit falls back to the shell.
+  const loose = pages.map(p => `\`${p.name}\``).join(', ');
+  const pick = pickStart(ranked);
+  const closest = pick && catalog.find(t => t.name === pick.name);
+  if (closest) {
+    const agrees = closest.name === direct;
+    return {
+      ...asTemplate(closest),
+      basis: agrees ? 'direct' : 'closest',
+      reason: agrees
+        ? 'Matches the idea.'
+        : unready
+          ? `\`${unready}\` matches but is not ready yet; this is the closest ready template.`
+          : direct
+            ? `Search matched \`${direct}\` by name, but this template fits more of the idea.`
+            : 'The closest template; none is exactly this page.',
+    };
+  }
+  for (const id of FALLBACK_STARTS) {
+    const shell = catalog.find(t => t.name === id);
+    if (shell) {
+      // The shell can also be the ranker's best guess without the evidence to
+      // lead ("horizontal site navigation"); say so rather than "no match".
+      const nearest = ranked[0]?.name === shell.name && ranked[0].hits > 0;
+      return {
+        ...asTemplate(shell),
+        basis: 'fallback',
+        reason: unready
+          ? `\`${unready}\` matches but is not ready yet, so start from the app shell.`
+          : direct
+            ? `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
+            : nearest
+              ? 'No template is a clear match; the app shell is the closest.'
+              : loose
+                ? `Search matched ${loose} only loosely, so start from the app shell.`
+                : 'No template matched, so start from the app shell.',
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * The page template to start from, and the kit around it.
  *
  * @param {string} query what you're building (e.g. "analytics dashboard")
  * @param {{cwd?: string, type?: import('../../search/search.type.mjs').SearchDomain, limit?: number}} [options]
@@ -83,12 +191,30 @@ const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
  */
 export async function buildKit(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 60} = options;
+  // A kit is built from Core's components, hooks, and templates. An open
+  // search without core covers the docs alone, so the kit asks for core here.
+  if (type !== 'doc' && !findCoreDir(cwd)) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
   // search()'s JSDoc @returns widens results to object[]; the SearchResponse
   // shape is the contract (api/search/search.type.mjs). Cast locally rather than
   // tightening the search @returns (a separate follow-up).
   const result =
     /** @type {import('../../search/search.type.mjs').SearchResponse} */ (
-      await search(query, {cwd, type, limit})
+      await search(query, {
+        cwd,
+        type,
+        // Search wider than the surfaced kit so a flood of doc matches cannot
+        // bury the page templates past the cutoff; the caller's `limit` still
+        // caps the kit below. A non-positive or non-integer limit is passed
+        // through unchanged so search rejects it (ERR_INVALID_ARGUMENT).
+        limit:
+          Number.isInteger(limit) && limit > 0 ? Math.max(limit, 200) : limit,
+      })
     );
   const results = result.data.results;
   // The TOTAL number of matches, not the number that survived `limit`. The kit
@@ -98,7 +224,7 @@ export async function buildKit(query, options = {}) {
   const matchCount = result.data.matchCount;
 
   /**
-   * Did this result answer enough of the query to stand as a page?
+   * Did this result answer enough of the query to stand as a page on breadth?
    * Single-concept queries have nothing to cover, so they always pass. Coverage
    * stays in a module-private WeakMap and never enters public search/build JSON.
    * @param {object} r
@@ -110,7 +236,7 @@ export async function buildKit(query, options = {}) {
     return (coverage?.matched ?? 0) / total >= PAGE_COVERAGE;
   };
 
-  const pages = results
+  const matchedPages = results
     .filter(
       r =>
         r.domain === 'template' &&
@@ -135,32 +261,60 @@ export async function buildKit(query, options = {}) {
         !ALWAYS.has(r.name),
     )
     .slice(0, 6);
-  const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
+  const directMatch =
+    matchedPages.length > 0 && matchedPages[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.
+   * On a loose match, a page entry's `command` previews the layout rather
+   * than printing the whole template: `--skeleton` gives the shape without
+   * presenting the page as the thing to build. The recommendation itself is
+   * `start`, which always scaffolds. 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`}));
+  const pages = directMatch
+    ? matchedPages
+    : matchedPages.map(page => ({
+        ...page,
+        command: `${page.command} --skeleton`,
+      }));
+
+  // The caller's `limit` caps the surfaced kit, even though the search above
+  // ran wider to find templates that a flood of doc matches would otherwise
+  // bury past the cutoff. Keep pages first, then blocks, then components.
+  let budget = limit;
+  /**
+   * @template T
+   * @param {T[]} arr
+   * @returns {T[]}
+   */
+  const toLimit = arr => {
+    const out = arr.slice(0, Math.max(0, budget));
+    budget -= out.length;
+    return out;
+  };
+  const pagesKept = toLimit(pages);
+  const blocksKept = toLimit(blocks);
+  const domainKept = toLimit(domain);
+
+  // A kit narrowed to components or hooks has no page to start from; every
+  // other kit does, so the reader is never left to compose a page from scratch.
+  const wantsPages = !type || type === 'template';
+  const catalog = wantsPages ? await loadPageTemplates(cwd) : [];
+  const ranked = wantsPages ? rankPages(query, catalog) : [];
+  const chosen = wantsPages
+    ? chooseStart(ranked, matchedPages, directMatch, catalog)
+    : null;
+  // Name the ranker's next two templates beside the start: the reader judges
+  // meaning better than keywords do, and an acceptable template is in these
+  // three far more often than it is the start alone.
+  /** @type {BuildStart | null} */
+  const start = chosen && {
+    ...chosen,
+    alternatives: pickAlternatives(ranked, chosen.name).flatMap(r => {
+      const t = catalog.find(c => c.name === r.name);
+      return t ? [asTemplate(t)] : [];
+    }),
+  };
 
   // 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
@@ -173,7 +327,7 @@ export async function buildKit(query, options = {}) {
   // 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
+    pagesKept.length + blocksKept.length + domainKept.length < THIN_KIT
       ? {
           reason:
             'Few matches. This is keyword search, not semantic — try other wordings.',
@@ -185,14 +339,15 @@ export async function buildKit(query, options = {}) {
     type: 'build.kit',
     data: {
       query: result.data.query,
-      // Distinguishes "search found nothing" (renderer shows "No matches")
-      // from a weak-but-non-empty result set (renderer still shows the kit).
+      // Distinguishes "search found nothing" from a weak-but-non-empty result
+      // set. Either way the kit still names a template to start from.
       hasResults: matchCount > 0,
       matchCount,
       directMatch,
-      pages: recommendedPages,
-      blocks,
-      domain,
+      start,
+      pages: pagesKept,
+      blocks: blocksKept,
+      domain: domainKept,
       frame: FRAME,
       foundation: FOUNDATION,
       hint,

package/api/build/kit/rank.d.mts

@@ -0,0 +1,44 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @typedef {import('../_adapter.mjs').PageTemplate} PageTemplate
+ * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, containerMatched: boolean}} RankedPage
+ */
+/**
+ * Rank page templates against an idea, best first. Ties go to the template
+ * with the shorter id (the family's broader page), then by name.
+ *
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @returns {RankedPage[]}
+ */
+export function rankPages(query: string, pages: PageTemplate[]): RankedPage[];
+/**
+ * The next closest templates after the start, best first: the ones a reader
+ * should check the idea against when the start's shape is wrong. Each matched
+ * at least one term and scored at least half of what a start needs.
+ *
+ * @param {RankedPage[]} ranked
+ * @param {string} startName
+ * @param {number} [count]
+ * @returns {RankedPage[]}
+ */
+export function pickAlternatives(ranked: RankedPage[], startName: string, count?: number): RankedPage[];
+/**
+ * The template to start from, or null when the best one has too little
+ * evidence to lead and the page should start from the app shell. Evidence is
+ * two matched terms, the idea naming the template's family, or its container.
+ *
+ * @param {RankedPage[]} ranked
+ * @returns {RankedPage | null}
+ */
+export function pickStart(ranked: RankedPage[]): RankedPage | null;
+export type PageTemplate = import("../_adapter.mjs").PageTemplate;
+export type RankedPage = {
+    name: string;
+    score: number;
+    hits: number;
+    familyNamed: boolean;
+    containerMatched: boolean;
+};