workos 0.17.0 → 0.18.0

package/dist/lib/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAS1C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,aAAa,EAAE,gBAAgB;IAC/B,WAAW,EAAE,cAAc;IAC3B,SAAS,EAAE,YAAY;CACf,CAAC;AAOX,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AAEnF,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;AAE7B,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC;AACxE,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC;AAC5D,MAAM,CAAC,MAAM,gCAAgC,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAa;IACvC,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,aAAa;CACd,CAAC","sourcesContent":["import { getConfig } from './settings.js';\n\n/**\n * Integration identifier type.\n * No longer an enum — each integration self-registers via the auto-discovery registry.\n * The string value matches the integration directory name (e.g., 'nextjs', 'react-router').\n */\nexport type Integration = string;\n\n/**\n * Well-known integration names for backwards compatibility.\n * New integrations do NOT need to be added here — they're auto-discovered.\n */\nexport const KNOWN_INTEGRATIONS = {\n  nextjs: 'nextjs',\n  react: 'react',\n  tanstackStart: 'tanstack-start',\n  reactRouter: 'react-router',\n  vanillaJs: 'vanilla-js',\n} as const;\n\nexport interface Args {\n  debug: boolean;\n  integration: Integration;\n}\n\nexport const IS_DEV = ['test', 'development'].includes(process.env.NODE_ENV ?? '');\n\nconst settings = getConfig();\n\nexport const DEBUG = settings.logging.debugMode;\nexport const WORKOS_DOCS_URL = settings.documentation.workosDocsUrl;\nexport const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;\nexport const ISSUES_URL = settings.documentation.issuesUrl;\nexport const ANALYTICS_ENABLED = settings.telemetry.enabled;\nexport const INSTALLER_INTERACTION_EVENT_NAME = settings.telemetry.eventName;\nexport const OAUTH_PORT = settings.legacy.oauthPort;\n\n/**\n * Common glob patterns to ignore when searching for files.\n * Used by multiple integrations.\n */\nexport const IGNORE_PATTERNS: string[] = [\n  '**/node_modules/**',\n  '**/dist/**',\n  '**/build/**',\n  '**/public/**',\n  '**/.next/**',\n];\n"]}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAS1C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,aAAa,EAAE,gBAAgB;IAC/B,WAAW,EAAE,cAAc;IAC3B,SAAS,EAAE,YAAY;CACf,CAAC;AAOX,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AAEnF,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;AAE7B,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC;AACxE,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC;AAC5D,MAAM,CAAC,MAAM,gCAAgC,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC;AACxC,MAAM,CAAC,MAAM,cAAc,GAAG,4BAA4B,CAAC;AAE3D;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAa;IACvC,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,aAAa;CACd,CAAC","sourcesContent":["import { getConfig } from './settings.js';\n\n/**\n * Integration identifier type.\n * No longer an enum — each integration self-registers via the auto-discovery registry.\n * The string value matches the integration directory name (e.g., 'nextjs', 'react-router').\n */\nexport type Integration = string;\n\n/**\n * Well-known integration names for backwards compatibility.\n * New integrations do NOT need to be added here — they're auto-discovered.\n */\nexport const KNOWN_INTEGRATIONS = {\n  nextjs: 'nextjs',\n  react: 'react',\n  tanstackStart: 'tanstack-start',\n  reactRouter: 'react-router',\n  vanillaJs: 'vanilla-js',\n} as const;\n\nexport interface Args {\n  debug: boolean;\n  integration: Integration;\n}\n\nexport const IS_DEV = ['test', 'development'].includes(process.env.NODE_ENV ?? '');\n\nconst settings = getConfig();\n\nexport const DEBUG = settings.logging.debugMode;\nexport const WORKOS_DOCS_URL = settings.documentation.workosDocsUrl;\nexport const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;\nexport const ISSUES_URL = settings.documentation.issuesUrl;\nexport const ANALYTICS_ENABLED = settings.telemetry.enabled;\nexport const INSTALLER_INTERACTION_EVENT_NAME = settings.telemetry.eventName;\nexport const OAUTH_PORT = settings.legacy.oauthPort;\n\n/**\n * WorkOS MCP server identity, shared by the `mcp` command group and the\n * per-client writers in `lib/mcp-clients.ts`.\n *\n * The server is secret-free: HTTP transport with OAuth handled by each client\n * on first connect, so configuring it never requires CLI auth.\n */\nexport const MCP_SERVER_NAME = 'workos';\nexport const MCP_SERVER_URL = 'https://mcp.workos.com/mcp';\n\n/**\n * Common glob patterns to ignore when searching for files.\n * Used by multiple integrations.\n */\nexport const IGNORE_PATTERNS: string[] = [\n  '**/node_modules/**',\n  '**/dist/**',\n  '**/build/**',\n  '**/public/**',\n  '**/.next/**',\n];\n"]}

package/dist/lib/installer-core.d.ts

@@ -42,54 +42,54 @@ export declare const installerMachine: import("xstate").StateMachine<InstallerMa
 } | {
     type: "PR_DECLINED";
 }, {
-    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<string, {
-        title: string;
-        body: string;
-        cwd: string;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<boolean, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<boolean, {
         options: InstallerOptions;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<WorkspaceCheckOutput, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<WorkspaceCheckOutput, {
         options: InstallerOptions;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<void, {
         context: InstallerMachineContext;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<DetectionOutput, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<DetectionOutput, {
         options: InstallerOptions;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<GitCheckOutput, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<GitCheckOutput, {
         installDir: string;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<void, {
         context: InstallerMachineContext;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<AgentOutput, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<AgentOutput, {
         context: InstallerMachineContext;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<EnvFileInfo, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<EnvFileInfo, {
         installDir: string;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<DiscoveryResult, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<DiscoveryResult, {
         installDir: string;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<boolean, void, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<{
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<boolean, void, import("xstate").EventObject> | import("xstate").PromiseActorLogic<{
         result: DeviceAuthResult;
         deviceAuth: DeviceAuthResponse;
     }, {
         emitter: InstallerMachineContext["emitter"];
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<StagingCredentials, void, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<BranchCheckOutput, void, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<{
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<StagingCredentials, void, import("xstate").EventObject> | import("xstate").PromiseActorLogic<BranchCheckOutput, void, import("xstate").EventObject> | import("xstate").PromiseActorLogic<{
         branch: string;
     }, {
         name: string;
         fallbackName: string;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<{
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<{
         hasChanges: boolean;
         files: string[];
-    }, void, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<string, {
+    }, void, import("xstate").EventObject> | import("xstate").PromiseActorLogic<string, {
         integration: string;
         files: string[];
         direct?: boolean;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<void, {
         message: string;
         cwd: string;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<string, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<string, {
         integration: string;
         files: string[];
         commitMessage: string;
         direct?: boolean;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, {
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<void, {
+        cwd: string;
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<string, {
+        title: string;
+        body: string;
         cwd: string;
     }, import("xstate").EventObject>> | undefined;
 }, {

package/dist/lib/mcp-clients.d.ts

@@ -0,0 +1,39 @@
+export type McpAgentKey = 'claude-code' | 'codex' | 'cursor';
+export type McpOutcome = 'installed' | 'already-installed' | 'removed' | 'not-installed' | 'skipped' | 'failed';
+export interface McpClientResult {
+    agent: McpAgentKey;
+    displayName: string;
+    outcome: McpOutcome;
+    /** stderr/message excerpt when `outcome === 'failed'`. */
+    error?: string;
+}
+export interface McpClientTarget {
+    key: McpAgentKey;
+    displayName: string;
+    /** Agent is usable on this machine (config dir present AND, for CLI clients, binary runnable). */
+    isAvailable(): Promise<boolean>;
+    /** The WorkOS server is present in this client's config. */
+    isInstalled(): Promise<boolean>;
+    add(): Promise<McpClientResult>;
+    remove(): Promise<McpClientResult>;
+}
+/** Stable list of known agent keys, for `--agent` validation by callers. */
+export declare const MCP_AGENT_KEYS: McpAgentKey[];
+/** The three client targets, in a stable order. */
+export declare function createMcpClients(): McpClientTarget[];
+/**
+ * The URL the WorkOS server is configured with in Cursor's `~/.cursor/mcp.json`,
+ * or null when the file/entry is absent, unreadable, or unparseable.
+ *
+ * Cursor is the only client whose config we read directly (the CLI clients don't
+ * expose per-entry URLs), so this powers doctor's URL-drift ("misconfigured")
+ * check without a second jsonc reader duplicating the config schema. Read-only
+ * and never throws — a problem reading just yields null.
+ */
+export declare function getCursorConfiguredUrl(): Promise<string | null>;
+/**
+ * Return only the clients available on this machine, optionally narrowed to
+ * `agentFilter` keys. Availability is probed in parallel. An unknown filter key
+ * simply matches nothing here — callers validate keys and surface the error.
+ */
+export declare function detectMcpClients(agentFilter?: string[]): Promise<McpClientTarget[]>;

package/dist/lib/mcp-clients.js

@@ -0,0 +1,284 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { access, mkdir, readFile, writeFile } from 'fs/promises';
+import * as jsonc from 'jsonc-parser';
+import { execFileNoThrow } from '../utils/exec-file.js';
+import { MCP_SERVER_NAME, MCP_SERVER_URL } from './constants.js';
+/**
+ * Client-writer library for the WorkOS MCP server.
+ *
+ * One `McpClientTarget` interface, three implementations. Claude Code and Codex
+ * are configured by shelling out to their own CLIs (robust to their config
+ * format changes); Cursor has no CLI, so we merge `~/.cursor/mcp.json` directly
+ * with `jsonc-parser` (hand-edited files may contain comments / trailing
+ * commas). Every operation degrades to a reported outcome — a missing binary,
+ * an old client without HTTP-transport support, or an unparseable config is a
+ * `failed`/`skipped`/`not-installed` result, never a thrown error.
+ *
+ * The library owns detection and per-client config writing; callers (the `mcp`
+ * command today; install-flow / doctor in Phase 2) stay thin. Nothing here may
+ * assume it runs inside the `mcp` command.
+ */
+/** 10s ceiling on every CLI shell-out so a hung client can't wedge the caller. */
+const EXEC_TIMEOUT_MS = 10_000;
+/** jsonc parse options: tolerate the comments / trailing commas real users
+ * hand-edit into `~/.cursor/mcp.json`, and an empty file, so only genuinely
+ * malformed JSON is flagged. */
+const JSONC_PARSE_OPTIONS = {
+    allowTrailingComma: true,
+    allowEmptyContent: true,
+};
+const JSONC_MODIFY_OPTIONS = {
+    formattingOptions: { tabSize: 2, insertSpaces: true },
+};
+/** Stable list of known agent keys, for `--agent` validation by callers. */
+export const MCP_AGENT_KEYS = ['claude-code', 'codex', 'cursor'];
+/** Async existence check — `access` rejects with ENOENT when the path is missing. */
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Trim a shell-out message to a single-line excerpt for the `error` field. */
+function excerpt(raw) {
+    const text = raw.trim();
+    if (!text)
+        return 'Unknown error';
+    const firstLine = text.split('\n').find((l) => l.trim().length > 0) ?? text;
+    return firstLine.trim().slice(0, 300);
+}
+/**
+ * Does a CLI `mcp list` output contain our server?
+ *
+ * Matches the first whitespace-delimited token of any line (with an optional
+ * trailing colon stripped), which covers both list shapes we support:
+ *   - Claude Code:  `workos: https://mcp.workos.com/mcp (HTTP) - ✔ Connected`
+ *   - Codex table:  `workos   https://mcp.workos.com/mcp   ...`
+ *
+ * First-token matching avoids the substring collision a naive
+ * `output.includes('workos')` would hit on an unrelated `workos-docs` entry.
+ */
+function listHasServer(stdout, name) {
+    return stdout.split('\n').some((line) => {
+        const firstToken = line.trim().split(/\s+/)[0] ?? '';
+        return firstToken.replace(/:$/, '') === name;
+    });
+}
+/**
+ * Shared shell-out client for Claude Code and Codex. The two differ only in
+ * binary name, config dir, and the `add` arg shape; every outcome-mapping rule
+ * is identical, so they share one implementation.
+ */
+function createCliClient(config) {
+    const { key, displayName, binary, configDir, addArgs, removeArgs } = config;
+    const result = (outcome, error) => ({
+        agent: key,
+        displayName,
+        outcome,
+        ...(error ? { error } : {}),
+    });
+    async function checkInstalled() {
+        const res = await execFileNoThrow(binary, ['mcp', 'list'], { timeout: EXEC_TIMEOUT_MS });
+        if (res.status !== 0)
+            return false;
+        return listHasServer(res.stdout, MCP_SERVER_NAME);
+    }
+    return {
+        key,
+        displayName,
+        async isAvailable() {
+            // Two layers: the config dir can exist while the binary isn't on PATH,
+            // and vice versa — require both before we try to shell out.
+            if (!(await pathExists(join(homedir(), configDir))))
+                return false;
+            const res = await execFileNoThrow(binary, ['--version'], { timeout: EXEC_TIMEOUT_MS });
+            return res.status === 0;
+        },
+        isInstalled: checkInstalled,
+        async add() {
+            const res = await execFileNoThrow(binary, addArgs, { timeout: EXEC_TIMEOUT_MS });
+            if (res.status === 0)
+                return result('installed');
+            // Idempotent: an "already exists" collision is a success, not a failure.
+            const combined = `${res.stdout}\n${res.stderr}`.toLowerCase();
+            if (combined.includes('already exists') || combined.includes('already configured')) {
+                return result('already-installed');
+            }
+            // A non-zero exit doesn't always mean the write failed: Codex persists the
+            // server config and THEN starts an OAuth flow that blocks (no browser /
+            // callback available here) until our timeout kills it with a non-zero
+            // status. Confirm against the actual config before declaring failure —
+            // more robust than matching each client's success wording.
+            if (await checkInstalled())
+                return result('installed');
+            // Otherwise a real failure — an old client lacking `--transport http` /
+            // `--url`, a bad invocation, etc. Reported, never thrown.
+            return result('failed', excerpt(res.stderr || res.stdout));
+        },
+        async remove() {
+            const res = await execFileNoThrow(binary, removeArgs, { timeout: EXEC_TIMEOUT_MS });
+            const combined = `${res.stdout}\n${res.stderr}`.toLowerCase();
+            // Claude exits 1 and Codex exits 0 when the server is absent; both print
+            // "No MCP server named ...". Treat either as an idempotent no-op.
+            if (combined.includes('no mcp server'))
+                return result('not-installed');
+            if (res.status === 0)
+                return result('removed');
+            return result('failed', excerpt(res.stderr || res.stdout));
+        },
+    };
+}
+function createClaudeCodeClient() {
+    return createCliClient({
+        key: 'claude-code',
+        displayName: 'Claude Code',
+        binary: 'claude',
+        configDir: '.claude',
+        // User scope: the management MCP is account-level, not per-repo — project
+        // scope would nag teammates via checked-in config.
+        addArgs: ['mcp', 'add', '--transport', 'http', '--scope', 'user', MCP_SERVER_NAME, MCP_SERVER_URL],
+        removeArgs: ['mcp', 'remove', '--scope', 'user', MCP_SERVER_NAME],
+    });
+}
+function createCodexClient() {
+    return createCliClient({
+        key: 'codex',
+        displayName: 'Codex',
+        binary: 'codex',
+        configDir: '.codex',
+        addArgs: ['mcp', 'add', MCP_SERVER_NAME, '--url', MCP_SERVER_URL],
+        removeArgs: ['mcp', 'remove', MCP_SERVER_NAME],
+    });
+}
+/**
+ * Cursor has no CLI, so we read-modify-write `~/.cursor/mcp.json` directly with
+ * `jsonc-parser`, preserving existing servers, comments, and formatting.
+ */
+function createCursorClient() {
+    const key = 'cursor';
+    const displayName = 'Cursor';
+    const cursorDir = () => join(homedir(), '.cursor');
+    const configPath = () => join(cursorDir(), 'mcp.json');
+    const result = (outcome, error) => ({
+        agent: key,
+        displayName,
+        outcome,
+        ...(error ? { error } : {}),
+    });
+    /** Read + parse the config. `parseError` is true only for genuinely malformed
+     * JSON (not comments / trailing commas / empty). */
+    async function readConfig() {
+        const path = configPath();
+        if (!(await pathExists(path))) {
+            return { content: '', parsed: undefined, parseError: false, exists: false };
+        }
+        const content = await readFile(path, 'utf8');
+        const errors = [];
+        const parsed = jsonc.parse(content, errors, JSONC_PARSE_OPTIONS);
+        return { content, parsed, parseError: errors.length > 0, exists: true };
+    }
+    function hasWorkosServer(parsed) {
+        const servers = parsed?.mcpServers;
+        return Boolean(servers && typeof servers === 'object' && MCP_SERVER_NAME in servers);
+    }
+    return {
+        key,
+        displayName,
+        async isAvailable() {
+            return pathExists(cursorDir());
+        },
+        async isInstalled() {
+            try {
+                const { parsed, parseError } = await readConfig();
+                if (parseError)
+                    return false;
+                return hasWorkosServer(parsed);
+            }
+            catch {
+                return false;
+            }
+        },
+        async add() {
+            const path = configPath();
+            try {
+                const { content, parseError, exists } = await readConfig();
+                // Never overwrite a file we couldn't parse — the user must fix it first.
+                if (exists && parseError) {
+                    return result('failed', `Could not parse ${path}; fix it manually and retry.`);
+                }
+                await mkdir(cursorDir(), { recursive: true });
+                // Converge to our URL — an existing `workos` key with a different URL is
+                // overwritten (reported as `installed`).
+                const edits = jsonc.modify(content, ['mcpServers', MCP_SERVER_NAME], { url: MCP_SERVER_URL }, JSONC_MODIFY_OPTIONS);
+                await writeFile(path, jsonc.applyEdits(content, edits), 'utf8');
+                return result('installed');
+            }
+            catch (error) {
+                return result('failed', error instanceof Error ? error.message : 'Unknown error');
+            }
+        },
+        async remove() {
+            const path = configPath();
+            try {
+                const { content, parsed, parseError, exists } = await readConfig();
+                if (!exists)
+                    return result('not-installed');
+                if (parseError) {
+                    return result('failed', `Could not parse ${path}; fix it manually and retry.`);
+                }
+                if (!hasWorkosServer(parsed))
+                    return result('not-installed');
+                const edits = jsonc.modify(content, ['mcpServers', MCP_SERVER_NAME], undefined, JSONC_MODIFY_OPTIONS);
+                await writeFile(path, jsonc.applyEdits(content, edits), 'utf8');
+                return result('removed');
+            }
+            catch (error) {
+                return result('failed', error instanceof Error ? error.message : 'Unknown error');
+            }
+        },
+    };
+}
+/** The three client targets, in a stable order. */
+export function createMcpClients() {
+    return [createClaudeCodeClient(), createCodexClient(), createCursorClient()];
+}
+/**
+ * The URL the WorkOS server is configured with in Cursor's `~/.cursor/mcp.json`,
+ * or null when the file/entry is absent, unreadable, or unparseable.
+ *
+ * Cursor is the only client whose config we read directly (the CLI clients don't
+ * expose per-entry URLs), so this powers doctor's URL-drift ("misconfigured")
+ * check without a second jsonc reader duplicating the config schema. Read-only
+ * and never throws — a problem reading just yields null.
+ */
+export async function getCursorConfiguredUrl() {
+    try {
+        const path = join(homedir(), '.cursor', 'mcp.json');
+        if (!(await pathExists(path)))
+            return null;
+        const content = await readFile(path, 'utf8');
+        const parsed = jsonc.parse(content, [], JSONC_PARSE_OPTIONS);
+        const servers = parsed?.mcpServers;
+        const entry = servers?.[MCP_SERVER_NAME];
+        return typeof entry?.url === 'string' ? entry.url : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Return only the clients available on this machine, optionally narrowed to
+ * `agentFilter` keys. Availability is probed in parallel. An unknown filter key
+ * simply matches nothing here — callers validate keys and surface the error.
+ */
+export async function detectMcpClients(agentFilter) {
+    const clients = createMcpClients();
+    const filtered = agentFilter ? clients.filter((c) => agentFilter.includes(c.key)) : clients;
+    const availability = await Promise.all(filtered.map((c) => c.isAvailable()));
+    return filtered.filter((_, i) => availability[i]);
+}
+//# sourceMappingURL=mcp-clients.js.map

package/dist/lib/mcp-clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-clients.js","sourceRoot":"","sources":["../../src/lib/mcp-clients.ts"],"names":[],"mappings":"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","sourcesContent":["import { homedir } from 'os';\nimport { join } from 'path';\nimport { access, mkdir, readFile, writeFile } from 'fs/promises';\nimport * as jsonc from 'jsonc-parser';\nimport { execFileNoThrow } from '../utils/exec-file.js';\nimport { MCP_SERVER_NAME, MCP_SERVER_URL } from './constants.js';\n\n/**\n * Client-writer library for the WorkOS MCP server.\n *\n * One `McpClientTarget` interface, three implementations. Claude Code and Codex\n * are configured by shelling out to their own CLIs (robust to their config\n * format changes); Cursor has no CLI, so we merge `~/.cursor/mcp.json` directly\n * with `jsonc-parser` (hand-edited files may contain comments / trailing\n * commas). Every operation degrades to a reported outcome — a missing binary,\n * an old client without HTTP-transport support, or an unparseable config is a\n * `failed`/`skipped`/`not-installed` result, never a thrown error.\n *\n * The library owns detection and per-client config writing; callers (the `mcp`\n * command today; install-flow / doctor in Phase 2) stay thin. Nothing here may\n * assume it runs inside the `mcp` command.\n */\n\n/** 10s ceiling on every CLI shell-out so a hung client can't wedge the caller. */\nconst EXEC_TIMEOUT_MS = 10_000;\n\n/** jsonc parse options: tolerate the comments / trailing commas real users\n * hand-edit into `~/.cursor/mcp.json`, and an empty file, so only genuinely\n * malformed JSON is flagged. */\nconst JSONC_PARSE_OPTIONS: jsonc.ParseOptions = {\n  allowTrailingComma: true,\n  allowEmptyContent: true,\n};\n\nconst JSONC_MODIFY_OPTIONS: jsonc.ModificationOptions = {\n  formattingOptions: { tabSize: 2, insertSpaces: true },\n};\n\nexport type McpAgentKey = 'claude-code' | 'codex' | 'cursor';\n\nexport type McpOutcome = 'installed' | 'already-installed' | 'removed' | 'not-installed' | 'skipped' | 'failed';\n\nexport interface McpClientResult {\n  agent: McpAgentKey;\n  displayName: string;\n  outcome: McpOutcome;\n  /** stderr/message excerpt when `outcome === 'failed'`. */\n  error?: string;\n}\n\nexport interface McpClientTarget {\n  key: McpAgentKey;\n  displayName: string;\n  /** Agent is usable on this machine (config dir present AND, for CLI clients, binary runnable). */\n  isAvailable(): Promise<boolean>;\n  /** The WorkOS server is present in this client's config. */\n  isInstalled(): Promise<boolean>;\n  add(): Promise<McpClientResult>;\n  remove(): Promise<McpClientResult>;\n}\n\n/** Stable list of known agent keys, for `--agent` validation by callers. */\nexport const MCP_AGENT_KEYS: McpAgentKey[] = ['claude-code', 'codex', 'cursor'];\n\n/** Async existence check — `access` rejects with ENOENT when the path is missing. */\nasync function pathExists(p: string): Promise<boolean> {\n  try {\n    await access(p);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** Trim a shell-out message to a single-line excerpt for the `error` field. */\nfunction excerpt(raw: string): string {\n  const text = raw.trim();\n  if (!text) return 'Unknown error';\n  const firstLine = text.split('\\n').find((l) => l.trim().length > 0) ?? text;\n  return firstLine.trim().slice(0, 300);\n}\n\n/**\n * Does a CLI `mcp list` output contain our server?\n *\n * Matches the first whitespace-delimited token of any line (with an optional\n * trailing colon stripped), which covers both list shapes we support:\n *   - Claude Code:  `workos: https://mcp.workos.com/mcp (HTTP) - ✔ Connected`\n *   - Codex table:  `workos   https://mcp.workos.com/mcp   ...`\n *\n * First-token matching avoids the substring collision a naive\n * `output.includes('workos')` would hit on an unrelated `workos-docs` entry.\n */\nfunction listHasServer(stdout: string, name: string): boolean {\n  return stdout.split('\\n').some((line) => {\n    const firstToken = line.trim().split(/\\s+/)[0] ?? '';\n    return firstToken.replace(/:$/, '') === name;\n  });\n}\n\n/**\n * Shared shell-out client for Claude Code and Codex. The two differ only in\n * binary name, config dir, and the `add` arg shape; every outcome-mapping rule\n * is identical, so they share one implementation.\n */\nfunction createCliClient(config: {\n  key: McpAgentKey;\n  displayName: string;\n  binary: string;\n  configDir: string;\n  addArgs: string[];\n  removeArgs: string[];\n}): McpClientTarget {\n  const { key, displayName, binary, configDir, addArgs, removeArgs } = config;\n  const result = (outcome: McpOutcome, error?: string): McpClientResult => ({\n    agent: key,\n    displayName,\n    outcome,\n    ...(error ? { error } : {}),\n  });\n\n  async function checkInstalled(): Promise<boolean> {\n    const res = await execFileNoThrow(binary, ['mcp', 'list'], { timeout: EXEC_TIMEOUT_MS });\n    if (res.status !== 0) return false;\n    return listHasServer(res.stdout, MCP_SERVER_NAME);\n  }\n\n  return {\n    key,\n    displayName,\n    async isAvailable() {\n      // Two layers: the config dir can exist while the binary isn't on PATH,\n      // and vice versa — require both before we try to shell out.\n      if (!(await pathExists(join(homedir(), configDir)))) return false;\n      const res = await execFileNoThrow(binary, ['--version'], { timeout: EXEC_TIMEOUT_MS });\n      return res.status === 0;\n    },\n    isInstalled: checkInstalled,\n    async add() {\n      const res = await execFileNoThrow(binary, addArgs, { timeout: EXEC_TIMEOUT_MS });\n      if (res.status === 0) return result('installed');\n      // Idempotent: an \"already exists\" collision is a success, not a failure.\n      const combined = `${res.stdout}\\n${res.stderr}`.toLowerCase();\n      if (combined.includes('already exists') || combined.includes('already configured')) {\n        return result('already-installed');\n      }\n      // A non-zero exit doesn't always mean the write failed: Codex persists the\n      // server config and THEN starts an OAuth flow that blocks (no browser /\n      // callback available here) until our timeout kills it with a non-zero\n      // status. Confirm against the actual config before declaring failure —\n      // more robust than matching each client's success wording.\n      if (await checkInstalled()) return result('installed');\n      // Otherwise a real failure — an old client lacking `--transport http` /\n      // `--url`, a bad invocation, etc. Reported, never thrown.\n      return result('failed', excerpt(res.stderr || res.stdout));\n    },\n    async remove() {\n      const res = await execFileNoThrow(binary, removeArgs, { timeout: EXEC_TIMEOUT_MS });\n      const combined = `${res.stdout}\\n${res.stderr}`.toLowerCase();\n      // Claude exits 1 and Codex exits 0 when the server is absent; both print\n      // \"No MCP server named ...\". Treat either as an idempotent no-op.\n      if (combined.includes('no mcp server')) return result('not-installed');\n      if (res.status === 0) return result('removed');\n      return result('failed', excerpt(res.stderr || res.stdout));\n    },\n  };\n}\n\nfunction createClaudeCodeClient(): McpClientTarget {\n  return createCliClient({\n    key: 'claude-code',\n    displayName: 'Claude Code',\n    binary: 'claude',\n    configDir: '.claude',\n    // User scope: the management MCP is account-level, not per-repo — project\n    // scope would nag teammates via checked-in config.\n    addArgs: ['mcp', 'add', '--transport', 'http', '--scope', 'user', MCP_SERVER_NAME, MCP_SERVER_URL],\n    removeArgs: ['mcp', 'remove', '--scope', 'user', MCP_SERVER_NAME],\n  });\n}\n\nfunction createCodexClient(): McpClientTarget {\n  return createCliClient({\n    key: 'codex',\n    displayName: 'Codex',\n    binary: 'codex',\n    configDir: '.codex',\n    addArgs: ['mcp', 'add', MCP_SERVER_NAME, '--url', MCP_SERVER_URL],\n    removeArgs: ['mcp', 'remove', MCP_SERVER_NAME],\n  });\n}\n\n/**\n * Cursor has no CLI, so we read-modify-write `~/.cursor/mcp.json` directly with\n * `jsonc-parser`, preserving existing servers, comments, and formatting.\n */\nfunction createCursorClient(): McpClientTarget {\n  const key: McpAgentKey = 'cursor';\n  const displayName = 'Cursor';\n  const cursorDir = () => join(homedir(), '.cursor');\n  const configPath = () => join(cursorDir(), 'mcp.json');\n  const result = (outcome: McpOutcome, error?: string): McpClientResult => ({\n    agent: key,\n    displayName,\n    outcome,\n    ...(error ? { error } : {}),\n  });\n\n  /** Read + parse the config. `parseError` is true only for genuinely malformed\n   * JSON (not comments / trailing commas / empty). */\n  async function readConfig(): Promise<{\n    content: string;\n    parsed: Record<string, unknown> | undefined;\n    parseError: boolean;\n    exists: boolean;\n  }> {\n    const path = configPath();\n    if (!(await pathExists(path))) {\n      return { content: '', parsed: undefined, parseError: false, exists: false };\n    }\n    const content = await readFile(path, 'utf8');\n    const errors: jsonc.ParseError[] = [];\n    const parsed = jsonc.parse(content, errors, JSONC_PARSE_OPTIONS) as Record<string, unknown> | undefined;\n    return { content, parsed, parseError: errors.length > 0, exists: true };\n  }\n\n  function hasWorkosServer(parsed: Record<string, unknown> | undefined): boolean {\n    const servers = parsed?.mcpServers;\n    return Boolean(servers && typeof servers === 'object' && MCP_SERVER_NAME in (servers as object));\n  }\n\n  return {\n    key,\n    displayName,\n    async isAvailable() {\n      return pathExists(cursorDir());\n    },\n    async isInstalled() {\n      try {\n        const { parsed, parseError } = await readConfig();\n        if (parseError) return false;\n        return hasWorkosServer(parsed);\n      } catch {\n        return false;\n      }\n    },\n    async add() {\n      const path = configPath();\n      try {\n        const { content, parseError, exists } = await readConfig();\n        // Never overwrite a file we couldn't parse — the user must fix it first.\n        if (exists && parseError) {\n          return result('failed', `Could not parse ${path}; fix it manually and retry.`);\n        }\n        await mkdir(cursorDir(), { recursive: true });\n        // Converge to our URL — an existing `workos` key with a different URL is\n        // overwritten (reported as `installed`).\n        const edits = jsonc.modify(\n          content,\n          ['mcpServers', MCP_SERVER_NAME],\n          { url: MCP_SERVER_URL },\n          JSONC_MODIFY_OPTIONS,\n        );\n        await writeFile(path, jsonc.applyEdits(content, edits), 'utf8');\n        return result('installed');\n      } catch (error) {\n        return result('failed', error instanceof Error ? error.message : 'Unknown error');\n      }\n    },\n    async remove() {\n      const path = configPath();\n      try {\n        const { content, parsed, parseError, exists } = await readConfig();\n        if (!exists) return result('not-installed');\n        if (parseError) {\n          return result('failed', `Could not parse ${path}; fix it manually and retry.`);\n        }\n        if (!hasWorkosServer(parsed)) return result('not-installed');\n        const edits = jsonc.modify(content, ['mcpServers', MCP_SERVER_NAME], undefined, JSONC_MODIFY_OPTIONS);\n        await writeFile(path, jsonc.applyEdits(content, edits), 'utf8');\n        return result('removed');\n      } catch (error) {\n        return result('failed', error instanceof Error ? error.message : 'Unknown error');\n      }\n    },\n  };\n}\n\n/** The three client targets, in a stable order. */\nexport function createMcpClients(): McpClientTarget[] {\n  return [createClaudeCodeClient(), createCodexClient(), createCursorClient()];\n}\n\n/**\n * The URL the WorkOS server is configured with in Cursor's `~/.cursor/mcp.json`,\n * or null when the file/entry is absent, unreadable, or unparseable.\n *\n * Cursor is the only client whose config we read directly (the CLI clients don't\n * expose per-entry URLs), so this powers doctor's URL-drift (\"misconfigured\")\n * check without a second jsonc reader duplicating the config schema. Read-only\n * and never throws — a problem reading just yields null.\n */\nexport async function getCursorConfiguredUrl(): Promise<string | null> {\n  try {\n    const path = join(homedir(), '.cursor', 'mcp.json');\n    if (!(await pathExists(path))) return null;\n    const content = await readFile(path, 'utf8');\n    const parsed = jsonc.parse(content, [], JSONC_PARSE_OPTIONS) as Record<string, unknown> | undefined;\n    const servers = parsed?.mcpServers as Record<string, unknown> | undefined;\n    const entry = servers?.[MCP_SERVER_NAME] as { url?: unknown } | undefined;\n    return typeof entry?.url === 'string' ? entry.url : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Return only the clients available on this machine, optionally narrowed to\n * `agentFilter` keys. Availability is probed in parallel. An unknown filter key\n * simply matches nothing here — callers validate keys and surface the error.\n */\nexport async function detectMcpClients(agentFilter?: string[]): Promise<McpClientTarget[]> {\n  const clients = createMcpClients();\n  const filtered = agentFilter ? clients.filter((c) => agentFilter.includes(c.key)) : clients;\n  const availability = await Promise.all(filtered.map((c) => c.isAvailable()));\n  return filtered.filter((_, i) => availability[i]);\n}\n"]}

package/dist/lib/mcp-notice.d.ts

@@ -0,0 +1,72 @@
+/**
+ * MCP-install onboarding surfaces + their shared gate state.
+ *
+ * One module owns all automatic-ask state so the install-flow prompt and the
+ * one-time banner can't drift apart. The decline contract is absolute: any
+ * explicit "no" records `promptDeclined` and no automatic surface ever asks
+ * again — `workos mcp install` stays available manually.
+ *
+ * Mirrors telemetry-notice.ts: persisted shown/declined state in the plain
+ * prefs store, mode-gated display, and a never-throws contract so a notice can
+ * never block or fail a command. The mode gate is the CLI's interaction-mode
+ * system (isPromptAllowed / isHumanMode), which already folds in CI markers,
+ * agent markers, and TTY state — non-TTY safety comes from using it.
+ */
+export type McpAskState = {
+    declined: boolean;
+    bannerShown: boolean;
+};
+/**
+ * Ceiling on the whole install-flow offer so a wedged prompt can never hold up
+ * `workos install`. The deadline actively aborts the pending clack prompt (via
+ * AbortSignal) — clack's cancel path releases stdin and restores raw mode, so
+ * the process can actually exit; a race alone would leave the prompt's stdin
+ * handle keeping the event loop alive. Mirrors login.ts's
+ * SKILL_INSTALL_TIMEOUT_MS.
+ */
+export declare const MCP_OFFER_TIMEOUT_MS: number;
+/**
+ * Read the persisted automatic-ask state. Never throws — a missing/corrupt
+ * prefs file degrades to "nothing recorded" so gating still works in-memory.
+ */
+export declare function getMcpAskState(): Promise<McpAskState>;
+/**
+ * Record an explicit decline. Absolute and permanent for automatic surfaces.
+ * Write failures are swallowed: gating degrades to per-run memory, never
+ * crashes a command.
+ */
+export declare function recordMcpDeclined(): Promise<void>;
+/** Record that the one-time banner was shown, stamping the current time. */
+export declare function recordMcpBannerShown(): Promise<void>;
+/**
+ * Would an automatic ask be appropriate right now? True only when the user has
+ * not declined AND at least one detected agent lacks the server. Does NOT gate
+ * on interaction mode — callers add that (isPromptAllowed for the prompt,
+ * isHumanMode for the banner). Checks `declined` first so declined machines
+ * never pay for the client shell-outs.
+ */
+export declare function isAutoAskEligible(): Promise<boolean>;
+/**
+ * One-time stderr banner nudging the user toward `workos mcp install`. Shown at
+ * most once per machine, only on a normal human-mode run, and never when an
+ * earlier startup notice already fired this run (telemetry notice and unclaimed
+ * warning take precedence). Records `bannerShownAt` before printing —
+ * shown-once beats seen-once (a lost banner is fine; a nag loop is not). Never
+ * throws.
+ */
+export declare function maybeShowMcpNotice(): Promise<void>;
+/**
+ * Offer to install the WorkOS MCP server at the end of `workos install`.
+ *
+ * Wraps offerMcpInstall best-effort: a try/catch AND a 30s deadline so the
+ * offer can never throw into, wedge, or fail the install flow. The deadline
+ * aborts the pending prompt (AbortSignal → clack cancel, which releases stdin);
+ * the race is a backstop in case the flow is wedged somewhere that can't be
+ * aborted (client shell-outs are separately bounded by their exec timeouts).
+ * `workos install` has already succeeded by the time this runs.
+ */
+export declare function maybeOfferMcpInstall(_opts: {
+    entryPoint: 'install-flow';
+}): Promise<void>;
+/** Reset per-session banner state (for testing). */
+export declare function resetMcpNoticeState(): void;