stageflow 0.9.0 → 0.13.0

package/dist/config/resolvePipelineDag.js

@@ -1,4 +1,6 @@
 import { isAllowedPipelineStageEntryKey } from "./pipelineStageKeys.js";
+import { parseExecutionPolicy } from "./parseCompletionContract.js";
+import { parsePipelineNeeds, predecessorEdges, toNeedEdges } from "./pipelineNeeds.js";
 const ALLOWED_FORK_KEYS = new Set(["select", "allow_none"]);
 function pipelineLabel(ctx) {
     return `Pipeline ${ctx.pipelineId} (${ctx.path})`;
@@ -9,6 +11,44 @@ function formatError(ctx, message) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+const ALLOWED_FEEDBACK_LOOP_KEYS = new Set([
+    "target",
+    "max_replays",
+    "on_max_replays",
+    "replay_session",
+]);
+export function parseFeedbackLoopConfig(value, stageId, ctx) {
+    if (!isPlainObject(value)) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop must be an object`));
+    }
+    for (const key of Object.keys(value)) {
+        if (!ALLOWED_FEEDBACK_LOOP_KEYS.has(key)) {
+            throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop: unknown key "${key}"`));
+        }
+    }
+    if (Array.isArray(value.target)) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.target must be a single stage id string, not an array`));
+    }
+    if (typeof value.target !== "string" || value.target.trim() === "") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.target must be a non-empty stage id`));
+    }
+    if (!Number.isInteger(value.max_replays) || value.max_replays < 1) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.max_replays must be a positive integer`));
+    }
+    if (value.on_max_replays !== "require_continue" &&
+        value.on_max_replays !== "wait_for_human") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.on_max_replays must be "require_continue" or "wait_for_human"`));
+    }
+    if (value.replay_session !== "resume" && value.replay_session !== "new_session") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.replay_session must be "resume" or "new_session"`));
+    }
+    return {
+        target: value.target,
+        max_replays: value.max_replays,
+        on_max_replays: value.on_max_replays,
+        replay_session: value.replay_session,
+    };
+}
 export function parsePipelineStageEntries(raw, ctx) {
     if (!Array.isArray(raw)) {
         throw new Error(formatError(ctx, "stages[] is required"));
@@ -53,41 +93,69 @@ export function parsePipelineStageEntries(raw, ctx) {
             ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
             ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
         };
+        const policyOutcome = parseExecutionPolicy(entry, entry.id);
+        if (!policyOutcome.ok) {
+            throw new Error(formatError(ctx, policyOutcome.issues[0]?.message ?? "invalid execution policy"));
+        }
+        const policyFields = {
+            ...(policyOutcome.value.completion !== undefined
+                ? { completion: policyOutcome.value.completion }
+                : {}),
+            ...(policyOutcome.value.recovery !== undefined
+                ? { recovery: policyOutcome.value.recovery }
+                : {}),
+        };
+        const feedbackLoopFields = entry.feedback_loop !== undefined
+            ? { feedback_loop: parseFeedbackLoopConfig(entry.feedback_loop, entry.id, ctx) }
+            : {};
+        if (entry.replay_safe !== undefined && typeof entry.replay_safe !== "boolean") {
+            throw new Error(formatError(ctx, `stage "${entry.id}": replay_safe must be a boolean`));
+        }
+        const replaySafetyFields = entry.replay_safe !== undefined ? { replay_safe: entry.replay_safe } : {};
         if (entry.needs === undefined) {
             entries.push({
                 id: entry.id,
                 ...(forkValue !== undefined ? { fork: forkValue } : {}),
                 ...clonableFields,
+                ...policyFields,
+                ...feedbackLoopFields,
+                ...replaySafetyFields,
             });
             continue;
         }
-        if (Array.isArray(entry.needs)) {
-            if (entry.needs.length > 1) {
-                throw new Error(formatError(ctx, `stage "${entry.id}": fan-in not supported; needs must be a single stage id`));
-            }
-            throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a string, not an array`));
-        }
-        if (typeof entry.needs !== "string" || !entry.needs) {
-            throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a non-empty string`));
+        const parsedNeeds = parsePipelineNeeds(entry.needs, entry.id);
+        if (!parsedNeeds.ok) {
+            throw new Error(formatError(ctx, parsedNeeds.message));
         }
         entries.push({
             id: entry.id,
-            needs: entry.needs,
+            needs: parsedNeeds.value,
             ...(forkValue !== undefined ? { fork: forkValue } : {}),
             ...clonableFields,
+            ...policyFields,
+            ...feedbackLoopFields,
+            ...replaySafetyFields,
         });
     }
     return entries;
 }
 function normalizeToEdges(entries) {
-    return entries.map((entry, index) => ({
-        id: entry.id,
-        needs: entry.needs ?? null,
-        stageIndex: index,
-        ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
-        ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
-        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
-    }));
+    return entries.map((entry, index) => {
+        const needsEdges = toNeedEdges(entry.needs);
+        return {
+            id: entry.id,
+            needs: needsEdges.length === 1 ? needsEdges[0].id : null,
+            needsEdges,
+            stageIndex: index,
+            ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
+            ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
+            ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
+            ...(entry.completion !== undefined ? { completion: entry.completion } : {}),
+            ...(entry.recovery !== undefined ? { recovery: entry.recovery } : {}),
+            ...(entry.feedback_loop !== undefined ? { feedback_loop: entry.feedback_loop } : {}),
+            ...(entry.replay_safe !== undefined ? { replay_safe: entry.replay_safe } : {}),
+        };
+    });
 }
 function detectDuplicateIds(edges, ctx) {
     const seen = new Set();
@@ -101,8 +169,10 @@ function detectDuplicateIds(edges, ctx) {
 function validateNeedsTargets(edges, ctx) {
     const declared = new Set(edges.map((edge) => edge.id));
     for (const edge of edges) {
-        if (edge.needs !== null && !declared.has(edge.needs)) {
-            throw new Error(formatError(ctx, `stage "${edge.id}" has unknown needs "${edge.needs}"`));
+        for (const parent of edge.needsEdges) {
+            if (!declared.has(parent.id)) {
+                throw new Error(formatError(ctx, `stage "${edge.id}" has unknown needs "${parent.id}"`));
+            }
         }
     }
 }
@@ -114,10 +184,10 @@ function detectCycle(edges, ctx) {
         children.set(edge.id, []);
     }
     for (const edge of edges) {
-        if (edge.needs === null)
-            continue;
-        indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
-        children.get(edge.needs)?.push(edge.id);
+        for (const parent of edge.needsEdges) {
+            indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
+            children.get(parent.id)?.push(edge.id);
+        }
     }
     const queue = [];
     for (const [id, degree] of indegree) {
@@ -140,19 +210,31 @@ function detectCycle(edges, ctx) {
     }
 }
 function computeAncestors(edges) {
-    const needsById = new Map(edges.map((edge) => [edge.id, edge.needs]));
+    const parentsById = new Map(edges.map((edge) => [edge.id, edge.needsEdges]));
     const ancestorsById = new Map();
     function ancestorsFor(id) {
         const cached = ancestorsById.get(id);
         if (cached)
             return cached;
-        const needs = needsById.get(id) ?? null;
-        if (needs === null) {
+        const parents = parentsById.get(id) ?? [];
+        if (parents.length === 0) {
             ancestorsById.set(id, []);
             return [];
         }
-        const parentAncestors = ancestorsFor(needs);
-        const ancestors = [...parentAncestors, needs];
+        const seen = new Set();
+        const ancestors = [];
+        for (const parent of parents) {
+            for (const ancestor of ancestorsFor(parent.id)) {
+                if (seen.has(ancestor))
+                    continue;
+                seen.add(ancestor);
+                ancestors.push(ancestor);
+            }
+            if (!seen.has(parent.id)) {
+                seen.add(parent.id);
+                ancestors.push(parent.id);
+            }
+        }
         ancestorsById.set(id, ancestors);
         return ancestors;
     }
@@ -170,16 +252,16 @@ function topologicalSort(edges) {
         children.set(edge.id, []);
     }
     for (const edge of edges) {
-        if (edge.needs === null)
-            continue;
-        indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
-        children.get(edge.needs)?.push(edge.id);
+        for (const parent of edge.needsEdges) {
+            indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
+            children.get(parent.id)?.push(edge.id);
+        }
     }
     for (const [, childIds] of children) {
         childIds.sort((a, b) => (byId.get(a)?.stageIndex ?? 0) - (byId.get(b)?.stageIndex ?? 0));
     }
     const roots = edges
-        .filter((edge) => edge.needs === null)
+        .filter((edge) => edge.needsEdges.length === 0)
         .sort((a, b) => a.stageIndex - b.stageIndex)
         .map((edge) => edge.id);
     const sorted = [];
@@ -206,8 +288,8 @@ function buildResolvedPipelineDag(edges) {
         childrenOf[edge.id] = [];
     }
     for (const edge of edges) {
-        if (edge.needs !== null) {
-            childrenOf[edge.needs].push(edge.id);
+        for (const parent of edge.needsEdges) {
+            childrenOf[parent.id].push(edge.id);
         }
     }
     for (const id of Object.keys(childrenOf)) {
@@ -215,12 +297,13 @@ function buildResolvedPipelineDag(edges) {
             (edges.find((edge) => edge.id === b)?.stageIndex ?? 0));
     }
     const roots = edges
-        .filter((edge) => edge.needs === null)
+        .filter((edge) => edge.needsEdges.length === 0)
         .sort((a, b) => a.stageIndex - b.stageIndex)
         .map((edge) => edge.id);
     const nodes = sortedEdges.map((edge) => ({
         id: edge.id,
         needs: edge.needs,
+        needsEdges: edge.needsEdges,
         ancestors: ancestorsById.get(edge.id) ?? [],
         stageIndex: edge.stageIndex,
         ...(edge.fork !== undefined
@@ -229,6 +312,10 @@ function buildResolvedPipelineDag(edges) {
         ...(edge.clonable === true
             ? { clonable: true, clone_cap: edge.clone_cap ?? 5 }
             : {}),
+        ...(edge.completion !== undefined ? { completion: edge.completion } : {}),
+        ...(edge.recovery !== undefined ? { recovery: edge.recovery } : {}),
+        ...(edge.feedback_loop !== undefined ? { feedback_loop: edge.feedback_loop } : {}),
+        ...(edge.replay_safe !== undefined ? { replay_safe: edge.replay_safe } : {}),
     }));
     return { nodes, roots, childrenOf };
 }
@@ -259,6 +346,34 @@ function validateClonableFields(edges, dag, ctx) {
         }
     }
 }
+function validateFeedbackLoopFields(dag, ctx) {
+    const byId = new Map(dag.nodes.map((node) => [node.id, node]));
+    for (const source of dag.nodes) {
+        const policy = source.feedback_loop;
+        if (!policy)
+            continue;
+        if (source.clonable === true) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop source cannot be clonable`));
+        }
+        const targetId = policy.target;
+        const target = byId.get(targetId);
+        if (!target) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" is not declared`));
+        }
+        if (!source.ancestors.includes(targetId)) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" must be an earlier ancestor`));
+        }
+        if (target.clonable === true) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" cannot be clonable`));
+        }
+        const targetIndex = source.ancestors.indexOf(targetId);
+        const route = [...source.ancestors.slice(targetIndex), source.id];
+        const unsafeStage = route.find((stageId) => byId.get(stageId)?.replay_safe === false);
+        if (unsafeStage !== undefined) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" replays replay_safe: false stage "${unsafeStage}"`));
+        }
+    }
+}
 export function resolvePipelineDagFromRefs(refs, ctx) {
     const edges = normalizeToEdges(refs);
     detectDuplicateIds(edges, ctx);
@@ -271,6 +386,7 @@ export function resolvePipelineDagFromRefs(refs, ctx) {
     const dag = buildResolvedPipelineDag(edges);
     validateForkFields(edges, dag, ctx);
     validateClonableFields(edges, dag, ctx);
+    validateFeedbackLoopFields(dag, ctx);
     return { stages, dag };
 }
 export function resolvePipelineDag(rawStages, ctx) {
@@ -293,12 +409,40 @@ export function areResolvedDagsEquivalent(a, b) {
         const nodeB = byIdB.get(id);
         if (nodeA.needs !== nodeB.needs)
             return false;
+        const edgesA = predecessorEdges(nodeA);
+        const edgesB = predecessorEdges(nodeB);
+        if (edgesA.length !== edgesB.length)
+            return false;
+        for (let i = 0; i < edgesA.length; i++) {
+            if (edgesA[i].id !== edgesB[i].id)
+                return false;
+            if (edgesA[i].on.length !== edgesB[i].on.length)
+                return false;
+            for (let j = 0; j < edgesA[i].on.length; j++) {
+                if (edgesA[i].on[j] !== edgesB[i].on[j])
+                    return false;
+            }
+        }
         if (nodeA.ancestors.length !== nodeB.ancestors.length)
             return false;
         for (let i = 0; i < nodeA.ancestors.length; i++) {
             if (nodeA.ancestors[i] !== nodeB.ancestors[i])
                 return false;
         }
+        if ((nodeA.replay_safe ?? true) !== (nodeB.replay_safe ?? true))
+            return false;
+        if (nodeA.feedback_loop?.max_replays !== nodeB.feedback_loop?.max_replays) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.on_max_replays !==
+            nodeB.feedback_loop?.on_max_replays) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.replay_session !== nodeB.feedback_loop?.replay_session) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.target !== nodeB.feedback_loop?.target)
+            return false;
     }
     return true;
 }
@@ -321,9 +465,8 @@ export function extractPipelineStageIds(rawStages) {
         if (typeof entry.id !== "string" || !entry.id)
             return null;
         if (entry.needs !== undefined) {
-            if (Array.isArray(entry.needs))
-                return null;
-            if (typeof entry.needs !== "string" || !entry.needs)
+            const parsedNeeds = parsePipelineNeeds(entry.needs, entry.id);
+            if (!parsedNeeds.ok)
                 return null;
         }
         stageIds.push(entry.id);

package/dist/config/resolveStageMcpServers.d.ts

@@ -0,0 +1,35 @@
+export type StageMcpErrorCode = "missing_catalog" | "unknown_server" | "reserved_name" | "unresolved_var" | "invalid_config" | "connect_failed";
+export declare class StageMcpError extends Error {
+    readonly code: StageMcpErrorCode;
+    constructor(message: string, code: StageMcpErrorCode);
+}
+export type ResolvedMcpServerConfig = Record<string, unknown>;
+export type ResolvedMcpServers = Record<string, ResolvedMcpServerConfig>;
+export declare const MCP_CATALOG_FILENAME = ".mcp.json";
+export declare const STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV = "STAGEFLOW_STAGE_ARTIFACTS_DIR";
+export declare function stampStagePromptArtifactsDir(prompt: string, artifactsDir: string): string;
+export type McpCatalogServers = Record<string, Record<string, unknown>>;
+export type InspectedMcpCatalog = {
+    path: string;
+    servers: McpCatalogServers;
+};
+export declare function mcpCatalogPath(projectRoot: string): string;
+export declare function parseMcpCatalog(raw: string, catalogPath?: string): McpCatalogServers;
+export declare function loadMcpCatalog(projectRoot: string): Promise<InspectedMcpCatalog>;
+export type ProjectMcpCatalogTransport = "stdio" | "http";
+export type ProjectMcpCatalogEntry = {
+    name: string;
+    transport: ProjectMcpCatalogTransport;
+};
+export type ProjectMcpCatalogListStatus = "ok" | "missing_catalog" | "invalid_config";
+export type ProjectMcpCatalogList = {
+    status: ProjectMcpCatalogListStatus;
+    servers: ProjectMcpCatalogEntry[];
+};
+export declare function listProjectMcpCatalog(projectRoot: string): Promise<ProjectMcpCatalogList>;
+export declare function assertMcpAllowlistKnown(servers: McpCatalogServers, allowlist: readonly string[]): void;
+export declare function resolveStageMcpServers(options: {
+    projectRoot: string;
+    allowlist?: readonly string[];
+    env: NodeJS.ProcessEnv;
+}): Promise<ResolvedMcpServers>;

package/dist/config/resolveStageMcpServers.js

@@ -0,0 +1,207 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
+export class StageMcpError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "StageMcpError";
+        this.code = code;
+    }
+}
+export const MCP_CATALOG_FILENAME = ".mcp.json";
+export const STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV = "STAGEFLOW_STAGE_ARTIFACTS_DIR";
+const STAGEFLOW_STAGE_ARTIFACTS_DIR_TOKEN = `\${${STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV}}`;
+export function stampStagePromptArtifactsDir(prompt, artifactsDir) {
+    return prompt.replaceAll(STAGEFLOW_STAGE_ARTIFACTS_DIR_TOKEN, artifactsDir);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function mcpCatalogPath(projectRoot) {
+    return path.join(projectRoot, MCP_CATALOG_FILENAME);
+}
+export function parseMcpCatalog(raw, catalogPath = MCP_CATALOG_FILENAME) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new StageMcpError(`MCP catalog "${catalogPath}" is not valid JSON`, "invalid_config");
+    }
+    if (!isPlainObject(parsed)) {
+        throw new StageMcpError(`MCP catalog "${catalogPath}" must be a JSON object`, "invalid_config");
+    }
+    if (!Object.hasOwn(parsed, "mcpServers")) {
+        throw new StageMcpError(`MCP catalog "${catalogPath}" is missing mcpServers`, "invalid_config");
+    }
+    const mcpServers = parsed.mcpServers;
+    if (!isPlainObject(mcpServers)) {
+        throw new StageMcpError(`MCP catalog "${catalogPath}" mcpServers must be an object`, "invalid_config");
+    }
+    const servers = {};
+    for (const [name, entry] of Object.entries(mcpServers)) {
+        if (name === STAGEFLOW_MCP_SERVER_NAME) {
+            throw new StageMcpError(`MCP catalog must not include reserved name "${STAGEFLOW_MCP_SERVER_NAME}"`, "reserved_name");
+        }
+        if (!isPlainObject(entry)) {
+            throw new StageMcpError(`MCP catalog server "${name}" must be an object`, "invalid_config");
+        }
+        servers[name] = entry;
+    }
+    return servers;
+}
+export async function loadMcpCatalog(projectRoot) {
+    const catalogPath = mcpCatalogPath(projectRoot);
+    let raw;
+    try {
+        raw = await readFile(catalogPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "missing_catalog");
+        }
+        throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" could not be read`, "invalid_config");
+    }
+    return { path: catalogPath, servers: parseMcpCatalog(raw, catalogPath) };
+}
+function coarseMcpTransport(entry) {
+    if (Object.hasOwn(entry, "command")) {
+        return "stdio";
+    }
+    if (Object.hasOwn(entry, "url")) {
+        return "http";
+    }
+    return undefined;
+}
+export async function listProjectMcpCatalog(projectRoot) {
+    try {
+        const catalog = await loadMcpCatalog(projectRoot);
+        const servers = [];
+        for (const [name, entry] of Object.entries(catalog.servers)) {
+            const transport = coarseMcpTransport(entry);
+            if (transport === undefined) {
+                return { status: "invalid_config", servers: [] };
+            }
+            servers.push({ name, transport });
+        }
+        return { status: "ok", servers };
+    }
+    catch (err) {
+        if (err instanceof StageMcpError) {
+            if (err.code === "missing_catalog") {
+                return { status: "missing_catalog", servers: [] };
+            }
+            return { status: "invalid_config", servers: [] };
+        }
+        throw err;
+    }
+}
+export function assertMcpAllowlistKnown(servers, allowlist) {
+    for (const name of allowlist) {
+        if (!Object.hasOwn(servers, name)) {
+            throw new StageMcpError(`Unknown MCP server "${name}"`, "unknown_server");
+        }
+    }
+}
+const INTERPOLATION_TOKEN = /\$\{([^}]*)\}/g;
+const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_VAR_WITH_DEFAULT = /^([A-Za-z_][A-Za-z0-9_]*):-(.*)$/;
+function interpolateString(value, env, serverName) {
+    return value.replace(INTERPOLATION_TOKEN, (_match, inner) => {
+        const withDefault = ENV_VAR_WITH_DEFAULT.exec(inner);
+        if (withDefault) {
+            const found = env[withDefault[1]];
+            return found !== undefined ? found : withDefault[2];
+        }
+        if (ENV_VAR_NAME.test(inner)) {
+            const found = env[inner];
+            if (found !== undefined) {
+                return found;
+            }
+            throw new StageMcpError(`Unresolved MCP catalog variable "${inner}"`, "unresolved_var");
+        }
+        throw new StageMcpError(`MCP catalog server "${serverName}" has an invalid interpolation form`, "invalid_config");
+    });
+}
+function interpolateField(key, value, env, serverName) {
+    if ((key === "command" || key === "url" || key === "cwd") && typeof value === "string") {
+        return interpolateString(value, env, serverName);
+    }
+    if (key === "args" && Array.isArray(value)) {
+        return value.map((item) => typeof item === "string" ? interpolateString(item, env, serverName) : item);
+    }
+    if ((key === "env" || key === "headers") && isPlainObject(value)) {
+        const copied = {};
+        for (const [field, fieldValue] of Object.entries(value)) {
+            copied[field] =
+                typeof fieldValue === "string"
+                    ? interpolateString(fieldValue, env, serverName)
+                    : fieldValue;
+        }
+        return copied;
+    }
+    return value;
+}
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function isRelativeFsPath(value) {
+    if (value.length === 0 || path.isAbsolute(value) || value.startsWith("-") || value.startsWith("@")) {
+        return false;
+    }
+    return hasPathSeparator(value) || value.startsWith(".");
+}
+function isInsideProjectRoot(projectRoot, candidate) {
+    const root = path.resolve(projectRoot);
+    const resolved = path.resolve(candidate);
+    const rel = path.relative(root, resolved);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function stampSpawnRoot(resolved, projectRoot, serverName) {
+    const command = resolved.command;
+    if (typeof command === "string" && hasPathSeparator(command) && !path.isAbsolute(command)) {
+        resolved.command = path.resolve(projectRoot, command);
+    }
+    if (Array.isArray(resolved.args)) {
+        resolved.args = resolved.args.map((item) => typeof item === "string" && isRelativeFsPath(item)
+            ? path.resolve(projectRoot, item)
+            : item);
+    }
+    const catalogCwd = resolved.cwd;
+    if (catalogCwd !== undefined) {
+        if (typeof catalogCwd !== "string" || catalogCwd.length === 0 || !path.isAbsolute(catalogCwd)) {
+            throw new StageMcpError(`MCP catalog server "${serverName}" cwd must be an absolute path inside the project root`, "invalid_config");
+        }
+        const canonical = path.resolve(catalogCwd);
+        if (!isInsideProjectRoot(projectRoot, canonical)) {
+            throw new StageMcpError(`MCP catalog server "${serverName}" cwd is outside the project root`, "invalid_config");
+        }
+        resolved.cwd = canonical;
+    }
+    else if (typeof command === "string") {
+        resolved.cwd = path.resolve(projectRoot);
+    }
+    return resolved;
+}
+function interpolateServer(entry, env, serverName, projectRoot) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(entry)) {
+        resolved[key] = interpolateField(key, value, env, serverName);
+    }
+    return stampSpawnRoot(resolved, projectRoot, serverName);
+}
+export async function resolveStageMcpServers(options) {
+    const allowlist = options.allowlist ?? [];
+    if (allowlist.length === 0) {
+        return {};
+    }
+    const catalog = await loadMcpCatalog(options.projectRoot);
+    assertMcpAllowlistKnown(catalog.servers, allowlist);
+    const resolved = {};
+    for (const name of allowlist) {
+        resolved[name] = interpolateServer(catalog.servers[name], options.env, name, options.projectRoot);
+    }
+    return resolved;
+}

package/dist/config/validateCatalog.d.ts

@@ -2,7 +2,7 @@ import type { LoadedPipeline } from "../types/pipeline.js";
 import type { LoadIssue } from "./loadOutcome.js";
 export type ValidationSeverity = "error" | "warning";
 export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_gate_kinds" | "stage.invalid_skill" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.invalid_completion" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_agent" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;