@bridge_gpt/mcp-server 0.2.65 → 0.2.66

package/build/conductor/recovery-operations.js

@@ -18,9 +18,10 @@
  * callers: `recovery-cli.ts` and `plane/shutdown.ts`.
  */
 import { randomUUID } from "crypto";
-import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, patchPolicy, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, fetchChildContinuationStatus, postContinueParkedChild, REVIEW_HEAD_REFUSAL_CODES, } from "./bridge-api-client.js";
+import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, patchPolicy, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, fetchChildContinuationStatus, postContinueParkedChild, resumeCiTicket, REVIEW_HEAD_REFUSAL_CODES, } from "./bridge-api-client.js";
+import { clearGuidedReference, guardForBinding, GUIDED_PAYLOAD_CONFLICT_MESSAGE, GUIDED_REFERENCE_STORE_FAILED_MESSAGE, prepareGuidedRequest, } from "./guided-repair.js";
 import { DEFAULT_GATE_NAME } from "./git-ci-types.js";
-import { clearContinuationReference, computeContinuationFingerprint, isFullSha, newContinuationRequestId, readContinuationReference, writeContinuationReference, } from "./epic-child-continuation.js";
+import { canonicalSha256, clearContinuationReference, clearRecoveryReferenceFile, computeContinuationFingerprint, readRecoveryReferenceFile, writeRecoveryReferenceFile, isFullSha, newContinuationRequestId, readContinuationReference, writeContinuationReference, } from "./epic-child-continuation.js";
 import { resolveLocalMergeCredential, resolveLocalMergeMethod, runApprovedLocalMerge, } from "./local-merge.js";
 import { RESUME_RUN_UNCONFIRMED_MESSAGE } from "./repair-contract.js";
 /**
@@ -453,6 +454,53 @@ export async function resumeRunRepair(access, options, deps = {}) {
         return { ok: false, kind: "unavailable", message: RESUME_RUN_UNCONFIRMED_MESSAGE };
     }
 }
+// ---------------------------------------------------------------------------
+// BAPI-1333 — guided (binding-pinned) repairs
+// ---------------------------------------------------------------------------
+/** The server's refusal code for a guided repair whose pinned subject moved. */
+export const REPAIR_SUBJECT_STALE_CODE = "REPAIR_SUBJECT_STALE";
+/**
+ * Send ONE guided repair request, pinned to its displayed binding.
+ *
+ * The reference (request id, binding digest, payload digest) is durably stored
+ * BEFORE the first POST; a store failure sends nothing and never falls back to
+ * an unguarded or resetting verb. Only a structured 4xx is a definitive answer;
+ * a 5xx, timeout, dropped connection, or unparseable 2xx is `unconfirmed`, and
+ * the reference survives it so a new CLI process re-sends the same request.
+ */
+export async function guidedRepairOnce(options, deps = {}) {
+    const prepared = await prepareGuidedRequest(options.binding, options.payloadDigest, deps);
+    if (prepared.kind === "store_failed") {
+        return { kind: "unavailable", message: GUIDED_REFERENCE_STORE_FAILED_MESSAGE };
+    }
+    if (prepared.kind === "payload_conflict") {
+        return { kind: "unavailable", message: GUIDED_PAYLOAD_CONFLICT_MESSAGE };
+    }
+    const { requestId, referenceReused } = prepared;
+    let result;
+    try {
+        result = await options.send(guardForBinding(options.binding, requestId));
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError &&
+            typeof err.status === "number" &&
+            err.status >= 400 &&
+            err.status < 500 &&
+            err.errorCode) {
+            await clearGuidedReference(options.binding, deps);
+            const message = err.bodyPreview ?? err.errorCode;
+            if (err.errorCode === REPAIR_SUBJECT_STALE_CODE) {
+                return { kind: "stale", code: err.errorCode, message, requestId, referenceReused };
+            }
+            return { kind: "refused", code: err.errorCode, status: err.status, message, requestId };
+        }
+        return { kind: "unconfirmed", message: options.unconfirmedMessage, requestId, referenceReused };
+    }
+    await clearGuidedReference(options.binding, deps);
+    return result.committed
+        ? { kind: "committed", result, requestId, referenceReused }
+        : { kind: "no_op", result, requestId, referenceReused };
+}
 const AUTHORITATIVE_OUTCOMES = new Set([
     "committed",
     "already_continued",
@@ -644,3 +692,278 @@ export async function lookupContinuationReceipt(access, options, deps = {}) {
     }
     return { kind: "not_found", requestId, status };
 }
+// ---------------------------------------------------------------------------
+// BAPI-1326 — `resume-ci`: a pinned, bounded, allowance-preserving CI resume
+// ---------------------------------------------------------------------------
+/** The recovery-reference namespace of pinned `resume-ci` operations. */
+export const RESUME_CI_REFERENCE_NAMESPACE = "epic-ci-resumes";
+/**
+ * Bounded POSTs per invocation. Every POST of one invocation carries the SAME
+ * operation key and stop binding; only the row version may be refreshed, and
+ * only while every original binding still matches.
+ */
+export const RESUME_CI_POST_LIMIT = 3;
+/** The pause before a retry. Injectable so tests never sleep. */
+const RESUME_CI_RETRY_DELAY_MS = 250;
+const FULL_SHA_PATTERN = /^[0-9a-f]{40}$/;
+const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+const CI_STOP_REASON_VALUES = new Set(["wait_expired", "verdict_unavailable", "repair_exhausted"]);
+function isRecordValue(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** Strictly validate a stop binding; `null` for anything short of the contract. */
+export function parseCiStopBinding(value) {
+    if (!isRecordValue(value))
+        return null;
+    const checks = value.required_checks;
+    if (!isNonNegativeInteger(value.park_generation) ||
+        !CI_STOP_REASON_VALUES.has(value.reason) ||
+        typeof value.accepted_head_sha !== "string" || !FULL_SHA_PATTERN.test(value.accepted_head_sha) ||
+        !isNonNegativeInteger(value.pr_number) || value.pr_number < 1 ||
+        typeof value.base_ref !== "string" || !value.base_ref || value.base_ref.length > 200 ||
+        !Array.isArray(checks) || checks.length > 64 ||
+        !checks.every((c) => typeof c === "string" && c.length > 0 && c.length <= 200) ||
+        (value.required_checks_source !== "run" && value.required_checks_source !== "plan") ||
+        typeof value.required_checks_fingerprint !== "string" ||
+        !FINGERPRINT_PATTERN.test(value.required_checks_fingerprint) ||
+        !(value.spec_hash === null || value.spec_hash === undefined ||
+            (typeof value.spec_hash === "string" && value.spec_hash.length > 0 && value.spec_hash.length <= 128))) {
+        return null;
+    }
+    return {
+        park_generation: value.park_generation,
+        reason: value.reason,
+        accepted_head_sha: value.accepted_head_sha,
+        pr_number: value.pr_number,
+        base_ref: value.base_ref,
+        required_checks: [...checks],
+        required_checks_source: value.required_checks_source,
+        required_checks_fingerprint: value.required_checks_fingerprint,
+        spec_hash: (value.spec_hash ?? null),
+    };
+}
+/**
+ * Capture the ACTIVE typed CI stop's binding from authenticated ticket state,
+ * mirroring the server's selection: the ticket is `needs_human`, its single
+ * parked gate is `ci`, and `gates.ci.ci_stop` is a complete typed record for the
+ * gate's current park generation. Never derived from the park's reason text.
+ */
+export function captureCiStopBinding(ticket) {
+    // The client union predates the v2 gate statuses; the server sends them anyway.
+    if (ticket.status !== "needs_human")
+        return { ok: false, reason: "not_parked" };
+    const gates = isRecordValue(ticket.gates) ? ticket.gates : {};
+    const parked = Object.entries(gates).filter(([, state]) => isRecordValue(state) && state.status === "needs_human");
+    if (parked.length !== 1 || parked[0][0] !== "ci")
+        return { ok: false, reason: "not_ci_park" };
+    const ci = parked[0][1];
+    const stop = ci.ci_stop;
+    if (!isRecordValue(stop) || !isRecordValue(stop.evidence))
+        return { ok: false, reason: "no_typed_stop" };
+    const generation = isNonNegativeInteger(ci.park_generation) ? ci.park_generation : 0;
+    if (stop.park_generation !== generation)
+        return { ok: false, reason: "stop_superseded" };
+    const evidence = stop.evidence;
+    const binding = parseCiStopBinding({
+        park_generation: stop.park_generation,
+        reason: stop.reason,
+        accepted_head_sha: stop.accepted_head_sha,
+        pr_number: evidence.pr_number,
+        base_ref: evidence.base_ref,
+        required_checks: evidence.required_checks,
+        required_checks_source: evidence.required_checks_source,
+        required_checks_fingerprint: evidence.required_checks_fingerprint,
+        spec_hash: evidence.spec_hash ?? null,
+    });
+    return binding === null ? { ok: false, reason: "no_typed_stop" } : { ok: true, binding };
+}
+/** The fingerprint of a pinned operation's identity (the row version excluded). */
+export function computeCiResumeFingerprint(ref) {
+    return canonicalSha256({
+        v: 1,
+        operation: "resume_ci",
+        target: { repo_name: ref.repoName, epic_run_id: ref.epicRunId, ticket_key: ref.ticketKey },
+        operation_key: ref.operationKey,
+        stop_binding: ref.stopBinding,
+    });
+}
+function parseCiResumeReference(raw) {
+    if (!isRecordValue(raw) || raw.version !== 1 || raw.operation !== "resume_ci")
+        return null;
+    const binding = parseCiStopBinding(raw.stopBinding);
+    if (binding === null ||
+        typeof raw.repoName !== "string" || !raw.repoName ||
+        typeof raw.epicRunId !== "string" || !raw.epicRunId ||
+        typeof raw.ticketKey !== "string" || !raw.ticketKey ||
+        !isNonNegativeInteger(raw.expectedRowVersion) ||
+        typeof raw.operationKey !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/.test(raw.operationKey) ||
+        typeof raw.fingerprint !== "string") {
+        return null;
+    }
+    const ref = {
+        version: 1,
+        operation: "resume_ci",
+        repoName: raw.repoName,
+        epicRunId: raw.epicRunId,
+        ticketKey: raw.ticketKey,
+        expectedRowVersion: raw.expectedRowVersion,
+        operationKey: raw.operationKey,
+        stopBinding: binding,
+        fingerprint: raw.fingerprint,
+        createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "",
+    };
+    // A reference whose fingerprint no longer matches its own identity was
+    // tampered with or truncated; it never authorizes a replay.
+    return computeCiResumeFingerprint(ref) === ref.fingerprint ? ref : null;
+}
+function sameBinding(a, b) {
+    return canonicalSha256(a) === canonicalSha256(b);
+}
+async function readCiResumeReference(key, store) {
+    return parseCiResumeReference(await readRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, key, store));
+}
+/**
+ * Resume a ticket parked on a qualified CI stop, with its operation pinned.
+ *
+ * A pinned reference for this ticket is REUSED as-is — same operation key, same
+ * stop binding — so a lost response or a restarted process is answered from the
+ * server's durable receipt, and a later park is never silently targeted. Only
+ * when no reference exists is the binding read (once) from authenticated ticket
+ * state, and the reference is stored BEFORE the first POST.
+ *
+ * At most {@link RESUME_CI_POST_LIMIT} POSTs, all with the same key and binding.
+ * A row-version conflict refreshes the row version only while every original
+ * binding still matches; otherwise the result is `stale_reference` and nothing
+ * more is sent. There is no fallback to unpark, continue-child, or any other
+ * mutation.
+ */
+export async function resumeCiOnce(access, options, deps = {}) {
+    const fetchState = deps.fetchState ?? fetchEpicRunState;
+    const post = deps.post ?? resumeCiTicket;
+    const store = deps.store ?? {};
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const callerKey = { epicRunId: options.epicRunId, ticketKey: options.ticketKey };
+    let reference = await readCiResumeReference(callerKey, store);
+    if (reference !== null && reference.repoName !== access.repoName)
+        reference = null;
+    const reusedReference = reference !== null;
+    const persist = async (ref) => {
+        await writeRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, callerKey, ref, store);
+        if (ref.epicRunId !== callerKey.epicRunId || ref.ticketKey !== callerKey.ticketKey) {
+            await writeRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, { epicRunId: ref.epicRunId, ticketKey: ref.ticketKey }, ref, store);
+        }
+    };
+    const readTicket = async () => {
+        try {
+            const state = await fetchState(access, options.epicRunId);
+            return state.ticket_statuses.find((t) => t.ticket_key === options.ticketKey) ?? null;
+        }
+        catch {
+            return "unavailable";
+        }
+    };
+    if (reference === null) {
+        const ticket = await readTicket();
+        if (ticket === "unavailable") {
+            return { kind: "unavailable", message: "could not read the ticket's state, so nothing was sent" };
+        }
+        if (ticket === null)
+            return { kind: "not_eligible", reason: "ticket_not_found" };
+        const captured = captureCiStopBinding(ticket);
+        if (!captured.ok)
+            return { kind: "not_eligible", reason: captured.reason };
+        const identity = {
+            repoName: access.repoName,
+            epicRunId: ticket.epic_run_id,
+            ticketKey: ticket.ticket_key,
+            operationKey: (deps.newOperationKey ?? randomUUID)(),
+            stopBinding: captured.binding,
+        };
+        reference = {
+            version: 1,
+            operation: "resume_ci",
+            ...identity,
+            expectedRowVersion: ticket.row_version,
+            fingerprint: computeCiResumeFingerprint(identity),
+            createdAt: (deps.now ?? (() => new Date()))().toISOString(),
+        };
+        try {
+            await persist(reference);
+        }
+        catch {
+            return {
+                kind: "unavailable",
+                message: "could not store the local recovery reference, so the request was not sent",
+            };
+        }
+    }
+    const clear = async (ref) => {
+        await clearRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, callerKey, store);
+        await clearRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, { epicRunId: ref.epicRunId, ticketKey: ref.ticketKey }, store);
+    };
+    let ref = reference;
+    let last = null;
+    for (let attempt = 1; attempt <= RESUME_CI_POST_LIMIT; attempt += 1) {
+        if (attempt > 1)
+            await sleep(RESUME_CI_RETRY_DELAY_MS * (attempt - 1));
+        const outcome = await post(access, {
+            epicRunId: ref.epicRunId,
+            ticketKey: ref.ticketKey,
+            expectedRowVersion: ref.expectedRowVersion,
+            operationKey: ref.operationKey,
+            stopBinding: ref.stopBinding,
+        });
+        last = outcome;
+        if (outcome.kind === "result") {
+            await clear(ref);
+            return { kind: outcome.result.outcome, result: outcome.result, reusedReference };
+        }
+        if (outcome.kind === "uncertain")
+            continue;
+        if (outcome.kind === "refused" && outcome.errorCode === "CI_RESUME_BUSY")
+            continue;
+        if (outcome.kind === "refused" && outcome.errorCode === "ROW_VERSION_CONFLICT") {
+            // Refresh the row version ONLY while the stop is still the same one.
+            const ticket = await readTicket();
+            if (ticket === "unavailable" || ticket === null) {
+                return { kind: "refused", errorCode: outcome.errorCode, status: outcome.status, reusedReference };
+            }
+            const current = captureCiStopBinding(ticket);
+            if (!current.ok || !sameBinding(current.binding, ref.stopBinding)) {
+                return { kind: "stale_reference", reusedReference };
+            }
+            ref = { ...ref, expectedRowVersion: ticket.row_version };
+            try {
+                await persist(ref);
+            }
+            catch {
+                return {
+                    kind: "unavailable",
+                    message: "could not update the local recovery reference, so the retry was not sent",
+                };
+            }
+            continue;
+        }
+        // Every other refusal or rejection is authoritative: nothing was written,
+        // and this operation is finished.
+        await clear(ref);
+        return {
+            kind: "refused",
+            errorCode: outcome.errorCode ?? "REQUEST_REJECTED",
+            status: outcome.status,
+            reusedReference,
+        };
+    }
+    if (last !== null && last.kind === "refused") {
+        // Busy or row-version churn for the whole budget: nothing was written, and
+        // the pinned reference is kept for the next invocation.
+        return { kind: "refused", errorCode: last.errorCode, status: last.status, reusedReference };
+    }
+    const transport = last !== null && last.kind === "uncertain"
+        ? last.status !== undefined ? `${last.reason} (status ${last.status})` : last.reason
+        : "indeterminate";
+    return { kind: "unconfirmed", transport, reusedReference, attempts: RESUME_CI_POST_LIMIT };
+}

package/build/conductor/repair-contract.js

@@ -1,7 +1,8 @@
 /**
- * The shared contract for the six run-addressed operator repair verbs: BAPI-1154's
- * `scope-reparse`, `dispatch-remediation`, and `merge-child`, and BAPI-1176's
- * `scope-catch-up`, `patch-policy`, and `resume-run`.
+ * The shared contract for the seven operator repair verbs: BAPI-1154's
+ * `scope-reparse`, `dispatch-remediation`, and `merge-child`, BAPI-1176's
+ * `scope-catch-up`, `patch-policy`, and `resume-run`, and BAPI-1326's
+ * ticket-addressed `resume-ci`.
  *
  * CLI-only, exactly like the BAPI-872 recovery verbs: none of these names is ever
  * registered as an MCP tool (`index-static.test.ts` pins that). This module is the
@@ -20,6 +21,7 @@ export const VERB_MERGE_CHILD = "merge-child";
 export const VERB_SCOPE_CATCH_UP = "scope-catch-up";
 export const VERB_PATCH_POLICY = "patch-policy";
 export const VERB_RESUME_RUN = "resume-run";
+export const VERB_RESUME_CI = "resume-ci";
 /** Every repair verb, in the order an operator meets them. */
 export const OPERATOR_REPAIR_VERBS = [
     VERB_SCOPE_REPARSE,
@@ -28,6 +30,7 @@ export const OPERATOR_REPAIR_VERBS = [
     VERB_SCOPE_CATCH_UP,
     VERB_PATCH_POLICY,
     VERB_RESUME_RUN,
+    VERB_RESUME_CI,
 ];
 /**
  * The ONE cap on driver context, in UTF-8 BYTES — the same number the server
@@ -92,9 +95,64 @@ export const OPERATOR_REPAIR_REFUSAL_CODES = [
     "RUN_STOPPED",
     "QUARANTINE_CLEARANCE_REQUIRED",
     "RUN_CONTROL_CONFLICT",
+    // BAPI-1326
+    "CI_STOP_NOT_ELIGIBLE",
+    "CI_RESUME_STALE_OPERATION",
+    "CI_RESUME_OPERATION_CONFLICT",
+    "CI_RESUME_BINDING_CHANGED",
+    "CI_RESUME_POLICY_CHANGED",
+    "CI_RESUME_SPEC_CHANGED",
+    "CI_RESUME_CHECKS_NOT_GREEN",
+    "CI_RESUME_VERDICT_UNAVAILABLE",
+    "CI_RESUME_HELD",
+    "CI_RESUME_LIVE_WORK",
+    "CI_RESUME_BUDGET_EXHAUSTED",
+    "CI_RESUME_BUSY",
+    // BAPI-1333
+    "GUIDED_REPAIR_DISABLED",
+    "REPAIR_SUBJECT_STALE",
 ];
 /** True when `code` is one of the closed repair refusal codes. */
 export function isOperatorRepairRefusalCode(code) {
     return (typeof code === "string" &&
         OPERATOR_REPAIR_REFUSAL_CODES.includes(code));
 }
+// ---------------------------------------------------------------------------
+// BAPI-1326 — `resume-ci`
+// ---------------------------------------------------------------------------
+/**
+ * The closed `resume-ci` refusal subset, in the order the server checks them —
+ * mirrors `CI_RESUME_REFUSAL_CODES` in `operator_repair_contract.py`.
+ */
+export const CI_RESUME_REFUSAL_CODES = [
+    "TICKET_NOT_IN_RUN",
+    "CI_STOP_NOT_ELIGIBLE",
+    "CI_RESUME_STALE_OPERATION",
+    "CI_RESUME_OPERATION_CONFLICT",
+    "ROW_VERSION_CONFLICT",
+    "RUN_NOT_DISPATCHABLE",
+    "CI_RESUME_BUDGET_EXHAUSTED",
+    "CI_RESUME_HELD",
+    "CI_RESUME_LIVE_WORK",
+    "CI_RESUME_SPEC_CHANGED",
+    "CI_RESUME_POLICY_CHANGED",
+    "CI_RESUME_BINDING_CHANGED",
+    "CI_RESUME_CHECKS_NOT_GREEN",
+    "CI_RESUME_VERDICT_UNAVAILABLE",
+    "CI_RESUME_BUSY",
+];
+/**
+ * The closed outcome vocabulary. The server answers `committed` or `replayed`;
+ * `refused` is a structured error, and `unconfirmed` is minted only by the client
+ * when no durable answer arrived.
+ */
+export const CI_RESUME_OUTCOMES = ["committed", "replayed", "refused", "unconfirmed"];
+/**
+ * Receipt retention: only the latest committed operation per ticket is kept. A
+ * request whose receipt was displaced is refused as stale, never replayed.
+ */
+export const CI_RESUME_RECEIPT_RETENTION = "latest_only";
+/** True when `code` is one of the closed `resume-ci` refusal codes. */
+export function isCiResumeRefusalCode(code) {
+    return (typeof code === "string" && CI_RESUME_REFUSAL_CODES.includes(code));
+}

package/build/credential-store.js

@@ -38,6 +38,7 @@
  * user-scoped `~/.config/bridge/credentials.json` store written here.
  */
 import path from "path";
+import { diagnosticComponent } from "./epic-launch-diagnostic.js";
 // ---------------------------------------------------------------------------
 // Path resolution
 // ---------------------------------------------------------------------------
@@ -1497,9 +1498,9 @@ export async function resolveEpicLaunchCredential(repoName, targetBaseUrl, deps,
         return {
             ok: false,
             kind: "binding-unbound",
-            error: `The stored credential "${bundleKey}" has not been approved for this Bridge API endpoint ` +
-                `(${primaryPath}). Production needs no approval; any other endpoint does. Run guided setup ` +
-                `once to bind it: install conductor --launch-profile <name> --base-url ${target}.`,
+            error: `The stored credential "${diagnosticComponent(bundleKey)}" has not been approved for this Bridge API endpoint ` +
+                `(${diagnosticComponent(primaryPath)}). Production needs no approval; any other endpoint does. Run guided setup ` +
+                `once to bind it: install conductor --launch-profile <name> --base-url ${diagnosticComponent(target)}.`,
         };
     }
     // An unreadable read-back is refused like a mismatch: the key was read a
@@ -1508,7 +1509,7 @@ export async function resolveEpicLaunchCredential(repoName, targetBaseUrl, deps,
         return {
             ok: false,
             kind: "binding-mismatch",
-            error: `The stored credential "${bundleKey}" is approved for a different Bridge API endpoint than the ` +
+            error: `The stored credential "${diagnosticComponent(bundleKey)}" is approved for a different Bridge API endpoint than the ` +
                 "selected target. It was not sent. A key approved for a local server is never sent to " +
                 "production: pass that server's --launch-profile <name> or --base-url <url>, or bind the key " +
                 "once with install conductor --launch-profile <name> --base-url <url>.",

package/build/diagnostic-text.js

@@ -0,0 +1,36 @@
+/**
+ * Single-line rendering for untrusted values in diagnostics (BAPI-1318).
+ *
+ * Project names read from `.bridge/config` or an MCP config env block, and paths
+ * read from `BAPI_PROJECT_ROOT`, are user-controlled. A newline or other control
+ * character in one of them could forge an extra line in a stderr diagnostic or a
+ * doctor report. This renderer escapes every ASCII control character and bounds
+ * the length, so each value always occupies exactly one line of output.
+ */
+/** Longest rendered value; anything longer is cut and marked with an ellipsis. */
+export const DIAGNOSTIC_VALUE_MAX_LENGTH = 200;
+/**
+ * Render `value` for a one-line diagnostic: control characters become `\xNN`
+ * (with `\n`, `\r`, and `\t` spelled out), and the result is bounded to
+ * {@link DIAGNOSTIC_VALUE_MAX_LENGTH} characters.
+ */
+export function renderDiagnosticValue(value) {
+    let out = "";
+    for (const ch of value) {
+        const code = ch.charCodeAt(0);
+        if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (code <= 0x1f || code === 0x7f)
+            out += `\\x${code.toString(16).padStart(2, "0")}`;
+        else
+            out += ch;
+    }
+    if (out.length > DIAGNOSTIC_VALUE_MAX_LENGTH) {
+        out = `${out.slice(0, DIAGNOSTIC_VALUE_MAX_LENGTH)}…`;
+    }
+    return out;
+}