@aisa-one/cli 0.3.0 → 0.5.1

package/dist/commands/install.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Installing a coding agent on the user's behalf.
+ *
+ * Two rules decide everything here:
+ *
+ * 1. **Never sudo.** A CLI that escalates on a user's machine is a CLI nobody
+ *    should trust, and there is no terminal to type a password into anyway.
+ *    Where a global npm prefix is not writable we print the command and let
+ *    the user run it — the flow resumes on a re-check rather than failing.
+ * 2. **Prefer the vendor's own user-space installer.** Claude Code's script
+ *    lands in ~/.local/bin, so the permission question never arises. npm is
+ *    the fallback, and the one place rule 1 gets exercised.
+ *
+ * Windows is deliberately out of scope for now: the installers differ
+ * (PowerShell, winget) and nothing here has been tested there. `supported()`
+ * says so rather than half-working.
+ */
+export interface Installer {
+    id: string;
+    label: string;
+    /** The binary that must appear on PATH once installed. */
+    binary: string;
+    /** Preferred command, shown verbatim before it runs. */
+    command: string;
+    /** Where the preferred command puts things, for the "not on PATH" hint. */
+    installDir?: string;
+    /** Set when the command is an npm install; enables the broken-install retry. */
+    npmPackage?: string;
+    /** For a curl installer: the URL it depends on, probed (3s) before use.
+     *  The npm-registry probe cannot stand in for this — the two hosts can be
+     *  blocked independently, and a blackholed curl would otherwise sit at the
+     *  full install timeout before the npm fallback even started. */
+    probeUrl?: string;
+}
+export declare const INSTALLERS: Record<string, Installer>;
+export declare function supported(): boolean;
+export type NpmChannel = 
+/** The user's npm already points somewhere non-default — use it as is. */
+{
+    kind: "user";
+}
+/** The official registry answers — no flag needed. */
+ | {
+    kind: "official";
+}
+/** Official unreachable, the mirror answers — pass --registry once. */
+ | {
+    kind: "mirror";
+    registry: string;
+}
+/** Nothing answers — let the install fail with its own network error. */
+ | {
+    kind: "offline";
+};
+/**
+ * Decide which npm registry an install should use, by probing the channel
+ * itself rather than guessing at geography. An IP-location lookup answers
+ * the wrong question (an IP inside a firewall says nothing about whether a
+ * corporate proxy reaches the official registry, and the lookup service is
+ * one more thing to be unreachable); a HEAD request for the exact package
+ * we are about to install answers the right one. Worst case adds one fixed
+ * timeout, instead of the minutes-long install failure it replaces.
+ *
+ * The mirror is used only as a fallback, never by preference: it is a third
+ * party in the supply chain, trusted widely but still one more link.
+ */
+export declare function pickNpmChannel(pkg: string, probe?: (url: string) => Promise<boolean>, userRegistry?: () => string | null): Promise<NpmChannel>;
+/** Is the binary already on PATH and able to start? */
+export declare function isInstalled(binary: string): boolean;
+/**
+ * Can we write to npm's global prefix? Asked before running an npm install so
+ * the failure is a printed command rather than a wall of EACCES.
+ */
+export declare function npmPrefixWritable(): boolean;
+export type InstallOutcome = {
+    ok: true;
+    alreadyInstalled: boolean;
+} | {
+    ok: false;
+    reason: "unsupported-platform" | "needs-manual";
+    command: string;
+    detail: string;
+};
+/**
+ * Install one agent, or explain what the user should run instead.
+ *
+ * Never throws for an install failure: the caller reports it and the rest of
+ * the run continues, because a failed install must not cost the user the MCP
+ * servers they also asked for.
+ */
+export declare function installAgent(id: string): Promise<InstallOutcome>;

package/dist/commands/install.js

@@ -0,0 +1,258 @@
+import { accessSync, constants, existsSync } from "node:fs";
+import { runShell, runSync, QUICK_TIMEOUT_MS } from "../utils/exec.js";
+export const INSTALLERS = {
+    "claude-code": {
+        id: "claude-code",
+        label: "Claude Code",
+        binary: "claude",
+        // The vendor installer, which needs no elevated permissions. The npm
+        // package (also published by Anthropic) is the fallback channel — it is
+        // what makes the mirror path below work where claude.ai is unreachable.
+        // Curl gets its own timeouts: a blackholed connection must fail in
+        // seconds, not sit until the overall install deadline.
+        command: "curl -fsSL --connect-timeout 10 --max-time 180 https://claude.ai/install.sh | bash",
+        installDir: "~/.local/bin",
+        npmPackage: "@anthropic-ai/claude-code",
+        probeUrl: "https://claude.ai/install.sh",
+    },
+    codex: {
+        id: "codex",
+        label: "Codex",
+        binary: "codex",
+        command: "npm install -g @openai/codex",
+        npmPackage: "@openai/codex",
+    },
+    opencode: {
+        id: "opencode",
+        label: "opencode",
+        binary: "opencode",
+        command: "npm install -g opencode-ai",
+        npmPackage: "opencode-ai",
+    },
+    // The CLI itself. connect usually runs via npx, which installs nothing —
+    // without this step the user walks away with no `aisa` command for
+    // balance, top-up or key rotation, and has to rediscover npx every time.
+    "aisa-cli": {
+        id: "aisa-cli",
+        label: "AIsa CLI",
+        binary: "aisa",
+        command: "npm install -g @aisa-one/cli",
+        npmPackage: "@aisa-one/cli",
+    },
+};
+export function supported() {
+    return process.platform === "darwin" || process.platform === "linux";
+}
+// ── registry channel ────────────────────────────────────────────────────────
+const NPM_OFFICIAL = "https://registry.npmjs.org";
+const NPM_MIRROR = "https://registry.npmmirror.com";
+/**
+ * Decide which npm registry an install should use, by probing the channel
+ * itself rather than guessing at geography. An IP-location lookup answers
+ * the wrong question (an IP inside a firewall says nothing about whether a
+ * corporate proxy reaches the official registry, and the lookup service is
+ * one more thing to be unreachable); a HEAD request for the exact package
+ * we are about to install answers the right one. Worst case adds one fixed
+ * timeout, instead of the minutes-long install failure it replaces.
+ *
+ * The mirror is used only as a fallback, never by preference: it is a third
+ * party in the supply chain, trusted widely but still one more link.
+ */
+export async function pickNpmChannel(pkg, probe = headOk, userRegistry = npmConfiguredRegistry) {
+    const configured = userRegistry();
+    if (configured && !configured.startsWith(NPM_OFFICIAL))
+        return { kind: "user" };
+    const path = `/${pkg.replace("/", "%2f")}`;
+    if (await probe(NPM_OFFICIAL + path))
+        return { kind: "official" };
+    if (await probe(NPM_MIRROR + path))
+        return { kind: "mirror", registry: NPM_MIRROR };
+    return { kind: "offline" };
+}
+async function headOk(url) {
+    try {
+        const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(3_000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function npmConfiguredRegistry() {
+    try {
+        const r = runSync("npm", ["config", "get", "registry"], { timeout: QUICK_TIMEOUT_MS });
+        return r.status === 0 ? r.stdout.trim() || null : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the binary and report what actually happened, because "not working"
+ * has two very different causes with two very different fixes: absent from
+ * PATH (fix the PATH) versus present but failing to start (fix the install —
+ * seen live when npm's optional-dependency bug installed codex without its
+ * platform binary and every invocation threw "Missing optional dependency").
+ * The timeout is generous: macOS Gatekeeper can stall a binary's first run.
+ */
+function probeBinary(binary) {
+    const res = runSync(binary, ["--version"]);
+    if (res.status === 0)
+        return { ok: true };
+    if (res.error?.code === "ENOENT") {
+        return { ok: false, onPath: false, reason: "not on PATH" };
+    }
+    const line = (res.stderr || res.stdout || "")
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.includes("Error") || l.length > 0) ?? `exit status ${res.status}`;
+    return { ok: false, onPath: true, reason: line.slice(0, 160) };
+}
+/** Is the binary already on PATH and able to start? */
+export function isInstalled(binary) {
+    return probeBinary(binary).ok;
+}
+/**
+ * Can we write to npm's global prefix? Asked before running an npm install so
+ * the failure is a printed command rather than a wall of EACCES.
+ */
+export function npmPrefixWritable() {
+    try {
+        const r = runSync("npm", ["config", "get", "prefix"], { timeout: QUICK_TIMEOUT_MS });
+        const prefix = r.status === 0 ? r.stdout.trim() : "";
+        if (!prefix || !existsSync(prefix))
+            return false;
+        accessSync(prefix, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install one agent, or explain what the user should run instead.
+ *
+ * Never throws for an install failure: the caller reports it and the rest of
+ * the run continues, because a failed install must not cost the user the MCP
+ * servers they also asked for.
+ */
+export async function installAgent(id) {
+    const installer = INSTALLERS[id];
+    if (!installer) {
+        return { ok: false, reason: "needs-manual", command: "", detail: `unknown agent ${id}` };
+    }
+    if (isInstalled(installer.binary))
+        return { ok: true, alreadyInstalled: true };
+    if (!supported()) {
+        return {
+            ok: false,
+            reason: "unsupported-platform",
+            command: installer.command,
+            detail: "automatic install is macOS/Linux only for now",
+        };
+    }
+    // Pick the registry channel before running anything: one fixed 3s probe
+    // replaces the minutes-long hang a firewalled user would otherwise sit
+    // through before the fallback even started.
+    const channel = installer.npmPackage
+        ? await pickNpmChannel(installer.npmPackage)
+        : { kind: "official" };
+    const flag = channel.kind === "mirror" ? ` --registry=${channel.registry}` : "";
+    const npmCommand = installer.npmPackage
+        ? `npm install -g ${installer.npmPackage}${flag}`
+        : undefined;
+    // A curl installer needs its vendor host reachable — a fact the registry
+    // probe cannot vouch for, so it gets its own 3s probe. Unreachable (or the
+    // whole official channel is): go straight to the npm channel, which
+    // carries the same vendor-published package.
+    const isNpmInstaller = installer.command.startsWith("npm ");
+    const vendorReachable = isNpmInstaller || channel.kind === "mirror" || !installer.probeUrl
+        ? true
+        : await headOk(installer.probeUrl);
+    const command = isNpmInstaller
+        ? npmCommand
+        : (channel.kind === "mirror" || !vendorReachable) && npmCommand
+            ? npmCommand
+            : installer.command;
+    if (command.startsWith("npm ") && !npmPrefixWritable()) {
+        return {
+            ok: false,
+            reason: "needs-manual",
+            command,
+            detail: "npm's global prefix is not writable by this user",
+        };
+    }
+    // Shell, because the vendor installer is a pipeline. The command is
+    // printed by the caller before this runs; nothing is installed silently.
+    const first = await runShell(command);
+    // The installer may have succeeded even when the command reported an error
+    // (a killed pipe, a noisy postinstall): believe the binary, not the exit
+    // code, before spending a retry.
+    if (!first.ok && probeBinary(installer.binary).ok) {
+        return { ok: true, alreadyInstalled: false };
+    }
+    if (!first.ok) {
+        // A failed install gets exactly one more chance. Curl channel: retry over
+        // npm (same vendor package, different transport). npm channel: a clean
+        // uninstall + reinstall — npm's optional-dependency bug can fail the
+        // install itself (seen live with opencode: the platform binary gets
+        // "reify mark deleted" and the postinstall exits 1), and the reinstall
+        // is the remedy that works by hand.
+        const fallback = npmCommand && command !== npmCommand
+            ? npmCommand
+            : installer.npmPackage
+                // Retry over the top, never after removing what is there. See the
+                // note further down: the uninstall half of this cost a user their
+                // working install when the reinstall could not reach the registry.
+                ? npmCommand ?? command
+                : undefined;
+        if (!fallback) {
+            return {
+                ok: false,
+                reason: "needs-manual",
+                command,
+                detail: first.detail,
+            };
+        }
+        const second = await runShell(fallback);
+        if (!second.ok && !probeBinary(installer.binary).ok) {
+            return {
+                ok: false,
+                reason: "needs-manual",
+                command: npmCommand ?? command,
+                detail: second.detail,
+            };
+        }
+    }
+    let probe = probeBinary(installer.binary);
+    if (!probe.ok && probe.onPath && installer.npmPackage) {
+        // The binary exists but did not start. npm's optional-dependency bug
+        // leaves exactly this — package installed, platform binary missing — and
+        // reinstalling over the top fixes it.
+        //
+        // 🔴 What this must never do again is uninstall first. `probeBinary`
+        // reports a timeout the same way it reports a broken install, so a slow
+        // start on a loaded machine was enough to condemn a working tool; the
+        // uninstall then succeeded, the reinstall failed on a flaky download, and
+        // the user was left with nothing where their agent used to be. Observed
+        // on 2026-08-25 against a working `claude`, more than once.
+        //
+        // Installing over an existing copy is what npm does anyway. If it fails,
+        // the user still has what they had.
+        await runShell(npmCommand ?? command);
+        probe = probeBinary(installer.binary);
+    }
+    if (!probe.ok) {
+        return {
+            ok: false,
+            reason: "needs-manual",
+            command: installer.command,
+            detail: !probe.onPath
+                ? installer.installDir
+                    ? `installed, but ${installer.binary} is not on PATH — add ${installer.installDir} to it`
+                    : `install reported success but ${installer.binary} is not on PATH`
+                : `installed, but ${installer.binary} fails to start: ${probe.reason}`,
+        };
+    }
+    return { ok: true, alreadyInstalled: false };
+}

package/dist/commands/llm-config.d.ts

@@ -0,0 +1,103 @@
+export interface ModelChoice {
+    /** The workhorse model (Claude Code's sonnet/opus tiers, Codex's default). */
+    model: string;
+    /** The cheap model Claude Code reaches for on small tasks. */
+    smallModel: string;
+    /** Context window in tokens. Codex needs it declared; without it the CLI
+     *  warns "Model metadata not found" and falls back to defaults that
+     *  degrade its behaviour. */
+    contextWindow: number;
+}
+/**
+ * Defaults follow the agent, not our preference.
+ *
+ * Each coding agent is tuned around a model family: its system prompt, tool
+ * schemas and patch format were written and evaluated against one. Codex is
+ * OpenAI's, and `gpt-5.3-codex` is the model trained for it; Claude Code is
+ * Anthropic's. Sending either somewhere else works — the gateway speaks both
+ * protocols — but it is not the pairing the agent was built for, and it is
+ * not what a user installing that agent expects. Both remain switchable.
+ */
+export declare const DEFAULT_MODELS: ModelChoice;
+export declare const CODEX_DEFAULT_MODELS: ModelChoice;
+/** The default pairing for one agent. */
+export declare function defaultModelsFor(client: string): ModelChoice;
+export type ConfigResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function writeClaudeCodeLLM(apiKey: string, models?: ModelChoice): ConfigResult;
+export declare function removeClaudeCodeLLM(): ConfigResult;
+/**
+ * Codex talks the Responses API, not Chat Completions, so its base URL is the
+ * `/v1` root our gateway serves `/v1/responses` from — hence the separate
+ * constant and `wire_api = "responses"`.
+ */
+export declare function writeCodexLLM(apiKey: string, models?: ModelChoice): ConfigResult;
+export declare function removeCodexLLM(): ConfigResult;
+/**
+ * Codex keeps MCP servers in the same config.toml. Note `http_headers`, not
+ * `headers` — Codex's field name, and getting it wrong fails silently at the
+ * first authenticated call rather than at load.
+ */
+export declare function writeCodexMCP(servers: Array<{
+    slug: string;
+    endpoint: string;
+}>, apiKey: string | undefined): ConfigResult;
+/**
+ * Swap an entry's env-var token reference for the literal Authorization header.
+ *
+ * `codex mcp add --bearer-token-env-var` is the official way to add a keyed
+ * entry without triggering the OAuth flow, but it records only the variable
+ * NAME — at runtime Codex reads the token from its own process environment,
+ * and nothing guarantees the user's shell exports it. `http_headers` is the
+ * field Codex accepts for a literal header (`bearer_token` is explicitly
+ * rejected by its config loader), and it matches what the Claude Code path
+ * already stores via --header. The env-var reference is removed so the entry
+ * has exactly one source of credentials.
+ */
+export declare function patchCodexMCPAuth(name: string, apiKey: string): ConfigResult;
+/**
+ * Register AIsa as a custom provider and point the default models at it.
+ *
+ * `@ai-sdk/anthropic` is the runtime (opencode loads providers as Vercel AI
+ * SDK packages): our gateway's /v1/messages face is live and verified with a
+ * real Claude Code session, and the anthropic SDK is the pairing that face
+ * was built for. Models are declared explicitly — a custom provider has no
+ * models.dev entry to inherit from.
+ */
+export declare function writeOpencodeLLM(apiKey: string, models?: ModelChoice): ConfigResult;
+export declare function removeOpencodeLLM(): ConfigResult;
+/**
+ * Write the MCP entries. With a key the entry carries the literal
+ * Authorization header; without one, `oauth: {}` tells opencode to run its
+ * own MCP OAuth (dynamic client registration per its schema).
+ */
+export declare function writeOpencodeMCP(servers: Array<{
+    slug: string;
+    endpoint: string;
+}>, apiKey: string | undefined): ConfigResult;
+/**
+ * Codex backup: provider + catalog in the base config, top-level defaults
+ * untouched, and a standalone aisa.config.toml that `codex --profile aisa`
+ * (or the codex-aisa wrapper) layers on top of it.
+ *
+ * That standalone file is Codex ≥0.149's replacement for the old
+ * `[profiles.aisa]` table — `--profile <name>` now means "layer
+ * `$CODEX_HOME/<name>.config.toml`", and Codex refuses to start at all if
+ * the legacy table for that name still exists in config.toml alongside it
+ * (hit live 2026-08-24, codex-cli 0.149.1: "cannot be used while
+ * config.toml contains legacy `profile = \"aisa\"` or `[profiles.aisa]`").
+ * A machine still carrying that table from an earlier version of this
+ * writer gets it removed here — a one-time, one-way migration; nothing a
+ * user typed into it themselves would collide with a section this narrow.
+ */
+export declare function writeCodexAisaProfile(apiKey: string, models?: ModelChoice): ConfigResult;
+/**
+ * opencode backup: provider declared, `model`/`small_model` left alone — the
+ * user picks aisa/<model> in the TUI whenever they want it.
+ */
+export declare function writeOpencodeAisaBackup(apiKey: string, models?: ModelChoice): ConfigResult;