@mindlace/chreode 0.0.0-stage → 0.2.0

package/dist/signoff/plan.js

@@ -0,0 +1,112 @@
+import picomatch from 'picomatch';
+export class PlanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PlanError';
+    }
+}
+function tester(m) {
+    if (typeof m === 'string')
+        return picomatch(m, { dot: true });
+    return (path) => {
+        // A /g or /y RegExp carries lastIndex between calls; reset so every path is tested fresh.
+        m.lastIndex = 0;
+        return m.test(path);
+    };
+}
+export function matchesAny(path, matchers) {
+    return (Array.isArray(matchers) ? matchers : [matchers]).some((m) => tester(m)(path));
+}
+export function matchRule(path, rules) {
+    for (const rule of rules) {
+        if (matchesAny(path, rule.match))
+            return rule;
+    }
+    return null;
+}
+export function allTriggers(steps) {
+    return [...new Set(steps.flatMap((s) => s.when))].sort();
+}
+/** Rules can only make a run smaller by matching: an unmatched path fires everything. */
+export function fireTriggers(paths, rules, steps) {
+    const fired = new Set();
+    const unmatched = [];
+    for (const path of paths) {
+        const rule = matchRule(path, rules);
+        const triggers = rule === null ? allTriggers(steps) : rule.triggers;
+        if (rule === null)
+            unmatched.push(path);
+        for (const t of triggers)
+            fired.add(t);
+    }
+    return { triggers: [...fired].sort(), unmatched };
+}
+export function planSignoff(config, input) {
+    const known = config.steps.map((s) => s.label);
+    const unknownSkips = input.skip.filter((l) => !known.includes(l));
+    if (unknownSkips.length > 0) {
+        throw new PlanError(`--skip names unknown step(s): ${unknownSkips.join(', ')} (known: ${known.join(', ')})`);
+    }
+    const { triggers, unmatched } = input.full
+        ? { triggers: allTriggers(config.steps), unmatched: [] }
+        : fireTriggers(input.paths, config.rules, config.steps);
+    const ctx = {
+        base: input.base,
+        head: input.head,
+        paths: input.paths,
+        triggers,
+        isWorktree: input.isWorktree
+    };
+    const fired = new Set(triggers);
+    const skipSet = new Set(input.skip);
+    const skipped = [];
+    const skippedByFlag = [];
+    const survivors = [];
+    for (const step of config.steps) {
+        if (!step.when.some((t) => fired.has(t))) {
+            skipped.push({ label: step.label, reason: { kind: 'not-triggered' } });
+        }
+        else if (step.if && !step.if(ctx)) {
+            skipped.push({ label: step.label, reason: { kind: 'if-false' } });
+        }
+        else if (skipSet.has(step.label)) {
+            skipped.push({ label: step.label, reason: { kind: 'skip-flag' } });
+            skippedByFlag.push(step.label);
+        }
+        else {
+            survivors.push(step);
+        }
+    }
+    const surviving = new Set(survivors.map((s) => s.label));
+    const steps = [];
+    for (const step of survivors) {
+        const by = step.supersededBy.find((l) => surviving.has(l));
+        if (by !== undefined) {
+            skipped.push({ label: step.label, reason: { kind: 'superseded', by } });
+            continue;
+        }
+        const command = typeof step.run === 'function' ? step.run(ctx) : step.run;
+        if (typeof command !== 'string' || command.trim() === '') {
+            throw new PlanError(`step "${step.label}": run() must return a non-empty command`);
+        }
+        steps.push({
+            label: step.label,
+            command,
+            policeStderr: step.policeStderr,
+            timeoutMs: step.timeoutMs
+        });
+    }
+    return { triggers, unmatched, steps, skipped, skippedByFlag };
+}
+export function describeSkip(reason) {
+    switch (reason.kind) {
+        case 'not-triggered':
+            return 'no relevant changes';
+        case 'if-false':
+            return '`if` returned false';
+        case 'skip-flag':
+            return '--skip';
+        case 'superseded':
+            return `superseded by ${reason.by}`;
+    }
+}

package/dist/signoff/preconditions.d.ts

@@ -0,0 +1,12 @@
+import { type Exec } from '../run/exec.js';
+export declare class PreconditionError extends Error {
+    constructor(message: string);
+}
+export interface Preconditions {
+    branch: string;
+    /** git user.email: named in the status description. */
+    signer: string;
+}
+export declare function checkPreconditions(baseBranch: string, exec?: Exec, opts?: {
+    flakes: boolean;
+}): Preconditions;

package/dist/signoff/preconditions.js

@@ -0,0 +1,59 @@
+import { FLAKE_LOG_FILE } from '../flakes/log.js';
+import { defaultExec } from '../run/exec.js';
+export class PreconditionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PreconditionError';
+    }
+}
+export function checkPreconditions(baseBranch, exec = defaultExec, opts = { flakes: false }) {
+    if (exec('git', ['status', '--porcelain']).trim() !== '') {
+        throw new PreconditionError('working tree is dirty; commit or stash before signing off');
+    }
+    let branch;
+    try {
+        branch = exec('git', ['symbolic-ref', '-q', '--short', 'HEAD']).trim();
+    }
+    catch {
+        throw new PreconditionError('HEAD is detached; check out a branch before signing off');
+    }
+    if (branch === baseBranch) {
+        throw new PreconditionError(`on ${baseBranch} itself; signoff is for branches that merge into ${baseBranch}`);
+    }
+    let behind = '';
+    try {
+        behind = exec('git', ['rev-list', 'HEAD..@{u}']).trim();
+    }
+    catch {
+        // No upstream yet: nothing to be behind.
+    }
+    if (behind !== '') {
+        throw new PreconditionError('HEAD is behind its upstream; pull before signing off');
+    }
+    if (opts.flakes) {
+        try {
+            exec('git', ['check-ignore', '-q', FLAKE_LOG_FILE]);
+        }
+        catch {
+            throw new PreconditionError('`flakes` is configured but .chreode/ is not gitignored (the flake log would dirty ' +
+                'the tree); add the line `.chreode/` to .gitignore');
+        }
+    }
+    try {
+        exec('gh', ['auth', 'status']);
+    }
+    catch {
+        throw new PreconditionError('gh is not authenticated; run `gh auth login`');
+    }
+    let signer = '';
+    try {
+        signer = exec('git', ['config', 'user.email']).trim();
+    }
+    catch {
+        // Reported below.
+    }
+    if (signer === '') {
+        throw new PreconditionError('git config user.email is unset; the status description names the signer');
+    }
+    return { branch, signer };
+}

package/dist/signoff/run.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedConfig } from '../config/types.js';
+import type { FlakeLedgerDeps } from '../flakes/ledger.js';
+import { type MachineLock } from '../lock/machine-lock.js';
+import { type Exec, type Run } from '../run/exec.js';
+import { type StepOutcome } from '../run/step.js';
+import { type Plan, type PlannedStep } from './plan.js';
+import { type TailEffects } from './tail.js';
+export interface SignoffOptions {
+    full: boolean;
+    dryRun: boolean;
+    noMerge: boolean;
+    noPush: boolean;
+    allowStderr: boolean;
+    base: string | null;
+    skip: string[];
+}
+export interface SignoffDeps {
+    exec: Exec;
+    run: Run;
+    lock: MachineLock;
+    runStep: (step: PlannedStep) => Promise<StepOutcome>;
+    tail: TailEffects;
+    /** Files, bumps and lists flake issues. */
+    ledger: FlakeLedgerDeps;
+    /** Absolute path of the flake log; steps see it as CHREODE_FLAKE_LOG. */
+    flakeLog: string;
+    log: (m: string) => void;
+    warn: (m: string) => void;
+    error: (m: string) => void;
+}
+export declare function printPlan(plan: Plan, where: {
+    base: string;
+    head: string;
+    paths: readonly string[];
+    full: boolean;
+}, log: (m: string) => void): void;
+/**
+ * `loadConfig` is called once up front and again after a merge that changed the branch, so
+ * a merge that brings in a new chreode.config.ts is planned and run under that config.
+ */
+export declare function runSignoff(loadConfig: () => Promise<ResolvedConfig>, opts: SignoffOptions, overrides?: Partial<SignoffDeps>): Promise<number>;

package/dist/signoff/run.js

@@ -0,0 +1,226 @@
+import { resolve } from 'node:path';
+import { ghLedgerDeps } from '../flakes/gh.js';
+import { FLAKE_LOG_FILE } from '../flakes/log.js';
+import { escalationFailure, runFlakePhase } from '../flakes/phase.js';
+import { committedPaths, isWorktree, resolveBase, resolveRef } from '../git/change-set.js';
+import { mergeBaseBranch } from '../git/merge.js';
+import { repoInfo } from '../github/status.js';
+import { signoffLock } from '../lock/machine-lock.js';
+import { defaultExec, defaultRun } from '../run/exec.js';
+import { StepFailure, runStep, runSteps } from '../run/step.js';
+import { PlanError, describeSkip, planSignoff } from './plan.js';
+import { PreconditionError, checkPreconditions } from './preconditions.js';
+import { defaultTailEffects, runTail } from './tail.js';
+function defaultDeps(config, opts, stepEnv = {}) {
+    // Children can detect the gate (e.g. to quiet build-tool stderr) via CHREODE_SIGNOFF=1.
+    const env = { ...process.env, CHREODE_SIGNOFF: '1', ...stepEnv };
+    let repo = null;
+    const getRepo = () => (repo ??= repoInfo(defaultExec));
+    return {
+        exec: defaultExec,
+        run: (command) => defaultRun(command, env),
+        lock: signoffLock(),
+        runStep: (step) => runStep(step, { allowStderr: opts.allowStderr, allowlist: config.stderrAllowlist, env }),
+        tail: defaultTailEffects(getRepo, config.statusContext),
+        ledger: ghLedgerDeps(defaultExec),
+        // The CLI has already chdir'd to the repo root.
+        flakeLog: resolve(FLAKE_LOG_FILE),
+        log: (m) => console.log(m),
+        warn: (m) => console.warn(m),
+        error: (m) => console.error(m)
+    };
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Why the checkout no longer matches `head`, or null when it is clean and unmoved. */
+function checkoutChange(head, exec) {
+    if (exec('git', ['status', '--porcelain']).trim() !== '')
+        return 'the working tree is dirty';
+    const now = exec('git', ['rev-parse', 'HEAD']).trim();
+    return now !== head ? `HEAD moved to ${now}` : null;
+}
+export function printPlan(plan, where, log) {
+    log(`[chreode] base=${where.base} head=${where.head}${where.full ? ' (--full)' : ''}`);
+    log(`[chreode] changed paths (${where.paths.length}):`);
+    for (const p of where.paths)
+        log(`  ${p}`);
+    if (plan.unmatched.length > 0) {
+        log(`[chreode] matched no rule, so every trigger fired: ${plan.unmatched.join(', ')}`);
+    }
+    log(`[chreode] triggers: ${plan.triggers.length > 0 ? plan.triggers.join(', ') : '(none)'}`);
+    log(`[chreode] plan: ${plan.steps.length > 0 ? plan.steps.map((s) => s.label).join(', ') : '(no steps: a no-op signoff)'}`);
+    for (const { label, reason } of plan.skipped) {
+        log(`[chreode] skipping ${label} (${describeSkip(reason)})`);
+    }
+}
+/**
+ * `loadConfig` is called once up front and again after a merge that changed the branch, so
+ * a merge that brings in a new chreode.config.ts is planned and run under that config.
+ */
+export async function runSignoff(loadConfig, opts, overrides = {}) {
+    let config = await loadConfig();
+    let d = { ...defaultDeps(config, opts), ...overrides };
+    const baseBranch = config.baseBranch;
+    // 1. Preconditions
+    let pre;
+    try {
+        pre = checkPreconditions(baseBranch, d.exec, { flakes: config.flakes !== null });
+    }
+    catch (err) {
+        if (err instanceof PreconditionError) {
+            d.error(`[chreode] ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    // 2. Merge
+    const merge = mergeBaseBranch(baseBranch, { noMerge: opts.noMerge }, d.exec, d.warn);
+    if (merge.kind === 'conflict') {
+        d.error(`\n[chreode] merging origin/${baseBranch} hit a conflict. The merge is in progress.\n` +
+            `Resolve it, run \`git commit --no-edit\`, then re-run signoff.\n` +
+            `To bail out: \`git merge --abort\`.`);
+        return 1;
+    }
+    if (merge.kind === 'failed') {
+        d.error(`[chreode] merging origin/${baseBranch} failed: ${merge.message}`);
+        return 1;
+    }
+    if (merge.kind === 'merged') {
+        d.log(`[chreode] merged origin/${baseBranch} into ${pre.branch}`);
+        if (config.afterMerge) {
+            d.log(`[chreode] afterMerge: ${config.afterMerge}`);
+            const before = d.exec('git', ['rev-parse', 'HEAD']).trim();
+            try {
+                d.run(config.afterMerge);
+            }
+            catch {
+                d.error('[chreode] afterMerge failed');
+                return 1;
+            }
+            const moved = checkoutChange(before, d.exec);
+            if (moved) {
+                d.error(`[chreode] afterMerge changed the checkout (${moved}); commit the change and re-run signoff.`);
+                return 1;
+            }
+        }
+        // The merge may have changed the config itself: plan under what is now checked out.
+        try {
+            config = await loadConfig();
+        }
+        catch (err) {
+            d.error(`[chreode] the config merged in from origin/${baseBranch} failed to load: ${message(err)}\n` +
+                `Fix it in a commit on this branch, then re-run signoff.`);
+            return 1;
+        }
+        d = { ...defaultDeps(config, opts), ...overrides };
+    }
+    // 3. Resolve base
+    const head = d.exec('git', ['rev-parse', 'HEAD']).trim();
+    let base;
+    let source;
+    try {
+        if (opts.base !== null) {
+            base = resolveRef(opts.base, d.exec);
+            source = 'flag';
+        }
+        else {
+            ({ base, source } = resolveBase(baseBranch, d.exec));
+        }
+    }
+    catch (err) {
+        d.error(`[chreode] could not resolve the base: ${message(err)}`);
+        return 1;
+    }
+    if (!opts.full && base === head) {
+        d.log(source === 'note'
+            ? `[chreode] already signed off at ${head}; nothing to do (--full re-runs everything)`
+            : `[chreode] nothing to sign off: ${base} is HEAD`);
+        return 0;
+    }
+    // 4. Plan
+    const paths = committedPaths(base, head, d.exec);
+    let plan;
+    try {
+        plan = planSignoff(config, {
+            paths,
+            full: opts.full,
+            skip: opts.skip,
+            base,
+            head,
+            isWorktree: isWorktree(d.exec)
+        });
+    }
+    catch (err) {
+        if (err instanceof PlanError) {
+            d.error(`[chreode] ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    printPlan(plan, { base, head, paths, full: opts.full }, d.log);
+    if (opts.dryRun) {
+        d.log('[chreode] --dry-run: stopping before the run');
+        return 0;
+    }
+    // 5. Run. Steps learn the sha under test and where reporters record flakes.
+    d = {
+        ...defaultDeps(config, opts, { CHREODE_HEAD: head, CHREODE_FLAKE_LOG: d.flakeLog }),
+        ...overrides
+    };
+    let allowedStderr = [];
+    let stepsFailed = false;
+    try {
+        allowedStderr = await runSteps(plan.steps, d.lock, d.runStep);
+    }
+    catch (err) {
+        if (!(err instanceof StepFailure))
+            d.error(`[chreode] ${message(err)}`);
+        stepsFailed = true;
+    }
+    // 6. Flakes: after the steps, passed or failed, so a flake is charged to the run that saw
+    //    it. Network, not machine load: the lock is already released.
+    let escalated = false;
+    if (config.flakes !== null) {
+        const outcome = runFlakePhase({
+            logPath: d.flakeLog,
+            ctx: { branch: pre.branch, sha: head },
+            config: config.flakes,
+            ledger: d.ledger,
+            log: d.log,
+            warn: d.warn
+        });
+        const failure = escalationFailure(outcome, config.flakes);
+        if (failure !== undefined) {
+            d.error(failure);
+            escalated = true;
+        }
+    }
+    if (stepsFailed || escalated)
+        return 1;
+    // What was tested must be exactly HEAD.
+    const changed = checkoutChange(head, d.exec);
+    if (changed) {
+        d.error(`[chreode] the steps changed the checkout (${changed}); ` +
+            `commit the change and re-run signoff. Nothing was posted.`);
+        return 1;
+    }
+    // 7. Tail
+    try {
+        runTail({
+            sha: head,
+            signer: pre.signer,
+            noPush: opts.noPush,
+            ranLabels: plan.steps.map((s) => s.label),
+            skippedByFlag: plan.skippedByFlag,
+            allowedStderr,
+            baseFlag: opts.base,
+            context: config.statusContext
+        }, d.tail, d.log);
+    }
+    catch (err) {
+        d.error(`[chreode] ${message(err)}`);
+        return 1;
+    }
+    return 0;
+}

package/dist/signoff/tail.d.ts

@@ -0,0 +1,32 @@
+import { type RepoInfo } from '../github/status.js';
+import { type Exec, type Run } from '../run/exec.js';
+export interface TailEffects {
+    push(): void;
+    postStatus(sha: string, description: string): void;
+    writeNote(sha: string, ranLabels: readonly string[]): void;
+    prUrl(): string | null;
+}
+export interface TailWork {
+    sha: string;
+    signer: string;
+    noPush: boolean;
+    ranLabels: readonly string[];
+    skippedByFlag: readonly string[];
+    /** Policed steps that passed only because --allow-stderr waived their stderr. */
+    allowedStderr: readonly string[];
+    /** The --base ref as given, or null when the base came from the last signoff. */
+    baseFlag: string | null;
+    context: string;
+}
+/** Why this run must not become an incremental base: the note means "everything the
+ *  changes since the last note needed passed", and a partial run cannot vouch for that. */
+export declare function noteWithheldReasons(work: TailWork): string[];
+/**
+ * After every step passed: push, post the status, then write the note. The note is the
+ * incremental cache ("this commit is signed off"), so it goes last: a failed post must not
+ * leave a note that makes the next run a no-op with no status on GitHub. A partial run
+ * (--skip, --base, or stderr waived by --allow-stderr) posts a status that says so but
+ * writes no note, so the next signoff diffs from the last full one.
+ */
+export declare function runTail(work: TailWork, effects: TailEffects, log?: (m: string) => void): void;
+export declare function defaultTailEffects(repo: () => RepoInfo, context: string, exec?: Exec, run?: Run): TailEffects;

package/dist/signoff/tail.js

@@ -0,0 +1,55 @@
+import { writeNote } from '../git/change-set.js';
+import { postStatus, prUrl, statusDescription } from '../github/status.js';
+import { defaultExec, defaultRun } from '../run/exec.js';
+/** Why this run must not become an incremental base: the note means "everything the
+ *  changes since the last note needed passed", and a partial run cannot vouch for that. */
+export function noteWithheldReasons(work) {
+    return [
+        ...(work.skippedByFlag.length > 0 ? [`--skip ${work.skippedByFlag.join(', ')}`] : []),
+        ...(work.allowedStderr.length > 0
+            ? [`--allow-stderr waived ${work.allowedStderr.join(', ')}`]
+            : []),
+        ...(work.baseFlag !== null ? [`--base ${work.baseFlag}`] : [])
+    ];
+}
+/**
+ * After every step passed: push, post the status, then write the note. The note is the
+ * incremental cache ("this commit is signed off"), so it goes last: a failed post must not
+ * leave a note that makes the next run a no-op with no status on GitHub. A partial run
+ * (--skip, --base, or stderr waived by --allow-stderr) posts a status that says so but
+ * writes no note, so the next signoff diffs from the last full one.
+ */
+export function runTail(work, effects, log = (m) => console.log(m)) {
+    if (work.noPush) {
+        log('[chreode] --no-push: not pushing (the commit must already be on origin)');
+    }
+    else {
+        log('\n[chreode] git push -u origin HEAD');
+        effects.push();
+    }
+    effects.postStatus(work.sha, statusDescription(work.signer, {
+        skipped: work.skippedByFlag,
+        allowedStderr: work.allowedStderr,
+        base: work.baseFlag
+    }));
+    log(`[chreode] ${work.context} = success posted on ${work.sha}`);
+    const withheld = noteWithheldReasons(work);
+    if (withheld.length === 0) {
+        effects.writeNote(work.sha, work.ranLabels);
+    }
+    else {
+        log(`[chreode] not writing the signoff note (partial run: ${withheld.join('; ')}); ` +
+            `the next signoff diffs from the last full one`);
+    }
+    const url = effects.prUrl();
+    if (url)
+        log(`[chreode] PR: ${url}`);
+}
+export function defaultTailEffects(repo, context, exec = defaultExec, run = defaultRun) {
+    return {
+        push: () => run('git push -u origin HEAD'),
+        postStatus: (sha, description) => postStatus(repo(), sha, context, description, exec),
+        writeNote: (sha, labels) => writeNote(sha, labels, exec),
+        prUrl: () => prUrl(exec)
+    };
+}

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@mindlace/chreode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A deterministic, selective, unavoidable local-CI gate for agent-written code",
+  "keywords": [
+    "ci",
+    "signoff",
+    "git",
+    "github",
+    "agents",
+    "gate"
+  ],
+  "license": "MIT",
+  "author": "Ethan Fremen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mindlace/chreode.git"
+  },
+  "homepage": "https://github.com/mindlace/chreode#readme",
+  "bugs": {
+    "url": "https://github.com/mindlace/chreode/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "chreode": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./reporters/playwright": {
+      "types": "./dist/reporters/playwright.d.ts",
+      "default": "./dist/reporters/playwright.js"
+    },
+    "./reporters/vitest": {
+      "types": "./dist/reporters/vitest.d.ts",
+      "default": "./dist/reporters/vitest.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "prettier --check . && eslint .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "signoff": "npm run build && node dist/cli.js signoff",
+    "protect": "npm run build && node dist/cli.js protect"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "jiti": "^2.7.0",
+    "picomatch": "^4.0.7",
+    "proper-lockfile": "^4.1.2"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40",
+    "vitest": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.64.0",
+    "@types/node": "^24.0.0",
+    "@types/picomatch": "^4.0.3",
+    "@types/proper-lockfile": "^4.1.4",
+    "eslint": "^10.8.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.7.0",
+    "playwright": "^1.64.0",
+    "prettier": "^3.9.6",
+    "tsx": "^4.23.1",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^4.1.10"
+  }
+}