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

package/foundation/release/notices.mjs

@@ -43,9 +43,11 @@ import {userConfigDir} from '../env/user-dirs.mjs';
 import {astryxCommandsOnSearchPath} from '../env/search-path.mjs';
 import {
   CLI_PACKAGE,
+  commandInFolder,
   detectPackageManager,
   getCliInvocation,
 } from '../env/package-manager.mjs';
+import {findAstryxProject, findPackageRoot} from '../fs/paths.mjs';
 import {satisfiesRange, semverCompare} from '../env/semver.mjs';
 import {isInReleaseCache, isReleaseVersion} from './cache.mjs';
 import {
@@ -55,7 +57,12 @@ import {
   tryStateLock,
   writeGlobalState,
 } from './global-state.mjs';
-import {globalFolderOf, isGlobalCopy, projectRootOf} from './choose.mjs';
+import {
+  coreVersionOf,
+  globalFolderOf,
+  isGlobalCopy,
+  projectRootOf,
+} from './choose.mjs';
 import {readReleaseFacts} from './project.mjs';
 import {samePath} from '../fs/path-compare.mjs';
 import {updateNoticesOff} from './update-notice-env.mjs';
@@ -375,16 +382,49 @@ const ADD = {
   bun: 'bun add',
 };
 
+/**
+ * The command that adds a package to the project of a run in `cwd`, with the
+ * project's package manager (spec AST-081 FR12). Null when `cwd` belongs to
+ * no project `spec:AST-040` FR9 defines, and in a folder inside the project
+ * whose package.json is not the project's (see {@link installFolder}): a run
+ * there loads integrations from that package.json, so a package added to the
+ * project would stay unused there, and the advice is
+ * {@link RUN_FROM_PROJECT}.
+ * @param {string} cwd
+ * @returns {((name: string) => string) | null}
+ */
+export function projectAddCommand(cwd) {
+  const target = installFolder(cwd);
+  if (target == null || target.moved) return null;
+  const add = ADD[detectPackageManager(cwd)] ?? ADD.npm;
+  return name => `${add} ${name}`;
+}
+
 /**
  * The commands that bring a project's own CLI and Core to one release, with
  * the project's package manager: when the CLI is newer, Core up to it and then
  * the codemods from Core's release; otherwise the CLI to Core's release.
+ * Null in a folder that belongs to no project, or whose package.json is not
+ * the project's (see {@link installFolder}).
  * @param {{cwd: string, cli: string, core: string}} options
- * @returns {string}
+ * @returns {string | null}
  */
 export function alignCliAndCore({cwd, cli, core}) {
-  const facts = readReleaseFacts(cwd);
-  const root = projectRootOf(facts) ?? cwd;
+  const target = installFolder(cwd);
+  if (target == null || target.moved) return null;
+  const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;
+  return alignIn(root, cli, core);
+}
+
+/**
+ * The commands that bring the CLI and Core of the project at `root` to one
+ * release, run in `root`.
+ * @param {string} root
+ * @param {string} cli
+ * @param {string} core
+ * @returns {string}
+ */
+function alignIn(root, cli, core) {
   const add = ADD[detectPackageManager(root)] ?? ADD.npm;
   if (semverCompare(cli, core) > 0) {
     return `${add} @astryxdesign/core@${cli}, then ${getCliInvocation(root, {installed: true})} upgrade --from ${core} --apply`;
@@ -392,27 +432,81 @@ export function alignCliAndCore({cwd, cli, core}) {
   return `${add} ${CLI_PACKAGE}@${core}`;
 }
 
+/**
+ * Where a command that adds an Astryx package runs, for a run in `cwd`: in
+ * the project `spec:AST-040` FR9 defines, which stops at a repository root
+ * and never counts the home folder (spec AST-081 FR2, FR10). Null when `cwd`
+ * belongs to no such project, so no command adds anything. When `cwd`'s
+ * nearest package.json is not the project's, as in a tool folder that
+ * installs its own Core, a package manager would add to the tool's
+ * package.json, so `moved` says the command runs in the project's folder.
+ * @param {string} cwd
+ * @returns {{dir: string, moved: boolean} | null}
+ */
+export function installFolder(cwd) {
+  const project = findAstryxProject(cwd);
+  if (project == null) return null;
+  const nearest = findPackageRoot(cwd);
+  if (nearest == null || nearest === project) return {dir: cwd, moved: false};
+  return {dir: project, moved: true};
+}
+
+/**
+ * What to tell a run in a folder inside a project whose package.json is not
+ * the project's: run from the project's folder, since adding there would make
+ * the folder a project of its own (spec AST-081 FR2).
+ */
+export const RUN_FROM_PROJECT =
+  "Run this from the Astryx project's folder, or declare an Astryx package in this folder's package.json to make it a project of its own.";
+
+/**
+ * The command that adds the CLI at Core's version, for a run in `cwd` whose
+ * Core is `core`, with the project's package manager in the project root.
+ * `command` is null in a folder inside the project whose package.json is not
+ * the project's (see {@link installFolder}), where the advice is
+ * {@link RUN_FROM_PROJECT}. Null when the folder belongs to no project.
+ * @param {{cwd: string, core: string}} options
+ * @returns {{root: string, core: string, command: string | null} | null}
+ */
+export function cliInstallAdvice({cwd, core}) {
+  const target = installFolder(cwd);
+  if (target == null) return null;
+  if (target.moved) return {root: target.dir, core, command: null};
+  const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;
+  return {root, core, command: addCliCommand(root, core)};
+}
+
 /**
  * The hint for a project with no CLI of its own, answered by `answered` while
  * its Core is `core`: the command that adds the CLI at Core's version, with
- * the project's package manager.
+ * the project's package manager (see {@link cliInstallAdvice}). Null when no
+ * command fits, or when the project the command adds to already matches.
  * @param {{cwd: string, answered: string, core: string}} options
- * @returns {{root: string, line: string}}
+ * @returns {{root: string, line: string} | null}
  */
 export function noCliHint({cwd, answered, core}) {
-  const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;
-  return {root, line: noCliHintLine(answered, core, addCliCommand(root, core))};
+  if (core === answered) return null;
+  const advice = cliInstallAdvice({cwd, core});
+  if (advice == null) return null;
+  return {
+    root: advice.root,
+    line: noCliHintLine(answered, core, advice.command),
+  };
 }
 
 /**
  * The hint's text.
  * @param {string} answered
  * @param {string} core
- * @param {string} command the command that adds the CLI at Core's version
+ * @param {string | null} command the command that adds the CLI at Core's
+ *   version; null in a folder whose package.json is not the project's
  * @returns {string}
  */
 export function noCliHintLine(answered, core, command) {
-  return `astryx: this project has no Astryx CLI installed; answered by CLI ${answered} while its Core is ${core}. To match, run: ${command}`;
+  const head = `astryx: this project has no Astryx CLI installed; answered by CLI ${answered} while its Core is ${core}.`;
+  return command
+    ? `${head} To match, run: ${command}`
+    : `${head} ${RUN_FROM_PROJECT}`;
 }
 
 /**
@@ -432,17 +526,29 @@ export function addCliCommand(root, version) {
  * @param {{cwd: string, current: string, stateDir?: string}} options
  * @returns {ProjectLag | null}
  */
-export function projectLag({cwd, current, stateDir = userConfigDir()}) {
+export function projectLag({cwd, current: given, stateDir = userConfigDir()}) {
   const latest = knownLatest(stateDir);
-  if (!latest || !isBehind(current, latest.version)) return null;
-  const newest = latest.version;
+  if (!latest) return null;
   const facts = readReleaseFacts(cwd);
   if (!facts.inProject) return null;
-  const root = projectRootOf(facts) ?? cwd;
+  const target = installFolder(cwd);
+  if (target == null) return null;
+  const root = target.moved ? target.dir : (projectRootOf(facts) ?? cwd);
+  // From a folder inside the project, the project's own release: its CLI's,
+  // else its Core's, so the project gets one notice and one --from.
+  const projectFacts = target.moved ? readReleaseFacts(root) : null;
+  const current = projectFacts
+    ? (projectFacts.cli?.version ?? coreVersionOf(projectFacts) ?? given)
+    : given;
+  if (!isBehind(current, latest.version)) return null;
+  const newest = latest.version;
   const pm = detectPackageManager(root);
   // The CLI is always installed beside Core: a project that installed only
   // Core gets it too, as recommended, so its version is pinned with Core's.
-  const install = `${ADD[pm] ?? ADD.npm} @astryxdesign/core@${newest} ${CLI_PACKAGE}@${newest}`;
+  // From a folder inside the project whose package.json is not the
+  // project's, the install runs in the project's folder (see installFolder).
+  const add = `${ADD[pm] ?? ADD.npm} @astryxdesign/core@${newest} ${CLI_PACKAGE}@${newest}`;
+  const install = target.moved ? commandInFolder(root, add) : add;
   // The command runs after the install above, so the picker's guess is the
   // project's own CLI (spec AST-081 FR5).
   const stem = getCliInvocation(root, {installed: true});
@@ -452,7 +558,9 @@ export function projectLag({cwd, current, stateDir = userConfigDir()}) {
     newest,
     node: latest.node,
     install,
-    upgrade: `${stem} upgrade --from ${current} --apply`,
+    upgrade: target.moved
+      ? commandInFolder(root, `${stem} upgrade --from ${current} --apply`)
+      : `${stem} upgrade --from ${current} --apply`,
   };
 }
 
@@ -536,18 +644,13 @@ export function noticeLines({
   try {
     // A project with no CLI of its own, answered by a release other than its
     // Core's: once a day per project, how to match them (FR2).
-    if (
-      choice.inProject &&
-      choice.copy === 'starting' &&
-      choice.coreVersion &&
-      choice.coreVersion !== choice.version
-    ) {
+    if (choice.inProject && choice.copy === 'starting' && choice.coreVersion) {
       const hint = noCliHint({
         cwd,
         answered: choice.version,
         core: choice.coreVersion,
       });
-      if (take(`no-cli:${hint.root}`)) lines.push(hint.line);
+      if (hint && take(`no-cli:${hint.root}`)) lines.push(hint.line);
     }
   } catch {
     // A hint never fails a run.
@@ -559,8 +662,16 @@ export function noticeLines({
         choice.copy === 'starting' && choice.coreVersion
           ? choice.coreVersion
           : choice.version;
-      const lag = projectLag({cwd, current, stateDir});
-      if (!lag) recordNoticeSkip('project', 'no-newer', {stateDir, now});
+      // A folder that belongs to no project (spec AST-040 FR9) gets no
+      // project notice; the skip says why.
+      const noProject = installFolder(cwd) == null;
+      const lag = noProject ? null : projectLag({cwd, current, stateDir});
+      if (!lag) {
+        recordNoticeSkip('project', noProject ? 'no-project' : 'no-newer', {
+          stateDir,
+          now,
+        });
+      }
       if (lag && take(`project:${lag.root}`)) {
         lines.push(
           availableLine(lag.current, lag.newest),

package/foundation/release/notices.test.mjs

@@ -355,6 +355,27 @@ describe('globalBehind and projectLag', () => {
   });
 });
 
+describe('projectLag from a tool folder inside a project', () => {
+  it("uses the project's own CLI release, so the project gets one notice and one --from", () => {
+    const stateDir = checked('0.7.3');
+    const app = project(tempDir(), {
+      '@astryxdesign/core': '0.7.1',
+      '@astryxdesign/cli': '0.7.2',
+    });
+    writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});
+    installCore(app, '0.7.1');
+    installStandInCli(app, '0.7.2');
+    const tool = path.join(app, 'tools', 'codegen');
+    writeJson(path.join(tool, 'package.json'), {name: 'codegen'});
+    installCore(tool, '0.7.0');
+
+    const fromApp = projectLag({cwd: app, current: '0.7.2', stateDir});
+    const fromTool = projectLag({cwd: tool, current: '0.7.0', stateDir});
+    expect(fromTool).toMatchObject({root: app, current: '0.7.2'});
+    expect(fromTool?.upgrade).toBe(`cd ${app} && ${fromApp?.upgrade}`);
+  });
+});
+
 describe('the commands notices print go through the command-name picker (spec AST-081 FR5)', () => {
   /** A Core-only npm project behind the newest release. */
   const coreOnlyProject = () => {

package/foundation/release/run-context.mjs

@@ -22,6 +22,7 @@ import {progressLine} from './handoff.mjs';
 import {isJsonMode} from '../response/json.mjs';
 import {cachedRelease, ensureRelease, userCacheDir} from './cache.mjs';
 import {readJson, findReadCore, CORE_PACKAGE_NAME} from './project.mjs';
+import {hostedRun} from '../runtime/package-root.mjs';
 
 /** The running CLI package's folder. */
 const CLI_ROOT = path.resolve(
@@ -105,6 +106,19 @@ export function carriedCore(options = {}) {
   if (besidePkg?.name === CORE_PACKAGE_NAME && besidePkg.version === version) {
     return {dir: beside, unavailable: null};
   }
+  // A hosted run resolves from its package set alone and installs nothing
+  // (architecture:cli-surface INV30): the Core beside the CLI, or none.
+  if (hostedRun()) {
+    if (!fetch) return {dir: null, unavailable: null};
+    const reason =
+      "a hosted run installs nothing, and the host's package set holds no Core beside its CLI";
+    return {
+      dir: null,
+      unavailable: `Core ${version} could not be found: ${reason}`,
+      version,
+      reason,
+    };
+  }
   const cached = cachedRelease(version, cacheDir);
   if (cached) return {dir: cached.coreDir, unavailable: null};
   if (!fetch) return {dir: null, unavailable: null};

package/foundation/response/response-types.doc.mjs

@@ -338,7 +338,7 @@ export const doc = {
     {
       value: 'integration.validate',
       description:
-        'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked | skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).',
+        'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand and cli_peer_version when the running CLI is outside the @astryxdesign/cli peer range of the package, and the package layout findings added after the last minor release, each with its fix in the message (duplicate_component_doc, symlinked_root, unreadable_file, invalid_package_json, no_provider_id, source_without_component_doc where a doc and its source still pair), and doc_name_mismatch and unknown_block_component, until they become warnings in the next minor release. A runner_command note lists each Astryx command a topic writes with a package runner (its file, line and the bare command to write). When the manifest loads, docTypes checks each doc against its published authoring type: status (checked | skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked). When the manifest loads, docNames lists the component doc names it could not judge: status (checked), findings (always empty; a doc name the module its import names provably does not export is a doc_name_mismatch note, with its fix in the message) and unchecked ({file, name, reason}: a doc whose name differs from the name it is listed under and whose source exports cannot all be read, such as a re-export from another package). When the manifest loads, blockComponents lists the component names templates give in exampleFor or componentsUsed that could not be judged: status (checked), findings (always empty; a name neither the package nor Core has, and the template does not import, is an unknown_block_component note, with its fix in the message) and unchecked ({file, name, reason}: a name the template may reach through anything other than named imports and re-exports from Core, React, StyleX, local helpers or the entry of the package itself, such as an import from another package, a default or namespace import, an alias of or member read off an imported binding, require() or a dynamic import(), or a local module that cannot be read, or any name Core would have to resolve when Core is not installed). Since 0.7.3 each import apps cannot use is also a note (its fix in the message), listed only and failing --strict from the next minor. publicImports ({status: checked, findings: [], unchecked}) lists each import the check could not judge as {file, specifier, reason}; never counted or failed on.',
     },
     {
       value: 'integration.template-conflicts',

package/foundation/route/route.d.mts

@@ -0,0 +1,285 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file The small routing helper the commands that pick among candidates
+ * share (build, search): two node kinds and the runner that walks them.
+ *
+ * A searcher answers a request in its command's own result shape, or returns
+ * null to pass. A dispatcher scores nothing: it names the children that should
+ * answer, best first, with a confidence from 0 to 1. Below its floor, or when
+ * none of the children it named answers, its fallback searcher answers. A
+ * dispatcher's children may be dispatchers, so trees nest. A classifier is a
+ * dispatcher whose route is a static word-weight classifier: the request's
+ * tokens vote for a class, and a class with a searcher takes the request when
+ * the classifier is sure enough.
+ *
+ * A tree file types the helpers for its command once, by taking them from
+ * `routeKit` typed as `RouteKit<Request, Context, Answer>` (see
+ * api/search/tree.mjs); each node is then plain `{id, summary, run}`.
+ *
+ * Every node gets the same context, so any node can be run, measured, and
+ * tuned on its own: `runTree` takes an optional `tuning` with weights that
+ * replace a node's shipped weights for one call, and a trace callback that
+ * sees every step. Neither ever reaches a command's output.
+ *
+ * @input a tree of nodes, a request, and the context the command's adapter
+ *   gathered
+ * @output the first answer a searcher gives
+ * @position foundation; api/build and api/search build their trees with it
+ */
+/**
+ * @template Request, Context, Answer
+ * @typedef {object} Searcher
+ * @property {'searcher'} kind
+ * @property {string} id
+ * @property {string} summary One plain line: what it answers.
+ * @property {(request: Request, ctx: Context, weights: unknown) => Answer | null | Promise<Answer | null>} run
+ *   `weights` is a tuning override for this node, or null for its shipped weights.
+ */
+/**
+ * @typedef {object} Route
+ * @property {readonly string[]} ids The children to try, best first.
+ * @property {number} confidence From 0 to 1.
+ */
+/**
+ * @template Request, Context
+ * @typedef {object} Dispatcher
+ * @property {'dispatcher'} kind
+ * @property {string} id
+ * @property {string} summary
+ * @property {readonly string[]} children
+ * @property {number} floor Below this confidence the fallback answers.
+ * @property {string} fallback A searcher's id.
+ * @property {(request: Request, ctx: Context, weights: unknown) => Route | Promise<Route>} route
+ */
+/**
+ * @template Request, Context, Answer
+ * @typedef {Searcher<Request, Context, Answer> | Dispatcher<Request, Context>} TreeNode
+ */
+/**
+ * @template Request, Context, Answer
+ * @typedef {object} Tree
+ * @property {string} root
+ * @property {ReadonlyMap<string, TreeNode<Request, Context, Answer>>} nodes
+ */
+/**
+ * One step the runner took.
+ * @typedef {object} TraceStep
+ * @property {string} id
+ * @property {'searcher' | 'dispatcher'} kind
+ * @property {number} depth
+ * @property {boolean} fallback Whether this step ran as a fallback.
+ * @property {Route} [route] A dispatcher's route.
+ * @property {boolean} [answered] Whether a searcher answered.
+ */
+/**
+ * @typedef {object} Tuning
+ * @property {Readonly<Record<string, unknown>>} [weights] Weights by node id, replacing that node's shipped weights for this call.
+ * @property {(step: TraceStep) => void} [onTrace]
+ */
+/**
+ * Static classifier weights: one row of numbers per token, one number per
+ * class. A request's score for a class is the sum of its tokens' numbers.
+ * @typedef {object} ClassifierWeights
+ * @property {readonly string[]} classes
+ * @property {Readonly<Record<string, readonly number[]>>} tokens
+ */
+/**
+ * @template Request, Context
+ * @typedef {object} ClassifierSpec
+ * @property {string} id
+ * @property {string} summary
+ * @property {Readonly<Record<string, string>>} searchers Class name -> the
+ *   searcher that answers it. A class with no searcher goes to the fallback.
+ * @property {string} fallback The searcher that keeps every other request.
+ * @property {number} floor A searcher takes a request only when its class's
+ *   probability is at least this.
+ * @property {(request: Request, ctx: Context) => readonly string[]} features
+ *   The request's tokens.
+ * @property {(ctx: Context) => ClassifierWeights} weights The shipped weights,
+ *   which the command's adapter put in the context.
+ */
+/**
+ * The helpers, typed for one command's request, context, and answer.
+ * @template Request, Context, Answer
+ * @typedef {object} RouteKit
+ * @property {(node: Omit<Searcher<Request, Context, Answer>, 'kind'>) => Searcher<Request, Context, Answer>} defineSearcher
+ * @property {(node: Omit<Dispatcher<Request, Context>, 'kind'>) => Dispatcher<Request, Context>} defineDispatcher
+ * @property {(spec: ClassifierSpec<Request, Context>) => Dispatcher<Request, Context>} defineClassifier
+ * @property {(root: string, nodes: readonly TreeNode<Request, Context, Answer>[]) => Tree<Request, Context, Answer>} defineTree
+ */
+/**
+ * The probability of each class for these tokens: a softmax over the summed
+ * rows of the tokens the weights know.
+ * @param {ClassifierWeights} weights
+ * @param {readonly string[]} tokens
+ * @returns {number[]}
+ */
+export function classify(weights: ClassifierWeights, tokens: readonly string[]): number[];
+/**
+ * A dispatcher whose route is a static classifier. The most probable class
+ * (the first on a tie) is handed to its searcher; a class with no searcher,
+ * or the fallback's own class, stays with the fallback. Tuning weights for
+ * this node replace its shipped weights.
+ * @template Request, Context
+ * @param {ClassifierSpec<Request, Context>} spec
+ * @returns {Dispatcher<Request, Context>}
+ */
+export function defineClassifier<Request, Context>(spec: ClassifierSpec<Request, Context>): Dispatcher<Request, Context>;
+/**
+ * @template Request, Context, Answer
+ * @param {Omit<Searcher<Request, Context, Answer>, 'kind'>} node
+ * @returns {Searcher<Request, Context, Answer>}
+ */
+export function defineSearcher<Request, Context, Answer>(node: Omit<Searcher<Request, Context, Answer>, "kind">): Searcher<Request, Context, Answer>;
+/**
+ * @template Request, Context
+ * @param {Omit<Dispatcher<Request, Context>, 'kind'>} node
+ * @returns {Dispatcher<Request, Context>}
+ */
+export function defineDispatcher<Request, Context>(node: Omit<Dispatcher<Request, Context>, "kind">): Dispatcher<Request, Context>;
+/**
+ * A tree from its nodes. Throws on a duplicate id, a missing root, child, or
+ * fallback, a fallback that is not a searcher, or a dispatcher cycle.
+ * @template Request, Context, Answer
+ * @param {string} root
+ * @param {readonly TreeNode<Request, Context, Answer>[]} list
+ * @returns {Tree<Request, Context, Answer>}
+ */
+export function defineTree<Request, Context, Answer>(root: string, list: readonly TreeNode<Request, Context, Answer>[]): Tree<Request, Context, Answer>;
+/**
+ * Runs the tree from its root, or from `start` to run one node alone: a
+ * dispatcher below its floor runs its fallback; otherwise the children it
+ * names run in order and the first answer wins; when none answers, the
+ * fallback runs.
+ * @template Request, Context, Answer
+ * @param {Tree<Request, Context, Answer>} tree
+ * @param {Request} request
+ * @param {Context} ctx
+ * @param {{tuning?: Tuning, start?: string}} [options]
+ * @returns {Promise<Answer | null>}
+ */
+export function runTree<Request, Context, Answer>(tree: Tree<Request, Context, Answer>, request: Request, ctx: Context, options?: {
+    tuning?: Tuning;
+    start?: string;
+}): Promise<Answer | null>;
+/**
+ * The helpers in one object, for a tree file to type once (see the file
+ * comment).
+ * @type {RouteKit<any, any, any>}
+ */
+export const routeKit: RouteKit<any, any, any>;
+export type Searcher<Request, Context, Answer> = {
+    kind: "searcher";
+    id: string;
+    /**
+     * One plain line: what it answers.
+     */
+    summary: string;
+    /**
+     *   `weights` is a tuning override for this node, or null for its shipped weights.
+     */
+    run: (request: Request, ctx: Context, weights: unknown) => Answer | null | Promise<Answer | null>;
+};
+export type Route = {
+    /**
+     * The children to try, best first.
+     */
+    ids: readonly string[];
+    /**
+     * From 0 to 1.
+     */
+    confidence: number;
+};
+export type Dispatcher<Request, Context> = {
+    kind: "dispatcher";
+    id: string;
+    summary: string;
+    children: readonly string[];
+    /**
+     * Below this confidence the fallback answers.
+     */
+    floor: number;
+    /**
+     * A searcher's id.
+     */
+    fallback: string;
+    route: (request: Request, ctx: Context, weights: unknown) => Route | Promise<Route>;
+};
+export type TreeNode<Request, Context, Answer> = Searcher<Request, Context, Answer> | Dispatcher<Request, Context>;
+export type Tree<Request, Context, Answer> = {
+    root: string;
+    nodes: ReadonlyMap<string, TreeNode<Request, Context, Answer>>;
+};
+/**
+ * One step the runner took.
+ */
+export type TraceStep = {
+    id: string;
+    kind: "searcher" | "dispatcher";
+    depth: number;
+    /**
+     * Whether this step ran as a fallback.
+     */
+    fallback: boolean;
+    /**
+     * A dispatcher's route.
+     */
+    route?: Route | undefined;
+    /**
+     * Whether a searcher answered.
+     */
+    answered?: boolean | undefined;
+};
+export type Tuning = {
+    /**
+     * Weights by node id, replacing that node's shipped weights for this call.
+     */
+    weights?: Readonly<Record<string, unknown>> | undefined;
+    onTrace?: ((step: TraceStep) => void) | undefined;
+};
+/**
+ * Static classifier weights: one row of numbers per token, one number per
+ * class. A request's score for a class is the sum of its tokens' numbers.
+ */
+export type ClassifierWeights = {
+    classes: readonly string[];
+    tokens: Readonly<Record<string, readonly number[]>>;
+};
+export type ClassifierSpec<Request, Context> = {
+    id: string;
+    summary: string;
+    /**
+     * Class name -> the
+     * searcher that answers it. A class with no searcher goes to the fallback.
+     */
+    searchers: Readonly<Record<string, string>>;
+    /**
+     * The searcher that keeps every other request.
+     */
+    fallback: string;
+    /**
+     * A searcher takes a request only when its class's
+     * probability is at least this.
+     */
+    floor: number;
+    /**
+     *   The request's tokens.
+     */
+    features: (request: Request, ctx: Context) => readonly string[];
+    /**
+     * The shipped weights,
+     * which the command's adapter put in the context.
+     */
+    weights: (ctx: Context) => ClassifierWeights;
+};
+/**
+ * The helpers, typed for one command's request, context, and answer.
+ */
+export type RouteKit<Request, Context, Answer> = {
+    defineSearcher: (node: Omit<Searcher<Request, Context, Answer>, "kind">) => Searcher<Request, Context, Answer>;
+    defineDispatcher: (node: Omit<Dispatcher<Request, Context>, "kind">) => Dispatcher<Request, Context>;
+    defineClassifier: (spec: ClassifierSpec<Request, Context>) => Dispatcher<Request, Context>;
+    defineTree: (root: string, nodes: readonly TreeNode<Request, Context, Answer>[]) => Tree<Request, Context, Answer>;
+};