@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/api/build/build.doc.mjs

@@ -76,6 +76,10 @@ export const doc = {
       code: 'ERR_CORE_NOT_FOUND',
       when: 'a query is given and @astryxdesign/core cannot be found from cwd',
     },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: 'a query is given outside a project, or in a project with nothing installed, and the Core of the release that answers is not beside it or cached, and cannot be installed into the per-user cache (offline, a registry without it, or an unwritable cache)',
+    },
   ],
   examples: [
     {label: 'Get the playbook', code: 'const r = await build();'},

package/api/build/build.mjs

@@ -4,20 +4,27 @@
  * @file build API — dispatcher + barrel for the "assemble a page" assistant.
  *
  * `build()` with no query signals the workflow playbook (`build.help`). With a
- * query it runs the unified search and groups the results into a composition
- * KIT (`build.kit`). Each shape is projected by its own leaf; this file only
+ * query it runs build's tree (tree.mjs), whose searchers answer with a
+ * composition KIT (`build.kit`). Each shape is projected by its own leaf; this file only
  * routes to the leaves and re-exports them, keeping the SAME `build` export so
  * api/index.mjs and the CLI consumer stay unchanged.
  *
  *   no query  → build.help  (api/build/help/help.mjs)
- *   a query   → build.kit   (api/build/kit/kit.mjs)
+ *   a query   → build.kit   (api/build/tree.mjs: kit/signals.mjs, the block
+ *               picker in blocks/blocks.mjs, then kit/answer.mjs)
  */
 
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {buildHelp} from './help/help.mjs';
 import {buildKit} from './kit/kit.mjs';
-import {withListingCache} from './_adapter.mjs';
+import {
+  loadBlockPicker,
+  loadTreeWeights,
+  withListingCache,
+} from './_adapter.mjs';
+import {runTree} from '../../foundation/route/route.mjs';
+import {BUILD_TREE} from './tree.mjs';
 
 // Barrel: surface the leaves alongside the dispatcher for the fractal shape.
 export {buildHelp, buildKit};
@@ -34,7 +41,10 @@ export async function build(query, options = {}) {
   if (!query || !String(query).trim()) {
     return buildHelp();
   }
-  if (options.limit != null && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+  if (
+    options.limit != null &&
+    (!Number.isInteger(options.limit) || options.limit <= 0)
+  ) {
     throw new AstryxError(
       `Invalid limit "${options.limit}". Must be a positive integer.`,
       undefined,
@@ -43,5 +53,14 @@ export async function build(query, options = {}) {
   }
   // The kit resolves every candidate's source and docs by walking the same
   // tree; read each directory once for this call.
-  return withListingCache(() => buildKit(query, options));
+  return withListingCache(
+    async () =>
+      /** @type {import('./build.type.mjs').BuildKitResponse} */ (
+        await runTree(
+          BUILD_TREE,
+          {query, options},
+          {weights: loadTreeWeights(), blocks: loadBlockPicker()},
+        )
+      ),
+  );
 }

package/api/build/build.type.mjs

@@ -77,7 +77,7 @@
  * @property {boolean} data.directMatch True when the top page template is a confident direct match.
  * @property {BuildStart | null} data.start The page template to start from: the ranker's pick, else the app shell. Null only when the kit is narrowed to components or hooks (`type`), or when the project has no page template to offer.
  * @property {import('../search/search.type.mjs').SearchResultEntry[]} data.pages Closest page templates by search (≤3). Each entry's `command` carries `--skeleton` when `directMatch` is false, so it previews the layout; `start.command` is the scaffold.
- * @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.blocks Drop-in block patterns covering parts of the idea (≤5), best first. A block search returned keeps search's score and reason; any other block carries the block picker's relative score (100 for its best candidate, never below 1) and reason, so the two kinds of score are not comparable.
  * @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. Every page template already uses them.
  * @property {string[]} data.foundation Always-on layout/typography/action component names. Every page template already uses them.

package/api/build/help/help.mjs

@@ -63,7 +63,7 @@ export function buildHelp() {
         "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={...}> (import {Theme} from '@astryxdesign/core') and import core reset.css + astryx.css.",
+        "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core/theme') and import core reset.css + astryx.css.",
       ],
       related: [
         {

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

@@ -0,0 +1,18 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The kit for a request. `blocks` names the blocks to list, best first: a
+ * block build names itself keeps build's entry, another keeps search's own
+ * entry (its real score and reason), a name search did not return is
+ * dropped, and the kit never lists more blocks than build's own. Blocks of
+ * the same name from two packages are both kept.
+ *
+ * @param {import('./signals.mjs').KitSignals} signals
+ * @param {string[]} [blocks] block names; build's own when omitted
+ * @param {Map<string, import('../../search/search.type.mjs').SearchResultEntry>} [picked]
+ *   the block picker's own entry (its real score and reason) for each named
+ *   block search did not return
+ * @returns {import('../build.type.mjs').BuildKitResponse}
+ */
+export function kitAnswer(signals: import("./signals.mjs").KitSignals, blocks?: string[], picked?: Map<string, import("../../search/search.type.mjs").SearchResultEntry>): import("../build.type.mjs").BuildKitResponse;

package/api/build/kit/answer.mjs

@@ -0,0 +1,195 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The build.kit response, from a request's signals (signals.mjs) and the
+ * blocks to name. With build's own blocks it is the kit build has always
+ * given; another list changes only the blocks, never their count.
+ * @input {@link import('./signals.mjs').KitSignals} and block names
+ * @output the build.kit response
+ * @position api/build/kit, beside signals.mjs; the main searcher in tree.mjs
+ *   calls it with the block picker's list.
+ */
+
+import {firstSentence} from '../../../foundation/text/string-utils.mjs';
+import {FOUNDATION, FRAME} from './signals.mjs';
+
+/**
+ * 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;
+
+/**
+ * The kit for a request. `blocks` names the blocks to list, best first: a
+ * block build names itself keeps build's entry, another keeps search's own
+ * entry (its real score and reason), a name search did not return is
+ * dropped, and the kit never lists more blocks than build's own. Blocks of
+ * the same name from two packages are both kept.
+ *
+ * @param {import('./signals.mjs').KitSignals} signals
+ * @param {string[]} [blocks] block names; build's own when omitted
+ * @param {Map<string, import('../../search/search.type.mjs').SearchResultEntry>} [picked]
+ *   the block picker's own entry (its real score and reason) for each named
+ *   block search did not return
+ * @returns {import('../build.type.mjs').BuildKitResponse}
+ */
+export function kitAnswer(
+  signals,
+  blocks = signals.kitBlocks,
+  picked = new Map(),
+) {
+  // Entries by name, in build's order: two packages can ship a block with the
+  // same name, and each name in `blocks` takes the next entry of that name, so
+  // both stay listed.
+  /** @type {Map<string, import('../build.type.mjs').BuildKitResponse['data']['blocks']>} */
+  const own = new Map();
+  for (const b of signals.blocks)
+    own.set(b.name, [...(own.get(b.name) ?? []), b]);
+  /** @type {Set<string>} */
+  const added = new Set();
+  const named = blocks
+    .flatMap(name => {
+      const entry = own.get(name)?.shift();
+      if (entry) return [entry];
+      // A block build does not name itself keeps search's own entry, once;
+      // one search did not return keeps the picker's entry.
+      const found =
+        own.has(name) || added.has(name)
+          ? undefined
+          : (signals.searchedEntries.get(name) ?? picked.get(name));
+      if (!found) return [];
+      added.add(name);
+      return [found];
+    })
+    .slice(0, signals.blocks.length);
+
+  // 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 =
+    signals.pages.length + named.length + signals.domain.length < THIN_KIT
+      ? {
+          reason:
+            'Few matches. This is keyword search, not semantic — try other wordings.',
+          commands: ['component --list', 'template --list'],
+        }
+      : undefined;
+
+  const answer = (/** @type {typeof named} */ list) => ({
+    type: /** @type {const} */ ('build.kit'),
+    data: {
+      query: signals.query,
+      // Distinguishes "search found nothing" from a weak-but-non-empty result
+      // set. Either way the kit still names a template to start from.
+      hasResults: signals.matchCount > 0,
+      matchCount: signals.matchCount,
+      directMatch: signals.directMatch,
+      start: signals.start,
+      pages: signals.pages,
+      blocks: list,
+      domain: signals.domain,
+      frame: FRAME,
+      foundation: FOUNDATION,
+      hint,
+    },
+  });
+
+  // An added block must not make the answer longer than build's own, as JSON
+  // or as text: trim the added blocks' descriptions, never which blocks are
+  // listed.
+  const fitted = fitDescriptions(named, signals.blocks, {
+    json: list => bytes(answer(list)),
+    text: textSize,
+  });
+  return answer(fitted);
+}
+
+/** @param {unknown} value */
+const bytes = value => Buffer.byteLength(JSON.stringify(value));
+
+/**
+ * What the blocks add to the text answer, which prints each block's name,
+ * package, and the first sentence of its description.
+ * @param {{name: string, package?: string, description?: string}[]} list
+ */
+const textSize = list =>
+  list.reduce(
+    (n, b) =>
+      n +
+      Buffer.byteLength(
+        `${b.name}${b.package ?? ''}${firstSentence(b.description ?? '')}`,
+      ),
+    0,
+  );
+
+/** An added block keeps at least this much of its description. */
+const MIN_DESCRIPTION = 24;
+
+/**
+ * A description cut to about `keep` characters (never fewer than
+ * {@link MIN_DESCRIPTION}) at a word boundary, with an ellipsis. Never empty:
+ * a description already that short is kept whole.
+ * @param {string} description
+ * @param {number} keep
+ */
+function cutTo(description, keep) {
+  const room = Math.max(keep, MIN_DESCRIPTION);
+  if (description.length <= room) return description;
+  const cut = description.slice(0, room);
+  const at = cut.lastIndexOf(' ');
+  return `${(at > 0 ? cut.slice(0, at) : cut).trimEnd()}…`;
+}
+
+/**
+ * The listed blocks with the added blocks' descriptions shortened until
+ * neither the JSON nor the text answer is longer than with build's own
+ * blocks, or every added description is as short as it may get. A
+ * description is never emptied, and build's own entries never change.
+ * @template {{name: string, package?: string, description?: string}} B
+ * @param {B[]} list
+ * @param {B[]} own build's own entries
+ * @param {{json: (list: B[]) => number, text: (list: B[]) => number}} size
+ * @returns {B[]}
+ */
+function fitDescriptions(list, own, size) {
+  const limit = {json: size.json(own), text: size.text(own)};
+  let out = list;
+  /** The bytes over each limit; 0 when within. */
+  const over = (/** @type {B[]} */ l) => ({
+    text: Math.max(0, size.text(l) - limit.text),
+    json: Math.max(0, size.json(l) - limit.json),
+  });
+  // The last added block first, each cut by what is still over and never
+  // below MIN_DESCRIPTION; when one is as short as it may get, the next one
+  // up is cut, and passes repeat while any cut still helps.
+  for (let changed = true; changed;) {
+    changed = false;
+    for (let k = out.length - 1; k >= 0; k--) {
+      const o = over(out);
+      if (o.text === 0 && o.json === 0) return out;
+      const b = out[k];
+      if (own.includes(b) || !b.description) continue;
+      const first = firstSentence(b.description);
+      const keep = Math.min(
+        o.text > 0 ? first.length - o.text - 1 : b.description.length,
+        o.json > 0 ? b.description.length - o.json - 1 : b.description.length,
+      );
+      const description = cutTo(b.description, keep);
+      if (description.length >= b.description.length) continue;
+      out = out.map((x, i) => (i === k ? {...x, description} : x));
+      changed = true;
+    }
+  }
+  return out;
+}

package/api/build/kit/answer.test.mjs

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {kitAnswer} from './answer.mjs';
+
+/**
+ * @param {any[]} blocks
+ * @param {any[]} [searched] blocks search returned that build did not name
+ */
+const signals = (blocks, searched = []) =>
+  /** @type {any} */ ({
+    query: 'q',
+    matchCount: blocks.length,
+    directMatch: false,
+    start: null,
+    pages: [],
+    blocks,
+    kitBlocks: blocks.map(b => b.name),
+    domain: [],
+    searchedEntries: new Map(searched.map(b => [b.name, b])),
+  });
+
+describe('kitAnswer', () => {
+  const a = {name: 'Hero', package: '@a/one', score: 90, reason: 'name'};
+  const b = {name: 'Hero', package: '@b/two', score: 80, reason: 'name'};
+  const c = {name: 'Footer', package: '@a/one', score: 70, reason: 'keyword'};
+
+  it('keeps blocks of the same name from two packages', () => {
+    const kit = kitAnswer(signals([a, b, c]));
+    expect(kit.data.blocks).toEqual([a, b, c]);
+  });
+
+  it('keeps both when the picker re-orders them', () => {
+    const kit = kitAnswer(signals([a, b, c]), ['Footer', 'Hero', 'Hero']);
+    expect(kit.data.blocks).toEqual([c, a, b]);
+  });
+
+  it('never lists a block neither build nor search gave, or more than build gave', () => {
+    const kit = kitAnswer(signals([a, c]), ['Hero', 'Hero', 'Nav', 'Footer']);
+    expect(kit.data.blocks).toEqual([a, c]);
+  });
+
+  it('lists a block search returned with search’s own entry, within build’s count', () => {
+    const nav = {name: 'Nav', package: '@a/one', score: 60, reason: 'keyword'};
+    const kit = kitAnswer(signals([a, c], [nav]), [
+      'Nav',
+      'Nav',
+      'Hero',
+      'Footer',
+    ]);
+    expect(kit.data.blocks).toEqual([nav, a]);
+  });
+
+  it('trims an added block’s description so the answer is never longer than build’s own', () => {
+    const hero = {
+      ...a,
+      description: 'A wide hero with a title and two buttons.',
+    };
+    const foot = {...c, description: 'A footer with links in three columns.'};
+    const nav = {
+      name: 'Nav',
+      package: '@a/one',
+      score: 60,
+      reason: 'keyword',
+      description: 'word '.repeat(200).trim(),
+    };
+    const own = kitAnswer(signals([hero, foot]));
+    const kit = kitAnswer(signals([hero, foot], [nav]), ['Nav', 'Hero']);
+    expect(kit.data.blocks.map(b => b.name)).toEqual(['Nav', 'Hero']);
+    expect(kit.data.blocks[1]).toEqual(hero);
+    expect(Buffer.byteLength(JSON.stringify(kit))).toBeLessThanOrEqual(
+      Buffer.byteLength(JSON.stringify(own)),
+    );
+    expect(kit.data.blocks[0].description).toMatch(/…$/);
+  });
+  it('trims an added block’s first sentence so the text answer is never longer either', () => {
+    const long = ' More words follow here. '.repeat(20);
+    const hero = {...a, description: `A hero.${long}`};
+    const foot = {...c, description: `A footer.${long}`};
+    const nav = {
+      name: 'Nav',
+      package: '@a/one',
+      score: 60,
+      reason: 'keyword',
+      description:
+        'A navigation bar with a logo, five links, a search box and a menu.',
+    };
+    const kit = kitAnswer(signals([hero, foot], [nav]), ['Nav', 'Hero']);
+    const d = kit.data.blocks[0].description;
+    expect(d).toMatch(/…$/);
+    expect(d.length).toBeLessThan(nav.description.length);
+    expect(nav.description.startsWith(d.slice(0, -1))).toBe(true);
+    expect(kit.data.blocks[1]).toEqual(hero);
+  });
+  it('never empties an added block’s description', () => {
+    const nav = {
+      name: 'Nav',
+      package: '@a/one',
+      score: 60,
+      reason: 'keyword',
+      description:
+        'A navigation bar with a logo, five links, a search box and a menu.',
+    };
+    const kit = kitAnswer(signals([a, c], [nav]), ['Nav', 'Hero']);
+    expect(kit.data.blocks[0].name).toBe('Nav');
+    expect(kit.data.blocks[0].description.length).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,25 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * What an idea asks for (spec:AST-048/FR3): a whole `page`; a `part` of one,
+ * when its head noun names one of the system's components and it lists fewer
+ * than PAGE_PIECES pieces; or an `edit` of a page the builder already has.
+ *
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @param {ComponentWords[]} components
+ * @returns {IdeaKind}
+ */
+export function ideaKind(query: string, pages: PageTemplate[], components: ComponentWords[]): IdeaKind;
+/**
+ * Whether an idea asks for a new page (see `asksNewPage`), from the idea and
+ * the project's page templates.
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @returns {boolean}
+ */
+export function asksForNewPage(query: string, pages: PageTemplate[]): boolean;
+export type PageTemplate = import("./words.mjs").PageTemplate;
+export type ComponentWords = import("./words.mjs").ComponentWords;
+export type IdeaKind = import("./words.mjs").IdeaKind;

package/api/build/kit/kind.mjs

@@ -0,0 +1,170 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Whether a build idea asks for a page, a part of a page, or a change to
+ * a page the builder already has.
+ *
+ * Parts (spec:AST-048/FR3). "A date range picker" asks for a part of a page,
+ * not a page, and the system's own components say what a part is: an idea
+ * whose head noun is a word of a component's name or keywords, Core's or an
+ * integration's, asks for that part, unless the noun is a family word ("a data
+ * table") or the idea lists a page's worth of pieces. Words search drops as
+ * stopwords ("page", "screen", "app", "view") name no component, so "a calendar
+ * page" asks for a page and "a calendar" for a part. A part starts from the
+ * base template of the family the idea names ("an empty state for a settings
+ * page"), else from the app shell. An idea that changes a page or part the
+ * builder already has starts from the app shell too: that page is the
+ * builder's to keep (FR9), and no template scaffolds it. "Existing" marks one
+ * when its phrase names a page family or a component ("add a column to the
+ * existing table"), unless the idea asks for a new page ("a new dashboard like
+ * the existing dashboard", "clone the existing dashboard as a new page"). A
+ * bare "existing" phrase that names a page ("existing reports dashboard with a
+ * date filter") reads as the builder's own page.
+ */
+
+import {stem} from '../../search/search.mjs';
+import {
+  HEAD_END,
+  CONTAINER_PHRASE,
+  PHRASE_END,
+  terms,
+  containersOf,
+  familyWordsOf,
+} from './words.mjs';
+
+/**
+ * @typedef {import('./words.mjs').PageTemplate} PageTemplate
+ * @typedef {import('./words.mjs').ComponentWords} ComponentWords
+ * @typedef {import('./words.mjs').IdeaKind} IdeaKind
+ */
+
+/**
+ * How many listed pieces make an idea a page: a part is one thing with a detail
+ * or two ("a status pill with a tooltip"), while three pieces, two commas
+ * apart, describe a page.
+ */
+const PAGE_PIECES = 3;
+
+/**
+ * The word that marks a page or part the builder already has, when its phrase
+ * names one (see `changesExistingPage`).
+ */
+const EXISTING = /\bexisting\b/i;
+
+/**
+ * The word that marks an idea asking for a new page ("a new dashboard", "as a
+ * new page"), which is never a change to one the builder has.
+ */
+const NEW = /\bnew\b/;
+
+/**
+ * What an idea asks for (spec:AST-048/FR3): a whole `page`; a `part` of one,
+ * when its head noun names one of the system's components and it lists fewer
+ * than PAGE_PIECES pieces; or an `edit` of a page the builder already has.
+ *
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @param {ComponentWords[]} components
+ * @returns {IdeaKind}
+ */
+export function ideaKind(query, pages, components) {
+  const text = String(query);
+  const familyWords = familyWordsOf(pages);
+  if (changesExistingPage(text, familyWords, components)) return 'edit';
+  // The head's last word, page words included: "calendar" is the noun of "a
+  // calendar", "page" the noun of "a calendar page". An overlay frame names
+  // where the thing lives, not the thing: "drafts" is the noun of "drafts in
+  // a modal".
+  const head = (text.split(HEAD_END)[0] ?? '').replace(CONTAINER_PHRASE, m =>
+    containersOf(m).size > 0 ? ' ' : m,
+  );
+  const words = (head.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter(
+    w => w.length >= 2,
+  );
+  const noun = stem(words[words.length - 1] ?? '');
+  if (familyWords.has(noun)) return 'page';
+  const pieces = (text.match(/,/g) ?? []).length + 1;
+  if (pieces >= PAGE_PIECES) return 'page';
+  return components.some(c => componentTerms(c).includes(noun))
+    ? 'part'
+    : 'page';
+}
+
+/**
+ * Whether an idea changes a page or part the builder already has: "existing"
+ * in the same phrase as a word that names a family of page templates or one of
+ * the system's components ("the existing incidents table", "the existing
+ * banner"). A new page "inspired by the existing one", or "existing users" on a
+ * new page, names neither, and an idea that asks for a new page is no change
+ * whatever it names.
+ * @param {string} text
+ * @param {Map<string, string>} familyWords
+ * @param {ComponentWords[]} components
+ * @returns {boolean}
+ */
+function changesExistingPage(text, familyWords, components) {
+  const componentWords = new Set(components.flatMap(nameTerms));
+  const phrases = text.toLowerCase().split(PHRASE_END);
+  if (asksNewPage(phrases, familyWords)) return false;
+  return phrases.some(phrase => {
+    const at = phrase.search(EXISTING);
+    return (
+      at >= 0 &&
+      terms(phrase.slice(at)).some(
+        t => familyWords.has(t) || componentWords.has(t),
+      )
+    );
+  });
+}
+
+/**
+ * Whether an idea asks for a new page: "new" before a word that names a family
+ * of page templates ("a new dashboard"), or before only words search drops,
+ * such as "page" ("as a new page"). "A new column" asks for a part.
+ * @param {string[]} phrases
+ * @param {Map<string, string>} familyWords
+ * @returns {boolean}
+ */
+function asksNewPage(phrases, familyWords) {
+  return phrases.some(phrase => {
+    const at = phrase.search(NEW);
+    if (at < 0) return false;
+    const after = terms(phrase.slice(at + 'new'.length));
+    return after.length === 0 || familyWords.has(after[0]);
+  });
+}
+
+/**
+ * Whether an idea asks for a new page (see `asksNewPage`), from the idea and
+ * the project's page templates.
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @returns {boolean}
+ */
+export function asksForNewPage(query, pages) {
+  return asksNewPage(
+    String(query).toLowerCase().split(PHRASE_END),
+    familyWordsOf(pages),
+  );
+}
+
+/**
+ * The words of a component's name: "DateRangeInput" is date, range, input.
+ * @param {ComponentWords} component
+ * @returns {string[]}
+ */
+function nameTerms(component) {
+  return terms(component.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2'));
+}
+
+/**
+ * The terms a component answers to: the words of its name and of its keywords.
+ * @param {ComponentWords} component
+ * @returns {string[]}
+ */
+function componentTerms(component) {
+  return [
+    ...nameTerms(component),
+    ...component.keywords.flatMap(keyword => terms(keyword)),
+  ];
+}

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

@@ -2,7 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * The page template to start from, and the kit around it.
+ * The page template to start from, and the kit around it, with the blocks
+ * build names itself.
  *
  * @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,6 +14,3 @@ 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;