@b3labs/b3iq-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+<h1 align="center">b3iq CLI</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">Manage your B3IQ GPU machines from the terminal, a script, or an AI agent.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@b3labs/b3iq-cli"><img alt="npm version" src="https://img.shields.io/npm/v/@b3labs/b3iq-cli?label=npm&color=0a7cff"></a>
+  <a href="./LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
+  <img alt="Node 22.23.4+ or 24.22.1+" src="https://img.shields.io/badge/node-22.23.4%2B%20%7C%2024.22.1%2B-339933">
+</p>
+
+List your machines, see what they serve, install models and plugins, open an SSH
+session without writing a `ProxyCommand`, and run Codex, Claude Code or OpenCode on
+models you own. Every command speaks JSON when piped, so the same CLI drives scripts
+and agents.
+
+## Install
+
+```bash
+npm install -g @b3labs/b3iq-cli      # or: pnpm add -g @b3labs/b3iq-cli
+b3iq --version
+```
+
+Requires Node.js 22.23.4 or newer on 22.x, or 24.22.1 or newer on 24.x. The package
+ships compiled JavaScript; there is no build step. `b3iq ssh` also needs an OpenSSH
+client and, for tunnelled machines,
+[`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/).
+`b3iq doctor` checks both.
+
+## Quick start
+
+```bash
+b3iq login            # opens your browser; pick your personal account or an organization
+b3iq status           # machines online, models servable
+b3iq machines list
+b3iq ssh my-box       # a shell on the machine
+```
+
+`b3iq login` saves an API key that expires after 90 days. The CLI warns during the
+last 14; run `b3iq login` again to renew. For a script or CI job, create an API key
+with **Machines & SSH** access under
+[Dashboard → Keys → API keys](https://b3iq.org/dashboard/keys?tab=api) and set it
+as `B3IQ_TOKEN`.
+
+## Commands
+
+### Account
+
+| Command | What it does |
+| --- | --- |
+| `login [--token-stdin]` | Sign in through the browser and choose your personal account or an organization. `--token-stdin` saves an API key read from a pipe or file instead; `B3IQ_TOKEN` skips login altogether. An organization login's key reaches that organization's machines as far as your role allows |
+| `logout [--revoke]` | Forget the saved key; `--revoke` also revokes it server-side |
+| `whoami` | The signed-in account and, for an organization login, its organization |
+| `status` | Fleet overview: machines online and servable models (models need a personal login) |
+| `doctor` | Check config, auth, API reachability and `cloudflared` |
+| `config [default-machine <id>]` | View config, or set the machine used when `<machine>` is omitted |
+
+### Machines
+
+| Command | What it does |
+| --- | --- |
+| `machines list` | Your machines (`--quiet` prints node ids only) |
+| `machines get <machine>` | One machine in detail |
+| `machines qualify <machine>` | Re-run hardware qualification (`--no-wait` returns at once) |
+| `machines guests <machine>` | A KVM host's guests and cards: every guest for its owner, your own guest on a host you rent (`--quiet` prints guest ids) |
+| `commands list --machine <id> [--limit <n>]` | Recent commands sent to a machine, newest first |
+| `commands get <command-id> --machine <id>` | One command's status, progress and result |
+| `logs [--limit <n>] [--follow]` | Recent gateway request logs (personal login); `--follow` streams new events, as NDJSON when piped |
+
+### Plugins, models and runtimes
+
+| Command | What it does |
+| --- | --- |
+| `plugins list [--machine <id>]` | Plugins a machine can install, or the ones it has |
+| `plugins install <plugin> --machine <id>` | Install a plugin (`--no-wait`) |
+| `plugins remove <plugin> --machine <id>` | Remove a plugin and everything it installed (`--no-wait`) |
+| `models list [--machine <id>]` | Servable models across the fleet (personal login), or one machine's full catalog |
+| `models install <model> --machine <id>` | Install a model (`--no-wait`) |
+| `models remove <model> --machine <id>` | Uninstall a model (`--no-wait`) |
+| `models context <model> --machine <id> [--tokens <n>\|--reset]` | Allocate, verify and save an Ollama serving window (`--no-wait`) |
+| `runtimes list [--machine <id>]` | A machine's runtimes, with status and self-heal coverage |
+| `runtimes restart <runtime> --machine <id>` | Restart a runtime (`--no-wait`) |
+| `runtimes check --machine <id>` | Refresh installed and pinned Ollama versions; does not upgrade |
+| `runtimes upgrade <runtime-id> --machine <id> --target-version <v>` | Stage a pinned upgrade: wait for idle, verify, roll back on failure |
+| `runtimes policy <runtime-id> --machine <id> --mode manual\|scheduled [--hour-utc <0..23>]` | Keep upgrades manual (the default), or allow a daily one-hour window when idle |
+
+### SSH
+
+| Command | What it does |
+| --- | --- |
+| `ssh [<machine>] [-- <command>]` | Open a shell, or run one command, on a machine. With no machine it asks which one. Prints the `ssh` invocation instead when piped |
+
+### Inference and native coding clients
+
+| Command | What it does |
+| --- | --- |
+| `inference models [--machine <id>]` | Exact served model ids and their verified profile metadata |
+| `inference setup <codex\|claude\|opencode> --model <id>` | Write private client configuration without touching the client's existing settings |
+| `inference <codex\|claude\|opencode> --model <id> [-- <client args>]` | Launch the installed client on your own models, with the media tools attached |
+| `inference setup codex --desktop [--install] [--activate] --model <id>` | Save a separate Codex desktop instance on macOS; normal defaults stay unchanged |
+| `inference setup claude --desktop [--install] [--activate] --model <id>` | Save an inactive Claude desktop connection; it switches over only with `--activate` |
+| `inference restore claude --desktop` | Restore the provider Claude desktop used before activation |
+| `inference setup opencode --desktop --install --model <id>` | Merge OpenCode's persistent settings, keeping unrelated config and taking a backup |
+| `inference key-save` / `inference key-clear` | Save an API key from stdin to `~/.b3iq/gateway-key` (mode `0600`), or remove it |
+| `mcp media` | Run the B3IQ media MCP server over stdio |
+
+**Machine selectors.** `<machine>` accepts a node id, an id prefix, or a
+case-insensitive substring of the machine's name. An exact id or name wins; an
+ambiguous selector exits `1` and lists the candidates. A KVM host you rent stays in
+its owner's list, so `ssh` and `machines guests` also look in your rentals.
+
+**Waiting.** Commands that change a machine wait for the result by default: up to
+45 minutes for a model install, 25 for a plugin install, 10 for a plugin removal or
+a qualification, 6 for `models context`, 5 for a model removal or a runtime
+restart. `--no-wait` returns the command id at once; read it back with
+`commands get`.
+
+## SSH
+
+`b3iq ssh` reaches a machine over its Cloudflare Tunnel (this needs `cloudflared`)
+or a bastion jump host, whichever the machine advertises, and reconnects a shell
+that drops on a network failure (`--no-reconnect` turns that off). Accounts with
+the `cli_direct_ssh` feature go straight to the machine's own address when its sshd
+answers and fall back to the tunnel otherwise; `--direct` and `--tunnel` force one
+path. That feature is not yet available to a `b3iq login`. Passing `-v`, `-E`,
+`-q`, `-y` or `-S` to ssh turns the fallback and the reconnecting off for that run.
+On a KVM host you rent, `ssh` opens your guest as its own user.
+
+The SSH lane is off until you enable it on the machine's dashboard page, and your
+public key must be listed under **Keys → SSH keys**.
+
+## Scripts and agents
+
+- **stdout is data, stderr is logs.** Progress lines and hints never touch stdout.
+- **JSON is automatic when piped.** `--json` forces it, `--pretty` forces the
+  table, `--quiet` prints only ids, one per line.
+- **Exit codes are stable:** `0` ok, `1` usage, `2` api, `3` auth,
+  `4` rate-limited. Branch on these, not on message text.
+- **Errors are JSON too.** In JSON mode a failure writes one object to stderr with
+  `error`, `code`, `request_id`, `diagnostic`, `cause`, `observed`, `recovery` and
+  sometimes `limitation`. Keys and bearer values are redacted.
+
+[AGENTS.md](./AGENTS.md) is the guide for a coding agent that drives the CLI.
+[ERROR_PATHS.md](./ERROR_PATHS.md) lists every `diagnostic` code with what was
+checked and the next step.
+
+## Configuration
+
+| Setting | Meaning |
+| --- | --- |
+| `~/.b3iq/config.json` | The saved login (mode `0600`): the key, its `expires_at`, and for an organization login its `org_id` and `org_name` |
+| `B3IQ_TOKEN` | API key for machine-management commands; overrides the saved login |
+| `B3IQ_API_URL` | Control plane origin. Default `https://control-plane.b3iq.org` |
+| `B3IQ_ORG_ID` | Organization to act for. Refused with a personal key; an organization login does not need it |
+| `B3IQ_DASHBOARD_URL` | Dashboard origin for the `b3iq login` approval link. Defaults to the dashboard paired with `B3IQ_API_URL` |
+| `B3IQ_CONFIG_DIR` | Replaces `~/.b3iq` (config, saved API key, media output), so a test login does not touch your real one |
+| `B3IQ_GATEWAY_API_KEY` | API key for inference and media. Separate from `B3IQ_TOKEN`; `inference key-save` stores it privately instead |
+
+Environment variables override the config file. With `B3IQ_TOKEN` set, the saved
+`org_id` is not sent.
+
+## Native coding clients
+
+Run Codex, Claude Code or OpenCode on models served from your own machines. The CLI
+launches the client you already have installed, points it at the B3IQ gateway with
+a private configuration, and attaches the media MCP server. Your normal client
+settings, authentication and defaults are left alone.
+
+1. Create an API key under
+   [Dashboard → Keys → API keys](https://b3iq.org/dashboard/keys?tab=api) and
+   supply it as `B3IQ_GATEWAY_API_KEY`, or pipe it into `b3iq inference key-save`.
+   Keep it out of command arguments, committed files and tickets.
+2. Discover exact served ids with `b3iq inference models`. The model must be online,
+   serve text with `tool_calling`, and have a verified context window of at least
+   32K for Codex and OpenCode or 100K for Claude Code. `b3iq models context` sets the
+   window.
+3. From your project directory:
+
+   ```bash
+   b3iq inference codex --model <exact-served-id>
+   b3iq inference claude --model <exact-served-id>
+   b3iq inference opencode --model <exact-served-id>
+   ```
+
+Add `--machine <node-id>` to pin one machine; otherwise routing balances across the
+key's permitted machines. The clients keep their own coding tools, permissions,
+saved sessions and project instructions. Desktop setups (`--desktop`) save a
+separate instance or an inactive connection and are experimental on macOS. The full
+walkthrough, including desktop setup and rollback, is at
+[docs.b3iq.org/developers/cli](https://docs.b3iq.org/developers/cli).
+
+Anthropic does not officially support non-Claude gateway models.
+
+## Media MCP
+
+`b3iq mcp media` exposes model discovery, image generation, video submission and
+video status as MCP tools over stdio, using the same API key. Outputs go under
+`~/.b3iq/media` (`--output-dir` changes that). A request is refused when no served
+model matches its modality; a text or video model never stands in for an image
+model. Video submission returns a job id to poll; do not resubmit the same request.
+
+## Support
+
+Questions and bug reports: [hello@b3iq.org](mailto:hello@b3iq.org).
+Documentation: [docs.b3iq.org/developers/cli](https://docs.b3iq.org/developers/cli).
+
+## License
+
+[Apache-2.0](./LICENSE)

package/dist/commands/claude-desktop.js

@@ -0,0 +1,323 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, readFile, writeFile, rename, unlink } from "node:fs/promises";
+import { homedir, userInfo } from "node:os";
+import { join, dirname } from "node:path";
+import { configDir } from "../lib/config.js";
+import { CliError } from "../lib/output.js";
+export function claudeGatewayBase(base) {
+    const url = new URL(base);
+    url.pathname = url.pathname.replace(/\/v1(?:\/api)?$/, "");
+    return url.toString().replace(/\/$/, "");
+}
+export function claudeDesktopAlias(model) {
+    return "claude-" + createHash("sha256").update(`b3iq-desktop-v1:${model}`).digest("hex").slice(0, 24);
+}
+export function claudeDesktopConnection(base, executable, entrypoint, machine, model) {
+    if ([executable, entrypoint].some(value => /["%\x00-\x1f]/.test(value)))
+        throw new CliError("Claude desktop helper paths cannot contain double quotes, percent signs or control characters. Install Node and the CLI at a compatible path.", "usage");
+    return {
+        inferenceProvider: "gateway", inferenceCredentialKind: "helper-script",
+        inferenceGatewayBaseUrl: claudeGatewayBase(base) + (model ? `/v1/claude-desktop/${Buffer.from(model, "utf8").toString("base64url")}` : ""), inferenceGatewayAuthScheme: "bearer",
+        inferenceCredentialHelper: executable,
+        inferenceCredentialHelperArgs: [entrypoint, "inference", "credential", "--saved"],
+        ...(model ? { inferenceModels: [{ name: claudeDesktopAlias(model), labelOverride: `B3IQ · ${model} (experimental)`, supports1m: false, prefer1m: false, maxEffort: "low" }], modelPrefer1mContext: false, defaultModelEffort: "low" } : {}),
+        ...(machine ? { inferenceCustomHeaders: { "x-b3iq-node-id": machine } } : {}),
+    };
+}
+export function claudeDesktopReference(setup) {
+    const c = setup.connection;
+    return {
+        status: setup.activated ? "activated" : setup.saved ? "saved_inactive" : "exported_connection",
+        activated: Boolean(setup.activated), restart_required: Boolean(setup.activated), activation_supported: Boolean(c.inferenceModels), model_compatibility: "experimental",
+        compatibility_note: "Experimental non-Claude model compatibility. The dedicated gateway maps one opaque alias to the real B3IQ model. Anthropic does not support non-Claude models. Code file tools run locally with native permissions; Cowork is not qualified.",
+        discovery_note: "Requires the desktop compatibility gateway deployment. Verify Test model discovery and Test inference before coding. The UI may assume 200K despite a smaller served window; compact early on long sessions. Token counts are conservative estimates.",
+        restore_command: "b3iq inference restore claude --desktop",
+        export_note: "Claude classifies custom headers, including the machine pin, as sensitive. This connection contains no API key; exports include routing IDs and helper paths.",
+        selected_model: setup.selected_model, config_file: setup.config_file,
+        configuration_id: setup.saved?.id, configuration_name: setup.saved?.name,
+        installed_config: setup.saved?.path, backup: setup.saved?.backup,
+        ui_fields: {
+            "Provider": c.inferenceProvider, "Credential kind": c.inferenceCredentialKind,
+            "Gateway base URL": c.inferenceGatewayBaseUrl, "Gateway auth scheme": c.inferenceGatewayAuthScheme,
+            "Helper script": c.inferenceCredentialHelper,
+            "Helper script arguments": c.inferenceCredentialHelperArgs,
+            "Helper script arguments (paste JSON)": JSON.stringify(c.inferenceCredentialHelperArgs),
+            "Custom inference headers": c.inferenceCustomHeaders ?? {},
+            "Models": c.inferenceModels ?? [], "Use 1M wherever available": false, "Default model effort": c.defaultModelEffort,
+            "Gateway API key": "Leave blank; the helper supplies the saved API key.",
+            "Artifact preview iframe origin": "Leave blank.", "Stream idle timeout": "Leave at the default 300 seconds.",
+        },
+        credential: { source: "saved_gateway_key", path: join(configDir(), "gateway-key"), secret_included: false,
+            save_command: 'printf \'%s\' "$B3IQ_GATEWAY_API_KEY" | b3iq inference key-save',
+            instructions: "Create the API key at https://b3iq.org/dashboard/keys?tab=api. Save it privately before using Test script. Do not run b3iq inference credential in a captured terminal." },
+        instructions: setup.activated
+            ? "Reopen Claude normally and start a fresh Code conversation in your local project. To restore the original provider, quit Claude and run b3iq inference restore claude --desktop."
+            : setup.saved
+                ? "Open Claude, then Developer → Configure Third-Party Inference and select the named B3IQ configuration from the top-right saved-configuration dropdown beside Export (initially labelled Default). Keep Provider set to Gateway. Test script checks the helper. Saving leaves the previously applied configuration unchanged. To activate, quit Claude and rerun setup with --desktop --install --activate; reopen Claude afterward. Use b3iq inference restore claude --desktop with Claude closed to restore the original selection."
+                : "Use the generated connection JSON or copy ui_fields into Developer → Configure Third-Party Inference. To save it without typing fields, use b3iq inference setup claude --desktop --install with the same model and machine. Activation is separate and explicit: add --activate only when you intend to switch the desktop provider.",
+    };
+}
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+async function regular(path) {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)
+        throw new CliError("Claude configuration contains a symlink, hard link or non-file. No existing settings were changed.", "usage");
+    return info;
+}
+function libraryMeta(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new CliError("Claude configuration metadata is invalid JSON. No existing settings were changed.", "usage");
+    }
+    if (!value || typeof value !== "object" || !Array.isArray(value.entries) || !value.entries.length
+        || !value.entries.every(e => e && uuid.test(e.id) && typeof e.name === "string")
+        || new Set(value.entries.map(e => e.id)).size !== value.entries.length
+        || typeof value.appliedId !== "string" || !value.entries.some(e => e.id === value.appliedId)) {
+        throw new CliError("Claude configuration metadata is not a recognized initialized library. No existing settings were changed.", "usage");
+    }
+    return value;
+}
+export async function saveClaudeDesktopConnection(setup, directory) {
+    return withLibrary(directory, root => saveInLibrary(setup, root));
+}
+async function withLibrary(directory, operation) {
+    if (!directory && process.platform === "darwin") {
+        try {
+            await promisify(execFile)("/usr/bin/pgrep", ["-x", "Claude"]);
+            throw new CliError("Quit Claude desktop before saving its configuration library, then rerun. No desktop configuration was saved or activated.", "usage");
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            if (error.code !== 1)
+                throw new CliError("Could not verify that Claude desktop is closed. Close the app before saving; use the generated JSON and ui_fields until then.", "usage");
+        }
+    }
+    if (!directory && process.platform !== "darwin")
+        throw new CliError("Inactive Claude desktop saving is qualified on macOS only. Use the generated connection JSON and ui_fields on other systems.", "usage");
+    const root = directory ?? join(homedir(), "Library", "Application Support", "Claude-3p", "configLibrary");
+    let dir;
+    try {
+        dir = await lstat(root);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new CliError("Open Claude's Developer → Configure Third-Party Inference once to initialize its library, quit Claude, then rerun. No desktop configuration was created or activated.", "usage");
+        throw error;
+    }
+    if (!dir.isDirectory() || dir.isSymbolicLink())
+        throw new CliError("Claude's configuration library is not a regular directory. No existing settings were changed.", "usage");
+    const lock = join(root, ".b3iq-save.lock");
+    try {
+        await writeFile(lock, String(process.pid), { flag: "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new CliError("Another B3IQ desktop save is in progress, or its lock remains after interruption. Review .b3iq-save.lock before retrying; no configuration was changed.", "usage");
+        throw error;
+    }
+    try {
+        return await operation(root);
+    }
+    finally {
+        await unlink(lock);
+    }
+}
+async function saveInLibrary(setup, root) {
+    const metaPath = join(root, "_meta.json");
+    let original, metaInfo;
+    try {
+        metaInfo = await regular(metaPath);
+        original = await readFile(metaPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new CliError("Open Claude's third-party configuration window once to initialize its library, quit Claude, then rerun. No desktop configuration was activated.", "usage");
+        throw error;
+    }
+    const meta = libraryMeta(original);
+    await regular(join(root, `${meta.appliedId}.json`));
+    const content = JSON.stringify(setup.connection, null, 2) + "\n";
+    const digest = createHash("sha256").update(JSON.stringify([setup.selected_model, content])).digest().subarray(0, 16);
+    digest[6] = (digest[6] & 15) | 80;
+    digest[8] = (digest[8] & 63) | 128;
+    const hex = digest.toString("hex"), id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    if (meta.appliedId === id)
+        throw new CliError("This B3IQ configuration is already applied. This command only saves inactive configurations; review the active choice in Claude before rerunning.", "usage");
+    const path = join(root, `${id}.json`), entry = meta.entries.find(e => e.id === id);
+    let created = false, metadataInstalled = false;
+    let backupCreated;
+    try {
+        try {
+            await writeFile(path, content, { flag: "wx", mode: 0o600 });
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            await regular(path);
+            if (await readFile(path, "utf8") !== content)
+                throw new CliError("The saved B3IQ configuration contains user edits. No existing configuration was overwritten.", "usage");
+        }
+        if (entry)
+            return { id, name: entry.name, path, changed: created };
+        const name = `B3IQ · ${setup.selected_model}`;
+        const backup = join(root, `_meta.json.before-b3iq-${randomUUID()}`), temp = join(root, `._meta-b3iq-${randomUUID()}.tmp`);
+        await writeFile(backup, original, { flag: "wx", mode: 0o600 });
+        backupCreated = backup;
+        try {
+            await writeFile(temp, JSON.stringify({ ...meta, entries: [...meta.entries, { id, name }] }, null, 2) + "\n", { flag: "wx", mode: metaInfo.mode & 0o777 });
+            const current = await regular(metaPath);
+            if (current.ino !== metaInfo.ino || current.dev !== metaInfo.dev || await readFile(metaPath, "utf8") !== original) {
+                throw new CliError("Claude's configuration library changed during setup. Close its configuration window and retry; the concurrent settings were preserved.", "usage");
+            }
+            await rename(temp, metaPath);
+            metadataInstalled = true;
+        }
+        finally {
+            await unlink(temp).catch(error => { if (error.code !== "ENOENT")
+                throw error; });
+        }
+        return { id, name, path, backup, changed: true };
+    }
+    catch (error) {
+        if (!metadataInstalled) {
+            if (created && await readFile(path, "utf8").catch(() => "") === content)
+                await unlink(path).catch(() => { });
+            if (backupCreated)
+                await unlink(backupCreated).catch(() => { });
+        }
+        throw error;
+    }
+}
+const journalName = ".b3iq-activation.json";
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+async function readObject(path, optional = false) {
+    try {
+        await regular(path);
+        const original = await readFile(path, "utf8"), value = JSON.parse(original);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("object required");
+        return { original, value: value };
+    }
+    catch (error) {
+        if (optional && error.code === "ENOENT")
+            return { original: null, value: {} };
+        throw new CliError("Claude configuration is not a recognized regular JSON object. Existing settings were preserved.", "usage");
+    }
+}
+async function replaceObject(path, original, value) {
+    const current = await readObject(path, original === null);
+    if (current.original !== original)
+        throw new CliError("Claude configuration changed concurrently. Close Claude and retry; no concurrent edits were overwritten.", "usage");
+    const temp = `${path}.b3iq-${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, JSON.stringify(value, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+        if ((await readObject(path, original === null)).original !== original)
+            throw new CliError("Claude configuration changed concurrently; settings were preserved.", "usage");
+        await rename(temp, path);
+    }
+    finally {
+        await unlink(temp).catch(error => { if (error.code !== "ENOENT")
+            throw error; });
+    }
+}
+function deploymentMode(value) {
+    if (!Object.hasOwn(value, "deploymentMode"))
+        return { present: false };
+    if (value.deploymentMode !== "1p" && value.deploymentMode !== "3p")
+        throw new CliError("Claude has an unrecognized deployment mode; activate through its configuration window instead.", "usage");
+    return { present: true, value: value.deploymentMode };
+}
+async function refuseManagedActivation() {
+    for (const path of [join("/Library/Managed Preferences", userInfo().username, "com.anthropic.claudefordesktop.plist"), "/Library/Managed Preferences/com.anthropic.claudefordesktop.plist"]) {
+        try {
+            await lstat(path);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        throw new CliError("Claude has managed preferences. Local activation cannot override organizational policy; use the configuration window with your administrator.", "usage");
+    }
+}
+export async function activateClaudeDesktopConnection(setup, directory) {
+    if (!setup.saved || !setup.connection.inferenceModels)
+        throw new CliError("Save the complete B3IQ desktop connection before activation.", "usage");
+    if (!directory)
+        await refuseManagedActivation();
+    return withLibrary(directory, async (root) => {
+        const metaPath = join(root, "_meta.json"), modePath = join(dirname(root), "claude_desktop_config.json"), journalPath = join(root, journalName);
+        const m = await readObject(metaPath), meta = libraryMeta(m.original);
+        if (!meta.entries.some(e => e.id === setup.saved.id))
+            throw new CliError("Saved B3IQ configuration is missing from Claude's library.", "usage");
+        if (meta.appliedId === setup.saved.id)
+            throw new CliError("B3IQ is already active. Restore the prior connection before activating another configuration.", "usage");
+        const target = join(root, `${setup.saved.id}.json`);
+        await regular(target);
+        if (await readFile(target, "utf8") !== JSON.stringify(setup.connection, null, 2) + "\n")
+            throw new CliError("The saved B3IQ configuration contains user edits; activation refused.", "usage");
+        const mode = await readObject(modePath, true);
+        const original = join(root, `${meta.appliedId}.json`);
+        await regular(original);
+        const journal = { version: 1, before: meta.appliedId, target: setup.saved.id, originalHash: hash(await readFile(original, "utf8")), mode: deploymentMode(mode.value) };
+        try {
+            await writeFile(journalPath, JSON.stringify(journal, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                throw new CliError("A B3IQ activation or recovery is already recorded. Run b3iq inference restore claude --desktop before switching again.", "usage");
+            throw error;
+        }
+        try {
+            if (journal.mode.present) {
+                const value = { ...mode.value };
+                delete value.deploymentMode;
+                await replaceObject(modePath, mode.original, value);
+            }
+            await replaceObject(metaPath, m.original, { ...meta, appliedId: journal.target });
+            setup.activated = true;
+            return { activated: true, original_configuration_id: journal.before, configuration_id: journal.target, restore_command: "b3iq inference restore claude --desktop", restart_required: true };
+        }
+        catch (error) {
+            throw new CliError(`Desktop activation did not finish. Its recovery journal is preserved. With Claude closed, run b3iq inference restore claude --desktop. ${error instanceof Error ? error.message : ""}`, "usage");
+        }
+    });
+}
+export async function restoreClaudeDesktopConnection(directory) {
+    return withLibrary(directory, async (root) => {
+        const journalPath = join(root, journalName), journalFile = await readObject(journalPath, true);
+        if (journalFile.original === null)
+            return { restored: false, defaults_changed: false, instructions: "No B3IQ activation is recorded. Existing settings were preserved." };
+        const j = journalFile.value;
+        if (j.version !== 1 || !uuid.test(j.before) || !uuid.test(j.target) || !/^[a-f0-9]{64}$/.test(j.originalHash) || !j.mode || typeof j.mode.present !== "boolean" || (j.mode.present && j.mode.value !== "1p" && j.mode.value !== "3p"))
+            throw new CliError("The B3IQ recovery journal is invalid; no settings were changed.", "usage");
+        const metaPath = join(root, "_meta.json"), modePath = join(dirname(root), "claude_desktop_config.json");
+        const m = await readObject(metaPath), meta = libraryMeta(m.original);
+        if (![j.before, j.target].includes(meta.appliedId))
+            throw new CliError("You selected another Claude configuration after B3IQ activation. Restore refused to overwrite that choice.", "usage");
+        const original = join(root, `${j.before}.json`);
+        await regular(original);
+        if (!meta.entries.some(e => e.id === j.before) || hash(await readFile(original, "utf8")) !== j.originalHash)
+            throw new CliError("The original Claude configuration changed or was removed. Review it before restoring.", "usage");
+        const mode = await readObject(modePath, true);
+        deploymentMode(mode.value);
+        if (meta.appliedId !== j.before)
+            await replaceObject(metaPath, m.original, { ...meta, appliedId: j.before });
+        const value = { ...mode.value };
+        if (j.mode.present)
+            value.deploymentMode = j.mode.value;
+        else
+            delete value.deploymentMode;
+        if (JSON.stringify(value) !== JSON.stringify(mode.value))
+            await replaceObject(modePath, mode.original, value);
+        await unlink(journalPath);
+        return { restored: true, configuration_id: j.before, restart_required: true, instructions: "Reopen Claude. Your original configuration and account-mode preference are restored; saved B3IQ entries remain inactive." };
+    });
+}

package/dist/commands/codex-desktop.js

@@ -0,0 +1,118 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, readFile, writeFile, lstat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { CliError } from "../lib/output.js";
+const exec = promisify(execFile);
+const quote = (s) => `'${s.replace(/'/g, `'"'"'`)}'`;
+export async function findCodexDesktop(app) {
+    if (process.platform !== "darwin")
+        throw new CliError("Isolated Codex desktop setup is experimental and currently available on macOS only.", "usage");
+    for (const path of app
+        ? [resolve(app)]
+        : ["/Applications/ChatGPT.app", "/Applications/Codex.app"]) {
+        try {
+            const plist = join(path, "Contents", "Info.plist");
+            const { stdout: id } = await exec("/usr/libexec/PlistBuddy", [
+                "-c",
+                "Print :CFBundleIdentifier",
+                plist,
+            ]);
+            if (id.trim() !== "com.openai.codex")
+                continue;
+            const { stdout: version } = await exec("/usr/libexec/PlistBuddy", [
+                "-c",
+                "Print :CFBundleShortVersionString",
+                plist,
+            ]);
+            const bundle = await readFile(join(path, "Contents", "Resources", "app.asar"));
+            if (!bundle.includes(Buffer.from("CODEX_ELECTRON_USER_DATA_PATH")) ||
+                !bundle.includes(Buffer.from("CODEX_HOME"))) {
+                throw new CliError("This Codex desktop build does not expose the required isolation settings. The normal desktop configuration was not changed.", "usage");
+            }
+            return { path, version: version.trim() };
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+        }
+    }
+    throw new CliError("Install the macOS Codex desktop app, or provide its path with --desktop-app. Normal desktop settings were not changed.", "usage");
+}
+async function privateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const s = await lstat(path);
+    if (!s.isDirectory() || s.isSymbolicLink())
+        throw new CliError("Refusing a linked or non-directory desktop configuration path.", "usage");
+}
+async function saveExclusive(path, content, mode = 0o600) {
+    try {
+        await writeFile(path, content, { flag: "wx", mode });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const s = await lstat(path);
+        if (!s.isFile() ||
+            s.isSymbolicLink() ||
+            s.nlink !== 1 ||
+            (await readFile(path, "utf8")) !== content) {
+            throw new CliError(`The isolated Codex file ${JSON.stringify(path)} differs from the generated setup or is not a regular, unlinked file. Existing files were preserved. Changed setup options, a CLI update, or app/user edits can cause this. Keep this setup and rerun with --setup-name <new-name> to create a separate instance. Normal settings were not changed.`, "usage");
+        }
+    }
+}
+export function codexDesktopLaunchArgs(s) {
+    return [
+        "-n",
+        "--env",
+        `CODEX_HOME=${s.engine_home}`,
+        "--env",
+        `CODEX_ELECTRON_USER_DATA_PATH=${s.desktop_data}`,
+        "--env",
+        "CODEX_APP_SERVER_WS_URL=",
+        s.app,
+        "--args",
+        `--user-data-dir=${s.desktop_data}`,
+    ];
+}
+export async function saveCodexDesktop(config, dir, app) {
+    const engine = join(dir, "codex-home"), data = join(dir, "desktop-data");
+    await privateDirectory(dir);
+    await privateDirectory(engine);
+    await privateDirectory(data);
+    await saveExclusive(join(engine, "config.toml"), await readFile(config, "utf8"));
+    const setup = {
+        app: app.path,
+        app_version: app.version,
+        engine_home: engine,
+        desktop_data: data,
+        launcher: join(dir, "B3IQ Codex.command"),
+    };
+    const check = "const fs=require('node:fs');const b=fs.readFileSync(process.argv[1]);process.exit(b.includes(Buffer.from('CODEX_HOME'))&&b.includes(Buffer.from('CODEX_ELECTRON_USER_DATA_PATH'))?0:1)";
+    const script = "#!/bin/sh\nset -eu\n" +
+        "# B3IQ uses separate Codex engine and desktop state. Normal defaults remain unchanged.\n" +
+        `[ "$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' ${quote(join(setup.app, "Contents", "Info.plist"))})" = 'com.openai.codex' ] || exit 1\n` +
+        `${quote(process.execPath)} -e ${quote(check)} ${quote(join(setup.app, "Contents", "Resources", "app.asar"))} || { printf '%s\\n' 'Codex desktop isolation support is unavailable. Re-run B3IQ desktop setup.' >&2; exit 1; }\n` +
+        "exec /usr/bin/open " +
+        codexDesktopLaunchArgs(setup).map(quote).join(" ") +
+        "\n";
+    await saveExclusive(setup.launcher, script, 0o700);
+    return setup;
+}
+export async function installCodexDesktopLauncher(setup, directory = join(homedir(), "Applications")) {
+    await privateDirectory(directory);
+    const id = createHash("sha256")
+        .update(setup.engine_home)
+        .digest("hex")
+        .slice(0, 12);
+    const path = join(directory, `B3IQ Codex ${id}.command`);
+    await saveExclusive(path, await readFile(setup.launcher, "utf8"), 0o700);
+    setup.installed_launcher = path;
+}
+export async function launchCodexDesktop(setup) {
+    await findCodexDesktop(setup.app);
+    await exec("/usr/bin/open", codexDesktopLaunchArgs(setup));
+    setup.launched = true;
+}