@open-tomato/rafa 0.44.0 → 0.46.0

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

@@ -0,0 +1,91 @@
+/**
+ * The `logger` section of the config schema: the six keys the logger
+ * reads (#950), each one's field, its default, its spec and its reader.
+ * {@link LOGGER_SECTION} hands them to core as one `ConfigSection`,
+ * package `logger`, and the `declare module` below adds
+ * {@link LoggerConfigSettings} to `RafaConfig`.
+ * {@link LoggerShape} 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 `errors` section. It has its
+ * own module for the reason `config-schema-errors.ts` gives.
+ *
+ * ## The keys
+ *
+ *   - `logger.level` is the loudest ORDERED level written: `error`,
+ *     `warn` (the default) or `debug`. `api` is refused here: it sits
+ *     outside the order and has its own key.
+ *   - `logger.modules` gives one module a level of its own, over
+ *     `logger.level`: `modules: { board: { level: debug } }`. It is one
+ *     of the map settings `config.ts` merges across layers (its spec
+ *     sets `map`), so the user's and the project's maps are joined by
+ *     module name, the project's entry winning for a module both name. A module's mapping
+ *     holds `level` today, and any other key is kept and warned about.
+ *   - `logger.api` turns on `api` entries, the metadata of each request
+ *     to a service. Off by default.
+ *   - `logger.theme` is `default` or `plain`, which writes no colour.
+ *   - `logger.callSite` names the calling file on `debug` lines.
+ *   - `logger.kind` names the logger adapter, `console` by default. A
+ *     kind nothing registered is not refused at load, since the registry
+ *     an add-on fills is not at hand here: the active logger warns once
+ *     and stays on `console` (`adapters/logger/active.ts`).
+ *
+ * ## When they take effect
+ *
+ * `loadConfig` (`config-load.ts`) calls core's load hook as soon as a
+ * config is read, and `src/config-registry.ts` sets that hook to hand
+ * {@link loggerSettingsOf} to the logger. A command's logger exists
+ * before that, so until a command loads its config the defaults apply.
+ *
+ * None of the keys is a `CommandLineSetting`: the verbosity flags are the
+ * command line's say over what is written.
+ */
+import type { LoggerSettings, LoggerTheme } from './adapters/logger/settings.js';
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { LogLevel } from '@open-tomato/rafa/ports/log-level';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `logger` section's fields, added to core's. */
+    interface RafaConfig extends LoggerConfigSettings {
+    }
+}
+/**
+ * The `logger` keys a file writes, each `logger.modules` entry a mapping
+ * holding `level`; `src/config/shape.ts` composes them into `ConfigShape`.
+ */
+export interface LoggerShape {
+    readonly logger: {
+        readonly kind: string;
+        readonly level: LogLevel;
+        readonly theme: LoggerTheme;
+        readonly modules: Readonly<Record<string, {
+            readonly level: LogLevel;
+        }>>;
+        readonly callSite: boolean;
+        readonly api: boolean;
+    };
+}
+/** The `logger` settings. */
+export interface LoggerConfigSettings {
+    /** The logger adapter's kind. `logger.kind`. */
+    loggerKind: string;
+    /** The loudest ordered level written. `logger.level`. */
+    loggerLevel: LogLevel;
+    /** How lines are coloured. `logger.theme`. */
+    loggerTheme: LoggerTheme;
+    /** A level per module, over `logger.level`. `logger.modules`. */
+    loggerModules: ReadonlyMap<string, LogLevel>;
+    /** Whether a `debug` line names the calling file. `logger.callSite`. */
+    loggerCallSite: boolean;
+    /** Whether `api` entries are written. `logger.api`. */
+    loggerApi: boolean;
+}
+/** The defaults: the console logger at `warn`, nothing else turned on. */
+export declare const LOGGER_DEFAULTS: Readonly<LoggerConfigSettings>;
+/** Every `logger` setting. */
+export declare const LOGGER_SETTINGS: {
+    readonly [K in keyof LoggerConfigSettings]: SettingSpec<K>;
+};
+/** The `logger` section: the six `logger` keys, with their defaults and no check. */
+export declare const LOGGER_SECTION: ConfigSection;
+/** The settings a logger reads, from a resolved config's `logger` fields. */
+export declare function loggerSettingsOf(config: LoggerConfigSettings): LoggerSettings;

package/dist/config-schema-loop-continue.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The four keys `rafa loop start --continue` reads, with their fields,
+ * their defaults, their specs and their readers:
+ * `loop.retriesOnContinue`, `loop.continue.criteria`,
+ * `loop.continue.criteriaMode` and `loop.forceWrapUp.maxNewFailures`.
+ * {@link LOOP_CONTINUE_SECTION} hands them to core as one
+ * `ConfigSection`, package `loop-continue`, and the `declare module`
+ * below adds {@link LoopContinueSettings} to `RafaConfig`.
+ * {@link LoopContinueShape} 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.retries` and ahead of
+ * `loop.wrapUp`, so the order settings are reported in holds the `loop`
+ * section together.
+ *
+ * The keys have their own module, as `config-schema-loop-retries.ts`
+ * has, because `config-schema.ts`'s own note asks a new section for a
+ * sibling, and the two count readers are rules about VALUES that only
+ * these keys read. `config-registry.ts` imports this file to spread it; a
+ * caller reads the settings off the resolved `RafaConfig`.
+ *
+ * ## The keys
+ *
+ * Under `--continue`, a stop that would end the run is handed to a
+ * decision instead (`start/decision-prompt.ts`, `start/decision-parse.ts`):
+ * retry the task with a new approach, stop, jump over it, or defer it
+ * until a later task is done.
+ *
+ *   - `loop.retriesOnContinue` is the retry budget a `--continue` run
+ *     opens when `--retry` is not typed: `false` or a whole number from
+ *     1 to 3, default `1`, counted in a row as `loop.retries` is
+ *     (`start/retry-budget.ts`). A run without `--continue` never reads it.
+ *     It follows `loop.retries`' rules: `false` and not `0` means no
+ *     retry, and `0`, a negative number, a fraction, anything above 3,
+ *     `true` and a quoted number are refused.
+ *   - `loop.continue.criteria` is the project's own criteria file, read
+ *     from the project root on every decision, default
+ *     `.rafa/continue-criteria.md`. A missing file is not an error here:
+ *     whether it may be missing is the mode's rule.
+ *   - `loop.continue.criteriaMode` says how the project file meets the
+ *     bundled base criteria: `extend` (the default) appends it under the
+ *     base, `replace` uses it alone, and a `replace` whose file is
+ *     missing is refused when the run starts.
+ *   - `loop.forceWrapUp.maxNewFailures` is how many NEW suite failures
+ *     `--force-wrap-up` tolerates before it refuses the wrap-up: `false`
+ *     (the default, none tolerated) or a whole number from 1 to 50, with
+ *     the same refusals as the retry count. Inherited baseline failures
+ *     are not counted.
+ *
+ * None is a `CommandLineSetting`: the flags that outrank a key for one
+ * run (`--retry=<n>`) are read by `start/run-setup.ts`.
+ */
+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 `loop-continue` section's fields, added to core's. */
+    interface RafaConfig extends LoopContinueSettings {
+    }
+}
+/**
+ * The `loop` keys `loop start --continue` reads, the section's part of
+ * the shared `loop` namespace; `src/config/shape.ts` composes it into
+ * `LoopShape`.
+ */
+export interface LoopContinueShape {
+    readonly retriesOnContinue: ContinueCount;
+    readonly continue: {
+        readonly criteria: string;
+        readonly criteriaMode: ContinueCriteriaMode;
+    };
+    readonly forceWrapUp: {
+        readonly maxNewFailures: ContinueCount;
+    };
+}
+/** The fewest retries `loop.retriesOnContinue` accepts as a number. */
+export declare const RETRIES_ON_CONTINUE_MIN = 1;
+/** The most retries `loop.retriesOnContinue` accepts. */
+export declare const RETRIES_ON_CONTINUE_MAX = 3;
+/** The fewest new failures `loop.forceWrapUp.maxNewFailures` accepts as a number. */
+export declare const FORCE_WRAP_UP_MAX_NEW_FAILURES_MIN = 1;
+/** The most new failures `loop.forceWrapUp.maxNewFailures` accepts. */
+export declare const FORCE_WRAP_UP_MAX_NEW_FAILURES_MAX = 50;
+/** How the project criteria file meets the bundled base criteria. */
+export declare const CONTINUE_CRITERIA_MODES: readonly ["extend", "replace"];
+/** One of {@link CONTINUE_CRITERIA_MODES}. */
+export type ContinueCriteriaMode = (typeof CONTINUE_CRITERIA_MODES)[number];
+/** A whole-number count a key bounds, or `false` for none. */
+export type ContinueCount = number | false;
+/** The settings `loop start --continue` reads, resolved. */
+export interface LoopContinueSettings {
+    /**
+     * The retries a `--continue` run opens when `--retry` is not typed,
+     * or `false` for none. `loop.retriesOnContinue`.
+     */
+    loopRetriesOnContinue: ContinueCount;
+    /** The project criteria file, from the project root. `loop.continue.criteria`. */
+    loopContinueCriteria: string;
+    /** How the project criteria meet the base. `loop.continue.criteriaMode`. */
+    loopContinueCriteriaMode: ContinueCriteriaMode;
+    /**
+     * The new suite failures `--force-wrap-up` tolerates, or `false` for
+     * none. `loop.forceWrapUp.maxNewFailures`.
+     */
+    loopForceWrapUpMaxNewFailures: ContinueCount;
+}
+/** Accepts `false` or a whole number from 1 to 3; the module note says why. */
+export declare const retriesOnContinue: Reader<ContinueCount>;
+/** Accepts `false` or a whole number from 1 to 50; the module note says why. */
+export declare const forceWrapUpMaxNewFailures: Reader<ContinueCount>;
+/** Accepts a non-blank path, kept as written. */
+export declare const continueCriteria: Reader<string>;
+/** Accepts `extend` or `replace`. */
+export declare const continueCriteriaMode: Reader<ContinueCriteriaMode>;
+/** What the four settings resolve to when no layer names them. */
+export declare const LOOP_CONTINUE_DEFAULTS: Readonly<LoopContinueSettings>;
+/** The four settings' specs. */
+export declare const LOOP_CONTINUE_SETTINGS: {
+    readonly [K in keyof LoopContinueSettings]: SettingSpec<K>;
+};
+/** The `loop-continue` section: the four keys `loop start --continue` reads, with their defaults and no check. */
+export declare const LOOP_CONTINUE_SECTION: ConfigSection;

package/dist/config-schema-loop-retries.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `loop.retries`, the loop's own retry count: how many times in a row
+ * one run re-enters its task loop after a stop a blind re-run is known
+ * to pass, with its field, its default, its spec and its reader.
+ * {@link LOOP_RETRIES_SECTION} hands it to core as one `ConfigSection`,
+ * package `loop-retries`, and the `declare module` below adds
+ * {@link LoopRetriesSettings} to `RafaConfig`.
+ * {@link LoopRetriesShape} 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` and ahead of
+ * `loop.wrapUp`, so the order settings are reported in holds the `loop`
+ * section together.
+ *
+ * The key has its own module, as `config-schema-wrap-up.ts` has, because
+ * `config-schema.ts`'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`, and
+ * `start/run-setup.ts` checks `--retry` against the same two bounds.
+ *
+ * ## The key
+ *
+ * A soft stop of `rafa loop start` (a red suite step, a session that
+ * exited nonzero, a session that left neither a report nor a commit)
+ * ends the run today, and the person runs `rafa loop start` again by
+ * hand, which resumes at the `[BLOCKED]` line or the inserted repair.
+ * `loop.retries` is how many of those re-runs the loop makes itself,
+ * in a row, at those stops alone (`start/retry-budget.ts`): a task done
+ * past the stop, neither the stopped task nor a repair, starts the count
+ * over.
+ *
+ *
+ *   - It defaults to `false`: no retry, so a run stops where it always
+ *     did until a person asks for more.
+ *   - It accepts a whole number from 1 to 3. Each retry spends at least
+ *     one more session, so the cap of 3 bounds what a run whose stop
+ *     keeps coming back can spend before it halts: a task that keeps
+ *     failing never starts its own count over.
+ *   - `false` means no retry. It is spelled `false` and not `0`, so a
+ *     number always names retries 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 some count
+ *     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
+ * flag that outranks it for one run is `loop start --retry=<n>`, read
+ * by `start/run-setup.ts`.
+ */
+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 `loop-retries` section's fields, added to core's. */
+    interface RafaConfig extends LoopRetriesSettings {
+    }
+}
+/**
+ * `loop.retries`, the section's part of the shared `loop` namespace;
+ * `src/config/shape.ts` composes it into `LoopShape`.
+ */
+export interface LoopRetriesShape {
+    readonly retries: LoopRetries;
+}
+/** The fewest retries `loop.retries` accepts as a number. */
+export declare const LOOP_RETRIES_MIN = 1;
+/** The most retries `loop.retries` accepts. */
+export declare const LOOP_RETRIES_MAX = 3;
+/** How many times in a row one run re-enters its loop after a retry-safe stop, or `false` for none. */
+export type LoopRetries = number | false;
+/** The `loop.retries` setting, resolved. */
+export interface LoopRetriesSettings {
+    /**
+     * The retries in a row one run makes after a retry-safe stop, or
+     * `false` for none. `loop.retries`.
+     */
+    loopRetries: LoopRetries;
+}
+/** True for a whole number from {@link LOOP_RETRIES_MIN} to {@link LOOP_RETRIES_MAX}. */
+export declare function isLoopRetryCount(raw: unknown): raw is number;
+/**
+ * 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 loopRetries: Reader<LoopRetries>;
+/** What `loop.retries` resolves to when no layer names it. */
+export declare const LOOP_RETRIES_DEFAULTS: Readonly<LoopRetriesSettings>;
+/** The `loop.retries` setting spec. */
+export declare const LOOP_RETRIES_SETTINGS: {
+    readonly [K in keyof LoopRetriesSettings]: SettingSpec<K>;
+};
+/** The `loop-retries` section: `loop.retries`, with their defaults and no check. */
+export declare const LOOP_RETRIES_SECTION: ConfigSection;

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

@@ -0,0 +1,307 @@
+/**
+ * The `pr` and `release` sections of the config schema, and the one
+ * `dangerous` key the release plan adds: each setting's field, its
+ * default and its spec. {@link RELEASE_SECTION} hands them to core as
+ * one `ConfigSection`, package `release`, and the `declare module` below
+ * adds {@link PrSettings}, {@link ReleaseSettings} and
+ * {@link DangerousReleaseSettings} to `RafaConfig`.
+ * {@link ReleaseShape} holds the keys a file writes and
+ * {@link ReleaseDangerousShape} its part of the shared `dangerous`
+ * namespace, which `src/config/shape.ts` composes into `ConfigShape`,
+ * the nested file shape.
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
+ * spread the objects below at the places the two sections always sat,
+ * and the `dangerous` key right after `dangerous.acceptStaleRefs`, so
+ * the order settings are reported in, and the order a warning lists keys
+ * in, holds each key's section.
+ *
+ * They moved out of `config-schema.ts` when that module stood at 780
+ * lines, measured with `wc -l`, before the release plan's six keys
+ * joined these two sections and `dangerous`: new keys in a module near
+ * the 800-line cap of `context/source.md` would be paid for by
+ * rewrapping prose. The six keys then joined here. Every rule the schema module states about a KEY
+ * still holds here, and `config-sections.ts` still holds every rule
+ * about a VALUE. `config-registry.ts` imports this file to spread it; a
+ * caller reads these settings off the resolved `RafaConfig`.
+ *
+ * ## The `pr` section
+ *
+ * `.rafa/specs/rafa-20-pr-commands.md` spells it `pr: { provider: gh | none,
+ * mergeMethod: squash | merge | rebase, base: <default branch> }`, and
+ * names `pr.resolveBudget` as what a `triage --resolve` session's
+ * `--max-budget-usd` comes from. Four readings it leaves to this module:
+ *
+ *   - `pr.provider` and `pr.base` default to NULL, and null here means
+ *     "nobody has said", not "off". The spec's default for the provider
+ *     is `gh` when `origin` is a GitHub remote and `none` otherwise, and
+ *     its default base is whatever the remote calls its default branch;
+ *     neither is a value this module can spell, because both are read
+ *     off the repository at use (`pr/provider.ts`). Writing either
+ *     default as a literal would be the silent choice the config refuses
+ *     everywhere else: `prBase: 'main'` would open a pull request into a
+ *     branch that may not exist on a repository whose default is
+ *     `master`. A file spelling `provider:` or `base:` with no value
+ *     says nothing, as every null does, and resolves to the same null.
+ *   - `pr.mergeMethod` defaults to `squash`, the first method the spec
+ *     lists and the one the merge flow is written for: it deletes the
+ *     local branch with `-D` because a squash leaves it unmerged in
+ *     git's eyes.
+ *   - `pr.resolveBudget` defaults to 2 US dollars, which the attempt
+ *     guard's default of two attempts caps at 4 for one pull request.
+ *     It is a number and not null: the spec has every resolve run carry
+ *     `--max-budget-usd`, so a session with no budget is not a state
+ *     this setting can be left in.
+ *   - No `pr` setting is a `CommandLineSetting`. `pr merge` takes
+ *     a `--method` flag, but that flag is the command's own argument for
+ *     one merge, read by the command beside this setting, and not a
+ *     layer over the config: a global `--merge-method` nobody typed
+ *     would be a flag this module invented.
+ *   - `pr.versionCollision` defaults to `report`. It sets how `rafa pr
+ *     merge` reacts to a branch the release guard reads as `missing`
+ *     (source changes and no fragment) or `stale` (a stamped version
+ *     the base branch has passed): `report` names it and merges,
+ *     `allow` is silent, `ask` asks and `refuse` stops. A `collision` is
+ *     not this setting's: it always refuses, unless
+ *     `dangerous.acceptVersionCollision` says otherwise. A default of
+ *     `refuse` would stop every project whose branches still stamp their
+ *     own versions the day it upgrades.
+ *
+ * ## The `release` section
+ *
+ * `.rafa/specs/rafa-21-changelog-and-release.md` spells it `release: {
+ * enabled: auto, versionFile: package.json, changelog: CHANGELOG.md,
+ * heading: "## {version} — {date}, {title}" }`, and those four values
+ * are the defaults here. Four readings it leaves to this module:
+ *
+ *   - `release.enabled` is not a flag. `auto`, its default, is a third
+ *     value meaning "on when both files below exist" — a reading
+ *     `release/enabled.ts` makes against a disk, which no value here
+ *     could stand for. What the reader takes beside it, and why `on`
+ *     and `off` are refused, is `config-sections.ts`'s to say.
+ *   - `release.versionFile` and `release.changelog` are paths relative
+ *     to the repository root, and neither is null. Null elsewhere here
+ *     means "nobody has said", and the spec has said: `package.json`
+ *     and `CHANGELOG.md`. The absence the spec cares about is the
+ *     FILE's — "a project with no version file gets the changelog
+ *     entry under a date heading and no bump" — which is a question
+ *     about a disk, answered at use and not spellable as a default.
+ *   - `release.heading` is free text. The spec makes it a template so
+ *     "a consumer's changelog has another shape" is an edit rather
+ *     than a fork, and which placeholders it may carry, and what an
+ *     unknown one renders to, is `release/changelog.ts`'s to say. So
+ *     nothing here refuses a heading for the placeholders it spells.
+ *   - No `release` setting is a `CommandLineSetting`, for the
+ *     reason the `pr` section gives: the `release` commands read these
+ *     settings beside their own arguments, and a global flag nobody
+ *     typed would be one this module invented.
+ *
+ * Four more `release` settings belong to the plan in which no branch
+ * owns a version number — a branch commits one change fragment, and
+ * `rafa release settle` folds the fragments into a version on the base
+ * branch after the merges:
+ *
+ *   - `release.fragments` defaults to `.changes`, the directory a
+ *     fragment is written into. It is a path relative to the repository
+ *     root and never under `.rafa/`, which is gitignored; the reader,
+ *     `config-readers.ts`'s `fragmentsDirectory`, says why.
+ *   - `release.strategy` defaults to `semver-by-level`, and that is the
+ *     only value it accepts today: a closed list of one, so a file
+ *     naming a strategy that does not exist is refused rather than
+ *     folded by a strategy it did not name.
+ *   - `release.settle` defaults to `push`: settle pushes the settled
+ *     commit to the base branch, and `pr` opens a pull request with it
+ *     instead, for a base branch that takes no direct push.
+ *   - `release.tag` defaults to `manual`: `rafa release tag` stays the
+ *     one write of the tag, and `settle` has settle put it on the
+ *     commit it pushes.
+ *
+ * One more `release` setting is text `rafa release tag` prints and
+ * `rafa release publish` runs:
+ *
+ *   - `release.publishCommand` defaults to `npm publish`, the command
+ *     `rafa release tag` names for the publish after the tag and
+ *     `rafa release publish` runs in each tagged unit's folder. It is free
+ *     text, so a project that publishes with another tool, or with a
+ *     flag such as `--tag next`, says so here. It was read off the
+ *     manifest's `packageManager` field until 2026-09-30, which named
+ *     `bun publish` for this repository while its releases are
+ *     published with `npm publish`: the tool a project installs with is
+ *     not the tool it publishes with.
+ *
+ * One more `release` setting says who publishes a tagged version:
+ *
+ *   - `release.publish` defaults to `manual`: a person runs the publish
+ *     after the tag. `ci` says the pushed tag publishes through the
+ *     project's CI workflow instead. It is the third key the release
+ *     ladder is read off, beside `release.settle` and `release.tag`.
+ *
+ * One more `release` setting is for the repository that releases rafa:
+ *
+ *   - `release.moveLock` defaults to `false`. When it is `true`, settle
+ *     also writes `rafa.lock` at the repository root to the version it
+ *     settles, in the same release commit as the version file and the
+ *     changelog, so the repository's own lock follows the rafa it
+ *     publishes. It is read through `flag`, so `"true"`, `yes` and `1`
+ *     are refused, and it is not a `CommandLineSetting`.
+ *
+ * ## The `dangerous` key
+ *
+ * `dangerous.acceptVersionCollision` has `rafa pr merge` accept, on
+ * every run, a branch the release guard reads as a `collision` — its
+ * version already on the base branch with different notes — which it
+ * refuses whatever `pr.versionCollision` says. It is read as `dangerous.acceptStaleRefs`
+ * is, for the reasons `config-schema.ts`'s "The `dangerous` section"
+ * gives: it defaults to `false` and not null, it goes through `flag` so
+ * `"true"`, `yes` and `1` are refused, and it is not a
+ * `CommandLineSetting`.
+ */
+import type { MergeMethod } from './pr/types.js';
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { PrProvider, Reader, ReleaseEnabled, ReleasePublishMode, ReleaseSettleMode, ReleaseStrategy, ReleaseTagMode, VersionCollisionMode } from '@open-tomato/rafa/core/config/sections';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `release` section's fields, added to core's. */
+    interface RafaConfig extends PrSettings, ReleaseSettings, DangerousReleaseSettings {
+    }
+}
+/**
+ * The `pr` and `release` keys a file writes, both namespaces this
+ * section's alone; `src/config/shape.ts` composes them into `ConfigShape`.
+ */
+export interface ReleaseShape {
+    readonly pr: {
+        readonly provider: PrProvider;
+        readonly mergeMethod: MergeMethod;
+        readonly base: string;
+        readonly resolveBudget: number;
+        readonly versionCollision: VersionCollisionMode;
+    };
+    readonly release: {
+        readonly enabled: ReleaseEnabled;
+        readonly versionFile: string;
+        readonly changelog: string;
+        readonly heading: string;
+        readonly fragments: string;
+        readonly strategy: ReleaseStrategy;
+        readonly settle: ReleaseSettleMode;
+        readonly tag: ReleaseTagMode;
+        readonly publishCommand: string;
+        readonly publish: ReleasePublishMode;
+        readonly moveLock: boolean;
+    };
+}
+/**
+ * `dangerous.acceptVersionCollision`, the section's part of the shared
+ * `dangerous` namespace; `src/config/shape.ts` composes it into
+ * `DangerousShape` beside core's consents.
+ */
+export interface ReleaseDangerousShape {
+    readonly acceptVersionCollision: boolean;
+}
+/** The `pr` section's settings, resolved. */
+export interface PrSettings {
+    /**
+     * The provider every `pr` action goes through, or null to read it off
+     * the `origin` remote. `pr.provider`.
+     */
+    prProvider: PrProvider | null;
+    /** How `pr merge` merges, unless `--method` names another. `pr.mergeMethod`. */
+    prMergeMethod: MergeMethod;
+    /**
+     * The branch a pull request is opened into, or null for whatever the
+     * remote calls its default branch. `pr.base`.
+     */
+    prBase: string | null;
+    /**
+     * The budget in US dollars each `pr triage --resolve` session is
+     * spawned with. `pr.resolveBudget`.
+     */
+    prResolveBudget: number;
+    /**
+     * How `pr merge` reacts to a branch the release guard reads as
+     * `missing` or `stale`. `pr.versionCollision`.
+     */
+    prVersionCollision: VersionCollisionMode;
+}
+/** The `release` section's settings, resolved. */
+export interface ReleaseSettings {
+    /**
+     * Whether a run bumps the version and writes a changelog entry, or
+     * `auto` to decide it off the two files below. `release.enabled`.
+     */
+    releaseEnabled: ReleaseEnabled;
+    /**
+     * The manifest the version is read from and written back to, from
+     * the repository root. `release.versionFile`.
+     */
+    releaseVersionFile: string;
+    /**
+     * The changelog an entry is inserted into, from the repository root.
+     * `release.changelog`.
+     */
+    releaseChangelog: string;
+    /** The template one entry's heading is rendered from. `release.heading`. */
+    releaseHeading: string;
+    /**
+     * The directory change fragments are written into, from the
+     * repository root. `release.fragments`.
+     */
+    releaseFragments: string;
+    /** The strategy the fragments are folded into a version by. `release.strategy`. */
+    releaseStrategy: ReleaseStrategy;
+    /** How settle lands the settled version on the base branch. `release.settle`. */
+    releaseSettle: ReleaseSettleMode;
+    /** Who tags a settled version. `release.tag`. */
+    releaseTag: ReleaseTagMode;
+    /** The command `rafa release tag` prints for the publish and `rafa release publish` runs. `release.publishCommand`. */
+    releasePublishCommand: string;
+    /** Who publishes a tagged version: a person, or CI on the pushed tag. `release.publish`. */
+    releasePublish: ReleasePublishMode;
+    /**
+     * Whether settle also writes `rafa.lock` to the version it settles,
+     * in the same release commit. `release.moveLock`.
+     */
+    releaseMoveLock: boolean;
+}
+/** The `dangerous` setting the release plan adds, resolved. */
+export interface DangerousReleaseSettings {
+    /**
+     * Whether `pr merge` accepts, on every run, a branch the release
+     * guard reads as a `collision`. `dangerous.acceptVersionCollision`.
+     */
+    dangerousAcceptVersionCollision: boolean;
+}
+/** What every `pr` setting resolves to when no layer names it. */
+export declare const PR_DEFAULTS: Readonly<PrSettings>;
+/** What every `release` setting resolves to when no layer names it. */
+export declare const RELEASE_DEFAULTS: Readonly<ReleaseSettings>;
+/** What the release plan's `dangerous` setting resolves to when no layer names it. */
+export declare const DANGEROUS_RELEASE_DEFAULTS: Readonly<DangerousReleaseSettings>;
+/**
+ * Accepts one of the pull request port's three merge methods. The list
+ * is the port's (`pr/types.ts`), which spells them to match what
+ * `gh pr merge` takes, so a second spelling here could not disagree
+ * with it.
+ *
+ * It sits here, beside the one setting that reads it, and not among
+ * core's readers in `config-sections.ts`, so no core file imports
+ * `pr/types.ts`. The port is reached at `./pr/types.js` and not through
+ * the `./pr/index.js` barrel, because the barrel carries `pr/gh.ts`,
+ * which imports the config's sections barrel and the `gh` spawner:
+ * importing it here would put the CLI adapter behind every config read.
+ * `pr/types.ts` imports types alone, so this import reaches nothing back.
+ */
+export declare const mergeMethod: Reader<MergeMethod>;
+/** The `pr` section's setting specs, in the order problems are reported. */
+export declare const PR_SETTINGS: {
+    readonly [K in keyof PrSettings]: SettingSpec<K>;
+};
+/** The `release` section's setting specs, in the order problems are reported. */
+export declare const RELEASE_SETTINGS: {
+    readonly [K in keyof ReleaseSettings]: SettingSpec<K>;
+};
+/** The release plan's `dangerous` setting spec. */
+export declare const DANGEROUS_RELEASE_SETTINGS: {
+    readonly [K in keyof DangerousReleaseSettings]: SettingSpec<K>;
+};
+/** The `release` section: the `pr` and `release` keys and `dangerous.acceptVersionCollision`, with their defaults and no check. */
+export declare const RELEASE_SECTION: ConfigSection;