@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/core/command/confirm.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The line prompter: the one prompt that reads whole lines, not keys as
+ * `src/cli/prompt/`'s do, so it needs no raw mode and works on a pipe as
+ * well as on a terminal. Every yes-or-no question rafa asks, and the root
+ * `rafa init` reads, goes through a {@link Prompter}; the commands take
+ * one from {@link createLinePrompter} over `process.stdin` and
+ * `process.stderr`, and tests pass a scripted one.
+ *
+ * ## The prompter
+ *
+ * {@link createLinePrompter} reads lines from a stream with `readline`'s
+ * `line` and `close` events, and writes each question and each thing it
+ * says to another stream. It does not use `readline/promises`: measured
+ * on bun 1.3.14, a `question` pending when its input ends never settles,
+ * where the `close` event fires. The final line of an input that ends
+ * without a line break is still delivered as a line, measured the same
+ * way. readline is given no output and `terminal: false`, so on a
+ * terminal the terminal's own line discipline echoes and edits what is
+ * typed.
+ *
+ * Two line prompters over one input both receive every line, so a
+ * command handing a question to another closes its own first.
+ *
+ * ## The lazy prompter
+ *
+ * {@link lazyPrompter} wraps the opening of a prompter so a run that
+ * never asks opens nothing: the prompter is opened at the first
+ * question, kept for the next, and closed by `close`, after which the
+ * next question opens a fresh one. Its `ask` answers whether the line
+ * typed means yes: `y` or `yes`, trimmed and in any case, the reading
+ * every `[y/N]` question in rafa makes. Anything else declines, the empty
+ * answer and the null of an input that ended included. `issue ready`,
+ * `next`, `cleanup` and `plan create`'s three offers ask through it.
+ */
+import type { Readable } from 'node:stream';
+/** Asks an operator, and tells them what went wrong. */
+export interface Prompter {
+    /** Writes `text` and a line break. */
+    readonly say: (text: string) => void;
+    /** Writes `question` and answers the next line typed, or null once the input has ended. */
+    readonly ask: (question: string) => Promise<string | null>;
+    /** Stops reading the input. */
+    readonly close: () => void;
+}
+/** A prompter opened at its first question, see the module note. */
+export interface LazyPrompter {
+    /** Opens the prompter if it is not open, asks `question` and answers whether the line typed means yes. */
+    readonly ask: (question: string) => Promise<boolean>;
+    /** Closes the prompter if one is open; the next question opens another. */
+    readonly close: () => void;
+}
+/** A stream the prompter writes to: `process.stderr`, or a test's own. */
+export interface PromptOutput {
+    readonly write: (chunk: string) => unknown;
+}
+/**
+ * A {@link Prompter} reading lines from `input` and writing to `output`;
+ * see the module note. A line typed before it is asked for is kept for
+ * the next question.
+ */
+export declare function createLinePrompter(input: Readable, output: PromptOutput): Prompter;
+/**
+ * A {@link LazyPrompter} over `open`, which is called at the first
+ * question and again at the first one after each `close`; see the
+ * module note.
+ */
+export declare function lazyPrompter(open: () => Prompter): LazyPrompter;

package/dist/core/command/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The barrel over the command contract: every name `command.ts`,
+ * `confirm.ts`, `lazy.ts`, `registry-types.ts`, `running.ts`,
+ * `spends.ts`, `types.ts` and `version.ts` export, and nothing else.
+ *
+ * A file outside `packages/rafa/src/core/` imports this file and never the eight
+ * behind it (`scripts/survey/core-barrels.ts` measures that, and
+ * `src/tests/core-barrels.sweep.test.ts` holds it against the tree). A
+ * file inside `packages/rafa/src/core/` imports the eight directly and never this
+ * file.
+ *
+ * ## What sits behind it
+ *
+ *   - `command.ts`: `RafaCommand`, the `RafaContext` it runs with,
+ *     `CommandExit`, the routing words and the shape check;
+ *   - `confirm.ts`: the `Prompter` every yes-or-no question goes
+ *     through, the line prompter that reads one from a stream, and the
+ *     lazy prompter that opens one only to ask;
+ *   - `lazy.ts`: `CommandDeclaration`, a command less its `run`, and
+ *     `lazyCommand`, the command over a declaration whose `run` imports
+ *     the command's module and delegates to its default export;
+ *   - `registry-types.ts`: the contract of the dispatcher's registry,
+ *     `CommandRegistry` and the five shapes it names, and
+ *     `CommandFeature`, what one feature contributes to it, whose
+ *     builder stays in `src/cli/registry.ts`;
+ *   - `running.ts`: the command this process is running with its parsed
+ *     flags, recorded by the dispatcher and read by the spend guard;
+ *   - `spends.ts`: a command's `spends` declaration, `CommandSpend`, its
+ *     shape check and the mark help ends a spender's roster line with;
+ *   - `types.ts`: the contracts copied from open-tomato's `cli-core`,
+ *     `CliContext`, `CliCommand`, `ArgSpec` and `FlagSpec`, which
+ *     `RafaCommand` extends;
+ *   - `version.ts`: the version the running build answers with, and the
+ *     line that spells it.
+ *
+ * The eight hold no name in common, so each name is exported once and
+ * from the file that declares it.
+ *
+ * ## Why one barrel can hold all eight
+ *
+ * A barrel that groups a file with a file outside `packages/rafa/src/core/` that
+ * imports the barrel back by value is a runtime cycle. None of the eight
+ * imports a file outside `packages/rafa/src/core/` by value. `command.ts` takes
+ * `spendsProblem` from `spends.ts` beside it, and both take
+ * `describeValue` from `packages/rafa/src/core/config/config-sections.ts`.
+ * `lazy.ts` takes the shape check, `CommandExit` and `commandSpelling`
+ * from `command.ts`, and `messageOf` from the same config file; the
+ * module a lazy command loads is the caller's `load()`, imported when
+ * the command runs, never by `lazy.ts` itself.
+ * `confirm.ts` and `running.ts` import `node:` modules alone by value,
+ * `running.ts` naming `command.ts` and `types.ts` with `import type`.
+ * `version.ts` imports the root `package.json`, and `types.ts` nothing
+ * by value: it names `packages/rafa/src/core/config/config-sections.ts` and the
+ * `Output` port with `import type`. `registry-types.ts` imports nothing
+ * by value either: it names `command.ts` with `import type`, and this
+ * file exports its names with `export type`, so loading the barrel
+ * never loads it.
+ *
+ * `command.ts` also names `src/project/scope.ts` with `import type`,
+ * which is erased before anything loads; it named `src/cli/registry.ts`
+ * the same way until the registry's contract moved into
+ * `registry-types.ts`. `src/cli/registry.ts` imports this barrel by
+ * value, for the shape check and the routing words, so that edge is the
+ * one a value import in `command.ts` would turn into a cycle.
+ *
+ * Measured when the three moved: the value imports of the non-test files
+ * under `src/` and `packages/` held six cycles before the move and the
+ * same six after it, none through a file of this folder. The control,
+ * the same tree with `command.ts` taking one value (`HELP_WORD`) from
+ * `src/cli/registry.ts`, held a seventh: `src/cli/registry.ts`,
+ * `command.ts` and this file.
+ *
+ * Measured again when `types.ts` moved in, over every strongly connected
+ * set of the same value imports: five cycles at the base and five after
+ * the move, none through a file of this folder or of `src/cli/core/`.
+ * The same `HELP_WORD` control held a sixth, `src/cli/registry.ts`,
+ * `command.ts` and this file.
+ *
+ * Measured again when `spends.ts` moved in, the same way: five cycles at
+ * the base and five after the move, none through a file of this folder
+ * or of `src/cli/`. The same `HELP_WORD` control held a sixth,
+ * `src/cli/registry.ts`, `command.ts` and this file.
+ *
+ * Measured again when the registry's contract moved into
+ * `registry-types.ts`, the same way: five cycles at the base and five
+ * after the move, none through a file of this folder or of `src/cli/`.
+ * The same `HELP_WORD` control held a sixth, `src/cli/registry.ts`,
+ * `command.ts` and this file.
+ *
+ * ## What it exports
+ *
+ * Each name is spelled, types apart from values, as the config barrels
+ * spell theirs. No name here is part of the published surface:
+ * `src/index.ts` re-exports nothing from this file.
+ *
+ * `index.test.ts` holds the list to the eight files: every name any of
+ * them exports is here once, as the same binding, and no other name is
+ * here.
+ */
+export type { CommandDeprecation, CommandExample, CommandOutput, FlagDeprecation, RafaCommand, RafaContext, RafaFlagSpec, } from './command.js';
+export type { LazyPrompter, PromptOutput, Prompter } from './confirm.js';
+export type { CommandDeclaration } from './lazy.js';
+export type { CommandAlias, CommandFeature, CommandRegistry, CommandRegistryInput, ModuleMount, RosterOptions, SubjectSpec, } from './registry-types.js';
+export type { RunningCommand } from './running.js';
+export type { CommandSpend, SpendsWhen } from './spends.js';
+export type { ArgSpec, CliCommand, CliContext, FlagSpec, } from './types.js';
+export { COMMAND_OUTPUTS, CommandExit, commandProblem, commandSpelling, isRoutingWord, isTopLevel, } from './command.js';
+export { createLinePrompter, lazyPrompter } from './confirm.js';
+export { lazyCommand } from './lazy.js';
+export { restoreRunningCommand, runAsRunningCommand, runningCommand, setRunningCommand, } from './running.js';
+export { SPENDS_GLYPH, SPENDS_WHEN, spendsCondition, spendsMark, spendsProblem, } from './spends.js';
+export { RAFA_VERSION, versionLine } from './version.js';

package/dist/core/command/lazy.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A command whose module is imported when it runs, not when the roster
+ * is built: {@link lazyCommand} over a {@link CommandDeclaration}.
+ *
+ * ## What is declared and what is loaded
+ *
+ * A declaration is a `RafaCommand` less its `run`: every field routing,
+ * help, `describe` and the spend guard read, so a roster of lazy
+ * commands is built, routed and rendered without importing one command
+ * module. The lazy command is the declaration spread under a `run` of
+ * its own, so it passes `commandProblem` (`command.ts` beside this
+ * file) as the declaration's fields stand.
+ *
+ * Its `run` awaits `load()`, typically `() => import('./x.js')`, and
+ * holds the module's default export to a command: one `commandProblem`
+ * accepts, whose subject and action are the declaration's. It then hands
+ * the context to that command's `run` and settles as that `run`
+ * settles, a `CommandExit` it throws included. The loaded command's
+ * other fields are not compared with the declaration's: the dispatcher
+ * routed, parsed and guarded by the declaration's before `run` was
+ * called.
+ *
+ * ## Refusing
+ *
+ * A load that rejects, a default export `commandProblem` refuses, and a
+ * default export spelled as another command each refuse with
+ * `CommandExit(1, message)`, the message reading
+ * `feature "<feature>": command "<spelling>" failed to load: <reason>`.
+ * The spelling is `commandSpelling`'s, so a top-level command reads as
+ * its one word, as every other refusal naming a command spells it. The
+ * reason is the rejection's message, the shape check's sentence, or the
+ * spelling the export has against the one declared.
+ *
+ * Nothing is cached here: a second run calls `load()` again, and the
+ * module loader's own cache answers it.
+ */
+import type { RafaCommand } from './command.js';
+/** A command less its `run`: what a feature declares for a command it loads when run. */
+export type CommandDeclaration = Omit<RafaCommand, 'run'>;
+/** What a command module's import resolves to: the command is its default export. */
+type CommandModule = {
+    readonly default?: unknown;
+} | null | undefined;
+/**
+ * A command spreading `declaration` under a `run` that loads the
+ * command and delegates to it. See the module note.
+ *
+ * @param declaration - Every field of the command but its `run`.
+ * @param load - Imports the command's module, whose default export is the command.
+ * @param feature - The name of the feature the command belongs to, which a refusal names.
+ * @returns The lazy command.
+ */
+export declare function lazyCommand(declaration: CommandDeclaration, load: () => Promise<CommandModule>, feature: string): RafaCommand;
+export {};

package/dist/core/command/registry-types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The registry's contract: the {@link CommandRegistry} the dispatcher
+ * routes through, what it is built from, the subjects, aliases and
+ * mounts it answers, and the {@link CommandFeature} one feature hands
+ * the registry its subjects and commands in.
+ *
+ * The registry itself, `createCommandRegistry` and the refusals it
+ * throws, stays the CLI's, in `src/cli/registry.ts`, which imports
+ * these names from here and re-exports them under the same names. Core
+ * holds the contract alone, so `RafaContext` can name the registry a
+ * command runs with without importing a file above core.
+ *
+ * Every name here is a type: the file imports `RafaCommand` from
+ * `command.ts` beside it with `import type`, and nothing by value.
+ */
+import type { RafaCommand } from './command.js';
+/** A subject: the first routing word, and what its roster line says. */
+export interface SubjectSpec {
+    /** The routing word, singular: `issue`. */
+    readonly name: string;
+    /** One line for the root roster. */
+    readonly summary: string;
+}
+/** The commands one module's entry exports, mounted under `module/<name>`. */
+export interface ModuleMount {
+    /** The word typed after an `exec` action: `linear` in `rafa module exec linear next`. */
+    readonly name: string;
+    /** The file the commands were imported from. */
+    readonly entry: string;
+    /** The commands, each routed by its action. */
+    readonly commands: readonly RafaCommand[];
+}
+/** One alias: the words it is typed as, the command it routes to, and whether it is kept for good. */
+export interface CommandAlias {
+    readonly words: readonly string[];
+    readonly command: RafaCommand;
+    /** True for one of the command's `lastingAliases`, which prints no deprecation line. */
+    readonly lasting: boolean;
+}
+/** Whether a roster keeps hidden commands. */
+export interface RosterOptions {
+    /** Keeps the commands declaring `hidden`. Off by default. */
+    readonly includeHidden?: boolean;
+}
+/** What a registry is built from. */
+export interface CommandRegistryInput {
+    /** The subjects, in roster order. */
+    readonly subjects: readonly SubjectSpec[];
+    /** The core commands, in roster order. */
+    readonly commands: readonly RafaCommand[];
+}
+/**
+ * What one feature contributes to a registry: its name, the subjects it
+ * declares and the commands under them, each list in roster order. The
+ * same two lists as a {@link CommandRegistryInput}, under the name that
+ * says which feature they came from.
+ */
+export interface CommandFeature {
+    /** The feature's name, which a load failure of one of its commands names. */
+    readonly name: string;
+    /** The subjects the feature declares, in roster order. */
+    readonly subjects: readonly SubjectSpec[];
+    /** The feature's commands, in roster order. */
+    readonly commands: readonly RafaCommand[];
+}
+/** The subjects, commands, aliases and mounts the dispatcher routes through. Never changes once made. */
+export interface CommandRegistry {
+    /** The subjects, in the order declared. */
+    readonly subjects: () => readonly SubjectSpec[];
+    /** The subject a word names, as its name or its plural, or undefined. */
+    readonly subjectOf: (word: string) => SubjectSpec | undefined;
+    /** The core commands in the order declared, top-level ones included. */
+    readonly commands: (options?: RosterOptions) => readonly RafaCommand[];
+    /**
+     * The commands under a subject's name, or under a mount's key
+     * (`module/<name>`), in the order declared. Empty for a name holding
+     * none, a top-level command's included.
+     */
+    readonly actionsOf: (subject: string, options?: RosterOptions) => readonly RafaCommand[];
+    /** The command under a subject's name or a mount's key, and an action, or undefined. */
+    readonly find: (subject: string, action: string) => RafaCommand | undefined;
+    /** The top-level command a word names, or undefined. */
+    readonly topLevel: (word: string) => RafaCommand | undefined;
+    /** Every alias, longest first, in the order declared among equals. */
+    readonly aliases: () => readonly CommandAlias[];
+    /** The mounts, in the order mounted. */
+    readonly mounts: () => readonly ModuleMount[];
+    /** The mount a module name names, or undefined. */
+    readonly mountOf: (name: string) => ModuleMount | undefined;
+    /**
+     * A new registry holding this one's mounts followed by `mount`, leaving
+     * this one unchanged. Throws, answering no registry, on a mount the
+     * module note refuses.
+     */
+    readonly mount: (mount: ModuleMount) => CommandRegistry;
+}

package/dist/core/command/running.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The command this process is running, and the flags its line was parsed
+ * into.
+ *
+ * A reader deep below a command's `run` — the spend guard in
+ * `packages/rafa/src/core/loop/claude.ts` — asks {@link runningCommand} which command it
+ * runs under, without a context threaded down to it. The record is held
+ * in two places, and the reader answers the first that has one.
+ *
+ * ## The scope
+ *
+ * {@link runAsRunningCommand} runs a function with a record in an async
+ * scope of its own, an `AsyncLocalStorage` (`node:async_hooks`). Inside
+ * that function, and in everything it awaits or starts, the reader
+ * answers that record; once the function ends, however it ends, nothing
+ * of it is left. The dispatcher runs every command this way
+ * (`src/cli/dispatch.ts`), so nothing it records outlives the
+ * invocation.
+ *
+ * A scope belongs to one run, so runs need not nest to stay apart. Two
+ * runs that overlap in one process, started together and awaited with
+ * `Promise.all`, each read their own record whichever ends first. A run
+ * started inside another reads the inner record inside and the outer one
+ * after. The module-level value below keeps overlapping runs apart only
+ * while they nest: set and put back in a `finally` it is a stack, and
+ * two that end out of order leave the record of one of them for the
+ * rest of the process (#927).
+ *
+ * ## The module-level value
+ *
+ * {@link setRunningCommand} records a command with its parsed flags at
+ * module level and answers the record it replaced, null when nothing was
+ * recorded. {@link restoreRunningCommand} puts back a record
+ * {@link setRunningCommand} answered, so a caller that sets one restores
+ * it in a `finally`. Outside every scope the reader answers this value,
+ * or null. No module but a test sets it: a case stands in for a dispatch
+ * with it, as `src/tests/core-coupled/core/loop/claude.test.ts` does ahead of a door.
+ *
+ * ## A set made inside a scope
+ *
+ * The reader prefers the scope, and the setters write the module-level
+ * value alone, inside a scope as outside one. So a set made inside a
+ * scope changes nothing that scope reads, answers the module-level
+ * record it replaced, and is what the reader answers once the scope has
+ * ended. A scope's record cannot be replaced from inside it.
+ *
+ * ## What reads outside the scope
+ *
+ * A scope follows the awaits and the callbacks started inside it. A
+ * callback the runtime calls from elsewhere does not carry it. Measured
+ * under bun 1.3.14, three listeners registered inside a scope read no
+ * store: a `process.on` signal listener when the signal arrived, an
+ * abort listener that handler fired, and an abort listener an
+ * `AbortSignal.timeout` fired. A timer, a child process's `data`
+ * listener, a `readline` `line` listener and the code after an await
+ * such a handler settled all read the scope's. A reader outside the
+ * scope gets the module-level value; one that needs the scope's is
+ * wrapped with `AsyncResource.bind` where it is registered.
+ *
+ * The flags are copied and frozen when recorded, so a caller changing
+ * its own flags object afterwards changes nothing recorded.
+ *
+ * Bun runs every test file in one process, and the module-level value is
+ * module state: a case that sets a record restores the one it replaced
+ * after it.
+ */
+import type { RafaCommand } from './command.js';
+import type { CliContext } from './types.js';
+/** A running command and the flags its line was parsed into. */
+export interface RunningCommand {
+    /** The command running. */
+    readonly command: RafaCommand;
+    /** Its parsed flags by name, as the context carries them. */
+    readonly flags: CliContext['flags'];
+}
+/**
+ * Runs `run` with `command` and `flags` recorded as running in an async
+ * scope of its own, and answers what `run` answers. The record is read
+ * inside `run` and whatever it awaits, and nowhere after it; see the
+ * module note.
+ */
+export declare function runAsRunningCommand<T>(command: RafaCommand, flags: CliContext['flags'], run: () => T): T;
+/**
+ * Records `command` as running with `flags` at module level, and answers
+ * the module-level record it replaced for {@link restoreRunningCommand}.
+ * Inside a scope it changes nothing that scope reads; see the module
+ * note.
+ */
+export declare function setRunningCommand(command: RafaCommand, flags: CliContext['flags']): RunningCommand | null;
+/**
+ * The command running now with its flags: the record of the scope this
+ * is read in, else the module-level one, else null.
+ */
+export declare function runningCommand(): RunningCommand | null;
+/** Puts back `previous`, a module-level record {@link setRunningCommand} answered. */
+export declare function restoreRunningCommand(previous: RunningCommand | null): void;

package/dist/core/command/spends.d.ts

@@ -0,0 +1,39 @@
+/** The mark help puts on a command that spends Claude usage. */
+export declare const SPENDS_GLYPH = "\uD83E\uDE99";
+/** The four values `when` takes. */
+export declare const SPENDS_WHEN: readonly ["always", "with", "unless", "through"];
+/** One of the four forms of a declaration. */
+export type SpendsWhen = (typeof SPENDS_WHEN)[number];
+/** What a command spends, and when; see the module note. */
+export type CommandSpend = {
+    readonly when: 'always';
+    readonly what: string;
+} | {
+    readonly when: 'with';
+    readonly flag: string;
+    readonly what: string;
+} | {
+    readonly when: 'unless';
+    readonly flag: string;
+    readonly what: string;
+} | {
+    readonly when: 'through';
+    readonly what: string;
+};
+/**
+ * What keeps `value` from being a `spends` declaration, as a sentence
+ * naming the field, or null when nothing does. Absent passes: a command
+ * that declares nothing spends nothing.
+ */
+export declare function spendsProblem(value: unknown): string | null;
+/**
+ * The condition a declaration spends under, as help prints it:
+ * `with --resolve`, `unless --no-model`, or null for `always` and
+ * `through`.
+ */
+export declare function spendsCondition(spend: CommandSpend): string | null;
+/**
+ * The mark ending a spender's roster line: `🪙`, `🪙 with --resolve` or
+ * `🪙 unless --no-model`.
+ */
+export declare function spendsMark(spend: CommandSpend): string;

package/dist/core/command/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The contracts a rafa command is written against: the context it runs
+ * with, the positional arguments and flags it declares, and the command.
+ *
+ * Copied from open-tomato's `packages/shared/cli-core/src/types.ts` at
+ * commit `6c774b81fc62489f31748c47e251f11448e3904a` (2026-06-25). The
+ * package is not on the public registry, so rafa copies it rather than
+ * depending on it, as it copies `parseArgs.ts` and `assembleContext.ts`,
+ * which stay in `src/cli/core/`, from the same package.
+ *
+ * The copy sat beside those two until it moved into `packages/rafa/src/core/command/`,
+ * so core's `command.ts` reads it without importing the CLI.
+ * `packages/rafa/src/core/command/index.ts` exports its names to every
+ * file outside core; the re-export `src/cli/core/types.ts` kept for the
+ * CLI was deleted when core moved into its package (#1090).
+ *
+ * ## What the copy changes
+ *
+ * `CliContext.output` is rafa's `Output` port, which `packages/rafa/src/ports/index.ts`
+ * copies from the source's `CliOutput`. The source imports that type from
+ * its own `output.ts`, whose two renderers rafa ported to
+ * `packages/rafa/src/core/output/text.ts` and `src/adapters/output/json.ts`. Every member is otherwise the source's, with a
+ * TSDoc line added to each.
+ *
+ * `ArgSpec` and `FlagSpec` are still two names for one shape. The source
+ * declares `default` and `aliases` on both and reads neither. The copy's
+ * `parseArgs` reads a flag's `default` and `aliases` and an argument's
+ * `default`, and refuses an argument that declares `aliases`, as its
+ * module note says.
+ */
+import type { Output } from '../../ports/index.js';
+import type { OutputMode } from '../config/config-sections.js';
+/** Everything a command runs with, built and frozen by `assembleContext`. */
+export interface CliContext {
+    /** The positional words of the line, in order. */
+    args: readonly string[];
+    /** The flags of the line by name: a value, `true` for a bare flag, `false` for `--no-<name>`. */
+    flags: Readonly<Record<string, string | boolean>>;
+    /** How the command's output is rendered: lines a person reads, NDJSON events, or one line per loop event. */
+    outputMode: OutputMode;
+    /** How much the command writes, from 0, the least, to 3. */
+    verbosity: 0 | 1 | 2 | 3;
+    /** Where the command writes, rendered in its `outputMode`. */
+    output: Output;
+    /** Aborted when the command is asked to stop. */
+    signal: AbortSignal;
+    /** The environment the context was built from, as a frozen copy. */
+    env: Readonly<Record<string, string | undefined>>;
+}
+/** A positional argument a command declares. */
+export interface ArgSpec {
+    /** What the argument is called. */
+    name: string;
+    /** What the argument holds, in a sentence. */
+    description: string;
+    /** The value's type. `parseArgs` converts no word to it: every word is a string. */
+    type: 'string' | 'boolean' | 'number';
+    /** Whether the command needs the argument. `parseArgs` refuses no line leaving it out. */
+    required?: boolean;
+    /** The word filled in when the line leaves the argument out, as a string. */
+    default?: string | boolean | number;
+    /** Refused by `parseArgs` when it names any: a positional word has no spelling but its place. */
+    aliases?: readonly string[];
+}
+/** A flag a command declares. */
+export interface FlagSpec {
+    /** The flag's name, which `CliContext.flags` is keyed by: `plan` for `--plan`. */
+    name: string;
+    /** What the flag does, in a sentence. */
+    description: string;
+    /** The value's type. `parseArgs` converts no value to it: a value is a string. */
+    type: 'string' | 'boolean' | 'number';
+    /** Whether the command needs the flag. `parseArgs` refuses no line leaving it out. */
+    required?: boolean;
+    /** The value filled in when the line gives the flag none: a number as its string, anything else as it is. */
+    default?: string | boolean | number;
+    /** Other spellings of the flag, each read as its name: `p` reads `-p` and `--p` as `plan`. */
+    aliases?: readonly string[];
+}
+/** A command: what it declares, and what runs. */
+export interface CliCommand {
+    /** The command's name. */
+    name: string;
+    /** What the command does. */
+    description: string;
+    /** The positional arguments, in the order the line gives them. */
+    args: ArgSpec[];
+    /** The flags. */
+    flags: FlagSpec[];
+    /** Runs the command with the context built for it. */
+    run: (context: CliContext) => Promise<void>;
+}

package/dist/core/command/version.d.ts

@@ -0,0 +1,4 @@
+/** The `version` of `package.json`, inlined into the build that reads it. */
+export declare const RAFA_VERSION: string;
+/** The line `rafa --version` prints and `rafa doctor` opens with: `rafa <version>`. */
+export declare function versionLine(): string;

package/dist/core/config/branch-template.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The glob matching every plan branch the template names: the template
+ * with `{stub}` replaced by `rafa-*`.
+ *
+ * @param template - A `naming.branch` template, such as `feat/{stub}`.
+ * @returns The glob, `feat/rafa-*` for the default template.
+ */
+export declare function branchGlob(template: string): string;
+/**
+ * The stub a branch carries under the template: what lies between the
+ * template's part before `{stub}` and its part after, when the branch
+ * opens with the one, closes with the other, and the stub between opens
+ * with `rafa-`.
+ *
+ * @param template - A `naming.branch` template, such as `feat/{stub}`.
+ * @param branch - A branch name, without `refs/heads/`.
+ * @returns The stub, `rafa-12-x` for `feat/rafa-12-x` under the default
+ *   template; null for a branch the template does not name.
+ */
+export declare function stubOfBranch(template: string, branch: string): string | null;