@smithers-orchestrator/cli 0.16.0

package/src/output.js

@@ -0,0 +1,111 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./RunOutputCommandInput.ts").RunOutputCommandInput} RunOutputCommandInput */
+/** @typedef {import("./RunOutputCommandResult.ts").RunOutputCommandResult} RunOutputCommandResult */
+// @smithers-type-exports-end
+
+import { getNodeOutputRoute } from "@smithers-orchestrator/server/gatewayRoutes/getNodeOutput";
+import { NodeOutputRouteError } from "@smithers-orchestrator/server/gatewayRoutes/NodeOutputRouteError";
+import { EXIT_OK } from "./util/exitCodes.js";
+import { formatCliErrorForStderr, getCliErrorMapping } from "./util/errorMessage.js";
+
+/**
+ * @param {any} response
+ * @returns {string}
+ */
+export function renderPrettyOutput(response) {
+    if (!response || response.row === null || response.row === undefined) {
+        if (response?.status === "pending") return "(pending)";
+        if (response?.status === "failed") return "(failed)";
+        return "(no output)";
+    }
+    const schemaFields = Array.isArray(response.schema?.fields) ? response.schema.fields : [];
+    const row = /** @type {Record<string, unknown>} */ (response.row);
+    const printed = new Set();
+    /** @type {string[]} */
+    const lines = [];
+    for (const field of schemaFields) {
+        if (!field || typeof field.name !== "string") continue;
+        if (!(field.name in row)) continue;
+        const value = row[field.name];
+        lines.push(`${field.name}: ${formatValue(value)}`);
+        printed.add(field.name);
+    }
+    for (const [key, value] of Object.entries(row)) {
+        if (printed.has(key)) continue;
+        lines.push(`${key}: ${formatValue(value)}`);
+    }
+    return lines.join("\n");
+}
+
+/** @param {unknown} value */
+function formatValue(value) {
+    if (value === null) return "null";
+    if (value === undefined) return "";
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    try {
+        return JSON.stringify(value);
+    } catch {
+        return String(value);
+    }
+}
+
+/**
+ * @param {import("@smithers-orchestrator/db/adapter").SmithersDb} adapter
+ * @param {string} runId
+ * @param {string} nodeId
+ * @returns {Promise<number | null>}
+ */
+async function resolveLatestIteration(adapter, runId, nodeId) {
+    try {
+        const iterations = await adapter.listNodeIterations(runId, nodeId);
+        if (!Array.isArray(iterations) || iterations.length === 0) return null;
+        return iterations.reduce((max, row) => {
+            const it = typeof row?.iteration === "number" ? row.iteration : 0;
+            return it > max ? it : max;
+        }, 0);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * @param {RunOutputCommandInput} input
+ * @returns {Promise<RunOutputCommandResult>}
+ */
+export async function runOutputOnce(input) {
+    let iteration = input.iteration;
+    if (typeof iteration !== "number") {
+        const latest = await resolveLatestIteration(input.adapter, input.runId, input.nodeId);
+        iteration = latest ?? 0;
+    }
+    try {
+        const response = await getNodeOutputRoute({
+            runId: input.runId,
+            nodeId: input.nodeId,
+            iteration,
+            async resolveRun(runId) {
+                if (runId !== input.runId) return null;
+                const run = await input.adapter.getRun(runId);
+                if (!run) return null;
+                return { adapter: input.adapter, workflow: input.workflow ?? {} };
+            },
+        });
+        if (input.pretty) {
+            input.stdout.write(`${renderPrettyOutput(response)}\n`);
+        } else {
+            // Ticket 0014 §"output --json — raw row (default)": emit the row,
+            // not the response envelope. When the server signals non-produced
+            // state (pending/failed) we still emit the row field verbatim so
+            // scripts see `null` for those cases.
+            input.stdout.write(`${JSON.stringify(response?.row ?? null)}\n`);
+        }
+        return { exitCode: EXIT_OK };
+    } catch (err) {
+        const code = err instanceof NodeOutputRouteError ? err.code : undefined;
+        const message = err instanceof Error ? err.message : String(err);
+        input.stderr.write(`${formatCliErrorForStderr(code, message)}\n`);
+        const mapping = getCliErrorMapping(code, message);
+        return { exitCode: mapping.exitCode };
+    }
+}

package/src/resume-detached.js

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** @typedef {import("./SupervisorOptions.ts").SupervisorSpawnClaim} SupervisorSpawnClaim */
+
+/**
+ * Resume an existing run by launching `smithers up ... --resume` as a detached process.
+ * Returns the spawned PID when available.
+ *
+ * @param {string} workflowPath
+ * @param {string} runId
+ * @param {SupervisorSpawnClaim} [claim]
+ * @returns {number | null}
+ */
+export function resumeRunDetached(workflowPath, runId, claim) {
+    const cliPath = fileURLToPath(new URL("./index.js", import.meta.url));
+    const args = [cliPath, "up", workflowPath, "--resume", "--run-id", runId, "-d", "--force"];
+    if (claim) {
+        args.push("--resume-claim-owner", claim.claimOwnerId);
+        args.push("--resume-claim-heartbeat", String(claim.claimHeartbeatAtMs));
+        if (claim.restoreRuntimeOwnerId !== undefined && claim.restoreRuntimeOwnerId !== null) {
+            args.push("--resume-restore-owner", claim.restoreRuntimeOwnerId);
+        }
+        if (claim.restoreHeartbeatAtMs !== undefined && claim.restoreHeartbeatAtMs !== null) {
+            args.push("--resume-restore-heartbeat", String(claim.restoreHeartbeatAtMs));
+        }
+    }
+    const child = spawn("bun", args, {
+        cwd: dirname(resolve(workflowPath)),
+        stdio: "ignore",
+        env: process.env,
+        detached: true,
+    });
+    child.unref();
+    return child.pid ?? null;
+}

package/src/rewind.js

@@ -0,0 +1,88 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./RunRewindCommandInput.ts").RunRewindCommandInput} RunRewindCommandInput */
+/** @typedef {import("./RunRewindCommandResult.ts").RunRewindCommandResult} RunRewindCommandResult */
+// @smithers-type-exports-end
+
+import readline from "node:readline";
+import { jumpToFrameRoute } from "@smithers-orchestrator/server/gatewayRoutes/jumpToFrame";
+import { JumpToFrameError } from "@smithers-orchestrator/time-travel/jumpToFrame";
+import {
+    EXIT_OK,
+    EXIT_USER_ERROR,
+    EXIT_DECLINED,
+} from "./util/exitCodes.js";
+import { formatCliErrorForStderr, getCliErrorMapping } from "./util/errorMessage.js";
+
+/**
+ * @param {RunRewindCommandInput} input
+ * @returns {Promise<boolean>}
+ */
+async function defaultConfirm(input) {
+    if (!input.stdin.isTTY) {
+        return false;
+    }
+    const rl = readline.createInterface({ input: input.stdin, output: input.stderr });
+    try {
+        /** @type {string} */
+        const answer = await new Promise((resolve) => {
+            rl.question(
+                `Rewind run ${input.runId} to frame ${input.frameNo}? This is destructive. [y/N] `,
+                (raw) => resolve(raw ?? ""),
+            );
+        });
+        return /^y(es)?$/i.test(answer.trim());
+    } finally {
+        rl.close();
+    }
+}
+
+/**
+ * @param {RunRewindCommandInput} input
+ * @returns {Promise<RunRewindCommandResult>}
+ */
+export async function runRewindOnce(input) {
+    if (!input.yes) {
+        if (!input.stdin.isTTY && !input.confirm) {
+            input.stderr.write(`${formatCliErrorForStderr("ConfirmationRequired", "stdin is not a TTY and --yes was not passed")}\n`);
+            return { exitCode: EXIT_DECLINED };
+        }
+        const confirmFn = input.confirm ?? (() => defaultConfirm(input));
+        const confirmed = await confirmFn();
+        if (!confirmed) {
+            input.stderr.write("rewind declined by user\n");
+            return { exitCode: EXIT_DECLINED };
+        }
+    }
+    try {
+        const result = await jumpToFrameRoute({
+            adapter: input.adapter,
+            runId: input.runId,
+            frameNo: input.frameNo,
+            confirm: true,
+            caller: "cli",
+        });
+        input.onResult?.(result);
+        if (input.json) {
+            input.stdout.write(`${JSON.stringify(result)}\n`);
+        } else {
+            input.stdout.write(
+                `rewound run ${input.runId} to frame ${result.newFrameNo} ` +
+                `(reverted ${result.revertedSandboxes} sandbox${result.revertedSandboxes === 1 ? "" : "es"}, ` +
+                `deleted ${result.deletedFrames} frame${result.deletedFrames === 1 ? "" : "s"}, ` +
+                `${result.deletedAttempts} attempt${result.deletedAttempts === 1 ? "" : "s"}, ` +
+                `invalidated ${result.invalidatedDiffs} diff${result.invalidatedDiffs === 1 ? "" : "s"}, ` +
+                `took ${result.durationMs}ms)\n`,
+            );
+        }
+        return { exitCode: EXIT_OK };
+    } catch (err) {
+        const code = err instanceof JumpToFrameError ? err.code : undefined;
+        const message = err instanceof Error ? err.message : String(err);
+        input.stderr.write(`${formatCliErrorForStderr(code, message)}\n`);
+        if (code === "ConfirmationRequired") {
+            return { exitCode: EXIT_USER_ERROR };
+        }
+        const mapping = getCliErrorMapping(code, message);
+        return { exitCode: mapping.exitCode };
+    }
+}

package/src/scheduler.js

@@ -0,0 +1,112 @@
+import { spawn } from "node:child_process";
+import { CronExpressionParser } from "cron-parser";
+import { Effect, Schedule } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { runPromise } from "./smithersRuntime.js";
+import { findAndOpenDb } from "./find-db.js";
+/**
+ * @param {unknown} error
+ */
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function acquireSchedulerDbEffect() {
+    return Effect.acquireRelease(Effect.tryPromise({
+        try: () => findAndOpenDb(),
+        catch: (cause) => toSmithersError(cause, "find and open scheduler db"),
+    }), ({ cleanup }) => Effect.sync(() => cleanup()));
+}
+/**
+ * @param {SmithersDb} adapter
+ * @param {SchedulerCronRecord} job
+ * @param {number} now
+ * @returns {Effect.Effect<void, never>}
+ */
+function processCronEffect(adapter, job, now) {
+    return Effect.gen(function* () {
+        yield* Effect.logInfo(`[smithers-cron] Triggering due workflow: ${job.workflowPath} (Schedule: ${job.pattern})`);
+        yield* Effect.try({
+            try: () => {
+                const proc = spawn("bun", ["run", "src/index.js", "up", job.workflowPath, "-d"], {
+                    cwd: process.cwd(),
+                    detached: true,
+                    stdio: "ignore",
+                });
+                proc.unref();
+            },
+            catch: (cause) => toSmithersError(cause, `spawn cron workflow ${job.cronId}`),
+        });
+        const nextRunAtMs = yield* Effect.try({
+            try: () => {
+                const interval = CronExpressionParser.parse(job.pattern);
+                return interval.next().getTime();
+            },
+            catch: (cause) => toSmithersError(cause, `calculate next run for cron ${job.cronId}`),
+        });
+        yield* adapter.updateCronRunTimeEffect(job.cronId, now, nextRunAtMs);
+    }).pipe(Effect.catchAll((error) => Effect.gen(function* () {
+        const errorMessage = formatError(error);
+        yield* Effect.logWarning(`[smithers-cron] Error processing job ${job.cronId}: ${errorMessage}`);
+        const failedAtMs = Date.now();
+        yield* adapter
+            .updateCronRunTimeEffect(job.cronId, failedAtMs, job.nextRunAtMs ?? failedAtMs + 60_000, errorMessage)
+            .pipe(Effect.catchAll((updateError) => Effect.logWarning(`[smithers-cron] Failed to record error for job ${job.cronId}: ${formatError(updateError)}`)));
+    })));
+}
+/**
+ * @param {SmithersDb} adapter
+ * @returns {Effect.Effect<void, never>}
+ */
+function schedulerTickEffect(adapter) {
+    return Effect.withLogSpan("scheduler:poll")(Effect.gen(function* () {
+        const crons = yield* adapter.listCronsEffect(true).pipe(Effect.catchAll((error) => Effect.logWarning(`[smithers-cron] Tick failed: ${formatError(error)}`).pipe(Effect.as([]))));
+        const now = Date.now();
+        for (const job of crons) {
+            if (typeof job.nextRunAtMs === "number" && now < job.nextRunAtMs) {
+                continue;
+            }
+            yield* processCronEffect(adapter, job, now);
+        }
+    }));
+}
+/**
+ * @param {number} pollIntervalMs
+ */
+function schedulerLoopEffect(pollIntervalMs) {
+    return Effect.scoped(Effect.gen(function* () {
+        const { adapter } = yield* acquireSchedulerDbEffect();
+        yield* Effect.logInfo("[smithers-cron] Starting background scheduler loop...");
+        yield* Effect.logInfo(`[smithers-cron] Polling every ${pollIntervalMs / 1000}s for due jobs.`);
+        yield* schedulerTickEffect(adapter).pipe(Effect.repeat(Schedule.spaced(`${pollIntervalMs} millis`)));
+    }).pipe(Effect.annotateLogs({ component: "scheduler" }), Effect.ensuring(Effect.logInfo("[smithers-cron] Scheduler stopped.")), Effect.interruptible, Effect.asVoid));
+}
+function setupAbortSignal() {
+    const abort = new AbortController();
+    const onSigInt = () => abort.abort();
+    const onSigTerm = () => abort.abort();
+    process.once("SIGINT", onSigInt);
+    process.once("SIGTERM", onSigTerm);
+    return {
+        signal: abort.signal,
+        dispose() {
+            process.off("SIGINT", onSigInt);
+            process.off("SIGTERM", onSigTerm);
+        },
+    };
+}
+export async function runScheduler(pollIntervalMs = 15_000) {
+    const abort = setupAbortSignal();
+    try {
+        await runPromise(schedulerLoopEffect(pollIntervalMs), {
+            signal: abort.signal,
+        });
+    }
+    catch (error) {
+        abort.dispose();
+        if (abort.signal.aborted) {
+            process.exit(0);
+        }
+        throw error;
+    }
+    abort.dispose();
+}

package/src/smithersRuntime.js

@@ -0,0 +1,63 @@
+import * as WorkflowEngine from "@effect/workflow/WorkflowEngine";
+import { Cause, Effect, Exit, Layer, ManagedRuntime } from "effect";
+import { SchedulerLive, WorkflowSessionLive } from "@smithers-orchestrator/scheduler";
+import { CorrelationContextLive, MetricsServiceLive, TracingServiceLive, createSmithersRuntimeLayer, getCurrentSmithersTraceAnnotations, getCurrentSmithersTraceSpan, } from "@smithers-orchestrator/observability";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+const ObservabilityLayer = Layer.mergeAll(CorrelationContextLive, MetricsServiceLive, TracingServiceLive);
+const SmithersCoreLayer = Layer.mergeAll(ObservabilityLayer, SchedulerLive.pipe(Layer.provide(ObservabilityLayer)), WorkflowSessionLive);
+const SmithersWorkflowEngineLayer = Layer.suspend(() => WorkflowEngine.layerMemory);
+const SmithersRuntimeLayer = Layer.mergeAll(SmithersCoreLayer, SmithersWorkflowEngineLayer, createSmithersRuntimeLayer()).pipe(Layer.orDie);
+const runtime = ManagedRuntime.make(SmithersRuntimeLayer);
+/**
+ * @template A, E, R
+ * @param {Effect.Effect<A, E, R>} effect
+ */
+function decorate(effect) {
+    let program = effect.pipe(Effect.annotateLogs("service", "smithers"), Effect.withTracerEnabled(true));
+    const traceAnnotations = getCurrentSmithersTraceAnnotations();
+    if (traceAnnotations) {
+        program = program.pipe(Effect.annotateLogs(traceAnnotations));
+    }
+    const parentSpan = getCurrentSmithersTraceSpan();
+    if (parentSpan) {
+        program = program.pipe(Effect.withParentSpan(parentSpan));
+    }
+    return program;
+}
+/**
+ * @param {unknown} cause
+ * @returns {SmithersError}
+ */
+function normalizeRejection(cause) {
+    return toSmithersError(cause);
+}
+/**
+ * @template A, E, R
+ * @param {Effect.Effect<A, E, R>} effect
+ * @param {{ signal?: AbortSignal }} [options]
+ */
+export async function runPromise(effect, options) {
+    const exit = await runtime.runPromiseExit(decorate(effect), options);
+    if (Exit.isSuccess(exit)) {
+        return exit.value;
+    }
+    const failure = Cause.failureOption(exit.cause);
+    if (failure._tag === "Some") {
+        throw normalizeRejection(failure.value);
+    }
+    throw normalizeRejection(Cause.squash(exit.cause));
+}
+/**
+ * @template A, E, R
+ * @param {Effect.Effect<A, E, R>} effect
+ */
+export function runFork(effect) {
+    return runtime.runFork(decorate(effect));
+}
+/**
+ * @template A, E, R
+ * @param {Effect.Effect<A, E, R>} effect
+ */
+export function runSync(effect) {
+    return runtime.runSync(decorate(effect));
+}