brainctl 0.1.6 → 0.1.9

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

@@ -0,0 +1,89 @@
+export function redactPortableMcpCredentials(config) {
+    const credentialsByKey = new Map();
+    const redactedEnv = redactStringMap(config.env, 'env', credentialsByKey);
+    if (config.kind === 'remote') {
+        const redactedHeaders = redactStringMap(config.headers, 'header', credentialsByKey);
+        return {
+            redacted: {
+                ...config,
+                ...(redactedEnv ? { env: redactedEnv } : {}),
+                ...(redactedHeaders ? { headers: redactedHeaders } : {}),
+            },
+            credentials: finalizePortableCredentialSpecs(credentialsByKey),
+        };
+    }
+    return {
+        redacted: {
+            ...config,
+            ...(redactedEnv ? { env: redactedEnv } : {}),
+        },
+        credentials: finalizePortableCredentialSpecs(credentialsByKey),
+    };
+}
+function redactStringMap(values, source, credentialsByKey) {
+    if (!values) {
+        return undefined;
+    }
+    const redacted = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (!shouldRedact(key)) {
+            redacted[key] = value;
+            continue;
+        }
+        const credentialKey = normalizeCredentialKey(key);
+        addCredentialSpec(credentialsByKey, credentialKey, source, key);
+        redacted[key] = isCredentialPlaceholder(value)
+            ? value
+            : `\${credentials.${credentialKey}}`;
+    }
+    return redacted;
+}
+function shouldRedact(key) {
+    const tokens = tokenizeCredentialKey(key);
+    if (tokens.length === 0) {
+        return false;
+    }
+    return (tokens[tokens.length - 1] === 'authorization' ||
+        tokens[tokens.length - 1] === 'password' ||
+        tokens[tokens.length - 1] === 'secret' ||
+        tokens[tokens.length - 1] === 'token' ||
+        (tokens[tokens.length - 1] === 'key' &&
+            (tokens.includes('api') || (tokens.includes('auth') && tokens.includes('key')))));
+}
+function normalizeCredentialKey(key) {
+    return tokenizeCredentialKey(key).join('_');
+}
+function tokenizeCredentialKey(key) {
+    return key
+        .trim()
+        .replace(/([A-Z]+)([A-Z][a-z0-9])/g, '$1 $2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/g)
+        .filter(Boolean);
+}
+function isCredentialPlaceholder(value) {
+    return /^\$\{credentials\.[^}]+\}$/.test(value) || /^(Bearer|Token)\s+\$\{credentials\.[^}]+\}$/i.test(value);
+}
+function addCredentialSpec(credentialsByKey, credentialKey, source, originalKey) {
+    const description = source === 'env' ? `Environment variable ${originalKey}` : `Header ${originalKey}`;
+    const existing = credentialsByKey.get(credentialKey);
+    if (existing) {
+        existing.descriptions.add(description);
+        return;
+    }
+    credentialsByKey.set(credentialKey, {
+        key: credentialKey,
+        required: true,
+        descriptions: new Set([description]),
+    });
+}
+export function finalizePortableCredentialSpecs(credentialsByKey) {
+    return Array.from(credentialsByKey.values())
+        .sort((left, right) => left.key.localeCompare(right.key))
+        .map((entry) => ({
+        key: entry.key,
+        required: entry.required,
+        description: `${Array.from(entry.descriptions).sort().join('; ')} required for MCP access`,
+    }));
+}

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

@@ -0,0 +1,11 @@
+import type { McpServerConfig, PortableCredentialPlaceholder, PortableCredentialSpec } from '../types.js';
+export interface CredentialResolutionResult<T extends McpServerConfig> {
+    resolved: T;
+    missing: PortableCredentialSpec[];
+}
+export declare function resolvePortableMcpCredentials<T extends McpServerConfig>(config: T, options?: {
+    credentials?: Record<string, string>;
+    credentialSpecs?: PortableCredentialSpec[];
+    environment?: Record<string, string | undefined>;
+}): CredentialResolutionResult<T>;
+export declare function toPortableCredentialPlaceholder(key: string): PortableCredentialPlaceholder;

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

@@ -0,0 +1,69 @@
+export function resolvePortableMcpCredentials(config, options = {}) {
+    const specs = new Map((options.credentialSpecs ?? []).map((spec) => [spec.key, spec]));
+    const missing = new Map();
+    const env = resolveStringMap(config.env, specs, missing, options.credentials, options.environment);
+    if (config.kind === 'remote') {
+        const headers = resolveStringMap(config.headers, specs, missing, options.credentials, options.environment);
+        return {
+            resolved: {
+                ...config,
+                ...(env ? { env } : {}),
+                ...(headers ? { headers } : {}),
+            },
+            missing: Array.from(missing.values()),
+        };
+    }
+    return {
+        resolved: {
+            ...config,
+            ...(env ? { env } : {}),
+        },
+        missing: Array.from(missing.values()),
+    };
+}
+function resolveStringMap(values, specs, missing, credentials, environment) {
+    if (!values) {
+        return undefined;
+    }
+    const resolved = {};
+    for (const [key, value] of Object.entries(values)) {
+        const placeholder = parseCredentialPlaceholder(value);
+        if (!placeholder) {
+            resolved[key] = value;
+            continue;
+        }
+        const resolvedValue = credentials?.[placeholder.key] ?? environment?.[placeholder.key];
+        if (typeof resolvedValue === 'string' && resolvedValue.length > 0) {
+            resolved[key] = placeholder.prefix ? `${placeholder.prefix} ${resolvedValue}` : resolvedValue;
+            continue;
+        }
+        const spec = specs.get(placeholder.key) ?? {
+            key: placeholder.key,
+            required: true,
+            description: `Credential ${placeholder.key} is required`,
+        };
+        if (spec.required) {
+            missing.set(spec.key, spec);
+        }
+        resolved[key] = value;
+    }
+    return resolved;
+}
+function parseCredentialPlaceholder(value) {
+    const bareMatch = value.match(/^\$\{credentials\.([^}]+)\}$/);
+    if (bareMatch) {
+        return { key: bareMatch[1] };
+    }
+    const prefixedMatch = value.match(/^(Bearer|Token)\s+\$\{credentials\.([^}]+)\}$/i);
+    if (prefixedMatch) {
+        const prefix = prefixedMatch[1].toLowerCase() === 'bearer' ? 'Bearer' : 'Token';
+        return {
+            key: prefixedMatch[2],
+            prefix,
+        };
+    }
+    return null;
+}
+export function toPortableCredentialPlaceholder(key) {
+    return `\${credentials.${key}}`;
+}

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

@@ -0,0 +1,26 @@
+import type { AgentName } from '../types.js';
+import type { AgentMcpEntry, PortableRemoteMcpMetadata } 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;
+        remoteEntry?: PortableRemoteMcpMetadata;
+    }): 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,238 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { findExecutable } from '../system/executables.js';
+const ENTRYPOINT_RUNNERS = new Set(['node', 'nodejs', 'python', 'python3', 'bash', 'sh', 'zsh', 'deno', 'bun']);
+const SUPPORTED_LOCAL_LAUNCHERS = ['npx', 'uvx', 'node', 'python', 'python3', 'java -jar', 'go run', 'cargo run', 'and local binaries/scripts'];
+export function createMcpPreflightService(dependencies = {}) {
+    const resolveExecutable = dependencies.resolveExecutable ?? findExecutable;
+    const pathExists = dependencies.pathExists ?? defaultPathExists;
+    return {
+        async execute(options) {
+            if (options.remoteEntry) {
+                return validateRemoteMcp(options.agent, options.remoteEntry);
+            }
+            const checks = [];
+            if (!options.entry) {
+                checks.push({
+                    label: 'Launcher',
+                    status: 'error',
+                    message: 'Missing local MCP command metadata.',
+                });
+                return { ok: false, checks };
+            }
+            const launcherCheck = validateLocalLauncher(options.entry);
+            checks.push(launcherCheck);
+            if (launcherCheck.status === 'error') {
+                return { ok: false, checks };
+            }
+            if (isLocalBinaryPath(options.entry.command)) {
+                const commandPath = path.isAbsolute(options.entry.command)
+                    ? options.entry.command
+                    : path.resolve(options.cwd, options.entry.command);
+                const exists = await pathExists(commandPath);
+                checks.push({
+                    label: 'Command',
+                    status: exists ? 'ok' : 'error',
+                    message: exists
+                        ? `Local MCP command was found: ${commandPath}`
+                        : `Local MCP command was not found: ${commandPath}`,
+                });
+                return {
+                    ok: checks.every((check) => check.status !== 'error'),
+                    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' || options.entry.command === 'uvx') {
+                const nonFlagArg = options.entry.args?.find((arg) => !arg.startsWith('-'));
+                if (!nonFlagArg) {
+                    checks.push({
+                        label: 'Package',
+                        status: 'error',
+                        message: `${options.entry.command}-based MCP entries must include a package or executable argument.`,
+                    });
+                }
+                else {
+                    checks.push({
+                        label: 'Package',
+                        status: 'ok',
+                        message: `${options.entry.command} 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 (entry.command === 'java') {
+        const jarIndex = entry.args?.indexOf('-jar') ?? -1;
+        const jarPath = jarIndex >= 0 ? entry.args?.[jarIndex + 1] : undefined;
+        if (!jarPath || !looksLikeLocalPath(jarPath))
+            return null;
+        return path.isAbsolute(jarPath) ? jarPath : path.resolve(cwd, jarPath);
+    }
+    if (entry.command === 'go') {
+        const runIndex = entry.args?.indexOf('run') ?? -1;
+        const runPath = runIndex >= 0 ? entry.args?.[runIndex + 1] : undefined;
+        if (!runPath || !looksLikeLocalPath(runPath))
+            return null;
+        return path.isAbsolute(runPath) ? runPath : path.resolve(cwd, runPath);
+    }
+    if (!ENTRYPOINT_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));
+}
+function validateLocalLauncher(entry) {
+    if (isLocalBinaryPath(entry.command)) {
+        return {
+            label: 'Launcher',
+            status: 'ok',
+            message: `Launcher "${entry.command}" is supported for exact MCP copy.`,
+        };
+    }
+    if (entry.command === 'npx' || entry.command === 'uvx' || entry.command === 'node' || entry.command === 'nodejs' || entry.command === 'python' || entry.command === 'python3') {
+        return {
+            label: 'Launcher',
+            status: 'ok',
+            message: `Launcher "${entry.command}" is supported for exact MCP copy.`,
+        };
+    }
+    if (entry.command === 'java') {
+        const jarIndex = entry.args?.indexOf('-jar') ?? -1;
+        const jarPath = jarIndex >= 0 ? entry.args?.[jarIndex + 1] : undefined;
+        return jarPath
+            ? {
+                label: 'Launcher',
+                status: 'ok',
+                message: 'Launcher "java -jar" is supported for exact MCP copy.',
+            }
+            : {
+                label: 'Launcher',
+                status: 'error',
+                message: 'Launcher "java" is only supported for exact MCP copy when used as "java -jar <path>".',
+            };
+    }
+    if (entry.command === 'go') {
+        const runIndex = entry.args?.indexOf('run') ?? -1;
+        const runPath = runIndex >= 0 ? entry.args?.[runIndex + 1] : undefined;
+        return runPath
+            ? {
+                label: 'Launcher',
+                status: 'ok',
+                message: 'Launcher "go run" is supported for exact MCP copy.',
+            }
+            : {
+                label: 'Launcher',
+                status: 'error',
+                message: 'Launcher "go" is only supported for exact MCP copy when used as "go run <path>".',
+            };
+    }
+    if (entry.command === 'cargo') {
+        return entry.args?.[0] === 'run'
+            ? {
+                label: 'Launcher',
+                status: 'ok',
+                message: 'Launcher "cargo run" is supported for exact MCP copy.',
+            }
+            : {
+                label: 'Launcher',
+                status: 'error',
+                message: 'Launcher "cargo" is only supported for exact MCP copy when used as "cargo run".',
+            };
+    }
+    return {
+        label: 'Launcher',
+        status: 'error',
+        message: `Launcher "${entry.command}" is not supported for exact MCP copy. Supported launchers: ${SUPPORTED_LOCAL_LAUNCHERS.join(', ')}.`,
+    };
+}
+function isLocalBinaryPath(command) {
+    return command.startsWith('./') || command.startsWith('/') || command.startsWith('.\\');
+}
+function validateRemoteMcp(agent, remoteEntry) {
+    const checks = [];
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(remoteEntry.url);
+    }
+    catch {
+        checks.push({
+            label: 'Remote URL',
+            status: 'error',
+            message: `Remote MCP URL is invalid: ${remoteEntry.url}`,
+        });
+        return { ok: false, checks };
+    }
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        checks.push({
+            label: 'Remote URL',
+            status: 'error',
+            message: `Remote MCP URL must use http or https: ${remoteEntry.url}`,
+        });
+        return { ok: false, checks };
+    }
+    checks.push({
+        label: 'Remote URL',
+        status: 'ok',
+        message: `Remote MCP URL is valid: ${remoteEntry.url}`,
+    });
+    if (agent === 'codex' && (remoteEntry.transport !== 'http' || remoteEntry.headers || remoteEntry.env)) {
+        checks.push({
+            label: 'Remote support',
+            status: 'error',
+            message: 'Codex remote MCP entries only support a plain HTTP url today; headers and env cannot be preserved exactly.',
+        });
+    }
+    return {
+        ok: checks.every((check) => check.status !== 'error'),
+        checks,
+    };
+}
+async function defaultPathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,135 @@
+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 PluginBundleAgent {
+    name: string;
+    sourceFormat: 'claude-md' | 'codex-toml';
+    content: string;
+}
+export interface PluginBundleCommand {
+    name: string;
+    content: string;
+}
+export interface PluginInstallPlan {
+    ok: boolean;
+    checks: PluginInstallCheck[];
+    skills: string[];
+    mcps: Record<string, AgentMcpEntry>;
+    agents: string[];
+    commands: string[];
+}
+export interface PluginInstallResult {
+    installedSkills: string[];
+    installedMcps: string[];
+    installedAgents: string[];
+    installedCommands: string[];
+}
+export interface PluginUninstallPlan {
+    ok: boolean;
+    checks: PluginInstallCheck[];
+    skills: string[];
+    mcps: string[];
+    agents: string[];
+    commands: string[];
+}
+export interface PluginUninstallResult {
+    removedSkills: string[];
+    removedMcps: string[];
+    removedAgents: string[];
+    removedCommands: 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>;
+    agents: PluginBundleAgent[];
+    commands: PluginBundleCommand[];
+}
+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>;
+    installAgent?: (options: {
+        targetAgent: AgentName;
+        agent: PluginBundleAgent;
+    }) => Promise<void>;
+    installCommand?: (options: {
+        targetAgent: AgentName;
+        command: PluginBundleCommand;
+    }) => 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>;
+    removeAgentFile?: (options: {
+        targetAgent: AgentName;
+        agentName: string;
+    }) => Promise<void>;
+    removeCommandFile?: (options: {
+        targetAgent: AgentName;
+        commandName: string;
+    }) => Promise<void>;
+    removeMcpEntry?: (options: {
+        cwd: string;
+        agent: AgentName;
+        key: string;
+    }) => Promise<void>;
+    removeManagedPluginInstall?: (options: {
+        agent: AgentName;
+        pluginName: string;
+    }) => Promise<void>;
+    uninstallCodexPlugin?: (options: {
+        pluginKey: string;
+        installPath: string;
+    }) => Promise<void>;
+    uninstallClaudePlugin?: (options: {
+        pluginKey: string;
+        installPath: string;
+    }) => Promise<void>;
+}
+export declare function createPluginInstallService(dependencies?: PluginInstallDependencies): PluginInstallService;
+export {};