@bridge_gpt/mcp-server 0.2.52 → 0.2.53

package/build/plane/alembic-head.js

@@ -13,10 +13,16 @@
  * condition it guards is already reported loudly by the server at dispatch time.
  */
 import path from "path";
+import { planeCheckFinding, planeCheckPassed } from "./types.js";
 /** Remediation embedded in a confirmed-mismatch diagnostic. */
 export const PLANE_ALEMBIC_REMEDIATION = "alembic -c alembic.ini upgrade head";
 /** Fixed prefix of the fail-open warning, so tests and greps can match it. */
 export const PLANE_ALEMBIC_UNVERIFIED_PREFIX = "could not verify database migration head";
+/** Structured fix for a confirmed migration mismatch. */
+export const PLANE_ALEMBIC_MISMATCH_REMEDIATION = `run \`${PLANE_ALEMBIC_REMEDIATION}\` to bring the database up to the migration head, then retry.`;
+/** Structured fix for an unverifiable migration head. Never blocking. */
+export const PLANE_ALEMBIC_UNVERIFIED_REMEDIATION = "verify by hand with `alembic -c alembic.ini heads` and `alembic -c alembic.ini current`; " +
+    "startup continues, and the server reports CONTRACT_MIGRATION_BEHIND at dispatch if the database is behind.";
 /**
  * Path to the repository virtualenv's Alembic executable.
  *
@@ -72,39 +78,62 @@ export function parseAlembicRevisions(output) {
 export async function checkAlembicHead(repoRoot, deps) {
     const alembic = resolveRepositoryAlembicCommand(repoRoot, deps.platform);
     if (!(await deps.fileExists(alembic))) {
-        return unverified("the repository virtualenv Alembic executable was not found");
+        return unverified("the repository virtualenv Alembic executable was not found", "the repository virtualenv Alembic executable was not found");
     }
     const heads = await deps.execFile(alembic, ["-c", "alembic.ini", "heads"], { cwd: repoRoot });
     if (!heads.ok) {
-        return unverified(`\`alembic heads\` did not complete (${heads.error})`);
+        // The interpolated `error` stays in the legacy message for the operator at
+        // the terminal; the consolidated detail is fixed prose. In production that
+        // field is an errno code, but this outcome flows into a wider report and
+        // must not depend on every caller keeping it that way.
+        return unverified(`\`alembic heads\` did not complete (${heads.error})`, "`alembic heads` did not complete");
     }
     const current = await deps.execFile(alembic, ["-c", "alembic.ini", "current"], { cwd: repoRoot });
     if (!current.ok) {
-        return unverified(`\`alembic current\` did not complete (${current.error})`);
+        return unverified(`\`alembic current\` did not complete (${current.error})`, "`alembic current` did not complete");
     }
     const headRevisions = parseAlembicRevisions(heads.stdout);
     const currentRevisions = parseAlembicRevisions(current.stdout);
     if (headRevisions === null || currentRevisions === null) {
-        return unverified("Alembic output did not contain a readable revision");
+        return unverified("Alembic output did not contain a readable revision", "Alembic output did not contain a readable revision");
     }
     const matches = headRevisions.length === currentRevisions.length &&
         headRevisions.every((rev, i) => rev === currentRevisions[i]);
-    if (matches)
-        return null;
-    return {
+    if (matches) {
+        return planeCheckPassed("alembic-head", ALEMBIC_CHECK_LABEL, "the database is at the repository migration head");
+    }
+    return planeCheckFinding({
         check: "alembic-head",
         severity: "blocking",
         message: `the database is not at the migration head — heads [${headRevisions.join(", ")}], ` +
             `current [${currentRevisions.join(", ")}]. A database behind the head blocks ` +
             `conductor dispatch. Run \`${PLANE_ALEMBIC_REMEDIATION}\``,
-    };
+        remediation: PLANE_ALEMBIC_MISMATCH_REMEDIATION,
+    }, ALEMBIC_CHECK_LABEL, 
+    // Revision ids are repository-authored slugs, not secrets, and they are the
+    // one fact that makes this finding actionable.
+    `database at [${currentRevisions.join(", ")}], repository head [${headRevisions.join(", ")}]`);
 }
-function unverified(detail) {
-    return {
+/** Human-readable name for the migration-head prerequisite. */
+const ALEMBIC_CHECK_LABEL = "Database migration head";
+/**
+ * The fail-open branch: warning severity, and never blocking.
+ *
+ * TWO details, deliberately. `messageDetail` is the legacy operator-facing prose
+ * and may name the command's own `error` field; `outcomeDetail` is fixed prose
+ * only, because the outcome flows into the consolidated readiness report. The
+ * production `execFile` adapter puts an errno code in `error`, but this
+ * separation means the consolidated report stays safe even if some caller ever
+ * puts raw stderr, an interpreter path, or a thrown message there.
+ */
+function unverified(messageDetail, outcomeDetail) {
+    const diagnostic = {
         check: "alembic-head",
         severity: "warning",
-        message: `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${detail}. Startup continues — verify with ` +
+        message: `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${messageDetail}. Startup continues — verify with ` +
             `\`alembic -c alembic.ini heads\` and \`alembic -c alembic.ini current\` if a run ` +
             "later reports CONTRACT_MIGRATION_BEHIND.",
+        remediation: PLANE_ALEMBIC_UNVERIFIED_REMEDIATION,
     };
+    return planeCheckFinding(diagnostic, ALEMBIC_CHECK_LABEL, `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${outcomeDetail}`);
 }

package/build/plane/build-freshness.js

@@ -13,6 +13,7 @@
  * can be older than a rebuild that overwrote files in place.
  */
 import path from "path";
+import { planeCheckFinding, planeCheckPassed } from "./types.js";
 /** Remediation text embedded in every blocking build diagnostic. */
 export const PLANE_BUILD_REMEDIATION = "cd mcp_server && npm run build";
 /**
@@ -93,42 +94,49 @@ export async function findBuildMtime(executorEntrypoint, deps) {
  * stale or absent build is exactly the failure this check exists to prevent, so
  * unlike the Alembic check there is no fail-open branch.
  */
+export const PLANE_BUILD_FIX_REMEDIATION = "run `cd mcp_server && npm run build` to rebuild the executor entrypoint, then retry.";
 export async function checkPlaneBuildFreshness(repoRoot, deps) {
+    const label = "Executor build freshness";
     const packageRoot = path.join(repoRoot, "mcp_server");
     const buildDir = path.join(packageRoot, "build");
     const executorEntrypoint = path.join(buildDir, "index.js");
     const srcDir = path.join(packageRoot, "src");
     const buildMtime = await findBuildMtime(executorEntrypoint, deps);
     if (!buildMtime.ok) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: `the executor build entrypoint is missing or unreadable at ` +
                 `mcp_server/build/index.js — run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, "the executor build entrypoint is missing or unreadable");
     }
     const sourceMtime = await findNewestSourceMtime(srcDir, deps);
     if (!sourceMtime.ok) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: `could not read mcp_server/src to compare against the build ` +
                 `(${sourceMtime.error}) — run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, 
+        // `sourceMtime.error` is an errno code, already sanitized by `sanitize()`.
+        `the executor sources could not be read for comparison (${sourceMtime.error})`);
     }
     // Equality passes: a build written in the same millisecond as its newest
     // source is current, and treating the boundary as stale would refuse a
     // perfectly good build on a coarse-resolution filesystem.
     if (sourceMtime.mtimeMs !== null && sourceMtime.mtimeMs > buildMtime.mtimeMs) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: "mcp_server/build/ is STALE — a source file under mcp_server/src is newer " +
                 `than mcp_server/build/index.js, so executors would run old code. ` +
                 `Run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, "mcp_server/build/ is stale — a source file is newer than the build entrypoint");
     }
-    return null;
+    return planeCheckPassed("executor-build", label, "the executor build is present and current");
 }
 /**
  * Fixed refusal prose for an unresolvable runtime re-exec target (BAPI-768).
@@ -153,13 +161,16 @@ export const PLANE_RUNTIME_ENTRYPOINT_REFUSAL = "the currently executing MCP bui
  * degraded plane, it is no plane at all.
  */
 export function checkPlaneRuntimeEntrypoint(resolution) {
-    if (resolution.ok)
-        return null;
-    return {
+    const label = "Runtime re-exec entrypoint";
+    if (resolution.ok) {
+        return planeCheckPassed("runtime-entrypoint", label, "the executing build can re-enter itself");
+    }
+    return planeCheckFinding({
         check: "runtime-entrypoint",
         severity: "blocking",
         message: PLANE_RUNTIME_ENTRYPOINT_REFUSAL,
-    };
+        remediation: PLANE_BUILD_FIX_REMEDIATION,
+    }, label, "the currently executing MCP build could not be re-entered");
 }
 function sanitize(err) {
     const code = err?.code;