@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/epic-ci-workflow-drift.js

@@ -0,0 +1,77 @@
+/**
+ * Fail-closed byte identity for the managed CI workflow (BAPI-1460).
+ *
+ * Unlike the merge workflow, the CI workflow's bytes depend on one input — the
+ * stored test command — so recognition cannot be a fixed SHA list. Instead a
+ * file is recognized as Bridge-rendered only when its ENTIRE bytes equal a
+ * re-render: of the current proposal, or of the command extracted from the
+ * file's own fixed `run:` line by a renderer version Bridge actually published.
+ * A version marker alone proves nothing; a hand-edited or hostile file can claim
+ * any version it likes.
+ *
+ * Leaf module: no filesystem, network, or subprocess access, and no YAML parser.
+ * Nothing here logs file content.
+ */
+import { EPIC_CI_COMMAND_LINE_PREFIX, EPIC_CI_WORKFLOW_PATH, renderEpicImplementerCiWorkflow, } from "./epic-ci-workflow.js";
+import { TestCommandValidationError, validateTestCommand } from "./test-command-validation.js";
+/**
+ * Renderers for every OLDER published version, keyed by version.
+ *
+ * Empty on purpose: version 1 is the first release, and inventing a historical
+ * version would let a file that never shipped be "upgraded". When version 2
+ * ships, freeze version 1's renderer as a function here, unchanged, so its exact
+ * bytes stay recognizable.
+ */
+export const EPIC_CI_WORKFLOW_HISTORICAL_RENDERERS = new Map();
+/** Extract and validate the command from the fixed `run:` line; `null` if absent or bad. */
+export function extractEpicCiWorkflowCommand(content) {
+    const lines = content.split("\n");
+    const commandLines = lines.filter((line) => line.startsWith(EPIC_CI_COMMAND_LINE_PREFIX + "\""));
+    if (commandLines.length !== 1)
+        return null;
+    const scalar = commandLines[0].slice(EPIC_CI_COMMAND_LINE_PREFIX.length);
+    let decoded;
+    try {
+        decoded = JSON.parse(scalar);
+    }
+    catch {
+        return null;
+    }
+    try {
+        return validateTestCommand(decoded);
+    }
+    catch (err) {
+        if (err instanceof TestCommandValidationError)
+            return null;
+        throw err;
+    }
+}
+/**
+ * Classify `existing` (`null` when absent) against the proposal for
+ * `proposedCommand`. Comparison is on raw bytes; line-ending differences are
+ * differences.
+ */
+export function classifyEpicCiWorkflowContent(existing, proposedCommand) {
+    if (existing === null)
+        return "not_installed";
+    if (existing === renderEpicImplementerCiWorkflow(proposedCommand))
+        return "identical";
+    const extracted = extractEpicCiWorkflowCommand(existing);
+    if (extracted === null)
+        return "modified_or_unrecognized";
+    for (const render of EPIC_CI_WORKFLOW_HISTORICAL_RENDERERS.values()) {
+        if (existing === render(extracted))
+            return "managed_version_older";
+    }
+    if (existing === renderEpicImplementerCiWorkflow(extracted))
+        return "managed_command_differs";
+    return "modified_or_unrecognized";
+}
+/** Operator-facing gloss for each classification. Path-only; never the command. */
+export const EPIC_CI_WORKFLOW_CLASSIFICATION_TEXT = {
+    not_installed: `${EPIC_CI_WORKFLOW_PATH} is not installed`,
+    identical: `${EPIC_CI_WORKFLOW_PATH} already matches the stored test command`,
+    managed_version_older: `${EPIC_CI_WORKFLOW_PATH} is an older Bridge-managed version and can be upgraded`,
+    managed_command_differs: `${EPIC_CI_WORKFLOW_PATH} was rendered by Bridge for a different test command and can be updated`,
+    modified_or_unrecognized: `${EPIC_CI_WORKFLOW_PATH} has been modified or is not a file Bridge rendered`,
+};

package/build/epic-ci-workflow-install.js

@@ -0,0 +1,183 @@
+/**
+ * The Epic Implementer CI workflow as an installable artifact set (BAPI-1460).
+ *
+ * One managed file, `.github/workflows/epic-implementer-ci.yml`, rendered from
+ * the repository's stored test command and delivered through the shared
+ * {@link installArtifactSet} engine: read-only preflight, consent, a temporary
+ * worktree, a managed branch, and one pull request into the default branch.
+ *
+ * ## The setup caller's sequence (BAPI-1461)
+ *
+ * 1. Detect or select a command (`detectTestCommand`), asking at most once.
+ * 2. Get consent to save the command, then save it with `PUT /setup/testing-config`
+ *    (`writeStoredTestCommand`).
+ * 3. Read the authoritative command back with `GET /setup/testing-config`
+ *    (`readStoredTestCommand`) and build the descriptor from THAT value with
+ *    {@link buildEpicCiWorkflowArtifactSet} — never from the typed answer.
+ * 4. Get separate consent for the pull request and call {@link installEpicCiWorkflow}.
+ *
+ * A failed command read or write stops before any installation. Saving the
+ * command and installing the workflow are reported separately
+ * ({@link describeEpicCiSetupStatus}): a refused or failed install never undoes
+ * a stored command.
+ *
+ * The backend integration point for readiness (BAPI-1459) is
+ * `get_test_command(repo_name)` in `api/library/db/postgres_functions.py`. A
+ * runnable command is never derived from the worker prose fields.
+ */
+import { EPIC_CI_GATE_JOB_TIMEOUT_MINUTES, EPIC_CI_TEST_JOB_TIMEOUT_MINUTES, EPIC_CI_WORKFLOW_PATH, EPIC_CI_WORKFLOW_RENDERER_VERSION, EPIC_IMPLEMENTER_CI_CHECK_NAME, renderEpicImplementerCiWorkflow, } from "./epic-ci-workflow.js";
+import { EPIC_CI_WORKFLOW_CLASSIFICATION_TEXT, classifyEpicCiWorkflowContent, } from "./epic-ci-workflow-drift.js";
+import { installArtifactSet, } from "./merge-workflow-install.js";
+import { TestCommandValidationError, validateTestCommand } from "./test-command-validation.js";
+/** Managed branch for a fresh installation. */
+export const EPIC_CI_WORKFLOW_INSTALL_BRANCH = "bridge/epic-implementer-ci-v" + String(EPIC_CI_WORKFLOW_RENDERER_VERSION);
+/**
+ * Managed branch for replacing an existing Bridge rendering: an older renderer
+ * version, or the current version rendered for a different stored command.
+ */
+export const EPIC_CI_WORKFLOW_UPGRADE_BRANCH = "bridge/epic-implementer-ci-upgrade-v" + String(EPIC_CI_WORKFLOW_RENDERER_VERSION);
+export const EPIC_CI_WORKFLOW_INSTALL_COMMIT_SUBJECT = "Add the Bridge Epic Implementer CI workflow";
+export const EPIC_CI_WORKFLOW_UPGRADE_COMMIT_SUBJECT = "Update the Bridge Epic Implementer CI workflow";
+/**
+ * Render the CI pull request body. Deterministic and secret-free. It describes
+ * the command contract but never embeds the command; the diff shows it.
+ */
+export function renderEpicCiWorkflowPrBody(upgrade) {
+    return [
+        upgrade
+            ? "This pull request updates the Bridge Epic Implementer CI workflow to renderer version " +
+                String(EPIC_CI_WORKFLOW_RENDERER_VERSION) + " and the repository's current stored test command."
+            : "This pull request adds the Bridge Epic Implementer CI workflow, renderer version " +
+                String(EPIC_CI_WORKFLOW_RENDERER_VERSION) + ".",
+        "",
+        "The workflow publishes one required check, `" + EPIC_IMPLEMENTER_CI_CHECK_NAME + "`. The Bridge",
+        "Epic Implementer reads it before it merges a child pull request.",
+        "",
+        "## How it runs",
+        "",
+        "- On every pull request, it runs the repository's stored test command with bash from the",
+        "  repository root, on `ubuntu-latest`, with a " + String(EPIC_CI_TEST_JOB_TIMEOUT_MINUTES) + "-minute limit.",
+        "- The command must be self-contained: the workflow installs no runtime or dependencies.",
+        "- It requests only `contents: read` and uses no secrets.",
+        "- A pull request from a fork never checks out or runs repository code. The gate passes for",
+        "  it immediately and says so. The gate job itself has a " + String(EPIC_CI_GATE_JOB_TIMEOUT_MINUTES) + "-minute limit.",
+        "",
+        "## Files",
+        "",
+        "- `" + EPIC_CI_WORKFLOW_PATH + "`",
+        "",
+        "## What you must do",
+        "",
+        "Review the command in the diff, then merge this pull request yourself. Bridge never merges",
+        "it. The branch, the commit, and this pull request were created locally with your own git",
+        "and `gh`; Bridge performed no write to this repository.",
+        "",
+    ].join("\n");
+}
+/**
+ * The CI artifact set for one stored command. Build it from the command read
+ * back through `GET /setup/testing-config`, never from unsaved input.
+ */
+export function buildEpicCiWorkflowArtifactSet(testCommand) {
+    return {
+        setName: "epic-ci-workflow",
+        installBranch: EPIC_CI_WORKFLOW_INSTALL_BRANCH,
+        upgradeBranch: EPIC_CI_WORKFLOW_UPGRADE_BRANCH,
+        installCommitSubject: EPIC_CI_WORKFLOW_INSTALL_COMMIT_SUBJECT,
+        upgradeCommitSubject: EPIC_CI_WORKFLOW_UPGRADE_COMMIT_SUBJECT,
+        installPrTitle: EPIC_CI_WORKFLOW_INSTALL_COMMIT_SUBJECT,
+        upgradePrTitle: EPIC_CI_WORKFLOW_UPGRADE_COMMIT_SUBJECT,
+        renderPrBody: renderEpicCiWorkflowPrBody,
+        validateOptions: () => {
+            try {
+                validateTestCommand(testCommand);
+            }
+            catch (err) {
+                if (err instanceof TestCommandValidationError)
+                    return { ok: false, reason: "test_command_invalid" };
+                throw err;
+            }
+            return { ok: true, progress: [] };
+        },
+        artifacts: [
+            {
+                relPath: EPIC_CI_WORKFLOW_PATH,
+                render: () => renderEpicImplementerCiWorkflow(testCommand),
+                progressLabel: "workflow",
+                classify: (existing) => {
+                    const classification = classifyEpicCiWorkflowContent(existing, testCommand);
+                    const text = EPIC_CI_WORKFLOW_CLASSIFICATION_TEXT[classification];
+                    if (classification === "modified_or_unrecognized") {
+                        return { state: "conflict", reason: "workflow_modified_or_unrecognized", text };
+                    }
+                    // A complete Bridge rendering of a different command is not a hand
+                    // edit: the stored command changed. Replace it through the same
+                    // reviewed update PR as an older renderer version, so the workflow
+                    // header's "save a new command and re-run the installer" holds.
+                    if (classification === "managed_command_differs")
+                        return { state: "managed_version_older", text };
+                    return { state: classification, text };
+                },
+            },
+        ],
+    };
+}
+/** Install the CI workflow for `testCommand`. Returns the typed result; prints progress only. */
+export async function installEpicCiWorkflow(testCommand, options, deps) {
+    return await installArtifactSet(buildEpicCiWorkflowArtifactSet(testCommand), options, deps);
+}
+const REFUSALS = new Set([
+    "workflow_modified_or_unrecognized",
+    "consent_declined",
+    "worktree_not_clean",
+    "test_command_invalid",
+]);
+/** Map an install result to its status. `null` means the install was not attempted. */
+export function epicCiInstallStatus(result) {
+    if (result === null)
+        return "not_attempted";
+    switch (result.outcome) {
+        case "installed-pr-opened":
+        case "upgrade-pr-opened":
+            return "pr_opened";
+        case "dry-run":
+            return "proposal_ready";
+        case "identical":
+            return "already_installed";
+        case "existing-pr":
+            return "setup_pr_already_open";
+        case "failed":
+            if (result.reason === "existing_pr_differs")
+                return "proposal_differs";
+            if (result.reason === "managed_branch_without_pr" || result.reason === "pr_open_failed") {
+                return "managed_branch_needs_recovery";
+            }
+            return REFUSALS.has(result.reason) ? "install_refused" : "install_failed";
+    }
+}
+/**
+ * Combine the command outcome and the install outcome into one status, keeping
+ * them separate: the command can be saved while the install is refused.
+ */
+export function describeEpicCiSetupStatus(command, provenance, result) {
+    const status = {
+        command,
+        install: epicCiInstallStatus(result),
+        provenance,
+        branch: null,
+        prUrl: null,
+        compareUrl: null,
+        reason: null,
+    };
+    if (result === null)
+        return status;
+    if ("branch" in result && typeof result.branch === "string")
+        status.branch = result.branch;
+    if ("prUrl" in result && typeof result.prUrl === "string")
+        status.prUrl = result.prUrl;
+    if (result.outcome === "failed") {
+        status.reason = result.reason;
+        status.compareUrl = result.compareUrl ?? null;
+    }
+    return status;
+}

package/build/epic-ci-workflow.js

@@ -0,0 +1,157 @@
+/**
+ * The customer Epic Implementer CI workflow renderer (BAPI-1460).
+ *
+ * Renders `.github/workflows/epic-implementer-ci.yml` from the repository's ONE
+ * stored test command. The workflow publishes the single required context the
+ * Epic Implementer `ci` gate observes, `epic-implementer-ci / gate`: green when
+ * the command passes on a same-repository pull request, and green immediately,
+ * without running anything, for a fork pull request.
+ *
+ * ## Why a TypeScript renderer
+ *
+ * Same precedent as `merge-workflow.ts`: the compiled renderer is the file's
+ * only byte source, so "did Bridge render this?" has one answer.
+ *
+ * ## The command is data, never code in this process
+ *
+ * The command is written as ONE double-quoted YAML scalar produced by
+ * `JSON.stringify` (a JSON string is a valid YAML double-quoted scalar), on one
+ * fixed `run:` line. It is never placed in this process's own shell or git
+ * arguments. The renderer re-checks the stored-command rules and throws on a bad
+ * command; `${{` in particular is refused because Actions would evaluate an
+ * expression inside a `run:` value before the shell sees it.
+ *
+ * ## Safe by default
+ *
+ * `on: pull_request` only, `permissions: contents: read`, no secrets, no
+ * path filters, `ubuntu-latest`. The execution job runs only when the pull
+ * request head is this repository; a fork pull request never checks out or runs
+ * repository code. The checkout does not persist its token. The command must be
+ * self-contained: it installs whatever it needs, because the workflow provisions
+ * no runtime.
+ */
+import { validateTestCommand } from "./test-command-validation.js";
+/** Repository-relative path of the managed workflow. */
+export const EPIC_CI_WORKFLOW_PATH = ".github/workflows/epic-implementer-ci.yml";
+/** The renderer version written into the managed header. */
+export const EPIC_CI_WORKFLOW_RENDERER_VERSION = 1;
+/** The header marker key; the line is `# <key>: <version>`. */
+export const EPIC_CI_WORKFLOW_VERSION_MARKER_KEY = "x-bridge-ci-renderer-version";
+/** The workflow `name:`. */
+export const EPIC_CI_WORKFLOW_NAME = "epic-implementer-ci";
+/**
+ * The required check context, and the aggregator job's display `name:`.
+ *
+ * Must equal `EPIC_IMPLEMENTER_GATE_CHECK_NAME` in
+ * `api/library/github/workflow_inspection.py` and `CURRENT_GATE_NAME` in
+ * `mcp_server/src/conductor/readiness.ts`; a test asserts all three agree.
+ */
+export const EPIC_IMPLEMENTER_CI_CHECK_NAME = "epic-implementer-ci / gate";
+/** Bound on the execution job, in minutes. */
+export const EPIC_CI_TEST_JOB_TIMEOUT_MINUTES = 30;
+/** Bound on the aggregator job, in minutes. */
+export const EPIC_CI_GATE_JOB_TIMEOUT_MINUTES = 5;
+/** The fixed indentation and key that precede the command scalar. */
+export const EPIC_CI_COMMAND_LINE_PREFIX = "        run: ";
+/**
+ * Characters `JSON.stringify` leaves raw that a YAML parser may read as a line
+ * break or a byte-order mark (YAML 1.1 treats U+0085, U+2028 and U+2029 as
+ * breaks), plus DEL and the C1 controls. They are escaped as `\uXXXX`, which is
+ * still valid JSON and a valid YAML double-quoted escape.
+ */
+const YAML_UNSAFE_RAW = /[\u007f-\u009f\u2028\u2029\ufeff]/g;
+/** Encode the command as one JSON string that is also a safe YAML scalar. */
+export function encodeCommandScalar(testCommand) {
+    return JSON.stringify(testCommand).replace(YAML_UNSAFE_RAW, (ch) => "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+/**
+ * Render the workflow for `testCommand`. Deterministic: the same command always
+ * gives the same bytes. Throws `TestCommandValidationError` for a bad command.
+ */
+export function renderEpicImplementerCiWorkflow(testCommand) {
+    const command = validateTestCommand(testCommand);
+    const lines = [
+        "# ===========================================================================",
+        "# Epic Implementer CI gate — MANAGED FILE",
+        "#",
+        "# Generated by Bridge (`" + EPIC_CI_WORKFLOW_PATH + "`). Do not hand-edit: the",
+        "# installer compares this file byte for byte against what it renders and",
+        "# refuses to overwrite a modified or unrecognized copy.",
+        "#",
+        "# " + EPIC_CI_WORKFLOW_VERSION_MARKER_KEY + ": " + String(EPIC_CI_WORKFLOW_RENDERER_VERSION),
+        "#",
+        "# WHAT THIS WORKFLOW IS",
+        "#",
+        "# It publishes one required check, `" + EPIC_IMPLEMENTER_CI_CHECK_NAME + "`, that the",
+        "# Bridge Epic Implementer reads before it merges a child pull request. The",
+        "# check is green only when the repository's stored test command passes.",
+        "#",
+        "# SCOPE: SAME-REPOSITORY PULL REQUESTS ONLY",
+        "#",
+        "# The `tests` job runs only when the pull request head is this repository.",
+        "# A fork pull request never checks out or runs repository code; the gate",
+        "# passes for it immediately and says so. Nothing here uses a secret, and the",
+        "# token is read-only.",
+        "#",
+        "# THE TEST COMMAND",
+        "#",
+        "# The command below is the repository's stored test command, run with bash",
+        "# from the repository root. It must be self-contained: this workflow installs",
+        "# no language runtime or dependencies, so the command must install what it",
+        "# needs. To change it, save a new command through Bridge setup and re-run the",
+        "# installer; do not edit it here.",
+        "# ===========================================================================",
+        "name: " + EPIC_CI_WORKFLOW_NAME,
+        "",
+        "on:",
+        "  pull_request:",
+        "",
+        "permissions:",
+        "  contents: read",
+        "",
+        "jobs:",
+        "  tests:",
+        "    name: tests",
+        "    if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}",
+        "    runs-on: ubuntu-latest",
+        "    timeout-minutes: " + String(EPIC_CI_TEST_JOB_TIMEOUT_MINUTES),
+        "    steps:",
+        "      - name: Check out the pull request",
+        "        uses: actions/checkout@v7",
+        "        with:",
+        "          persist-credentials: false",
+        "      - name: Run the stored test command",
+        "        shell: bash",
+        EPIC_CI_COMMAND_LINE_PREFIX + encodeCommandScalar(command),
+        "",
+        "  gate:",
+        "    name: " + EPIC_IMPLEMENTER_CI_CHECK_NAME,
+        "    needs: [tests]",
+        "    if: ${{ always() }}",
+        "    runs-on: ubuntu-latest",
+        "    timeout-minutes: " + String(EPIC_CI_GATE_JOB_TIMEOUT_MINUTES),
+        "    steps:",
+        "      - name: Aggregate the Epic Implementer CI result",
+        "        env:",
+        "          HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}",
+        "          THIS_REPOSITORY: ${{ github.repository }}",
+        "          TESTS_RESULT: ${{ needs.tests.result }}",
+        "        run: |",
+        "          if [ -z \"$HEAD_REPOSITORY\" ] || [ -z \"$THIS_REPOSITORY\" ]; then",
+        "            echo \"The pull request head repository could not be identified; the gate fails.\"",
+        "            exit 1",
+        "          fi",
+        "          if [ \"$HEAD_REPOSITORY\" != \"$THIS_REPOSITORY\" ]; then",
+        "            echo \"Fork pull request: repository code is never run for a fork, so the gate passes without running tests.\"",
+        "            exit 0",
+        "          fi",
+        "          echo \"Tests: $TESTS_RESULT\"",
+        "          if [ \"$TESTS_RESULT\" = \"success\" ]; then",
+        "            exit 0",
+        "          fi",
+        "          echo \"The stored test command did not conclude 'success'; the gate fails.\"",
+        "          exit 1",
+        "",
+    ];
+    return lines.join("\n");
+}