workos 0.17.1 → 0.19.0

package/dist/lib/mcp-clients.js

@@ -0,0 +1,297 @@
+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 },
+};
+/**
+ * Human phrasing for each outcome (JSON mode emits the raw `outcome` value).
+ * Lives with the `McpOutcome` type so every consumer (`mcp` command, `setup`)
+ * stays in lockstep when an outcome is added.
+ */
+export const MCP_OUTCOME_LABELS = {
+    installed: 'installed',
+    'already-installed': 'already installed',
+    removed: 'removed',
+    'not-installed': 'not installed',
+    skipped: 'skipped',
+    failed: 'failed',
+};
+/** 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\n/**\n * Human phrasing for each outcome (JSON mode emits the raw `outcome` value).\n * Lives with the `McpOutcome` type so every consumer (`mcp` command, `setup`)\n * stays in lockstep when an outcome is added.\n */\nexport const MCP_OUTCOME_LABELS: Record<McpOutcome, string> = {\n  installed: 'installed',\n  'already-installed': 'already installed',\n  removed: 'removed',\n  'not-installed': 'not installed',\n  skipped: 'skipped',\n  failed: 'failed',\n};\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/port-detection.js

@@ -45,6 +45,20 @@ function parseViteConfigPort(configPath) {
     }
     return null;
 }
+/**
+ * Try vite.config.{ts,js,mjs} in installDir for a server.port value.
+ * NOTE: parseViteConfigPort uses a greedy first-match /port\s*:\s*.../ regex,
+ * so an unrelated `port:` (e.g. hmr.port) appearing before server.port wins.
+ * Pre-existing behavior for all Vite frameworks — not a regression here.
+ */
+function parseViteConfigPortFromDir(installDir) {
+    for (const p of ['vite.config.ts', 'vite.config.js', 'vite.config.mjs']) {
+        const port = parseViteConfigPort(join(installDir, p));
+        if (port)
+            return port;
+    }
+    return null;
+}
 /**
  * Parse port from Next.js package.json scripts.
  * Next.js uses: "dev": "next dev -p 4000" or --port 4000
@@ -202,24 +216,16 @@ export function detectPort(integration, installDir) {
             detectedPort = parseNextConfigPort(installDir);
             break;
         case 'tanstack-start':
-            detectedPort = parseTanStackPort(installDir);
+            // Modern @tanstack/react-start is Vite-based (port in vite.config.ts);
+            // legacy Vinxi projects use app.config.ts. Try Vite first.
+            detectedPort = parseViteConfigPortFromDir(installDir) ?? parseTanStackPort(installDir);
             break;
         case 'react':
         case 'react-router':
-        case 'vanilla-js': {
+        case 'vanilla-js':
             // Vite-based frameworks
-            const viteConfigs = [
-                join(installDir, 'vite.config.ts'),
-                join(installDir, 'vite.config.js'),
-                join(installDir, 'vite.config.mjs'),
-            ];
-            for (const configPath of viteConfigs) {
-                detectedPort = parseViteConfigPort(configPath);
-                if (detectedPort)
-                    break;
-            }
+            detectedPort = parseViteConfigPortFromDir(installDir);
             break;
-        }
         case 'dotnet':
             detectedPort = parseDotnetPort(installDir);
             break;

package/dist/lib/port-detection.js.map

@@ -1 +1 @@
-{"version":3,"file":"port-detection.js","sourceRoot":"","sources":["../../src/lib/port-detection.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport { join } from 'node:path';\nimport type { Integration } from './constants.js';\nimport { getConfig } from './settings.js';\n\nconst settings = getConfig();\n\nconst INTEGRATION_TO_SETTINGS_KEY: Record<string, string> = {\n  nextjs: 'nextjs',\n  react: 'react',\n  'tanstack-start': 'tanstackStart',\n  'react-router': 'reactRouter',\n  'vanilla-js': 'vanillaJs',\n  python: 'python',\n  ruby: 'ruby',\n  php: 'php',\n  'php-laravel': 'phpLaravel',\n  go: 'go',\n  dotnet: 'dotnet',\n  elixir: 'elixir',\n  kotlin: 'kotlin',\n};\n\nconst DEFAULT_PORT = 3000;\nconst DEFAULT_CALLBACK_PATH = '/auth/callback';\n\nfunction getDefaultPort(integration: Integration): number {\n  const settingsKey = INTEGRATION_TO_SETTINGS_KEY[integration];\n  return settings.frameworks[settingsKey]?.port ?? DEFAULT_PORT;\n}\n\nexport function getCallbackPath(integration: Integration): string {\n  const settingsKey = INTEGRATION_TO_SETTINGS_KEY[integration];\n  return settings.frameworks[settingsKey]?.callbackPath ?? DEFAULT_CALLBACK_PATH;\n}\n\n/**\n * Parse port from Vite config file.\n * Looks for server.port in vite.config.{ts,js,mjs}\n */\nfunction parseViteConfigPort(configPath: string): number | null {\n  try {\n    const content = fs.readFileSync(configPath, 'utf-8');\n    // Match: port: 3000 or port: \"3000\" or port: '3000'\n    const portMatch = content.match(/port\\s*:\\s*['\"]?(\\d+)['\"]?/);\n    if (portMatch) {\n      return parseInt(portMatch[1], 10);\n    }\n  } catch {\n    // File doesn't exist or can't be read\n  }\n  return null;\n}\n\n/**\n * Parse port from Next.js package.json scripts.\n * Next.js uses: \"dev\": \"next dev -p 4000\" or --port 4000\n */\nfunction parseNextConfigPort(installDir: string): number | null {\n  try {\n    const packageJsonPath = join(installDir, 'package.json');\n    const content = fs.readFileSync(packageJsonPath, 'utf-8');\n    const packageJson = JSON.parse(content);\n\n    const devScript = packageJson.scripts?.dev || '';\n    // Match: -p 4000, --port 4000, --port=4000\n    const portMatch = devScript.match(/-p\\s+(\\d+)|--port[=\\s]+(\\d+)/);\n    if (portMatch) {\n      return parseInt(portMatch[1] || portMatch[2], 10);\n    }\n  } catch {\n    // Can't read package.json\n  }\n  return null;\n}\n\n/**\n * Parse port from TanStack Start app.config.ts.\n * Uses Vinxi: server: { port: N }\n */\nfunction parseTanStackPort(installDir: string): number | null {\n  const configPaths = [join(installDir, 'app.config.ts'), join(installDir, 'app.config.js')];\n\n  for (const configPath of configPaths) {\n    try {\n      const content = fs.readFileSync(configPath, 'utf-8');\n      // Match server config with port\n      const portMatch = content.match(/server\\s*:\\s*\\{[^}]*port\\s*:\\s*(\\d+)/);\n      if (portMatch) {\n        return parseInt(portMatch[1], 10);\n      }\n    } catch {\n      // Config file doesn't exist\n    }\n  }\n  return null;\n}\n\n/**\n * Parse port from .NET Properties/launchSettings.json.\n * VS/Rider scaffold: profiles[*].applicationUrl = \"http://localhost:5000;https://localhost:5001\"\n */\nfunction parseDotnetPort(installDir: string): number | null {\n  try {\n    const configPath = join(installDir, 'Properties', 'launchSettings.json');\n    const content = fs.readFileSync(configPath, 'utf-8');\n    const parsed = JSON.parse(content) as { profiles?: Record<string, { applicationUrl?: string }> };\n    for (const profile of Object.values(parsed.profiles ?? {})) {\n      const match = profile.applicationUrl?.match(/http:\\/\\/[^:/]+:(\\d+)/);\n      if (match) return parseInt(match[1], 10);\n    }\n  } catch {\n    // File doesn't exist or can't parse\n  }\n  return null;\n}\n\n/**\n * Parse port from Phoenix config/dev.exs or config/runtime.exs.\n * Looks for `port: NNNN` — typically inside `http: [...]` but a bare regex is fine.\n */\nfunction parseElixirPort(installDir: string): number | null {\n  for (const relPath of ['config/dev.exs', 'config/runtime.exs']) {\n    try {\n      const content = fs.readFileSync(join(installDir, relPath), 'utf-8');\n      const match = content.match(/port:\\s*(\\d+)/);\n      if (match) return parseInt(match[1], 10);\n    } catch {\n      // skip\n    }\n  }\n  return null;\n}\n\n/**\n * Parse port from Spring Boot application.properties or application.yml.\n * Both the default `src/main/resources/` location and a top-level file are checked.\n */\nfunction parseKotlinPort(installDir: string): number | null {\n  const propsPaths = [\n    join(installDir, 'src', 'main', 'resources', 'application.properties'),\n    join(installDir, 'application.properties'),\n  ];\n  for (const propsPath of propsPaths) {\n    try {\n      const content = fs.readFileSync(propsPath, 'utf-8');\n      const match = content.match(/^server\\.port\\s*=\\s*(\\d+)/m);\n      if (match) return parseInt(match[1], 10);\n    } catch {\n      // skip\n    }\n  }\n\n  const ymlPaths = [\n    join(installDir, 'src', 'main', 'resources', 'application.yml'),\n    join(installDir, 'src', 'main', 'resources', 'application.yaml'),\n    join(installDir, 'application.yml'),\n    join(installDir, 'application.yaml'),\n  ];\n  for (const ymlPath of ymlPaths) {\n    try {\n      const content = fs.readFileSync(ymlPath, 'utf-8');\n      // `server:\\n  port: 8080` — shallow YAML parse via regex\n      const match = content.match(/server\\s*:\\s*\\n[^\\S\\n]+port\\s*:\\s*(\\d+)/);\n      if (match) return parseInt(match[1], 10);\n    } catch {\n      // skip\n    }\n  }\n  return null;\n}\n\n/**\n * Parse port from Rails config/puma.rb.\n * Common forms:\n *   port ENV.fetch(\"PORT\") { 3000 }\n *   port ENV.fetch(\"PORT\", 3000)\n *   port 3000\n */\nfunction parseRubyPort(installDir: string): number | null {\n  try {\n    const configPath = join(installDir, 'config', 'puma.rb');\n    const content = fs.readFileSync(configPath, 'utf-8');\n    const blockFetch = content.match(/port\\s+ENV\\.fetch\\([^)]*\\)\\s*\\{\\s*(\\d+)\\s*\\}/);\n    if (blockFetch) return parseInt(blockFetch[1], 10);\n    const argFetch = content.match(/port\\s+ENV\\.fetch\\([^,]+,\\s*(\\d+)\\)/);\n    if (argFetch) return parseInt(argFetch[1], 10);\n    const literal = content.match(/^\\s*port\\s+(\\d+)/m);\n    if (literal) return parseInt(literal[1], 10);\n  } catch {\n    // skip\n  }\n  return null;\n}\n\n/**\n * Detect the dev server port for a framework.\n * Checks config files first, falls back to framework default.\n */\nexport function detectPort(integration: Integration, installDir: string): number {\n  let detectedPort: number | null = null;\n\n  switch (integration) {\n    case 'nextjs':\n      detectedPort = parseNextConfigPort(installDir);\n      break;\n\n    case 'tanstack-start':\n      detectedPort = parseTanStackPort(installDir);\n      break;\n\n    case 'react':\n    case 'react-router':\n    case 'vanilla-js': {\n      // Vite-based frameworks\n      const viteConfigs = [\n        join(installDir, 'vite.config.ts'),\n        join(installDir, 'vite.config.js'),\n        join(installDir, 'vite.config.mjs'),\n      ];\n      for (const configPath of viteConfigs) {\n        detectedPort = parseViteConfigPort(configPath);\n        if (detectedPort) break;\n      }\n      break;\n    }\n\n    case 'dotnet':\n      detectedPort = parseDotnetPort(installDir);\n      break;\n\n    case 'elixir':\n      detectedPort = parseElixirPort(installDir);\n      break;\n\n    case 'kotlin':\n      detectedPort = parseKotlinPort(installDir);\n      break;\n\n    case 'ruby':\n      detectedPort = parseRubyPort(installDir);\n      break;\n  }\n\n  return detectedPort ?? getDefaultPort(integration);\n}\n"]}
+{"version":3,"file":"port-detection.js","sourceRoot":"","sources":["../../src/lib/port-detection.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport { join } from 'node:path';\nimport type { Integration } from './constants.js';\nimport { getConfig } from './settings.js';\n\nconst settings = getConfig();\n\nconst INTEGRATION_TO_SETTINGS_KEY: Record<string, string> = {\n  nextjs: 'nextjs',\n  react: 'react',\n  'tanstack-start': 'tanstackStart',\n  'react-router': 'reactRouter',\n  'vanilla-js': 'vanillaJs',\n  python: 'python',\n  ruby: 'ruby',\n  php: 'php',\n  'php-laravel': 'phpLaravel',\n  go: 'go',\n  dotnet: 'dotnet',\n  elixir: 'elixir',\n  kotlin: 'kotlin',\n};\n\nconst DEFAULT_PORT = 3000;\nconst DEFAULT_CALLBACK_PATH = '/auth/callback';\n\nfunction getDefaultPort(integration: Integration): number {\n  const settingsKey = INTEGRATION_TO_SETTINGS_KEY[integration];\n  return settings.frameworks[settingsKey]?.port ?? DEFAULT_PORT;\n}\n\nexport function getCallbackPath(integration: Integration): string {\n  const settingsKey = INTEGRATION_TO_SETTINGS_KEY[integration];\n  return settings.frameworks[settingsKey]?.callbackPath ?? DEFAULT_CALLBACK_PATH;\n}\n\n/**\n * Parse port from Vite config file.\n * Looks for server.port in vite.config.{ts,js,mjs}\n */\nfunction parseViteConfigPort(configPath: string): number | null {\n  try {\n    const content = fs.readFileSync(configPath, 'utf-8');\n    // Match: port: 3000 or port: \"3000\" or port: '3000'\n    const portMatch = content.match(/port\\s*:\\s*['\"]?(\\d+)['\"]?/);\n    if (portMatch) {\n      return parseInt(portMatch[1], 10);\n    }\n  } catch {\n    // File doesn't exist or can't be read\n  }\n  return null;\n}\n\n/**\n * Try vite.config.{ts,js,mjs} in installDir for a server.port value.\n * NOTE: parseViteConfigPort uses a greedy first-match /port\\s*:\\s*.../ regex,\n * so an unrelated `port:` (e.g. hmr.port) appearing before server.port wins.\n * Pre-existing behavior for all Vite frameworks — not a regression here.\n */\nfunction parseViteConfigPortFromDir(installDir: string): number | null {\n  for (const p of ['vite.config.ts', 'vite.config.js', 'vite.config.mjs']) {\n    const port = parseViteConfigPort(join(installDir, p));\n    if (port) return port;\n  }\n  return null;\n}\n\n/**\n * Parse port from Next.js package.json scripts.\n * Next.js uses: \"dev\": \"next dev -p 4000\" or --port 4000\n */\nfunction parseNextConfigPort(installDir: string): number | null {\n  try {\n    const packageJsonPath = join(installDir, 'package.json');\n    const content = fs.readFileSync(packageJsonPath, 'utf-8');\n    const packageJson = JSON.parse(content);\n\n    const devScript = packageJson.scripts?.dev || '';\n    // Match: -p 4000, --port 4000, --port=4000\n    const portMatch = devScript.match(/-p\\s+(\\d+)|--port[=\\s]+(\\d+)/);\n    if (portMatch) {\n      return parseInt(portMatch[1] || portMatch[2], 10);\n    }\n  } catch {\n    // Can't read package.json\n  }\n  return null;\n}\n\n/**\n * Parse port from TanStack Start app.config.ts.\n * Uses Vinxi: server: { port: N }\n */\nfunction parseTanStackPort(installDir: string): number | null {\n  const configPaths = [join(installDir, 'app.config.ts'), join(installDir, 'app.config.js')];\n\n  for (const configPath of configPaths) {\n    try {\n      const content = fs.readFileSync(configPath, 'utf-8');\n      // Match server config with port\n      const portMatch = content.match(/server\\s*:\\s*\\{[^}]*port\\s*:\\s*(\\d+)/);\n      if (portMatch) {\n        return parseInt(portMatch[1], 10);\n      }\n    } catch {\n      // Config file doesn't exist\n    }\n  }\n  return null;\n}\n\n/**\n * Parse port from .NET Properties/launchSettings.json.\n * VS/Rider scaffold: profiles[*].applicationUrl = \"http://localhost:5000;https://localhost:5001\"\n */\nfunction parseDotnetPort(installDir: string): number | null {\n  try {\n    const configPath = join(installDir, 'Properties', 'launchSettings.json');\n    const content = fs.readFileSync(configPath, 'utf-8');\n    const parsed = JSON.parse(content) as { profiles?: Record<string, { applicationUrl?: string }> };\n    for (const profile of Object.values(parsed.profiles ?? {})) {\n      const match = profile.applicationUrl?.match(/http:\\/\\/[^:/]+:(\\d+)/);\n      if (match) return parseInt(match[1], 10);\n    }\n  } catch {\n    // File doesn't exist or can't parse\n  }\n  return null;\n}\n\n/**\n * Parse port from Phoenix config/dev.exs or config/runtime.exs.\n * Looks for `port: NNNN` — typically inside `http: [...]` but a bare regex is fine.\n */\nfunction parseElixirPort(installDir: string): number | null {\n  for (const relPath of ['config/dev.exs', 'config/runtime.exs']) {\n    try {\n      const content = fs.readFileSync(join(installDir, relPath), 'utf-8');\n      const match = content.match(/port:\\s*(\\d+)/);\n      if (match) return parseInt(match[1], 10);\n    } catch {\n      // skip\n    }\n  }\n  return null;\n}\n\n/**\n * Parse port from Spring Boot application.properties or application.yml.\n * Both the default `src/main/resources/` location and a top-level file are checked.\n */\nfunction parseKotlinPort(installDir: string): number | null {\n  const propsPaths = [\n    join(installDir, 'src', 'main', 'resources', 'application.properties'),\n    join(installDir, 'application.properties'),\n  ];\n  for (const propsPath of propsPaths) {\n    try {\n      const content = fs.readFileSync(propsPath, 'utf-8');\n      const match = content.match(/^server\\.port\\s*=\\s*(\\d+)/m);\n      if (match) return parseInt(match[1], 10);\n    } catch {\n      // skip\n    }\n  }\n\n  const ymlPaths = [\n    join(installDir, 'src', 'main', 'resources', 'application.yml'),\n    join(installDir, 'src', 'main', 'resources', 'application.yaml'),\n    join(installDir, 'application.yml'),\n    join(installDir, 'application.yaml'),\n  ];\n  for (const ymlPath of ymlPaths) {\n    try {\n      const content = fs.readFileSync(ymlPath, 'utf-8');\n      // `server:\\n  port: 8080` — shallow YAML parse via regex\n      const match = content.match(/server\\s*:\\s*\\n[^\\S\\n]+port\\s*:\\s*(\\d+)/);\n      if (match) return parseInt(match[1], 10);\n    } catch {\n      // skip\n    }\n  }\n  return null;\n}\n\n/**\n * Parse port from Rails config/puma.rb.\n * Common forms:\n *   port ENV.fetch(\"PORT\") { 3000 }\n *   port ENV.fetch(\"PORT\", 3000)\n *   port 3000\n */\nfunction parseRubyPort(installDir: string): number | null {\n  try {\n    const configPath = join(installDir, 'config', 'puma.rb');\n    const content = fs.readFileSync(configPath, 'utf-8');\n    const blockFetch = content.match(/port\\s+ENV\\.fetch\\([^)]*\\)\\s*\\{\\s*(\\d+)\\s*\\}/);\n    if (blockFetch) return parseInt(blockFetch[1], 10);\n    const argFetch = content.match(/port\\s+ENV\\.fetch\\([^,]+,\\s*(\\d+)\\)/);\n    if (argFetch) return parseInt(argFetch[1], 10);\n    const literal = content.match(/^\\s*port\\s+(\\d+)/m);\n    if (literal) return parseInt(literal[1], 10);\n  } catch {\n    // skip\n  }\n  return null;\n}\n\n/**\n * Detect the dev server port for a framework.\n * Checks config files first, falls back to framework default.\n */\nexport function detectPort(integration: Integration, installDir: string): number {\n  let detectedPort: number | null = null;\n\n  switch (integration) {\n    case 'nextjs':\n      detectedPort = parseNextConfigPort(installDir);\n      break;\n\n    case 'tanstack-start':\n      // Modern @tanstack/react-start is Vite-based (port in vite.config.ts);\n      // legacy Vinxi projects use app.config.ts. Try Vite first.\n      detectedPort = parseViteConfigPortFromDir(installDir) ?? parseTanStackPort(installDir);\n      break;\n\n    case 'react':\n    case 'react-router':\n    case 'vanilla-js':\n      // Vite-based frameworks\n      detectedPort = parseViteConfigPortFromDir(installDir);\n      break;\n\n    case 'dotnet':\n      detectedPort = parseDotnetPort(installDir);\n      break;\n\n    case 'elixir':\n      detectedPort = parseElixirPort(installDir);\n      break;\n\n    case 'kotlin':\n      detectedPort = parseKotlinPort(installDir);\n      break;\n\n    case 'ruby':\n      detectedPort = parseRubyPort(installDir);\n      break;\n  }\n\n  return detectedPort ?? getDefaultPort(integration);\n}\n"]}

package/dist/lib/preferences.d.ts

@@ -18,6 +18,34 @@ export interface CliPreferences {
         /** ISO timestamp the first-run notice was shown — written in Phase 2 only. */
         noticeShownAt?: string;
     };
+    /**
+     * Legacy MCP-install onboarding state. The MCP offer folded into `setup` (see
+     * commands/setup.ts); these fields are retained for back-compat so a user who
+     * declined the old standalone MCP offer is still treated as setup-declined
+     * (see isSetupDeclined). Kept in this plain-JSON store alongside telemetry.
+     */
+    mcp?: {
+        /**
+         * true => the user explicitly declined an automatic MCP install offer. The
+         * decline is absolute: no automatic surface (prompt or banner) asks again;
+         * `workos mcp install` stays available manually.
+         */
+        promptDeclined?: boolean;
+        /** ISO timestamp the one-time MCP banner was shown. */
+        bannerShownAt?: string;
+    };
+    /**
+     * Consolidated agent-setup onboarding state (skills + MCP). Owned by
+     * commands/setup.ts. `declined` is absolute for the automatic surfaces
+     * (post-login / post-install); `workos setup` stays available manually.
+     * Legacy `mcp.promptDeclined` is treated as an implicit setup-decline on read
+     * (see isSetupDeclined) so users who already declined MCP are never re-asked.
+     */
+    setup?: {
+        declined?: boolean;
+        /** ISO timestamp the user completed a setup run. */
+        completedAt?: string;
+    };
 }
 /** Effective source of the resolved telemetry-enabled decision. */
 export type TelemetrySource = 'env' | 'preference' | 'default';
@@ -56,6 +84,20 @@ export declare function isNoticeShown(): boolean;
  * telemetry-notice.ts swallows it so a read-only FS never blocks a command.
  */
 export declare function markNoticeShown(): void;
+/**
+ * Whether an automatic setup offer should be suppressed. Absolute once the user
+ * declines. Treats the legacy `mcp.promptDeclined` flag as an implicit decline
+ * so anyone who declined the old MCP offer is never re-prompted by the new flow.
+ */
+export declare function isSetupDeclined(): boolean;
+/** Whether the user has completed a setup run (ever). */
+export declare function isSetupCompleted(): boolean;
+/** Persist an explicit setup decline. Throws on write failure (see savePreferences). */
+export declare function recordSetupDeclined(): void;
+/** Persist a completed setup run, stamping the current time. */
+export declare function recordSetupCompleted(): void;
+/** Clear the setup decline (new + legacy) so automatic offers resume. For `workos setup --reset`. */
+export declare function clearSetupDecline(): void;
 /**
  * Tri-state env override for telemetry.
  *

package/dist/lib/preferences.js

@@ -97,11 +97,15 @@ export function savePreferences(next) {
     catch {
         // No existing file (or unreadable) — start from empty.
     }
-    const merged = {
-        ...current,
-        ...next,
-        ...(current.telemetry || next.telemetry ? { telemetry: { ...current.telemetry, ...next.telemetry } } : {}),
-    };
+    // Shallow-merge each known nested group (one level) so writing one field
+    // (e.g. setup.completedAt) never clobbers a sibling written at a different
+    // time (e.g. setup.declined). A new nested group is one entry in this list.
+    const merged = { ...current, ...next };
+    for (const key of ['telemetry', 'mcp', 'setup']) {
+        if (current[key] || next[key]) {
+            Object.assign(merged, { [key]: { ...current[key], ...next[key] } });
+        }
+    }
     fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
     fs.writeFileSync(filePath, JSON.stringify(merged), { encoding: 'utf8', mode: 0o600 });
     cached = merged;
@@ -127,6 +131,31 @@ export function isNoticeShown() {
 export function markNoticeShown() {
     savePreferences({ telemetry: { noticeShownAt: new Date().toISOString() } });
 }
+/**
+ * Whether an automatic setup offer should be suppressed. Absolute once the user
+ * declines. Treats the legacy `mcp.promptDeclined` flag as an implicit decline
+ * so anyone who declined the old MCP offer is never re-prompted by the new flow.
+ */
+export function isSetupDeclined() {
+    const prefs = getPreferences();
+    return prefs.setup?.declined === true || prefs.mcp?.promptDeclined === true;
+}
+/** Whether the user has completed a setup run (ever). */
+export function isSetupCompleted() {
+    return !!getPreferences().setup?.completedAt;
+}
+/** Persist an explicit setup decline. Throws on write failure (see savePreferences). */
+export function recordSetupDeclined() {
+    savePreferences({ setup: { declined: true } });
+}
+/** Persist a completed setup run, stamping the current time. */
+export function recordSetupCompleted() {
+    savePreferences({ setup: { completedAt: new Date().toISOString() } });
+}
+/** Clear the setup decline (new + legacy) so automatic offers resume. For `workos setup --reset`. */
+export function clearSetupDecline() {
+    savePreferences({ setup: { declined: false }, mcp: { promptDeclined: false } });
+}
 /**
  * Tri-state env override for telemetry.
  *