stageflow 0.23.0 → 0.27.0

package/dist/cli/artifactCommand.js

@@ -1,9 +1,9 @@
 import { writeFileSync } from "node:fs";
-import path from "node:path";
 import { readRunArtifact } from "../mcp/readArtifact.js";
 import { globalStageflowHome } from "../project/globalHome.js";
-import { createRunStore } from "../runstore/createStore.js";
-import { isInsideDir } from "../runstore/workspaceLayout.js";
+import { createRunStoreAfterHostEnsure, } from "../runstore/createStore.js";
+import { ensureGlobalService, } from "../server/ensureGlobalService.js";
+import { resolveSafeOutPath } from "./resolveSafeOutPath.js";
 export const ARTIFACT_USAGE = `Usage:
   sf artifact read --run <runId> --path <relPath> [--out <file>]`;
 const defaultIo = {
@@ -60,18 +60,6 @@ function parseArtifactArgs(args) {
     }
     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 out = { ...defaultIo, ...options.io };
@@ -99,7 +87,12 @@ export async function runArtifactCommand(args, options = {}) {
         out.error(ARTIFACT_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: globalStageflowHome() });
+    const opened = await createRunStoreAfterHostEnsure({ rootDir: globalStageflowHome() }, () => ensureGlobalService());
+    if (!opened.ok) {
+        out.error(opened.message);
+        return 1;
+    }
+    const store = opened.store;
     try {
         const contents = await readRunArtifact(store, parsed.runId, parsed.artifactPath);
         if (parsed.outPath !== undefined) {

package/dist/cli/backupCommand.d.ts

@@ -0,0 +1,9 @@
+export declare const BACKUP_USAGE = "Usage:\n  sf backup [--out <file>] [--db-only] [--no-credentials] [--include-a2a-artifacts] [--json]\n\nCreates a consistent snapshot of the Stageflow store. Default archives include\nprovider credentials (mode 0600) and must be treated as secrets.\nDefault --out is under $STAGEFLOW_HOME/backups/.";
+export type BackupCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runBackupCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<BackupCommandIo>;
+}): Promise<number>;

package/dist/cli/backupCommand.js

@@ -0,0 +1,111 @@
+import { globalStageflowHome } from "../project/globalHome.js";
+import { BackupError, createBackup, defaultBackupOutPath, } from "../runstore/backup.js";
+import { createRunStoreAfterHostEnsure, } from "../runstore/createStore.js";
+import { ensureGlobalService } from "../server/ensureGlobalService.js";
+export const BACKUP_USAGE = `Usage:
+  sf backup [--out <file>] [--db-only] [--no-credentials] [--include-a2a-artifacts] [--json]
+
+Creates a consistent snapshot of the Stageflow store. Default archives include
+provider credentials (mode 0600) and must be treated as secrets.
+Default --out is under $STAGEFLOW_HOME/backups/.`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseBackupArgs(args) {
+    let help = false;
+    let outPath;
+    let dbOnly = false;
+    let noCredentials = false;
+    let includeA2aArtifacts = false;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        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 === "--db-only") {
+            dbOnly = true;
+        }
+        else if (arg === "--no-credentials") {
+            noCredentials = true;
+        }
+        else if (arg === "--include-a2a-artifacts") {
+            includeA2aArtifacts = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg?.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, outPath, dbOnly, noCredentials, includeA2aArtifacts, json };
+}
+export async function runBackupCommand(args, options = {}) {
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseBackupArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(BACKUP_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(BACKUP_USAGE);
+        return 0;
+    }
+    const home = globalStageflowHome();
+    const opened = await createRunStoreAfterHostEnsure({ rootDir: home }, () => ensureGlobalService());
+    if (!opened.ok) {
+        out.error(opened.message);
+        return 1;
+    }
+    const store = opened.store;
+    try {
+        const result = await createBackup({
+            store,
+            homeDir: home,
+            outPath: parsed.outPath ??
+                defaultBackupOutPath(home, new Date(), parsed.dbOnly),
+            dbOnly: parsed.dbOnly,
+            noCredentials: parsed.noCredentials,
+            includeA2aArtifacts: parsed.includeA2aArtifacts,
+        });
+        if (!parsed.dbOnly && !parsed.noCredentials) {
+            out.error("warning: backup may contain provider credentials — treat the file as a secret");
+        }
+        if (parsed.json) {
+            out.log(JSON.stringify(result));
+        }
+        else {
+            out.log(`Wrote ${result.path} (${result.bytes} bytes, sha256=${result.sha256})`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof BackupError) {
+            out.error(`${err.code}: ${err.message}`);
+            return 1;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+    finally {
+        await store.close();
+    }
+}

package/dist/cli/debugRunCommand.d.ts

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

package/dist/cli/debugRunCommand.js

@@ -0,0 +1,109 @@
+import { writeFileSync } from "node:fs";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { createRunStoreAfterHostEnsure } from "../runstore/createStore.js";
+import { buildDebugBundle } from "../runstore/debugBundle.js";
+import { ensureGlobalService } from "../server/ensureGlobalService.js";
+import { resolveSafeOutPath } from "./resolveSafeOutPath.js";
+export const DEBUG_RUN_USAGE = `Usage:
+  sf debug-run <runId> [--out <file>]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseDebugRunArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    let runId;
+    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 === "--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 if (runId === undefined) {
+            runId = arg;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, runId, outPath };
+}
+const DEBUGABLE_STATUSES = new Set([
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "queued",
+    "created",
+]);
+function assertRunDebugable(status, runId) {
+    if (DEBUGABLE_STATUSES.has(status)) {
+        return;
+    }
+    throw new Error(`run cannot be debugged: ${runId} (status: ${status})`);
+}
+export async function runDebugRunCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseDebugRunArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(DEBUG_RUN_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(DEBUG_RUN_USAGE);
+        return 0;
+    }
+    if (!parsed.runId) {
+        out.error("Missing <runId>");
+        out.error(DEBUG_RUN_USAGE);
+        return 1;
+    }
+    const opened = await createRunStoreAfterHostEnsure({ rootDir: globalStageflowHome() }, () => ensureGlobalService());
+    if (!opened.ok) {
+        out.error(opened.message);
+        return 1;
+    }
+    const store = opened.store;
+    try {
+        const detail = await store.readRun(parsed.runId);
+        assertRunDebugable(detail.status, parsed.runId);
+        const bundle = await buildDebugBundle(store, parsed.runId);
+        const json = JSON.stringify(bundle, 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/doctorCommand.d.ts

@@ -0,0 +1,32 @@
+import { type PipelinePreflightResult } from "../preflight/pipelinePreflight.js";
+import type { RunStore } from "../runstore/port.js";
+export type DoctorCheckStatus = "pass" | "warn" | "fail" | "skipped";
+export type DoctorCheck = {
+    id: string;
+    status: DoctorCheckStatus;
+    message: string;
+    code?: string;
+};
+export type DoctorResult = {
+    ok: boolean;
+    checks: DoctorCheck[];
+    preflight?: PipelinePreflightResult;
+};
+export type DoctorCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runDoctorChecks(options?: {
+    cwd?: string;
+    homeDir?: string;
+    store?: RunStore;
+    env?: NodeJS.ProcessEnv;
+    pipeline?: string;
+    strict?: boolean;
+}): Promise<DoctorResult>;
+export declare function runDoctorCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<DoctorCommandIo>;
+    runChecks?: typeof runDoctorChecks;
+}): Promise<number>;
+export declare const DOCTOR_USAGE = "Usage:\n  sf doctor [--json] [--pipeline <path>] [--strict]\n\nRun Host preflight checks (shared /readyz store/home/migrations/git, full PRAGMA integrity_check, plus bash, Node, credentials, TLS CA paths, free disk, MCP commands).\nWith --pipeline, also checks pipeline requires:/secrets:/mcp against the toolchain manifest and curated stage env.\n--strict treats unknown_version as failure (default: warn/pass).\nDo not use sf doctor as a container HEALTHCHECK \u2014 use GET /livez instead.\n";