stageflow 0.2.0 → 0.8.0

package/dist/config/loadStage.js

@@ -5,14 +5,14 @@ import { readYamlObject } from "./readYamlObject.js";
 function isGateKind(value) {
     return STAGE_GATE_KINDS.includes(value);
 }
-function parseGateKinds(raw, filePath) {
+function parseGateKinds(raw, label) {
     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`,
+                message: `Invalid stage ${label}: gate_kinds must be an array of strings`,
                 category: "stage",
             },
         ]);
@@ -23,7 +23,7 @@ function parseGateKinds(raw, filePath) {
             return loadFailure([
                 {
                     code: "stage.invalid_gate_kinds",
-                    message: `Invalid stage file ${filePath}: unsupported gate kind "${item}" (allowed: ${STAGE_GATE_KINDS.join(", ")})`,
+                    message: `Invalid stage ${label}: unsupported gate kind "${item}" (allowed: ${STAGE_GATE_KINDS.join(", ")})`,
                     category: "stage",
                 },
             ]);
@@ -32,35 +32,20 @@ function parseGateKinds(raw, filePath) {
     }
     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") {
+function parseStageFields(raw, label, entryId) {
+    if (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`,
+                message: `Invalid stage ${label}: system_prompt and model are required strings`,
                 category: "stage",
-                stageId: typeof raw?.id === "string" ? raw.id : undefined,
+                stageId: entryId,
             },
         ]);
     }
     const stage = {
-        id: raw.id,
+        id: entryId,
         system_prompt: raw.system_prompt,
         model: raw.model,
     };
@@ -71,9 +56,9 @@ export async function loadStageOutcome(filePath) {
             return loadFailure([
                 {
                     code: "stage.invalid_payload_schema",
-                    message: `Invalid stage file ${filePath}: payload_schema must be an object`,
+                    message: `Invalid stage ${label}: payload_schema must be an object`,
                     category: "stage",
-                    stageId: raw.id,
+                    stageId: entryId,
                 },
             ]);
         }
@@ -85,19 +70,19 @@ export async function loadStageOutcome(filePath) {
             return loadFailure([
                 {
                     code: "stage.invalid_payload_schema",
-                    message: `Invalid stage file ${filePath}: invalid payload_schema: ${message}`,
+                    message: `Invalid stage ${label}: invalid payload_schema: ${message}`,
                     category: "stage",
-                    stageId: raw.id,
+                    stageId: entryId,
                 },
             ]);
         }
         stage.payload_schema = raw.payload_schema;
     }
-    const gateKindsOutcome = parseGateKinds(raw.gate_kinds, filePath);
+    const gateKindsOutcome = parseGateKinds(raw.gate_kinds, label);
     if (!gateKindsOutcome.ok) {
         const issues = gateKindsOutcome.issues.map((issue) => ({
             ...issue,
-            stageId: stage.id,
+            stageId: entryId,
         }));
         return loadFailure(issues);
     }
@@ -108,9 +93,9 @@ export async function loadStageOutcome(filePath) {
             return loadFailure([
                 {
                     code: "stage.invalid_skill",
-                    message: `Invalid stage file ${filePath}: skill must be a non-empty string`,
+                    message: `Invalid stage ${label}: skill must be a non-empty string`,
                     category: "stage",
-                    stageId: stage.id,
+                    stageId: entryId,
                 },
             ]);
         }
@@ -118,6 +103,49 @@ export async function loadStageOutcome(filePath) {
     }
     return loadSuccess(stage);
 }
+export function loadStageFromObjectOutcome(raw, ctx) {
+    const label = `${ctx.entryId} (${ctx.declaringPath})`;
+    return parseStageFields(raw, label, ctx.entryId);
+}
+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") {
+        return loadFailure([
+            {
+                code: "stage.invalid_shape",
+                message: `Invalid stage file ${filePath}: id, system_prompt, and model are required strings`,
+                category: "stage",
+            },
+        ]);
+    }
+    const outcome = parseStageFields(raw, `file ${filePath}`, raw.id);
+    if (!outcome.ok)
+        return outcome;
+    if (outcome.value.id !== raw.id) {
+        return loadFailure([
+            {
+                code: "stage.invalid_shape",
+                message: `Invalid stage file ${filePath}: id mismatch`,
+                category: "stage",
+                stageId: raw.id,
+            },
+        ]);
+    }
+    return outcome;
+}
 export async function loadStage(filePath) {
     const outcome = await loadStageOutcome(filePath);
     if (!outcome.ok) {

package/dist/config/loadStageflowManifest.d.ts

@@ -0,0 +1,5 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export declare function manifestPathForProject(projectRoot: string): string;
+export declare function parseStageflowManifestOutcome(yamlText: string, manifestPath: string, projectRoot: string): LoadOutcome<LoadedManifest>;
+export declare function loadStageflowManifestOutcome(projectRoot: string): Promise<LoadOutcome<LoadedManifest>>;

package/dist/config/loadStageflowManifest.js

@@ -0,0 +1,157 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
+const DEFAULT_TASK_PATTERN = "*.task.yaml";
+export function manifestPathForProject(projectRoot) {
+    return path.join(projectRoot, "stageflow.yaml");
+}
+function catalogIssue(code, message) {
+    return { code, message, category: "catalog" };
+}
+function normalizeEntryPath(entry) {
+    return entry.replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+function parseStringArray(raw, field, issues) {
+    if (!Array.isArray(raw)) {
+        issues.push(catalogIssue("catalog.manifest_invalid", `catalog.${field} must be an array`));
+        return null;
+    }
+    const entries = [];
+    for (const item of raw) {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            issues.push(catalogIssue("catalog.manifest_invalid", `catalog.${field} entries must be non-empty strings`));
+            return null;
+        }
+        const normalized = normalizeEntryPath(item.trim());
+        if (path.isAbsolute(normalized)) {
+            issues.push(catalogIssue("catalog.manifest_invalid", `catalog.${field} entries must be repo-relative paths`));
+            return null;
+        }
+        entries.push(normalized);
+    }
+    return entries;
+}
+function parsePatterns(raw, issues) {
+    const defaults = {
+        pipeline: DEFAULT_PIPELINE_PATTERN,
+        task: DEFAULT_TASK_PATTERN,
+    };
+    if (raw === undefined || raw === null) {
+        return defaults;
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        issues.push(catalogIssue("catalog.manifest_invalid", "catalog.patterns must be an object"));
+        return defaults;
+    }
+    const record = raw;
+    const pipeline = record.pipeline === undefined
+        ? defaults.pipeline
+        : typeof record.pipeline === "string" && record.pipeline.trim().length > 0
+            ? record.pipeline.trim()
+            : null;
+    const task = record.task === undefined
+        ? defaults.task
+        : typeof record.task === "string" && record.task.trim().length > 0
+            ? record.task.trim()
+            : null;
+    if (pipeline === null) {
+        issues.push(catalogIssue("catalog.manifest_invalid", "catalog.patterns.pipeline must be a string"));
+    }
+    if (task === null) {
+        issues.push(catalogIssue("catalog.manifest_invalid", "catalog.patterns.task must be a string"));
+    }
+    return {
+        pipeline: pipeline ?? defaults.pipeline,
+        task: task ?? defaults.task,
+    };
+}
+export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoot) {
+    let raw;
+    try {
+        raw = parseYaml(yamlText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([catalogIssue("catalog.manifest_load_error", message)]);
+    }
+    const issues = [];
+    const record = raw;
+    if (!record || typeof record !== "object" || Array.isArray(record)) {
+        return loadFailure([
+            catalogIssue("catalog.manifest_invalid", "stageflow.yaml must be a mapping"),
+        ]);
+    }
+    if (record.version !== 1) {
+        issues.push(catalogIssue("catalog.manifest_invalid", `Unsupported manifest version: ${record.version}`));
+    }
+    const catalogRaw = record.catalog;
+    if (catalogRaw === undefined ||
+        typeof catalogRaw !== "object" ||
+        catalogRaw === null ||
+        Array.isArray(catalogRaw)) {
+        issues.push(catalogIssue("catalog.manifest_invalid", "catalog object is required"));
+        if (issues.length > 0) {
+            return loadFailure(issues);
+        }
+    }
+    const catalogRecord = catalogRaw;
+    const pipelines = parseStringArray(catalogRecord.pipelines, "pipelines", issues);
+    const tasks = parseStringArray(catalogRecord.tasks, "tasks", issues);
+    const excludeRaw = catalogRecord.exclude;
+    let exclude;
+    if (excludeRaw !== undefined) {
+        const parsed = parseStringArray(excludeRaw, "exclude", issues);
+        if (parsed !== null) {
+            exclude = parsed;
+        }
+    }
+    const patterns = parsePatterns(catalogRecord.patterns, issues);
+    if (issues.length > 0) {
+        return loadFailure(issues);
+    }
+    if (pipelines === null || tasks === null) {
+        return loadFailure(issues);
+    }
+    const catalog = { pipelines, tasks };
+    if (exclude !== undefined) {
+        catalog.exclude = exclude;
+    }
+    if (catalogRecord.patterns !== undefined) {
+        catalog.patterns = {};
+        if (typeof catalogRecord.patterns.pipeline === "string") {
+            catalog.patterns.pipeline = patterns.pipeline;
+        }
+        if (typeof catalogRecord.patterns.task === "string") {
+            catalog.patterns.task = patterns.task;
+        }
+    }
+    const manifest = { version: 1, catalog };
+    return loadSuccess({
+        path: manifestPath,
+        projectRoot,
+        manifest,
+        patterns,
+    });
+}
+export async function loadStageflowManifestOutcome(projectRoot) {
+    const manifestPath = manifestPathForProject(projectRoot);
+    try {
+        await access(manifestPath);
+    }
+    catch {
+        return loadFailure([
+            catalogIssue("catalog.manifest_load_error", `Manifest not found: ${manifestPath}`),
+        ]);
+    }
+    let yamlText;
+    try {
+        yamlText = await readFile(manifestPath, "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([catalogIssue("catalog.manifest_load_error", message)]);
+    }
+    return parseStageflowManifestOutcome(yamlText, manifestPath, projectRoot);
+}

package/dist/config/mergePipelineIncludes.d.ts

@@ -0,0 +1,9 @@
+import { type LoadOutcome } from "./loadOutcome.js";
+export type RawMergedEntry = {
+    raw: unknown;
+    declaringPath: string;
+};
+export declare function mergePipelineStages(rootPath: string): Promise<LoadOutcome<{
+    entries: RawMergedEntry[];
+    pipelineId: string;
+}>>;

package/dist/config/mergePipelineIncludes.js

@@ -0,0 +1,141 @@
+import path from "node:path";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { readYamlObject } from "./readYamlObject.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizePath(filePath) {
+    return path.normalize(path.resolve(filePath));
+}
+function formatIncludeCycle(stack, nextPath) {
+    const chain = [...stack, nextPath].map((p) => path.basename(p));
+    return chain.join(" → ");
+}
+async function visitPipelineFile(filePath, stack, idLocations, entries) {
+    const absPath = normalizePath(filePath);
+    if (stack.some((p) => normalizePath(p) === absPath)) {
+        const cycleChain = formatIncludeCycle(stack, absPath);
+        return loadFailure([
+            {
+                code: "pipeline.include_cycle",
+                message: `Include cycle detected: ${cycleChain}`,
+                category: "pipeline",
+            },
+        ]);
+    }
+    let raw;
+    try {
+        raw = await readYamlObject(absPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([
+            {
+                code: "pipeline.load_error",
+                message,
+                category: "pipeline",
+            },
+        ]);
+    }
+    const nextStack = [...stack, absPath];
+    if (raw.include !== undefined) {
+        if (!Array.isArray(raw.include)) {
+            return loadFailure([
+                {
+                    code: "pipeline.include_invalid",
+                    message: `Invalid include in ${absPath}: include must be an array`,
+                    category: "pipeline",
+                },
+            ]);
+        }
+        for (let index = 0; index < raw.include.length; index++) {
+            const item = raw.include[index];
+            if (!isPlainObject(item) || typeof item.local !== "string" || !item.local) {
+                return loadFailure([
+                    {
+                        code: "pipeline.include_invalid",
+                        message: `Invalid include entry at index ${index} in ${absPath}: expected { local: "<path>" }`,
+                        category: "pipeline",
+                    },
+                ]);
+            }
+            const includePath = normalizePath(path.resolve(path.dirname(absPath), item.local));
+            const includeResult = await visitPipelineFile(includePath, nextStack, idLocations, entries);
+            if (!includeResult.ok)
+                return includeResult;
+        }
+    }
+    if (Array.isArray(raw.stages)) {
+        for (const entry of raw.stages) {
+            if (isPlainObject(entry)) {
+                const entryId = typeof entry.id === "string" ? entry.id : undefined;
+                if (entryId) {
+                    const priorPath = idLocations.get(entryId);
+                    if (priorPath) {
+                        return loadFailure([
+                            {
+                                code: "pipeline.include_duplicate_stage",
+                                message: `Duplicate stage id "${entryId}" in ${absPath} (also declared in ${priorPath})`,
+                                category: "pipeline",
+                            },
+                        ]);
+                    }
+                    idLocations.set(entryId, absPath);
+                }
+            }
+            entries.push({ raw: entry, declaringPath: absPath });
+        }
+    }
+    return loadSuccess(undefined);
+}
+export async function mergePipelineStages(rootPath) {
+    const absRoot = normalizePath(rootPath);
+    let raw;
+    try {
+        raw = await readYamlObject(absRoot);
+    }
+    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" || !raw.id) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_shape",
+                message: `Invalid pipeline ${absRoot}: id is required`,
+                category: "pipeline",
+            },
+        ]);
+    }
+    if (!Array.isArray(raw.stages)) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_shape",
+                message: `Invalid pipeline ${absRoot}: stages[] is required`,
+                category: "pipeline",
+            },
+        ]);
+    }
+    const pipelineId = raw.id;
+    const idLocations = new Map();
+    const entries = [];
+    const mergeResult = await visitPipelineFile(absRoot, [], idLocations, entries);
+    if (!mergeResult.ok)
+        return mergeResult;
+    if (entries.length === 0) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_shape",
+                message: `Invalid pipeline ${absRoot}: stages must be non-empty`,
+                category: "pipeline",
+            },
+        ]);
+    }
+    return loadSuccess({ entries, pipelineId });
+}

package/dist/config/normalizePipelineStageEntry.d.ts

@@ -0,0 +1,18 @@
+import type { NormalizedPipelineStageEntry } from "../types/pipeline.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+import type { RawMergedEntry } from "./mergePipelineIncludes.js";
+export declare function inferIdFromUsesPath(usesPath: string): string | null;
+export declare function normalizePipelineStageEntries(rawEntries: RawMergedEntry[], ctx: {
+    pipelineId: string;
+    path: string;
+}): LoadOutcome<NormalizedPipelineStageEntry[]>;
+export declare function toWiringRefs(entries: NormalizedPipelineStageEntry[]): Array<{
+    id: string;
+    needs?: string;
+    fork?: {
+        select: "one" | "subset";
+        allow_none?: boolean;
+    };
+    clonable?: boolean;
+    clone_cap?: number;
+}>;