stageflow 0.36.0 → 0.40.0

package/dist/config/loadTask.js

@@ -6,6 +6,16 @@ import { yamlParsePosition } from "./yamlParsePosition.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function parseCheckout(value) {
+    if (typeof value === "string")
+        return value;
+    if (isPlainObject(value)) {
+        const branch = typeof value.branch === "string" ? value.branch : undefined;
+        const base = typeof value.base === "string" ? value.base : undefined;
+        return { ...(branch !== undefined ? { branch } : {}), ...(base !== undefined ? { base } : {}) };
+    }
+    return undefined;
+}
 function parseGitIdentity(raw) {
     if (!isPlainObject(raw))
         return undefined;
@@ -30,7 +40,7 @@ export function coerceTaskFile(raw) {
         goal: record.goal,
         context: typeof record.context === "string" ? record.context : undefined,
         constraints: typeof record.constraints === "string" ? record.constraints : undefined,
-        checkout: typeof record.checkout === "string" ? record.checkout : undefined,
+        checkout: parseCheckout(record.checkout),
         ...(typeof record.repository === "string" ? { repository: record.repository } : {}),
         ...(typeof record.ref === "string" ? { ref: record.ref } : {}),
         ...(typeof record.run_branch_template === "string"
@@ -73,6 +83,29 @@ export function parseTaskFile(raw, source = "task") {
             return { ...issue, taskId: task.id };
         }));
     }
+    if (isPlainObject(record?.checkout)) {
+        const { branch, base } = record.checkout;
+        if (branch !== undefined && typeof branch !== "string") {
+            return loadFailure([
+                {
+                    code: "task.invalid_shape",
+                    message: `Invalid ${source}: checkout.branch must be a string`,
+                    category: "task",
+                    taskId: task.id,
+                },
+            ]);
+        }
+        if (base !== undefined && typeof base !== "string") {
+            return loadFailure([
+                {
+                    code: "task.invalid_shape",
+                    message: `Invalid ${source}: checkout.base must be a string`,
+                    category: "task",
+                    taskId: task.id,
+                },
+            ]);
+        }
+    }
     return loadSuccess(task);
 }
 export function loadTaskFromYamlOutcome(yamlText, source = "task yaml") {

package/dist/config/mcpHostCatalog.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Host-level MCP state kept under $STAGEFLOW_HOME so it survives image rebuilds:
+ * - `mcp/.mcp.json` — servers added from the console, merged over the project `.mcp.json`
+ * - `secrets/mcp-secrets.json` — write-only values that fill `${VAR}` in those configs
+ */
+export type HostMcpError = Error & {
+    code: "invalid_server" | "invalid_secret" | "reserved_name";
+};
+/**
+ * A host-state file exists but cannot be trusted (unparseable, wrong shape, unreadable). It is
+ * never read as empty and never overwritten: the owner has to fix or remove the file.
+ */
+export declare class McpHostStateError extends Error {
+    readonly code: "host_state_corrupt";
+    readonly file: string;
+    constructor(file: string, detail: string);
+}
+export declare function isMcpHostStateError(err: unknown): err is McpHostStateError;
+export declare function hostMcpCatalogPath(home?: string): string;
+export declare function mcpSecretsPath(home?: string): string;
+/** Servers the console saved. Missing file = empty; a corrupt file throws McpHostStateError. */
+export declare function readHostMcpServers(home?: string): Record<string, Record<string, unknown>>;
+/** Host env names an owner explicitly lets agents and probes use to fill `${NAME}`. */
+export declare const MCP_ENV_ALLOW = "STAGEFLOW_MCP_ENV_ALLOW";
+export declare function mcpEnvAllowNames(env?: NodeJS.ProcessEnv): string[];
+export declare function assertServerName(name: string): void;
+export declare function validateServerEntry(name: string, rawEntry: unknown): Record<string, unknown>;
+/** Placeholders (`${NAME}`) without a `:-default`, in the order they appear. */
+export declare function requiredVars(entry: Record<string, unknown>): string[];
+export type SaveServerResult = {
+    name: string;
+    /** Names of secrets created from literal tokens in the pasted config. */
+    secretsStored: string[];
+};
+/**
+ * Save one server. Literal tokens in env, headers, url (query/userinfo) and args are moved into the
+ * secrets store and replaced with `${NAME}`, so the catalog file never holds a secret.
+ *
+ * Both files are read first (a corrupt one aborts before anything is written). The secrets file is
+ * written before the catalog and put back if the catalog write fails.
+ */
+export declare function saveHostMcpServer(name: string, entry: unknown, home?: string): SaveServerResult;
+export declare function removeHostMcpServer(name: string, home?: string): boolean;
+/** Pull `{ name: entry }` out of pasted JSON: a full `.mcp.json`, a bare map, or `{ mcpServers }`. */
+export declare function parsePastedMcpJson(raw: unknown): Record<string, unknown>;
+export declare function readMcpSecrets(home?: string): Record<string, string>;
+export declare function setMcpSecret(name: string, value: string, home?: string): void;
+export declare function deleteMcpSecret(name: string, home?: string): boolean;
+/** Secret names only; values never leave the store through the API. */
+export declare function listMcpSecretNames(home?: string): string[];

package/dist/config/mcpHostCatalog.js

@@ -0,0 +1,405 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { isForeverDeniedSecret, isProviderOrCloudName } from "../runtime/stageEnvironment.js";
+import { assertSafeMcpUrl, extractSecrets, McpUrlPolicyError, } from "./mcpRedaction.js";
+function hostError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+/**
+ * A host-state file exists but cannot be trusted (unparseable, wrong shape, unreadable). It is
+ * never read as empty and never overwritten: the owner has to fix or remove the file.
+ */
+export class McpHostStateError extends Error {
+    code = "host_state_corrupt";
+    file;
+    constructor(file, detail) {
+        super(`MCP host state file "${file}" ${detail}. Fix or remove it; nothing was changed.`);
+        this.name = "McpHostStateError";
+        this.file = file;
+    }
+}
+export function isMcpHostStateError(err) {
+    return err instanceof McpHostStateError;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function hostMcpCatalogPath(home = globalStageflowHome()) {
+    return path.join(home, "mcp", ".mcp.json");
+}
+export function mcpSecretsPath(home = globalStageflowHome()) {
+    return path.join(home, "secrets", "mcp-secrets.json");
+}
+/** Write via a uniquely named tmp file created with the final mode, then rename into place. */
+function atomicWrite(file, body, mode) {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tmp, body, { mode, flag: "wx" });
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* tmp never created */
+        }
+        throw err;
+    }
+}
+function readJsonState(file) {
+    if (!existsSync(file))
+        return undefined;
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (err) {
+        throw new McpHostStateError(file, `could not be read (${err.code ?? "error"})`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new McpHostStateError(file, "is not valid JSON");
+    }
+}
+/** Servers the console saved. Missing file = empty; a corrupt file throws McpHostStateError. */
+export function readHostMcpServers(home = globalStageflowHome()) {
+    const file = hostMcpCatalogPath(home);
+    const parsed = readJsonState(file);
+    if (parsed === undefined)
+        return {};
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.mcpServers)) {
+        throw new McpHostStateError(file, "does not have an mcpServers object");
+    }
+    const out = {};
+    for (const [name, entry] of Object.entries(parsed.mcpServers)) {
+        if (name === STAGEFLOW_MCP_SERVER_NAME)
+            continue;
+        if (!isPlainObject(entry)) {
+            throw new McpHostStateError(file, `has a non-object entry for "${name}"`);
+        }
+        out[name] = entry;
+    }
+    return out;
+}
+function writeHostMcpServers(servers, home) {
+    atomicWrite(hostMcpCatalogPath(home), `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`, 0o600);
+}
+/** Host env names an owner explicitly lets agents and probes use to fill `${NAME}`. */
+export const MCP_ENV_ALLOW = "STAGEFLOW_MCP_ENV_ALLOW";
+export function mcpEnvAllowNames(env = process.env) {
+    const raw = env[MCP_ENV_ALLOW];
+    if (raw === undefined || raw.trim() === "")
+        return [];
+    return raw
+        .split(",")
+        .map((n) => n.trim())
+        .filter((n) => n.length > 0 && !isForeverDeniedSecret(n));
+}
+const SERVER_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const MAX_SECRET_BYTES = 16 * 1024;
+const PLACEHOLDER = /\$\{([^}]*)\}/g;
+export function assertServerName(name) {
+    if (name === STAGEFLOW_MCP_SERVER_NAME) {
+        throw hostError("reserved_name", `"${name}" is reserved`);
+    }
+    if (!SERVER_NAME.test(name)) {
+        throw hostError("invalid_server", "Server name must be 1-64 letters, digits, '.', '_' or '-'");
+    }
+}
+/**
+ * Other tools write remote servers as `serverUrl` / `httpUrl` and mark the transport with `type`.
+ * Map those onto our shape: `url`, plus `httpTransport: "sse"` only when SSE is asked for
+ * (streamable HTTP is the default and falls back to SSE by itself).
+ */
+function normaliseSnippet(entry) {
+    const out = { ...entry };
+    for (const alias of ["serverUrl", "httpUrl"]) {
+        if (out.url === undefined && typeof out[alias] === "string")
+            out.url = out[alias];
+        delete out[alias];
+    }
+    const kind = out.type ?? out.transport;
+    delete out.type;
+    delete out.transport;
+    if (kind !== undefined) {
+        if (kind === "sse")
+            out.httpTransport = "sse";
+        else if (kind === "http" || kind === "streamable-http" || kind === "streamableHttp") {
+            if (out.httpTransport === undefined)
+                out.httpTransport = "streamable-http";
+        }
+        else if (kind !== "stdio") {
+            throw hostError("invalid_server", `Unsupported server type "${String(kind)}" (use stdio, http or sse)`);
+        }
+    }
+    return out;
+}
+export function validateServerEntry(name, rawEntry) {
+    assertServerName(name);
+    if (!isPlainObject(rawEntry)) {
+        throw hostError("invalid_server", `Server "${name}" must be an object`);
+    }
+    const entry = normaliseSnippet(rawEntry);
+    const hasCommand = Object.hasOwn(entry, "command");
+    const hasUrl = Object.hasOwn(entry, "url");
+    if (hasCommand === hasUrl) {
+        throw hostError("invalid_server", `Server "${name}" needs exactly one of "command" (stdio) or "url" (http)`);
+    }
+    const text = (key) => {
+        const v = entry[key];
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== "string" || v.trim().length === 0) {
+            throw hostError("invalid_server", `"${key}" must be a non-empty string`);
+        }
+        return v;
+    };
+    const out = {};
+    if (hasCommand)
+        out.command = text("command");
+    if (hasUrl) {
+        const url = text("url");
+        if (!/^(?:https?:\/\/|\$\{)/i.test(url)) {
+            throw hostError("invalid_server", `"url" must start with http:// or https://`);
+        }
+        try {
+            assertSafeMcpUrl(url);
+        }
+        catch (err) {
+            if (err instanceof McpUrlPolicyError)
+                throw hostError("invalid_server", err.message);
+            throw err;
+        }
+        out.url = url;
+        const transport = entry.httpTransport;
+        if (transport !== undefined) {
+            if (transport !== "sse" && transport !== "streamable-http") {
+                throw hostError("invalid_server", `"httpTransport" must be "sse" or "streamable-http"`);
+            }
+            // Streamable HTTP is the default; only SSE needs to be spelled out.
+            if (transport === "sse")
+                out.httpTransport = "sse";
+        }
+    }
+    else if (entry.httpTransport !== undefined) {
+        throw hostError("invalid_server", `"httpTransport" only applies to url servers`);
+    }
+    if (entry.args !== undefined) {
+        if (!Array.isArray(entry.args) || entry.args.some((a) => typeof a !== "string")) {
+            throw hostError("invalid_server", `"args" must be an array of strings`);
+        }
+        out.args = entry.args;
+    }
+    for (const key of ["env", "headers"]) {
+        const bag = entry[key];
+        if (bag === undefined)
+            continue;
+        if (!isPlainObject(bag) || Object.values(bag).some((v) => typeof v !== "string")) {
+            throw hostError("invalid_server", `"${key}" must map names to strings`);
+        }
+        if (key === "env" && hasUrl) {
+            throw hostError("invalid_server", `"env" only applies to stdio servers`);
+        }
+        if (key === "headers" && hasCommand) {
+            throw hostError("invalid_server", `"headers" only applies to http servers`);
+        }
+        out[key] = { ...bag };
+    }
+    const cwd = text("cwd");
+    if (cwd !== undefined)
+        out.cwd = cwd;
+    assertPlaceholderNamesAllowed(name, out);
+    return out;
+}
+/** Every `${NAME}` / `${NAME:-x}` name in an entry, in order of appearance. */
+function placeholderNames(entry) {
+    const found = new Set();
+    const scan = (value) => {
+        if (typeof value !== "string")
+            return;
+        for (const m of value.matchAll(PLACEHOLDER)) {
+            const inner = (m[1] ?? "").split(":-")[0] ?? "";
+            if (SECRET_NAME.test(inner))
+                found.add(inner);
+        }
+    };
+    scan(entry.command);
+    scan(entry.url);
+    scan(entry.cwd);
+    if (Array.isArray(entry.args))
+        entry.args.forEach(scan);
+    for (const key of ["env", "headers"]) {
+        const bag = entry[key];
+        if (isPlainObject(bag))
+            Object.values(bag).forEach(scan);
+    }
+    return [...found];
+}
+/**
+ * A server entry may not ask for the Host's own credentials: control tokens (forever denied) or
+ * provider/cloud credentials, unless the owner put the name in STAGEFLOW_MCP_ENV_ALLOW.
+ */
+function assertPlaceholderNamesAllowed(server, entry) {
+    const allowed = new Set(mcpEnvAllowNames());
+    for (const name of placeholderNames(entry)) {
+        if (isForeverDeniedSecret(name)) {
+            throw hostError("invalid_server", `Server "${server}" uses \${${name}}, which can never be provided to an MCP server`);
+        }
+        if (isProviderOrCloudName(name) && !allowed.has(name)) {
+            throw hostError("invalid_server", `Server "${server}" uses \${${name}}, a provider or cloud credential name. Use a different variable name, or list it in ${MCP_ENV_ALLOW} to allow it.`);
+        }
+    }
+}
+function secretNameFor(key, server, value, existing) {
+    const serverPart = server.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+    // `Authorization` says nothing about which service the token is for.
+    const base = key.toLowerCase() === "authorization"
+        ? `${serverPart}_TOKEN`
+        : key.toUpperCase().replace(/[^A-Z0-9_]/g, "_").replace(/^(\d)/, "_$1") || "SECRET";
+    const prefixed = `${server.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_${base}`;
+    for (const candidate of [base, prefixed]) {
+        if (isForeverDeniedSecret(candidate) || isProviderOrCloudName(candidate))
+            continue;
+        if (existing[candidate] === undefined || existing[candidate] === value)
+            return candidate;
+    }
+    return `${prefixed}_2`;
+}
+/** Placeholders (`${NAME}`) without a `:-default`, in the order they appear. */
+export function requiredVars(entry) {
+    const found = new Set();
+    const scan = (value) => {
+        if (typeof value !== "string")
+            return;
+        for (const m of value.matchAll(PLACEHOLDER)) {
+            const inner = m[1] ?? "";
+            if (SECRET_NAME.test(inner))
+                found.add(inner);
+        }
+    };
+    scan(entry.command);
+    scan(entry.url);
+    scan(entry.cwd);
+    if (Array.isArray(entry.args))
+        entry.args.forEach(scan);
+    for (const key of ["env", "headers"]) {
+        const bag = entry[key];
+        if (isPlainObject(bag))
+            Object.values(bag).forEach(scan);
+    }
+    return [...found];
+}
+/**
+ * Save one server. Literal tokens in env, headers, url (query/userinfo) and args are moved into the
+ * secrets store and replaced with `${NAME}`, so the catalog file never holds a secret.
+ *
+ * Both files are read first (a corrupt one aborts before anything is written). The secrets file is
+ * written before the catalog and put back if the catalog write fails.
+ */
+export function saveHostMcpServer(name, entry, home = globalStageflowHome()) {
+    const validated = validateServerEntry(name, entry);
+    const secrets = readMcpSecrets(home);
+    const servers = readHostMcpServers(home);
+    const { entry: stored, secrets: pending } = extractSecrets(validated, (key, value, taken) => secretNameFor(key, name, value, taken), secrets);
+    for (const secretName of Object.keys(pending))
+        assertUsableSecret(secretName, pending[secretName]);
+    servers[name] = stored;
+    const names = Object.keys(pending);
+    if (names.length === 0) {
+        writeHostMcpServers(servers, home);
+        return { name, secretsStored: [] };
+    }
+    const secretsFile = mcpSecretsPath(home);
+    const previous = existsSync(secretsFile) ? readFileSync(secretsFile, "utf8") : undefined;
+    writeMcpSecretsFile({ ...secrets, ...pending }, home);
+    try {
+        writeHostMcpServers(servers, home);
+    }
+    catch (err) {
+        try {
+            if (previous === undefined)
+                rmSync(secretsFile, { force: true });
+            else
+                atomicWrite(secretsFile, previous, 0o600);
+        }
+        catch {
+            /* best effort: the original error is the one to report */
+        }
+        throw err;
+    }
+    return { name, secretsStored: names };
+}
+export function removeHostMcpServer(name, home = globalStageflowHome()) {
+    const servers = readHostMcpServers(home);
+    if (!Object.hasOwn(servers, name))
+        return false;
+    delete servers[name];
+    writeHostMcpServers(servers, home);
+    return true;
+}
+/** Pull `{ name: entry }` out of pasted JSON: a full `.mcp.json`, a bare map, or `{ mcpServers }`. */
+export function parsePastedMcpJson(raw) {
+    if (!isPlainObject(raw)) {
+        throw hostError("invalid_server", "Pasted JSON must be an object");
+    }
+    const inner = isPlainObject(raw.mcpServers) ? raw.mcpServers : raw;
+    if (Object.hasOwn(inner, "command") || Object.hasOwn(inner, "url")) {
+        throw hostError("invalid_server", 'Wrap a single server as { "mcpServers": { "name": { … } } } so it has a name');
+    }
+    if (Object.keys(inner).length === 0) {
+        throw hostError("invalid_server", "No servers found in the pasted JSON");
+    }
+    return inner;
+}
+export function readMcpSecrets(home = globalStageflowHome()) {
+    const file = mcpSecretsPath(home);
+    const parsed = readJsonState(file);
+    if (parsed === undefined)
+        return {};
+    if (!isPlainObject(parsed)) {
+        throw new McpHostStateError(file, "is not a JSON object of secret names to values");
+    }
+    const out = {};
+    for (const [name, value] of Object.entries(parsed)) {
+        if (typeof value === "string" && SECRET_NAME.test(name))
+            out[name] = value;
+    }
+    return out;
+}
+function writeMcpSecretsFile(secrets, home) {
+    atomicWrite(mcpSecretsPath(home), `${JSON.stringify(secrets, null, 2)}\n`, 0o600);
+}
+function assertUsableSecret(name, value) {
+    if (!SECRET_NAME.test(name) || isForeverDeniedSecret(name)) {
+        throw hostError("invalid_secret", `"${name}" is not a usable secret name`);
+    }
+    if (value.length === 0 || Buffer.byteLength(value) > MAX_SECRET_BYTES) {
+        throw hostError("invalid_secret", "Secret value must be 1 byte to 16 KB");
+    }
+}
+export function setMcpSecret(name, value, home = globalStageflowHome()) {
+    assertUsableSecret(name, value);
+    const secrets = readMcpSecrets(home);
+    secrets[name] = value;
+    writeMcpSecretsFile(secrets, home);
+}
+export function deleteMcpSecret(name, home = globalStageflowHome()) {
+    const secrets = readMcpSecrets(home);
+    if (!Object.hasOwn(secrets, name))
+        return false;
+    delete secrets[name];
+    writeMcpSecretsFile(secrets, home);
+    return true;
+}
+/** Secret names only; values never leave the store through the API. */
+export function listMcpSecretNames(home = globalStageflowHome()) {
+    return Object.keys(readMcpSecrets(home)).sort();
+}

package/dist/config/mcpOAuth.d.ts

@@ -0,0 +1,37 @@
+/**
+ * OAuth sign-in for remote MCP servers, run through pi-mcp-adapter's own flow.
+ *
+ * Tokens live in the adapter's encrypted-file store under the Host's Pi agent dir
+ * (`$STAGEFLOW_HOME/agent/mcp-oauth-encrypted`) and are keyed by a Host-generated key, so it works
+ * in a container with no OS keyring. The adapter refuses a symlinked store, and stage attempts run
+ * with a sealed per-attempt agent dir, so signed-in servers are available to agents and Check, not
+ * to pipeline stages.
+ */
+export declare const OAUTH_FILE_KEY_ENV = "PI_MCP_ADAPTER_OAUTH_FILE_KEY";
+export type McpOAuthStatus = "authenticated" | "expired" | "not_authenticated";
+export type McpOAuthErrorCode = "not_found" | "not_http" | "store_unavailable" | "flow_failed" | "invalid_input" | "blocked_url" | "host_state_corrupt";
+/** HTTP status for each OAuth error code; the routes use this one table. */
+export declare const MCP_OAUTH_HTTP_STATUS: Record<McpOAuthErrorCode, number>;
+export declare class McpOAuthError extends Error {
+    readonly code: McpOAuthErrorCode;
+    constructor(message: string, code: McpOAuthErrorCode);
+}
+export declare function oauthKeyPath(home?: string): string;
+/**
+ * Make the Host's file key available to the adapter, creating it on first use. The key is written
+ * to a private tmp file and linked into place, so a concurrent reader never sees a half-written key.
+ */
+export declare function ensureOAuthFileKey(home?: string): void;
+/** Everything the adapter needs before it can read or write OAuth tokens in this process. */
+export declare function prepareMcpOAuth(): void;
+export declare function resetMcpOAuthFlowCacheForTests(): void;
+/** Begin sign-in; returns the link to open in a browser. */
+export declare function startMcpOAuth(projectRoot: string, name: string): Promise<{
+    authorizationUrl: string;
+}>;
+/** The pasted redirect address, or a bare authorization code of sane length. */
+export declare function assertOAuthInput(input: string): void;
+/** Finish sign-in from the redirect URL the browser landed on (or a bare code). */
+export declare function completeMcpOAuth(name: string, input: string, projectRoot?: string): Promise<McpOAuthStatus>;
+export declare function mcpOAuthStatus(name: string, projectRoot?: string): Promise<McpOAuthStatus>;
+export declare function removeMcpOAuth(name: string, projectRoot?: string): Promise<void>;