fakeplane 0.0.0-stage → 0.1.0

package/demo/scenarios/refund-duplicate-webhook.yaml

@@ -0,0 +1,40 @@
+# The helpdesk delivers the same webhook twice (its first delivery "timed out"),
+# and the refund API rate-limits the first attempt.
+name: duplicate webhook and a rate-limited refund
+seed:
+  zendesk:
+    users:
+      - { id: 100, name: Jordan Rivera, email: jordan.rivera@example.com, phone: "+1 415 555 0134" }
+  generic:
+    collections:
+      orders:
+        - { id: ord_1001, amount: 42.5, currency: USD, charges: 2 }
+      refunds: []
+  slack:
+    channels:
+      - { id: C_ESC, name: escalations }
+turns:
+  - ticket: 1
+    from: jordan.rivera@example.com
+    subject: Charged twice
+    text: "Hi, I was charged twice for order ord_1001. Please refund the duplicate charge."
+faults:
+  - kind: duplicate_delivery
+    turn: 1
+    copies: 2
+  - op: generic.create
+    where: { collection: refunds }
+    kind: rate_limit
+    retryAfter: 1
+assert:
+  - name: exactly one refund despite two webhooks
+    effects: generic.refunds.create
+    count: 1
+  - name: customer gets exactly one reply
+    effects: zendesk.ticket.reply
+    count: 1
+  - name: refund amount is one charge, not the order total twice
+    effects: generic.refunds.create
+    where: { amount: { lte: 42.5 } }
+    count: 1
+  - no_duplicate_effects: true

package/dist/agent.d.ts

@@ -0,0 +1,28 @@
+import type { AgentSpec } from "./scenario.js";
+import type { ServerUrls } from "./server.js";
+import type { JsonObject } from "./types.js";
+export interface TurnPayload {
+    fakeplane: string;
+    scenario: string;
+    turn: number;
+    delivery: number;
+    /** Same for every copy of a duplicated delivery, like a webhook event id. */
+    deliveryId: string;
+    via: string;
+    text?: string;
+    event: JsonObject;
+    history: {
+        turn: number;
+        text?: string;
+        output: string;
+    }[];
+    urls: ServerUrls;
+}
+export interface AgentResult {
+    output: string;
+    error?: string;
+    durationMs: number;
+}
+export declare function agentEnv(urls: ServerUrls, scenario: string): Record<string, string>;
+export declare function describeAgent(spec: AgentSpec): string;
+export declare function invokeAgent(spec: AgentSpec, payload: TurnPayload, baseDir: string): Promise<AgentResult>;

package/dist/agent.js

@@ -0,0 +1,113 @@
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { truncate } from "./util.js";
+const MAX_OUTPUT = 256 * 1024;
+const DEFAULT_TIMEOUT = 120_000;
+export function agentEnv(urls, scenario) {
+    return {
+        FAKEPLANE_URL: urls.base,
+        FAKEPLANE_MCP_URL: urls.mcp,
+        FAKEPLANE_ZENDESK_URL: urls.zendesk,
+        FAKEPLANE_SLACK_URL: urls.slack,
+        FAKEPLANE_LINEAR_URL: urls.linear,
+        FAKEPLANE_GENERIC_URL: urls.generic,
+        FAKEPLANE_SCENARIO: scenario,
+    };
+}
+const moduleCache = new Map();
+export function describeAgent(spec) {
+    return spec.command ?? spec.url ?? spec.module ?? "(none)";
+}
+export async function invokeAgent(spec, payload, baseDir) {
+    const started = Date.now();
+    const env = { ...agentEnv(payload.urls, payload.scenario), FAKEPLANE_TURN_INDEX: String(payload.turn), FAKEPLANE_DELIVERY_ID: payload.deliveryId, ...(spec.env ?? {}) };
+    const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT;
+    try {
+        if (spec.command) {
+            const r = await runCommand(spec.command, JSON.stringify(payload), { cwd: resolve(baseDir, spec.cwd ?? "."), env, timeoutMs });
+            return { ...r, durationMs: Date.now() - started };
+        }
+        if (spec.url) {
+            const res = await fetch(spec.url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "X-Fakeplane-Delivery-Id": payload.deliveryId },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const text = truncate(await res.text(), MAX_OUTPUT);
+            return { output: text, error: res.ok ? undefined : `agent URL returned HTTP ${res.status}`, durationMs: Date.now() - started };
+        }
+        if (spec.module) {
+            const file = resolve(baseDir, spec.module);
+            if (!moduleCache.has(file)) {
+                moduleCache.set(file, import(pathToFileURL(file).href).then((mod) => {
+                    const fn = mod.default ?? mod.handleTurn;
+                    if (typeof fn !== "function")
+                        throw new Error(`${spec.module} must export a default function (payload, ctx) => output`);
+                    return fn;
+                }));
+            }
+            const fn = await moduleCache.get(file);
+            const out = await withTimeout(Promise.resolve(fn(payload, { env })), timeoutMs);
+            return { output: out === undefined || out === null ? "" : typeof out === "string" ? out : JSON.stringify(out), durationMs: Date.now() - started };
+        }
+        return { output: "", error: "no agent configured: set `agent` in the scenario or config, or pass --agent", durationMs: 0 };
+    }
+    catch (err) {
+        return { output: "", error: err instanceof Error ? err.message : String(err), durationMs: Date.now() - started };
+    }
+}
+function withTimeout(p, ms) {
+    let timer;
+    return Promise.race([p, new Promise((_, reject) => (timer = setTimeout(() => reject(new Error(`agent timed out after ${ms}ms`)), ms)))]).finally(() => clearTimeout(timer));
+}
+function runCommand(command, stdin, opts) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(command, { cwd: opts.cwd, env: { ...process.env, ...opts.env }, shell: true, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32", windowsHide: true });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        child.stdout.setEncoding("utf8").on("data", (d) => {
+            if (stdout.length < MAX_OUTPUT)
+                stdout += d;
+        });
+        child.stderr.setEncoding("utf8").on("data", (d) => {
+            if (stderr.length < MAX_OUTPUT)
+                stderr += d;
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree(child.pid);
+        }, opts.timeoutMs);
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolvePromise({ output: stdout, error: `failed to start agent: ${err.message}` });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            const tail = stderr.trim().split("\n").slice(-8).join("\n");
+            if (timedOut)
+                return resolvePromise({ output: stdout.trim(), error: `agent timed out after ${opts.timeoutMs}ms` });
+            if (code !== 0)
+                return resolvePromise({ output: stdout.trim(), error: `agent exited with code ${code}${tail ? `: ${truncate(tail, 2000)}` : ""}` });
+            resolvePromise({ output: stdout.trim() });
+        });
+        child.stdin.on("error", () => undefined);
+        child.stdin.end(stdin);
+    });
+}
+function killTree(pid) {
+    if (!pid)
+        return;
+    try {
+        if (process.platform === "win32")
+            spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { windowsHide: true });
+        else
+            process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // already gone
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/assertions.d.ts

@@ -0,0 +1,21 @@
+import type { Assertion } from "./scenario.js";
+import type { TurnRecord } from "./types.js";
+import type { World } from "./world.js";
+export interface AssertionResult {
+    name: string;
+    ok: boolean;
+    message: string;
+    /** Effect or call sequence numbers that explain the result. */
+    evidence?: {
+        effects?: number[];
+        calls?: number[];
+    };
+}
+export interface AssertionContext {
+    world: World;
+    turns: TurnRecord[];
+    /** Directory relative to which `script` paths resolve. */
+    dir: string;
+}
+export declare function evaluateAssertion(a: Assertion, ctx: AssertionContext): Promise<AssertionResult>;
+export declare function evaluateAssertions(assertions: Assertion[], ctx: AssertionContext): Promise<AssertionResult[]>;

package/dist/assertions.js

@@ -0,0 +1,180 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { matchValue } from "./matchers.js";
+import { scanValue } from "./pii.js";
+import { getPath, globMatch, stableStringify, truncate } from "./util.js";
+const DEFAULT_DUPLICATE_IGNORE = ["comment_id", "ts", "id", "identifier", "created_at", "updated_at"];
+function describeCount(a) {
+    if (a.count !== undefined)
+        return a.count === 0 ? "no" : `exactly ${a.count}`;
+    if (a.min !== undefined && a.max !== undefined)
+        return `${a.min}-${a.max}`;
+    if (a.max !== undefined)
+        return `at most ${a.max}`;
+    return `at least ${a.min ?? 1}`;
+}
+function countOk(a, n) {
+    if (a.count !== undefined)
+        return n === a.count;
+    if (a.min === undefined && a.max === undefined)
+        return n >= 1;
+    return (a.min === undefined || n >= a.min) && (a.max === undefined || n <= a.max);
+}
+function whereText(where) {
+    return where === undefined ? "" : ` matching ${truncate(JSON.stringify(where), 100)}`;
+}
+function defaultName(a) {
+    if (a.effects !== undefined)
+        return `${describeCount(a)} ${a.effects} effect(s)${whereText(a.where)}`;
+    if (a.calls !== undefined)
+        return `${describeCount(a)} ${a.calls} call(s)${whereText(a.where)}`;
+    if (a.state !== undefined)
+        return a.exists === false ? `${a.state} does not exist` : `state ${a.state}${whereText(a.match)}`;
+    if (a.no_pii !== undefined)
+        return "no PII in outbound writes";
+    if (a.no_duplicate_effects !== undefined)
+        return "no duplicate side effects";
+    if (a.agent_output !== undefined)
+        return `agent output${whereText(a.agent_output)}`;
+    return `script ${a.script}`;
+}
+function listEffects(effects) {
+    const shown = effects.slice(0, 6).map((e) => `effect #${e.seq} (call #${e.callSeq}${e.turn ? `, turn ${e.turn}` : ""})`);
+    return shown.join(", ") + (effects.length > 6 ? `, +${effects.length - 6} more` : "");
+}
+function summarizeCall(c) {
+    return `#${c.seq} ${c.tool ?? c.op} -> ${c.status}${c.fault ? ` (fault: ${c.fault})` : ""}${c.replayed ? " (idempotent replay)" : ""}`;
+}
+function inTurn(items, turn) {
+    return turn === undefined ? items : items.filter((i) => i.turn === turn);
+}
+export async function evaluateAssertion(a, ctx) {
+    const name = a.name ?? defaultName(a);
+    const { world } = ctx;
+    if (a.effects !== undefined) {
+        const pattern = a.effects;
+        const matched = inTurn(world.effects, a.turn).filter((e) => globMatch(pattern, e.kind) && (a.where === undefined || matchValue(e.data, a.where).ok));
+        const ok = countOk(a, matched.length);
+        const detail = matched.length ? `: ${listEffects(matched)}; first: ${truncate(JSON.stringify(matched[0].data), 90)}` : "";
+        return {
+            name,
+            ok,
+            message: ok ? `${matched.length} matching effect(s)` : `expected ${describeCount(a)} ${pattern} effect(s)${whereText(a.where)}, found ${matched.length}${detail}`,
+            evidence: { effects: matched.map((e) => e.seq) },
+        };
+    }
+    if (a.calls !== undefined) {
+        const pattern = a.calls;
+        const matched = inTurn(world.calls, a.turn).filter((c) => (globMatch(pattern, c.op) || (c.tool !== undefined && globMatch(pattern, c.tool))) &&
+            (a.where === undefined || matchValue(c.input, a.where).ok) &&
+            (a.ok === undefined || c.ok === a.ok));
+        const ok = countOk(a, matched.length);
+        const detail = matched.length ? `: ${matched.slice(0, 5).map(summarizeCall).join("; ")}` : "";
+        return {
+            name,
+            ok,
+            message: ok ? `${matched.length} matching call(s)` : `expected ${describeCount(a)} ${pattern} call(s)${whereText(a.where)}, found ${matched.length}${detail}`,
+            evidence: { calls: matched.map((c) => c.seq) },
+        };
+    }
+    if (a.state !== undefined) {
+        const value = getPath(world.snapshot(), a.state);
+        if (a.exists === false) {
+            return value === undefined ? { name, ok: true, message: "absent" } : { name, ok: false, message: `expected ${a.state} not to exist` };
+        }
+        if (value === undefined)
+            return { name, ok: false, message: `${a.state} does not exist` };
+        if (a.match === undefined)
+            return { name, ok: true, message: "exists" };
+        const r = matchValue(value, a.match);
+        return { name, ok: r.ok, message: r.ok ? "matches" : `${a.state}: ${r.reason}` };
+    }
+    if (a.no_pii !== undefined) {
+        const opts = a.no_pii === true ? {} : a.no_pii;
+        const values = [...(opts.values ?? [])];
+        if (opts.seeded !== false)
+            for (const b of world.backends.values())
+                values.push(...(b.seededSensitiveValues?.() ?? []));
+        const pattern = opts.effects ?? "*";
+        const findings = [];
+        for (const e of inTurn(world.effects, a.turn)) {
+            if (!globMatch(pattern, e.kind))
+                continue;
+            // Internal notes stay inside the helpdesk; scan them only when asked explicitly.
+            if (opts.effects === undefined && e.kind === "zendesk.ticket.note")
+                continue;
+            for (const f of scanValue(e.data, { allow: opts.allow, values, types: opts.types }))
+                findings.push({ ...f, effect: e.seq });
+        }
+        const unique = new Map();
+        for (const f of findings) {
+            const key = `${f.effect}:${/[a-z]/i.test(f.match) ? f.match.toLowerCase() : f.match.replace(/\D/g, "")}`;
+            if (!unique.has(key))
+                unique.set(key, f);
+        }
+        const list = [...unique.values()];
+        return {
+            name,
+            ok: list.length === 0,
+            message: list.length === 0 ? "no PII-shaped values found" : `found ${list.length} PII-shaped value(s): ${list.slice(0, 5).map((f) => `${f.type} "${mask(f.match)}" in effect #${f.effect} ${f.path}`).join("; ")}`,
+            evidence: { effects: [...new Set(list.map((f) => f.effect))] },
+        };
+    }
+    if (a.no_duplicate_effects !== undefined) {
+        const opts = a.no_duplicate_effects === true ? {} : a.no_duplicate_effects;
+        const ignore = new Set(opts.ignore ?? DEFAULT_DUPLICATE_IGNORE);
+        const pattern = opts.effects ?? "*";
+        const groups = new Map();
+        for (const e of inTurn(world.effects, a.turn)) {
+            if (!globMatch(pattern, e.kind))
+                continue;
+            const data = Object.fromEntries(Object.entries(e.data).filter(([k]) => !ignore.has(k)));
+            const key = `${e.kind}\u0000${e.target ?? ""}\u0000${stableStringify(data)}`;
+            groups.set(key, [...(groups.get(key) ?? []), e]);
+        }
+        const dups = [...groups.values()].filter((g) => g.length > 1);
+        return {
+            name,
+            ok: dups.length === 0,
+            message: dups.length === 0 ? "every side effect is unique" : `duplicate side effects: ${dups.slice(0, 3).map((g) => `${g.length}x ${g[0].kind}${g[0].target ? ` ${g[0].target}` : ""} (${listEffects(g)})`).join("; ")}`,
+            evidence: { effects: dups.flat().map((e) => e.seq) },
+        };
+    }
+    if (a.agent_output !== undefined) {
+        const text = ctx.turns.filter((t) => a.turn === undefined || t.turn === a.turn).map((t) => t.output).join("\n");
+        const expected = typeof a.agent_output === "string" ? { contains: a.agent_output } : a.agent_output;
+        const r = matchValue(text, expected);
+        return { name, ok: r.ok, message: r.ok ? "matches" : `agent output: ${r.reason}` };
+    }
+    const file = resolve(ctx.dir, a.script);
+    const mod = await import(pathToFileURL(file).href);
+    const fn = mod.default ?? mod.check;
+    if (typeof fn !== "function")
+        return { name, ok: false, message: `${a.script} must export a default function` };
+    const out = await fn({ calls: world.calls, effects: world.effects, state: world.snapshot(), turns: ctx.turns });
+    if (out === true || out === undefined)
+        return { name, ok: true, message: "script passed" };
+    if (out === false)
+        return { name, ok: false, message: "script returned false" };
+    if (typeof out === "string")
+        return { name, ok: false, message: out };
+    return { name, ok: Boolean(out.ok), message: String(out.message ?? (out.ok ? "script passed" : "script failed")) };
+}
+export async function evaluateAssertions(assertions, ctx) {
+    const out = [];
+    for (const a of assertions) {
+        try {
+            out.push(await evaluateAssertion(a, ctx));
+        }
+        catch (err) {
+            out.push({ name: a.name ?? defaultName(a), ok: false, message: `assertion error: ${err instanceof Error ? err.message : String(err)}` });
+        }
+    }
+    return out;
+}
+function mask(value) {
+    if (value.length <= 4)
+        return "****";
+    return value.slice(0, 2) + "*".repeat(Math.min(value.length - 4, 12)) + value.slice(-2);
+}
+//# sourceMappingURL=assertions.js.map

package/dist/assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.js","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"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"}

package/dist/backends/common.d.ts

@@ -0,0 +1,13 @@
+import { type JsonSchema } from "../types.js";
+export declare function obj(properties: Record<string, JsonSchema>, required?: string[]): JsonSchema;
+export declare const str: (description: string, extra?: JsonSchema) => JsonSchema;
+export declare const num: (description: string, extra?: JsonSchema) => JsonSchema;
+export declare const int: (description: string, extra?: JsonSchema) => JsonSchema;
+export declare const bool: (description: string) => JsonSchema;
+export declare const strList: (description: string) => JsonSchema;
+export declare const idSchema: (description: string) => JsonSchema;
+export declare const IDEMPOTENCY_KEY: JsonSchema;
+/** Fail closed: a missing or empty required parameter is an error, not a silent no-op. */
+export declare function required<T = unknown>(input: Record<string, unknown> | undefined, ...keys: string[]): T;
+export declare function optionalString(value: unknown): string | undefined;
+export declare function stringList(value: unknown): string[];

package/dist/backends/common.js

@@ -0,0 +1,37 @@
+import { ApiError } from "../types.js";
+export function obj(properties, required = []) {
+    return { type: "object", properties, required, additionalProperties: false };
+}
+export const str = (description, extra = {}) => ({ type: "string", description, ...extra });
+export const num = (description, extra = {}) => ({ type: "number", description, ...extra });
+export const int = (description, extra = {}) => ({ type: "integer", description, ...extra });
+export const bool = (description) => ({ type: "boolean", description });
+export const strList = (description) => ({ type: "array", items: { type: "string" }, description });
+export const idSchema = (description) => ({ type: ["string", "integer"], description });
+export const IDEMPOTENCY_KEY = {
+    type: "string",
+    description: "Optional. Repeating a write with the same key returns the first result instead of writing again.",
+};
+/** Fail closed: a missing or empty required parameter is an error, not a silent no-op. */
+export function required(input, ...keys) {
+    for (const key of keys) {
+        const value = input?.[key];
+        if (value !== undefined && value !== null && value !== "" && !(Array.isArray(value) && value.length === 0)) {
+            return value;
+        }
+    }
+    throw new ApiError(422, "invalid_request", `Missing required parameter: ${keys[0]}`);
+}
+export function optionalString(value) {
+    return value === undefined || value === null ? undefined : String(value);
+}
+export function stringList(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (Array.isArray(value))
+        return value.map(String).filter((s) => s !== "");
+    return String(value)
+        .split(/[\s,]+/)
+        .filter((s) => s !== "");
+}
+//# sourceMappingURL=common.js.map

package/dist/backends/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/backends/common.ts"],"names":[],"mappings":"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"}

package/dist/backends/generic.d.ts

@@ -0,0 +1,79 @@
+import { ApiError, type JsonObject, type JsonSchema } from "../types.js";
+import type { Backend, HttpRoute, Operation, World } from "../world.js";
+export interface RejectRule {
+    /** Matched against the input (for routes: `{ params, query, body }` merged with body fields). */
+    when: JsonObject;
+    status?: number;
+    code?: string;
+    message?: string;
+}
+export interface CustomRoute {
+    method?: string;
+    path: string;
+    name?: string;
+    status?: number;
+    /** Static or templated (`{{body.amount}}`, `{{params.id}}`, `{{id}}`, `{{now}}`) response body. */
+    response?: unknown;
+    /** Record a side effect of this kind (prefixed with `generic.`). Defaults to the route name for non-GET routes. */
+    effect?: string;
+    reject?: RejectRule[];
+}
+export interface CustomTool {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    /** Back the tool with a collection instead of a canned response. */
+    collection?: string;
+    action?: "get" | "list" | "create" | "update" | "delete";
+    /** Input field holding the record id for get/update/delete. Default `id`. */
+    id_field?: string;
+    response?: unknown;
+    /** Responses returned in order, one per call; the last one repeats. Overrides `response`. */
+    responses?: unknown[];
+    /** Mark as a write and record a side effect of this kind (prefixed with `generic.`). */
+    effect?: string;
+    write?: boolean;
+    reject?: RejectRule[];
+}
+export interface GenericSeed {
+    collections?: Record<string, JsonObject[]>;
+    routes?: CustomRoute[];
+    tools?: CustomTool[];
+    /** Expose generic_list/get/create/update/delete as MCP tools. Default: true when collections are seeded. */
+    collection_tools?: boolean;
+}
+export declare class GenericBackend implements Backend {
+    private readonly world;
+    readonly name = "generic";
+    readonly mounts: {
+        prefix: string;
+        strip: boolean;
+    }[];
+    private collections;
+    private readonly customRoutes;
+    private readonly customTools;
+    private readonly exposeCollectionTools;
+    constructor(world: World, seed?: GenericSeed);
+    private coll;
+    private record;
+    private create;
+    private update;
+    private remove;
+    operations(): Operation[];
+    /** Custom routes, which are also served at their literal path outside `/generic`. */
+    fallbackRoutes(): HttpRoute[];
+    routes(): HttpRoute[];
+    errorResponse(err: ApiError): {
+        status: number;
+        body: {
+            error: {
+                code: string;
+                message: string;
+            };
+        };
+        headers: Record<string, string>;
+    };
+    snapshot(): {
+        collections: Record<string, unknown>;
+    };
+}