@mindlace/chreode 0.0.0-stage → 0.2.0

package/dist/flakes/log.d.ts

@@ -0,0 +1,39 @@
+/** One retried-then-passed test, as a reporter saw it. */
+export interface FlakeEvent {
+    /** Issue-title bucket, e.g. 'e2e', 'unit', 'client'. */
+    kind: string;
+    runner: 'playwright' | 'vitest';
+    /** Runner project name ('' if none). */
+    project: string;
+    /** Repo-relative, '/'-separated. */
+    file: string;
+    /** Describe chain joined with ' › '. */
+    title: string;
+    /** At most ERROR_LINE_CAP lines, ANSI-stripped. */
+    firstAttemptError: string;
+    /** Playwright trace of the failed attempt. */
+    tracePath?: string;
+    /** CHREODE_HEAD when run under signoff. */
+    sha?: string;
+    /** ISO timestamp. */
+    at: string;
+}
+/** Repo-relative. Not under test-results/: Playwright wipes its outputDir at start and would
+ *  delete events an earlier vitest step wrote. */
+export declare const FLAKE_LOG_FILE = ".chreode/flakes.jsonl";
+export declare const ERROR_LINE_CAP = 40;
+export declare function flakeLogPath(env?: NodeJS.ProcessEnv, cwd?: string): string;
+/** jsonl, append-only: sequential writer processes in one run never clobber each other. */
+export declare function appendFlakeEvent(event: FlakeEvent, logPath: string): void;
+export declare function readFlakeEvents(logPath: string): FlakeEvent[];
+export declare function clearFlakeLog(logPath: string): void;
+export declare function writeFlakeEvents(logPath: string, events: readonly FlakeEvent[]): void;
+export declare function flakeKey(event: FlakeEvent): string;
+/** One report per test per run: the same flake seen in two projects counts once. */
+export declare function dedupeEvents(events: readonly FlakeEvent[]): FlakeEvent[];
+export declare function truncateError(message: string | undefined): string;
+/** The nearest ancestor holding `.git`: a directory in a checkout, a file in a worktree. */
+export declare function findRepoRoot(start: string, exists?: (path: string) => boolean): string | null;
+/** Relative to the git root found from the file itself, so a runner started in a subpackage
+ *  still yields repo paths; '/'-separated. */
+export declare function repoRelative(file: string, cwd?: string, exists?: (path: string) => boolean): string;

package/dist/flakes/log.js

@@ -0,0 +1,89 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { stripAnsi } from '../run/stderr.js';
+/** Repo-relative. Not under test-results/: Playwright wipes its outputDir at start and would
+ *  delete events an earlier vitest step wrote. */
+export const FLAKE_LOG_FILE = '.chreode/flakes.jsonl';
+export const ERROR_LINE_CAP = 40;
+export function flakeLogPath(env = process.env, cwd = process.cwd()) {
+    const fromEnv = env.CHREODE_FLAKE_LOG;
+    return fromEnv !== undefined && fromEnv !== '' ? fromEnv : join(cwd, FLAKE_LOG_FILE);
+}
+/** jsonl, append-only: sequential writer processes in one run never clobber each other. */
+export function appendFlakeEvent(event, logPath) {
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify(event)}\n`);
+}
+const REQUIRED = ['kind', 'runner', 'project', 'file', 'title', 'firstAttemptError', 'at'];
+function isFlakeEvent(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const record = v;
+    return REQUIRED.every((key) => typeof record[key] === 'string');
+}
+export function readFlakeEvents(logPath) {
+    if (!existsSync(logPath))
+        return [];
+    const events = [];
+    for (const line of readFileSync(logPath, 'utf8').split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isFlakeEvent(parsed))
+                events.push(parsed);
+        }
+        catch {
+            // An interrupted write: skip it rather than fail the report.
+        }
+    }
+    return events;
+}
+export function clearFlakeLog(logPath) {
+    rmSync(logPath, { force: true });
+}
+export function writeFlakeEvents(logPath, events) {
+    if (events.length === 0) {
+        clearFlakeLog(logPath);
+        return;
+    }
+    mkdirSync(dirname(logPath), { recursive: true });
+    writeFileSync(logPath, events.map((e) => `${JSON.stringify(e)}\n`).join(''));
+}
+export function flakeKey(event) {
+    return `${event.kind}/${event.file}/${event.title}`;
+}
+/** One report per test per run: the same flake seen in two projects counts once. */
+export function dedupeEvents(events) {
+    const seen = new Set();
+    return events.filter((e) => {
+        const key = flakeKey(e);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+export function truncateError(message) {
+    if (message === undefined || message === '')
+        return '(first attempt error unavailable)';
+    return stripAnsi(message).split('\n').slice(0, ERROR_LINE_CAP).join('\n');
+}
+/** The nearest ancestor holding `.git`: a directory in a checkout, a file in a worktree. */
+export function findRepoRoot(start, exists = existsSync) {
+    let dir = start;
+    for (;;) {
+        if (exists(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Relative to the git root found from the file itself, so a runner started in a subpackage
+ *  still yields repo paths; '/'-separated. */
+export function repoRelative(file, cwd = process.cwd(), exists = existsSync) {
+    const root = findRepoRoot(dirname(file), exists) ?? cwd;
+    return relative(root, file).split(sep).join('/');
+}

package/dist/flakes/phase.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedFlakes } from '../config/types.js';
+import { type FlakeLedgerDeps, type LedgerEntry, type LedgerResult, type RunContext } from './ledger.js';
+export interface FlakePhaseInput {
+    logPath: string;
+    ctx: RunContext;
+    config: ResolvedFlakes;
+    ledger: FlakeLedgerDeps;
+    log: (m: string) => void;
+    warn: (m: string) => void;
+}
+export type FlakePhaseOutcome = {
+    kind: 'none';
+} | {
+    kind: 'reported';
+    result: LedgerResult;
+} | {
+    kind: 'gh-error';
+    message: string;
+    partial: LedgerResult;
+};
+/**
+ * Report the logged flakes to the ledger. Recorded events leave the log; on a GitHub failure
+ * the unrecorded ones stay for the next run (an outage must not block merging, and each event
+ * keeps its own sha and time). Escalations are returned, not acted on: the caller decides.
+ */
+export declare function runFlakePhase(input: FlakePhaseInput): FlakePhaseOutcome;
+/** The failure text for escalated flakes; each issue is listed once, at its highest count. */
+export declare function escalationMessage(escalations: readonly LedgerEntry[], config: ResolvedFlakes): string;
+/**
+ * The single place a phase outcome becomes a pass/fail decision: the failure message when any
+ * flake escalated (including ones recorded before a GitHub error), otherwise undefined.
+ * Signoff and `flake-report` both call this.
+ */
+export declare function escalationFailure(outcome: FlakePhaseOutcome, config: ResolvedFlakes): string | undefined;

package/dist/flakes/phase.js

@@ -0,0 +1,66 @@
+import { LedgerError, processFlakeEvents } from './ledger.js';
+import { clearFlakeLog, readFlakeEvents, writeFlakeEvents } from './log.js';
+function printResult(result, log) {
+    for (const f of result.filed)
+        log(`[chreode] flake filed: ${f.url} ${f.title}`);
+    for (const b of result.bumped) {
+        log(`[chreode] flake seen again (${b.count} occurrences): ${b.url} ${b.title}`);
+    }
+}
+/**
+ * Report the logged flakes to the ledger. Recorded events leave the log; on a GitHub failure
+ * the unrecorded ones stay for the next run (an outage must not block merging, and each event
+ * keeps its own sha and time). Escalations are returned, not acted on: the caller decides.
+ */
+export function runFlakePhase(input) {
+    const events = readFlakeEvents(input.logPath);
+    if (events.length === 0)
+        return { kind: 'none' };
+    input.log(`\n[chreode] flakes: ${events.length} retried-then-passed result(s) recorded`);
+    let result;
+    try {
+        result = processFlakeEvents(events, input.ctx, input.config, input.ledger);
+    }
+    catch (err) {
+        if (!(err instanceof LedgerError))
+            throw err;
+        printResult(err.partial, input.log);
+        writeFlakeEvents(input.logPath, err.remaining);
+        input.warn(`[chreode] flakes: a GitHub call failed (${err.message}); kept ` +
+            `${err.remaining.length} event(s) in ${input.logPath} for the next run`);
+        return { kind: 'gh-error', message: err.message, partial: err.partial };
+    }
+    clearFlakeLog(input.logPath);
+    printResult(result, input.log);
+    return { kind: 'reported', result };
+}
+function dedupeEscalations(escalations) {
+    const byIssue = new Map();
+    for (const e of escalations) {
+        const seen = byIssue.get(e.number);
+        if (!seen || e.count > seen.count)
+            byIssue.set(e.number, e);
+    }
+    return [...byIssue.values()];
+}
+/** The failure text for escalated flakes; each issue is listed once, at its highest count. */
+export function escalationMessage(escalations, config) {
+    const unique = dedupeEscalations(escalations);
+    return [
+        `\n[chreode] FAILED: ${unique.length} flake(s) reached ${config.threshold} occurrences:`,
+        ...unique.map((e) => `  ${e.url} (${e.count} occurrences) ${e.title}`),
+        `[chreode] Fix each one (playbook: ${config.playbookUrl}), or label its issue`,
+        `[chreode] ${config.snoozeLabel} to defer it deliberately.`
+    ].join('\n');
+}
+/**
+ * The single place a phase outcome becomes a pass/fail decision: the failure message when any
+ * flake escalated (including ones recorded before a GitHub error), otherwise undefined.
+ * Signoff and `flake-report` both call this.
+ */
+export function escalationFailure(outcome, config) {
+    if (outcome.kind === 'none')
+        return undefined;
+    const result = outcome.kind === 'reported' ? outcome.result : outcome.partial;
+    return result.escalations.length > 0 ? escalationMessage(result.escalations, config) : undefined;
+}

package/dist/flakes/report.d.ts

@@ -0,0 +1,14 @@
+import { type ResolvedConfig } from '../config/types.js';
+import { type Exec } from '../run/exec.js';
+import type { FlakeLedgerDeps } from './ledger.js';
+export interface FlakeReportDeps {
+    exec: Exec;
+    ledger: FlakeLedgerDeps;
+    logPath: string;
+    log: (m: string) => void;
+    warn: (m: string) => void;
+    error: (m: string) => void;
+}
+/** `chreode flake-report`: the signoff flake phase on its own, for hosted CI or by hand.
+ *  Without a `flakes` block it uses the defaults: running it is the opt-in. */
+export declare function runFlakeReport(config: ResolvedConfig, overrides?: Partial<FlakeReportDeps>): number;

package/dist/flakes/report.js

@@ -0,0 +1,45 @@
+import { resolveFlakes } from '../config/types.js';
+import { defaultExec } from '../run/exec.js';
+import { ghLedgerDeps } from './gh.js';
+import { flakeLogPath } from './log.js';
+import { escalationFailure, runFlakePhase } from './phase.js';
+/** `chreode flake-report`: the signoff flake phase on its own, for hosted CI or by hand.
+ *  Without a `flakes` block it uses the defaults: running it is the opt-in. */
+export function runFlakeReport(config, overrides = {}) {
+    const d = {
+        exec: defaultExec,
+        ledger: ghLedgerDeps(),
+        logPath: flakeLogPath(),
+        log: (m) => console.log(m),
+        warn: (m) => console.warn(m),
+        error: (m) => console.error(m),
+        ...overrides
+    };
+    const flakes = config.flakes ?? resolveFlakes({});
+    const sha = d.exec('git', ['rev-parse', 'HEAD']).trim();
+    let branch = 'HEAD';
+    try {
+        branch = d.exec('git', ['symbolic-ref', '-q', '--short', 'HEAD']).trim();
+    }
+    catch {
+        // Detached, e.g. a CI checkout of a sha.
+    }
+    const outcome = runFlakePhase({
+        logPath: d.logPath,
+        ctx: { branch, sha },
+        config: flakes,
+        ledger: d.ledger,
+        log: d.log,
+        warn: d.warn
+    });
+    if (outcome.kind === 'none') {
+        d.log('[chreode] flakes: no flakes recorded');
+        return 0;
+    }
+    const failure = escalationFailure(outcome, flakes);
+    if (failure !== undefined) {
+        d.error(failure);
+        return 1;
+    }
+    return 0;
+}

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;

package/dist/git/change-set.js

@@ -0,0 +1,42 @@
+import { defaultExec, lines } from '../run/exec.js';
+/** Successful signoffs are recorded as notes under refs/notes/chreode. */
+export const NOTES_REF = 'chreode';
+export function hasNote(sha, exec = defaultExec) {
+    try {
+        exec('git', ['notes', `--ref=${NOTES_REF}`, 'show', sha]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The nearest commit on this branch (not on origin/<baseBranch>) carrying a signoff note;
+ *  else the merge-base with origin/<baseBranch>. */
+export function resolveBase(baseBranch, exec = defaultExec) {
+    const head = exec('git', ['rev-parse', 'HEAD']).trim();
+    const upstream = `origin/${baseBranch}`;
+    for (const sha of lines(exec('git', ['rev-list', '--topo-order', 'HEAD', `^${upstream}`]))) {
+        if (hasNote(sha, exec))
+            return { base: sha, head, source: 'note' };
+    }
+    return { base: exec('git', ['merge-base', 'HEAD', upstream]).trim(), head, source: 'merge-base' };
+}
+export function resolveRef(ref, exec = defaultExec) {
+    return exec('git', ['rev-parse', '--verify', `${ref}^{commit}`]).trim();
+}
+/** 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 function committedPaths(base, head, exec = defaultExec) {
+    if (base === head)
+        return [];
+    const out = exec('git', ['diff', '--name-only', '--no-renames', '-z', `${base}..${head}`]);
+    return out.split('\0').filter((p) => p !== '');
+}
+export function isWorktree(exec = defaultExec) {
+    const [gitDir, commonDir] = lines(exec('git', ['rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir']));
+    return gitDir !== commonDir;
+}
+export function writeNote(sha, ranLabels, exec = defaultExec) {
+    const summary = ranLabels.length > 0 ? ranLabels.join(' ') : 'no-op';
+    exec('git', ['notes', `--ref=${NOTES_REF}`, 'add', '-f', '-m', summary, sha]);
+}

package/dist/git/merge.d.ts

@@ -0,0 +1,21 @@
+import { type Exec } from '../run/exec.js';
+export type MergeOutcome = {
+    kind: 'skipped';
+} | {
+    kind: 'up-to-date';
+} | {
+    kind: 'merged';
+} | {
+    kind: 'conflict';
+} | {
+    kind: 'failed';
+    message: string;
+};
+/**
+ * Fold the latest origin/<baseBranch> into the branch so what is signed off is what will
+ * land. Merge, never rebase: existing SHAs (and their notes) survive and the push stays a
+ * fast-forward. On conflict the merge is left in progress for the user to resolve.
+ */
+export declare function mergeBaseBranch(baseBranch: string, opts: {
+    noMerge: boolean;
+}, exec?: Exec, warn?: (m: string) => void): MergeOutcome;

package/dist/git/merge.js

@@ -0,0 +1,33 @@
+import { defaultExec } from '../run/exec.js';
+/**
+ * Fold the latest origin/<baseBranch> into the branch so what is signed off is what will
+ * land. Merge, never rebase: existing SHAs (and their notes) survive and the push stays a
+ * fast-forward. On conflict the merge is left in progress for the user to resolve.
+ */
+export function mergeBaseBranch(baseBranch, opts, exec = defaultExec, warn = (m) => console.warn(m)) {
+    if (opts.noMerge)
+        return { kind: 'skipped' };
+    const upstream = `origin/${baseBranch}`;
+    try {
+        exec('git', ['fetch', 'origin', baseBranch]);
+    }
+    catch (err) {
+        warn(`[chreode] git fetch origin ${baseBranch} failed (${err.message.trim()}); ` +
+            `continuing with the local view of ${upstream}`);
+    }
+    if (exec('git', ['rev-list', `HEAD..${upstream}`]).trim() === '')
+        return { kind: 'up-to-date' };
+    try {
+        exec('git', ['merge', '--no-edit', upstream]);
+    }
+    catch (err) {
+        try {
+            exec('git', ['rev-parse', '-q', '--verify', 'MERGE_HEAD']);
+            return { kind: 'conflict' };
+        }
+        catch {
+            return { kind: 'failed', message: err.message.trim() };
+        }
+    }
+    return { kind: 'merged' };
+}

package/dist/github/protect.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedConfig } from '../config/types.js';
+import { type Exec } from '../run/exec.js';
+import { type RepoInfo } from './status.js';
+export declare const DEFAULT_BRANCH_PROTECTION: Record<string, unknown>;
+export declare const DEFAULT_REPO_SETTINGS: Record<string, unknown>;
+/** Defaults shallow-merged with config.protection; the status context is always required. */
+export declare function protectionPayloads(config: ResolvedConfig): {
+    branch: Record<string, unknown>;
+    repo: Record<string, unknown>;
+};
+export interface ProtectDeps {
+    exec: Exec;
+    log: (m: string) => void;
+    repo: () => RepoInfo;
+}
+/** Idempotently require the signoff status on the base branch and set squash-only merges. */
+export declare function runProtect(config: ResolvedConfig, opts: {
+    dryRun: boolean;
+    repo: RepoInfo | null;
+}, overrides?: Partial<ProtectDeps>): number;

package/dist/github/protect.js

@@ -0,0 +1,90 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isRecord } from '../config/validate.js';
+import { defaultExec } from '../run/exec.js';
+import { repoInfo } from './status.js';
+export const DEFAULT_BRANCH_PROTECTION = {
+    enforce_admins: true,
+    required_pull_request_reviews: {
+        dismiss_stale_reviews: true,
+        require_code_owner_reviews: false,
+        required_approving_review_count: 0
+    },
+    restrictions: null,
+    allow_force_pushes: false,
+    allow_deletions: false,
+    required_linear_history: true,
+    required_conversation_resolution: false
+};
+export const DEFAULT_REPO_SETTINGS = {
+    allow_squash_merge: true,
+    allow_merge_commit: false,
+    allow_rebase_merge: false,
+    squash_merge_commit_title: 'PR_TITLE',
+    squash_merge_commit_message: 'PR_BODY',
+    delete_branch_on_merge: true
+};
+/** Defaults shallow-merged with config.protection; the status context is always required. */
+export function protectionPayloads(config) {
+    const override = config.protection.branch ?? {};
+    const checks = isRecord(override.required_status_checks) ? override.required_status_checks : {};
+    const extra = Array.isArray(checks.contexts)
+        ? checks.contexts.filter((c) => typeof c === 'string')
+        : [];
+    return {
+        branch: {
+            ...DEFAULT_BRANCH_PROTECTION,
+            ...override,
+            required_status_checks: {
+                strict: true,
+                ...checks,
+                contexts: [...new Set([config.statusContext, ...extra])]
+            }
+        },
+        repo: { ...DEFAULT_REPO_SETTINGS, ...(config.protection.repo ?? {}) }
+    };
+}
+/** Idempotently require the signoff status on the base branch and set squash-only merges. */
+export function runProtect(config, opts, overrides = {}) {
+    const d = {
+        exec: defaultExec,
+        log: (m) => console.log(m),
+        repo: () => repoInfo(defaultExec),
+        ...overrides
+    };
+    let repo = opts.repo;
+    if (repo === null) {
+        try {
+            repo = d.repo();
+        }
+        catch (err) {
+            if (!opts.dryRun)
+                throw err;
+            d.log('[chreode] gh repo view failed; showing payloads for <owner>/<repo>');
+            repo = { owner: '<owner>', name: '<repo>' };
+        }
+    }
+    const { branch, repo: settings } = protectionPayloads(config);
+    const apply = (method, path, body) => {
+        if (opts.dryRun) {
+            d.log(`[dry-run] ${method} ${path}\n${JSON.stringify(body, null, 2)}`);
+            return;
+        }
+        const dir = mkdtempSync(join(tmpdir(), 'chreode-protect-'));
+        const file = join(dir, 'payload.json');
+        writeFileSync(file, JSON.stringify(body));
+        try {
+            d.exec('gh', ['api', '-X', method, path, '--input', file]);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    };
+    const target = `${repo.owner}/${repo.name}`;
+    d.log(`[chreode] protecting ${target} ${config.baseBranch} (dry-run=${opts.dryRun})`);
+    apply('PUT', `repos/${target}/branches/${config.baseBranch}/protection`, branch);
+    apply('PATCH', `repos/${target}`, settings);
+    d.log(`[chreode] ${config.baseBranch} now requires ${config.statusContext}`);
+    return 0;
+}

package/dist/github/status.d.ts

@@ -0,0 +1,24 @@
+import { type Exec } from '../run/exec.js';
+/** GitHub rejects longer descriptions with a 422; truncate rather than fail the post. */
+export declare const STATUS_DESCRIPTION_MAX = 140;
+/** What made a run less than a full signoff; every part is named in the status. */
+export interface Disclosure {
+    /** Steps dropped by --skip. */
+    skipped?: readonly string[];
+    /** Policed steps that passed only because --allow-stderr waived their stderr. */
+    allowedStderr?: readonly string[];
+    /** The --base ref, when the diff did not start from the last signoff. */
+    base?: string | null;
+}
+/** Honest about --skip, --allow-stderr and --base, so a partial run cannot wear the same
+ *  green as a full one. */
+export declare function statusDescription(signer: string, disclosure: Disclosure): string;
+export interface RepoInfo {
+    owner: string;
+    name: string;
+}
+export declare function parseRepo(s: string): RepoInfo;
+export declare function repoInfo(exec?: Exec): RepoInfo;
+export declare function statusArgs(repo: RepoInfo, sha: string, context: string, description: string): string[];
+export declare function postStatus(repo: RepoInfo, sha: string, context: string, description: string, exec?: Exec): void;
+export declare function prUrl(exec?: Exec): string | null;

package/dist/github/status.js

@@ -0,0 +1,54 @@
+import { defaultExec } from '../run/exec.js';
+/** GitHub rejects longer descriptions with a 422; truncate rather than fail the post. */
+export const STATUS_DESCRIPTION_MAX = 140;
+/** Honest about --skip, --allow-stderr and --base, so a partial run cannot wear the same
+ *  green as a full one. */
+export function statusDescription(signer, disclosure) {
+    const { skipped = [], allowedStderr = [], base = null } = disclosure;
+    const parts = [
+        ...(skipped.length > 0 ? [`skipped: ${skipped.join(', ')}`] : []),
+        ...(allowedStderr.length > 0 ? [`allowed stderr: ${allowedStderr.join(', ')}`] : []),
+        ...(base !== null ? [`base=${base}`] : [])
+    ];
+    const desc = parts.length === 0
+        ? `signed off by ${signer}`
+        : `signed off by ${signer} (${parts.join('; ')})`;
+    if (desc.length <= STATUS_DESCRIPTION_MAX)
+        return desc;
+    return `${desc.slice(0, STATUS_DESCRIPTION_MAX - 3)}...`;
+}
+export function parseRepo(s) {
+    const m = /^([\w.-]+)\/([\w.-]+)$/.exec(s);
+    if (!m)
+        throw new Error(`repo must look like owner/name, got "${s}"`);
+    return { owner: m[1], name: m[2] };
+}
+export function repoInfo(exec = defaultExec) {
+    const parsed = JSON.parse(exec('gh', ['repo', 'view', '--json', 'owner,name']));
+    return { owner: parsed.owner.login, name: parsed.name };
+}
+export function statusArgs(repo, sha, context, description) {
+    return [
+        'api',
+        '-X',
+        'POST',
+        `repos/${repo.owner}/${repo.name}/statuses/${sha}`,
+        '-f',
+        'state=success',
+        '-f',
+        `context=${context}`,
+        '-f',
+        `description=${description}`
+    ];
+}
+export function postStatus(repo, sha, context, description, exec = defaultExec) {
+    exec('gh', statusArgs(repo, sha, context, description));
+}
+export function prUrl(exec = defaultExec) {
+    try {
+        return JSON.parse(exec('gh', ['pr', 'view', '--json', 'url'])).url;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { defineConfig } from './config/types.js';
+export { burnInStep, type BurnInStepOptions } from './burn-in/step.js';
+export type { AllowlistEntry, BurnInConfig, BurnInRunner, ChreodeConfig, FlakesConfig, Matcher, ProtectionConfig, RuleConfig, StepConfig, StepContext } from './config/types.js';
+export type { FlakeEvent } from './flakes/log.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { defineConfig } from './config/types.js';
+export { burnInStep } from './burn-in/step.js';

package/dist/lock/machine-lock.d.ts

@@ -0,0 +1,40 @@
+export declare const LOCK_STALE_MS = 30000;
+export declare const LOCK_UPDATE_MS = 10000;
+export declare const LOCK_POLL_MS = 2000;
+export declare const LOCK_MAX_WAIT_MS: number;
+export type Release = () => Promise<void>;
+export interface MachineLock {
+    /** Resolves to a release fn once held; while held elsewhere, logs once and polls. */
+    acquire(): Promise<Release>;
+}
+export interface RetryingLockDeps {
+    /** One attempt; must reject with an `ELOCKED`-coded error when held. */
+    tryLock: () => Promise<Release>;
+    label: string;
+    lockPath: string;
+    pollMs: number;
+    maxWaitMs: number;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    log: (msg: string) => void;
+    /** One-line remedy appended to the timeout error. */
+    hint?: string;
+}
+/** Poll-until-free around a one-shot lock. All I/O injected so the retry/log/timeout logic
+ *  is testable without the filesystem or real timers. */
+export declare function createRetryingLock(deps: RetryingLockDeps): MachineLock;
+/** proper-lockfile at a fixed path, with stale-steal. */
+export declare function fileLock(opts: {
+    label: string;
+    lockPath: string;
+    staleMs?: number;
+    updateMs?: number;
+    pollMs?: number;
+    maxWaitMs?: number;
+    hint?: string;
+    log?: (msg: string) => void;
+}): MachineLock;
+/** `CHREODE_LOCK_PATH` exists for test isolation: chreode's own suite runs `chreode signoff`
+ *  while an outer signoff holds the real lock. */
+export declare function defaultLockPath(env?: NodeJS.ProcessEnv): string;
+export declare function signoffLock(env?: NodeJS.ProcessEnv): MachineLock;