stageflow 0.2.0 → 0.8.0

package/dist/cli/initCommand.js

@@ -0,0 +1,71 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { findProjectRoot } from "../project/findProjectRoot.js";
+import { ensureGlobalHome } from "../project/globalHome.js";
+import { HELLO_PIPELINE_YAML, HELLO_TASK_YAML, STAGEFLOW_YAML, } from "./initTemplates.js";
+export const INIT_USAGE = `Usage:
+  sf init`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+const INIT_TARGETS = [
+    { relPath: "stageflow.yaml", content: STAGEFLOW_YAML },
+    { relPath: "pipelines/hello.pipeline.yaml", content: HELLO_PIPELINE_YAML },
+    { relPath: "tasks/hello.task.yaml", content: HELLO_TASK_YAML },
+];
+async function fileExists(absPath) {
+    try {
+        await access(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseInitArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    if (args[0].startsWith("-")) {
+        throw new Error(`Unknown flag: ${args[0]}`);
+    }
+    throw new Error(`Unexpected argument: ${args[0]}`);
+}
+export async function runInitCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const out = { ...defaultIo, ...options.io };
+    try {
+        const parsed = parseInitArgs(args);
+        if (parsed.help) {
+            out.error(INIT_USAGE);
+            return 0;
+        }
+        const initRoot = findProjectRoot(cwd) ?? path.resolve(cwd);
+        ensureGlobalHome();
+        for (const target of INIT_TARGETS) {
+            const absPath = path.join(initRoot, target.relPath);
+            if (await fileExists(absPath)) {
+                out.log(`Skipped ${target.relPath} (exists)`);
+                continue;
+            }
+            await mkdir(path.dirname(absPath), { recursive: true });
+            await writeFile(absPath, target.content, "utf8");
+            out.log(`Created ${target.relPath}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error
+            ? err.message
+            : typeof err === "string"
+                ? err
+                : "Init command failed";
+        out.error(message);
+        out.error(INIT_USAGE);
+        return 1;
+    }
+}

package/dist/cli/initTemplates.d.ts

@@ -0,0 +1,3 @@
+export declare const STAGEFLOW_YAML = "version: 1\ncatalog:\n  pipelines:\n    - pipelines\n  tasks:\n    - tasks\n  patterns:\n    pipeline: \"*.pipeline.yaml\"\n    task: \"*.task.yaml\"\n";
+export declare const HELLO_PIPELINE_YAML = "id: hello\nstages:\n  - id: hello\n    system_prompt: Say hello and emit a success envelope.\n    model: anthropic/claude-sonnet-4-5\n";
+export declare const HELLO_TASK_YAML = "id: hello\ngoal: Run the hello pipeline scaffold.\n";

package/dist/cli/initTemplates.js

@@ -0,0 +1,19 @@
+export const STAGEFLOW_YAML = `version: 1
+catalog:
+  pipelines:
+    - pipelines
+  tasks:
+    - tasks
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"
+`;
+export const HELLO_PIPELINE_YAML = `id: hello
+stages:
+  - id: hello
+    system_prompt: Say hello and emit a success envelope.
+    model: anthropic/claude-sonnet-4-5
+`;
+export const HELLO_TASK_YAML = `id: hello
+goal: Run the hello pipeline scaffold.
+`;

package/dist/cli/operatorCatalog.d.ts

@@ -0,0 +1,10 @@
+import type { OperatorCatalog } from "../runtime/stageAttemptBootstrap.js";
+export type OperatorCatalogFlags = {
+    operatorCwd?: string;
+    operatorAgentDir?: string;
+};
+export declare function resolveOperatorCatalog(input: {
+    flags: OperatorCatalogFlags;
+    env: Record<string, string | undefined>;
+    defaultCwd: string;
+}): OperatorCatalog;

package/dist/cli/operatorCatalog.js

@@ -0,0 +1,16 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+function nonempty(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+export function resolveOperatorCatalog(input) {
+    const cwd = nonempty(input.flags.operatorCwd) ??
+        nonempty(input.env.STAGEFLOW_OPERATOR_CWD) ??
+        input.defaultCwd;
+    const agentDir = nonempty(input.flags.operatorAgentDir) ??
+        nonempty(input.env.STAGEFLOW_OPERATOR_AGENT_DIR) ??
+        getAgentDir();
+    return { cwd, agentDir };
+}

package/dist/cli/runCommand.d.ts

@@ -1,6 +1,7 @@
+import type { RunStore } from "../runstore/port.js";
 import { type StartRunResult } from "../runtime/runManager.js";
 import { type CliRunReportIo } from "./runOutput.js";
-export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <name-or-path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>]";
+export declare const RUN_USAGE = "Usage:\n  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>]";
 export type RunCommandIo = CliRunReportIo;
 export type StartRunFn = (input: {
     task: string;
@@ -15,10 +16,15 @@ export declare function completeCliRun(started: Extract<StartRunResult, {
     ok: true;
 }>, io?: RunCommandIo, options?: {
     json?: boolean;
+    store?: RunStore;
+    includeStages?: boolean;
 }): Promise<number>;
 export declare function runRunCommand(args: string[], options?: {
     cwd?: string;
+    projectRoot?: string;
+    isGitProject?: boolean;
     io?: Partial<RunCommandIo>;
     startRun?: StartRunFn;
+    store?: RunStore;
     env?: Record<string, string | undefined>;
 }): Promise<number>;

package/dist/cli/runCommand.js

@@ -1,4 +1,3 @@
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { PiAgentAdapter } from "../agent/piAdapter.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { PipelineValidationError } from "../runtime/pipelineRunner.js";
@@ -6,19 +5,20 @@ import { RunManager } from "../runtime/runManager.js";
 import { readStageExecutionMode } from "../runtime/stageConcurrency.js";
 import { reportCliRun, } from "./runOutput.js";
 import { resolveCiIdentity } from "./ciIdentity.js";
+import { resolveOperatorCatalog } from "./operatorCatalog.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const RUN_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 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>]`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
 };
 function parseRunArgs(args) {
     if (args.length === 0) {
-        return { help: false, json: false, skipGates: false };
+        return { help: false, json: false, includeStages: false, skipGates: false };
     }
     if (args[0] === "--help" || args[0] === "-h") {
-        return { help: true, json: false, skipGates: false };
+        return { help: true, json: false, includeStages: false, skipGates: false };
     }
     let task;
     let pipeline;
@@ -26,7 +26,10 @@ function parseRunArgs(args) {
     let gitSha;
     let ciPrUrl;
     let ciJobUrl;
+    let operatorCwd;
+    let operatorAgentDir;
     let json = false;
+    let includeStages = false;
     let skipGates = false;
     let help = false;
     for (let i = 0; i < args.length; i++) {
@@ -76,9 +79,35 @@ function parseRunArgs(args) {
             }
             ciJobUrl = value;
         }
+        else if (arg === "--operator-cwd") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --operator-cwd");
+            }
+            operatorCwd = value;
+        }
+        else if (arg === "--operator-agent-dir") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --operator-agent-dir");
+            }
+            operatorAgentDir = value;
+        }
         else if (arg === "--json") {
             json = true;
         }
+        else if (arg === "--include") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --include");
+            }
+            if (value === "stages") {
+                includeStages = true;
+            }
+            else {
+                throw new Error(`Unknown --include value: ${value}`);
+            }
+        }
         else if (arg === "--skip-gates") {
             skipGates = true;
         }
@@ -89,16 +118,31 @@ function parseRunArgs(args) {
             throw new Error(`Unexpected argument: ${arg}`);
         }
     }
-    return { help, json, skipGates, task, pipeline, checkout, gitSha, ciPrUrl, ciJobUrl };
+    return {
+        help,
+        json,
+        includeStages,
+        skipGates,
+        task,
+        pipeline,
+        checkout,
+        gitSha,
+        ciPrUrl,
+        ciJobUrl,
+        operatorCwd,
+        operatorAgentDir,
+    };
 }
-function defaultStartRun(cwd) {
+function defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog) {
     return async (input) => {
-        const store = createRunStore({ rootDir: cwd });
+        const store = createRunStore({ rootDir: projectRoot });
         const manager = new RunManager({
             agent: new PiAgentAdapter(),
             store,
             cwd,
-            operatorCatalog: { cwd, agentDir: getAgentDir() },
+            projectRoot,
+            isGitProject,
+            operatorCatalog,
             executionMode: readStageExecutionMode(process.env, "process"),
         });
         return manager.startRun(input);
@@ -106,10 +150,17 @@ function defaultStartRun(cwd) {
 }
 export async function completeCliRun(started, io = defaultIo, options = {}) {
     const result = await started.done;
-    return reportCliRun({ kind: "completion", result }, { json: options.json, io });
+    return reportCliRun({ kind: "completion", result }, {
+        json: options.json,
+        io,
+        store: options.store,
+        includeStages: options.includeStages,
+    });
 }
 export async function runRunCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const isGitProject = options.isGitProject ?? false;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -130,7 +181,20 @@ export async function runRunCommand(args, options = {}) {
         out.error(RUN_USAGE);
         return 1;
     }
-    const startRun = options.startRun ?? defaultStartRun(cwd);
+    if (parsed.includeStages && !parsed.json) {
+        out.error("error: --include stages requires --json");
+        return 1;
+    }
+    const operatorCatalog = resolveOperatorCatalog({
+        flags: {
+            operatorCwd: parsed.operatorCwd,
+            operatorAgentDir: parsed.operatorAgentDir,
+        },
+        env: options.env ?? process.env,
+        defaultCwd: cwd,
+    });
+    const startRun = options.startRun ??
+        defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog);
     const identity = resolveCiIdentity({
         flags: {
             gitSha: parsed.gitSha,
@@ -139,6 +203,10 @@ export async function runRunCommand(args, options = {}) {
         },
         env: options.env ?? process.env,
     });
+    const store = options.store ??
+        (parsed.includeStages
+            ? createRunStore({ rootDir: projectRoot })
+            : undefined);
     try {
         const started = await startRun({
             task: parsed.task,
@@ -150,7 +218,11 @@ export async function runRunCommand(args, options = {}) {
         if (!started.ok) {
             return reportCliRun({ kind: "start-failure", started }, { json: parsed.json, io: out });
         }
-        return completeCliRun(started, out, { json: parsed.json });
+        return completeCliRun(started, out, {
+            json: parsed.json,
+            includeStages: parsed.includeStages,
+            store,
+        });
     }
     catch (err) {
         if (err instanceof PipelineValidationError) {

package/dist/cli/runOutput.d.ts

@@ -1,3 +1,4 @@
+import type { RunStore } from "../runstore/port.js";
 import type { PipelineRunResult } from "../runtime/pipelineRunner.js";
 import type { StartRunResult } from "../runtime/runManager.js";
 export type CliRunReportIo = {
@@ -16,4 +17,6 @@ export type CliRunReportEvent = {
 export declare function reportCliRun(event: CliRunReportEvent, options: {
     json?: boolean;
     io: CliRunReportIo;
-}): number;
+    store?: RunStore;
+    includeStages?: boolean;
+}): Promise<number>;

package/dist/cli/runOutput.js

@@ -1,3 +1,4 @@
+import { projectRun } from "../projection/projectRun.js";
 function stringify(payload) {
     return JSON.stringify(payload, null, 2);
 }
@@ -44,22 +45,22 @@ function formatStartFailureJson(started) {
     }
     return formatRunStartFailedJson(started);
 }
-function formatRunCompletionJson(result) {
+function baseRunCompletionPayload(result) {
     if (result.outcome === "succeeded") {
-        return stringify({
+        return {
             ok: true,
             outcome: "succeeded",
             runId: result.runId,
             runDir: result.runDir,
-        });
+        };
     }
     if (result.outcome === "waiting") {
-        return stringify({
+        return {
             ok: false,
             outcome: "waiting",
             runId: result.runId,
             runDir: result.runDir,
-        });
+        };
     }
     const payload = {
         ok: false,
@@ -69,7 +70,18 @@ function formatRunCompletionJson(result) {
     };
     if (result.reason !== undefined)
         payload.reason = result.reason;
-    return stringify(payload);
+    return payload;
+}
+function formatRunCompletionJson(result) {
+    return stringify(baseRunCompletionPayload(result));
+}
+async function formatRunCompletionJsonWithStages(result, store) {
+    const detail = await store.readRun(result.runId);
+    const projection = projectRun(detail);
+    return stringify({
+        ...baseRunCompletionPayload(result),
+        stages: projection.stages,
+    });
 }
 function writeStartFailureHuman(started, io) {
     const code = started.code ?? "error";
@@ -105,7 +117,7 @@ function exitCodeForRunOutcome(outcome) {
             return 1;
     }
 }
-export function reportCliRun(event, options) {
+export async function reportCliRun(event, options) {
     if (event.kind === "start-failure") {
         if (options.json) {
             options.io.log(formatStartFailureJson(event.started));
@@ -116,7 +128,23 @@ export function reportCliRun(event, options) {
         return 1;
     }
     if (options.json) {
-        options.io.log(formatRunCompletionJson(event.result));
+        if (options.includeStages) {
+            if (!options.store) {
+                options.io.error("error: --include stages requires an internal run store (report bug)");
+                return 1;
+            }
+            try {
+                options.io.log(await formatRunCompletionJsonWithStages(event.result, options.store));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                options.io.error(`failed to read run for --include stages: ${message}`);
+                return 1;
+            }
+        }
+        else {
+            options.io.log(formatRunCompletionJson(event.result));
+        }
     }
     else {
         writeCompletionHuman(event.result, options.io);

package/dist/cli/skillsCommand.d.ts

@@ -0,0 +1,16 @@
+export declare const SKILLS_USAGE = "Usage:\n  sf skills list\n  sf skills install --from-path <dir> [--skill-name <name>]\n  sf skills install --from-zip <url-or-path> [--skill-name <name>] [--checksum sha256:<hex>]";
+export type SkillsCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+    fetch: typeof globalThis.fetch;
+    runDoctor: (scriptPath: string, cwd: string) => number;
+};
+export declare function runSkillsCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<SkillsCommandIo>;
+}): Promise<number>;
+export declare function createStoredZip(files: {
+    name: string;
+    content: string | Buffer;
+}[]): Buffer;