@lostgradient/weft 0.2.0

package/dist/cli/schedule.js

@@ -0,0 +1,128 @@
+import { registerOnRuntimeEngine, runtimeWorkflowEngine } from "../core/runtime-workflow-engine.js";
+import { createStorage } from "./storage-factory.js";
+function formatScheduleCadence(schedule) {
+  if (schedule.intervalMs !== void 0)
+    return `every ${schedule.intervalMs}ms`;
+  return schedule.cronExpression ?? "unknown";
+}
+function formatScheduleLine(schedule) {
+  return [
+    schedule.id,
+    schedule.workflowType,
+    schedule.status,
+    formatScheduleCadence(schedule),
+    schedule.nextFireAt === null ? "none" : new Date(schedule.nextFireAt).toISOString()
+  ].join(" | ");
+}
+function formatScheduleCommandOutput(schedule, json, message) {
+  return json ? JSON.stringify(schedule, null, 2) : message;
+}
+function getScheduleStorageValidationError(storage) {
+  if (storage !== "memory")
+    return null;
+  return "Error: --storage memory is not supported for schedule commands because data does not persist across CLI invocations";
+}
+async function executeScheduleList(options, engine) {
+  const result = await engine.listSchedules();
+  return { stdout: options.json ? JSON.stringify(result, null, 2) : result.items.length === 0 ? "No schedules found." : [
+    "ID | Workflow Type | Status | Cadence | Next Fire",
+    ...result.items.map(formatScheduleLine)
+  ].join(`
+`), exitCode: 0 };
+}
+function getScheduleCreateValidationError(options) {
+  if (!options.workflows)
+    return "Error: --workflows flag is required for schedule create";
+  if (!options.workflowType)
+    return "Error: missing required argument <workflowType> for schedule create";
+  const hasCron = typeof options.cronExpression === "string" && options.cronExpression.length > 0, hasEvery = options.every !== void 0;
+  if (hasCron && hasEvery)
+    return "Error: provide exactly one of <cronExpression> or --every, not both";
+  if (!hasCron && !hasEvery)
+    return "Error: provide a <cronExpression> argument or an --every <duration> flag for schedule create";
+  return null;
+}
+function parseScheduleInput(input) {
+  try {
+    return { ok: !0, value: JSON.parse(input) };
+  } catch (error) {
+    return { ok: !1, message: `Error: could not parse --input JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+async function registerScheduleWorkflows(engine, workflowsPath, loadRegistrationsFromModule) {
+  const loaded = await loadRegistrationsFromModule(workflowsPath);
+  for (const [workflowType, registration] of Object.entries(loaded.registrations)) {
+    const definition = { ...registration, name: workflowType };
+    registerOnRuntimeEngine(runtimeWorkflowEngine(engine), definition);
+  }
+}
+async function executeScheduleCreate(options, engine, loadRegistrationsFromModule) {
+  const validationError = getScheduleCreateValidationError(options);
+  if (validationError !== null)
+    return { stdout: "", stderr: validationError, exitCode: 1 };
+  await registerScheduleWorkflows(engine, options.workflows, loadRegistrationsFromModule);
+  const parsedInput = parseScheduleInput(options.input);
+  if (!parsedInput.ok)
+    return { stdout: "", stderr: parsedInput.message, exitCode: 1 };
+  const spec = options.every !== void 0 ? { every: options.every } : options.cronExpression, handle = await engine.schedule(options.workflowType, parsedInput.value, spec, {
+    ...options.id !== void 0 ? { id: options.id } : {},
+    ...options.overlap !== void 0 ? { overlap: options.overlap } : {},
+    ...options.backfill ? { backfill: !0 } : {}
+  }), schedule = await handle.describe();
+  return {
+    stdout: formatScheduleCommandOutput(schedule, options.json, `Created schedule ${handle.id}`),
+    exitCode: 0
+  };
+}
+async function executeScheduleMutation(options, engine) {
+  if (!options.scheduleId)
+    return {
+      stdout: "",
+      stderr: `Error: scheduleId is required for schedule ${options.action}`,
+      exitCode: 1
+    };
+  if (options.action === "pause") {
+    await engine.pauseSchedule(options.scheduleId);
+    const schedule = await engine.getSchedule(options.scheduleId);
+    return {
+      stdout: formatScheduleCommandOutput(schedule, options.json, `Paused schedule ${options.scheduleId}`),
+      exitCode: 0
+    };
+  }
+  if (options.action === "resume") {
+    await engine.resumeSchedule(options.scheduleId);
+    const schedule = await engine.getSchedule(options.scheduleId);
+    return {
+      stdout: formatScheduleCommandOutput(schedule, options.json, `Resumed schedule ${options.scheduleId}`),
+      exitCode: 0
+    };
+  }
+  await engine.cancelSchedule(options.scheduleId);
+  const schedule = await engine.getSchedule(options.scheduleId);
+  return {
+    stdout: formatScheduleCommandOutput(schedule, options.json, `Cancelled schedule ${options.scheduleId}`),
+    exitCode: 0
+  };
+}
+export async function executeSchedule(options) {
+  const storageValidationError = getScheduleStorageValidationError(options.storage);
+  if (storageValidationError !== null)
+    return {
+      stdout: "",
+      stderr: storageValidationError,
+      exitCode: 1
+    };
+  const { Engine } = await import("../core/engine.js"), { loadRegistrationsFromModule } = await import("../diagnostics/validate.js"), storage = await createStorage(options.storage, options.database), engine = new Engine({ storage });
+  try {
+    if (options.action === "list")
+      return await executeScheduleList(options, engine);
+    if (options.action === "create")
+      return await executeScheduleCreate(options, engine, loadRegistrationsFromModule);
+    return await executeScheduleMutation(options, engine);
+  } catch (error) {
+    return { stdout: "", stderr: `Error: ${error instanceof Error ? error.message : String(error)}`, exitCode: 1 };
+  } finally {
+    await engine[Symbol.asyncDispose]();
+    storage[Symbol.dispose]();
+  }
+}

package/dist/cli/serve-registrations.d.ts

@@ -0,0 +1,15 @@
+import type { ActivityDefinition } from '../core/activity.ts';
+import type { Engine } from '../core/engine.ts';
+import type { WorkflowRegistration } from '../diagnostics/validate.ts';
+/**
+ * Convert a plain-object `ActivityDefinition` into a callable function that
+ * satisfies the engine's `isActivityDefinition` check (which requires a
+ * function with `name` and `execute` own properties).
+ */
+export declare function toActivityCallable(definition: ActivityDefinition): (...args: unknown[]) => unknown;
+/**
+ * Register a map of workflow registrations and a list of activity definitions
+ * on an engine instance. Plain-object activities are normalized to callables
+ * before registration.
+ */
+export declare function registerModuleExports(engine: Engine, registrations: Record<string, WorkflowRegistration>, activities: ActivityDefinition[]): void;

package/dist/cli/serve-registrations.js

@@ -0,0 +1,23 @@
+import { registerOnRuntimeEngine, runtimeWorkflowEngine } from "../core/runtime-workflow-engine.js";
+export function toActivityCallable(definition) {
+  const { name, execute, ...metadata } = definition, callable = Object.assign(async function activityCallable(...args) {
+    return execute(...args);
+  }, metadata);
+  Object.defineProperty(callable, "name", { value: name, configurable: !0 });
+  Object.defineProperty(callable, "execute", {
+    value: execute,
+    enumerable: !0,
+    configurable: !0
+  });
+  return callable;
+}
+export function registerModuleExports(engine, registrations, activities) {
+  const runtime = runtimeWorkflowEngine(engine);
+  for (const [workflowType, registration] of Object.entries(registrations))
+    registerOnRuntimeEngine(runtime, { ...registration, name: workflowType });
+  for (const activity of activities)
+    if (typeof activity === "function")
+      engine.register(activity);
+    else
+      engine.register(toActivityCallable(activity));
+}

package/dist/cli/server-client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared invocation seam for hand-authored, server-facing CLI commands.
+ *
+ * Every noun-verb command (`server`, `workflow`, `tail`) routes its operation
+ * calls through {@link callCatalogOperation}, which wraps the generated typed
+ * client. The generated client is the only path to the wire: commands never
+ * build HTTP requests directly, so the compiler rejects any reference to an
+ * operation the catalog does not define (drift is caught at build time).
+ *
+ * At runtime this helper maps two failure shapes the typed client cannot
+ * express on its own: connection failures (server unreachable) and version
+ * skew (a newer wrapper calling an operation an older server lacks). The
+ * latter surfaces as a specific compatibility message instead of a raw
+ * `Method not found` / HTTP 404 dump.
+ *
+ * @module cli/server-client
+ */
+import type { ConnectionOptions } from '../connection.ts';
+import { type CatalogOperationName, type CatalogOperationTypes } from './generated/operation-client.generated.ts';
+/** Successful or failed result of a catalog operation call, never thrown. */
+export type CatalogCallResult<Output> = {
+    readonly ok: true;
+    readonly value: Output;
+} | {
+    readonly ok: false;
+    readonly kind: 'connection';
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly kind: 'compat';
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly kind: 'operation';
+    readonly message: string;
+};
+/**
+ * Invoke a single catalog operation through the generated typed client and
+ * normalize every failure into a {@link CatalogCallResult}. The operation name
+ * is a typed catalog key, so an unknown operation is a compile error rather
+ * than a runtime surprise.
+ */
+export declare function callCatalogOperation<Name extends CatalogOperationName>(connection: ConnectionOptions, operationName: Name, input: CatalogOperationTypes[Name]['input']): Promise<CatalogCallResult<CatalogOperationTypes[Name]['output']>>;
+/** Exit code for a {@link CatalogCallResult} failure, by failure kind. */
+export declare function failureExitCode(kind: 'connection' | 'compat' | 'operation'): number;

package/dist/cli/server-client.js

@@ -0,0 +1,33 @@
+import {
+  CATALOG_OPERATION_NAMES
+} from "./generated/operation-client.generated.js";
+import {
+  CatalogClientError,
+  createCatalogWeftClient,
+  httpJsonRpcTransport
+} from "./operation-client-runtime.js";
+import { messageOf } from "./output.js";
+export async function callCatalogOperation(connection, operationName, input) {
+  const client = createCatalogWeftClient(CATALOG_OPERATION_NAMES, httpJsonRpcTransport(connection));
+  try {
+    return { ok: !0, value: await client[operationName](input) };
+  } catch (error) {
+    if (error instanceof CatalogClientError) {
+      if (error.isUnknownOperation)
+        return {
+          ok: !1,
+          kind: "compat",
+          message: `operation ${operationName} is not available on this server; the server is older than this CLI. Run 'weft server info' to compare versions, or upgrade the server`
+        };
+      return { ok: !1, kind: "operation", message: error.message };
+    }
+    return { ok: !1, kind: "connection", message: messageOf(error) };
+  }
+}
+export function failureExitCode(kind) {
+  if (kind === "connection")
+    return 2;
+  if (kind === "compat")
+    return 4;
+  return 1;
+}

package/dist/cli/server-commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `weft server health` and `weft server info` — operate/inspect commands for a
+ * running Weft server.
+ *
+ * `health` probes the `/v1/health` meta endpoint and maps reachability to an
+ * exit code (0 healthy, 1 unreachable). `--wait` polls until the server
+ * responds or a timeout elapses, which deploy scripts use to block until a
+ * freshly started server is ready.
+ *
+ * `info` reports the resolved server, its health, and a version-skew summary:
+ * the count of operations the server advertises in `/openrpc.json` that this
+ * CLI's bundled catalog does not know about, surfaced as "N additional
+ * operations available via weft api".
+ *
+ * @module cli/server-commands
+ */
+import type { CommandOutput, ServerCommand } from './types.ts';
+/** Execute `weft server health` or `weft server info`. */
+export declare function executeServer(command: ServerCommand): Promise<CommandOutput>;

package/dist/cli/server-commands.js

@@ -0,0 +1,151 @@
+import { resolveConnection } from "../connection.js";
+import { CATALOG_OPERATION_NAMES } from "./generated/operation-client.generated.js";
+import { messageOf, prettyJson } from "./output.js";
+const HEALTH_POLL_INTERVAL_MS = 250;
+export async function executeServer(command) {
+  let resolved;
+  try {
+    resolved = resolveServerConnection(command);
+  } catch (error) {
+    return {
+      stdout: "",
+      stderr: `server: connection error: ${messageOf(error)}`,
+      exitCode: 2
+    };
+  }
+  const { server, token } = resolved;
+  if (command.action === "health")
+    return executeServerHealth(command, server, token);
+  return executeServerInfo(command, server, token);
+}
+function resolveServerConnection(command) {
+  const connection = resolveConnection({
+    ...command.server === void 0 ? {} : { server: command.server },
+    ...command.token === void 0 ? {} : { token: command.token },
+    ...command.profile === void 0 ? {} : { profile: command.profile }
+  });
+  return { server: connection.server, token: connection.token };
+}
+function metaEndpoint(server, path) {
+  const endpoint = new URL(server.toString()), basePath = endpoint.pathname.endsWith("/") ? endpoint.pathname : `${endpoint.pathname}/`;
+  endpoint.pathname = `${basePath}${path}`.replaceAll(/\/+/g, "/");
+  endpoint.search = "";
+  endpoint.hash = "";
+  return endpoint;
+}
+function authHeaders(token) {
+  const headers = new Headers;
+  if (token !== void 0 && token !== "")
+    headers.set("authorization", `Bearer ${token}`);
+  return headers;
+}
+async function probeHealth(server, token) {
+  try {
+    const response = await fetch(metaEndpoint(server, "v1/health"), {
+      method: "GET",
+      headers: authHeaders(token)
+    });
+    if (!response.ok)
+      return {
+        healthy: !1,
+        detail: `server returned status ${response.status}`,
+        connectionError: !1
+      };
+    return { healthy: !0, detail: "ok", connectionError: !1 };
+  } catch (error) {
+    return {
+      healthy: !1,
+      detail: error instanceof Error ? error.message : String(error),
+      connectionError: !0
+    };
+  }
+}
+async function executeServerHealth(command, server, token) {
+  const result = command.wait ? await waitForHealth(server, token, command.waitTimeoutMs) : await probeHealth(server, token), exitCode = result.healthy ? 0 : result.connectionError ? 2 : 1;
+  if (command.json)
+    return {
+      stdout: prettyJson({
+        server: server.toString(),
+        healthy: result.healthy,
+        detail: result.detail
+      }),
+      exitCode
+    };
+  if (result.healthy)
+    return {
+      stdout: command.quiet ? "" : `${server.toString()} is healthy`,
+      exitCode: 0
+    };
+  return {
+    stdout: "",
+    stderr: command.quiet ? "" : `${server.toString()} is unreachable: ${result.detail}`,
+    exitCode
+  };
+}
+async function waitForHealth(server, token, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let last = await probeHealth(server, token);
+  while (!last.healthy && Date.now() < deadline) {
+    await Bun.sleep(HEALTH_POLL_INTERVAL_MS);
+    last = await probeHealth(server, token);
+  }
+  return last;
+}
+function isOpenRpcDocument(value) {
+  return typeof value === "object" && value !== null;
+}
+async function fetchServerOperationNames(server, token) {
+  try {
+    const response = await fetch(metaEndpoint(server, "openrpc.json"), {
+      method: "GET",
+      headers: authHeaders(token)
+    });
+    if (!response.ok)
+      return;
+    const body = await response.json();
+    if (!isOpenRpcDocument(body) || !Array.isArray(body.methods))
+      return;
+    return body.methods.map((method) => typeof method.name === "string" ? method.name : void 0).filter((name) => name !== void 0);
+  } catch {
+    return;
+  }
+}
+function additionalServerOperations(serverOperationNames) {
+  if (serverOperationNames === void 0)
+    return [];
+  const knownNames = new Set(CATALOG_OPERATION_NAMES);
+  return serverOperationNames.filter((name) => !knownNames.has(name)).toSorted();
+}
+function formatServerInfoLines(server, health, serverOperationNames, additionalOperations) {
+  const lines = [
+    `Server:  ${server.toString()}`,
+    `Health:  ${health.healthy ? "ok" : `unreachable (${health.detail})`}`,
+    `CLI catalog operations: ${CATALOG_OPERATION_NAMES.length}`
+  ];
+  if (serverOperationNames === void 0)
+    return lines;
+  lines.push(`Server operations: ${serverOperationNames.length}`);
+  if (additionalOperations.length > 0)
+    lines.push(`${additionalOperations.length} additional operations available via weft api:`, ...additionalOperations.map((name) => `  ${name}`));
+  return lines;
+}
+async function executeServerInfo(command, server, token) {
+  const health = await probeHealth(server, token), serverOperationNames = health.healthy ? await fetchServerOperationNames(server, token) : void 0, additionalOperations = additionalServerOperations(serverOperationNames), exitCode = health.healthy ? 0 : health.connectionError ? 2 : 1;
+  if (command.json)
+    return {
+      stdout: prettyJson({
+        server: server.toString(),
+        healthy: health.healthy,
+        detail: health.detail,
+        cliOperationCount: CATALOG_OPERATION_NAMES.length,
+        serverOperationCount: serverOperationNames?.length ?? null,
+        additionalOperations
+      }),
+      exitCode
+    };
+  return {
+    stdout: formatServerInfoLines(server, health, serverOperationNames, additionalOperations).join(`
+`),
+    exitCode
+  };
+}

package/dist/cli/storage-backend-arguments.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared CLI parsing for the `--storage` backend flag. Centralizes the valid
+ * backend set and the persistent-only restriction so the top-level argument
+ * parser and the schedule subcommand parser agree on validation.
+ *
+ * @module cli/storage-backend-arguments
+ */
+import type { PersistentStorageBackend, StorageBackend } from './types.ts';
+/** Validate a `--storage` value, defaulting to `sqlite` when omitted. */
+export declare function parseStorageBackend(value: string | undefined): StorageBackend;
+/**
+ * Validate a `--storage` value for commands that must persist data across CLI
+ * invocations (e.g. schedules). Rejects the in-memory backend.
+ */
+export declare function parsePersistentStorageBackend(value: string | undefined): PersistentStorageBackend;

package/dist/cli/storage-backend-arguments.js

@@ -0,0 +1,16 @@
+const VALID_STORAGE_BACKENDS = new Set(["sqlite", "lmdb", "memory"]);
+function isValidStorageBackend(value) {
+  return VALID_STORAGE_BACKENDS.has(value);
+}
+export function parseStorageBackend(value) {
+  const storageValue = value ?? "sqlite";
+  if (!isValidStorageBackend(storageValue))
+    throw Error(`Invalid storage backend '${storageValue}'. Must be one of: sqlite, lmdb, memory`);
+  return storageValue;
+}
+export function parsePersistentStorageBackend(value) {
+  const storageValue = parseStorageBackend(value);
+  if (storageValue === "memory")
+    throw Error("Invalid storage backend 'memory'. Schedule commands support only sqlite and lmdb because data must persist across CLI invocations");
+  return storageValue;
+}

package/dist/cli/storage-factory.d.ts

@@ -0,0 +1,8 @@
+import type { Storage } from '../storage/interface.ts';
+import type { StorageBackend } from './types.ts';
+/**
+ * Creates a storage instance based on the selected backend and database path.
+ *
+ * Uses dynamic imports so that native addons are only loaded when requested.
+ */
+export declare function createStorage(backend: StorageBackend, database: string): Promise<Storage>;

package/dist/cli/storage-factory.js

@@ -0,0 +1,18 @@
+export async function createStorage(backend, database) {
+  switch (backend) {
+    case "sqlite": {
+      const { BunSQLiteStorage } = await import("../storage/bun-sql.js");
+      return new BunSQLiteStorage(database);
+    }
+    case "lmdb": {
+      const { LMDBStorage } = await import("../storage/lmdb.js");
+      return new LMDBStorage(database);
+    }
+    case "memory":
+      return createMemoryStorage();
+  }
+}
+async function createMemoryStorage() {
+  const { MemoryStorage } = await import("../storage/memory.js");
+  return new MemoryStorage;
+}

package/dist/cli/subcommand-detection.d.ts

@@ -0,0 +1,2 @@
+export declare const CLI_FLAG_VALUE_OPTIONS: Set<string>;
+export declare function findCliSubcommandName(args: readonly string[]): string | undefined;

package/dist/cli/subcommand-detection.js

@@ -0,0 +1,38 @@
+export const CLI_FLAG_VALUE_OPTIONS = new Set([
+  "-p",
+  "-d",
+  "-s",
+  "-w",
+  "-o",
+  "--port",
+  "--database",
+  "--storage",
+  "--workflows",
+  "--timeout",
+  "--server",
+  "--from",
+  "--token",
+  "--out",
+  "--input",
+  "--input-file",
+  "--describe",
+  "--profile",
+  "--shell",
+  "--type",
+  "--status",
+  "--limit",
+  "--id",
+  "--wait-timeout"
+]);
+export function findCliSubcommandName(args) {
+  for (let index = 0;index < args.length; index++) {
+    const arg = args[index];
+    if (arg.startsWith("-")) {
+      if (CLI_FLAG_VALUE_OPTIONS.has(arg) && !arg.includes("="))
+        index++;
+      continue;
+    }
+    return arg;
+  }
+  return;
+}

package/dist/cli/tail.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `weft tail <workflow-id>` — stream a workflow's token events as they replay
+ * from the server's Server-Sent Events endpoint (`GET /v1/workflows/:id/sse`).
+ *
+ * Each SSE frame is parsed into a structured event and emitted as one line:
+ * a compact JSON object under `--json` (valid NDJSON), or a TTY-formatted line
+ * otherwise. The stream ends on the server's `done` event, when the connection
+ * closes, or when the caller aborts (Ctrl-C) — all of which resolve cleanly
+ * with exit code 0 rather than leaving the reader hanging.
+ *
+ * The consumer is factored as {@link streamWorkflowEvents} so tests drive it
+ * with an injected `fetch` and `AbortSignal` instead of a real terminal.
+ *
+ * @module cli/tail
+ */
+import type { CommandOutput, TailCommand } from './types.ts';
+/** A single parsed SSE frame surfaced to the tail sink. */
+export type TailEvent = {
+    readonly id?: string;
+    readonly event: string;
+    readonly data: string;
+};
+/** Minimal `fetch` shape the tail consumer needs; lets tests inject a stub. */
+export type TailFetch = (url: URL, init: RequestInit) => Promise<Response>;
+/** Dependencies injected into {@link streamWorkflowEvents} for testing. */
+export type TailStreamOptions = {
+    readonly url: URL;
+    readonly token?: string;
+    readonly signal: AbortSignal;
+    /** Sink for streamed events (stdout, suppressed under `--quiet`). */
+    readonly write: (line: string) => void;
+    /** Sink for connection/status errors (stderr, never suppressed). Defaults to `write`. */
+    readonly reportError?: (line: string) => void;
+    readonly json: boolean;
+    readonly fetchImpl?: TailFetch;
+};
+/**
+ * Connect to the workflow SSE endpoint and emit each frame through `write`.
+ * Resolves when the stream ends, the server emits `done`, or the signal aborts.
+ * Returns the exit code (0 on a clean end/abort, non-zero on a failed connect).
+ */
+export declare function streamWorkflowEvents(options: TailStreamOptions): Promise<number>;
+/**
+ * Execute `weft tail`. Wires the process's SIGINT into an `AbortController` so
+ * Ctrl-C ends the stream cleanly, and writes events to stdout. A bare
+ * `weft tail` with no workflow id is not yet supported (system-wide tail needs
+ * a server-side multiplexed SSE route); it returns a usage error pointing at
+ * the per-workflow form.
+ */
+export declare function executeTail(command: TailCommand): Promise<CommandOutput>;