unfazed 0.4.0 → 0.6.0

package/dist/workflow/index.js

@@ -0,0 +1,23 @@
+/**
+ * `unfazed/workflow` — the unfazed World for Workflow SDK.
+ *
+ * ```ts
+ * import { setWorld } from "workflow/runtime";
+ * import { createWorld } from "unfazed/workflow";
+ *
+ * setWorld(createWorld());   // before the server serves
+ * ```
+ *
+ * With Nitro, add `"unfazed/workflow/nitro"` to `modules` instead; it does
+ * exactly that for you. Requires the optional peers `workflow`,
+ * `@workflow/world` and `@workflow/world-postgres`.
+ */
+export { createWorld, LOCAL_DEPLOYMENT_ID } from "./world.js";
+export { UnfazedWorkflowError } from "./errors.js";
+export { DATABASE_URL_VARS, resolveDatabaseUrl, withLibpqCompat } from "./config.js";
+export { applyPublicUrl } from "./public-url.js";
+export { DELIVERY_HEADERS, QUEUE_API_PATH, verifyQueueToken } from "./queue.js";
+export { createInspectHandler, INSPECT_BASE_PATH, INSPECT_CONTRACT_VERSION } from "./inspect.js";
+export { MIGRATIONS_SCHEMA, MIGRATIONS_TABLE } from "./migration-types.js";
+export { embeddedMigrations } from "./migrations.generated.js";
+//# sourceMappingURL=index.js.map

package/dist/workflow/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflow/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAIjG,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC","sourcesContent":["/**\n * `unfazed/workflow` — the unfazed World for Workflow SDK.\n *\n * ```ts\n * import { setWorld } from \"workflow/runtime\";\n * import { createWorld } from \"unfazed/workflow\";\n *\n * setWorld(createWorld());   // before the server serves\n * ```\n *\n * With Nitro, add `\"unfazed/workflow/nitro\"` to `modules` instead; it does\n * exactly that for you. Requires the optional peers `workflow`,\n * `@workflow/world` and `@workflow/world-postgres`.\n */\nexport { createWorld, LOCAL_DEPLOYMENT_ID } from \"./world.js\";\nexport type { UnfazedWorld, UnfazedWorldOptions } from \"./world.js\";\nexport { UnfazedWorkflowError } from \"./errors.js\";\nexport type { UnfazedWorkflowErrorCode } from \"./errors.js\";\nexport { DATABASE_URL_VARS, resolveDatabaseUrl, withLibpqCompat } from \"./config.js\";\nexport { applyPublicUrl } from \"./public-url.js\";\nexport type { PublicUrlResult } from \"./public-url.js\";\nexport type { WorkflowEnv } from \"./config.js\";\nexport { DELIVERY_HEADERS, QUEUE_API_PATH, verifyQueueToken } from \"./queue.js\";\nexport { createInspectHandler, INSPECT_BASE_PATH, INSPECT_CONTRACT_VERSION } from \"./inspect.js\";\nexport type { InspectHandlerOptions, InspectRunHandle } from \"./inspect.js\";\nexport type { InspectError, InspectValue } from \"./inspect-render.js\";\nexport type { QueueStats, WorkflowFetch } from \"./queue.js\";\nexport { MIGRATIONS_SCHEMA, MIGRATIONS_TABLE } from \"./migration-types.js\";\nexport type { WorkflowMigrations } from \"./migration-types.js\";\nexport { embeddedMigrations } from \"./migrations.generated.js\";\n"]}

package/dist/workflow/inspect-render.d.ts

@@ -0,0 +1,93 @@
+/** A payload as display text (`Value` in the contract). */
+export interface InspectValue {
+    text: string;
+    /** UTF-8 length of the whole text, before any cut. */
+    bytes: number;
+    truncated: boolean;
+    /** Present (true) only when the payload could not be hydrated; `text` is the reason. */
+    error?: true;
+}
+/** A thrown run or step error (`Error` in the contract). */
+export interface InspectError {
+    message: string;
+    stack: string | null;
+    code: string | null;
+    truncated: boolean;
+}
+export declare const MESSAGE_CAP_BYTES: number;
+export declare const STACK_CAP_BYTES: number;
+export declare const INFO_CAP_BYTES: number;
+export interface DisplayOptions {
+    /**
+     * Strings to replace with `[redacted]` wherever they occur in a string
+     * (hook tokens, so neither a token nor a webhook URL built from one leaves).
+     */
+    secrets?: readonly string[];
+    /** Drop every object key named `token`, at any depth. */
+    dropTokenKeys?: boolean;
+}
+export declare const REDACTED = "[redacted]";
+/** Workflow SDK's webhook route; the path segment after it is the hook's token. */
+export declare const WEBHOOK_PATH = "/.well-known/workflow/v1/webhook/";
+/**
+ * `text` with the token of every Workflow SDK webhook URL in it replaced by
+ * `[redacted]`: `https://app.example/.well-known/workflow/v1/webhook/<token>?a=1`
+ * reads `https://app.example/.well-known/workflow/v1/webhook/[redacted]?a=1`.
+ * A webhook URL is a capability (anyone holding it resumes the run), so none
+ * leaves the route, whatever the app wrote it into.
+ */
+export declare function redactWebhookTokens(text: string): string;
+/** UTF-8 length of `text`. */
+export declare function utf8Length(text: string): number;
+/**
+ * `text` cut to at most `capBytes` of UTF-8 on a character boundary, and
+ * whether it was cut.
+ */
+export declare function cutUtf8(text: string, capBytes: number): {
+    text: string;
+    truncated: boolean;
+    bytes: number;
+};
+/**
+ * The contract's replacer, as a walk that builds a JSON-safe tree:
+ * `bigint` → `"123n"`, `undefined` → `null`, `Map` → `{"$map": [[k, v], …]}`,
+ * `Set` → `{"$set": […]}`, bytes → `{"$bytes": n}`, `Error` →
+ * `{"$error": {name, message, stack}}`, a function → `"[function name]"`, a
+ * cycle → `"[circular]"`; anything with `toJSON()` (the revivers' display
+ * objects, `Date`, `URL`) goes through it first, as `JSON.stringify` does.
+ */
+export declare function toDisplayJson(value: unknown, options?: DisplayOptions): unknown;
+/** `JSON.stringify(value, replacer, 2)` of the contract. */
+export declare function displayText(value: unknown, options?: DisplayOptions): string;
+/** A hydrated payload as a `Value`, cut at `capBytes`; `undefined`/`null` is `null`. */
+export declare function renderValue(value: unknown, capBytes: number, options?: DisplayOptions): InspectValue | null;
+/** A payload that failed to hydrate (or to render): the error's message, flagged. */
+export declare function failedValue(error: unknown, capBytes: number): InspectValue;
+/**
+ * A hydrated run or step error as the contract's `Error`: `message` at most
+ * 4 KiB, `stack` at most 8 KiB or `null`, `code` as given.
+ */
+export declare function renderError(hydrated: unknown, code: string | null, failure: unknown, options?: DisplayOptions): InspectError;
+type InfoJson = string | number | boolean | null | InfoJson[] | {
+    [key: string]: InfoJson;
+};
+/**
+ * An event's `info`: its `eventData` as `resolveData: "none"` leaves it, every
+ * `token` key removed at any depth, only strings, numbers, booleans, `null`
+ * and objects/arrays of those kept (a `Date` becomes its RFC 3339 string); at
+ * most 2 KiB serialized, else `{}` and truncated.
+ */
+export declare function eventInfo(eventData: unknown): {
+    info: Record<string, InfoJson>;
+    truncated: boolean;
+};
+/** RFC 3339 UTC with milliseconds, or `null`. */
+export declare function isoTime(value: unknown): string | null;
+/**
+ * A step's input as the SDK's own inspector shows it: its arguments. Workflow
+ * SDK stores a step's input as `{ args, closureVars, thisVal }`; this answers
+ * `args` alone, or `{ args, closureVars?, thisVal? }` with only the parts that
+ * hold something. Anything not exactly that envelope is returned as it is.
+ */
+export declare function stepInputDisplay(input: unknown): unknown;
+export {};

package/dist/workflow/inspect-render.js

@@ -0,0 +1,302 @@
+/**
+ * How the inspection route turns World data into the display JSON of the
+ * contract (unfazed docs/workflow-inspect.md, "Values", "Errors", `Event`).
+ * Pure functions, no SDK imports: the caller hydrates, this renders.
+ */
+import { Buffer } from "node:buffer";
+export const MESSAGE_CAP_BYTES = 4 * 1024;
+export const STACK_CAP_BYTES = 8 * 1024;
+export const INFO_CAP_BYTES = 2 * 1024;
+export const REDACTED = "[redacted]";
+/** Workflow SDK's webhook route; the path segment after it is the hook's token. */
+export const WEBHOOK_PATH = "/.well-known/workflow/v1/webhook/";
+// The route as written, also with JSON-escaped slashes (`\/`), then its token:
+// one path segment of RFC 3986 characters (what `encodeURIComponent` emits,
+// plus `%`), so a query string, fragment, quote or space after it stays.
+const WEBHOOK_URL = /(\\?\/\.well-known\\?\/workflow\\?\/v1\\?\/webhook\\?\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%]+/g;
+// The same URL percent-encoded inside another URL (`?next=https%3A%2F%2F…`).
+const WEBHOOK_URL_ENCODED = /(%2F\.well-known%2Fworkflow%2Fv1%2Fwebhook%2F)[A-Za-z0-9\-._~!$'()*+,;:@%]+/gi;
+/**
+ * `text` with the token of every Workflow SDK webhook URL in it replaced by
+ * `[redacted]`: `https://app.example/.well-known/workflow/v1/webhook/<token>?a=1`
+ * reads `https://app.example/.well-known/workflow/v1/webhook/[redacted]?a=1`.
+ * A webhook URL is a capability (anyone holding it resumes the run), so none
+ * leaves the route, whatever the app wrote it into.
+ */
+export function redactWebhookTokens(text) {
+    if (!text.includes("well-known"))
+        return text;
+    return text.replace(WEBHOOK_URL, `$1${REDACTED}`).replace(WEBHOOK_URL_ENCODED, `$1${REDACTED}`);
+}
+/** UTF-8 length of `text`. */
+export function utf8Length(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/**
+ * `text` cut to at most `capBytes` of UTF-8 on a character boundary, and
+ * whether it was cut.
+ */
+export function cutUtf8(text, capBytes) {
+    const bytes = utf8Length(text);
+    if (bytes <= capBytes)
+        return { text, truncated: false, bytes };
+    const encoded = Buffer.from(text, "utf8");
+    let end = capBytes;
+    // Back off continuation bytes (10xxxxxx) so no code point is split.
+    while (end > 0 && (encoded[end] & 0xc0) === 0x80)
+        end--;
+    return { text: encoded.subarray(0, end).toString("utf8"), truncated: true, bytes };
+}
+/**
+ * The contract's replacer, as a walk that builds a JSON-safe tree:
+ * `bigint` → `"123n"`, `undefined` → `null`, `Map` → `{"$map": [[k, v], …]}`,
+ * `Set` → `{"$set": […]}`, bytes → `{"$bytes": n}`, `Error` →
+ * `{"$error": {name, message, stack}}`, a function → `"[function name]"`, a
+ * cycle → `"[circular]"`; anything with `toJSON()` (the revivers' display
+ * objects, `Date`, `URL`) goes through it first, as `JSON.stringify` does.
+ */
+export function toDisplayJson(value, options = {}) {
+    const secrets = (options.secrets ?? []).filter((s) => s.length > 0);
+    const ancestors = new Set();
+    const str = (text) => {
+        let out = text;
+        for (const secret of secrets)
+            if (out.includes(secret))
+                out = out.split(secret).join(REDACTED);
+        return redactWebhookTokens(out);
+    };
+    const walk = (input, key) => {
+        let v = input;
+        if (v !== null && typeof v === "object" && !(v instanceof Error) && !ArrayBuffer.isView(v)) {
+            const toJSON = v.toJSON;
+            if (typeof toJSON === "function") {
+                if (ancestors.has(v))
+                    return "[circular]";
+                v = toJSON.call(v, key);
+            }
+        }
+        switch (typeof v) {
+            case "undefined":
+                return null;
+            case "string":
+                return str(v);
+            case "number":
+                return Number.isFinite(v) ? v : null;
+            case "boolean":
+                return v;
+            case "bigint":
+                return `${v}n`;
+            case "function":
+                return `[function ${v.name || "anonymous"}]`;
+            case "symbol":
+                return str(v.toString());
+        }
+        if (v === null)
+            return null;
+        const obj = v;
+        if (obj instanceof ArrayBuffer)
+            return { $bytes: obj.byteLength };
+        if (ArrayBuffer.isView(obj))
+            return { $bytes: obj.byteLength };
+        if (ancestors.has(obj))
+            return "[circular]";
+        ancestors.add(obj);
+        try {
+            if (obj instanceof Error) {
+                return {
+                    $error: {
+                        name: str(String(obj.name)),
+                        message: str(String(obj.message)),
+                        stack: typeof obj.stack === "string" ? str(obj.stack) : null,
+                    },
+                };
+            }
+            if (obj instanceof Map) {
+                const entries = [];
+                for (const [k, item] of obj) {
+                    if (options.dropTokenKeys && k === "token")
+                        continue;
+                    entries.push([walk(k, ""), walk(item, typeof k === "string" ? k : "")]);
+                }
+                return { $map: entries };
+            }
+            if (obj instanceof Set)
+                return { $set: [...obj].map((item, i) => walk(item, String(i))) };
+            if (typeof Headers !== "undefined" && obj instanceof Headers) {
+                const out = {};
+                obj.forEach((item, name) => {
+                    out[name] = str(item);
+                });
+                return out;
+            }
+            if (obj instanceof RegExp)
+                return str(String(obj));
+            if (Array.isArray(obj))
+                return obj.map((item, i) => walk(item, String(i)));
+            const out = {};
+            for (const k of Object.keys(obj)) {
+                if (options.dropTokenKeys && k === "token")
+                    continue;
+                out[str(k)] = walk(obj[k], k);
+            }
+            return out;
+        }
+        finally {
+            ancestors.delete(obj);
+        }
+    };
+    return walk(value, "");
+}
+/** `JSON.stringify(value, replacer, 2)` of the contract. */
+export function displayText(value, options = {}) {
+    return JSON.stringify(toDisplayJson(value, options), null, 2) ?? "null";
+}
+/** A hydrated payload as a `Value`, cut at `capBytes`; `undefined`/`null` is `null`. */
+export function renderValue(value, capBytes, options = {}) {
+    if (value === undefined || value === null)
+        return null;
+    let text;
+    try {
+        text = displayText(value, options);
+    }
+    catch (error) {
+        return failedValue(error, capBytes);
+    }
+    const cut = cutUtf8(text, capBytes);
+    return { text: cut.text, bytes: cut.bytes, truncated: cut.truncated };
+}
+/** A payload that failed to hydrate (or to render): the error's message, flagged. */
+export function failedValue(error, capBytes) {
+    const message = redactWebhookTokens(error instanceof Error ? error.message : String(error));
+    const cut = cutUtf8(message || "the payload could not be read", capBytes);
+    return { text: cut.text, bytes: cut.bytes, truncated: false, error: true };
+}
+/**
+ * A hydrated run or step error as the contract's `Error`: `message` at most
+ * 4 KiB, `stack` at most 8 KiB or `null`, `code` as given.
+ */
+export function renderError(hydrated, code, failure, options = {}) {
+    let message;
+    let stack = null;
+    if (failure !== undefined) {
+        message = `the error could not be read: ${failure instanceof Error ? failure.message : String(failure)}`;
+    }
+    else if (hydrated === undefined || hydrated === null) {
+        message = "(no error recorded)";
+    }
+    else if (typeof hydrated === "string") {
+        message = hydrated;
+    }
+    else if (hydrated !== null &&
+        typeof hydrated === "object" &&
+        typeof hydrated.message === "string") {
+        message = hydrated.message;
+        const rawStack = hydrated.stack;
+        stack = typeof rawStack === "string" ? rawStack : null;
+    }
+    else {
+        try {
+            message = displayText(hydrated, options);
+        }
+        catch (error) {
+            message = `the error could not be read: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+    const secrets = (options.secrets ?? []).filter((s) => s.length > 0);
+    const scrub = (text) => redactWebhookTokens(secrets.reduce((out, secret) => out.split(secret).join(REDACTED), text));
+    const m = cutUtf8(scrub(message), MESSAGE_CAP_BYTES);
+    const s = stack === null ? null : cutUtf8(scrub(stack), STACK_CAP_BYTES);
+    return { message: m.text, stack: s ? s.text : null, code, truncated: m.truncated || (s?.truncated ?? false) };
+}
+/**
+ * An event's `info`: its `eventData` as `resolveData: "none"` leaves it, every
+ * `token` key removed at any depth, only strings, numbers, booleans, `null`
+ * and objects/arrays of those kept (a `Date` becomes its RFC 3339 string); at
+ * most 2 KiB serialized, else `{}` and truncated.
+ */
+export function eventInfo(eventData) {
+    const sanitize = (v, depth) => {
+        if (v === null)
+            return null;
+        if (v instanceof Date)
+            return Number.isNaN(v.getTime()) ? undefined : v.toISOString();
+        switch (typeof v) {
+            case "string":
+                return redactWebhookTokens(v);
+            case "boolean":
+                return v;
+            case "number":
+                return Number.isFinite(v) ? v : undefined;
+            case "object": {
+                if (depth > 32 || ArrayBuffer.isView(v) || v instanceof ArrayBuffer)
+                    return undefined;
+                if (Array.isArray(v)) {
+                    return v.map((item) => sanitize(item, depth + 1)).filter((item) => item !== undefined);
+                }
+                const proto = Object.getPrototypeOf(v);
+                if (proto !== Object.prototype && proto !== null)
+                    return undefined;
+                const out = {};
+                for (const [k, item] of Object.entries(v)) {
+                    if (k === "token")
+                        continue;
+                    const clean = sanitize(item, depth + 1);
+                    if (clean !== undefined)
+                        out[redactWebhookTokens(k)] = clean;
+                }
+                return out;
+            }
+            default:
+                return undefined;
+        }
+    };
+    const clean = sanitize(eventData ?? {}, 0);
+    const info = clean !== null && typeof clean === "object" && !Array.isArray(clean) ? clean : {};
+    if (utf8Length(JSON.stringify(info)) > INFO_CAP_BYTES)
+        return { info: {}, truncated: true };
+    return { info, truncated: false };
+}
+/** RFC 3339 UTC with milliseconds, or `null`. */
+export function isoTime(value) {
+    if (value === undefined || value === null)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+/**
+ * A step's input as the SDK's own inspector shows it: its arguments. Workflow
+ * SDK stores a step's input as `{ args, closureVars, thisVal }`; this answers
+ * `args` alone, or `{ args, closureVars?, thisVal? }` with only the parts that
+ * hold something. Anything not exactly that envelope is returned as it is.
+ */
+export function stepInputDisplay(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input))
+        return input;
+    const proto = Object.getPrototypeOf(input);
+    if (proto !== Object.prototype && proto !== null)
+        return input;
+    const keys = Object.keys(input);
+    if (!keys.includes("args") || keys.some((k) => k !== "args" && k !== "closureVars" && k !== "thisVal"))
+        return input;
+    const { args, closureVars, thisVal } = input;
+    if (!Array.isArray(args))
+        return input;
+    const extra = {};
+    if (!isEmpty(closureVars))
+        extra.closureVars = closureVars;
+    if (thisVal !== undefined && thisVal !== null)
+        extra.thisVal = thisVal;
+    return Object.keys(extra).length === 0 ? args : { args, ...extra };
+}
+function isEmpty(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (value instanceof Map || value instanceof Set)
+        return value.size === 0;
+    if (typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype)
+        return Object.keys(value).length === 0;
+    return false;
+}
+//# sourceMappingURL=inspect-render.js.map

package/dist/workflow/inspect-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-render.js","sourceRoot":"","sources":["../../src/workflow/inspect-render.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How the inspection route turns World data into the display JSON of the\n * contract (unfazed docs/workflow-inspect.md, \"Values\", \"Errors\", `Event`).\n * Pure functions, no SDK imports: the caller hydrates, this renders.\n */\nimport { Buffer } from \"node:buffer\";\n\n/** A payload as display text (`Value` in the contract). */\nexport interface InspectValue {\n  text: string;\n  /** UTF-8 length of the whole text, before any cut. */\n  bytes: number;\n  truncated: boolean;\n  /** Present (true) only when the payload could not be hydrated; `text` is the reason. */\n  error?: true;\n}\n\n/** A thrown run or step error (`Error` in the contract). */\nexport interface InspectError {\n  message: string;\n  stack: string | null;\n  code: string | null;\n  truncated: boolean;\n}\n\nexport const MESSAGE_CAP_BYTES = 4 * 1024;\nexport const STACK_CAP_BYTES = 8 * 1024;\nexport const INFO_CAP_BYTES = 2 * 1024;\n\nexport interface DisplayOptions {\n  /**\n   * Strings to replace with `[redacted]` wherever they occur in a string\n   * (hook tokens, so neither a token nor a webhook URL built from one leaves).\n   */\n  secrets?: readonly string[];\n  /** Drop every object key named `token`, at any depth. */\n  dropTokenKeys?: boolean;\n}\n\nexport const REDACTED = \"[redacted]\";\n\n/** Workflow SDK's webhook route; the path segment after it is the hook's token. */\nexport const WEBHOOK_PATH = \"/.well-known/workflow/v1/webhook/\";\n\n// The route as written, also with JSON-escaped slashes (`\\/`), then its token:\n// one path segment of RFC 3986 characters (what `encodeURIComponent` emits,\n// plus `%`), so a query string, fragment, quote or space after it stays.\nconst WEBHOOK_URL = /(\\\\?\\/\\.well-known\\\\?\\/workflow\\\\?\\/v1\\\\?\\/webhook\\\\?\\/)[A-Za-z0-9\\-._~!$&'()*+,;=:@%]+/g;\n// The same URL percent-encoded inside another URL (`?next=https%3A%2F%2F…`).\nconst WEBHOOK_URL_ENCODED = /(%2F\\.well-known%2Fworkflow%2Fv1%2Fwebhook%2F)[A-Za-z0-9\\-._~!$'()*+,;:@%]+/gi;\n\n/**\n * `text` with the token of every Workflow SDK webhook URL in it replaced by\n * `[redacted]`: `https://app.example/.well-known/workflow/v1/webhook/<token>?a=1`\n * reads `https://app.example/.well-known/workflow/v1/webhook/[redacted]?a=1`.\n * A webhook URL is a capability (anyone holding it resumes the run), so none\n * leaves the route, whatever the app wrote it into.\n */\nexport function redactWebhookTokens(text: string): string {\n  if (!text.includes(\"well-known\")) return text;\n  return text.replace(WEBHOOK_URL, `$1${REDACTED}`).replace(WEBHOOK_URL_ENCODED, `$1${REDACTED}`);\n}\n\n/** UTF-8 length of `text`. */\nexport function utf8Length(text: string): number {\n  return Buffer.byteLength(text, \"utf8\");\n}\n\n/**\n * `text` cut to at most `capBytes` of UTF-8 on a character boundary, and\n * whether it was cut.\n */\nexport function cutUtf8(text: string, capBytes: number): { text: string; truncated: boolean; bytes: number } {\n  const bytes = utf8Length(text);\n  if (bytes <= capBytes) return { text, truncated: false, bytes };\n  const encoded = Buffer.from(text, \"utf8\");\n  let end = capBytes;\n  // Back off continuation bytes (10xxxxxx) so no code point is split.\n  while (end > 0 && (encoded[end]! & 0xc0) === 0x80) end--;\n  return { text: encoded.subarray(0, end).toString(\"utf8\"), truncated: true, bytes };\n}\n\n/**\n * The contract's replacer, as a walk that builds a JSON-safe tree:\n * `bigint` → `\"123n\"`, `undefined` → `null`, `Map` → `{\"$map\": [[k, v], …]}`,\n * `Set` → `{\"$set\": […]}`, bytes → `{\"$bytes\": n}`, `Error` →\n * `{\"$error\": {name, message, stack}}`, a function → `\"[function name]\"`, a\n * cycle → `\"[circular]\"`; anything with `toJSON()` (the revivers' display\n * objects, `Date`, `URL`) goes through it first, as `JSON.stringify` does.\n */\nexport function toDisplayJson(value: unknown, options: DisplayOptions = {}): unknown {\n  const secrets = (options.secrets ?? []).filter((s) => s.length > 0);\n  const ancestors = new Set<object>();\n\n  const str = (text: string): string => {\n    let out = text;\n    for (const secret of secrets) if (out.includes(secret)) out = out.split(secret).join(REDACTED);\n    return redactWebhookTokens(out);\n  };\n\n  const walk = (input: unknown, key: string): unknown => {\n    let v = input;\n    if (v !== null && typeof v === \"object\" && !(v instanceof Error) && !ArrayBuffer.isView(v)) {\n      const toJSON = (v as { toJSON?: unknown }).toJSON;\n      if (typeof toJSON === \"function\") {\n        if (ancestors.has(v as object)) return \"[circular]\";\n        v = (toJSON as (k: string) => unknown).call(v, key);\n      }\n    }\n    switch (typeof v) {\n      case \"undefined\":\n        return null;\n      case \"string\":\n        return str(v);\n      case \"number\":\n        return Number.isFinite(v) ? v : null;\n      case \"boolean\":\n        return v;\n      case \"bigint\":\n        return `${v}n`;\n      case \"function\":\n        return `[function ${(v as { name?: string }).name || \"anonymous\"}]`;\n      case \"symbol\":\n        return str(v.toString());\n    }\n    if (v === null) return null;\n    const obj = v as object;\n    if (obj instanceof ArrayBuffer) return { $bytes: obj.byteLength };\n    if (ArrayBuffer.isView(obj)) return { $bytes: obj.byteLength };\n    if (ancestors.has(obj)) return \"[circular]\";\n    ancestors.add(obj);\n    try {\n      if (obj instanceof Error) {\n        return {\n          $error: {\n            name: str(String(obj.name)),\n            message: str(String(obj.message)),\n            stack: typeof obj.stack === \"string\" ? str(obj.stack) : null,\n          },\n        };\n      }\n      if (obj instanceof Map) {\n        const entries: unknown[] = [];\n        for (const [k, item] of obj) {\n          if (options.dropTokenKeys && k === \"token\") continue;\n          entries.push([walk(k, \"\"), walk(item, typeof k === \"string\" ? k : \"\")]);\n        }\n        return { $map: entries };\n      }\n      if (obj instanceof Set) return { $set: [...obj].map((item, i) => walk(item, String(i))) };\n      if (typeof Headers !== \"undefined\" && obj instanceof Headers) {\n        const out: Record<string, unknown> = {};\n        obj.forEach((item, name) => {\n          out[name] = str(item);\n        });\n        return out;\n      }\n      if (obj instanceof RegExp) return str(String(obj));\n      if (Array.isArray(obj)) return obj.map((item, i) => walk(item, String(i)));\n      const out: Record<string, unknown> = {};\n      for (const k of Object.keys(obj)) {\n        if (options.dropTokenKeys && k === \"token\") continue;\n        out[str(k)] = walk((obj as Record<string, unknown>)[k], k);\n      }\n      return out;\n    } finally {\n      ancestors.delete(obj);\n    }\n  };\n\n  return walk(value, \"\");\n}\n\n/** `JSON.stringify(value, replacer, 2)` of the contract. */\nexport function displayText(value: unknown, options: DisplayOptions = {}): string {\n  return JSON.stringify(toDisplayJson(value, options), null, 2) ?? \"null\";\n}\n\n/** A hydrated payload as a `Value`, cut at `capBytes`; `undefined`/`null` is `null`. */\nexport function renderValue(value: unknown, capBytes: number, options: DisplayOptions = {}): InspectValue | null {\n  if (value === undefined || value === null) return null;\n  let text: string;\n  try {\n    text = displayText(value, options);\n  } catch (error) {\n    return failedValue(error, capBytes);\n  }\n  const cut = cutUtf8(text, capBytes);\n  return { text: cut.text, bytes: cut.bytes, truncated: cut.truncated };\n}\n\n/** A payload that failed to hydrate (or to render): the error's message, flagged. */\nexport function failedValue(error: unknown, capBytes: number): InspectValue {\n  const message = redactWebhookTokens(error instanceof Error ? error.message : String(error));\n  const cut = cutUtf8(message || \"the payload could not be read\", capBytes);\n  return { text: cut.text, bytes: cut.bytes, truncated: false, error: true };\n}\n\n/**\n * A hydrated run or step error as the contract's `Error`: `message` at most\n * 4 KiB, `stack` at most 8 KiB or `null`, `code` as given.\n */\nexport function renderError(\n  hydrated: unknown,\n  code: string | null,\n  failure: unknown,\n  options: DisplayOptions = {},\n): InspectError {\n  let message: string;\n  let stack: string | null = null;\n  if (failure !== undefined) {\n    message = `the error could not be read: ${failure instanceof Error ? failure.message : String(failure)}`;\n  } else if (hydrated === undefined || hydrated === null) {\n    message = \"(no error recorded)\";\n  } else if (typeof hydrated === \"string\") {\n    message = hydrated;\n  } else if (\n    hydrated !== null &&\n    typeof hydrated === \"object\" &&\n    typeof (hydrated as { message?: unknown }).message === \"string\"\n  ) {\n    message = (hydrated as { message: string }).message;\n    const rawStack = (hydrated as { stack?: unknown }).stack;\n    stack = typeof rawStack === \"string\" ? rawStack : null;\n  } else {\n    try {\n      message = displayText(hydrated, options);\n    } catch (error) {\n      message = `the error could not be read: ${error instanceof Error ? error.message : String(error)}`;\n    }\n  }\n  const secrets = (options.secrets ?? []).filter((s) => s.length > 0);\n  const scrub = (text: string) =>\n    redactWebhookTokens(secrets.reduce((out, secret) => out.split(secret).join(REDACTED), text));\n  const m = cutUtf8(scrub(message), MESSAGE_CAP_BYTES);\n  const s = stack === null ? null : cutUtf8(scrub(stack), STACK_CAP_BYTES);\n  return { message: m.text, stack: s ? s.text : null, code, truncated: m.truncated || (s?.truncated ?? false) };\n}\n\ntype InfoJson = string | number | boolean | null | InfoJson[] | { [key: string]: InfoJson };\n\n/**\n * An event's `info`: its `eventData` as `resolveData: \"none\"` leaves it, every\n * `token` key removed at any depth, only strings, numbers, booleans, `null`\n * and objects/arrays of those kept (a `Date` becomes its RFC 3339 string); at\n * most 2 KiB serialized, else `{}` and truncated.\n */\nexport function eventInfo(eventData: unknown): { info: Record<string, InfoJson>; truncated: boolean } {\n  const sanitize = (v: unknown, depth: number): InfoJson | undefined => {\n    if (v === null) return null;\n    if (v instanceof Date) return Number.isNaN(v.getTime()) ? undefined : v.toISOString();\n    switch (typeof v) {\n      case \"string\":\n        return redactWebhookTokens(v);\n      case \"boolean\":\n        return v;\n      case \"number\":\n        return Number.isFinite(v) ? v : undefined;\n      case \"object\": {\n        if (depth > 32 || ArrayBuffer.isView(v) || v instanceof ArrayBuffer) return undefined;\n        if (Array.isArray(v)) {\n          return v.map((item) => sanitize(item, depth + 1)).filter((item): item is InfoJson => item !== undefined);\n        }\n        const proto = Object.getPrototypeOf(v);\n        if (proto !== Object.prototype && proto !== null) return undefined;\n        const out: Record<string, InfoJson> = {};\n        for (const [k, item] of Object.entries(v as Record<string, unknown>)) {\n          if (k === \"token\") continue;\n          const clean = sanitize(item, depth + 1);\n          if (clean !== undefined) out[redactWebhookTokens(k)] = clean;\n        }\n        return out;\n      }\n      default:\n        return undefined;\n    }\n  };\n  const clean = sanitize(eventData ?? {}, 0);\n  const info = clean !== null && typeof clean === \"object\" && !Array.isArray(clean) ? clean : {};\n  if (utf8Length(JSON.stringify(info)) > INFO_CAP_BYTES) return { info: {}, truncated: true };\n  return { info, truncated: false };\n}\n\n/** RFC 3339 UTC with milliseconds, or `null`. */\nexport function isoTime(value: unknown): string | null {\n  if (value === undefined || value === null) return null;\n  const date = value instanceof Date ? value : new Date(value as string | number);\n  return Number.isNaN(date.getTime()) ? null : date.toISOString();\n}\n\n/**\n * A step's input as the SDK's own inspector shows it: its arguments. Workflow\n * SDK stores a step's input as `{ args, closureVars, thisVal }`; this answers\n * `args` alone, or `{ args, closureVars?, thisVal? }` with only the parts that\n * hold something. Anything not exactly that envelope is returned as it is.\n */\nexport function stepInputDisplay(input: unknown): unknown {\n  if (input === null || typeof input !== \"object\" || Array.isArray(input)) return input;\n  const proto = Object.getPrototypeOf(input);\n  if (proto !== Object.prototype && proto !== null) return input;\n  const keys = Object.keys(input);\n  if (!keys.includes(\"args\") || keys.some((k) => k !== \"args\" && k !== \"closureVars\" && k !== \"thisVal\")) return input;\n  const { args, closureVars, thisVal } = input as { args: unknown; closureVars?: unknown; thisVal?: unknown };\n  if (!Array.isArray(args)) return input;\n  const extra: Record<string, unknown> = {};\n  if (!isEmpty(closureVars)) extra.closureVars = closureVars;\n  if (thisVal !== undefined && thisVal !== null) extra.thisVal = thisVal;\n  return Object.keys(extra).length === 0 ? args : { args, ...extra };\n}\n\nfunction isEmpty(value: unknown): boolean {\n  if (value === undefined || value === null) return true;\n  if (Array.isArray(value)) return value.length === 0;\n  if (value instanceof Map || value instanceof Set) return value.size === 0;\n  if (typeof value === \"object\" && Object.getPrototypeOf(value) === Object.prototype) return Object.keys(value).length === 0;\n  return false;\n}\n"]}

package/dist/workflow/inspect.d.ts

@@ -0,0 +1,52 @@
+import { type World } from "@workflow/world";
+import { type WorkflowEnv } from "./config.js";
+/** Where `unfazed/workflow/nitro` mounts the route; other frameworks mount {@link createInspectHandler} here. */
+export declare const INSPECT_BASE_PATH = "/.well-known/workflow/v1/unfazed/inspect/v1";
+export declare const INSPECT_CONTRACT_VERSION = 1;
+/** The slice of Workflow SDK's `Run` the actions use (`getRun(id)` from `workflow/api`). */
+export interface InspectRunHandle {
+    wakeUp(options?: {
+        correlationIds?: string[];
+    }): Promise<{
+        stoppedCount: number;
+    }>;
+    cancel(options?: {
+        cancelReason?: string;
+    }): Promise<void>;
+}
+export interface InspectHandlerOptions {
+    /** The World to read. Default: Workflow SDK's `getWorld()`, the World installed with `setWorld()`. */
+    getWorld?: () => World | Promise<World>;
+    /** Default: Workflow SDK's `getRun()` (`workflow/api`). */
+    getRun?: (runId: string) => InspectRunHandle;
+    /** The token the platform sends. Default: `UNFZ_STATE_TOKEN`, read per request. */
+    stateToken?: string;
+    /** Where `UNFZ_STATE_TOKEN` is read from. Default: `process.env`. */
+    env?: WorkflowEnv;
+    /** The build's workflow machine names (`workflow//./src/x//name`), for `info`. Default: none. */
+    workflows?: readonly string[];
+    /** The Workflow SDK version the app was built with, for `info`. Default: `"unknown"`. */
+    workflowVersion?: string;
+    /** How long a request may take before it answers with an error. Default 19 s (the contract allows 20). */
+    timeoutMs?: number;
+}
+/**
+ * The reason as Workflow SDK stores it: its schema takes at most 512 UTF-16
+ * units, so a reason of 512 characters that holds astral-plane ones (emoji)
+ * is cut on a character boundary to fit, rather than failing the cancel.
+ */
+export declare function sdkCancelReason(reason: string): string;
+/**
+ * Creates the inspection route's handler: `(request) => Response` for every
+ * request under {@link INSPECT_BASE_PATH}.
+ *
+ * ```ts
+ * // e.g. a catch-all route at /.well-known/workflow/v1/unfazed/inspect/v1/*
+ * import { createInspectHandler } from "unfazed/workflow";
+ * const inspect = createInspectHandler();
+ * export const GET = inspect, POST = inspect;
+ * ```
+ *
+ * `unfazed/workflow/nitro` mounts it for you.
+ */
+export declare function createInspectHandler(options?: InspectHandlerOptions): (request: Request) => Promise<Response>;