@mindlace/chreode 0.0.0-stage → 0.2.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,250 @@
-# 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
+npx chreode flake-report       # report logged flakes to GitHub issues (signoff does this itself)
+npx chreode burn-in --base <sha> --head <sha>  # run changed test files N times, retries off
+```
+
+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.
+
+## Flakes
+
+A test that fails and then passes on retry is a flake, and a flake is a bug. chreode records
+each one, files it as a GitHub issue, and fails signoff when the same flake keeps coming back.
+The doctrine and the fix playbook are in [docs/flakes.md](docs/flakes.md).
+
+**1. Record.** Give your runners at least one retry locally and register the reporters. They record only
+tests that pass on a retry, so with retries off nothing is recorded. Both take
+`{ kind?, projects? }`: `kind` (a string, or `(project) => string`) is the issue-title bucket
+(default `'e2e'` for Playwright, the project name or `'unit'` for vitest); `projects` limits
+recording to those runner projects.
+
+```ts
+// playwright.config.ts
+export default defineConfig({
+  retries: 1,
+  use: { trace: 'retain-on-failure' }, // 'on-first-retry' records no trace of the failed attempt
+  reporter: [['list'], ['@mindlace/chreode/reporters/playwright']]
+});
+```
+
+```ts
+// vitest.config.ts (reporters are root-level only)
+import VitestFlakeReporter from '@mindlace/chreode/reporters/vitest';
+
+export default defineConfig({
+  test: { retry: 1, reporters: ['default', new VitestFlakeReporter()] }
+});
+```
+
+Events go to `.chreode/flakes.jsonl` (signoff tells each step the absolute path in
+`CHREODE_FLAKE_LOG`, and the sha under test in `CHREODE_HEAD`). Add `.chreode/` to
+`.gitignore`; when `flakes` is configured, signoff refuses to run otherwise. Registering the
+reporters without a `flakes` block just accumulates events in `.chreode/flakes.jsonl`, unreported.
+Filed issues carry the Playwright trace's local path, valid until the next Playwright run wipes
+`test-results/`, not the trace itself. `playwright` and `vitest` are optional peer
+dependencies: the reporters import only their types.
+
+**2. Ledger.** Add `flakes: {}` to the config. After the steps, pass or fail, signoff gives
+each flaking test one open issue labelled `flake` (the label is created if missing) and adds an
+occurrence comment each time it recurs. At `threshold` occurrences (default 3) signoff fails,
+any run that sees that flake again fails, listing the issue URLs in its failure output (no
+commit status is posted), until the flake is fixed or its issue is labelled `snoozeLabel`
+(default `flake-snoozed`). A run that sees no flake events is silent. A GitHub error is a
+warning: the events not yet recorded stay in the log for the next run.
+`chreode flake-report` runs the same report outside signoff and exits 1 on escalation.
+
+**3. Burn-in.** `burnInStep({ when, timeoutMs? })` adds a step that runs every test file changed since the base
+`repeats` times with retries off, so a new flake fails before it lands rather than after three
+victims. Pass your test steps' triggers as `when`, and place it after them. Its stderr is policed like a
+test step's, so it needs the same `stderrAllowlist` entries:
+
+```ts
+import { burnInStep, defineConfig } from '@mindlace/chreode';
+
+export default defineConfig({
+  steps: [
+    { label: 'test:unit', run: 'npm run test:unit', when: ['unit'], policeStderr: true },
+    { label: 'test:e2e', run: 'npm run test:e2e', when: ['e2e'], policeStderr: true },
+    burnInStep({ when: ['unit', 'e2e'] }) // timeoutMs defaults to 10 minutes
+  ],
+  flakes: {}, // threshold: 3, snoozeLabel: 'flake-snoozed', playbookUrl: chreode's docs/flakes.md on GitHub
+  burnIn: {
+    repeats: 5, // default
+    maxFiles: 12, // default; the overflow is listed, never silently dropped
+    runners: [
+      {
+        name: 'e2e',
+        match: 'e2e/**/*.spec.ts',
+        ignore: 'e2e/helpers/**',
+        // Pin a project: --repeat-each multiplies across every project otherwise.
+        command: (files, n) =>
+          `npx playwright test --project chromium --repeat-each=${n} --retries=0 ${files.join(' ')}`
+      },
+      {
+        name: 'unit',
+        match: 'src/**/*.spec.ts',
+        // vitest has no --repeat-each: return one invocation per repeat.
+        command: (files, n) =>
+          Array.from({ length: n }, () => `npx vitest --run --retry=0 ${files.join(' ')}`)
+      }
+    ]
+  }
+});
+```
+
+A changed file goes to the first runner that matches it and does not `ignore` it; files no
+runner takes are not burned in, and deleted files never are. Commands run from the repo root
+with inherited output; the first failure fails the step and names the files and the command.
+
+## 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.
+
+**`flakes`** (presence turns flake tracking on) and **`burnIn`** are described under
+[Flakes](#flakes). `threshold`, `repeats` and `maxFiles` must be positive integers, and
+`burnIn.runners` must be non-empty.
+
+## License
+
+MIT

package/dist/burn-in/run.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedBurnIn } from '../config/types.js';
+import { type Exec, type Run } from '../run/exec.js';
+export interface BurnInDeps {
+    exec: Exec;
+    /** Inherited stdio: the test runners' own output streams through. */
+    run: Run;
+    mtime: (path: string) => number | null;
+    log: (m: string) => void;
+}
+/**
+ * Run every test file added or changed in base..head `repeats` times with retries off. The
+ * first failure exits 1. All of chreode's own output goes to stdout: this runs inside a
+ * policed signoff step.
+ */
+export declare function runBurnIn(config: ResolvedBurnIn | null, range: {
+    base: string;
+    head: string;
+}, overrides?: Partial<BurnInDeps>): number;

package/dist/burn-in/run.js

@@ -0,0 +1,71 @@
+import { statSync } from 'node:fs';
+import { defaultExec, defaultRun } from '../run/exec.js';
+import { BurnInError, burnInCandidates, burnInCommands, selectBurnIn } from './select.js';
+function mtimeOf(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run every test file added or changed in base..head `repeats` times with retries off. The
+ * first failure exits 1. All of chreode's own output goes to stdout: this runs inside a
+ * policed signoff step.
+ */
+export function runBurnIn(config, range, overrides = {}) {
+    const d = {
+        exec: defaultExec,
+        run: (command) => defaultRun(command),
+        mtime: mtimeOf,
+        log: (m) => console.log(m),
+        ...overrides
+    };
+    if (config === null) {
+        d.log('[chreode] burn-in: chreode.config.ts has no burnIn block; nothing knows how to run tests');
+        return 1;
+    }
+    const candidates = burnInCandidates(range.base, range.head, d.exec, d.mtime);
+    const plan = selectBurnIn(candidates, config);
+    let commands;
+    try {
+        commands = burnInCommands(plan, config.repeats);
+    }
+    catch (err) {
+        if (err instanceof BurnInError) {
+            d.log(`[chreode] ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    const kept = plan.groups.reduce((n, g) => n + g.files.length, 0);
+    if (kept === 0) {
+        d.log('[chreode] burn-in: no changed test files; nothing to burn in');
+        return 0;
+    }
+    d.log(`[chreode] burn-in: ${kept} changed test file(s) × ${config.repeats}, retries off:`);
+    for (const group of plan.groups) {
+        for (const file of group.files)
+            d.log(`  ${file} (${group.runner.name})`);
+    }
+    if (plan.skipped.length > 0) {
+        d.log(`[chreode] burn-in: over the ${config.maxFiles}-file cap, NOT burned in:`);
+        for (const file of plan.skipped)
+            d.log(`  ${file}`);
+    }
+    for (const c of commands) {
+        d.log(`[chreode] burn-in (${c.runner}): ${c.command}`);
+        try {
+            d.run(c.command);
+        }
+        catch {
+            d.log(`\n[chreode] burn-in FAILED (${c.runner}): ${c.files.join(' ')}\n` +
+                `[chreode] command: ${c.command}\n` +
+                `[chreode] A test that flakes at birth flakes forever: fix it before it lands.`);
+            return 1;
+        }
+    }
+    d.log('[chreode] burn-in: every changed test file survived');
+    return 0;
+}

package/dist/burn-in/select.d.ts

@@ -0,0 +1,30 @@
+import type { BurnInRunner, ResolvedBurnIn } from '../config/types.js';
+import type { Exec } from '../run/exec.js';
+export declare class BurnInError extends Error {
+    constructor(message: string);
+}
+/**
+ * Paths added or modified in base..head, newest mtime first so the file cap keeps the most
+ * recently touched. --no-renames lists a rename as delete + add and --diff-filter=d drops
+ * deletions, so a renamed file appears under its new name only. Files missing on disk
+ * (mtime null) are dropped.
+ */
+export declare function burnInCandidates(base: string, head: string, exec: Exec, mtime: (path: string) => number | null): string[];
+/** The first runner that matches the path and does not ignore it. */
+export declare function runnerFor(path: string, runners: readonly BurnInRunner[]): BurnInRunner | null;
+export interface BurnInGroup {
+    runner: BurnInRunner;
+    files: string[];
+}
+export interface BurnInPlan {
+    groups: BurnInGroup[];
+    /** Burnable files past maxFiles: listed, never silently dropped. */
+    skipped: string[];
+}
+export declare function selectBurnIn(paths: readonly string[], config: ResolvedBurnIn): BurnInPlan;
+export interface BurnInCommand {
+    runner: string;
+    files: string[];
+    command: string;
+}
+export declare function burnInCommands(plan: BurnInPlan, repeats: number): BurnInCommand[];

package/dist/burn-in/select.js

@@ -0,0 +1,78 @@
+import { matchesAny } from '../signoff/plan.js';
+export class BurnInError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BurnInError';
+    }
+}
+/**
+ * Paths added or modified in base..head, newest mtime first so the file cap keeps the most
+ * recently touched. --no-renames lists a rename as delete + add and --diff-filter=d drops
+ * deletions, so a renamed file appears under its new name only. Files missing on disk
+ * (mtime null) are dropped.
+ */
+export function burnInCandidates(base, head, exec, mtime) {
+    if (base === head)
+        return [];
+    const out = exec('git', [
+        'diff',
+        '--name-only',
+        '--no-renames',
+        '--diff-filter=d',
+        '-z',
+        `${base}..${head}`
+    ]);
+    return out
+        .split('\0')
+        .filter((p) => p !== '')
+        .map((path) => ({ path, time: mtime(path) }))
+        .filter((c) => c.time !== null)
+        .sort((a, b) => b.time - a.time)
+        .map((c) => c.path);
+}
+/** The first runner that matches the path and does not ignore it. */
+export function runnerFor(path, runners) {
+    for (const runner of runners) {
+        if (!matchesAny(path, runner.match))
+            continue;
+        if (runner.ignore !== undefined && matchesAny(path, runner.ignore))
+            continue;
+        return runner;
+    }
+    return null;
+}
+export function selectBurnIn(paths, config) {
+    const byRunner = new Map();
+    const skipped = [];
+    let kept = 0;
+    for (const path of paths) {
+        const runner = runnerFor(path, config.runners);
+        if (runner === null)
+            continue;
+        if (kept >= config.maxFiles) {
+            skipped.push(path);
+            continue;
+        }
+        byRunner.set(runner, [...(byRunner.get(runner) ?? []), path]);
+        kept += 1;
+    }
+    const groups = config.runners
+        .filter((runner) => byRunner.has(runner))
+        .map((runner) => ({ runner, files: byRunner.get(runner) }));
+    return { groups, skipped };
+}
+export function burnInCommands(plan, repeats) {
+    const out = [];
+    for (const { runner, files } of plan.groups) {
+        const produced = runner.command([...files], repeats);
+        const commands = Array.isArray(produced) ? produced : [produced];
+        const ok = commands.length > 0 && commands.every((c) => typeof c === 'string' && c.trim() !== '');
+        if (!ok) {
+            throw new BurnInError(`burnIn runner "${runner.name}": command() must return a non-empty command or a ` +
+                `non-empty array of them`);
+        }
+        for (const command of commands)
+            out.push({ runner: runner.name, files, command });
+    }
+    return out;
+}

package/dist/burn-in/step.d.ts

@@ -0,0 +1,10 @@
+import { type StepConfig } from '../config/types.js';
+export declare const BURN_IN_LABEL = "burn-in";
+export interface BurnInStepOptions {
+    /** The triggers of your test steps: chreode cannot tell which steps are tests. */
+    when: string[];
+    timeoutMs?: number;
+}
+/** A signoff step that burns in the test files changed since the base. Place it after the
+ *  test steps. */
+export declare function burnInStep(opts: BurnInStepOptions): StepConfig;

package/dist/burn-in/step.js

@@ -0,0 +1,14 @@
+import { DEFAULT_TIMEOUT_MS } from '../config/types.js';
+export const BURN_IN_LABEL = 'burn-in';
+/** A signoff step that burns in the test files changed since the base. Place it after the
+ *  test steps. */
+export function burnInStep(opts) {
+    return {
+        label: BURN_IN_LABEL,
+        run: ({ base, head }) => `npx chreode burn-in --base ${base} --head ${head}`,
+        when: [...opts.when],
+        if: ({ base, head }) => base !== head,
+        policeStderr: true,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,37 @@
+#!/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;
+}
+export interface FlakeReportFlags {
+    config?: string;
+}
+export interface BurnInFlags {
+    base: string;
+    head: 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>;
+    flakeReport: (flags: FlakeReportFlags) => Promise<number>;
+    burnIn: (flags: BurnInFlags) => 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,121 @@
+#!/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 { runBurnIn } from './burn-in/run.js';
+import { CONFIG_FILE, loadConfig } from './config/load.js';
+import { runFlakeReport } from './flakes/report.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)));
+    program
+        .command('flake-report')
+        .description('report logged flakes to GitHub issues; exit 1 if any reached the threshold')
+        .option('--config <path>', `config file (default: <repo root>/${CONFIG_FILE})`)
+        .action(async (flags) => setExit(await actions.flakeReport(flags)));
+    program
+        .command('burn-in')
+        .description('run the test files changed in base..head repeatedly, with retries off')
+        .requiredOption('--base <sha>', 'diff from this commit')
+        .requiredOption('--head <sha>', 'diff to this commit')
+        .option('--config <path>', `config file (default: <repo root>/${CONFIG_FILE})`)
+        .action(async (flags) => setExit(await actions.burnIn(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
+        }),
+        flakeReport: async (flags) => runFlakeReport(await repoConfigLoader(flags.config)()),
+        burnIn: async (flags) => runBurnIn((await repoConfigLoader(flags.config)()).burnIn, {
+            base: flags.base,
+            head: flags.head
+        })
+    }, (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>;