stageflow 0.2.0 → 0.3.0

package/dist/config/createPipeline.js

@@ -1,10 +1,11 @@
-import { access, mkdir, readdir, writeFile } from "node:fs/promises";
+import { access, mkdir, readdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { STAGE_ID_PATTERN } from "./createStage.js";
-import { loadPipeline } from "./loadPipeline.js";
-import { loadStage } from "./loadStage.js";
+import { inferIdFromUsesPath, normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
 import { readYamlObject } from "./readYamlObject.js";
-import { resolvePipelineDag } from "./resolvePipelineDag.js";
+import { resolvePipelineDagFromRefs } from "./resolvePipelineDag.js";
+import { validatePipeline } from "./validateCatalog.js";
+import { loadPipelineOutcome } from "./loadPipeline.js";
 function isPlainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -17,24 +18,136 @@ function validatePipelineId(id) {
     }
     return null;
 }
+function defaultUsesPath(stageId) {
+    return `./${stageId}.yaml`;
+}
 export function normalizeCreatePipelineStages(stages) {
-    if (stages.length > 0 && typeof stages[0] === "string") {
-        return stages.map((id) => ({ id }));
+    return stages.map((stage) => ({
+        ...stage,
+        uses: stage.uses ?? (stage.inline ? undefined : defaultUsesPath(stage.id)),
+    }));
+}
+function stageRefToRaw(ref) {
+    const raw = { id: ref.id };
+    if (ref.needs !== undefined)
+        raw.needs = ref.needs;
+    if (ref.uses !== undefined)
+        raw.uses = ref.uses;
+    if (ref.inline) {
+        raw.system_prompt = ref.inline.system_prompt;
+        raw.model = ref.inline.model;
+        if (ref.inline.gate_kinds !== undefined) {
+            raw.gate_kinds = ref.inline.gate_kinds;
+        }
+    }
+    return raw;
+}
+function toAuthoringRawEntries(stages, declaringPath) {
+    return stages.map((stage) => ({
+        raw: stageRefToRaw(stage),
+        declaringPath,
+    }));
+}
+function normalizedToCreateRefs(entries) {
+    return entries.map((entry) => {
+        const ref = { id: entry.id };
+        if (entry.needs !== undefined)
+            ref.needs = entry.needs;
+        if (entry.body.kind === "uses") {
+            ref.uses = entry.body.path;
+        }
+        else {
+            const raw = entry.body.raw;
+            ref.inline = {
+                system_prompt: String(raw.system_prompt ?? ""),
+                model: String(raw.model ?? ""),
+                ...(Array.isArray(raw.gate_kinds)
+                    ? { gate_kinds: raw.gate_kinds }
+                    : {}),
+            };
+        }
+        return ref;
+    });
+}
+function normalizeAuthoringStages(stages, ctx) {
+    const prepared = normalizeCreatePipelineStages(stages);
+    const normalizeOutcome = normalizePipelineStageEntries(toAuthoringRawEntries(prepared, ctx.path), ctx);
+    if (!normalizeOutcome.ok) {
+        return {
+            ok: false,
+            status: 422,
+            error: normalizeOutcome.issues[0]?.message ?? "Invalid pipeline stages",
+        };
+    }
+    try {
+        resolvePipelineDagFromRefs(toWiringRefs(normalizeOutcome.value), ctx);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 422, error: message };
+    }
+    return { ok: true, stages: normalizedToCreateRefs(normalizeOutcome.value) };
+}
+function parseInlineBody(entry, index) {
+    if (typeof entry.system_prompt !== "string" || entry.system_prompt.length === 0) {
+        return {
+            ok: false,
+            status: 400,
+            error: `stages[${index}].system_prompt is required for inline stage`,
+        };
+    }
+    if (typeof entry.model !== "string" || entry.model.length === 0) {
+        return {
+            ok: false,
+            status: 400,
+            error: `stages[${index}].model is required for inline stage`,
+        };
     }
-    return stages;
+    const inline = {
+        system_prompt: entry.system_prompt,
+        model: entry.model,
+    };
+    if (entry.gate_kinds !== undefined) {
+        if (!Array.isArray(entry.gate_kinds)) {
+            return {
+                ok: false,
+                status: 400,
+                error: `stages[${index}].gate_kinds must be an array`,
+            };
+        }
+        inline.gate_kinds = entry.gate_kinds;
+    }
+    return inline;
 }
 function parseStageEntry(entry, index) {
+    if (typeof entry === "string") {
+        const hint = entry
+            ? `bare string stage refs are not supported; use { id: "${entry}", uses: "./${entry}.yaml" } or inline body`
+            : `bare string stage refs are not supported; use { id: "…", uses: "./….yaml" } or inline body`;
+        return {
+            ok: false,
+            status: 400,
+            error: `stages[${index}]: ${hint}`,
+        };
+    }
     if (!isPlainObject(entry)) {
         return {
             ok: false,
             status: 400,
-            error: `stages[${index}] must be a string or object with id`,
+            error: `stages[${index}] must be an object with id`,
         };
     }
-    if (typeof entry.id !== "string") {
+    let id = typeof entry.id === "string" ? entry.id : undefined;
+    const uses = typeof entry.uses === "string" && entry.uses.trim() ? entry.uses : undefined;
+    if (!id && uses) {
+        const inferred = inferIdFromUsesPath(uses);
+        if (inferred)
+            id = inferred;
+    }
+    if (!id) {
         return { ok: false, status: 400, error: `stages[${index}].id is required` };
     }
-    const ref = { id: entry.id };
+    const ref = { id };
     if (entry.needs !== undefined) {
         if (typeof entry.needs !== "string") {
             return {
@@ -45,12 +158,45 @@ function parseStageEntry(entry, index) {
         }
         ref.needs = entry.needs;
     }
+    if (entry.uses !== undefined) {
+        if (typeof entry.uses !== "string" || !entry.uses.trim()) {
+            return {
+                ok: false,
+                status: 400,
+                error: `stages[${index}].uses must be a non-empty string`,
+            };
+        }
+        ref.uses = entry.uses;
+    }
+    else if (uses) {
+        ref.uses = uses;
+    }
+    const hasInlineFields = entry.system_prompt !== undefined ||
+        entry.model !== undefined ||
+        entry.gate_kinds !== undefined;
+    if (hasInlineFields) {
+        const inline = parseInlineBody(entry, index);
+        if ("ok" in inline)
+            return inline;
+        ref.inline = inline;
+    }
     return ref;
 }
 export function parseCreatePipelineBody(body) {
     if (!isPlainObject(body)) {
         return { ok: false, status: 400, error: "Request body must be an object" };
     }
+    if (typeof body.directory !== "string" || !body.directory.trim()) {
+        return { ok: false, status: 400, error: "directory is required" };
+    }
+    const directory = body.directory.trim().replace(/\\/g, "/");
+    if (directory.endsWith(".yaml") || directory.endsWith(".yml")) {
+        return {
+            ok: false,
+            status: 400,
+            error: "directory must be a catalog folder, not a pipeline file path",
+        };
+    }
     if (typeof body.id !== "string") {
         return { ok: false, status: 400, error: "id is required" };
     }
@@ -64,32 +210,6 @@ export function parseCreatePipelineBody(body) {
     if (body.stages.length === 0) {
         return { ok: false, status: 400, error: "stages must be a non-empty array" };
     }
-    let hasString = false;
-    let hasObject = false;
-    for (const entry of body.stages) {
-        if (typeof entry === "string") {
-            hasString = true;
-        }
-        else if (isPlainObject(entry)) {
-            hasObject = true;
-        }
-        else {
-            return { ok: false, status: 400, error: "stages must be an array of strings" };
-        }
-    }
-    if (hasString && hasObject) {
-        return {
-            ok: false,
-            status: 400,
-            error: "stages must be either all strings or all objects",
-        };
-    }
-    if (hasString) {
-        return {
-            id: body.id,
-            stages: body.stages,
-        };
-    }
     const refs = [];
     for (let index = 0; index < body.stages.length; index++) {
         const parsed = parseStageEntry(body.stages[index], index);
@@ -99,23 +219,54 @@ export function parseCreatePipelineBody(body) {
         refs.push(parsed);
     }
     return {
+        directory,
         id: body.id,
         stages: refs,
     };
 }
+function formatInlineYamlScalar(value) {
+    if (value.includes("\n") ||
+        /[:#"'&*!|>@`[\]{}]/.test(value) ||
+        value.startsWith(" ") ||
+        value.endsWith(" ") ||
+        value.startsWith("-") ||
+        value.startsWith("?")) {
+        return JSON.stringify(value);
+    }
+    return value;
+}
 export function pipelineConfigToYaml(pipeline, options) {
     const lines = [`id: ${pipeline.id}`, "stages:"];
-    if (options.format === "linear") {
-        for (const stage of pipeline.stages) {
-            lines.push(`  - ${stage.id}`);
-        }
-    }
-    else {
-        for (const stage of pipeline.stages) {
+    for (const stage of pipeline.stages) {
+        if (options.format === "linear" && !stage.needs && !stage.inline && stage.uses) {
             lines.push(`  - id: ${stage.id}`);
-            if (stage.needs) {
-                lines.push(`    needs: ${stage.needs}`);
+            lines.push(`    uses: ${stage.uses}`);
+            continue;
+        }
+        lines.push(`  - id: ${stage.id}`);
+        if (stage.needs) {
+            lines.push(`    needs: ${stage.needs}`);
+        }
+        if (stage.inline) {
+            if (stage.inline.gate_kinds && stage.inline.gate_kinds.length > 0) {
+                lines.push("    gate_kinds:");
+                for (const kind of stage.inline.gate_kinds) {
+                    lines.push(`      - ${kind}`);
+                }
+            }
+            if (stage.inline.system_prompt.includes("\n")) {
+                lines.push("    system_prompt: |");
+                for (const line of stage.inline.system_prompt.split("\n")) {
+                    lines.push(`      ${line}`);
+                }
             }
+            else {
+                lines.push(`    system_prompt: ${formatInlineYamlScalar(stage.inline.system_prompt)}`);
+            }
+            lines.push(`    model: ${formatInlineYamlScalar(stage.inline.model)}`);
+        }
+        else if (stage.uses) {
+            lines.push(`    uses: ${stage.uses}`);
         }
     }
     lines.push("");
@@ -130,14 +281,21 @@ async function fileExists(filePath) {
         return false;
     }
 }
-async function findPipelineIdCollision(cwd, id, targetPath) {
+function resolveDirectory(projectRoot, directory) {
+    const absDirectory = path.resolve(projectRoot, directory);
+    const rel = path.relative(projectRoot, absDirectory);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return null;
+    }
+    return absDirectory;
+}
+async function findPipelineIdCollision(pipelineDirectory, projectRoot, id, targetPath) {
     if (await fileExists(targetPath)) {
-        return path.relative(cwd, targetPath);
+        return path.relative(projectRoot, targetPath);
     }
-    const dir = path.join(cwd, "pipelines");
     let entries;
     try {
-        entries = await readdir(dir, { withFileTypes: true });
+        entries = await readdir(pipelineDirectory, { withFileTypes: true });
     }
     catch {
         return null;
@@ -145,13 +303,13 @@ async function findPipelineIdCollision(cwd, id, targetPath) {
     for (const entry of entries) {
         if (!entry.isFile() || !entry.name.endsWith(".yaml"))
             continue;
-        const filePath = path.join(dir, entry.name);
+        const filePath = path.join(pipelineDirectory, entry.name);
         if (filePath === targetPath)
             continue;
         try {
             const raw = await readYamlObject(filePath);
             if (raw?.id === id) {
-                return path.relative(cwd, filePath);
+                return path.relative(projectRoot, filePath);
             }
         }
         catch {
@@ -160,7 +318,7 @@ async function findPipelineIdCollision(cwd, id, targetPath) {
     }
     return null;
 }
-async function validateStageReferences(cwd, stages) {
+async function validateStageReferences(pipelineDirectory, stages) {
     const seen = new Set();
     for (const stage of stages) {
         if (seen.has(stage.id)) {
@@ -172,44 +330,77 @@ async function validateStageReferences(cwd, stages) {
         }
         seen.add(stage.id);
     }
-    const stagesDir = path.join(cwd, "stages");
+    const inlineCount = stages.filter((stage) => stage.inline).length;
+    if (inlineCount > 0 && stages.length > 1) {
+        return {
+            ok: false,
+            status: 422,
+            error: "Inline stage bodies are supported for single-stage pipelines only",
+        };
+    }
     for (const stage of stages) {
-        const stagePath = path.join(stagesDir, `${stage.id}.yaml`);
-        try {
-            await loadStage(stagePath);
-        }
-        catch {
+        if (stage.inline)
+            continue;
+        const uses = stage.uses ?? defaultUsesPath(stage.id);
+        const stagePath = path.resolve(pipelineDirectory, uses);
+        if (!(await fileExists(stagePath))) {
             return {
                 ok: false,
                 status: 422,
-                error: "one or more selected Stages no longer exist",
+                error: `missing stage file for "${stage.id}" at ${uses}`,
             };
         }
     }
     return { ok: true };
 }
-function buildResolverInput(input, normalized) {
-    if (input.stages.length > 0 && typeof input.stages[0] === "string") {
-        return input.stages;
-    }
-    return normalized.map((ref) => ref.needs ? { id: ref.id, needs: ref.needs } : { id: ref.id });
-}
-function usesDagYaml(input, normalized) {
-    if (input.stages.length > 0 && typeof input.stages[0] !== "string") {
-        return true;
-    }
+function usesDagYaml(normalized) {
     return normalized.some((ref) => ref.needs !== undefined);
 }
-export async function createPipeline(cwd, input) {
-    const normalized = normalizeCreatePipelineStages(input.stages);
-    const stageValidation = await validateStageReferences(cwd, normalized);
+function buildPipelineListing(projectRoot, relPath, loaded) {
+    return {
+        path: relPath,
+        id: loaded.pipeline.id,
+        stages: loaded.stages.map((stage) => {
+            const source = loaded.stageSources?.[stage.id];
+            const listing = {
+                id: stage.id,
+                ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+            };
+            if (source?.kind === "inline") {
+                return { ...listing, inline: true };
+            }
+            if (source?.kind === "file") {
+                return {
+                    ...listing,
+                    uses_path: path.relative(projectRoot, source.path).replace(/\\/g, "/"),
+                };
+            }
+            return listing;
+        }),
+    };
+}
+export async function createPipeline(projectRoot, input) {
+    const pipelineDirectory = resolveDirectory(projectRoot, input.directory);
+    if (!pipelineDirectory) {
+        return {
+            ok: false,
+            status: 400,
+            error: "directory must be inside the project root",
+        };
+    }
+    const filePath = path.join(pipelineDirectory, `${input.id}.pipeline.yaml`);
+    const relPath = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+    const validationCtx = { pipelineId: input.id, path: relPath };
+    const normalizedOutcome = normalizeAuthoringStages(input.stages, validationCtx);
+    if (!normalizedOutcome.ok) {
+        return normalizedOutcome;
+    }
+    const normalized = normalizedOutcome.stages;
+    const stageValidation = await validateStageReferences(pipelineDirectory, normalized);
     if (!stageValidation.ok) {
         return stageValidation;
     }
-    const pipelinesDir = path.join(cwd, "pipelines");
-    const filePath = path.join(pipelinesDir, `${input.id}.yaml`);
-    const relPath = path.relative(cwd, filePath);
-    const collision = await findPipelineIdCollision(cwd, input.id, filePath);
+    const collision = await findPipelineIdCollision(pipelineDirectory, projectRoot, input.id, filePath);
     if (collision) {
         return {
             ok: false,
@@ -217,39 +408,40 @@ export async function createPipeline(cwd, input) {
             error: `Pipeline id already exists (${collision})`,
         };
     }
-    const resolverInput = buildResolverInput(input, normalized);
-    try {
-        resolvePipelineDag(resolverInput, { pipelineId: input.id, path: relPath });
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { ok: false, status: 422, error: message };
-    }
-    const yamlFormat = usesDagYaml(input, normalized) ? "dag" : "linear";
+    const yamlFormat = usesDagYaml(normalized) ? "dag" : "linear";
     try {
-        await mkdir(pipelinesDir, { recursive: true });
+        await mkdir(pipelineDirectory, { recursive: true });
         await writeFile(filePath, pipelineConfigToYaml({ id: input.id, stages: normalized }, { format: yamlFormat }), "utf8");
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { ok: false, status: 500, error: message };
     }
-    try {
-        const loaded = await loadPipeline(filePath, { cwd });
+    const validation = await validatePipeline(relPath, {
+        cwd: projectRoot,
+        validateStages: true,
+        strict: true,
+    });
+    if (!validation.ok) {
+        await unlink(filePath).catch(() => { });
+        const errorFinding = validation.findings.find((finding) => finding.severity === "error");
         return {
-            ok: true,
-            pipeline: {
-                path: relPath,
-                id: loaded.pipeline.id,
-                stages: loaded.stages.map((stage) => ({
-                    id: stage.id,
-                    ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
-                })),
-            },
+            ok: false,
+            status: 422,
+            error: errorFinding?.message ?? "Pipeline validation failed",
         };
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { ok: false, status: 500, error: message };
+    const loadOutcome = await loadPipelineOutcome(relPath, { cwd: projectRoot });
+    if (!loadOutcome.ok) {
+        await unlink(filePath).catch(() => { });
+        return {
+            ok: false,
+            status: 500,
+            error: loadOutcome.issues[0]?.message ?? "Failed to load created pipeline",
+        };
     }
+    return {
+        ok: true,
+        pipeline: buildPipelineListing(projectRoot, relPath, loadOutcome.value),
+    };
 }

package/dist/config/createStage.d.ts

@@ -1,12 +1,18 @@
 import { type StageGateKind } from "../types/stage.js";
-import type { ValidStageListing } from "./listConfig.js";
 export declare const STAGE_ID_PATTERN: RegExp;
 export type CreateStageInput = {
+    pipeline_directory: string;
+    filename: string;
     id: string;
     system_prompt: string;
     model: string;
     gate_kinds?: StageGateKind[];
 };
+export type CreatedStageListing = {
+    path: string;
+    id: string;
+    gate_kinds?: StageGateKind[];
+};
 export type CreateStageParseError = {
     ok: false;
     status: 400;
@@ -14,12 +20,12 @@ export type CreateStageParseError = {
 };
 export type CreateStageResult = {
     ok: true;
-    stage: ValidStageListing;
+    stage: CreatedStageListing;
 } | {
     ok: false;
     status: 400 | 409 | 500;
     error: string;
 };
 export declare function parseCreateStageBody(body: unknown): CreateStageInput | CreateStageParseError;
-export declare function stageConfigToYaml(stage: CreateStageInput): string;
-export declare function createStage(cwd: string, input: CreateStageInput): Promise<CreateStageResult>;
+export declare function stageConfigToYaml(stage: Omit<CreateStageInput, "pipeline_directory" | "filename">): string;
+export declare function createStage(projectRoot: string, input: CreateStageInput): Promise<CreateStageResult>;

package/dist/config/createStage.js

@@ -43,6 +43,16 @@ export function parseCreateStageBody(body) {
     if ("skill" in body) {
         return { ok: false, status: 400, error: "skill is not supported" };
     }
+    if (typeof body.pipeline_directory !== "string" || !body.pipeline_directory.trim()) {
+        return { ok: false, status: 400, error: "pipeline_directory is required" };
+    }
+    if (typeof body.filename !== "string" || !body.filename.trim()) {
+        return { ok: false, status: 400, error: "filename is required" };
+    }
+    const filename = body.filename.trim().replace(/\\/g, "/");
+    if (!filename.endsWith(".yaml") && !filename.endsWith(".yml")) {
+        return { ok: false, status: 400, error: "filename must end with .yaml" };
+    }
     if (typeof body.id !== "string") {
         return { ok: false, status: 400, error: "id is required" };
     }
@@ -65,6 +75,8 @@ export function parseCreateStageBody(body) {
         };
     }
     return {
+        pipeline_directory: body.pipeline_directory.trim().replace(/\\/g, "/"),
+        filename,
         id: body.id,
         system_prompt: body.system_prompt,
         model: body.model,
@@ -112,14 +124,21 @@ async function fileExists(filePath) {
         return false;
     }
 }
-async function findStageIdCollision(cwd, id, targetPath) {
+function resolvePipelineDirectory(projectRoot, pipelineDirectory) {
+    const absDirectory = path.resolve(projectRoot, pipelineDirectory);
+    const rel = path.relative(projectRoot, absDirectory);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return null;
+    }
+    return absDirectory;
+}
+async function findStageIdCollision(pipelineDirectory, projectRoot, id, targetPath) {
     if (await fileExists(targetPath)) {
-        return path.relative(cwd, targetPath);
+        return path.relative(projectRoot, targetPath);
     }
-    const dir = path.join(cwd, "stages");
     let entries;
     try {
-        entries = await readdir(dir, { withFileTypes: true });
+        entries = await readdir(pipelineDirectory, { withFileTypes: true });
     }
     catch {
         return null;
@@ -127,13 +146,13 @@ async function findStageIdCollision(cwd, id, targetPath) {
     for (const entry of entries) {
         if (!entry.isFile() || !entry.name.endsWith(".yaml"))
             continue;
-        const filePath = path.join(dir, entry.name);
+        const filePath = path.join(pipelineDirectory, entry.name);
         if (filePath === targetPath)
             continue;
         try {
             const raw = await readYamlObject(filePath);
             if (raw?.id === id) {
-                return path.relative(cwd, filePath);
+                return path.relative(projectRoot, filePath);
             }
         }
         catch {
@@ -142,11 +161,18 @@ async function findStageIdCollision(cwd, id, targetPath) {
     }
     return null;
 }
-export async function createStage(cwd, input) {
-    const stagesDir = path.join(cwd, "stages");
-    const filePath = path.join(stagesDir, `${input.id}.yaml`);
-    const relPath = path.relative(cwd, filePath);
-    const collision = await findStageIdCollision(cwd, input.id, filePath);
+export async function createStage(projectRoot, input) {
+    const pipelineDirectory = resolvePipelineDirectory(projectRoot, input.pipeline_directory);
+    if (!pipelineDirectory) {
+        return {
+            ok: false,
+            status: 400,
+            error: "pipeline_directory must be inside the project root",
+        };
+    }
+    const filePath = path.join(pipelineDirectory, path.basename(input.filename));
+    const relPath = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+    const collision = await findStageIdCollision(pipelineDirectory, projectRoot, input.id, filePath);
     if (collision) {
         return {
             ok: false,
@@ -155,8 +181,13 @@ export async function createStage(cwd, input) {
         };
     }
     try {
-        await mkdir(stagesDir, { recursive: true });
-        await writeFile(filePath, stageConfigToYaml(input), "utf8");
+        await mkdir(pipelineDirectory, { recursive: true });
+        await writeFile(filePath, stageConfigToYaml({
+            id: input.id,
+            system_prompt: input.system_prompt,
+            model: input.model,
+            ...(input.gate_kinds ? { gate_kinds: input.gate_kinds } : {}),
+        }), "utf8");
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -169,7 +200,6 @@ export async function createStage(cwd, input) {
             stage: {
                 path: relPath,
                 id: stage.id,
-                used_by_pipeline_ids: [],
                 ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
             },
         };