@layoutplatforms/cli 0.1.0

package/dist/args.js

@@ -0,0 +1,53 @@
+import { usageError } from "./errors.js";
+export const GLOBAL_FLAGS = [
+    { name: "json", type: "boolean" },
+    { name: "help", type: "boolean" },
+    { name: "version", type: "boolean" },
+    { name: "app", type: "string" },
+];
+export function parseArgs(argv, specs) {
+    const all = new Map();
+    for (const s of [...GLOBAL_FLAGS, ...specs])
+        all.set(s.name, s);
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--") {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (arg === "-h") {
+            flags.help = true;
+            continue;
+        }
+        if (!arg.startsWith("--") || arg === "--") {
+            positionals.push(arg);
+            continue;
+        }
+        const eq = arg.indexOf("=");
+        const name = arg.slice(2, eq === -1 ? undefined : eq);
+        const negated = name.startsWith("no-") && all.get(name.slice(3))?.type === "boolean";
+        const spec = all.get(negated ? name.slice(3) : name) ?? all.get(name);
+        if (!spec)
+            throw usageError(`Unknown flag --${name}. Run with --help to see the flags.`);
+        if (spec.type === "boolean") {
+            if (eq !== -1)
+                throw usageError(`--${name} takes no value.`);
+            flags[spec.name] = !negated;
+            continue;
+        }
+        const value = eq !== -1 ? arg.slice(eq + 1) : argv[++i];
+        if (value === undefined || (eq === -1 && value.startsWith("--")))
+            throw usageError(`--${name} needs a value.`);
+        flags[spec.name] = value;
+    }
+    return { positionals, flags };
+}
+export function str(p, name) {
+    const v = p.flags[name];
+    return typeof v === "string" ? v : undefined;
+}
+export function bool(p, name) {
+    return p.flags[name] === true;
+}

package/dist/bin.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { defaultPlatform } from "./context.js";
+import { main } from "./main.js";
+const [major] = process.versions.node.split(".").map(Number);
+if ((major ?? 0) < 20) {
+    process.stderr.write("The Layout CLI needs Node 20 or later.\n");
+    process.exit(1);
+}
+function openUrl(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const platform = {
+    ...defaultPlatform({ out: process.stdout, err: process.stderr, env: process.env }),
+    openUrl,
+    hostname: () => hostname().replace(/\.local$/, ""),
+};
+main(process.argv.slice(2), platform).then((code) => { process.exitCode = code; }, () => { process.exitCode = 1; });

package/dist/commands/listen.js

@@ -0,0 +1,96 @@
+import { join } from "node:path";
+import { bool, str } from "../args.js";
+import { configDir, hostKey, readJson, writePrivateJson } from "../config.js";
+import { EXIT, usageError } from "../errors.js";
+import { authed, pickApp } from "../context.js";
+import { WEBHOOKS_PAGE } from "./resources.js";
+import { mintLocalSecret, runListener } from "../listen.js";
+export function cursorFile(env, base, app) {
+    return join(configDir(env), "listen", hostKey(base).replace(/[^A-Za-z0-9.-]/g, "_"), `${app.replace(/[^A-Za-z0-9_]/g, "_")}.json`);
+}
+function forwardUrl(raw) {
+    if (!raw)
+        throw usageError("Give --forward-to, for example --forward-to http://localhost:3000/webhooks/layout.");
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw usageError("--forward-to must be a full http or https URL.");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw usageError("--forward-to must be an http or https URL.");
+    return url.toString();
+}
+export async function listen(ctx) {
+    const { out, p } = ctx;
+    const forwardTo = forwardUrl(str(ctx.args, "forward-to"));
+    const filter = str(ctx.args, "events");
+    const events = filter ? new Set(filter.split(",").map((s) => s.trim()).filter(Boolean)) : null;
+    const app = await pickApp(ctx);
+    const enc = encodeURIComponent(app);
+    const stateFile = cursorFile(ctx.env, ctx.base, app);
+    const saved = readJson(stateFile)?.cursor ?? null;
+    let start;
+    if (bool(ctx.args, "from-start"))
+        start = null;
+    else if (saved)
+        start = saved;
+    else
+        start = (await authed(ctx, `/v1/cli/apps/${enc}/events/cursor`)).cursor;
+    const hooks = await authed(ctx, `/v1/cli/apps/${enc}/webhooks`);
+    const secret = mintLocalSecret();
+    if (out.json)
+        out.data({ event: "listening", app, forwardTo, secret, resumed: Boolean(saved) && !bool(ctx.args, "from-start") });
+    else {
+        out.line(`Forwarding sandbox events for ${app} to ${forwardTo}`);
+        out.line(`Signing secret for this run  ${out.accent(secret)}`);
+        out.line(saved && !bool(ctx.args, "from-start") ? "Resuming after the last event forwarded." : "Starting from now. Press Ctrl-C to stop.");
+    }
+    if (!hooks.subscriptions.some((s) => s.enabled)) {
+        out.note(`This application has no enabled webhook endpoint, so Layout records no events for it. Add one once in the console: ${WEBHOOKS_PAGE}`);
+    }
+    let stopped = false;
+    const off = p.onInterrupt(() => { stopped = true; });
+    const spin = out.spinner("Waiting for events");
+    const report = (r) => {
+        if (r.kind === "forwarded") {
+            if (out.json)
+                out.data({ cursor: r.cursor, event: r.event, eventId: r.eventId, status: r.status, forwardedAt: new Date(p.now()).toISOString() });
+            else {
+                spin.stop();
+                out.line(`${new Date(p.now()).toISOString().slice(11, 19)}  ${r.event.padEnd(18)} ${out.accent(String(r.status))}  ${r.eventId ?? ""}`.trimEnd());
+            }
+        }
+        else if (r.kind === "forward_failed") {
+            out.note(`${r.event} not accepted by ${forwardTo} (${r.status === 0 ? "no answer" : r.status}). Retrying in ${Math.round(r.retryInMs / 1000)}s.`);
+        }
+        else if (r.kind === "feed_unavailable") {
+            out.note(`Layout could not be reached. Retrying in ${Math.round(r.retryInMs / 1000)}s.`);
+        }
+    };
+    try {
+        await runListener(start, { forwardTo, secret, events, pollMs: 2_000, maxBackoffMs: 30_000 }, {
+            fetchPage: (cursor) => authed(ctx, `/v1/cli/apps/${enc}/events?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`, { retry: false }),
+            forward: async (url, body, headers) => {
+                const res = await p.http.fetch(url, { method: "POST", headers, body, signal: AbortSignal.timeout(10_000), redirect: "manual" });
+                await res.arrayBuffer().catch(() => undefined);
+                return { ok: res.status >= 200 && res.status < 300, status: res.status };
+            },
+            saveCursor: (cursor) => writePrivateJson(stateFile, { cursor, updatedAt: new Date(p.now()).toISOString() }),
+            sleep: async (ms) => {
+                const until = p.now() + ms;
+                while (!stopped && p.now() < until)
+                    await p.sleep(Math.min(250, until - p.now()));
+            },
+            stopped: () => stopped,
+            report,
+            nowSec: () => Math.floor(p.now() / 1000),
+        });
+    }
+    finally {
+        spin.stop();
+        off();
+    }
+    return stopped ? EXIT.interrupted : EXIT.ok;
+}

package/dist/commands/resources.js

@@ -0,0 +1,161 @@
+import { bool, str } from "../args.js";
+import { DOCS_BASE } from "../config.js";
+import { CliError, EXIT, usageError } from "../errors.js";
+import { authed, pickApp } from "../context.js";
+export const WEBHOOKS_PAGE = `${DOCS_BASE}/console/webhooks/subscriptions`;
+const SHOWN_ONCE = "Shown once. Store it in your secret manager, never in source control.";
+export async function appsList(ctx) {
+    const data = await authed(ctx, "/v1/cli/apps");
+    ctx.out.result(data, () => {
+        if (data.apps.length === 0)
+            return ctx.out.line("No applications yet. Create one with layout apps create <name>.");
+        ctx.out.table(data.apps.map((a) => [a.id, a.name, a.status, a.createdAt.slice(0, 10)]), ["ID", "NAME", "STATUS", "CREATED"]);
+    });
+    return EXIT.ok;
+}
+export async function appsCreate(ctx) {
+    const name = ctx.args.positionals.slice(2).join(" ").trim();
+    if (!name)
+        throw usageError("Name the application: layout apps create <name>.");
+    const data = await authed(ctx, "/v1/cli/apps", {
+        method: "POST", body: { name }, idempotent: true, retry: true,
+    });
+    ctx.out.result(data, () => {
+        ctx.out.line(`Created ${data.app.name} (${data.app.id}). Production is reviewed by a person; sandbox works now.`);
+        ctx.out.line(`Sandbox client id  ${data.sandboxKey.clientId}`);
+        ctx.out.line(`Sandbox secret     ${ctx.out.accent(data.sandboxKey.secret)}`);
+        ctx.out.line(SHOWN_ONCE);
+    });
+    return EXIT.ok;
+}
+export async function keysList(ctx) {
+    const app = await pickApp(ctx);
+    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys`);
+    ctx.out.result({ app, ...data }, () => {
+        if (data.keys.length === 0)
+            return ctx.out.line("No sandbox key. Create one with layout keys create.");
+        ctx.out.table(data.keys.map((k) => [k.clientId, `sk_test_...${k.last4}`, k.createdAt.slice(0, 10), k.lastUsedAt ? k.lastUsedAt.slice(0, 10) : "never"]), ["CLIENT ID", "SECRET", "CREATED", "LAST USED"]);
+    });
+    return EXIT.ok;
+}
+export async function keysCreate(ctx) {
+    const app = await pickApp(ctx);
+    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys`, {
+        method: "POST", body: { replace: bool(ctx.args, "replace") }, idempotent: true, retry: true,
+    }).catch((err) => {
+        if (err instanceof CliError && err.code === "key_exists") {
+            throw new CliError("key_exists", "This application already has a sandbox key. Run layout keys create --replace to retire it and make another.", EXIT.conflict);
+        }
+        throw err;
+    });
+    ctx.out.result({ app, ...data }, () => {
+        ctx.out.line(data.replaced ? "New sandbox key. The old one no longer works." : "New sandbox key.");
+        ctx.out.line(`Client id  ${data.clientId}`);
+        ctx.out.line(`Secret     ${ctx.out.accent(data.secret)}`);
+        ctx.out.line(SHOWN_ONCE);
+    });
+    return EXIT.ok;
+}
+export async function keysRevoke(ctx) {
+    const app = await pickApp(ctx);
+    if (!bool(ctx.args, "yes")) {
+        throw usageError("Revoking stops the sandbox key and its sandbox build grants at once. Run again with --yes to confirm.");
+    }
+    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys/revoke`, {
+        method: "POST", body: {}, idempotent: true, retry: true,
+    });
+    ctx.out.result({ app, ...data }, () => {
+        ctx.out.line(data.revoked > 0 ? "Sandbox key revoked." : "There was no sandbox key to revoke.");
+    });
+    return EXIT.ok;
+}
+export async function webhooksList(ctx) {
+    const app = await pickApp(ctx);
+    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/webhooks`);
+    ctx.out.result({ app, ...data }, () => {
+        if (data.subscriptions.length === 0)
+            ctx.out.line(`No webhook endpoints. Add one once in the console: ${WEBHOOKS_PAGE}`);
+        else
+            ctx.out.table(data.subscriptions.map((s) => [s.id, s.enabled ? "on" : "off", s.url, s.events.join(",")]), ["ID", "STATE", "URL", "EVENTS"]);
+        if (data.signingSecret)
+            ctx.out.line(`Sandbox signing secret  ${data.signingSecret}`);
+        ctx.out.line(`Endpoints are managed in the console: ${WEBHOOKS_PAGE}`);
+    });
+    return EXIT.ok;
+}
+export async function trigger(ctx) {
+    const event = ctx.args.positionals[1];
+    if (!event)
+        throw usageError("Name the event: layout trigger order.placed.");
+    const app = await pickApp(ctx);
+    const order = str(ctx.args, "order");
+    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/trigger`, {
+        method: "POST", body: { event, ...(order ? { orderId: order } : {}) }, idempotent: true, retry: true,
+    });
+    ctx.out.result({ app, ...data }, () => {
+        ctx.out.line(`Sent ${data.event} to ${data.deliveries.length} endpoint${data.deliveries.length === 1 ? "" : "s"}${data.order ? `, describing ${data.order.id}` : ""}.`);
+        ctx.out.table(data.deliveries.map((d) => [d.id, d.outcome, d.url]));
+    });
+    return EXIT.ok;
+}
+export async function usage(ctx) {
+    const app = await pickApp(ctx);
+    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/usage`);
+    ctx.out.result({ app, usage: data }, () => {
+        for (const env of ["sandbox", "live"]) {
+            const u = data[env];
+            if (u && typeof u.perDay === "number")
+                ctx.out.line(`${env === "live" ? "Production" : "Sandbox"} builds today  ${u.usedToday ?? 0} of ${u.perDay}`);
+        }
+        ctx.out.line(`Every allowance: ${DOCS_BASE}/console/usage`);
+    });
+    return EXIT.ok;
+}
+export async function deliveries(ctx) {
+    const app = await pickApp(ctx);
+    const limit = Number(str(ctx.args, "limit") ?? "20");
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw usageError("--limit is a whole number from 1 to 100.");
+    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/deliveries?limit=${limit}`);
+    ctx.out.result({ app, ...data }, () => {
+        if (data.deliveries.length === 0)
+            return ctx.out.line("No sandbox deliveries yet.");
+        ctx.out.table(data.deliveries.map((d) => [d.createdAt.replace("T", " ").slice(0, 19), d.event, d.status, d.responseStatus === null ? "" : String(d.responseStatus), d.url]), ["WHEN", "EVENT", "STATUS", "HTTP", "URL"]);
+    });
+    return EXIT.ok;
+}
+export async function requestLiveAccess(ctx) {
+    const app = await pickApp(ctx);
+    const note = str(ctx.args, "note");
+    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/live-access`, {
+        method: "POST", body: note ? { note } : {}, idempotent: true, retry: true,
+    });
+    ctx.out.result({ app, ...data }, () => {
+        if (data.status === "approved")
+            ctx.out.line("This application is already approved for production.");
+        else if (data.status === "already_requested")
+            ctx.out.line("A review is already open. Layout emails you when it is decided.");
+        else
+            ctx.out.line("Review requested. A person at Layout decides it and emails you. Sandbox keeps working.");
+    });
+    return EXIT.ok;
+}
+export const DOC_TOPICS = {
+    cli: "/reference/cli",
+    quickstart: "/reference/quickstart",
+    sandbox: "/reference/sandbox",
+    webhooks: "/reference/webhooks",
+    events: "/reference/events",
+    api: "/reference/api",
+};
+export async function docs(ctx) {
+    const topic = ctx.args.positionals[1] ?? "cli";
+    const path = DOC_TOPICS[topic];
+    if (!path)
+        throw usageError(`Unknown topic ${topic}. Topics: ${Object.keys(DOC_TOPICS).join(", ")}.`);
+    const url = `${DOCS_BASE}${path}`;
+    const markdown = `${url}.md`;
+    const opened = !ctx.out.json && Boolean(ctx.p.streams.out.isTTY) && ctx.p.openUrl(url);
+    ctx.out.result({ topic, url, markdown }, () => ctx.out.line(opened ? `Opened ${url}` : url));
+    return EXIT.ok;
+}

package/dist/commands/session.js

@@ -0,0 +1,129 @@
+import { bool, str } from "../args.js";
+import { hostKey, readSession, writeSession } from "../config.js";
+import { chooseStore, fileStore, storeOfKind } from "../credentials.js";
+import { CliError, EXIT } from "../errors.js";
+import { authed, forget } from "../context.js";
+const GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export async function login(ctx) {
+    const { out, api, p } = ctx;
+    const existing = readSession(ctx.env, ctx.base);
+    if (existing)
+        forget(ctx, existing);
+    const deviceName = str(ctx.args, "device-name") ?? p.hostname() ?? null;
+    const code = (await api.request("/v1/cli/device/code", { method: "POST", body: { device_name: deviceName || null }, retry: true })).data;
+    if (out.json) {
+        out.data({ event: "code", userCode: code.user_code, verificationUri: code.verification_uri, verificationUriComplete: code.verification_uri_complete, expiresIn: code.expires_in });
+    }
+    else {
+        out.line(out.wordmark());
+        out.line();
+        out.line(`Your sign-in code is ${out.accent(code.user_code)}`);
+        out.line(`Approve it at ${code.verification_uri_complete}`);
+        out.line("Check the code matches before you approve.");
+        out.line();
+    }
+    const opened = !bool(ctx.args, "no-browser") && !ctx.env.CI && p.openUrl(code.verification_uri_complete);
+    if (!out.json && !opened)
+        out.line("Open that link in a browser signed in to the Layout console.");
+    const spin = out.spinner("Waiting for approval in the console");
+    let interval = Math.max(1, code.interval);
+    const deadline = p.now() + code.expires_in * 1000;
+    let cancelled = false;
+    const off = p.onInterrupt(() => { cancelled = true; });
+    try {
+        while (p.now() < deadline) {
+            await p.sleep(interval * 1000);
+            if (cancelled)
+                throw new CliError("interrupted", "Sign-in cancelled.", EXIT.interrupted);
+            let res;
+            try {
+                res = await api.request("/v1/cli/device/token", {
+                    method: "POST",
+                    body: { grant_type: GRANT, device_code: code.device_code },
+                    retry: true,
+                    okStatuses: [400],
+                });
+            }
+            catch (err) {
+                if (err instanceof CliError && err.exit === EXIT.unavailable)
+                    continue;
+                throw err;
+            }
+            if (res.status === 200) {
+                spin.stop();
+                return await finishLogin(ctx, res.data);
+            }
+            const e = res.data;
+            if (e.error === "authorization_pending")
+                continue;
+            if (e.error === "slow_down") {
+                interval = Math.max(interval + 5, e.interval ?? 0);
+                continue;
+            }
+            if (e.error === "access_denied")
+                throw new CliError("access_denied", "Sign-in was denied in the console.", EXIT.refused);
+            if (e.error === "expired_token")
+                throw new CliError("expired_token", "The sign-in code expired. Run layout login again.", EXIT.auth);
+            throw new CliError(e.error || "invalid_grant", e.error_description ?? "Sign-in failed. Run layout login again.", EXIT.auth);
+        }
+        throw new CliError("expired_token", "The sign-in code expired. Run layout login again.", EXIT.auth);
+    }
+    finally {
+        spin.stop();
+        off();
+    }
+}
+async function finishLogin(ctx, tok) {
+    const { out } = ctx;
+    const choice = chooseStore(ctx.env, ctx.p.platform, ctx.p.run);
+    let store = choice.store;
+    let warning = choice.warning;
+    if (!store.set(hostKey(ctx.base), tok.access_token)) {
+        const file = fileStore(ctx.env);
+        if (!file.set(hostKey(ctx.base), tok.access_token))
+            throw new CliError("store_failed", "The CLI token could not be saved.", EXIT.error);
+        store = file;
+        warning = `The ${choice.store.kind} store refused the CLI token, so it is stored in ${file.path} (readable only by you).`;
+    }
+    const expiresAt = new Date(ctx.p.now() + tok.expires_in * 1000).toISOString();
+    writeSession(ctx.env, ctx.base, { sessionId: tok.session_id, accountId: "", accountName: null, store: store.kind, expiresAt });
+    if (warning)
+        out.note(warning);
+    const who = await authed(ctx, "/v1/cli/whoami");
+    writeSession(ctx.env, ctx.base, { sessionId: tok.session_id, accountId: who.account.id, accountName: who.account.name, store: store.kind, expiresAt: who.session.expiresAt });
+    out.result({ event: "signed_in", account: who.account, session: who.session }, () => {
+        out.line(`Signed in to ${who.account.name ?? "your developer account"}. This CLI works in sandbox only.`);
+    });
+    return EXIT.ok;
+}
+export async function logout(ctx) {
+    const { out } = ctx;
+    const record = readSession(ctx.env, ctx.base);
+    let revoked = false;
+    if (record) {
+        const token = storeOfKind(record.store, ctx.env, ctx.p.run).get(hostKey(ctx.base));
+        if (token) {
+            try {
+                await ctx.api.request("/v1/cli/logout", { method: "POST", body: {}, auth: token, retry: true });
+                revoked = true;
+            }
+            catch (err) {
+                if (!(err instanceof CliError) || err.exit !== EXIT.auth) {
+                    throw new CliError(err instanceof CliError ? err.code : "error", "Could not revoke this session on Layout, so it is still signed in here. Retry layout logout.", err instanceof CliError ? err.exit : EXIT.error);
+                }
+            }
+        }
+        forget(ctx, record);
+    }
+    out.result({ signedOut: true, revoked }, () => out.line(record ? (revoked ? "Signed out. This session is revoked on Layout." : "Signed out.") : "Not signed in."));
+    return EXIT.ok;
+}
+export async function whoami(ctx) {
+    const who = await authed(ctx, "/v1/cli/whoami");
+    ctx.out.result(who, () => {
+        ctx.out.line(`${who.account.name ?? "Developer account"} (${who.account.id})`);
+        ctx.out.line(`Session ${who.session.deviceName ? `on ${who.session.deviceName}, ` : ""}expires ${who.session.expiresAt.slice(0, 10)}`);
+        ctx.out.line("Sandbox only.");
+    });
+    return EXIT.ok;
+}

package/dist/commands/test-order.js

@@ -0,0 +1,128 @@
+import { createHash, randomUUID } from "node:crypto";
+import { str } from "../args.js";
+import { CliError, EXIT, usageError } from "../errors.js";
+import { authed, pickApp } from "../context.js";
+export const EXPECTED = {
+    test_place_carted: "placed",
+    test_place_placed: "placed",
+    test_place_branch_north: "placed",
+    test_place_branch_south: "placed",
+    test_place_challenge: "placed",
+    test_place_slow: "placed",
+    test_place_price_changed: "placed",
+    test_place_failed: "failed",
+    test_place_unconfirmed: "unconfirmed",
+    test_place_closed: "failed",
+};
+const TERMINAL = new Set(["placed", "failed", "unconfirmed", "canceled", "cancelled", "expired", "refunded"]);
+export function testPhone(appId) {
+    const n = parseInt(createHash("sha256").update(appId).digest("hex").slice(0, 8), 16) % 1900;
+    return `+1500555${String(100 + n).padStart(4, "0")}`;
+}
+const money = (minor) => (typeof minor === "number" ? `$${(minor / 100).toFixed(2)}` : "unknown");
+export async function testOrder(ctx) {
+    const { out, api, p } = ctx;
+    const place = str(ctx.args, "place") ?? "test_place_placed";
+    const expected = EXPECTED[place];
+    if (!expected)
+        throw usageError(`test-order runs a test restaurant that builds a cart on its own: ${Object.keys(EXPECTED).join(", ")}.`);
+    const app = await pickApp(ctx);
+    const steps = [];
+    const run = `cli-${randomUUID()}`;
+    let current = out.spinner("Reading the sandbox key");
+    const done = (step, detail) => {
+        steps.push({ step, status: "ok", detail });
+        current.stop();
+        if (!out.json)
+            out.line(`${out.accent("done")}    ${step}  ${detail}`);
+    };
+    const next = (text) => { current = out.spinner(text); };
+    const fail = (step, err) => {
+        const e = err instanceof CliError ? err : new CliError("error", String(err), EXIT.error);
+        steps.push({ step, status: "failed", detail: e.message });
+        current.stop();
+        if (out.json)
+            out.data({ app, place, steps, order: null, ok: false });
+        else
+            out.line(`failed  ${step}  ${e.message}`);
+        throw new CliError(e.code, e.message, e.exit, { step });
+    };
+    const until = async (step, read, settled, timeoutMs) => {
+        const deadline = p.now() + timeoutMs;
+        for (;;) {
+            const v = await read().catch((err) => fail(step, err));
+            if (settled(v))
+                return v;
+            if (p.now() > deadline)
+                fail(step, new CliError("timeout", "Timed out waiting. Read it again later.", EXIT.unavailable));
+            await p.sleep(1_500);
+        }
+    };
+    const key = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys/reveal`, { method: "POST", body: {}, retry: true })
+        .catch((err) => fail("Read the sandbox key", err));
+    done("Read the sandbox key", `${key.clientId}, held in memory for this run`);
+    const sk = key.secret;
+    next("Provisioning a sandbox test user");
+    const phone = testPhone(app);
+    const user = await api.request("/v1/users", {
+        method: "POST", auth: sk, idempotent: true, retry: true, body: { firstName: "Layout", lastName: "CLI test", phone },
+    }).then((r) => r.data).catch((err) => fail("Provision a test user", err));
+    done("Provision a test user", `${user.id} on ${phone}`);
+    if (user.next === "verify") {
+        next("Verifying with the sandbox code");
+        await api.request(`/v1/users/${encodeURIComponent(user.id)}/verify/start`, { method: "POST", auth: sk, idempotent: true, retry: true, body: {} })
+            .catch((err) => fail("Verify the test user", err));
+        const verified = await api.request(`/v1/users/${encodeURIComponent(user.id)}/verify`, {
+            method: "POST", auth: sk, idempotent: true, retry: true, body: { code: "000000" },
+        }).then((r) => r.data).catch((err) => fail("Verify the test user", err));
+        if (!verified.verified || verified.authorized === false)
+            fail("Verify the test user", new CliError("not_verified", "The sandbox code was not accepted.", EXIT.error));
+        done("Verify the test user", "000000 accepted");
+    }
+    else if (user.next !== "connected") {
+        fail("Provision a test user", new CliError("not_connected", `This test user needs ${user.next} first.`, EXIT.error));
+    }
+    next("Minting a build grant");
+    const grant = await api.request(`/v1/users/${encodeURIComponent(user.id)}/grant`, {
+        method: "POST", auth: sk, idempotent: true, retry: true, body: {},
+    }).then((r) => r.data).catch((err) => fail("Mint a build grant", err));
+    done("Mint a build grant", `expires ${grant.expiresAt}`);
+    next(`Building a cart at ${place}`);
+    const started = await api.request("/v1/carts", {
+        method: "POST", auth: grant.token, idempotent: true, retry: true,
+        body: { placeId: place, items: ["latte", "blueberry muffin"], idempotencyKey: `${run}-cart` },
+    }).then((r) => r.data.cart).catch((err) => fail("Build a cart", err));
+    const readCart = () => api.request(`/v1/carts/${encodeURIComponent(started.id)}`, { auth: grant.token }).then((r) => r.data.cart);
+    const cart = await until("Build a cart", readCart, (c) => c.status !== "building", 90_000);
+    if (cart.status === "failed") {
+        const code = cart.failure?.code ?? "UNKNOWN";
+        if (expected === "failed" && place === "test_place_closed") {
+            done("Build a cart", `failed with ${code}, as ${place} scripts`);
+            out.result({ app, place, steps, order: null, ok: true }, () => out.line(`Done. ${place} ended as scripted.`));
+            return EXIT.ok;
+        }
+        fail("Build a cart", new CliError("cart_failed", `The cart failed with ${code}.`, EXIT.error));
+    }
+    if (cart.status !== "ready")
+        fail("Build a cart", new CliError("cart_not_ready", `The cart is ${cart.status}, not ready.`, EXIT.error));
+    done("Build a cart", `${started.id} ready, ${money(cart.totalMinor)}`);
+    next("Confirming (simulated)");
+    const confirm = (total, attempt) => api.request(`/v1/carts/${encodeURIComponent(started.id)}/confirm`, { method: "POST", auth: grant.token, idempotent: true, retry: true, body: { expectedTotalMinor: total, idempotencyKey: `${run}-confirm-${attempt}` } }).then((r) => r.data.order);
+    let order = await confirm(cart.totalMinor, 1).catch(async (err) => {
+        if (err instanceof CliError && err.code === "price_changed") {
+            const moved = await readCart().catch((e) => fail("Confirm", e));
+            return confirm(moved.totalMinor, 2).catch((e) => fail("Confirm", e));
+        }
+        return fail("Confirm", err);
+    });
+    done("Confirm", `${order.id} ${order.status}${order.simulated ? ", simulated" : ""}`);
+    next("Waiting for the outcome");
+    const final = await until("Wait for the outcome", () => api.request(`/v1/orders/${encodeURIComponent(order.id)}`, { auth: sk }).then((r) => r.data), (o) => TERMINAL.has(o.state), 90_000);
+    order = { ...order, status: final.state };
+    const okOutcome = final.state === expected;
+    if (!okOutcome)
+        fail("Wait for the outcome", new CliError("unexpected_outcome", `The order ended ${final.state}; ${place} scripts ${expected}.`, EXIT.error));
+    done("Wait for the outcome", `${final.state}${final.failure_code ? ` (${final.failure_code})` : ""}, as ${place} scripts`);
+    out.result({ app, place, steps, order: { id: order.id, status: final.state }, ok: true }, () => out.line("Done. Nothing reached a restaurant and no money moved."));
+    return EXIT.ok;
+}

package/dist/config.js

@@ -0,0 +1,60 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { usageError } from "./errors.js";
+export const DEFAULT_API_BASE = "https://api.layout.link";
+export const DOCS_BASE = "https://developer.layout.link";
+export function apiBase(env) {
+    const raw = (env.LAYOUT_API_BASE ?? DEFAULT_API_BASE).trim().replace(/\/+$/, "");
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw usageError("LAYOUT_API_BASE is not a URL.");
+    }
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+        throw usageError("LAYOUT_API_BASE must be https, or http on localhost.");
+    }
+    return `${url.protocol}//${url.host}${url.pathname === "/" ? "" : url.pathname}`;
+}
+export function configDir(env) {
+    const xdg = env.XDG_CONFIG_HOME?.trim();
+    return join(xdg ? xdg : join(env.HOME ?? homedir(), ".config"), "layout");
+}
+export function ensurePrivateDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+export function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writePrivateJson(file, value) {
+    ensurePrivateDir(dirname(file));
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, file);
+}
+const configFile = (env) => join(configDir(env), "config.json");
+export function hostKey(base) {
+    return base.replace(/^https?:\/\//, "");
+}
+export function readSession(env, base) {
+    return readJson(configFile(env))?.sessions?.[hostKey(base)] ?? null;
+}
+export function writeSession(env, base, record) {
+    const cfg = readJson(configFile(env)) ?? {};
+    const sessions = { ...(cfg.sessions ?? {}) };
+    if (record)
+        sessions[hostKey(base)] = record;
+    else
+        delete sessions[hostKey(base)];
+    writePrivateJson(configFile(env), { ...cfg, sessions });
+}