stageflow 0.2.0 → 0.3.0

package/dist/config/listConfig.d.ts

@@ -1,18 +1,9 @@
-import { type StageGateKind } from "../types/stage.js";
-export type TaskListing = {
-    path: string;
-    id: string;
-    goal: string;
-};
-export type PipelineStageListing = {
-    id: string;
-    gate_kinds?: StageGateKind[];
-};
-export type PipelineListing = {
-    path: string;
-    id: string;
-    stages: PipelineStageListing[];
-};
+import type { StageGateKind } from "../types/stage.js";
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import { type PipelineListing, type TaskListing } from "./browseCatalog.js";
+import { type StageflowContext } from "../project/resolveStageflowContext.js";
+import { type CatalogContext } from "./resolveCatalogContext.js";
+export type { PipelineListing, PipelineStageListing, TaskListing } from "./browseCatalog.js";
 export type ValidStageListing = {
     path: string;
     id: string;
@@ -27,7 +18,11 @@ export type BrokenStageListing = {
     gate_kinds?: StageGateKind[];
 };
 export type StageListing = ValidStageListing | BrokenStageListing;
-export declare function listTasks(cwd: string): Promise<TaskListing[]>;
-export declare function listPipelines(cwd: string): Promise<PipelineListing[]>;
-export declare function listStages(cwd: string): Promise<StageListing[]>;
-export declare function listModels(cwd: string): Promise<string[]>;
+export type CatalogListOptions = {
+    projectRoot: string;
+    manifest: LoadedManifest;
+};
+export declare function listTasks(options: CatalogListOptions): Promise<TaskListing[]>;
+export declare function listPipelines(options: CatalogListOptions): Promise<PipelineListing[]>;
+export declare function listStages(_options?: unknown): Promise<StageListing[]>;
+export declare function listModels(cwdOrContext: string | CatalogContext | StageflowContext): Promise<string[]>;

package/dist/config/listConfig.js

@@ -1,195 +1,30 @@
-import { readdir } from "node:fs/promises";
-import path from "node:path";
-import { STAGE_GATE_KINDS, } from "../types/stage.js";
-import { loadPipeline } from "./loadPipeline.js";
-import { loadStage } from "./loadStage.js";
-import { loadTask } from "./loadTask.js";
-import { readYamlObject } from "./readYamlObject.js";
-import { extractPipelineStageIds } from "./resolvePipelineDag.js";
-const BAKED_MODEL_IDS = [
-    "anthropic/claude-sonnet-4-5",
-    "cursor/auto",
-    "cursor/composer-2-5",
-];
-function parseSafeGateKinds(raw) {
-    if (!Array.isArray(raw) || !raw.every((item) => typeof item === "string")) {
-        return undefined;
-    }
-    const allowed = new Set(STAGE_GATE_KINDS);
-    const gateKinds = raw.filter((item) => allowed.has(item));
-    return gateKinds.length > 0 ? gateKinds : undefined;
+import { listModelsForContext, listPipelinesForContext, listTasksForContext, } from "./browseCatalog.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
+export async function listTasks(options) {
+    return listTasksForContext({
+        projectRoot: options.projectRoot,
+        manifest: options.manifest,
+        manifestStatus: "ok",
+        issues: [],
+    });
 }
-async function listPipelineUsageByStage(cwd) {
-    const dir = path.join(cwd, "pipelines");
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return new Map();
-    }
-    const usage = new Map();
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith(".yaml"))
-            continue;
-        const filePath = path.join(dir, entry.name);
-        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) {
-                let pipelineIds = usage.get(stageId);
-                if (!pipelineIds) {
-                    pipelineIds = new Set();
-                    usage.set(stageId, pipelineIds);
-                }
-                pipelineIds.add(raw.id);
-            }
-        }
-        catch {
-            // skip invalid pipeline files
-        }
-    }
-    return usage;
+export async function listPipelines(options) {
+    return listPipelinesForContext({
+        projectRoot: options.projectRoot,
+        manifest: options.manifest,
+        manifestStatus: "ok",
+        issues: [],
+    });
 }
-export async function listTasks(cwd) {
-    const dir = path.join(cwd, "tasks");
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    const listings = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith(".yaml"))
-            continue;
-        const filePath = path.join(dir, entry.name);
-        try {
-            const task = await loadTask(filePath);
-            listings.push({
-                path: path.relative(cwd, filePath),
-                id: task.id,
-                goal: task.goal,
-            });
-        }
-        catch {
-            // skip invalid
-        }
-    }
-    listings.sort((a, b) => a.id.localeCompare(b.id));
-    return listings;
+export async function listStages(_options) {
+    return [];
 }
-export async function listPipelines(cwd) {
-    const dir = path.join(cwd, "pipelines");
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    const listings = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith(".yaml"))
-            continue;
-        const filePath = path.join(dir, entry.name);
-        try {
-            const loaded = await loadPipeline(filePath, { cwd });
-            listings.push({
-                path: path.relative(cwd, filePath),
-                id: loaded.pipeline.id,
-                stages: loaded.stages.map((stage) => ({
-                    id: stage.id,
-                    ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
-                })),
-            });
-        }
-        catch {
-            // skip invalid
-        }
-    }
-    listings.sort((a, b) => a.id.localeCompare(b.id));
-    return listings;
-}
-export async function listStages(cwd) {
-    const dir = path.join(cwd, "stages");
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    const usageByStage = await listPipelineUsageByStage(cwd);
-    const valid = [];
-    const broken = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith(".yaml"))
-            continue;
-        const filePath = path.join(dir, entry.name);
-        const relPath = path.relative(cwd, filePath);
-        try {
-            const stage = await loadStage(filePath);
-            valid.push({
-                path: relPath,
-                id: stage.id,
-                used_by_pipeline_ids: [...(usageByStage.get(stage.id) ?? new Set())].sort(),
-                ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
-            });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const brokenRow = {
-                path: relPath,
-                error: message,
-            };
-            try {
-                const raw = await readYamlObject(filePath);
-                if (typeof raw?.id === "string")
-                    brokenRow.id = raw.id;
-                if (typeof raw?.model === "string")
-                    brokenRow.model = raw.model;
-                const gateKinds = parseSafeGateKinds(raw?.gate_kinds);
-                if (gateKinds)
-                    brokenRow.gate_kinds = gateKinds;
-            }
-            catch {
-                // keep path + error only when parsing itself fails
-            }
-            broken.push(brokenRow);
-        }
-    }
-    valid.sort((a, b) => a.id.localeCompare(b.id));
-    broken.sort((a, b) => a.path.localeCompare(b.path));
-    return [...valid, ...broken];
-}
-export async function listModels(cwd) {
-    const dir = path.join(cwd, "stages");
-    const models = new Set(BAKED_MODEL_IDS);
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return [...models].sort((a, b) => a.localeCompare(b));
-    }
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith(".yaml"))
-            continue;
-        try {
-            const raw = await readYamlObject(path.join(dir, entry.name));
-            if (typeof raw?.model === "string" && raw.model.trim()) {
-                models.add(raw.model);
-            }
-        }
-        catch {
-            // ignore unreadable or invalid stage YAML
-        }
-    }
-    return [...models].sort((a, b) => a.localeCompare(b));
+export async function listModels(cwdOrContext) {
+    const ctx = typeof cwdOrContext === "string"
+        ? catalogContextFromStageflow(await resolveStageflowContext(cwdOrContext))
+        : "manifestIssues" in cwdOrContext
+            ? catalogContextFromStageflow(cwdOrContext)
+            : cwdOrContext;
+    return listModelsForContext(ctx);
 }

package/dist/config/listModelsFromManifest.d.ts

@@ -0,0 +1,2 @@
+import type { CatalogContext } from "./resolveCatalogContext.js";
+export declare function listModelsFromManifest(ctx: CatalogContext): Promise<string[]>;

package/dist/config/listModelsFromManifest.js

@@ -0,0 +1,4 @@
+import { listModelsForContext } from "./browseCatalog.js";
+export async function listModelsFromManifest(ctx) {
+    return listModelsForContext(ctx);
+}

package/dist/config/loadOutcome.d.ts

@@ -15,6 +15,10 @@ export type LoadIssue = {
     message: string;
     category: "task";
     taskId?: string;
+} | {
+    code: ValidationFindingCode | string;
+    message: string;
+    category: "catalog";
 };
 export type LoadOutcome<T> = {
     ok: true;

package/dist/config/loadPipeline.d.ts

@@ -1,25 +1,11 @@
 import type { LoadedPipeline } from "../types/pipeline.js";
 import { type LoadOutcome } from "./loadOutcome.js";
-import type { ValidationFinding } from "./validateCatalog.js";
 export type { LoadedPipeline } from "../types/pipeline.js";
 export type { LoadIssue, LoadOutcome } from "./loadOutcome.js";
-export type LoadPipelineValidatedResult = {
-    ok: true;
-    loaded: LoadedPipeline;
-} | {
-    ok: false;
-    findings: ValidationFinding[];
-};
+export declare function resolvePipelinePath(pipelinePath: string, cwd: string): Promise<string>;
 export declare function loadPipelineOutcome(nameOrPath: string, options?: {
     cwd?: string;
-    stagesDir?: string;
 }): Promise<LoadOutcome<LoadedPipeline>>;
-export declare function loadPipelineValidated(nameOrPath: string, options?: {
-    cwd?: string;
-    stagesDir?: string;
-    validateStages?: boolean;
-}): Promise<LoadPipelineValidatedResult>;
 export declare function loadPipeline(nameOrPath: string, options?: {
     cwd?: string;
-    stagesDir?: string;
 }): Promise<LoadedPipeline>;

package/dist/config/loadPipeline.js

@@ -1,68 +1,38 @@
 import { access } from "node:fs/promises";
 import path from "node:path";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
-import { loadStageOutcome } from "./loadStage.js";
-import { readYamlObject } from "./readYamlObject.js";
-import { extractPipelineStageIds, resolvePipelineDag } from "./resolvePipelineDag.js";
-import { findingStageIdFilenameMismatch, findingsFromLoadIssues, } from "./validateCatalog.js";
-async function resolvePipelinePath(nameOrPath, cwd) {
-    const direct = path.resolve(cwd, nameOrPath);
+import { mergePipelineStages } from "./mergePipelineIncludes.js";
+import { normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
+import { loadStageFromObjectOutcome, loadStageOutcome } from "./loadStage.js";
+import { resolvePipelineDagFromRefs } from "./resolvePipelineDag.js";
+export async function resolvePipelinePath(pipelinePath, cwd) {
+    const resolved = path.normalize(path.resolve(cwd, pipelinePath));
     try {
-        await access(direct);
-        return direct;
+        await access(resolved);
+        return resolved;
     }
     catch {
-        const candidate = path.resolve(cwd, "pipelines", `${nameOrPath}.yaml`);
-        await access(candidate);
-        return candidate;
+        throw new Error(`Pipeline file not found: ${resolved}. Pass a filesystem path to --pipeline (e.g. pipelines/hello.pipeline.yaml), not a bare pipeline id.`);
     }
 }
-export async function loadPipelineOutcome(nameOrPath, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
-    const stagesDir = options.stagesDir ?? path.join(cwd, "stages");
-    let pipelinePath;
-    try {
-        pipelinePath = await resolvePipelinePath(nameOrPath, cwd);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return loadFailure([
-            {
-                code: "pipeline.load_error",
-                message,
-                category: "pipeline",
-            },
-        ]);
-    }
-    let raw;
-    try {
-        raw = await readYamlObject(pipelinePath);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return loadFailure([
-            {
-                code: "pipeline.load_error",
-                message,
-                category: "pipeline",
-            },
-        ]);
-    }
-    if (typeof raw?.id !== "string" || !Array.isArray(raw.stages)) {
-        return loadFailure([
-            {
-                code: "pipeline.invalid_shape",
-                message: `Invalid pipeline ${pipelinePath}: id and stages[] are required`,
-                category: "pipeline",
-            },
-        ]);
-    }
-    const pipelineId = raw.id;
-    const ctx = { pipelineId: raw.id, path: pipelinePath };
+async function loadPipelineFromPath(pipelinePath) {
+    const normalizedPipelinePath = path.normalize(path.resolve(pipelinePath));
+    const mergeOutcome = await mergePipelineStages(normalizedPipelinePath);
+    if (!mergeOutcome.ok) {
+        return loadFailure(mergeOutcome.issues);
+    }
+    const { entries: rawEntries, pipelineId } = mergeOutcome.value;
+    const ctx = { pipelineId, path: normalizedPipelinePath };
+    const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
+    if (!normalizeOutcome.ok) {
+        return loadFailure(normalizeOutcome.issues);
+    }
+    const normalizedEntries = normalizeOutcome.value;
+    const wiringRefs = toWiringRefs(normalizedEntries);
     let stageIds;
     let dag;
     try {
-        const resolved = resolvePipelineDag(raw.stages, ctx);
+        const resolved = resolvePipelineDagFromRefs(wiringRefs, ctx);
         stageIds = resolved.stages;
         dag = resolved.dag;
     }
@@ -77,115 +47,87 @@ export async function loadPipelineOutcome(nameOrPath, options = {}) {
             },
         ]);
     }
-    const pipeline = {
-        id: raw.id,
-        stages: stageIds,
-    };
+    const entryById = new Map(normalizedEntries.map((entry) => [entry.id, entry]));
+    const stageSources = {};
     const stages = [];
-    for (const stageId of pipeline.stages) {
-        const stagePath = path.join(stagesDir, `${stageId}.yaml`);
-        const stageOutcome = await loadStageOutcome(stagePath);
+    for (const stageId of stageIds) {
+        const entry = entryById.get(stageId);
+        if (!entry) {
+            return loadFailure([
+                {
+                    code: "pipeline.invalid_shape",
+                    message: `Pipeline ${pipelineId}: missing normalized entry for stage "${stageId}"`,
+                    category: "pipeline",
+                    pipelineId,
+                },
+            ]);
+        }
+        if (entry.body.kind === "inline") {
+            const inlineOutcome = loadStageFromObjectOutcome(entry.body.raw, {
+                entryId: entry.id,
+                declaringPath: entry.declaringPath,
+            });
+            if (!inlineOutcome.ok) {
+                return loadFailure(inlineOutcome.issues);
+            }
+            stages.push(inlineOutcome.value);
+            stageSources[stageId] = { kind: "inline" };
+            continue;
+        }
+        const stageOutcome = await loadStageOutcome(entry.body.absolutePath);
         if (!stageOutcome.ok) {
-            const message = `Pipeline ${pipeline.id} references missing stage "${stageId}" at ${stagePath}`;
             return loadFailure([
                 {
                     code: "pipeline.missing_stage",
-                    message,
+                    message: `Pipeline ${pipelineId} references missing stage "${stageId}" at ${entry.body.absolutePath}`,
                     category: "pipeline",
                     pipelineId,
                 },
+                ...stageOutcome.issues,
             ]);
         }
-        stages.push(stageOutcome.value);
-    }
-    return loadSuccess({ pipeline, stages, dag });
-}
-async function checkStageIdFilename(cwd, stagePath) {
-    const fileStem = path.basename(stagePath, ".yaml");
-    try {
-        const raw = await readYamlObject(stagePath);
-        if (typeof raw?.id === "string" && raw.id !== fileStem) {
-            return findingStageIdFilenameMismatch(cwd, stagePath, fileStem, raw.id);
+        if (stageOutcome.value.id !== entry.id) {
+            return loadFailure([
+                {
+                    code: "pipeline.stage_id_mismatch",
+                    message: `Pipeline ${pipelineId}: stage entry "${entry.id}" in ${entry.declaringPath} uses ${entry.body.path} which declares id "${stageOutcome.value.id}"`,
+                    category: "pipeline",
+                    pipelineId,
+                },
+            ]);
         }
+        stages.push(stageOutcome.value);
+        stageSources[stageId] = { kind: "file", path: entry.body.absolutePath };
     }
-    catch {
-        // loadStageOutcome will report read errors
-    }
-    return null;
-}
-async function validateStageFile(cwd, stagePath) {
-    const findings = [];
-    const mismatch = await checkStageIdFilename(cwd, stagePath);
-    if (mismatch)
-        findings.push(mismatch);
-    const outcome = await loadStageOutcome(stagePath);
-    if (!outcome.ok) {
-        findings.push(...findingsFromLoadIssues(cwd, stagePath, outcome.issues));
-        return findings;
-    }
-    if (!mismatch && path.basename(stagePath, ".yaml") !== outcome.value.id) {
-        findings.push(findingStageIdFilenameMismatch(cwd, stagePath, path.basename(stagePath, ".yaml"), outcome.value.id));
-    }
-    return findings;
+    const pipeline = {
+        id: pipelineId,
+        stages: stageIds,
+    };
+    return loadSuccess({
+        pipeline,
+        stages,
+        dag,
+        pipelinePath: normalizedPipelinePath,
+        stageSources,
+    });
 }
-export async function loadPipelineValidated(nameOrPath, options = {}) {
+export async function loadPipelineOutcome(nameOrPath, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const stagesDir = options.stagesDir ?? path.join(cwd, "stages");
-    const validateStages = options.validateStages ?? true;
     let pipelinePath;
     try {
         pipelinePath = await resolvePipelinePath(nameOrPath, cwd);
     }
     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 referencedStageIds = new Set();
-    try {
-        const raw = await readYamlObject(pipelinePath);
-        if (typeof raw?.id === "string" && Array.isArray(raw.stages)) {
-            const stageIds = extractPipelineStageIds(raw.stages);
-            if (stageIds) {
-                for (const stageId of stageIds) {
-                    referencedStageIds.add(stageId);
-                }
-            }
-        }
-    }
-    catch {
-        // loadPipelineOutcome will report read errors
-    }
-    const outcome = await loadPipelineOutcome(nameOrPath, { cwd, stagesDir });
-    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) {
-        for (const stageId of outcome.value.pipeline.stages) {
-            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 loadFailure([
+            {
+                code: "pipeline.load_error",
+                message,
+                category: "pipeline",
+            },
+        ]);
     }
-    return { ok: true, loaded: outcome.value };
+    return loadPipelineFromPath(pipelinePath);
 }
 export async function loadPipeline(nameOrPath, options = {}) {
     const outcome = await loadPipelineOutcome(nameOrPath, options);

package/dist/config/loadStage.d.ts

@@ -1,4 +1,8 @@
 import { type StageConfig } from "../types/stage.js";
 import { type LoadOutcome } from "./loadOutcome.js";
+export declare function loadStageFromObjectOutcome(raw: Record<string, unknown>, ctx: {
+    entryId: string;
+    declaringPath: string;
+}): LoadOutcome<StageConfig>;
 export declare function loadStageOutcome(filePath: string): Promise<LoadOutcome<StageConfig>>;
 export declare function loadStage(filePath: string): Promise<StageConfig>;