@nextxai/cli 0.0.0-stage → 0.1.0

package/dist/commands/webhooks.js

@@ -0,0 +1,249 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { fetch } from "undici";
+import { brand } from "../core/brand.js";
+import { context } from "../core/context.js";
+import { CliError, Exit } from "../core/errors.js";
+import { currentLang, tr } from "../core/i18n.js";
+import { c, emit, info, json, ok, table, warn } from "../core/output.js";
+import { get, post, del, requestRaw, errorFor } from "../core/http.js";
+import { confirm, hasTty } from "../core/prompt.js";
+const when = (iso) => (iso ? iso.slice(0, 19).replace("T", " ") : "");
+export async function eventTypes() {
+    return get("/webhook/public/event-types", { anonymous: true });
+}
+/** Checks both the NextX header (sha256=HMAC(ts.body)) and Standard Webhooks (v1,base64 HMAC(id.ts.body)). */
+export function verifySignature(secret, body, headers, toleranceSec = 300) {
+    const h = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+    const eq = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+    const ts = h["x-nextx-timestamp"] ?? h["webhook-timestamp"];
+    if (ts && Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec)
+        return { ok: false, reason: tr("dấu thời gian quá cũ", "timestamp too old") };
+    if (h["x-nextx-signature-256"] && ts) {
+        const expected = "sha256=" + createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
+        const got = [h["x-nextx-signature-256"], h["x-nextx-signature-256-previous"]].filter(Boolean);
+        if (got.some((g) => eq(g, expected)))
+            return { ok: true, scheme: "Signature-256" };
+    }
+    if (h["webhook-signature"] && h["webhook-id"] && ts) {
+        const key = secret.startsWith("whsec_") ? Buffer.from(secret.slice(6), "base64") : Buffer.from(secret);
+        const expected = createHmac("sha256", key).update(`${h["webhook-id"]}.${ts}.${body}`).digest("base64");
+        if (h["webhook-signature"].split(" ").some((s) => eq(s.replace(/^v1,/, ""), expected)))
+            return { ok: true, scheme: "webhook-signature" };
+    }
+    return { ok: false, reason: tr("chữ ký không khớp", "signature mismatch") };
+}
+async function findEndpoint(id) {
+    const e = (await get("/webhook/endpoints")).find((x) => x.id.startsWith(id) || x.url === id);
+    if (!e)
+        throw new CliError(tr("Không thấy endpoint này.", "Endpoint not found."), Exit.notFound);
+    return e;
+}
+export function registerWebhooks(program) {
+    const wh = program.command("webhooks").alias("webhook").description(tr("sự kiện webhook: xem, bắn thử, nghe về máy", "webhook events: browse, trigger, listen locally"));
+    wh.command("events").description(tr("danh sách sự kiện", "list events")).option("--module <m>")
+        .action(async (o) => {
+        let list = await eventTypes();
+        if (o.module)
+            list = list.filter((e) => e.service.toLowerCase() === o.module.toLowerCase());
+        emit(list, () => info(table([tr("Sự kiện", "Event"), tr("Phân hệ", "Module"), tr("Mô tả", "Description"), tr("Gói", "Plan")], list.map((e) => [e.event, e.service, (currentLang() === "en" ? e.descriptionEn ?? e.title : e.title), e.planRequired ?? ""]))));
+    });
+    wh.command("schema <event>").description(tr("schema và ví dụ payload", "payload schema and example"))
+        .action(async (event) => {
+        const e = (await eventTypes()).find((x) => x.event === event);
+        if (!e)
+            throw new CliError(tr("Không có sự kiện này.", "No such event."), Exit.notFound, `${brand().bin} webhooks events`);
+        emit(e, () => {
+            info(`${c.bold(e.event)} — ${e.title}`);
+            if (e.description)
+                info(currentLang() === "en" ? e.descriptionEn ?? e.description : e.description);
+            info(c.dim(tr("\nVí dụ:", "\nExample:")));
+            json(e.example);
+        });
+    });
+    const ep = wh.command("endpoints").description(tr("endpoint nhận webhook của workspace", "your webhook endpoints"));
+    ep.command("list", { isDefault: true }).action(async () => {
+        const list = await get("/webhook/endpoints");
+        emit(list, () => info(table(["ID", "URL", tr("Sự kiện", "Events"), tr("Trạng thái", "Status"), tr("Lỗi liên tiếp", "Failures")], list.map((e) => [e.id.slice(0, 8), e.url, e.events.length > 3 ? `${e.events.slice(0, 3).join(", ")} +${e.events.length - 3}` : e.events.join(", "), e.isActive ? c.green(e.status) : c.dim(e.status), e.consecutiveFailures || ""]))));
+    });
+    ep.command("create <url>")
+        .requiredOption("--events <list>", tr("sự kiện, phẩy ngăn cách", "events, comma separated"))
+        .option("--description <text>")
+        .action(async (url, o) => {
+        const events = o.events.split(",").map((s) => s.trim()).filter(Boolean);
+        const types = await eventTypes();
+        const services = [...new Set(events.map((e) => types.find((t) => t.event === e)?.service).filter(Boolean))];
+        if (services.length !== 1)
+            throw new CliError(tr("Mỗi endpoint nhận sự kiện của MỘT phân hệ.", "Each endpoint receives events of ONE module."), Exit.usage);
+        const r = await post("/webhook/endpoints", { url, description: o.description, events, service: services[0] });
+        emit(r, () => {
+            ok(tr("Đã tạo endpoint.", "Endpoint created."));
+            if (r.secret)
+                info(`  ${tr("Khoá ký", "Signing secret")}: ${c.bold(String(r.secret))} ${c.dim(tr("(chỉ hiện một lần)", "(shown once)"))}`);
+        });
+    });
+    ep.command("delete <id>").action(async (id) => {
+        const e = await findEndpoint(id);
+        if (hasTty() && !(await confirm(tr(`Xoá endpoint ${e.url}?`, `Delete endpoint ${e.url}?`))))
+            return;
+        await del(`/webhook/endpoints/${e.id}`);
+        ok(tr("Đã xoá.", "Deleted."));
+    });
+    ep.command("rotate-secret <id>").description(tr("đổi khoá ký (khoá cũ còn hiệu lực một thời gian)", "rotate the signing secret (old one stays valid for a while)"))
+        .action(async (id) => {
+        const e = await findEndpoint(id);
+        const r = await post(`/webhook/endpoints/${e.id}/rotate-secret`, {});
+        emit(r, () => ok(`${tr("Khoá ký mới", "New secret")}: ${c.bold(String(r.secret ?? ""))}`));
+    });
+    wh.command("trigger <event>").description(tr("bắn một sự kiện mẫu tới endpoint", "send a sample event to an endpoint"))
+        .option("--endpoint <id>", tr("endpoint đích (mặc định: endpoint đầu tiên nhận sự kiện này)", "target endpoint (default: first one subscribed)"))
+        .action(async (event, o) => {
+        const list = await get("/webhook/endpoints");
+        const target = o.endpoint ? await findEndpoint(o.endpoint) : list.find((e) => e.events.includes(event));
+        if (!target)
+            throw new CliError(tr("Chưa có endpoint nào nhận sự kiện này.", "No endpoint subscribes to this event."), Exit.notFound, tr(`Dùng \`${brand().bin} webhooks listen --events ${event}\` để nghe về máy.`, `Use \`${brand().bin} webhooks listen --events ${event}\` to receive it locally.`));
+        const r = await post(`/webhook/endpoints/${target.id}/test`, { eventType: event });
+        emit(r, () => ok(tr(`Đã gửi ${event} → ${target.url}`, `Sent ${event} → ${target.url}`) + (r.responseStatus ? ` · HTTP ${r.responseStatus}` : "")));
+    });
+    wh.command("deliveries").description(tr("lượt giao gần đây", "recent deliveries"))
+        .option("--status <s>", "success | failed | pending")
+        .option("--endpoint <id>")
+        .option("--limit <n>", "", "30")
+        .action(async (o) => {
+        const path = o.endpoint ? `/webhook/endpoints/${(await findEndpoint(o.endpoint)).id}/deliveries` : "/webhook/deliveries";
+        const r = await get(path, { query: { status: o.status, pageSize: o.limit } });
+        const list = Array.isArray(r) ? r : r.items;
+        emit(list, () => info(table(["ID", tr("Sự kiện", "Event"), tr("Kết quả", "Result"), "HTTP", "ms", tr("Thử lại", "Retries"), tr("Lúc", "At")], list.map((d) => [
+            d.id.slice(0, 8), d.eventType, d.status === "success" ? c.green(d.status) : d.status === "failed" ? c.red(d.status) : d.status, d.responseStatus ?? "", d.durationMs ?? "", `${d.retryCount}/${d.maxRetries}`, when(d.createdAt),
+        ]))));
+    });
+    wh.command("retry <deliveryId>").description(tr("gửi lại một lượt giao", "retry a delivery")).action(async (id) => {
+        const full = id.length >= 32 ? id : (await get("/webhook/deliveries", { query: { pageSize: 100 } }).then((r) => (Array.isArray(r) ? r : r.items).find((d) => d.id.startsWith(id))?.id));
+        if (!full)
+            throw new CliError(tr("Không thấy lượt giao này.", "Delivery not found."), Exit.notFound);
+        const r = await post(`/webhook/deliveries/${full}/retry`, {});
+        emit(r, () => ok(tr("Đã xếp gửi lại.", "Retry queued.")));
+    });
+    wh.command("verify").description(tr("kiểm chữ ký webhook tại máy (không gọi máy chủ)", "verify a webhook signature locally (no server call)"))
+        .requiredOption("--secret <secret>")
+        .requiredOption("--payload <file>", tr("thân thô đã nhận (- = stdin)", "raw received body (- = stdin)"))
+        .option("-H, --header <K: V>", tr("header đã nhận (lặp được)", "received header (repeatable)"), (v, p = []) => [...p, v])
+        .option("--signature <sig>", tr("chữ ký trong header *-Signature-256", "signature from the *-Signature-256 header"))
+        .option("--timestamp <ts>", tr("dấu thời gian trong header *-Timestamp", "timestamp from the *-Timestamp header"))
+        .action((o) => {
+        const body = readFileSync(o.payload === "-" ? 0 : o.payload, "utf8");
+        const headers = {};
+        for (const h of o.header ?? []) {
+            const i = h.indexOf(":");
+            if (i > 0)
+                headers[h.slice(0, i).trim()] = h.slice(i + 1).trim();
+        }
+        if (o.signature)
+            headers["x-nextx-signature-256"] = o.signature;
+        if (o.timestamp)
+            headers["x-nextx-timestamp"] = o.timestamp;
+        const r = verifySignature(o.secret, body, headers);
+        emit(r, () => (r.ok ? ok(tr(`Chữ ký hợp lệ (${r.scheme})`, `Valid signature (${r.scheme})`)) : warn(tr(`Không hợp lệ: ${r.reason}`, `Invalid: ${r.reason}`))));
+        if (!r.ok)
+            process.exitCode = Exit.general;
+    });
+    wh.command("listen")
+        .description(tr("nhận sự kiện thật về máy và chuyển tới địa chỉ local", "receive real events on this machine and forward them locally"))
+        .option("--forward-to <url>", tr("vd localhost:3000/hook", "e.g. localhost:3000/hook"))
+        .option("--events <list>", tr("sự kiện, phẩy ngăn cách (mặc định: tất cả)", "events, comma separated (default: all)"))
+        .option("--print-secret", tr("in đủ khoá ký", "print the full signing secret"))
+        .option("--print-json", tr("in thân sự kiện", "print event bodies"))
+        .action(async (o) => listen(o));
+}
+/**
+ * Dev listen protocol (webhook service, permission webhook.endpoints.manage):
+ *   GET /api/v1/webhook/dev-listen?events=a,b   (SSE)
+ *       data: {"type":"ready","listenerId","secret","idleTimeoutSec","events"}
+ *       data: {"type":"delivery","deliveryId","eventType","headers":{…},"body":"<raw>"}
+ *       ": ping" comments every 15 s
+ * Best effort: no delivery records, no retries. The listener expires idleTimeoutSec after the stream closes.
+ */
+async function listen(o) {
+    const target = o.forwardTo ? (/^https?:\/\//.test(o.forwardTo) ? o.forwardTo : `http://${o.forwardTo}`) : undefined;
+    if (target && !["localhost", "127.0.0.1", "[::1]"].includes(new URL(target).hostname))
+        throw new CliError(tr("--forward-to chỉ nhận địa chỉ trên máy này (localhost).", "--forward-to only accepts local addresses (localhost)."), Exit.usage);
+    if (context().env === "prod")
+        warn(c.red(tr("PROD: dữ liệu thật của khách sẽ chảy về máy này.", "PROD: real customer data will flow to this machine.")));
+    const stop = new AbortController();
+    process.once("SIGINT", () => stop.abort());
+    let backoff = 1000;
+    while (!stop.signal.aborted) {
+        let res;
+        try {
+            res = await requestRaw("GET", "/webhook/dev-listen", { query: { events: o.events }, signal: stop.signal, headers: { Accept: "text/event-stream" } });
+        }
+        catch (e) {
+            if (stop.signal.aborted)
+                break;
+            warn(tr(`Mất kết nối, thử lại sau ${backoff / 1000}s…`, `Disconnected, retrying in ${backoff / 1000}s…`));
+            await new Promise((r) => setTimeout(r, backoff));
+            backoff = Math.min(backoff * 2, 30_000);
+            void e;
+            continue;
+        }
+        if (res.status === 404)
+            throw new CliError(tr("Máy chủ chưa hỗ trợ nghe webhook về máy.", "The server does not support local webhook listening yet."), Exit.general);
+        if (!res.ok)
+            throw errorFor(res.status, await res.json().catch(() => undefined), res);
+        backoff = 1000;
+        const decoder = new TextDecoder();
+        let buf = "";
+        try {
+            for await (const part of res.body) {
+                buf += decoder.decode(part, { stream: true });
+                let idx;
+                while ((idx = buf.indexOf("\n\n")) >= 0) {
+                    const frame = buf.slice(0, idx);
+                    buf = buf.slice(idx + 2);
+                    const data = frame.split("\n").filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trimStart()).join("\n");
+                    if (!data)
+                        continue;
+                    const msg = JSON.parse(data);
+                    if (msg.type === "ready") {
+                        const sec = msg.secret ?? "";
+                        ok(tr(`Đang nghe trên ${c.bold(context().env)} · khoá ký ${c.yellow(o.printSecret ? sec : `${sec.slice(0, 6)}…${sec.slice(-3)}`)}`, `Listening on ${c.bold(context().env)} · signing secret ${c.yellow(o.printSecret ? sec : `${sec.slice(0, 6)}…${sec.slice(-3)}`)}`));
+                        info(c.dim(tr("  Ctrl+C dừng · sự kiện thật của workspace, đã ký như lượt giao thật", "  Ctrl+C to stop · real workspace events, signed like real deliveries")));
+                        continue;
+                    }
+                    if (msg.type !== "delivery")
+                        continue;
+                    const at = new Date().toTimeString().slice(0, 8);
+                    if (o.printJson)
+                        info(msg.body ?? "");
+                    if (!target) {
+                        info(`  ${at}  ${(msg.eventType ?? "").padEnd(22)} ${c.dim(msg.deliveryId?.slice(0, 12) ?? "")}`);
+                        if (o.printJson)
+                            continue;
+                        continue;
+                    }
+                    const started = Date.now();
+                    let status = 0;
+                    let respBody = "";
+                    try {
+                        const r = await fetch(target, { method: "POST", headers: { "Content-Type": "application/json", ...msg.headers }, body: msg.body });
+                        status = r.status;
+                        respBody = (await r.text()).slice(0, 2000);
+                    }
+                    catch (e) {
+                        respBody = String(e.message);
+                    }
+                    const ms = Date.now() - started;
+                    const code = status ? (status < 300 ? c.green(String(status)) : c.red(String(status))) : c.red(tr("lỗi", "error"));
+                    info(`  ${at}  ${(msg.eventType ?? "").padEnd(22)} → ${code} ${String(ms).padStart(4)}ms  ${c.dim(msg.deliveryId?.slice(0, 12) ?? "")}`);
+                    if (status >= 300 && respBody)
+                        info(c.dim(`      ${respBody.slice(0, 200).replace(/\s+/g, " ")}`));
+                }
+            }
+        }
+        catch (e) {
+            if (stop.signal.aborted)
+                break;
+            void e;
+        }
+    }
+}

package/dist/commands/workspace.js

@@ -0,0 +1,44 @@
+import { context } from "../core/context.js";
+import { CliError, Exit } from "../core/errors.js";
+import { tr } from "../core/i18n.js";
+import { c, emit, info, ok, table } from "../core/output.js";
+import { getProfile } from "../core/config.js";
+import { hasTty, select } from "../core/prompt.js";
+import { findWorkspace, listWorkspaces, requirePerson, switchWorkspace } from "../auth/session.js";
+export async function pickWorkspace(key) {
+    await requirePerson();
+    const list = await listWorkspaces();
+    if (key) {
+        const w = findWorkspace(list, key);
+        if (!w)
+            throw new CliError(tr(`Không thấy workspace "${key}".`, `Workspace "${key}" not found.`), Exit.notFound, tr("Xem danh sách: workspace list", "See: workspace list"));
+        return w;
+    }
+    if (!hasTty())
+        throw new CliError(tr("Cần mã workspace khi không có terminal.", "Pass a workspace code without a terminal."), Exit.usage);
+    const cur = getProfile(context().profile)?.workspaceId;
+    const w = await select(tr("Chọn workspace:", "Choose a workspace:"), list.map((x) => ({ label: x.name, hint: [x.code, x.primaryGroupName, x.id === cur ? tr("đang dùng", "current") : ""].filter(Boolean).join(" · "), value: x })), Math.max(0, list.findIndex((x) => x.id === cur)));
+    if (!w)
+        throw new CliError(tr("Đã huỷ.", "Cancelled."), Exit.interrupted);
+    return w;
+}
+export function registerWorkspace(program) {
+    const ws = program.command("workspace").alias("ws").description(tr("các workspace (công ty) của bạn", "your workspaces (companies)"));
+    ws.command("list", { isDefault: true })
+        .description(tr("danh sách workspace", "list workspaces"))
+        .action(async () => {
+        await requirePerson();
+        const list = await listWorkspaces();
+        const cur = getProfile(context().profile)?.workspaceId;
+        emit(list.map((w) => ({ ...w, current: w.id === cur })), () => info(table(["", tr("Tên", "Name"), tr("Mã", "Code"), tr("Vai trò", "Role"), tr("Trạng thái", "Status")], list.map((w) => [
+            w.id === cur ? c.green("●") : "", w.name, w.code, w.primaryGroupName ?? "", w.status ?? "",
+        ]))));
+    });
+    ws.command("use [code]")
+        .description(tr("đổi workspace đang làm việc (lưu vào hồ sơ)", "switch the working workspace (saved in the profile)"))
+        .action(async (code) => {
+        const w = await pickWorkspace(code);
+        await switchWorkspace(w);
+        emit({ workspace: w }, () => ok(tr(`Đang làm việc trên ${c.bold(w.name)}`, `Now working on ${c.bold(w.name)}`)));
+    });
+}

package/dist/core/brand.js

@@ -0,0 +1,51 @@
+// One codebase, several branded binaries. The entry file (src/bin/<brand>.ts) picks the brand before
+// anything else is imported; every user-facing name, host and storage location comes from here.
+// <brand:nextx>
+const NEXTX = {
+    id: "nextx",
+    bin: "nextx",
+    name: "NextX",
+    aiName: "NextX AI",
+    pkg: "@nextxai/cli",
+    clientId: "nextx-cli",
+    envPrefix: "NEXTX",
+    mobileApp: "NextX",
+    modules: null,
+    env: {
+        prod: {
+            api: "https://api.nextx.vn",
+            auth: "https://auth.nextx.vn",
+            mcp: "https://mcp.nextx.vn/mcp",
+            app: "https://app.nextx.vn",
+            docs: "https://developers.nextx.vn",
+            id: "https://id.nextx.vn",
+        },
+        sandbox: {
+            api: "https://api-dev.nextx.vn",
+            auth: "https://auth-dev.nextx.vn",
+            mcp: "https://mcp-dev.nextx.vn/mcp",
+            app: "https://app-dev.nextx.vn",
+            docs: "https://developers-dev.nextx.vn",
+            id: "https://id-dev.nextx.vn",
+        },
+    },
+};
+// </brand:nextx>
+// Exported trees keep only their own brand (scripts/export.sh strips the other block and its line here).
+const BRANDS = {
+    nextx: NEXTX, // <brand-line:nextx>
+};
+let current = Object.values(BRANDS)[0];
+export function setBrand(id) {
+    const b = BRANDS[id];
+    if (b)
+        current = b;
+}
+export function brand() {
+    return current;
+}
+/** Reads `<PREFIX>_<name>` from the environment, e.g. envVar("API_KEY") → NEXTX_API_KEY. */
+export function envVar(name) {
+    const v = process.env[`${current.envPrefix}_${name}`];
+    return v === undefined || v === "" ? undefined : v;
+}

package/dist/core/config.js

@@ -0,0 +1,52 @@
+// ~/.config/<bin>/config.toml — preferences and profiles. Never holds tokens or keys (see credentials.ts).
+import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { parse, stringify } from "smol-toml";
+import { configFile } from "./paths.js";
+import { envVar } from "./brand.js";
+const EMPTY = { defaultProfile: "default", profiles: {} };
+export function loadConfig() {
+    const f = configFile();
+    if (!existsSync(f))
+        return structuredClone(EMPTY);
+    const raw = parse(readFileSync(f, "utf8"));
+    return { ...structuredClone(EMPTY), ...raw, profiles: (raw.profiles ?? {}) };
+}
+export function saveConfig(c) {
+    const f = configFile();
+    const tmp = `${f}.tmp`;
+    writeFileSync(tmp, stringify(c), { mode: 0o600 });
+    renameSync(tmp, f);
+}
+/** Profile chosen by --profile, then <PREFIX>_PROFILE, then the configured default. */
+export function profileName(flag) {
+    return flag ?? envVar("PROFILE") ?? loadConfig().defaultProfile;
+}
+export function getProfile(name) {
+    return loadConfig().profiles[name];
+}
+export function updateProfile(name, patch) {
+    const c = loadConfig();
+    const next = { env: "prod", ...c.profiles[name], ...patch };
+    c.profiles[name] = next;
+    saveConfig(c);
+    return next;
+}
+export function removeProfile(name) {
+    const c = loadConfig();
+    delete c.profiles[name];
+    saveConfig(c);
+}
+/** Dotted keys settable with `config set`. */
+export const SETTABLE = {
+    lang: (v) => (v === "en" ? "en" : "vi"),
+    mode: (v) => {
+        if (v !== "read" && v !== "propose" && v !== "auto")
+            throw new Error("mode: read | propose | auto");
+        return v;
+    },
+    updateChannel: (v) => (v === "next" ? "next" : "latest"),
+    updateCheck: (v) => v !== "false" && v !== "0",
+    telemetry: (v) => v !== "false" && v !== "0",
+    color: (v) => v !== "false" && v !== "0",
+    defaultProfile: (v) => v,
+};

package/dist/core/context.js

@@ -0,0 +1,42 @@
+// Options shared by every command, resolved once from global flags + environment + config.
+import { brand, envVar } from "./brand.js";
+import { getProfile, loadConfig, profileName } from "./config.js";
+let ctx;
+export function initContext(flags) {
+    const profile = profileName(flags.profile);
+    const p = getProfile(profile);
+    const envFromVar = envVar("ENV");
+    const env = flags.sandbox || envFromVar === "sandbox" ? "sandbox" : envFromVar === "prod" ? "prod" : (p?.env ?? "prod");
+    const cfg = loadConfig();
+    ctx = {
+        profile,
+        env,
+        endpoints: overrideEndpoints(brand().env[env]),
+        workspace: flags.workspace ?? envVar("WORKSPACE"),
+        agent: flags.agent ?? p?.agent,
+        mode: flags.mode ?? cfg.mode ?? "propose",
+        debug: flags.debug === true || envVar("DEBUG") === "1",
+        verbose: flags.verbose === true,
+        interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+    };
+    return ctx;
+}
+/** <PREFIX>_API_URL etc. let us point a build at a local stack; never documented for customers. */
+function overrideEndpoints(e) {
+    return {
+        api: envVar("API_URL") ?? e.api,
+        auth: envVar("AUTH_URL") ?? e.auth,
+        mcp: envVar("MCP_URL") ?? e.mcp,
+        app: envVar("APP_URL") ?? e.app,
+        docs: envVar("DOCS_URL") ?? e.docs,
+        id: envVar("ID_URL") ?? e.id,
+    };
+}
+export function context() {
+    if (!ctx)
+        return initContext({});
+    return ctx;
+}
+export function setContext(patch) {
+    ctx = { ...context(), ...patch };
+}

package/dist/core/errors.js

@@ -0,0 +1,28 @@
+// Exit codes are part of the public contract (docs: /docs/cli#exit-codes). Do not renumber.
+export const Exit = {
+    ok: 0,
+    general: 1,
+    usage: 2,
+    auth: 3,
+    forbidden: 4,
+    quota: 5,
+    network: 6,
+    notConfirmed: 7,
+    notFound: 8,
+    interrupted: 130,
+};
+export class CliError extends Error {
+    exitCode;
+    hint;
+    requestId;
+    constructor(message, exitCode = Exit.general, hint, requestId) {
+        super(message);
+        this.exitCode = exitCode;
+        this.hint = hint;
+        this.requestId = requestId;
+        this.name = "CliError";
+    }
+}
+export function isCliError(e) {
+    return e instanceof CliError;
+}

package/dist/core/http.js

@@ -0,0 +1,170 @@
+// Every call to the platform goes through here: identity headers, retry on expired token, error → exit code.
+import { randomUUID } from "node:crypto";
+import { arch, platform } from "node:os";
+import { fetch, EnvHttpProxyAgent, setGlobalDispatcher } from "undici";
+import { brand } from "./brand.js";
+import { context } from "./context.js";
+import { CliError, Exit } from "./errors.js";
+import { t, currentLang } from "./i18n.js";
+import { VERSION } from "./version.js";
+import { currentAuth, refreshSession } from "../auth/session.js";
+setGlobalDispatcher(new EnvHttpProxyAgent());
+export const userAgent = () => `${brand().bin}-cli/${VERSION} (${platform()}; ${arch()}; node ${process.versions.node})`;
+export function apiPath(path) {
+    if (/^https?:\/\//.test(path))
+        return path;
+    const p = path.startsWith("/") ? path : `/${path}`;
+    return p.startsWith("/api/") ? p : `/api/v1${p}`;
+}
+function buildUrl(path, opts) {
+    const base = opts.baseUrl ?? context().endpoints.api;
+    const url = new URL(/^https?:\/\//.test(path) ? path : base + (opts.baseUrl ? path : apiPath(path)));
+    for (const [k, v] of Object.entries(opts.query ?? {}))
+        if (v !== undefined)
+            url.searchParams.set(k, String(v));
+    return url.toString();
+}
+function authHeaders(auth) {
+    if (!auth)
+        return {};
+    if (auth.kind === "apiKey")
+        return { "X-Api-Key": auth.key };
+    return { Authorization: `Bearer ${auth.token}` };
+}
+function debug(line) {
+    if (context().debug)
+        process.stderr.write(`\u001b[2m[debug] ${line}\u001b[22m\n`);
+}
+async function send(method, url, opts, auth) {
+    const headers = {
+        "User-Agent": userAgent(),
+        "X-Client-Type": "cli",
+        "Accept-Language": currentLang(),
+        Accept: "application/json, text/event-stream",
+        ...(opts.bearer ? { Authorization: `Bearer ${opts.bearer}` } : opts.anonymous ? {} : authHeaders(auth)),
+        ...opts.headers,
+    };
+    let body;
+    if (opts.body !== undefined) {
+        if (typeof opts.body === "string")
+            body = opts.body;
+        else {
+            body = JSON.stringify(opts.body);
+            headers["Content-Type"] ??= "application/json";
+        }
+    }
+    if (opts.idempotencyKey)
+        headers["Idempotency-Key"] = opts.idempotencyKey === true ? randomUUID() : opts.idempotencyKey;
+    const started = Date.now();
+    try {
+        const res = await fetch(url, { method, headers, body, signal: opts.signal });
+        debug(`${method} ${url.replace(/([?&](token|key)=)[^&]+/gi, "$1…")} → ${res.status} ${Date.now() - started}ms rid=${res.headers.get("x-request-id") ?? "-"}`);
+        return res;
+    }
+    catch (e) {
+        throw networkError(e, url);
+    }
+}
+export function networkError(e, url) {
+    if (e?.name === "AbortError")
+        return new CliError(t("interrupted"), Exit.interrupted);
+    const cause = e?.cause?.code ?? e?.code ?? "";
+    if (/CERT|SSL|TLS|SELF_SIGNED|UNABLE_TO_VERIFY/i.test(cause))
+        return new CliError(t("net.tls"), Exit.network, t("net.tls.hint"));
+    return new CliError(t("net.failed", { host: new URL(url).host }) + (cause ? ` (${cause})` : ""), Exit.network, t("net.failed.hint"));
+}
+async function readBody(res) {
+    const text = await res.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** Human message from ProblemDetails / {code,message} / plain text bodies. */
+export function serverMessage(body) {
+    if (!body || typeof body !== "object")
+        return { message: typeof body === "string" ? body.slice(0, 300) : undefined };
+    const b = body;
+    // ProblemDetails: errors is either a list of messages or { field: [messages] }.
+    const errors = Array.isArray(b.errors)
+        ? b.errors.map(String).join("; ")
+        : b.errors && typeof b.errors === "object"
+            ? Object.entries(b.errors).map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(", ") : String(v)}`).join("; ")
+            : undefined;
+    const code = (b.code ?? b.errorCode ?? b.error ?? b.type);
+    const generic = typeof b.title === "string" && /validation errors occurred/i.test(b.title);
+    const message = (b.message ?? b.detail ?? b.error_description ?? (generic && errors ? errors : (b.title ?? errors)));
+    return { code: typeof code === "string" ? code : undefined, message: typeof message === "string" ? message : undefined };
+}
+export function errorFor(status, body, res) {
+    const { code, message } = serverMessage(body);
+    const rid = (res.headers.get("x-request-id") ?? res.headers.get("x-correlation-id") ?? body?.traceId ?? undefined)?.split(",")[0]?.trim();
+    const minVersion = res.headers.get("x-min-cli-version");
+    if (status === 426 || (minVersion && isOlder(VERSION, minVersion)))
+        return new CliError(t("http.tooOld", { cur: VERSION, min: minVersion ?? "?" }), Exit.general, t("http.tooOld.hint"));
+    if (status === 401) {
+        if (code && /revoked|blacklist/i.test(code))
+            return new CliError(t("auth.revoked"), Exit.auth, t("auth.expired.hint"));
+        return new CliError(message ?? t("auth.expired"), Exit.auth, t("auth.expired.hint"));
+    }
+    if (status === 403)
+        return new CliError(message ?? t("http.forbidden"), Exit.forbidden, undefined, rid);
+    if (status === 404)
+        return new CliError(message ?? t("http.notFound"), Exit.notFound, undefined, rid);
+    if (status === 429) {
+        const sec = Number(res.headers.get("retry-after") ?? body?.retryAfterSeconds ?? 0);
+        return new CliError(message ?? t("http.rateLimited", { sec }), Exit.quota, undefined, rid);
+    }
+    if (status >= 500)
+        return new CliError(t("http.server", { rid: rid ?? "-" }), Exit.general, t("http.server.hint"), rid);
+    return new CliError(message ?? `HTTP ${status}${code ? ` ${code}` : ""}`, status === 409 || status === 410 ? Exit.notConfirmed : Exit.general, undefined, rid);
+}
+export function isOlder(a, b) {
+    const pa = a.split(/[.-]/).map((x) => parseInt(x, 10) || 0);
+    const pb = b.split(/[.-]/).map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < 3; i++)
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) < (pb[i] ?? 0);
+    return false;
+}
+/** Raw response with the shared identity + one refresh-and-retry on 401. */
+export async function requestRaw(method, path, opts = {}) {
+    const url = buildUrl(path, opts);
+    const auth = opts.anonymous || opts.bearer ? undefined : await currentAuth();
+    let res = await send(method, url, opts, auth);
+    if (res.status === 401 && auth?.kind === "session") {
+        await res.body?.cancel();
+        const fresh = await refreshSession(auth.token);
+        res = await send(method, url, opts, fresh);
+    }
+    return res;
+}
+export async function request(method, path, opts = {}) {
+    let res = await requestRaw(method, path, opts);
+    // Short rate limits are waited out once; long ones surface to the user.
+    if (res.status === 429 && !opts.allow?.includes(429)) {
+        const sec = Number(res.headers.get("retry-after") ?? 0);
+        if (sec > 0 && sec <= 30) {
+            await res.body?.cancel();
+            process.stderr.write(`${t("http.rateLimited", { sec })}\n`);
+            await new Promise((r) => setTimeout(r, sec * 1000));
+            res = await requestRaw(method, path, opts);
+        }
+    }
+    const requestId = res.headers.get("x-request-id") ?? undefined;
+    if (opts.raw)
+        return { status: res.status, data: res, headers: res.headers, requestId };
+    const data = await readBody(res);
+    if (!res.ok && !opts.allow?.includes(res.status))
+        throw errorFor(res.status, data, res);
+    return { status: res.status, data: data, headers: res.headers, requestId };
+}
+export const get = (path, opts) => request("GET", path, opts).then((r) => r.data);
+export const post = (path, body, opts) => request("POST", path, { ...opts, body }).then((r) => r.data);
+export const put = (path, body, opts) => request("PUT", path, { ...opts, body }).then((r) => r.data);
+export const patch = (path, body, opts) => request("PATCH", path, { ...opts, body }).then((r) => r.data);
+export const del = (path, opts) => request("DELETE", path, opts).then((r) => r.data);