brainctl 0.1.21 → 0.1.23

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/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))
@@ -363,11 +396,12 @@ async function readSkillDirs(skillsDir) {
     for (const entry of entries) {
         if (entry.name.startsWith('.'))
             continue;
+        const installPath = path.join(skillsDir, entry.name);
         if (entry.isDirectory()) {
-            skills.push({ name: entry.name, source: 'local', kind: 'skill' });
+            skills.push({ name: entry.name, source: 'local', kind: 'skill', installPath });
         }
         else if (entry.isSymbolicLink()) {
-            skills.push({ name: entry.name, source: 'linked', kind: 'skill' });
+            skills.push({ name: entry.name, source: 'linked', kind: 'skill', installPath });
         }
     }
     return skills;

package/dist/ui/routes.js

@@ -50,6 +50,36 @@ export function createUiRouteHandler(dependencies) {
                 const configs = await agentConfigService.readAll({ cwd: dependencies.cwd });
                 return sendJson(response, 200, configs);
             }
+            case '/api/open-folder': {
+                if (request.method !== 'POST') {
+                    return sendJson(response, 405, { error: 'Method not allowed' });
+                }
+                const body = await readJsonBody(request);
+                if (!body.ok) {
+                    return sendJson(response, 400, { error: 'Invalid JSON body' });
+                }
+                const { path: folderPath } = (body.value ?? {});
+                if (!folderPath || typeof folderPath !== 'string') {
+                    return sendJson(response, 400, { error: 'path is required' });
+                }
+                if (!existsSync(folderPath)) {
+                    return sendJson(response, 404, { error: `Path not found: ${folderPath}` });
+                }
+                const opener = process.platform === 'darwin'
+                    ? 'open'
+                    : process.platform === 'win32'
+                        ? 'explorer'
+                        : 'xdg-open';
+                try {
+                    spawn(opener, [folderPath], { detached: true, stdio: 'ignore' }).unref();
+                    return sendJson(response, 200, { ok: true, path: folderPath });
+                }
+                catch (error) {
+                    return sendJson(response, 500, {
+                        error: error instanceof Error ? error.message : 'Failed to open folder',
+                    });
+                }
+            }
             case '/api/profiles': {
                 if (request.method === 'GET') {
                     const result = await profileService.list({ cwd: dependencies.cwd });
@@ -259,6 +289,7 @@ export function createUiRouteHandler(dependencies) {
                                 key: data.key,
                                 entry: data.entry,
                                 remoteEntry: data.remoteEntry,
+                                scope: data.scope === 'project' ? 'project' : 'global',
                             });
                             return sendJson(response, 200, { ok: true });
                         }
@@ -267,11 +298,13 @@ export function createUiRouteHandler(dependencies) {
                         }
                     }
                     if (request.method === 'DELETE' && mcpKey) {
+                        const scope = url.searchParams.get('scope') === 'project' ? 'project' : 'global';
                         try {
                             await agentConfigService.removeMcp({
                                 cwd: dependencies.cwd,
                                 agent: agentName,
                                 key: mcpKey,
+                                scope,
                             });
                             return sendJson(response, 200, { ok: true });
                         }