@lostgradient/weft 0.15.0 → 0.17.0

package/README.md

@@ -1,6 +1,6 @@
 # Weft
 
-A Bun-native durable execution engine. Current release: `0.15.0`.
+A Bun-native durable execution engine. Current release: `0.17.0`.
 
 Install the library from npm as `@lostgradient/weft`:
 

package/dist/alerting/alert-manager.d.ts

@@ -5,7 +5,7 @@
  *
  * @module alerting/alert-manager
  */
-import type { AlertState, AlertingOptions } from './types';
+import type { AlertStateSnapshot, AlertingOptions } from './types';
 /**
  * Event-driven alert manager that evaluates metric-based rules against sliding
  * time windows and fires `alert:fired` / `alert:resolved` lifecycle events.
@@ -38,7 +38,9 @@ export declare class AlertManager implements Disposable {
     constructor(target: EventTarget, options: AlertingOptions, getNow?: () => number, startBackgroundTick?: boolean);
     /** Re-evaluate every rule once, for hosts that drive maintenance explicitly. */
     tick(): void;
-    /** Get current state of all alert rules (for debugging/testing). */
-    get states(): readonly AlertState[];
+    /** Get a detached snapshot of all alert rules (for debugging/testing). */
+    get states(): readonly AlertStateSnapshot[];
+    /** Get detached snapshots of the alert rules that are currently firing. */
+    get activeStates(): readonly AlertStateSnapshot[];
     [Symbol.dispose](): void;
 }

package/dist/alerting/alert-manager.js

@@ -7,6 +7,15 @@ import {
 import { parseDuration } from "../core/scheduler.js";
 import { CounterWindow, HistogramWindow } from "./sliding-window.js";
 const TICK_INTERVAL_MS = 1e4;
+function snapshotAlertState(state) {
+  return {
+    rule: { ...state.rule },
+    status: state.status,
+    currentValue: state.currentValue,
+    ...state.lastFiredAt === void 0 ? {} : { lastFiredAt: state.lastFiredAt },
+    ...state.lastResolvedAt === void 0 ? {} : { lastResolvedAt: state.lastResolvedAt }
+  };
+}
 
 export class AlertManager {
   #target;
@@ -20,21 +29,30 @@ export class AlertManager {
   #tickInterval;
   constructor(target, options, getNow = Date.now, startBackgroundTick = !0) {
     this.#target = target;
-    this.#options = options;
+    this.#options = {
+      ...options,
+      rules: options.rules.map((rule) => ({ ...rule })),
+      ...options.webhooks === void 0 ? {} : {
+        webhooks: options.webhooks.map((webhook) => ({
+          ...webhook,
+          events: [...webhook.events]
+        }))
+      }
+    };
     this.#getNow = getNow;
     this.#latestStorageSize = 0;
     this.#pendingWebhooks = new Set;
     this.#listeners = [];
     this.#states = [];
-    for (const rule of options.rules)
+    for (const rule of this.#options.rules)
       this.#states.push({
         rule,
         status: "idle",
         currentValue: 0
       });
     this.#windows = new Map;
-    for (let i = 0;i < options.rules.length; i++) {
-      const rule = options.rules[i], windowMs = rule.window ? parseDuration(rule.window) : 60000;
+    for (let i = 0;i < this.#options.rules.length; i++) {
+      const rule = this.#options.rules[i], windowMs = rule.window ? parseDuration(rule.window) : 60000;
       if (rule.metric === "workflow.failure_rate")
         this.#windows.set(i, new CounterWindow(windowMs));
       else if (rule.metric === "activity.p99_duration")
@@ -153,7 +171,10 @@ export class AlertManager {
     }
   }
   get states() {
-    return this.#states;
+    return this.#states.map(snapshotAlertState);
+  }
+  get activeStates() {
+    return this.#states.filter((state) => state.status === "firing").map(snapshotAlertState);
   }
   [Symbol.dispose]() {
     if (this.#tickInterval !== null) {

package/dist/alerting/index.d.ts

@@ -1,2 +1,2 @@
 export { AlertManager } from './alert-manager';
-export type { AlertAction, AlertMetric, AlertRule, AlertState, AlertStatus, AlertingOptions, WebhookTarget, } from './types';
+export type { AlertAction, AlertMetric, AlertRule, AlertStateSnapshot, AlertStatus, AlertingOptions, WebhookTarget, } from './types';

package/dist/alerting/types.d.ts

@@ -6,6 +6,8 @@
  * {@link WebhookTarget} URLs.
  */
 export type AlertAction = 'log' | 'webhook';
+/** Runtime vocabulary shared by alerting types and operation schemas. */
+export declare const ALERT_METRICS: readonly ["workflow.failure_rate", "activity.p99_duration", "storage.size"];
 /**
  * Which built-in metric an {@link AlertRule} monitors.
  *
@@ -30,7 +32,7 @@ export type AlertAction = 'log' | 'webhook';
  * void rule;
  * ```
  */
-export type AlertMetric = 'workflow.failure_rate' | 'activity.p99_duration' | 'storage.size';
+export type AlertMetric = (typeof ALERT_METRICS)[number];
 /**
  * Defines a single alerting threshold applied to a named metric.
  *
@@ -124,7 +126,8 @@ export type AlertingOptions = {
  *
  * Transitions from `'idle'` to `'firing'` when the metric exceeds the
  * threshold and back to `'idle'` once the metric drops below it again.
- * Read this off an {@link AlertState} object to see the current state of a rule.
+ * Read this off an {@link AlertStateSnapshot} object to see the current state
+ * of a rule.
  *
  * @example
  * ```ts
@@ -141,17 +144,18 @@ export type AlertingOptions = {
  */
 export type AlertStatus = 'idle' | 'firing';
 /**
- * Runtime tracking state for a single {@link AlertRule} managed by
- * {@link AlertManager}.
+ * Detached, deeply read-only observation of a single alert rule's runtime
+ * state. The manager returns a fresh snapshot for every getter call, so
+ * changing it cannot affect alert evaluation.
  *
- * Users observe this shape via `AlertManager.states` to see the current
- * metric value, firing status, and timestamps of the last transition.  It is
- * created and owned by the manager — callers do not construct it directly.
+ * Users observe this shape via `AlertManager.states` or
+ * `Engine.getActiveAlerts()` to see the current metric value, firing status,
+ * and timestamps of the last transition.
  */
-export type AlertState = {
-    rule: AlertRule;
-    status: AlertStatus;
-    currentValue: number;
-    lastFiredAt?: number;
-    lastResolvedAt?: number;
+export type AlertStateSnapshot = {
+    readonly rule: Readonly<AlertRule>;
+    readonly status: AlertStatus;
+    readonly currentValue: number;
+    readonly lastFiredAt?: number;
+    readonly lastResolvedAt?: number;
 };

package/dist/alerting/types.js

@@ -0,0 +1,5 @@
+export const ALERT_METRICS = [
+  "workflow.failure_rate",
+  "activity.p99_duration",
+  "storage.size"
+];

package/dist/cli/api.js

@@ -1,6 +1,7 @@
 import { createLiveOperationRegistry } from "../server/rest-bindings.js";
 import { findNearestCandidate } from "./command-suggestions.js";
 import snapshotData from "./generated/operation-catalog.snapshot.json";
+import { loadJsonInput } from "./json-input.js";
 import { sendJsonRpcRequest } from "./json-rpc-client.js";
 const snapshot = snapshotData, operationByName = new Map(snapshot.operations.map((operation) => [operation.name, operation]));
 export async function executeApi(command) {
@@ -107,25 +108,10 @@ function formatOperationDescription(operation) {
 `);
 }
 async function readInput(command) {
-  if (command.input !== void 0)
-    return parseInput(command.input);
-  if (command.inputFile !== void 0) {
-    if (command.inputFile === "-")
-      return parseInput(await Bun.stdin.text());
-    const file = Bun.file(command.inputFile);
-    if (!await file.exists())
-      return { ok: !1, output: usageError(`api: input file not found: ${command.inputFile}`) };
-    return parseInput(await file.text());
-  }
-  return { ok: !0, value: {} };
-}
-function parseInput(source) {
-  try {
-    return { ok: !0, value: JSON.parse(source) };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { ok: !1, output: usageError(`api: invalid JSON input: ${message}`) };
-  }
+  const result = await loadJsonInput(command.input, command.inputFile);
+  if (!result.ok)
+    return { ok: !1, output: usageError(`api: ${result.error.message}`) };
+  return { ok: !0, value: result.value === void 0 ? {} : result.value };
 }
 function validateInput(operationName, input) {
   const operation = createLiveOperationRegistry().get(operationName);

package/dist/cli/console.d.ts

@@ -0,0 +1,12 @@
+import type { DashboardAssets, DashboardRouteTarget } from '../server/index.ts';
+export interface ConsoleMount {
+    dashboard: DashboardRouteTarget;
+    dashboardAssets: DashboardAssets;
+}
+export interface ConsoleModuleLoaderOptions {
+    cwd?: string;
+    resolveModule?: (specifier: string, cwd: string) => string;
+    importModule?: (url: string) => Promise<unknown>;
+}
+/** Resolve and load the optional console from the CLI user's environment. */
+export declare function loadConsoleMount(options?: ConsoleModuleLoaderOptions): Promise<ConsoleMount>;

package/dist/cli/console.js

@@ -0,0 +1,62 @@
+import { statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const CONSOLE_PACKAGE_NAME = "@lostgradient/weft-console";
+function defaultImportModule(url) {
+  return import(url);
+}
+function isDashboardRouteTarget(value) {
+  return typeof value === "function" || typeof value === "string" || value instanceof Response;
+}
+function isConsoleModule(value) {
+  return typeof value === "object" && value !== null;
+}
+function consoleError(message) {
+  return Error(`--console ${message}`);
+}
+function resolveConsoleEntry(cwd, resolveModule) {
+  try {
+    return resolveModule(CONSOLE_PACKAGE_NAME, cwd);
+  } catch {
+    throw consoleError(`requires ${CONSOLE_PACKAGE_NAME}. Install it in the CLI project: bun add ${CONSOLE_PACKAGE_NAME}`);
+  }
+}
+async function importConsoleModule(resolvedEntry, importModule) {
+  try {
+    const loaded = await importModule(pathToFileURL(resolvedEntry).href);
+    if (!isConsoleModule(loaded))
+      throw Error("module is not an object");
+    return loaded;
+  } catch {
+    throw consoleError(`could not load ${CONSOLE_PACKAGE_NAME}; reinstall or update it, then retry, or remove --console`);
+  }
+}
+function loadDashboard(module) {
+  if (typeof module.weftConsole !== "function")
+    throw consoleError(`${CONSOLE_PACKAGE_NAME} must export a weftConsole() function; update the package or remove --console`);
+  try {
+    const dashboard = module.weftConsole();
+    if (!isDashboardRouteTarget(dashboard))
+      throw Error("invalid dashboard route target");
+    return dashboard;
+  } catch {
+    throw consoleError(`${CONSOLE_PACKAGE_NAME} weftConsole() failed; reinstall or update it, then retry, or remove --console`);
+  }
+}
+function resolveConsoleAssets(resolvedEntry) {
+  const directory = join(dirname(fileURLToPath(pathToFileURL(resolvedEntry))), "assets");
+  try {
+    if (!statSync(directory).isDirectory())
+      throw Error("not a directory");
+  } catch {
+    throw consoleError(`${CONSOLE_PACKAGE_NAME} is missing its built assets; reinstall or update it, then retry, or remove --console`);
+  }
+  return { prefix: "/assets", directory };
+}
+export async function loadConsoleMount(options = {}) {
+  const cwd = options.cwd ?? process.cwd(), resolveModule = options.resolveModule ?? Bun.resolveSync, importModule = options.importModule ?? defaultImportModule, resolvedEntry = resolveConsoleEntry(cwd, resolveModule), module = await importConsoleModule(resolvedEntry, importModule);
+  return {
+    dashboard: loadDashboard(module),
+    dashboardAssets: resolveConsoleAssets(resolvedEntry)
+  };
+}

package/dist/cli/generated/operation-catalog.snapshot.json

@@ -98,6 +98,77 @@
         "type": "object"
       }
     },
+    {
+      "name": "weft.alerts.list",
+      "kind": "unary",
+      "summary": "List currently firing alerts",
+      "description": "List the alert rules that are currently firing, including their metric, threshold, current value, configured window, and firing timestamp. Read-only and limited to active in-memory alert state; resolved alerts are not returned.",
+      "tags": ["Observability"],
+      "destructive": false,
+      "access": {
+        "kind": "scoped",
+        "scopes": ["system:read"]
+      },
+      "transports": {
+        "http": true,
+        "jsonRpcHttp": true,
+        "jsonRpcWebSocket": true,
+        "jsonRpcStdio": true
+      },
+      "producibleFaults": [],
+      "inputSchema": {
+        "additionalProperties": false,
+        "properties": {},
+        "type": "object"
+      },
+      "outputSchema": {
+        "additionalProperties": false,
+        "properties": {
+          "items": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "currentValue": {
+                  "type": "number"
+                },
+                "firedAt": {
+                  "anyOf": [
+                    {
+                      "type": "number"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "metric": {
+                  "enum": ["workflow.failure_rate", "activity.p99_duration", "storage.size"],
+                  "type": "string"
+                },
+                "threshold": {
+                  "type": "number"
+                },
+                "window": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              },
+              "required": ["metric", "threshold", "currentValue", "window", "firedAt"],
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "required": ["items"],
+        "type": "object"
+      }
+    },
     {
       "name": "weft.events.sse",
       "kind": "stream",

package/dist/cli/generated/operation-client.generated.d.ts

@@ -1,7 +1,7 @@
 import { type CatalogWeftClient, type WeftClientConnection } from '../operation-client-runtime.ts';
-export declare const CATALOG_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.drain", "weft.workers.list", "weft.workers.resume", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
+export declare const CATALOG_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.drain", "weft.workers.list", "weft.workers.resume", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
 export type CatalogOperationName = (typeof CATALOG_OPERATION_NAMES)[number];
-export declare const CLIENT_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.diagnostics.deadletters.clear", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.drain", "weft.workers.list", "weft.workers.resume", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
+export declare const CLIENT_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.diagnostics.deadletters.clear", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.drain", "weft.workers.list", "weft.workers.resume", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
 export type ClientOperationName = (typeof CLIENT_OPERATION_NAMES)[number];
 export declare const CLIENT_REST_OPERATION_BINDINGS: {
     readonly 'weft.tasks.diagnostics.deadletters.clear': {
@@ -93,6 +93,19 @@ export type ClientOperationTypes = {
         };
         readonly faults: 'InvalidParams' | 'NotFound';
     };
+    'weft.alerts.list': {
+        readonly input: {};
+        readonly output: {
+            readonly items: ReadonlyArray<{
+                readonly currentValue: number;
+                readonly firedAt: unknown;
+                readonly metric: 'workflow.failure_rate' | 'activity.p99_duration' | 'storage.size';
+                readonly threshold: number;
+                readonly window: unknown;
+            }>;
+        };
+        readonly faults: never;
+    };
     'weft.recover.all': {
         readonly input: {};
         readonly output: {

package/dist/cli/generated/operation-client.generated.js

@@ -5,6 +5,7 @@ import {
 export const CATALOG_OPERATION_NAMES = [
   "weft.activities.complete",
   "weft.activities.fail",
+  "weft.alerts.list",
   "weft.recover.all",
   "weft.retention.get",
   "weft.reviews.decision.submit",
@@ -65,6 +66,7 @@ export const CATALOG_OPERATION_NAMES = [
 ], CLIENT_OPERATION_NAMES = [
   "weft.activities.complete",
   "weft.activities.fail",
+  "weft.alerts.list",
   "weft.recover.all",
   "weft.retention.get",
   "weft.reviews.decision.submit",

package/dist/cli/help-text.d.ts

@@ -1,4 +1,4 @@
-export declare const HELP_TEXT = "\nweft - Bun-native durable execution engine\n\nUsage: weft [command] [options]\n\nCommands:\n  serve           Start the Weft server (default)\n  doctor          Run diagnostics on the Weft database\n  conformance     Run RemoteWorker protocol conformance checks\n  schedule        Manage recurring schedules\n  timeline        Inspect workflow timeline and replay history\n  version:check   Check workflow version compatibility\n  validate        Lint workflow definitions for design-time anti-patterns\n  codegen         Generate TypeScript declarations from a registry snapshot\n  api             Inspect and invoke catalog operations on a running server\n  server          Inspect a running server's health and operation surface\n  workflow        List, inspect, start, signal, and cancel workflows on a server\n  tail            Stream a workflow's events as Server-Sent Events\n  completions     Generate or install shell completion scripts\n  version         Print the installed Weft version\n\nVersion (leading token only; a subcommand owns its own option line):\n  weft version | weft --version | weft -v   Print the installed Weft version\n\nServe Options:\n  -p, --port <port>           Server port (default: 7233)\n  -d, --database <path>       Database file path (default: ./weft.db)\n  -s, --storage <backend>     Storage backend: sqlite, lmdb, memory (default: sqlite)\n  -w, --workflows <path>      Path to workflow module to register on startup\n  -h, --help                  Show this help message\n";
+export declare const HELP_TEXT = "\nweft - Bun-native durable execution engine\n\nUsage: weft [command] [options]\n\nCommands:\n  serve           Start the Weft server (default)\n  doctor          Run diagnostics on the Weft database\n  conformance     Run RemoteWorker protocol conformance checks\n  schedule        Manage recurring schedules\n  timeline        Inspect workflow timeline and replay history\n  version:check   Check workflow version compatibility\n  validate        Lint workflow definitions for design-time anti-patterns\n  codegen         Generate TypeScript declarations from a registry snapshot\n  api             Inspect and invoke catalog operations on a running server\n  server          Inspect a running server's health and operation surface\n  workflow        List, inspect, start, signal, and cancel workflows on a server\n  tail            Stream a workflow's events as Server-Sent Events\n  completions     Generate or install shell completion scripts\n  version         Print the installed Weft version\n\nVersion (leading token only; a subcommand owns its own option line):\n  weft version | weft --version | weft -v   Print the installed Weft version\n\nServe Options:\n  -p, --port <port>           Server port (default: 7233)\n  -d, --database <path>       Database file path (default: ./weft.db)\n  -s, --storage <backend>     Storage backend: sqlite, lmdb, memory (default: sqlite)\n  -w, --workflows <path>      Path to workflow module to register on startup\n      --console               Mount @lostgradient/weft-console\n  -h, --help                  Show this help message\n";
 export declare const API_HELP_TEXT = "\nweft api - Inspect and invoke catalog operations on a running server\n\nUsage:\n  weft api --list [options]\n  weft api --describe <operation-name> [options]\n  weft api <operation-name> [--input <json> | --input-file <path|->] [options]\n\nOptions:\n      --server <url>       Server URL (default: WEFT_ADDR, profile, run lockfile, or localhost)\n      --token <token>      Bearer token (default: WEFT_TOKEN)\n      --profile <name>     Profile from ~/.weft/config (default: WEFT_PROFILE or default_profile)\n      --input <json>       JSON object input for the operation\n      --input-file <path>  Read JSON object input from a file, or '-' for stdin\n      --list               List catalog operations\n      --describe <name>    Print one operation's schema and metadata\n      --yes                Confirm destructive operations without prompting\n  -j, --json               Emit machine-readable JSON output\n  -h, --help               Show this help message\n\nExit codes:\n  0   Success\n  1   Operation failed or destructive operation was not confirmed\n  2   Connection error\n  3   Usage or input validation error\n";
 export declare const CONFORMANCE_HELP_TEXT = "\nweft conformance - Run RemoteWorker protocol conformance checks\n\nUsage: weft conformance [options] -- <worker-command> [args...]\n\nThe worker command receives:\n  WEFT_WORKER_URL\n  WEFT_WORKER_QUEUE\n  WEFT_WORKER_ACTIVITIES\n  WEFT_WORKER_PROTOCOL_VERSION\n\nOptions:\n      --timeout <ms>       Per-check timeout in milliseconds (default: 15000)\n  -j, --json               Output results as JSON\n  -h, --help               Show this help message\n";
 export declare const DOCTOR_HELP_TEXT = "\nweft doctor - Run diagnostics on the Weft database\n\nUsage: weft doctor [options]\n\nOptions:\n  -d, --database <path>   Database file path (default: ./weft.db)\n  -j, --json              Output results as JSON\n  -h, --help              Show this help message\n";

package/dist/cli/help-text.js

@@ -27,6 +27,7 @@ Serve Options:
   -d, --database <path>       Database file path (default: ./weft.db)
   -s, --storage <backend>     Storage backend: sqlite, lmdb, memory (default: sqlite)
   -w, --workflows <path>      Path to workflow module to register on startup
+      --console               Mount @lostgradient/weft-console
   -h, --help                  Show this help message
 `, API_HELP_TEXT = `
 weft api - Inspect and invoke catalog operations on a running server

package/dist/cli/index.d.ts

@@ -4,6 +4,7 @@ export { executeApi } from './api.ts';
 export { executeCodegen } from './codegen.ts';
 export { executeCompletions } from './completions.ts';
 export { executeConformance } from './conformance.ts';
+export { loadConsoleMount } from './console.ts';
 export { executeDoctor } from './doctor.ts';
 export { createWeftClient } from './generated/operation-client.generated.ts';
 export type { CatalogOperationName, WeftClient } from './generated/operation-client.generated.ts';

package/dist/cli/index.js

@@ -4,6 +4,7 @@ export { executeApi } from "./api.js";
 export { executeCodegen } from "./codegen.js";
 export { executeCompletions } from "./completions.js";
 export { executeConformance } from "./conformance.js";
+export { loadConsoleMount } from "./console.js";
 export { executeDoctor } from "./doctor.js";
 export { createWeftClient } from "./generated/operation-client.generated.js";
 export {

package/dist/cli/json-input.d.ts

@@ -0,0 +1,20 @@
+export type JsonInputFailure = {
+    readonly kind: 'invalid-json';
+    readonly detail: string;
+    readonly message: string;
+} | {
+    readonly kind: 'missing-file';
+    readonly message: string;
+    readonly path: string;
+};
+export type JsonInputResult = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: JsonInputFailure;
+};
+/** Parse one inline JSON source without applying a command-specific error format. */
+export declare function parseJsonInput(source: string): JsonInputResult;
+/** Load JSON from inline input, a file, or stdin without applying caller policy. */
+export declare function loadJsonInput(input: string | undefined, inputFile: string | undefined, readStdin?: () => Promise<string>): Promise<JsonInputResult>;

package/dist/cli/json-input.js

@@ -0,0 +1,33 @@
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export function parseJsonInput(source) {
+  try {
+    return { ok: !0, value: JSON.parse(source) };
+  } catch (error) {
+    const detail = errorMessage(error);
+    return {
+      ok: !1,
+      error: { kind: "invalid-json", detail, message: `invalid JSON input: ${detail}` }
+    };
+  }
+}
+export async function loadJsonInput(input, inputFile, readStdin = () => Bun.stdin.text()) {
+  if (input !== void 0)
+    return parseJsonInput(input);
+  if (inputFile === void 0)
+    return { ok: !0, value: void 0 };
+  if (inputFile === "-")
+    return parseJsonInput(await readStdin());
+  const file = Bun.file(inputFile);
+  if (!await file.exists())
+    return {
+      ok: !1,
+      error: {
+        kind: "missing-file",
+        message: `input file not found: ${inputFile}`,
+        path: inputFile
+      }
+    };
+  return parseJsonInput(await file.text());
+}

package/dist/cli/parse-arguments.js

@@ -75,6 +75,7 @@ function parseServeArguments(args) {
       database: { type: "string", short: "d", default: "./weft.db" },
       storage: { type: "string", short: "s", default: "sqlite" },
       help: { type: "boolean", short: "h", default: !1 },
+      console: { type: "boolean", default: !1 },
       workflows: { type: "string", short: "w" }
     },
     strict: !0,
@@ -89,6 +90,7 @@ function parseServeArguments(args) {
     database: values.database ?? "./weft.db",
     storage: parseStorageBackend(values.storage),
     help: values.help ?? !1,
+    console: values.console ?? !1,
     ...values.workflows ? { workflows: values.workflows } : {}
   };
 }

package/dist/cli/schedule.js

@@ -1,4 +1,5 @@
 import { registerOnRuntimeEngine, runtimeWorkflowEngine } from "../core/runtime-workflow-engine.js";
+import { parseJsonInput } from "./json-input.js";
 import { createStorage } from "./storage-factory.js";
 function formatScheduleCadence(schedule) {
   if (schedule.intervalMs !== void 0)
@@ -42,13 +43,6 @@ function getScheduleCreateValidationError(options) {
     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 definition of Object.values(loaded.registrations))
@@ -59,9 +53,13 @@ async function executeScheduleCreate(options, engine, loadRegistrationsFromModul
   if (validationError !== null)
     return { stdout: "", stderr: validationError, exitCode: 1 };
   await registerScheduleWorkflows(engine, options.workflows, loadRegistrationsFromModule);
-  const parsedInput = parseScheduleInput(options.input);
+  const parsedInput = parseJsonInput(options.input);
   if (!parsedInput.ok)
-    return { stdout: "", stderr: parsedInput.message, exitCode: 1 };
+    return {
+      stdout: "",
+      stderr: parsedInput.error.kind === "invalid-json" ? `Error: could not parse --input JSON: ${parsedInput.error.detail}` : `Error: ${parsedInput.error.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 } : {},

package/dist/cli/types.d.ts

@@ -10,6 +10,7 @@ export type CliCommand = {
     database: string;
     storage: StorageBackend;
     help: boolean;
+    console: boolean;
     workflows?: string;
 } | {
     command: 'version';

package/dist/cli/workflow-commands.js

@@ -1,7 +1,7 @@
+import { loadJsonInput } from "./json-input.js";
 import {
   confirmDestructive,
   formatTimestamp,
-  messageOf,
   ndjson,
   prettyJson,
   truncateToWidth
@@ -105,30 +105,10 @@ async function executeWorkflowEvents(command, connection) {
   }).join(`
 `), exitCode: 0 };
 }
-async function readInlineInput(input, inputFile) {
-  if (input !== void 0)
-    return parseJson(input);
-  if (inputFile !== void 0) {
-    if (inputFile === "-")
-      return parseJson(await Bun.stdin.text());
-    const file = Bun.file(inputFile);
-    if (!await file.exists())
-      return { ok: !1, message: `input file not found: ${inputFile}` };
-    return parseJson(await file.text());
-  }
-  return { ok: !0, value: void 0 };
-}
-function parseJson(source) {
-  try {
-    return { ok: !0, value: JSON.parse(source) };
-  } catch (error) {
-    return { ok: !1, message: `invalid JSON input: ${messageOf(error)}` };
-  }
-}
 async function executeWorkflowStart(command, connection) {
-  const parsed = await readInlineInput(command.input, command.inputFile);
+  const parsed = await loadJsonInput(command.input, command.inputFile);
   if (!parsed.ok)
-    return { stdout: "", stderr: `workflow start: ${parsed.message}`, exitCode: 3 };
+    return { stdout: "", stderr: `workflow start: ${parsed.error.message}`, exitCode: 3 };
   const result = await callCatalogOperation(connection, "weft.workflows.start", {
     type: command.workflowType,
     ...parsed.value === void 0 ? {} : { input: parsed.value },
@@ -169,9 +149,9 @@ async function executeWorkflowCancel(command, connection) {
   };
 }
 async function executeWorkflowSignal(command, connection) {
-  const parsed = await readInlineInput(command.input, command.inputFile);
+  const parsed = await loadJsonInput(command.input, command.inputFile);
   if (!parsed.ok)
-    return { stdout: "", stderr: `workflow signal: ${parsed.message}`, exitCode: 3 };
+    return { stdout: "", stderr: `workflow signal: ${parsed.error.message}`, exitCode: 3 };
   const result = await callCatalogOperation(connection, "weft.workflows.signal", {
     workflowId: command.workflowId,
     signalName: command.signalName,