@projectctx/agent 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/connect.js

@@ -0,0 +1,544 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// `projectctx connect` wires the project-memory MCP into each locally installed
+// AI client and installs the T-002 instruction blocks. Sacred constraint
+// (data-loss): every config file is parsed -> merged -> written atomically
+// (temp file + rename) with a timestamped backup taken before modification. A
+// --dry-run mode prints the would-be changes without touching disk.
+export const MCP_SERVER_NAME = "project-memory";
+export const MCP_URL = "https://projectctx.com/mcp";
+// Which instruction-text version is installed today. v1 = goal-mode wording
+// (get_context {mode:"checkin"} FAILS Zod validation until T-301 ships). Flip to
+// "v2" and re-run connect once T-301 has deployed; the marker blocks make the
+// swap a clean replace. See assets/instructions/README.md.
+export const INSTRUCTION_VERSION = "v1";
+const MARKER_BEGIN = "<!-- projectctx:begin -->";
+const MARKER_END = "<!-- projectctx:end -->";
+// All paths derive from HOME so tests can point at a sandbox
+// (HOME=$(mktemp -d)) without touching the real user's configs.
+export function connectPaths(home = homedir()) {
+    return {
+        home,
+        claudeJson: join(home, ".claude.json"),
+        claudeMd: join(home, ".claude", "CLAUDE.md"),
+        cursorMcp: join(home, ".cursor", "mcp.json"),
+        cursorRules: join(home, ".cursor", "rules", "projectctx.mdc"),
+        codexToml: join(home, ".codex", "config.toml"),
+        codexAgents: join(home, ".codex", "AGENTS.md")
+    };
+}
+function assetPath(name) {
+    // Resolves the same from src/ (tsx dev) and dist/ (published): both sit one
+    // level below the package root, so ../assets is correct either way.
+    return fileURLToPath(new URL(`../assets/instructions/${name}`, import.meta.url));
+}
+function readInstructionBody(client, version) {
+    const file = `${client}.${version}.md`;
+    return readFileSync(assetPath(file), "utf8").trim();
+}
+export function readManualRemainderText(version) {
+    return readFileSync(assetPath(`chatgpt-claudeai.${version}.md`), "utf8").trim();
+}
+// --- marker block install (idempotent replace, never append) ---------------
+function markerBlock(body) {
+    return `${MARKER_BEGIN}\n${body}\n${MARKER_END}`;
+}
+/**
+ * Insert or replace the projectctx marker block in a markdown-ish file. Content
+ * outside the markers is preserved verbatim. Re-running with the same body is a
+ * no-op (byte-identical output), which is what makes connect idempotent.
+ */
+export function upsertMarkerBlock(existing, body) {
+    const block = markerBlock(body);
+    if (existing === null || existing === "") {
+        return block + "\n";
+    }
+    const begin = existing.indexOf(MARKER_BEGIN);
+    if (begin !== -1) {
+        const endIdx = existing.indexOf(MARKER_END, begin);
+        if (endIdx !== -1) {
+            const after = existing.slice(endIdx + MARKER_END.length);
+            const before = existing.slice(0, begin);
+            return before + block + after;
+        }
+        // Dangling begin with no end: replace from begin to EOF rather than nest.
+        return existing.slice(0, begin) + block + "\n";
+    }
+    // No block yet: append after existing content with a blank-line separator.
+    const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+    return existing + sep + block + "\n";
+}
+// Cursor .mdc needs YAML frontmatter at the very top (outside the marker block).
+// We install/repair the frontmatter, then upsert the marker block in the body.
+const CURSOR_FRONTMATTER = ["---", "description: ProjectCtx memory usage", "alwaysApply: true", "---"].join("\n");
+export function buildCursorMdc(existing, body) {
+    let frontmatter = CURSOR_FRONTMATTER;
+    let rest;
+    if (existing && existing.startsWith("---")) {
+        const end = existing.indexOf("\n---", 3);
+        if (end !== -1) {
+            const closeLineEnd = existing.indexOf("\n", end + 1);
+            frontmatter = existing.slice(0, closeLineEnd === -1 ? existing.length : closeLineEnd);
+            rest = closeLineEnd === -1 ? "" : existing.slice(closeLineEnd + 1);
+        }
+        else {
+            rest = existing;
+            frontmatter = CURSOR_FRONTMATTER;
+        }
+    }
+    else {
+        rest = existing;
+    }
+    // Strip leading blank lines from the body so re-runs don't accumulate them
+    // (the frontmatter separator is re-added below, making the op idempotent).
+    const restTrimmed = rest ? rest.replace(/^\s+/, "") : "";
+    const bodyOut = upsertMarkerBlock(restTrimmed !== "" ? restTrimmed : null, body);
+    return `${frontmatter}\n\n${bodyOut}`;
+}
+function stringifyJson(value) {
+    return JSON.stringify(value, null, 2) + "\n";
+}
+/**
+ * Merge the project-memory server into an mcpServers map without disturbing any
+ * other key. `entry` is the value stored under the server name (Claude Code and
+ * Cursor differ slightly). Returns byte-identical output when already present.
+ */
+// Some editors save JSON with a UTF-8 BOM, which JSON.parse rejects.
+function stripBom(value) {
+    return value.replace(/^\uFEFF/, "");
+}
+export function mergeMcpServersJson(existing, entry) {
+    let root = {};
+    if (existing && stripBom(existing).trim() !== "") {
+        const parsed = JSON.parse(stripBom(existing));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("existing config is not a JSON object");
+        }
+        root = parsed;
+    }
+    const servers = (root.mcpServers && typeof root.mcpServers === "object" && !Array.isArray(root.mcpServers)
+        ? { ...root.mcpServers }
+        : {});
+    const nextRoot = { ...root, mcpServers: { ...servers, [MCP_SERVER_NAME]: entry } };
+    const after = stringifyJson(nextRoot);
+    const before = existing ?? "";
+    return { after, changed: after !== before };
+}
+// --- TOML block append (Codex) ---------------------------------------------
+//
+// Ladder note: no TOML parser exists anywhere in the workspace (rung 5 miss),
+// and we only need to insert/replace one well-known table
+// ([mcp_servers.project-memory]). A full parser (rung 7 dependency) is overkill
+// for that, so we do a minimal, line-based table splice that preserves every
+// other byte of the file. It handles: a pre-existing project-memory block
+// (replace in place, idempotent) and other [mcp_servers.*] blocks (untouched).
+const CODEX_BLOCK_HEADER = `[mcp_servers.${MCP_SERVER_NAME}]`;
+function codexBlock() {
+    return `${CODEX_BLOCK_HEADER}\nurl = "${MCP_URL}"`;
+}
+function isTableHeaderLine(line) {
+    return /^\s*\[\[?[^\]]+\]\]?\s*(#.*)?$/.test(line);
+}
+// Extract the table path from a header line, tolerating an inline comment
+// (`[mcp_servers.project-memory] # pinned` is legal TOML) and internal
+// whitespace. Returns null for non-header lines. The finder MUST use this, not
+// a whole-line comparison: missing a commented header would send us down the
+// append path and produce a duplicate table, which TOML forbids — Codex would
+// then refuse to load the entire config (review finding B1).
+function tableHeaderPath(line) {
+    const match = /^\s*\[([^\]]+)\]\s*(#.*)?$/.exec(line);
+    return match ? match[1].replace(/\s+/g, "") : null;
+}
+export function upsertCodexToml(existing) {
+    const block = codexBlock();
+    if (existing === null || existing.trim() === "") {
+        return { after: block + "\n", changed: true };
+    }
+    // Preserve the file's own line endings when splicing (CRLF files stay CRLF).
+    const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+    const lines = existing.split(/\r?\n/);
+    const blockLines = block.split("\n");
+    const targetPath = `mcp_servers.${MCP_SERVER_NAME}`;
+    const headerIdx = lines.findIndex((line) => tableHeaderPath(line) === targetPath);
+    if (headerIdx === -1) {
+        // No existing project-memory block: append after a separating blank line.
+        const trimmedEnd = existing.replace(/(\r?\n)+$/, "");
+        const after = `${trimmedEnd}${eol}${eol}${blockLines.join(eol)}${eol}`;
+        return { after, changed: after !== existing };
+    }
+    // Replace the existing block: from its header up to (but not including) the
+    // next table header or EOF. A nested subtable header
+    // ([mcp_servers.project-memory.env]) counts as a boundary, so subtables and
+    // neighbor tables survive untouched. A trailing comment on the url line is
+    // simply replaced with the canonical line, so re-runs stay idempotent.
+    let end = headerIdx + 1;
+    while (end < lines.length && !isTableHeaderLine(lines[end]))
+        end++;
+    const before = lines.slice(0, headerIdx);
+    const afterLines = lines.slice(end);
+    const rebuilt = [...before, ...blockLines, ...afterLines].join(eol);
+    const normalized = rebuilt.endsWith("\n") ? rebuilt : rebuilt + eol;
+    return { after: normalized, changed: normalized !== existing };
+}
+// --- running-process detection ---------------------------------------------
+//
+// ~/.claude.json is actively rewritten by a live Claude Code process; a
+// read-modify-write race can clobber in either direction. We warn (not block)
+// when a matching process appears to be running so the user can quit it first.
+// Match on the executable's basename (pgrep -x against the process name), not a
+// full-command-line substring. The looser -f form gave false positives whenever
+// connect ran from a path containing "claude" (e.g. a ~/.claude worktree). This
+// is a best-effort convenience warning, so a miss (client renamed its binary)
+// is acceptable; a false alarm on every run is not. We also skip the check when
+// connect is itself running under the named client (Claude Code sets
+// CLAUDECODE=1) to avoid warning about our own parent process.
+function isProcessRunning(processName, logger) {
+    if (process.platform === "win32")
+        return false; // pgrep unavailable; skip.
+    try {
+        const out = execFileSync("pgrep", ["-x", processName], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+        });
+        return out.trim().length > 0;
+    }
+    catch (error) {
+        // pgrep exits non-zero (1) when nothing matches — that's "not running".
+        logger?.debug(`pgrep -x ${processName} -> ${error instanceof Error ? error.message : "no match"}`);
+        return false;
+    }
+}
+// --- atomic write with backup ----------------------------------------------
+function timestamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+/**
+ * Write `content` to `path` atomically: back up any existing file to
+ * `<target>.bak-<timestamp>`, write to a temp file in the same directory, then
+ * rename over the target (atomic on POSIX). The temp+rename means a crash
+ * mid-write never leaves a truncated config.
+ *
+ * Symlinked configs (dotfiles setups) are followed: the write and backup act on
+ * the resolved real path, so the link stays intact and the linked target gets
+ * the new content. Renaming over the link path itself would silently replace
+ * the symlink with a regular file and leave the real target stale (review
+ * finding S1).
+ */
+export function atomicWriteWithBackup(path, content) {
+    const target = existsSync(path) ? realpathSync(path) : path;
+    const dir = dirname(target);
+    mkdirSync(dir, { recursive: true });
+    let backupPath;
+    if (existsSync(target)) {
+        backupPath = `${target}.bak-${timestamp()}`;
+        copyFileSync(target, backupPath);
+    }
+    const tmp = join(dir, `.${Math.random().toString(36).slice(2)}.projectctx.tmp`);
+    try {
+        writeFileSync(tmp, content, { mode: 0o600 });
+        renameSync(tmp, target);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+    return { backupPath };
+}
+// --- plan builders ----------------------------------------------------------
+function fileChange(path, kind, after, note) {
+    const before = existsSync(path) ? readFileSync(path, "utf8") : null;
+    return { path, kind, before, after, changed: after !== (before ?? ""), note };
+}
+function planClaudeCode(paths, version, claudeOnPath, logger) {
+    const detected = existsSync(paths.claudeJson) || existsSync(dirname(paths.claudeMd));
+    const warnings = [];
+    if (isProcessRunning("claude", logger)) {
+        warnings.push("Claude Code appears to be running. It actively rewrites ~/.claude.json; quit it before applying to avoid a read-modify-write race.");
+    }
+    const changes = [];
+    let cliCommand;
+    if (claudeOnPath) {
+        cliCommand = {
+            argv: ["mcp", "add", "--transport", "http", MCP_SERVER_NAME, MCP_URL, "--scope", "user"],
+            description: `claude mcp add --transport http ${MCP_SERVER_NAME} ${MCP_URL} --scope user`
+        };
+    }
+    else {
+        // Fallback: merge directly into ~/.claude.json (Claude Code's HTTP entry
+        // shape mirrors Cursor's — a url field).
+        const merged = mergeMcpServersJson(existsSync(paths.claudeJson) ? readFileSync(paths.claudeJson, "utf8") : null, {
+            type: "http",
+            url: MCP_URL
+        });
+        changes.push({
+            path: paths.claudeJson,
+            kind: "mcp-config",
+            before: existsSync(paths.claudeJson) ? readFileSync(paths.claudeJson, "utf8") : null,
+            after: merged.after,
+            changed: merged.changed,
+            note: "claude CLI not on PATH; merging ~/.claude.json directly"
+        });
+    }
+    const body = readInstructionBody("claude-code", version);
+    const claudeMdBefore = existsSync(paths.claudeMd) ? readFileSync(paths.claudeMd, "utf8") : null;
+    changes.push(fileChange(paths.claudeMd, "instructions", upsertMarkerBlock(claudeMdBefore, body)));
+    return { client: "claude-code", label: "Claude Code", detected, cliCommand, changes, warnings };
+}
+function planCursor(paths, version, logger) {
+    const detected = existsSync(paths.cursorMcp) || existsSync(join(paths.home, ".cursor"));
+    const warnings = [];
+    if (isProcessRunning("Cursor", logger)) {
+        warnings.push("Cursor appears to be running; it may reload its MCP config. Restart Cursor after applying.");
+    }
+    const merged = mergeMcpServersJson(existsSync(paths.cursorMcp) ? readFileSync(paths.cursorMcp, "utf8") : null, {
+        url: MCP_URL
+    });
+    const changes = [
+        {
+            path: paths.cursorMcp,
+            kind: "mcp-config",
+            before: existsSync(paths.cursorMcp) ? readFileSync(paths.cursorMcp, "utf8") : null,
+            after: merged.after,
+            changed: merged.changed
+        }
+    ];
+    const body = readInstructionBody("cursor", version);
+    const rulesBefore = existsSync(paths.cursorRules) ? readFileSync(paths.cursorRules, "utf8") : null;
+    changes.push(fileChange(paths.cursorRules, "instructions", buildCursorMdc(rulesBefore, body)));
+    return { client: "cursor", label: "Cursor", detected, changes, warnings };
+}
+function planCodex(paths, version, logger) {
+    const detected = existsSync(paths.codexToml) || existsSync(join(paths.home, ".codex"));
+    const warnings = [];
+    if (isProcessRunning("codex", logger)) {
+        warnings.push("Codex appears to be running; restart it after applying so it re-reads config.toml.");
+    }
+    const merged = upsertCodexToml(existsSync(paths.codexToml) ? readFileSync(paths.codexToml, "utf8") : null);
+    const changes = [
+        {
+            path: paths.codexToml,
+            kind: "mcp-config",
+            before: existsSync(paths.codexToml) ? readFileSync(paths.codexToml, "utf8") : null,
+            after: merged.after,
+            changed: merged.changed
+        }
+    ];
+    const body = readInstructionBody("codex", version);
+    const agentsBefore = existsSync(paths.codexAgents) ? readFileSync(paths.codexAgents, "utf8") : null;
+    changes.push(fileChange(paths.codexAgents, "instructions", upsertMarkerBlock(agentsBefore, body)));
+    return { client: "codex", label: "Codex", detected, changes, warnings };
+}
+function claudeCliAvailable(logger) {
+    try {
+        execFileSync(process.platform === "win32" ? "where" : "which", ["claude"], {
+            stdio: ["ignore", "ignore", "ignore"]
+        });
+        return true;
+    }
+    catch (error) {
+        logger?.debug(`claude not on PATH: ${error instanceof Error ? error.message : "not found"}`);
+        return false;
+    }
+}
+function buildManualRemainder(version) {
+    const custom = readManualRemainderText(version);
+    return [
+        "Manual steps (account-side connectors — no local config file to edit):",
+        "",
+        "  ChatGPT (Settings -> Connectors -> Add / MCP servers):",
+        `    URL: ${MCP_URL}`,
+        "  claude.ai (Settings -> Connectors -> Add custom connector):",
+        `    URL: ${MCP_URL}`,
+        "  Claude Desktop:",
+        "    Its local config supports stdio servers only today; use the account-side",
+        "    Connectors UI (same as claude.ai) for this remote HTTP server.",
+        "",
+        "Then paste this into each tool's custom instructions / personalization box:",
+        "",
+        ...custom.split("\n").map((line) => `    ${line}`),
+        "",
+        "Note: each client pops its own OAuth browser handshake on first tool use.",
+        "The server supports rotating refresh tokens; whether renewal is seamless",
+        "depends on the client's OAuth implementation."
+    ].join("\n");
+}
+/**
+ * Build the full plan without writing anything. Pure w.r.t. disk except for
+ * reads, so --dry-run and the real run share one code path.
+ */
+// A malformed (or BOM-mangled beyond repair) config must not kill the whole
+// run with a raw SyntaxError: the client is skipped with a clear message —
+// its file is left untouched — and the other clients still get wired (review
+// finding S2).
+function planClientSafely(build, client, label, configPath) {
+    try {
+        return build();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "unknown parse error";
+        return {
+            client,
+            label,
+            detected: true,
+            changes: [],
+            warnings: [
+                `Couldn't parse ${configPath} — file left untouched. Fix or remove it, then re-run projectctx connect. (${detail})`
+            ]
+        };
+    }
+}
+export function buildConnectPlan(opts = {}) {
+    const version = opts.version ?? INSTRUCTION_VERSION;
+    const paths = connectPaths(opts.home);
+    const claudeOnPath = claudeCliAvailable(opts.logger);
+    const clients = [
+        planClientSafely(() => planClaudeCode(paths, version, claudeOnPath, opts.logger), "claude-code", "Claude Code", paths.claudeJson),
+        planClientSafely(() => planCursor(paths, version, opts.logger), "cursor", "Cursor", paths.cursorMcp),
+        planClientSafely(() => planCodex(paths, version, opts.logger), "codex", "Codex", paths.codexToml)
+    ];
+    return {
+        dryRun: false,
+        home: paths.home,
+        instructionVersion: version,
+        clients,
+        manualRemainder: buildManualRemainder(version)
+    };
+}
+export function runConnect(opts = {}) {
+    const dryRun = opts.dryRun ?? false;
+    const plan = buildConnectPlan({ home: opts.home, version: opts.version, logger: opts.logger });
+    if (dryRun) {
+        return { ...plan, dryRun: true, applied: false };
+    }
+    for (const client of plan.clients) {
+        if (!client.detected)
+            continue;
+        // Run the CLI-delegated MCP wiring (Claude Code) if requested.
+        if (client.cliCommand && opts.runCliCommands) {
+            try {
+                execFileSync("claude", client.cliCommand.argv, { stdio: ["ignore", "pipe", "pipe"] });
+            }
+            catch (error) {
+                client.warnings.push(`Failed to run \`${client.cliCommand.description}\`: ${error instanceof Error ? error.message : "unknown error"}. Wire it manually or re-run.`);
+            }
+        }
+        for (const change of client.changes) {
+            if (!change.changed)
+                continue;
+            atomicWriteWithBackup(change.path, change.after);
+        }
+    }
+    return { ...plan, dryRun: false, applied: true };
+}
+function claudeJsonHasEntry(raw) {
+    try {
+        const parsed = JSON.parse(stripBom(raw));
+        const servers = parsed?.mcpServers;
+        return Boolean(servers && typeof servers === "object" && MCP_SERVER_NAME in servers);
+    }
+    catch {
+        return false;
+    }
+}
+export function inspectClientConfigs(home = homedir()) {
+    const paths = connectPaths(home);
+    const statuses = [];
+    // Claude Code: ~/.claude.json mcpServers map.
+    {
+        const exists = existsSync(paths.claudeJson);
+        const configured = exists && claudeJsonHasEntry(readFileSync(paths.claudeJson, "utf8"));
+        statuses.push({
+            client: "claude-code",
+            label: "Claude Code",
+            configPath: paths.claudeJson,
+            configExists: exists,
+            mcpConfigured: configured
+        });
+    }
+    // Cursor: ~/.cursor/mcp.json mcpServers map.
+    {
+        const exists = existsSync(paths.cursorMcp);
+        const configured = exists && claudeJsonHasEntry(readFileSync(paths.cursorMcp, "utf8"));
+        statuses.push({
+            client: "cursor",
+            label: "Cursor",
+            configPath: paths.cursorMcp,
+            configExists: exists,
+            mcpConfigured: configured
+        });
+    }
+    // Codex: ~/.codex/config.toml [mcp_servers.project-memory] block.
+    {
+        const exists = existsSync(paths.codexToml);
+        const configured = exists && readFileSync(paths.codexToml, "utf8").includes(CODEX_BLOCK_HEADER);
+        statuses.push({
+            client: "codex",
+            label: "Codex",
+            configPath: paths.codexToml,
+            configExists: exists,
+            mcpConfigured: configured
+        });
+    }
+    return statuses;
+}
+// --- human-readable formatting ---------------------------------------------
+function relHome(path, home) {
+    return path.startsWith(home) ? "~" + path.slice(home.length) : path;
+}
+function summarizeChange(change) {
+    if (!change.changed)
+        return "no change (already up to date)";
+    if (change.before === null)
+        return "create";
+    return "update";
+}
+/**
+ * Render the plan as product-grade terminal copy. Doubles as onboarding, so it
+ * names every file it would touch, flags detected-vs-not, and prints the manual
+ * remainder. In dry-run it says nothing was written.
+ */
+export function formatConnectOutput(result) {
+    const home = result.home;
+    const lines = [];
+    const heading = result.dryRun
+        ? "projectctx connect — DRY RUN (no files will be written)"
+        : "projectctx connect";
+    lines.push(heading);
+    lines.push("=".repeat(heading.length));
+    lines.push("");
+    lines.push(`Instruction text version: ${result.instructionVersion}${result.instructionVersion === "v1" ? " (goal-mode; swap to v2 after roadmap T-301)" : ""}`);
+    lines.push("");
+    for (const client of result.clients) {
+        lines.push(`${client.detected ? "[detected]" : "[not found]"} ${client.label}`);
+        if (!client.detected) {
+            lines.push("   (no config detected — skipped; install the client, then re-run connect)");
+            lines.push("");
+            continue;
+        }
+        if (client.cliCommand) {
+            lines.push(`   MCP: ${client.cliCommand.description}`);
+        }
+        for (const change of client.changes) {
+            lines.push(`   ${change.kind === "instructions" ? "instructions" : "MCP config"}: ${relHome(change.path, home)} — ${summarizeChange(change)}`);
+            if (change.note)
+                lines.push(`      note: ${change.note}`);
+        }
+        for (const warning of client.warnings) {
+            lines.push(`   ! ${warning}`);
+        }
+        lines.push("");
+    }
+    lines.push(result.manualRemainder);
+    lines.push("");
+    if (result.dryRun) {
+        lines.push("Dry run complete. Nothing was written. Re-run without --dry-run to apply.");
+    }
+    else {
+        lines.push("Done. Backups of every modified file were saved alongside them (.bak-<timestamp>).");
+        lines.push("Run `projectctx doctor` to verify.");
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/doctor.js

@@ -4,6 +4,7 @@ import { scanWorkspace } from "@projectctx/indexer";
 import { checkConfigPermissions, configFilePath, readAgentConfig, resolveCloudConfig } from "./config.js";
 import { createProjectCtxClient } from "./cloud-client.js";
 import { getCredentialStore } from "./credentials.js";
+import { inspectClientConfigs } from "./connect.js";
 import { AgentError } from "./errors.js";
 function check(name, fn) {
     try {
@@ -86,6 +87,19 @@ export async function runDoctor(logger) {
             return "scanWorkspace import ok";
         }),
     ];
+    // Per-client MCP config presence. Informational (always ok): a client that
+    // isn't wired yet is a "run connect" prompt, not a doctor failure. These
+    // report config PRESENCE only — doctor cannot verify each client's OAuth
+    // state (each client owns its own token store). The single live server ping
+    // below uses the CLI's own keyring credential and is labeled as such.
+    for (const status of inspectClientConfigs()) {
+        const message = !status.configExists
+            ? `${status.label}: no config found (${status.configPath}); run projectctx connect`
+            : status.mcpConfigured
+                ? `${status.label}: project-memory MCP configured in ${status.configPath}`
+                : `${status.label}: config exists but project-memory not wired (${status.configPath}); run projectctx connect`;
+        checks.push({ name: `client_${status.client.replace(/-/g, "_")}`, ok: true, message });
+    }
     const { resolveChecks, config } = await cloudChecks();
     checks.push(...resolveChecks);
     if (config?.token) {
@@ -94,7 +108,11 @@ export async function runDoctor(logger) {
         const client = createProjectCtxClient(config, logger);
         try {
             whoami = await client.whoami();
-            checks.push({ name: "cloud_auth", ok: true, message: `Authenticated as ${whoami.actor.name}` });
+            checks.push({
+                name: "cloud_auth",
+                ok: true,
+                message: `Server reachable; authenticated as ${whoami.actor.name} (CLI credential — does not reflect per-client OAuth state)`
+            });
         }
         catch (error) {
             checks.push({ name: "cloud_auth", ok: false, message: error instanceof Error ? error.message : "Unknown error" });

package/dist/index.d.ts

@@ -7,4 +7,6 @@ export { checkConfigPermissions, clearAgentToken, clearStoredToken, configDir, c
 export { getCredentialStore, setCredentialStoreForTesting, InMemoryCredentialStore, type CredentialStore } from "./credentials.js";
 export { createProjectCtxClient, requireToken, type ProjectCtxClient } from "./cloud-client.js";
 export { runLogin, runLogout, runWhoami, runWorkspaceUse, runWorkspaces } from "./auth-commands.js";
+export { runConnect, buildConnectPlan, formatConnectOutput, inspectClientConfigs, connectPaths, upsertMarkerBlock, mergeMcpServersJson, upsertCodexToml, buildCursorMdc, atomicWriteWithBackup, MCP_SERVER_NAME, MCP_URL, INSTRUCTION_VERSION, type ClientId, type ConnectPlan, type ConnectResult, type ClientPlan, type FileChange, type ClientConfigStatus, type RunConnectOptions } from "./connect.js";
+export { runTokenCreate, runTokenList, runTokenRevoke, type TokenCreateInput, type TokenScope } from "./token-commands.js";
 export { AgentError, redactSensitiveText, toErrorShape, type AgentErrorCode, type AgentErrorShape } from "./errors.js";

package/dist/index.js

@@ -7,4 +7,6 @@ export { checkConfigPermissions, clearAgentToken, clearStoredToken, configDir, c
 export { getCredentialStore, setCredentialStoreForTesting, InMemoryCredentialStore } from "./credentials.js";
 export { createProjectCtxClient, requireToken } from "./cloud-client.js";
 export { runLogin, runLogout, runWhoami, runWorkspaceUse, runWorkspaces } from "./auth-commands.js";
+export { runConnect, buildConnectPlan, formatConnectOutput, inspectClientConfigs, connectPaths, upsertMarkerBlock, mergeMcpServersJson, upsertCodexToml, buildCursorMdc, atomicWriteWithBackup, MCP_SERVER_NAME, MCP_URL, INSTRUCTION_VERSION } from "./connect.js";
+export { runTokenCreate, runTokenList, runTokenRevoke } from "./token-commands.js";
 export { AgentError, redactSensitiveText, toErrorShape } from "./errors.js";

package/dist/mcp.js

@@ -29,7 +29,7 @@ export function createMcpServer(logger) {
     logger?.debug("creating MCP server");
     const server = new McpServer({ name: "projectctx-agent", version: "0.1.0-alpha.0" });
     logger?.debug("registering MCP tool: scan_workspace");
-    server.tool("scan_workspace", "Scan a local workspace with the ProjectCtx scanner and return structured JSON. Read-only: no memory writes or cloud calls. The result includes auditTargets[]: EVERY content-bearing target — git repos, plain folders (docs, notes, research, campaigns), a root-level loose-file cluster (kind file_cluster), and allowlisted agent/tool dot folders such as .claude, .codex, .agents, .cursor, .windsurf, and .github — each with facts, overview excerpts, importantLookingFiles, and a suggestedReadPlan. Coverage mandate: do not silently skip any audit target, and never infer meaning from folder or file names — meaning comes from reading the actual file contents. If skipped contains beyond maxDepth, re-invoke scan_workspace on that subtree with higher maxDepth; depth is iterative, not a reason to stop. Delegation: <=3 targets inspect inline; 4-15 targets use one focused subagent per target; >15 targets cluster related targets by parent folder at 3-5 targets per subagent; never skip a target to save agents. Each subagent prompt must include the target facts block verbatim, overview excerpts, importantLookingFiles, and suggestedReadPlan as a starting point, then read beyond the plan until it can state what the target is for, what decisions/knowledge it holds, and what would be lost if it vanished. Subagents return memory candidates — never writes — e.g. Project, Person, Decision, Research Thread, Campaign, Experiment, Service, Dataset, Open Question, Source (open-ended; capture other meaningful things too), each with title, type, why it matters, source file path(s), confidence, suggested collection, and suggested relationships. Then run a verification pass: confirm each candidate is supported by cited files, captures meaning rather than file inventory, and is not already in memory. Check existence PER CANDIDATE, not with one broad sweep: for each one, search_memory/query_records by its own distinctive name/identifier (for a repo, its name and externalId such as github:owner/repo) — search_memory is ranked and capped, so a single multi-term query is not a census and must never be the basis for declaring anything 'new' or 'missing'. When results are ambiguous, confirm with get_workspace_schema + get_context before concluding. Treat the preview/apply duplicate-title/externalId warnings as a final backstop, not your primary existence check. Run a completeness critic: every target has candidates or a concrete 'nothing meaningful' explanation, no skipped deep subtree is left unre-scanned, and another bounded round would produce nothing new. Present a coverage table to the user before preview/apply; ask before writing anything; use the preview/apply flow only.", {
+    server.tool("scan_workspace", "Scan a local workspace with the ProjectCtx scanner and return structured JSON. Read-only: no memory writes or cloud calls. The result includes auditTargets[]: EVERY content-bearing target — git repos, plain folders (docs, notes, research, campaigns), a root-level loose-file cluster (kind file_cluster), and allowlisted agent/tool dot folders such as .claude, .codex, .agents, .cursor, .windsurf, and .github — each with facts, overview excerpts, importantLookingFiles, and a suggestedReadPlan. Coverage mandate: do not silently skip any audit target, and never infer meaning from folder or file names — meaning comes from reading the actual file contents. If skipped contains beyond maxDepth, re-invoke scan_workspace on that subtree with higher maxDepth; depth is iterative, not a reason to stop. Delegation: <=3 targets inspect inline; 4-15 targets use one focused subagent per target; >15 targets cluster related targets by parent folder at 3-5 targets per subagent; never skip a target to save agents. Each subagent prompt must include the target facts block verbatim, overview excerpts, importantLookingFiles, and suggestedReadPlan as a starting point, then read beyond the plan until it can state the decision, fact, or relationship a future agent would need — if you can only describe what files exist, it is not a candidate. Subagents return memory candidates — never writes — e.g. Project, Person, Decision, Research Thread, Campaign, Experiment, Service, Dataset, Open Question, Source (open-ended; capture other meaningful things too), each with title, type, why it matters, confidence, suggested collection, suggested relationships, and — for every claim — a line-range citation `path:Lstart-Lend` (or a heading anchor for prose docs) plus a verbatim excerpt <=300 chars; these citations become the source `locator` at preview time. When a candidate warrants a NEW collection, also suggest a concise 3-5 typed snake_case field set for it — durable/queryable/at-a-glance dimensions only (status, owner, stage, dates, links); narrative stays in the record markdown, never in fields. Reuse an existing collection's fields rather than proposing parallel ones. CONFIDENCE RUBRIC: high = the claim is stated explicitly in a cited file (README, ADR, manifest); medium = inferred from >=2 consistent independent signals (e.g. dependencies + folder structure + commit messages); low = a single indirect signal. Downgrade low-confidence candidates to Open Question records or drop them — never write them as facts. CONSOLIDATION (when subagents were used): the orchestrator MUST merge all candidates before verification — normalize titles (case/punctuation), merge candidates sharing a normalized title or externalId, union their source citations, keep the highest confidence, and resolve type conflicts explicitly into one merged candidate with the conflict noted (never two records). Only the merged set proceeds to existence checks. VERIFICATION CHECKLIST — output as a table, one row per merged candidate, and do not call any preview tool until it is shown: (1) cited file + line range exists and supports the claim, (2) captures meaning not file inventory, (3) per-candidate existence search performed (show the query used), (4) confidence assigned per the rubric. Check existence PER CANDIDATE, not with one broad sweep: for each one, search_memory/query_records by its own distinctive name/identifier (for a repo, its name and externalId such as github:owner/repo) — search_memory is ranked and capped, so a single multi-term query is not a census and must never be the basis for declaring anything 'new' or 'missing'. When results are ambiguous, confirm with get_workspace_schema + get_context before concluding. Treat the preview/apply duplicate-title/externalId warnings as a final backstop, not your primary existence check. Run a completeness critic: every target has candidates or a concrete 'nothing meaningful' explanation, no skipped deep subtree is left unre-scanned, and another bounded round would produce nothing new. Present a coverage table to the user before preview/apply; ask before writing anything; use the preview/apply flow only.", {
         rootPath: z.string().optional(),
         maxRepos: z.number().int().positive().optional(),
         maxTargets: z.number().int().positive().optional(),
@@ -59,7 +59,7 @@ export function createMcpServer(logger) {
         }
     });
     logger?.debug("registering MCP tool: preview_code_memory");
-    server.tool("preview_code_memory", "Compile codebase scan context and an agent-written code brief into a ProjectCtx memory preview. No durable memory writes are applied. Write each repo brief self-contained: describe the repo on its own terms; do not define it by contrast to sibling records. To group repos, reuse an existing Project rather than forking a parallel one — the compiler reuses an exact-name match and returns warnings that surface similar-named existing projects. Read the returned warnings before you apply. To reuse a surfaced project, pass its externalId as projectExternalId when it has one, or reuse it by its exact title/alias when it does not — projectExternalId accepts only an externalId, never a record id. The flow self-provisions its own code ontology: the Repos and Projects collections and the builds relationship type are reused if they already exist, otherwise created on the fly, and are POPULATED in the same pass (repo + project records, builds links) — so scanning into a brand-new empty workspace needs no seeding. Separately, if the repo context clearly describes an entity type no existing collection covers (e.g. Services, People, Datasets), you may propose it in the optional collections[] input; those emergent collections are created/reconciled by name (exact-name reuse, fuzzy warning) but are NOT populated by code-memory yet — they are created empty. Prefer an existing collection; do not propose one just because a topic is mentioned in passing.", previewCodeMemorySchema.shape, async (input) => {
+    server.tool("preview_code_memory", "Compile codebase scan context and an agent-written code brief into a ProjectCtx memory preview. No durable memory writes are applied. Write each repo brief self-contained: describe the repo on its own terms; do not define it by contrast to sibling records. To group repos, reuse an existing Project rather than forking a parallel one — the compiler reuses an exact-name match and returns warnings that surface similar-named existing projects. Read the returned warnings before you apply. To reuse a surfaced project, pass its externalId as projectExternalId when it has one, or reuse it by its exact title/alias when it does not — projectExternalId accepts only an externalId, never a record id. The flow self-provisions its own code ontology: the Repos and Projects collections and the builds relationship type are reused if they already exist, otherwise created on the fly, and are POPULATED in the same pass (repo + project records, builds links) — so scanning into a brand-new empty workspace needs no seeding. Fields are agent-authored, with no baked-in defaults: to give Repos/Projects structured fields, include collections[] entries named \"Repos\"/\"Projects\" with a concise fields[] (3-5 typed snake_case fields for durable/queryable dimensions — Repo e.g. primary_language/status/deploy_url; Project e.g. status/stage/owner/next_step). Populate them by passing a repo.fields value map and a repo.project.fields value map whose keys match those fields, and put the project's prose in repo.project.markdownBrief so the Project record is not an empty hub. Separately, if the repo context clearly describes an entity type no existing collection covers (e.g. Services, People, Datasets), you may propose it in the optional collections[] input with its own concise fields[]; those emergent collections are created/reconciled by name (exact-name reuse, fuzzy warning) and their fields reconcile additively (existing fields never change). Keep narrative in markdown, not fields. Prefer an existing collection; do not propose one just because a topic is mentioned in passing. Brief-quality rubric: each repo brief must name purpose, key decisions, current state, and next step — a directory listing is not a brief. When the target collection defines REQUIRED fields, populate them; leaving a required field unset is a gap the server will warn on (optional fields are fine to leave empty). Every claim in a brief that is not self-evident from the manifest should carry a locator-bearing source (create_source with a `locator` of `path:Lstart-Lend` or a heading anchor, plus its verbatim excerpt); the server warns on records with no attached source, on any source missing an excerpt, and on repo_doc sources missing a locator (chat/url sources are not expected to have one).", previewCodeMemorySchema.shape, async (input) => {
         try {
             return jsonText(await runPreviewCodeMemory(previewCodeMemorySchema.parse(input), logger));
         }