@nimblebrain/mpak-sdk 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -1,53 +1,13 @@
-import { VersionDetail, DownloadInfo, VersionsResponse, PlatformInfo, FullProvenance, SkillSummary, SkillDetail, BundleSearchResponse, BundleDetail, SkillSearchResponse, SkillDownloadInfo } from '@nimblebrain/mpak-schemas';
-export { Bundle, BundleDetail, BundleDetail as BundleDetailResponse, DownloadInfo as BundleDownloadResponse, BundleSearchResponse, VersionDetail as BundleVersionResponse, VersionsResponse as BundleVersionsResponse, Pagination, SkillDetail, SkillDetail as SkillDetailResponse, SkillDownloadInfo, SkillDownloadInfo as SkillDownloadResponse, SkillSearchResponse } from '@nimblebrain/mpak-schemas';
+import { BundleSearchParamsInput, BundleSearchResponse, BundleDetail, VersionsResponse, VersionDetail, PlatformInfo, DownloadInfo, SkillSearchParamsInput, SkillSearchResponse, SkillDetail, SkillDownloadInfo, CacheMetadata, McpbManifest, CachedBundleInfo } from '@nimblebrain/mpak-schemas';
+import { z } from 'zod';
 
 /**
  * SDK-specific type definitions for mpak SDK
  *
- * API response types are re-exported from @nimblebrain/mpak-schemas.
- * This file contains SDK-specific types (client config, skill references, etc.)
+ * API response types should be imported directly from @nimblebrain/mpak-schemas.
+ * This file contains only SDK-specific types (client config).
  */
 
-/** Version in versions listing */
-type BundleVersion = VersionsResponse['versions'][number];
-/** Artifact in version detail */
-type BundleArtifact = VersionDetail['artifacts'][number];
-/** Download info alias */
-type BundleDownloadInfo = DownloadInfo;
-/** Skill summary in search results */
-type Skill = SkillSummary;
-
-/** Skill version in detail */
-type SkillVersion = SkillDetail['versions'][number];
-/** Platform identifier (os + arch) */
-type Platform = PlatformInfo;
-
-/** Provenance information for verified packages */
-type Provenance = FullProvenance;
-/** Author information */
-interface Author {
-    name: string;
-    url?: string;
-    email?: string;
-}
-/** Query parameters for bundle search */
-interface BundleSearchParams {
-    q?: string;
-    type?: string;
-    sort?: 'downloads' | 'recent' | 'name';
-    limit?: number;
-    offset?: number;
-}
-/** Query parameters for skill search */
-interface SkillSearchParams {
-    q?: string;
-    tags?: string;
-    category?: string;
-    surface?: string;
-    sort?: 'downloads' | 'recent' | 'name';
-    limit?: number;
-    offset?: number;
-}
 /**
  * Configuration options for MpakClient
  */
@@ -68,64 +28,11 @@ interface MpakClientConfig {
      */
     userAgent?: string;
 }
-/**
- * Base fields shared by all skill reference types
- */
-interface SkillReferenceBase {
-    /** Skill artifact identifier (e.g., '@nimbletools/folk-crm') */
-    name: string;
-    /** Semver version (e.g., '1.0.0') or 'latest' */
-    version: string;
-    /** SHA256 integrity hash (format: 'sha256-hexdigest') */
-    integrity?: string;
-}
-/**
- * Skill reference from mpak registry
- */
-interface MpakSkillReference extends SkillReferenceBase {
-    source: 'mpak';
-}
-/**
- * Skill reference from GitHub repository
- */
-interface GithubSkillReference extends SkillReferenceBase {
-    source: 'github';
-    /** GitHub repository (owner/repo) */
-    repo: string;
-    /** Path to skill file in repo */
-    path: string;
-}
-/**
- * Skill reference from direct URL
- */
-interface UrlSkillReference extends SkillReferenceBase {
-    source: 'url';
-    /** Direct download URL */
-    url: string;
-}
-/**
- * Discriminated union of skill reference types
- */
-type SkillReference = MpakSkillReference | GithubSkillReference | UrlSkillReference;
-/**
- * Result of resolving a skill reference
- */
-interface ResolvedSkill {
-    /** The markdown content of the skill */
-    content: string;
-    /** Version that was resolved */
-    version: string;
-    /** Source the skill was fetched from */
-    source: 'mpak' | 'github' | 'url';
-    /** Whether integrity was verified */
-    verified: boolean;
-}
 
 /**
  * Client for interacting with the mpak registry
  *
  * Requires Node.js 18+ for native fetch support.
- * Uses jszip for skill bundle extraction.
  */
 declare class MpakClient {
     private readonly registryUrl;
@@ -135,7 +42,7 @@ declare class MpakClient {
     /**
      * Search for bundles
      */
-    searchBundles(params?: BundleSearchParams): Promise<BundleSearchResponse>;
+    searchBundles(params?: BundleSearchParamsInput): Promise<BundleSearchResponse>;
     /**
      * Get bundle details
      */
@@ -151,11 +58,11 @@ declare class MpakClient {
     /**
      * Get download info for a bundle
      */
-    getBundleDownload(name: string, version: string, platform?: Platform): Promise<DownloadInfo>;
+    getBundleDownload(name: string, version: string, platform?: PlatformInfo): Promise<DownloadInfo>;
     /**
      * Search for skills
      */
-    searchSkills(params?: SkillSearchParams): Promise<SkillSearchResponse>;
+    searchSkills(params?: SkillSearchParamsInput): Promise<SkillSearchResponse>;
     /**
      * Get skill details
      */
@@ -169,96 +76,456 @@ declare class MpakClient {
      */
     getSkillVersionDownload(name: string, version: string): Promise<SkillDownloadInfo>;
     /**
-     * Download skill content and verify integrity
+     * Download content from a URL and verify its SHA-256 integrity.
      *
-     * @throws {MpakIntegrityError} If expectedSha256 is provided and doesn't match (fail-closed)
+     * @throws {MpakIntegrityError} If SHA-256 doesn't match
+     * @throws {MpakNetworkError} For network failures
      */
-    downloadSkillContent(downloadUrl: string, expectedSha256?: string): Promise<{
-        content: string;
-        verified: boolean;
-    }>;
+    downloadContent(url: string, sha256: string): Promise<Uint8Array>;
     /**
-     * Resolve a skill reference to actual content
+     * Download a bundle by name, with optional version and platform.
+     * Defaults to latest version and auto-detected platform.
      *
-     * Supports mpak, github, and url sources. This is the main method for
-     * fetching skill content from any supported source.
+     * @throws {MpakNotFoundError} If bundle not found
+     * @throws {MpakIntegrityError} If SHA-256 doesn't match
+     * @throws {MpakNetworkError} For network failures
+     */
+    downloadBundle(name: string, version?: string, platform?: PlatformInfo): Promise<{
+        data: Uint8Array;
+        metadata: DownloadInfo['bundle'];
+    }>;
+    /**
+     * Download a skill bundle by name, with optional version.
+     * Defaults to latest version.
      *
      * @throws {MpakNotFoundError} If skill not found
-     * @throws {MpakIntegrityError} If integrity check fails (fail-closed)
+     * @throws {MpakIntegrityError} If SHA-256 doesn't match
      * @throws {MpakNetworkError} For network failures
+     */
+    downloadSkillBundle(name: string, version?: string): Promise<{
+        data: Uint8Array;
+        metadata: SkillDownloadInfo['skill'];
+    }>;
+    /**
+     * Detect the current platform
+     */
+    static detectPlatform(): PlatformInfo;
+    /**
+     * Compute SHA256 hash of content
+     */
+    private computeSha256;
+    /**
+     * Validate that a name is scoped (@scope/name)
+     */
+    private validateScopedName;
+    /**
+     * Fetch with timeout support
+     */
+    private fetchWithTimeout;
+}
+
+interface MpakBundleCacheOptions {
+    mpakHome?: string;
+}
+/**
+ * Manages the local bundle cache (`~/.mpak/cache/`).
+ *
+ * Handles downloading, extracting, and tracking cached bundles.
+ * The cache directory is derived from `mpakHome` — the root directory
+ * for all mpak state. Consumers can wire this to `MpakConfigManager.mpakHome`
+ * for a shared base, or pass any directory.
+ *
+ * Requires an `MpakClient` for registry operations (download, update checks).
+ *
+ * @example
+ * ```ts
+ * // Via MpakSDK facade (recommended)
+ * const mpak = new MpakSDK();
+ * await mpak.cache.loadBundle('@scope/name');
+ *
+ * // Standalone
+ * const client = new MpakClient();
+ * const cache = new MpakBundleCache(client, { mpakHome: '/path/to/.mpak' });
+ * await cache.loadBundle('@scope/name');
+ * ```
+ */
+declare class MpakBundleCache {
+    readonly cacheHome: string;
+    private readonly mpakClient;
+    constructor(client: MpakClient, options?: MpakBundleCacheOptions);
+    /**
+     * Compute the cache path for a package. Does not create the directory.
+     * @example getPackageCachePath('@scope/name') => '<cacheBase>/scope-name'
+     */
+    getBundleCacheDirName(packageName: string): string;
+    /**
+     * Read and validate cache metadata for a package.
+     * Returns `null` if the package does not exist in the cache.
+     * throws Error if metadata is corrupt
+     */
+    getBundleMetadata(packageName: string): CacheMetadata | null;
+    /**
+     * Read and validate the MCPB manifest from a cached package.
+     * Returns `null` if the package is not cached (directory doesn't exist).
+     *
+     * @throws {MpakCacheCorruptedError} If the cache directory exists but
+     *   `manifest.json` is missing, contains invalid JSON, or fails schema validation.
+     */
+    getBundleManifest(packageName: string): McpbManifest | null;
+    /**
+     * Scan the cache directory and return metadata for every cached registry bundle.
+     * Skips the `_local/` directory (local dev bundles) and entries with
+     * missing/corrupt metadata or manifests.
+     */
+    listCachedBundles(): CachedBundleInfo[];
+    /**
+     * Remove a cached bundle from disk.
+     * @returns `true` if the bundle was cached and removed, `false` if it wasn't cached.
+     */
+    removeCachedBundle(packageName: string): boolean;
+    /**
+     * Load a bundle into the local cache, downloading from the registry only
+     * if the cache is missing or stale. Returns the cache directory and version.
      *
-     * @example
-     * ```typescript
-     * // Resolve from mpak registry
-     * const skill = await client.resolveSkillRef({
-     *   source: 'mpak',
-     *   name: '@nimblebraininc/folk-crm',
-     *   version: '1.3.0',
-     * });
+     * Requires an `MpakClient` to be provided at construction time.
      *
-     * // Resolve from GitHub
-     * const skill = await client.resolveSkillRef({
-     *   source: 'github',
-     *   name: '@example/my-skill',
-     *   version: 'v1.0.0',
-     *   repo: 'owner/repo',
-     *   path: 'skills/my-skill/SKILL.md',
-     * });
+     * @param name - Scoped package name (e.g. `@scope/bundle`)
+     * @param options.version - Specific version to load. Omit for "latest".
+     * @param options.force - Skip cache checks and always re-download.
      *
-     * // Resolve from URL
-     * const skill = await client.resolveSkillRef({
-     *   source: 'url',
-     *   name: '@example/custom',
-     *   version: '1.0.0',
-     *   url: 'https://example.com/skill.md',
-     * });
-     * ```
-     */
-    resolveSkillRef(ref: SkillReference): Promise<ResolvedSkill>;
-    /**
-     * Resolve a skill from mpak registry
+     * @returns `cacheDir` — path to the extracted bundle on disk,
+     *          `version` — the resolved version string,
+     *          `pulled` — whether a download actually occurred.
      *
-     * The API returns a ZIP bundle containing SKILL.md and metadata.
+     * @throws If no `MpakClient` was provided at construction time.
      */
-    private resolveMpakSkill;
+    loadBundle(name: string, options?: {
+        version?: string;
+        force?: boolean;
+    }): Promise<{
+        cacheDir: string;
+        version: string;
+        pulled: boolean;
+    }>;
     /**
-     * Resolve a skill from GitHub releases
+     * Fire-and-forget background check for bundle updates.
+     * Return the latest version string if an update is available, null otherwise (not cached, skipped, up-to-date, or error).
+     * The caller can just check `if (result) { console.log("update available: " + result) }`
+     * @param packageName - Scoped package name (e.g. `@scope/bundle`)
      */
-    private resolveGithubSkill;
+    checkForUpdate(packageName: string, options?: {
+        force?: boolean;
+    }): Promise<string | null>;
     /**
-     * Resolve a skill from a direct URL
+     * Write cache metadata for a package.
+     * @throws If the metadata fails schema validation.
      */
-    private resolveUrlSkill;
+    private writeCacheMetadata;
     /**
-     * Extract SKILL.md content from a skill bundle ZIP
+     * Download a bundle using pre-resolved download info, extract it into
+     * the cache, and write metadata.
      */
-    private extractSkillFromZip;
+    private downloadAndExtract;
+}
+
+/**
+ * Zod schema for per-package user configuration.
+ * Each key-value pair represents a user-supplied config value
+ * (e.g. API keys, workspace IDs) referenced via `${user_config.*}` in manifests.
+ */
+declare const PackageConfigSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/**
+ * Per-package user configuration — a string-to-string map of values
+ * that bundles reference via `${user_config.*}` placeholders.
+ */
+type PackageConfig = z.infer<typeof PackageConfigSchema>;
+/**
+ * Manages the mpak user configuration file (`config.json`).
+ *
+ * Handles:
+ * - **Registry URL** — custom registry endpoint with hardcoded default fallback
+ * - **Per-package config** — key-value pairs for `${user_config.*}` substitution
+ *
+ * The config is lazy-loaded on first access and cached in memory.
+ * The config directory is created lazily on first write — read-only usage
+ * never touches the filesystem.
+ * All writes are validated against the schema before flushing to disk
+ * with `0o600` permissions (owner read/write only).
+ *
+ * @example
+ * ```ts
+ * // Default: ~/.mpak/config.json
+ * const config = new MpakConfigManager();
+ *
+ * // Custom home and registry URL
+ * const config = new MpakConfigManager({ mpakHome: '/tmp/test-mpak', registryUrl: 'https://custom.registry.dev' });
+ *
+ * // Registry URL (config > default)
+ * config.getRegistryUrl();
+ *
+ * // Per-package user config for ${user_config.*} substitution
+ * config.setPackageConfigValue('@scope/bundle', 'api_key', 'sk-...');
+ * config.getPackageConfig('@scope/bundle'); // { api_key: 'sk-...' }
+ * ```
+ */
+interface MpakConfigManagerOptions {
+    mpakHome?: string;
+    registryUrl?: string;
+}
+declare class MpakConfigManager {
+    readonly mpakHome: string;
+    private configFile;
+    private config;
+    constructor(options?: MpakConfigManagerOptions);
     /**
-     * Verify content integrity and throw if mismatch (fail-closed)
+     * Resolve the registry URL with a 2-tier fallback:
+     * 1. Saved value in config file
+     * 2. Default: `https://registry.mpak.dev`
+     *
+     * @returns The resolved registry URL
      */
-    private verifyIntegrityOrThrow;
+    getRegistryUrl(): string;
     /**
-     * Extract hash from integrity string (removes prefix)
+     * Get all stored user config values for a package.
+     *
+     * @param packageName - Scoped package name (e.g. `@scope/bundle`)
+     * @returns The key-value map, or `undefined` if the package has no stored config
      */
-    private extractHash;
+    getPackageConfig(packageName: string): PackageConfig | undefined;
     /**
-     * Detect the current platform
+     * Store a user config value for a package. Creates the package entry if needed.
+     *
+     * @param packageName - Scoped package name (e.g. `@scope/bundle`)
+     * @param key - The config key (e.g. `api_key`)
+     * @param value - The value to store
      */
-    static detectPlatform(): Platform;
+    setPackageConfigValue(packageName: string, key: string, value: string): void;
     /**
-     * Compute SHA256 hash of content
+     * Remove all stored config for a package.
+     *
+     * @param packageName - Scoped package name (e.g. `@scope/bundle`)
+     * @returns `true` if the package had config that was removed, `false` if it didn't exist
      */
-    private computeSha256;
+    clearPackageConfig(packageName: string): boolean;
     /**
-     * Validate that a name is scoped (@scope/name)
+     * Remove a single config value for a package. If this was the last key,
+     * the package entry is cleaned up entirely.
+     *
+     * @param packageName - Scoped package name (e.g. `@scope/bundle`)
+     * @param key - The config key to remove
+     * @returns `true` if the key existed and was removed, `false` otherwise
      */
-    private validateScopedName;
+    clearPackageConfigValue(packageName: string, key: string): boolean;
     /**
-     * Fetch with timeout support
+     * List all package names that have stored user config.
+     *
+     * @returns Array of scoped package names (e.g. `['@scope/pkg1', '@scope/pkg2']`)
      */
-    private fetchWithTimeout;
+    getPackageNames(): string[];
+    /**
+     * Load the config from disk, or create a fresh one if the file doesn't exist yet.
+     * The result is cached — subsequent calls return the in-memory copy without
+     * re-reading the file.
+     *
+     * @returns The validated config object
+     * @throws {MpakConfigCorruptedError} If the file exists but contains invalid JSON or fails schema validation
+     */
+    private loadConfig;
+    /**
+     * Read the config file from disk, parse JSON, and validate against the schema.
+     *
+     * @returns The validated config object
+     * @throws {MpakConfigCorruptedError} If the file can't be read, contains invalid JSON,
+     *   or doesn't match the expected schema
+     */
+    private readAndValidateConfig;
+    /**
+     * Flush the in-memory config to disk. Creates the config directory if needed,
+     * validates against the schema, updates `lastUpdated`, and writes
+     * with mode `0o600` (owner read/write only — config may contain secrets).
+     *
+     * @throws {MpakConfigCorruptedError} If the in-memory config fails schema validation
+     */
+    private saveConfig;
+    /**
+     * Persist a custom registry URL to the config file.
+     *
+     * @param url - The registry URL to save (e.g. `https://registry.example.com`)
+     */
+    private setRegistryUrl;
+}
+
+/**
+ * Options for the {@link Mpak} facade.
+ *
+ * All fields are optional — sensible defaults are derived from
+ * `MpakConfigManager` (registry URL, mpakHome) when omitted.
+ */
+interface MpakOptions {
+    /** Root directory for mpak state. Defaults to `~/.mpak`. */
+    mpakHome?: string;
+    /** Registry URL override. Defaults to `MpakConfigManager.getRegistryUrl()`. */
+    registryUrl?: string;
+    /** Request timeout in milliseconds for the client. */
+    timeout?: number;
+    /** User-Agent string sent with every request. */
+    userAgent?: string;
+}
+/**
+ * Specifies which bundle to prepare.
+ *
+ * - `{ name, version? }` — registry bundle. Omit `version` for "latest".
+ * - `{ local }` — a local `.mcpb` file on disk. The caller is responsible for
+ *   validating that the path exists and has a `.mcpb` extension before calling.
+ */
+type PrepareServerSpec = {
+    name: string;
+    version?: string;
+} | {
+    local: string;
+};
+/**
+ * Options for {@link Mpak.prepareServer}.
+ */
+interface PrepareServerOptions {
+    /** Skip cache and re-download/re-extract. */
+    force?: boolean;
+    /** Extra environment variables merged on top of the manifest env. */
+    env?: Record<string, string>;
+    /**
+     * Directory for `MPAK_WORKSPACE` — where stateful bundles write
+     * project-local data (databases, logs, etc.). Defaults to `process.cwd()/.mpak`.
+     */
+    workspaceDir?: string;
+}
+/**
+ * Fully resolved server configuration, ready to spawn.
+ */
+interface ServerCommand {
+    /** The executable command (e.g. `"node"`, `"python3"`, or an absolute binary path). */
+    command: string;
+    /** Arguments to pass to the command. */
+    args: string[];
+    /** Environment variables (manifest env + user config substitutions + caller overrides). */
+    env: Record<string, string>;
+    /** Working directory for the spawned process — the extracted bundle's cache directory. */
+    cwd: string;
+    /** The resolved package name. */
+    name: string;
+    /** The resolved version string. */
+    version: string;
+}
+/**
+ * Top-level facade that wires together the SDK's core components:
+ * `MpakConfigManager`, `MpakClient`, and `BundleCache`.
+ *
+ * Provides a single entry point for the common setup pattern,
+ * while still exposing each component for direct use.
+ *
+ * @example
+ * ```ts
+ * import { MpakSDK } from '@nimblebrain/mpak-sdk';
+ *
+ * const mpak = new MpakSDK();
+ *
+ * // Prepare a server for spawning
+ * const server = await mpak.prepareServer('@scope/pkg');
+ * const child = spawn(server.command, server.args, {
+ *   env: { ...server.env, ...process.env },
+ *   cwd: server.cwd,
+ *   stdio: 'inherit',
+ * });
+ *
+ * // Access components directly
+ * mpak.config.setPackageConfigValue('@scope/pkg', 'api_key', 'sk-...');
+ * const bundles = await mpak.client.searchBundles({ q: 'mcp' });
+ * ```
+ */
+declare class Mpak {
+    /** User configuration manager (`config.json`). */
+    readonly configManager: MpakConfigManager;
+    /** Registry API client. */
+    readonly client: MpakClient;
+    /** Local bundle cache. */
+    readonly bundleCache: MpakBundleCache;
+    constructor(options?: MpakOptions);
+    /**
+     * Prepare a bundle for execution.
+     *
+     * Accepts either a registry spec (`{ name, version? }`) or a local bundle
+     * spec (`{ local }`). Downloads/extracts as needed, reads the manifest,
+     * validates user config, and resolves the command, args, and env needed
+     * to spawn the MCP server process.
+     *
+     * @param spec - Which bundle to prepare. See {@link PrepareServerSpec}.
+     * @param options - Force re-download/re-extract, extra env, and workspace dir.
+     *
+     * @throws {MpakConfigError} If required user config values are missing.
+     * @throws {MpakCacheCorruptedError} If the manifest is missing or corrupt after download.
+     */
+    prepareServer(spec: PrepareServerSpec, options?: PrepareServerOptions): Promise<ServerCommand>;
+    /**
+     * Load a registry bundle into cache and read its manifest.
+     */
+    private prepareRegistryBundle;
+    /**
+     * Extract a local `.mcpb` bundle (if stale) and read its manifest.
+     * Local bundles are cached under `<cacheHome>/_local/<hash>`.
+     *
+     * The caller is responsible for validating that `bundlePath` exists
+     * and has a `.mcpb` extension before calling this method.
+     */
+    private prepareLocalBundle;
+    /**
+     * Gather stored user config values and validate that all required fields are present.
+     * @throws If required config values are missing.
+     */
+    private gatherUserConfig;
+    /**
+     * Resolve the manifest's `server` block into a spawnable command, args, and env.
+     *
+     * Handles three server types:
+     * - **binary** — runs the compiled executable at `entry_point`, chmod'd +x.
+     * - **node** — runs `mcp_config.command` (default `"node"`) with `mcp_config.args`,
+     *   or falls back to `node <entry_point>` when args are empty.
+     * - **python** — like node, but resolves `python3`/`python` at runtime and
+     *   prepends `<cacheDir>/deps` to `PYTHONPATH` for bundled dependencies.
+     *
+     * All `${__dirname}` placeholders in args are replaced with `cacheDir`.
+     * All `${user_config.*}` placeholders in env are replaced with gathered user values.
+     *
+     * @throws For unsupported server types.
+     */
+    private resolveCommand;
+    /**
+     * Substitute `${__dirname}` placeholders in args.
+     */
+    private static resolveArgs;
+    /**
+     * Substitute `${user_config.*}` placeholders in env vars.
+     */
+    private static substituteEnvVars;
+    /**
+     * Find a working Python executable. Tries `python3` first, falls back to `python`.
+     */
+    private static findPythonCommand;
 }
 
+/**
+ * Parse a scoped package spec (`@scope/name` or `@scope/name@version`)
+ * into its name and optional version components.
+ *
+ * @throws {MpakError} If the spec is not a valid scoped package name.
+ *
+ * @example
+ * parsePackageSpec('@scope/name')        // { name: '@scope/name' }
+ * parsePackageSpec('@scope/name@1.0.0')  // { name: '@scope/name', version: '1.0.0' }
+ */
+declare function parsePackageSpec(spec: string): {
+    name: string;
+    version?: string;
+};
+
 /**
  * Base error class for mpak SDK errors
  */
@@ -288,5 +555,63 @@ declare class MpakIntegrityError extends MpakError {
 declare class MpakNetworkError extends MpakError {
     constructor(message: string);
 }
+/**
+ * Thrown when the config file cannot be read, parsed, or validated.
+ *
+ * @param message - Human-readable description of what went wrong
+ * @param configPath - Absolute path to the config file that failed
+ * @param cause - The underlying error (parse failure, read error, etc.)
+ */
+declare class MpakConfigCorruptedError extends MpakError {
+    readonly configPath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, configPath: string, cause?: Error | undefined);
+}
+/**
+ * Thrown when required user config fields are missing for a package.
+ *
+ * @param packageName - The package that requires config
+ * @param missingFields - Structured list of missing fields
+ */
+/**
+ * Thrown when cache metadata or manifest is missing, corrupt, or fails validation.
+ *
+ * @param message - Human-readable description of what went wrong
+ * @param filePath - Absolute path to the file that failed
+ * @param cause - The underlying error (parse failure, validation error, etc.)
+ */
+declare class MpakCacheCorruptedError extends MpakError {
+    readonly filePath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, filePath: string, cause?: Error | undefined);
+}
+/**
+ * Thrown when a local `.mcpb` bundle is invalid — e.g. manifest is missing,
+ * contains invalid JSON, or fails schema validation.
+ *
+ * @param message - Human-readable description of what went wrong
+ * @param bundlePath - Absolute path to the `.mcpb` file
+ * @param cause - The underlying error
+ */
+declare class MpakInvalidBundleError extends MpakError {
+    readonly bundlePath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, bundlePath: string, cause?: Error | undefined);
+}
+declare class MpakConfigError extends MpakError {
+    readonly packageName: string;
+    readonly missingFields: Array<{
+        key: string;
+        title: string;
+        description?: string;
+        sensitive: boolean;
+    }>;
+    constructor(packageName: string, missingFields: Array<{
+        key: string;
+        title: string;
+        description?: string;
+        sensitive: boolean;
+    }>);
+}
 
-export { type Author, type BundleArtifact, type BundleDownloadInfo, type BundleSearchParams, type BundleVersion, type GithubSkillReference, MpakClient, type MpakClientConfig, MpakError, MpakIntegrityError, MpakNetworkError, MpakNotFoundError, type MpakSkillReference, type Platform, type Provenance, type ResolvedSkill, type Skill, type SkillReference, type SkillSearchParams, type SkillVersion, type UrlSkillReference };
+export { Mpak, MpakBundleCache, type MpakBundleCacheOptions, MpakCacheCorruptedError, MpakClient, type MpakClientConfig, MpakConfigCorruptedError, MpakConfigError, MpakConfigManager, type MpakConfigManagerOptions, MpakError, MpakIntegrityError, MpakInvalidBundleError, MpakNetworkError, MpakNotFoundError, type MpakOptions, type PackageConfig, type PrepareServerOptions, type PrepareServerSpec, type ServerCommand, parsePackageSpec };