@mindlace/chreode 0.0.0-stage → 0.1.0

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,2 @@
+export { defineConfig } from './config/types.js';
+export type { AllowlistEntry, ChreodeConfig, Matcher, ProtectionConfig, RuleConfig, StepConfig, StepContext } from './config/types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { defineConfig } from './config/types.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;

package/dist/lock/machine-lock.js

@@ -0,0 +1,76 @@
+import os from 'node:os';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+// Steps hold gigabytes. Several agents in parallel worktrees running a suite at once swap
+// the machine to death and produce spurious failures, and the contended resource is the
+// machine, not the repo, so every chreode repo on the box shares ONE lock.
+//
+// A live holder refreshes the lock mtime every UPDATE; a holder that dies stops refreshing,
+// so the lock goes stale after STALE and the next waiter steals it.
+export const LOCK_STALE_MS = 30_000;
+export const LOCK_UPDATE_MS = 10_000;
+export const LOCK_POLL_MS = 2_000;
+export const LOCK_MAX_WAIT_MS = 60 * 60_000;
+/** 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 function createRetryingLock(deps) {
+    return {
+        async acquire() {
+            const deadline = deps.now() + deps.maxWaitMs;
+            let logged = false;
+            for (;;) {
+                try {
+                    return await deps.tryLock();
+                }
+                catch (err) {
+                    if (err.code !== 'ELOCKED')
+                        throw err;
+                    if (!logged) {
+                        deps.log(`[chreode] another run holds the ${deps.label} lock; waiting…`);
+                        logged = true;
+                    }
+                    if (deps.now() >= deadline) {
+                        const hint = deps.hint ? ` ${deps.hint}` : '';
+                        throw new Error(`[chreode] timed out after ${Math.round(deps.maxWaitMs / 60_000)}m waiting for ` +
+                            `the ${deps.label} lock (${deps.lockPath}).${hint}`, { cause: err });
+                    }
+                    await deps.sleep(deps.pollMs);
+                }
+            }
+        }
+    };
+}
+/** proper-lockfile at a fixed path, with stale-steal. */
+export function fileLock(opts) {
+    return createRetryingLock({
+        tryLock: () => lockfile.lock(opts.lockPath, {
+            realpath: false, // the target need not exist; the lock is the `${lockPath}.lock` dir
+            stale: opts.staleMs ?? LOCK_STALE_MS,
+            update: opts.updateMs ?? LOCK_UPDATE_MS,
+            retries: 0, // we own the retry loop so we can log once and bound the wait
+            // The default handler throws from a timer: a stalled mtime refresh (laptop sleep) would crash
+            // chreode uncaught and orphan the detached step group. Log and carry on instead.
+            onCompromised: (err) => console.error(`[chreode] lock compromised: ${err.message}`)
+        }),
+        label: opts.label,
+        lockPath: opts.lockPath,
+        pollMs: opts.pollMs ?? LOCK_POLL_MS,
+        maxWaitMs: opts.maxWaitMs ?? LOCK_MAX_WAIT_MS,
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        log: opts.log ?? ((msg) => console.log(msg)),
+        hint: opts.hint
+    });
+}
+/** `CHREODE_LOCK_PATH` exists for test isolation: chreode's own suite runs `chreode signoff`
+ *  while an outer signoff holds the real lock. */
+export function defaultLockPath(env = process.env) {
+    return env.CHREODE_LOCK_PATH || path.join(os.tmpdir(), 'chreode-signoff.lock');
+}
+export function signoffLock(env = process.env) {
+    return fileLock({
+        label: 'signoff',
+        lockPath: defaultLockPath(env),
+        hint: 'The holder is another chreode signoff on this machine (any repo). Do not kill it; wait it out.'
+    });
+}

package/dist/run/exec.d.ts

@@ -0,0 +1,8 @@
+/** Run a program (no shell) and return its stdout. Throws on non-zero exit; the error
+ *  message carries the program's stderr. */
+export type Exec = (file: string, args: readonly string[]) => string;
+export declare const defaultExec: Exec;
+/** Run a shell command with inherited stdio (for long, chatty commands). */
+export type Run = (command: string, env?: NodeJS.ProcessEnv) => void;
+export declare const defaultRun: Run;
+export declare function lines(out: string): string[];

package/dist/run/exec.js

@@ -0,0 +1,15 @@
+import { execFileSync, execSync } from 'node:child_process';
+export const defaultExec = (file, args) => execFileSync(file, [...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024
+});
+export const defaultRun = (command, env) => {
+    execSync(command, { stdio: 'inherit', env: env ?? process.env });
+};
+export function lines(out) {
+    return out
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}

package/dist/run/stderr.d.ts

@@ -0,0 +1,21 @@
+import type { AllowlistEntry } from '../config/types.js';
+/** Classify captured stderr line by line: blank and allowlisted lines are benign,
+ *  everything else is returned ANSI-stripped. */
+export declare function policeStderr(buffer: string, allowlist: readonly AllowlistEntry[]): {
+    offendingLines: string[];
+};
+export type PolicedOutcome = {
+    kind: 'pass';
+} | {
+    kind: 'fail-exit';
+    rawStderr: string;
+} | {
+    kind: 'fail-stderr';
+    offendingLines: string[];
+};
+/** A non-zero/null exit is a real failure (surface everything). A clean exit with
+ *  non-allowlisted stderr is a policy failure (surface just the offending lines). */
+export declare function decidePolicedOutcome(result: {
+    code: number | null;
+    stderr?: string;
+}, allowlist: readonly AllowlistEntry[]): PolicedOutcome;

package/dist/run/stderr.js

@@ -0,0 +1,27 @@
+// ANSI SGR color codes must not defeat allowlist matching. The escape character is built at
+// runtime so no control character appears in source (keeps no-control-regex quiet).
+const ANSI_SGR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+/** Classify captured stderr line by line: blank and allowlisted lines are benign,
+ *  everything else is returned ANSI-stripped. */
+export function policeStderr(buffer, allowlist) {
+    const offendingLines = buffer
+        .split(/\r?\n/)
+        .map((line) => line.replace(ANSI_SGR, ''))
+        .filter((line) => line.trim() !== '')
+        .filter((line) => !allowlist.some((entry) => {
+        entry.pattern.lastIndex = 0;
+        return entry.pattern.test(line);
+    }));
+    return { offendingLines };
+}
+/** A non-zero/null exit is a real failure (surface everything). A clean exit with
+ *  non-allowlisted stderr is a policy failure (surface just the offending lines). */
+export function decidePolicedOutcome(result, allowlist) {
+    const buffer = result.stderr ?? '';
+    if (result.code !== 0)
+        return { kind: 'fail-exit', rawStderr: buffer };
+    const { offendingLines } = policeStderr(buffer, allowlist);
+    if (offendingLines.length > 0)
+        return { kind: 'fail-stderr', offendingLines };
+    return { kind: 'pass' };
+}

package/dist/run/step.d.ts

@@ -0,0 +1,55 @@
+import type { AllowlistEntry } from '../config/types.js';
+import type { MachineLock } from '../lock/machine-lock.js';
+import type { PlannedStep } from '../signoff/plan.js';
+export interface RunResult {
+    /** Exit code, or null when killed by a signal. */
+    code: number | null;
+    timedOut: boolean;
+    interrupted: boolean;
+    /** Present only when captureStderr was set. */
+    stderr?: string;
+}
+export interface SignalSource {
+    on(event: 'SIGINT' | 'SIGTERM', fn: () => void): unknown;
+    off(event: 'SIGINT' | 'SIGTERM', fn: () => void): unknown;
+}
+export interface RunOptions {
+    /** stdout stays live; stderr is piped, buffered and returned. */
+    captureStderr?: boolean;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    /** Where SIGINT/SIGTERM arrive; defaults to the process. Injectable for tests. */
+    signals?: SignalSource;
+}
+/** After forwarding SIGINT/SIGTERM, how long a step gets to exit before its group is SIGKILLed. */
+export declare const INTERRUPT_GRACE_MS = 3000;
+/**
+ * Run a shell command with a hard wall-clock timeout. The command runs in its OWN process
+ * group (detached) so a timeout can SIGKILL the whole tree, not just the wrapping shell.
+ * Being in its own group, it no longer receives the terminal's Ctrl-C, so SIGINT/SIGTERM
+ * delivered to us are forwarded to the group. Never rejects.
+ */
+export declare function runWithTimeout(cmd: string, timeoutMs: number, opts?: RunOptions): Promise<RunResult>;
+export declare class StepFailure extends Error {
+    readonly label: string;
+    constructor(label: string, message: string);
+}
+export declare function timeoutMessage(label: string, timeoutMs: number): string;
+export interface StepRunOptions {
+    allowStderr: boolean;
+    allowlist: readonly AllowlistEntry[];
+    env?: NodeJS.ProcessEnv;
+    log?: (m: string) => void;
+    error?: (m: string) => void;
+    writeStderr?: (s: string) => void;
+    runImpl?: (cmd: string, timeoutMs: number, opts: RunOptions) => Promise<RunResult>;
+}
+/** How a step passed: 'allowed-stderr' means it would have failed stderr policing but for
+ *  --allow-stderr, which makes the run partial. */
+export type StepOutcome = 'passed' | 'allowed-stderr';
+/** Run one planned step. Every failure throws StepFailure so the caller's `finally`
+ *  releases the lock before the run exits. */
+export declare function runStep(step: PlannedStep, opts: StepRunOptions): Promise<StepOutcome>;
+/** Run the plan holding the machine lock; an empty plan touches no lock. The lock is
+ *  released on every exit path. Returns the labels whose stderr --allow-stderr waived. */
+export declare function runSteps(steps: readonly PlannedStep[], lock: MachineLock, run: (step: PlannedStep) => Promise<StepOutcome>): Promise<string[]>;