@bridge_gpt/mcp-server 0.2.2 → 0.2.4

package/build/conductor/epic-state.js

@@ -0,0 +1,125 @@
+/**
+ * Pure, deterministic observed-state rebuild + ready-set computation for the
+ * Epic Supervisor (BAPI-408).
+ *
+ * This module has NO I/O, NO timers, and NO LLM calls. Every time-dependent
+ * function takes an explicit `now` (epoch ms) so tests are wall-clock
+ * independent. Truth precedence: raw local ledger events override non-terminal
+ * Postgres states.
+ */
+// ---------------------------------------------------------------------------
+// Status sets (module-private)
+// ---------------------------------------------------------------------------
+const NOT_STARTED_STATUS = "planned";
+const DONE_STATUSES = new Set(["done"]);
+const NON_TERMINAL_STATUSES = new Set([
+    "planned",
+    "ready",
+    "dispatched",
+    "running",
+    "blocked",
+]);
+const TERMINAL_SIGNAL_TYPES = new Set([
+    "gate.met",
+    "merge.succeeded",
+    "ci.failed",
+    "run.stopped",
+]);
+function isNonTerminal(status) {
+    return NON_TERMINAL_STATUSES.has(status);
+}
+function signalToNextStatus(signalType) {
+    if (signalType === "ci.failed")
+        return "blocked";
+    return "done";
+}
+// ---------------------------------------------------------------------------
+// computeReadySet
+// ---------------------------------------------------------------------------
+/**
+ * Pure deterministic ready-set computation. Returns ticket keys that:
+ *   1. Have status "planned" (not yet started), AND
+ *   2. Whose full `depends_on` list is satisfied (all deps have "done" status).
+ *
+ * Never calls an LLM or performs I/O. Goal 8 invariant.
+ */
+export function computeReadySet(plan, ticketStatuses) {
+    const ready = [];
+    for (const ticket of plan.tickets) {
+        const currentStatus = ticketStatuses.get(ticket.ticket_key) ?? "planned";
+        if (currentStatus !== NOT_STARTED_STATUS)
+            continue;
+        const allDepsResolved = ticket.depends_on.every((dep) => DONE_STATUSES.has(ticketStatuses.get(dep) ?? "planned"));
+        if (allDepsResolved)
+            ready.push(ticket.ticket_key);
+    }
+    return ready;
+}
+// ---------------------------------------------------------------------------
+// rebuildObservedState
+// ---------------------------------------------------------------------------
+/**
+ * Rebuild the merged observed state from the durable Postgres desired state
+ * and raw local ledger events. Local sticky terminal signals override
+ * non-terminal Postgres states. Pure: no I/O, no side-effects, explicit `now`.
+ */
+export function rebuildObservedState(postgresState, events, _now) {
+    const { epic_run, ticket_statuses, dispatches } = postgresState;
+    // Build run_id → ticket_key lookup from dispatch records
+    const runIdToTicketKey = new Map();
+    for (const dispatch of dispatches) {
+        if (dispatch.run_id) {
+            runIdToTicketKey.set(dispatch.run_id, dispatch.ticket_key);
+        }
+    }
+    // Populate base maps from Postgres
+    const ticketStatusMap = new Map();
+    const ticketRowVersionMap = new Map();
+    for (const ts of ticket_statuses) {
+        ticketStatusMap.set(ts.ticket_key, ts.status);
+        ticketRowVersionMap.set(ts.ticket_key, ts.row_version);
+    }
+    const unfoldedSignals = [];
+    const pendingMergeEvents = [];
+    // Track which tickets already have a folded signal (one override per ticket)
+    const foldedTicketKeys = new Set();
+    for (const event of events) {
+        if (!TERMINAL_SIGNAL_TYPES.has(event.type))
+            continue;
+        // Map event → ticket via run_id
+        const runId = typeof event.run_id === "string" ? event.run_id : null;
+        const ticketKey = runId ? runIdToTicketKey.get(runId) : undefined;
+        if (!ticketKey)
+            continue;
+        if (event.type === "gate.met") {
+            pendingMergeEvents.push(event);
+        }
+        const postgresStatus = ticketStatusMap.get(ticketKey) ?? "planned";
+        if (!isNonTerminal(postgresStatus))
+            continue;
+        if (foldedTicketKeys.has(ticketKey))
+            continue;
+        const signalType = event.type;
+        const nextStatus = signalToNextStatus(signalType);
+        const rowVersion = ticketRowVersionMap.get(ticketKey) ?? 0;
+        unfoldedSignals.push({
+            ticket_key: ticketKey,
+            postgres_row_version: rowVersion,
+            next_status: nextStatus,
+            signal_type: signalType,
+            event,
+        });
+        // Apply override locally so the effective status map reflects the change
+        ticketStatusMap.set(ticketKey, nextStatus);
+        foldedTicketKeys.add(ticketKey);
+    }
+    return {
+        epic_key: epic_run.epic_key,
+        epic_status: epic_run.status,
+        plan_version: epic_run.current_plan_version,
+        ticket_statuses: ticketStatusMap,
+        ticket_row_versions: ticketRowVersionMap,
+        unfolded_terminal_signals: unfoldedSignals,
+        pending_merge_events: pendingMergeEvents,
+    };
+}

package/build/conductor/errors.js

@@ -0,0 +1,85 @@
+/**
+ * Conductor error types and the secret-safe error-envelope mapper.
+ *
+ * Every error surfaced to an MCP caller or the CLI passes through
+ * {@link toConductorErrorEnvelope}, which maps an arbitrary thrown value to a
+ * small structured envelope with an HTTP-style status. The returned `message`
+ * is sanitized: it NEVER echoes raw event payloads, secret material, or stack
+ * traces. Only validation errors (which the conductor constructs itself with
+ * safe text) carry their message through; everything else collapses to a
+ * generic message.
+ */
+import { redactSecretString } from "./redaction.js";
+/** Raised when caller input violates a conductor validation rule. */
+export class ConductorValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConductorValidationError";
+    }
+}
+/** Raised when the underlying SQLite store cannot complete an operation. */
+export class ConductorStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConductorStoreError";
+    }
+}
+/**
+ * Heuristically detect SQLite busy/locked failures so they can be surfaced as a
+ * retryable 503 rather than an opaque 500. Matches the `better-sqlite3` error
+ * `code` field (`SQLITE_BUSY` / `SQLITE_LOCKED`) and the common message text.
+ */
+function isSqliteBusyError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    // Match the extended result codes too (e.g. SQLITE_BUSY_SNAPSHOT,
+    // SQLITE_BUSY_RECOVERY, SQLITE_LOCKED_SHAREDCACHE), which better-sqlite3 surfaces
+    // on `code`. A deferred read-then-write transaction that loses a WAL snapshot
+    // race throws SQLITE_BUSY_SNAPSHOT, and that should map to a retryable 503, not
+    // an opaque 500.
+    if (typeof code === "string" && (code.startsWith("SQLITE_BUSY") || code.startsWith("SQLITE_LOCKED"))) {
+        return true;
+    }
+    const message = error.message;
+    if (typeof message === "string") {
+        const lowered = message.toLowerCase();
+        if (lowered.includes("database is locked") ||
+            lowered.includes("database is busy") ||
+            lowered.includes("sqlite_busy") ||
+            lowered.includes("sqlite_locked")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Map any thrown value to a secret-safe {@link ConductorErrorEnvelope}.
+ *
+ *   - {@link ConductorValidationError} -> `{ VALIDATION_ERROR, 400 }` (message
+ *     carried through, since the conductor authors it with safe text).
+ *   - Distinguishable SQLite busy/locked failures -> `{ STORE_BUSY, 503 }` with
+ *     a generic message.
+ *   - Everything else -> `{ INTERNAL_ERROR, 500 }` with a fixed generic message;
+ *     the raw error text, stack, and any secret material are discarded.
+ */
+export function toConductorErrorEnvelope(error) {
+    if (error instanceof ConductorValidationError) {
+        // Validation messages are conductor-authored and name the offending field,
+        // never its value — but redact defensively so an adversarial/secret-bearing
+        // message can never round-trip back to the caller.
+        return { error: "VALIDATION_ERROR", status: 400, message: redactSecretString(error.message) };
+    }
+    if (isSqliteBusyError(error)) {
+        return {
+            error: "STORE_BUSY",
+            status: 503,
+            message: "Conductor ledger is busy; retry shortly.",
+        };
+    }
+    return {
+        error: "INTERNAL_ERROR",
+        status: 500,
+        message: "Conductor ledger operation failed.",
+    };
+}

package/build/conductor/git-ci-types.js

@@ -0,0 +1,129 @@
+/**
+ * Shared, tool-agnostic contracts and boundary validators for the conductor
+ * git / PR / CI producer (BAPI-395).
+ *
+ * Everything here is provider-neutral: there are no Claude-specific fields and no
+ * GitHub/Bitbucket-native PR/CI fields outside an explicit `raw` channel. The git
+ * hooks, the PR/CI observer, and the done-gate evaluator all derive their accepted
+ * vocabulary, normalization, and stable hashing from this single module so the
+ * binding identity (`repo + pr_number + head_sha`) and gate config hashes can
+ * never drift between producers.
+ *
+ * This module is pure: it performs no I/O, spawns no subprocess, and never throws
+ * for invalid input — every validator returns `null` for unusable values so the
+ * whole producer surface fails closed rather than emitting half-formed events.
+ */
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Identity constants
+// ---------------------------------------------------------------------------
+/** Per-repo config field that carries the v1 done-gate definition. */
+export const DONE_GATE_CONFIG_FIELD = "conductor_done_gate";
+/** `producer` identity for PR/CI/gate events emitted by the observer. */
+export const GIT_CI_PRODUCER = "git-pr-ci-producer";
+/** `producer` identity for events emitted by the local git hooks. */
+export const GIT_HOOK_PRODUCER = "git-hook";
+/** The single v1 done-gate condition type. */
+export const REQUIRED_CI_CHECKS_GREEN = "required_ci_checks_green";
+/** Default gate name surfaced in `gate.met` event data. */
+export const DEFAULT_GATE_NAME = "done";
+/** Matches ASCII control characters (C0 range plus DEL). */
+const CONTROL_CHAR_RE = /[\u0000-\u001F\u007F]/;
+/** Matches a 40- or 64-character hex string (git SHA-1 / SHA-256 object ids). */
+const SHA_RE = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/;
+// ---------------------------------------------------------------------------
+// Boundary validators (fail closed, never throw)
+// ---------------------------------------------------------------------------
+/**
+ * Trim and validate a repository name. Accepts any non-empty string free of
+ * control characters (slashes and dots are valid — `org/repo`, `team.repo`).
+ * Returns the trimmed value, or `null` for empty/whitespace/control-char/
+ * non-string input.
+ */
+export function normalizeRepoName(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (CONTROL_CHAR_RE.test(trimmed))
+        return null;
+    return trimmed;
+}
+/**
+ * Validate a git object id. Outer whitespace is trimmed, then the value must be
+ * exactly 40 or 64 hex characters (case-insensitive). Returns the lowercase,
+ * normalized SHA or `null`. Non-hex content, wrong lengths, and non-strings are
+ * rejected — never silently coerced into a usable value.
+ */
+export function normalizeSha(value) {
+    if (typeof value !== "string")
+        return null;
+    const lowered = value.trim().toLowerCase();
+    if (!SHA_RE.test(lowered))
+        return null;
+    return lowered;
+}
+/**
+ * Validate a PR number. Accepts only an actual positive safe integer; rejects 0,
+ * negatives, non-integers, values beyond `Number.MAX_SAFE_INTEGER`, and string
+ * coercions (`"123"`). Returns the number or `null`.
+ */
+export function normalizePrNumber(value) {
+    if (typeof value !== "number")
+        return null;
+    if (!Number.isSafeInteger(value))
+        return null;
+    if (value <= 0)
+        return null;
+    return value;
+}
+/**
+ * Trim and validate a CI check name. Provider-neutral: spaces, slashes, and
+ * colons are preserved (`"test / python"`, `"CI: unit-tests"`). Empty,
+ * whitespace-only, control-char-bearing, and non-string names return `null`.
+ */
+export function normalizeCheckName(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (CONTROL_CHAR_RE.test(trimmed))
+        return null;
+    return trimmed;
+}
+// ---------------------------------------------------------------------------
+// Stable canonical hashing
+// ---------------------------------------------------------------------------
+/**
+ * Produce a canonical JSON representation with object keys sorted recursively.
+ * Array order is preserved (it is semantically significant); object key order is
+ * not (it is not). Used as the input to {@link stableJsonHash}.
+ */
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalize(item));
+    }
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        const sortedKeys = Object.keys(record).sort();
+        const out = {};
+        for (const key of sortedKeys) {
+            out[key] = canonicalize(record[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Hash any JSON-serializable value to a stable lowercase SHA-256 hex digest. The
+ * hash is canonical for object key ordering (so `{a,b}` and `{b,a}` collide) and
+ * sensitive to values, types, and array order. Does not depend on runtime object
+ * identity — two separately constructed equal structures hash identically.
+ */
+export function stableJsonHash(value) {
+    const canonical = canonicalize(value);
+    const json = JSON.stringify(canonical) ?? "null";
+    return createHash("sha256").update(json).digest("hex");
+}

package/build/conductor/git-hooks.js

@@ -0,0 +1,218 @@
+/**
+ * Managed, non-blocking local git hook installation and verification (BAPI-395).
+ *
+ * `conductor install-git-hooks` installs opportunistic `post-commit` and
+ * `reference-transaction` hooks that launch the conductor producer in the
+ * background and never block the user's git workflow. Hooks are LOCAL and
+ * unversioned: only a clearly-delimited managed block is inserted/replaced, all
+ * surrounding user hook content is preserved, and anything that looks binary or
+ * unsafe to merge is left untouched with a warning. Missing hooks are a degraded
+ * OPTIONAL capability — never a fatal error.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runGitCommand } from "./git-inspection.js";
+/** Markers delimiting the conductor-managed block inside a hook file. */
+export const BRIDGE_CONDUCTOR_HOOK_START = "# >>> BRIDGE_CONDUCTOR_HOOK_START >>>";
+export const BRIDGE_CONDUCTOR_HOOK_END = "# <<< BRIDGE_CONDUCTOR_HOOK_END <<<";
+/** The managed hook names this module installs/inspects. */
+export const MANAGED_HOOK_NAMES = ["post-commit", "reference-transaction"];
+/**
+ * Resolve the hooks directory using `git rev-parse --git-common-dir`, so the
+ * correct shared hooks directory is found even from inside a linked worktree. A
+ * relative common dir is resolved against `cwd`. Returns `{ is_worktree: false,
+ * hooks_dir: null }` when the current directory is not a git worktree.
+ */
+export function resolveGitHooksDirectory(deps = {}) {
+    const runGit = deps.runGit ?? runGitCommand;
+    const cwd = deps.cwd ?? process.cwd();
+    const result = runGit(["rev-parse", "--git-common-dir"], { cwd });
+    if (!result.ok)
+        return { is_worktree: false, hooks_dir: null };
+    const commonDir = result.stdout.trim();
+    if (commonDir.length === 0)
+        return { is_worktree: false, hooks_dir: null };
+    const absoluteCommonDir = isAbsolute(commonDir) ? commonDir : resolve(cwd, commonDir);
+    return { is_worktree: true, hooks_dir: resolve(absoluteCommonDir, "hooks") };
+}
+/** Best-effort default path to the compiled conductor bin (`build/conductor-bin.js`). */
+function defaultConductorBin() {
+    // This file compiles to build/conductor/git-hooks.js; the bin is build/conductor-bin.js.
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "conductor-bin.js");
+}
+function wrapManagedBlock(body) {
+    return [BRIDGE_CONDUCTOR_HOOK_START, body, BRIDGE_CONDUCTOR_HOOK_END].join("\n");
+}
+/**
+ * Build the managed `post-commit` snippet: launches
+ * `node <conductor-bin> git-hook post-commit` fully detached in the background,
+ * redirecting all output away from the user's git workflow. Failures are tolerated
+ * (`|| true`) so the hook never returns non-zero.
+ */
+export function buildPostCommitHookSnippet(conductorBin) {
+    const body = [
+        "# Managed by Bridge conductor (BAPI-395). Local, unversioned, opportunistic, bypassable.",
+        `( node ${JSON.stringify(conductorBin)} git-hook post-commit >/dev/null 2>&1 & ) || true`,
+    ].join("\n");
+    return wrapManagedBlock(body);
+}
+/**
+ * Build the managed `reference-transaction` snippet: captures stdin to a temp
+ * file (the ref updates), then launches
+ * `node <conductor-bin> git-hook reference-transaction --phase "$1" --stdin-file <tmp>`
+ * detached in the background, redirecting output away from the user's workflow.
+ */
+export function buildReferenceTransactionHookSnippet(conductorBin) {
+    const body = [
+        "# Managed by Bridge conductor (BAPI-395). Local, unversioned, opportunistic, bypassable.",
+        '__bridge_tmp="$(mktemp 2>/dev/null || echo "/tmp/bridge-conductor-refs.$$")"',
+        'cat > "$__bridge_tmp"',
+        `( node ${JSON.stringify(conductorBin)} git-hook reference-transaction --phase "$1" --stdin-file "$__bridge_tmp" >/dev/null 2>&1 & ) || true`,
+    ].join("\n");
+    return wrapManagedBlock(body);
+}
+function looksBinary(content) {
+    return content.includes("\u0000");
+}
+/**
+ * Insert or replace ONLY the conductor-managed block within existing hook content,
+ * preserving all surrounding user content. A binary/unsafe existing hook is left
+ * untouched with a warning. Idempotent: an existing managed block is replaced, not
+ * duplicated.
+ */
+export function mergeManagedHookSnippet(existing, managedBlock) {
+    if (existing === null || existing.length === 0) {
+        const content = `#!/bin/sh\n${managedBlock}\n`;
+        return { ok: true, content, action: "created" };
+    }
+    if (looksBinary(existing)) {
+        return {
+            ok: false,
+            content: existing,
+            action: "skipped",
+            warning: "existing hook appears binary/unsafe to merge; left untouched",
+        };
+    }
+    const startIdx = existing.indexOf(BRIDGE_CONDUCTOR_HOOK_START);
+    const endIdx = existing.indexOf(BRIDGE_CONDUCTOR_HOOK_END);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const before = existing.slice(0, startIdx);
+        const after = existing.slice(endIdx + BRIDGE_CONDUCTOR_HOOK_END.length);
+        const content = `${before}${managedBlock}${after}`;
+        return { ok: true, content, action: "replaced" };
+    }
+    // No managed block yet — append after the user's content, preserving it.
+    const separator = existing.endsWith("\n") ? "" : "\n";
+    const content = `${existing}${separator}${managedBlock}\n`;
+    return { ok: true, content, action: "appended" };
+}
+function snippetForHook(name, conductorBin) {
+    return name === "post-commit"
+        ? buildPostCommitHookSnippet(conductorBin)
+        : buildReferenceTransactionHookSnippet(conductorBin);
+}
+/**
+ * Install or update the managed `post-commit` and `reference-transaction` hooks.
+ * Creates the hooks directory when needed and marks hook files executable on
+ * POSIX. A non-worktree directory is reported as a degraded optional capability
+ * (warning), never a fatal error.
+ */
+export function installConductorGitHooks(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const conductorBin = deps.conductorBin ?? defaultConductorBin();
+    const { is_worktree, hooks_dir } = resolveGitHooksDirectory(deps);
+    if (!is_worktree || hooks_dir === null) {
+        return {
+            is_worktree: false,
+            hooks_dir: null,
+            installed: [],
+            warnings: ["not a git worktree; git hooks were not installed (degraded optional capability)"],
+        };
+    }
+    const warnings = [];
+    if (!existsSync(hooks_dir)) {
+        mkdirSync(hooks_dir, { recursive: true });
+    }
+    const installed = [];
+    for (const name of MANAGED_HOOK_NAMES) {
+        const hookPath = resolve(hooks_dir, name);
+        let existing = null;
+        if (existsSync(hookPath)) {
+            try {
+                existing = readFileSync(hookPath, "utf-8");
+            }
+            catch {
+                installed.push({ name, path: hookPath, action: "skipped", warning: "could not read existing hook" });
+                warnings.push(`could not read existing ${name} hook; left untouched`);
+                continue;
+            }
+        }
+        const merge = mergeManagedHookSnippet(existing, snippetForHook(name, conductorBin));
+        if (!merge.ok) {
+            installed.push({ name, path: hookPath, action: "skipped", warning: merge.warning });
+            if (merge.warning)
+                warnings.push(`${name}: ${merge.warning}`);
+            continue;
+        }
+        writeFileSync(hookPath, merge.content, "utf-8");
+        if (platform !== "win32") {
+            try {
+                chmodSync(hookPath, 0o755);
+            }
+            catch {
+                warnings.push(`could not mark ${name} executable`);
+            }
+        }
+        installed.push({ name, path: hookPath, action: merge.action });
+    }
+    return { is_worktree: true, hooks_dir, installed, warnings };
+}
+/**
+ * Inspect the managed git hooks WITHOUT modifying anything. Reports worktree
+ * status, the resolved hooks directory, and per-hook existence, executability, and
+ * managed-block presence. Missing hooks and non-worktree directories are reported
+ * as degraded optional capability, never fatal.
+ */
+export function inspectConductorGitHooks(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const { is_worktree, hooks_dir } = resolveGitHooksDirectory(deps);
+    if (!is_worktree || hooks_dir === null) {
+        return {
+            is_worktree: false,
+            hooks_dir: null,
+            hooks: [],
+            warnings: ["not a git worktree; conductor git hooks are unavailable (degraded optional capability)"],
+            degraded: true,
+        };
+    }
+    const warnings = [];
+    const hooks = [];
+    for (const name of MANAGED_HOOK_NAMES) {
+        const hookPath = resolve(hooks_dir, name);
+        const exists = existsSync(hookPath);
+        let executable = false;
+        let managedPresent = false;
+        if (exists) {
+            try {
+                const mode = statSync(hookPath).mode;
+                executable = platform === "win32" ? true : (mode & 0o111) !== 0;
+            }
+            catch {
+                /* unreadable stat — leave executable false */
+            }
+            try {
+                managedPresent = readFileSync(hookPath, "utf-8").includes(BRIDGE_CONDUCTOR_HOOK_START);
+            }
+            catch {
+                /* unreadable — leave managedPresent false */
+            }
+        }
+        else {
+            warnings.push(`${name} hook not installed (degraded optional capability)`);
+        }
+        hooks.push({ name, path: hookPath, exists, executable, managed_block_present: managedPresent });
+    }
+    const degraded = hooks.some((h) => !h.exists || !h.managed_block_present);
+    return { is_worktree: true, hooks_dir, hooks, warnings, degraded };
+}