@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/epic-launch-profile.js

@@ -0,0 +1,455 @@
+/**
+ * Host-local epic-launch profiles (BAPI-1260).
+ *
+ * A profile is the approved, reusable binding guided setup produces for one
+ * epic launch target: WHICH Bridge API endpoint, WHICH repository, WHICH
+ * execution host and mode, HOW the packaged CLI is invoked, and REFERENCES to the
+ * run policy and the credential. It is what lets the launch command printed at
+ * the end of setup run unchanged in a fresh shell — no `export BAPI_BASE_URL`,
+ * no remembered working shell, no database repair.
+ *
+ * ## What it is not
+ *
+ *  - **Not a secret store.** A profile holds references only. The credential
+ *    reference names a `bapi:<repo>` entry in the user-scoped credential store;
+ *    the key itself stays there. Validation rejects any field this module does
+ *    not know, so a secret cannot be smuggled in under a new name.
+ *  - **Not project configuration.** Profiles live beside the credential store in
+ *    the USER's config directory (`$XDG_CONFIG_HOME/bridge/` or
+ *    `~/.config/bridge/`), never in the repository, so committed configuration
+ *    stays secret-free and host-neutral.
+ *  - **Not an authority.** A profile selects a target; the server still decides
+ *    admission. Changing a profile's target is a guided-setup act (it re-verifies
+ *    access at the new target); a command-line override alone never rebinds one.
+ *
+ * Every exported operation returns a typed result and never throws.
+ */
+import os from "node:os";
+import path from "node:path";
+import { chmod, mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { durablyReplaceCredentialStoreJson, getPrimaryCredentialStorePath, withCredentialStoreLock, } from "./credential-store.js";
+import { validateHttpBaseUrl, describeBaseUrlRejection } from "./base-url.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+import { isTransientNpxEntryPath } from "./mcp-server-invocation.js";
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** The only profile schema this build reads or writes. */
+export const EPIC_LAUNCH_PROFILE_VERSION = 1;
+/** File name of the host-local profile store, beside `credentials.json`. */
+export const EPIC_LAUNCH_PROFILE_STORE_FILENAME = "epic-launch-profiles.json";
+/** Selector shape: short, lowercase, shell-safe without quoting. */
+export const EPIC_LAUNCH_PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,62}$/;
+/** Where the executor that serves this launch runs. */
+export const EPIC_LAUNCH_EXECUTION_MODES = ["local", "durable"];
+/** One-time migration guidance for a profile this build cannot read. */
+export function epicLaunchProfileSetupGuidance(name) {
+    return (`Re-run guided setup to (re)write it: npx -y ${MCP_PACKAGE_NAME} install conductor ` +
+        `--launch-profile ${EPIC_LAUNCH_PROFILE_NAME_PATTERN.test(name) ? name : "<name>"} --base-url <url> ...`);
+}
+// ---------------------------------------------------------------------------
+// Validation (pure)
+// ---------------------------------------------------------------------------
+const PROFILE_KEYS = new Set([
+    "version",
+    "name",
+    "baseUrl",
+    "repoName",
+    "executionMode",
+    "host",
+    "runtime",
+    "policyRef",
+    "credentialRef",
+    "approvedAt",
+]);
+const NPM_CHANNEL_SPEC = new RegExp(`^${MCP_PACKAGE_NAME.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")}@[A-Za-z0-9][A-Za-z0-9.+-]{0,63}$`);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value, max = 512) {
+    return typeof value === "string" && value.trim().length > 0 && value.length <= max && !/[\0\n\r]/.test(value);
+}
+function malformed(name, field, why) {
+    return {
+        ok: false,
+        kind: "profile-malformed",
+        message: `Epic launch profile '${name}' is unusable: ${field} ${why}. ${epicLaunchProfileSetupGuidance(name)}`,
+    };
+}
+function validateRuntime(name, raw) {
+    if (!isPlainObject(raw))
+        return malformed(name, "runtime", "is not an object");
+    if (raw.kind === "packaged") {
+        const keys = Object.keys(raw);
+        if (keys.some((k) => !["kind", "executable", "entryPath"].includes(k))) {
+            return malformed(name, "runtime", "carries an unknown field");
+        }
+        if (!nonEmptyString(raw.executable) || !path.isAbsolute(raw.executable)) {
+            return malformed(name, "runtime.executable", "is not an absolute path");
+        }
+        if (!nonEmptyString(raw.entryPath) || !path.isAbsolute(raw.entryPath)) {
+            return malformed(name, "runtime.entryPath", "is not an absolute path");
+        }
+        if (isTransientNpxEntryPath(raw.entryPath)) {
+            return malformed(name, "runtime.entryPath", "lives in a transient npx cache that can be pruned");
+        }
+        return { kind: "packaged", executable: raw.executable, entryPath: raw.entryPath };
+    }
+    if (raw.kind === "npm-channel") {
+        if (Object.keys(raw).some((k) => !["kind", "spec"].includes(k))) {
+            return malformed(name, "runtime", "carries an unknown field");
+        }
+        if (typeof raw.spec !== "string" || !NPM_CHANNEL_SPEC.test(raw.spec)) {
+            return malformed(name, "runtime.spec", `is not ${MCP_PACKAGE_NAME}@<channel-or-version>`);
+        }
+        return { kind: "npm-channel", spec: raw.spec };
+    }
+    return malformed(name, "runtime.kind", "is not 'packaged' or 'npm-channel'");
+}
+/**
+ * Validate one decoded profile. Strict: unknown fields, a GitHub or non-`bapi:`
+ * credential reference, a transient runtime, a relative policy path, or a
+ * durable-mode profile without a packaged runtime are all refused.
+ */
+export function validateEpicLaunchProfile(raw, selector = "<unnamed>") {
+    if (!isPlainObject(raw))
+        return malformed(selector, "the entry", "is not an object");
+    if (raw.version !== EPIC_LAUNCH_PROFILE_VERSION) {
+        return {
+            ok: false,
+            kind: "profile-unsupported-version",
+            message: `Epic launch profile '${selector}' uses an unsupported schema version; this build reads ` +
+                `version ${EPIC_LAUNCH_PROFILE_VERSION} only. ${epicLaunchProfileSetupGuidance(selector)}`,
+        };
+    }
+    for (const key of Object.keys(raw)) {
+        if (!PROFILE_KEYS.has(key))
+            return malformed(selector, `field '${key.slice(0, 40)}'`, "is not recognized");
+    }
+    if (typeof raw.name !== "string" || !EPIC_LAUNCH_PROFILE_NAME_PATTERN.test(raw.name) || raw.name !== selector) {
+        return malformed(selector, "name", "does not match its selector");
+    }
+    const url = validateHttpBaseUrl(typeof raw.baseUrl === "string" ? raw.baseUrl : undefined);
+    if (!url.ok)
+        return malformed(selector, "baseUrl", `is invalid (${describeBaseUrlRejection("baseUrl", url.reason)})`);
+    if (url.baseUrl !== raw.baseUrl)
+        return malformed(selector, "baseUrl", "is not normalized");
+    if (!nonEmptyString(raw.repoName, 200))
+        return malformed(selector, "repoName", "is missing");
+    if (!EPIC_LAUNCH_EXECUTION_MODES.includes(raw.executionMode)) {
+        return malformed(selector, "executionMode", "is not 'local' or 'durable'");
+    }
+    if (!nonEmptyString(raw.host, 255))
+        return malformed(selector, "host", "is missing");
+    const runtime = validateRuntime(selector, raw.runtime);
+    if ("ok" in runtime)
+        return runtime;
+    if (raw.executionMode === "durable" && runtime.kind !== "packaged") {
+        return malformed(selector, "runtime", "must be a packaged absolute path for durable execution");
+    }
+    let policyRef = null;
+    if (raw.policyRef !== null && raw.policyRef !== undefined) {
+        const p = raw.policyRef;
+        if (!isPlainObject(p) || p.kind !== "file" || Object.keys(p).some((k) => k !== "kind" && k !== "path")) {
+            return malformed(selector, "policyRef", "is not a file reference");
+        }
+        if (!nonEmptyString(p.path) || !path.isAbsolute(p.path)) {
+            return malformed(selector, "policyRef.path", "is not an absolute path");
+        }
+        policyRef = { kind: "file", path: p.path };
+    }
+    const c = raw.credentialRef;
+    if (!isPlainObject(c) ||
+        c.store !== "bridge-credentials" ||
+        Object.keys(c).some((k) => k !== "store" && k !== "target") ||
+        c.target !== `bapi:${raw.repoName}`) {
+        // Refused rather than generalized: a launch uses exactly one Bridge
+        // credential, and a `github:*` (or any other) reference here would be the
+        // first step toward a standing code-host credential on the launch path.
+        return malformed(selector, "credentialRef", "must reference exactly bapi:<repoName>");
+    }
+    if (!nonEmptyString(raw.approvedAt, 64))
+        return malformed(selector, "approvedAt", "is missing");
+    return {
+        ok: true,
+        profile: {
+            version: EPIC_LAUNCH_PROFILE_VERSION,
+            name: raw.name,
+            baseUrl: url.baseUrl,
+            repoName: raw.repoName,
+            executionMode: raw.executionMode,
+            host: raw.host,
+            runtime,
+            policyRef,
+            credentialRef: { store: "bridge-credentials", target: `bapi:${raw.repoName}` },
+            approvedAt: raw.approvedAt,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Store I/O
+// ---------------------------------------------------------------------------
+/** The profile store path, beside the primary credential store. */
+export function getEpicLaunchProfileStorePath(deps) {
+    return path.join(path.dirname(getPrimaryCredentialStorePath(deps)), EPIC_LAUNCH_PROFILE_STORE_FILENAME);
+}
+async function readStoreDocument(deps) {
+    const storePath = getEpicLaunchProfileStorePath(deps);
+    let raw;
+    try {
+        raw = await deps.readFile(storePath);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code === "ENOENT") {
+            return { ok: true, present: false, document: { version: EPIC_LAUNCH_PROFILE_VERSION, profiles: {} } };
+        }
+        return { ok: false, kind: "store-unreadable", message: `Unable to read ${storePath}.` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, kind: "store-unreadable", message: `${storePath} is not valid JSON.` };
+    }
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.profiles)) {
+        return { ok: false, kind: "store-unreadable", message: `${storePath} has no profiles object.` };
+    }
+    if (parsed.version !== EPIC_LAUNCH_PROFILE_VERSION) {
+        return {
+            ok: false,
+            kind: "profile-unsupported-version",
+            message: `${storePath} uses an unsupported schema version; this build reads version ` +
+                `${EPIC_LAUNCH_PROFILE_VERSION} only. ${epicLaunchProfileSetupGuidance("<name>")}`,
+        };
+    }
+    return { ok: true, present: true, document: { version: EPIC_LAUNCH_PROFILE_VERSION, profiles: parsed.profiles } };
+}
+/**
+ * Read and validate one profile by selector. Read-only: a missing, malformed, or
+ * unsupported profile is reported with guidance and never repaired here.
+ *
+ * `host`, when supplied, must match the profile's approved host — a profile
+ * copied to another machine names a runtime and a credential store that do not
+ * exist there.
+ */
+export async function readEpicLaunchProfile(name, deps) {
+    if (!EPIC_LAUNCH_PROFILE_NAME_PATTERN.test(name)) {
+        return {
+            ok: false,
+            kind: "invalid-name",
+            message: "An epic launch profile name must match [a-z0-9][a-z0-9._-]{0,62}.",
+        };
+    }
+    const store = await readStoreDocument(deps);
+    if (!store.ok)
+        return store;
+    if (!Object.prototype.hasOwnProperty.call(store.document.profiles, name)) {
+        return {
+            ok: false,
+            kind: "profile-missing",
+            message: `No epic launch profile named '${name}' exists on this host. ${epicLaunchProfileSetupGuidance(name)}`,
+        };
+    }
+    const validated = validateEpicLaunchProfile(store.document.profiles[name], name);
+    if (!validated.ok)
+        return validated;
+    if (deps.host !== undefined && validated.profile.host !== deps.host) {
+        return {
+            ok: false,
+            kind: "profile-host-mismatch",
+            message: `Epic launch profile '${name}' was approved on a different host. Profiles are host-local; ` +
+                epicLaunchProfileSetupGuidance(name),
+        };
+    }
+    return validated;
+}
+export async function listEpicLaunchProfiles(deps) {
+    const store = await readStoreDocument(deps);
+    if (!store.ok)
+        return store;
+    if (!store.present)
+        return { ok: true, present: false };
+    const entries = Object.keys(store.document.profiles)
+        .sort()
+        .map((name) => ({ name, validation: validateEpicLaunchProfile(store.document.profiles[name], name) }));
+    return { ok: true, present: true, entries };
+}
+/**
+ * Persist one validated profile: locked (the shared credential-store lock) and
+ * durable (temp → fsync → rename). Every other profile in the store is kept,
+ * including ones this build cannot validate — a newer build's profile is never
+ * deleted by an older one.
+ */
+export async function writeEpicLaunchProfile(profile, deps) {
+    const validated = validateEpicLaunchProfile(profile, profile.name);
+    if (!validated.ok)
+        return validated;
+    const storePath = getEpicLaunchProfileStorePath(deps);
+    return withCredentialStoreLock(deps, async () => {
+        const store = await readStoreDocument(deps);
+        if (!store.ok)
+            return store;
+        const existing = store.document.profiles[profile.name];
+        const serialized = JSON.parse(JSON.stringify(validated.profile));
+        if (existing !== undefined && JSON.stringify(existing) === JSON.stringify(serialized)) {
+            return { ok: true, path: storePath, action: "unchanged" };
+        }
+        const next = {
+            version: EPIC_LAUNCH_PROFILE_VERSION,
+            profiles: { ...store.document.profiles, [profile.name]: serialized },
+        };
+        // The durable writer is typed for the credential store, but it serializes
+        // any JSON value the same way (2-space indent, 0600, fsync, rename).
+        const written = await durablyReplaceCredentialStoreJson(storePath, next, deps);
+        if (!written.ok) {
+            return { ok: false, kind: "store-write-failed", message: `Failed to durably write ${storePath}.` };
+        }
+        return { ok: true, path: storePath, action: existing === undefined ? "created" : "updated" };
+    }, (error) => ({ ok: false, kind: "store-write-failed", message: error }));
+}
+/**
+ * Normalize every applicable target source and decide ONE target, before any
+ * credential is resolved and before any request is made.
+ *
+ *  - With a selected profile, the profile's target wins, and a `--base-url` or
+ *    `BAPI_BASE_URL` that names a DIFFERENT endpoint is a conflict — an override
+ *    alone never rebinds a profile; guided setup does that.
+ *  - Without one, `--base-url` and `BAPI_BASE_URL` must agree when both are set.
+ *  - Nothing set is `target-missing`. There is no production default here:
+ *    production is supported, but only as a deliberate selection.
+ *
+ * Messages name the source and the rule only — never a URL, which can carry
+ * userinfo.
+ */
+export function resolveEpicLaunchTarget(inputs) {
+    const normalize = (raw, label) => {
+        if (raw === undefined || raw.trim() === "")
+            return { ok: true, value: null };
+        const v = validateHttpBaseUrl(raw);
+        if (!v.ok)
+            return { ok: false, message: describeBaseUrlRejection(label, v.reason) };
+        return { ok: true, value: v.baseUrl };
+    };
+    const flag = normalize(inputs.flagBaseUrl, "--base-url");
+    if (!flag.ok)
+        return { ok: false, kind: "target-invalid", message: flag.message };
+    const env = normalize(inputs.env.BAPI_BASE_URL, "BAPI_BASE_URL");
+    if (!env.ok)
+        return { ok: false, kind: "target-invalid", message: env.message };
+    const profile = inputs.profile;
+    if (profile !== null) {
+        if (flag.value !== null && flag.value !== profile.baseUrl) {
+            return {
+                ok: false,
+                kind: "target-conflict",
+                message: `--base-url names a different endpoint than launch profile '${profile.name}'. An override ` +
+                    "does not rebind a profile; re-run guided setup to change its target.",
+            };
+        }
+        if (env.value !== null && env.value !== profile.baseUrl) {
+            return {
+                ok: false,
+                kind: "target-conflict",
+                message: `BAPI_BASE_URL names a different endpoint than launch profile '${profile.name}'. Unset it, ` +
+                    "or re-run guided setup to change the profile's target.",
+            };
+        }
+        const flagRepo = inputs.flagRepo?.trim();
+        if (flagRepo && flagRepo !== profile.repoName) {
+            return {
+                ok: false,
+                kind: "repository-conflict",
+                message: `--repo names a different repository than launch profile '${profile.name}'.`,
+            };
+        }
+        return { ok: true, baseUrl: profile.baseUrl, source: "profile", repoName: profile.repoName };
+    }
+    if (flag.value !== null && env.value !== null && flag.value !== env.value) {
+        return {
+            ok: false,
+            kind: "target-conflict",
+            message: "--base-url and BAPI_BASE_URL name different endpoints. Keep one, or make them agree.",
+        };
+    }
+    if (flag.value !== null)
+        return { ok: true, baseUrl: flag.value, source: "flag" };
+    if (env.value !== null)
+        return { ok: true, baseUrl: env.value, source: "env" };
+    return {
+        ok: false,
+        kind: "target-missing",
+        message: "No Bridge API target is selected for this epic launch. Pass --launch-profile <name> (created by " +
+            `\`npx -y ${MCP_PACKAGE_NAME} install conductor --launch-profile <name> --base-url <url>\`), or ` +
+            "--base-url <url>. Nothing defaults to production.",
+    };
+}
+// ---------------------------------------------------------------------------
+// Command rendering (pure)
+// ---------------------------------------------------------------------------
+/** POSIX single-quote a word unless it is already shell-safe. */
+export function shellQuote(word) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(word))
+        return word;
+    return `'${word.replace(/'/g, `'\\''`)}'`;
+}
+/** The argv prefix that invokes the packaged CLI for a runtime. */
+export function epicLaunchRuntimeArgv(runtime) {
+    return runtime.kind === "packaged"
+        ? [runtime.executable, runtime.entryPath]
+        : ["npx", "-y", runtime.spec];
+}
+/**
+ * Render the one reusable `drive-epic` command for a profile: shell-safe,
+ * secret-free (a profile holds no secret and nothing here reads the
+ * environment), and complete — the profile selector, the plan, and the policy —
+ * so it runs unchanged in a fresh shell.
+ */
+export function renderEpicLaunchCommand(profile, inputs) {
+    const policy = inputs.policyFile ?? profile.policyRef?.path;
+    const argv = [
+        ...epicLaunchRuntimeArgv(profile.runtime),
+        "drive-epic",
+        inputs.epicKey,
+        "--launch-profile",
+        profile.name,
+        "--plan-file",
+        inputs.planFile,
+        ...(policy ? ["--policy-file", policy] : []),
+        ...(inputs.featureBranch ? ["--feature-branch", inputs.featureBranch] : []),
+        ...(inputs.intoBase ? ["--into-base"] : []),
+        ...(inputs.attended ? ["--attended"] : []),
+    ];
+    return argv.map(shellQuote).join(" ");
+}
+// ---------------------------------------------------------------------------
+// Production I/O
+// ---------------------------------------------------------------------------
+/**
+ * Real-filesystem write deps for the profile store and the credential binding:
+ * `fs/promises` plus the `open` primitive that gives the shared lock and the
+ * fsync'd replacement. Built here rather than imported from `index.ts`, whose
+ * import runs the CLI dispatcher.
+ */
+export function createNodeEpicLaunchStoreDeps(env = process.env) {
+    return {
+        env,
+        homedir: os.homedir,
+        platform: process.platform,
+        readFile: (p) => readFile(p, "utf-8"),
+        mkdir: (p, options) => mkdir(p, options),
+        writeFile: (p, data, options) => writeFile(p, data, options),
+        rename: (oldPath, newPath) => rename(oldPath, newPath),
+        chmod: (p, mode) => chmod(p, mode),
+        unlink: (p) => unlink(p),
+        open: async (p, flags, mode) => {
+            const handle = await open(p, flags, mode);
+            return {
+                writeFile: (data) => handle.writeFile(data, { encoding: "utf-8" }),
+                sync: () => handle.sync(),
+                close: () => handle.close(),
+            };
+        },
+    };
+}