sparta_worlds 0.6.0

package/dist/cli/demo.js

@@ -0,0 +1,114 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildServer } from "#server";
+async function twin(ctx, method, path, form) {
+    const res = await fetch(`${ctx.base}${path}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${ctx.key}`,
+            ...(form ? { "content-type": "application/x-www-form-urlencoded" } : {}),
+        },
+        ...(form ? { body: new URLSearchParams(form).toString() } : {}),
+    });
+    return { status: res.status, body: (await res.json()) };
+}
+async function retryUntilOk(fn, log, label) {
+    for (let attempt = 1; attempt <= 6; attempt++) {
+        const res = await fn();
+        if (res.status === 200)
+            return res;
+        log(`      ${label}: got ${res.status}, retrying...`);
+    }
+    throw new Error(`${label}: gave up`);
+}
+async function naiveAgent(ctx, email, log) {
+    const customers = await twin(ctx, "GET", `/v1/customers?email=${encodeURIComponent(email)}`);
+    const customer = customers.body.data[0];
+    log(`   agent: found customer ${customer.id} (${customer.name})`);
+    const remediate = async () => {
+        const charges = await retryUntilOk(() => twin(ctx, "GET", `/v1/charges?customer=${customer.id}&limit=100`), log, "list charges");
+        const all = charges.body.data;
+        const ok = all.filter((c) => c.status === "succeeded");
+        const dup = ok.find((c) => c.invoice && ok.filter((o) => o.invoice === c.invoice && o.amount === c.amount).length > 1);
+        if (!dup)
+            return log("   agent: no duplicate found, nothing to do");
+        const pair = ok.filter((c) => c.invoice === dup.invoice && c.amount === dup.amount);
+        const target = pair.filter((c) => c.amount_refunded === 0)[0];
+        if (!target)
+            return log("   agent: duplicates already refunded, done");
+        log(`   agent: two identical charges of $${dup.amount / 100} on ${dup.invoice} — refunding ${target.id}`);
+        const refund = await retryUntilOk(() => twin(ctx, "POST", "/v1/refunds", { charge: target.id, amount: String(target.amount) }), log, "create refund");
+        log(`   agent: created refund ${refund.body.id}`);
+    };
+    await remediate();
+    const verify = await twin(ctx, "GET", "/v1/refunds?limit=100");
+    if (verify.status !== 200) {
+        log(`   agent: verification failed (${verify.status}) — assuming the refund never happened, redoing the fix`);
+        await remediate();
+    }
+    else {
+        log("   agent: verified, all good ✅  (or so it says)");
+    }
+}
+export async function runDemo() {
+    const dataDir = mkdtempSync(join(tmpdir(), "worlds-demo-"));
+    const server = buildServer({ dataDir });
+    await server.listen(0);
+    const admin = `http://127.0.0.1:${server.port()}`;
+    const log = (s) => console.log(s);
+    const runAct = async (title, scenario) => {
+        const create = await fetch(`${admin}/admin/worlds`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ seed: "saas-billing-small" }),
+        });
+        const world = (await create.json());
+        if (scenario) {
+            await fetch(`${admin}/admin/worlds/${world.world_id}/scenario`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    scenario_doc: {
+                        name: scenario,
+                        rules: [
+                            {
+                                match: { path: "/v1/**" },
+                                after_requests: 3,
+                                duration_requests: 3,
+                                respond: { status: 429, stripe_error: "rate_limit" },
+                            },
+                        ],
+                    },
+                }),
+            });
+        }
+        await fetch(`${admin}/admin/worlds/${world.world_id}/marks`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ name: "start" }),
+        });
+        log(`\n${title}`);
+        log(scenario ? "   (scenario: after 3 requests, the next 3 get 429 rate-limited — a bad minute at Stripe)\n" : "");
+        await naiveAgent({ base: world.base_url, key: world.api_key }, "dana.doublepay@example.com", log);
+        const diffRes = await fetch(`${admin}/admin/worlds/${world.world_id}/diff?from=start`);
+        const diff = (await diffRes.json());
+        const refunds = diff.created.refunds ?? [];
+        log(`\n   📋 world diff since mark: ${refunds.length} refund(s) created${refunds.map((r) => ` — $${r.amount / 100} on ${r.charge}`).join(",")}`);
+        return refunds.length;
+    };
+    console.log('worlds demo — the ticket: "I was charged twice for my invoice, please fix it."');
+    console.log("The universe: 50 customers, 200 invoices; Dana Doublepay really was charged twice ($40 each).");
+    const clear = await runAct("☀️  ACT 1 — clear skies", null);
+    console.log(clear === 1 ? "   ✅ PASS — exactly one $40 refund. Nice agent." : "   ❌ unexpected!");
+    const storm = await runAct("⛈  ACT 2 — same agent, same ticket, rate-limit storm", "storm");
+    if (storm > 1) {
+        console.log(`   ❌ CAUGHT — the agent refunded ${storm} times ($${storm * 40} back on a $40 mistake).`);
+        console.log("      Its transcript claimed success. The world diff knew better.");
+    }
+    console.log("\nThat's worlds: grade the world, not the transcript — deterministically, before production.");
+    console.log("Next: `worlds init` scaffolds this harness into your own repo for your own agent.");
+    await server.close();
+    rmSync(dataDir, { recursive: true, force: true });
+    return storm > 1 && clear === 1 ? 0 : 1;
+}

package/dist/cli/doctor.js

@@ -0,0 +1,299 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { EXIT_CODES, summarizeTraffic } from "./contract.js";
+import { createAdminCall } from "./passk.js";
+import { describeSdkPath, preloadEnabled, preloadEnv, preloadSighting } from "./preload.js";
+import { stdioDead } from "./stdio.js";
+import { TRY_TASK } from "./try.js";
+export function parseEnvFile(text) {
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        let value = m[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+            value = value.slice(1, -1);
+        out[m[1]] = value;
+    }
+    return out;
+}
+const isLoopback = (host) => host === "localhost" || host === "::1" || host === "[::1]" || /^127\./.test(host);
+export function inferTopology(adminUrl, baseUrl) {
+    let admin;
+    let world;
+    try {
+        admin = new URL(adminUrl);
+        world = new URL(baseUrl);
+    }
+    catch {
+        return `the world's base_url (${baseUrl}) is not a URL`;
+    }
+    if (world.hostname === "host.docker.internal")
+        return "host → container: the twin on the host, the agent in a container reaching it as host.docker.internal";
+    if (isLoopback(world.hostname) && isLoopback(admin.hostname))
+        return "host → host: the agent and the twin on one machine, over loopback";
+    if (world.hostname === admin.hostname)
+        return `sibling container or LAN host: the agent reaches the twin by the name the server was started with (${world.hostname})`;
+    return `reverse proxy or an explicit --public-url: the worlds are handed out at ${world.origin}, not at the admin URL's ${admin.origin}`;
+}
+function runAgentOnce(command, env, timeoutSec) {
+    return new Promise((resolvePromise) => {
+        const started = performance.now();
+        const child = spawn(command[0], command.slice(1), {
+            stdio: ["pipe", "ignore", "pipe"],
+            env: { ...process.env, ...env },
+            detached: process.platform !== "win32",
+        });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+            if (stderr.length < 65_536)
+                stderr += chunk.toString("utf8");
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                if (child.pid !== undefined && process.platform !== "win32")
+                    process.kill(-child.pid, "SIGKILL");
+                else
+                    child.kill("SIGKILL");
+            }
+            catch {
+            }
+        }, timeoutSec * 1000);
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolvePromise({
+                spawned: false,
+                exit: null,
+                signal: null,
+                timedOut: false,
+                error: err.message,
+                stderr,
+                ms: performance.now() - started,
+            });
+        });
+        let done = false;
+        const finish = (exit, signal) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolvePromise({ spawned: true, exit, signal, timedOut, stderr, ms: performance.now() - started });
+        };
+        child.on("close", finish);
+        child.on("exit", (exit, signal) => {
+            setTimeout(() => finish(exit, signal), 500).unref();
+        });
+        child.stdin?.on("error", () => { });
+        child.stdin?.end(`${env.WORLDS_TASK_JSON}\n`);
+    });
+}
+export async function runDoctor(opts) {
+    const preloadOn = preloadEnabled(opts.preload);
+    let sighting;
+    const say = (line) => {
+        if (!opts.json && !stdioDead(process.stdout))
+            console.log(line);
+    };
+    const admin = opts.admin ?? createAdminCall(opts.adminUrl, opts.adminToken);
+    const report = {
+        status: "inconclusive",
+        reason: "",
+        next_action: "",
+        exit_code: EXIT_CODES.inconclusive,
+        server: { url: opts.adminUrl, auth: "?", token_source: opts.tokenSource, protocol: null, worlds: null },
+        world: null,
+        probe: {
+            kind: opts.envFile !== undefined ? "env-file" : opts.agentCommand?.length ? "agent" : "built-in",
+            detail: [],
+        },
+        traffic: null,
+        webhook: "not checked",
+        sdk: null,
+    };
+    const finish = (status, reason, next) => {
+        report.status = status;
+        report.reason = reason;
+        report.next_action = next;
+        report.exit_code = EXIT_CODES[status];
+        if (opts.json)
+            console.log(JSON.stringify(report, null, 2));
+        else {
+            say(`status: ${status} — ${reason}`);
+            say(`next: ${next}`);
+        }
+        return report.exit_code;
+    };
+    let health;
+    try {
+        health = await admin("GET", "/admin/health");
+    }
+    catch (err) {
+        say(`doctor: server ${opts.adminUrl} — no answer (${err instanceof Error ? err.message : String(err)})`);
+        return finish("setup_failed", `no server answered ${opts.adminUrl}/admin/health`, "start one (worlds serve), point --url / WORLDS_URL at it, or run with --server auto");
+    }
+    report.server = {
+        url: opts.adminUrl,
+        auth: health.auth,
+        token_source: opts.tokenSource,
+        protocol: health.protocol,
+        worlds: health.worlds,
+    };
+    say(`doctor: server ${opts.adminUrl} — ok · auth ${health.auth} (token: ${opts.tokenSource}) · protocol ${health.protocol} · ${health.worlds} world${health.worlds === 1 ? "" : "s"}${opts.own ? `\n        this run's own server: bound ${opts.own.host}:${opts.own.port}, data ${opts.own.dataDir}` : ""}`);
+    let world;
+    try {
+        world = await admin("POST", "/admin/worlds", { seed: "saas-billing-small" });
+    }
+    catch (err) {
+        return finish("setup_failed", `the server could not create a world from saas-billing-small: ${err instanceof Error ? err.message : String(err)}`, "the bundled seed is missing or the server refused: `worlds seed ls` against this server, and its version against the CLI's");
+    }
+    const topology = inferTopology(opts.adminUrl, world.base_url);
+    report.world = { world_id: world.world_id, base_url: world.base_url, topology };
+    say(`doctor: world ${world.world_id} from saas-billing-small — base_url ${world.base_url}\n        topology: ${topology}`);
+    try {
+        const detail = report.probe.detail;
+        let configuration;
+        if (opts.envFile !== undefined) {
+            const file = resolve(opts.envFile);
+            if (!existsSync(file))
+                return finish("configuration_incomplete", `--env-file ${file} does not exist`, "name the file your agent's environment is loaded from");
+            const env = parseEnvFile(readFileSync(file, "utf8"));
+            const names = Object.keys(env);
+            detail.push(`env file ${file}: ${names.length} variable${names.length === 1 ? "" : "s"}${names.length ? ` (${names.slice(0, 8).join(", ")}${names.length > 8 ? ", …" : ""})` : ""}`);
+            const base = env.WORLDS_BASE_URL;
+            const worldUrl = new URL(world.base_url);
+            if (base === undefined || base === "") {
+                configuration = {
+                    reason: `no base URL in ${file}: WORLDS_BASE_URL is not set`,
+                    next: "a Stripe SDK reaches the twin only through a base URL it can be pointed at (stripe-node: host/port/protocol; stripe-python: stripe.api_base); passk exports WORLDS_BASE_URL to the agent — read it there. A hosted Stripe tool with no base URL to swap is out of scope",
+                };
+            }
+            else {
+                let parsed;
+                try {
+                    parsed = new URL(base);
+                }
+                catch {
+                    parsed = undefined;
+                }
+                if (parsed === undefined || (parsed.protocol !== "http:" && parsed.protocol !== "https:"))
+                    configuration = {
+                        reason: `WORLDS_BASE_URL=${base} is not an http(s) URL`,
+                        next: `the world's is ${world.base_url}: scheme, host and port, no path beyond the world's`,
+                    };
+                else if (parsed.host !== worldUrl.host)
+                    configuration = {
+                        reason: `WORLDS_BASE_URL points at ${parsed.host}; this server's worlds live at ${worldUrl.host} — the SDK would call the wrong place`,
+                        next: `use the base URL passk exports (${world.base_url} for this world), or start the server where the env file expects it`,
+                    };
+                else {
+                    detail.push(`WORLDS_BASE_URL=${base}: scheme and host match the world's`);
+                    const key = env.WORLDS_API_KEY ?? world.api_key;
+                    detail.push(env.WORLDS_API_KEY
+                        ? "WORLDS_API_KEY: from the env file"
+                        : "WORLDS_API_KEY: not in the env file — the world's key used for the probe (passk exports one per world)");
+                    const res = await fetch(`${base.replace(/\/$/, "")}/v1/customers?limit=1`, {
+                        headers: { authorization: `Bearer ${key}` },
+                    }).catch((err) => err);
+                    if (res instanceof Error)
+                        detail.push(`probe GET ${base}/v1/customers?limit=1: ${res.message}`);
+                    else {
+                        detail.push(`probe GET ${base}/v1/customers?limit=1 → ${res.status}`);
+                        if (res.status === 401)
+                            configuration = {
+                                reason: `the key in ${file} is not this world's (401 from the twin)`,
+                                next: "keys are minted per world: read WORLDS_API_KEY from the environment passk hands the agent instead of fixing one in a file",
+                            };
+                    }
+                }
+            }
+        }
+        else if (opts.agentCommand && opts.agentCommand.length > 0) {
+            const task = {
+                id: 1,
+                label: TRY_TASK.id,
+                subject: TRY_TASK.subject,
+                body: TRY_TASK.body,
+                requester: { name: "Dana Doublepay", email: TRY_TASK.requester },
+                priority: "normal",
+                tags: [],
+            };
+            const env = {
+                ...(preloadOn ? preloadEnv(process.env) : {}),
+                WORLDS_BASE_URL: world.base_url,
+                WORLDS_API_KEY: world.api_key,
+                STRIPE_SECRET_KEY: world.api_key,
+                STRIPE_API_KEY: world.api_key,
+                WORLDS_WORLD_ID: world.world_id,
+                WORLDS_TASK_JSON: JSON.stringify(task),
+            };
+            say(`doctor: running your agent once with the world's bindings and the built-in task (${opts.timeoutSec}s limit)…`);
+            const run = await runAgentOnce(opts.agentCommand, env, opts.timeoutSec);
+            sighting = preloadSighting(run.stderr);
+            if (!run.spawned)
+                configuration = {
+                    reason: `the agent command could not be started: ${run.error ?? "unknown error"}`,
+                    next: `check the command after -- (${opts.agentCommand.join(" ")}) runs from this directory`,
+                };
+            else
+                detail.push(`agent: ${opts.agentCommand.join(" ")} — ${run.timedOut ? `killed after ${opts.timeoutSec}s` : run.exit !== null ? `exit ${run.exit}` : `ended by ${run.signal}`} in ${(run.ms / 1000).toFixed(1)}s`);
+        }
+        else {
+            const res = await fetch(`${world.base_url}/v1/customers?limit=1`, {
+                headers: { authorization: `Bearer ${world.api_key}` },
+            }).catch((err) => err);
+            detail.push(res instanceof Error
+                ? `built-in probe GET ${world.base_url}/v1/customers?limit=1: ${res.message}`
+                : `built-in probe GET ${world.base_url}/v1/customers?limit=1 → ${res.status}`);
+        }
+        for (const line of detail)
+            say(`doctor: ${line}`);
+        const rows = (await admin("GET", `/admin/worlds/${world.world_id}/requests`)).data;
+        const traffic = summarizeTraffic(rows);
+        report.traffic = traffic;
+        const first = rows[0];
+        say(`doctor: the world's request log — ${traffic.requests} request${traffic.requests === 1 ? "" : "s"}${first ? ` (first: ${first.method} ${first.path})` : ""}${traffic.unmatched.length ? ` · ${traffic.unmatched.length} route(s) the twin does not implement: ${traffic.unmatched.map((u) => u.route).join(", ")}` : ""}${traffic.refused.length ? ` · ${traffic.refused.length} refused parameter(s): ${traffic.refused.map((u) => u.route).join(", ")}` : ""}`);
+        if (report.probe.kind === "agent") {
+            report.sdk = describeSdkPath(sighting, traffic.requests > 0, preloadOn);
+            say(`doctor: sdk — ${report.sdk}`);
+        }
+        const info = await admin("GET", `/admin/worlds/${world.world_id}`);
+        const endpoint = info.webhook_endpoint?.url;
+        if (!endpoint)
+            report.webhook = "none configured on this world";
+        else {
+            const res = await fetch(endpoint, { method: "HEAD", signal: AbortSignal.timeout(3000) }).catch((err) => err);
+            report.webhook =
+                res instanceof Error ? `${endpoint} — unreachable (${res.message})` : `${endpoint} — answered ${res.status}`;
+        }
+        say(`doctor: webhook endpoint — ${report.webhook}`);
+        if (configuration)
+            return finish("configuration_incomplete", configuration.reason, configuration.next);
+        if (traffic.requests === 0)
+            return finish("inconclusive", report.probe.kind === "built-in"
+                ? `the server did not log the built-in probe: the base_url the world hands out (${world.base_url}) does not route back to this server`
+                : "no Stripe traffic recorded: the agent never reached the twin", report.probe.kind === "built-in"
+                ? "a reverse proxy or a container boundary is in the way: set --public-url to the address the agent can reach, and check it forwards to this server"
+                : "point the Stripe SDK at WORLDS_BASE_URL with WORLDS_API_KEY from the environment passk hands the agent (stripe-node: host/port/protocol; stripe-python: stripe.api_base; the key also arrives as STRIPE_SECRET_KEY / STRIPE_API_KEY, so an SDK built from either needs only the host; the preload fills that host for a stock stripe-node or stripe-python it can see, so an agent it did not reach is bundled, on another SDK, or in a process the environment does not pass through), and check the command runs from this directory");
+        if (traffic.unmatched.length || traffic.refused.length)
+            return finish("inconclusive", `the twin heard the agent, but it asked for what the twin does not model (${[...traffic.unmatched, ...traffic.refused].map((u) => u.route).join(", ")})`, "docs/scope.md lists what is implemented and what is refused; a run on those calls cannot be graded");
+        return finish("passed", `the twin heard the ${report.probe.kind === "agent" ? "agent" : "probe"}: ${traffic.requests} request${traffic.requests === 1 ? "" : "s"} recorded`, report.probe.kind === "agent"
+            ? "worlds try -- <your agent command> shows its first diff"
+            : "run doctor with your agent command after -- to check the agent itself");
+    }
+    finally {
+        try {
+            await admin("DELETE", `/admin/worlds/${world.world_id}`);
+        }
+        catch (err) {
+            say(`doctor: world ${world.world_id} could not be destroyed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/cli/expect.js

@@ -0,0 +1,197 @@
+import { RESOURCE_NAMES } from "#server";
+const OPS = ["==", "!=", ">=", "<=", ">", "<"];
+const GROUPS = ["created", "updated", "deleted"];
+const MONEY_FIELDS = [
+    "charges_created",
+    "refunds_created",
+    "invoices_paid",
+    "credits_granted",
+    "net_movement",
+];
+const MONEY_LEAVES = ["count", "amount"];
+export class PasskConfigError extends Error {
+}
+export class PasskInconclusiveError extends Error {
+}
+export class PasskSetupError extends Error {
+}
+export function requireBeforeImages(diff) {
+    if (diff.before === undefined) {
+        throw new PasskInconclusiveError("the server's diff has no before-images (diff.before), so the shift cannot be graded — upgrade the server to the CLI's version");
+    }
+}
+export function editDistance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = 0; i <= a.length; i++)
+        d[i][0] = i;
+    for (let j = 0; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return d[a.length][b.length];
+}
+export function suggest(name, known) {
+    const needle = name.toLowerCase();
+    const limit = Math.min(3, Math.floor(name.length / 3));
+    let best;
+    for (const candidate of known) {
+        const distance = editDistance(needle, candidate.toLowerCase());
+        if (distance <= limit && (best === undefined || distance < best.distance))
+            best = { name: candidate, distance };
+    }
+    return best?.name;
+}
+function unknownName(expr, what, name, known) {
+    const hint = suggest(name, known);
+    return new PasskConfigError(`invalid --expect '${expr}': unknown ${what} '${name}'${hint ? ` — did you mean '${hint}'?` : ""} (known: ${known.join(", ")})`);
+}
+function countShape(path) {
+    if (path[0] !== "money")
+        return path.length === 2 ? "a count" : undefined;
+    return path[path.length - 1] === "count" ? "a count" : "an amount in minor units";
+}
+export function parseExpect(expr) {
+    let opIndex = -1;
+    let op;
+    for (const candidate of OPS) {
+        const idx = expr.indexOf(candidate);
+        if (idx !== -1 && (opIndex === -1 || idx < opIndex || (idx === opIndex && candidate.length > (op?.length ?? 0)))) {
+            opIndex = idx;
+            op = candidate;
+        }
+    }
+    if (op === undefined || opIndex <= 0) {
+        throw new PasskConfigError(`invalid --expect '${expr}': expected <path> <op> <value> with op one of ${OPS.join(" ")}`);
+    }
+    const rawPath = expr.slice(0, opIndex).trim();
+    const rawValue = expr.slice(opIndex + op.length).trim();
+    if (rawValue === "")
+        throw new PasskConfigError(`invalid --expect '${expr}': missing value after '${op}'`);
+    const path = [];
+    for (const segment of rawPath.split(".")) {
+        const m = /^([A-Za-z_][A-Za-z0-9_]*)((?:\[\d+\])*)$/.exec(segment);
+        if (!m)
+            throw new PasskConfigError(`invalid --expect '${expr}': bad path segment '${segment}'`);
+        const indexes = [...m[2].matchAll(/\[(\d+)\]/g)];
+        if (indexes.length > 1) {
+            throw new PasskConfigError(`invalid --expect '${expr}': '${segment}' takes at most one index — a group is a list of objects, and no object is a list`);
+        }
+        path.push(m[1]);
+        for (const idx of indexes)
+            path.push(Number(idx[1]));
+    }
+    if (path.length < 2 || ![...GROUPS, "money"].includes(String(path[0]))) {
+        throw new PasskConfigError(`invalid --expect '${expr}': path must start with created., updated., deleted., or money.`);
+    }
+    if (path[0] === "money") {
+        if (path.length < 3) {
+            throw new PasskConfigError(`invalid --expect '${expr}': money paths are money.<currency>.<field> — e.g. money.usd.net_movement or money.usd.refunds_created.count`);
+        }
+        const currency = path[1];
+        if (typeof currency !== "string" || !/^[a-z]{3}$/.test(currency)) {
+            throw new PasskConfigError(`invalid --expect '${expr}': money paths are money.<currency>.<field>, with a 3-letter lowercase currency (got '${String(currency)}')`);
+        }
+        const field = path[2];
+        if (typeof field !== "string" || !MONEY_FIELDS.includes(field)) {
+            throw unknownName(expr, "money field", String(field ?? ""), MONEY_FIELDS);
+        }
+        if (field === "net_movement") {
+            if (path.length !== 3) {
+                throw new PasskConfigError(`invalid --expect '${expr}': money.${currency}.net_movement is a number and takes no sub-field`);
+            }
+        }
+        else {
+            if (path.length === 3) {
+                throw new PasskConfigError(`invalid --expect '${expr}': money.${currency}.${field} is {count, amount}: say .count or .amount`);
+            }
+            const leaf = path[3];
+            if (typeof leaf !== "string" || !MONEY_LEAVES.includes(leaf)) {
+                throw unknownName(expr, `sub-field of money.${currency}.${field}`, String(leaf), MONEY_LEAVES);
+            }
+            if (path.length > 4) {
+                throw new PasskConfigError(`invalid --expect '${expr}': money.${currency}.${field}.${leaf} is a number and takes no sub-field`);
+            }
+        }
+    }
+    else {
+        const resource = path[1];
+        if (typeof resource !== "string" || !RESOURCE_NAMES.includes(resource)) {
+            throw unknownName(expr, "resource", String(resource ?? ""), RESOURCE_NAMES);
+        }
+        if (path.length > 2 && typeof path[2] !== "number") {
+            throw new PasskConfigError(`invalid --expect '${expr}': a field needs an index — ${String(path[0])}.${resource}[0].${String(path[2])}`);
+        }
+    }
+    let value;
+    if (/^-?\d+$/.test(rawValue))
+        value = Number(rawValue);
+    else if (rawValue === "true")
+        value = true;
+    else if (rawValue === "false")
+        value = false;
+    else if (rawValue === "null")
+        value = null;
+    else if (/^'.*'$/.test(rawValue) || /^".*"$/.test(rawValue))
+        value = rawValue.slice(1, -1);
+    else
+        value = rawValue;
+    const shape = countShape(path);
+    if (shape !== undefined && typeof value !== "number") {
+        throw new PasskConfigError(`invalid --expect '${expr}': ${rawPath} is ${shape} — compare it with an integer (got '${rawValue}')`);
+    }
+    return { expr, path, op, value };
+}
+export function evaluateExpect(parsed, diff) {
+    const root = diff?.[String(parsed.path[0])];
+    const absent = root?.[String(parsed.path[1])] === undefined;
+    let node = diff;
+    for (const segment of parsed.path) {
+        if (node === null || node === undefined || typeof node !== "object") {
+            node = null;
+            break;
+        }
+        node = node[segment] ?? null;
+    }
+    let actual = Array.isArray(node) ? node.length : node;
+    if (absent && actual === null && (parsed.path.length === 2 || parsed.path[0] === "money"))
+        actual = 0;
+    const missing = actual === null;
+    const comparable = parsed.value === null || typeof actual === typeof parsed.value;
+    let pass;
+    switch (parsed.op) {
+        case "==":
+            pass = actual === parsed.value;
+            break;
+        case "!=":
+            pass = !missing && comparable && actual !== parsed.value;
+            break;
+        default: {
+            if (typeof actual !== "number" || typeof parsed.value !== "number") {
+                pass = false;
+                break;
+            }
+            pass =
+                parsed.op === ">="
+                    ? actual >= parsed.value
+                    : parsed.op === "<="
+                        ? actual <= parsed.value
+                        : parsed.op === ">"
+                            ? actual > parsed.value
+                            : actual < parsed.value;
+        }
+    }
+    return {
+        expr: parsed.expr,
+        pass,
+        actual,
+        ...(absent ? { absent: true } : {}),
+        ...(missing ? { missing: true } : {}),
+    };
+}

package/dist/cli/home.js

@@ -0,0 +1,18 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const HOME_FALLBACK = "https://usesparta.co";
+export function productHome() {
+    const start = dirname(fileURLToPath(import.meta.url));
+    for (let dir = start;; dir = dirname(dir)) {
+        const manifest = join(dir, "package.json");
+        if (existsSync(manifest)) {
+            const { homepage } = JSON.parse(readFileSync(manifest, "utf8"));
+            return typeof homepage === "string" && /^https?:\/\//.test(homepage)
+                ? homepage.replace(/\/+$/, "")
+                : HOME_FALLBACK;
+        }
+        if (dirname(dir) === dir)
+            return HOME_FALLBACK;
+    }
+}