@lostgradient/weft 0.2.0

package/dist/alerting/alert-manager.js

@@ -0,0 +1,167 @@
+import {
+  ActivityCompletedEvent,
+  AlertFiredEvent,
+  AlertResolvedEvent,
+  StorageSizeReportedEvent
+} from "../core/events.js";
+import { parseDuration } from "../core/scheduler.js";
+import { CounterWindow, HistogramWindow } from "./sliding-window.js";
+const TICK_INTERVAL_MS = 1e4;
+
+export class AlertManager {
+  #target;
+  #options;
+  #states;
+  #windows;
+  #listeners;
+  #latestStorageSize;
+  #pendingWebhooks;
+  #getNow;
+  #tickInterval;
+  constructor(target, options, getNow = Date.now) {
+    this.#target = target;
+    this.#options = options;
+    this.#getNow = getNow;
+    this.#latestStorageSize = 0;
+    this.#pendingWebhooks = new Set;
+    this.#listeners = [];
+    this.#states = [];
+    for (const rule of 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;
+      if (rule.metric === "workflow.failure_rate")
+        this.#windows.set(i, new CounterWindow(windowMs));
+      else if (rule.metric === "activity.p99_duration")
+        this.#windows.set(i, new HistogramWindow(windowMs));
+    }
+    this.#subscribeToEvents();
+    this.#tickInterval = setInterval(this.#evaluateAll.bind(this), TICK_INTERVAL_MS);
+  }
+  #evaluateAll() {
+    for (let i = 0;i < this.#options.rules.length; i++)
+      this.#evaluate(i);
+  }
+  #subscribeToEvents() {
+    const hasFailureRate = this.#options.rules.some((rule) => rule.metric === "workflow.failure_rate"), hasDuration = this.#options.rules.some((rule) => rule.metric === "activity.p99_duration");
+    if (hasFailureRate) {
+      const recordFailureRate = (failed) => {
+        const now = this.#getNow();
+        for (let i = 0;i < this.#options.rules.length; i++) {
+          if (this.#options.rules[i].metric !== "workflow.failure_rate")
+            continue;
+          this.#windows.get(i).record(now, failed);
+          this.#evaluate(i);
+        }
+      };
+      this.#addListener("workflow:completed", () => recordFailureRate(!1));
+      for (const eventType of [
+        "workflow:failed",
+        "workflow:timed-out",
+        "workflow:cancelled"
+      ])
+        this.#addListener(eventType, () => recordFailureRate(!0));
+    }
+    if (hasDuration)
+      this.#addListener("activity:completed", (event) => {
+        if (!(event instanceof ActivityCompletedEvent))
+          return;
+        const now = this.#getNow();
+        for (let i = 0;i < this.#options.rules.length; i++) {
+          if (this.#options.rules[i].metric !== "activity.p99_duration")
+            continue;
+          this.#windows.get(i).record(now, event.duration);
+          this.#evaluate(i);
+        }
+      });
+    if (this.#options.rules.some((rule) => rule.metric === "storage.size"))
+      this.#addListener("storage:size-reported", (event) => {
+        if (!(event instanceof StorageSizeReportedEvent))
+          return;
+        this.#latestStorageSize = event.sizeBytes;
+        for (let i = 0;i < this.#options.rules.length; i++) {
+          if (this.#options.rules[i].metric !== "storage.size")
+            continue;
+          this.#evaluate(i);
+        }
+      });
+  }
+  #addListener(type, handler) {
+    this.#listeners.push({ type, handler });
+    this.#target.addEventListener(type, handler);
+  }
+  #evaluate(ruleIndex) {
+    const rule = this.#options.rules[ruleIndex], state = this.#states[ruleIndex], now = this.#getNow();
+    let currentValue = 0;
+    const threshold = rule.threshold;
+    if (rule.metric === "workflow.failure_rate")
+      currentValue = this.#windows.get(ruleIndex).rate(now);
+    else if (rule.metric === "activity.p99_duration")
+      currentValue = this.#windows.get(ruleIndex).percentile(99, now);
+    else if (rule.metric === "storage.size")
+      currentValue = this.#latestStorageSize;
+    state.currentValue = currentValue;
+    if (currentValue >= threshold && state.status === "idle") {
+      state.status = "firing";
+      state.lastFiredAt = now;
+      this.#target.dispatchEvent(new AlertFiredEvent(rule.metric, threshold, currentValue, rule.window));
+      this.#executeAction(rule, "alert:fired", currentValue);
+    } else if (currentValue < threshold && state.status === "firing") {
+      state.status = "idle";
+      state.lastResolvedAt = now;
+      this.#target.dispatchEvent(new AlertResolvedEvent(rule.metric, threshold, currentValue, rule.window));
+      this.#executeAction(rule, "alert:resolved", currentValue);
+    }
+  }
+  #executeAction(rule, eventType, currentValue) {
+    if (rule.action === "log")
+      console.warn(`[weft:alert] ${eventType}: ${rule.metric} = ${currentValue} (threshold: ${rule.threshold})`);
+    if (rule.action === "webhook")
+      this.#sendWebhooks(rule, eventType, currentValue);
+  }
+  #sendWebhooks(rule, eventType, currentValue) {
+    const webhooks = this.#options.webhooks ?? [];
+    for (const target of webhooks) {
+      if (!target.events.includes(eventType))
+        continue;
+      const controller = new AbortController;
+      this.#pendingWebhooks.add(controller);
+      const payload = {
+        event: eventType,
+        alert: {
+          metric: rule.metric,
+          threshold: rule.threshold,
+          currentValue,
+          window: rule.window,
+          timestamp: this.#getNow()
+        }
+      };
+      fetch(target.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.any([controller.signal, AbortSignal.timeout(30000)])
+      }).catch(() => {}).finally(this.#pendingWebhooks.delete.bind(this.#pendingWebhooks, controller));
+    }
+  }
+  get states() {
+    return this.#states;
+  }
+  [Symbol.dispose]() {
+    if (this.#tickInterval !== null) {
+      clearInterval(this.#tickInterval);
+      this.#tickInterval = null;
+    }
+    for (const { type, handler } of this.#listeners)
+      this.#target.removeEventListener(type, handler);
+    this.#listeners = [];
+    for (const controller of this.#pendingWebhooks)
+      controller.abort();
+    this.#pendingWebhooks.clear();
+  }
+}

package/dist/alerting/index.d.ts

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

package/dist/alerting/index.js

@@ -0,0 +1 @@
+export { AlertManager } from "./alert-manager.js";

package/dist/alerting/sliding-window.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Sliding time window data structures for metric computation.
+ *
+ * Both windows use a chronologically-ordered deque and binary search for
+ * pruning, keeping amortized cost O(log n) per event rather than O(n).
+ *
+ * @module alerting/sliding-window
+ */
+/** Tracks event counts for rate computation (e.g., failure_rate). */
+export declare class CounterWindow {
+    #private;
+    constructor(windowMs: number);
+    /** Record an event with its timestamp and failure status. */
+    record(timestamp: number, failed: boolean): void;
+    /** Returns failure rate as a number between 0 and 1. Returns 0 if no events. */
+    rate(now: number): number;
+}
+/** Stores individual values for percentile computation (e.g., p99 duration). */
+export declare class HistogramWindow {
+    #private;
+    constructor(windowMs: number);
+    /** Record an observation with its timestamp. */
+    record(timestamp: number, value: number): void;
+    /** Returns the p-th percentile value (p between 0 and 100). Returns 0 if no observations. */
+    percentile(p: number, now: number): number;
+}

package/dist/alerting/sliding-window.js

@@ -0,0 +1,97 @@
+function lowerBound(entries, cutoff) {
+  let lo = 0, hi = entries.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (entries[mid].timestamp < cutoff)
+      lo = mid + 1;
+    else
+      hi = mid;
+  }
+  return lo;
+}
+
+export class CounterWindow {
+  #windowMs;
+  #events;
+  #failureCount;
+  constructor(windowMs) {
+    this.#windowMs = windowMs;
+    this.#events = [];
+    this.#failureCount = 0;
+  }
+  record(timestamp, failed) {
+    this.#events.push({ timestamp, failed });
+    if (failed)
+      this.#failureCount++;
+    this.#prune(timestamp);
+  }
+  rate(now) {
+    this.#prune(now);
+    if (this.#events.length === 0)
+      return 0;
+    return this.#failureCount / this.#events.length;
+  }
+  #prune(now) {
+    const cutoff = now - this.#windowMs, start = lowerBound(this.#events, cutoff);
+    if (start === 0)
+      return;
+    for (let i = 0;i < start; i++)
+      if (this.#events[i].failed)
+        this.#failureCount--;
+    this.#events.splice(0, start);
+  }
+}
+
+export class HistogramWindow {
+  #windowMs;
+  #observations;
+  #sortedValues;
+  constructor(windowMs) {
+    this.#windowMs = windowMs;
+    this.#observations = [];
+    this.#sortedValues = [];
+  }
+  record(timestamp, value) {
+    this.#observations.push({ timestamp, value });
+    this.#insertSorted(value);
+    this.#prune(timestamp);
+  }
+  percentile(p, now) {
+    this.#prune(now);
+    if (this.#sortedValues.length === 0)
+      return 0;
+    const index = Math.ceil(p / 100 * this.#sortedValues.length) - 1;
+    return this.#sortedValues[Math.max(0, index)] ?? 0;
+  }
+  #insertSorted(value) {
+    let lo = 0, hi = this.#sortedValues.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (this.#sortedValues[mid] < value)
+        lo = mid + 1;
+      else
+        hi = mid;
+    }
+    this.#sortedValues.splice(lo, 0, value);
+  }
+  #removeSorted(value) {
+    let lo = 0, hi = this.#sortedValues.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (this.#sortedValues[mid] < value)
+        lo = mid + 1;
+      else
+        hi = mid;
+    }
+    if (lo < this.#sortedValues.length && this.#sortedValues[lo] === value)
+      this.#sortedValues.splice(lo, 1);
+  }
+  #prune(now) {
+    const cutoff = now - this.#windowMs, start = lowerBound(this.#observations, cutoff);
+    if (start === 0)
+      return;
+    for (let i = 0;i < start; i++)
+      this.#removeSorted(this.#observations[i].value);
+    this.#observations.splice(0, start);
+  }
+}

package/dist/alerting/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * What an alert rule does when its threshold is exceeded.
+ *
+ * `'log'` writes to the engine's console; `'webhook'` POSTs an
+ * `alert:fired` or `alert:resolved` payload to the configured
+ * {@link WebhookTarget} URLs.
+ */
+export type AlertAction = 'log' | 'webhook';
+/**
+ * Which built-in metric an {@link AlertRule} monitors.
+ *
+ * - `'workflow.failure_rate'` — fraction of workflows that failed within the
+ *   sliding window.
+ * - `'activity.p99_duration'` — 99th-percentile activity execution duration in
+ *   milliseconds.
+ * - `'storage.size'` — total storage size in bytes as reported by the engine's
+ *   `StorageSizeReported` event.
+ *
+ * @example
+ * ```ts
+ * import { type AlertMetric, type AlertRule } from '@lostgradient/weft';
+ *
+ * const metric: AlertMetric = 'workflow.failure_rate';
+ * const rule: AlertRule = {
+ *   metric,
+ *   threshold: 0.1,
+ *   window: '5m',
+ *   action: 'log',
+ * };
+ * void rule;
+ * ```
+ */
+export type AlertMetric = 'workflow.failure_rate' | 'activity.p99_duration' | 'storage.size';
+/**
+ * Defines a single alerting threshold applied to a named metric.
+ *
+ * When the metric's current value in the sliding window exceeds `threshold`,
+ * the configured `action` is triggered.  An optional `window` duration string
+ * (e.g. `'5m'`, `'1m'`) controls how far back the evaluation looks; it defaults
+ * to one minute when omitted.
+ *
+ * @example
+ * ```ts
+ * import { AlertManager, type AlertRule } from '@lostgradient/weft';
+ *
+ * const rule: AlertRule = {
+ *   metric: 'workflow.failure_rate',
+ *   threshold: 0.05,
+ *   window: '10m',
+ *   action: 'webhook',
+ * };
+ *
+ * const engine = new EventTarget();
+ * using manager = new AlertManager(engine, { rules: [rule] });
+ * void manager;
+ * ```
+ */
+export type AlertRule = {
+    metric: AlertMetric;
+    threshold: number;
+    window?: string;
+    action: AlertAction;
+};
+/**
+ * Webhook destination that receives `alert:fired` and `alert:resolved` HTTP
+ * POST requests from the {@link AlertManager}.
+ *
+ * Specify which event types to subscribe to via the `events` array.  Both
+ * `alert:fired` and `alert:resolved` are sent as JSON objects with the rule
+ * and current metric value.
+ *
+ * @example
+ * ```ts
+ * import { AlertManager, type WebhookTarget, type AlertingOptions } from '@lostgradient/weft';
+ *
+ * const target: WebhookTarget = {
+ *   url: 'https://hooks.example.com/alerts',
+ *   events: ['alert:fired', 'alert:resolved'],
+ * };
+ *
+ * const options: AlertingOptions = {
+ *   rules: [{ metric: 'workflow.failure_rate', threshold: 0.1, action: 'webhook' }],
+ *   webhooks: [target],
+ * };
+ * const engine = new EventTarget();
+ * using manager = new AlertManager(engine, options);
+ * void manager;
+ * ```
+ */
+export type WebhookTarget = {
+    url: string;
+    events: Array<'alert:fired' | 'alert:resolved'>;
+};
+/**
+ * Top-level alerting configuration passed to {@link AlertManager}.
+ *
+ * Provide an array of {@link AlertRule} definitions that the manager evaluates
+ * continuously against the engine's event stream.  Optionally supply
+ * {@link WebhookTarget} destinations for `alert:fired` and `alert:resolved`
+ * notifications.
+ *
+ * @example
+ * ```ts
+ * import { AlertManager, type AlertingOptions } from '@lostgradient/weft';
+ *
+ * const options: AlertingOptions = {
+ *   rules: [
+ *     { metric: 'workflow.failure_rate', threshold: 0.1, window: '5m', action: 'log' },
+ *     { metric: 'activity.p99_duration', threshold: 5000, action: 'webhook' },
+ *   ],
+ *   webhooks: [{ url: 'https://hooks.example.com', events: ['alert:fired'] }],
+ * };
+ * const engine = new EventTarget();
+ * using manager = new AlertManager(engine, options);
+ * void manager;
+ * ```
+ */
+export type AlertingOptions = {
+    rules: AlertRule[];
+    webhooks?: WebhookTarget[];
+};
+/**
+ * Whether an alert rule is currently quiet or actively firing.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { AlertManager, type AlertStatus } from '@lostgradient/weft';
+ *
+ * const engine = new EventTarget();
+ * using manager = new AlertManager(engine, {
+ *   rules: [{ metric: 'workflow.failure_rate', threshold: 0.05, action: 'log' }],
+ * });
+ * const states = manager.states;
+ * const status: AlertStatus = states[0]?.status ?? 'idle';
+ * console.log(status); // 'idle'
+ * ```
+ */
+export type AlertStatus = 'idle' | 'firing';
+/**
+ * Runtime tracking state for a single {@link AlertRule} managed by
+ * {@link AlertManager}.
+ *
+ * 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.
+ */
+export type AlertState = {
+    rule: AlertRule;
+    status: AlertStatus;
+    currentValue: number;
+    lastFiredAt?: number;
+    lastResolvedAt?: number;
+};

package/dist/cli/api-arguments.d.ts

@@ -0,0 +1,2 @@
+import type { CliCommand } from './types.ts';
+export declare function parseApiArguments(args: string[]): CliCommand;

package/dist/cli/api-arguments.js

@@ -0,0 +1,48 @@
+import { parseArgs } from "node:util";
+export function parseApiArguments(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      server: { type: "string" },
+      token: { type: "string" },
+      profile: { type: "string" },
+      input: { type: "string" },
+      "input-file": { type: "string" },
+      list: { type: "boolean", default: !1 },
+      describe: { type: "string" },
+      yes: { type: "boolean", default: !1 },
+      help: { type: "boolean", short: "h", default: !1 },
+      json: { type: "boolean", short: "j", default: !1 }
+    },
+    strict: !0,
+    allowPositionals: !0
+  });
+  validateApiArguments(values, positionals);
+  return {
+    command: "api",
+    ...optionalField("operationName", positionals[0]),
+    ...optionalField("server", values.server),
+    ...optionalField("token", values.token),
+    ...optionalField("profile", values.profile),
+    ...optionalField("input", values.input),
+    ...optionalField("inputFile", values["input-file"]),
+    list: values.list ?? !1,
+    ...optionalField("describe", values.describe),
+    yes: values.yes ?? !1,
+    help: values.help ?? !1,
+    json: values.json ?? !1
+  };
+}
+function validateApiArguments(values, positionals) {
+  if (positionals.length > 1)
+    throw Error("api: expected at most one operation name");
+  if (values.input !== void 0 && values["input-file"] !== void 0)
+    throw Error("api: --input and --input-file cannot be used together");
+  if (values.describe !== void 0 && positionals.length > 0)
+    throw Error("api: --describe cannot be combined with an operation name");
+  if (values.list === !0 && (values.describe !== void 0 || positionals.length > 0))
+    throw Error("api: --list cannot be combined with --describe or an operation name");
+}
+function optionalField(key, value) {
+  return value === void 0 ? {} : { [key]: value };
+}

package/dist/cli/api.d.ts

@@ -0,0 +1,13 @@
+import type { CliCommand, CommandOutput } from './types.ts';
+type ApiCommand = Extract<CliCommand, {
+    command: 'api';
+}>;
+export declare function executeApi(command: ApiCommand): Promise<CommandOutput>;
+export declare function normalizeValidatedInput(operationName: string, parsedData: unknown): {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    output: CommandOutput;
+};
+export {};