stageflow 0.12.0 → 0.15.0

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.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_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";
+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" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "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.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;
@@ -15,6 +15,7 @@ export type ValidationFinding = {
 export type ValidationScope = "full" | "pipeline" | "task";
 export type ValidateCatalogOptions = {
     cwd?: string;
+    projectRoot?: string;
     scope: ValidationScope;
     pipeline?: string;
     task?: string;
@@ -36,6 +37,7 @@ export declare function findingsFromLoadIssues(cwd: string, absPath: string, iss
 export declare function findingStageIdFilenameMismatch(cwd: string, absPath: string, fileStem: string, declaredId: string): ValidationFinding;
 export type ValidatePipelineOptions = {
     cwd?: string;
+    projectRoot?: string;
     validateStages?: boolean;
     strict?: boolean;
 };
@@ -43,12 +45,14 @@ export declare function validatePipeline(nameOrPath: string, options?: ValidateP
 export type LoadPipelineValidatedResult = {
     ok: true;
     loaded: LoadedPipeline;
+    findings: ValidationFinding[];
 } | {
     ok: false;
     findings: ValidationFinding[];
 };
 export declare function loadPipelineValidated(nameOrPath: string, options?: {
     cwd?: string;
+    projectRoot?: string;
     validateStages?: boolean;
 }): Promise<LoadPipelineValidatedResult>;
 export declare function validateCatalog(options: ValidateCatalogOptions): Promise<ValidationResult>;

package/dist/config/validateCatalog.js

@@ -6,6 +6,7 @@ import { readYamlObject } from "./readYamlObject.js";
 import { resolveCatalogContext } from "./resolveCatalogContext.js";
 import { getCatalogScanPaths } from "./browseCatalog.js";
 import { manifestPathForProject } from "./loadStageflowManifest.js";
+import { MCP_CATALOG_FILENAME, StageMcpError, assertMcpAllowlistKnown, loadMcpCatalog, mcpCatalogPath, } from "./resolveStageMcpServers.js";
 export function relPath(cwd, absPath) {
     return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
@@ -109,6 +110,18 @@ function findingCatalog(cwd, absPath, message, code, severity) {
 export function findingsFromLoadIssues(cwd, absPath, issues) {
     return issues.flatMap((issue) => {
         if (issue.category === "pipeline") {
+            if (issue.code === "pipeline.model_applies") {
+                return [
+                    baseFinding({
+                        cwd,
+                        absPath,
+                        message: issue.message,
+                        code: issue.code,
+                        category: "pipeline",
+                        pipelineId: issue.pipelineId,
+                    }, "warning"),
+                ];
+            }
             return [
                 findingPipelineError(cwd, absPath, issue.message, issue.code, issue.pipelineId),
             ];
@@ -125,7 +138,9 @@ export function findingsFromLoadIssues(cwd, absPath, issues) {
         }
         if (issue.category === "catalog") {
             const code = issue.code;
-            const severity = code === "catalog.manifest_missing" || code === "catalog.empty_catalog"
+            const severity = code === "catalog.manifest_missing" ||
+                code === "catalog.empty_catalog" ||
+                code === "catalog.legacy_yaml"
                 ? "warning"
                 : "error";
             return [findingCatalog(cwd, absPath, issue.message, code, severity)];
@@ -171,8 +186,58 @@ async function validateStageFile(cwd, stagePath) {
     }
     return findings;
 }
+function collectMcpAllowlistNames(loaded) {
+    const names = new Set();
+    for (const stage of loaded.stages) {
+        for (const name of stage.mcp ?? []) {
+            names.add(name);
+        }
+    }
+    return [...names];
+}
+async function findingsForStageMcpCatalog(cwd, loaded) {
+    const allowlist = collectMcpAllowlistNames(loaded);
+    const ctx = await resolveCatalogContext(cwd);
+    const projectRoot = ctx.projectRoot;
+    const catalogAbsPath = projectRoot
+        ? mcpCatalogPath(projectRoot)
+        : path.resolve(cwd, MCP_CATALOG_FILENAME);
+    if (!projectRoot) {
+        if (allowlist.length === 0)
+            return [];
+        return [
+            findingCatalog(cwd, catalogAbsPath, `MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "catalog.invalid_mcp", "error"),
+        ];
+    }
+    let catalog;
+    try {
+        catalog = await loadMcpCatalog(projectRoot);
+    }
+    catch (err) {
+        if (!(err instanceof StageMcpError))
+            throw err;
+        if (err.code === "missing_catalog" && allowlist.length === 0)
+            return [];
+        return [
+            findingCatalog(cwd, catalogAbsPath, err.message, "catalog.invalid_mcp", "error"),
+        ];
+    }
+    try {
+        assertMcpAllowlistKnown(catalog.servers, allowlist);
+    }
+    catch (err) {
+        if (err instanceof StageMcpError) {
+            return [
+                findingCatalog(cwd, catalogAbsPath, err.message, "catalog.invalid_mcp", "error"),
+            ];
+        }
+        throw err;
+    }
+    return [];
+}
 async function runPipelineValidation(nameOrPath, options) {
     const { cwd, validateStages } = options;
+    const projectRoot = options.projectRoot ?? cwd;
     let pipelinePath;
     try {
         pipelinePath = await resolvePipelinePath(nameOrPath, cwd);
@@ -190,16 +255,21 @@ async function runPipelineValidation(nameOrPath, options) {
             ]),
         };
     }
-    const outcome = await loadPipelineOutcome(pipelinePath, { cwd });
+    const outcome = await loadPipelineOutcome(pipelinePath, { cwd, projectRoot });
     const findings = [];
     if (!outcome.ok) {
         findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));
         return { ok: false, findings };
     }
+    if (outcome.issues) {
+        findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));
+    }
+    findings.push(...(await findingsForStageMcpCatalog(cwd, outcome.value)));
     if (validateStages && outcome.value.stageSources) {
         for (const source of Object.values(outcome.value.stageSources)) {
             if (source.kind === "file") {
-                findings.push(...(await validateStageFile(cwd, source.path)));
+                const extra = await validateStageFile(cwd, source.path);
+                findings.push(...extra.filter((finding) => finding.code !== "stage.unresolved_schema_ref"));
             }
         }
     }
@@ -210,17 +280,27 @@ async function runPipelineValidation(nameOrPath, options) {
 }
 export async function validatePipeline(nameOrPath, options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
     const validateStages = options.validateStages ?? true;
     const strict = options.strict ?? false;
-    const core = await runPipelineValidation(nameOrPath, { cwd, validateStages });
+    const core = await runPipelineValidation(nameOrPath, {
+        cwd,
+        projectRoot,
+        validateStages,
+    });
     return buildValidationResult("pipeline", core.findings, strict);
 }
 export async function loadPipelineValidated(nameOrPath, options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
     const validateStages = options.validateStages ?? true;
-    const core = await runPipelineValidation(nameOrPath, { cwd, validateStages });
+    const core = await runPipelineValidation(nameOrPath, {
+        cwd,
+        projectRoot,
+        validateStages,
+    });
     if (core.ok) {
-        return { ok: true, loaded: core.loaded };
+        return { ok: true, loaded: core.loaded, findings: core.findings };
     }
     return { ok: false, findings: core.findings };
 }
@@ -345,6 +425,7 @@ export async function validateCatalog(options) {
     if (options.scope === "pipeline") {
         return validatePipeline(options.pipeline, {
             cwd,
+            projectRoot: options.projectRoot ?? cwd,
             validateStages: true,
             strict,
         });

package/dist/config/validateCompletionContract.js

@@ -30,6 +30,11 @@ function isRequiredStringArrayField(schema, field) {
         items.type === "string");
 }
 export function validateCompletionContractForStage(stage, completion) {
+    for (const check of stage.pre_emit_checks ?? []) {
+        if (check.type === "gate" && !stage.gate_kinds?.includes(check.kind)) {
+            return failure(stage.id, `gate check "${check.id}" requires gate_kinds to include "${check.kind}"`);
+        }
+    }
     if (!completion)
         return loadSuccess(undefined);
     for (const check of completion.checks) {

package/dist/config/yamlDialect.d.ts

@@ -0,0 +1,29 @@
+import type { CompletionContract, RecoveryPolicy } from "../types/completion.js";
+import { type LoadIssue, type LoadOutcome } from "./loadOutcome.js";
+export { LEGACY_CONTRACT_KEYS, LEGACY_KEY_REPLACEMENTS, dialectWarningForDocument, formatLegacyReplacements, legacyYamlIssue, presentLegacyKeys, } from "./legacyYaml.js";
+/** Target authoring keys. New catalog contracts belong here, not on the IR field names. */
+export declare const TARGET_CONTRACT_KEYS: Set<string>;
+/** Target wiring on a stage *file* is forbidden (`on_verify_fail`). `completion`/`recovery` are IR/legacy keys. */
+export declare const STAGE_FILE_WIRING_KEYS: readonly ["needs", "on_verify_fail", "completion", "recovery", "fork", "clonable"];
+export type YamlDialect = "legacy" | "target" | "invalid" | "neutral";
+/** Target YAML compiled onto IR field names (see file comment). */
+export type CompiledTargetContract = {
+    payload_schema?: unknown;
+    clone_input_schema?: unknown;
+    pre_emit_raw?: unknown[];
+    completion?: CompletionContract;
+    recovery?: RecoveryPolicy;
+};
+export declare function dialectFromKeys(keys: Iterable<string>): YamlDialect;
+export declare function collectDocumentKeys(raw: Record<string, unknown>): Set<string>;
+export declare function classifyYamlDocument(raw: Record<string, unknown>): YamlDialect;
+export declare function mixedDialectIssue(message?: string): LoadIssue;
+/** Compile target YAML (`io` / `verify` / `on_verify_fail`) onto IR fields. */
+export declare function compileTargetContract(raw: Record<string, unknown>, ctx: {
+    stageId: string;
+    label: string;
+    category: "pipeline" | "stage";
+    deferSchemaRefs?: boolean;
+}): LoadOutcome<CompiledTargetContract>;
+/** Strip target YAML keys and stamp IR `payload_schema` / `clone_input_schema` / `pre_emit_checks`. */
+export declare function applyCompiledBody(raw: Record<string, unknown>, compiled: CompiledTargetContract): Record<string, unknown>;