@agent-native/core 0.48.3 → 0.49.0

package/dist/cli/connect.d.ts

@@ -0,0 +1,168 @@
+/**
+ * `agent-native connect <url>` — wire your local Claude Code / Codex / Cowork
+ * to a DEPLOYED agent-native app. OAuth-capable clients receive a standard
+ * remote MCP URL entry and authenticate in the host. Fallback clients use the
+ * browser device-code flow: open the verification URL, approve in the browser,
+ * and the minted HTTP MCP server entry is written idempotently.
+ *
+ *   agent-native connect <url> [--client all|claude-code|claude-code-cli|
+ *                               codex|cowork] [--scope user|project]
+ *                               [--name <serverName>]
+ *   agent-native reconnect [<url>] [--client ...] [--name <serverName>]
+ *   agent-native connect <url> --token <token>   (no-browser fallback)
+ *   agent-native connect        [--client ...]   (pick first-party apps)
+ *   agent-native connect --all  [--client ...]   (separate first-party app MCP resources)
+ *
+ * Server contract (implemented by another agent on `<url>`):
+ *   POST <url>/_agent-native/mcp/connect/device/start  (no auth)
+ *     body { client?, app? }
+ *     → { device_code, user_code, verification_uri,
+ *         verification_uri_complete, interval, expires_in }
+ *   POST <url>/_agent-native/mcp/connect/device/poll   (no auth)
+ *     body { device_code }
+ *     → { status: "pending" }
+ *     | { status: "approved", token, mcpUrl, serverName, mcpServerEntry }
+ *     | { status: "expired" }
+ *     | { status: "consumed" }
+ *     | { status: "error" | "not_found", message? }
+ *
+ * Node-only CLI module. Uses Node built-ins, @clack/prompts, and global fetch.
+ */
+import { ClientId } from "./mcp-config-writers.js";
+export interface ParsedConnectArgs {
+    /** Developer profile switch: local dev gateway or saved production config. */
+    mode?: "dev" | "prod" | "reauth" | "reconnect";
+    /** Positional URL (the deployed app origin). Undefined for `--all`. */
+    url?: string;
+    /** all | claude-code | claude-code-cli | codex | cowork (default "all"). */
+    client: string;
+    /** True when the user passed --client explicitly, so we skip the picker. */
+    clientExplicit: boolean;
+    /** user | project (default "user"). */
+    scope: string;
+    /** Override the minted MCP server name. */
+    name?: string;
+    /** No-browser fallback: skip device flow, use this token directly. */
+    token?: string;
+    /**
+     * Mint an ORG SERVICE token with this service name (e.g. "ci") instead of
+     * writing local MCP configs. Authenticates the human via the device flow,
+     * then calls the app's `create-org-service-token` action and prints the
+     * token once — for CI secrets like PLAN_RECAP_TOKEN.
+     */
+    serviceToken?: string;
+    /** Optional token TTL in days (1–365) for --service-token. */
+    ttlDays?: number;
+    /** Connect every first-party hosted app. */
+    all: boolean;
+    /** Comma-separated app names for profile switching. */
+    apps?: string;
+    /** Local dev-lazy gateway URL for `connect dev`. */
+    gateway?: string;
+    /** Shorthand for a local dev-lazy gateway port. */
+    port?: number;
+    /** Local owner email override for dev entries. */
+    ownerEmail?: string;
+    /**
+     * Embed `catalog_scope: "full"` in the minted token so the connected client
+     * bypasses the connector-catalog tier and sees the complete action surface,
+     * identical to the local/dev experience. Matches the `fullCatalog` body
+     * param on the app's token-mint route.
+     */
+    fullCatalog?: boolean;
+}
+export declare function parseConnectArgs(argv: string[]): ParsedConnectArgs;
+/**
+ * Normalize a user-supplied app URL: trim, require http/https, strip the
+ * trailing slash. Throws a friendly Error otherwise.
+ */
+export declare function normalizeUrl(raw: string): string;
+/** Resolve the requested clients list. "all" → every supported client. */
+export declare function resolveClients(client: string): ClientId[];
+export declare function connectPreferencesPath(): string;
+export declare function readConnectClientPreferences(file?: string): ClientId[] | null;
+export declare function writeConnectClientPreferences(clients: ClientId[], file?: string): void;
+export interface ConnectClientPromptContext {
+    initialClients: ClientId[];
+    options: {
+        value: ClientId;
+        label: string;
+        hint: string;
+    }[];
+    preferencesFile: string;
+}
+export interface HostedApp {
+    name: string;
+    label: string;
+    url: string;
+}
+export interface ConnectHostedAppsPromptContext {
+    apps: HostedApp[];
+    initialApps: string[];
+}
+export declare function supportsRemoteMcpOAuth(client: ClientId): boolean;
+/** Injectable hooks so the poll state machine is unit-testable. */
+export interface ConnectDeps {
+    /** Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Sleep between polls (ms). Defaults to real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Open the verification URL. Defaults to the platform browser opener. */
+    openBrowser?: (url: string) => void;
+    /** Override "now" for the expiry cap (ms epoch). Defaults to Date.now. */
+    now?: () => number;
+    /** Tests/embedders can force or suppress the interactive client picker. */
+    isInteractive?: () => boolean;
+    /** Injectable client picker. Defaults to @clack/prompts multiselect. */
+    promptClients?: (context: ConnectClientPromptContext) => Promise<ClientId[] | null>;
+    /** Injectable hosted app picker. Defaults to @clack/prompts multiselect. */
+    promptHostedApps?: (context: ConnectHostedAppsPromptContext) => Promise<string[] | null>;
+    /** Override the persisted connect preferences file. */
+    preferencesFile?: string;
+    /** Override the saved dev/prod profile file. */
+    profilesFile?: string;
+}
+/**
+ * Run the device-code flow against `baseUrl` and return the approved grant.
+ * Resolves with `null` (and prints a clear message) on expired/consumed or
+ * other terminal failure — the caller maps that to a non-zero exit.
+ */
+export declare function runDeviceFlow(baseUrl: string, appSlug: string, clientArg: string, deps?: ConnectDeps, options?: {
+    fullCatalog?: boolean;
+}): Promise<{
+    token?: string;
+    mcpUrl: string;
+    serverName: string;
+    headers?: Record<string, string>;
+} | null>;
+/**
+ * Write the HTTP MCP entry into every requested client config idempotently.
+ * Returns the list of files written so the caller can print them.
+ */
+export declare function writeConfigs(clients: ClientId[], serverName: string, mcpUrl: string, token: string | undefined, scope: string, baseDir?: string, headers?: Record<string, string>): {
+    client: ClientId;
+    file: string;
+}[];
+export declare function connectProfilesPath(): string;
+/** Hosted first-party apps: visible (non-hidden) templates with a prodUrl. */
+export declare function hostedApps(): HostedApp[];
+/**
+ * `agent-native connect <url> --service-token <name>` — mint an ORG service
+ * token for CI (e.g. the PLAN_RECAP_TOKEN GitHub secret).
+ *
+ * Flow: authenticate the human via the existing browser device flow, then use
+ * that short-lived grant to call the app's `create-org-service-token` action
+ * (org owner/admin gated server-side). The service token is printed exactly
+ * once and never written to any local config file.
+ */
+export declare function runServiceTokenMint(parsed: ParsedConnectArgs, deps?: ConnectDeps): Promise<boolean>;
+/**
+ * `agent-native connect` entry point. `deps` is injectable for tests; the
+ * dispatcher in index.ts calls it with just `args`.
+ *
+ * Sets `process.exitCode = 1` on failure (so the process exits non-zero
+ * once the event loop drains) rather than calling `process.exit`, keeping
+ * the function testable — same pattern as `audit-agent-web`.
+ */
+export declare function runConnect(args: string[], deps?: ConnectDeps): Promise<void>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/cli/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/cli/connect.ts"],"names":[],"mappings":"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"}

package/dist/cli/connect.js

@@ -33,7 +33,7 @@ import os from "node:os";
 import { spawn } from "node:child_process";
 import path from "node:path";
 import { findWorkspaceRoot } from "../mcp/workspace-resolve.js";
-import { CLIENTS, configPathFor, writeCodexBlock, writeHttpEntryForClient, writeJsonMcpEntry, } from "./mcp-config-writers.js";
+import { CLIENTS, configPathFor, removeSameUrlDuplicatesForClient, writeCodexBlock, writeHttpEntryForClient, writeJsonMcpEntry, } from "./mcp-config-writers.js";
 import { isFirstPartyPlanHost, writePlanPublishAuth, } from "./plan-publish-store.js";
 import { TEMPLATES, visibleTemplates } from "./templates-meta.js";
 const DEVICE_START_PATH = "/_agent-native/mcp/connect/device/start";
@@ -41,6 +41,17 @@ const DEVICE_POLL_PATH = "/_agent-native/mcp/connect/device/poll";
 const MCP_PATH = "/_agent-native/mcp";
 const SERVER_NAME_PREFIX = "agent-native";
 const CONNECT_PREFERENCES_VERSION = 1;
+/**
+ * Maps a normalised hosted MCP URL to the canonical server name for that
+ * first-party app. Kept in sync with BUILT_IN_APP_SKILLS in skills.ts (we
+ * cannot import from there — it imports connect.ts, which would be circular).
+ */
+const CANONICAL_SERVER_NAME_BY_MCP_URL = {
+    "https://plan.agent-native.com/_agent-native/mcp": "plan",
+    "https://assets.agent-native.com/_agent-native/mcp": "agent-native-assets",
+    "https://design.agent-native.com/_agent-native/mcp": "agent-native-design",
+    "https://context-xray.agent-native.com/_agent-native/mcp": "agent-native-context-xray",
+};
 const CONNECT_PROFILES_VERSION = 1;
 const DEFAULT_DEV_GATEWAY = "http://127.0.0.1:8080";
 const MCP_FULL_CATALOG_HEADER = "X-Agent-Native-MCP-Full-Catalog";
@@ -129,7 +140,7 @@ export function parseConnectArgs(argv) {
 export function normalizeUrl(raw) {
     const trimmed = (raw ?? "").trim();
     if (!trimmed) {
-        throw new Error("Missing app URL. Usage: agent-native connect <url>");
+        throw new Error("Missing app URL. Usage: npx @agent-native/core@latest connect <url>");
     }
     let parsed;
     try {
@@ -137,7 +148,7 @@ export function normalizeUrl(raw) {
     }
     catch {
         throw new Error(`Not a valid URL: "${raw}". Pass a full origin, e.g. ` +
-            `agent-native connect https://mail.agent-native.com`);
+            `npx @agent-native/core@latest connect https://mail.agent-native.com`);
     }
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
         throw new Error(`Unsupported URL scheme "${parsed.protocol}". Use http:// or https://`);
@@ -1137,7 +1148,7 @@ async function connectProdProfile(parsed, clients, deps) {
         for (const row of missing) {
             const app = apps.find((candidate) => candidate.name === row.app);
             logOut(`    ${row.app.padEnd(12)} ${row.client.padEnd(18)} ` +
-                `run: agent-native connect ${app?.url ?? "<url>"} --client ${row.client}`);
+                `run: npx @agent-native/core@latest connect ${app?.url ?? "<url>"} --client ${row.client}`);
         }
     }
     logOut("");
@@ -1159,7 +1170,23 @@ function distinctReconnectEntries(entries) {
 function describeReconnectEntry(entry) {
     return `${entry.serverName} (${entry.url}) in ${entry.client}`;
 }
-function resolveReconnectTarget(parsed, clients) {
+/**
+ * Return true when `url` is an agent-native MCP endpoint.
+ * Matches any URL whose path ends with `/_agent-native/mcp` (after stripping
+ * trailing slashes), regardless of the MCP server's name in the config.
+ */
+function isAgentNativeMcpUrl(url) {
+    if (!url)
+        return false;
+    try {
+        const pathname = new URL(url).pathname.replace(/\/+$/, "");
+        return pathname === MCP_PATH || pathname.endsWith(MCP_PATH);
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveReconnectTarget(parsed, clients, deps) {
     const baseDir = projectBaseDir();
     const scope = parsed.scope === "user" ? "user" : "project";
     const entries = readExistingMcpEntries(clients, baseDir, scope);
@@ -1181,28 +1208,78 @@ function resolveReconnectTarget(parsed, clients) {
         }
         return { rawUrl: parsed.url };
     }
-    const candidates = distinctReconnectEntries(parsed.name
+    // No URL provided: scan all configs for agent-native MCP entries by URL
+    // pattern, not by server name prefix. This finds the canonical "plan" entry
+    // (and any other custom-named entries) that the old prefix scan missed.
+    const agentNativeEntries = distinctReconnectEntries(parsed.name
         ? entries.filter((entry) => entry.serverName === parsed.name)
-        : entries.filter((entry) => entry.serverName.startsWith(`${SERVER_NAME_PREFIX}-`)));
-    if (candidates.length === 0) {
+        : entries.filter((entry) => isAgentNativeMcpUrl(entry.url)));
+    // Group by normalised URL so we can detect multi-app situations.
+    const byUrl = new Map();
+    for (const entry of agentNativeEntries) {
+        const key = canonicalMcpUrl(entry.url) ?? entry.url;
+        const bucket = byUrl.get(key) ?? [];
+        bucket.push(entry);
+        byUrl.set(key, bucket);
+    }
+    if (byUrl.size === 0) {
         logErr("  No existing Agent Native MCP entry found to reconnect.");
         logErr("  Pass a URL, or use --name <serverName> if the entry has a custom name.");
-        logErr("  First-time setup still uses: agent-native connect <url> --client <client>");
+        logErr("  First-time setup still uses: npx @agent-native/core@latest connect <url> --client <client>");
         return null;
     }
-    if (candidates.length > 1) {
-        logErr("  Found multiple Agent Native MCP entries:");
-        for (const entry of candidates) {
-            logErr(`    ${describeReconnectEntry(entry)}`);
+    if (byUrl.size === 1) {
+        // Exactly one distinct URL: prefer the entry whose serverName matches the
+        // canonical name for this app (e.g. "plan" over "agent-native-plans").
+        // Fall back to any entry whose name doesn't start with "agent-native-"
+        // (short canonical names like "plan"), then bucket[0].
+        const [url, bucket] = [...byUrl.entries()][0];
+        const canonicalName = CANONICAL_SERVER_NAME_BY_MCP_URL[url];
+        const preferred = (canonicalName
+            ? bucket.find((e) => e.serverName === canonicalName)
+            : undefined) ??
+            bucket.find((e) => !e.serverName.startsWith("agent-native-")) ??
+            bucket[0];
+        return { rawUrl: preferred.url, serverName: preferred.serverName };
+    }
+    // Multiple distinct URLs: pick interactively when TTY, else list with hints.
+    const urlList = [...byUrl.keys()];
+    if (shouldPrompt(deps)) {
+        const clack = await import("@clack/prompts");
+        const result = await clack.select({
+            message: "Multiple Agent Native apps found. Which one do you want to reconnect?",
+            options: urlList.map((u) => {
+                const representativeEntry = byUrl.get(u)[0];
+                return {
+                    value: u,
+                    label: representativeEntry.serverName,
+                    hint: u,
+                };
+            }),
+        });
+        if (clack.isCancel(result)) {
+            clack.cancel("Cancelled.");
+            return null;
         }
-        logErr("  Re-run with a URL or --name <serverName>.");
-        return null;
+        const chosen = byUrl.get(result)?.[0];
+        if (!chosen)
+            return null;
+        return { rawUrl: chosen.url, serverName: chosen.serverName };
+    }
+    logErr("  Found multiple Agent Native MCP entries:");
+    for (const [u, bucket] of byUrl) {
+        logErr(`    ${bucket[0].serverName} → ${u}`);
     }
-    const [entry] = candidates;
-    return { rawUrl: entry.url, serverName: entry.serverName };
+    logErr("  Re-run with a URL or --name <serverName>. For example:");
+    for (const u of urlList) {
+        // Strip the MCP path suffix for a cleaner reconnect URL suggestion.
+        const baseUrl = u.replace(/\/_agent-native\/mcp$/, "");
+        logErr(`    npx @agent-native/core@latest reconnect ${baseUrl}`);
+    }
+    return null;
 }
 async function reconnectOne(parsed, clients, deps) {
-    const target = resolveReconnectTarget(parsed, clients);
+    const target = await resolveReconnectTarget(parsed, clients, deps);
     if (!target)
         return false;
     const effectiveParsed = {
@@ -1274,6 +1351,17 @@ async function connectOne(rawUrl, parsed, clients, deps) {
         }
         allWritten.push(...writeConfigs(oauthClients, serverName, mcpUrl, undefined, scope, baseDir, undefined));
     }
+    // After writing the canonical entry, remove any same-URL duplicates (alias
+    // names, legacy default names, stale custom names) from the same config
+    // files so each app has exactly one MCP session.
+    const allRemovedNames = [];
+    for (const client of clients) {
+        const removed = removeSameUrlDuplicatesForClient(client, serverName, mcpUrl, baseDir, scope);
+        allRemovedNames.push(...removed);
+    }
+    if (allRemovedNames.length > 0) {
+        logOut(`  Removed duplicate MCP entries: ${[...new Set(allRemovedNames)].join(", ")}`);
+    }
     // Canonical publish-token write: when we have a real minted bearer token for
     // a first-party Plans app, also persist `{ url, token }` to
     // `~/.agent-native/plan-publish.json` so the local Plans server can read the
@@ -1431,7 +1519,7 @@ export async function runServiceTokenMint(parsed, deps = {}) {
     const serviceName = parsed.serviceToken?.trim() ?? "";
     if (!parsed.url) {
         logErr("  --service-token requires the app URL.");
-        logErr("  Usage: agent-native connect <url> --service-token <name> [--ttl-days <1-365>]");
+        logErr("  Usage: npx @agent-native/core@latest connect <url> --service-token <name> [--ttl-days <1-365>]");
         return false;
     }
     if (!serviceName) {
@@ -1504,14 +1592,14 @@ export async function runServiceTokenMint(parsed, deps = {}) {
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
-const HELP = `agent-native connect — wire your coding agent to a deployed app
+const HELP = `npx @agent-native/core@latest connect — wire your coding agent to a deployed app
 
 Usage:
-  agent-native connect [--client <c>] [--scope user|project]
+  npx @agent-native/core@latest connect [--client <c>] [--scope user|project]
       With no URL, opens a picker for the built-in hosted apps
       (mail.agent-native.com, calendar.agent-native.com, and friends).
 
-  agent-native connect <url> [--client <c>] [--scope user|project] [--name <n>]
+  npx @agent-native/core@latest connect <url> [--client <c>] [--scope user|project] [--name <n>]
       Writes the HTTP MCP entry into your selected client config(s). Claude
       Code / Claude Code CLI use standard remote MCP OAuth: restart Claude,
       run /mcp, and choose Authenticate. Codex / Cowork use the browser
@@ -1523,13 +1611,13 @@ Usage:
       OAuth config and prompts you to authenticate with /mcp.
 
       For cross-app access, prefer the unified Dispatch gateway:
-      agent-native connect https://dispatch.agent-native.com
+      npx @agent-native/core@latest connect https://dispatch.agent-native.com
 
-  agent-native connect <url> --token <token>
+  npx @agent-native/core@latest connect <url> --token <token>
       No-browser fallback. Skip the device flow and write the entry with
       the supplied token (get it from the app's Connect page).
 
-  agent-native connect <url> --service-token <name> [--ttl-days <1-365>]
+  npx @agent-native/core@latest connect <url> --service-token <name> [--ttl-days <1-365>]
       Mint an ORG service token for CI (e.g. the PLAN_RECAP_TOKEN secret for
       PR Visual Recap). Authenticates you via the browser device flow, then
       mints a token owned by your ORGANIZATION — it keeps working if you
@@ -1537,22 +1625,22 @@ Usage:
       org-visible. Org owner/admin only. Printed once; nothing is written
       to local MCP configs.
 
-  agent-native reconnect [<url>] [--client <c>] [--scope user|project]
-  agent-native connect reconnect [<url>] [--client <c>] [--scope user|project]
+  npx @agent-native/core@latest reconnect [<url>] [--client <c>] [--scope user|project]
+  npx @agent-native/core@latest connect reconnect [<url>] [--client <c>] [--scope user|project]
       Re-authenticate an existing MCP entry without reinstalling apps/skills.
       With a URL, it reuses the existing server name for that MCP URL when
       possible. Without a URL, it reconnects the only matching Agent Native
       entry in the selected client config. Use --name for custom server names.
 
-  agent-native connect --all [--client <c>] [--scope user|project]
+  npx @agent-native/core@latest connect --all [--client <c>] [--scope user|project]
       Connect every first-party hosted app as separate MCP resources.
 
 Developer:
-  agent-native connect dev [--apps mail,calendar] [--client <c>]
+  npx @agent-native/core@latest connect dev [--apps mail,calendar] [--client <c>]
       Switch selected first-party MCP entries to a local dev-lazy gateway.
       Defaults to ${DEFAULT_DEV_GATEWAY}; override with --gateway or --port.
 
-  agent-native connect prod [--apps mail,calendar] [--client <c>]
+  npx @agent-native/core@latest connect prod [--apps mail,calendar] [--client <c>]
       Restore production MCP entries saved before the dev switch.
 
 Clients:  all (default), claude-code, claude-code-cli, codex, cowork