@bridge_gpt/mcp-server 0.2.24 → 0.2.25

package/build/connect-github.js

@@ -0,0 +1,415 @@
+/**
+ * `connect-github` — sessionless GitHub App connection from the terminal (BAPI-631).
+ *
+ * The whole point of this command is that it needs no Bridge web session: a user who has
+ * a Bridge API key can connect GitHub without ever opening the setup UI. The flow is
+ *
+ *   mint → browser (install on GitHub) → poll → pick a repository → confirm
+ *
+ * and the browser half authenticates to *GitHub*, not to Bridge. Bridge never asks for,
+ * accepts, echoes, or transports a GitHub credential. The only thing crossing between
+ * the browser and this process is a Bridge-issued state nonce, held in memory.
+ *
+ * Two properties are load-bearing and easy to erode:
+ *
+ * 1. **The nonce and install URL are never printed.** The URL carries the state as a
+ *    query parameter, so printing it (or letting it into an error message) would paste
+ *    a live credential-equivalent into the user's scrollback.
+ * 2. **Nothing binds without an explicit human choice.** Even a single-repository
+ *    installation is confirmed by hand — the server stages candidates and this command
+ *    asks. There is deliberately no `--yes`.
+ */
+import { readFile, stat } from "fs/promises";
+import { spawn } from "child_process";
+import os from "os";
+import path from "path";
+import readline from "readline";
+import { DEFAULT_BAPI_BASE_URL } from "./install-bridge.js";
+import { validateRepoName } from "./bridge-config.js";
+import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
+import { resolveBapiCredentials, } from "./credential-store.js";
+import { POLL_DEADLINE_MS, confirmGithubConnection, mintGithubConnection, pollGithubConnection, } from "./connect-github-api.js";
+const USAGE = `Usage: connect-github [--repo <repo_name>]
+
+Connect a GitHub repository to a Bridge project from your terminal.
+
+Opens the GitHub App install page in your browser, waits for you to install it,
+then asks which repository to connect. You are never asked for a GitHub token or
+password — you authenticate to GitHub in the browser.
+
+Options:
+  --repo <repo_name>   Bridge project to connect (inferred from this directory
+                       when omitted; you will be asked to confirm).
+  --help               Show this message.`;
+/**
+ * Parse argv. Deliberately strict — an unknown flag is an error, not something to
+ * ignore. In particular there is NO `--yes` (every bind is confirmed by a human) and no
+ * `--installation-id` (the server derives it; accepting one from the caller would let an
+ * API-key holder claim an installation they do not own).
+ */
+export function parseConnectGithubArgs(argv) {
+    const out = { help: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            out.help = true;
+            continue;
+        }
+        if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (!value || value.startsWith("-")) {
+                return { ok: false, error: "--repo requires a value (e.g. --repo my-project)." };
+            }
+            out.repo = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--repo=")) {
+            const value = arg.slice("--repo=".length);
+            if (!value) {
+                return { ok: false, error: "--repo requires a value (e.g. --repo my-project)." };
+            }
+            out.repo = value;
+            continue;
+        }
+        if (arg === "--yes" || arg === "-y") {
+            return {
+                ok: false,
+                error: "connect-github does not support --yes: connecting a repository always " +
+                    "requires an explicit confirmation.",
+            };
+        }
+        if (arg === "--installation-id" || arg.startsWith("--installation-id=")) {
+            return {
+                ok: false,
+                error: "connect-github does not accept --installation-id: the installation is " +
+                    "verified by Bridge from your browser install, not supplied by the caller.",
+            };
+        }
+        if (arg.startsWith("-")) {
+            return { ok: false, error: `Unknown option: ${arg}` };
+        }
+        return { ok: false, error: `Unexpected argument: ${arg}` };
+    }
+    return { ok: true, value: out };
+}
+/** Echoed single-line prompt on stderr. */
+function defaultPromptLine(promptText) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        // `rl.close()` emits `close` SYNCHRONOUSLY, so without this guard the close handler
+        // would settle the promise empty and discard a real answer. EOF must also resolve
+        // rather than deadlock a top-level await.
+        let answered = false;
+        rl.on("close", () => {
+            if (!answered)
+                resolve("");
+        });
+        rl.question(promptText, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Open *url* in the platform browser.
+ *
+ * `shell: false` is mandatory: the URL carries the state nonce, and handing it to a
+ * shell would expose it to word-splitting and metacharacter interpretation. Passing it
+ * as a single argv entry means the OS opener receives it verbatim.
+ */
+function defaultOpenBrowser(platform, url) {
+    const [command, args] = platform === "darwin"
+        ? ["open", [url]]
+        : platform === "win32"
+            ? // `start` is a cmd builtin; the empty string is its window-title argument,
+                // without which a quoted URL would be swallowed as the title.
+                ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, {
+                stdio: "ignore",
+                detached: false,
+                shell: false,
+            });
+            child.on("error", () => resolve(false));
+            child.on("spawn", () => resolve(true));
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+export function createDefaultConnectGithubDeps() {
+    return {
+        env: process.env,
+        cwd: process.cwd(),
+        platform: process.platform,
+        homedir: os.homedir,
+        isTTY: Boolean(process.stdin.isTTY),
+        readFile: (filePath) => readFile(filePath, "utf-8"),
+        stat: async (filePath) => {
+            const s = await stat(filePath);
+            return { mode: s.mode };
+        },
+        fetch: globalThis.fetch,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        jitter: () => Math.random(),
+        promptLine: defaultPromptLine,
+        openBrowser: (url) => defaultOpenBrowser(process.platform, url),
+        stdout: (message) => process.stdout.write(`${message}\n`),
+        stderr: (message) => process.stderr.write(`${message}\n`),
+    };
+}
+/**
+ * Resolve the Bridge project name: explicit `--repo`, then repository identity from the
+ * environment / project-local config (confirmed interactively, since an inferred name is
+ * a guess and connecting the wrong project is not cheap to undo).
+ */
+export async function resolveConnectGithubRepoName(args, deps) {
+    if (args.repo) {
+        const validated = validateRepoName(args.repo);
+        return validated.ok ? { ok: true, value: validated.value } : { ok: false, error: validated.error };
+    }
+    let inferred = await resolveStartTicketsRepoName({
+        env: deps.env,
+        cwd: deps.cwd,
+        readFile: deps.readFile,
+    });
+    if (!inferred) {
+        const validated = validateRepoName(path.basename(deps.cwd));
+        if (validated.ok)
+            inferred = validated.value;
+    }
+    if (!inferred) {
+        return {
+            ok: false,
+            error: "Could not determine the Bridge project. Pass --repo <repo_name>.",
+        };
+    }
+    const answer = (await deps.promptLine(`Bridge project [${inferred}]: `)).trim();
+    const chosen = answer.length > 0 ? answer : inferred;
+    const validated = validateRepoName(chosen);
+    return validated.ok ? { ok: true, value: validated.value } : { ok: false, error: validated.error };
+}
+// ---------------------------------------------------------------------------
+// Browser handoff
+// ---------------------------------------------------------------------------
+/**
+ * Hand the install URL to the browser.
+ *
+ * On failure this returns a FIXED message and never falls back to printing the URL —
+ * that URL contains the state nonce, and a copy-paste fallback would defeat the reason
+ * the nonce is kept in memory in the first place.
+ */
+export async function openGithubInstallPage(deps, installUrl) {
+    const opened = await deps.openBrowser(installUrl);
+    if (opened)
+        return { ok: true };
+    return {
+        ok: false,
+        error: "Could not open your browser automatically. Re-run this command from a desktop " +
+            "session with a browser available.",
+    };
+}
+// ---------------------------------------------------------------------------
+// Flow
+// ---------------------------------------------------------------------------
+const STEPS = [
+    "Connect GitHub",
+    "Complete GitHub in browser",
+    "Verify connection",
+    "Choose repository",
+    "Confirm connection",
+];
+function renderStep(deps, index) {
+    deps.stderr(`[${index + 1}/${STEPS.length}] ${STEPS[index]}`);
+}
+/** Display identity for a candidate: prefer the unambiguous owner/repo form. */
+function candidateLabel(c) {
+    if (c.github_repo_full_name)
+        return c.github_repo_full_name;
+    return c.owner ? `${c.owner}/${c.github_repo_name}` : c.github_repo_name;
+}
+/** One remediation line per terminal non-success outcome. Never any upstream detail. */
+const OUTCOME_MESSAGES = {
+    expired: "The connection request expired before GitHub reported back. Run connect-github again.",
+    invalid: "This connection request is no longer valid. Run connect-github again.",
+    "verification-failed": "Bridge could not verify the GitHub installation. Run connect-github again.",
+    "no-repositories": "The GitHub App installation did not include any repositories Bridge can access. " +
+        "Re-run connect-github and grant access to at least one repository.",
+    conflict: "This GitHub installation or project is already connected to a different Bridge " +
+        "account or repository. Contact support if that is unexpected.",
+    failed: "The GitHub connection did not complete. Run connect-github again.",
+};
+const FAILURE_MESSAGES = {
+    network: "Could not reach Bridge API. Check your network, then run connect-github again.",
+    timeout: "Bridge API did not respond in time. Run connect-github again.",
+    unauthorized: "Bridge rejected your API key for this project. Re-run install-bridge with a current key.",
+    "not-found": "Bridge does not recognize this project. Check --repo matches your Bridge project name.",
+    server: "Bridge API returned an error. Run connect-github again shortly.",
+    malformed: "Bridge API returned an unexpected response. Run connect-github again shortly.",
+    deadline: "Timed out waiting for GitHub. If you completed the install, run connect-github again " +
+        "to pick up the connection.",
+};
+/** The no-connection-made framing, used for every unsuccessful terminal path. */
+function reportNoConnection(deps, detail) {
+    deps.stderr("");
+    deps.stderr("No GitHub connection was made.");
+    deps.stderr(detail);
+    return 1;
+}
+export async function runGithubConnectionFlow(deps, api, repoName) {
+    renderStep(deps, 0);
+    const minted = await mintGithubConnection(api, repoName);
+    if (!minted.ok) {
+        return reportNoConnection(deps, FAILURE_MESSAGES[minted.kind]);
+    }
+    renderStep(deps, 1);
+    deps.stderr("Opening GitHub…");
+    // The URL goes straight from memory to the opener — never through a log line.
+    const opened = await openGithubInstallPage(deps, minted.value.installUrl);
+    if (!opened.ok) {
+        return reportNoConnection(deps, opened.error);
+    }
+    renderStep(deps, 2);
+    // floor, not round: the deadline carries ~30s of slack past the server's 15-minute
+    // code TTL purely so the SERVER reports the expiry rather than us guessing at it.
+    // Advertising that slack as "~16 minutes" would overstate how long the code lives.
+    const minutes = Math.floor(POLL_DEADLINE_MS / 60_000);
+    deps.stderr(`Waiting for GitHub installation… (up to ~${minutes} minutes)`);
+    const pollDeps = { sleep: deps.sleep, now: deps.now, jitter: deps.jitter };
+    const started = deps.now();
+    const polled = await pollGithubConnection(api, pollDeps, repoName, minted.value.state);
+    if (!polled.ok) {
+        return reportNoConnection(deps, FAILURE_MESSAGES[polled.kind]);
+    }
+    const elapsedSec = Math.max(0, Math.round((deps.now() - started) / 1_000));
+    deps.stderr(`Waited ${elapsedSec}s.`);
+    const result = polled.value;
+    if (result.status === "awaiting-organization-approval") {
+        deps.stderr("");
+        deps.stderr("No GitHub connection was made.");
+        deps.stderr("Your request to install the GitHub App was sent to an organization owner for approval.");
+        deps.stderr("That approval happens on GitHub and does not return here, so this command cannot " +
+            "wait for it.");
+        deps.stderr("Once an owner approves the install, finish the connection with the manual steps in " +
+            "the GitHub App setup guide (docs/install/github-app.md).");
+        return 1;
+    }
+    if (result.status === "connected") {
+        // Already bound (e.g. a re-run against a finished handshake).
+        deps.stdout(`Connected ${result.githubRepoName ?? repoName}.`);
+        return 0;
+    }
+    if (result.status !== "staged") {
+        return reportNoConnection(deps, OUTCOME_MESSAGES[result.status] ?? OUTCOME_MESSAGES.failed);
+    }
+    const candidates = result.candidates;
+    if (candidates.length === 0) {
+        return reportNoConnection(deps, OUTCOME_MESSAGES["no-repositories"]);
+    }
+    renderStep(deps, 3);
+    let selected = null;
+    if (candidates.length === 1) {
+        const only = candidates[0];
+        // Even with one option: show the full identity and require a yes. The user is
+        // authorizing a binding, not acknowledging a notice.
+        const answer = (await deps.promptLine(`Connect ${candidateLabel(only)}? [y/N]: `))
+            .trim()
+            .toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            deps.stderr("");
+            deps.stderr("No GitHub connection was made. Nothing was changed.");
+            return 1;
+        }
+        selected = only;
+    }
+    else {
+        deps.stderr("");
+        deps.stderr("Your GitHub installation includes multiple repositories:");
+        candidates.forEach((c, i) => {
+            deps.stderr(`  ${String(i + 1).padStart(2, " ")}. ${candidateLabel(c)}`);
+        });
+        deps.stderr("");
+        // No default: a stray Enter must not bind anything.
+        const answer = (await deps.promptLine(`Choose a repository [1-${candidates.length}]: `)).trim();
+        const index = Number(answer);
+        if (!/^\d+$/.test(answer) || !Number.isInteger(index) || index < 1 || index > candidates.length) {
+            deps.stderr("");
+            deps.stderr("No GitHub connection was made. No repository was selected.");
+            return 1;
+        }
+        selected = candidates[index - 1];
+        deps.stderr(`Selected ${candidateLabel(selected)}.`);
+    }
+    renderStep(deps, 4);
+    const confirmed = await confirmGithubConnection(api, repoName, minted.value.state, selected.github_repository_id);
+    if (!confirmed.ok) {
+        return reportNoConnection(deps, FAILURE_MESSAGES[confirmed.kind]);
+    }
+    deps.stdout(`Connected ${confirmed.value.githubRepoFullName ?? confirmed.value.githubRepoName}.`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Process boundary
+// ---------------------------------------------------------------------------
+/**
+ * Entry point. Catches everything and always resolves to a numeric exit code — an
+ * unhandled rejection here would surface a stack trace that could contain the install
+ * URL (and therefore the nonce).
+ */
+export async function runConnectGithubCli(argv, injected) {
+    const deps = injected ?? createDefaultConnectGithubDeps();
+    try {
+        const parsed = parseConnectGithubArgs(argv);
+        if (!parsed.ok) {
+            deps.stderr(parsed.error);
+            deps.stderr("");
+            deps.stderr(USAGE);
+            return 1;
+        }
+        if (parsed.value.help) {
+            deps.stdout(USAGE);
+            return 0;
+        }
+        // Checked BEFORE minting: this flow always ends in a human choice, so a
+        // non-interactive run can only ever strand a code it can never confirm.
+        if (!deps.isTTY) {
+            deps.stderr("connect-github needs an interactive terminal: it asks you to confirm which " +
+                "repository to connect. Run it directly in your terminal.");
+            return 1;
+        }
+        const repo = await resolveConnectGithubRepoName(parsed.value, deps);
+        if (!repo.ok) {
+            deps.stderr(repo.error);
+            return 1;
+        }
+        const cred = await resolveBapiCredentials(repo.value, {
+            env: deps.env,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+            stderr: () => { },
+        });
+        if (!cred.ok) {
+            deps.stderr(cred.error);
+            return 1;
+        }
+        const api = {
+            fetch: deps.fetch,
+            baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL,
+            apiKey: cred.credentials.apiKey,
+        };
+        return await runGithubConnectionFlow(deps, api, repo.value);
+    }
+    catch {
+        // Never forward the caught value: it may carry the install URL or the nonce.
+        deps.stderr("No GitHub connection was made. An unexpected error occurred.");
+        return 1;
+    }
+}

package/build/decision-page-schema.js

@@ -111,10 +111,34 @@ export const SystemGoalNfrSchema = z.object({
         .enum(["confirmed", "assumed", "open"])
         .describe("confirmed = explicitly stated or observable in code; assumed = low-risk and reversible default; open = unresolved (also surface as an actionable_items card)."),
 });
-// Read-only system-goals panel for the pre_ticket_planning artifact. Captures the
-// business goal, the desired end-state, how the system must behave to complete its
-// task, and the classified NFR list. Display-only: it states what is settled; it
-// does not collect input.
+// A single acceptance criterion: what the system must do, stated so it can be
+// verified. Criteria are the input to implementation options, not a summary of
+// them — solutioning is expected to flow downstream from this list. `status` uses
+// the same confirmed/assumed/open rubric as NFRs, and `id` is the per-criterion
+// JSON output key (data-ac-id) in the rendered page, so it must be unique.
+export const AcceptanceCriterionSchema = z.object({
+    id: z
+        .string()
+        .min(1)
+        .regex(/^[A-Za-z0-9_-]+$/, "id must contain only letters, digits, hyphens, or underscores")
+        .describe("Stable per-criterion id, e.g. AC-1. Becomes the captured-feedback JSON key."),
+    criterion: z
+        .string()
+        .min(1)
+        .describe("What the system must do, stated concretely enough to be verified."),
+    verification: z
+        .string()
+        .min(1)
+        .describe("How we would confirm this criterion is met. Required — a criterion with no way to check it is not yet a criterion."),
+    status: z
+        .enum(["confirmed", "assumed", "open"])
+        .describe("confirmed = explicitly stated or observable in code; assumed = low-risk and reversible default; open = unresolved."),
+});
+// System-goals panel for the pre_ticket_planning artifact. Captures the business
+// goal, the desired end-state, how the system must behave to complete its task,
+// the acceptance criteria (what it must do), and the classified NFR list (the
+// standards it must meet). The three prose fields are display-only; acceptance
+// criteria and NFRs additionally collect a per-item stance from the reader.
 export const SystemGoalsSchema = z.object({
     business_goal: z.string().min(1).describe("The business goal this work serves."),
     desired_end_state: z.string().min(1).describe("The end-state the system should reach."),
@@ -122,6 +146,11 @@ export const SystemGoalsSchema = z.object({
         .string()
         .min(1)
         .describe("How the system must behave / complete its task (quality attributes in prose)."),
+    acceptance_criteria: z
+        .array(AcceptanceCriterionSchema)
+        .optional()
+        .default([])
+        .describe("What the system must do, as verifiable criteria. Implementation options should be derived from these rather than the reverse."),
     nfrs: z.array(SystemGoalNfrSchema).optional().default([]),
 });
 // Read-only recommended implementation order for epic-planning surfaces. Hard
@@ -153,7 +182,7 @@ export const DecisionPageInputShape = {
         .optional()
         .default("review_decisions")
         .describe('Which flavor of page to render. "review_decisions" (default) is the ticket-review decision-capture page and is unaffected by the planning fields. "pre_ticket_planning" additionally renders the read-only system_goals and implementation_order sections for pre-ticket epic/task framing.'),
-    system_goals: SystemGoalsSchema.optional().describe("pre_ticket_planning only: read-only business goal, desired end-state, system behavior, and classified NFRs. Unresolved (open) NFRs should ALSO be passed as actionable_items so the human can decide them."),
+    system_goals: SystemGoalsSchema.optional().describe("pre_ticket_planning only: business goal, desired end-state, system behavior, acceptance criteria (what the system must do), and classified NFRs (the standards it must meet). Acceptance criteria and NFRs render with per-item stance controls. Unresolved (open) NFRs should ALSO be passed as actionable_items so the human can decide them."),
     implementation_order: z
         .array(ImplementationOrderItemSchema)
         .optional()