brainctl 0.1.5 → 0.1.7

package/dist/services/plugin-install-service.js

@@ -0,0 +1,243 @@
+import { cp, mkdir, readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { ValidationError } from '../errors.js';
+import { createAgentConfigService } from './agent-config-service.js';
+import { getSkillDir } from './skill-paths.js';
+import { removeManagedPluginInstall, writeManagedPluginInstall, } from './sync/managed-plugin-registry.js';
+export function createPluginInstallService(dependencies = {}) {
+    const agentConfigService = createAgentConfigService();
+    const readInstalledPluginBundle = dependencies.readInstalledPluginBundle ?? defaultReadInstalledPluginBundle;
+    const readTargetState = dependencies.readTargetState ?? (async ({ cwd, agent }) => {
+        const configs = await agentConfigService.readAll({ cwd });
+        const match = configs.find((config) => config.agent === agent);
+        return {
+            skills: match?.skills ?? [],
+            mcpServers: match?.mcpServers ?? {},
+        };
+    });
+    const copySkillDirectory = dependencies.copySkillDirectory ?? defaultCopySkillDirectory;
+    const addMcpEntry = dependencies.addMcpEntry ?? (async ({ cwd, agent, key, entry }) => {
+        await agentConfigService.addMcp({ cwd, agent, key, entry });
+    });
+    const recordManagedPluginInstall = dependencies.recordManagedPluginInstall ??
+        (async ({ agent, plugin }) => {
+            await writeManagedPluginInstall({ agent, plugin });
+        });
+    const removeSkillDirectory = dependencies.removeSkillDirectory ?? defaultRemoveSkillDirectory;
+    const removeMcpEntry = dependencies.removeMcpEntry ?? (async ({ cwd, agent, key }) => {
+        await agentConfigService.removeMcp({ cwd, agent, key });
+    });
+    const removeRecordedManagedPluginInstall = dependencies.removeManagedPluginInstall ??
+        (async ({ agent, pluginName }) => {
+            await removeManagedPluginInstall({ agent, pluginName });
+        });
+    return {
+        async plan(options) {
+            const checks = [];
+            if (options.plugin.kind !== 'plugin' || !options.plugin.installPath) {
+                checks.push({
+                    label: 'Source plugin',
+                    status: 'error',
+                    message: `Plugin "${options.plugin.name}" is missing an install path and cannot be installed as a bundle.`,
+                });
+                return { ok: false, checks, skills: [], mcps: {} };
+            }
+            const bundle = await readInstalledPluginBundle(options.plugin.installPath);
+            const targetState = await readTargetState({
+                cwd: options.cwd,
+                agent: options.targetAgent,
+            });
+            checks.push({
+                label: 'Bundle',
+                status: 'ok',
+                message: `Discovered ${bundle.skills.length} skills and ${Object.keys(bundle.mcps).length} MCPs in plugin "${options.plugin.name}".`,
+            });
+            if (bundle.skills.length === 0 && Object.keys(bundle.mcps).length === 0) {
+                checks.push({
+                    label: 'Bundle',
+                    status: 'error',
+                    message: `Plugin "${options.plugin.name}" does not expose portable skills or MCPs for installation.`,
+                });
+            }
+            for (const skillName of bundle.skills) {
+                if (targetState.skills.some((skill) => skill.name === skillName)) {
+                    checks.push({
+                        label: 'Target skill',
+                        status: 'error',
+                        message: `Skill "${skillName}" already exists in ${options.targetAgent}.`,
+                    });
+                }
+            }
+            for (const key of Object.keys(bundle.mcps)) {
+                if (targetState.mcpServers[key]) {
+                    checks.push({
+                        label: 'Target MCP',
+                        status: 'error',
+                        message: `MCP "${key}" already exists in ${options.targetAgent}.`,
+                    });
+                }
+            }
+            return {
+                ok: checks.every((check) => check.status !== 'error'),
+                checks,
+                skills: bundle.skills,
+                mcps: bundle.mcps,
+            };
+        },
+        async execute(options) {
+            const plan = await this.plan(options);
+            if (!plan.ok) {
+                const firstError = plan.checks.find((check) => check.status === 'error');
+                throw new ValidationError(firstError?.message ?? 'Plugin install plan failed.');
+            }
+            const installPath = options.plugin.installPath;
+            for (const skillName of plan.skills) {
+                await copySkillDirectory({
+                    sourceInstallPath: installPath,
+                    skillName,
+                    targetAgent: options.targetAgent,
+                });
+            }
+            for (const [key, entry] of Object.entries(plan.mcps)) {
+                await addMcpEntry({
+                    cwd: options.cwd,
+                    agent: options.targetAgent,
+                    key,
+                    entry,
+                });
+            }
+            await recordManagedPluginInstall({
+                agent: options.targetAgent,
+                plugin: {
+                    ...options.plugin,
+                    kind: 'plugin',
+                    pluginSkills: plan.skills,
+                    pluginMcps: Object.keys(plan.mcps),
+                    managed: true,
+                },
+            });
+            return {
+                installedSkills: plan.skills,
+                installedMcps: Object.keys(plan.mcps),
+            };
+        },
+        async planRemoval(options) {
+            const checks = [];
+            if (options.plugin.kind !== 'plugin') {
+                checks.push({
+                    label: 'Target plugin',
+                    status: 'error',
+                    message: `"${options.plugin.name}" is not a plugin entry.`,
+                });
+                return { ok: false, checks, skills: [], mcps: [] };
+            }
+            if (!options.plugin.managed) {
+                checks.push({
+                    label: 'Target plugin',
+                    status: 'error',
+                    message: `Only Brainctl-managed plugin installs can be removed today. "${options.plugin.name}" is not managed by Brainctl on ${options.targetAgent}.`,
+                });
+                return { ok: false, checks, skills: [], mcps: [] };
+            }
+            let skills = [...(options.plugin.pluginSkills ?? [])];
+            let mcps = [...(options.plugin.pluginMcps ?? [])];
+            if ((skills.length === 0 || mcps.length === 0) && options.plugin.installPath) {
+                const bundle = await readInstalledPluginBundle(options.plugin.installPath);
+                if (skills.length === 0) {
+                    skills = bundle.skills;
+                }
+                if (mcps.length === 0) {
+                    mcps = Object.keys(bundle.mcps);
+                }
+            }
+            checks.push({
+                label: 'Bundle',
+                status: 'ok',
+                message: `Will remove ${skills.length} skills and ${mcps.length} MCPs from plugin "${options.plugin.name}".`,
+            });
+            return {
+                ok: true,
+                checks,
+                skills,
+                mcps,
+            };
+        },
+        async remove(options) {
+            const plan = await this.planRemoval(options);
+            if (!plan.ok) {
+                const firstError = plan.checks.find((check) => check.status === 'error');
+                throw new ValidationError(firstError?.message ?? 'Plugin removal plan failed.');
+            }
+            for (const skillName of plan.skills) {
+                await removeSkillDirectory({
+                    targetAgent: options.targetAgent,
+                    skillName,
+                });
+            }
+            for (const key of plan.mcps) {
+                await removeMcpEntry({
+                    cwd: options.cwd,
+                    agent: options.targetAgent,
+                    key,
+                });
+            }
+            await removeRecordedManagedPluginInstall({
+                agent: options.targetAgent,
+                pluginName: options.plugin.name,
+            });
+            return {
+                removedSkills: plan.skills,
+                removedMcps: plan.mcps,
+            };
+        },
+    };
+}
+async function defaultReadInstalledPluginBundle(installPath) {
+    const skillsDir = path.join(installPath, 'skills');
+    let skills = [];
+    try {
+        const { readdir } = await import('node:fs/promises');
+        const entries = await readdir(skillsDir, { withFileTypes: true });
+        skills = entries
+            .filter((entry) => !entry.name.startsWith('.') && entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch {
+        skills = [];
+    }
+    let mcps = {};
+    try {
+        const mcpSource = await readFile(path.join(installPath, '.mcp.json'), 'utf8');
+        const parsed = JSON.parse(mcpSource);
+        mcps = Object.fromEntries(Object.entries(parsed)
+            .filter(([, value]) => typeof value?.command === 'string')
+            .map(([key, value]) => [
+            key,
+            {
+                command: String(value.command),
+                args: Array.isArray(value.args) ? value.args.map(String) : undefined,
+                env: value.env && typeof value.env === 'object' && !Array.isArray(value.env)
+                    ? Object.fromEntries(Object.entries(value.env).map(([envKey, envValue]) => [
+                        envKey,
+                        String(envValue),
+                    ]))
+                    : undefined,
+            },
+        ]));
+    }
+    catch {
+        mcps = {};
+    }
+    return { skills, mcps };
+}
+async function defaultCopySkillDirectory(options) {
+    const sourceDir = path.join(options.sourceInstallPath, 'skills', options.skillName);
+    const targetDir = getSkillDir(options.targetAgent, options.skillName);
+    await mkdir(path.dirname(targetDir), { recursive: true });
+    await cp(sourceDir, targetDir, { recursive: true });
+}
+async function defaultRemoveSkillDirectory(options) {
+    const targetDir = getSkillDir(options.targetAgent, options.skillName);
+    await rm(targetDir, { recursive: true, force: true });
+}

package/dist/services/profile-export-service.js

@@ -30,7 +30,7 @@ async function stageProfile(profile, cwd, stagingDir) {
     const mcpsDir = path.join(stagingDir, 'mcps');
     const exportMcps = {};
     for (const [name, mcp] of Object.entries(profile.mcps)) {
-        if (mcp.type === 'bundled') {
+        if (mcp.kind === 'local' && mcp.source === 'bundled') {
             const sourcePath = path.isAbsolute(mcp.path)
                 ? mcp.path
                 : path.resolve(cwd, mcp.path);
@@ -41,17 +41,17 @@ async function stageProfile(profile, cwd, stagingDir) {
                 filter: (src) => !src.includes('node_modules'),
             });
             exportMcps[name] = {
-                type: 'bundled',
+                kind: 'local',
+                source: 'bundled',
                 path: `./mcps/${name}`,
                 ...(mcp.install ? { install: mcp.install } : {}),
                 command: mcp.command,
                 ...(mcp.args ? { args: mcp.args } : {}),
                 ...(mcp.env ? { env: mcp.env } : {}),
             };
+            continue;
         }
-        else {
-            exportMcps[name] = mcp;
-        }
+        exportMcps[name] = mcp;
     }
     return {
         name: profile.name,

package/dist/services/profile-import-service.js

@@ -39,7 +39,7 @@ export function createProfileImportService() {
                 const installedMcps = [];
                 const mcpsBaseDir = path.join(cwd, PROFILES_DIR, profileName, 'mcps');
                 for (const [name, mcp] of Object.entries(profile.mcps)) {
-                    if (mcp.type !== 'bundled')
+                    if (!(mcp.kind === 'local' && mcp.source === 'bundled'))
                         continue;
                     const extractedMcpPath = path.join(extractDir, 'mcps', name);
                     const destMcpPath = path.join(mcpsBaseDir, name);

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

@@ -17,6 +17,15 @@ export interface ProfileService {
     }): Promise<{
         profilePath: string;
     }>;
+    update(options: {
+        cwd?: string;
+        name: string;
+        config: ProfileConfig;
+    }): Promise<void>;
+    delete(options: {
+        cwd?: string;
+        name: string;
+    }): Promise<void>;
     use(options: {
         cwd?: string;
         name: string;
@@ -29,3 +38,4 @@ export interface ProfileService {
 }
 export declare function createProfileService(): ProfileService;
 export declare function parseProfile(source: string, name: string): ProfileConfig;
+export declare function normalizeProfileConfig(value: unknown, name: string): ProfileConfig;

package/dist/services/profile-service.js

@@ -1,4 +1,4 @@
-import { readdir, readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { readdir, readFile, writeFile, mkdir, stat, unlink } from 'node:fs/promises';
 import path from 'node:path';
 import YAML from 'yaml';
 import { ProfileError, ProfileNotFoundError } from '../errors.js';
@@ -64,6 +64,34 @@ export function createProfileService() {
             await writeFile(profilePath, YAML.stringify(scaffold), 'utf8');
             return { profilePath };
         },
+        async update(options) {
+            const cwd = options.cwd ?? process.cwd();
+            const profilePath = path.join(cwd, PROFILES_DIR, `${options.name}.yaml`);
+            if (!(await pathExists(profilePath))) {
+                throw new ProfileNotFoundError(`Profile "${options.name}" not found.`);
+            }
+            const normalized = normalizeProfileConfig(options.config, options.name);
+            const data = {
+                name: normalized.name,
+                ...(normalized.description ? { description: normalized.description } : {}),
+                skills: normalized.skills,
+                mcps: normalized.mcps,
+                memory: normalized.memory,
+            };
+            await writeFile(profilePath, YAML.stringify(data), 'utf8');
+        },
+        async delete(options) {
+            const cwd = options.cwd ?? process.cwd();
+            const profilePath = path.join(cwd, PROFILES_DIR, `${options.name}.yaml`);
+            if (!(await pathExists(profilePath))) {
+                throw new ProfileNotFoundError(`Profile "${options.name}" not found.`);
+            }
+            const meta = await loadMetaConfig(cwd);
+            if (meta.active_profile === options.name) {
+                throw new ProfileError('Cannot delete the active profile.');
+            }
+            await unlink(profilePath);
+        },
         async use(options) {
             const cwd = options.cwd ?? process.cwd();
             // Validate profile exists
@@ -110,7 +138,13 @@ export function parseProfile(source, name) {
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new ProfileError(`Profile "${name}" has invalid structure.`);
     }
-    const data = parsed;
+    return normalizeProfileConfig(parsed, name);
+}
+export function normalizeProfileConfig(value, name) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ProfileError(`Profile "${name}" has invalid structure.`);
+    }
+    const data = value;
     const skills = {};
     if (data.skills && typeof data.skills === 'object' && !Array.isArray(data.skills)) {
         for (const [key, value] of Object.entries(data.skills)) {
@@ -125,31 +159,7 @@ export function parseProfile(source, name) {
             }
         }
     }
-    const mcps = {};
-    if (data.mcps && typeof data.mcps === 'object' && !Array.isArray(data.mcps)) {
-        for (const [key, value] of Object.entries(data.mcps)) {
-            if (value && typeof value === 'object' && !Array.isArray(value)) {
-                const m = value;
-                if (m.type === 'npm' && typeof m.package === 'string') {
-                    mcps[key] = {
-                        type: 'npm',
-                        package: m.package,
-                        env: parseEnv(m.env),
-                    };
-                }
-                else if (m.type === 'bundled' && typeof m.command === 'string') {
-                    mcps[key] = {
-                        type: 'bundled',
-                        path: typeof m.path === 'string' ? m.path : '.',
-                        install: typeof m.install === 'string' ? m.install : undefined,
-                        command: m.command,
-                        args: Array.isArray(m.args) ? m.args.map(String) : undefined,
-                        env: parseEnv(m.env),
-                    };
-                }
-            }
-        }
-    }
+    const mcps = normalizeMcps(data.mcps, name);
     const memoryPaths = [];
     if (data.memory && typeof data.memory === 'object' && !Array.isArray(data.memory)) {
         const mem = data.memory;
@@ -169,7 +179,102 @@ export function parseProfile(source, name) {
         memory: { paths: memoryPaths },
     };
 }
-function parseEnv(value) {
+function normalizeMcps(value, profileName) {
+    if (value === undefined || value === null) {
+        return {};
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new ProfileError(`Profile "${profileName}" has an invalid "mcps" section.`);
+    }
+    const mcps = {};
+    for (const [key, rawValue] of Object.entries(value)) {
+        if (!rawValue || typeof rawValue !== 'object' || Array.isArray(rawValue)) {
+            throw new ProfileError(`MCP "${key}" must be an object.`);
+        }
+        const mcp = rawValue;
+        // Local profile files may still use the older type-based shape.
+        if (mcp.type === 'npm') {
+            if (typeof mcp.package !== 'string' || mcp.package.trim().length === 0) {
+                throw new ProfileError(`Local MCP "${key}" must include a non-empty package.`);
+            }
+            mcps[key] = {
+                kind: 'local',
+                source: 'npm',
+                package: mcp.package,
+                env: parseStringMap(mcp.env),
+            };
+            continue;
+        }
+        if (mcp.type === 'bundled') {
+            if (typeof mcp.path !== 'string' ||
+                mcp.path.trim().length === 0 ||
+                typeof mcp.command !== 'string' ||
+                mcp.command.trim().length === 0) {
+                throw new ProfileError(`Bundled local MCP "${key}" must include non-empty path and command fields.`);
+            }
+            mcps[key] = {
+                kind: 'local',
+                source: 'bundled',
+                path: mcp.path,
+                install: typeof mcp.install === 'string' ? mcp.install : undefined,
+                command: mcp.command,
+                args: parseStringArray(mcp.args),
+                env: parseStringMap(mcp.env),
+            };
+            continue;
+        }
+        if (mcp.kind !== 'local' && mcp.kind !== 'remote') {
+            throw new ProfileError(`MCP "${key}" must declare kind "local" or "remote".`);
+        }
+        if (mcp.kind === 'remote') {
+            if ((mcp.transport !== 'http' && mcp.transport !== 'sse') ||
+                typeof mcp.url !== 'string' ||
+                mcp.url.trim().length === 0) {
+                throw new ProfileError(`Remote MCP "${key}" must include transport ("http" or "sse") and a url.`);
+            }
+            mcps[key] = {
+                kind: 'remote',
+                transport: mcp.transport,
+                url: mcp.url,
+                headers: parseStringMap(mcp.headers),
+                env: parseStringMap(mcp.env),
+            };
+            continue;
+        }
+        if (mcp.source !== 'npm' && mcp.source !== 'bundled') {
+            throw new ProfileError(`Local MCP "${key}" must declare source "npm" or "bundled".`);
+        }
+        if (mcp.source === 'npm') {
+            if (typeof mcp.package !== 'string' || mcp.package.trim().length === 0) {
+                throw new ProfileError(`Local MCP "${key}" must include a non-empty package.`);
+            }
+            mcps[key] = {
+                kind: 'local',
+                source: 'npm',
+                package: mcp.package,
+                env: parseStringMap(mcp.env),
+            };
+            continue;
+        }
+        if (typeof mcp.path !== 'string' ||
+            mcp.path.trim().length === 0 ||
+            typeof mcp.command !== 'string' ||
+            mcp.command.trim().length === 0) {
+            throw new ProfileError(`Bundled local MCP "${key}" must include non-empty path and command fields.`);
+        }
+        mcps[key] = {
+            kind: 'local',
+            source: 'bundled',
+            path: mcp.path,
+            install: typeof mcp.install === 'string' ? mcp.install : undefined,
+            command: mcp.command,
+            args: parseStringArray(mcp.args),
+            env: parseStringMap(mcp.env),
+        };
+    }
+    return mcps;
+}
+function parseStringMap(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         return undefined;
     }
@@ -179,6 +284,13 @@ function parseEnv(value) {
     }
     return Object.keys(result).length > 0 ? result : undefined;
 }
+function parseStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const items = value.map(String);
+    return items.length > 0 ? items : undefined;
+}
 async function pathExists(targetPath) {
     try {
         await stat(targetPath);

package/dist/services/skill-paths.d.ts

@@ -0,0 +1,2 @@
+import type { AgentName } from '../types.js';
+export declare function getSkillDir(agent: AgentName, skillName: string): string;

package/dist/services/skill-paths.js

@@ -0,0 +1,12 @@
+import { homedir } from 'node:os';
+import path from 'node:path';
+export function getSkillDir(agent, skillName) {
+    const safeName = path.basename(skillName);
+    if (agent === 'claude')
+        return path.join(homedir(), '.claude', 'skills', safeName);
+    if (agent === 'codex')
+        return path.join(homedir(), '.codex', 'skills', safeName);
+    if (agent === 'gemini')
+        return path.join(homedir(), '.gemini', 'skills', safeName);
+    throw new Error(`Skill management is not supported for ${agent}`);
+}

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

@@ -0,0 +1,23 @@
+import type { AgentName } from '../types.js';
+export interface SkillPreflightCheck {
+    label: string;
+    status: 'ok' | 'warn' | 'error';
+    message: string;
+}
+export interface SkillPreflightResult {
+    ok: boolean;
+    checks: SkillPreflightCheck[];
+}
+export interface SkillPreflightService {
+    execute(options: {
+        sourceAgent: AgentName;
+        targetAgent: AgentName;
+        skillName: string;
+        source?: string;
+    }): Promise<SkillPreflightResult>;
+}
+interface SkillPreflightDependencies {
+    pathExists?: (targetPath: string) => Promise<boolean>;
+}
+export declare function createSkillPreflightService(dependencies?: SkillPreflightDependencies): SkillPreflightService;
+export {};

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

@@ -0,0 +1,40 @@
+import { stat } from 'node:fs/promises';
+import { getSkillDir } from './skill-paths.js';
+export function createSkillPreflightService(dependencies = {}) {
+    const pathExists = dependencies.pathExists ?? defaultPathExists;
+    return {
+        async execute(options) {
+            const checks = [];
+            if (options.source && options.source !== 'local' && options.source !== 'linked') {
+                checks.push({
+                    label: 'Source',
+                    status: 'error',
+                    message: `Only local skill folders can be copied today. "${options.skillName}" is a plugin/managed entry from ${options.source}.`,
+                });
+                return { ok: false, checks };
+            }
+            const sourceDir = getSkillDir(options.sourceAgent, options.skillName);
+            const exists = await pathExists(sourceDir);
+            checks.push({
+                label: 'Source',
+                status: exists ? 'ok' : 'error',
+                message: exists
+                    ? `Skill folder was found: ${sourceDir}`
+                    : `Skill folder was not found: ${sourceDir}`,
+            });
+            return {
+                ok: exists,
+                checks,
+            };
+        },
+    };
+}
+async function defaultPathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,30 @@
+import type { AgentName } from '../../types.js';
+export interface AgentMcpEntry {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export interface AgentSkillEntry {
+    name: string;
+    source?: string;
+    kind?: 'skill' | 'plugin';
+    pluginSkills?: string[];
+    pluginMcps?: string[];
+    installPath?: string;
+    managed?: boolean;
+}
+export interface AgentLiveConfig {
+    agent: AgentName;
+    configPath: string;
+    exists: boolean;
+    mcpServers: Record<string, AgentMcpEntry>;
+    skills: AgentSkillEntry[];
+}
+export interface AgentConfigReader {
+    read(options: {
+        cwd: string;
+    }): Promise<AgentLiveConfig>;
+}
+export declare function createClaudeReader(): AgentConfigReader;
+export declare function createCodexReader(): AgentConfigReader;
+export declare function createGeminiReader(): AgentConfigReader;