stageflow 0.1.0

package/dist/config/loadPipeline.js

@@ -0,0 +1,196 @@
+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);
+    try {
+        await access(direct);
+        return direct;
+    }
+    catch {
+        const candidate = path.resolve(cwd, "pipelines", `${nameOrPath}.yaml`);
+        await access(candidate);
+        return candidate;
+    }
+}
+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 };
+    let stageIds;
+    let dag;
+    try {
+        const resolved = resolvePipelineDag(raw.stages, ctx);
+        stageIds = resolved.stages;
+        dag = resolved.dag;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([
+            {
+                code: "pipeline.dag_error",
+                message,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    const pipeline = {
+        id: raw.id,
+        stages: stageIds,
+    };
+    const stages = [];
+    for (const stageId of pipeline.stages) {
+        const stagePath = path.join(stagesDir, `${stageId}.yaml`);
+        const stageOutcome = await loadStageOutcome(stagePath);
+        if (!stageOutcome.ok) {
+            const message = `Pipeline ${pipeline.id} references missing stage "${stageId}" at ${stagePath}`;
+            return loadFailure([
+                {
+                    code: "pipeline.missing_stage",
+                    message,
+                    category: "pipeline",
+                    pipelineId,
+                },
+            ]);
+        }
+        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);
+        }
+    }
+    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;
+}
+export async function loadPipelineValidated(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 { ok: true, loaded: outcome.value };
+}
+export async function loadPipeline(nameOrPath, options = {}) {
+    const outcome = await loadPipelineOutcome(nameOrPath, options);
+    if (!outcome.ok) {
+        throw new Error(outcome.issues[0].message);
+    }
+    return outcome.value;
+}

package/dist/config/loadStage.d.ts

@@ -0,0 +1,4 @@
+import { type StageConfig } from "../types/stage.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export declare function loadStageOutcome(filePath: string): Promise<LoadOutcome<StageConfig>>;
+export declare function loadStage(filePath: string): Promise<StageConfig>;

package/dist/config/loadStage.js

@@ -0,0 +1,127 @@
+import { STAGE_GATE_KINDS, } from "../types/stage.js";
+import { compilePayloadSchema } from "../envelope/payloadSchema.js";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { readYamlObject } from "./readYamlObject.js";
+function isGateKind(value) {
+    return STAGE_GATE_KINDS.includes(value);
+}
+function parseGateKinds(raw, filePath) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!Array.isArray(raw) || !raw.every((item) => typeof item === "string")) {
+        return loadFailure([
+            {
+                code: "stage.invalid_gate_kinds",
+                message: `Invalid stage file ${filePath}: gate_kinds must be an array of strings`,
+                category: "stage",
+            },
+        ]);
+    }
+    const kinds = [];
+    for (const item of raw) {
+        if (!isGateKind(item)) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_gate_kinds",
+                    message: `Invalid stage file ${filePath}: unsupported gate kind "${item}" (allowed: ${STAGE_GATE_KINDS.join(", ")})`,
+                    category: "stage",
+                },
+            ]);
+        }
+        kinds.push(item);
+    }
+    return loadSuccess(kinds.length > 0 ? kinds : undefined);
+}
+export async function loadStageOutcome(filePath) {
+    let raw;
+    try {
+        raw = await readYamlObject(filePath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([
+            {
+                code: "stage.load_error",
+                message,
+                category: "stage",
+            },
+        ]);
+    }
+    if (typeof raw?.id !== "string" ||
+        typeof raw?.system_prompt !== "string" ||
+        typeof raw?.model !== "string") {
+        return loadFailure([
+            {
+                code: "stage.invalid_shape",
+                message: `Invalid stage file ${filePath}: id, system_prompt, and model are required strings`,
+                category: "stage",
+                stageId: typeof raw?.id === "string" ? raw.id : undefined,
+            },
+        ]);
+    }
+    const stage = {
+        id: raw.id,
+        system_prompt: raw.system_prompt,
+        model: raw.model,
+    };
+    if (raw.payload_schema !== undefined) {
+        if (raw.payload_schema === null ||
+            typeof raw.payload_schema !== "object" ||
+            Array.isArray(raw.payload_schema)) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_payload_schema",
+                    message: `Invalid stage file ${filePath}: payload_schema must be an object`,
+                    category: "stage",
+                    stageId: raw.id,
+                },
+            ]);
+        }
+        try {
+            compilePayloadSchema(raw.payload_schema);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return loadFailure([
+                {
+                    code: "stage.invalid_payload_schema",
+                    message: `Invalid stage file ${filePath}: invalid payload_schema: ${message}`,
+                    category: "stage",
+                    stageId: raw.id,
+                },
+            ]);
+        }
+        stage.payload_schema = raw.payload_schema;
+    }
+    const gateKindsOutcome = parseGateKinds(raw.gate_kinds, filePath);
+    if (!gateKindsOutcome.ok) {
+        const issues = gateKindsOutcome.issues.map((issue) => ({
+            ...issue,
+            stageId: stage.id,
+        }));
+        return loadFailure(issues);
+    }
+    if (gateKindsOutcome.value)
+        stage.gate_kinds = gateKindsOutcome.value;
+    if (raw.skill !== undefined) {
+        if (typeof raw.skill !== "string" || raw.skill.trim() === "") {
+            return loadFailure([
+                {
+                    code: "stage.invalid_skill",
+                    message: `Invalid stage file ${filePath}: skill must be a non-empty string`,
+                    category: "stage",
+                    stageId: stage.id,
+                },
+            ]);
+        }
+        stage.skill = raw.skill.trim();
+    }
+    return loadSuccess(stage);
+}
+export async function loadStage(filePath) {
+    const outcome = await loadStageOutcome(filePath);
+    if (!outcome.ok) {
+        throw new Error(outcome.issues[0].message);
+    }
+    return outcome.value;
+}

package/dist/config/loadTask.d.ts

@@ -0,0 +1,7 @@
+import type { TaskFile } from "../types/task.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export declare function parseTaskFile(raw: unknown, source?: string): LoadOutcome<TaskFile>;
+export declare function loadTaskFromYamlOutcome(yamlText: string, source?: string): LoadOutcome<TaskFile>;
+export declare function loadTaskOutcome(filePath: string): Promise<LoadOutcome<TaskFile>>;
+export declare function loadTaskFromYaml(yamlText: string, source?: string): TaskFile;
+export declare function loadTask(filePath: string): Promise<TaskFile>;

package/dist/config/loadTask.js

@@ -0,0 +1,69 @@
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+export function parseTaskFile(raw, source = "task") {
+    const record = raw;
+    if (typeof record?.id !== "string" || typeof record?.goal !== "string") {
+        return loadFailure([
+            {
+                code: "task.invalid_shape",
+                message: `Invalid ${source}: id and goal are required strings`,
+                category: "task",
+                taskId: typeof record?.id === "string" ? record.id : undefined,
+            },
+        ]);
+    }
+    return loadSuccess({
+        id: record.id,
+        goal: record.goal,
+        context: typeof record.context === "string" ? record.context : undefined,
+        constraints: typeof record.constraints === "string" ? record.constraints : undefined,
+        checkout: typeof record.checkout === "string" ? record.checkout : undefined,
+    });
+}
+export function loadTaskFromYamlOutcome(yamlText, source = "task yaml") {
+    let raw;
+    try {
+        raw = parseYaml(yamlText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([
+            {
+                code: "task.load_error",
+                message,
+                category: "task",
+            },
+        ]);
+    }
+    return parseTaskFile(raw, source);
+}
+export async function loadTaskOutcome(filePath) {
+    let yamlText;
+    try {
+        yamlText = await readFile(filePath, "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([
+            {
+                code: "task.load_error",
+                message,
+                category: "task",
+            },
+        ]);
+    }
+    return loadTaskFromYamlOutcome(yamlText, `task file ${filePath}`);
+}
+export function loadTaskFromYaml(yamlText, source = "task yaml") {
+    const outcome = loadTaskFromYamlOutcome(yamlText, source);
+    if (!outcome.ok)
+        throw new Error(outcome.issues[0].message);
+    return outcome.value;
+}
+export async function loadTask(filePath) {
+    const outcome = await loadTaskOutcome(filePath);
+    if (!outcome.ok)
+        throw new Error(outcome.issues[0].message);
+    return outcome.value;
+}

package/dist/config/readYamlObject.d.ts

@@ -0,0 +1 @@
+export declare function readYamlObject(filePath: string): Promise<Record<string, unknown>>;

package/dist/config/readYamlObject.js

@@ -0,0 +1,5 @@
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+export async function readYamlObject(filePath) {
+    return parseYaml(await readFile(filePath, "utf8"));
+}

package/dist/config/resolvePipelineDag.d.ts

@@ -0,0 +1,12 @@
+import type { PipelineStageYamlEntry, ResolvedPipelineDag } from "../types/pipeline.js";
+export type ResolvePipelineDagContext = {
+    pipelineId: string;
+    path: string;
+};
+export declare function parsePipelineStageEntries(raw: unknown, ctx: ResolvePipelineDagContext): PipelineStageYamlEntry[];
+export declare function resolvePipelineDag(rawStages: unknown, ctx: ResolvePipelineDagContext): {
+    stages: string[];
+    dag: ResolvedPipelineDag;
+};
+export declare function areResolvedDagsEquivalent(a: ResolvedPipelineDag, b: ResolvedPipelineDag): boolean;
+export declare function extractPipelineStageIds(rawStages: unknown[]): string[] | null;