@bridge_gpt/mcp-server 0.2.2 → 0.2.4

package/build/conductor/data-normalization.js

@@ -0,0 +1,114 @@
+/**
+ * Event `data` normalization and the tool-native-field boundary.
+ *
+ * Conductor events carry a small, semantically-normalized `data` object. Only an
+ * allowlisted set of top-level keys is accepted; any tool-native field (branch,
+ * commitSha, jiraTicket, …) must be nested under `data.raw`. Oversized inline
+ * payloads are rejected BEFORE any SQLite transaction so large diffs/transcripts
+ * are passed by reference instead. {@link prepareDataJsonForStorage} ties the
+ * pipeline together: normalize -> validate size -> redact -> compact JSON, with
+ * redaction guaranteed to run before the JSON can be inserted.
+ */
+import { ConductorValidationError } from "./errors.js";
+import { redactSecrets } from "./redaction.js";
+/** Allowlisted top-level `data` keys. Everything else must go under `raw`. */
+export const ALLOWED_DATA_KEYS = [
+    "summary",
+    "status",
+    "message",
+    "details",
+    "reason",
+    "metrics",
+    "labels",
+    "references",
+    "payload_ref",
+    "raw",
+];
+const ALLOWED_DATA_KEY_SET = new Set(ALLOWED_DATA_KEYS);
+/** Max characters for any single inline string anywhere in `data`. */
+export const MAX_INLINE_STRING_CHARS = 16_384;
+/** Max characters for the whole serialized `data` object. */
+export const MAX_TOTAL_DATA_CHARS = 65_536;
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Validate and return event `data` as a JSON object. Missing data defaults to
+ * `{}`. Non-object data and non-allowlisted top-level keys are rejected with an
+ * actionable {@link ConductorValidationError}. Error messages name offending
+ * keys only — never their (possibly secret) values.
+ */
+export function normalizeEventData(data) {
+    if (data === undefined || data === null) {
+        return {};
+    }
+    if (!isPlainObject(data)) {
+        throw new ConductorValidationError("Event data must be a JSON object (received an array or primitive).");
+    }
+    const offending = Object.keys(data).filter((key) => !ALLOWED_DATA_KEY_SET.has(key));
+    if (offending.length > 0) {
+        throw new ConductorValidationError(`Event data has non-allowlisted top-level field(s): ${offending.join(", ")}. ` +
+            `Place tool-native fields under "data.raw" instead. Allowed top-level keys: ${ALLOWED_DATA_KEYS.join(", ")}.`);
+    }
+    return data;
+}
+/** Recursively find the longest inline string length within a value. */
+function maxInlineStringLength(value) {
+    if (typeof value === "string") {
+        return value.length;
+    }
+    if (Array.isArray(value)) {
+        let max = 0;
+        for (const item of value) {
+            max = Math.max(max, maxInlineStringLength(item));
+        }
+        return max;
+    }
+    if (isPlainObject(value)) {
+        let max = 0;
+        for (const val of Object.values(value)) {
+            max = Math.max(max, maxInlineStringLength(val));
+        }
+        return max;
+    }
+    return 0;
+}
+/**
+ * Reject oversized inline payloads BEFORE serialization/storage. Callers must
+ * store large diffs/transcripts externally and pass a reference via
+ * `data.references` or `data.payload_ref`.
+ */
+export function validateLargePayloadReferences(data) {
+    const longest = maxInlineStringLength(data);
+    if (longest > MAX_INLINE_STRING_CHARS) {
+        throw new ConductorValidationError(`Event data contains an inline string of ${longest} characters, exceeding the ` +
+            `${MAX_INLINE_STRING_CHARS}-character limit. Store large diffs/transcripts externally and ` +
+            `pass a reference via "data.references" or "data.payload_ref".`);
+    }
+    let serializedLength = 0;
+    try {
+        serializedLength = JSON.stringify(data)?.length ?? 0;
+    }
+    catch {
+        throw new ConductorValidationError("Event data is not JSON-serializable.");
+    }
+    if (serializedLength > MAX_TOTAL_DATA_CHARS) {
+        throw new ConductorValidationError(`Serialized event data is ${serializedLength} characters, exceeding the ` +
+            `${MAX_TOTAL_DATA_CHARS}-character limit. Pass large content by reference via ` +
+            `"data.references" or "data.payload_ref".`);
+    }
+}
+/**
+ * Full storage-preparation pipeline for the `data_json` column:
+ *   1. normalize (allowlist + object check),
+ *   2. validate inline payload size (outside any SQLite transaction),
+ *   3. redact secrets recursively,
+ *   4. serialize to compact JSON.
+ * Redaction is guaranteed to happen before the returned JSON can be inserted.
+ */
+export function prepareDataJsonForStorage(data) {
+    const normalized = normalizeEventData(data);
+    validateLargePayloadReferences(normalized);
+    const redacted = redactSecrets(normalized);
+    return JSON.stringify(redacted);
+}

package/build/conductor/doctor.js

@@ -0,0 +1,164 @@
+/**
+ * Combined, strictly read-only conductor doctor report (BAPI-395, BAPI-418).
+ *
+ * Extends the existing SQLite ledger health report with local git hook health
+ * and Epic Supervisor schedule enablement status. Missing hooks and non-worktree
+ * directories are reported as a degraded OPTIONAL capability — never a fatal
+ * failure. This module performs NO writes: no hook installation, no schema
+ * migration, no event emission, and no scheduler unit creation.
+ */
+import { doctorConductorLedger } from "./store.js";
+import { inspectConductorGitHooks } from "./git-hooks.js";
+/**
+ * Inspect the local schedule metadata store for a registered epic-tick schedule.
+ * Strictly read-only: composes orchestrateScheduleList (read-only list path) and
+ * never creates, updates, or deletes any unit. A missing or erroring schedule is
+ * mapped to a degraded state, never a thrown exception.
+ *
+ * Schedule-run is loaded lazily via dynamic import to avoid eagerly pulling its
+ * node:fs/promises dependency into the module graph when doctor.ts is imported.
+ */
+export async function inspectEpicTickSchedule(deps, orchestrateListOverride) {
+    try {
+        // Lazily import schedule-run to avoid pulling node:fs/promises into the graph
+        // when doctor.ts is first imported (which would break node:fs mocks in tests).
+        const schedRun = orchestrateListOverride
+            ? null
+            : await import("../schedule-run.js");
+        const doList = orchestrateListOverride
+            ? orchestrateListOverride
+            : (d) => schedRun.orchestrateScheduleList({ json: false }, d);
+        const resolvedDeps = orchestrateListOverride
+            ? deps
+            : (deps ?? schedRun.createDefaultScheduleRunDeps());
+        const commandLabel = schedRun
+            ? schedRun.scheduleCommandLabel
+            : (m) => m.command ?? (m.idea_file ? "full-automation" : "(unknown)");
+        const runStatus = schedRun
+            ? schedRun.latestRunStatus
+            : (m) => {
+                const h = m.run_history;
+                return h && h.length > 0 ? h[h.length - 1].status : "";
+            };
+        const report = await doList(resolvedDeps);
+        const entry = report.entries.find((e) => commandLabel(e.metadata) === "epic-tick");
+        if (!entry) {
+            return {
+                registered: false,
+                backend: null,
+                next_fire_iso: null,
+                latest_run_status: null,
+                degraded: true,
+                warnings: [
+                    "No epic-tick schedule is registered. Run: " +
+                        "npx -y @bridge_gpt/mcp-server schedule-run create --in 1m --command epic-tick -- --epic-key <EPIC-KEY>",
+                ],
+            };
+        }
+        const m = entry.metadata;
+        const latest = runStatus(m);
+        const degraded = entry.status !== "active";
+        const warnings = [];
+        if (degraded) {
+            const msg = entry.status === "backend-unavailable"
+                ? `epic-tick schedule status is "backend-unavailable": the OS scheduler backend is unreachable. Check that the scheduler daemon is running.`
+                : `epic-tick schedule status is "${entry.status}" (expected "active"); re-register if stale.`;
+            warnings.push(msg);
+        }
+        return {
+            registered: true,
+            backend: m.backend ?? null,
+            next_fire_iso: m.run_at_iso ?? null,
+            latest_run_status: latest || null,
+            degraded,
+            warnings,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            registered: false,
+            backend: null,
+            next_fire_iso: null,
+            latest_run_status: null,
+            degraded: true,
+            warnings: [`Failed to inspect epic-tick schedule: ${msg}`],
+        };
+    }
+}
+/**
+ * Build the combined read-only doctor report. Composes the existing ledger
+ * doctor, git hook inspection, and the epic-tick schedule enablement check.
+ * Never mutates the ledger, the hooks, the schema, or the OS scheduler.
+ */
+export async function buildConductorDoctorReport(deps = {}) {
+    const doctorLedger = deps.doctorLedger ?? doctorConductorLedger;
+    const inspectHooks = deps.inspectHooks ?? inspectConductorGitHooks;
+    const epicTick = await inspectEpicTickSchedule(deps.scheduleDeps, deps.orchestrateList);
+    return {
+        ledger: doctorLedger(),
+        git_hooks: inspectHooks(deps.hooksDeps),
+        epic_tick: epicTick,
+    };
+}
+/**
+ * Render the combined doctor report as human-readable text: ledger health,
+ * git hooks section, and an Epic Supervisor Schedule section using semantic
+ * status tags consistent with the git hooks section's visual hierarchy.
+ */
+export function formatConductorDoctorReport(report) {
+    const { ledger, git_hooks, epic_tick } = report;
+    const lines = [
+        "Conductor ledger doctor",
+        "───────────────────────",
+        `path:                  ${ledger.path}`,
+        `directory exists:      ${ledger.directory_exists}`,
+        `database exists:       ${ledger.database_exists}`,
+        `directory mode:        ${ledger.directory_mode ?? "n/a"} (ok: ${ledger.directory_permissions_ok})`,
+        `database mode:         ${ledger.database_mode ?? "n/a"} (ok: ${ledger.database_permissions_ok})`,
+        `schema present:        ${ledger.schema_present}`,
+        `journal mode:          ${ledger.journal_mode ?? "n/a"}`,
+        `user_version:          ${ledger.user_version ?? "n/a"}`,
+        `event count:           ${ledger.event_count ?? "n/a"}`,
+        `max seq:               ${ledger.max_seq ?? "n/a"}`,
+        `busy_timeout_ms:       ${ledger.retention.busy_timeout_ms}`,
+        `retention_days:        ${ledger.retention.retention_days}`,
+        `retention_max_rows:    ${ledger.retention.retention_max_rows}`,
+        `message_cooldown_ms:   ${ledger.message_relay.message_cooldown_ms}`,
+        `degraded (network FS): ${ledger.degraded}`,
+    ];
+    if (ledger.warnings.length > 0) {
+        lines.push("warnings:");
+        for (const w of ledger.warnings)
+            lines.push(`  - ${w}`);
+    }
+    lines.push("");
+    lines.push("git hooks (optional, local)");
+    lines.push("───────────────────────────");
+    lines.push(`is git worktree:       ${git_hooks.is_worktree}`);
+    lines.push(`hooks dir:             ${git_hooks.hooks_dir ?? "n/a"}`);
+    lines.push(`degraded:              ${git_hooks.degraded}`);
+    for (const hook of git_hooks.hooks) {
+        lines.push(`  ${hook.name}: exists=${hook.exists} executable=${hook.executable} managed=${hook.managed_block_present}`);
+    }
+    if (git_hooks.warnings.length > 0) {
+        lines.push("git hook warnings:");
+        for (const w of git_hooks.warnings)
+            lines.push(`  - ${w}`);
+    }
+    lines.push("");
+    lines.push("Epic Supervisor Schedule (optional, local)");
+    lines.push("──────────────────────────────────────────");
+    const registeredTag = epic_tick.registered ? "[SUCCESS] registered" : "[WARNING] not registered";
+    lines.push(`registered:            ${registeredTag}`);
+    lines.push(`backend:               ${epic_tick.backend ?? "n/a"}`);
+    lines.push(`next fire:             ${epic_tick.next_fire_iso ?? "n/a"}`);
+    lines.push(`latest run status:     ${epic_tick.latest_run_status ?? "n/a"}`);
+    lines.push(`degraded:              ${epic_tick.degraded}`);
+    if (epic_tick.warnings.length > 0) {
+        lines.push("epic-tick warnings:");
+        for (const w of epic_tick.warnings)
+            lines.push(`  - ${w}`);
+    }
+    return lines.join("\n");
+}

package/build/conductor/done-gate.js

@@ -0,0 +1,325 @@
+/**
+ * Pure done-gate config parsing, CI snapshot normalization, and deterministic
+ * gate evaluation (BAPI-395).
+ *
+ * v1 supports exactly one gate condition — `required_ci_checks_green` — and fails
+ * CLOSED everywhere: unset, disabled, malformed, and unsupported config all yield
+ * an inactive result that can never emit `gate.met`. A gate is met only when every
+ * configured required check is present, complete, and green for the exact
+ * `repo + pr_number + head_sha` binding. This module is pure (no I/O) and never
+ * throws for caller input.
+ */
+import { DEFAULT_GATE_NAME, REQUIRED_CI_CHECKS_GREEN, normalizeCheckName, normalizeSha, stableJsonHash, } from "./git-ci-types.js";
+// ---------------------------------------------------------------------------
+// Config parsing
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Build a fail-closed inactive config with the given reason. */
+function inactiveConfig(reason) {
+    return {
+        enabled: false,
+        valid: false,
+        reason,
+        condition: null,
+        config_hash: null,
+        gate_name: DEFAULT_GATE_NAME,
+    };
+}
+/**
+ * Coerce a raw config value into a JSON object, or `null` when it is unset or not
+ * an object. Accepts objects directly and non-empty JSON strings that parse to
+ * objects; treats `undefined`, `null`, empty/whitespace strings, and empty
+ * objects as unset. Malformed JSON, JSON arrays/primitives, and non-objects
+ * return `null` (the caller maps that to a fail-closed reason).
+ */
+function coerceConfigObject(value) {
+    if (value === undefined || value === null)
+        return { kind: "unset" };
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            return { kind: "unset" };
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            return { kind: "invalid" };
+        }
+        if (!isPlainObject(parsed))
+            return { kind: "invalid" };
+        if (Object.keys(parsed).length === 0)
+            return { kind: "unset" };
+        return { kind: "object", object: parsed };
+    }
+    if (isPlainObject(value)) {
+        if (Object.keys(value).length === 0)
+            return { kind: "unset" };
+        return { kind: "object", object: value };
+    }
+    return { kind: "invalid" };
+}
+/**
+ * Extract and validate the single v1 condition from a config object. Requires
+ * `conditions` to be an array containing exactly one `required_ci_checks_green`
+ * condition whose `required_checks` is a non-empty array of unique, valid,
+ * normalized check names. Returns the normalized condition or `null`.
+ */
+function parseSingleCondition(object) {
+    const conditions = object.conditions;
+    if (!Array.isArray(conditions) || conditions.length !== 1)
+        return null;
+    const condition = conditions[0];
+    if (!isPlainObject(condition))
+        return null;
+    if (condition.type !== REQUIRED_CI_CHECKS_GREEN)
+        return null;
+    const rawChecks = condition.required_checks;
+    if (!Array.isArray(rawChecks) || rawChecks.length === 0)
+        return null;
+    const normalized = [];
+    const seen = new Set();
+    for (const raw of rawChecks) {
+        const name = normalizeCheckName(raw);
+        if (name === null)
+            return null; // invalid name invalidates the whole config
+        if (seen.has(name))
+            return null; // duplicate after normalization
+        seen.add(name);
+        normalized.push(name);
+    }
+    return { type: REQUIRED_CI_CHECKS_GREEN, required_checks: normalized };
+}
+/**
+ * Parse a raw `conductor_done_gate` value into a fail-closed
+ * {@link NormalizedDoneGateConfig}. Active (`enabled && valid`) only when the
+ * value is an enabled object with `enabled === true` (strict boolean) and exactly
+ * one valid v1 condition. Every other shape is inactive with a safe reason.
+ */
+export function parseDoneGateConfig(value) {
+    const coerced = coerceConfigObject(value);
+    if (coerced.kind === "unset")
+        return inactiveConfig("unset");
+    if (coerced.kind === "invalid")
+        return inactiveConfig("malformed");
+    const object = coerced.object;
+    // `enabled` must be the strict boolean `true`; truthy non-booleans are rejected.
+    if (object.enabled !== true) {
+        if (object.enabled === false)
+            return inactiveConfig("disabled");
+        return inactiveConfig("invalid: 'enabled' must be the boolean true");
+    }
+    const condition = parseSingleCondition(object);
+    if (condition === null) {
+        return inactiveConfig("invalid: expected exactly one valid required_ci_checks_green condition");
+    }
+    const gateName = DEFAULT_GATE_NAME;
+    const configHash = stableJsonHash({
+        gate_name: gateName,
+        type: condition.type,
+        required_checks: condition.required_checks,
+    });
+    return {
+        enabled: true,
+        valid: true,
+        reason: "active",
+        condition,
+        config_hash: configHash,
+        gate_name: gateName,
+    };
+}
+// ---------------------------------------------------------------------------
+// CI snapshot normalization
+// ---------------------------------------------------------------------------
+const SUCCESS_STATES = new Set(["success", "passed", "succeeded"]);
+const COMPLETE_STATES = new Set([
+    "completed",
+    "complete",
+    "success",
+    "passed",
+    "succeeded",
+    "failure",
+    "failed",
+    "error",
+    "cancelled",
+    "canceled",
+    "timed_out",
+    "action_required",
+    "neutral",
+    "skipped",
+]);
+function asLowerString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim().toLowerCase() : undefined;
+}
+/**
+ * Normalize one raw check entry (already keyed by `name`) into a
+ * {@link NormalizedCiCheck}. Returns `null` for malformed entries so they are
+ * skipped rather than poisoning sibling checks.
+ */
+function normalizeOneCheck(name, raw) {
+    const checkName = normalizeCheckName(name);
+    if (checkName === null)
+        return null;
+    if (!isPlainObject(raw)) {
+        // A bare name with no status info is not usable as a green check.
+        return { name: checkName, complete: false, green: false };
+    }
+    const status = asLowerString(raw.status);
+    const conclusion = asLowerString(raw.conclusion);
+    const explicitComplete = typeof raw.complete === "boolean" ? raw.complete : undefined;
+    const explicitPassed = typeof raw.passed === "boolean" ? raw.passed : undefined;
+    let complete = false;
+    if (explicitComplete !== undefined) {
+        complete = explicitComplete;
+    }
+    else if (conclusion !== undefined && COMPLETE_STATES.has(conclusion)) {
+        complete = true;
+    }
+    else if (status !== undefined && COMPLETE_STATES.has(status)) {
+        complete = true;
+    }
+    let green = false;
+    if (complete) {
+        if (explicitPassed === true) {
+            green = true;
+        }
+        else if (conclusion !== undefined && SUCCESS_STATES.has(conclusion)) {
+            green = true;
+        }
+        else if (conclusion === undefined &&
+            explicitPassed === undefined &&
+            status !== undefined &&
+            SUCCESS_STATES.has(status)) {
+            green = true;
+        }
+    }
+    // An explicit failure signal can never be green even if complete.
+    if (explicitPassed === false)
+        green = false;
+    const state = conclusion ?? status ?? (explicitPassed === true ? "passed" : undefined);
+    const check = { name: checkName, complete, green };
+    if (state !== undefined)
+        check.state = state;
+    return check;
+}
+/**
+ * Normalize a raw `poll_ci_checks` response into a SHA-keyed
+ * {@link NormalizedCiSnapshot}. Supports both array-shaped and object/map-shaped
+ * `checks`. Pending, missing, failed, cancelled, malformed, and unknown checks are
+ * never treated as green. `all_passed`/`all_complete` are recomputed from the
+ * normalized set, never trusted from the raw aggregate flags alone.
+ */
+export function normalizeCiSnapshot(response) {
+    const checks = [];
+    const byName = new Map();
+    if (isPlainObject(response)) {
+        const rawChecks = response.checks;
+        if (Array.isArray(rawChecks)) {
+            for (const entry of rawChecks) {
+                if (!isPlainObject(entry))
+                    continue;
+                const normalized = normalizeOneCheck(entry.name, entry);
+                if (normalized && !byName.has(normalized.name)) {
+                    byName.set(normalized.name, normalized);
+                    checks.push(normalized);
+                }
+            }
+        }
+        else if (isPlainObject(rawChecks)) {
+            for (const [name, value] of Object.entries(rawChecks)) {
+                const normalized = normalizeOneCheck(name, value);
+                if (normalized && !byName.has(normalized.name)) {
+                    byName.set(normalized.name, normalized);
+                    checks.push(normalized);
+                }
+            }
+        }
+    }
+    const unknownChecks = [];
+    if (isPlainObject(response) && Array.isArray(response.unknown_checks)) {
+        for (const raw of response.unknown_checks) {
+            const name = normalizeCheckName(raw);
+            if (name !== null && !unknownChecks.includes(name))
+                unknownChecks.push(name);
+        }
+    }
+    const allComplete = checks.length > 0 && checks.every((c) => c.complete);
+    const allPassed = checks.length > 0 && checks.every((c) => c.green) && unknownChecks.length === 0;
+    // Stable, order-independent hash: sort by name so array vs map and differing
+    // input order collide, while any status/conclusion change shifts the hash.
+    const hashInput = {
+        checks: [...checks]
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((c) => ({ name: c.name, complete: c.complete, green: c.green })),
+        unknown_checks: [...unknownChecks].sort(),
+    };
+    return {
+        checks,
+        unknown_checks: unknownChecks,
+        check_state_hash: stableJsonHash(hashInput),
+        all_complete: allComplete,
+        all_passed: allPassed,
+    };
+}
+// ---------------------------------------------------------------------------
+// Gate evaluation
+// ---------------------------------------------------------------------------
+function failedEvaluation(reason) {
+    return { met: false, reason };
+}
+/**
+ * Deterministically evaluate a done gate for one binding. Returns `met: true` with
+ * canonical `gate.met` event data (allowlisted top-level keys only) when every
+ * configured required check is present, complete, and green; otherwise `met:
+ * false` with a fail-closed reason and no event data. Pure and deterministic:
+ * identical inputs always produce deep-equal output.
+ */
+export function evaluateDoneGate(config, binding, snapshot, evaluatedAtIso) {
+    if (!config.enabled || !config.valid || config.condition === null) {
+        return failedEvaluation(`gate inactive: ${config.reason}`);
+    }
+    const headSha = normalizeSha(binding.head_sha);
+    if (headSha === null) {
+        return failedEvaluation("invalid binding: head_sha is not a valid SHA");
+    }
+    const byName = new Map();
+    for (const check of snapshot.checks)
+        byName.set(check.name, check);
+    const unknownSet = new Set(snapshot.unknown_checks);
+    const checkResults = [];
+    const unmet = [];
+    for (const name of config.condition.required_checks) {
+        const check = byName.get(name);
+        if (!check) {
+            checkResults.push({ name, present: false, complete: false, green: false });
+            unmet.push(unknownSet.has(name) ? `${name} (unknown)` : `${name} (missing)`);
+            continue;
+        }
+        checkResults.push({ name, present: true, complete: check.complete, green: check.green });
+        if (!check.green) {
+            unmet.push(check.complete ? `${name} (not green)` : `${name} (pending)`);
+        }
+    }
+    if (unmet.length > 0) {
+        return failedEvaluation(`required checks not green: ${unmet.join(", ")}`);
+    }
+    const details = {
+        repo: binding.repo,
+        pr_number: binding.pr_number,
+        head_sha: headSha,
+        gate_name: config.gate_name,
+        config_hash: config.config_hash,
+        condition_type: config.condition.type,
+        required_checks: [...config.condition.required_checks],
+        check_results: checkResults,
+        evaluated_at: evaluatedAtIso,
+    };
+    const gateEventData = {
+        summary: `Done gate "${config.gate_name}" met for ${binding.subject}`,
+        status: "met",
+        details,
+    };
+    return { met: true, reason: "met", gateEventData };
+}