stageflow 0.3.0 → 0.8.0

package/dist/cli/envelopeCommand.js

@@ -0,0 +1,285 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { buildHandoffDeliverable, isHandoffSkipped, } from "./handoffFormat.js";
+import { createRunStore } from "../runstore/createStore.js";
+export const ENVELOPE_USAGE = `Usage:
+  sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+export function parseEnvelopeArgs(args) {
+    if (args.length === 0) {
+        return { help: false, json: false, format: "envelope" };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, json: false, format: "envelope" };
+    }
+    const subcommand = args[0];
+    if (subcommand !== "get") {
+        throw new Error(`Unknown envelope subcommand: ${subcommand}`);
+    }
+    let runId;
+    let stageId;
+    let json = false;
+    let fromPath;
+    let detectStageId;
+    let format = "envelope";
+    let help = false;
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--run") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --run");
+            }
+            runId = value;
+        }
+        else if (arg === "--stage") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --stage");
+            }
+            stageId = value;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--from") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --from");
+            }
+            fromPath = value;
+        }
+        else if (arg === "--detect-stage") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --detect-stage");
+            }
+            detectStageId = value;
+        }
+        else if (arg === "--format") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --format");
+            }
+            if (value !== "envelope" && value !== "handoff") {
+                throw new Error(`Unknown --format value: ${value}`);
+            }
+            format = value;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return {
+        help,
+        subcommand,
+        runId,
+        stageId,
+        json,
+        fromPath,
+        detectStageId,
+        format,
+    };
+}
+function parseSfRunDocument(raw) {
+    const trimmed = raw.trim();
+    const jsonStart = trimmed.indexOf("{");
+    const doc = jsonStart >= 0 ? trimmed.slice(jsonStart) : trimmed;
+    let parsed;
+    try {
+        parsed = JSON.parse(doc);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse --from file JSON: ${message}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("--from file must contain a JSON object with runId");
+    }
+    const record = parsed;
+    const runId = typeof record.runId === "string" && record.runId.length > 0
+        ? record.runId
+        : undefined;
+    const runDir = typeof record.runDir === "string" && record.runDir.length > 0
+        ? record.runDir
+        : undefined;
+    return { runId, runDir, outcome: record.outcome, ok: record.ok };
+}
+function assertSfRunSucceededForHandoff(doc) {
+    if (doc.outcome !== "succeeded") {
+        const got = doc.outcome === undefined || doc.outcome === null
+            ? "<missing>"
+            : String(doc.outcome);
+        throw new Error(`pipeline outcome is not succeeded (got: ${got})`);
+    }
+    if (doc.ok !== true) {
+        const got = doc.ok === undefined || doc.ok === null ? "<missing>" : String(doc.ok);
+        throw new Error(`pipeline ok is not true (got: ${got})`);
+    }
+}
+function resolveRunContext(parsed, cwd, store) {
+    if (parsed.fromPath !== undefined) {
+        const resolved = path.resolve(cwd, parsed.fromPath);
+        let raw;
+        try {
+            raw = readFileSync(resolved, "utf8");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to read --from file: ${message}`);
+        }
+        const fromDoc = parseSfRunDocument(raw);
+        if (parsed.format === "handoff") {
+            assertSfRunSucceededForHandoff(fromDoc);
+        }
+        const runId = fromDoc.runId ?? parsed.runId;
+        if (!runId) {
+            throw new Error("--from file must contain a JSON object with runId");
+        }
+        return {
+            runId,
+            runDir: fromDoc.runDir ?? store.getWorkspaceDir(runId),
+        };
+    }
+    if (!parsed.runId) {
+        throw new Error("Missing --run (or --from <sf-run.json>)");
+    }
+    return {
+        runId: parsed.runId,
+        runDir: store.getWorkspaceDir(parsed.runId),
+    };
+}
+function isEnvelopeNotFoundError(err) {
+    return (err instanceof Error &&
+        err.message.startsWith("Envelope not found:"));
+}
+export const SYNTHETIC_SKIPPED_ENVELOPE = {
+    status: "skipped",
+    summary: "stage was fork-skipped",
+    artifacts: [],
+    fork_choice: null,
+};
+async function readStageEnvelopeOrSynthetic(store, runId, stageId) {
+    try {
+        return await store.readEnvelope(runId, stageId);
+    }
+    catch (err) {
+        if (!isEnvelopeNotFoundError(err)) {
+            throw err;
+        }
+        const detail = await store.readRun(runId);
+        const stage = detail.stages.find((s) => s.stage_id === stageId);
+        if (!stage) {
+            throw new Error(`Stage not found: ${stageId} in run ${runId}`);
+        }
+        if (stage.status === "skipped") {
+            return SYNTHETIC_SKIPPED_ENVELOPE;
+        }
+        throw new Error(`No envelope found for stage '${stageId}' in run '${runId}'`);
+    }
+}
+function formatEnvelopeHuman(stageId, envelope) {
+    return `[${stageId}] status=${envelope.status}  summary: ${envelope.summary}  artifacts: ${envelope.artifacts.length}`;
+}
+function formatHandoffHuman(result) {
+    if (result.skipped) {
+        return "handoff: skipped";
+    }
+    return `handoff: ${result.diagrams.length} diagram(s)`;
+}
+export async function runEnvelopeCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseEnvelopeArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(ENVELOPE_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(ENVELOPE_USAGE);
+        return 0;
+    }
+    if (parsed.subcommand !== "get") {
+        out.error("Missing envelope subcommand");
+        out.error(ENVELOPE_USAGE);
+        return 1;
+    }
+    if (!parsed.stageId) {
+        out.error("Missing --stage");
+        out.error(ENVELOPE_USAGE);
+        return 1;
+    }
+    const store = createRunStore({ rootDir: projectRoot });
+    let runContext;
+    try {
+        runContext = resolveRunContext(parsed, cwd, store);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(ENVELOPE_USAGE);
+        return 1;
+    }
+    try {
+        if (parsed.format === "handoff") {
+            if (parsed.detectStageId !== undefined) {
+                const detectEnvelope = await store.readEnvelope(runContext.runId, parsed.detectStageId);
+                if (isHandoffSkipped(detectEnvelope)) {
+                    const skipped = { skipped: true };
+                    if (parsed.json) {
+                        out.log(JSON.stringify(skipped));
+                    }
+                    else {
+                        out.log(formatHandoffHuman(skipped));
+                    }
+                    return 0;
+                }
+            }
+            const authorEnvelope = await readStageEnvelopeOrSynthetic(store, runContext.runId, parsed.stageId);
+            if (authorEnvelope.status === "skipped") {
+                throw new Error(`No envelope found for stage '${parsed.stageId}' in run '${runContext.runId}'`);
+            }
+            const handoff = buildHandoffDeliverable({
+                runId: runContext.runId,
+                runDir: runContext.runDir,
+                stageId: parsed.stageId,
+                envelope: authorEnvelope,
+            });
+            if (parsed.json) {
+                out.log(JSON.stringify(handoff));
+            }
+            else {
+                out.log(formatHandoffHuman(handoff));
+            }
+            return 0;
+        }
+        const envelope = await readStageEnvelopeOrSynthetic(store, runContext.runId, parsed.stageId);
+        if (parsed.json) {
+            out.log(JSON.stringify(envelope));
+        }
+        else {
+            out.log(formatEnvelopeHuman(parsed.stageId, envelope));
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+}

package/dist/cli/exportRunCommand.d.ts

@@ -0,0 +1,10 @@
+export declare const EXPORT_RUN_USAGE = "Usage:\n  sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]";
+export type ExportRunCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runExportRunCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<ExportRunCommandIo>;
+}): Promise<number>;

package/dist/cli/exportRunCommand.js

@@ -0,0 +1,150 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { projectRun } from "../projection/projectRun.js";
+import { createRunStore } from "../runstore/createStore.js";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+export const EXPORT_RUN_USAGE = `Usage:
+  sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseExportRunArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    let runId;
+    let fromPath;
+    let outPath;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--run") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --run");
+            }
+            runId = value;
+        }
+        else if (arg === "--from") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --from");
+            }
+            fromPath = value;
+        }
+        else if (arg === "--out") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --out");
+            }
+            outPath = value;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, runId, fromPath, outPath };
+}
+function resolveRunIdFromFile(fromPath, cwd) {
+    const resolved = path.resolve(cwd, fromPath);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(resolved, "utf8"));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read --from file: ${message}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("--from file must contain a JSON object with runId");
+    }
+    const runId = parsed.runId;
+    if (typeof runId !== "string" || runId.length === 0) {
+        throw new Error("--from file must contain a JSON object with runId");
+    }
+    return runId;
+}
+function resolveSafeOutPath(outPath, cwd) {
+    const segments = outPath.split(/[/\\]/);
+    if (segments.some((segment) => segment === "..")) {
+        throw new Error("path must not contain .. segments");
+    }
+    const resolved = path.resolve(cwd, outPath);
+    const cwdResolved = path.resolve(cwd);
+    if (!isInsideDir(resolved, cwdResolved)) {
+        throw new Error("output path must resolve under the current working directory");
+    }
+    return resolved;
+}
+function assertRunComplete(status, runId) {
+    if (status === "succeeded" || status === "failed") {
+        return;
+    }
+    throw new Error(`run is not complete: ${runId} (status: ${status})`);
+}
+export async function runExportRunCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseExportRunArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(EXPORT_RUN_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(EXPORT_RUN_USAGE);
+        return 0;
+    }
+    let runId = parsed.runId;
+    if (parsed.fromPath !== undefined) {
+        try {
+            runId = resolveRunIdFromFile(parsed.fromPath, cwd);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            out.error(message);
+            return 1;
+        }
+    }
+    if (!runId) {
+        out.error("Missing --run (or --from <sf-run.json>)");
+        out.error(EXPORT_RUN_USAGE);
+        return 1;
+    }
+    const store = createRunStore({ rootDir: projectRoot });
+    try {
+        const detail = await store.readRun(runId);
+        assertRunComplete(detail.status, runId);
+        const projection = projectRun(detail);
+        const json = JSON.stringify(projection, null, 2);
+        if (parsed.outPath !== undefined) {
+            const target = resolveSafeOutPath(parsed.outPath, cwd);
+            writeFileSync(target, json, "utf8");
+            out.error(`Wrote ${target}`);
+        }
+        else {
+            out.log(json);
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+}

package/dist/cli/handoffFormat.d.ts

@@ -0,0 +1,22 @@
+import type { StageEnvelope } from "../types/envelope.js";
+export type HandoffDiagram = {
+    diagram_type: string;
+    summary: string;
+    spec_path: string;
+};
+export type HandoffResult = {
+    skipped: true;
+} | {
+    skipped: false;
+    runId: string;
+    runDir: string;
+    stageId: string;
+    diagrams: HandoffDiagram[];
+};
+export declare function isHandoffSkipped(detectEnvelope: StageEnvelope): boolean;
+export declare function buildHandoffDeliverable(input: {
+    runId: string;
+    runDir: string;
+    stageId: string;
+    envelope: StageEnvelope;
+}): HandoffResult;

package/dist/cli/handoffFormat.js

@@ -0,0 +1,61 @@
+function absArtifactPath(runDir, rel) {
+    const base = runDir.replace(/\/+$/, "");
+    const normalized = rel.replace(/^\.\//, "");
+    return `${base}/${normalized}`;
+}
+export function isHandoffSkipped(detectEnvelope) {
+    return (Array.isArray(detectEnvelope.fork_choice) &&
+        detectEnvelope.fork_choice.length === 0);
+}
+export function buildHandoffDeliverable(input) {
+    const diagrams = buildDiagrams(input.runDir, input.envelope);
+    if (diagrams.length === 0) {
+        throw new Error(`no *.spec.json artifacts or payload.diagrams in envelope for stage '${input.stageId}'`);
+    }
+    return {
+        skipped: false,
+        runId: input.runId,
+        runDir: input.runDir,
+        stageId: input.stageId,
+        diagrams,
+    };
+}
+function buildDiagrams(runDir, envelope) {
+    const diagramsPayload = envelope.payload?.diagrams;
+    if (Array.isArray(diagramsPayload) && diagramsPayload.length > 0) {
+        return diagramsPayload.map((entry) => {
+            if (!entry || typeof entry !== "object") {
+                throw new Error("invalid diagram entry in payload.diagrams");
+            }
+            const diagram = entry;
+            const diagramType = diagram.diagram_type;
+            if (typeof diagramType !== "string" || diagramType.length === 0) {
+                throw new Error("payload.diagrams entry missing diagram_type");
+            }
+            const suffix = `${diagramType}.spec.json`;
+            const rel = envelope.artifacts.find((artifact) => artifact.endsWith(suffix));
+            if (!rel) {
+                throw new Error(`no artifact matching ${diagramType}.spec.json in envelope for stage`);
+            }
+            return {
+                diagram_type: diagramType,
+                summary: typeof diagram.summary === "string" ? diagram.summary : "",
+                spec_path: absArtifactPath(runDir, rel),
+            };
+        });
+    }
+    return envelope.artifacts
+        .filter((artifact) => /\.spec\.json$/.test(artifact))
+        .map((rel) => {
+        const match = rel.match(/([^/]+)\.spec\.json$/);
+        const diagramType = match?.[1];
+        if (!diagramType) {
+            throw new Error(`invalid spec artifact path: ${rel}`);
+        }
+        return {
+            diagram_type: diagramType,
+            summary: envelope.summary ?? "",
+            spec_path: absArtifactPath(runDir, rel),
+        };
+    });
+}

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 <path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
+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,6 +16,8 @@ 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;
@@ -22,5 +25,6 @@ export declare function runRunCommand(args: string[], options?: {
     isGitProject?: boolean;
     io?: Partial<RunCommandIo>;
     startRun?: StartRunFn;
+    store?: RunStore;
     env?: Record<string, string | undefined>;
 }): Promise<number>;

package/dist/cli/runCommand.js

@@ -8,17 +8,17 @@ 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 <path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
+  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;
@@ -29,6 +29,7 @@ function parseRunArgs(args) {
     let operatorCwd;
     let operatorAgentDir;
     let json = false;
+    let includeStages = false;
     let skipGates = false;
     let help = false;
     for (let i = 0; i < args.length; i++) {
@@ -95,6 +96,18 @@ function parseRunArgs(args) {
         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;
         }
@@ -108,6 +121,7 @@ function parseRunArgs(args) {
     return {
         help,
         json,
+        includeStages,
         skipGates,
         task,
         pipeline,
@@ -136,7 +150,12 @@ function defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog) {
 }
 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();
@@ -162,6 +181,10 @@ export async function runRunCommand(args, options = {}) {
         out.error(RUN_USAGE);
         return 1;
     }
+    if (parsed.includeStages && !parsed.json) {
+        out.error("error: --include stages requires --json");
+        return 1;
+    }
     const operatorCatalog = resolveOperatorCatalog({
         flags: {
             operatorCwd: parsed.operatorCwd,
@@ -180,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,
@@ -191,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>;