@open-tomato/rafa 0.44.0 → 0.46.0

package/dist/config-schema-tests.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The `tests` section of the config schema: the three settings the
+ * runner reads when it chooses which tests a recorded step runs, the one
+ * that names the contract tests, and the one that says whether a step reruns a newly red file alone, each one's
+ * field, its default, its spec and its reader. {@link TESTS_SECTION}
+ * hands them to core as one `ConfigSection`, package `tests`, and the
+ * `declare module` below adds {@link TestsSettings} to `RafaConfig`.
+ * {@link TestsShape} holds the keys a file writes, which
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file shape.
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
+ * spread the objects below last, after the `task` section, so the order
+ * settings are reported in holds the section.
+ *
+ * The section has its own module, as `config-schema-release.ts` does,
+ * because `config-sections.ts` stood at 699 lines, measured with
+ * `wc -l`, when these keys were added, and takes nothing new under the
+ * 800-line cap of `context/source.md`. The one reader the four glob keys
+ * share, {@link globList}, is a rule about a VALUE and sits here all the
+ * same, for that reason. `config-registry.ts` imports this file to spread
+ * it; a caller reads these settings off the resolved `RafaConfig`.
+ *
+ * ## The four glob keys
+ *
+ * `.rafa/plans/PLAN-rafa-479-loop-task-sessions-run.md` names the first
+ * two, the plan `rafa-683-content-sweeps-lint-run` the third, and the
+ * plan `rafa-807-spec-monorepo-bootstrap-turbo` the fourth. Each
+ * is a list of glob patterns, matched against a path relative to the
+ * repository root, the form `git diff --name-only` answers with:
+ *
+ *   - `tests.fullSuiteTriggers` names the files a task's diff runs the
+ *     full suite for, however the task line scoped its tests. Its
+ *     default is the five files whose change can move a test no import
+ *     graph reaches: `bunfig.toml`, `tsconfig*.json`, `package.json`,
+ *     `bun.lock` and `bun.lockb`. The plan adds the preload files
+ *     `bunfig.toml`'s `[test] preload` names, and those are NOT in this
+ *     default: a default is a value this module can spell, and which
+ *     files a project preloads is a question about its disk, answered
+ *     at run time by the reader of the scope. A project that sets this
+ *     key replaces the five, and the preload files are added to its own
+ *     list all the same.
+ *   - `tests.integration` names the test files a stage step runs beside
+ *     the tests under the folders the stage touched, because they drive
+ *     the whole CLI rather than one folder's modules. Its default is the
+ *     four spellings this repository gives such a file, in any folder:
+ *     a name ending `-integration.test.ts` or `.integration.test.ts`,
+ *     one holding `-spawned` and ending `.test.ts`, and one ending
+ *     `-cli.test.ts`. Each default pattern opens with the any-folder
+ *     prefix, two stars and a slash, which this note cannot spell
+ *     because it would close the comment.
+ *   - `tests.contract` names the contract tests. A contract test checks
+ *     the promise a package makes to others, with a fixture, and runs in
+ *     that package's own `test` task in ring 1 of CI, where a use-case
+ *     test matching `tests.integration` runs in ring 0's full run. Its
+ *     default is one pattern: a name ending `.contract.test.ts`, in any
+ *     folder, under the same any-folder prefix. No step reads the key
+ *     yet; its readers come with the CI rings that run each kind.
+ *   - `tests.alwaysRun` names the test files a task's scoped run takes
+ *     beside the ones `bun test --changed=<base>` selects. A content
+ *     sweep, a test that imports no project file and reads the tree at
+ *     run time, sits outside every import graph, so no changed file ever
+ *     selects one. Its default is one pattern: any file under `src/`
+ *     whose name ends `.sweep.test.ts`, the suffix this repository gives
+ *     a content sweep. A pattern that matches no file today is accepted,
+ *     since the sweeps it names may not have been written yet. The task
+ *     prompt reads it (`start/task-gate-lines.ts`), naming the files it
+ *     resolves to, and so does the runner's task step
+ *     (`start/task-always-run.ts`), running those files beside a
+ *     `module` or `affected` scope.
+ *
+ * An empty list is a value every glob key accepts, and means what it says:
+ * no file triggers the full suite beyond the preload files, a stage
+ * runs no integration tier, no file is a contract test, or a task runs no sweep beside its scoped
+ * tests. It is not read as "the default", since a list written `[]`
+ * has been said.
+ *
+ * ## The reader
+ *
+ * {@link globList} takes a list whose every entry is a non-empty
+ * string, as `cleanup.keep` does, and refuses one more entry `text`
+ * would take: an absolute path. The paths a pattern is matched against
+ * are relative to the repository root, so a pattern opening with `/`
+ * matches nothing, and a trigger that can never fire is the silent
+ * failure this key exists to prevent. No other check is made on the
+ * pattern: `Bun.Glob` builds a matcher from any string, so there is no
+ * malformed glob to refuse.
+ *
+ * ## The switch
+ *
+ * `tests.retakeRedAlone` says whether a task, stage or pre-wrap-up step
+ * that reads new failures reruns each newly red test file alone, once,
+ * before it settles (`start/suite-retake-alone.ts`). A file green alone
+ * was red only in the step's own file order, by state another test file
+ * left in the shared process, and is reported as such rather than handed
+ * to a repair task (issue 926: one run of 2026-10-10 inserted five repair
+ * tasks for a file each repair session found green). Two readings:
+ *
+ *   - It defaults to `true`. The retake costs one `bun test <file>` per
+ *     newly red file and only on a step already red, and what it saves is
+ *     a repair session per order-dependent file. `false` switches the
+ *     retake off and nothing else: every new failure blocks, and no file
+ *     is run a second time. The error lines a step keeps for each failed
+ *     case (`suite/failure-lines.ts`), on its record, in its output file
+ *     and in its blocker, are kept either way; no key turns them off.
+ *   - It is read through `flag` (`config-sections.ts`), a YAML boolean
+ *     and nothing spelled like one, as `status.notice` is.
+ *
+ * No key here is a `CommandLineSetting`: four are lists, which the
+ * command line has no spelling for, as `config-schema.ts` says, and the
+ * switch is none for the reason the `pr` section gives
+ * (`config-schema-readings.ts`): a global flag nobody typed would be one
+ * this module invented.
+ */
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { Reader } from '@open-tomato/rafa/core/config/sections';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `tests` section's fields, added to core's. */
+    interface RafaConfig extends TestsSettings {
+    }
+}
+/** The `tests` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
+export interface TestsShape {
+    readonly tests: {
+        readonly fullSuiteTriggers: readonly string[];
+        readonly integration: readonly string[];
+        readonly contract: readonly string[];
+        readonly alwaysRun: readonly string[];
+        readonly retakeRedAlone: boolean;
+    };
+}
+/** The `tests` section's settings, resolved. */
+export interface TestsSettings {
+    /**
+     * Globs naming the files whose change runs the full suite at a task
+     * step, beside `bunfig.toml`'s preload files. `tests.fullSuiteTriggers`.
+     */
+    testsFullSuiteTriggers: readonly string[];
+    /**
+     * Globs naming the test files every stage step runs.
+     * `tests.integration`.
+     */
+    testsIntegration: readonly string[];
+    /**
+     * Globs naming the contract tests, each checking the promise a package
+     * makes to others. `tests.contract`.
+     */
+    testsContract: readonly string[];
+    /**
+     * Globs naming the test files a task's scoped run takes beside the
+     * changed-file selection. `tests.alwaysRun`.
+     */
+    testsAlwaysRun: readonly string[];
+    /**
+     * Whether a step reading new failures reruns each newly red test file
+     * alone, once, before it settles. `tests.retakeRedAlone`.
+     */
+    testsRetakeRedAlone: boolean;
+}
+/**
+ * The reader the four glob settings share: a list of glob patterns, each
+ * relative to the repository root, answered frozen in the order written.
+ */
+export declare const globList: Reader<readonly string[]>;
+/** What every `tests` setting resolves to when no layer names it. */
+export declare const TESTS_DEFAULTS: Readonly<TestsSettings>;
+/** The `tests` section's setting specs, in the order problems are reported. */
+export declare const TESTS_SETTINGS: {
+    readonly [K in keyof TestsSettings]: SettingSpec<K>;
+};
+/** The `tests` section: the five `tests` keys, with their defaults and no check. */
+export declare const TESTS_SECTION: ConfigSection;

package/dist/config-schema-triage.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The `triage` section of the config schema: the five settings triage
+ * reads when it looks for the nearest open bug a report repeats and ranks
+ * the ones a new bug lists, each one's field, its default, its spec and
+ * its reader.
+ * {@link TRIAGE_SECTION} hands them to core as one `ConfigSection`,
+ * package `triage`, and the `declare module` below adds
+ * {@link TriageSettings} to `RafaConfig`.
+ * {@link TriageShape} holds the keys a file writes, which
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file shape.
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
+ * spread the objects below right after the `claims` section.
+ *
+ * The section has its own module, as `config-schema-tests.ts` and
+ * `config-schema-wrap-up.ts` do, because `config-schema.ts` stood at 592
+ * lines and `config-sections.ts` at 705, measured with `wc -l`, when
+ * these keys were added: the schema module's own note asks a new
+ * section for a sibling, and the readers are rules about a VALUE that
+ * only these keys read, so they sit here beside them. Only
+ * `config-registry.ts` imports this file; a caller reads the settings off
+ * the resolved `RafaConfig`.
+ *
+ * ## The five keys
+ *
+ * Step 3 of a public bug's lookup (`triage/triage.ts`) scores the
+ * report against each open bug by Jaccard similarity of their word
+ * sets, after the exact-key lookups have missed:
+ *
+ *   - `triage.similarity.threshold` is the least score at which the
+ *     nearest open bug is taken for the same bug and commented on. It
+ *     defaults to `0.3` and accepts a number above 0 and at most 1: a
+ *     Jaccard score lies in 0..1, so a threshold above 1 could never be
+ *     met, and one of 0 or below would match every open bug, words
+ *     shared or not. `false` turns step 3 off, so triage files with the
+ *     exact-key lookups alone. `true` is refused: it names no score, and
+ *     reading it as the default would be a choice nobody wrote.
+ *   - `triage.similarity.candidates` is how many of the nearest open
+ *     bugs a new bug's `Possible duplicates` section lists. It defaults
+ *     to `3` and accepts a whole number from 1 to 10; the cap keeps that
+ *     section short enough to read. It takes no `false`: turning step 3
+ *     off is the threshold's to say.
+ *   - `triage.similarity.weights.causeLeaf`, `.causeFamily` and
+ *     `.boundary` are the bonuses `rankedCandidates`
+ *     (`triage/similarity.ts`) adds to an open bug's word score when it
+ *     shares the new bug's cause code, only its cause family, or its
+ *     module and action; the sum is capped at 1 and orders the
+ *     `Possible duplicates` list, never the same-bug decision. They
+ *     default to `0.15`, `0.05` and `0.10` and each accepts a number from
+ *     0 to 1 inclusive: `0` turns its signal off, which is why it is
+ *     accepted here and refused by the threshold, and a bonus above 1
+ *     could only ever hit the cap. `true` and `false` are refused, as the
+ *     threshold refuses `true`: `0` already says off.
+ *
+ * A quoted number is refused, as every other reader refuses a string
+ * spelled like its type. No key is a `CommandLineSetting`: the
+ * command line has no spelling for `false` or a number this module
+ * would not have to invent.
+ */
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { Reader } from '@open-tomato/rafa/core/config/sections';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `triage` section's fields, added to core's. */
+    interface RafaConfig extends TriageSettings {
+    }
+}
+/** The `triage` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
+export interface TriageShape {
+    readonly triage: {
+        readonly similarity: {
+            readonly threshold: SimilarityThreshold;
+            readonly candidates: number;
+            readonly weights: {
+                readonly causeLeaf: number;
+                readonly causeFamily: number;
+                readonly boundary: number;
+            };
+        };
+    };
+}
+/** The most `triage.similarity.threshold` accepts. */
+export declare const SIMILARITY_THRESHOLD_MAX = 1;
+/** The least a `triage.similarity.weights.*` bonus accepts; `0` turns its signal off. */
+export declare const SIMILARITY_WEIGHT_MIN = 0;
+/** The most a `triage.similarity.weights.*` bonus accepts. */
+export declare const SIMILARITY_WEIGHT_MAX = 1;
+/** The fewest nearest issues `triage.similarity.candidates` accepts. */
+export declare const SIMILARITY_CANDIDATES_MIN = 1;
+/** The most nearest issues `triage.similarity.candidates` accepts. */
+export declare const SIMILARITY_CANDIDATES_MAX = 10;
+/**
+ * The least Jaccard score at which the nearest open bug is taken for the
+ * report's, or `false` with the similarity step turned off.
+ */
+export type SimilarityThreshold = number | false;
+/** The `triage` section's settings, resolved. */
+export interface TriageSettings {
+    /**
+     * The least score at which the nearest open bug is commented on, or
+     * `false` to skip the similarity step. `triage.similarity.threshold`.
+     */
+    triageSimilarityThreshold: SimilarityThreshold;
+    /**
+     * How many nearest open bugs a new bug's `Possible duplicates`
+     * section lists. `triage.similarity.candidates`.
+     */
+    triageSimilarityCandidates: number;
+    /**
+     * The bonus an open bug with the same cause code earns in the
+     * `Possible duplicates` rank. `triage.similarity.weights.causeLeaf`.
+     */
+    triageSimilarityWeightsCauseLeaf: number;
+    /**
+     * The bonus an open bug with the same cause family and another leaf
+     * earns in that rank. `triage.similarity.weights.causeFamily`.
+     */
+    triageSimilarityWeightsCauseFamily: number;
+    /**
+     * The bonus an open bug with the same module and action earns in that
+     * rank. `triage.similarity.weights.boundary`.
+     */
+    triageSimilarityWeightsBoundary: number;
+}
+/**
+ * Accepts `false` or a number above 0 and at most 1, each as itself; the
+ * module note says why `0`, `true` and a quoted number are refused.
+ */
+export declare const similarityThreshold: Reader<SimilarityThreshold>;
+/** Accepts a whole number from 1 to 10 as itself. */
+export declare const similarityCandidates: Reader<number>;
+/**
+ * Accepts a number from 0 to 1 inclusive as itself; the module note says
+ * why `0` is accepted and `true`, `false` and a quoted number are refused.
+ */
+export declare const similarityWeight: Reader<number>;
+/** What every `triage` setting resolves to when no layer names it. */
+export declare const TRIAGE_DEFAULTS: Readonly<TriageSettings>;
+/** The `triage` section's setting specs, in the order problems are reported. */
+export declare const TRIAGE_SETTINGS: {
+    readonly [K in keyof TriageSettings]: SettingSpec<K>;
+};
+/** The `triage` section: the five `triage` keys, with their defaults and no check. */
+export declare const TRIAGE_SECTION: ConfigSection;

package/dist/config-schema-wrap-up.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The `loop.wrapUp` section of the config schema: the one setting the
+ * wrap-up reads when its session ends without an open pull request, with
+ * its field, its default, its spec and its reader.
+ * {@link WRAP_UP_SECTION} hands it to core as one `ConfigSection`,
+ * package `wrap-up`, and the `declare module` below adds
+ * {@link WrapUpSettings} to `RafaConfig`.
+ * {@link WrapUpShape} holds its part of the shared `loop` namespace,
+ * which `src/config/shape.ts` composes into `LoopShape` of `ConfigShape`,
+ * the nested file shape.
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
+ * spread the objects below right after `loop.worktreeDir`, so the order
+ * settings are reported in holds the `loop` section together.
+ *
+ * The section has its own module, as `config-schema-release.ts` and
+ * `config-schema-tests.ts` do, because `config-schema.ts` stood at 578
+ * lines and `config-sections.ts` at 642, measured with `wc -l`, when
+ * this key was added: the schema module's own note asks a new section
+ * for a sibling, and the reader is a rule about a VALUE that only this
+ * key reads, so it sits here beside it. `config-registry.ts` imports this
+ * file to spread it; a caller reads the setting off the resolved
+ * `RafaConfig`.
+ *
+ * ## The key
+ *
+ * `.rafa/specs/rafa-579-loop-run-ends-delivered.md` has a loop run end
+ * with its pull request open. When the wrap-up session ends and no pull
+ * request is open for the branch, the runner spawns another wrap-up
+ * session that is told the pull request is missing, and
+ * `loop.wrapUp.retries` is how many of those it spawns before opening
+ * the pull request itself:
+ *
+ *   - It defaults to `1`: one retry session, which costs one more
+ *     session's spend on the run that needed it and nothing on a run
+ *     whose first wrap-up opened the pull request.
+ *   - It accepts a whole number from 1 to 3. Each retry is a full
+ *     session, so the cap of 3 bounds what a run whose wrap-up keeps
+ *     missing the pull request can spend before the runner opens it.
+ *   - `false` means no retry: the runner goes straight to opening the
+ *     pull request itself. It is spelled `false` and not `0`, so a
+ *     number always names sessions that run; `0` is refused, as are a
+ *     negative number, a fraction and anything above 3. `true` is
+ *     refused too: it names no count, and reading it as the default
+ *     would be a choice nobody wrote.
+ *
+ * A quoted `"2"` is refused, as every other reader refuses a string
+ * spelled like its type. The key is not a `CommandLineSetting`: the
+ * command line has no spelling for `false` or a number this module
+ * would not have to invent.
+ */
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { Reader } from '@open-tomato/rafa/core/config/sections';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `wrap-up` section's fields, added to core's. */
+    interface RafaConfig extends WrapUpSettings {
+    }
+}
+/**
+ * `loop.wrapUp.retries`, the section's part of the shared `loop`
+ * namespace; `src/config/shape.ts` composes it into `LoopShape`.
+ */
+export interface WrapUpShape {
+    readonly wrapUp: {
+        readonly retries: WrapUpRetries;
+    };
+}
+/** The fewest retry sessions `loop.wrapUp.retries` accepts as a number. */
+export declare const WRAP_UP_RETRIES_MIN = 1;
+/** The most retry sessions `loop.wrapUp.retries` accepts. */
+export declare const WRAP_UP_RETRIES_MAX = 3;
+/**
+ * How many retry wrap-up sessions a run spawns when its wrap-up ends
+ * with no pull request open, or `false` for none.
+ */
+export type WrapUpRetries = number | false;
+/** The `loop.wrapUp` section's settings, resolved. */
+export interface WrapUpSettings {
+    /**
+     * The retry wrap-up sessions spawned before the runner opens the pull
+     * request itself, or `false` for none. `loop.wrapUp.retries`.
+     */
+    loopWrapUpRetries: WrapUpRetries;
+}
+/**
+ * Accepts `false` or a whole number from 1 to 3, each as itself; the
+ * module note says why `0`, `true` and a quoted number are refused.
+ */
+export declare const wrapUpRetries: Reader<WrapUpRetries>;
+/** What the `loop.wrapUp` setting resolves to when no layer names it. */
+export declare const WRAP_UP_DEFAULTS: Readonly<WrapUpSettings>;
+/** The `loop.wrapUp` section's setting spec. */
+export declare const WRAP_UP_SETTINGS: {
+    readonly [K in keyof WrapUpSettings]: SettingSpec<K>;
+};
+/** The `wrap-up` section: `loop.wrapUp.retries`, with their defaults and no check. */
+export declare const WRAP_UP_SECTION: ConfigSection;

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

@@ -0,0 +1,228 @@
+/**
+ * The command rafa's dispatcher routes to: `RafaCommand`, the context it
+ * runs with, and `CommandExit`, the one way it refuses.
+ *
+ * The CLI surface spec declares `RafaCommand` as a superset of `cli-core`'s
+ * `CliCommand`, so a `cli-core` command still loads. The superset is spelled
+ * here over the copy in `types.ts` beside this file.
+ *
+ * ## Routing keys
+ *
+ * `subject` and `action` are the words a line routes by: `rafa loop start`
+ * runs the command whose subject is `loop` and whose action is `start`.
+ * A command whose action is its subject is a top-level command, reached
+ * by its one word: `status`, with subject and action both `status`. That is
+ * open-tomato's rule for a single-token verb, which it registers with
+ * tool and command equal. `name` is for display, and routes nothing.
+ *
+ * ## The context
+ *
+ * {@link RafaContext} is `CliContext` plus `argv`, the words of the line
+ * after the last word the dispatcher routed by, as they were typed. The
+ * phase 0 commands read their own flags, so a wrapper hands `argv` to
+ * the parser it already has. `args` and `flags` are the rest of the
+ * line read against the command's own `args` and `flags`, flags typed
+ * ahead of the subject included.
+ *
+ * It also carries `registry`, the registry the dispatcher routed the line
+ * through, every module mounted for the invocation included. `describe`
+ * reads it, so the roster it gives is the dispatcher's own and never a
+ * second one.
+ *
+ * And it carries `project`, the project the command runs in as
+ * `resolveScope` answers it (`src/project/scope.ts`): its root, the home,
+ * and both scopes' paths. A command runs inside a project unless it
+ * declares `needsProject: false`. The dispatcher resolves the project
+ * before any other command runs, and runs none outside a project, so
+ * such a command's `project` is never null. For a command declaring
+ * `needsProject: false`, as `module exec`, `init` and `describe` do, it resolves
+ * nothing, and `project` is null inside a project as outside one.
+ *
+ * `run` takes a `RafaContext`, where `CliCommand.run` takes a
+ * `CliContext`, so the interface extends `CliCommand` without its `run`.
+ * A `RafaContext` is a `CliContext`, so a `run` written against
+ * `CliContext` is assignable to this one.
+ *
+ * ## Refusing
+ *
+ * A command refuses by throwing {@link CommandExit} with an exit code. The
+ * dispatcher is the only place that turns one into the process's exit
+ * code and the invocation's terminal event. A `process.exitCode` a
+ * command sets is not read, and a command setting one and returning is
+ * a success to the dispatcher.
+ *
+ * ## The shape check
+ *
+ * {@link commandProblem} answers what keeps a value from being a
+ * `RafaCommand`, for a roster the type checker never saw: a module's
+ * command entry is imported at run time. It checks the shape and not
+ * the content, so an empty `summary` or an empty `examples` list passes.
+ * The registry refuses a core command it answers for, and the module
+ * loader skips the file of a module command it answers for.
+ *
+ * `spends` is checked last, by `spendsProblem` (`spends.ts` beside this file),
+ * whose sentence names the field inside it: `spends.flag is "resolve",
+ * expected a flag as typed, starting with --`. A module entry declaring a
+ * malformed `spends` is therefore skipped like any other bad shape.
+ *
+ * ## Dangerous phrases
+ *
+ * `dangerous` maps a `dangerous.*` key to the phrase naming what the
+ * command does under it: `{ 'dangerous.acceptVersionCollision': 'a
+ * release guard reading collision merges anyway' }`. The dispatcher
+ * runs the command inside `runWithDangerousPhrases`
+ * (`packages/rafa/src/core/config/dangerous.ts`) with it, so a pass line the loader
+ * writes for a declared key during the run ends with `; <phrase>`. The
+ * shape check refuses a key not opening with `dangerous.` and a phrase
+ * that is not a non-empty string.
+ *
+ * ## Deprecated flags
+ *
+ * A flag a command declares is a {@link RafaFlagSpec}: a `FlagSpec` that
+ * may carry `deprecated`, naming the spelling to type instead. The
+ * dispatcher reads such a flag, typed bare, as that spelling and writes
+ * one deprecation line (`src/cli/dispatch.ts`), so
+ * `rafa effort report --json` runs as `rafa effort report --output=json`.
+ * The field is declared here rather than on `FlagSpec`, so the copy of
+ * `cli-core`'s contracts in `types.ts` keeps the source's shape.
+ */
+import type { CommandRegistry } from './registry-types.js';
+import type { CommandSpend } from './spends.js';
+import type { CliCommand, CliContext, FlagSpec } from './types.js';
+import type { DangerousPhrases } from '../config/dangerous.js';
+import type { ProjectFound } from '../config/scope.js';
+/** What an action can render: text a person reads, NDJSON events, one line per loop event, or the TUI. */
+export declare const COMMAND_OUTPUTS: readonly ["text", "json", "events", "tui"];
+/** One of the four renderings an action declares. */
+export type CommandOutput = (typeof COMMAND_OUTPUTS)[number];
+/** One example a command's help lists. */
+export interface CommandExample {
+    /** The line as a person types it: `rafa loop start --plan=PLAN-x.md`. */
+    readonly cmd: string;
+    /** What the line does, in a sentence. */
+    readonly note: string;
+}
+/** Why a command is deprecated, and what to type instead. */
+export interface CommandDeprecation {
+    /** The version the command was deprecated in. */
+    readonly since: string;
+    /** The spelling to use instead, after `rafa`: `loop start`. */
+    readonly use: string;
+}
+/** What a deprecated flag is read as, which is also what to type instead. */
+export interface FlagDeprecation {
+    /**
+     * The spelling to type instead, `--output=json`: the words, joined by
+     * one space, the dispatcher reads the flag as.
+     */
+    readonly use: string;
+}
+/** A flag a rafa command declares: a `FlagSpec`, which may be a deprecated spelling. */
+export interface RafaFlagSpec extends FlagSpec {
+    /** Set when the flag is a deprecated spelling; see the module note. */
+    readonly deprecated?: FlagDeprecation;
+}
+/** Everything a rafa command runs with. */
+export interface RafaContext extends CliContext {
+    /** The words after the last word the line was routed by, as typed. */
+    readonly argv: readonly string[];
+    /** The registry the line was routed through, every module mounted for the invocation included. */
+    readonly registry: CommandRegistry;
+    /** The project the command runs in, or null for a command declaring `needsProject: false`; see the module note. */
+    readonly project: ProjectFound | null;
+}
+/** A command the dispatcher routes to by its subject and action. */
+export interface RafaCommand extends Omit<CliCommand, 'run'> {
+    /** The first routing word: `loop` in `rafa loop start`. */
+    readonly subject: string;
+    /** The second routing word: `start`. Equal to `subject` for a top-level command. */
+    readonly action: string;
+    /** One line for the subject's roster. `description` may be longer. */
+    readonly summary: string;
+    /** The flags, any of them a deprecated spelling. */
+    flags: RafaFlagSpec[];
+    /** The examples help lists. */
+    readonly examples: readonly CommandExample[];
+    /**
+     * Whole other spellings of the command, each printing one deprecation
+     * line when typed, `start` for `loop start`, unless it is also one of
+     * {@link RafaCommand.lastingAliases}. Routed for a core command only; a
+     * module's command is reached through an `exec` action alone.
+     */
+    readonly aliases?: readonly string[];
+    /**
+     * The aliases, each also listed in `aliases`, kept for good rather than
+     * for one release: typed, they print no deprecation line. `epic` for
+     * `epic show`, which `rafa epics` reaches through the subject's plural.
+     */
+    readonly lastingAliases?: readonly string[];
+    /** What the action can render. */
+    readonly outputs: readonly CommandOutput[];
+    /** Set when the command itself is deprecated; typing it prints one deprecation line. */
+    readonly deprecated?: CommandDeprecation;
+    /** Out of every roster, and still dispatched. */
+    readonly hidden?: boolean;
+    /**
+     * The action delegates to a module: the word after it names a module
+     * mounted as `module/<name>`, and the word after that one of the
+     * module's actions.
+     */
+    readonly exec?: true;
+    /**
+     * False for a command that runs outside a project too, which the
+     * dispatcher resolves no project for: `module exec`, `init` and
+     * `describe`. Absent,
+     * the command runs inside a project; see the module note.
+     */
+    readonly needsProject?: boolean;
+    /**
+     * Whether running the command can start a Claude Code session, and
+     * under what condition; absent, it spends nothing. See `spends.ts`
+     * beside this file.
+     */
+    readonly spends?: CommandSpend;
+    /**
+     * What the command does under each `dangerous.*` key it declares, as a
+     * phrase the loader's pass line for that key ends with after `; `.
+     * The dispatcher sets it for the command's run; see "Dangerous
+     * phrases" in the module note.
+     */
+    readonly dangerous?: DangerousPhrases;
+    /** Runs the command. Throws {@link CommandExit} to refuse. */
+    readonly run: (context: RafaContext) => Promise<void>;
+}
+/**
+ * Thrown by a command to end its invocation with an exit code: nonzero to
+ * refuse, 0 to stop early as a success.
+ *
+ * The message, when it is not empty, is what the dispatcher tells the
+ * reader: on stderr in text mode, in the terminal event in json mode.
+ *
+ * `options` goes to `Error` as it is, so a `cause` given there is kept on
+ * the refusal: `new CommandExit(3, 'refused', { cause: error })` reads the
+ * error back as `exit.cause`.
+ */
+export declare class CommandExit extends Error {
+    /** The exit code the invocation ends with, from 0 to 255. */
+    readonly exitCode: number;
+    /**
+     * Throws a `TypeError` when `exitCode` is not a whole number from 0 to 255,
+     * whatever `options` holds.
+     */
+    constructor(exitCode: number, message?: string, options?: ErrorOptions);
+}
+/**
+ * True when a value is a word a line can route by: no space, no slash and
+ * no leading dash. The slash is kept for the `module/<name>` mount keys,
+ * so no subject is spelled as one.
+ */
+export declare function isRoutingWord(value: unknown): value is string;
+/**
+ * What keeps `value` from being a `RafaCommand`, as a sentence naming the
+ * command when it can, or null when nothing does. See the module note.
+ */
+export declare function commandProblem(value: unknown): string | null;
+/** True when a command is top-level: its action is its subject. */
+export declare function isTopLevel(command: Pick<RafaCommand, 'subject' | 'action'>): boolean;
+/** A command's canonical spelling after `rafa`: `loop start`, or `status` for a top-level command. */
+export declare function commandSpelling(command: Pick<RafaCommand, 'subject' | 'action'>): string;