@bridge_gpt/mcp-server 0.2.51 → 0.2.52

package/build/scripts/executor-protocol-contract-driver.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/**
+ * Executor `/executor/jobs/*` protocol contract driver (BAPI-997, T4).
+ *
+ * A Python `subprocess` boundary that lets the real pytest suite drive the
+ * REAL, emitted TypeScript executor HTTP client (`createExecutorHttpClient` in
+ * `../executor/http-client.js`, built from `mcp_server/src/executor/`) against
+ * the real FastAPI `/executor/jobs/*` routes, and separately projects the
+ * TypeScript protocol's closed vocabularies and structural request/response
+ * shapes into canonical JSON so a Python test can compare them against the
+ * server's Pydantic models — WITHOUT either side hand-maintaining a duplicate
+ * description of the other's contract.
+ *
+ * This module is deliberately NOT registered as an MCP tool
+ * (`server.registerTool`) and is NOT listed in `INTEGRATION_LANE_ONLY`: it is
+ * test-support infrastructure invoked directly by a Python subprocess test,
+ * never shipped as user-facing functionality.
+ *
+ * Two independent modes, selected by argv shape:
+ *
+ *   node executor-protocol-contract-driver.js <commandsJsonPath> <resultsJsonPath>
+ *     Reads a JSON array of commands from `commandsJsonPath`, executes each
+ *     against a real `createExecutorHttpClient` instance (built from a
+ *     narrowly-constructed child environment, never argv, for credential
+ *     material — see `readClientConfigFromEnv`), and atomically writes a JSON
+ *     array of outcomes to `resultsJsonPath`. See `executeCommand` for the
+ *     supported `claim` / `heartbeat` / `complete` / `fail` command shapes.
+ *
+ *   node executor-protocol-contract-driver.js --emit-protocol <outputJsonPath>
+ *     Emits the closed-vocabulary runtime constants (job types,
+ *     classifications, mutation outcomes, reconciler-liveness states) from the
+ *     BUILT `../executor/types.js` module, plus structural metadata (property
+ *     names, optionality, and union-literal members) for the claim/claimed/
+ *     heartbeat/completion/failure/process-heartbeat wire shapes, projected
+ *     from the SOURCE `mcp_server/src/executor/types.ts` through the
+ *     TypeScript compiler API (`typescript/unstable/sync` +
+ *     `typescript/unstable/ast`) — never regex, substring matching, or a raw
+ *     source snapshot.
+ *
+ * Reserved stdout: this driver writes ITS results only to the output file.
+ * stdout carries no diagnostics — every diagnostic and error goes to stderr —
+ * so a caller that happens to capture stdout never accumulates incidental
+ * log noise.
+ */
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+import { API, SymbolFlags } from "typescript/unstable/sync";
+import { isInterfaceDeclaration, isTypeAliasDeclaration } from "typescript/unstable/ast";
+import { createExecutorHttpClient, RECONCILER_LIVENESS_HEADER, HEARTBEAT_STOP_FIELD, } from "../executor/http-client.js";
+import { EXECUTOR_JOB_TYPE_VALUES, EXECUTOR_CLASSIFICATION_VALUES, EXECUTOR_MUTATION_OUTCOME_VALUES, RECONCILER_LIVENESS_VALUES, } from "../executor/types.js";
+// ---------------------------------------------------------------------------
+// realFetch — a thin adapter over global fetch. Never constructs a URL,
+// header, or fenced body field itself; it only shapes the Response into what
+// FetchLike expects and observes (never sets) the one response header this
+// driver is allowed to record as evidence.
+// ---------------------------------------------------------------------------
+/**
+ * The most recently observed `RECONCILER_LIVENESS_HEADER` value, reset before
+ * every command and captured here rather than threaded through the injected
+ * `fetch` return type — the client's own `FetchResponseLike` contract is
+ * unchanged by this driver (BAPI-997 action item: "do not construct... raw
+ * `fetch` requests in the driver" — this reads a header, it does not build
+ * one).
+ */
+let lastReconcilerLivenessHeaderRaw = null;
+const realFetch = async (url, init) => {
+    const response = await fetch(url, {
+        method: init.method,
+        headers: init.headers,
+        body: init.body,
+    });
+    lastReconcilerLivenessHeaderRaw = response.headers.get(RECONCILER_LIVENESS_HEADER);
+    const text = await response.text();
+    const adapted = {
+        status: response.status,
+        text: async () => text,
+        headers: response.headers,
+    };
+    return adapted;
+};
+// ---------------------------------------------------------------------------
+// Client configuration — read from a narrowly constructed child environment,
+// never from argv (argv here is reserved for the two non-sensitive file
+// paths). The Python caller constructs a minimal env containing only these
+// four variables; this driver never inspects or forwards the rest of
+// `process.env`, and never echoes the environment in any output.
+// ---------------------------------------------------------------------------
+const ENV_BASE_URL = "EXECUTOR_CONTRACT_DRIVER_BASE_URL";
+const ENV_API_KEY = "EXECUTOR_CONTRACT_DRIVER_API_KEY";
+const ENV_API_KEY_BY_REPO_JSON = "EXECUTOR_CONTRACT_DRIVER_API_KEY_BY_REPO_JSON";
+const ENV_MCP_VERSION = "EXECUTOR_CONTRACT_DRIVER_MCP_VERSION";
+/** Read the five client configuration entries (BAPI-997 action item 5). */
+function readClientConfigFromEnv(env) {
+    const baseUrl = env[ENV_BASE_URL];
+    const apiKey = env[ENV_API_KEY];
+    const mcpVersion = env[ENV_MCP_VERSION];
+    if (!baseUrl)
+        throw new Error(`${ENV_BASE_URL} must be set in the child environment`);
+    if (!apiKey)
+        throw new Error(`${ENV_API_KEY} must be set in the child environment`);
+    if (!mcpVersion)
+        throw new Error(`${ENV_MCP_VERSION} must be set in the child environment`);
+    let apiKeyByRepo;
+    const rawApiKeyByRepo = env[ENV_API_KEY_BY_REPO_JSON];
+    if (rawApiKeyByRepo) {
+        const parsed = JSON.parse(rawApiKeyByRepo);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            apiKeyByRepo = parsed;
+        }
+        else {
+            throw new Error(`${ENV_API_KEY_BY_REPO_JSON} must decode to a JSON object`);
+        }
+    }
+    return { baseUrl, apiKey, apiKeyByRepo, mcpVersion };
+}
+const KNOWN_OPS = new Set(["claim", "heartbeat", "complete", "fail"]);
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+async function executeCommand(client, command) {
+    lastReconcilerLivenessHeaderRaw = null;
+    try {
+        switch (command.op) {
+            case "claim": {
+                const result = await client.claim(command.manifest);
+                return {
+                    op: command.op,
+                    ok: true,
+                    result,
+                    evidence: { [RECONCILER_LIVENESS_HEADER]: lastReconcilerLivenessHeaderRaw },
+                };
+            }
+            case "heartbeat": {
+                const result = await client.heartbeat(command.job, command.payload);
+                return { op: command.op, ok: true, result };
+            }
+            case "complete": {
+                const result = await client.complete(command.job, command.completion);
+                return { op: command.op, ok: true, result };
+            }
+            case "fail": {
+                const result = await client.fail(command.job, command.failure);
+                return { op: command.op, ok: true, result };
+            }
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { op: command.op, ok: false, error: message };
+    }
+}
+/** Atomically replace `outputPath`'s contents (write-then-rename, same filesystem). */
+function writeJsonAtomically(outputPath, value) {
+    const tmpPath = `${outputPath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(value, null, 2));
+    fs.renameSync(tmpPath, outputPath);
+}
+async function runCommands(inputPath, outputPath) {
+    const config = readClientConfigFromEnv(process.env);
+    const client = createExecutorHttpClient({
+        baseUrl: config.baseUrl,
+        apiKey: config.apiKey,
+        apiKeyByRepo: config.apiKeyByRepo,
+        mcpVersion: config.mcpVersion,
+        fetch: realFetch,
+    });
+    const rawCommands = JSON.parse(fs.readFileSync(inputPath, "utf8"));
+    if (!Array.isArray(rawCommands)) {
+        throw new Error("commands file must contain a JSON array");
+    }
+    const outcomes = [];
+    for (const raw of rawCommands) {
+        if (!isPlainObject(raw) || typeof raw.op !== "string" || !KNOWN_OPS.has(raw.op)) {
+            outcomes.push({
+                op: isPlainObject(raw) && typeof raw.op === "string" ? raw.op : "unknown",
+                ok: false,
+                error: "unrecognized or malformed command",
+            });
+            continue;
+        }
+        outcomes.push(await executeCommand(client, raw));
+    }
+    writeJsonAtomically(outputPath, outcomes);
+}
+/** The exported shapes this driver projects (BAPI-997 action item 13). */
+const PROJECTED_SHAPE_NAMES = [
+    "ExecutorClaimJobRequest",
+    "ClaimedExecutorJob",
+    "ExecutorHeartbeatWireRequest",
+    "ExecutorCompletionWireRequest",
+    "ExecutorFailureWireRequest",
+    "ExecutorProcessHeartbeatRequest",
+];
+/** Return the closed string-literal members of *type*, or `undefined` when it is not one. */
+function literalValuesOf(type) {
+    if (type.isStringLiteralType()) {
+        return [type.value];
+    }
+    if (type.isUnionType()) {
+        const values = [];
+        for (const member of type.getTypes()) {
+            if (!member.isStringLiteralType())
+                return undefined;
+            values.push(member.value);
+        }
+        return values.sort();
+    }
+    return undefined;
+}
+function projectShape(checker, declaration, name) {
+    const type = checker.getTypeAtLocation(declaration);
+    if (!type) {
+        throw new Error(`could not resolve a type for ${name}`);
+    }
+    const properties = checker
+        .getPropertiesOfType(type)
+        .map((symbol) => {
+        const propertyType = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+        return {
+            name: symbol.name,
+            optional: !!(symbol.flags & SymbolFlags.Optional),
+            type: checker.typeToString(propertyType),
+            literalValues: literalValuesOf(propertyType),
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { name, properties };
+}
+async function emitProtocolProjection(outputPath) {
+    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+    // This driver runs from build/scripts/; the emitted tree mirrors src/, so
+    // the SOURCE file the compiler API projects lives two levels up, under
+    // src/executor/ — never mcp_server/build/.
+    const mcpServerRoot = path.resolve(scriptDir, "..", "..");
+    const typesSourcePath = path.join(mcpServerRoot, "src", "executor", "types.ts");
+    const api = new API({ cwd: mcpServerRoot });
+    try {
+        const snapshot = api.updateSnapshot({ openFiles: [typesSourcePath] });
+        const project = snapshot.getDefaultProjectForFile(typesSourcePath);
+        if (!project) {
+            throw new Error(`no TypeScript project resolved for ${typesSourcePath}`);
+        }
+        const checker = project.checker;
+        const sourceFile = project.program.getSourceFile(typesSourcePath);
+        if (!sourceFile) {
+            throw new Error(`could not load source file ${typesSourcePath}`);
+        }
+        const shapes = {};
+        for (const statement of sourceFile.statements) {
+            if (!isInterfaceDeclaration(statement) && !isTypeAliasDeclaration(statement))
+                continue;
+            const name = statement.name.text;
+            if (!PROJECTED_SHAPE_NAMES.includes(name))
+                continue;
+            shapes[name] = projectShape(checker, statement, name);
+        }
+        const missing = PROJECTED_SHAPE_NAMES.filter((name) => !(name in shapes));
+        if (missing.length > 0) {
+            throw new Error(`could not project shape(s): ${missing.join(", ")}`);
+        }
+        const projection = {
+            jobTypes: [...EXECUTOR_JOB_TYPE_VALUES],
+            classifications: [...EXECUTOR_CLASSIFICATION_VALUES],
+            mutationOutcomes: [...EXECUTOR_MUTATION_OUTCOME_VALUES],
+            reconcilerLiveness: [...RECONCILER_LIVENESS_VALUES],
+            reconcilerLivenessHeader: RECONCILER_LIVENESS_HEADER,
+            heartbeatStopField: HEARTBEAT_STOP_FIELD,
+            shapes,
+        };
+        writeJsonAtomically(outputPath, projection);
+        project.dispose();
+    }
+    finally {
+        api.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export async function main(argv) {
+    if (argv[0] === "--emit-protocol") {
+        const outputPath = argv[1];
+        if (!outputPath) {
+            process.stderr.write("usage: executor-protocol-contract-driver --emit-protocol <outputJsonPath>\n");
+            process.exitCode = 1;
+            return;
+        }
+        await emitProtocolProjection(outputPath);
+        return;
+    }
+    const [inputPath, outputPath] = argv;
+    if (!inputPath || !outputPath) {
+        process.stderr.write("usage: executor-protocol-contract-driver <commandsJsonPath> <resultsJsonPath>\n");
+        process.exitCode = 1;
+        return;
+    }
+    await runCommands(inputPath, outputPath);
+}
+const invokedDirectly = process.argv[1]
+    ? fileURLToPath(import.meta.url) === path.resolve(process.argv[1])
+    : false;
+if (invokedDirectly) {
+    main(process.argv.slice(2)).catch((err) => {
+        // Sanitized top-level catch: never print a stack trace, raw error, or
+        // secret material (the child environment/API key) to stderr.
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`executor-protocol-contract-driver: ${message}\n`);
+        process.exitCode = 1;
+    });
+}