@ai21/gateway 0.5.3

package/dist/config.d.ts

@@ -0,0 +1,76 @@
+import { type Client, type Target } from "./args.js";
+/** The `env` keys this tool owns. Anything else in the file is not ours. */
+export declare const MANAGED_KEYS: readonly ["ANTHROPIC_BASE_URL", "ANTHROPIC_CUSTOM_HEADERS", "ENABLE_TOOL_SEARCH"];
+/** Injected rather than read from the process, so tests can use a temp directory. */
+export interface PathContext {
+    readonly cwd: string;
+    readonly home: string;
+}
+export interface ConfigPaths {
+    readonly settings: string;
+    readonly backup: string;
+}
+/**
+ * Whether this file is *ours*, judged by a marker rather than by key names. Key names
+ * cannot tell our `ENABLE_TOOL_SEARCH` from one the developer set, so a hand-added key
+ * would be deleted by the next `uninstall`. Only this tool writes an `x-ai21-key`.
+ */
+export declare function isOurConfig(env: Record<string, unknown> | undefined): boolean;
+/**
+ * `--user` targets the home directory, `--repo` (the default) the project. A
+ * literal `~` is never expanded, so a directory named `~` is treated as one.
+ */
+export declare function resolvePaths(target: Target, ctx: PathContext, client?: Client): ConfigPaths;
+export interface Conflict {
+    readonly key: string;
+    readonly current: string;
+    readonly desired: string;
+}
+export type ConfigOutcome = {
+    readonly kind: "created";
+    readonly path: string;
+} | {
+    readonly kind: "updated";
+    readonly path: string;
+    readonly backup: string;
+    readonly changed: readonly string[];
+} | {
+    readonly kind: "unchanged";
+    readonly path: string;
+} | {
+    readonly kind: "conflict";
+    readonly path: string;
+    readonly conflicts: readonly Conflict[];
+} | {
+    readonly kind: "malformed";
+    readonly path: string;
+    readonly reason: string;
+} | {
+    readonly kind: "failed";
+    readonly path: string;
+    readonly reason: string;
+};
+/**
+ * Turns an fs error into something safe to print. The code is translated rather
+ * than forwarded so no stack frame, errno struct or internal path escapes.
+ */
+export declare function describeFsError(err: unknown): string;
+type JsonObject = Record<string, unknown>;
+export declare function isPlainObject(value: unknown): value is JsonObject;
+/**
+ * Write via a sibling temp file and rename. The rename is atomic within a
+ * filesystem, so a reader either sees the old file or the new one — never a
+ * half-written config. The temp file is removed on any failure so a crashed run
+ * leaves no litter next to the real file.
+ */
+export declare function atomicWrite(target: string, contents: string): void;
+export declare function serialize(settings: JsonObject): string;
+/**
+ * Merge `desiredEnv` into `paths.settings`. Returns what happened rather than
+ * throwing, so the caller owns reporting and the exit code. Nothing is written on
+ * the `conflict` or `malformed` outcomes.
+ */
+export declare function writeConfig(paths: ConfigPaths, desiredEnv: Record<string, string>, options?: {
+    readonly force: boolean;
+}): ConfigOutcome;
+export {};

package/dist/config.js

@@ -0,0 +1,187 @@
+/**
+ * Reading, merging and writing `settings.json`.
+ *
+ * The governing constraint: this edits a file a developer owns and did not create
+ * for us. Every path leaves it byte-identical or replaces it atomically with a
+ * backup alongside, and no refusal path touches it at all.
+ *
+ * Four helpers are exported for `revert.ts`, which upholds the same guarantees on
+ * the way back out — a second atomic write is a second chance to get it wrong.
+ */
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { DEFAULT_CLIENT } from "./args.js";
+/** The `env` keys this tool owns. Anything else in the file is not ours. */
+export const MANAGED_KEYS = ["ANTHROPIC_BASE_URL", "ANTHROPIC_CUSTOM_HEADERS", "ENABLE_TOOL_SEARCH"];
+/* Where each client's config lives, relative to whichever root the target selects.
+ * A second client needs more than a row here — MANAGED_KEYS and the snippet builders
+ * are Claude Code's env shape — but this is the fork the rest of the code reads. */
+const CLIENT_CONFIG = {
+    "claude-code": { dir: ".claude", file: "settings.json" },
+};
+/**
+ * Whether this file is *ours*, judged by a marker rather than by key names. Key names
+ * cannot tell our `ENABLE_TOOL_SEARCH` from one the developer set, so a hand-added key
+ * would be deleted by the next `uninstall`. Only this tool writes an `x-ai21-key`.
+ */
+export function isOurConfig(env) {
+    const headers = env?.ANTHROPIC_CUSTOM_HEADERS;
+    return typeof headers === "string" && /^\s*x-ai21-key\s*:\s*\S/im.test(headers);
+}
+/**
+ * `--user` targets the home directory, `--repo` (the default) the project. A
+ * literal `~` is never expanded, so a directory named `~` is treated as one.
+ */
+export function resolvePaths(target, ctx, client = DEFAULT_CLIENT) {
+    const { dir, file } = CLIENT_CONFIG[client];
+    const settings = join(target === "user" ? ctx.home : ctx.cwd, dir, file);
+    return { settings, backup: `${settings}.bak` };
+}
+/**
+ * Turns an fs error into something safe to print. The code is translated rather
+ * than forwarded so no stack frame, errno struct or internal path escapes.
+ */
+export function describeFsError(err) {
+    const code = err?.code;
+    switch (code) {
+        case "EACCES":
+        case "EPERM":
+            return "permission denied";
+        case "ENOSPC":
+            return "no space left on the device";
+        case "EROFS":
+            return "the filesystem is read-only";
+        case "EISDIR":
+            return "it is a directory, not a file";
+        default:
+            return "the write could not be completed";
+    }
+}
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Write via a sibling temp file and rename. The rename is atomic within a
+ * filesystem, so a reader either sees the old file or the new one — never a
+ * half-written config. The temp file is removed on any failure so a crashed run
+ * leaves no litter next to the real file.
+ */
+export function atomicWrite(target, contents) {
+    // Same directory, so the rename cannot cross a filesystem boundary. The pid
+    // keeps two concurrent runs from fighting over one temp name.
+    const tmp = `${target}.${process.pid}.tmp`;
+    try {
+        // 0600: this file carries an API key.
+        writeFileSync(tmp, contents, { mode: 0o600 });
+        renameSync(tmp, target);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+export function serialize(settings) {
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+/**
+ * Merge `desiredEnv` into `paths.settings`. Returns what happened rather than
+ * throwing, so the caller owns reporting and the exit code. Nothing is written on
+ * the `conflict` or `malformed` outcomes.
+ */
+export function writeConfig(paths, desiredEnv, options = { force: false }) {
+    const { settings: path } = paths;
+    // Dotfile managers routinely symlink settings.json, and `existsSync` follows
+    // links — so a *dangling* link reports false and would be clobbered by the
+    // create path below. Resolve it ourselves so the link always survives.
+    let linkTarget = path;
+    try {
+        if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink() === true) {
+            linkTarget = resolve(dirname(path), readlinkSync(path));
+        }
+    }
+    catch {
+        linkTarget = path;
+    }
+    if (!existsSync(path)) {
+        try {
+            mkdirSync(dirname(linkTarget), { recursive: true });
+            atomicWrite(linkTarget, serialize({ env: { ...desiredEnv } }));
+        }
+        catch (err) {
+            // Usually `.claude` is already a regular file, or the directory is not
+            // writable. Either way, refuse cleanly rather than surface a stack trace.
+            return { kind: "failed", path, reason: describeFsError(err) };
+        }
+        return { kind: "created", path };
+    }
+    let realPath;
+    let raw;
+    try {
+        realPath = realpathSync(path);
+        // Guarded alongside the resolve: EISDIR for a directory, EACCES when it is
+        // not ours to read. Neither should reach the user as a stack trace.
+        raw = readFileSync(realPath, "utf8");
+    }
+    catch (err) {
+        return { kind: "failed", path, reason: describeFsError(err) };
+    }
+    const backupPath = realPath === path ? paths.backup : `${realPath}.bak`;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Deliberately no parser detail: the message is user-facing and the file may
+        // contain credentials. Refusing beats guessing at a repair.
+        return { kind: "malformed", path, reason: "it is not valid JSON" };
+    }
+    if (!isPlainObject(parsed)) {
+        return { kind: "malformed", path, reason: "its top level is not a JSON object" };
+    }
+    const existingEnv = parsed.env;
+    if (existingEnv !== undefined && !isPlainObject(existingEnv)) {
+        return { kind: "malformed", path, reason: 'its "env" is not a JSON object' };
+    }
+    const currentEnv = existingEnv ?? {};
+    const conflicts = [];
+    const changed = [];
+    for (const [key, desired] of Object.entries(desiredEnv)) {
+        const current = currentEnv[key];
+        if (current === desired)
+            continue;
+        changed.push(key);
+        // Only a *different existing* value is a conflict. A key we have not written
+        // yet is simply an addition.
+        if (current !== undefined) {
+            conflicts.push({ key, current: typeof current === "string" ? current : JSON.stringify(current), desired });
+        }
+    }
+    if (conflicts.length > 0 && !options.force) {
+        return { kind: "conflict", path, conflicts };
+    }
+    // Idempotent: no write, and no backup of an unchanged file.
+    if (changed.length === 0) {
+        return { kind: "unchanged", path };
+    }
+    // Backup first, so a failure anywhere here leaves the original in place: the
+    // replacement is a rename that either happens or does not.
+    try {
+        /* The invariant: the backup always holds the last state that was *not* ours. So a
+         * re-run never buries the developer's original, and a repo we created the file in
+         * gets no backup at all — there is no pre-AI21 state to go back to, and inventing
+         * one made `uninstall` restore the gateway it was meant to remove. */
+        if (!isOurConfig(currentEnv)) {
+            copyFileSync(realPath, backupPath);
+            // copyFileSync inherits the source's mode, and Claude Code's own file is often
+            // 0644 — so the backup would be a world-readable copy of the previous key, left
+            // behind after we tighten the real file to 0600.
+            chmodSync(backupPath, 0o600);
+        }
+        atomicWrite(realPath, serialize({ ...parsed, env: { ...currentEnv, ...desiredEnv } }));
+    }
+    catch (err) {
+        return { kind: "failed", path, reason: describeFsError(err) };
+    }
+    return { kind: "updated", path, backup: backupPath, changed };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,MAAM,EACN,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAe,cAAc,EAAe,MAAM,WAAW,CAAC;AAErE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,oBAAoB,EAAE,0BAA0B,EAAE,oBAAoB,CAAU,CAAC;AAE9G;;oFAEoF;AACpF,MAAM,aAAa,GAA8E;IAC/F,aAAa,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE;CACzD,CAAC;AAaF;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAwC;IAClE,MAAM,OAAO,GAAG,GAAG,EAAE,wBAAwB,CAAC;IAE9C,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,GAAgB,EAAE,SAAiB,cAAc;IAC5F,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAEzE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,QAAQ,MAAM,EAAE,CAAC;AACjD,CAAC;AAgBD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,MAAM,IAAI,GAAI,GAAyC,EAAE,IAAI,CAAC;IAC9D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,OAAO,mBAAmB,CAAC;QAC7B,KAAK,QAAQ;YACX,OAAO,6BAA6B,CAAC;QACvC,KAAK,OAAO;YACV,OAAO,6BAA6B,CAAC;QACvC,KAAK,QAAQ;YACX,OAAO,+BAA+B,CAAC;QACzC;YACE,OAAO,kCAAkC,CAAC;IAC9C,CAAC;AACH,CAAC;AAID,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,QAAgB;IAC1D,4EAA4E;IAC5E,8DAA8D;IAC9D,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC3C,IAAI,CAAC;QACH,sCAAsC;QACtC,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9C,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7B,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAoB;IAC5C,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,KAAkB,EAClB,UAAkC,EAClC,UAAuC,EAAE,KAAK,EAAE,KAAK,EAAE;IAEvD,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAEjC,6EAA6E;IAC7E,2EAA2E;IAC3E,uEAAuE;IACvE,IAAI,UAAU,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC;QACH,IAAI,SAAS,CAAC,IAAI,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC;YAC1E,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACpD,WAAW,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,uEAAuE;YACvE,0EAA0E;YAC1E,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QAChE,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACnC,CAAC;IAED,IAAI,QAAgB,CAAC;IACrB,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAC9B,2EAA2E;QAC3E,oEAAoE;QACpE,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,MAAM,CAAC;IACxE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;QAC7E,4DAA4D;QAC5D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACrE,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAC;IACnF,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC;IAC/B,IAAI,WAAW,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;IAC/E,CAAC;IAED,MAAM,UAAU,GAAe,WAAW,IAAI,EAAE,CAAC;IAEjD,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACxD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,OAAO,KAAK,OAAO;YAAE,SAAS;QAElC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,6EAA6E;QAC7E,6BAA6B;QAC7B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC3C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC/C,CAAC;IAED,4DAA4D;IAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IAED,6EAA6E;IAC7E,2DAA2D;IAC3D,IAAI,CAAC;QACH;;;8EAGsE;QACtE,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7B,YAAY,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACnC,+EAA+E;YAC/E,gFAAgF;YAChF,iDAAiD;YACjD,SAAS,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QAED,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,EAAE,GAAG,UAAU,EAAE,GAAG,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;IACzF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;IAChE,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAChE,CAAC"}

package/dist/login/browser.d.ts

@@ -0,0 +1,7 @@
+export interface BrowserDeps {
+    readonly platform: string;
+    /** Returns false when the process could not be started at all. */
+    readonly launch: (command: string, args: readonly string[]) => boolean;
+}
+export declare function openBrowser(url: string, deps: BrowserDeps): boolean;
+export declare function nodeBrowserDeps(): BrowserDeps;

package/dist/login/browser.js

@@ -0,0 +1,41 @@
+/**
+ * Opening the user's browser — best-effort by nature, since a headless box or SSH
+ * session has none. Failing is not an error: the caller prints the URL regardless.
+ */
+import { spawn } from "node:child_process";
+function launcherFor(platform, url) {
+    switch (platform) {
+        case "darwin":
+            return { command: "open", args: [url] };
+        case "win32":
+            // The empty string is the window *title*: `start "http://…"` would treat the
+            // URL as a title and open nothing. Quoting also keeps `&` in the query string
+            // from being read as a command separator by cmd.exe.
+            return { command: "cmd", args: ["/c", "start", "", url] };
+        default:
+            return { command: "xdg-open", args: [url] };
+    }
+}
+export function openBrowser(url, deps) {
+    const { command, args } = launcherFor(deps.platform, url);
+    return deps.launch(command, args);
+}
+/** The real launcher: detached, so the CLI never waits on a browser to exit. */
+function launch(command, args) {
+    try {
+        const child = spawn(command, [...args], { detached: true, stdio: "ignore" });
+        // Without unref the event loop stays alive until the browser closes — hours.
+        child.unref();
+        // A missing binary is reported asynchronously, too late to return here. Swallowed
+        // rather than thrown, which is why the caller always prints the URL too.
+        child.on("error", () => undefined);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function nodeBrowserDeps() {
+    return { platform: process.platform, launch };
+}
+//# sourceMappingURL=browser.js.map

package/dist/login/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/login/browser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAa3C,SAAS,WAAW,CAAC,QAAgB,EAAE,GAAW;IAChD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ;YACX,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,KAAK,OAAO;YACV,6EAA6E;YAC7E,8EAA8E;YAC9E,qDAAqD;YACrD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;QAC5D;YACE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IAChD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,IAAiB;IACxD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE1D,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,gFAAgF;AAChF,SAAS,MAAM,CAAC,OAAe,EAAE,IAAuB;IACtD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7E,6EAA6E;QAC7E,KAAK,CAAC,KAAK,EAAE,CAAC;QAEd,kFAAkF;QAClF,yEAAyE;QACzE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAEnC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;AAChD,CAAC"}

package/dist/login/contract.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The interface between this CLI and the gateway webapp: the CLI opens
+ * `{app}/welcome` with a callback URL and a `state` nonce, the user signs in, and the
+ * page POSTs the credentials back to the loopback listener.
+ *
+ * The webapp half lives in ai21-intelligent-gateway-webapp
+ * (src/pages/welcome/cliHandoff.ts); this file is the only place either side's shape
+ * is defined, so a change to the agreement is a change to this module.
+ *
+ * Three properties are what make it safe rather than merely convenient: the secret
+ * arrives in a POST body and never a URL; `state` is compared before anything is
+ * written; and the listener is loopback-only.
+ */
+/** Query parameters the CLI adds to the `/welcome` URL it opens. */
+export declare const CALLBACK_PARAM = "cli_callback";
+export declare const STATE_PARAM = "state";
+/** Path the listener answers on. Only this path, and only POST (plus preflight). */
+export declare const CALLBACK_PATH = "/cli-callback";
+/**
+ * Opened first, and redirects to `/welcome`, so the nonce stays out of the browser's
+ * argv where other local users could read it.
+ *
+ * A mitigation, not a cure — it still reaches the URL bar and history, and a local
+ * attacker who guesses the port can request `/start`. Hence single-use: losing that
+ * race breaks the sign-in visibly rather than quietly.
+ */
+export declare const START_PATH = "/start";
+/** What the webapp is expected to POST as JSON. */
+export interface CliCallback {
+    readonly state: string;
+    readonly ai21Key: string;
+    readonly agentId: string;
+    /** Drives the dashboard link; the webapp routes on `/w/:workspaceId`. Optional. */
+    readonly workspaceId?: string;
+}
+export declare function isWorkspaceId(value: unknown): value is string;
+/**
+ * Reads an untrusted JSON body into the contract shape. Strict by design: this is
+ * remote input, so a missing or non-string field is a rejection, not a coercion.
+ * Values are validated separately, by the rule the flags use.
+ */
+export declare function parseCallback(body: unknown): CliCallback | undefined;

package/dist/login/contract.js

@@ -0,0 +1,60 @@
+/**
+ * The interface between this CLI and the gateway webapp: the CLI opens
+ * `{app}/welcome` with a callback URL and a `state` nonce, the user signs in, and the
+ * page POSTs the credentials back to the loopback listener.
+ *
+ * The webapp half lives in ai21-intelligent-gateway-webapp
+ * (src/pages/welcome/cliHandoff.ts); this file is the only place either side's shape
+ * is defined, so a change to the agreement is a change to this module.
+ *
+ * Three properties are what make it safe rather than merely convenient: the secret
+ * arrives in a POST body and never a URL; `state` is compared before anything is
+ * written; and the listener is loopback-only.
+ */
+/** Query parameters the CLI adds to the `/welcome` URL it opens. */
+export const CALLBACK_PARAM = "cli_callback";
+export const STATE_PARAM = "state";
+/** Path the listener answers on. Only this path, and only POST (plus preflight). */
+export const CALLBACK_PATH = "/cli-callback";
+/**
+ * Opened first, and redirects to `/welcome`, so the nonce stays out of the browser's
+ * argv where other local users could read it.
+ *
+ * A mitigation, not a cure — it still reaches the URL bar and history, and a local
+ * attacker who guesses the port can request `/start`. Hence single-use: losing that
+ * race breaks the sign-in visibly rather than quietly.
+ */
+export const START_PATH = "/start";
+/**
+ * An id, never a URL: the dashboard link is built from the baked-in origin, so a
+ * callback cannot choose where the browser lands. No `/`, `:` or `%` means an id
+ * cannot escape its path segment. Not a UUID check — that would be a guessed format,
+ * and the property needed is only "cannot escape".
+ */
+const SAFE_ID = /^[A-Za-z0-9._-]{1,64}$/;
+export function isWorkspaceId(value) {
+    return typeof value === "string" && SAFE_ID.test(value) && value !== "." && value !== "..";
+}
+/**
+ * Reads an untrusted JSON body into the contract shape. Strict by design: this is
+ * remote input, so a missing or non-string field is a rejection, not a coercion.
+ * Values are validated separately, by the rule the flags use.
+ */
+export function parseCallback(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return undefined;
+    const { state, ai21Key, agentId, workspaceId } = body;
+    if (typeof state !== "string" || typeof ai21Key !== "string" || typeof agentId !== "string")
+        return undefined;
+    if (state === "" || ai21Key === "" || agentId === "")
+        return undefined;
+    return {
+        state,
+        ai21Key,
+        agentId,
+        // Dropped rather than rejected when malformed: the dashboard redirect is a
+        // convenience, and losing it must not fail an otherwise good sign-in.
+        ...(isWorkspaceId(workspaceId) ? { workspaceId } : {}),
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/login/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/login/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAC;AAC7C,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC;AAWnC;;;;;GAKG;AACH,MAAM,OAAO,GAAG,wBAAwB,CAAC;AAEzC,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,IAAI,CAAC;AAC7F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAEvF,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAA+B,CAAC;IACjF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAE9G,IAAI,KAAK,KAAK,EAAE,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAEvE,OAAO;QACL,KAAK;QACL,OAAO;QACP,OAAO;QACP,2EAA2E;QAC3E,sEAAsE;QACtE,GAAG,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvD,CAAC;AACJ,CAAC"}

package/dist/login/loopback.d.ts

@@ -0,0 +1,42 @@
+import { type CliCallback } from "./contract.js";
+/** Two minutes: long enough to sign in, short enough not to look wedged. */
+export declare const LOGIN_TIMEOUT_MS = 120000;
+export type LoopbackOutcome = {
+    readonly kind: "callback";
+    readonly payload: CliCallback;
+} | {
+    readonly kind: "timeout";
+} | {
+    readonly kind: "failed";
+    readonly reason: string;
+};
+export interface Listener {
+    /** Open this in the browser; it redirects to the sign-in page. */
+    readonly startUrl: string;
+    /** Where the sign-in page is redirected to, and what to print if no browser opens. */
+    readonly signInUrl: string;
+    /** The URL to hand the webapp. Always loopback, always an ephemeral port. */
+    readonly callbackUrl: string;
+    readonly state: string;
+    /** The interface the socket is actually bound to — asserted in tests. */
+    readonly host: string;
+    readonly port: number;
+    /** Settles once a valid callback arrives, on timeout, or on a listener error. */
+    readonly result: Promise<LoopbackOutcome>;
+    /** Idempotent; safe to call after the promise has settled. */
+    readonly close: () => void;
+}
+/** 256 bits from the CSPRNG. Guessing it is not a threat model we need to model. */
+export declare function newState(): string;
+export interface LoopbackOptions {
+    /** Origin allowed to POST here — the webapp's, never `*`. */
+    readonly allowedOrigin: string;
+    readonly timeoutMs?: number;
+    /** Builds the sign-in URL once the port is known. */
+    readonly signInUrl: (callbackUrl: string, state: string) => string;
+}
+/**
+ * Starts the listener. Resolves once it is bound, so the caller can put the real
+ * port into the URL it opens.
+ */
+export declare function startLoopback(options: LoopbackOptions): Promise<Listener>;