@mindlace/chreode 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethan Fremen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# chreode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Why this exists
+
+A _chreode_ (Waddington) is the canalized valley a developing system rolls
+down: perturb it and it returns to the path, because the landscape is shaped
+to select for it. Carcinization is the same idea seen from the outside —
+independent lineages converging on the same form because the selective
+pressure is consistent.
+
+Agent-written software needs both. An agent will produce _something_ for any
+prompt; whether the codebase drifts toward the shape you want depends on
+whether the feedback it receives is **deterministic, selective, and
+unavoidable**:
+
+- **Deterministic** — the same change gets the same verdict, every time, on
+  any machine. No "it passed when I re-ran it".
+- **Selective** — the feedback discriminates: a change that weakens the
+  codebase fails, and says why, in terms the agent can act on.
+- **Unavoidable** — the agent cannot route around it: no wrapping the gate in
+  `| tail`, no running a hand-picked subset and calling it green, no merging
+  without the gate's status.
+
+chreode packages a working implementation of that landscape, extracted from a
+production codebase where agents write most of the code. It is a set of
+layers; the **gate** (`chreode signoff`) is the terminal one, and it is only as
+good as the layers feeding it (lint rules, e2e coverage, visual checks, the
+guardrail hooks). This spec covers the core — the gate and its plumbing — and
+names the later layers so the structure has room for them.
+
+## Install
+
+```bash
+npm install --save-dev @mindlace/chreode
+```
+
+Requires Node ≥ 22.12, `git`, and an authenticated [`gh`](https://cli.github.com/).
+
+## Usage
+
+Add `chreode.config.ts` at the repo root (see below), then:
+
+```bash
+npx chreode signoff            # merge origin/main, run what changed, push, post the status
+npx chreode signoff --dry-run  # merge, then print the plan and stop
+npx chreode protect            # require the status on main (idempotent); --dry-run previews
+```
+
+Wire them into `package.json` as `"signoff": "chreode signoff"` and
+`"branch-protection": "chreode protect"`. Run signoff instead of pushing: it pushes for you.
+
+### `chreode signoff`
+
+1. **Preconditions**: clean tree, a branch (not detached, not the base branch), not behind its
+   upstream, `gh auth status` ok, `git config user.email` set.
+2. **Merge** `origin/<baseBranch>` (unless `--no-merge`). A conflict exits 1 and leaves the
+   merge in progress. When the merge changed the branch, `afterMerge` runs and the config is
+   reloaded, so a merged-in `chreode.config.ts` governs the rest of the run.
+3. **Base**: `--base`, else the nearest commit on the branch carrying a `refs/notes/chreode`
+   note (the last successful signoff), else the merge-base with `origin/<baseBranch>`.
+4. **Plan**: changed paths (both sides of renames, deletions included) → triggers (first
+   matching rule; a path no rule matches fires every trigger) → steps (`when`, `if`,
+   `--skip`, `supersededBy`). The plan and every skipped step's reason are printed.
+5. **Run** the steps in order under one machine-wide lock shared by every chreode repo on the
+   machine. Each step runs in its own process group with a hard timeout; policed steps fail
+   on unexpected stderr. Children see `CHREODE_SIGNOFF=1`.
+6. **Tail**: refuse if the steps changed the checkout; push; post `<statusContext>` = success
+   naming the signer and disclosing any `--skip`'d steps, stderr waived by `--allow-stderr`,
+   and `base=<ref>` for `--base`; write the note. A partial run (any of those three) writes
+   no note, so it never becomes the incremental base: the next signoff diffs from the last
+   full one and re-plans what was skipped.
+
+| Flag              | Env                      | Effect                                                                                                                       |
+| ----------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `--full`          | `CHREODE_FULL=1`         | Ignore the incremental base; run every step                                                                                  |
+| `--dry-run`       |                          | Merge and run `afterMerge`, then print the plan and stop without running steps; add `--no-merge` for a side-effect-free look |
+| `--no-merge`      | `CHREODE_NO_MERGE=1`     | Do not merge `origin/<baseBranch>` first                                                                                     |
+| `--no-push`       | `CHREODE_NO_PUSH=1`      | Do not push (the commit must already be on origin)                                                                           |
+| `--allow-stderr`  | `CHREODE_ALLOW_STDERR=1` | Downgrade policed stderr to a warning (named in the status; no note)                                                         |
+| `--base <ref>`    |                          | Diff from this ref (named in the status; no note)                                                                            |
+| `--skip <label>`  |                          | Skip a planned step (repeatable; named in the status; no note)                                                               |
+| `--config <path>` |                          | Config file (default `<repo root>/chreode.config.ts`)                                                                        |
+
+Exit codes: `0` signed off, already signed off, or dry run; `1` anything else.
+
+The lock lives at `$TMPDIR/chreode-signoff.lock`. A waiter logs once and polls for up to an
+hour; a lock whose holder died goes stale after 30 s and is stolen. `CHREODE_LOCK_PATH`
+overrides the path (for test isolation only).
+
+### `chreode protect`
+
+`PUT`s branch protection on `<baseBranch>` requiring `<statusContext>` (strict), with admins
+enforced, linear history, PRs required (0 approvals, stale reviews dismissed), and `PATCH`es
+the repo to squash-only merges that delete head branches. Override either payload under
+`protection` in the config. `--repo owner/name` targets another repo; `--dry-run` prints the
+payloads.
+
+## Config reference
+
+```ts
+import { defineConfig } from '@mindlace/chreode';
+
+export default defineConfig({
+  baseBranch: 'main', // default
+  statusContext: 'chreode/signoff', // default
+  rules: [
+    { match: ['docs/**', '**/*.md'], triggers: ['format'] },
+    { match: 'src/**', triggers: ['lint', 'check', 'unit', 'e2e'] },
+    { match: 'generated/**', triggers: [] } // matched, nothing to run
+  ],
+  steps: [
+    { label: 'format', run: 'npx prettier --check .', when: ['format'], supersededBy: ['lint'] },
+    { label: 'lint', run: 'npm run lint', when: ['lint'] },
+    { label: 'check', run: 'npm run check', when: ['check'] },
+    { label: 'test:unit', run: 'npm run test:unit', when: ['unit'], policeStderr: true },
+    {
+      label: 'test:e2e',
+      run: 'npm run test:e2e',
+      when: ['e2e'],
+      policeStderr: true,
+      timeoutMs: 15 * 60_000
+    }
+  ],
+  afterMerge: 'npm ci', // not `npm install`: see below
+  stderrAllowlist: [{ pattern: /^\[WebServer\] /, reason: 'Playwright echoes the preview server' }]
+});
+```
+
+**Rules** are tried in order; the first whose `match` (a [picomatch](https://github.com/micromatch/picomatch)
+glob, dotfiles included, or a RegExp, or an array of them) matches a changed path decides its
+triggers. A path no rule matches fires every trigger: rules can only make runs smaller, so a
+forgotten rule costs time, never coverage. Triggers are free-form strings.
+
+**Steps** run in config order.
+
+| Field          | Type                        | Meaning                                                                |
+| -------------- | --------------------------- | ---------------------------------------------------------------------- |
+| `label`        | string                      | Unique, no whitespace. Used by `--skip`, the note and the status.      |
+| `run`          | `string \| (ctx) => string` | Shell command. `ctx` is `{ base, head, paths, triggers, isWorktree }`. |
+| `when`         | string[]                    | Planned if any listed trigger fired.                                   |
+| `if`           | `(ctx) => boolean`          | Extra predicate, e.g. only in a worktree.                              |
+| `supersededBy` | string[]                    | Dropped when any listed step will also run.                            |
+| `policeStderr` | boolean                     | Fail a clean exit that wrote non-allowlisted stderr.                   |
+| `timeoutMs`    | number                      | Hard ceiling; default 10 minutes.                                      |
+
+**`afterMerge`** runs only when merging `origin/<baseBranch>` changed the branch. It must
+leave the checkout clean (signoff refuses to run otherwise), so use `npm ci`, which installs
+exactly the lockfile, rather than `npm install`, which can rewrite it.
+**`stderrAllowlist`** entries need a `reason`: allowlisting noise is a reviewed decision.
+Unknown keys, duplicate labels, and `supersededBy` naming a missing step are load errors.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { type SignoffOptions } from './signoff/run.js';
+export interface SignoffFlags {
+    full?: boolean;
+    dryRun?: boolean;
+    merge?: boolean;
+    push?: boolean;
+    allowStderr?: boolean;
+    base?: string;
+    skip?: string[];
+    config?: string;
+}
+export interface ProtectFlags {
+    dryRun?: boolean;
+    repo?: string;
+    config?: string;
+}
+/** Each flag also has an env form, for harnesses that forbid flags after `--`. */
+export declare function resolveSignoffOptions(flags: SignoffFlags, env: NodeJS.ProcessEnv): SignoffOptions;
+export declare function buildProgram(actions: {
+    signoff: (flags: SignoffFlags) => Promise<number>;
+    protect: (flags: ProtectFlags) => Promise<number>;
+}, setExit: (code: number) => void): Command;
+export declare function main(argv?: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+/** npm installs the bin as a symlink, so compare real paths, not the invoked path. */
+export declare function isInvokedDirectly(moduleUrl: string, argv1: string | undefined): boolean;

package/dist/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+import { CONFIG_FILE, loadConfig } from './config/load.js';
+import { parseRepo } from './github/status.js';
+import { runProtect } from './github/protect.js';
+import { defaultExec } from './run/exec.js';
+import { runSignoff } from './signoff/run.js';
+/** Each flag also has an env form, for harnesses that forbid flags after `--`. */
+export function resolveSignoffOptions(flags, env) {
+    const on = (key) => env[key] === '1';
+    return {
+        full: flags.full === true || on('CHREODE_FULL'),
+        dryRun: flags.dryRun === true,
+        noMerge: flags.merge === false || on('CHREODE_NO_MERGE'),
+        noPush: flags.push === false || on('CHREODE_NO_PUSH'),
+        allowStderr: flags.allowStderr === true || on('CHREODE_ALLOW_STDERR'),
+        base: flags.base ?? null,
+        skip: flags.skip ?? []
+    };
+}
+function readVersion() {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+}
+const collect = (value, previous) => [...previous, value];
+export function buildProgram(actions, setExit) {
+    const program = new Command('chreode')
+        .description('A deterministic, selective, unavoidable local-CI gate')
+        .version(readVersion());
+    program
+        .command('signoff')
+        .description('merge the base branch, run the steps the changes need, push, post the status')
+        .option('--full', 'ignore the incremental base and run every step (env CHREODE_FULL=1)')
+        .option('--dry-run', 'merge origin/<baseBranch> and run afterMerge as usual, then print the plan and stop ' +
+        'without running steps (add --no-merge for a side-effect-free look)')
+        .option('--no-merge', 'do not merge origin/<baseBranch> first (env CHREODE_NO_MERGE=1)')
+        .option('--no-push', 'do not push; the commit must already be on origin (env CHREODE_NO_PUSH=1)')
+        .option('--allow-stderr', 'downgrade policed stderr to a warning (env CHREODE_ALLOW_STDERR=1)')
+        .option('--base <ref>', 'diff from this ref instead of the last signoff')
+        .option('--skip <label>', 'skip a planned step; repeatable; named in the status', collect, [])
+        .option('--config <path>', `config file (default: <repo root>/${CONFIG_FILE})`)
+        .action(async (flags) => setExit(await actions.signoff(flags)));
+    program
+        .command('protect')
+        .description('require the signoff status on the base branch (idempotent)')
+        .option('--dry-run', 'print the payloads without applying them')
+        .option('--repo <owner/name>', 'target repository (default: gh repo view)')
+        .option('--config <path>', `config file (default: <repo root>/${CONFIG_FILE})`)
+        .action(async (flags) => setExit(await actions.protect(flags)));
+    return program;
+}
+/** Steps and git commands run from the repo root, whatever directory chreode was started in.
+ *  Returns a loader rather than a config: signoff reloads it after a merge. */
+function repoConfigLoader(configFlag) {
+    const explicit = configFlag ? path.resolve(configFlag) : null;
+    const root = defaultExec('git', ['rev-parse', '--show-toplevel']).trim();
+    process.chdir(root);
+    const file = explicit ?? path.join(root, CONFIG_FILE);
+    return () => loadConfig(file);
+}
+export async function main(argv = process.argv, env = process.env) {
+    let code = 0;
+    const program = buildProgram({
+        signoff: async (flags) => runSignoff(repoConfigLoader(flags.config), resolveSignoffOptions(flags, env)),
+        protect: async (flags) => runProtect(await repoConfigLoader(flags.config)(), {
+            dryRun: flags.dryRun === true,
+            repo: flags.repo ? parseRepo(flags.repo) : null
+        })
+    }, (c) => {
+        code = c;
+    });
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (err) {
+        console.error(`[chreode] ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    return code;
+}
+/** npm installs the bin as a symlink, so compare real paths, not the invoked path. */
+export function isInvokedDirectly(moduleUrl, argv1) {
+    if (!argv1)
+        return false;
+    try {
+        return moduleUrl === pathToFileURL(realpathSync(argv1)).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (isInvokedDirectly(import.meta.url, process.argv[1])) {
+    main().then((c) => {
+        process.exitCode = c;
+    }, (err) => {
+        console.error(err);
+        process.exitCode = 1;
+    });
+}

package/dist/config/load.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedConfig } from './types.js';
+export declare const CONFIG_FILE = "chreode.config.ts";
+/** Load and validate a config file. jiti transpiles TypeScript on the fly, so consumers
+ *  need no build step and no tsx. */
+export declare function loadConfig(file: string): Promise<ResolvedConfig>;

package/dist/config/load.js

@@ -0,0 +1,13 @@
+import { existsSync } from 'node:fs';
+import { createJiti } from 'jiti';
+import { ConfigError, validateConfig } from './validate.js';
+export const CONFIG_FILE = 'chreode.config.ts';
+/** Load and validate a config file. jiti transpiles TypeScript on the fly, so consumers
+ *  need no build step and no tsx. */
+export async function loadConfig(file) {
+    if (!existsSync(file))
+        throw new ConfigError([`no config file at ${file}`]);
+    const jiti = createJiti(import.meta.url, { moduleCache: false, fsCache: false });
+    const mod = await jiti.import(file, { default: true });
+    return validateConfig(mod);
+}

package/dist/config/types.d.ts

@@ -0,0 +1,71 @@
+/** A path matcher: a picomatch glob (dotfiles match) or a RegExp tested against the
+ *  repo-relative POSIX path. */
+export type Matcher = string | RegExp;
+/** What a step's `run` function and `if` predicate see. */
+export interface StepContext {
+    base: string;
+    head: string;
+    paths: readonly string[];
+    triggers: readonly string[];
+    isWorktree: boolean;
+}
+/** First matching rule wins. `triggers: []` means "matched, nothing to run". */
+export interface RuleConfig {
+    match: Matcher | Matcher[];
+    triggers: string[];
+}
+export interface StepConfig {
+    /** Unique, no whitespace. Used by --skip, the note and the status description. */
+    label: string;
+    run: string | ((ctx: StepContext) => string);
+    /** Planned when any listed trigger fired. */
+    when: string[];
+    if?: (ctx: StepContext) => boolean;
+    /** Dropped when any listed step label is also going to run. */
+    supersededBy?: string[];
+    /** Capture stderr; a clean exit with non-allowlisted stderr fails the step. */
+    policeStderr?: boolean;
+    /** Hard wall-clock ceiling; the step's process group is SIGKILLed past it. */
+    timeoutMs?: number;
+}
+export interface AllowlistEntry {
+    /** A stderr line (ANSI-stripped) matching this pattern is benign. */
+    pattern: RegExp;
+    /** Why this noise is unavoidable. Required: allowlisting is a reviewed decision. */
+    reason: string;
+}
+export interface ProtectionConfig {
+    /** Shallow-merged over the default branch-protection payload. */
+    branch?: Record<string, unknown>;
+    /** Shallow-merged over the default repository merge settings. */
+    repo?: Record<string, unknown>;
+}
+export interface ChreodeConfig {
+    baseBranch?: string;
+    statusContext?: string;
+    rules?: RuleConfig[];
+    steps: StepConfig[];
+    /** Runs only when the merge of origin/<baseBranch> actually changed the branch. */
+    afterMerge?: string;
+    stderrAllowlist?: AllowlistEntry[];
+    protection?: ProtectionConfig;
+}
+export interface ResolvedStep extends StepConfig {
+    supersededBy: string[];
+    policeStderr: boolean;
+    timeoutMs: number;
+}
+export interface ResolvedConfig {
+    baseBranch: string;
+    statusContext: string;
+    rules: RuleConfig[];
+    steps: ResolvedStep[];
+    afterMerge: string | null;
+    stderrAllowlist: AllowlistEntry[];
+    protection: ProtectionConfig;
+}
+export declare const DEFAULT_BASE_BRANCH = "main";
+export declare const DEFAULT_STATUS_CONTEXT = "chreode/signoff";
+export declare const DEFAULT_TIMEOUT_MS: number;
+/** Identity helper so `chreode.config.ts` gets types. */
+export declare function defineConfig(config: ChreodeConfig): ChreodeConfig;

package/dist/config/types.js

@@ -0,0 +1,7 @@
+export const DEFAULT_BASE_BRANCH = 'main';
+export const DEFAULT_STATUS_CONTEXT = 'chreode/signoff';
+export const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+/** Identity helper so `chreode.config.ts` gets types. */
+export function defineConfig(config) {
+    return config;
+}

package/dist/config/validate.d.ts

@@ -0,0 +1,9 @@
+import { type ResolvedConfig } from './types.js';
+export declare class ConfigError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/** Cross-realm safe: a config evaluated by jiti may not share this realm's RegExp. */
+export declare function isRegExp(v: unknown): v is RegExp;
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+export declare function validateConfig(raw: unknown): ResolvedConfig;

package/dist/config/validate.js

@@ -0,0 +1,204 @@
+import { DEFAULT_BASE_BRANCH, DEFAULT_STATUS_CONTEXT, DEFAULT_TIMEOUT_MS } from './types.js';
+export class ConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(`invalid chreode config:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+        this.problems = problems;
+        this.name = 'ConfigError';
+    }
+}
+const TOP_KEYS = new Set([
+    'baseBranch',
+    'statusContext',
+    'rules',
+    'steps',
+    'afterMerge',
+    'stderrAllowlist',
+    'protection'
+]);
+const RULE_KEYS = new Set(['match', 'triggers']);
+const STEP_KEYS = new Set([
+    'label',
+    'run',
+    'when',
+    'if',
+    'supersededBy',
+    'policeStderr',
+    'timeoutMs'
+]);
+const ALLOW_KEYS = new Set(['pattern', 'reason']);
+const PROTECTION_KEYS = new Set(['branch', 'repo']);
+/** Cross-realm safe: a config evaluated by jiti may not share this realm's RegExp. */
+export function isRegExp(v) {
+    return Object.prototype.toString.call(v) === '[object RegExp]';
+}
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v) && !isRegExp(v);
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every(isNonEmptyString);
+}
+function isMatcher(v) {
+    return isNonEmptyString(v) || isRegExp(v);
+}
+function unknownKeys(obj, allowed, where, problems) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.has(key))
+            problems.push(`${where}: unknown key "${key}"`);
+    }
+}
+function validateRules(raw, problems) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push('config.rules: must be an array');
+        return [];
+    }
+    raw.forEach((rule, i) => {
+        const where = `rules[${i}]`;
+        if (!isRecord(rule)) {
+            problems.push(`${where}: must be an object`);
+            return;
+        }
+        unknownKeys(rule, RULE_KEYS, where, problems);
+        const m = rule.match;
+        const ok = Array.isArray(m) ? m.length > 0 && m.every(isMatcher) : isMatcher(m);
+        if (!ok) {
+            problems.push(`${where}.match: must be a glob string, a RegExp, or a non-empty array of them`);
+        }
+        if (!Array.isArray(rule.triggers) || !rule.triggers.every(isNonEmptyString)) {
+            problems.push(`${where}.triggers: must be an array of trigger names ([] means "matched, run nothing")`);
+        }
+    });
+    return raw;
+}
+function validateSteps(raw, problems) {
+    if (!Array.isArray(raw)) {
+        problems.push('config.steps: must be an array');
+        return [];
+    }
+    const labels = new Set();
+    const out = [];
+    raw.forEach((step, i) => {
+        const where = `steps[${i}]`;
+        if (!isRecord(step)) {
+            problems.push(`${where}: must be an object`);
+            return;
+        }
+        unknownKeys(step, STEP_KEYS, where, problems);
+        const label = step.label;
+        if (typeof label !== 'string' || !/^\S+$/.test(label)) {
+            problems.push(`${where}.label: must be non-empty with no whitespace`);
+        }
+        else if (labels.has(label)) {
+            problems.push(`${where}.label: duplicate label "${label}"`);
+        }
+        else {
+            labels.add(label);
+        }
+        if (!isNonEmptyString(step.run) && typeof step.run !== 'function') {
+            problems.push(`${where}.run: must be a non-empty string or a function`);
+        }
+        if (!isStringArray(step.when) || step.when.length === 0) {
+            problems.push(`${where}.when: must be a non-empty array of trigger names`);
+        }
+        if (step.if !== undefined && typeof step.if !== 'function') {
+            problems.push(`${where}.if: must be a function`);
+        }
+        if (step.supersededBy !== undefined && !isStringArray(step.supersededBy)) {
+            problems.push(`${where}.supersededBy: must be an array of step labels`);
+        }
+        if (step.policeStderr !== undefined && typeof step.policeStderr !== 'boolean') {
+            problems.push(`${where}.policeStderr: must be a boolean`);
+        }
+        const t = step.timeoutMs;
+        if (t !== undefined && (typeof t !== 'number' || !Number.isFinite(t) || t <= 0)) {
+            problems.push(`${where}.timeoutMs: must be a positive number`);
+        }
+        out.push({
+            ...step,
+            supersededBy: isStringArray(step.supersededBy) ? step.supersededBy : [],
+            policeStderr: step.policeStderr === true,
+            timeoutMs: typeof t === 'number' && t > 0 ? t : DEFAULT_TIMEOUT_MS
+        });
+    });
+    for (const step of out) {
+        for (const target of step.supersededBy) {
+            if (target === step.label) {
+                problems.push(`step "${step.label}": supersededBy names itself`);
+            }
+            else if (!labels.has(target)) {
+                problems.push(`step "${step.label}": supersededBy names unknown step "${target}"`);
+            }
+        }
+    }
+    return out;
+}
+function validateAllowlist(raw, problems) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push('config.stderrAllowlist: must be an array');
+        return [];
+    }
+    raw.forEach((entry, i) => {
+        const where = `stderrAllowlist[${i}]`;
+        if (!isRecord(entry)) {
+            problems.push(`${where}: must be an object`);
+            return;
+        }
+        unknownKeys(entry, ALLOW_KEYS, where, problems);
+        if (!isRegExp(entry.pattern))
+            problems.push(`${where}.pattern: must be a RegExp`);
+        if (!isNonEmptyString(entry.reason))
+            problems.push(`${where}.reason: must be a non-empty string`);
+    });
+    return raw;
+}
+function validateProtection(raw, problems) {
+    if (raw === undefined)
+        return {};
+    if (!isRecord(raw)) {
+        problems.push('config.protection: must be an object');
+        return {};
+    }
+    unknownKeys(raw, PROTECTION_KEYS, 'protection', problems);
+    for (const key of ['branch', 'repo']) {
+        if (raw[key] !== undefined && !isRecord(raw[key])) {
+            problems.push(`protection.${key}: must be an object`);
+        }
+    }
+    return raw;
+}
+export function validateConfig(raw) {
+    if (!isRecord(raw)) {
+        throw new ConfigError([
+            'config must be an object (does chreode.config.ts `export default defineConfig({ ... })`?)'
+        ]);
+    }
+    const problems = [];
+    unknownKeys(raw, TOP_KEYS, 'config', problems);
+    for (const key of ['baseBranch', 'statusContext', 'afterMerge']) {
+        if (raw[key] !== undefined && !isNonEmptyString(raw[key])) {
+            problems.push(`config.${key}: must be a non-empty string`);
+        }
+    }
+    const rules = validateRules(raw.rules, problems);
+    const steps = validateSteps(raw.steps, problems);
+    const stderrAllowlist = validateAllowlist(raw.stderrAllowlist, problems);
+    const protection = validateProtection(raw.protection, problems);
+    if (problems.length > 0)
+        throw new ConfigError(problems);
+    return {
+        baseBranch: raw.baseBranch ?? DEFAULT_BASE_BRANCH,
+        statusContext: raw.statusContext ?? DEFAULT_STATUS_CONTEXT,
+        rules,
+        steps,
+        afterMerge: raw.afterMerge ?? null,
+        stderrAllowlist,
+        protection
+    };
+}

package/dist/git/change-set.d.ts

@@ -0,0 +1,18 @@
+import { type Exec } from '../run/exec.js';
+/** Successful signoffs are recorded as notes under refs/notes/chreode. */
+export declare const NOTES_REF = "chreode";
+export interface BaseInfo {
+    base: string;
+    head: string;
+    source: 'note' | 'merge-base';
+}
+export declare function hasNote(sha: string, exec?: Exec): boolean;
+/** The nearest commit on this branch (not on origin/<baseBranch>) carrying a signoff note;
+ *  else the merge-base with origin/<baseBranch>. */
+export declare function resolveBase(baseBranch: string, exec?: Exec): BaseInfo;
+export declare function resolveRef(ref: string, exec?: Exec): string;
+/** Paths changed between base and head. --no-renames lists both sides of a rename, so a
+ *  file moved out of a rule's reach still fires that rule; deletions are included. */
+export declare function committedPaths(base: string, head: string, exec?: Exec): string[];
+export declare function isWorktree(exec?: Exec): boolean;
+export declare function writeNote(sha: string, ranLabels: readonly string[], exec?: Exec): void;