brainctl 0.1.22 → 0.1.25

package/dist/commands/mcp.d.ts

@@ -1,2 +1,14 @@
 import type { Command } from 'commander';
+import { createUpdateCheckService } from '../services/platform/update-check-service.js';
 export declare function registerMcpCommand(program: Command): void;
+export interface AutoUpdateDeps {
+    service?: ReturnType<typeof createUpdateCheckService>;
+    env?: NodeJS.ProcessEnv;
+    log?: (msg: string) => void;
+    relaunch?: (env: NodeJS.ProcessEnv) => number;
+    exit?: (code: number) => void;
+}
+export declare function autoUpdateAndRelaunch(deps?: AutoUpdateDeps): Promise<{
+    updated: boolean;
+    reason?: string;
+}>;

package/dist/commands/mcp.js

@@ -7,16 +7,48 @@ export function registerMcpCommand(program) {
         .description('Start the brainctl MCP server (stdio transport)')
         .action(async () => {
         killPriorMcpServers();
+        await autoUpdateAndRelaunch();
         process.stdin.on('end', () => process.exit(0));
         process.stdin.on('close', () => process.exit(0));
         await startMcpServer({ cwd: process.cwd() });
         if (!process.env.BRAINCTL_NO_UPDATE_CHECK) {
-            // Fire-and-forget after the server is up so cold-start isn't blocked
-            // on a network round-trip (or `npm install brainctl@latest`).
             void notifyIfOutdated();
         }
     });
 }
+export async function autoUpdateAndRelaunch(deps = {}) {
+    const env = deps.env ?? process.env;
+    if (env.BRAINCTL_NO_UPDATE_CHECK)
+        return { updated: false, reason: 'disabled' };
+    if (env.BRAINCTL_NO_AUTO_UPDATE)
+        return { updated: false, reason: 'disabled' };
+    // Guard against a re-launch loop if the new version still reports outdated.
+    if (env.BRAINCTL_SELF_UPDATED === '1')
+        return { updated: false, reason: 'already-updated' };
+    const log = deps.log ?? ((m) => process.stderr.write(m));
+    const relaunch = deps.relaunch ??
+        ((nextEnv) => {
+            const child = spawnSync(process.execPath, process.argv.slice(1), {
+                stdio: 'inherit',
+                env: nextEnv,
+            });
+            return child.status ?? 0;
+        });
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const service = deps.service ?? createUpdateCheckService();
+    const check = await service.check().catch(() => null);
+    if (!check || !check.isOutdated)
+        return { updated: false, reason: 'up-to-date' };
+    log(`brainctl: auto-updating ${check.current} -> ${check.latest}...\n`);
+    const result = await service.selfUpdate();
+    if (!result.success) {
+        log(`brainctl: self-update failed (${result.error ?? 'unknown'}); continuing on ${check.current}\n`);
+        return { updated: false, reason: 'install-failed' };
+    }
+    const status = relaunch({ ...env, BRAINCTL_SELF_UPDATED: '1' });
+    exit(status);
+    return { updated: true };
+}
 function killPriorMcpServers() {
     const self = process.pid;
     const ppid = process.ppid;

package/dist/services/agent/agent-config-service.d.ts

@@ -14,11 +14,13 @@ export interface AgentConfigService {
         key: string;
         entry?: AgentMcpEntry;
         remoteEntry?: PortableRemoteMcpMetadata;
+        scope?: 'global' | 'project';
     }): Promise<void>;
     removeMcp(options: {
         cwd: string;
         agent: AgentName;
         key: string;
+        scope?: 'global' | 'project';
     }): Promise<void>;
     copySkill(options: {
         sourceAgent: AgentName;

package/dist/services/agent/agent-config-service.js

@@ -25,52 +25,83 @@ export function createAgentConfigService(dependencies = {}) {
             return results;
         },
         async addMcp(options) {
-            const { cwd, agent, key, entry, remoteEntry } = options;
+            const { cwd, agent, key, entry, remoteEntry, scope = 'global' } = options;
             const preflight = await mcpPreflightService.execute({ cwd, agent, key, entry, remoteEntry });
             const firstError = preflight.checks.find((check) => check.status === 'error');
             if (firstError) {
                 throw new ValidationError(`MCP "${key}" cannot be added to ${agent}: ${firstError.message}`);
             }
             if (agent === 'claude') {
-                await mutateClaudeConfig(cwd, (servers) => {
+                await mutateClaudeConfig(cwd, scope, (servers) => {
                     servers[key] = remoteEntry ? toClaudeRemoteEntry(remoteEntry) : toClaudeEntry(entry);
                 });
             }
             else if (agent === 'codex') {
-                await mutateCodexConfig(cwd, (state) => {
-                    delete state.mcpServers[key];
-                    delete state.remoteMcpServers[key];
-                    if (remoteEntry) {
-                        state.remoteMcpServers[key] = remoteEntry;
-                    }
-                    else {
-                        state.mcpServers[key] = entry;
-                    }
-                });
+                if (scope === 'project') {
+                    await mutateBrainctlProjectMcps(cwd, 'codex', (state) => {
+                        delete state.mcpServers[key];
+                        delete state.remoteMcpServers[key];
+                        if (remoteEntry) {
+                            state.remoteMcpServers[key] = remoteEntry;
+                        }
+                        else {
+                            state.mcpServers[key] = entry;
+                        }
+                    });
+                }
+                else {
+                    await mutateCodexConfig(cwd, (state) => {
+                        delete state.mcpServers[key];
+                        delete state.remoteMcpServers[key];
+                        if (remoteEntry) {
+                            state.remoteMcpServers[key] = remoteEntry;
+                        }
+                        else {
+                            state.mcpServers[key] = entry;
+                        }
+                    });
+                }
             }
             else if (agent === 'gemini') {
-                await mutateGeminiConfig(cwd, (servers) => {
-                    servers[key] = remoteEntry ? toGeminiRemoteEntry(remoteEntry) : toGeminiEntry(entry);
-                });
+                if (scope === 'project') {
+                    await mutateBrainctlProjectMcps(cwd, 'gemini', (state) => {
+                        delete state.mcpServers[key];
+                        delete state.remoteMcpServers[key];
+                        if (remoteEntry) {
+                            state.remoteMcpServers[key] = remoteEntry;
+                        }
+                        else {
+                            state.mcpServers[key] = entry;
+                        }
+                    });
+                }
+                else {
+                    await mutateGeminiConfig(cwd, (servers) => {
+                        servers[key] = remoteEntry ? toGeminiRemoteEntry(remoteEntry) : toGeminiEntry(entry);
+                    });
+                }
             }
         },
         async removeMcp(options) {
-            const { cwd, agent, key } = options;
+            const { cwd, agent, key, scope = 'global' } = options;
             if (agent === 'claude') {
-                await mutateClaudeConfig(cwd, (servers) => {
-                    delete servers[key];
-                });
+                await mutateClaudeConfig(cwd, scope, (servers) => { delete servers[key]; });
             }
             else if (agent === 'codex') {
-                await mutateCodexConfig(cwd, (state) => {
-                    delete state.mcpServers[key];
-                    delete state.remoteMcpServers[key];
-                });
+                if (scope === 'project') {
+                    await mutateBrainctlProjectMcps(cwd, 'codex', (state) => { delete state.mcpServers[key]; delete state.remoteMcpServers[key]; });
+                }
+                else {
+                    await mutateCodexConfig(cwd, (state) => { delete state.mcpServers[key]; delete state.remoteMcpServers[key]; });
+                }
             }
             else if (agent === 'gemini') {
-                await mutateGeminiConfig(cwd, (servers) => {
-                    delete servers[key];
-                });
+                if (scope === 'project') {
+                    await mutateBrainctlProjectMcps(cwd, 'gemini', (state) => { delete state.mcpServers[key]; delete state.remoteMcpServers[key]; });
+                }
+                else {
+                    await mutateGeminiConfig(cwd, (servers) => { delete servers[key]; });
+                }
             }
         },
         async copySkill(options) {
@@ -98,7 +129,7 @@ export function createAgentConfigService(dependencies = {}) {
     };
 }
 /* ---- Claude: JSON with projects[cwd].mcpServers ---- */
-async function mutateClaudeConfig(cwd, mutate) {
+async function mutateClaudeConfig(cwd, scope, mutate) {
     const configPath = path.join(homedir(), '.claude.json');
     let existing = {};
     try {
@@ -108,18 +139,20 @@ async function mutateClaudeConfig(cwd, mutate) {
     catch {
         // fresh config
     }
-    // Apply mutation to user-scoped (top-level) MCPs
-    const userServers = (existing.mcpServers ?? {});
-    mutate(userServers);
-    existing.mcpServers = userServers;
-    // Apply mutation to project-scoped MCPs
-    const projects = (existing.projects ?? {});
-    const projectConfig = projects[cwd] ?? {};
-    const servers = (projectConfig.mcpServers ?? {});
-    mutate(servers);
-    projectConfig.mcpServers = servers;
-    projects[cwd] = projectConfig;
-    existing.projects = projects;
+    if (scope === 'global') {
+        const servers = (existing.mcpServers ?? {});
+        mutate(servers);
+        existing.mcpServers = servers;
+    }
+    else {
+        const projects = (existing.projects ?? {});
+        const projectConfig = (projects[cwd] ?? {});
+        const servers = (projectConfig.mcpServers ?? {});
+        mutate(servers);
+        projectConfig.mcpServers = servers;
+        projects[cwd] = projectConfig;
+        existing.projects = projects;
+    }
     await atomicWriteJson(configPath, existing);
 }
 function toClaudeEntry(entry) {
@@ -237,6 +270,40 @@ function toGeminiRemoteEntry(entry) {
         ...(entry.env ? { env: entry.env } : {}),
     };
 }
+/* ---- Brainctl project MCPs: .brainctl/project-mcps.json ---- */
+async function mutateBrainctlProjectMcps(cwd, agent, mutate) {
+    const filePath = path.join(cwd, '.brainctl', 'project-mcps.json');
+    let data = {};
+    try {
+        data = JSON.parse(await readFile(filePath, 'utf8'));
+    }
+    catch {
+        // fresh file
+    }
+    const agentData = (data[agent] ?? {});
+    const rawServers = (agentData.mcpServers ?? {});
+    const mcpServers = {};
+    const remoteMcpServers = {};
+    for (const [name, entry] of Object.entries(rawServers)) {
+        if (typeof entry.url === 'string' && entry.url) {
+            remoteMcpServers[name] = { transport: entry.transport ?? 'http', url: entry.url };
+        }
+        else {
+            mcpServers[name] = { command: String(entry.command ?? ''), args: Array.isArray(entry.args) ? entry.args.map(String) : undefined };
+        }
+    }
+    mutate({ mcpServers, remoteMcpServers });
+    const newServers = {};
+    for (const [name, entry] of Object.entries(mcpServers)) {
+        newServers[name] = { command: entry.command, ...(entry.args ? { args: entry.args } : {}), ...(entry.env ? { env: entry.env } : {}) };
+    }
+    for (const [name, entry] of Object.entries(remoteMcpServers)) {
+        newServers[name] = { transport: entry.transport, url: entry.url };
+    }
+    data[agent] = { mcpServers: newServers };
+    await mkdir(path.join(cwd, '.brainctl'), { recursive: true });
+    await atomicWriteJson(filePath, data);
+}
 /* ---- Shared helpers ---- */
 async function backupFile(filePath) {
     const backupPath = `${filePath}.bak.${formatTimestamp()}`;

package/dist/services/platform/recent-projects-service.d.ts

@@ -0,0 +1,16 @@
+interface FsLike {
+    readFile(p: string): Promise<string>;
+    writeFile(p: string, content: string): Promise<void>;
+    mkdir(p: string, opts?: {
+        recursive: boolean;
+    }): Promise<unknown>;
+}
+export interface RecentProjectsService {
+    read(): Promise<string[]>;
+    addRecent(cwd: string): Promise<string[]>;
+}
+export declare function createRecentProjectsService(deps: {
+    filePath: string;
+    fs?: FsLike;
+}): RecentProjectsService;
+export {};

package/dist/services/platform/recent-projects-service.js

@@ -0,0 +1,51 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const MAX_RECENTS = 20;
+const FILE_VERSION = 1;
+const defaultFs = {
+    readFile: (p) => readFile(p, 'utf8'),
+    writeFile: (p, content) => writeFile(p, content, 'utf8'),
+    mkdir: (p, opts) => mkdir(p, opts),
+};
+export function createRecentProjectsService(deps) {
+    const { filePath, fs: fsImpl = defaultFs } = deps;
+    async function readFile_() {
+        try {
+            const content = await fsImpl.readFile(filePath);
+            const parsed = JSON.parse(content);
+            if (typeof parsed === 'object' && parsed !== null && 'recents' in parsed) {
+                return parsed;
+            }
+            return null;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return null;
+            }
+            throw err;
+        }
+    }
+    async function persist(recents) {
+        const dir = path.dirname(filePath);
+        await fsImpl.mkdir(dir, { recursive: true });
+        const data = { version: FILE_VERSION, recents };
+        await fsImpl.writeFile(filePath, JSON.stringify(data, null, 2));
+    }
+    async function read() {
+        const data = await readFile_();
+        if (!data)
+            return [];
+        return (data.recents ?? []).filter((e) => typeof e === 'string');
+    }
+    async function addRecent(cwd) {
+        if (!path.isAbsolute(cwd)) {
+            throw new Error(`cwd must be an absolute path, got: ${cwd}`);
+        }
+        const current = await read();
+        const deduplicated = current.filter((p) => p !== cwd);
+        const updated = [cwd, ...deduplicated].slice(0, MAX_RECENTS);
+        await persist(updated);
+        return updated;
+    }
+    return { read, addRecent };
+}

package/dist/services/sync/agent-reader.d.ts

@@ -27,6 +27,8 @@ export interface AgentLiveConfig {
     exists: boolean;
     mcpServers: Record<string, AgentMcpEntry>;
     remoteMcpServers: Record<string, PortableRemoteMcpMetadata>;
+    projectMcpServers: Record<string, AgentMcpEntry>;
+    projectRemoteMcpServers: Record<string, PortableRemoteMcpMetadata>;
     skills: AgentSkillEntry[];
 }
 export interface AgentConfigReader {

package/dist/services/sync/agent-reader.js

@@ -10,39 +10,40 @@ export function createClaudeReader() {
             try {
                 const source = await readFile(configPath, 'utf8');
                 const data = JSON.parse(source);
-                // Merge user-scoped MCPs (top-level) with project-scoped MCPs (project overrides user)
                 const userServers = (data.mcpServers ?? {});
                 const projects = (data.projects ?? {});
-                const projectConfig = projects[options.cwd] ?? {};
+                const projectConfig = (projects[options.cwd] ?? {});
                 const projectServers = (projectConfig.mcpServers ?? {});
-                const rawServers = { ...userServers, ...projectServers };
                 const mcpServers = {};
                 const remoteMcpServers = {};
-                for (const [name, entry] of Object.entries(rawServers)) {
+                for (const [name, entry] of Object.entries(userServers)) {
                     if (isClaudeRemoteEntry(entry)) {
-                        const url = typeof entry.url === 'string' ? entry.url : '';
-                        remoteMcpServers[name] = {
-                            transport: entry.type === 'sse' ? 'sse' : 'http',
-                            url,
-                            headers: parseEnvObject(entry.headers),
-                            env: parseEnvObject(entry.env),
-                        };
-                        continue;
+                        remoteMcpServers[name] = { transport: entry.type === 'sse' ? 'sse' : 'http', url: String(entry.url ?? ''), headers: parseEnvObject(entry.headers), env: parseEnvObject(entry.env) };
+                    }
+                    else {
+                        mcpServers[name] = { command: String(entry.command ?? ''), args: Array.isArray(entry.args) ? entry.args.map(String) : undefined, env: parseEnvObject(entry.env) };
+                    }
+                }
+                const projectMcpServers = {};
+                const projectRemoteMcpServers = {};
+                for (const [name, entry] of Object.entries(projectServers)) {
+                    if (isClaudeRemoteEntry(entry)) {
+                        projectRemoteMcpServers[name] = { transport: entry.type === 'sse' ? 'sse' : 'http', url: String(entry.url ?? ''), headers: parseEnvObject(entry.headers), env: parseEnvObject(entry.env) };
+                    }
+                    else {
+                        projectMcpServers[name] = { command: String(entry.command ?? ''), args: Array.isArray(entry.args) ? entry.args.map(String) : undefined, env: parseEnvObject(entry.env) };
                     }
-                    mcpServers[name] = {
-                        command: String(entry.command ?? ''),
-                        args: Array.isArray(entry.args) ? entry.args.map(String) : undefined,
-                        env: parseEnvObject(entry.env),
-                    };
                 }
                 const skills = await readClaudePlugins();
-                const filtered = filterPluginOwnedMcps({ mcpServers, remoteMcpServers, skills });
+                const filtered = filterPluginOwnedMcps({ mcpServers, remoteMcpServers, projectMcpServers, projectRemoteMcpServers, skills });
                 return {
                     agent: 'claude',
                     configPath,
                     exists: true,
                     mcpServers: filtered.mcpServers,
                     remoteMcpServers: filtered.remoteMcpServers,
+                    projectMcpServers: filtered.projectMcpServers,
+                    projectRemoteMcpServers: filtered.projectRemoteMcpServers,
                     skills,
                 };
             }
@@ -54,6 +55,8 @@ export function createClaudeReader() {
                     exists: false,
                     mcpServers: {},
                     remoteMcpServers: {},
+                    projectMcpServers: {},
+                    projectRemoteMcpServers: {},
                     skills,
                 };
             }
@@ -62,19 +65,22 @@ export function createClaudeReader() {
 }
 export function createCodexReader() {
     return {
-        async read() {
+        async read(options) {
             const configPath = path.join(homedir(), '.codex', 'config.toml');
+            const { projectMcpServers, projectRemoteMcpServers } = await readBrainctlProjectMcps(options.cwd, 'codex');
             try {
                 const source = await readFile(configPath, 'utf8');
                 const { mcpServers, remoteMcpServers } = parseCodexToml(source);
                 const skills = await readCodexSkills();
-                const filtered = filterPluginOwnedMcps({ mcpServers, remoteMcpServers, skills });
+                const filtered = filterPluginOwnedMcps({ mcpServers, remoteMcpServers, projectMcpServers, projectRemoteMcpServers, skills });
                 return {
                     agent: 'codex',
                     configPath,
                     exists: true,
                     mcpServers: filtered.mcpServers,
                     remoteMcpServers: filtered.remoteMcpServers,
+                    projectMcpServers: filtered.projectMcpServers,
+                    projectRemoteMcpServers: filtered.projectRemoteMcpServers,
                     skills,
                 };
             }
@@ -86,6 +92,8 @@ export function createCodexReader() {
                     exists: false,
                     mcpServers: {},
                     remoteMcpServers: {},
+                    projectMcpServers,
+                    projectRemoteMcpServers,
                     skills,
                 };
             }
@@ -94,8 +102,9 @@ export function createCodexReader() {
 }
 export function createGeminiReader() {
     return {
-        async read() {
+        async read(options) {
             const configPath = path.join(homedir(), '.gemini', 'settings.json');
+            const { projectMcpServers, projectRemoteMcpServers } = await readBrainctlProjectMcps(options.cwd, 'gemini');
             let rawServers = {};
             let exists = false;
             try {
@@ -115,33 +124,57 @@ export function createGeminiReader() {
                     remoteMcpServers[name] = remoteEntry;
                     continue;
                 }
-                mcpServers[name] = {
-                    command: String(entry.command ?? ''),
-                    args: Array.isArray(entry.args) ? entry.args.map(String) : undefined,
-                    env: parseEnvObject(entry.env),
-                };
+                mcpServers[name] = { command: String(entry.command ?? ''), args: Array.isArray(entry.args) ? entry.args.map(String) : undefined, env: parseEnvObject(entry.env) };
             }
             const skills = await readGeminiSkills();
-            const filtered = filterPluginOwnedMcps({ mcpServers, remoteMcpServers, skills });
+            const filtered = filterPluginOwnedMcps({ mcpServers, remoteMcpServers, projectMcpServers, projectRemoteMcpServers, skills });
             return {
                 agent: 'gemini',
                 configPath,
                 exists,
                 mcpServers: filtered.mcpServers,
                 remoteMcpServers: filtered.remoteMcpServers,
+                projectMcpServers: filtered.projectMcpServers,
+                projectRemoteMcpServers: filtered.projectRemoteMcpServers,
                 skills,
             };
         },
     };
 }
+async function readBrainctlProjectMcps(cwd, agent) {
+    try {
+        const filePath = path.join(cwd, '.brainctl', 'project-mcps.json');
+        const data = JSON.parse(await readFile(filePath, 'utf8'));
+        const agentData = (data[agent] ?? {});
+        const rawServers = (agentData.mcpServers ?? {});
+        const projectMcpServers = {};
+        const projectRemoteMcpServers = {};
+        for (const [name, entry] of Object.entries(rawServers)) {
+            if (typeof entry.url === 'string' && entry.url) {
+                projectRemoteMcpServers[name] = { transport: entry.transport ?? 'http', url: entry.url, headers: parseEnvObject(entry.headers), env: parseEnvObject(entry.env) };
+            }
+            else {
+                projectMcpServers[name] = { command: String(entry.command ?? ''), args: Array.isArray(entry.args) ? entry.args.map(String) : undefined, env: parseEnvObject(entry.env) };
+            }
+        }
+        return { projectMcpServers, projectRemoteMcpServers };
+    }
+    catch {
+        return { projectMcpServers: {}, projectRemoteMcpServers: {} };
+    }
+}
 function filterPluginOwnedMcps(options) {
     const pluginOwned = new Set(options.skills.flatMap((skill) => skill.pluginMcps ?? []));
     if (pluginOwned.size === 0) {
-        return { mcpServers: options.mcpServers, remoteMcpServers: options.remoteMcpServers };
+        return { mcpServers: options.mcpServers, remoteMcpServers: options.remoteMcpServers, projectMcpServers: options.projectMcpServers, projectRemoteMcpServers: options.projectRemoteMcpServers };
     }
-    const mcpServers = Object.fromEntries(Object.entries(options.mcpServers).filter(([key]) => !pluginOwned.has(key)));
-    const remoteMcpServers = Object.fromEntries(Object.entries(options.remoteMcpServers).filter(([key]) => !pluginOwned.has(key)));
-    return { mcpServers, remoteMcpServers };
+    const notOwned = ([key]) => !pluginOwned.has(key);
+    return {
+        mcpServers: Object.fromEntries(Object.entries(options.mcpServers).filter(notOwned)),
+        remoteMcpServers: Object.fromEntries(Object.entries(options.remoteMcpServers).filter(notOwned)),
+        projectMcpServers: Object.fromEntries(Object.entries(options.projectMcpServers).filter(notOwned)),
+        projectRemoteMcpServers: Object.fromEntries(Object.entries(options.projectRemoteMcpServers).filter(notOwned)),
+    };
 }
 function parseEnvObject(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))

package/dist/ui/routes.d.ts

@@ -3,6 +3,8 @@ import type { StatusService } from '../services/platform/status-service.js';
 export interface UiRouteDependencies {
     cwd: string;
     statusService?: StatusService;
+    recentsFilePath?: string;
+    claudeJsonPath?: string;
 }
 export type UiRouteHandler = (request: IncomingMessage, response: ServerResponse) => Promise<void>;
 export declare function createUiRouteHandler(dependencies: UiRouteDependencies): UiRouteHandler;