stageflow 0.1.0 → 0.3.0

package/dist/config/validateCatalog.d.ts

@@ -1,7 +1,8 @@
+import type { LoadedPipeline } from "../types/pipeline.js";
 import type { LoadIssue } from "./loadOutcome.js";
 export type ValidationSeverity = "error" | "warning";
-export type ValidationCategory = "pipeline" | "stage" | "catalog";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_gate_kinds" | "stage.invalid_skill" | "stage.load_error" | "stage.id_filename_mismatch" | "catalog.duplicate_pipeline_id" | "catalog.orphan_stage";
+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 ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;
@@ -11,12 +12,12 @@ export type ValidationFinding = {
     pipelineId?: string;
     stageId?: string;
 };
-export type ValidationScope = "full" | "pipeline";
+export type ValidationScope = "full" | "pipeline" | "task";
 export type ValidateCatalogOptions = {
     cwd?: string;
-    stagesDir?: string;
     scope: ValidationScope;
     pipeline?: string;
+    task?: string;
     strict?: boolean;
 };
 export type ValidationResult = {
@@ -33,4 +34,21 @@ export declare function effectiveSeverity(finding: ValidationFinding, strict: bo
 export declare function buildValidationResult(scope: ValidationScope, findings: ValidationFinding[], strict: boolean): ValidationResult;
 export declare function findingsFromLoadIssues(cwd: string, absPath: string, issues: LoadIssue[]): ValidationFinding[];
 export declare function findingStageIdFilenameMismatch(cwd: string, absPath: string, fileStem: string, declaredId: string): ValidationFinding;
+export type ValidatePipelineOptions = {
+    cwd?: string;
+    validateStages?: boolean;
+    strict?: boolean;
+};
+export declare function validatePipeline(nameOrPath: string, options?: ValidatePipelineOptions): Promise<ValidationResult>;
+export type LoadPipelineValidatedResult = {
+    ok: true;
+    loaded: LoadedPipeline;
+} | {
+    ok: false;
+    findings: ValidationFinding[];
+};
+export declare function loadPipelineValidated(nameOrPath: string, options?: {
+    cwd?: string;
+    validateStages?: boolean;
+}): Promise<LoadPipelineValidatedResult>;
 export declare function validateCatalog(options: ValidateCatalogOptions): Promise<ValidationResult>;

package/dist/config/validateCatalog.js

@@ -1,12 +1,18 @@
-import { readdir } from "node:fs/promises";
 import path from "node:path";
-import { loadPipelineOutcome, loadPipelineValidated } from "./loadPipeline.js";
+import { loadPipelineOutcome, resolvePipelinePath } from "./loadPipeline.js";
 import { loadStageOutcome } from "./loadStage.js";
+import { loadTaskOutcome } from "./loadTask.js";
 import { readYamlObject } from "./readYamlObject.js";
-import { extractPipelineStageIds } from "./resolvePipelineDag.js";
+import { resolveCatalogContext } from "./resolveCatalogContext.js";
+import { getCatalogScanPaths } from "./browseCatalog.js";
+import { manifestPathForProject } from "./loadStageflowManifest.js";
 export function relPath(cwd, absPath) {
-    return path.relative(cwd, absPath);
+    return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
+const STRICT_CATALOG_WARNINGS = new Set([
+    "catalog.manifest_missing",
+    "catalog.empty_catalog",
+]);
 const SEVERITY_RANK = {
     error: 0,
     warning: 1,
@@ -28,7 +34,7 @@ function sortFindings(findings) {
 export function effectiveSeverity(finding, strict) {
     if (strict &&
         finding.severity === "warning" &&
-        finding.code === "catalog.orphan_stage") {
+        STRICT_CATALOG_WARNINGS.has(finding.code)) {
         return "error";
     }
     return finding.severity;
@@ -82,6 +88,24 @@ function findingStageError(cwd, absPath, message, code, stageId) {
         stageId,
     }, "error");
 }
+function findingTaskError(cwd, absPath, message, code) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message,
+        code,
+        category: "task",
+    }, "error");
+}
+function findingCatalog(cwd, absPath, message, code, severity) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message,
+        code,
+        category: "catalog",
+    }, severity);
+}
 export function findingsFromLoadIssues(cwd, absPath, issues) {
     return issues.flatMap((issue) => {
         if (issue.category === "pipeline") {
@@ -94,6 +118,18 @@ export function findingsFromLoadIssues(cwd, absPath, issues) {
                 findingStageError(cwd, absPath, issue.message, issue.code, issue.stageId),
             ];
         }
+        if (issue.category === "task") {
+            return [
+                findingTaskError(cwd, absPath, issue.message, issue.code),
+            ];
+        }
+        if (issue.category === "catalog") {
+            const code = issue.code;
+            const severity = code === "catalog.manifest_missing" || code === "catalog.empty_catalog"
+                ? "warning"
+                : "error";
+            return [findingCatalog(cwd, absPath, issue.message, code, severity)];
+        }
         return [];
     });
 }
@@ -107,40 +143,6 @@ export function findingStageIdFilenameMismatch(cwd, absPath, fileStem, declaredI
         stageId: declaredId,
     }, "error");
 }
-function findingCatalogDuplicatePipelineId(cwd, absPath, pipelineId, conflictingPaths) {
-    const relConflicts = conflictingPaths.map((p) => relPath(cwd, p));
-    return baseFinding({
-        cwd,
-        absPath,
-        message: `Duplicate pipeline id "${pipelineId}" declared in: ${relConflicts.join(", ")}`,
-        code: "catalog.duplicate_pipeline_id",
-        category: "catalog",
-        pipelineId,
-    }, "error");
-}
-function findingCatalogOrphanStage(cwd, absPath, stageId) {
-    return baseFinding({
-        cwd,
-        absPath,
-        message: `Stage "${stageId}" is not referenced by any pipeline`,
-        code: "catalog.orphan_stage",
-        category: "catalog",
-        stageId,
-    }, "warning");
-}
-async function listYamlFiles(dir) {
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    return entries
-        .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
-        .map((entry) => path.join(dir, entry.name))
-        .sort((a, b) => a.localeCompare(b));
-}
 async function checkStageIdFilename(cwd, stagePath) {
     const fileStem = path.basename(stagePath, ".yaml");
     try {
@@ -169,52 +171,79 @@ async function validateStageFile(cwd, stagePath) {
     }
     return findings;
 }
-async function validatePipelineFile(pipelinePath, options) {
-    const { cwd, stagesDir, validateStages } = options;
-    const findings = [];
-    const referencedStageIds = new Set();
-    let pipelineId;
+async function runPipelineValidation(nameOrPath, options) {
+    const { cwd, validateStages } = options;
+    let pipelinePath;
     try {
-        const raw = await readYamlObject(pipelinePath);
-        if (typeof raw?.id === "string") {
-            pipelineId = raw.id;
-            if (Array.isArray(raw.stages)) {
-                const stageIds = extractPipelineStageIds(raw.stages);
-                if (stageIds) {
-                    for (const stageId of stageIds) {
-                        referencedStageIds.add(stageId);
-                    }
-                }
-            }
-        }
+        pipelinePath = await resolvePipelinePath(nameOrPath, cwd);
     }
-    catch {
-        // loadPipelineOutcome will report read errors
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            findings: findingsFromLoadIssues(cwd, path.resolve(cwd, nameOrPath), [
+                {
+                    code: "pipeline.load_error",
+                    message,
+                    category: "pipeline",
+                },
+            ]),
+        };
     }
-    const outcome = await loadPipelineOutcome(pipelinePath, { cwd, stagesDir });
+    const outcome = await loadPipelineOutcome(pipelinePath, { cwd });
+    const findings = [];
     if (!outcome.ok) {
         findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));
-        if (validateStages) {
-            for (const stageId of referencedStageIds) {
-                const stagePath = path.join(stagesDir, `${stageId}.yaml`);
-                findings.push(...(await validateStageFile(cwd, stagePath)));
+        return { ok: false, findings };
+    }
+    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)));
             }
         }
-        return { findings, pipelineId, referencedStageIds };
     }
-    for (const stageId of outcome.value.pipeline.stages) {
-        referencedStageIds.add(stageId);
-        if (validateStages) {
-            const stagePath = path.join(stagesDir, `${stageId}.yaml`);
-            findings.push(...(await validateStageFile(cwd, stagePath)));
-        }
+    if (findings.some((finding) => finding.severity === "error")) {
+        return { ok: false, findings };
     }
-    return { findings, pipelineId: outcome.value.pipeline.id, referencedStageIds };
+    return { ok: true, loaded: outcome.value, findings };
+}
+export async function validatePipeline(nameOrPath, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const validateStages = options.validateStages ?? true;
+    const strict = options.strict ?? false;
+    const core = await runPipelineValidation(nameOrPath, { cwd, validateStages });
+    return buildValidationResult("pipeline", core.findings, strict);
 }
-async function collectPipelineIds(pipelinesDir) {
-    const files = await listYamlFiles(pipelinesDir);
+export async function loadPipelineValidated(nameOrPath, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const validateStages = options.validateStages ?? true;
+    const core = await runPipelineValidation(nameOrPath, { cwd, validateStages });
+    if (core.ok) {
+        return { ok: true, loaded: core.loaded };
+    }
+    return { ok: false, findings: core.findings };
+}
+function findingCatalogDuplicatePipelineId(cwd, absPath, pipelineId, conflictingPaths) {
+    const relConflicts = conflictingPaths.map((p) => relPath(cwd, p));
+    return baseFinding({
+        cwd,
+        absPath,
+        message: `Duplicate pipeline id "${pipelineId}" declared in: ${relConflicts.join(", ")}`,
+        code: "catalog.duplicate_pipeline_id",
+        category: "catalog",
+        pipelineId,
+    }, "error");
+}
+function findingManifestMissing(cwd, projectRoot) {
+    return findingCatalog(cwd, manifestPathForProject(projectRoot), "No stageflow.yaml manifest found at project root", "catalog.manifest_missing", "warning");
+}
+function findingEmptyCatalog(cwd, manifestPath, kind) {
+    return findingCatalog(cwd, manifestPath, `Manifest catalog.${kind} is empty`, "catalog.empty_catalog", "warning");
+}
+async function collectPipelineIdsFromPaths(pipelinePaths) {
     const idToPaths = new Map();
-    for (const filePath of files) {
+    for (const filePath of pipelinePaths) {
         try {
             const raw = await readYamlObject(filePath);
             if (typeof raw?.id !== "string")
@@ -240,83 +269,91 @@ function findingsForDuplicatePipelineIds(cwd, idToPaths) {
     }
     return findings;
 }
-async function collectReferencedStageIds(pipelinesDir) {
-    const files = await listYamlFiles(pipelinesDir);
-    const referenced = new Set();
-    for (const filePath of files) {
-        try {
-            const raw = await readYamlObject(filePath);
-            if (typeof raw?.id !== "string" || !Array.isArray(raw.stages))
-                continue;
-            const stageIds = extractPipelineStageIds(raw.stages);
-            if (!stageIds)
-                continue;
-            for (const stageId of stageIds) {
-                referenced.add(stageId);
-            }
+async function validateManifestAll(invocationCwd) {
+    const ctx = await resolveCatalogContext(invocationCwd);
+    const findings = [];
+    if (ctx.manifestStatus === "not_git" || ctx.manifestStatus === "missing") {
+        if (ctx.projectRoot) {
+            findings.push(findingManifestMissing(invocationCwd, ctx.projectRoot));
         }
-        catch {
-            // skip unreadable
+        else {
+            findings.push(findingCatalog(invocationCwd, path.resolve(invocationCwd), "Not inside a git repository; no catalog manifest", "catalog.manifest_missing", "warning"));
         }
+        return findings;
     }
-    return referenced;
-}
-async function findingsForOrphanStages(cwd, stagesDir, referencedStageIds) {
-    const findings = [];
-    const stageFiles = await listYamlFiles(stagesDir);
-    for (const stagePath of stageFiles) {
-        const stageId = path.basename(stagePath, ".yaml");
-        if (referencedStageIds.has(stageId))
-            continue;
-        findings.push(findingCatalogOrphanStage(cwd, stagePath, stageId));
-        findings.push(...(await validateStageFile(cwd, stagePath)));
+    if (ctx.manifestStatus === "invalid") {
+        const manifestPath = ctx.projectRoot
+            ? manifestPathForProject(ctx.projectRoot)
+            : path.resolve(invocationCwd, "stageflow.yaml");
+        findings.push(...findingsFromLoadIssues(invocationCwd, manifestPath, ctx.issues));
+        return findings;
+    }
+    const { projectRoot, manifest } = ctx;
+    if (!projectRoot || !manifest) {
+        return findings;
+    }
+    if (manifest.manifest.catalog.pipelines.length === 0) {
+        findings.push(findingEmptyCatalog(invocationCwd, manifest.path, "pipelines"));
+    }
+    if (manifest.manifest.catalog.tasks.length === 0) {
+        findings.push(findingEmptyCatalog(invocationCwd, manifest.path, "tasks"));
+    }
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths) {
+        return findings;
+    }
+    const { pipelinePaths, taskPaths } = scanPaths;
+    for (const pipelinePath of pipelinePaths) {
+        const core = await runPipelineValidation(pipelinePath, {
+            cwd: projectRoot,
+            validateStages: true,
+        });
+        if (!core.ok) {
+            findings.push(...core.findings);
+        }
     }
+    for (const taskPath of taskPaths) {
+        const outcome = await loadTaskOutcome(taskPath);
+        if (!outcome.ok) {
+            findings.push(...findingsFromLoadIssues(projectRoot, taskPath, outcome.issues));
+        }
+    }
+    const idToPaths = await collectPipelineIdsFromPaths(pipelinePaths);
+    findings.push(...findingsForDuplicatePipelineIds(projectRoot, idToPaths));
     return findings;
 }
+async function validateSingleTask(invocationCwd, taskArg) {
+    const ctx = await resolveCatalogContext(invocationCwd);
+    const relCwd = ctx.projectRoot ?? invocationCwd;
+    const taskPath = path.resolve(invocationCwd, taskArg);
+    const outcome = await loadTaskOutcome(taskPath);
+    if (!outcome.ok) {
+        return findingsFromLoadIssues(relCwd, taskPath, outcome.issues);
+    }
+    return [];
+}
 export async function validateCatalog(options) {
     const cwd = options.cwd ?? process.cwd();
-    const stagesDir = options.stagesDir ?? path.join(cwd, "stages");
     const strict = options.strict ?? false;
-    const pipelinesDir = path.join(cwd, "pipelines");
     if (options.scope === "pipeline" && !options.pipeline) {
         throw new Error("validateCatalog: pipeline is required when scope is \"pipeline\"");
     }
+    if (options.scope === "task" && !options.task) {
+        throw new Error("validateCatalog: task is required when scope is \"task\"");
+    }
     const allFindings = [];
     if (options.scope === "pipeline") {
-        const result = await loadPipelineValidated(options.pipeline, {
+        return validatePipeline(options.pipeline, {
             cwd,
-            stagesDir,
             validateStages: true,
+            strict,
         });
-        if (!result.ok) {
-            allFindings.push(...result.findings);
-        }
+    }
+    else if (options.scope === "task") {
+        allFindings.push(...(await validateSingleTask(cwd, options.task)));
     }
     else {
-        const referencedStageIds = await collectReferencedStageIds(pipelinesDir);
-        const pipelineFiles = await listYamlFiles(pipelinesDir);
-        for (const pipelinePath of pipelineFiles) {
-            const result = await validatePipelineFile(pipelinePath, {
-                cwd,
-                stagesDir,
-                validateStages: false,
-            });
-            allFindings.push(...result.findings);
-            for (const stageId of result.referencedStageIds) {
-                referencedStageIds.add(stageId);
-            }
-        }
-        const validatedStages = new Set();
-        for (const stageId of referencedStageIds) {
-            if (validatedStages.has(stageId))
-                continue;
-            validatedStages.add(stageId);
-            const stagePath = path.join(stagesDir, `${stageId}.yaml`);
-            allFindings.push(...(await validateStageFile(cwd, stagePath)));
-        }
-        const idToPaths = await collectPipelineIds(pipelinesDir);
-        allFindings.push(...findingsForDuplicatePipelineIds(cwd, idToPaths));
-        allFindings.push(...(await findingsForOrphanStages(cwd, stagesDir, referencedStageIds)));
+        allFindings.push(...(await validateManifestAll(cwd)));
     }
     return buildValidationResult(options.scope, allFindings, strict);
 }

package/dist/envelope/check.js

@@ -25,6 +25,13 @@ export function assertRequiredEnvelope(value) {
         summary: record.summary,
         artifacts: record.artifacts,
     };
+    if (record.fork_choice !== undefined) {
+        if (!Array.isArray(record.fork_choice) ||
+            !record.fork_choice.every((item) => typeof item === "string")) {
+            throw new EnvelopeError("fork_choice must be an array of strings");
+        }
+        envelope.fork_choice = record.fork_choice;
+    }
     if (record.payload !== undefined) {
         if (record.payload === null ||
             typeof record.payload !== "object" ||

package/dist/envelope/forkChoice.d.ts

@@ -0,0 +1,3 @@
+import type { ForkEmitContext } from "../types/forkChoice.js";
+export declare function assertForkEnvelope(params: unknown, forkEmitContext: ForkEmitContext): void;
+export declare function normalizeForkChoice(raw: string[] | undefined, mode: "emit" | "stored", forkEmitContext?: ForkEmitContext): Set<string>;

package/dist/envelope/forkChoice.js

@@ -0,0 +1,47 @@
+/**
+ * Emit mode rejects missing fork_choice on fork success; stored mode treats
+ * undefined as an empty choice set (scheduler defensive path).
+ */
+import { EnvelopeError } from "../types/envelope.js";
+function assertForkChoiceLegality(choices, forkEmitContext) {
+    const { immediateSuccessorIds, forkShape } = forkEmitContext;
+    for (const id of choices) {
+        if (!immediateSuccessorIds.includes(id)) {
+            throw new EnvelopeError(`fork_choice contains non-immediate successor: ${id}`);
+        }
+    }
+    if (choices.length === 0) {
+        if (forkShape === null || !forkShape.allowNone) {
+            throw new EnvelopeError("fork_choice must not be empty");
+        }
+    }
+    if (forkShape !== null && forkShape.cardinality === "one" && choices.length !== 1) {
+        throw new EnvelopeError("fork shape requires exactly one choice");
+    }
+}
+export function assertForkEnvelope(params, forkEmitContext) {
+    const record = params;
+    if (record.status === "failure")
+        return;
+    if (record.fork_choice === undefined) {
+        throw new EnvelopeError("fork stage must include fork_choice on success");
+    }
+    assertForkChoiceLegality(record.fork_choice, forkEmitContext);
+}
+export function normalizeForkChoice(raw, mode, forkEmitContext) {
+    if (mode === "stored") {
+        if (raw === undefined)
+            return new Set();
+        return new Set(raw);
+    }
+    if (forkEmitContext === undefined) {
+        if (raw === undefined)
+            return new Set();
+        return new Set(raw);
+    }
+    if (raw === undefined) {
+        throw new EnvelopeError("fork stage must include fork_choice on success");
+    }
+    assertForkChoiceLegality(raw, forkEmitContext);
+    return new Set(raw);
+}

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/findProjectRoot.js";
+export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
+export { resolveProjectContext, legacyProjectContext, type ProjectContext, } from "./project/resolveProjectContext.js";
+export { resolveStageflowContext, projectContextFromStageflow, type StageflowContext, type CatalogManifestStatus, } from "./project/resolveStageflowContext.js";
 export { PACKAGE_NAME } from "./package-meta.js";
 export type { StageEnvelope } from "./types/envelope.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";

package/dist/index.js

@@ -1,3 +1,7 @@
+export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/findProjectRoot.js";
+export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
+export { resolveProjectContext, legacyProjectContext, } from "./project/resolveProjectContext.js";
+export { resolveStageflowContext, projectContextFromStageflow, } from "./project/resolveStageflowContext.js";
 export { PACKAGE_NAME } from "./package-meta.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";

package/dist/mcp/projectRun.d.ts

@@ -19,6 +19,9 @@ export type McpRunProjection = {
     run_id: string;
     pipeline_id: string;
     task_id?: string;
+    pipeline_path?: string;
+    task_path?: string;
+    project_root?: string;
     status: RunDetail["status"];
     created_at: string;
     updated_at?: string;

package/dist/mcp/projectRun.js

@@ -3,6 +3,13 @@ export function projectRunForMcp(detail) {
         run_id: detail.run_id,
         pipeline_id: detail.pipeline_id,
         task_id: detail.task_id,
+        ...(detail.pipeline_path !== undefined
+            ? { pipeline_path: detail.pipeline_path }
+            : {}),
+        ...(detail.task_path !== undefined ? { task_path: detail.task_path } : {}),
+        ...(detail.project_root !== undefined
+            ? { project_root: detail.project_root }
+            : {}),
         status: detail.status,
         created_at: detail.created_at,
         updated_at: detail.updated_at,

package/dist/mcp/server.js

@@ -4,7 +4,7 @@ import { registerMcpTools } from "./tools.js";
 export function createStageflowMcpServer(deps) {
     const server = new McpServer({
         name: "stageflow",
-        version: "0.1.0",
+        version: "0.2.0",
     });
     registerMcpTools(server, deps);
     return server;

package/dist/mcp/tools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { listPipelines } from "../config/listConfig.js";
+import { browseCatalog } from "../config/browseCatalog.js";
 import { projectRunForMcp } from "./projectRun.js";
 import { readRunArtifact } from "./readArtifact.js";
 const taskFileSchema = z.object({
@@ -9,6 +9,15 @@ const taskFileSchema = z.object({
     constraints: z.string().optional(),
     checkout: z.string().optional(),
 });
+const startRunSchema = z
+    .object({
+    pipeline: z.string().describe("Filesystem path to a pipeline YAML file"),
+    task_path: z.string().optional(),
+    task: taskFileSchema.optional(),
+})
+    .refine((data) => Boolean(data.task_path) !== Boolean(data.task), {
+    message: "Exactly one of task_path or task is required",
+});
 function textResult(data, isError = false) {
     return {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -18,11 +27,18 @@ function textResult(data, isError = false) {
 export function registerMcpTools(server, deps) {
     const { manager, store, cwd } = deps;
     server.registerTool("list_pipelines", {
-        description: "List runnable pipeline ids from the factory cwd",
+        description: "List manifest-declared pipeline paths from the project catalog",
+        inputSchema: z.object({}),
+    }, async () => {
+        const catalog = await browseCatalog(cwd);
+        return textResult({ pipelines: catalog.pipelines });
+    });
+    server.registerTool("list_tasks", {
+        description: "List manifest-declared task paths from the project catalog",
         inputSchema: z.object({}),
     }, async () => {
-        const pipelines = await listPipelines(cwd);
-        return textResult({ pipelines });
+        const catalog = await browseCatalog(cwd);
+        return textResult({ tasks: catalog.tasks });
     });
     server.registerTool("list_runs", {
         description: "List known pipeline runs",
@@ -36,16 +52,17 @@ export function registerMcpTools(server, deps) {
         inputSchema: z.object({}),
     }, async () => textResult(manager.getHealth()));
     server.registerTool("start_run", {
-        description: "Start a pipeline with an inline TaskFile (not written under tasks/). Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
-        inputSchema: z.object({
-            pipeline: z.string(),
-            task: taskFileSchema,
-        }),
-    }, async ({ pipeline, task }) => {
+        description: "Start a pipeline run using a filesystem pipeline path and either task_path (catalog task file) or an inline task object. Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
+        inputSchema: startRunSchema,
+    }, async ({ pipeline, task_path, task }) => {
         if (!pipeline.trim()) {
             return textResult({ error: "pipeline is required" }, true);
         }
-        const result = await manager.startRun({ pipeline, task });
+        const taskInput = task_path ?? task;
+        if (taskInput === undefined) {
+            return textResult({ error: "Exactly one of task_path or task is required" }, true);
+        }
+        const result = await manager.startRun({ pipeline, task: taskInput });
         if (!result.ok) {
             const { ok: _ok, reason, ...rest } = result;
             return textResult({ error: reason, ...rest }, true);

package/dist/project/findProjectRoot.d.ts

@@ -0,0 +1,2 @@
+export declare function findProjectRoot(startDir: string): string | null;
+export declare function clearFindProjectRootCacheForTests(): void;