brainctl 0.1.7 → 0.1.9

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

@@ -1,8 +1,13 @@
-import { cp, mkdir, readFile, rm } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { copyFile, cp, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { ValidationError } from '../errors.js';
+import { formatTimestamp } from './sync/agent-writer.js';
+import { stripPluginSection } from './sync/codex-writer.js';
 import { createAgentConfigService } from './agent-config-service.js';
-import { getSkillDir } from './skill-paths.js';
+import { claudeAgentMdToCodexToml, claudeCommandMdToCodexSkill, codexAgentTomlToClaudeMd, } from './agent-converter-service.js';
+import { getAgentFilePath, getCommandFilePath, getSkillDir } from './skill-paths.js';
 import { removeManagedPluginInstall, writeManagedPluginInstall, } from './sync/managed-plugin-registry.js';
 export function createPluginInstallService(dependencies = {}) {
     const agentConfigService = createAgentConfigService();
@@ -16,6 +21,8 @@ export function createPluginInstallService(dependencies = {}) {
         };
     });
     const copySkillDirectory = dependencies.copySkillDirectory ?? defaultCopySkillDirectory;
+    const installAgent = dependencies.installAgent ?? defaultInstallAgent;
+    const installCommand = dependencies.installCommand ?? defaultInstallCommand;
     const addMcpEntry = dependencies.addMcpEntry ?? (async ({ cwd, agent, key, entry }) => {
         await agentConfigService.addMcp({ cwd, agent, key, entry });
     });
@@ -24,9 +31,13 @@ export function createPluginInstallService(dependencies = {}) {
             await writeManagedPluginInstall({ agent, plugin });
         });
     const removeSkillDirectory = dependencies.removeSkillDirectory ?? defaultRemoveSkillDirectory;
+    const removeAgentFile = dependencies.removeAgentFile ?? defaultRemoveAgentFile;
+    const removeCommandFile = dependencies.removeCommandFile ?? defaultRemoveCommandFile;
     const removeMcpEntry = dependencies.removeMcpEntry ?? (async ({ cwd, agent, key }) => {
         await agentConfigService.removeMcp({ cwd, agent, key });
     });
+    const uninstallCodexPlugin = dependencies.uninstallCodexPlugin ?? defaultUninstallCodexPlugin;
+    const uninstallClaudePlugin = dependencies.uninstallClaudePlugin ?? defaultUninstallClaudePlugin;
     const removeRecordedManagedPluginInstall = dependencies.removeManagedPluginInstall ??
         (async ({ agent, pluginName }) => {
             await removeManagedPluginInstall({ agent, pluginName });
@@ -40,25 +51,39 @@ export function createPluginInstallService(dependencies = {}) {
                     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: {} };
+                return { ok: false, checks, skills: [], mcps: {}, agents: [], commands: [] };
             }
             const bundle = await readInstalledPluginBundle(options.plugin.installPath);
             const targetState = await readTargetState({
                 cwd: options.cwd,
                 agent: options.targetAgent,
             });
+            const bundleAgents = bundle.agents ?? [];
+            const bundleCommands = bundle.commands ?? [];
+            const agentsForTarget = bundleAgents.filter(() => isAgentInstallableOnTarget(options.targetAgent));
+            const commandsForTarget = bundleCommands.filter(() => isCommandInstallableOnTarget(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}".`,
+                message: `Discovered ${bundle.skills.length} skills, ${Object.keys(bundle.mcps).length} MCPs, ${agentsForTarget.length} agents, and ${commandsForTarget.length} commands in plugin "${options.plugin.name}".`,
             });
-            if (bundle.skills.length === 0 && Object.keys(bundle.mcps).length === 0) {
+            if (bundle.skills.length === 0 &&
+                Object.keys(bundle.mcps).length === 0 &&
+                agentsForTarget.length === 0 &&
+                commandsForTarget.length === 0) {
                 checks.push({
                     label: 'Bundle',
                     status: 'error',
                     message: `Plugin "${options.plugin.name}" does not expose portable skills or MCPs for installation.`,
                 });
             }
+            const incompatible = await detectIncompatibleArtifacts(options.plugin.installPath);
+            for (const warning of formatCompatibilityWarnings(incompatible, {
+                sourceAgent: options.sourceAgent,
+                targetAgent: options.targetAgent,
+            })) {
+                checks.push(warning);
+            }
             for (const skillName of bundle.skills) {
                 if (targetState.skills.some((skill) => skill.name === skillName)) {
                     checks.push({
@@ -77,11 +102,45 @@ export function createPluginInstallService(dependencies = {}) {
                     });
                 }
             }
+            for (const agent of agentsForTarget) {
+                const targetPath = getAgentFilePath(options.targetAgent, agent.name);
+                if (await pathExists(targetPath)) {
+                    checks.push({
+                        label: 'Target agent',
+                        status: 'error',
+                        message: `Agent "${agent.name}" already exists in ${options.targetAgent}.`,
+                    });
+                }
+            }
+            for (const command of commandsForTarget) {
+                if (options.targetAgent === 'claude') {
+                    const targetPath = getCommandFilePath('claude', command.name);
+                    if (await pathExists(targetPath)) {
+                        checks.push({
+                            label: 'Target command',
+                            status: 'error',
+                            message: `Command "${command.name}" already exists in claude.`,
+                        });
+                    }
+                }
+                else if (options.targetAgent === 'codex') {
+                    const skillDir = getSkillDir('codex', command.name);
+                    if (await pathExists(skillDir) || targetState.skills.some((s) => s.name === command.name)) {
+                        checks.push({
+                            label: 'Target command',
+                            status: 'error',
+                            message: `Command "${command.name}" already exists as a skill in codex.`,
+                        });
+                    }
+                }
+            }
             return {
                 ok: checks.every((check) => check.status !== 'error'),
                 checks,
                 skills: bundle.skills,
                 mcps: bundle.mcps,
+                agents: agentsForTarget.map((a) => a.name),
+                commands: commandsForTarget.map((c) => c.name),
             };
         },
         async execute(options) {
@@ -91,6 +150,7 @@ export function createPluginInstallService(dependencies = {}) {
                 throw new ValidationError(firstError?.message ?? 'Plugin install plan failed.');
             }
             const installPath = options.plugin.installPath;
+            const bundle = await readInstalledPluginBundle(installPath);
             for (const skillName of plan.skills) {
                 await copySkillDirectory({
                     sourceInstallPath: installPath,
@@ -106,6 +166,18 @@ export function createPluginInstallService(dependencies = {}) {
                     entry,
                 });
             }
+            for (const agentName of plan.agents) {
+                const agent = (bundle.agents ?? []).find((a) => a.name === agentName);
+                if (!agent)
+                    continue;
+                await installAgent({ targetAgent: options.targetAgent, agent });
+            }
+            for (const commandName of plan.commands) {
+                const command = (bundle.commands ?? []).find((c) => c.name === commandName);
+                if (!command)
+                    continue;
+                await installCommand({ targetAgent: options.targetAgent, command });
+            }
             await recordManagedPluginInstall({
                 agent: options.targetAgent,
                 plugin: {
@@ -113,12 +185,16 @@ export function createPluginInstallService(dependencies = {}) {
                     kind: 'plugin',
                     pluginSkills: plan.skills,
                     pluginMcps: Object.keys(plan.mcps),
+                    pluginAgents: plan.agents,
+                    pluginCommands: plan.commands,
                     managed: true,
                 },
             });
             return {
                 installedSkills: plan.skills,
                 installedMcps: Object.keys(plan.mcps),
+                installedAgents: plan.agents,
+                installedCommands: plan.commands,
             };
         },
         async planRemoval(options) {
@@ -129,37 +205,36 @@ export function createPluginInstallService(dependencies = {}) {
                     status: 'error',
                     message: `"${options.plugin.name}" is not a plugin entry.`,
                 });
-                return { ok: false, checks, skills: [], mcps: [] };
+                return { ok: false, checks, skills: [], mcps: [], agents: [], commands: [] };
             }
-            if (!options.plugin.managed) {
+            const unmanagedCodex = isUnmanagedCodexPlugin(options.targetAgent, options.plugin);
+            const unmanagedClaude = isUnmanagedClaudePlugin(options.targetAgent, options.plugin);
+            if (!options.plugin.managed && !unmanagedCodex && !unmanagedClaude) {
                 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);
-                }
+                return { ok: false, checks, skills: [], mcps: [], agents: [], commands: [] };
             }
+            const skills = [...(options.plugin.pluginSkills ?? [])];
+            const mcps = [...(options.plugin.pluginMcps ?? [])];
+            const agents = [...(options.plugin.pluginAgents ?? [])];
+            const commands = [...(options.plugin.pluginCommands ?? [])];
             checks.push({
                 label: 'Bundle',
                 status: 'ok',
-                message: `Will remove ${skills.length} skills and ${mcps.length} MCPs from plugin "${options.plugin.name}".`,
+                message: unmanagedCodex || unmanagedClaude
+                    ? `Will uninstall ${options.targetAgent} plugin "${options.plugin.name}" (${skills.length} skills, ${mcps.length} MCPs, ${agents.length} agents, ${commands.length} commands) and remove its cache directory.`
+                    : `Will remove ${skills.length} skills, ${mcps.length} MCPs, ${agents.length} agents, and ${commands.length} commands from plugin "${options.plugin.name}".`,
             });
             return {
                 ok: true,
                 checks,
                 skills,
                 mcps,
+                agents,
+                commands,
             };
         },
         async remove(options) {
@@ -168,6 +243,32 @@ export function createPluginInstallService(dependencies = {}) {
                 const firstError = plan.checks.find((check) => check.status === 'error');
                 throw new ValidationError(firstError?.message ?? 'Plugin removal plan failed.');
             }
+            if (isUnmanagedCodexPlugin(options.targetAgent, options.plugin)) {
+                const pluginKey = `${options.plugin.name}@${options.plugin.source}`;
+                await uninstallCodexPlugin({
+                    pluginKey,
+                    installPath: options.plugin.installPath,
+                });
+                return {
+                    removedSkills: plan.skills,
+                    removedMcps: plan.mcps,
+                    removedAgents: plan.agents,
+                    removedCommands: plan.commands,
+                };
+            }
+            if (isUnmanagedClaudePlugin(options.targetAgent, options.plugin)) {
+                const pluginKey = `${options.plugin.name}@${options.plugin.source}`;
+                await uninstallClaudePlugin({
+                    pluginKey,
+                    installPath: options.plugin.installPath,
+                });
+                return {
+                    removedSkills: plan.skills,
+                    removedMcps: plan.mcps,
+                    removedAgents: plan.agents,
+                    removedCommands: plan.commands,
+                };
+            }
             for (const skillName of plan.skills) {
                 await removeSkillDirectory({
                     targetAgent: options.targetAgent,
@@ -181,6 +282,12 @@ export function createPluginInstallService(dependencies = {}) {
                     key,
                 });
             }
+            for (const agentName of plan.agents) {
+                await removeAgentFile({ targetAgent: options.targetAgent, agentName });
+            }
+            for (const commandName of plan.commands) {
+                await removeCommandFile({ targetAgent: options.targetAgent, commandName });
+            }
             await removeRecordedManagedPluginInstall({
                 agent: options.targetAgent,
                 pluginName: options.plugin.name,
@@ -188,10 +295,81 @@ export function createPluginInstallService(dependencies = {}) {
             return {
                 removedSkills: plan.skills,
                 removedMcps: plan.mcps,
+                removedAgents: plan.agents,
+                removedCommands: plan.commands,
             };
         },
     };
 }
+function isUnmanagedCodexPlugin(targetAgent, plugin) {
+    return (!plugin.managed &&
+        targetAgent === 'codex' &&
+        typeof plugin.installPath === 'string' &&
+        typeof plugin.source === 'string' &&
+        plugin.source.length > 0);
+}
+function isUnmanagedClaudePlugin(targetAgent, plugin) {
+    return (!plugin.managed &&
+        targetAgent === 'claude' &&
+        typeof plugin.installPath === 'string' &&
+        typeof plugin.source === 'string' &&
+        plugin.source.length > 0);
+}
+async function defaultUninstallClaudePlugin(options) {
+    // Delegate to `claude plugin uninstall` so a running Claude Code session
+    // drops the plugin from its in-memory state (direct fs mutation gets
+    // resurrected by live sessions that still have the plugin loaded).
+    await new Promise((resolve, reject) => {
+        const child = spawn('claude', ['plugin', 'uninstall', options.pluginKey, '--scope', 'user'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stderr = '';
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', (error) => {
+            reject(new ValidationError(`Failed to invoke \`claude\` CLI: ${error.message}. Is Claude Code installed on PATH?`));
+        });
+        child.on('exit', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            const detail = (stderr || stdout).trim();
+            reject(new ValidationError(`\`claude plugin uninstall ${options.pluginKey}\` exited ${code}${detail ? `: ${detail}` : ''}`));
+        });
+    });
+}
+async function defaultUninstallCodexPlugin(options) {
+    const home = homedir();
+    const cacheRoot = path.join(home, '.codex', 'plugins', 'cache');
+    const resolvedInstall = path.resolve(options.installPath);
+    if (!resolvedInstall.startsWith(cacheRoot + path.sep)) {
+        throw new ValidationError(`Refusing to remove Codex plugin files outside ${cacheRoot}: ${resolvedInstall}`);
+    }
+    const pluginRoot = path.dirname(resolvedInstall);
+    const configPath = path.join(home, '.codex', 'config.toml');
+    let existing = '';
+    try {
+        existing = await readFile(configPath, 'utf8');
+    }
+    catch {
+        existing = '';
+    }
+    if (existing.length > 0) {
+        const next = stripPluginSection(existing, options.pluginKey);
+        if (next !== existing) {
+            const backupPath = `${configPath}.bak.${formatTimestamp()}`;
+            await copyFile(configPath, backupPath);
+            const tmpPath = `${configPath}.tmp.${Date.now()}`;
+            await writeFile(tmpPath, next, 'utf8');
+            await rename(tmpPath, configPath);
+        }
+    }
+    await rm(pluginRoot, { recursive: true, force: true });
+}
 async function defaultReadInstalledPluginBundle(installPath) {
     const skillsDir = path.join(installPath, 'skills');
     let skills = [];
@@ -229,7 +407,98 @@ async function defaultReadInstalledPluginBundle(installPath) {
     catch {
         mcps = {};
     }
-    return { skills, mcps };
+    const agents = [];
+    try {
+        const entries = await readdir(path.join(installPath, 'agents'), { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (entry.name.endsWith('.md')) {
+                const content = await readFile(path.join(installPath, 'agents', entry.name), 'utf8');
+                agents.push({ name: entry.name.replace(/\.md$/, ''), sourceFormat: 'claude-md', content });
+            }
+            else if (entry.name.endsWith('.toml')) {
+                const content = await readFile(path.join(installPath, 'agents', entry.name), 'utf8');
+                agents.push({ name: entry.name.replace(/\.toml$/, ''), sourceFormat: 'codex-toml', content });
+            }
+        }
+        agents.sort((left, right) => left.name.localeCompare(right.name));
+    }
+    catch {
+        // no agents dir
+    }
+    const commands = [];
+    try {
+        const entries = await readdir(path.join(installPath, 'commands'), { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            const content = await readFile(path.join(installPath, 'commands', entry.name), 'utf8');
+            commands.push({ name: entry.name.replace(/\.md$/, ''), content });
+        }
+        commands.sort((left, right) => left.name.localeCompare(right.name));
+    }
+    catch {
+        // no commands dir
+    }
+    return { skills, mcps, agents, commands };
+}
+function isAgentInstallableOnTarget(target) {
+    return target === 'claude' || target === 'codex';
+}
+function isCommandInstallableOnTarget(target) {
+    return target === 'claude' || target === 'codex';
+}
+async function defaultInstallAgent(options) {
+    const targetPath = getAgentFilePath(options.targetAgent, options.agent.name);
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    let output;
+    if (options.targetAgent === 'claude') {
+        output = options.agent.sourceFormat === 'claude-md'
+            ? options.agent.content
+            : codexAgentTomlToClaudeMd(options.agent.content);
+    }
+    else if (options.targetAgent === 'codex') {
+        output = options.agent.sourceFormat === 'codex-toml'
+            ? options.agent.content
+            : claudeAgentMdToCodexToml(options.agent.content);
+    }
+    else {
+        throw new Error(`Agent install is not supported for ${options.targetAgent}`);
+    }
+    await writeFile(targetPath, output, 'utf8');
+}
+async function defaultInstallCommand(options) {
+    if (options.targetAgent === 'claude') {
+        const targetPath = getCommandFilePath('claude', options.command.name);
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, options.command.content, 'utf8');
+        return;
+    }
+    if (options.targetAgent === 'codex') {
+        const skillDir = getSkillDir('codex', options.command.name);
+        await mkdir(skillDir, { recursive: true });
+        const { skillMarkdown } = claudeCommandMdToCodexSkill(options.command.content);
+        await writeFile(path.join(skillDir, 'SKILL.md'), skillMarkdown, 'utf8');
+        return;
+    }
+    throw new Error(`Command install is not supported for ${options.targetAgent}`);
+}
+async function defaultRemoveAgentFile(options) {
+    const targetPath = getAgentFilePath(options.targetAgent, options.agentName);
+    await rm(targetPath, { force: true });
+}
+async function defaultRemoveCommandFile(options) {
+    if (options.targetAgent === 'claude') {
+        const targetPath = getCommandFilePath('claude', options.commandName);
+        await rm(targetPath, { force: true });
+        return;
+    }
+    if (options.targetAgent === 'codex') {
+        const skillDir = getSkillDir('codex', options.commandName);
+        await rm(skillDir, { recursive: true, force: true });
+        return;
+    }
 }
 async function defaultCopySkillDirectory(options) {
     const sourceDir = path.join(options.sourceInstallPath, 'skills', options.skillName);
@@ -241,3 +510,92 @@ async function defaultRemoveSkillDirectory(options) {
     const targetDir = getSkillDir(options.targetAgent, options.skillName);
     await rm(targetDir, { recursive: true, force: true });
 }
+async function detectIncompatibleArtifacts(installPath) {
+    const [hasAppConnector, hasHooks, hasCommands, codexAgentSkills, claudeAgents] = await Promise.all([
+        pathExists(path.join(installPath, '.app.json')),
+        pathExists(path.join(installPath, 'hooks')),
+        pathExists(path.join(installPath, 'commands')),
+        listCodexAgentSkills(installPath),
+        listClaudeAgentFiles(installPath),
+    ]);
+    return { hasAppConnector, hasHooks, hasCommands, codexAgentSkills, claudeAgents };
+}
+async function pathExists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function listCodexAgentSkills(installPath) {
+    const skillsDir = path.join(installPath, 'skills');
+    try {
+        const entries = await readdir(skillsDir, { withFileTypes: true });
+        const matches = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            if (await pathExists(path.join(skillsDir, entry.name, 'agents'))) {
+                matches.push(entry.name);
+            }
+        }
+        return matches.sort((left, right) => left.localeCompare(right));
+    }
+    catch {
+        return [];
+    }
+}
+async function listClaudeAgentFiles(installPath) {
+    const agentsDir = path.join(installPath, 'agents');
+    try {
+        const entries = await readdir(agentsDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+            .map((entry) => entry.name.replace(/\.md$/, ''))
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch {
+        return [];
+    }
+}
+function formatCompatibilityWarnings(artifacts, context) {
+    const warnings = [];
+    if (artifacts.hasAppConnector && context.targetAgent !== 'codex') {
+        warnings.push({
+            label: 'App connector',
+            status: 'warn',
+            message: `Plugin ships a Codex app connector (.app.json) that will NOT transfer. Skill instructions will copy over but the backing integration will not work on ${context.targetAgent}.`,
+        });
+    }
+    if (artifacts.codexAgentSkills.length > 0 && context.targetAgent !== 'codex') {
+        warnings.push({
+            label: 'Codex agent YAML',
+            status: 'warn',
+            message: `Skills ${artifacts.codexAgentSkills.join(', ')} include Codex-specific agent YAML that will not transfer to ${context.targetAgent}.`,
+        });
+    }
+    if (artifacts.hasHooks && context.targetAgent !== 'claude') {
+        warnings.push({
+            label: 'Claude hooks',
+            status: 'warn',
+            message: `Plugin ships session hooks that only work on Claude and will NOT transfer to ${context.targetAgent}.`,
+        });
+    }
+    if (context.targetAgent === 'gemini' && artifacts.claudeAgents.length > 0) {
+        warnings.push({
+            label: 'Subagents',
+            status: 'warn',
+            message: `Plugin ships subagent definitions (${artifacts.claudeAgents.join(', ')}) that cannot be converted to ${context.targetAgent}.`,
+        });
+    }
+    if (context.targetAgent === 'gemini' && artifacts.hasCommands) {
+        warnings.push({
+            label: 'Slash commands',
+            status: 'warn',
+            message: `Plugin ships slash commands that cannot be converted to ${context.targetAgent}.`,
+        });
+    }
+    return warnings;
+}

package/dist/services/portable-mcp-classifier.d.ts

@@ -0,0 +1,12 @@
+import { ValidationError } from '../errors.js';
+import type { LocalBundledMcpServerConfig, LocalNpmMcpServerConfig, RemoteMcpServerConfig } from '../types.js';
+import type { AgentMcpEntry, PortableRemoteMcpMetadata } from './agent-config-service.js';
+export type PortableMcpClassification = LocalNpmMcpServerConfig | LocalBundledMcpServerConfig | RemoteMcpServerConfig;
+export declare class PortableMcpClassificationError extends ValidationError {
+}
+export declare function classifyPortableMcp(options: {
+    cwd: string;
+    key: string;
+    entry: AgentMcpEntry;
+    remote?: PortableRemoteMcpMetadata;
+}): PortableMcpClassification;

package/dist/services/portable-mcp-classifier.js

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import { ValidationError } from '../errors.js';
+import { detectMcpRuntime, extractEntrypoint } from './runtime-detector.js';
+const NPX_LIKE_COMMANDS = new Set(['npx', 'uvx']);
+export class PortableMcpClassificationError extends ValidationError {
+}
+export function classifyPortableMcp(options) {
+    if (options.remote) {
+        return classifyRemoteMcp(options.key, options.remote);
+    }
+    const packageName = resolveNpxPackage(options.entry);
+    if (packageName) {
+        return {
+            kind: 'local',
+            source: 'npm',
+            package: packageName,
+            ...(options.entry.env ? { env: options.entry.env } : {}),
+        };
+    }
+    const runtime = detectMcpRuntime(options.entry.command);
+    if (runtime) {
+        return classifyBundledMcp(options.cwd, options.key, options.entry, runtime);
+    }
+    throw new PortableMcpClassificationError(`MCP "${options.key}" cannot be packed: unrecognized command "${options.entry.command}".`);
+}
+function classifyBundledMcp(cwd, key, entry, runtime) {
+    const entrypoint = extractEntrypoint(entry.command, entry.args ?? []);
+    let bundlePath;
+    if (runtime === 'rust') {
+        bundlePath = cwd;
+    }
+    else if (entrypoint) {
+        const resolvedEntrypoint = path.resolve(cwd, entrypoint);
+        const entrypointDir = path.dirname(resolvedEntrypoint);
+        bundlePath = resolveProjectLocalPath(cwd, entrypointDir, key);
+    }
+    else {
+        throw new PortableMcpClassificationError(`MCP "${key}" cannot be packed: could not determine entrypoint from args.`);
+    }
+    return {
+        kind: 'local',
+        source: 'bundled',
+        runtime,
+        path: bundlePath,
+        command: entry.command,
+        ...(entry.args ? { args: entry.args } : {}),
+        ...(entry.env ? { env: entry.env } : {}),
+    };
+}
+function classifyRemoteMcp(key, remote) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(remote.url);
+    }
+    catch {
+        throw new PortableMcpClassificationError(`Remote MCP "${key}" must include an absolute http(s) url.`);
+    }
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        throw new PortableMcpClassificationError(`Remote MCP "${key}" must include an absolute http(s) url.`);
+    }
+    if (remote.transport !== 'http' && remote.transport !== 'sse') {
+        throw new PortableMcpClassificationError(`Remote MCP "${key}" must use transport "http" or "sse".`);
+    }
+    return {
+        kind: 'remote',
+        transport: remote.transport,
+        url: remote.url,
+        ...(remote.headers ? { headers: remote.headers } : {}),
+        ...(remote.env ? { env: remote.env } : {}),
+    };
+}
+function resolveNpxPackage(entry) {
+    if (!NPX_LIKE_COMMANDS.has(entry.command)) {
+        return null;
+    }
+    const packageName = resolveDeclaredNpxPackage(entry.args ?? []);
+    if (!packageName) {
+        throw new PortableMcpClassificationError('npx/uvx-based MCP entries must include a package or executable argument.');
+    }
+    return packageName;
+}
+function resolveDeclaredNpxPackage(args) {
+    let packageName = null;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--package') {
+            const nextArg = args[index + 1];
+            if (nextArg && !nextArg.startsWith('-')) {
+                return nextArg;
+            }
+            continue;
+        }
+        if (arg.startsWith('--package=')) {
+            const declaredPackage = arg.slice('--package='.length).trim();
+            if (declaredPackage.length > 0) {
+                return declaredPackage;
+            }
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            continue;
+        }
+        if (!packageName) {
+            packageName = arg;
+        }
+    }
+    return packageName;
+}
+function resolveProjectLocalPath(cwd, candidate, key) {
+    const resolved = path.resolve(cwd, candidate);
+    const relative = path.relative(cwd, resolved);
+    if (relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) {
+        throw new PortableMcpClassificationError(`MCP "${key}" cannot be packed: path "${candidate}" is outside the project directory.`);
+    }
+    return resolved;
+}