stageflow 0.2.0 → 0.8.0

package/dist/cli.js

@@ -4,34 +4,61 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { PiAgentAdapter } from "./agent/piAdapter.js";
+import { ARTIFACT_USAGE, runArtifactCommand } from "./cli/artifactCommand.js";
+import { ENVELOPE_USAGE, runEnvelopeCommand, } from "./cli/envelopeCommand.js";
+import { EXPORT_RUN_USAGE, runExportRunCommand, } from "./cli/exportRunCommand.js";
+import { INIT_USAGE, runInitCommand } from "./cli/initCommand.js";
 import { PROVIDERS_USAGE, runProvidersCommand } from "./cli/providersCommand.js";
 import { RUN_USAGE, runRunCommand } from "./cli/runCommand.js";
+import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
+import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
 import { VALIDATE_USAGE, runValidateCommand } from "./cli/validateCommand.js";
 import { createRunStore } from "./runstore/createStore.js";
+import { resolveStageflowContext } from "./project/resolveStageflowContext.js";
 import { exitForOutcome, runStageWorker } from "./runtime/stageWorker.js";
 import { SF_STAGE_WORKER } from "./runtime/stageWorkerProtocol.js";
 import { DEFAULT_PORT, startUiServer } from "./server/http.js";
+import { startMcpServer } from "./server/mcpHost.js";
+import { resolveMcpStateless } from "./mcp/server.js";
 const USAGE = `Usage:
-  sf run --task <path> --pipeline <name-or-path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>]
-  sf validate [--pipeline <name-or-path>] [--strict] [--json]
-  sf ui [--port ${DEFAULT_PORT}]
+  sf init
+  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]
+  sf validate [--pipeline <path>] [--task <path>] [--strict] [--json]
+  sf artifact read --run <runId> --path <relPath> [--out <file>]
+  sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]
+  sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]
+  sf ui [--port ${DEFAULT_PORT}] [--mcp-stateless]
+  sf mcp [--port ${DEFAULT_PORT}] [--mcp-stateless]
   sf providers list
   sf providers status [--provider <id>]
   sf providers detect
   sf providers source [get | set <pi_home|sf_owned>]
   sf providers login <providerId> [--type api_key|oauth] [--api-key-env <VAR>]
   sf providers logout <providerId>
+  sf skills list
+  sf skills install --from-path <dir> [--skill-name <name>]
+  sf skills install --from-zip <url-or-path> [--skill-name <name>] [--checksum sha256:<hex>]
   sf --help
 
 Stageflow (sf) runs YAML-defined automatic stage pipelines.
 
 Store backend: SF_STORE=sqlite only. SF_STORE=disk is rejected; disk-era .stageflow/runs trees import when the SQLite store is empty. Data under .stageflow/.
 
+${INIT_USAGE}
+
 ${RUN_USAGE}
 
 ${VALIDATE_USAGE}
 
-${PROVIDERS_USAGE}`;
+${ARTIFACT_USAGE}
+
+${ENVELOPE_USAGE}
+
+${EXPORT_RUN_USAGE}
+
+${PROVIDERS_USAGE}
+
+${SKILLS_USAGE}`;
 function parseArgs(argv) {
     const args = argv.slice(2);
     if (args.length === 0) {
@@ -44,7 +71,12 @@ function parseArgs(argv) {
     const command = args[0];
     if (command === "providers" ||
         command === "validate" ||
-        command === "run") {
+        command === "run" ||
+        command === "init" ||
+        command === "artifact" ||
+        command === "envelope" ||
+        command === "export-run" ||
+        command === "skills") {
         return { help: false, command };
     }
     if (args.includes("--help") || args.includes("-h")) {
@@ -54,6 +86,7 @@ function parseArgs(argv) {
     let pipeline;
     let port;
     let checkout;
+    let mcpStateless = false;
     for (let i = 1; i < args.length; i++) {
         if (args[i] === "--task") {
             task = args[++i];
@@ -75,8 +108,11 @@ function parseArgs(argv) {
                 throw new Error(`Invalid --port: ${raw}`);
             }
         }
+        else if (args[i] === "--mcp-stateless") {
+            mcpStateless = true;
+        }
     }
-    return { help: false, command, task, pipeline, port, checkout };
+    return { help: false, command, task, pipeline, port, checkout, mcpStateless };
 }
 export function parseRunStageArgs(argv) {
     let runId;
@@ -85,6 +121,7 @@ export function parseRunStageArgs(argv) {
     let resumeAnswer;
     let attempt;
     let sessionFilePath;
+    let operatorCwd;
     let operatorAgentDir;
     let skipGates = false;
     for (let i = 0; i < argv.length; i++) {
@@ -130,6 +167,12 @@ export function parseRunStageArgs(argv) {
                 throw new Error("Missing value for --session-file");
             }
         }
+        else if (argv[i] === "--operator-cwd") {
+            operatorCwd = argv[++i];
+            if (operatorCwd === undefined) {
+                throw new Error("Missing value for --operator-cwd");
+            }
+        }
         else if (argv[i] === "--operator-agent-dir") {
             operatorAgentDir = argv[++i];
             if (operatorAgentDir === undefined) {
@@ -143,6 +186,11 @@ export function parseRunStageArgs(argv) {
     if (!runId || !stageId) {
         throw new Error("Missing --run-id and/or --stage-id");
     }
+    const operatorCatalog = resolveOperatorCatalog({
+        flags: { operatorCwd, operatorAgentDir },
+        env: process.env,
+        defaultCwd: process.cwd(),
+    });
     return {
         runId,
         stageId,
@@ -151,9 +199,7 @@ export function parseRunStageArgs(argv) {
         attempt,
         sessionFilePath,
         skipGates,
-        ...(operatorAgentDir !== undefined
-            ? { operatorCatalog: { cwd: process.cwd(), agentDir: operatorAgentDir } }
-            : {}),
+        operatorCatalog,
     };
 }
 async function handleInternalRunStage(argv) {
@@ -194,22 +240,59 @@ async function main(argv) {
             console.log(USAGE);
             return argv.slice(2).length === 0 ? 1 : 0;
         }
-        const rootDir = process.cwd();
+        const ctx = await resolveStageflowContext(process.cwd());
+        if (parsed.command === "init") {
+            return runInitCommand(argv.slice(3), { cwd: ctx.invocationCwd });
+        }
         if (parsed.command === "validate") {
-            return runValidateCommand(argv.slice(3), { cwd: rootDir });
+            return runValidateCommand(argv.slice(3), { cwd: ctx.invocationCwd });
         }
         if (parsed.command === "run") {
-            return runRunCommand(argv.slice(3), { cwd: rootDir });
+            return runRunCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+                isGitProject: ctx.isGitProject,
+            });
+        }
+        if (parsed.command === "artifact") {
+            return runArtifactCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
+        if (parsed.command === "envelope") {
+            return runEnvelopeCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
+        if (parsed.command === "export-run") {
+            return runExportRunCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
         }
         if (parsed.command === "providers") {
-            return runProvidersCommand(argv.slice(3), rootDir);
+            return runProvidersCommand(argv.slice(3), ctx.invocationCwd);
+        }
+        if (parsed.command === "skills") {
+            return runSkillsCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
         }
-        const store = createRunStore({ rootDir });
+        const store = createRunStore({ rootDir: ctx.projectRoot });
         if (parsed.command === "ui") {
+            const mcpStateless = resolveMcpStateless({
+                mcpStateless: parsed.mcpStateless,
+            });
             const { url, mcpUrl } = await startUiServer({
                 agent: new PiAgentAdapter(),
                 store,
+                cwd: ctx.invocationCwd,
+                rootDir: ctx.projectRoot,
                 port: parsed.port,
+                mcpStateless,
             });
             console.log(`Operator console: ${url}`);
             console.log(`MCP endpoint: ${mcpUrl}`);
@@ -217,6 +300,22 @@ async function main(argv) {
             await new Promise(() => undefined);
             return 0;
         }
+        if (parsed.command === "mcp") {
+            const mcpStateless = resolveMcpStateless({
+                mcpStateless: parsed.mcpStateless,
+            });
+            const { mcpUrl } = await startMcpServer({
+                agent: new PiAgentAdapter(),
+                store,
+                cwd: ctx.invocationCwd,
+                rootDir: ctx.projectRoot,
+                port: parsed.port,
+                mcpStateless,
+            });
+            console.log(`MCP endpoint: ${mcpUrl}`);
+            await new Promise(() => undefined);
+            return 0;
+        }
         if (parsed.command === "internal") {
             const subArgs = argv.slice(3);
             const subcommand = subArgs[0];
@@ -235,16 +334,23 @@ async function main(argv) {
         return 1;
     }
 }
+function normalizeCliEntry(filePath) {
+    const resolved = path.resolve(filePath);
+    let canonical;
+    try {
+        canonical = realpathSync(resolved);
+    }
+    catch {
+        canonical = resolved;
+    }
+    return canonical.replace(/\.(?:[cm]?[jt]s)$/i, "");
+}
+export function sameCliEntry(a, b) {
+    return normalizeCliEntry(a) === normalizeCliEntry(b);
+}
 function isDirectCliInvocation() {
     const self = fileURLToPath(import.meta.url);
-    return process.argv.slice(1).some((arg) => {
-        try {
-            return realpathSync(path.resolve(arg)) === realpathSync(self);
-        }
-        catch {
-            return false;
-        }
-    });
+    return process.argv.slice(1).some((arg) => sameCliEntry(arg, self));
 }
 if (isDirectCliInvocation()) {
     main(process.argv)

package/dist/config/browseCatalog.d.ts

@@ -0,0 +1,45 @@
+import type { StageGateKind } from "../types/stage.js";
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import type { LoadIssue } from "./loadOutcome.js";
+import type { CatalogContext } from "./resolveCatalogContext.js";
+import { type CatalogManifestStatus, type StageflowContext } from "../project/resolveStageflowContext.js";
+export type TaskListing = {
+    path: string;
+    id: string;
+    goal: string;
+};
+export type PipelineStageListing = {
+    id: string;
+    gate_kinds?: StageGateKind[];
+    uses_path?: string;
+    inline?: boolean;
+};
+export type PipelineListing = {
+    path: string;
+    id: string;
+    stages: PipelineStageListing[];
+};
+export type CatalogBrowseWarning = {
+    path: string;
+    kind: "pipeline" | "task";
+    error: string;
+};
+export type CatalogBrowseResult = {
+    projectRoot: string | null;
+    manifest: LoadedManifest | null;
+    manifestStatus: CatalogManifestStatus;
+    issues: LoadIssue[];
+    pipelines: PipelineListing[];
+    tasks: TaskListing[];
+    models: string[];
+    warnings: CatalogBrowseWarning[];
+};
+export type CatalogScanPaths = {
+    pipelinePaths: string[];
+    taskPaths: string[];
+};
+export declare function getCatalogScanPaths(ctx: CatalogContext): Promise<CatalogScanPaths | null>;
+export declare function browseCatalog(invocationCwd: string | StageflowContext): Promise<CatalogBrowseResult>;
+export declare function listPipelinesForContext(ctx: CatalogContext): Promise<PipelineListing[]>;
+export declare function listTasksForContext(ctx: CatalogContext): Promise<TaskListing[]>;
+export declare function listModelsForContext(ctx: CatalogContext): Promise<string[]>;

package/dist/config/browseCatalog.js

@@ -0,0 +1,170 @@
+import path from "node:path";
+import { loadPipeline } from "./loadPipeline.js";
+import { loadTask } from "./loadTask.js";
+import { resolveStageflowContext, } from "../project/resolveStageflowContext.js";
+import { scanCatalogPaths } from "./scanCatalogPaths.js";
+const BAKED_MODEL_IDS = [
+    "anthropic/claude-sonnet-4-5",
+    "cursor/auto",
+    "cursor/composer-2-5",
+];
+function repoRelPath(projectRoot, absPath) {
+    return path.relative(projectRoot, absPath).replace(/\\/g, "/");
+}
+function mapStageListing(stage, source, projectRoot) {
+    const listing = {
+        id: stage.id,
+        ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+    };
+    if (source?.kind === "inline") {
+        listing.inline = true;
+    }
+    else if (source?.kind === "file") {
+        listing.uses_path = repoRelPath(projectRoot, source.path);
+    }
+    return listing;
+}
+function bakedModels() {
+    return [...BAKED_MODEL_IDS].sort((a, b) => a.localeCompare(b));
+}
+function catalogReadyFromStageflow(ctx) {
+    return ctx.isGitProject && ctx.manifestStatus === "ok" && ctx.manifest !== null;
+}
+function catalogReady(ctx) {
+    return ctx.manifestStatus === "ok" && ctx.projectRoot !== null && ctx.manifest !== null;
+}
+export async function getCatalogScanPaths(ctx) {
+    if (!catalogReady(ctx)) {
+        return null;
+    }
+    const [pipelinePaths, taskPaths] = await Promise.all([
+        scanCatalogPaths(ctx.manifest, "pipeline"),
+        scanCatalogPaths(ctx.manifest, "task"),
+    ]);
+    return { pipelinePaths, taskPaths };
+}
+async function listTasksFromManifest(projectRoot, manifest, warnings) {
+    const filePaths = await scanCatalogPaths(manifest, "task");
+    const listings = [];
+    for (const filePath of filePaths) {
+        try {
+            const task = await loadTask(filePath);
+            listings.push({
+                path: repoRelPath(projectRoot, filePath),
+                id: task.id,
+                goal: task.goal,
+            });
+        }
+        catch (err) {
+            warnings.push({
+                path: repoRelPath(projectRoot, filePath),
+                kind: "task",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    listings.sort((a, b) => {
+        const pathCmp = a.path.localeCompare(b.path);
+        if (pathCmp !== 0)
+            return pathCmp;
+        return a.id.localeCompare(b.id);
+    });
+    return listings;
+}
+async function listPipelinesFromManifest(projectRoot, manifest, warnings) {
+    const filePaths = await scanCatalogPaths(manifest, "pipeline");
+    const listings = [];
+    for (const filePath of filePaths) {
+        try {
+            const loaded = await loadPipeline(filePath, { cwd: projectRoot });
+            listings.push({
+                path: repoRelPath(projectRoot, filePath),
+                id: loaded.pipeline.id,
+                stages: loaded.stages.map((stage) => mapStageListing(stage, loaded.stageSources?.[stage.id], projectRoot)),
+            });
+        }
+        catch (err) {
+            warnings.push({
+                path: repoRelPath(projectRoot, filePath),
+                kind: "pipeline",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    listings.sort((a, b) => {
+        const pathCmp = a.path.localeCompare(b.path);
+        if (pathCmp !== 0)
+            return pathCmp;
+        return a.id.localeCompare(b.id);
+    });
+    return listings;
+}
+async function listModelsFromManifest(projectRoot, manifest) {
+    const models = new Set(BAKED_MODEL_IDS);
+    const filePaths = await scanCatalogPaths(manifest, "pipeline");
+    for (const filePath of filePaths) {
+        try {
+            const loaded = await loadPipeline(filePath, { cwd: projectRoot });
+            for (const stage of loaded.stages) {
+                if (stage.model.trim()) {
+                    models.add(stage.model);
+                }
+            }
+        }
+        catch {
+            // skip invalid pipelines
+        }
+    }
+    return [...models].sort((a, b) => a.localeCompare(b));
+}
+export async function browseCatalog(invocationCwd) {
+    const ctx = typeof invocationCwd === "string"
+        ? await resolveStageflowContext(invocationCwd)
+        : invocationCwd;
+    const base = {
+        projectRoot: ctx.isGitProject ? ctx.projectRoot : null,
+        manifest: ctx.manifest,
+        manifestStatus: ctx.manifestStatus,
+        issues: ctx.manifestIssues,
+    };
+    if (!catalogReadyFromStageflow(ctx)) {
+        return {
+            ...base,
+            pipelines: [],
+            tasks: [],
+            models: bakedModels(),
+            warnings: [],
+        };
+    }
+    const warnings = [];
+    const [pipelines, tasks, models] = await Promise.all([
+        listPipelinesFromManifest(ctx.projectRoot, ctx.manifest, warnings),
+        listTasksFromManifest(ctx.projectRoot, ctx.manifest, warnings),
+        listModelsFromManifest(ctx.projectRoot, ctx.manifest),
+    ]);
+    return {
+        ...base,
+        pipelines,
+        tasks,
+        models,
+        warnings,
+    };
+}
+export async function listPipelinesForContext(ctx) {
+    if (!catalogReady(ctx)) {
+        return [];
+    }
+    return listPipelinesFromManifest(ctx.projectRoot, ctx.manifest, []);
+}
+export async function listTasksForContext(ctx) {
+    if (!catalogReady(ctx)) {
+        return [];
+    }
+    return listTasksFromManifest(ctx.projectRoot, ctx.manifest, []);
+}
+export async function listModelsForContext(ctx) {
+    if (!catalogReady(ctx)) {
+        return bakedModels();
+    }
+    return listModelsFromManifest(ctx.projectRoot, ctx.manifest);
+}

package/dist/config/createPipeline.d.ts

@@ -1,11 +1,20 @@
+import type { StageGateKind } from "../types/stage.js";
 import type { PipelineListing } from "./listConfig.js";
+export type CreatePipelineStageInline = {
+    system_prompt: string;
+    model: string;
+    gate_kinds?: StageGateKind[];
+};
 export type CreatePipelineStageRef = {
     id: string;
     needs?: string;
+    uses?: string;
+    inline?: CreatePipelineStageInline;
 };
 export type CreatePipelineInput = {
+    directory: string;
     id: string;
-    stages: CreatePipelineStageRef[] | string[];
+    stages: CreatePipelineStageRef[];
 };
 export type CreatePipelineParseError = {
     ok: false;
@@ -20,7 +29,7 @@ export type CreatePipelineResult = {
     status: 400 | 409 | 422 | 500;
     error: string;
 };
-export declare function normalizeCreatePipelineStages(stages: CreatePipelineStageRef[] | string[]): CreatePipelineStageRef[];
+export declare function normalizeCreatePipelineStages(stages: CreatePipelineStageRef[]): CreatePipelineStageRef[];
 export declare function parseCreatePipelineBody(body: unknown): CreatePipelineInput | CreatePipelineParseError;
 export declare function pipelineConfigToYaml(pipeline: {
     id: string;
@@ -28,4 +37,4 @@ export declare function pipelineConfigToYaml(pipeline: {
 }, options: {
     format: "linear" | "dag";
 }): string;
-export declare function createPipeline(cwd: string, input: CreatePipelineInput): Promise<CreatePipelineResult>;
+export declare function createPipeline(projectRoot: string, input: CreatePipelineInput): Promise<CreatePipelineResult>;