@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/journey/survey.js

@@ -0,0 +1,203 @@
+/**
+ * The Survey: what the workspace already answers, read before anyone is asked
+ * anything.
+ *
+ * There is no model here, by design (spec decision 18). A survey fact that a
+ * model produced could be hallucinated, and the asymmetry is brutal: a missing
+ * fact costs one extra interview question, while a wrong fact is a confident
+ * silent guess. Everything below is a file read, each one independently
+ * guarded, so an unreadable or hostile workspace yields absent facts rather
+ * than wrong ones or an exception.
+ *
+ * Nothing here decides "greenfield" or "brownfield". It reports facts; the
+ * question set is derived from which of them came back empty.
+ */
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { isOutsideRel } from '../tools/shared.js';
+import { detectProjectChecks } from '../verify/detect.js';
+/** Ceiling on the tree walk, so a monorepo costs the same as a small repo. */
+export const MAX_SURVEY_FILES = 400;
+/** Second ceiling: a tree of mostly empty or non-source directories is bounded too. */
+export const MAX_SURVEY_DIRS = 2000;
+const MANIFESTS = ['package.json', 'Cargo.toml', 'pyproject.toml', 'go.mod', 'pom.xml', 'Gemfile', 'composer.json'];
+const CONVENTION_FILES = ['AGENTS.md', 'CLAUDE.md'];
+const SOURCE_EXT = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.rb', '.php', '.cs', '.kt', '.swift',
+]);
+const IGNORE_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', '.next', 'coverage', 'target', 'vendor', '__pycache__', '.venv',
+]);
+const STOPWORDS = new Set([
+    'add', 'the', 'and', 'this', 'our', 'for', 'with', 'from', 'into', 'build', 'create', 'make', 'need', 'want',
+    'support', 'existing', 'that', 'them', 'app', 'repo', 'project', 'please', 'also', 'new',
+]);
+const MAX_RELATED = 20;
+/**
+ * True when `name` inside `root` resolves to something still inside `root`.
+ * A repository can ship a symlink or junction, so the check resolves links on
+ * both sides and tests the relative path with `isOutsideRel` (RB-20).
+ */
+function containedIn(root, name) {
+    try {
+        const realRoot = realpathSync(root);
+        const realTarget = realpathSync(path.join(root, name));
+        return !isOutsideRel(path.relative(realRoot, realTarget));
+    }
+    catch {
+        return false;
+    }
+}
+function firstContainedManifest(cwd) {
+    return MANIFESTS.find((m) => containedIn(cwd, m));
+}
+/**
+ * History, read rather than run: a ref anywhere under `refs/heads`, or a
+ * packed-refs file. Branch names nest (`refs/heads/user/feature/x`), so each
+ * directory's children are joined to *that* directory, and a single unreadable
+ * directory skips rather than ending the scan.
+ */
+function hasCommits(cwd) {
+    const git = path.join(cwd, '.git');
+    try {
+        // A worktree or submodule has `.git` as a file holding `gitdir: …`. Following
+        // it would mean parsing a path out of another repo's layout; a worktree only
+        // exists for a repo that already has history, so take that as the answer.
+        if (statSync(git).isFile())
+            return true;
+    }
+    catch {
+        return false;
+    }
+    if (existsSync(path.join(git, 'packed-refs')))
+        return true;
+    const stack = [path.join(git, 'refs', 'heads')];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isDirectory())
+                stack.push(path.join(dir, e.name));
+            else
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Repo-relative source paths, breadth-first, bounded, never entering an ignored
+ * directory.
+ *
+ * The directory is tracked explicitly rather than read from the `Dirent`
+ * parent-directory property: that one arrived in Node 20.12 / 18.20, and this
+ * also runs in the VS Code extension host, which ships older Node across the
+ * supported `engines.vscode` range. A fallback there would build paths that do
+ * not exist, and the walk would quietly see only the top level — reporting
+ * *wrong* facts, which is the one thing this file promises never to do.
+ * `journey-survey.test.ts` forbids that identifier here, prose included, since
+ * the mistake cannot fail on a developer's newer Node.
+ *
+ * Directories visited are capped as well as files, so a huge non-source tree
+ * outside `IGNORE_DIRS` cannot make this walk unbounded on the editor's thread.
+ */
+function sourceFiles(cwd) {
+    const out = [];
+    const queue = [cwd];
+    let visited = 0;
+    while (queue.length > 0 && out.length < MAX_SURVEY_FILES && visited < MAX_SURVEY_DIRS) {
+        const dir = queue.shift();
+        visited += 1;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (out.length >= MAX_SURVEY_FILES)
+                break;
+            const abs = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!IGNORE_DIRS.has(e.name))
+                    queue.push(abs);
+            }
+            else if (SOURCE_EXT.has(path.extname(e.name))) {
+                out.push(path.relative(cwd, abs));
+            }
+        }
+    }
+    return out;
+}
+/** Source paths whose name mentions a noun from the request. Deterministic, no index needed. */
+function relatedTo(request, files) {
+    const tokens = [...new Set((request.toLowerCase().match(/[a-z][a-z0-9-]{2,}/g) ?? []).filter((w) => !STOPWORDS.has(w)))];
+    if (tokens.length === 0)
+        return [];
+    const hits = files.filter((f) => {
+        const lower = f.toLowerCase();
+        return tokens.some((tok) => lower.includes(tok));
+    });
+    return hits.slice(0, MAX_RELATED);
+}
+function presentFiles(cwd, names) {
+    return names.filter((n) => containedIn(cwd, n));
+}
+function priorSpecIds(cwd) {
+    try {
+        return readdirSync(path.join(cwd, '.forge', 'specs'), { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read what this workspace already says about itself. Never throws: a fact that
+ * cannot be read is absent.
+ */
+export async function surveyWorkspace(cwd, request) {
+    const facts = {
+        checks: [],
+        isGitRepo: false,
+        hasCommits: false,
+        sourceFileCount: 0,
+        conventionFiles: [],
+        relatedSymbols: [],
+        priorSpecIds: [],
+    };
+    const manifest = firstContainedManifest(cwd);
+    if (manifest) {
+        // Only ask detect.ts about a manifest we have established is inside the
+        // workspace, so a symlinked one is never read for its scripts either.
+        try {
+            const detected = await detectProjectChecks(cwd);
+            facts.checks = detected.checks;
+            facts.manifest = { path: manifest, ...(detected.packageManager ? { packageManager: detected.packageManager } : {}) };
+        }
+        catch {
+            facts.manifest = { path: manifest };
+        }
+    }
+    try {
+        facts.isGitRepo = existsSync(path.join(cwd, '.git'));
+    }
+    catch {
+        facts.isGitRepo = false;
+    }
+    if (facts.isGitRepo)
+        facts.hasCommits = hasCommits(cwd);
+    const files = sourceFiles(cwd);
+    facts.sourceFileCount = files.length;
+    facts.relatedSymbols = relatedTo(request, files);
+    facts.conventionFiles = presentFiles(cwd, CONVENTION_FILES);
+    facts.priorSpecIds = priorSpecIds(cwd);
+    return facts;
+}

package/dist/journey/trigger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tier 1 of the journey trigger: does this message deserve a read-only Survey?
+ *
+ * It decides whether to *look*, not whether to show a card. A false positive
+ * costs a few auto-approved, token-capped reads; a false positive on the card
+ * is the nagging that kills the feature (spec anti-goal 1). So this is
+ * deliberately generous and the vetoes carry the weight.
+ *
+ * Signals are noun-driven, not verb-driven: a change verb on its own trips on
+ * everything ("add a button"), so it only counts beside a noun that implies
+ * many files.
+ */
+import type { TriggerVerdict } from './types.js';
+/**
+ * `typed` is what the person wrote, `sent` what goes to the model. They differ
+ * when a slash command, skill or `@agent` mention expanded into a long body;
+ * judging that text would offer a journey for a one-line request (RB-16).
+ */
+export declare function shouldSurvey(typed: string, sent: string): TriggerVerdict;

package/dist/journey/trigger.js

@@ -0,0 +1,79 @@
+const BUILD_VERBS = /\b(?:build|create|make|develop|scaffold|set up|generate|write me)\b/i;
+const CHANGE_VERBS = /\b(?:add|extend|integrate|migrate|refactor|support|introduce|replace|rework|wire up|hook up|implement)\b/i;
+const SYSTEM_NOUNS = /\b(?:app|application|system|platform|crm|erp|cms|web ?site|api|backend|frontend|dashboard|portal|saas|marketplace|game)\b/i;
+/** Nouns that imply many files rather than one element. */
+const SCALE_NOUNS = /\b(?:module|subsystem|service|integration|pipeline|workflow|migration|multi-?tenancy|auth|authentication|authorisation|authorization|sso|oauth|billing|payments|notifications|search|reporting|analytics|audit log|admin panel|permissions|rbac|onboarding|checkout)\b/i;
+/** Hard vetoes: the person has already told us the scope is small. */
+const SMALL_VERBS = /\b(?:fix|typo|rename|bump|tweak|format|indent|lint|spelling|revert)\b/i;
+const UI_ATOM = /\b(?:button|label|icon|tooltip|placeholder|colour|color|margin|padding|border|font)\b/i;
+const CROSS_CUTTING = /\b(?:across|everywhere|all our|end-to-end|throughout|every (?:page|screen|endpoint))\b/i;
+const PLURAL_DELIVERABLE = /\b(?:pages|endpoints|models|screens|tables|services|roles|reports)\b/i;
+const REQUIREMENT_INTENT = /\b(?:need|want|should|must|would like|let (?:people|users|them|me))\b/i;
+const LONGISH_WORDS = 25;
+const MIN_LIST_SEPARATORS = 3;
+/** Cap before any regex runs, so a pathological message cannot stall the editor. */
+const MAX_INPUT = 4000;
+/**
+ * Technology names that are shaped exactly like filenames. Without this,
+ * "Build me a Next.js SaaS platform" — close to the canonical phrasing of the
+ * flagship scenario — is vetoed as naming a file and silently gets nothing.
+ */
+const TECH_TOKENS = /\b(?:next|node|nuxt|vue|three|d3|express|react|nest|ember|backbone|socket|chart|moment|day)\.(?:js|io|ts)\b/gi;
+/**
+ * A file path or extension means a scoped change, however big the noun beside it.
+ *
+ * Two narrowings against the version in `vscode/src/chat/large-request.ts`:
+ * technology names are removed first, and the extension must be letters, so a
+ * version number ("the 2.0 release") is not a filename.
+ */
+function namesAFile(text) {
+    const withoutTech = text.replace(TECH_TOKENS, ' ');
+    return /[\\/]|\.[a-z]{1,5}\b/i.test(withoutTech.replace(/[.!?]+(?=\s|$)/g, ''));
+}
+function listSeparators(text) {
+    const commasAndAnds = (text.match(/,|\band\b/gi) ?? []).length;
+    const bullets = (text.match(/^\s*(?:[-*•]|\d+[.)])\s/gm) ?? []).length;
+    return commasAndAnds + bullets;
+}
+/**
+ * `typed` is what the person wrote, `sent` what goes to the model. They differ
+ * when a slash command, skill or `@agent` mention expanded into a long body;
+ * judging that text would offer a journey for a one-line request (RB-16).
+ */
+export function shouldSurvey(typed, sent) {
+    const full = typed.trim();
+    if (!full)
+        return { survey: false, reasons: ['empty'] };
+    if (full !== sent.trim())
+        return { survey: false, reasons: ['expanded command'] };
+    if (/^\/\w/.test(full))
+        return { survey: false, reasons: ['slash command'] };
+    if (/(?:^|\s)@\S/.test(full))
+        return { survey: false, reasons: ['@agent mention'] };
+    const t = full.slice(0, MAX_INPUT);
+    if (namesAFile(t))
+        return { survey: false, reasons: ['veto: names a file or path'] };
+    if (SMALL_VERBS.test(t))
+        return { survey: false, reasons: ['veto: small-change verb'] };
+    const reasons = [];
+    const change = CHANGE_VERBS.test(t);
+    if (BUILD_VERBS.test(t) && SYSTEM_NOUNS.test(t))
+        reasons.push('build verb + system noun');
+    if (change && SCALE_NOUNS.test(t))
+        reasons.push('change verb + scale noun');
+    if (change && SYSTEM_NOUNS.test(t))
+        reasons.push('change verb + system noun');
+    if (CROSS_CUTTING.test(t))
+        reasons.push('cross-cutting scope');
+    if (change && PLURAL_DELIVERABLE.test(t))
+        reasons.push('plural deliverables');
+    if (t.split(/\s+/).length >= LONGISH_WORDS && REQUIREMENT_INTENT.test(t) && listSeparators(t) >= MIN_LIST_SEPARATORS) {
+        reasons.push('long multi-requirement message');
+    }
+    if (reasons.length === 0)
+        return { survey: false, reasons: ['no scope signal'] };
+    // One UI element with a single weak signal is a scoped edit, not a subsystem.
+    if (UI_ATOM.test(t) && reasons.length < 2)
+        return { survey: false, reasons: ['veto: single UI element'] };
+    return { survey: true, reasons };
+}

package/dist/journey/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared types for the guided journey. Types only, no logic, so every other
+ * file in `journey/` can import this one without a cycle.
+ *
+ * Design: docs/superpowers/specs/2026-10-23-guided-journey-design.md (rev 3)
+ */
+import type { DetectedCheck } from '../verify/detect.js';
+/** Tier-1 verdict: whether a read-only Survey is worth running, and why. */
+export interface TriggerVerdict {
+    survey: boolean;
+    /** Human-readable signals or vetoes; the offer card shows these. */
+    reasons: string[];
+}
+/**
+ * What the Survey read. Every field is absent or empty when it was not read —
+ * never guessed. There is deliberately no greenfield/brownfield flag: a
+ * workspace that is half-scaffolded is neither, and a label would have to lie
+ * about it. `journey-questions.test.ts` forbids that identifier anywhere under
+ * `src/`, prose included, which is why this note spells it out in words.
+ */
+export interface SurveyFacts {
+    manifest?: {
+        path: string;
+        packageManager?: string;
+    };
+    checks: DetectedCheck[];
+    isGitRepo: boolean;
+    hasCommits: boolean;
+    sourceFileCount: number;
+    conventionFiles: string[];
+    relatedSymbols: string[];
+    priorSpecIds: string[];
+}
+/** Tier-2 decision, with the evidence that earns the card. */
+export interface JourneyOffer {
+    offer: boolean;
+    evidence: string[];
+}
+/**
+ * One interview question. `answeredBy` is the precondition: when it returns a
+ * value, the Survey already answered this and the question is never asked.
+ */
+export interface InterviewQuestion {
+    id: string;
+    question: string;
+    options?: string[];
+    multiSelect?: boolean;
+    answeredBy: (facts: SurveyFacts) => string | undefined;
+}
+/** A question the person answered, carried into the system prompt. */
+export interface Answer {
+    id: string;
+    question: string;
+    answer: string;
+}
+export type StageId = 'survey' | 'interview' | 'plan' | 'spec' | 'implPlan' | 'build';
+export interface Stage {
+    id: StageId;
+    /** Survey and Interview are host-driven and run no model at all. */
+    usesModel: boolean;
+    promptSuffix: string;
+    allowTools: readonly string[];
+    artefact: string;
+    gateOptions: readonly string[];
+}
+export interface JourneyState {
+    /** `'done'` once the journey is over, including when a saved stage id is unknown. */
+    current: StageId | 'done';
+    answers: Answer[];
+    /** Index into the approved `tasks.md` during the Build stage. */
+    taskCursor: number;
+}

package/dist/journey/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lsp/client.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The absolute path of `command` found on PATH (with PATHEXT on Windows), or undefined. Never the current directory.
+ * A command that already names a path is returned as it is.
+ */
+export declare function resolveOnPath(command: string, env: NodeJS.ProcessEnv, platform: NodeJS.Platform): string | undefined;
 export type LspSeverity = 'error' | 'warning' | 'info' | 'hint';
 export interface LspDiagnostic {
     /** 1-based. */

package/dist/lsp/client.js

@@ -4,6 +4,37 @@
  * JSON-RPC 2.0 with `Content-Length` framing is small enough to own.
  */
 import { spawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * The absolute path of `command` found on PATH (with PATHEXT on Windows), or undefined. Never the current directory.
+ * A command that already names a path is returned as it is.
+ */
+export function resolveOnPath(command, env, platform) {
+    if (/[\\/]/.test(command))
+        return command;
+    const isFile = (p) => {
+        try {
+            return statSync(p).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    const win = platform === 'win32';
+    const dirs = (env.PATH ?? env.Path ?? '').split(win ? ';' : path.delimiter).filter(Boolean);
+    const exts = win ? ['', ...(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((e) => e.toLowerCase())] : [''];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            if (win && ext === '' && !/\.[a-z0-9]+$/i.test(command))
+                continue; // Windows runs nothing without an extension
+            const candidate = path.join(dir, command + ext);
+            if (isFile(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
 import { fileURLToPath, pathToFileURL } from 'node:url';
 /**
  * Servers echo document URIs in their own spelling (`file:///c%3A/x` for the
@@ -45,9 +76,14 @@ export class LspClient {
      * the spawn error (e.g. ENOENT) when the server binary is not installed.
      */
     static async start(spec, rootDir, timeoutMs) {
-        // Bare names on Windows are usually npm `.cmd` shims, which need a shell; explicit paths must not go through one.
-        const shell = process.platform === 'win32' && !/[\\/]/.test(spec.command);
-        const proc = spawn(spec.command, spec.args ?? [], { cwd: rootDir, stdio: ['pipe', 'pipe', 'pipe'], shell });
+        // The server runs in the workspace, and Windows looks in the current directory before PATH: a repository could
+        // ship its own `typescript-language-server.cmd`. So a bare name is resolved on PATH first, never in the workspace.
+        const command = resolveOnPath(spec.command, process.env, process.platform);
+        if (!command)
+            throw Object.assign(new Error(`${spec.command} is not installed (not found on PATH)`), { code: 'ENOENT' });
+        // npm `.cmd` shims need a shell on Windows; the path is quoted because it is now absolute and may contain spaces.
+        const shell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(command);
+        const proc = spawn(shell ? `"${command}"` : command, spec.args ?? [], { cwd: rootDir, stdio: ['pipe', 'pipe', 'pipe'], shell });
         const spawned = new Promise((_, reject) => proc.once('error', reject));
         const client = new LspClient(proc);
         const rootUri = pathToFileURL(rootDir).href;

package/dist/mcp/index.d.ts

@@ -1,7 +1,11 @@
 export { loadMcpConfig, parseMcpConfig } from './mcp-config.js';
 export type { McpConfigFile, McpServerSpec } from './mcp-config.js';
 export { jsonSchemaToZod } from './json-schema-to-zod.js';
-export { connectAll, connectOne, closeAll, mcpResultToValue } from './mcp-client.js';
+export { connectAll, connectOne, closeAll, mcpInstructionsBlock, mcpResultToValue, McpAuthRequiredError } from './mcp-client.js';
+export type { ConnectOptions } from './mcp-client.js';
+export { forgetSavedAuth, defaultMcpAuthDir } from './oauth.js';
+export type { McpOAuthOptions } from './oauth.js';
+export { createMcpResourceTools } from './resource-tools.js';
 export { BUILTIN_MCP_CATALOG, loadMcpCatalog } from './catalog.js';
 export { McpManager, expandSpec } from './manager.js';
 export type { McpManagerOptions, McpServerState, McpServerStatus } from './manager.js';

package/dist/mcp/index.js

@@ -1,6 +1,8 @@
 export { loadMcpConfig, parseMcpConfig } from './mcp-config.js';
 export { jsonSchemaToZod } from './json-schema-to-zod.js';
-export { connectAll, connectOne, closeAll, mcpResultToValue } from './mcp-client.js';
+export { connectAll, connectOne, closeAll, mcpInstructionsBlock, mcpResultToValue, McpAuthRequiredError } from './mcp-client.js';
+export { forgetSavedAuth, defaultMcpAuthDir } from './oauth.js';
+export { createMcpResourceTools } from './resource-tools.js';
 export { BUILTIN_MCP_CATALOG, loadMcpCatalog } from './catalog.js';
 export { McpManager, expandSpec } from './manager.js';
 export { assertValidServerName, registerMcpServer, setMcpServerDisabled } from './registry.js';

package/dist/mcp/manager.d.ts

@@ -1,8 +1,9 @@
 import type { ToolDefinition } from '../types.js';
-import { type ConnectedMcpServer } from './mcp-client.js';
+import { type ConnectOptions, type ConnectedMcpServer } from './mcp-client.js';
+import type { McpOAuthOptions } from './oauth.js';
 import type { McpServerSpec } from './mcp-config.js';
 import { type OrgPolicy } from '../policy/policy.js';
-export type McpServerState = 'connected' | 'failed' | 'disabled';
+export type McpServerState = 'connected' | 'failed' | 'disabled' | 'needs-auth';
 export interface McpServerStatus {
     name: string;
     state: McpServerState;
@@ -24,8 +25,13 @@ export interface McpManagerOptions {
     connectTimeoutMs?: number;
     /** Organization policy for the MCP allowlist. Unset = the managed policy file; null = none. */
     policy?: OrgPolicy | null;
+    /**
+     * OAuth sign-in for HTTP servers that want it. Without it such a server is simply "failed" (401). With it, saved
+     * tokens are used and a server without them is listed as "needs-auth" until {@link McpManager.signIn} runs.
+     */
+    oauth?: Omit<McpOAuthOptions, 'interactive'>;
     /** Test seam. */
-    connect?: (name: string, spec: McpServerSpec) => Promise<ConnectedMcpServer>;
+    connect?: (name: string, spec: McpServerSpec, options?: ConnectOptions) => Promise<ConnectedMcpServer>;
 }
 /** Replace `${workspaceFolder}` in args, env values, url and headers. */
 export declare function expandSpec(spec: McpServerSpec, cwd: string): McpServerSpec;
@@ -41,8 +47,16 @@ export declare class McpManager {
     ensureConnected(): Promise<void>;
     /** Tools from all connected servers (call {@link ensureConnected} first). */
     tools(): ToolDefinition[];
+    /** The servers that are connected right now (call {@link ensureConnected} first). */
+    servers(): readonly ConnectedMcpServer[];
     status(): McpServerStatus[];
     /** Drop connections and re-read the config files. */
+    private readonly specs;
+    /**
+     * Sign in to a server listed as `needs-auth`: opens the user's browser, waits for them to finish (up to the sign-in
+     * timeout), saves the tokens, then reconnects everything so the server's tools appear.
+     */
+    signIn(name: string): Promise<void>;
     reload(): Promise<void>;
     dispose(): Promise<void>;
     private readScope;

package/dist/mcp/manager.js

@@ -5,7 +5,7 @@
  * reported in `status()` instead of only written to stderr.
  */
 import path from 'node:path';
-import { closeAll, connectOne } from './mcp-client.js';
+import { McpAuthRequiredError, closeAll, connectOne } from './mcp-client.js';
 import { loadMcpConfig } from './mcp-config.js';
 import { defaultUserMcpPath } from './marketplace.js';
 import { filterMcpServers, getOrgPolicy } from '../policy/policy.js';
@@ -50,10 +50,32 @@ export class McpManager {
     tools() {
         return this.connected.flatMap((s) => s.tools);
     }
+    /** The servers that are connected right now (call {@link ensureConnected} first). */
+    servers() {
+        return this.connected;
+    }
     status() {
         return [...this.statuses];
     }
     /** Drop connections and re-read the config files. */
+    specs = new Map();
+    /**
+     * Sign in to a server listed as `needs-auth`: opens the user's browser, waits for them to finish (up to the sign-in
+     * timeout), saves the tokens, then reconnects everything so the server's tools appear.
+     */
+    async signIn(name) {
+        const oauth = this.options.oauth;
+        const spec = this.specs.get(name);
+        if (!oauth)
+            throw new Error('sign-in is not available here');
+        if (!spec)
+            throw new Error(`no MCP server named "${name}"`);
+        const connect = this.options.connect ?? connectOne;
+        const wait = oauth.signInTimeoutMs ?? 5 * 60_000;
+        const server = await withTimeout(connect(name, expandSpec(spec, this.options.cwd), { oauth: { ...oauth, interactive: true } }), wait + (this.options.connectTimeoutMs ?? 30_000), `Signing in to MCP server "${name}"`);
+        await closeAll([server]);
+        await this.reload();
+    }
     async reload() {
         await this.dispose();
         await this.ensureConnected();
@@ -110,10 +132,13 @@ export class McpManager {
             if (spec.disabled)
                 return { status: { name, state: 'disabled', scope, toolCount: 0 } };
             try {
-                const server = await withTimeout(connect(name, expandSpec(spec, cwd)), timeoutMs, `MCP server "${name}"`);
+                this.specs.set(name, spec);
+                const server = await withTimeout(connect(name, expandSpec(spec, cwd), this.options.oauth ? { oauth: { ...this.options.oauth, interactive: false } } : undefined), timeoutMs, `MCP server "${name}"`);
                 return { server, status: { name, state: 'connected', scope, toolCount: server.tools.length } };
             }
             catch (err) {
+                if (err instanceof McpAuthRequiredError)
+                    return { status: { name, state: 'needs-auth', scope, toolCount: 0, error: err.message } };
                 return { status: { name, state: 'failed', scope, toolCount: 0, error: err.message } };
             }
         }));

package/dist/mcp/marketplace.d.ts

@@ -55,6 +55,8 @@ export declare function installDirNameFor(source: {
  * server" message instead of silently registering nothing.
  */
 export declare function probeRepoForServer(repoPath: string, subdir?: string): Promise<McpServerSpec>;
+/** `--` ends git's option parsing: a source that starts with `-` (`--upload-pack=…`) must never be read as an option. */
+export declare function gitCloneArgs(url: string, target: string): string[];
 /**
  * Install an MCP server from a catalog entry or a raw GitHub URL.
  * Returns the {@link InstalledMcpServer} describing what was installed.

package/dist/mcp/marketplace.js

@@ -27,6 +27,8 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { parseMcpConfig } from './mcp-config.js';
+import { isOutsideRel } from '../tools/shared.js';
+import { updateJsonFile } from '../config-file.js';
 const execFileP = promisify(execFile);
 /** Path to the cache root (caller-controlled so tests can inject a temp dir). */
 export function defaultCacheRoot() {
@@ -152,10 +154,14 @@ export async function probeRepoForServer(repoPath, subdir) {
 }
 /** Side-effect: clone the source into the cache dir. */
 async function gitClone(url, target) {
-    await execFileP('git', ['clone', '--depth', '1', '--quiet', url, target], {
+    await execFileP('git', gitCloneArgs(url, target), {
         windowsHide: true,
     });
 }
+/** `--` ends git's option parsing: a source that starts with `-` (`--upload-pack=…`) must never be read as an option. */
+export function gitCloneArgs(url, target) {
+    return ['clone', '--depth', '1', '--quiet', '--', url, target];
+}
 /**
  * Install an MCP server from a catalog entry or a raw GitHub URL.
  * Returns the {@link InstalledMcpServer} describing what was installed.
@@ -197,7 +203,7 @@ export async function installMcpServer(params) {
     // consequences of a bypass (arbitrary recursive delete) are severe.
     const installPath = path.join(cacheRoot, name);
     const relInstall = path.relative(cacheRoot, installPath);
-    if (relInstall.startsWith('..') || path.isAbsolute(relInstall)) {
+    if (isOutsideRel(relInstall)) {
         throw new Error(`Refusing to install "${name}": resolved path escapes the cache root.`);
     }
     if (existsSync(installPath)) {
@@ -260,8 +266,8 @@ export async function readUserMcpRegistry(userMcpPath) {
 }
 /** Write the user's MCP registry, creating parent directories as needed. */
 export async function writeUserMcpRegistry(userMcpPath, config) {
-    await mkdir(path.dirname(userMcpPath), { recursive: true });
-    await writeFile(userMcpPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    // Atomic, and one writer at a time (see updateJsonFile).
+    await updateJsonFile(userMcpPath, () => config);
 }
 /** Remove an installed MCP server by name. Idempotent: succeeds even when absent. */
 export async function uninstallMcpServer(params) {

package/dist/mcp/mcp-client.d.ts

@@ -1,4 +1,5 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type McpOAuthOptions } from './oauth.js';
 import type { McpConfigFile, McpServerSpec } from './mcp-config.js';
 import type { ToolDefinition } from '../types.js';
 /**
@@ -9,11 +10,20 @@ export interface ConnectedMcpServer {
     name: string;
     client: Client;
     tools: ToolDefinition[];
+    /** What the server says about using it (from `initialize`); shown to the model next to its tools. */
+    instructions?: string | undefined;
 }
 /** Connect to every server in a parsed MCP config. Failed connections are skipped with a warning. */
-export declare function connectAll(config: McpConfigFile): Promise<ConnectedMcpServer[]>;
+export declare function connectAll(config: McpConfigFile, options?: ConnectOptions): Promise<ConnectedMcpServer[]>;
+export { McpAuthRequiredError } from './oauth.js';
+export interface ConnectOptions {
+    /** Let an HTTP server that wants OAuth sign-in use saved tokens, and (with `interactive`) ask the user to sign in. */
+    oauth?: McpOAuthOptions;
+}
 /** Connect to a single server and pull its tools. */
-export declare function connectOne(name: string, spec: McpServerSpec): Promise<ConnectedMcpServer>;
+export declare function connectOne(name: string, spec: McpServerSpec, options?: ConnectOptions): Promise<ConnectedMcpServer>;
+/** The instructions servers sent with `initialize`, as one prompt block (empty when none sent any). */
+export declare function mcpInstructionsBlock(servers: readonly ConnectedMcpServer[]): string;
 /** Close all clients and their underlying transports. */
 export declare function closeAll(servers: ConnectedMcpServer[]): Promise<void>;
 /**