@aisa-one/cli 0.2.4 → 0.5.0

package/dist/commands/mcp.d.ts

@@ -1,4 +1,81 @@
+/**
+ * `aisa mcp setup` — write real, per-client MCP entries from the live manifest.
+ *
+ * Three rules, each one a lesson from the version this replaces:
+ *
+ * 1. The server list comes from the platform's discovery manifest at setup
+ *    time, never from this file. Servers ship without a CLI release.
+ * 2. Nothing is written unless the manifest was actually fetched. The old
+ *    command wrote first and verified never, which is how a dead hostname
+ *    sat in users' configs across releases.
+ * 3. Each client gets the shape it executes: `{url}` for clients that dial
+ *    HTTP themselves, an `npx mcp-remote` stdio bridge for the ones that only
+ *    spawn processes. One shape for all three was the old bug.
+ *
+ * Auth is a choice the user already made: with an API key configured, entries
+ * carry it as a Bearer header (zero-interaction, but the key lands in each
+ * client's config file); without one, entries carry no credentials and the
+ * server's 401 challenge drives the client through the Clerk OAuth flow.
+ */
+export interface LiveServer {
+    slug: string;
+    name: string;
+    endpoint: string;
+    toolCount: number;
+    /** One-paragraph capability description from the manifest — the single
+     *  source of truth for what a server does; rendered on the connect page. */
+    description: string;
+    category: string;
+}
+export declare const stripped: (name: string) => string;
+/**
+ * Which servers exist, asked of the host that runs them.
+ *
+ * The index is preferred and the manifest is the fallback, in that order for
+ * one reason: the manifest is a snapshot committed by hand, and on 2026-08-25
+ * it was three servers and 72 tools behind what the host was actually serving.
+ * Anything derived from a running process cannot drift that way.
+ *
+ * The fallback is not defensive padding — the index is newer than some
+ * deployments, and a self-hosted gateway configured through `baseUrl` may
+ * never grow one. A user in either case should still get a working setup from
+ * a slightly stale list rather than an error.
+ */
+export declare function fetchLiveServers(): Promise<LiveServer[]>;
+/** One config entry in the shape the client actually executes. */
+export declare function buildEntry(shape: "url" | "stdio", endpoint: string, key: string | undefined): Record<string, unknown>;
+export type WriteResult = {
+    ok: true;
+    written: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Write the chosen servers (plus the docs server) into one client's config
+ * file. Shared by `aisa mcp setup` and `aisa connect` so the two entry points
+ * cannot drift in how they treat existing files: unparseable JSON is refused,
+ * never replaced, and only the known-dead legacy entry is cleaned up.
+ */
+export declare function writeClientConfig(agent: string, chosen: LiveServer[], key: string | undefined): WriteResult;
 export declare function mcpSetupAction(options: {
     agent?: string;
-}): void;
-export declare function mcpStatusAction(): void;
+    all?: boolean;
+    yes?: boolean;
+}): Promise<void>;
+/**
+ * `aisa mcp status` — what is configured, and does it actually answer.
+ *
+ * The old status only checked that a config file contained an "aisa" key,
+ * which is exactly how a dead URL looked healthy. Reachability means a real
+ * HTTP exchange with each configured endpoint.
+ */
+export declare function mcpStatusAction(): Promise<void>;
+/**
+ * One initialize POST, no credentials. What each answer means:
+ *   200 -> alive and open (the docs MCP)
+ *   401 -> alive, auth required — the expected answer from mcp.aisa.one
+ *   anything else -> alive but odd; say so
+ *   network error -> the dead-hostname class this command exists to catch
+ */
+export declare function pingEndpoint(endpoint: string): Promise<string>;

package/dist/commands/mcp.js

@@ -2,66 +2,280 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import chalk from "chalk";
 import { success, error, info, hint } from "../utils/display.js";
 import { expandHome, ensureDir } from "../utils/file.js";
-import { MCP_CONFIGS, MCP_URL } from "../constants.js";
+import { MCP_CONFIGS, MCP_MANIFEST_URL, MCP_CATALOG_URL, DOCS_MCP_URL, MCP_DEFAULT_SLUGS } from "../constants.js";
+import { httpFetch, MAX_ATTEMPTS } from "../utils/http.js";
+import { getApiKey } from "../config.js";
+import { detectClients } from "./connect.js";
 import { join } from "node:path";
-export function mcpSetupAction(options) {
-    const targets = options.agent && options.agent !== "all"
-        ? [options.agent]
-        : Object.keys(MCP_CONFIGS);
-    let configured = 0;
-    for (const agent of targets) {
-        const config = MCP_CONFIGS[agent];
-        if (!config) {
+export const stripped = (name) => name.replace(/^AIsa\s+/i, "");
+function toLive(servers) {
+    return servers
+        .filter((s) => s.status === "live" && s.slug && s.transport?.endpoint)
+        .map((s) => ({
+        slug: s.slug,
+        name: s.name ?? s.slug,
+        endpoint: s.transport.endpoint,
+        toolCount: s.toolCount ?? s.tools?.length ?? 0,
+        description: s.description ?? "",
+        category: s.category ?? "Other",
+    }));
+}
+async function readSource(url, attempts) {
+    const res = await httpFetch(url, { idempotent: true, maxAttempts: attempts, timeoutMs: 15_000 });
+    if (!res.ok)
+        throw new Error(`${url} answered HTTP ${res.status}`);
+    const doc = (await res.json());
+    const live = toLive(doc.servers ?? []);
+    if (live.length === 0)
+        throw new Error(`${url} lists no live servers`);
+    return live;
+}
+/**
+ * Which servers exist, asked of the host that runs them.
+ *
+ * The index is preferred and the manifest is the fallback, in that order for
+ * one reason: the manifest is a snapshot committed by hand, and on 2026-08-25
+ * it was three servers and 72 tools behind what the host was actually serving.
+ * Anything derived from a running process cannot drift that way.
+ *
+ * The fallback is not defensive padding — the index is newer than some
+ * deployments, and a self-hosted gateway configured through `baseUrl` may
+ * never grow one. A user in either case should still get a working setup from
+ * a slightly stale list rather than an error.
+ */
+export async function fetchLiveServers() {
+    try {
+        // One attempt only: there is somewhere else to go, so spending a retry
+        // budget here just delays the fallback. The manifest is the last resort
+        // and gets the full three.
+        return await readSource(MCP_CATALOG_URL, 1);
+    }
+    catch {
+        return await readSource(MCP_MANIFEST_URL, MAX_ATTEMPTS);
+    }
+}
+/** One config entry in the shape the client actually executes. */
+export function buildEntry(shape, endpoint, key) {
+    if (shape === "url") {
+        return key ? { url: endpoint, headers: { Authorization: `Bearer ${key}` } } : { url: endpoint };
+    }
+    // The exact invocation verified against production on 2026-08-18. The
+    // header value splits on the first colon, so no space after "Authorization:".
+    // Without a key, mcp-remote answers the server's 401 challenge by running
+    // the OAuth flow itself and caching tokens under ~/.mcp-auth.
+    const args = ["-y", "mcp-remote", endpoint];
+    if (key)
+        args.push("--header", `Authorization:Bearer ${key}`);
+    args.push("--transport", "http-only");
+    return { command: "npx", args };
+}
+/** The dead entry every pre-v0.3 setup wrote. Remove it on sight. */
+const DEAD_URL = "https://docs.aisa.one/mcp";
+/**
+ * Write the chosen servers (plus the docs server) into one client's config
+ * file. Shared by `aisa mcp setup` and `aisa connect` so the two entry points
+ * cannot drift in how they treat existing files: unparseable JSON is refused,
+ * never replaced, and only the known-dead legacy entry is cleaned up.
+ */
+export function writeClientConfig(agent, chosen, key) {
+    const config = MCP_CONFIGS[agent];
+    if (!config)
+        return { ok: false, reason: `unknown client "${agent}"` };
+    const filePath = expandHome(config.path);
+    let existing = {};
+    if (existsSync(filePath)) {
+        try {
+            existing = JSON.parse(readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            // A file we cannot parse is a file we do not own. Refuse instead of
+            // wiping a user's hand-edited config.
+            return { ok: false, reason: `${config.path} exists but is not valid JSON` };
+        }
+    }
+    else {
+        ensureDir(join(filePath, ".."));
+    }
+    const entries = existing[config.key] || {};
+    // Clean up the dead entry earlier releases wrote, and only that one: an
+    // "aisa" entry the user pointed somewhere else on purpose stays.
+    const stale = entries["aisa"];
+    if (stale?.url === DEAD_URL)
+        delete entries["aisa"];
+    for (const s of chosen) {
+        entries[`aisa-${s.slug}`] = buildEntry(config.shape, s.endpoint, key);
+    }
+    // The docs-search MCP is tiny, unauthenticated, and answers "how do I call
+    // this" questions — always included.
+    entries["aisa-docs"] = buildEntry(config.shape, DOCS_MCP_URL, undefined);
+    existing[config.key] = entries;
+    writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+    return { ok: true, written: chosen.length + 1 };
+}
+export async function mcpSetupAction(options) {
+    const requested = options.agent && options.agent !== "all" ? [options.agent] : Object.keys(MCP_CONFIGS);
+    for (const agent of requested) {
+        if (!MCP_CONFIGS[agent]) {
             error(`Unknown agent: ${agent}. Valid: ${Object.keys(MCP_CONFIGS).join(", ")}, all`);
             return;
         }
-        const filePath = expandHome(config.path);
-        let existing = {};
-        if (existsSync(filePath)) {
-            try {
-                existing = JSON.parse(readFileSync(filePath, "utf-8"));
-            }
-            catch {
-                existing = {};
-            }
+    }
+    // Write only where the client actually lives. Until 2026-08-25 `--agent all`
+    // (the default) wrote to every entry in MCP_CONFIGS whether or not it was
+    // installed, which on a machine without Windsurf created ~/.codeium/ and
+    // made the next `aisa connect` offer a card for an editor that was never
+    // there — this command's output became that command's input.
+    const installed = new Set(detectClients().filter((c) => c.detected).map((c) => c.id));
+    const targets = requested.filter((a) => installed.has(a));
+    const absent = requested.filter((a) => !installed.has(a));
+    for (const a of absent) {
+        console.log(`  ${chalk.gray("○")} ${a}: not installed — skipped`);
+    }
+    if (targets.length === 0) {
+        error("None of the requested clients are installed on this machine.");
+        hint("`aisa connect` detects what is here and walks you through it.");
+        process.exitCode = 1;
+        return;
+    }
+    // Fetch before touching any file: a setup that cannot see the manifest has
+    // nothing true to write.
+    let servers;
+    try {
+        servers = await fetchLiveServers();
+    }
+    catch (e) {
+        error(`Could not read the MCP manifest at ${MCP_MANIFEST_URL}: ${e.message}`);
+        hint("Nothing was written. Check your network and try again.");
+        process.exitCode = 1;
+        return;
+    }
+    const chosen = options.all
+        ? servers
+        : servers.filter((s) => MCP_DEFAULT_SLUGS.includes(s.slug));
+    const skipped = servers.length - chosen.length;
+    const key = getApiKey();
+    if (key) {
+        info("Using your configured API key (Bearer). It will be written into each client's config file.");
+    }
+    else {
+        info("No API key configured — entries are written without credentials, and the");
+        info("server's OAuth flow will open in your browser on first use.");
+    }
+    // Nothing is written without saying so first. This command used to change
+    // three config files the moment it was typed, with no preview and no way to
+    // ask what it would do — the opposite of `connect`, which shows the plan and
+    // waits. --yes is how a script opts back in to writing straight away.
+    if (!options.yes) {
+        info("This would write:");
+        for (const agent of targets) {
+            console.log(`  ${chalk.cyan(MCP_CONFIGS[agent].path)}  (${agent}, ${MCP_CONFIGS[agent].shape})`);
         }
-        else {
-            ensureDir(join(filePath, ".."));
+        for (const s of chosen) {
+            console.log(`    ${chalk.gray(`aisa-${s.slug}`)}  ${stripped(s.name)} (${s.toolCount} tools)`);
         }
-        const servers = existing[config.key] || {};
-        servers["aisa"] = { url: MCP_URL };
-        existing[config.key] = servers;
-        writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
-        console.log(`  ${chalk.green("✓")} ${agent}: ${config.path}`);
-        configured++;
+        hint("Nothing was written. Re-run with --yes to apply, or use `aisa connect` to choose interactively.");
+        return;
     }
-    if (configured > 0) {
-        success(`MCP server configured for ${configured} agent(s)`);
-        hint("Restart your agent/editor to activate");
+    for (const agent of targets) {
+        const config = MCP_CONFIGS[agent];
+        const result = writeClientConfig(agent, chosen, key);
+        if (!result.ok) {
+            error(`${agent}: ${result.reason} — refusing to overwrite it.`);
+            hint("Fix or remove the file, then re-run setup.");
+            continue;
+        }
+        console.log(`  ${chalk.green("✓")} ${agent}: ${result.written} servers (${config.shape}) → ${config.path}`);
+    }
+    success(`Configured ${chosen.length} live servers plus docs search for ${targets.length} client(s)`);
+    for (const s of chosen) {
+        console.log(`    ${chalk.cyan(`aisa-${s.slug}`)}  ${stripped(s.name)} (${s.toolCount} tools)`);
     }
+    if (skipped > 0)
+        hint(`${skipped} more live servers available — run with --all to configure every one`);
+    hint("Restart your agent/editor to activate");
 }
-export function mcpStatusAction() {
-    info(`MCP Server: ${MCP_URL}`);
+/**
+ * `aisa mcp status` — what is configured, and does it actually answer.
+ *
+ * The old status only checked that a config file contained an "aisa" key,
+ * which is exactly how a dead URL looked healthy. Reachability means a real
+ * HTTP exchange with each configured endpoint.
+ */
+export async function mcpStatusAction() {
+    const endpoints = new Map(); // endpoint -> [client/entry]
     for (const [agent, config] of Object.entries(MCP_CONFIGS)) {
         const filePath = expandHome(config.path);
-        if (existsSync(filePath)) {
-            try {
-                const data = JSON.parse(readFileSync(filePath, "utf-8"));
-                const servers = data[config.key];
-                if (servers?.["aisa"]) {
-                    console.log(`  ${chalk.green("✓")} ${agent}: configured`);
-                }
-                else {
-                    console.log(`  ${chalk.gray("○")} ${agent}: not configured`);
-                }
-            }
-            catch {
-                console.log(`  ${chalk.gray("○")} ${agent}: config unreadable`);
-            }
-        }
-        else {
+        if (!existsSync(filePath)) {
             console.log(`  ${chalk.gray("○")} ${agent}: not installed`);
+            continue;
         }
+        let entries = {};
+        try {
+            const data = JSON.parse(readFileSync(filePath, "utf-8"));
+            entries = data[config.key] || {};
+        }
+        catch {
+            console.log(`  ${chalk.gray("○")} ${agent}: config unreadable`);
+            continue;
+        }
+        const ours = Object.entries(entries).filter(([name]) => name.startsWith("aisa"));
+        if (ours.length === 0) {
+            console.log(`  ${chalk.gray("○")} ${agent}: not configured`);
+            continue;
+        }
+        console.log(`  ${chalk.green("✓")} ${agent}: ${ours.length} entries`);
+        for (const [name, entry] of ours) {
+            const e = entry;
+            const endpoint = e.url ?? e.args?.find((a) => a.startsWith("http"));
+            if (endpoint) {
+                const users = endpoints.get(endpoint) ?? [];
+                users.push(`${agent}/${name}`);
+                endpoints.set(endpoint, users);
+            }
+        }
+    }
+    if (endpoints.size === 0) {
+        hint("Run 'aisa mcp setup' to configure");
+        return;
+    }
+    console.log("");
+    info("Checking each configured endpoint:");
+    for (const [endpoint, users] of endpoints) {
+        console.log(`  ${endpoint}  ${chalk.gray(`(${users.length} entr${users.length > 1 ? "ies" : "y"})`)}`);
+        console.log(`    ${await pingEndpoint(endpoint)}`);
+    }
+}
+/**
+ * One initialize POST, no credentials. What each answer means:
+ *   200 -> alive and open (the docs MCP)
+ *   401 -> alive, auth required — the expected answer from mcp.aisa.one
+ *   anything else -> alive but odd; say so
+ *   network error -> the dead-hostname class this command exists to catch
+ */
+export async function pingEndpoint(endpoint) {
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "initialize",
+                params: {
+                    protocolVersion: "2025-06-18",
+                    capabilities: {},
+                    clientInfo: { name: "aisa-cli", version: "status" },
+                },
+            }),
+            signal: AbortSignal.timeout(8_000),
+        });
+        if (res.status === 200)
+            return `${chalk.green("✓")} reachable (open)`;
+        if (res.status === 401)
+            return `${chalk.green("✓")} reachable (auth required — normal)`;
+        return `${chalk.yellow("⚠")} reachable but answered HTTP ${res.status}`;
+    }
+    catch (e) {
+        return `${chalk.red("✗")} unreachable: ${e.message}`;
     }
-    hint("Run 'aisa mcp setup' to configure");
 }

package/dist/commands/oauth-login.d.ts

@@ -0,0 +1,33 @@
+import { type Lang } from "./flow.js";
+/**
+ * The whole sign-in, as a function other commands can embed: browser (or
+ * paste-back) OAuth, then the mint. Stores the key and returns it; throws on
+ * any failure. `aisa login` wraps this with CLI messaging; `aisa connect`
+ * runs it as its "Sign in to AIsa" step.
+ */
+/**
+ * Somewhere for the browser to land.
+ *
+ * `aisa login` on its own takes a random loopback port and serves one page on
+ * it. Inside `connect` that is the wrong shape: the sign-in opens in a second
+ * tab, and a random port has nothing to do with the run — the tab finishes on
+ * a page that knows nothing about the setup in progress and leaves the user
+ * to find their way back to the first tab themselves. Handing the run's own
+ * server in means the approval comes home to the address the setup already
+ * lives at, and the tab can return the reader to it.
+ */
+export interface OAuthCatcher {
+    /** Registered with the authorization server before the browser opens. */
+    redirectUri: string;
+    /** Resolves with the authorization code, or rejects with why it will not. */
+    wait(expectedState: string): Promise<string>;
+}
+export declare function mintCliKey(options?: {
+    open?: boolean;
+    lang?: Lang;
+    catcher?: OAuthCatcher;
+}): Promise<string>;
+export declare function oauthLogin(options?: {
+    open?: boolean;
+    lang?: Lang;
+}): Promise<void>;