stageflow 0.23.0 → 0.27.0

package/dist/cli/exportAllCommand.js

@@ -0,0 +1,218 @@
+import { createWriteStream } from "node:fs";
+import path from "node:path";
+import { projectRun } from "../projection/projectRun.js";
+import { PACKAGE_VERSION } from "../package-meta.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { createRunStoreAfterHostEnsure, } from "../runstore/createStore.js";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+import { ensureGlobalService } from "../server/ensureGlobalService.js";
+export const EXPORT_ALL_USAGE = `Usage:
+  sf export --all [--status <status>] [--since <iso>] [--pipeline <id-or-path>] [--out <file>]
+
+Streams whole-instance NDJSON (header + one projectRun line per run, including
+non-terminal). Not a backup — restore does not accept export streams.`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+export function buildExportHeader(filter, now = new Date()) {
+    return {
+        type: "stageflow_export",
+        version: 1,
+        stageflow_version: PACKAGE_VERSION,
+        created_at: now.toISOString(),
+        ...(filter !== undefined ? { filter } : {}),
+    };
+}
+export function resolveExportPipelineSource(options) {
+    if (options.pipelineSource === "inline") {
+        if (options.pipelineBody != null && options.pipelineBody !== "") {
+            try {
+                return {
+                    kind: "inline",
+                    pipeline: JSON.parse(options.pipelineBody),
+                };
+            }
+            catch {
+                return {
+                    kind: "unavailable",
+                    pipeline: null,
+                    note: "pipeline_body is not valid JSON",
+                };
+            }
+        }
+        return {
+            kind: "unavailable",
+            pipeline: null,
+            note: "inline pipeline body missing",
+        };
+    }
+    if (options.pipelineSource === "path" || options.pipelinePath) {
+        return {
+            kind: "path",
+            path: options.pipelinePath ?? "",
+            pipeline: null,
+        };
+    }
+    return {
+        kind: "unavailable",
+        pipeline: null,
+        note: "pipeline source not recorded",
+    };
+}
+export function projectRunForExport(detail, pipelineBody) {
+    return {
+        ...projectRun(detail),
+        pipeline_source: resolveExportPipelineSource({
+            pipelineSource: detail.pipeline_source,
+            pipelinePath: detail.pipeline_path,
+            pipelineBody,
+        }),
+    };
+}
+export function assertExportOutPathAllowed(outPath, homeDir = globalStageflowHome(), cwd = process.cwd()) {
+    const segments = outPath.split(/[/\\]/);
+    if (segments.some((segment) => segment === "..")) {
+        throw new Error("path must not contain .. segments");
+    }
+    const resolved = path.isAbsolute(outPath)
+        ? path.resolve(outPath)
+        : path.resolve(cwd, outPath);
+    const worktrees = path.resolve(homeDir, "worktrees");
+    const runs = path.resolve(homeDir, "runs");
+    if (isInsideDir(resolved, worktrees) || isInsideDir(resolved, runs)) {
+        throw new Error("output path must not be under worktrees/ or runs/");
+    }
+    return resolved;
+}
+function parseExportArgs(args) {
+    let help = false;
+    let all = false;
+    let status;
+    let since;
+    let pipeline;
+    let outPath;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--all") {
+            all = true;
+        }
+        else if (arg === "--status") {
+            const value = args[++i];
+            if (value === undefined)
+                throw new Error("Missing value for --status");
+            status = value;
+        }
+        else if (arg === "--since") {
+            const value = args[++i];
+            if (value === undefined)
+                throw new Error("Missing value for --since");
+            since = value;
+        }
+        else if (arg === "--pipeline") {
+            const value = args[++i];
+            if (value === undefined)
+                throw new Error("Missing value for --pipeline");
+            pipeline = value;
+        }
+        else if (arg === "--out") {
+            const value = args[++i];
+            if (value === undefined)
+                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, all, status, since, pipeline, outPath };
+}
+export async function* iterateExportNdjson(options) {
+    yield `${JSON.stringify(buildExportHeader(options.filter, options.now ?? new Date()))}\n`;
+    const runs = await options.store.listRuns(options.filter);
+    for (const summary of runs) {
+        const detail = await options.store.readRun(summary.run_id);
+        const pipelineBody = await options.store.readPipelineBody(summary.run_id);
+        const line = {
+            type: "projectRun",
+            run: projectRunForExport(detail, pipelineBody),
+        };
+        yield `${JSON.stringify(line)}\n`;
+    }
+}
+export async function runExportAllCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseExportArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(EXPORT_ALL_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(EXPORT_ALL_USAGE);
+        return 0;
+    }
+    if (!parsed.all) {
+        out.error("sf export requires --all (whole-instance NDJSON)");
+        out.error(EXPORT_ALL_USAGE);
+        return 1;
+    }
+    const filter = {};
+    if (parsed.status !== undefined)
+        filter.status = parsed.status;
+    if (parsed.since !== undefined)
+        filter.since = parsed.since;
+    if (parsed.pipeline !== undefined)
+        filter.pipeline = parsed.pipeline;
+    const opened = await createRunStoreAfterHostEnsure({ rootDir: globalStageflowHome() }, () => ensureGlobalService());
+    if (!opened.ok) {
+        out.error(opened.message);
+        return 1;
+    }
+    const store = opened.store;
+    try {
+        let sink = (line) => out.log(line.replace(/\n$/, ""));
+        let close;
+        if (parsed.outPath !== undefined) {
+            const target = assertExportOutPathAllowed(parsed.outPath, globalStageflowHome(), cwd);
+            const stream = createWriteStream(target);
+            sink = (line) => {
+                stream.write(line);
+            };
+            close = () => new Promise((resolve, reject) => {
+                stream.end(() => resolve());
+                stream.on("error", reject);
+            });
+        }
+        for await (const line of iterateExportNdjson({
+            store,
+            filter: Object.keys(filter).length > 0 ? filter : undefined,
+        })) {
+            sink(line);
+        }
+        await close?.();
+        if (parsed.outPath !== undefined) {
+            out.error(`Wrote ${assertExportOutPathAllowed(parsed.outPath, globalStageflowHome(), cwd)}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+    finally {
+        await store.close();
+    }
+}

package/dist/cli/exportRunCommand.js

@@ -1,9 +1,10 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { projectRun } from "../projection/projectRun.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 { buildRunExportPayload } from "../runstore/exportRunPayload.js";
+import { resolveSafeOutPath } from "./resolveSafeOutPath.js";
 export const EXPORT_RUN_USAGE = `Usage:
   sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]`;
 const defaultIo = {
@@ -75,23 +76,19 @@ function resolveRunIdFromFile(fromPath, cwd) {
     }
     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") {
+const EXPORTABLE_STATUSES = new Set([
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "queued",
+    "created",
+]);
+function assertRunExportable(status, runId) {
+    if (EXPORTABLE_STATUSES.has(status)) {
         return;
     }
-    throw new Error(`run is not complete: ${runId} (status: ${status})`);
+    throw new Error(`run cannot be exported: ${runId} (status: ${status})`);
 }
 export async function runExportRunCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
@@ -126,11 +123,16 @@ export async function runExportRunCommand(args, options = {}) {
         out.error(EXPORT_RUN_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 detail = await store.readRun(runId);
-        assertRunComplete(detail.status, runId);
-        const projection = projectRun(detail);
+        assertRunExportable(detail.status, runId);
+        const projection = buildRunExportPayload(detail);
         const json = JSON.stringify(projection, null, 2);
         if (parsed.outPath !== undefined) {
             const target = resolveSafeOutPath(parsed.outPath, cwd);

package/dist/cli/hostClient.d.ts

@@ -1,8 +1,9 @@
 import type { PipelineRunResult } from "../runtime/pipelineRunner.js";
-import type { AbandonStageResult, DecideFeedbackLoopResult, StartRunResult, StopManualRecoveryResult } from "../runtime/runManager.js";
+import type { AbandonStageResult, CancelRunResult, DecideFeedbackLoopResult, DeleteRunResult, GcRunsResult, StartRunResult, StopManualRecoveryResult } from "../runtime/runManager.js";
 import type { DeliverAnswerResult } from "../runtime/stageHitl.js";
 import type { RetryStageResult } from "../runtime/runRetryCoordinator.js";
 import type { RunDetail, RunStore } from "../runstore/port.js";
+import type { TaskFile } from "../types/task.js";
 export declare function computeRunDir(runId: string): string;
 export declare function httpReadRun(base: string, runId: string): Promise<RunDetail>;
 /** Thin RunStore-shaped reader backed by the global service, for the CLI output helpers that only need `readRun`. */
@@ -13,7 +14,8 @@ export declare function pollRunUntilTerminal(base: string, runId: string, option
 export declare function runDetailToPipelineRunResult(detail: RunDetail): PipelineRunResult;
 export type HttpStartRunInput = {
     pipeline: string;
-    task: string;
+    task: string | TaskFile;
+    project_root?: string;
     checkoutOverride?: string;
     skipGates?: boolean;
     gitSha?: string;
@@ -21,7 +23,16 @@ export type HttpStartRunInput = {
     ciJobUrl?: string;
 };
 export declare function httpStartRun(base: string, input: HttpStartRunInput): Promise<StartRunResult>;
-export declare function httpRerun(base: string, runId: string): Promise<StartRunResult>;
+export type HttpEnsureProjectResult = {
+    ok: true;
+    project_root: string;
+} | Extract<StartRunResult, {
+    ok: false;
+}>;
+export declare function httpEnsureProject(base: string, projectRoot: string): Promise<HttpEnsureProjectResult>;
+export declare function httpRerun(base: string, runId: string, options?: {
+    pinned?: boolean;
+}): Promise<StartRunResult>;
 export declare function httpDeliverAnswer(base: string, runId: string, stageId: string, answer: unknown): Promise<DeliverAnswerResult>;
 export declare function httpDecideFeedbackLoop(base: string, runId: string, stageId: string, input: {
     decision: "extend" | "continue" | "abandon";
@@ -39,5 +50,12 @@ export declare function httpResumeTimedOutStage(base: string, runId: string, sta
 export declare function httpRecoverManualStageUntilStop(base: string, runId: string, stageId: string, guidance?: string): Promise<RetryOrchestrationResult>;
 export declare function httpStopManualRecovery(base: string, runId: string, stageId: string): Promise<StopManualRecoveryResult>;
 export declare function httpAbandonStage(base: string, runId: string, stageId: string): Promise<AbandonStageResult>;
+export declare function httpCancelRun(base: string, runId: string, reason: string): Promise<CancelRunResult>;
+export declare function httpDeleteRun(base: string, runId: string, options?: {
+    force?: boolean;
+}): Promise<DeleteRunResult>;
+export declare function httpGcRuns(base: string, options?: {
+    execute?: boolean;
+}): Promise<GcRunsResult>;
 export declare function resolveAbsolute(cwd: string, maybeRelative: string): string;
 export {};

package/dist/cli/hostClient.js

@@ -1,17 +1,23 @@
 import path from "node:path";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { PipelineValidationError } from "../runtime/pipelineValidationError.js";
-import { runWorkspaceDir, storeRootFor } from "../runstore/paths.js";
+import { resolveStoreRoot, runWorkspaceDir } from "../runstore/paths.js";
+import { clientAuthorizationHeaders } from "../server/controlToken.js";
 async function postJson(base, urlPath, body) {
     const res = await fetch(`${base}${urlPath}`, {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers: {
+            "Content-Type": "application/json",
+            ...clientAuthorizationHeaders("POST"),
+        },
         body: JSON.stringify(body ?? {}),
     });
     return { status: res.status, body: await parseJsonBody(res) };
 }
 async function getJson(base, urlPath) {
-    const res = await fetch(`${base}${urlPath}`);
+    const res = await fetch(`${base}${urlPath}`, {
+        headers: { ...clientAuthorizationHeaders("GET") },
+    });
     return { status: res.status, body: await parseJsonBody(res) };
 }
 async function parseJsonBody(res) {
@@ -35,7 +41,7 @@ function enc(value) {
     return encodeURIComponent(value);
 }
 export function computeRunDir(runId) {
-    return runWorkspaceDir(storeRootFor(globalStageflowHome()), runId);
+    return runWorkspaceDir(resolveStoreRoot(globalStageflowHome()), runId);
 }
 export async function httpReadRun(base, runId) {
     const { status, body } = await getJson(base, `/api/runs/${enc(runId)}`);
@@ -51,6 +57,7 @@ export function httpStoreReader(base) {
 function isRunTerminal(detail) {
     return (detail.status === "succeeded" ||
         detail.status === "failed" ||
+        detail.status === "cancelled" ||
         (detail.status === "running" && detail.waiting_stage_id !== undefined));
 }
 function sleep(ms) {
@@ -70,15 +77,20 @@ export function runDetailToPipelineRunResult(detail) {
         ? "succeeded"
         : detail.status === "failed"
             ? "failed"
-            : "waiting";
+            : detail.status === "cancelled"
+                ? "cancelled"
+                : "waiting";
+    const reason = outcome === "cancelled"
+        ? (detail.cancel_reason ?? detail.failed_reason)
+        : outcome === "failed"
+            ? detail.failed_reason
+            : undefined;
     return {
         ok: outcome === "succeeded",
         outcome,
         runId: detail.run_id,
         runDir: computeRunDir(detail.run_id),
-        ...(outcome === "failed" && detail.failed_reason !== undefined
-            ? { reason: detail.failed_reason }
-            : {}),
+        ...(reason !== undefined ? { reason } : {}),
     };
 }
 function toStartFailure(status, body) {
@@ -107,15 +119,36 @@ export async function httpStartRun(base, input) {
     }
     if (status !== 202)
         return toStartFailure(status, body);
-    const runId = body.runId;
+    const parsed = body;
+    const runId = parsed.runId;
     return {
         ok: true,
         runId,
+        ...(parsed.queued === true
+            ? { queued: true, queuePosition: parsed.queuePosition }
+            : {}),
         done: pollRunUntilTerminal(base, runId).then(runDetailToPipelineRunResult),
     };
 }
-export async function httpRerun(base, runId) {
-    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/rerun`, {});
+export async function httpEnsureProject(base, projectRoot) {
+    const { status, body } = await postJson(base, "/api/projects", {
+        project_root: projectRoot,
+    });
+    if (status === 200) {
+        const parsed = body;
+        if (typeof parsed.project_root === "string" && parsed.project_root.length > 0) {
+            return { ok: true, project_root: parsed.project_root };
+        }
+        return {
+            ok: false,
+            reason: "ensure_project response missing project_root",
+            status,
+        };
+    }
+    return toStartFailure(status, body);
+}
+export async function httpRerun(base, runId, options) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/rerun`, options?.pinned !== undefined ? { pinned: options.pinned } : {});
     if (status !== 202)
         return toStartFailure(status, body);
     const newRunId = body.runId;
@@ -142,7 +175,15 @@ export async function httpDecideFeedbackLoop(base, runId, stageId, input) {
 export async function httpRetryStageUntilStop(base, runId, stageId) {
     const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/stages/${enc(stageId)}/retry`, {});
     if (status !== 202) {
-        return { ok: false, reason: extractError(body, status), status };
+        const code = body && typeof body === "object" && typeof body.code === "string"
+            ? body.code
+            : undefined;
+        return {
+            ok: false,
+            reason: extractError(body, status),
+            status,
+            ...(code !== undefined ? { code } : {}),
+        };
     }
     const detail = await pollRunUntilTerminal(base, runId);
     return { ok: true, pipeline: runDetailToPipelineRunResult(detail) };
@@ -177,6 +218,46 @@ export async function httpAbandonStage(base, runId, stageId) {
     }
     return { ok: false, reason: extractError(body, status), status };
 }
+export async function httpCancelRun(base, runId, reason) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/cancel`, { reason });
+    if (status === 202) {
+        const parsed = body;
+        return { ok: true, runId: parsed.runId };
+    }
+    return { ok: false, reason: extractError(body, status), status };
+}
+export async function httpDeleteRun(base, runId, options) {
+    const forceQs = options?.force ? "?force=true" : "";
+    const res = await fetch(`${base}/api/runs/${enc(runId)}${forceQs}`, {
+        method: "DELETE",
+        headers: { ...clientAuthorizationHeaders("DELETE") },
+    });
+    const body = await parseJsonBody(res);
+    if (res.status === 200) {
+        const parsed = body;
+        return { ok: true, runId: parsed.runId };
+    }
+    return {
+        ok: false,
+        reason: extractError(body, res.status),
+        status: res.status,
+    };
+}
+export async function httpGcRuns(base, options) {
+    const { status, body } = await postJson(base, "/api/runs/gc", {
+        execute: options?.execute === true,
+    });
+    if (status === 200) {
+        const parsed = body;
+        return {
+            ok: true,
+            slimmed: parsed.slimmed ?? [],
+            purged: parsed.purged ?? [],
+            bareCachesEvicted: parsed.bareCachesEvicted ?? [],
+        };
+    }
+    return { ok: false, reason: extractError(body, status), status };
+}
 export function resolveAbsolute(cwd, maybeRelative) {
     return path.resolve(cwd, maybeRelative);
 }

package/dist/cli/initTemplates.d.ts

@@ -1,3 +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\nmodel: anthropic/claude-sonnet-4-5\nstages:\n  - id: hello\n    system_prompt: Say hello and emit a success envelope.\n";
+export declare const HELLO_PIPELINE_YAML = "id: hello\nstages:\n  - id: hello\n    model: anthropic/claude-sonnet-4-5\n    system_prompt: Say hello and emit a success envelope.\n    io:\n      input:\n        schema:\n          type: object\n      output:\n        schema:\n          type: object\n";
 export declare const HELLO_TASK_YAML = "id: hello\ngoal: Run the hello pipeline scaffold.\n";

package/dist/cli/initTemplates.js

@@ -9,10 +9,17 @@ catalog:
     task: "*.task.yaml"
 `;
 export const HELLO_PIPELINE_YAML = `id: hello
-model: anthropic/claude-sonnet-4-5
 stages:
   - id: hello
+    model: anthropic/claude-sonnet-4-5
     system_prompt: Say hello and emit a success envelope.
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
 `;
 export const HELLO_TASK_YAML = `id: hello
 goal: Run the hello pipeline scaffold.

package/dist/cli/resolveSafeOutPath.d.ts

@@ -0,0 +1,2 @@
+/** Resolve `--out` under cwd, realpath-normalizing both sides before containment. */
+export declare function resolveSafeOutPath(outPath: string, cwd: string): string;

package/dist/cli/resolveSafeOutPath.js

@@ -0,0 +1,40 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+function resolveEffectiveRealPathSync(candidatePath) {
+    try {
+        return realpathSync(candidatePath);
+    }
+    catch {
+        const missing = [];
+        let current = candidatePath;
+        while (true) {
+            missing.unshift(path.basename(current));
+            const parent = path.dirname(current);
+            if (parent === current) {
+                return path.resolve(candidatePath);
+            }
+            try {
+                const realParent = realpathSync(parent);
+                return path.join(realParent, ...missing);
+            }
+            catch {
+                current = parent;
+            }
+        }
+    }
+}
+/** Resolve `--out` under cwd, realpath-normalizing both sides before containment. */
+export 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 = resolveEffectiveRealPathSync(path.resolve(cwd));
+    const outResolved = resolveEffectiveRealPathSync(resolved);
+    if (!isInsideDir(outResolved, cwdResolved)) {
+        throw new Error("output path must resolve under the current working directory");
+    }
+    return resolved;
+}

package/dist/cli/restoreCommand.d.ts

@@ -0,0 +1,10 @@
+import { probeGlobalServiceDetailed } from "../server/ensureGlobalService.js";
+export declare const RESTORE_USAGE = "Usage:\n  sf restore <file> [--force] [--json]\n\nRestores a Stageflow backup. The Host must be down (probed via /livez).\nNever autostarts a Host. Previous state.db is moved aside, not deleted.";
+export type RestoreCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runRestoreCommand(args: string[], options?: {
+    io?: Partial<RestoreCommandIo>;
+    probe?: typeof probeGlobalServiceDetailed;
+}): Promise<number>;

package/dist/cli/restoreCommand.js

@@ -0,0 +1,90 @@
+import path from "node:path";
+import { applyRestoreArchive, RestoreError, } from "../runstore/restore.js";
+import { StoreSchemaError } from "../runstore/sqlite/storeSchemaError.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+export const RESTORE_USAGE = `Usage:
+  sf restore <file> [--force] [--json]
+
+Restores a Stageflow backup. The Host must be down (probed via /livez).
+Never autostarts a Host. Previous state.db is moved aside, not deleted.`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseRestoreArgs(args) {
+    let help = false;
+    let file;
+    let force = 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 === "--force") {
+            force = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg?.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else if (file === undefined) {
+            file = arg;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, file, force, json };
+}
+export async function runRestoreCommand(args, options = {}) {
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseRestoreArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(RESTORE_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(RESTORE_USAGE);
+        return 0;
+    }
+    if (!parsed.file) {
+        out.error("Missing <file>");
+        out.error(RESTORE_USAGE);
+        return 1;
+    }
+    try {
+        const result = await applyRestoreArchive({
+            archivePath: path.resolve(parsed.file),
+            homeDir: globalStageflowHome(),
+            force: parsed.force,
+            probe: options.probe,
+        });
+        if (parsed.json) {
+            out.log(JSON.stringify({ ok: true, ...result }));
+        }
+        else {
+            out.log(`Restored schema_version=${result.schema_version}` +
+                (result.missing_a2a_artifact_rows > 0
+                    ? ` (missing A2A artifact bytes: ${result.missing_a2a_artifact_rows})`
+                    : ""));
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof RestoreError || err instanceof StoreSchemaError) {
+            out.error(`${err.code}: ${err.message}`);
+            return 1;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+}