brainctl 0.1.5 → 0.1.7

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

@@ -0,0 +1,35 @@
+import type { AgentName } from '../types.js';
+import { type AgentLiveConfig, type AgentMcpEntry } from './sync/agent-reader.js';
+import { type McpPreflightService } from './mcp-preflight-service.js';
+import { type SkillPreflightService } from './skill-preflight-service.js';
+export type { AgentLiveConfig, AgentMcpEntry, AgentSkillEntry } from './sync/agent-reader.js';
+export interface AgentConfigService {
+    readAll(options: {
+        cwd: string;
+    }): Promise<AgentLiveConfig[]>;
+    addMcp(options: {
+        cwd: string;
+        agent: AgentName;
+        key: string;
+        entry: AgentMcpEntry;
+    }): Promise<void>;
+    removeMcp(options: {
+        cwd: string;
+        agent: AgentName;
+        key: string;
+    }): Promise<void>;
+    copySkill(options: {
+        sourceAgent: AgentName;
+        targetAgent: AgentName;
+        skillName: string;
+    }): Promise<void>;
+    removeSkill(options: {
+        agent: AgentName;
+        skillName: string;
+    }): Promise<void>;
+}
+interface AgentConfigServiceDependencies {
+    mcpPreflightService?: McpPreflightService;
+    skillPreflightService?: SkillPreflightService;
+}
+export declare function createAgentConfigService(dependencies?: AgentConfigServiceDependencies): AgentConfigService;

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

@@ -0,0 +1,222 @@
+import { copyFile, cp, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { ValidationError } from '../errors.js';
+import { createClaudeReader, createCodexReader, createGeminiReader, } from './sync/agent-reader.js';
+import { formatTimestamp } from './sync/agent-writer.js';
+import { createMcpPreflightService } from './mcp-preflight-service.js';
+import { createSkillPreflightService } from './skill-preflight-service.js';
+import { getSkillDir } from './skill-paths.js';
+const readers = {
+    claude: createClaudeReader(),
+    codex: createCodexReader(),
+    gemini: createGeminiReader(),
+};
+export function createAgentConfigService(dependencies = {}) {
+    const mcpPreflightService = dependencies.mcpPreflightService ?? createMcpPreflightService();
+    const skillPreflightService = dependencies.skillPreflightService ?? createSkillPreflightService();
+    return {
+        async readAll(options) {
+            const results = await Promise.all([
+                readers.claude.read(options),
+                readers.codex.read(options),
+                readers.gemini.read(options),
+            ]);
+            return results;
+        },
+        async addMcp(options) {
+            const { cwd, agent, key, entry } = options;
+            const preflight = await mcpPreflightService.execute({ cwd, agent, key, entry });
+            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) => {
+                    servers[key] = toClaudeEntry(entry);
+                });
+            }
+            else if (agent === 'codex') {
+                await mutateCodexConfig((servers) => {
+                    servers[key] = entry;
+                });
+            }
+            else if (agent === 'gemini') {
+                await mutateGeminiConfig(cwd, (servers) => {
+                    servers[key] = toGeminiEntry(entry);
+                });
+            }
+        },
+        async removeMcp(options) {
+            const { cwd, agent, key } = options;
+            if (agent === 'claude') {
+                await mutateClaudeConfig(cwd, (servers) => {
+                    delete servers[key];
+                });
+            }
+            else if (agent === 'codex') {
+                await mutateCodexConfig((servers) => {
+                    delete servers[key];
+                });
+            }
+            else if (agent === 'gemini') {
+                await mutateGeminiConfig(cwd, (servers) => {
+                    delete servers[key];
+                });
+            }
+        },
+        async copySkill(options) {
+            const { sourceAgent, targetAgent, skillName } = options;
+            const preflight = await skillPreflightService.execute({
+                sourceAgent,
+                targetAgent,
+                skillName,
+                source: 'local',
+            });
+            const firstError = preflight.checks.find((check) => check.status === 'error');
+            if (firstError) {
+                throw new ValidationError(`Skill "${skillName}" cannot be copied from ${sourceAgent} to ${targetAgent}: ${firstError.message}`);
+            }
+            const sourceDir = getSkillDir(sourceAgent, skillName);
+            const targetDir = getSkillDir(targetAgent, skillName);
+            await mkdir(path.dirname(targetDir), { recursive: true });
+            await cp(sourceDir, targetDir, { recursive: true });
+        },
+        async removeSkill(options) {
+            const { agent, skillName } = options;
+            const skillDir = getSkillDir(agent, skillName);
+            await rm(skillDir, { recursive: true, force: true });
+        },
+    };
+}
+/* ---- Claude: JSON with projects[cwd].mcpServers ---- */
+async function mutateClaudeConfig(cwd, mutate) {
+    const configPath = path.join(homedir(), '.claude.json');
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(configPath, 'utf8'));
+        await backupFile(configPath);
+    }
+    catch {
+        // fresh config
+    }
+    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) {
+    return {
+        type: 'stdio',
+        command: entry.command,
+        args: entry.args ?? [],
+        ...(entry.env ? { env: entry.env } : {}),
+    };
+}
+/* ---- Codex: TOML with [mcp_servers.*] ---- */
+async function mutateCodexConfig(mutate) {
+    const configPath = path.join(homedir(), '.codex', 'config.toml');
+    let existingContent = '';
+    try {
+        existingContent = await readFile(configPath, 'utf8');
+        await backupFile(configPath);
+    }
+    catch {
+        // fresh config
+    }
+    // Read current servers via reader
+    const current = await readers.codex.read({ cwd: '' });
+    const servers = { ...current.mcpServers };
+    mutate(servers);
+    // Rebuild: preserve non-mcp content + new mcp sections
+    const nonMcp = stripCodexMcpSections(existingContent).trim();
+    const mcpToml = buildCodexMcpToml(servers);
+    const final = nonMcp.length > 0 ? `${nonMcp}\n\n${mcpToml}` : mcpToml;
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await atomicWrite(configPath, final + '\n');
+}
+function stripCodexMcpSections(content) {
+    const lines = content.split('\n');
+    const result = [];
+    let inMcp = false;
+    for (const line of lines) {
+        if (/^\[mcp_servers[\].]/.test(line)) {
+            inMcp = true;
+            continue;
+        }
+        if (inMcp && /^\[/.test(line) && !/^\[mcp_servers[\].]/.test(line)) {
+            inMcp = false;
+        }
+        if (!inMcp)
+            result.push(line);
+    }
+    return result.join('\n');
+}
+function buildCodexMcpToml(servers) {
+    const lines = [];
+    for (const [name, entry] of Object.entries(servers)) {
+        lines.push(`[mcp_servers.${name}]`);
+        lines.push(`command = ${tomlStr(entry.command)}`);
+        if (entry.args && entry.args.length > 0) {
+            lines.push(`args = [${entry.args.map(tomlStr).join(', ')}]`);
+        }
+        if (entry.env && Object.keys(entry.env).length > 0) {
+            lines.push('');
+            lines.push(`[mcp_servers.${name}.env]`);
+            for (const [k, v] of Object.entries(entry.env)) {
+                lines.push(`${k} = ${tomlStr(v)}`);
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+function tomlStr(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/* ---- Gemini: JSON with mcpServers ---- */
+async function mutateGeminiConfig(_cwd, mutate) {
+    const configPath = path.join(homedir(), '.gemini', 'settings.json');
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(configPath, 'utf8'));
+        await backupFile(configPath);
+    }
+    catch {
+        // fresh config
+    }
+    const servers = (existing.mcpServers ?? {});
+    mutate(servers);
+    existing.mcpServers = servers;
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await atomicWriteJson(configPath, existing);
+}
+function toGeminiEntry(entry) {
+    return {
+        command: entry.command,
+        args: entry.args ?? [],
+        ...(entry.env ? { env: entry.env } : {}),
+    };
+}
+/* ---- Shared helpers ---- */
+async function backupFile(filePath) {
+    const backupPath = `${filePath}.bak.${formatTimestamp()}`;
+    try {
+        await copyFile(filePath, backupPath);
+    }
+    catch {
+        // File may not exist yet
+    }
+}
+async function atomicWriteJson(filePath, data) {
+    await atomicWrite(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+async function atomicWrite(filePath, content) {
+    const tmpPath = `${filePath}.tmp.${Date.now()}`;
+    await writeFile(tmpPath, content, 'utf8');
+    await rename(tmpPath, filePath);
+}

package/dist/services/mcp-preflight-service.d.ts

@@ -0,0 +1,25 @@
+import type { AgentName } from '../types.js';
+import type { AgentMcpEntry } from './agent-config-service.js';
+export interface McpPreflightCheck {
+    label: string;
+    status: 'ok' | 'warn' | 'error';
+    message: string;
+}
+export interface McpPreflightResult {
+    ok: boolean;
+    checks: McpPreflightCheck[];
+}
+export interface McpPreflightService {
+    execute(options: {
+        cwd: string;
+        agent: AgentName;
+        key: string;
+        entry: AgentMcpEntry;
+    }): Promise<McpPreflightResult>;
+}
+interface McpPreflightDependencies {
+    resolveExecutable?: (command: string) => Promise<string | null>;
+    pathExists?: (targetPath: string) => Promise<boolean>;
+}
+export declare function createMcpPreflightService(dependencies?: McpPreflightDependencies): McpPreflightService;
+export {};

package/dist/services/mcp-preflight-service.js

@@ -0,0 +1,84 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { findExecutable } from '../system/executables.js';
+const SCRIPT_RUNNERS = new Set(['node', 'nodejs', 'python', 'python3', 'bash', 'sh', 'zsh', 'deno', 'bun']);
+export function createMcpPreflightService(dependencies = {}) {
+    const resolveExecutable = dependencies.resolveExecutable ?? findExecutable;
+    const pathExists = dependencies.pathExists ?? defaultPathExists;
+    return {
+        async execute(options) {
+            const checks = [];
+            const resolvedCommand = await resolveExecutable(options.entry.command);
+            if (!resolvedCommand) {
+                checks.push({
+                    label: 'Command',
+                    status: 'error',
+                    message: `Command "${options.entry.command}" is not available on PATH.`,
+                });
+                return { ok: false, checks };
+            }
+            checks.push({
+                label: 'Command',
+                status: 'ok',
+                message: `Command "${options.entry.command}" resolved to ${resolvedCommand}.`,
+            });
+            if (options.entry.command === 'npx') {
+                const nonFlagArg = options.entry.args?.find((arg) => !arg.startsWith('-'));
+                if (!nonFlagArg) {
+                    checks.push({
+                        label: 'Package',
+                        status: 'error',
+                        message: 'npx-based MCP entries must include a package or executable argument.',
+                    });
+                }
+                else {
+                    checks.push({
+                        label: 'Package',
+                        status: 'ok',
+                        message: `npx will attempt to launch ${nonFlagArg}.`,
+                    });
+                }
+            }
+            const entrypointPath = resolveEntrypointPath(options.cwd, options.entry);
+            if (entrypointPath) {
+                const exists = await pathExists(entrypointPath);
+                checks.push({
+                    label: 'Entrypoint',
+                    status: exists ? 'ok' : 'error',
+                    message: exists
+                        ? `Entrypoint script was found: ${entrypointPath}`
+                        : `Entrypoint script was not found: ${entrypointPath}`,
+                });
+            }
+            return {
+                ok: checks.every((check) => check.status !== 'error'),
+                checks,
+            };
+        },
+    };
+}
+function resolveEntrypointPath(cwd, entry) {
+    if (!SCRIPT_RUNNERS.has(entry.command)) {
+        return null;
+    }
+    const firstArg = entry.args?.[0];
+    if (!firstArg || !looksLikeLocalPath(firstArg)) {
+        return null;
+    }
+    return path.isAbsolute(firstArg) ? firstArg : path.resolve(cwd, firstArg);
+}
+function looksLikeLocalPath(value) {
+    return (value.startsWith('.') ||
+        value.startsWith('/') ||
+        value.includes(path.sep) ||
+        /\.(cjs|cts|js|json|jsx|mjs|mts|py|sh|ts|tsx)$/i.test(value));
+}
+async function defaultPathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/services/plugin-install-service.d.ts

@@ -0,0 +1,92 @@
+import type { AgentName } from '../types.js';
+import type { AgentLiveConfig, AgentMcpEntry, AgentSkillEntry } from './agent-config-service.js';
+export interface PluginInstallCheck {
+    label: string;
+    status: 'ok' | 'warn' | 'error';
+    message: string;
+}
+export interface PluginInstallPlan {
+    ok: boolean;
+    checks: PluginInstallCheck[];
+    skills: string[];
+    mcps: Record<string, AgentMcpEntry>;
+}
+export interface PluginInstallResult {
+    installedSkills: string[];
+    installedMcps: string[];
+}
+export interface PluginUninstallPlan {
+    ok: boolean;
+    checks: PluginInstallCheck[];
+    skills: string[];
+    mcps: string[];
+}
+export interface PluginUninstallResult {
+    removedSkills: string[];
+    removedMcps: string[];
+}
+export interface PluginInstallService {
+    plan(options: {
+        cwd: string;
+        targetAgent: AgentName;
+        sourceAgent: AgentName;
+        plugin: AgentSkillEntry;
+    }): Promise<PluginInstallPlan>;
+    execute(options: {
+        cwd: string;
+        targetAgent: AgentName;
+        sourceAgent: AgentName;
+        plugin: AgentSkillEntry;
+    }): Promise<PluginInstallResult>;
+    planRemoval(options: {
+        cwd: string;
+        targetAgent: AgentName;
+        plugin: AgentSkillEntry;
+    }): Promise<PluginUninstallPlan>;
+    remove(options: {
+        cwd: string;
+        targetAgent: AgentName;
+        plugin: AgentSkillEntry;
+    }): Promise<PluginUninstallResult>;
+}
+interface PluginBundle {
+    skills: string[];
+    mcps: Record<string, AgentMcpEntry>;
+}
+interface PluginInstallDependencies {
+    readInstalledPluginBundle?: (installPath: string) => Promise<PluginBundle>;
+    readTargetState?: (options: {
+        cwd: string;
+        agent: AgentName;
+    }) => Promise<Pick<AgentLiveConfig, 'skills' | 'mcpServers'>>;
+    copySkillDirectory?: (options: {
+        sourceInstallPath: string;
+        skillName: string;
+        targetAgent: AgentName;
+    }) => Promise<void>;
+    addMcpEntry?: (options: {
+        cwd: string;
+        agent: AgentName;
+        key: string;
+        entry: AgentMcpEntry;
+    }) => Promise<void>;
+    recordManagedPluginInstall?: (options: {
+        agent: AgentName;
+        plugin: AgentSkillEntry;
+    }) => Promise<void>;
+    removeSkillDirectory?: (options: {
+        targetAgent: AgentName;
+        skillName: string;
+    }) => Promise<void>;
+    removeMcpEntry?: (options: {
+        cwd: string;
+        agent: AgentName;
+        key: string;
+    }) => Promise<void>;
+    removeManagedPluginInstall?: (options: {
+        agent: AgentName;
+        pluginName: string;
+    }) => Promise<void>;
+}
+export declare function createPluginInstallService(dependencies?: PluginInstallDependencies): PluginInstallService;
+export {};