stageflow 0.1.0

package/dist/config/createStage.js

@@ -0,0 +1,181 @@
+import { access, mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { STAGE_GATE_KINDS, } from "../types/stage.js";
+import { loadStage } from "./loadStage.js";
+import { readYamlObject } from "./readYamlObject.js";
+export const STAGE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function isGateKind(value) {
+    return STAGE_GATE_KINDS.includes(value);
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validateStageId(id) {
+    if (id.length === 0 || id.length > 64) {
+        return "id must be 1-64 characters";
+    }
+    if (!STAGE_ID_PATTERN.test(id)) {
+        return "id must be lowercase kebab-case";
+    }
+    return null;
+}
+function parseGateKinds(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return "invalid";
+    const kinds = [];
+    for (const item of raw) {
+        if (typeof item !== "string" || !isGateKind(item)) {
+            return "invalid";
+        }
+        kinds.push(item);
+    }
+    return kinds;
+}
+export function parseCreateStageBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "Request body must be an object" };
+    }
+    if ("payload_schema" in body) {
+        return { ok: false, status: 400, error: "payload_schema is not supported" };
+    }
+    if ("skill" in body) {
+        return { ok: false, status: 400, error: "skill is not supported" };
+    }
+    if (typeof body.id !== "string") {
+        return { ok: false, status: 400, error: "id is required" };
+    }
+    const idError = validateStageId(body.id);
+    if (idError) {
+        return { ok: false, status: 400, error: idError };
+    }
+    if (typeof body.system_prompt !== "string" || body.system_prompt.length === 0) {
+        return { ok: false, status: 400, error: "system_prompt is required" };
+    }
+    if (typeof body.model !== "string" || body.model.length === 0) {
+        return { ok: false, status: 400, error: "model is required" };
+    }
+    const gateKinds = parseGateKinds(body.gate_kinds);
+    if (gateKinds === "invalid") {
+        return {
+            ok: false,
+            status: 400,
+            error: `gate_kinds must be a non-empty array of: ${STAGE_GATE_KINDS.join(", ")}`,
+        };
+    }
+    return {
+        id: body.id,
+        system_prompt: body.system_prompt,
+        model: body.model,
+        ...(gateKinds ? { gate_kinds: gateKinds } : {}),
+    };
+}
+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 stageConfigToYaml(stage) {
+    const lines = [`id: ${stage.id}`];
+    if (stage.gate_kinds && stage.gate_kinds.length > 0) {
+        lines.push("gate_kinds:");
+        for (const kind of stage.gate_kinds) {
+            lines.push(`  - ${kind}`);
+        }
+    }
+    if (stage.system_prompt.includes("\n")) {
+        lines.push("system_prompt: |");
+        for (const line of stage.system_prompt.split("\n")) {
+            lines.push(`  ${line}`);
+        }
+    }
+    else {
+        lines.push(`system_prompt: ${formatInlineYamlScalar(stage.system_prompt)}`);
+    }
+    lines.push(`model: ${formatInlineYamlScalar(stage.model)}`);
+    lines.push("");
+    return lines.join("\n");
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findStageIdCollision(cwd, id, targetPath) {
+    if (await fileExists(targetPath)) {
+        return path.relative(cwd, targetPath);
+    }
+    const dir = path.join(cwd, "stages");
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".yaml"))
+            continue;
+        const filePath = path.join(dir, entry.name);
+        if (filePath === targetPath)
+            continue;
+        try {
+            const raw = await readYamlObject(filePath);
+            if (raw?.id === id) {
+                return path.relative(cwd, filePath);
+            }
+        }
+        catch {
+            // ignore unreadable files for collision scan
+        }
+    }
+    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);
+    if (collision) {
+        return {
+            ok: false,
+            status: 409,
+            error: `Stage id already exists (${collision})`,
+        };
+    }
+    try {
+        await mkdir(stagesDir, { recursive: true });
+        await writeFile(filePath, stageConfigToYaml(input), "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 500, error: message };
+    }
+    try {
+        const stage = await loadStage(filePath);
+        return {
+            ok: true,
+            stage: {
+                path: relPath,
+                id: stage.id,
+                used_by_pipeline_ids: [],
+                ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+            },
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 500, error: message };
+    }
+}

package/dist/config/listConfig.d.ts

@@ -0,0 +1,33 @@
+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[];
+};
+export type ValidStageListing = {
+    path: string;
+    id: string;
+    used_by_pipeline_ids: string[];
+    gate_kinds?: StageGateKind[];
+};
+export type BrokenStageListing = {
+    path: string;
+    error: string;
+    id?: string;
+    model?: string;
+    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[]>;

package/dist/config/listConfig.js

@@ -0,0 +1,195 @@
+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;
+}
+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 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 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));
+}

package/dist/config/listExtensions.d.ts

@@ -0,0 +1,26 @@
+export type PackageScope = "user" | "project";
+export type ExtensionFileScope = "user" | "project" | "temporary";
+export type PackageListing = {
+    source: string;
+    scope: PackageScope;
+    filtered: boolean;
+    installedPath?: string;
+};
+export type ExtensionFileListing = {
+    name: string;
+    path: string;
+    scope: ExtensionFileScope;
+    source: string;
+    origin: "package" | "top-level";
+    baseDir?: string;
+    enabled: boolean;
+};
+export type ExtensionCatalog = {
+    packages: PackageListing[];
+    extensions: ExtensionFileListing[];
+};
+export type ListExtensionsOptions = {
+    cwd: string;
+    agentDir: string;
+};
+export declare function listExtensions(options: ListExtensionsOptions): Promise<ExtensionCatalog>;

package/dist/config/listExtensions.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { DefaultPackageManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+function listingName(filePath) {
+    return path.basename(filePath).replace(/\.(ts|js)$/i, "");
+}
+export async function listExtensions(options) {
+    const settingsManager = SettingsManager.create(options.cwd, options.agentDir, {
+        projectTrusted: true,
+    });
+    const packageManager = new DefaultPackageManager({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        settingsManager,
+    });
+    const packages = packageManager.listConfiguredPackages().map((pkg) => ({
+        source: pkg.source,
+        scope: pkg.scope,
+        filtered: pkg.filtered,
+        ...(pkg.installedPath !== undefined
+            ? { installedPath: pkg.installedPath }
+            : {}),
+    }));
+    packages.sort((a, b) => {
+        const bySource = a.source.localeCompare(b.source);
+        if (bySource !== 0)
+            return bySource;
+        return a.scope.localeCompare(b.scope);
+    });
+    const resolved = await packageManager.resolve(async () => "skip");
+    const extensions = resolved.extensions
+        .filter((entry) => entry.enabled)
+        .map((entry) => ({
+        name: listingName(entry.path),
+        path: entry.path,
+        scope: entry.metadata.scope,
+        source: entry.metadata.source,
+        origin: entry.metadata.origin,
+        ...(entry.metadata.baseDir !== undefined
+            ? { baseDir: entry.metadata.baseDir }
+            : {}),
+        enabled: true,
+    }));
+    extensions.sort((a, b) => {
+        const byName = a.name.localeCompare(b.name);
+        if (byName !== 0)
+            return byName;
+        return a.path.localeCompare(b.path);
+    });
+    return { packages, extensions };
+}

package/dist/config/listSkills.d.ts

@@ -0,0 +1,29 @@
+export type SkillScope = "user" | "project" | "temporary";
+export type SkillListing = {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    scope: SkillScope;
+    source: string;
+    disableModelInvocation: boolean;
+};
+export type SkillDiagnostic = {
+    message: string;
+    path?: string;
+};
+export type SkillCatalog = {
+    skills: SkillListing[];
+    diagnostics: SkillDiagnostic[];
+};
+export type ListSkillsOptions = {
+    cwd: string;
+    agentDir: string;
+};
+export type ResolvedSkill = {
+    name: string;
+    filePath: string;
+    baseDir: string;
+};
+export declare function resolveSkillByName(name: string, options: ListSkillsOptions): Promise<ResolvedSkill | undefined>;
+export declare function listSkills(options: ListSkillsOptions): Promise<SkillCatalog>;

package/dist/config/listSkills.js

@@ -0,0 +1,55 @@
+import { access } from "node:fs/promises";
+import { DefaultResourceLoader, SettingsManager, } from "@earendil-works/pi-coding-agent";
+function toListing(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        filePath: skill.filePath,
+        baseDir: skill.baseDir,
+        scope: skill.sourceInfo.scope,
+        source: skill.sourceInfo.source,
+        disableModelInvocation: skill.disableModelInvocation,
+    };
+}
+async function openSkillCatalogLoader(options) {
+    const settingsManager = SettingsManager.create(options.cwd, options.agentDir, {
+        projectTrusted: true,
+    });
+    const loader = new DefaultResourceLoader({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        settingsManager,
+    });
+    await loader.reload();
+    return loader;
+}
+export async function resolveSkillByName(name, options) {
+    const loader = await openSkillCatalogLoader(options);
+    const match = loader.getSkills().skills.find((skill) => skill.name === name);
+    if (!match)
+        return undefined;
+    try {
+        await access(match.filePath);
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        name: match.name,
+        filePath: match.filePath,
+        baseDir: match.baseDir,
+    };
+}
+export async function listSkills(options) {
+    const loader = await openSkillCatalogLoader(options);
+    const { skills, diagnostics } = loader.getSkills();
+    return {
+        skills: skills
+            .map(toListing)
+            .sort((a, b) => a.name.localeCompare(b.name)),
+        diagnostics: diagnostics.map((d) => ({
+            message: d.message,
+            ...(d.path !== undefined ? { path: d.path } : {}),
+        })),
+    };
+}

package/dist/config/loadOutcome.d.ts

@@ -0,0 +1,27 @@
+import type { ValidationFindingCode } from "./validateCatalog.js";
+export type TaskLoadCode = "task.invalid_shape" | "task.load_error";
+export type LoadIssue = {
+    code: ValidationFindingCode;
+    message: string;
+    category: "pipeline";
+    pipelineId?: string;
+} | {
+    code: ValidationFindingCode;
+    message: string;
+    category: "stage";
+    stageId?: string;
+} | {
+    code: TaskLoadCode;
+    message: string;
+    category: "task";
+    taskId?: string;
+};
+export type LoadOutcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: LoadIssue[];
+};
+export declare function loadFailure<T>(issues: LoadIssue[]): LoadOutcome<T>;
+export declare function loadSuccess<T>(value: T): LoadOutcome<T>;

package/dist/config/loadOutcome.js

@@ -0,0 +1,6 @@
+export function loadFailure(issues) {
+    return { ok: false, issues };
+}
+export function loadSuccess(value) {
+    return { ok: true, value };
+}

package/dist/config/loadPipeline.d.ts

@@ -0,0 +1,25 @@
+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 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>;