brainctl 0.1.7 → 0.1.9

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

@@ -1,12 +1,16 @@
 import { execSync } from 'node:child_process';
-import { cp, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { copyFile, cp, mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
 import YAML from 'yaml';
 import { ProfileError } from '../errors.js';
+import { formatTimestamp } from './sync/agent-writer.js';
+import { resolvePortableMcpCredentials } from './credential-resolution-service.js';
+import { createMcpPreflightService } from './mcp-preflight-service.js';
 import { parseProfile } from './profile-service.js';
 const PROFILES_DIR = '.brainctl/profiles';
-export function createProfileImportService() {
+export function createProfileImportService(deps = {}) {
+    const mcpPreflightService = deps.mcpPreflightService ?? createMcpPreflightService();
     return {
         async execute(options) {
             const cwd = options.cwd ?? process.cwd();
@@ -22,9 +26,13 @@ export function createProfileImportService() {
                 execSync(`tar -xzf "${archivePath}" -C "${extractDir}"`, {
                     stdio: 'pipe',
                 });
+                const manifest = await readPortableManifest(extractDir);
                 const profileSource = await readFile(path.join(extractDir, 'profile.yaml'), 'utf8');
                 const profile = parseProfile(profileSource, 'imported');
                 const profileName = profile.name;
+                if (manifest.profileName !== profileName) {
+                    throw new ProfileError(`Portable profile manifest name "${manifest.profileName}" does not match profile name "${profileName}".`);
+                }
                 const profilePath = path.join(cwd, PROFILES_DIR, `${profileName}.yaml`);
                 if (!options.force) {
                     try {
@@ -36,12 +44,27 @@ export function createProfileImportService() {
                             throw err;
                     }
                 }
+                const missingCredentials = new Map();
+                for (const [name, mcp] of Object.entries(profile.mcps)) {
+                    const resolution = resolvePortableMcpCredentials(mcp, {
+                        credentials: options.credentials,
+                        credentialSpecs: manifest.credentials,
+                        environment: process.env,
+                    });
+                    profile.mcps[name] = resolution.resolved;
+                    for (const credential of resolution.missing) {
+                        missingCredentials.set(credential.key, credential.description ?? credential.key);
+                    }
+                }
+                if (missingCredentials.size > 0) {
+                    throw new ProfileError(`Missing required credentials: ${Array.from(missingCredentials.keys()).join(', ')}.`);
+                }
                 const installedMcps = [];
                 const mcpsBaseDir = path.join(cwd, PROFILES_DIR, profileName, 'mcps');
                 for (const [name, mcp] of Object.entries(profile.mcps)) {
                     if (!(mcp.kind === 'local' && mcp.source === 'bundled'))
                         continue;
-                    const extractedMcpPath = path.join(extractDir, 'mcps', name);
+                    const extractedMcpPath = resolveBundledArchivePath(extractDir, mcp.path);
                     const destMcpPath = path.join(mcpsBaseDir, name);
                     try {
                         await stat(extractedMcpPath);
@@ -49,19 +72,44 @@ export function createProfileImportService() {
                     catch {
                         throw new ProfileError(`Bundled MCP "${name}" source not found in archive.`);
                     }
+                    await rm(destMcpPath, { recursive: true, force: true });
                     await mkdir(destMcpPath, { recursive: true });
                     await cp(extractedMcpPath, destMcpPath, { recursive: true });
-                    const installCmd = mcp.install ?? 'npm install';
-                    execSync(installCmd, {
-                        cwd: destMcpPath,
-                        stdio: 'pipe',
-                    });
+                    const installCmd = mcp.install;
+                    if (!installCmd) {
+                        profile.mcps[name] = {
+                            ...mcp,
+                            path: destMcpPath,
+                        };
+                        installedMcps.push(name);
+                        continue;
+                    }
+                    try {
+                        execSync(installCmd, {
+                            cwd: destMcpPath,
+                            stdio: 'pipe',
+                        });
+                    }
+                    catch (error) {
+                        throw new ProfileError(`Bundled MCP "${name}" install failed: ${formatExecError(error)}`);
+                    }
                     profile.mcps[name] = {
                         ...mcp,
                         path: destMcpPath,
                     };
                     installedMcps.push(name);
                 }
+                await validateImportedMcps(profile, cwd, mcpPreflightService);
+                const installedPlugins = [];
+                for (const plugin of manifest.plugins ?? []) {
+                    await restorePlugin(extractDir, plugin);
+                    installedPlugins.push(`${plugin.agent}:${plugin.name}`);
+                }
+                const installedUserSkills = [];
+                for (const skill of manifest.userSkills ?? []) {
+                    await restoreUserSkill(extractDir, skill);
+                    installedUserSkills.push(`${skill.agent}:${skill.name}`);
+                }
                 const outputYaml = {
                     name: profile.name,
                     ...(profile.description ? { description: profile.description } : {}),
@@ -71,7 +119,7 @@ export function createProfileImportService() {
                 };
                 await mkdir(path.dirname(profilePath), { recursive: true });
                 await writeFile(profilePath, YAML.stringify(outputYaml), 'utf8');
-                return { profileName, installedMcps };
+                return { profileName, installedMcps, installedPlugins, installedUserSkills };
             }
             finally {
                 await rm(extractDir, { recursive: true, force: true });
@@ -79,3 +127,210 @@ export function createProfileImportService() {
         },
     };
 }
+async function validateImportedMcps(profile, cwd, mcpPreflightService) {
+    for (const [name, mcp] of Object.entries(profile.mcps)) {
+        if (mcp.kind === 'remote') {
+            validateRemoteMcp(name, mcp);
+            continue;
+        }
+        const validation = await mcpPreflightService.execute({
+            cwd: mcp.source === 'bundled' ? mcp.path : cwd,
+            agent: 'claude',
+            key: name,
+            entry: toAgentMcpEntry(mcp),
+        });
+        const firstError = validation.checks.find((check) => check.status === 'error');
+        if (firstError) {
+            throw new ProfileError(`Imported MCP "${name}" failed validation: ${firstError.message}`);
+        }
+    }
+}
+function toAgentMcpEntry(mcp) {
+    if (mcp.source === 'npm') {
+        return {
+            command: 'npx',
+            args: ['-y', mcp.package],
+            ...(mcp.env ? { env: mcp.env } : {}),
+        };
+    }
+    return {
+        command: mcp.command,
+        ...(mcp.args ? { args: mcp.args } : {}),
+        ...(mcp.env ? { env: mcp.env } : {}),
+    };
+}
+function validateRemoteMcp(name, mcp) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(mcp.url);
+    }
+    catch {
+        throw new ProfileError(`Remote MCP "${name}" must include an absolute http(s) url.`);
+    }
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        throw new ProfileError(`Remote MCP "${name}" must include an absolute http(s) url.`);
+    }
+}
+function formatExecError(error) {
+    if (error && typeof error === 'object') {
+        const stderr = 'stderr' in error && typeof error.stderr === 'string'
+            ? error.stderr.trim()
+            : 'stderr' in error && Buffer.isBuffer(error.stderr)
+                ? error.stderr.toString('utf8').trim()
+                : '';
+        if (stderr.length > 0) {
+            return stderr;
+        }
+        if ('message' in error && typeof error.message === 'string') {
+            return error.message;
+        }
+    }
+    return 'Unknown install error.';
+}
+async function readPortableManifest(extractDir) {
+    let source;
+    try {
+        source = await readFile(path.join(extractDir, 'manifest.yaml'), 'utf8');
+    }
+    catch {
+        throw new ProfileError('Portable profile archive is missing manifest.yaml.');
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(source) ?? {};
+    }
+    catch {
+        throw new ProfileError('Portable profile manifest has invalid YAML.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ProfileError('Portable profile manifest has invalid structure.');
+    }
+    const manifest = parsed;
+    if (manifest.schemaVersion !== 1 && manifest.schemaVersion !== 2) {
+        throw new ProfileError(`Unsupported portable profile schema version: ${String(manifest.schemaVersion)}.`);
+    }
+    if (typeof manifest.profileName !== 'string' || manifest.profileName.trim().length === 0) {
+        throw new ProfileError('Portable profile manifest must include profileName.');
+    }
+    return manifest;
+}
+function resolveBundledArchivePath(extractDir, bundlePath) {
+    if (!bundlePath || path.isAbsolute(bundlePath)) {
+        throw new ProfileError('Bundled MCP path must be a relative archive path.');
+    }
+    const resolved = path.resolve(extractDir, bundlePath);
+    const relative = path.relative(extractDir, resolved);
+    if (relative.startsWith(`..${path.sep}`) ||
+        relative === '..' ||
+        path.isAbsolute(relative)) {
+        throw new ProfileError(`Bundled MCP path "${bundlePath}" escapes the archive root.`);
+    }
+    return resolved;
+}
+async function restorePlugin(extractDir, plugin) {
+    const sourceDir = resolveBundledArchivePath(extractDir, plugin.archivePath);
+    try {
+        await stat(sourceDir);
+    }
+    catch {
+        throw new ProfileError(`Bundled plugin "${plugin.name}" source missing in archive at ${plugin.archivePath}.`);
+    }
+    if (plugin.agent === 'gemini') {
+        // Gemini has no plugin cache concept. Treat as user-skill-equivalent no-op.
+        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}`,
+        });
+    }
+}
+async function restoreUserSkill(extractDir, skill) {
+    const sourceDir = resolveBundledArchivePath(extractDir, skill.archivePath);
+    try {
+        await stat(sourceDir);
+    }
+    catch {
+        throw new ProfileError(`Bundled user skill "${skill.name}" source missing in archive at ${skill.archivePath}.`);
+    }
+    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/profile-service.js

@@ -2,6 +2,7 @@ import { readdir, readFile, writeFile, mkdir, stat, unlink } from 'node:fs/promi
 import path from 'node:path';
 import YAML from 'yaml';
 import { ProfileError, ProfileNotFoundError } from '../errors.js';
+const VALID_RUNTIMES = new Set(['node', 'python', 'java', 'go', 'rust', 'binary']);
 const BRAINCTL_DIR = '.brainctl';
 const PROFILES_DIR = '.brainctl/profiles';
 const META_CONFIG = '.brainctl/config.yaml';
@@ -215,10 +216,12 @@ function normalizeMcps(value, profileName) {
             mcps[key] = {
                 kind: 'local',
                 source: 'bundled',
+                runtime: parseMcpRuntime(mcp.runtime),
                 path: mcp.path,
                 install: typeof mcp.install === 'string' ? mcp.install : undefined,
                 command: mcp.command,
                 args: parseStringArray(mcp.args),
+                ...(Array.isArray(mcp.exclude) ? { exclude: mcp.exclude.filter((v) => typeof v === 'string') } : {}),
                 env: parseStringMap(mcp.env),
             };
             continue;
@@ -265,10 +268,12 @@ function normalizeMcps(value, profileName) {
         mcps[key] = {
             kind: 'local',
             source: 'bundled',
+            runtime: parseMcpRuntime(mcp.runtime),
             path: mcp.path,
             install: typeof mcp.install === 'string' ? mcp.install : undefined,
             command: mcp.command,
             args: parseStringArray(mcp.args),
+            ...(Array.isArray(mcp.exclude) ? { exclude: mcp.exclude.filter((v) => typeof v === 'string') } : {}),
             env: parseStringMap(mcp.env),
         };
     }
@@ -284,6 +289,12 @@ function parseStringMap(value) {
     }
     return Object.keys(result).length > 0 ? result : undefined;
 }
+function parseMcpRuntime(value) {
+    if (typeof value === 'string' && VALID_RUNTIMES.has(value)) {
+        return value;
+    }
+    return 'node';
+}
 function parseStringArray(value) {
     if (!Array.isArray(value)) {
         return undefined;

package/dist/services/runtime-detector.d.ts

@@ -0,0 +1,9 @@
+import type { McpRuntime } from '../types.js';
+export declare function detectMcpRuntime(command: string): McpRuntime | null;
+export declare function extractEntrypoint(command: string, args: string[]): string | null;
+export declare function findProjectRoot(entrypointPath: string, runtime: McpRuntime): {
+    root: string;
+    marker: string | null;
+};
+export declare function getDefaultInstall(runtime: McpRuntime, marker: string | null, projectRoot: string, entrypoint?: string): string | undefined;
+export declare function getDefaultExclude(runtime: McpRuntime, marker?: string | null): string[] | undefined;

package/dist/services/runtime-detector.js

@@ -0,0 +1,130 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+const COMMAND_RUNTIME_MAP = {
+    node: 'node',
+    nodejs: 'node',
+    python: 'python',
+    python3: 'python',
+    java: 'java',
+    go: 'go',
+    cargo: 'rust',
+};
+const RUNTIME_MARKERS = {
+    node: ['package.json'],
+    python: ['pyproject.toml', 'requirements.txt', 'setup.py'],
+    java: ['pom.xml', 'build.gradle'],
+    go: ['go.mod'],
+    rust: ['Cargo.toml'],
+    binary: [],
+};
+const MAX_WALK_DEPTH = 5;
+export function detectMcpRuntime(command) {
+    const basename = path.basename(command);
+    const mapped = COMMAND_RUNTIME_MAP[basename];
+    if (mapped) {
+        return mapped;
+    }
+    if (command.startsWith('./') || command.startsWith('/') || command.startsWith('.\\')) {
+        return 'binary';
+    }
+    return null;
+}
+export function extractEntrypoint(command, args) {
+    const runtime = detectMcpRuntime(command);
+    if (runtime === 'binary') {
+        return command;
+    }
+    if (runtime === 'java') {
+        const jarIndex = args.indexOf('-jar');
+        if (jarIndex !== -1 && jarIndex + 1 < args.length) {
+            return args[jarIndex + 1];
+        }
+        return null;
+    }
+    if (runtime === 'go') {
+        const runIndex = args.indexOf('run');
+        if (runIndex !== -1 && runIndex + 1 < args.length) {
+            return args[runIndex + 1];
+        }
+        return null;
+    }
+    if (runtime === 'rust') {
+        return null;
+    }
+    // node, python: first non-flag arg
+    for (const arg of args) {
+        if (!arg.startsWith('-')) {
+            return arg;
+        }
+    }
+    return null;
+}
+export function findProjectRoot(entrypointPath, runtime) {
+    const markers = RUNTIME_MARKERS[runtime];
+    if (markers.length === 0) {
+        return { root: path.dirname(entrypointPath), marker: null };
+    }
+    let current = path.dirname(entrypointPath);
+    for (let depth = 0; depth <= MAX_WALK_DEPTH; depth++) {
+        for (const marker of markers) {
+            if (existsSync(path.join(current, marker))) {
+                return { root: current, marker };
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return { root: path.dirname(entrypointPath), marker: null };
+}
+export function getDefaultInstall(runtime, marker, projectRoot, entrypoint) {
+    switch (runtime) {
+        case 'node':
+            return 'npm install';
+        case 'python':
+            if (marker === 'requirements.txt') {
+                return 'pip install -r requirements.txt';
+            }
+            if (marker === 'pyproject.toml') {
+                return existsSync(path.join(projectRoot, 'uv.lock')) ? 'uv sync' : 'pip install -e .';
+            }
+            return undefined;
+        case 'java':
+            if (entrypoint && entrypoint.endsWith('.jar')) {
+                return undefined;
+            }
+            if (marker === 'pom.xml')
+                return 'mvn package -q';
+            if (marker === 'build.gradle')
+                return 'gradle build';
+            return undefined;
+        case 'go':
+            return 'go build ./...';
+        case 'rust':
+            return 'cargo build --release';
+        case 'binary':
+            return undefined;
+    }
+}
+export function getDefaultExclude(runtime, marker) {
+    switch (runtime) {
+        case 'node':
+            return ['node_modules'];
+        case 'python':
+            return ['.venv', '__pycache__', '*.pyc'];
+        case 'rust':
+            return ['target'];
+        case 'java':
+            if (marker === 'build.gradle')
+                return ['build'];
+            if (marker === 'pom.xml')
+                return ['target'];
+            return undefined;
+        case 'go':
+            return undefined;
+        case 'binary':
+            return undefined;
+    }
+}

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

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

package/dist/services/skill-paths.js

@@ -10,3 +10,17 @@ export function getSkillDir(agent, skillName) {
         return path.join(homedir(), '.gemini', 'skills', safeName);
     throw new Error(`Skill management is not supported for ${agent}`);
 }
+export function getAgentFilePath(agent, agentName) {
+    const safeName = path.basename(agentName);
+    if (agent === 'claude')
+        return path.join(homedir(), '.claude', 'agents', `${safeName}.md`);
+    if (agent === 'codex')
+        return path.join(homedir(), '.codex', 'agents', `${safeName}.toml`);
+    throw new Error(`Subagent management is not supported for ${agent}`);
+}
+export function getCommandFilePath(agent, commandName) {
+    const safeName = path.basename(commandName);
+    if (agent === 'claude')
+        return path.join(homedir(), '.claude', 'commands', `${safeName}.md`);
+    throw new Error(`Slash-command management is not supported for ${agent}`);
+}

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

@@ -4,12 +4,20 @@ export interface AgentMcpEntry {
     args?: string[];
     env?: Record<string, string>;
 }
+export interface PortableRemoteMcpMetadata {
+    transport: 'http' | 'sse';
+    url: string;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+}
 export interface AgentSkillEntry {
     name: string;
     source?: string;
     kind?: 'skill' | 'plugin';
     pluginSkills?: string[];
     pluginMcps?: string[];
+    pluginAgents?: string[];
+    pluginCommands?: string[];
     installPath?: string;
     managed?: boolean;
 }
@@ -18,6 +26,7 @@ export interface AgentLiveConfig {
     configPath: string;
     exists: boolean;
     mcpServers: Record<string, AgentMcpEntry>;
+    remoteMcpServers: Record<string, PortableRemoteMcpMetadata>;
     skills: AgentSkillEntry[];
 }
 export interface AgentConfigReader {