@bridge_gpt/mcp-server 0.2.52 → 0.2.53

package/build/plane/types.js

@@ -143,6 +143,42 @@ export const PLANE_OBSERVER_MODE_VALUE = "true";
 export const PLANE_OBSERVER_CHANNEL_TYPE_ENV = "CONDUCTOR_DEADMAN_CHANNEL_TYPE";
 /** Env var naming the env var that holds the observer's destination URL. */
 export const PLANE_OBSERVER_DESTINATION_ENV = "CONDUCTOR_DEADMAN_DESTINATION_REF";
+/** Build a {@link PlaneCheckReport} for a check that ran and passed. */
+export function planeCheckPassed(check, label, detail) {
+    return {
+        diagnostic: null,
+        outcomes: [{ check, id: check, label, status: "pass", ...(detail ? { detail } : {}) }],
+    };
+}
+/**
+ * Build a {@link PlaneCheckReport} from a diagnostic plus its structured fix.
+ *
+ * The severity is the single source of the canonical status — `blocking` is
+ * `fail`, `warning` is `warn` — so the two can never disagree about the same
+ * finding.
+ */
+export function planeCheckFinding(diagnostic, label, detail) {
+    return {
+        diagnostic,
+        outcomes: [
+            {
+                check: diagnostic.check,
+                id: diagnostic.check,
+                label,
+                status: diagnostic.severity === "blocking" ? "fail" : "warn",
+                detail,
+                ...(diagnostic.remediation ? { remediation: diagnostic.remediation } : {}),
+            },
+        ],
+    };
+}
+/** Build a {@link PlaneCheckReport} for a check that was never reached. */
+export function planeCheckSkipped(check, label, detail) {
+    return {
+        diagnostic: null,
+        outcomes: [{ check, id: check, label, status: "skip", detail }],
+    };
+}
 /**
  * Every value {@link PlaneHeartbeatComponent} may take, for runtime guards.
  *

package/build/readiness-check.js

@@ -0,0 +1,412 @@
+/**
+ * The canonical shared readiness-check contract (BAPI-1055, AC-6).
+ *
+ * Conductor prerequisite probing is spread across five loci — `bridge doctor`
+ * ({@link file:./install-doctor.ts}), `conductor doctor`
+ * ({@link file:./conductor/doctor.ts}), `plane` preflight
+ * ({@link file:./plane/preflight.ts}), the server `conductor-readiness`
+ * collector, and the unified install doctor
+ * ({@link file:./conductor/install-doctor.ts}) that already composes four of
+ * them. Each speaks its own status vocabulary. This module is the ONE record
+ * shape they are all projected into, so a consolidated report can say
+ * pass/fail and name exactly one remediation per failure without any locus
+ * having to abandon its own verdicts.
+ *
+ * DEPENDENCY-NEUTRAL LEAF. It imports nothing: no fs, no network, no CLI, no
+ * sibling diagnostic. That is what makes it safe to import from every surface,
+ * including ones pinned to issue zero probes.
+ *
+ * ## Exhaustive source-status mapping (the accepted four-state vocabulary)
+ *
+ * The shared vocabulary has FOUR states, not three, because four is the
+ * minimum that lets every source verdict round-trip without a lossy merge.
+ * Collapsing `degraded` onto `fail` would make a fallback npm channel read
+ * identically to an unusable ledger, which would contradict the rule that each
+ * section's own advisory semantics stay unchanged.
+ *
+ * | Source                              | Source verdict                | Canonical |
+ * | ----------------------------------- | ----------------------------- | --------- |
+ * | `install-doctor` `InstallCheckStatus`  | `PASS`                        | `pass`    |
+ * | `install-doctor` `InstallCheckStatus`  | `WARN`                        | `warn`    |
+ * | `install-doctor` `InstallCheckStatus`  | `SKIP`                        | `skip`    |
+ * | `install-doctor` `InstallCheckStatus`  | `INFO`                        | see below |
+ * | `conductor/install-doctor` section  | `ok`                          | `pass`    |
+ * | `conductor/install-doctor` section  | `degraded`                    | `warn`    |
+ * | `conductor/install-doctor` section  | `fatal`                       | `fail`    |
+ * | `conductor/doctor` inspection       | `degraded: true`              | `warn`    |
+ * | `plane` diagnostic                  | `severity: "warning"`         | `warn`    |
+ * | `plane` diagnostic                  | `severity: "blocking"`         | `fail`    |
+ * | server readiness                    | unreadable / `null` / missing | `fail`    |
+ *
+ * `INFO` never becomes a canonical status. It is informational by definition,
+ * so its content is preserved in {@link ReadinessCheck.detail} while the check
+ * takes `pass`, `warn`, or `skip` according to that check's own established
+ * semantics — chosen per check id by the adapter, never guessed here.
+ *
+ * Three states are deliberately NOT interchangeable:
+ *
+ * - `fail` means a prerequisite is not satisfied, INCLUDING the case where its
+ *   state could not be established. An unreadable liveness read, a failed
+ *   permission probe, `executor.ready === null`, and a field a newer server
+ *   would have sent are all `fail` with a remediation for restoring the probe.
+ *   Uncertainty must never appear healthy.
+ * - `warn` means the prerequisite is degraded but usable, or a launch-permitting
+ *   plane warning. It is not a soft failure and is never derived from silence.
+ * - `skip` means the check genuinely did not apply or a dependency prevented it
+ *   from running. It is never used to hide an unknown.
+ *
+ * ## The failure/remediation invariant
+ *
+ * AC-6 requires exactly ONE named remediation on every failure, so the union
+ * below makes that a property of the type: the `fail` variant REQUIRES one
+ * non-empty scalar remediation and the `pass` variant PROHIBITS one. `warn` and
+ * `skip` may each carry at most one, because an actionable warning and the
+ * actionable deny-probe skip both have a named next step, while a
+ * dependency-driven skip has none.
+ *
+ * ## Secret discipline
+ *
+ * Every `detail` and `remediation` is fixed prose plus non-secret facts: a
+ * label, a closed enum, a count, a boolean, a timestamp, a relative identifier,
+ * or an approved base/setup URL. The helpers here cap length, strip control
+ * characters, and refuse obvious absolute paths — but they are a last line of
+ * defence, NOT permission to pass a raw exception, subprocess output, a request
+ * header, a response body, or a credential into the constructor. Projecting
+ * source data into safe prose is the adapter's job; this module only refuses
+ * the most obvious leaks.
+ */
+/** Every valid status, for exhaustive validation and test enumeration. */
+export const READINESS_CHECK_STATUSES = [
+    "pass",
+    "warn",
+    "fail",
+    "skip",
+];
+/** Every valid source, for exhaustive validation and test enumeration. */
+export const READINESS_CHECK_SOURCES = [
+    "install",
+    "conductor",
+    "plane",
+    "server",
+];
+/** Raised by {@link createReadinessCheck} for input that cannot be projected. */
+export class ReadinessCheckValidationError extends Error {
+    constructor(reason) {
+        // The reason names the RULE that was broken, never the offending value: the
+        // value is exactly the untrusted material this module exists to keep out of
+        // output, and an error message is an output.
+        super(`invalid readiness check: ${reason}`);
+        this.name = "ReadinessCheckValidationError";
+    }
+}
+/** Length cap for a projected detail line. */
+export const READINESS_DETAIL_MAX_LENGTH = 400;
+/** Length cap for a projected remediation. */
+export const READINESS_REMEDIATION_MAX_LENGTH = 400;
+/**
+ * Stable id grammar: `<source>.<segment>[.<segment>...]`.
+ *
+ * Lowercase, digits, and hyphens only. Whitespace, uppercase, quotes, slashes,
+ * and colons are all rejected, which is what makes an interpolated value — a
+ * path, a repo name, an error string — structurally unable to become an id.
+ */
+const ID_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
+const READINESS_ID_PATTERN = new RegExp(`^${ID_SEGMENT}(?:\\.${ID_SEGMENT})+$`);
+/**
+ * Filesystem roots an absolute POSIX path leak actually starts with.
+ *
+ * An allowlist of DANGER rather than a general "starts with a slash" rule,
+ * because the strings this contract legitimately carries are full of leading
+ * slashes that are not paths at all: the slash commands remediations name
+ * (`/install-bridge`), and the endpoint identifiers details name (`/jira/ping`).
+ * Rejecting those would push adapters toward vaguer prose without removing any
+ * real leak — the leak is always a home, temp, or system root.
+ */
+const POSIX_PATH_ROOTS = [
+    "Users",
+    "home",
+    "root",
+    "var",
+    "tmp",
+    "private",
+    "opt",
+    "usr",
+    "etc",
+    "srv",
+    "mnt",
+    "media",
+    "Applications",
+    "Library",
+    "System",
+    "Volumes",
+    "node_modules",
+];
+/**
+ * Absolute POSIX and Windows paths, and `file://` URLs.
+ *
+ * Deliberately narrow: it catches the obvious leak (`/Users/...`, `/private/tmp/...`,
+ * `C:\\...`) without rejecting the relative, repository-conventional paths
+ * remediations legitimately name (`.github/workflows/claude-review.yml`,
+ * `docs/claude/epic-conductor-v2-operator-runbook.md`) or the approved setup
+ * URLs (`https://host/setup`) — note the Windows drive alternative requires a
+ * word boundary before the letter, so the `s:/` inside `https://` is not a hit.
+ */
+const ABSOLUTE_PATH_PATTERN = new RegExp("(^|[\\s\"'`(<])(?:" +
+    `\\/(?:${POSIX_PATH_ROOTS.join("|")})\\/` +
+    "|[A-Za-z]:[\\\\/]" +
+    "|file:\\/\\/)");
+/** True when `value` looks like it embeds an absolute filesystem path. */
+export function containsAbsolutePath(value) {
+    return ABSOLUTE_PATH_PATTERN.test(value);
+}
+/**
+ * Request headers and serialized response bodies.
+ *
+ * Both have recognizable shapes, which is what makes them worth refusing here:
+ * unlike a credential value — a random-looking string no validator can tell
+ * from a repository name — an `Authorization:` header or a JSON object body
+ * announces itself. Neither belongs in a report field under any circumstances,
+ * so this is a structural refusal rather than a judgement call.
+ *
+ * The credential value itself is NOT covered, and cannot be: nothing in this
+ * module ever holds one. That guarantee lives at the collectors that do, which
+ * is why they author prose instead of copying resolver output.
+ */
+const TRANSPORT_ARTIFACT_PATTERN = /(^|[\s"'`(<])(?:authorization\s*:|x-api-key\s*:|bearer\s+\S|\{\s*"[A-Za-z_$][\w$]*"\s*:)/i;
+/** True when `value` looks like a request header or a serialized response body. */
+export function containsTransportArtifact(value) {
+    return TRANSPORT_ARTIFACT_PATTERN.test(value);
+}
+/**
+ * Normalize already-projected prose for a bounded, secret-free field.
+ *
+ * Strips control characters (including the newlines that would let one field
+ * forge another report line), collapses runs of whitespace, trims, and caps the
+ * length. Throws when the result is empty or still looks like an absolute path.
+ */
+function normalizeProse(value, field, maxLength) {
+    if (typeof value !== "string") {
+        // Arrays are called out by name because "one remediation" is the invariant
+        // an array silently violates: a caller handing over two fixes is not a
+        // formatting problem, it is a contract violation.
+        throw new ReadinessCheckValidationError(Array.isArray(value) ? `${field} must be a single string, not an array` : `${field} must be a string`);
+    }
+    // eslint-disable-next-line no-control-regex -- stripping control characters is the point
+    const stripped = value.replace(/[\u0000-\u001f\u007f]+/g, " ");
+    const collapsed = stripped.replace(/\s{2,}/g, " ").trim();
+    if (collapsed.length === 0) {
+        throw new ReadinessCheckValidationError(`${field} must not be blank`);
+    }
+    if (containsAbsolutePath(collapsed)) {
+        throw new ReadinessCheckValidationError(`${field} must not contain an absolute path`);
+    }
+    if (containsTransportArtifact(collapsed)) {
+        throw new ReadinessCheckValidationError(`${field} must not contain a request header or a response body`);
+    }
+    return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength - 1).trimEnd()}…` : collapsed;
+}
+/** Normalize a detail line. Exported so adapters project through one helper. */
+export function normalizeReadinessDetail(value) {
+    return normalizeProse(value, "detail", READINESS_DETAIL_MAX_LENGTH);
+}
+/** Normalize a remediation. Exported so adapters project through one helper. */
+export function normalizeReadinessRemediation(value) {
+    return normalizeProse(value, "remediation", READINESS_REMEDIATION_MAX_LENGTH);
+}
+/**
+ * Build one validated {@link ReadinessCheck}.
+ *
+ * The ONLY sanctioned way to construct a canonical check. It enforces the
+ * failure/remediation invariant, the id namespace, the closed vocabularies, and
+ * the bounded secret-free field rules — so a report cannot acquire a failure
+ * with no fix, a fix attached to a pass, or an id derived from untrusted input.
+ *
+ * Throws {@link ReadinessCheckValidationError}; callers assembling a report from
+ * external material should route through {@link validateReadinessChecks}, which
+ * converts a throw into a stable failed check rather than losing the locus.
+ */
+export function createReadinessCheck(input) {
+    if (input === null || typeof input !== "object") {
+        throw new ReadinessCheckValidationError("check must be an object");
+    }
+    if (!READINESS_CHECK_SOURCES.includes(input.source)) {
+        throw new ReadinessCheckValidationError("source is not a supported readiness source");
+    }
+    if (!READINESS_CHECK_STATUSES.includes(input.status)) {
+        throw new ReadinessCheckValidationError("status is not a supported readiness status");
+    }
+    if (typeof input.id !== "string" || !READINESS_ID_PATTERN.test(input.id)) {
+        throw new ReadinessCheckValidationError("id is not a stable dotted lowercase identifier");
+    }
+    if (!input.id.startsWith(`${input.source}.`)) {
+        throw new ReadinessCheckValidationError("id namespace does not match its source");
+    }
+    const label = normalizeProse(input.label, "label", READINESS_DETAIL_MAX_LENGTH);
+    const detail = input.detail === undefined ? undefined : normalizeReadinessDetail(input.detail);
+    if (input.status === "pass") {
+        if (input.remediation !== undefined) {
+            // A pass with a fix attached is how a report starts telling operators to
+            // act on things that are already fine, which is how they learn to ignore it.
+            throw new ReadinessCheckValidationError("a passing check must not carry a remediation");
+        }
+        return { id: input.id, source: input.source, label, status: "pass", ...(detail ? { detail } : {}) };
+    }
+    if (input.status === "fail") {
+        if (input.remediation === undefined) {
+            throw new ReadinessCheckValidationError("a failing check must carry exactly one remediation");
+        }
+        return {
+            id: input.id,
+            source: input.source,
+            label,
+            status: "fail",
+            ...(detail ? { detail } : {}),
+            remediation: normalizeReadinessRemediation(input.remediation),
+        };
+    }
+    const remediation = input.remediation === undefined ? undefined : normalizeReadinessRemediation(input.remediation);
+    return {
+        id: input.id,
+        source: input.source,
+        label,
+        status: input.status,
+        ...(detail ? { detail } : {}),
+        ...(remediation ? { remediation } : {}),
+    };
+}
+/** Fixed prose for a check that had to be replaced because it was malformed. */
+export const READINESS_MALFORMED_CHECK_DETAIL = "this prerequisite reported a result that failed the readiness contract, so its real state is unknown";
+/** Fixed remediation for a replaced malformed check. */
+export const READINESS_MALFORMED_CHECK_REMEDIATION = "re-run `conductor readiness`; if it persists, run `conductor doctor` and `install conductor` to re-collect this locus.";
+/** Fixed label for a replaced malformed check. */
+export const READINESS_MALFORMED_CHECK_LABEL = "Unreadable prerequisite";
+/**
+ * Validate a whole array of checks, replacing every malformed entry with a
+ * stable, source-scoped failure rather than dropping it.
+ *
+ * Dropping is the dangerous direction: a locus that vanished reads as "nothing
+ * to report", while a failed check with fixed prose reads as "this could not be
+ * established" — which is the truth. The replacement satisfies the
+ * one-remediation invariant like any other failure.
+ *
+ * `fallbackSource` is used when the malformed entry does not even carry a usable
+ * source, so the substitute still lands in a namespace a reader can act on.
+ */
+export function validateReadinessChecks(checks, fallbackSource = "conductor") {
+    const validated = [];
+    let malformedIndex = 0;
+    for (const candidate of checks) {
+        try {
+            validated.push(createReadinessCheck(candidate));
+        }
+        catch {
+            const raw = (candidate ?? {});
+            const source = READINESS_CHECK_SOURCES.includes(raw.source)
+                ? raw.source
+                : fallbackSource;
+            // The malformed entry's OWN id is never reused: it is the untrusted value
+            // that failed validation, so the substitute gets a generated stable id in
+            // the right namespace instead.
+            malformedIndex += 1;
+            validated.push(createReadinessCheck({
+                id: `${source}.unreadable-check-${malformedIndex}`,
+                source,
+                label: READINESS_MALFORMED_CHECK_LABEL,
+                status: "fail",
+                detail: READINESS_MALFORMED_CHECK_DETAIL,
+                remediation: READINESS_MALFORMED_CHECK_REMEDIATION,
+            }));
+        }
+    }
+    return validated;
+}
+/** Count checks by canonical status. Pure; used by report summaries and tests. */
+export function summarizeReadinessChecks(checks) {
+    const counts = { pass: 0, warn: 0, fail: 0, skip: 0 };
+    for (const check of checks)
+        counts[check.status] += 1;
+    return counts;
+}
+/** Fixed stand-in for a source detail that failed the secret-safety contract. */
+export const READINESS_UNSAFE_DETAIL_REPLACEMENT = "detail withheld — the source reported it in a form this report may not carry";
+/** Fixed stand-in for a source remediation that failed the secret-safety contract. */
+export const READINESS_UNSAFE_REMEDIATION_REPLACEMENT = "re-run `conductor readiness`; this prerequisite's own fix text could not be carried into this report safely.";
+/**
+ * Build a check, degrading REJECTED prose rather than losing the finding — and
+ * never throwing.
+ *
+ * Legacy sections and diagnostics author their prose for a terminal, and some of
+ * them legitimately name an absolute path there — the executor service-unit
+ * collector reports the LaunchAgents directory it searched, for instance. That
+ * is fine in the report it was written for and NOT fine in this one, which is a
+ * wider surface.
+ *
+ * The two obvious responses are both wrong. Passing it through would put a home
+ * directory into the consolidated report; dropping the whole check on a
+ * validation failure would silently remove a real prerequisite because its prose
+ * was unsafe. So the offending FIELD is replaced and the id, label, and status —
+ * the parts an operator acts on — survive.
+ *
+ * The ladder degrades one field at a time, least-destructive first, so a check
+ * loses no more of itself than the failure requires. The last rung is a stable
+ * failure in the same namespace: this function is called from inside
+ * {@link file:./conductor/readiness.ts}'s checks-array literal, which is built
+ * BEFORE {@link validateReadinessChecks} runs, so a throw here would escape the
+ * aggregator's "never throws" contract rather than being absorbed by it. An
+ * earlier revision of this function replaced only `detail` and justified the gap
+ * by pointing at that later validation pass — which does not run early enough to
+ * catch it.
+ */
+export function createReadinessCheckSafely(input) {
+    // A pass may not carry a remediation at all, so for a pass the field is
+    // DROPPED rather than replaced — substituting prose there would invent an
+    // action for a prerequisite that is already satisfied.
+    const safeRemediation = () => input?.status === "pass"
+        ? { remediation: undefined }
+        : { remediation: READINESS_UNSAFE_REMEDIATION_REPLACEMENT };
+    // 1. As authored.
+    try {
+        return createReadinessCheck(input);
+    }
+    catch {
+        /* fall through */
+    }
+    // 2. The detail alone — the field untrusted source prose usually arrives in.
+    try {
+        return createReadinessCheck({ ...input, detail: READINESS_UNSAFE_DETAIL_REPLACEMENT });
+    }
+    catch {
+        /* fall through */
+    }
+    // 3. The remediation alone, keeping a detail that was never the problem.
+    try {
+        return createReadinessCheck({ ...input, ...safeRemediation() });
+    }
+    catch {
+        /* fall through */
+    }
+    // 4. Both.
+    try {
+        return createReadinessCheck({
+            ...input,
+            detail: READINESS_UNSAFE_DETAIL_REPLACEMENT,
+            ...safeRemediation(),
+        });
+    }
+    catch {
+        /* fall through */
+    }
+    // 5. Structurally invalid — a bad id, source, or status, which is a caller bug
+    //    rather than untrusted prose. Reported as an unreadable prerequisite in the
+    //    caller's namespace when it named a usable one, exactly as
+    //    `validateReadinessChecks` would have. Never a throw, and never a pass.
+    const source = READINESS_CHECK_SOURCES.includes(input?.source) ? input.source : "conductor";
+    return createReadinessCheck({
+        id: `${source}.unreadable-check`,
+        source,
+        label: READINESS_MALFORMED_CHECK_LABEL,
+        status: "fail",
+        detail: READINESS_MALFORMED_CHECK_DETAIL,
+        remediation: READINESS_MALFORMED_CHECK_REMEDIATION,
+    });
+}