@cleocode/caamp 2026.4.0 → 2026.4.4

package/dist/index.d.ts

@@ -1196,146 +1196,11 @@ interface GlobalOptions {
     quiet?: boolean;
 }
 
-/**
- * MCP config installer
- *
- * Writes MCP server configurations to agent config files,
- * handling per-agent formats, keys, and transformations.
- */
-
-/**
- * Result of installing an MCP server configuration to a single provider.
- *
- * @example
- * ```typescript
- * const provider = getProvider("claude-code")!;
- * const result = await installMcpServer(provider, "my-server", {
- *   command: "npx",
- *   args: ["-y", "@modelcontextprotocol/server-filesystem"],
- * });
- * if (result.success) {
- *   console.log(`Written to ${result.configPath}`);
- * }
- * ```
- *
- * @public
- */
-interface InstallResult {
-    /** The provider the config was written to. */
-    provider: Provider;
-    /** Whether project or global scope was used. */
-    scope: 'project' | 'global';
-    /** Absolute path to the config file that was written. */
-    configPath: string;
-    /** Whether the write succeeded. */
-    success: boolean;
-    /** Error message if the write failed. @defaultValue undefined */
-    error?: string;
-}
-/**
- * Install an MCP server configuration for a single provider.
- *
- * Applies provider-specific transforms (e.g. Goose, Zed, Codex) and writes
- * the config to the provider's config file in the specified scope.
- *
- * @remarks
- * The installation flow is: resolve config path, apply any provider-specific
- * transform via {@link getTransform}, then write the result using the
- * provider's config format (JSON, YAML, or TOML). If the provider does not
- * support the requested scope, a failed result is returned without throwing.
- *
- * @param provider - Target provider to write config for
- * @param serverName - Name/key for the MCP server entry
- * @param config - Canonical MCP server configuration
- * @param scope - Whether to write to project or global config (default: `"project"`)
- * @param projectDir - Project directory path (defaults to `process.cwd()`)
- * @returns Install result with success status and config path
- *
- * @example
- * ```typescript
- * const provider = getProvider("claude-code")!;
- * const result = await installMcpServer(provider, "filesystem", {
- *   command: "npx",
- *   args: ["-y", "@modelcontextprotocol/server-filesystem"],
- * }, "project", "/home/user/my-project");
- * ```
- *
- * @public
- */
-declare function installMcpServer(provider: Provider, serverName: string, config: McpServerConfig, scope?: 'project' | 'global', projectDir?: string): Promise<InstallResult>;
-/**
- * Install an MCP server configuration to multiple providers.
- *
- * Calls {@link installMcpServer} for each provider sequentially and collects results.
- *
- * @remarks
- * Providers are processed sequentially (not in parallel) to avoid concurrent
- * writes to shared config files. Each provider's result is independent --
- * a failure for one provider does not prevent installation to others.
- *
- * @param providers - Array of target providers
- * @param serverName - Name/key for the MCP server entry
- * @param config - Canonical MCP server configuration
- * @param scope - Whether to write to project or global config (default: `"project"`)
- * @param projectDir - Project directory path (defaults to `process.cwd()`)
- * @returns Array of install results, one per provider
- *
- * @example
- * ```typescript
- * const providers = getInstalledProviders();
- * const config = { command: "npx", args: ["-y", "@mcp/server"] };
- * const results = await installMcpServerToAll(providers, "my-server", config, "project", "/home/user/project");
- * const successes = results.filter(r => r.success);
- * ```
- *
- * @see {@link installMcpServer}
- *
- * @public
- */
-declare function installMcpServerToAll(providers: Provider[], serverName: string, config: McpServerConfig, scope?: 'project' | 'global', projectDir?: string): Promise<InstallResult[]>;
-/**
- * Build a canonical {@link McpServerConfig} from a parsed source.
- *
- * Maps source types to appropriate transport configurations:
- * - `"remote"` sources become HTTP/SSE configs with a `url`
- * - `"package"` sources become `npx -y <package>` stdio configs
- * - All others are treated as shell commands split into `command` + `args`
- *
- * @remarks
- * This function normalizes diverse source inputs into the canonical config
- * format that CAAMP uses internally. Provider-specific transforms are applied
- * later during installation via {@link getTransform}. Command-type sources
- * are split on whitespace, with the first token becoming `command` and the
- * remainder becoming `args`.
- *
- * @param source - Parsed source with `type` and `value`
- * @param transport - Override transport type for remote sources (default: `"http"`)
- * @param headers - Optional HTTP headers for remote servers
- * @returns Canonical MCP server configuration
- *
- * @example
- * ```typescript
- * buildServerConfig({ type: "package", value: "@mcp/server-fs" }, undefined, undefined);
- * // { command: "npx", args: ["-y", "@mcp/server-fs"] }
- *
- * buildServerConfig({ type: "remote", value: "https://mcp.example.com" }, "http", { "Authorization": "Bearer token" });
- * // { type: "http", url: "https://mcp.example.com", headers: { "Authorization": "Bearer token" } }
- * ```
- *
- * @see {@link installMcpServer}
- *
- * @public
- */
-declare function buildServerConfig(source: {
-    type: string;
-    value: string;
-}, transport?: string, headers?: Record<string, string>): McpServerConfig;
-
 /**
  * Advanced orchestration helpers for multi-provider operations.
  *
  * These helpers compose CAAMP's lower-level APIs into production patterns:
- * tier-based targeting, conflict-aware installs, and rollback-capable batches.
+ * tier-based targeting, rollback-capable skill batches, and instruction updates.
  */
 
 type Scope = 'project' | 'global';
@@ -1360,23 +1225,6 @@ type Scope = 'project' | 'global';
  * @public
  */
 declare function selectProvidersByMinimumPriority(providers: Provider[], minimumPriority?: ProviderPriority): Provider[];
-/**
- * Single MCP operation entry used by batch orchestration.
- *
- * @remarks
- * Represents one MCP server installation that will be applied across
- * all targeted providers during a batch operation.
- *
- * @public
- */
-interface McpBatchOperation {
-    /** The name of the MCP server to install. */
-    serverName: string;
-    /** The MCP server configuration to write. */
-    config: McpServerConfig;
-    /** The scope for installation, defaults to `"project"`. */
-    scope?: Scope;
-}
 /**
  * Single skill operation entry used by batch orchestration.
  *
@@ -1409,8 +1257,6 @@ interface BatchInstallOptions {
     providers?: Provider[];
     /** Minimum provider priority threshold for filtering. */
     minimumPriority?: ProviderPriority;
-    /** MCP server operations to apply in the batch. */
-    mcp?: McpBatchOperation[];
     /** Skill operations to apply in the batch. */
     skills?: SkillBatchOperation[];
     /** Project root directory, defaults to `process.cwd()`. */
@@ -1430,8 +1276,6 @@ interface BatchInstallResult {
     success: boolean;
     /** IDs of providers that were targeted. */
     providerIds: string[];
-    /** Number of MCP server installations that were applied. */
-    mcpApplied: number;
     /** Number of skill installations that were applied. */
     skillsApplied: number;
     /** Whether rollback was performed due to a failure. */
@@ -1442,13 +1286,12 @@ interface BatchInstallResult {
     error?: string;
 }
 /**
- * Installs multiple MCP servers and skills across filtered providers with rollback.
+ * Installs multiple skills across filtered providers with rollback.
  *
  * @remarks
- * Snapshots all affected config files and skill directories before applying
- * operations. If any operation fails, all changes are rolled back by restoring
- * config file snapshots and reverting skill symlinks and canonical directories
- * to their pre-operation state.
+ * Snapshots all affected skill directories before applying operations.
+ * If any operation fails, all changes are rolled back by reverting
+ * skill symlinks and canonical directories to their pre-operation state.
  *
  * @param options - The batch installation options including providers, operations, and scope
  * @returns A result object indicating success, applied counts, and any rollback information
@@ -1457,7 +1300,6 @@ interface BatchInstallResult {
  * ```typescript
  * const result = await installBatchWithRollback({
  *   minimumPriority: "high",
- *   mcp: [{ serverName: "my-server", config: { command: "npx", args: ["my-server"] } }],
  *   skills: [{ sourcePath: "/path/to/skill", skillName: "my-skill" }],
  * });
  * if (!result.success) {
@@ -1468,119 +1310,6 @@ interface BatchInstallResult {
  * @public
  */
 declare function installBatchWithRollback(options: BatchInstallOptions): Promise<BatchInstallResult>;
-/**
- * Conflict policy when applying MCP install plans.
- *
- * @remarks
- * Controls behavior when an existing MCP server configuration conflicts
- * with the desired configuration: `"fail"` aborts the entire operation,
- * `"skip"` leaves conflicting entries unchanged, and `"overwrite"` replaces them.
- *
- * @public
- */
-type ConflictPolicy = 'fail' | 'skip' | 'overwrite';
-/**
- * Conflict code identifying the type of MCP configuration conflict.
- *
- * @remarks
- * Used in {@link McpConflict} to categorize detected conflicts during
- * preflight checks before applying MCP installations.
- *
- * @public
- */
-type McpConflictCode = 'unsupported-transport' | 'unsupported-headers' | 'existing-mismatch';
-/**
- * Describes a conflict detected during MCP installation preflight.
- *
- * @remarks
- * Contains the provider, server, scope, and nature of the conflict
- * so that callers can decide how to proceed based on their conflict policy.
- *
- * @public
- */
-interface McpConflict {
-    /** The provider where the conflict was detected. */
-    providerId: string;
-    /** The MCP server name involved in the conflict. */
-    serverName: string;
-    /** The scope (global or project) of the conflicting config. */
-    scope: Scope;
-    /** The type of conflict detected. */
-    code: McpConflictCode;
-    /** Human-readable description of the conflict. */
-    message: string;
-}
-/**
- * Result from applying an MCP install plan with a conflict policy.
- *
- * @remarks
- * Contains all detected conflicts, successfully applied installations,
- * and any operations that were skipped due to the conflict policy.
- *
- * @public
- */
-interface McpPlanApplyResult {
-    /** All conflicts detected during preflight, regardless of policy. */
-    conflicts: McpConflict[];
-    /** Successfully applied MCP server installations. */
-    applied: InstallResult[];
-    /** Operations skipped due to the conflict policy. */
-    skipped: Array<{
-        providerId: string;
-        serverName: string;
-        scope: Scope;
-        reason: McpConflictCode;
-    }>;
-}
-/**
- * Performs preflight conflict detection for MCP install plans across providers.
- *
- * @remarks
- * Checks each provider-operation pair for transport support, header support,
- * and existing configuration mismatches. Returns all detected conflicts without
- * modifying any files. Callers can then decide whether to proceed based on
- * their conflict policy.
- *
- * @param providers - The providers to check for conflicts
- * @param operations - The MCP operations to validate against existing configs
- * @param projectDir - The project root directory, defaults to `process.cwd()`
- * @returns An array of detected conflicts, empty if no conflicts found
- *
- * @example
- * ```typescript
- * const conflicts = await detectMcpConfigConflicts(providers, operations);
- * if (conflicts.length > 0) {
- *   console.warn("Conflicts detected:", conflicts);
- * }
- * ```
- *
- * @public
- */
-declare function detectMcpConfigConflicts(providers: Provider[], operations: McpBatchOperation[], projectDir?: string): Promise<McpConflict[]>;
-/**
- * Applies an MCP install plan with a conflict policy controlling behavior on conflicts.
- *
- * @remarks
- * First runs {@link detectMcpConfigConflicts} to find all conflicts, then applies
- * the specified policy: `"fail"` returns immediately with no changes, `"skip"`
- * leaves conflicting entries unchanged and applies the rest, and `"overwrite"`
- * applies all operations regardless of conflicts.
- *
- * @param providers - The providers to install MCP servers for
- * @param operations - The MCP server operations to apply
- * @param policy - The conflict resolution policy, defaults to `"fail"`
- * @param projectDir - The project root directory, defaults to `process.cwd()`
- * @returns A result containing conflicts, applied installations, and skipped operations
- *
- * @example
- * ```typescript
- * const result = await applyMcpInstallWithPolicy(providers, operations, "skip");
- * console.log(`Applied: ${result.applied.length}, Skipped: ${result.skipped.length}`);
- * ```
- *
- * @public
- */
-declare function applyMcpInstallWithPolicy(providers: Provider[], operations: McpBatchOperation[], policy?: ConflictPolicy, projectDir?: string): Promise<McpPlanApplyResult>;
 /**
  * Result of a single-operation instruction update across providers.
  *
@@ -1631,87 +1360,6 @@ interface InstructionUpdateSummary {
  * @public
  */
 declare function updateInstructionsSingleOperation(providers: Provider[], content: string, scope?: Scope, projectDir?: string): Promise<InstructionUpdateSummary>;
-/**
- * Request payload for dual-scope provider configuration.
- *
- * @remarks
- * Allows configuring both global and project-level MCP servers and
- * instructions in a single call. Instruction content can be a single
- * string applied to both scopes or scope-specific strings.
- *
- * @public
- */
-interface DualScopeConfigureOptions {
-    /** MCP servers to install at global scope. */
-    globalMcp?: Array<{
-        serverName: string;
-        config: McpServerConfig;
-    }>;
-    /** MCP servers to install at project scope. */
-    projectMcp?: Array<{
-        serverName: string;
-        config: McpServerConfig;
-    }>;
-    /** Instruction content for injection, either shared or per-scope. */
-    instructionContent?: string | {
-        global?: string;
-        project?: string;
-    };
-    /** Project root directory, defaults to `process.cwd()`. */
-    projectDir?: string;
-}
-/**
- * Result of dual-scope provider configuration.
- *
- * @remarks
- * Contains the resolved config paths, MCP installation results for both
- * scopes, and instruction injection results for each scope that was configured.
- *
- * @public
- */
-interface DualScopeConfigureResult {
-    /** The ID of the configured provider. */
-    providerId: string;
-    /** Resolved configuration file paths for both scopes. */
-    configPaths: {
-        global: string | null;
-        project: string | null;
-    };
-    /** MCP installation results for each scope. */
-    mcp: {
-        global: InstallResult[];
-        project: InstallResult[];
-    };
-    /** Instruction injection results for each scope, if applicable. */
-    instructions: {
-        global?: Map<string, 'created' | 'added' | 'consolidated' | 'updated' | 'intact'>;
-        project?: Map<string, 'created' | 'added' | 'consolidated' | 'updated' | 'intact'>;
-    };
-}
-/**
- * Configures both global and project-level settings for one provider in one call.
- *
- * @remarks
- * Applies MCP server installations and instruction injections at both global
- * and project scope in a single coordinated operation. This avoids the need
- * to make separate calls for each scope.
- *
- * @param provider - The provider to configure
- * @param options - The dual-scope configuration options
- * @returns A result containing config paths, MCP results, and instruction results for both scopes
- *
- * @example
- * ```typescript
- * const result = await configureProviderGlobalAndProject(provider, {
- *   globalMcp: [{ serverName: "my-server", config: { command: "npx", args: ["my-server"] } }],
- *   instructionContent: "## Agent Setup\nUse these tools...",
- * });
- * console.log(result.configPaths);
- * ```
- *
- * @public
- */
-declare function configureProviderGlobalAndProject(provider: Provider, options: DualScopeConfigureOptions): Promise<DualScopeConfigureResult>;
 
 /**
  * Format utility functions
@@ -3166,691 +2814,6 @@ declare class MarketplaceClient {
     getSkill(scopedName: string): Promise<MarketplaceResult | null>;
 }
 
-/**
- * CLEO MCP channel profile helpers.
- */
-
-/**
- * CLEO release channel identifier.
- *
- * @remarks
- * Determines which version stream is used: `"stable"` for production releases,
- * `"beta"` for pre-release versions, and `"dev"` for local development builds.
- *
- * @public
- */
-type CleoChannel = 'stable' | 'beta' | 'dev';
-/**
- * Options for building a CLEO MCP server profile configuration.
- *
- * @remarks
- * For stable and beta channels, the `version` field controls the npm package
- * version. For the dev channel, `command` is required to specify the local
- * binary path or command.
- *
- * @public
- */
-interface CleoProfileBuildOptions {
-    /** The CLEO release channel to target. */
-    channel: CleoChannel;
-    /** Optional npm version tag or semver range for stable/beta channels. */
-    version?: string;
-    /** Custom command binary for dev channel, required when channel is `"dev"`. */
-    command?: string;
-    /** Additional arguments to pass to the command. */
-    args?: string[];
-    /** Environment variables to set in the MCP server config. */
-    env?: Record<string, string>;
-    /** Custom CLEO directory path for dev channel, overrides default. */
-    cleoDir?: string;
-}
-/**
- * Result of building a CLEO MCP server profile configuration.
- *
- * @remarks
- * Contains the resolved channel, server name, and MCP configuration.
- * For stable/beta channels, `packageSpec` contains the npm package
- * specifier used in the npx command.
- *
- * @public
- */
-interface CleoProfileBuildResult {
-    /** The resolved CLEO release channel. */
-    channel: CleoChannel;
-    /** The MCP server name for this channel. */
-    serverName: string;
-    /** The MCP server configuration ready for installation. */
-    config: McpServerConfig;
-    /** The npm package specifier, present for stable/beta channels. */
-    packageSpec?: string;
-}
-/**
- * Result of checking whether a command is reachable on the system.
- *
- * @remarks
- * The `method` field indicates whether the command was checked as a filesystem
- * path or via system PATH lookup (using `which`/`where`).
- *
- * @public
- */
-interface CommandReachability {
-    /** Whether the command was found and is reachable. */
-    reachable: boolean;
-    /** The method used to check reachability. */
-    method: 'path' | 'lookup';
-    /** The resolved path or command name that was checked. */
-    detail: string;
-}
-/**
- * Normalizes a string value to a valid CLEO channel identifier.
- *
- * @remarks
- * Trims and lowercases the input, then validates it against the known
- * channel names. Returns `"stable"` for empty or undefined input.
- * Throws if the value is not a recognized channel.
- *
- * @param value - The raw channel string to normalize
- * @returns The normalized CLEO channel
- * @throws Error if the value is not `"stable"`, `"beta"`, or `"dev"`
- *
- * @example
- * ```typescript
- * const channel = normalizeCleoChannel("Beta");
- * // returns "beta"
- * ```
- *
- * @public
- */
-declare function normalizeCleoChannel(value?: string): CleoChannel;
-/**
- * Resolves the MCP server name for a given CLEO channel.
- *
- * @remarks
- * Maps channel identifiers to their corresponding server names
- * using the {@link CLEO_SERVER_NAMES} registry.
- *
- * @param channel - The CLEO channel to resolve
- * @returns The MCP server name for the channel
- *
- * @example
- * ```typescript
- * const name = resolveCleoServerName("stable");
- * // returns "cleo"
- * ```
- *
- * @public
- */
-declare function resolveCleoServerName(channel: CleoChannel): string;
-/**
- * Resolves a CLEO channel from an MCP server name.
- *
- * @remarks
- * Performs a reverse lookup from server name to channel. Returns null
- * if the server name does not match any known CLEO channel.
- *
- * @param serverName - The MCP server name to look up
- * @returns The matching CLEO channel, or null if not a CLEO server
- *
- * @example
- * ```typescript
- * const channel = resolveChannelFromServerName("cleo-beta");
- * // returns "beta"
- * ```
- *
- * @public
- */
-declare function resolveChannelFromServerName(serverName: string): CleoChannel | null;
-/**
- * Builds a CLEO MCP server profile configuration from options.
- *
- * @remarks
- * For the dev channel, constructs a config using the provided command and args.
- * For stable/beta channels, constructs an npx-based config with the appropriate
- * package specifier. Dev channel requires a command; stable/beta use npx with
- * the `@cleocode/cleo` package.
- *
- * @param options - The profile build options specifying channel, command, version, etc.
- * @returns The built profile with server name, config, and optional package spec
- * @throws Error if dev channel is selected without a command
- *
- * @example
- * ```typescript
- * const profile = buildCleoProfile({ channel: "stable" });
- * // profile.config.command === "npx"
- * // profile.config.args === ["-y", "@cleocode/cleo@latest", "mcp"]
- * ```
- *
- * @public
- */
-declare function buildCleoProfile(options: CleoProfileBuildOptions): CleoProfileBuildResult;
-/**
- * Checks whether a command binary is reachable on the current system.
- *
- * @remarks
- * If the command contains path separators or starts with `~`, it is treated
- * as a filesystem path and checked with `existsSync`. Otherwise, a system
- * PATH lookup is performed using `which` (Unix) or `where` (Windows).
- *
- * @param command - The command or path to check for reachability
- * @returns A reachability result indicating whether the command was found
- *
- * @example
- * ```typescript
- * const result = checkCommandReachability("node");
- * if (result.reachable) {
- *   console.log("Found via", result.method);
- * }
- * ```
- *
- * @public
- */
-declare function checkCommandReachability(command: string): CommandReachability;
-/**
- * Parses an array of `KEY=value` strings into an environment variable record.
- *
- * @remarks
- * Each string must contain an `=` separator with a non-empty key.
- * Throws on malformed entries. Whitespace around keys and values is trimmed.
- *
- * @param values - Array of `KEY=value` assignment strings
- * @returns A record mapping environment variable names to their values
- * @throws Error if any assignment is malformed (missing `=` or empty key)
- *
- * @example
- * ```typescript
- * const env = parseEnvAssignments(["NODE_ENV=production", "PORT=3000"]);
- * // returns { NODE_ENV: "production", PORT: "3000" }
- * ```
- *
- * @public
- */
-declare function parseEnvAssignments(values: string[]): Record<string, string>;
-/**
- * Extracts the version tag from an npm package specifier string.
- *
- * @remarks
- * Splits on the last `@` character to separate the package name from
- * the version tag. Returns undefined if no version tag is present or
- * the input is falsy.
- *
- * @param packageSpec - The npm package specifier, e.g., `"@cleocode/cleo@1.2.0"`
- * @returns The extracted version tag, or undefined if not present
- *
- * @example
- * ```typescript
- * const tag = extractVersionTag("@cleocode/cleo@1.2.0");
- * // returns "1.2.0"
- * ```
- *
- * @public
- */
-declare function extractVersionTag(packageSpec?: string): string | undefined;
-/**
- * Checks whether a source string identifies a CLEO MCP installation.
- *
- * @remarks
- * Performs a case-insensitive comparison after trimming whitespace.
- * Returns true only when the source is exactly `"cleo"`.
- *
- * @param source - The source identifier string to check
- * @returns True if the source represents a CLEO installation
- *
- * @example
- * ```typescript
- * isCleoSource("cleo");  // true
- * isCleoSource("Cleo");  // true
- * isCleoSource("other"); // false
- * ```
- *
- * @public
- */
-declare function isCleoSource(source: string): boolean;
-
-/**
- * Shared lock file utilities
- *
- * Single source of truth for reading/writing the canonical CAAMP lock file path.
- * Both MCP and skills lock modules import from here.
- */
-
-/**
- * Read and parse the CAAMP lock file from disk.
- *
- * @remarks
- * Returns a default empty lock structure when the file does not exist or
- * cannot be parsed, ensuring callers always receive a valid object.
- *
- * @returns Parsed lock file contents
- *
- * @example
- * ```typescript
- * const lock = await readLockFile();
- * console.log(Object.keys(lock.mcpServers));
- * ```
- *
- * @public
- */
-declare function readLockFile(): Promise<CaampLockFile>;
-
-/**
- * MCP lock file management
- *
- * Tracks installed MCP servers with source and agent metadata.
- * Stored in the canonical CAAMP lock file (shared with skills lock).
- */
-
-/**
- * Record an MCP server installation in the lock file.
- *
- * Creates or updates an entry in `lock.mcpServers`. If the server already exists,
- * the agent list is merged and `updatedAt` is refreshed while `installedAt` is preserved.
- *
- * @remarks
- * Uses an atomic read-modify-write pattern via `updateLockFile`. When updating
- * an existing entry, the agent list is deduplicated using a `Set` to prevent
- * duplicate provider IDs. The `installedAt` timestamp is preserved from the
- * original entry while `updatedAt` is always refreshed.
- *
- * @param serverName - Name/key of the MCP server
- * @param source - Original source string
- * @param sourceType - Classified source type
- * @param agents - Provider IDs the server was installed to
- * @param isGlobal - Whether this is a global installation
- * @param version - Optional version string for the installed package
- *
- * @example
- * ```typescript
- * await recordMcpInstall("filesystem", "@mcp/server-fs", "package", ["claude-code"], true, "1.0.0");
- * ```
- *
- * @public
- */
-declare function recordMcpInstall(serverName: string, source: string, sourceType: SourceType, agents: string[], isGlobal: boolean, version?: string): Promise<void>;
-/**
- * Remove an MCP server entry from the lock file.
- *
- * @remarks
- * Uses an atomic read-modify-write pattern. If the server name is not present
- * in the lock file, the file is not modified and `false` is returned.
- *
- * @param serverName - Name/key of the MCP server to remove
- * @returns `true` if the entry was found and removed, `false` if not found
- *
- * @example
- * ```typescript
- * const removed = await removeMcpFromLock("filesystem");
- * if (removed) {
- *   console.log("Server removed from lock file");
- * }
- * ```
- *
- * @public
- */
-declare function removeMcpFromLock(serverName: string): Promise<boolean>;
-/**
- * Get all MCP servers tracked in the lock file.
- *
- * @remarks
- * Returns the `mcpServers` section of the lock file as a record. Each key
- * is a server name and each value contains installation metadata including
- * source, agents, timestamps, and scope.
- *
- * @returns Record of server name to lock entry
- *
- * @example
- * ```typescript
- * const servers = await getTrackedMcpServers();
- * for (const [name, entry] of Object.entries(servers)) {
- *   console.log(`${name}: installed ${entry.installedAt}`);
- * }
- * ```
- *
- * @public
- */
-declare function getTrackedMcpServers(): Promise<Record<string, LockEntry>>;
-/**
- * Save the last selected agent IDs to the lock file for UX persistence.
- *
- * Used to remember the user's agent selection between CLI invocations.
- *
- * @remarks
- * Persists the `lastSelectedAgents` field in the lock file so subsequent
- * CLI invocations can default to the same agent selection. This avoids
- * requiring the user to re-select agents each time.
- *
- * @param agents - Array of provider IDs to remember
- *
- * @example
- * ```typescript
- * await saveLastSelectedAgents(["claude-code", "cursor"]);
- * ```
- *
- * @public
- */
-declare function saveLastSelectedAgents(agents: string[]): Promise<void>;
-/**
- * Retrieve the last selected agent IDs from the lock file.
- *
- * @remarks
- * Returns the `lastSelectedAgents` field from the lock file, which is
- * set by {@link saveLastSelectedAgents}. Returns `undefined` if no
- * selection has been persisted yet.
- *
- * @returns Array of provider IDs, or `undefined` if none were saved
- *
- * @example
- * ```typescript
- * const agents = await getLastSelectedAgents();
- * // ["claude-code", "cursor"] or undefined
- * ```
- *
- * @public
- */
-declare function getLastSelectedAgents(): Promise<string[] | undefined>;
-
-/**
- * MCP config reader
- *
- * Reads, lists, and removes MCP server entries from agent config files.
- * Provides the programmatic API that CLI commands delegate to.
- */
-
-/**
- * Resolve the absolute config file path for a provider and scope.
- *
- * For project scope, joins the project directory with the provider's relative
- * config path. For global scope, returns the provider's global config path.
- *
- * @remarks
- * Delegates to {@link resolveProviderConfigPath} from the paths module.
- * Returns `null` when the provider has no config path defined for the
- * requested scope (e.g. some providers only support global config).
- *
- * @param provider - Provider to resolve config path for
- * @param scope - Whether to resolve project or global config path
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Absolute config file path, or `null` if the provider does not support the given scope
- *
- * @example
- * ```typescript
- * const provider = getProvider("claude-code")!;
- * const path = resolveConfigPath(provider, "project", "/home/user/my-project");
- * // Returns provider-specific project config path
- * ```
- *
- * @public
- */
-declare function resolveConfigPath(provider: Provider, scope: 'project' | 'global', projectDir?: string): string | null;
-/**
- * List MCP servers configured for a single provider.
- *
- * Reads the provider's config file, extracts the MCP servers section using the
- * provider's `configKey`, and returns each server entry with metadata.
- *
- * @remarks
- * The config file is read using the format handler matching the provider's
- * `configFormat` (JSON, YAML, or TOML). The `configKey` is used to extract
- * the MCP servers section (e.g. `"mcpServers"`, `"mcp_servers"`, `"extensions"`).
- * Returns an empty array if the file does not exist or cannot be parsed.
- *
- * @param provider - Provider whose config file to read
- * @param scope - Whether to read project or global config
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Array of MCP server entries found in the config file
- *
- * @example
- * ```typescript
- * const provider = getProvider("claude-code")!;
- * const servers = await listMcpServers(provider, "project", "/home/user/my-project");
- * for (const s of servers) {
- *   console.log(`${s.name} (${s.scope})`);
- * }
- * ```
- *
- * @public
- */
-declare function listMcpServers(provider: Provider, scope: 'project' | 'global', projectDir?: string): Promise<McpServerEntry[]>;
-/**
- * List MCP servers from the `.agents/mcp/servers.json` standard location.
- *
- * Per the `.agents/` standard (Section 9), this file is the canonical
- * provider-agnostic MCP server registry. It should be checked before
- * per-provider legacy config files.
- *
- * @remarks
- * The `.agents/mcp/servers.json` file uses a `{ "servers": { ... } }` structure
- * where each key is a server name. Entries returned from this function use
- * `providerId: ".agents"` and `providerName: ".agents/ standard"` to distinguish
- * them from per-provider legacy entries.
- *
- * @param scope - `"global"` for `~/.agents/mcp/servers.json`, `"project"` for project-level
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Array of MCP server entries found in the `.agents/` servers.json
- *
- * @example
- * ```typescript
- * const globalServers = await listAgentsMcpServers("global");
- * const projectServers = await listAgentsMcpServers("project", "/home/user/my-project");
- * console.log(`Found ${globalServers.length} global, ${projectServers.length} project servers`);
- * ```
- *
- * @public
- */
-declare function listAgentsMcpServers(scope: 'project' | 'global', projectDir?: string): Promise<McpServerEntry[]>;
-/**
- * List MCP servers across all given providers, deduplicating by config path.
- *
- * Per the `.agents/` standard (Section 9.4), checks `.agents/mcp/servers.json`
- * first, then falls back to per-provider legacy config files. Multiple providers
- * may share the same config file; this function ensures each config file is read
- * only once to avoid duplicate entries.
- *
- * @remarks
- * The deduplication is path-based: if two providers share the same config file
- * (resolved to the same absolute path), it is read only once. The `.agents/`
- * standard location is always checked first and takes precedence.
- *
- * @param providers - Array of providers to query
- * @param scope - Whether to read project or global config
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Combined array of MCP server entries from all providers
- *
- * @example
- * ```typescript
- * const installed = getInstalledProviders();
- * const allServers = await listAllMcpServers(installed, "global", "/home/user/my-project");
- * console.log(`Found ${allServers.length} servers across all providers`);
- * ```
- *
- * @public
- */
-declare function listAllMcpServers(providers: Provider[], scope: 'project' | 'global', projectDir?: string): Promise<McpServerEntry[]>;
-/**
- * Remove an MCP server entry from a provider's config file.
- *
- * @remarks
- * Delegates to the format-specific `removeConfig` handler. If the provider
- * does not have a config path for the requested scope, returns `false`
- * without modifying any files.
- *
- * @param provider - Provider whose config file to modify
- * @param serverName - Name/key of the MCP server to remove
- * @param scope - Whether to modify project or global config
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns `true` if the entry was removed, `false` if no config path exists
- *
- * @example
- * ```typescript
- * const provider = getProvider("claude-code")!;
- * const removed = await removeMcpServer(provider, "my-server", "project", "/home/user/my-project");
- * ```
- *
- * @public
- */
-declare function removeMcpServer(provider: Provider, serverName: string, scope: 'project' | 'global', projectDir?: string): Promise<boolean>;
-
-/**
- * CLEO MCP lock reconciliation
- *
- * Infers lock metadata from live config entries and backfills
- * missing lock entries for CLEO servers installed before lock tracking.
- */
-
-/**
- * Lock metadata inferred from a live MCP config entry.
- *
- * @public
- */
-interface InferredLockData {
-    /** The source string (package name, command, or path). */
-    source: string;
-    /** Classified source type. */
-    sourceType: SourceType;
-    /** Inferred version string, if extractable from the config. @defaultValue undefined */
-    version: string | undefined;
-}
-/**
- * Infer lock metadata from a live MCP config entry.
- *
- * Determines source, sourceType, and version by inspecting the command and args
- * of an existing CLEO MCP server config entry.
- *
- * @remarks
- * The inference logic checks three patterns in order: (1) if any argument
- * contains the CLEO npm package name, it is classified as a `"package"` source
- * with the version extracted from the package specifier; (2) if the channel is
- * `"dev"` or the command contains path separators, it is classified as a
- * `"command"` source; (3) otherwise, the full command + args string is used as
- * a `"command"` source.
- *
- * @param config - The raw config object from the provider's config file
- * @param channel - The resolved CLEO channel (`"stable"`, `"next"`, or `"dev"`)
- * @returns Inferred lock metadata with source, sourceType, and optional version
- *
- * @example
- * ```typescript
- * const data = inferCleoLockData(
- *   { command: "npx", args: ["-y", "@cleocode/cleo-mcp@1.2.0"] },
- *   "stable",
- * );
- * // { source: "@cleocode/cleo-mcp@1.2.0", sourceType: "package", version: "1.2.0" }
- * ```
- *
- * @public
- */
-declare function inferCleoLockData(config: Record<string, unknown>, channel: CleoChannel): InferredLockData;
-/**
- * Options for the CLEO lock reconciliation process.
- *
- * @public
- */
-interface ReconcileOptions {
-    /** Specific provider IDs to scan (if omitted, scans all installed). @defaultValue undefined */
-    providerIds?: string[];
-    /** Whether to scan all providers. @defaultValue undefined */
-    all?: boolean;
-    /** Whether to scan global-scope configs. @defaultValue undefined */
-    global?: boolean;
-    /** Whether to scan project-scope configs. @defaultValue undefined */
-    project?: boolean;
-    /** Whether to remove orphaned lock entries not found in any live config. @defaultValue undefined */
-    prune?: boolean;
-    /** If true, report changes without writing to the lock file. @defaultValue undefined */
-    dryRun?: boolean;
-}
-/**
- * Result of a CLEO lock reconciliation operation.
- *
- * @public
- */
-interface ReconcileResult {
-    /** Entries that were backfilled into the lock file. @defaultValue [] */
-    backfilled: Array<{
-        serverName: string;
-        channel: CleoChannel;
-        scope: 'project' | 'global';
-        agents: string[];
-        source: string;
-        sourceType: SourceType;
-        version: string | undefined;
-    }>;
-    /** Server names that were pruned from the lock file. */
-    pruned: string[];
-    /** Count of entries that were already tracked in the lock file. */
-    alreadyTracked: number;
-    /** Errors encountered during reconciliation. */
-    errors: Array<{
-        message: string;
-    }>;
-}
-/**
- * Reconcile CLEO lock entries against live config.
- *
- * 1. Scans all providers x scopes for CLEO server entries
- * 2. Identifies entries not tracked in the lock file
- * 3. Backfills missing entries via recordMcpInstall
- * 4. Optionally prunes orphaned lock entries (in lock but not in any config)
- *
- * @remarks
- * This function bridges the gap between CLEO servers installed before lock
- * tracking was introduced and the current lock file state. It scans live
- * config files across all installed providers and requested scopes, infers
- * lock metadata from the config entries, and writes missing entries to the
- * lock file. When `prune` is enabled, it also removes lock entries for
- * CLEO servers that no longer appear in any live config.
- *
- * @param options - Reconciliation options controlling scope, providers, and behavior
- * @returns Reconciliation result with backfilled entries, pruned entries, and errors
- *
- * @example
- * ```typescript
- * const result = await reconcileCleoLock({ global: true, prune: true });
- * console.log(`Backfilled: ${result.backfilled.length}, Pruned: ${result.pruned.length}`);
- * ```
- *
- * @public
- */
-declare function reconcileCleoLock(options?: ReconcileOptions): Promise<ReconcileResult>;
-
-/**
- * Per-agent MCP config transformations
- *
- * Most agents use the canonical McpServerConfig directly.
- * These transforms handle agents with non-standard schemas.
- */
-
-/**
- * Get the config transform function for a provider, or `undefined` for passthrough.
- *
- * Providers with non-standard MCP config schemas (Goose, Zed, OpenCode, Codex, Cursor)
- * require transforms to convert the canonical {@link McpServerConfig} into their
- * provider-specific format.
- *
- * @remarks
- * Five of the 28+ supported providers use non-standard MCP config schemas.
- * This function acts as a registry of transform functions, returning `undefined`
- * for providers that accept the canonical format directly (the majority).
- * The returned function takes a server name and canonical config and produces
- * the provider-specific shape.
- *
- * @param providerId - Provider ID to look up (e.g. `"goose"`, `"zed"`)
- * @returns Transform function, or `undefined` if the provider uses the canonical format
- *
- * @example
- * ```typescript
- * const transform = getTransform("goose");
- * if (transform) {
- *   const gooseConfig = transform("my-server", { command: "npx", args: ["-y", "@mcp/server"] });
- * }
- * ```
- *
- * @see {@link transformGoose}
- * @see {@link transformZed}
- *
- * @public
- */
-declare function getTransform(providerId: string): ((name: string, config: McpServerConfig) => unknown) | undefined;
-
 /**
  * Scope for path resolution, either global (user home) or project-local.
  *
@@ -6700,4 +5663,4 @@ declare function parseSource(input: string): ParsedSource;
  */
 declare function isMarketplaceScoped(input: string): boolean;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type CleoChannel, type CleoProfileBuildResult, type ConfigFormat, type ConflictPolicy, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, type DetectionCacheOptions, type DetectionResult, type DualScopeConfigureOptions, type DualScopeConfigureResult, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type GlobalOptions, HOOK_CATEGORIES, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InferredLockData, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallResult, type InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpBatchOperation, type McpConflict, type McpConflictCode, type McpPlanApplyResult, type McpServerConfig, type McpServerEntry, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, type PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type ReconcileOptions, type ReconcileResult, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SystemInfo, type TransportType, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, applyMcpInstallWithPolicy, buildCleoProfile, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildServerConfig, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkCommandReachability, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, configureProviderGlobalAndProject, deepMerge, detectAllProviders, detectMcpConfigConflicts, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, extractVersionTag, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLastSelectedAgents, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedMcpServers, getTrackedSkills, getTransform, getUnsupportedEvents, groupByInstructFile, inferCleoLockData, inject, injectAll, installBatchWithRollback, installMcpServer, installMcpServerToAll, installSkill, isCaampOwnedSkill, isCleoSource, isMarketplaceScoped, isQuiet, isVerbose, listAgentsMcpServers, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeCleoChannel, normalizeRecommendationCriteria, parseEnvAssignments, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, readLockFile, recommendSkills, reconcileCleoLock, recordMcpInstall, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpFromLock, removeMcpServer, removeSkill, removeSkillFromLock, resetDetectionCache, resolveAlias, resolveChannelFromServerName, resolveCleoServerName, resolveConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, saveLastSelectedAgents, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, type DetectionCacheOptions, type DetectionResult, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type GlobalOptions, HOOK_CATEGORIES, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpServerConfig, type McpServerEntry, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, type PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SystemInfo, type TransportType, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, deepMerge, detectAllProviders, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inject, injectAll, installBatchWithRollback, installSkill, isCaampOwnedSkill, isMarketplaceScoped, isQuiet, isVerbose, listCanonicalSkills, loadLibraryFromModule, normalizeRecommendationCriteria, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeSkill, removeSkillFromLock, resetDetectionCache, resolveAlias, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };