stageflow 0.2.0 → 0.8.0

package/dist/cli/artifactCommand.js

@@ -0,0 +1,120 @@
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { readRunArtifact } from "../mcp/readArtifact.js";
+import { createRunStore } from "../runstore/createStore.js";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+export const ARTIFACT_USAGE = `Usage:
+  sf artifact read --run <runId> --path <relPath> [--out <file>]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseArtifactArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    const subcommand = args[0];
+    if (subcommand !== "read") {
+        throw new Error(`Unknown artifact subcommand: ${subcommand}`);
+    }
+    let runId;
+    let artifactPath;
+    let outPath;
+    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 === "--path") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --path");
+            }
+            artifactPath = 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, subcommand, runId, artifactPath, outPath };
+}
+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;
+}
+export async function runArtifactCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseArtifactArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(ARTIFACT_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(ARTIFACT_USAGE);
+        return 0;
+    }
+    if (parsed.subcommand !== "read") {
+        out.error("Missing artifact subcommand");
+        out.error(ARTIFACT_USAGE);
+        return 1;
+    }
+    if (!parsed.runId || !parsed.artifactPath) {
+        out.error("Missing --run and/or --path");
+        out.error(ARTIFACT_USAGE);
+        return 1;
+    }
+    const store = createRunStore({ rootDir: projectRoot });
+    try {
+        const contents = await readRunArtifact(store, parsed.runId, parsed.artifactPath);
+        if (parsed.outPath !== undefined) {
+            const target = resolveSafeOutPath(parsed.outPath, cwd);
+            writeFileSync(target, contents, "utf8");
+            out.error(`Wrote ${target}`);
+        }
+        else {
+            out.log(contents);
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+}

package/dist/cli/envelopeCommand.d.ts

@@ -0,0 +1,32 @@
+import type { StageEnvelope } from "../types/envelope.js";
+export declare const ENVELOPE_USAGE = "Usage:\n  sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]";
+export type EnvelopeCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export type EnvelopeOutput = StageEnvelope | SyntheticSkippedEnvelope;
+export type SyntheticSkippedEnvelope = {
+    status: "skipped";
+    summary: "stage was fork-skipped";
+    artifacts: [];
+    fork_choice: null;
+};
+type EnvelopeFormat = "envelope" | "handoff";
+type ParsedEnvelopeArgs = {
+    help: boolean;
+    subcommand?: string;
+    runId?: string;
+    stageId?: string;
+    json: boolean;
+    fromPath?: string;
+    detectStageId?: string;
+    format: EnvelopeFormat;
+};
+export declare function parseEnvelopeArgs(args: string[]): ParsedEnvelopeArgs;
+export declare const SYNTHETIC_SKIPPED_ENVELOPE: SyntheticSkippedEnvelope;
+export declare function runEnvelopeCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<EnvelopeCommandIo>;
+}): Promise<number>;
+export {};

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/initCommand.d.ts

@@ -0,0 +1,9 @@
+export declare const INIT_USAGE = "Usage:\n  sf init";
+export type InitCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runInitCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<InitCommandIo>;
+}): Promise<number>;