stageflow 0.2.0 → 0.3.0

package/dist/config/pipelineStageKeys.js

@@ -0,0 +1,14 @@
+export const WIRING_KEYS = new Set(["id", "needs", "fork", "uses"]);
+export const BODY_KEYS = new Set([
+    "system_prompt",
+    "model",
+    "payload_schema",
+    "gate_kinds",
+    "skill",
+]);
+export function isPipelineStageBodyKey(key) {
+    return BODY_KEYS.has(key);
+}
+export function isAllowedPipelineStageEntryKey(key) {
+    return WIRING_KEYS.has(key) || BODY_KEYS.has(key);
+}

package/dist/config/resolveCatalogContext.d.ts

@@ -0,0 +1,13 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import type { LoadIssue } from "./loadOutcome.js";
+import { type CatalogManifestStatus, type StageflowContext } from "../project/resolveStageflowContext.js";
+export type { CatalogManifestStatus };
+export type CatalogContext = {
+    projectRoot: string | null;
+    manifest: LoadedManifest | null;
+    manifestStatus: CatalogManifestStatus;
+    issues: LoadIssue[];
+};
+export declare function catalogContextFromStageflow(ctx: StageflowContext): CatalogContext;
+/** @deprecated Prefer resolveStageflowContext */
+export declare function resolveCatalogContext(invocationCwd: string): Promise<CatalogContext>;

package/dist/config/resolveCatalogContext.js

@@ -0,0 +1,13 @@
+import { resolveStageflowContext, } from "../project/resolveStageflowContext.js";
+export function catalogContextFromStageflow(ctx) {
+    return {
+        projectRoot: ctx.isGitProject ? ctx.projectRoot : null,
+        manifest: ctx.manifest,
+        manifestStatus: ctx.manifestStatus,
+        issues: ctx.manifestIssues,
+    };
+}
+/** @deprecated Prefer resolveStageflowContext */
+export async function resolveCatalogContext(invocationCwd) {
+    return catalogContextFromStageflow(await resolveStageflowContext(invocationCwd));
+}

package/dist/config/resolveForkEmitContext.d.ts

@@ -0,0 +1,3 @@
+import type { ForkEmitContext } from "../types/forkChoice.js";
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+export declare function resolveForkEmitContext(dag: ResolvedPipelineDag, stageId: string): ForkEmitContext | undefined;

package/dist/config/resolveForkEmitContext.js

@@ -0,0 +1,12 @@
+export function resolveForkEmitContext(dag, stageId) {
+    const dagNode = dag.nodes.find((n) => n.id === stageId);
+    if (!dagNode?.fork)
+        return undefined;
+    return {
+        immediateSuccessorIds: dag.childrenOf[stageId] ?? [],
+        forkShape: {
+            cardinality: dagNode.fork.select,
+            allowNone: dagNode.fork.allow_none,
+        },
+    };
+}

package/dist/config/resolvePipelineDag.d.ts

@@ -1,9 +1,13 @@
-import type { PipelineStageYamlEntry, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { PipelineStageRef, 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 resolvePipelineDagFromRefs(refs: PipelineStageRef[], ctx: ResolvePipelineDagContext): {
+    stages: string[];
+    dag: ResolvedPipelineDag;
+};
 export declare function resolvePipelineDag(rawStages: unknown, ctx: ResolvePipelineDagContext): {
     stages: string[];
     dag: ResolvedPipelineDag;

package/dist/config/resolvePipelineDag.js

@@ -1,4 +1,5 @@
-const ALLOWED_STAGE_REF_KEYS = new Set(["id", "needs"]);
+import { isAllowedPipelineStageEntryKey } from "./pipelineStageKeys.js";
+const ALLOWED_FORK_KEYS = new Set(["select", "allow_none"]);
 function pipelineLabel(ctx) {
     return `Pipeline ${ctx.pipelineId} (${ctx.path})`;
 }
@@ -19,26 +20,37 @@ export function parsePipelineStageEntries(raw, ctx) {
     for (let index = 0; index < raw.length; index++) {
         const entry = raw[index];
         if (typeof entry === "string") {
-            if (!entry) {
-                throw new Error(formatError(ctx, `invalid stage entry at index ${index}: stage id must be a non-empty string`));
-            }
-            entries.push(entry);
-            continue;
+            const hint = entry
+                ? `invalid stage entry at index ${index}: bare string stage refs are not supported; use { id: "${entry}", uses: "./${entry}.yaml" } or inline body`
+                : `invalid stage entry at index ${index}: bare string stage refs are not supported; use { id: "…", uses: "./….yaml" } or inline body`;
+            throw new Error(formatError(ctx, hint));
         }
         if (!isPlainObject(entry)) {
             throw new Error(formatError(ctx, `invalid stage entry at index ${index}`));
         }
         const keys = Object.keys(entry);
         for (const key of keys) {
-            if (!ALLOWED_STAGE_REF_KEYS.has(key)) {
+            if (!isAllowedPipelineStageEntryKey(key)) {
                 throw new Error(formatError(ctx, `invalid stage entry "${String(entry.id ?? index)}": unknown key "${key}"`));
             }
         }
         if (typeof entry.id !== "string" || !entry.id) {
             throw new Error(formatError(ctx, `invalid stage entry at index ${index}: id must be a non-empty string`));
         }
+        let forkValue;
+        if (entry.fork !== undefined) {
+            if (!isPlainObject(entry.fork)) {
+                throw new Error(formatError(ctx, `stage "${entry.id}": fork must be an object`));
+            }
+            for (const fk of Object.keys(entry.fork)) {
+                if (!ALLOWED_FORK_KEYS.has(fk)) {
+                    throw new Error(formatError(ctx, `stage "${entry.id}": fork: unknown key "${fk}"`));
+                }
+            }
+            forkValue = entry.fork;
+        }
         if (entry.needs === undefined) {
-            entries.push({ id: entry.id });
+            entries.push(forkValue !== undefined ? { id: entry.id, fork: forkValue } : { id: entry.id });
             continue;
         }
         if (Array.isArray(entry.needs)) {
@@ -50,29 +62,19 @@ export function parsePipelineStageEntries(raw, ctx) {
         if (typeof entry.needs !== "string" || !entry.needs) {
             throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a non-empty string`));
         }
-        entries.push({ id: entry.id, needs: entry.needs });
+        entries.push(forkValue !== undefined
+            ? { id: entry.id, needs: entry.needs, fork: forkValue }
+            : { id: entry.id, needs: entry.needs });
     }
     return entries;
 }
 function normalizeToEdges(entries) {
-    const edges = [];
-    for (let index = 0; index < entries.length; index++) {
-        const entry = entries[index];
-        if (typeof entry === "string") {
-            edges.push({
-                id: entry,
-                needs: index > 0 ? entries[index - 1] : null,
-                stageIndex: index,
-            });
-            continue;
-        }
-        edges.push({
-            id: entry.id,
-            needs: entry.needs ?? null,
-            stageIndex: index,
-        });
-    }
-    return edges;
+    return entries.map((entry, index) => ({
+        id: entry.id,
+        needs: entry.needs ?? null,
+        stageIndex: index,
+        ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
+    }));
 }
 function detectDuplicateIds(edges, ctx) {
     const seen = new Set();
@@ -160,7 +162,7 @@ function topologicalSort(edges) {
         indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
         children.get(edge.needs)?.push(edge.id);
     }
-    for (const [parent, childIds] of children) {
+    for (const [, childIds] of children) {
         childIds.sort((a, b) => (byId.get(a)?.stageIndex ?? 0) - (byId.get(b)?.stageIndex ?? 0));
     }
     const roots = edges
@@ -208,12 +210,26 @@ function buildResolvedPipelineDag(edges) {
         needs: edge.needs,
         ancestors: ancestorsById.get(edge.id) ?? [],
         stageIndex: edge.stageIndex,
+        ...(edge.fork !== undefined
+            ? { fork: { select: edge.fork.select, allow_none: edge.fork.allow_none ?? false } }
+            : {}),
     }));
     return { nodes, roots, childrenOf };
 }
-export function resolvePipelineDag(rawStages, ctx) {
-    const entries = parsePipelineStageEntries(rawStages, ctx);
-    const edges = normalizeToEdges(entries);
+function validateForkFields(edges, dag, ctx) {
+    for (const edge of edges) {
+        if (!edge.fork)
+            continue;
+        if (edge.fork.select !== "one" && edge.fork.select !== "subset") {
+            throw new Error(formatError(ctx, `stage "${edge.id}": fork.select must be "one" or "subset"${edge.fork.select === undefined ? " (missing)" : `, got "${String(edge.fork.select)}"`}`));
+        }
+        if ((dag.childrenOf[edge.id] ?? []).length === 0) {
+            throw new Error(formatError(ctx, `fork on stage "${edge.id}": no children in the DAG`));
+        }
+    }
+}
+export function resolvePipelineDagFromRefs(refs, ctx) {
+    const edges = normalizeToEdges(refs);
     detectDuplicateIds(edges, ctx);
     validateNeedsTargets(edges, ctx);
     detectCycle(edges, ctx);
@@ -222,8 +238,13 @@ export function resolvePipelineDag(rawStages, ctx) {
         .sort((a, b) => a.stageIndex - b.stageIndex)
         .map((edge) => edge.id);
     const dag = buildResolvedPipelineDag(edges);
+    validateForkFields(edges, dag, ctx);
     return { stages, dag };
 }
+export function resolvePipelineDag(rawStages, ctx) {
+    const entries = parsePipelineStageEntries(rawStages, ctx);
+    return resolvePipelineDagFromRefs(entries, ctx);
+}
 export function areResolvedDagsEquivalent(a, b) {
     const nodeIdsA = new Set(a.nodes.map((node) => node.id));
     const nodeIdsB = new Set(b.nodes.map((node) => node.id));
@@ -256,16 +277,13 @@ export function extractPipelineStageIds(rawStages) {
     const stageIds = [];
     for (const entry of rawStages) {
         if (typeof entry === "string") {
-            if (!entry)
-                return null;
-            stageIds.push(entry);
-            continue;
+            return null;
         }
         if (!isPlainObject(entry))
             return null;
         const keys = Object.keys(entry);
         for (const key of keys) {
-            if (!ALLOWED_STAGE_REF_KEYS.has(key))
+            if (!isAllowedPipelineStageEntryKey(key))
                 return null;
         }
         if (typeof entry.id !== "string" || !entry.id)

package/dist/config/scanCatalogPaths.d.ts

@@ -0,0 +1,4 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+export type CatalogPathKind = "pipeline" | "task";
+export declare function isExcluded(repoRelPath: string, exclude: string[] | undefined): boolean;
+export declare function scanCatalogPaths(manifest: LoadedManifest, kind: CatalogPathKind): Promise<string[]>;

package/dist/config/scanCatalogPaths.js

@@ -0,0 +1,83 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+function normalizeRepoRel(repoRelPath) {
+    return repoRelPath.replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+export function isExcluded(repoRelPath, exclude) {
+    if (!exclude || exclude.length === 0) {
+        return false;
+    }
+    const normalized = normalizeRepoRel(repoRelPath);
+    for (const entry of exclude) {
+        const prefix = normalizeRepoRel(entry);
+        if (normalized === prefix || normalized.startsWith(`${prefix}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function globPatternToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`);
+}
+function matchesPattern(basename, pattern) {
+    return globPatternToRegExp(pattern).test(basename);
+}
+async function walkDirectory(absDir) {
+    const files = [];
+    let entries;
+    try {
+        entries = await readdir(absDir, { withFileTypes: true, recursive: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const parentDir = entry.parentPath ?? absDir;
+        files.push(path.join(parentDir, entry.name));
+    }
+    return files;
+}
+async function expandCatalogEntry(projectRoot, entry, kind, pattern) {
+    const absPath = path.join(projectRoot, entry);
+    let entryStat;
+    try {
+        entryStat = await stat(absPath);
+    }
+    catch {
+        return [];
+    }
+    if (entryStat.isFile()) {
+        return [absPath];
+    }
+    if (!entryStat.isDirectory()) {
+        return [];
+    }
+    const files = await walkDirectory(absPath);
+    return files.filter((filePath) => matchesPattern(path.basename(filePath), pattern));
+}
+export async function scanCatalogPaths(manifest, kind) {
+    const { projectRoot, manifest: doc, patterns } = manifest;
+    const entries = kind === "pipeline" ? doc.catalog.pipelines : doc.catalog.tasks;
+    const pattern = kind === "pipeline" ? patterns.pipeline : patterns.task;
+    const exclude = doc.catalog.exclude;
+    const seen = new Set();
+    const resolved = [];
+    for (const entry of entries) {
+        const absPaths = await expandCatalogEntry(projectRoot, entry, kind, pattern);
+        for (const absPath of absPaths) {
+            const normalized = path.resolve(absPath);
+            if (seen.has(normalized))
+                continue;
+            const repoRel = normalizeRepoRel(path.relative(projectRoot, normalized));
+            if (isExcluded(repoRel, exclude))
+                continue;
+            seen.add(normalized);
+            resolved.push(normalized);
+        }
+    }
+    resolved.sort((a, b) => a.localeCompare(b));
+    return resolved;
+}

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>;