@bridge_gpt/mcp-server 0.2.1 → 0.2.3

package/build/conductor/paths.js

@@ -0,0 +1,224 @@
+/**
+ * Local conductor ledger path resolution and filesystem hardening.
+ *
+ * The ledger lives next to the Tier-1 credential store at
+ * `~/.config/bridge/events.db` (honoring `XDG_CONFIG_HOME`), reusing the exact
+ * directory precedent from credential-store.ts so the two local-state files
+ * stay co-located and XDG-consistent. Directories are created `0700` and the DB
+ * file `0600` on POSIX; Windows relies on user-profile ACLs (no chmod). All
+ * health/warning output is secret-free: only paths, filesystem types, and mode
+ * bits are ever surfaced.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { getPrimaryCredentialStorePath } from "../credential-store.js";
+/**
+ * Resolve the ledger DB path: take the credential-store path (which honors
+ * `XDG_CONFIG_HOME` exactly) and swap `credentials.json` for `events.db`, so the
+ * directory derivation is shared rather than re-implemented.
+ */
+export function getConductorLedgerPath() {
+    const credentialsPath = getPrimaryCredentialStorePath({
+        env: process.env,
+        homedir: os.homedir,
+    });
+    return path.join(path.dirname(credentialsPath), "events.db");
+}
+/** The directory containing the ledger DB file. */
+export function getConductorLedgerDirectory() {
+    return path.dirname(getConductorLedgerPath());
+}
+/**
+ * Create the ledger directory recursively and, on POSIX, enforce `0700`. On
+ * Windows the chmod is skipped (user-profile ACLs apply instead).
+ */
+export function ensureConductorLedgerDirectory() {
+    const dir = getConductorLedgerDirectory();
+    fs.mkdirSync(dir, { recursive: true });
+    if (process.platform !== "win32") {
+        fs.chmodSync(dir, 0o700);
+    }
+    return dir;
+}
+/**
+ * Ensure the `events.db` file exists with restrictive permissions BEFORE the
+ * SQLite driver opens it for writes. Creates the file `0600` if absent (without
+ * truncating an existing file) and re-applies `0600` on POSIX. Windows skips the
+ * chmod enforcement.
+ */
+export function ensureConductorDatabaseFile() {
+    ensureConductorLedgerDirectory();
+    const dbPath = getConductorLedgerPath();
+    if (!fs.existsSync(dbPath)) {
+        // `wx`-style create-if-absent without truncation; close immediately so the
+        // SQLite driver owns the handle. Mode is applied on creation on POSIX.
+        const fd = fs.openSync(dbPath, "a", 0o600);
+        fs.closeSync(fd);
+    }
+    if (process.platform !== "win32") {
+        fs.chmodSync(dbPath, 0o600);
+    }
+    return dbPath;
+}
+/** Render the low 9 permission bits of a stat mode as an octal string (e.g. "700"). */
+function formatMode(mode) {
+    return (mode & 0o777).toString(8).padStart(3, "0");
+}
+/**
+ * Inspect ledger directory/file existence and permissions without creating or
+ * modifying anything. Insecure (group/world-accessible) modes are reported as
+ * `*_permissions_ok: false` plus a `warnings` entry rather than throwing.
+ */
+export function getConductorPathHealth() {
+    const dbPath = getConductorLedgerPath();
+    const dir = path.dirname(dbPath);
+    const warnings = [];
+    let directoryExists = false;
+    let directoryMode = null;
+    let directoryPermissionsOk = true;
+    try {
+        const dirStat = fs.statSync(dir);
+        directoryExists = true;
+        directoryMode = formatMode(dirStat.mode);
+        if (process.platform !== "win32" && (dirStat.mode & 0o077) !== 0) {
+            directoryPermissionsOk = false;
+            warnings.push(`Conductor ledger directory ${dir} is group/world-accessible; it should be mode 0700.`);
+        }
+    }
+    catch {
+        directoryExists = false;
+    }
+    let databaseExists = false;
+    let databaseMode = null;
+    let databasePermissionsOk = true;
+    try {
+        const fileStat = fs.statSync(dbPath);
+        databaseExists = true;
+        databaseMode = formatMode(fileStat.mode);
+        if (process.platform !== "win32" && (fileStat.mode & 0o077) !== 0) {
+            databasePermissionsOk = false;
+            warnings.push(`Conductor ledger file ${dbPath} is group/world-accessible; it should be mode 0600.`);
+        }
+    }
+    catch {
+        databaseExists = false;
+    }
+    return {
+        path: dbPath,
+        directory_path: dir,
+        directory_exists: directoryExists,
+        database_exists: databaseExists,
+        directory_mode: directoryMode,
+        database_mode: databaseMode,
+        directory_permissions_ok: directoryPermissionsOk,
+        database_permissions_ok: databasePermissionsOk,
+        warnings,
+    };
+}
+/** Filesystem-type fragments that indicate a network-mounted home directory. */
+const NETWORK_FS_MARKERS = [
+    "nfs",
+    "cifs",
+    "smb",
+    "smbfs",
+    "afpfs",
+    "sshfs",
+    "fuse.sshfs",
+    "fuse.gvfs",
+    "9p",
+    "webdav",
+];
+function matchesNetworkFsType(raw) {
+    const lowered = raw.trim().toLowerCase();
+    if (lowered.length === 0)
+        return null;
+    for (const marker of NETWORK_FS_MARKERS) {
+        if (lowered.includes(marker)) {
+            return lowered;
+        }
+    }
+    return null;
+}
+/**
+ * Best-effort detection of a network-mounted home directory. Concurrent
+ * SQLite/WAL writes on NFS/SMB are unreliable, so we surface a degraded warning
+ * rather than failing. Detection that cannot run returns a non-throwing
+ * "unknown" result (`network_mounted: false`, no warning).
+ *
+ *   - win32: flag UNC home paths (`\\server\share`).
+ *   - linux: `stat -f -c %T <home>` and match the filesystem type.
+ *   - darwin: `stat -f %T <home>` and match the filesystem type.
+ */
+export function detectNetworkMountedHome() {
+    let home = "";
+    try {
+        home = os.homedir();
+    }
+    catch {
+        return { network_mounted: false, filesystem_type: null, home: "", warning: null };
+    }
+    if (process.platform === "win32") {
+        if (home.startsWith("\\\\") || home.startsWith("//")) {
+            return {
+                network_mounted: true,
+                filesystem_type: "unc",
+                home,
+                warning: `Home directory ${home} appears to be a UNC network share; ` +
+                    `concurrent SQLite writes to the conductor ledger may be unreliable.`,
+            };
+        }
+        return { network_mounted: false, filesystem_type: null, home, warning: null };
+    }
+    const args = process.platform === "darwin"
+        ? ["-f", "%T", home]
+        : ["-f", "-c", "%T", home];
+    try {
+        const output = execFileSync("stat", args, {
+            encoding: "utf-8",
+            timeout: 1500,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const fsType = matchesNetworkFsType(output);
+        if (fsType) {
+            return {
+                network_mounted: true,
+                filesystem_type: fsType,
+                home,
+                warning: `Home directory ${home} appears to be on a network filesystem (${fsType}); ` +
+                    `concurrent SQLite writes to the conductor ledger may be unreliable.`,
+            };
+        }
+        return {
+            network_mounted: false,
+            filesystem_type: output.trim().toLowerCase() || null,
+            home,
+            warning: null,
+        };
+    }
+    catch {
+        // Detection failed (no `stat`, timeout, permission). Degrade gracefully.
+        return { network_mounted: false, filesystem_type: null, home, warning: null };
+    }
+}
+/** Process-level guard so the network-home warning is emitted at most once. */
+let networkHomeWarned = false;
+/** Reset the one-time warning guard. Test-only seam. */
+export function resetNetworkHomeWarning() {
+    networkHomeWarned = false;
+}
+/**
+ * Emit a single process-level warning when the home directory looks
+ * network-mounted, and return the detection so MCP/CLI responses can report
+ * `degraded: true`. Only filesystem-type/path metadata is logged — never event
+ * payloads or secrets.
+ */
+export function warnIfNetworkMountedHome() {
+    const detection = detectNetworkMountedHome();
+    if (detection.network_mounted && detection.warning && !networkHomeWarned) {
+        networkHomeWarned = true;
+        console.error(`Warning: ${detection.warning}`);
+    }
+    return detection;
+}

package/build/conductor/plan.js

@@ -0,0 +1,77 @@
+/**
+ * Epic Supervisor plan representation — machine-readable DAG, canonical
+ * serialization, and content-addressed hashing.
+ *
+ * The plan is an immutable, content-addressed blob keyed by {@link hashPlan}.
+ * The sibling `epic-tick` reconcile loop enforces the gate:
+ *   `stableJsonHash(currentPlan) === epic_runs.approved_plan_hash`
+ * and FAIL-CLOSES (dispatches nothing, escalates, waits for re-approval) on
+ * any mismatch. The hash function exported here is the canonical implementation
+ * both sides import so the loop-side hash and the approved hash are always
+ * byte-identical (mirroring how `makeMergeActionKey` is kept in lock-step with
+ * the Python `build_merge_action_key`).
+ *
+ * The source of `EpicPlanDAG` values is LLM generation recipes (e.g.
+ * `/plan-epic`). The supervisor computes the ready-set deterministically from
+ * the DAG (`depends_on` all `done`) and never asks an LLM "what's next."
+ *
+ * Architecture note: the plan blob is stored as a dedicated durable-store row
+ * (not a decision-page artifact) via the protected `/jira/epic-runs/runs/{epicKey}/plan`
+ * endpoint, keeping the decision-page surface for human-facing approvals only.
+ * Plan data is immutable per `(epic_run_id, plan_version)` — a re-plan writes a
+ * new `plan_version + 1`, never mutating an existing blob.
+ */
+import { stableJsonHash } from "./git-ci-types.js";
+// ---------------------------------------------------------------------------
+// Canonicalization
+// ---------------------------------------------------------------------------
+/**
+ * Produce a fully-normalized copy of the plan DAG so that equivalent plans
+ * hash identically regardless of input ordering or whitespace:
+ *
+ *   - Trims outer whitespace from every `ticket_key` (nodes and edges).
+ *   - Sorts each node's `depends_on` array alphabetically.
+ *   - Sorts `nodes` lexicographically by normalized `ticket_key`.
+ *   - Sorts `edges` lexicographically by `from` then `to`.
+ *
+ * The canonical form is fed to {@link hashPlan} / `stableJsonHash`, which
+ * additionally sorts object keys recursively, so two independently constructed
+ * equal plans always produce a byte-identical SHA-256 digest.
+ */
+export function canonicalizePlanDAG(plan) {
+    const nodes = plan.nodes
+        .map((node) => ({
+        ...node,
+        ticket_key: node.ticket_key.trim(),
+        depends_on: [...node.depends_on].map((k) => k.trim()).sort(),
+    }))
+        .sort((a, b) => a.ticket_key.localeCompare(b.ticket_key));
+    const edges = [...plan.edges]
+        .map((e) => ({ from: e.from.trim(), to: e.to.trim() }))
+        .sort((a, b) => {
+        const cmp = a.from.localeCompare(b.from);
+        return cmp !== 0 ? cmp : a.to.localeCompare(b.to);
+    });
+    return { plan_version: plan.plan_version, nodes, edges };
+}
+// ---------------------------------------------------------------------------
+// Content-addressed hashing
+// ---------------------------------------------------------------------------
+/**
+ * Compute the canonical SHA-256 content-address of the plan. Canonicalizes
+ * before hashing so the result is insensitive to object key order, array
+ * order in `depends_on`, node order, and whitespace in ticket keys — but
+ * sensitive to any semantic change (added/removed node, edge, automation
+ * kind, or `base_lineage`). Two independently constructed equal plans always
+ * hash identically (cross-machine requirement from OQ1/OQ3).
+ *
+ * Reuses {@link stableJsonHash} from `git-ci-types.ts` — never invents a
+ * second hashing path.
+ *
+ * Note: `status` is part of the hash (by design — it is part of the type).
+ * The gate's stability guarantee holds because the approved blob always has all
+ * statuses as `"planned"`; the supervisor tracks live progress externally.
+ */
+export function hashPlan(plan) {
+    return stableJsonHash(canonicalizePlanDAG(plan));
+}