@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/core/config/section.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The section contract: how a slice of the config schema is handed to
+ * core, and the registry core reads the merged slices from.
+ *
+ * A {@link ConfigSection} is one package's part of the schema: its
+ * `settings` (each setting's file key, reader and command-line flag, as
+ * a partial of the record of every setting, {@link SettingsRecord}), its
+ * `defaults` (a partial of {@link RafaConfig}), and the cross-key
+ * `checks` run over the resolved config. {@link registerConfigSections}
+ * merges sections into the active registry, which {@link activeSettings},
+ * {@link activeDefaults} and {@link activeChecks} answer, and the key
+ * indexes below are read off. Core names no section here: the list of
+ * sections lives outside `packages/rafa/src/core/`, in `src/config-registry.ts`, the
+ * module that calls {@link registerConfigSections}.
+ *
+ * This file imports types alone, so it loads first in any order and can
+ * be imported by value from the loader and from every section file
+ * without closing a runtime cycle.
+ *
+ * ## The refusals
+ *
+ * A registration that breaks one of four rules throws a
+ * {@link ConfigSectionError} listing every problem it found, one
+ * sentence each, and leaves the active registry as it was:
+ *
+ *   - A setting name registered by one section and again by another, in
+ *     this call or an earlier one. The sentence names both packages, the
+ *     one holding the name first.
+ *   - A file key defined by one section and again by another under a
+ *     different setting name. Two settings read off one key would
+ *     answer one value under two names, so the sentence names both
+ *     packages and both setting names, the one holding the key first.
+ *   - A file key opening with `dangerous.` defined by one section and
+ *     again by another under the same setting name. A `dangerous.*` key
+ *     is a person's consent to a risk, so a second package defining it
+ *     could widen what that consent was given for; the sentence names
+ *     both packages, and the setting-name sentence is read beside it.
+ *     Any other key redefined under the same name reads the setting-name
+ *     sentence alone.
+ *   - A {@link RafaConfig} field no section defines: a default given for
+ *     a field no registered section has a setting for, or a setting no
+ *     registered section gives a default for. The sentence names the
+ *     package that gave the half it has. Types are erased at runtime, so
+ *     a field declared on {@link RafaConfig} that no section mentions at
+ *     all is out of this module's reach; the module that lists the
+ *     sections is where a complete set is held.
+ *
+ * The completeness rule reads the registry as it would stand after the
+ * call, so a section whose setting and default come in two calls is
+ * refused at the first. A section's package must be a non-empty string,
+ * since every refusal names one.
+ *
+ * The key rules compare one section with the sections before it, in
+ * this call or an earlier one; two setting names one section gives the
+ * same key are not compared with each other.
+ *
+ * ## A registry is a value
+ *
+ * {@link mergeConfigSections} answers a new {@link ConfigSectionRegistry}
+ * and leaves the one it was handed unchanged; each section is copied and
+ * frozen as it is accepted, so editing a section object afterwards
+ * changes nothing registered. The active registry is the one
+ * module-level value: {@link registerConfigSections} replaces it with a
+ * merge and answers the one it replaced, and
+ * {@link restoreConfigSections} puts one back. Bun runs every test file
+ * in one process, so a case that registers puts the previous registry
+ * back in a `finally`, or every file bun runs later reads its sections.
+ * {@link EMPTY_CONFIG_REGISTRY} is the registry before any registration.
+ *
+ * ## The key indexes
+ *
+ * `config.ts` sorts a file's keys through three indexes of the active
+ * registry's settings: {@link activeSettingByKey}, the setting each
+ * dotted file key names; {@link activeSectionPaths}, every dotted prefix
+ * a setting sits under, which are the sections a file may open; and
+ * {@link activeKnownKeysAbove}, the keys a warning about an unknown key
+ * lists. Each is built on first read and kept per registry, so a
+ * registration or a restore is read at once and a registry is indexed
+ * once. Keys are looked up in a `Map` and a `Set`, never with `in` or an
+ * object index: `Bun.YAML.parse` returns a key spelled `constructor`,
+ * `toString` or `__proto__` as an ordinary own key, and an object lookup
+ * would match it against `Object.prototype` instead.
+ *
+ * The indexes follow registration order: the keys under a path are
+ * listed in the order their settings were registered. The registry
+ * registers its sections cut into the order the schema has always
+ * reported problems in, so a warning lists the keys it always listed;
+ * `src/config-registry.test.ts` holds the indexes to the registry's own.
+ *
+ * ## The load hook
+ *
+ * A setting core resolves can be read by a module outside `packages/rafa/src/core/`
+ * that core must not import: the logger's settings are read through
+ * `loggerSettingsOf` in `src/config-schema-logger.ts`. So the module that
+ * lists the sections also hands core one {@link ConfigLoadHook} with
+ * {@link setConfigLoadHook}, and `loadConfig` (`config-load.ts`) calls
+ * {@link activeConfigLoadHook} with every config it resolves, before it
+ * prints the config's warnings. The hook is a module-level value of its
+ * own, beside the registry rather than in it: restoring a registry
+ * leaves the hook as it was, and a case that sets one puts the previous
+ * hook back in a `finally`, as a case that registers does.
+ */
+import type { ConfigSetting, RafaConfig, SettingSpec } from './config-schema.js';
+import type { ConfigSource } from './config.js';
+/** Every setting's spec, by name: the record a section hands a part of. */
+export type SettingsRecord = {
+    readonly [K in ConfigSetting]: SettingSpec<K>;
+};
+/** What a section's check reads: the resolved values, their layers and the files read. */
+export interface ConfigCheckInput {
+    /** The value each setting resolved to. */
+    readonly config: Readonly<RafaConfig>;
+    /** The layer that answered each setting. */
+    readonly sources: Readonly<Record<ConfigSetting, ConfigSource>>;
+    /** The project's file consulted, or null when there was none. */
+    readonly path: string | null;
+    /** The user scope's file consulted, or null when there was none. */
+    readonly userPath: string | null;
+}
+/**
+ * A cross-key refusal: the problems the resolved config holds, one
+ * sentence each, or an empty list when it holds none.
+ */
+export type ConfigCheck = (input: ConfigCheckInput) => readonly string[];
+/** One package's slice of the config schema. */
+export interface ConfigSection {
+    /** The package the section belongs to, named by every refusal. */
+    readonly package: string;
+    /** The specs of the settings the section defines. */
+    readonly settings: Partial<SettingsRecord>;
+    /** The default of each setting the section defines. */
+    readonly defaults: Partial<RafaConfig>;
+    /** The cross-key refusals run over the resolved config. */
+    readonly checks?: readonly ConfigCheck[];
+}
+/** The sections merged so far, and what core reads off them. */
+export interface ConfigSectionRegistry {
+    /** Every section accepted, copied and frozen, in registration order. */
+    readonly sections: readonly ConfigSection[];
+    /** Every setting's spec, in registration order. */
+    readonly settings: Readonly<Partial<SettingsRecord>>;
+    /** Every setting's default. */
+    readonly defaults: Readonly<Partial<RafaConfig>>;
+    /** Every section's checks, in registration order. */
+    readonly checks: readonly ConfigCheck[];
+}
+/**
+ * A registration refused: a setting name defined twice, a file key two
+ * sections define under two setting names or a `dangerous.` key under
+ * one, a field no section defines, or a section with no package name.
+ */
+export declare class ConfigSectionError extends Error {
+    /** Every problem found, one sentence each. */
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/** The registry before any registration: no section, setting, default or check. */
+export declare const EMPTY_CONFIG_REGISTRY: ConfigSectionRegistry;
+/**
+ * A new registry holding `registry`'s sections and then `sections`, or a
+ * {@link ConfigSectionError} listing every problem found; see the module
+ * note. `registry` is left unchanged either way.
+ */
+export declare function mergeConfigSections(registry: ConfigSectionRegistry, sections: readonly ConfigSection[]): ConfigSectionRegistry;
+/**
+ * Merges `sections` into the active registry, or throws a
+ * {@link ConfigSectionError} and leaves it unchanged. Answers the
+ * registry it replaced, for {@link restoreConfigSections}.
+ */
+export declare function registerConfigSections(sections: readonly ConfigSection[]): ConfigSectionRegistry;
+/** Makes `registry` the active one: what {@link registerConfigSections} answered, or {@link EMPTY_CONFIG_REGISTRY}. */
+export declare function restoreConfigSections(registry: ConfigSectionRegistry): void;
+/** Every registered section, in registration order. */
+export declare function activeSections(): readonly ConfigSection[];
+/** Every registered setting's spec, in registration order. */
+export declare function activeSettings(): Readonly<Partial<SettingsRecord>>;
+/** Every registered setting's default. */
+export declare function activeDefaults(): Readonly<Partial<RafaConfig>>;
+/** Every registered section's checks, in registration order. */
+export declare function activeChecks(): readonly ConfigCheck[];
+/** Every registered setting's name, by the dotted key a file spells it with. */
+export declare function activeSettingByKey(): ReadonlyMap<string, ConfigSetting>;
+/** Every dotted prefix a registered setting sits under: the sections a file opens. */
+export declare function activeSectionPaths(): ReadonlySet<string>;
+/**
+ * The nearest path above `key` with registered keys, and those keys, in
+ * registration order. An item path such as `modules[0]` looks up the
+ * item keys of `modules`.
+ *
+ * @param key - A dotted key a file spelled, `modules[0].kind` included.
+ * @returns The path the keys sit under, `''` for the top, and the keys.
+ */
+export declare function activeKnownKeysAbove(key: string): [string, readonly string[]];
+/**
+ * What `loadConfig` hands every config it resolves to, before printing
+ * its warnings: the reading of settings a module outside `packages/rafa/src/core/`
+ * acts on. See the module note.
+ */
+export type ConfigLoadHook = (config: Readonly<RafaConfig>) => void;
+/**
+ * Makes `hook` the one `loadConfig` calls, or clears it with null.
+ * Answers the hook it replaced, for a caller to put back.
+ */
+export declare function setConfigLoadHook(hook: ConfigLoadHook | null): ConfigLoadHook | null;
+/** The hook `loadConfig` calls with every config it resolves, or null when none is set. */
+export declare function activeConfigLoadHook(): ConfigLoadHook | null;

package/dist/core/config/sections.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The barrel over the config's value readers: every name
+ * `config-sections.ts`, `config-readers.ts` and `branch-template.ts`
+ * export, and nothing else.
+ *
+ * A file outside `packages/rafa/src/core/` imports this file and never the three 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 three directly and never this file.
+ *
+ * ## Why the pair has a barrel of its own
+ *
+ * `packages/rafa/src/core/config/` has three barrels, all listed under `CORE_BARRELS`
+ * in `scripts/survey/core-moves.ts`. This one holds the leaf pair: the
+ * two files import each other one way (`config-readers.ts` reads
+ * `config-sections.ts`), `node:path`, and four modules that import none
+ * of the config back. The schema's section files (`src/config-schema-*.ts`)
+ * import the pair by value. While `config-merged.ts` imported them by
+ * value in turn, one barrel over the pair and the schema would have made
+ * every section file import a barrel that imports it back: a runtime
+ * cycle that fails as a `ReferenceError` at load, in one import order
+ * only. That file is retired, and measured since, no value import of a
+ * file behind `index.ts` reaches a section file, so that cycle is no
+ * longer what keeps the two barrels apart; they stay as the move left
+ * them, a name with one barrel to be learned from.
+ *
+ * `branch-template.ts` joined the pair with the readers of a branch name
+ * through the `naming.branch` template, `branchGlob` and `stubOfBranch`.
+ * It imports `config-readers.ts` alone, so it is a leaf as the pair is,
+ * and it sits beside `branchFromTemplate`, the writer it reads back.
+ *
+ * ## What it exports
+ *
+ * Each name is spelled, types apart from values, as the entries
+ * `src/index.ts` and `src/plan/index.ts` spell theirs.
+ *
+ * `sections.test.ts` holds the list to the three files: every name any
+ * of them exports is here once, as the same binding, and no name is here
+ * that none of them exports.
+ */
+export type { ReleasePublishMode, ReleaseSettleMode, ReleaseStrategy, ReleaseTagMode, VersionCollisionMode, } from './config-readers.js';
+export type { BoardRelationshipMode, ClaimsAhead, ClaimsStaleAfter, ClaudeSettingSource, ConfigExtra, ConfigVersion, DuplicatesLevel, InjectMode, LessonSwitch, Mapping, OutputMode, PrProvider, Reader, Reading, ReleaseEnabled, RouteTarget, SkillResolverName, StoreBackend, SyncStrategy, TierPin, TierSwitch, ValueAt, } from './config-sections.js';
+export { branchGlob, stubOfBranch } from './branch-template.js';
+export { BRANCH_STUB, branchFromTemplate, branchTemplate, DEFAULT_BRANCH_TEMPLATE, directory, fragmentsDirectory, isBranchTemplate, mapOf, RELEASE_PUBLISH_MODES, RELEASE_SETTLE_MODES, RELEASE_STRATEGIES, RELEASE_TAG_MODES, releaseFile, releasePublishMode, releaseSettleMode, releaseStrategy, releaseTagMode, routeTable, tierPins, trackerKind, VERSION_COLLISION_MODES, versionCollisionMode, } from './config-readers.js';
+export { below, BOARD_PROJECT_TEMPLATE_DEFAULT, BOARD_RELATIONSHIP_MODES, BUSY_TIMEOUT_MAX_MS, BUSY_TIMEOUT_MIN_MS, busyTimeoutMs, claimDurationHours, CLAIMS_AHEAD, CLAIMS_STALE_DISABLED, claimsAhead, claimsStaleAfter, CLAUDE_SETTING_SOURCES, confidence, CONFIDENCE_MAX, CONFIDENCE_MIN, CONFIG_VERSIONS, dayCount, describeValue, DUPLICATE_LEVELS, duplicatesLevel, flag, githubLogin, INJECT_MODES, isBusyTimeoutMs, isGitHubLogin, isMapping, issueNumber, LESSON_SWITCHES, lessonSwitch, listOf, mapReading, messageOf, oneOf, OUTPUT_MODES, PR_PROVIDERS, projectNumber, projectUrl, recurrenceCount, refused, refusedWith, RELEASE_AUTO, releaseEnabled, routeTarget, SKILL_RESOLVERS, skillResolverName, STORE_BACKENDS, subsetOf, SYNC_STRATEGIES, text, TIER_SWITCHES, tierPin, tierSwitch, usdAmount, } from './config-sections.js';

package/dist/core/config/standard-schema.d.ts

@@ -0,0 +1,27 @@
+import type { ConfigSection } from './section.js';
+import type { StandardSchemaV1 } from '@open-tomato/define-config';
+/** The vendor every schema built here names. */
+export declare const SCHEMA_VENDOR = "rafa";
+/**
+ * One pair of `createLoader`'s `schema` list: the key path of the
+ * subtree, outermost key first, and the schema that subtree must
+ * satisfy. The empty path names the whole value.
+ */
+export type ConfigSchemaSection = readonly [path: readonly string[], schema: StandardSchemaV1];
+/**
+ * A Standard Schema V1 schema whose `validate` runs `section`'s readers
+ * over the merged mapping and answers one issue per refusal at the
+ * refused key's path; see the module note.
+ *
+ * @param section - The section whose settings' readers judge the value.
+ * @returns A schema validating synchronously, vendor {@link SCHEMA_VENDOR}.
+ */
+export declare function schemaOf(section: ConfigSection): StandardSchemaV1;
+/**
+ * The `[path, schema]` list `createLoader`'s `schema` option takes: one
+ * pair per section, in the order given, each at the empty path.
+ *
+ * @param sections - The sections to validate the merged config with.
+ * @returns One frozen pair per section.
+ */
+export declare function schemaSectionsOf(sections: readonly ConfigSection[]): readonly ConfigSchemaSection[];

package/dist/core/git/commit.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Conventional type of a derived subject.
+ *
+ * Exactly the six {@link COMMIT_TYPE_RULES} can select, one of which
+ * is also {@link DEFAULT_COMMIT_TYPE}. `ci` and `perf` are legal in
+ * this repo's history and are absent here on purpose: no rule selects
+ * them, and a member the inference can never answer would be a column
+ * that always reads empty.
+ */
+export type CommitType = 'chore' | 'docs' | 'feat' | 'fix' | 'refactor' | 'test';
+/** What a task text is labelled when no rule matches it. */
+export declare const DEFAULT_COMMIT_TYPE: CommitType;
+/** One inference rule. The first whose pattern matches wins. */
+export interface CommitTypeRule {
+    /** Type this rule selects. */
+    type: CommitType;
+    /** Matched against the normalised, still-capitalised task text. */
+    pattern: RegExp;
+}
+/**
+ * The inference table, in priority order.
+ *
+ * It is a LABEL and not a classification: a wrong type costs a
+ * slightly-off word at the front of a subject whose body carries the
+ * whole task text, so the rules are kept few and readable rather
+ * than exhaustive. Two orderings in it are load-bearing.
+ *
+ * `test` runs first because a test task is the one shape whose verb
+ * is indistinguishable from a feature's — both begin `Add` — and only
+ * the noun separates them.
+ *
+ * `docs` runs before every verb rule because a documentation task's
+ * verb is whatever the edit happens to be (`Remove the four commit
+ * instructions from PROMPT.md`, `Rewrite the root AGENTS.md`,
+ * `Split packages/service/AGENTS.md`), while the thing it names is
+ * reliably a markdown file. The known cost of that order is a real
+ * code task that merely mentions a `.md` path, which is labelled
+ * `docs`; the body still says what it did.
+ */
+export declare const COMMIT_TYPE_RULES: readonly CommitTypeRule[];
+/**
+ * Longest subject this module will produce, including the type
+ * prefix. Git's own convention, and the ceiling GitHub renders
+ * without eliding.
+ */
+export declare const MAX_SUBJECT_LENGTH = 72;
+/** Description used when the task text carries no words at all. */
+export declare const FALLBACK_DESCRIPTION = "complete the scoped task";
+/**
+ * Characters of a failed git invocation kept on the result.
+ *
+ * A rejected hook can print a finding per staged file, and the loop
+ * echoes this to a console a human is scrolling. Truncation is
+ * marked, so a caller can tell a short message from a cut one.
+ */
+export declare const MAX_MESSAGE_CHARS = 4000;
+/** Collapses every whitespace run, newlines included, to one space. */
+export declare function normaliseTaskText(taskText: string): string;
+/**
+ * Picks the conventional type for a task text.
+ *
+ * Falls back to {@link DEFAULT_COMMIT_TYPE}, which is what an
+ * unrecognised verb gets rather than an exception: the loop must
+ * still be able to commit a task whose wording nobody anticipated.
+ */
+export declare function inferCommitType(taskText: string): CommitType;
+/**
+ * The task text up to its first comma, colon or parenthesis outside a
+ * code span, trailing whitespace dropped. The whole text when nothing
+ * ends it, and the empty string when the text opens on an ending.
+ *
+ * A subject quotes the first clause rather than the first 72
+ * characters because a width cut stops wherever the width falls: the
+ * 2026-09-14 cutover run committed a subject ending `(under 60 lines)
+ * stating that the loop`, mid-sentence, where the clause before the
+ * parenthesis was the whole of what it needed to say.
+ *
+ * The code-span exception is what makes the rule usable on a plan,
+ * which names identifiers in backticks: the comma in `run(a, b)` is
+ * part of a name, never the end of a clause. A backtick run that
+ * nothing closes opens no span, as CommonMark reads it, so it is
+ * literal text and the endings after it still count.
+ */
+export declare function firstClause(text: string): string;
+/** How a subject is built. */
+export interface SubjectOptions {
+    /** Conventional scope, rendered as `type(scope):`. Optional. */
+    scope?: string;
+    /** Cap including the prefix. Defaults to {@link MAX_SUBJECT_LENGTH}. */
+    maxLength?: number;
+}
+/** A derived subject and what deriving it decided. */
+export interface DerivedSubject {
+    /** The whole subject line, prefix included. */
+    subject: string;
+    /** Type the rules selected. */
+    type: CommitType;
+    /**
+     * True when the description was cut to fit the cap. Ending at the
+     * first clause is not a cut: a clause that fits answers false
+     * however much task text follows it.
+     */
+    truncated: boolean;
+}
+/**
+ * Derives a conventional-commit subject from a task's text.
+ *
+ * The description is the text's {@link firstClause}, cut at a word
+ * boundary when that clause alone is longer than the cap leaves room
+ * for. The TYPE is still inferred from the whole text, since a clause
+ * can end before the path or the noun the rules read. Whatever the
+ * subject leaves out, the body {@link buildCommitMessage} writes
+ * carries.
+ *
+ * Deterministic over its input: the same task text answers the same
+ * subject on every machine and every run, which is what lets the
+ * loop's commits be predicted by a test instead of inspected by a
+ * human.
+ */
+export declare function deriveCommitSubject(taskText: string, options?: SubjectOptions): DerivedSubject;
+/** A subject with the body that carries the whole task line. */
+export interface CommitMessage extends DerivedSubject {
+    /**
+     * The whole normalised task text, written whatever the subject kept
+     * of it. The empty string only for a task text with no words, which
+     * has no line to carry.
+     */
+    body: string;
+}
+/**
+ * Builds the message a task's commit is made with.
+ *
+ * The body is the whole task line on every commit. The subject holds
+ * one clause at most, so it seldom carries the sentence, and a body
+ * written only when the subject lost words would leave a reader of
+ * `git log` checking, commit by commit, which of the two holds it. The
+ * sentence is the only record of what the commit was asked to do, so
+ * it sits in the same place every time, even where that repeats a
+ * subject that already says all of it.
+ */
+export declare function buildCommitMessage(taskText: string, options?: SubjectOptions): CommitMessage;
+/** Argv that stages the whole worktree. */
+export declare function stageAllArgs(): string[];
+/**
+ * Argv that answers whether anything is staged: exit 0 for nothing,
+ * exit 1 for something. Exported so a caller reading the exit code
+ * can see which command produced it.
+ */
+export declare function stagedChangesArgs(): string[];
+/**
+ * Argv that makes the commit.
+ *
+ * `--cleanup=whitespace` is spelled out because strip DELETES every
+ * line beginning with `#`, and a task text is free to open on a shell
+ * comment or a markdown heading. It is NOT defending against git's
+ * default: for a `-m` message the default already behaves as
+ * whitespace, strip being the default only when the message is to be
+ * edited. What it defends against is a `commit.cleanup=strip`
+ * CONFIGURATION, which a machine's global git config is free to set
+ * (measured, git 2.50.1). Since {@link buildCommitMessage} collapses
+ * the task text to one line, the whole reachable difference is a task
+ * text that OPENS on a hash.
+ *
+ * Two `-m` arguments rather than one joined string: git inserts the
+ * blank line between subject and body itself, so the separator
+ * cannot drift.
+ */
+export declare function commitArgs(subject: string, body?: string): string[];
+/** Argv that reads the sha the commit just produced. */
+export declare function headShaArgs(): string[];
+/** One git invocation's result, as the runner reports it. */
+export interface GitRunResult {
+    /** Exit code, or null when the process was killed or never ran. */
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Runs git with the given argv. The seam every test drives. */
+export type GitRunner = (args: string[]) => GitRunResult;
+/** Which invocation a failure came from. */
+export type CommitStep = 'stage' | 'inspect' | 'commit';
+/** What one attempt did. */
+export type CommitOutcome = 'committed' | 'nothing-to-commit' | 'failed';
+/** The whole result of one attempt. */
+export interface CommitAttempt {
+    outcome: CommitOutcome;
+    /** Subject the commit was made with, derived either way. */
+    subject: string;
+    /** Sha of the new commit, or null when none was made. */
+    sha: string | null;
+    /** Invocation that failed, or null when none did. */
+    failedStep: CommitStep | null;
+    /** That invocation's exit code, or null. */
+    exitCode: number | null;
+    /** Its stderr and stdout, capped. Empty when nothing failed. */
+    message: string;
+}
+/** How an attempt is made. */
+export interface CommitOptions {
+    /** The task's text, which the subject is derived from. */
+    taskText: string;
+    /** Directory git runs in. Defaults to the current one. */
+    cwd?: string;
+    /** Conventional scope for the subject. Optional. */
+    scope?: string;
+    /** Cap for the subject. Defaults to {@link MAX_SUBJECT_LENGTH}. */
+    maxLength?: number;
+    /** Runner override. Defaults to a real `git` spawn in `cwd`. */
+    runGit?: GitRunner;
+}
+/**
+ * The default runner: a real `git` in `cwd`.
+ *
+ * `spawnSync` and not `execFileSync`, because two of the three
+ * invocations use their exit code as an ANSWER rather than as an
+ * error — `git diff --cached --quiet` exits 1 to say a commit is
+ * warranted, and a thrown exception there would turn the ordinary
+ * case into the failure path.
+ */
+export declare function spawnGit(cwd: string): GitRunner;
+/**
+ * Stages the worktree and commits it under a subject derived from
+ * the task's text.
+ *
+ * The three invocations run in a fixed order and each one's failure
+ * stops the attempt, so a caller never sees a `committed` result
+ * whose commit did not happen. The fourth read — the sha — is the
+ * exception: it runs AFTER the commit succeeded, so a failure there
+ * leaves the outcome `committed` with a null sha rather than
+ * retracting a commit that is already in the history.
+ */
+export declare function commitTaskWork(options: CommitOptions): CommitAttempt;

package/dist/core/git/gh-runner.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The seam every `gh` command goes through: the runner's type and what
+ * one command answers.
+ *
+ * Declared here, below the `github` tracker that spawns `gh`, so the
+ * adapter registry types its `gh` option without importing the tracker.
+ * `src/adapters/tracker/github.ts` imports both names from this file
+ * and re-exports them under the same names, so none of its importers
+ * changes.
+ */
+/** What one `gh` command answered. */
+export interface GhResult {
+    /** True when `gh` exited 0. */
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Runs `gh` with the arguments after its name. A command that fails,
+ * or could not be run, answers `ok` false rather than rejecting.
+ * `stdin`, when given, is the whole of what `gh` reads on its standard
+ * input; left out, `gh` reads a closed one.
+ */
+export type GhRunner = (args: readonly string[], stdin?: string) => Promise<GhResult>;

package/dist/core/git/git.d.ts

@@ -0,0 +1,22 @@
+/** What one git command answered. Never a throw; see the module note. */
+export interface GitResult {
+    /** True when git exited 0. */
+    readonly ok: boolean;
+    /** Its standard output, empty when it wrote none. */
+    readonly stdout: string;
+    /** Its standard error, empty when it wrote none. */
+    readonly stderr: string;
+}
+/** Runs git with the arguments after its name, in the directory it was made for. */
+export type GitRunner = (args: readonly string[]) => GitResult;
+/**
+ * Makes the runner that spawns `git` in `cwd`, under `LC_ALL=C`, with
+ * its output read as UTF-8. It never throws; see the module note.
+ */
+export declare function createGitRunner(cwd: string): GitRunner;
+/**
+ * What git said, its standard error first, since that is where it
+ * writes its refusals and its progress. Empty when it said nothing at
+ * all, which a successful `git switch` does.
+ */
+export declare function gitSaid(result: GitResult): string;

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

@@ -0,0 +1,85 @@
+/**
+ * The barrel over git: every name `git.ts`, `commit.ts` and
+ * `gh-runner.ts` export but one, and nothing else.
+ *
+ * A file outside `packages/rafa/src/core/` imports this file and never the two 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 two directly and never this file.
+ * None does today.
+ *
+ * ## What sits behind it
+ *
+ *   - `git.ts`: the runner that spawns `git` in a directory and answers
+ *     what git said instead of throwing, with the reader of that answer;
+ *   - `commit.ts`: staging and committing one task's work on the loop's
+ *     behalf, the subject derived from the task text, and the argv of
+ *     each step;
+ *   - `gh-runner.ts`: the type of the runner every `gh` command goes
+ *     through and what one command answers, types alone, imported by
+ *     nothing.
+ *
+ * ## The one name the two files share
+ *
+ * Both files export a type named `GitRunner`, and they are two types.
+ * `git.ts` declares `(args: readonly string[]) => GitResult`, the seam
+ * the callers of this barrel stub. `commit.ts` declares
+ * `(args: string[]) => GitRunResult`, the runner `CommitOptions.runGit`
+ * takes, which carries an exit status where the first carries `ok`.
+ *
+ * One barrel exports one binding under a name, so `GitRunner` here is
+ * the one `git.ts` declares, and the one of `commit.ts` is not exported
+ * from this file. The move changed paths and no logic, so neither type
+ * was renamed, and the barrel coins no second name for the one it
+ * leaves out.
+ *
+ * Measured when the two moved: 138 files under `src/` imported
+ * `git.ts`, and 107 of them took its `GitRunner`. Eleven imported
+ * `commit.ts`, and one of those took its `GitRunner`:
+ * `commit.test.ts`, which moved with it and imports it directly. A
+ * caller outside `packages/rafa/src/core/` that stubs the commit runner types it
+ * through `CommitOptions['runGit']`, and `GitRunResult` is exported for
+ * what it answers.
+ *
+ * ## Why one barrel can hold both
+ *
+ * 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. `commit.ts`
+ * imports `node:child_process` and no file. `git.ts` imports one file by
+ * value: `packages/rafa/src/core/config/config-sections.ts`, for `messageOf`. That
+ * file imports one file outside `packages/rafa/src/core/` by value,
+ * `packages/rafa/src/schema/tiers.ts`, and it does not reach this barrel.
+ *
+ * `src/pr/index.ts`, the `pr` subject's barrel, re-exports the four
+ * names of `git.ts` from this file, as it re-exported them from
+ * `git.ts` before the move. `config-sections.ts` imports
+ * `src/pr/types.ts` directly and not that barrel, which is why the edge
+ * closes nothing.
+ *
+ * Measured when the two 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 `src/pr/types.ts` taking one value (`gitSaid`) from
+ * this barrel, held a seventh: that file, `config-sections.ts`, `git.ts`
+ * and this one. No load order of the control was run.
+ *
+ * `docs/survey/cluster-map.json` places `git.ts` and `commit.ts` in two
+ * clusters, and this file, which it does not name, lands by its folder
+ * in the cluster of `git.ts`. `src/tests/import-cycle.sweep.test.ts`
+ * reads cycles and this file is in none.
+ *
+ * ## What it exports
+ *
+ * Each name is spelled, types apart from values, as the other core
+ * 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 two files: every name either
+ * exports is here once, as the same binding, `GitRunner` as the type
+ * `git.ts` declares, and no other name is here.
+ */
+export type { GhResult, GhRunner } from './gh-runner.js';
+export type { GitResult, GitRunner } from './git.js';
+export type { CommitAttempt, CommitMessage, CommitOptions, CommitOutcome, CommitStep, CommitType, CommitTypeRule, DerivedSubject, GitRunResult, SubjectOptions, } from './commit.js';
+export { createGitRunner, gitSaid } from './git.js';
+export { buildCommitMessage, COMMIT_TYPE_RULES, commitArgs, commitTaskWork, DEFAULT_COMMIT_TYPE, deriveCommitSubject, FALLBACK_DESCRIPTION, firstClause, headShaArgs, inferCommitType, MAX_MESSAGE_CHARS, MAX_SUBJECT_LENGTH, normaliseTaskText, spawnGit, stageAllArgs, stagedChangesArgs, } from './commit.js';