brainctl 0.1.16 → 0.1.18

package/dist/mcp/server.js

@@ -1,74 +1,25 @@
 import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import path from 'node:path';
 import { FastMCP } from 'fastmcp';
 import { z } from 'zod';
-import { loadConfig } from '../config.js';
-import { loadMemory } from '../context/memory.js';
 import { createAgentConfigService } from '../services/agent-config-service.js';
 import { createDoctorService } from '../services/doctor-service.js';
 import { startUiServer } from '../ui/server.js';
-import { createMemoryWriteService } from '../services/memory-write-service.js';
 import { createProfileExportService } from '../services/profile-export-service.js';
 import { createProfileImportService } from '../services/profile-import-service.js';
+import { createProfileApplyService } from '../services/profile-apply-service.js';
 import { createProfileService } from '../services/profile-service.js';
-import { createRunService } from '../services/run-service.js';
+import { createProfileSnapshotService, defaultBackupProfileName, } from '../services/profile-snapshot-service.js';
 import { createStatusService } from '../services/status-service.js';
-import { createSyncService } from '../services/sync-service.js';
+const ALL_AGENTS = ['claude', 'codex', 'gemini'];
 const packageVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 export function createMcpServer(options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    const uiState = options.uiServerState ?? { current: null };
     const server = new FastMCP({
         name: 'brainctl',
         version: packageVersion.version,
     });
-    server.addTool({
-        name: 'brainctl_list_skills',
-        description: 'List available skills from the ai-stack.yaml config',
-        parameters: z.object({}),
-        execute: async () => {
-            const config = await loadConfig({ cwd });
-            const skills = Object.entries(config.skills).map(([name, skill]) => ({
-                name,
-                description: skill.description ?? null,
-            }));
-            return JSON.stringify(skills, null, 2);
-        },
-    });
-    server.addTool({
-        name: 'brainctl_run',
-        description: 'Execute a skill with input text. Runs the skill through the configured agent and returns the output.',
-        parameters: z.object({
-            skill: z.string().describe('Skill name as defined in ai-stack.yaml'),
-            input: z.string().describe('Input text to pass to the skill'),
-            agent: z.enum(['claude', 'codex']).default('claude').describe('Agent to use for execution'),
-            fallback_agent: z.enum(['claude', 'codex']).optional().describe('Fallback agent if primary is unavailable'),
-        }),
-        execute: async (args) => {
-            const inputPath = path.join(cwd, `.brainctl-mcp-input-${Date.now()}.tmp`);
-            const { writeFile: writeFileAsync, unlink } = await import('node:fs/promises');
-            try {
-                await writeFileAsync(inputPath, args.input, 'utf8');
-                const runService = createRunService();
-                const trace = await runService.execute({
-                    cwd,
-                    skill: args.skill,
-                    inputFile: path.basename(inputPath),
-                    primaryAgent: args.agent,
-                    fallbackAgent: args.fallback_agent,
-                });
-                return trace.finalOutput;
-            }
-            finally {
-                try {
-                    await unlink(inputPath);
-                }
-                catch {
-                    // temp file cleanup is best-effort
-                }
-            }
-        },
-    });
     server.addTool({
         name: 'brainctl_status',
         description: 'Show project status: config path, memory files, available skills, and agent availability',
@@ -90,94 +41,67 @@ export function createMcpServer(options = {}) {
         },
     });
     server.addTool({
-        name: 'brainctl_read_memory',
-        description: 'Read all shared memory files. Returns every markdown file from configured memory paths with file names and content. Use this to understand context left by other agents.',
+        name: 'brainctl_list_profiles',
+        description: 'List available profiles and show which one is active.',
         parameters: z.object({}),
         execute: async () => {
-            const config = await loadConfig({ cwd });
-            const memory = await loadMemory({ paths: config.memory.paths });
-            const result = {
-                count: memory.count,
-                files: memory.entries.map((entry) => ({
-                    path: entry.path,
-                    content: entry.content,
-                })),
-            };
+            const profileService = createProfileService();
+            const result = await profileService.list({ cwd });
             return JSON.stringify(result, null, 2);
         },
     });
     server.addTool({
-        name: 'brainctl_write_memory',
-        description: 'Write or update a shared memory file. Use this to leave notes, decisions, or context for other agents. The file must be within a configured memory path.',
+        name: 'brainctl_apply_profile',
+        description: 'Apply a profile (MCPs, plugins, user skills) to the specified agents. Selective by --agents and --items. Auto-backs up live agent state before a full apply unless backup=false.',
         parameters: z.object({
-            file_path: z.string().describe('Relative path for the memory file (e.g., "memory/notes.md")'),
-            content: z.string().describe('Markdown content to write'),
+            name: z.string().describe('Profile name to apply'),
+            agents: z
+                .array(z.enum(['claude', 'codex', 'gemini']))
+                .optional()
+                .describe('Agents to target (default: all three)'),
+            items: z
+                .array(z.object({
+                type: z.enum(['mcp', 'plugin', 'skill']),
+                name: z.string(),
+            }))
+                .optional()
+                .describe('Specific items to apply (default: everything matching)'),
+            backup: z
+                .boolean()
+                .optional()
+                .describe('Force backup on/off (default: on for full apply, off for partial)'),
         }),
         execute: async (args) => {
-            const memoryWriteService = createMemoryWriteService();
-            const result = await memoryWriteService.execute({
+            const applyService = createProfileApplyService();
+            const result = await applyService.execute({
                 cwd,
-                filePath: args.file_path,
-                content: args.content,
+                profileName: args.name,
+                agents: args.agents ?? ALL_AGENTS,
+                items: args.items,
+                backup: args.backup,
             });
-            return JSON.stringify({ written: result.filePath });
-        },
-    });
-    server.addTool({
-        name: 'brainctl_get_skill',
-        description: 'Get the full details of a specific skill including its prompt text and description. Use this to understand what a skill does before running it.',
-        parameters: z.object({
-            skill: z.string().describe('Skill name as defined in ai-stack.yaml'),
-        }),
-        execute: async (args) => {
-            const config = await loadConfig({ cwd });
-            const skillConfig = config.skills[args.skill];
-            if (!skillConfig) {
-                throw new Error(`Skill "${args.skill}" is not defined in ai-stack.yaml.`);
-            }
-            return JSON.stringify({
-                name: args.skill,
-                description: skillConfig.description ?? null,
-                prompt: skillConfig.prompt,
-            }, null, 2);
-        },
-    });
-    server.addTool({
-        name: 'brainctl_list_profiles',
-        description: 'List available profiles and show which one is active.',
-        parameters: z.object({}),
-        execute: async () => {
-            const profileService = createProfileService();
-            const result = await profileService.list({ cwd });
             return JSON.stringify(result, null, 2);
         },
     });
     server.addTool({
-        name: 'brainctl_switch_profile',
-        description: 'Switch the active profile and sync it to all configured agents. Combines profile switch + sync in one step.',
+        name: 'brainctl_snapshot_agent',
+        description: "Snapshot a live agent's MCPs+plugins+skills into a new profile folder. Useful for backups or capturing your current setup as a shareable profile.",
         parameters: z.object({
-            name: z.string().describe('Profile name to activate'),
+            agent: z.enum(['claude', 'codex', 'gemini']),
+            as: z
+                .string()
+                .optional()
+                .describe('Profile name to write into (default: backup-<agent>-<timestamp>)'),
         }),
         execute: async (args) => {
-            const profileService = createProfileService();
-            const switchResult = await profileService.use({ cwd, name: args.name });
-            const syncService = createSyncService({ profileService });
-            const syncResult = await syncService.execute({ cwd });
-            return JSON.stringify({
-                previousProfile: switchResult.previousProfile,
-                activeProfile: args.name,
-                synced: syncResult,
-            }, null, 2);
-        },
-    });
-    server.addTool({
-        name: 'brainctl_sync',
-        description: 'Sync the active profile to all configured agent configs (Claude, Codex). Creates backups before overwriting.',
-        parameters: z.object({}),
-        execute: async () => {
-            const syncService = createSyncService();
-            const result = await syncService.execute({ cwd });
-            return JSON.stringify(result, null, 2);
+            const snapshotService = createProfileSnapshotService();
+            const profileName = args.as ?? defaultBackupProfileName(args.agent);
+            const result = await snapshotService.execute({
+                cwd,
+                agent: args.agent,
+                profileName,
+            });
+            return JSON.stringify({ profileName, ...result }, null, 2);
         },
     });
     server.addTool({
@@ -211,20 +135,13 @@ export function createMcpServer(options = {}) {
     });
     server.addTool({
         name: 'brainctl_update_profile',
-        description: 'Update a profile config. Pass the full profile object with skills, mcps, and memory fields. Use this to add, remove, or modify skills and MCPs within a profile.',
+        description: 'Update a profile config. Pass the full profile object with name, optional description, and mcps map.',
         parameters: z.object({
             name: z.string().describe('Profile name to update'),
             config: z.object({
                 name: z.string(),
                 description: z.string().optional(),
-                skills: z.record(z.string(), z.object({
-                    description: z.string().optional(),
-                    prompt: z.string(),
-                })),
                 mcps: z.record(z.string(), z.unknown()),
-                memory: z.object({
-                    paths: z.array(z.string()),
-                }),
             }).describe('Full profile config object'),
         }),
         execute: async (args) => {
@@ -251,25 +168,17 @@ export function createMcpServer(options = {}) {
     });
     server.addTool({
         name: 'brainctl_copy_profile_items',
-        description: 'Copy skills and/or MCPs from one profile to another. Specify which skill and MCP keys to copy. Existing items with the same key in the target are overwritten.',
+        description: 'Copy MCPs from one profile to another. Existing MCPs with the same key in the target are overwritten.',
         parameters: z.object({
             source: z.string().describe('Source profile name'),
             target: z.string().describe('Target profile name'),
-            skills: z.array(z.string()).default([]).describe('Skill keys to copy'),
             mcps: z.array(z.string()).default([]).describe('MCP keys to copy'),
         }),
         execute: async (args) => {
             const profileService = createProfileService();
             const sourceProfile = await profileService.get({ cwd, name: args.source });
             const targetProfile = await profileService.get({ cwd, name: args.target });
-            const copiedSkills = [];
             const copiedMcps = [];
-            for (const key of args.skills) {
-                if (sourceProfile.skills[key]) {
-                    targetProfile.skills[key] = sourceProfile.skills[key];
-                    copiedSkills.push(key);
-                }
-            }
             for (const key of args.mcps) {
                 if (sourceProfile.mcps[key]) {
                     targetProfile.mcps[key] = sourceProfile.mcps[key];
@@ -280,7 +189,6 @@ export function createMcpServer(options = {}) {
             return JSON.stringify({
                 source: args.source,
                 target: args.target,
-                copiedSkills,
                 copiedMcps,
             }, null, 2);
         },
@@ -327,33 +235,32 @@ export function createMcpServer(options = {}) {
             return JSON.stringify(result, null, 2);
         },
     });
-    let uiServerInstance = null;
     server.addTool({
         name: 'brainctl_open_ui',
-        description: 'Start the brainctl web dashboard and open it in the default browser. Returns the URL. If already running, reopens the existing URL in the browser.',
+        description: 'Open the brainctl web dashboard in the default browser. The dashboard auto-starts with the MCP server; this tool just opens the URL. Starts the server on demand if auto-start was skipped or failed.',
         parameters: z.object({
-            port: z.number().default(3333).describe('Port number for the UI server'),
+            port: z.number().default(3333).describe('Port to use if the dashboard needs to be started'),
             openBrowser: z
                 .boolean()
                 .default(true)
                 .describe('Whether to launch the default browser at the UI URL'),
         }),
         execute: async (args) => {
-            if (uiServerInstance) {
+            if (uiState.current) {
                 if (args.openBrowser)
-                    openInBrowser(uiServerInstance.url);
+                    openInBrowser(uiState.current.url);
                 return JSON.stringify({
-                    url: uiServerInstance.url,
+                    url: uiState.current.url,
                     status: 'already_running',
                     browserOpened: args.openBrowser,
                 });
             }
             try {
-                uiServerInstance = await startUiServer({ cwd, port: args.port });
+                uiState.current = await startUiServer({ cwd, port: args.port });
                 if (args.openBrowser)
-                    openInBrowser(uiServerInstance.url);
+                    openInBrowser(uiState.current.url);
                 return JSON.stringify({
-                    url: uiServerInstance.url,
+                    url: uiState.current.url,
                     status: 'started',
                     browserOpened: args.openBrowser,
                 });
@@ -368,11 +275,11 @@ export function createMcpServer(options = {}) {
         description: 'Stop the brainctl web dashboard if it is running.',
         parameters: z.object({}),
         execute: async () => {
-            if (!uiServerInstance) {
+            if (!uiState.current) {
                 return JSON.stringify({ status: 'not_running' });
             }
-            await uiServerInstance.close();
-            uiServerInstance = null;
+            await uiState.current.close();
+            uiState.current = null;
             return JSON.stringify({ status: 'stopped' });
         },
     });
@@ -422,9 +329,33 @@ export function createMcpServer(options = {}) {
     return server;
 }
 export async function startMcpServer(options = {}) {
-    const server = createMcpServer(options);
+    const cwd = options.cwd ?? process.cwd();
+    const uiServerState = { current: null };
+    if (process.env.BRAINCTL_AUTO_UI !== '0') {
+        uiServerState.current = await tryAutoStartUi(cwd, 3333);
+    }
+    const server = createMcpServer({ cwd, uiServerState });
     await server.start({ transportType: 'stdio' });
 }
+async function tryAutoStartUi(cwd, port) {
+    try {
+        return await startUiServer({ cwd, port });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EADDRINUSE') {
+            const url = `http://127.0.0.1:${port}`;
+            process.stderr.write(`brainctl: UI port ${port} already in use; assuming another brainctl instance owns ${url}\n`);
+            return {
+                server: null,
+                url,
+                close: async () => { },
+            };
+        }
+        process.stderr.write(`brainctl: UI auto-start failed: ${err.message}\n`);
+        return null;
+    }
+}
 function openInBrowser(url) {
     const platform = process.platform;
     const { command, args } = platform === 'darwin'

package/dist/services/agent-asset-installer.d.ts

@@ -0,0 +1,3 @@
+import type { PortablePluginSnapshot, PortableUserSkillSnapshot } from '../types.js';
+export declare function installPlugin(sourceDir: string, plugin: PortablePluginSnapshot): Promise<void>;
+export declare function installUserSkill(sourceDir: string, skill: PortableUserSkillSnapshot): Promise<void>;

package/dist/services/agent-asset-installer.js

@@ -0,0 +1,109 @@
+import { copyFile, cp, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { ProfileError } from '../errors.js';
+import { formatTimestamp } from './sync/agent-writer.js';
+export async function installPlugin(sourceDir, plugin) {
+    try {
+        await stat(sourceDir);
+    }
+    catch {
+        throw new ProfileError(`Bundled plugin "${plugin.name}" source missing at ${sourceDir}.`);
+    }
+    if (plugin.agent === 'gemini') {
+        return;
+    }
+    const marketplace = plugin.marketplace ?? plugin.source;
+    const version = plugin.version ?? 'unknown';
+    const cacheRoot = path.join(homedir(), `.${plugin.agent}`, 'plugins', 'cache');
+    const targetDir = path.join(cacheRoot, marketplace, plugin.name, version);
+    await rm(targetDir, { recursive: true, force: true });
+    await mkdir(path.dirname(targetDir), { recursive: true });
+    await cp(sourceDir, targetDir, { recursive: true });
+    if (plugin.agent === 'claude') {
+        await registerClaudePlugin({
+            pluginKey: `${plugin.name}@${marketplace}`,
+            installPath: targetDir,
+            version,
+        });
+        return;
+    }
+    if (plugin.agent === 'codex') {
+        await registerCodexPlugin({
+            pluginKey: `${plugin.name}@${marketplace}`,
+        });
+    }
+}
+export async function installUserSkill(sourceDir, skill) {
+    try {
+        await stat(sourceDir);
+    }
+    catch {
+        throw new ProfileError(`Bundled user skill "${skill.name}" source missing at ${sourceDir}.`);
+    }
+    const targetDir = path.join(homedir(), `.${skill.agent}`, 'skills', skill.name);
+    await rm(targetDir, { recursive: true, force: true });
+    await mkdir(path.dirname(targetDir), { recursive: true });
+    await cp(sourceDir, targetDir, { recursive: true });
+}
+async function registerClaudePlugin(options) {
+    const filePath = path.join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
+    let existing = { version: 2, plugins: {} };
+    try {
+        const source = await readFile(filePath, 'utf8');
+        existing = JSON.parse(source);
+        await backupFile(filePath);
+    }
+    catch {
+        // fresh file
+    }
+    const plugins = (existing.plugins ?? {});
+    const now = new Date().toISOString();
+    const entry = {
+        scope: 'user',
+        installPath: options.installPath,
+        version: options.version,
+        installedAt: now,
+        lastUpdated: now,
+    };
+    plugins[options.pluginKey] = [entry];
+    existing.plugins = plugins;
+    if (typeof existing.version !== 'number')
+        existing.version = 2;
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
+async function registerCodexPlugin(options) {
+    const filePath = path.join(homedir(), '.codex', 'config.toml');
+    let existing = '';
+    try {
+        existing = await readFile(filePath, 'utf8');
+        await backupFile(filePath);
+    }
+    catch {
+        existing = '';
+    }
+    const header = `[plugins."${options.pluginKey}"]`;
+    if (existing.includes(header))
+        return;
+    const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    const separator = existing.length > 0 ? '\n' : '';
+    const block = `${header}\nenabled = true\n`;
+    const next = existing + prefix + separator + block;
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await atomicWrite(filePath, next);
+}
+async function backupFile(filePath) {
+    const backupPath = `${filePath}.bak.${formatTimestamp()}`;
+    try {
+        await copyFile(filePath, backupPath);
+    }
+    catch {
+        // file may not exist
+    }
+}
+async function atomicWrite(filePath, content) {
+    const tmpPath = `${filePath}.tmp.${Date.now()}`;
+    await writeFile(tmpPath, content, 'utf8');
+    await rename(tmpPath, filePath);
+}

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

@@ -0,0 +1,11 @@
+import type { AgentName } from '../types.js';
+export interface AgentAvailability {
+    agent: AgentName;
+    available: boolean;
+    command: string;
+    resolvedPath?: string;
+}
+export interface AgentAvailabilityService {
+    getAll(): Promise<Record<AgentName, AgentAvailability>>;
+}
+export declare function createAgentAvailabilityService(): AgentAvailabilityService;

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

@@ -0,0 +1,32 @@
+import { findExecutable } from '../system/executables.js';
+const SUPPORTED_AGENTS = ['claude', 'codex', 'gemini'];
+const AGENT_COMMANDS = {
+    claude: 'claude',
+    codex: 'codex',
+    gemini: 'gemini',
+};
+export function createAgentAvailabilityService() {
+    const cache = new Map();
+    const check = (agent) => {
+        if (!cache.has(agent)) {
+            cache.set(agent, checkAvailability(agent));
+        }
+        return cache.get(agent);
+    };
+    return {
+        async getAll() {
+            const entries = await Promise.all(SUPPORTED_AGENTS.map(async (agent) => [agent, await check(agent)]));
+            return Object.fromEntries(entries);
+        },
+    };
+}
+async function checkAvailability(agent) {
+    const command = AGENT_COMMANDS[agent];
+    const resolvedPath = await findExecutable(command);
+    return {
+        agent,
+        command,
+        available: resolvedPath !== null,
+        resolvedPath: resolvedPath ?? undefined,
+    };
+}

package/dist/services/credential-redaction-service.d.ts

@@ -2,6 +2,7 @@ import type { McpServerConfig, PortableCredentialSpec } from '../types.js';
 export interface CredentialRedactionResult<T extends McpServerConfig> {
     redacted: T;
     credentials: PortableCredentialSpec[];
+    rawValues: Record<string, string>;
 }
 export declare function redactPortableMcpCredentials<T extends McpServerConfig>(config: T): CredentialRedactionResult<T>;
 interface CredentialAccumulator {

package/dist/services/credential-redaction-service.js

@@ -1,8 +1,9 @@
 export function redactPortableMcpCredentials(config) {
     const credentialsByKey = new Map();
-    const redactedEnv = redactStringMap(config.env, 'env', credentialsByKey);
+    const rawValues = {};
+    const redactedEnv = redactStringMap(config.env, 'env', credentialsByKey, rawValues);
     if (config.kind === 'remote') {
-        const redactedHeaders = redactStringMap(config.headers, 'header', credentialsByKey);
+        const redactedHeaders = redactStringMap(config.headers, 'header', credentialsByKey, rawValues);
         return {
             redacted: {
                 ...config,
@@ -10,6 +11,7 @@ export function redactPortableMcpCredentials(config) {
                 ...(redactedHeaders ? { headers: redactedHeaders } : {}),
             },
             credentials: finalizePortableCredentialSpecs(credentialsByKey),
+            rawValues,
         };
     }
     return {
@@ -18,9 +20,10 @@ export function redactPortableMcpCredentials(config) {
             ...(redactedEnv ? { env: redactedEnv } : {}),
         },
         credentials: finalizePortableCredentialSpecs(credentialsByKey),
+        rawValues,
     };
 }
-function redactStringMap(values, source, credentialsByKey) {
+function redactStringMap(values, source, credentialsByKey, rawValues) {
     if (!values) {
         return undefined;
     }
@@ -32,6 +35,9 @@ function redactStringMap(values, source, credentialsByKey) {
         }
         const credentialKey = normalizeCredentialKey(key);
         addCredentialSpec(credentialsByKey, credentialKey, source, key);
+        if (!isCredentialPlaceholder(value)) {
+            rawValues[credentialKey] = value;
+        }
         redacted[key] = isCredentialPlaceholder(value)
             ? value
             : `\${credentials.${credentialKey}}`;

package/dist/services/doctor-service.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutorResolver } from '../executor/resolver.js';
+import { type AgentAvailabilityService } from './agent-availability-service.js';
 import type { DiagnosticCheck } from '../types.js';
 export interface DoctorResult {
     checks: DiagnosticCheck[];
@@ -10,5 +10,5 @@ export interface DoctorService {
     }): Promise<DoctorResult>;
 }
 export declare function createDoctorService(dependencies?: {
-    resolver?: ExecutorResolver;
+    availabilityService?: AgentAvailabilityService;
 }): DoctorService;