@nimblebrain/mpak-sdk 0.1.2 → 0.2.0

package/dist/index.js

@@ -1,3 +1,16 @@
+// src/mpakSDK.ts
+import { spawnSync } from "child_process";
+import { chmodSync, existsSync as existsSync4, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4, resolve as resolve3 } from "path";
+import { McpbManifestSchema as McpbManifestSchema2 } from "@nimblebrain/mpak-schemas";
+
+// src/cache.ts
+import { randomUUID } from "crypto";
+import { existsSync as existsSync2, readdirSync, rmSync, writeFileSync } from "fs";
+import { homedir, tmpdir } from "os";
+import { join as join2 } from "path";
+import { CacheMetadataSchema, McpbManifestSchema } from "@nimblebrain/mpak-schemas";
+
 // src/client.ts
 import { createHash } from "crypto";
 
@@ -34,11 +47,44 @@ var MpakNetworkError = class extends MpakError {
     this.name = "MpakNetworkError";
   }
 };
+var MpakConfigCorruptedError = class extends MpakError {
+  constructor(message, configPath, cause) {
+    super(message, "CONFIG_CORRUPTED");
+    this.configPath = configPath;
+    this.cause = cause;
+    this.name = "MpakConfigCorruptedError";
+  }
+};
+var MpakCacheCorruptedError = class extends MpakError {
+  constructor(message, filePath, cause) {
+    super(message, "CACHE_CORRUPTED");
+    this.filePath = filePath;
+    this.cause = cause;
+    this.name = "MpakCacheCorruptedError";
+  }
+};
+var MpakInvalidBundleError = class extends MpakError {
+  constructor(message, bundlePath, cause) {
+    super(message, "INVALID_BUNDLE");
+    this.bundlePath = bundlePath;
+    this.cause = cause;
+    this.name = "MpakInvalidBundleError";
+  }
+};
+var MpakConfigError = class extends MpakError {
+  constructor(packageName, missingFields) {
+    const fieldNames = missingFields.map((f) => f.title).join(", ");
+    super(`Missing required config for ${packageName}: ${fieldNames}`, "CONFIG_MISSING");
+    this.packageName = packageName;
+    this.missingFields = missingFields;
+    this.name = "MpakConfigError";
+  }
+};
 
 // src/client.ts
 var DEFAULT_REGISTRY_URL = "https://registry.mpak.dev";
 var DEFAULT_TIMEOUT = 3e4;
-var MpakClient = class {
+var MpakClient = class _MpakClient {
   registryUrl;
   timeout;
   userAgent;
@@ -150,7 +196,6 @@ var MpakClient = class {
     if (params.q) searchParams.set("q", params.q);
     if (params.tags) searchParams.set("tags", params.tags);
     if (params.category) searchParams.set("category", params.category);
-    if (params.surface) searchParams.set("surface", params.surface);
     if (params.sort) searchParams.set("sort", params.sort);
     if (params.limit) searchParams.set("limit", String(params.limit));
     if (params.offset) searchParams.set("offset", String(params.offset));
@@ -214,179 +259,55 @@ var MpakClient = class {
     }
     return response.json();
   }
+  // ===========================================================================
+  // Download Methods
+  // ===========================================================================
   /**
-   * Download skill content and verify integrity
-   *
-   * @throws {MpakIntegrityError} If expectedSha256 is provided and doesn't match (fail-closed)
-   */
-  async downloadSkillContent(downloadUrl, expectedSha256) {
-    const response = await this.fetchWithTimeout(downloadUrl);
-    if (!response.ok) {
-      throw new MpakNetworkError(`Failed to download skill: HTTP ${response.status}`);
-    }
-    const content = await response.text();
-    if (expectedSha256) {
-      const actualHash = this.computeSha256(content);
-      if (actualHash !== expectedSha256) {
-        throw new MpakIntegrityError(expectedSha256, actualHash);
-      }
-      return { content, verified: true };
-    }
-    return { content, verified: false };
-  }
-  /**
-   * Resolve a skill reference to actual content
-   *
-   * Supports mpak, github, and url sources. This is the main method for
-   * fetching skill content from any supported source.
+   * Download content from a URL and verify its SHA-256 integrity.
    *
-   * @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
-   *
-   * @example
-   * ```typescript
-   * // Resolve from mpak registry
-   * const skill = await client.resolveSkillRef({
-   *   source: 'mpak',
-   *   name: '@nimblebraininc/folk-crm',
-   *   version: '1.3.0',
-   * });
-   *
-   * // 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',
-   * });
-   *
-   * // Resolve from URL
-   * const skill = await client.resolveSkillRef({
-   *   source: 'url',
-   *   name: '@example/custom',
-   *   version: '1.0.0',
-   *   url: 'https://example.com/skill.md',
-   * });
-   * ```
-   */
-  async resolveSkillRef(ref) {
-    switch (ref.source) {
-      case "mpak":
-        return this.resolveMpakSkill(ref);
-      case "github":
-        return this.resolveGithubSkill(ref);
-      case "url":
-        return this.resolveUrlSkill(ref);
-      default: {
-        const _exhaustive = ref;
-        throw new Error(`Unknown skill source: ${_exhaustive.source}`);
-      }
-    }
-  }
-  /**
-   * Resolve a skill from mpak registry
-   *
-   * The API returns a ZIP bundle containing SKILL.md and metadata.
-   */
-  async resolveMpakSkill(ref) {
-    const url = `${this.registryUrl}/v1/skills/${ref.name}/versions/${ref.version}/download`;
-    const response = await this.fetchWithTimeout(url);
-    if (response.status === 404) {
-      throw new MpakNotFoundError(`${ref.name}@${ref.version}`);
-    }
-    if (!response.ok) {
-      throw new MpakNetworkError(`Failed to fetch skill: HTTP ${response.status}`);
-    }
-    const zipBuffer = await response.arrayBuffer();
-    const content = await this.extractSkillFromZip(zipBuffer, ref.name);
-    if (ref.integrity) {
-      this.verifyIntegrityOrThrow(content, ref.integrity);
-      return { content, version: ref.version, source: "mpak", verified: true };
-    }
-    return { content, version: ref.version, source: "mpak", verified: false };
-  }
-  /**
-   * Resolve a skill from GitHub releases
    */
-  async resolveGithubSkill(ref) {
-    const url = `https://github.com/${ref.repo}/releases/download/${ref.version}/${ref.path}`;
+  async downloadContent(url, sha256) {
     const response = await this.fetchWithTimeout(url);
     if (!response.ok) {
-      throw new MpakNotFoundError(`github:${ref.repo}/${ref.path}@${ref.version}`);
-    }
-    const content = await response.text();
-    if (ref.integrity) {
-      this.verifyIntegrityOrThrow(content, ref.integrity);
-      return {
-        content,
-        version: ref.version,
-        source: "github",
-        verified: true
-      };
+      throw new MpakNetworkError(`Failed to download: HTTP ${response.status}`);
     }
-    return {
-      content,
-      version: ref.version,
-      source: "github",
-      verified: false
-    };
-  }
-  /**
-   * Resolve a skill from a direct URL
-   */
-  async resolveUrlSkill(ref) {
-    const response = await this.fetchWithTimeout(ref.url);
-    if (!response.ok) {
-      throw new MpakNotFoundError(`url:${ref.url}`);
-    }
-    const content = await response.text();
-    if (ref.integrity) {
-      this.verifyIntegrityOrThrow(content, ref.integrity);
-      return { content, version: ref.version, source: "url", verified: true };
+    const downloadedRawData = new Uint8Array(await response.arrayBuffer());
+    const computedHash = this.computeSha256(downloadedRawData);
+    if (computedHash !== sha256) {
+      throw new MpakIntegrityError(sha256, computedHash);
     }
-    return { content, version: ref.version, source: "url", verified: false };
+    return downloadedRawData;
   }
   /**
-   * Extract SKILL.md content from a skill bundle ZIP
-   */
-  async extractSkillFromZip(zipBuffer, skillName) {
-    const JSZip = (await import("jszip")).default;
-    const zip = await JSZip.loadAsync(zipBuffer);
-    const folderName = skillName.split("/").pop() ?? skillName;
-    const skillPath = `${folderName}/SKILL.md`;
-    const skillFile = zip.file(skillPath);
-    if (!skillFile) {
-      const altFile = zip.file("SKILL.md");
-      if (!altFile) {
-        throw new MpakNotFoundError(`SKILL.md not found in bundle for ${skillName}`);
-      }
-      return altFile.async("string");
-    }
-    return skillFile.async("string");
-  }
-  /**
-   * Verify content integrity and throw if mismatch (fail-closed)
+   * Download a bundle by name, with optional version and platform.
+   * Defaults to latest version and auto-detected platform.
+   *
+   * @throws {MpakNotFoundError} If bundle not found
+   * @throws {MpakIntegrityError} If SHA-256 doesn't match
+   * @throws {MpakNetworkError} For network failures
    */
-  verifyIntegrityOrThrow(content, integrity) {
-    const expectedHash = this.extractHash(integrity);
-    const actualHash = this.computeSha256(content);
-    if (actualHash !== expectedHash) {
-      throw new MpakIntegrityError(expectedHash, actualHash);
-    }
+  async downloadBundle(name, version, platform) {
+    const resolvedPlatform = platform ?? _MpakClient.detectPlatform();
+    const resolvedVersion = version ?? "latest";
+    const downloadInfo = await this.getBundleDownload(name, resolvedVersion, resolvedPlatform);
+    const data = await this.downloadContent(downloadInfo.url, downloadInfo.bundle.sha256);
+    return { data, metadata: downloadInfo.bundle };
   }
   /**
-   * Extract hash from integrity string (removes prefix)
+   * Download a skill bundle by name, with optional version.
+   * Defaults to latest version.
+   *
+   * @throws {MpakNotFoundError} If skill not found
+   * @throws {MpakIntegrityError} If SHA-256 doesn't match
+   * @throws {MpakNetworkError} For network failures
    */
-  extractHash(integrity) {
-    if (integrity.startsWith("sha256:")) {
-      return integrity.slice(7);
-    }
-    if (integrity.startsWith("sha256-")) {
-      return integrity.slice(7);
-    }
-    return integrity;
+  async downloadSkillBundle(name, version) {
+    const resolvedVersion = version ?? "latest";
+    const downloadInfo = await this.getSkillVersionDownload(name, resolvedVersion);
+    const data = await this.downloadContent(downloadInfo.url, downloadInfo.skill.sha256);
+    return { data, metadata: downloadInfo.skill };
   }
   // ===========================================================================
   // Utility Methods
@@ -428,14 +349,17 @@ var MpakClient = class {
    * Compute SHA256 hash of content
    */
   computeSha256(content) {
-    return createHash("sha256").update(content, "utf8").digest("hex");
+    return createHash("sha256").update(content).digest("hex");
   }
   /**
    * Validate that a name is scoped (@scope/name)
    */
   validateScopedName(name) {
     if (!name.startsWith("@")) {
-      throw new Error("Package name must be scoped (e.g., @scope/package-name)");
+      throw new MpakError(
+        "Package name must be scoped (e.g., @scope/package-name)",
+        "INVALID_SPEC"
+      );
     }
   }
   /**
@@ -468,11 +392,780 @@ var MpakClient = class {
     }
   }
 };
+
+// src/helpers.ts
+import { execFileSync } from "child_process";
+import { createHash as createHash2 } from "crypto";
+import { existsSync, mkdirSync, readFileSync, statSync } from "fs";
+import { resolve, join } from "path";
+var MAX_UNCOMPRESSED_SIZE = 500 * 1024 * 1024;
+var UPDATE_CHECK_TTL_MS = 60 * 60 * 1e3;
+function isSemverEqual(a, b) {
+  return a.replace(/^v/, "") === b.replace(/^v/, "");
+}
+function extractZip(zipPath, destDir) {
+  try {
+    const listOutput = execFileSync("unzip", ["-l", zipPath], {
+      stdio: "pipe",
+      encoding: "utf8"
+    });
+    const totalMatch = listOutput.match(/^\s*(\d+)\s+\d+\s+files?$/m);
+    if (totalMatch) {
+      const totalSize = parseInt(totalMatch[1] ?? "0", 10);
+      if (totalSize > MAX_UNCOMPRESSED_SIZE) {
+        throw new MpakCacheCorruptedError(
+          `Bundle uncompressed size (${Math.round(totalSize / 1024 / 1024)}MB) exceeds maximum allowed (${MAX_UNCOMPRESSED_SIZE / (1024 * 1024)}MB)`,
+          zipPath
+        );
+      }
+    }
+  } catch (error) {
+    if (error instanceof MpakCacheCorruptedError) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new MpakCacheCorruptedError(
+      `Cannot verify bundle size before extraction: ${message}`,
+      zipPath,
+      error instanceof Error ? error : void 0
+    );
+  }
+  mkdirSync(destDir, { recursive: true });
+  execFileSync("unzip", ["-o", "-q", zipPath, "-d", destDir], {
+    stdio: "pipe"
+  });
+}
+function hashBundlePath(bundlePath) {
+  return createHash2("md5").update(resolve(bundlePath)).digest("hex").slice(0, 12);
+}
+function localBundleNeedsExtract(bundlePath, cacheDir) {
+  const metaPath = join(cacheDir, ".mpak-local-meta.json");
+  if (!existsSync(metaPath)) return true;
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+    if (!meta.extractedAt) return true;
+    const bundleStat = statSync(bundlePath);
+    return bundleStat.mtimeMs > new Date(meta.extractedAt).getTime();
+  } catch {
+    return true;
+  }
+}
+function readJsonFromFile(filePath, schema) {
+  if (!existsSync(filePath)) {
+    throw new MpakError(`File does not exist: ${filePath}`, "FILE_NOT_FOUND");
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    throw new MpakError(`File is not valid JSON: ${filePath}`, "INVALID_JSON");
+  }
+  const result = schema.safeParse(raw);
+  if (!result.success) {
+    throw new MpakError(
+      `File failed validation: ${filePath} \u2014 ${result.error.issues[0]?.message ?? "unknown error"}`,
+      "VALIDATION_FAILED"
+    );
+  }
+  return result.data;
+}
+
+// src/cache.ts
+var MpakBundleCache = class {
+  cacheHome;
+  mpakClient;
+  constructor(client, options) {
+    this.mpakClient = client;
+    this.cacheHome = join2(options?.mpakHome ?? join2(homedir(), ".mpak"), "cache");
+  }
+  /**
+   * Compute the cache path for a package. Does not create the directory.
+   * @example getPackageCachePath('@scope/name') => '<cacheBase>/scope-name'
+   */
+  getBundleCacheDirName(packageName) {
+    const safeName = packageName.replace("@", "").replace("/", "-");
+    return join2(this.cacheHome, safeName);
+  }
+  /**
+   * 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) {
+    const packageCacheDir = this.getBundleCacheDirName(packageName);
+    if (!existsSync2(packageCacheDir)) {
+      return null;
+    }
+    const metaPath = join2(packageCacheDir, ".mpak-meta.json");
+    try {
+      return readJsonFromFile(metaPath, CacheMetadataSchema);
+    } catch (err) {
+      throw new MpakCacheCorruptedError(
+        err instanceof Error ? err.message : String(err),
+        metaPath,
+        err instanceof Error ? err : void 0
+      );
+    }
+  }
+  /**
+   * 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) {
+    const dir = this.getBundleCacheDirName(packageName);
+    if (!existsSync2(dir)) {
+      return null;
+    }
+    const manifestPath = join2(dir, "manifest.json");
+    try {
+      return readJsonFromFile(manifestPath, McpbManifestSchema);
+    } catch (err) {
+      throw new MpakCacheCorruptedError(
+        err instanceof Error ? err.message : String(err),
+        manifestPath,
+        err instanceof Error ? err : void 0
+      );
+    }
+  }
+  /**
+   * 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() {
+    if (!existsSync2(this.cacheHome)) return [];
+    const entries = readdirSync(this.cacheHome, { withFileTypes: true });
+    const bundles = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === "_local") continue;
+      const cacheDir = join2(this.cacheHome, entry.name);
+      try {
+        const manifest = readJsonFromFile(join2(cacheDir, "manifest.json"), McpbManifestSchema);
+        const meta = this.getBundleMetadata(manifest.name);
+        if (!meta) continue;
+        bundles.push({
+          name: manifest.name,
+          version: meta.version,
+          pulledAt: meta.pulledAt,
+          cacheDir
+        });
+      } catch {
+      }
+    }
+    return bundles;
+  }
+  /**
+   * Remove a cached bundle from disk.
+   * @returns `true` if the bundle was cached and removed, `false` if it wasn't cached.
+   */
+  removeCachedBundle(packageName) {
+    const dir = this.getBundleCacheDirName(packageName);
+    if (!existsSync2(dir)) return false;
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+  }
+  /**
+   * 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.
+   *
+   * Requires an `MpakClient` to be provided at construction time.
+   *
+   * @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.
+   *
+   * @returns `cacheDir` — path to the extracted bundle on disk,
+   *          `version` — the resolved version string,
+   *          `pulled` — whether a download actually occurred.
+   *
+   * @throws If no `MpakClient` was provided at construction time.
+   */
+  async loadBundle(name, options) {
+    const { version: requestedVersion, force = false } = options ?? {};
+    const cacheDir = this.getBundleCacheDirName(name);
+    let cachedMeta = null;
+    try {
+      cachedMeta = this.getBundleMetadata(name);
+    } catch {
+    }
+    if (!options?.force && !!cachedMeta && (!requestedVersion || isSemverEqual(cachedMeta.version, requestedVersion))) {
+      return { cacheDir, version: cachedMeta.version, pulled: false };
+    }
+    const platform = MpakClient.detectPlatform();
+    const downloadInfo = await this.mpakClient.getBundleDownload(
+      name,
+      requestedVersion ?? "latest",
+      platform
+    );
+    if (!force && cachedMeta && isSemverEqual(cachedMeta.version, downloadInfo.bundle.version)) {
+      this.writeCacheMetadata(name, {
+        ...cachedMeta,
+        lastCheckedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return { cacheDir, version: cachedMeta.version, pulled: false };
+    }
+    await this.downloadAndExtract(name, downloadInfo);
+    return { cacheDir, version: downloadInfo.bundle.version, pulled: true };
+  }
+  /**
+   * 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`)
+   */
+  async checkForUpdate(packageName, options) {
+    const cachedMeta = this.getBundleMetadata(packageName);
+    if (!cachedMeta) return null;
+    if (!options?.force && cachedMeta.lastCheckedAt) {
+      const elapsed = Date.now() - new Date(cachedMeta.lastCheckedAt).getTime();
+      if (elapsed < UPDATE_CHECK_TTL_MS) return null;
+    }
+    try {
+      const detail = await this.mpakClient.getBundle(packageName);
+      this.writeCacheMetadata(packageName, {
+        ...cachedMeta,
+        lastCheckedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (!isSemverEqual(detail.latest_version, cachedMeta.version)) {
+        return detail.latest_version;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  // ===========================================================================
+  // Private methods
+  // ===========================================================================
+  /**
+   * Write cache metadata for a package.
+   * @throws If the metadata fails schema validation.
+   */
+  writeCacheMetadata(packageName, metadata) {
+    const metaPath = join2(this.getBundleCacheDirName(packageName), ".mpak-meta.json");
+    writeFileSync(metaPath, JSON.stringify(metadata, null, 2));
+  }
+  /**
+   * Download a bundle using pre-resolved download info, extract it into
+   * the cache, and write metadata.
+   */
+  async downloadAndExtract(name, downloadInfo) {
+    const bundle = downloadInfo.bundle;
+    const cacheDir = this.getBundleCacheDirName(name);
+    const tempPath = join2(tmpdir(), `mpak-${Date.now()}-${randomUUID().slice(0, 8)}.mcpb`);
+    try {
+      const data = await this.mpakClient.downloadContent(downloadInfo.url, bundle.sha256);
+      writeFileSync(tempPath, data);
+      if (existsSync2(cacheDir)) {
+        rmSync(cacheDir, { recursive: true, force: true });
+      }
+      extractZip(tempPath, cacheDir);
+      this.writeCacheMetadata(name, {
+        version: bundle.version,
+        pulledAt: (/* @__PURE__ */ new Date()).toISOString(),
+        platform: bundle.platform
+      });
+    } finally {
+      rmSync(tempPath, { force: true });
+    }
+  }
+};
+
+// src/config-manager.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join3, resolve as resolve2 } from "path";
+import { z } from "zod";
+var CONFIG_VERSION = "1.0.0";
+var PackageConfigSchema = z.record(z.string(), z.string());
+var MpakConfigSchema = z.object({
+  version: z.string(),
+  lastUpdated: z.string(),
+  registryUrl: z.string().optional(),
+  packages: z.record(z.string(), PackageConfigSchema).optional()
+}).strict();
+var MpakConfigManager = class {
+  mpakHome;
+  configFile;
+  config = null;
+  constructor(options) {
+    this.mpakHome = resolve2(options?.mpakHome ?? join3(homedir2(), ".mpak"));
+    this.configFile = join3(this.mpakHome, "config.json");
+    if (options?.registryUrl !== void 0) {
+      this.setRegistryUrl(options.registryUrl);
+    }
+  }
+  // ===========================================================================
+  // Public methods
+  // ===========================================================================
+  /**
+   * 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
+   */
+  getRegistryUrl() {
+    const config = this.loadConfig();
+    return config.registryUrl || "https://registry.mpak.dev";
+  }
+  /**
+   * 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
+   */
+  getPackageConfig(packageName) {
+    const config = this.loadConfig();
+    return config.packages?.[packageName];
+  }
+  /**
+   * 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
+   */
+  setPackageConfigValue(packageName, key, value) {
+    const config = this.loadConfig();
+    if (!config.packages) {
+      config.packages = {};
+    }
+    if (!config.packages[packageName]) {
+      config.packages[packageName] = {};
+    }
+    config.packages[packageName][key] = value;
+    this.saveConfig();
+  }
+  /**
+   * 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
+   */
+  clearPackageConfig(packageName) {
+    const config = this.loadConfig();
+    if (config.packages?.[packageName]) {
+      delete config.packages[packageName];
+      this.saveConfig();
+      return true;
+    }
+    return false;
+  }
+  /**
+   * 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
+   */
+  clearPackageConfigValue(packageName, key) {
+    const config = this.loadConfig();
+    if (config.packages?.[packageName]?.[key] !== void 0) {
+      delete config.packages[packageName][key];
+      if (Object.keys(config.packages[packageName]).length === 0) {
+        delete config.packages[packageName];
+      }
+      this.saveConfig();
+      return true;
+    }
+    return false;
+  }
+  /**
+   * List all package names that have stored user config.
+   *
+   * @returns Array of scoped package names (e.g. `['@scope/pkg1', '@scope/pkg2']`)
+   */
+  getPackageNames() {
+    const config = this.loadConfig();
+    return Object.keys(config.packages || {});
+  }
+  // ===========================================================================
+  // Private methods
+  // ===========================================================================
+  /**
+   * 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
+   */
+  loadConfig() {
+    if (this.config) {
+      return this.config;
+    }
+    if (!existsSync3(this.configFile)) {
+      this.config = {
+        version: CONFIG_VERSION,
+        lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      return this.config;
+    }
+    this.config = this.readAndValidateConfig();
+    return this.config;
+  }
+  /**
+   * 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
+   */
+  readAndValidateConfig() {
+    let configJson;
+    try {
+      configJson = readFileSync2(this.configFile, "utf8");
+    } catch (err) {
+      throw new MpakConfigCorruptedError(
+        `Failed to read config file: ${err instanceof Error ? err.message : String(err)}`,
+        this.configFile,
+        err instanceof Error ? err : void 0
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(configJson);
+    } catch (err) {
+      throw new MpakConfigCorruptedError(
+        `Config file contains invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        this.configFile,
+        err instanceof Error ? err : void 0
+      );
+    }
+    const result = MpakConfigSchema.safeParse(parsed);
+    if (!result.success) {
+      const message = result.error.issues[0]?.message ?? "Invalid config";
+      throw new MpakConfigCorruptedError(message, this.configFile);
+    }
+    return result.data;
+  }
+  /**
+   * 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
+   */
+  saveConfig() {
+    if (!this.config) {
+      throw new MpakConfigCorruptedError(
+        `saveConfig called before config was loaded`,
+        this.configFile
+      );
+    }
+    if (!existsSync3(this.mpakHome)) {
+      mkdirSync2(this.mpakHome, { recursive: true, mode: 448 });
+    }
+    this.config.lastUpdated = (/* @__PURE__ */ new Date()).toISOString();
+    const result = MpakConfigSchema.safeParse(this.config);
+    if (!result.success) {
+      const message = result.error.issues[0]?.message ?? "Invalid config";
+      throw new MpakConfigCorruptedError(message, this.configFile);
+    }
+    const configJson = JSON.stringify(result.data, null, 2);
+    writeFileSync2(this.configFile, configJson, { mode: 384 });
+  }
+  /**
+   * Persist a custom registry URL to the config file.
+   *
+   * @param url - The registry URL to save (e.g. `https://registry.example.com`)
+   */
+  setRegistryUrl(url) {
+    const config = this.loadConfig();
+    config.registryUrl = url;
+    this.saveConfig();
+  }
+};
+
+// src/mpakSDK.ts
+var Mpak = class _Mpak {
+  /** User configuration manager (`config.json`). */
+  configManager;
+  /** Registry API client. */
+  client;
+  /** Local bundle cache. */
+  bundleCache;
+  constructor(options) {
+    const configOptions = {};
+    if (options?.mpakHome !== void 0) configOptions.mpakHome = options.mpakHome;
+    if (options?.registryUrl !== void 0) configOptions.registryUrl = options.registryUrl;
+    this.configManager = new MpakConfigManager(configOptions);
+    const clientConfig = {
+      registryUrl: this.configManager.getRegistryUrl()
+    };
+    if (options?.timeout !== void 0) clientConfig.timeout = options.timeout;
+    if (options?.userAgent !== void 0) clientConfig.userAgent = options.userAgent;
+    this.client = new MpakClient(clientConfig);
+    this.bundleCache = new MpakBundleCache(this.client, {
+      mpakHome: this.configManager.mpakHome
+    });
+  }
+  /**
+   * 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.
+   */
+  async prepareServer(spec, options) {
+    let cacheDir;
+    let name;
+    let version;
+    let manifest;
+    if ("local" in spec) {
+      ({ cacheDir, name, version, manifest } = await this.prepareLocalBundle(spec.local, options));
+    } else {
+      ({ cacheDir, name, version, manifest } = await this.prepareRegistryBundle(
+        spec.name,
+        spec.version,
+        options
+      ));
+    }
+    const userConfigValues = this.gatherUserConfig(name, manifest);
+    const { command, args, env } = this.resolveCommand(manifest, cacheDir, userConfigValues);
+    env["MPAK_WORKSPACE"] = options?.workspaceDir ?? join4(process.cwd(), ".mpak");
+    if (options?.env) {
+      Object.assign(env, options.env);
+    }
+    return { command, args, env, cwd: cacheDir, name, version };
+  }
+  // ===========================================================================
+  // Private helpers
+  // ===========================================================================
+  /**
+   * Load a registry bundle into cache and read its manifest.
+   */
+  async prepareRegistryBundle(packageName, version, options) {
+    const loadOptions = {};
+    if (version !== void 0) loadOptions.version = version;
+    if (options?.force !== void 0) loadOptions.force = options.force;
+    const loadResult = await this.bundleCache.loadBundle(packageName, loadOptions);
+    const manifest = this.bundleCache.getBundleManifest(packageName);
+    if (!manifest) {
+      throw new MpakCacheCorruptedError(
+        `Manifest file missing for ${packageName}`,
+        join4(this.bundleCache.cacheHome, packageName)
+      );
+    }
+    return {
+      cacheDir: loadResult.cacheDir,
+      name: packageName,
+      version: loadResult.version,
+      manifest
+    };
+  }
+  /**
+   * 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.
+   */
+  async prepareLocalBundle(bundlePath, options) {
+    const absolutePath = resolve3(bundlePath);
+    const hash = hashBundlePath(absolutePath);
+    const cacheDir = join4(this.bundleCache.cacheHome, "_local", hash);
+    const needsExtract = options?.force || localBundleNeedsExtract(absolutePath, cacheDir);
+    if (needsExtract) {
+      if (existsSync4(cacheDir)) {
+        rmSync2(cacheDir, { recursive: true, force: true });
+      }
+      try {
+        extractZip(absolutePath, cacheDir);
+      } catch (err) {
+        throw new MpakInvalidBundleError(
+          err instanceof Error ? err.message : String(err),
+          absolutePath,
+          err instanceof Error ? err : void 0
+        );
+      }
+      writeFileSync3(
+        join4(cacheDir, ".mpak-local-meta.json"),
+        JSON.stringify({
+          localPath: absolutePath,
+          extractedAt: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+    }
+    let manifest;
+    try {
+      manifest = readJsonFromFile(join4(cacheDir, "manifest.json"), McpbManifestSchema2);
+    } catch (err) {
+      throw new MpakInvalidBundleError(
+        err instanceof Error ? err.message : String(err),
+        absolutePath,
+        err instanceof Error ? err : void 0
+      );
+    }
+    return { cacheDir, name: manifest.name, version: manifest.version, manifest };
+  }
+  /**
+   * Gather stored user config values and validate that all required fields are present.
+   * @throws If required config values are missing.
+   */
+  gatherUserConfig(packageName, manifest) {
+    if (!manifest.user_config || Object.keys(manifest.user_config).length === 0) {
+      return {};
+    }
+    const storedConfig = this.configManager.getPackageConfig(packageName) ?? {};
+    const result = {};
+    const missingFields = [];
+    for (const [fieldName, fieldData] of Object.entries(manifest.user_config)) {
+      const storedValue = storedConfig[fieldName];
+      if (storedValue !== void 0) {
+        result[fieldName] = storedValue;
+      } else if (fieldData.default !== void 0 && fieldData.default !== null) {
+        result[fieldName] = String(fieldData.default);
+      } else if (fieldData.required) {
+        const field = {
+          key: fieldName,
+          title: fieldData.title ?? fieldName,
+          sensitive: fieldData.sensitive ?? false
+        };
+        if (fieldData.description !== void 0) {
+          field.description = fieldData.description;
+        }
+        missingFields.push(field);
+      }
+    }
+    if (missingFields.length > 0) {
+      throw new MpakConfigError(packageName, missingFields);
+    }
+    return result;
+  }
+  /**
+   * 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.
+   */
+  resolveCommand(manifest, cacheDir, userConfigValues) {
+    const { type, entry_point, mcp_config } = manifest.server;
+    const env = _Mpak.substituteEnvVars(mcp_config.env, userConfigValues);
+    let command;
+    let args;
+    switch (type) {
+      case "binary": {
+        command = join4(cacheDir, entry_point);
+        args = _Mpak.resolveArgs(mcp_config.args ?? [], cacheDir);
+        try {
+          chmodSync(command, 493);
+        } catch {
+        }
+        break;
+      }
+      case "node": {
+        command = mcp_config.command || "node";
+        args = mcp_config.args.length > 0 ? _Mpak.resolveArgs(mcp_config.args, cacheDir) : [join4(cacheDir, entry_point)];
+        break;
+      }
+      case "python": {
+        command = mcp_config.command === "python" ? _Mpak.findPythonCommand() : mcp_config.command || _Mpak.findPythonCommand();
+        args = mcp_config.args.length > 0 ? _Mpak.resolveArgs(mcp_config.args, cacheDir) : [join4(cacheDir, entry_point)];
+        const depsDir = join4(cacheDir, "deps");
+        env["PYTHONPATH"] = env["PYTHONPATH"] ? `${depsDir}:${env["PYTHONPATH"]}` : depsDir;
+        break;
+      }
+      case "uv": {
+        command = mcp_config.command || "uv";
+        args = mcp_config.args.length > 0 ? _Mpak.resolveArgs(mcp_config.args, cacheDir) : ["run", join4(cacheDir, entry_point)];
+        break;
+      }
+      default: {
+        const _exhaustive = type;
+        throw new MpakCacheCorruptedError(
+          `Unsupported server type "${_exhaustive}" in manifest for ${manifest.name}`,
+          cacheDir
+        );
+      }
+    }
+    return { command, args, env };
+  }
+  /**
+   * Substitute `${__dirname}` placeholders in args.
+   */
+  static resolveArgs(args, cacheDir) {
+    return args.map((arg) => arg.replace(/\$\{__dirname\}/g, cacheDir));
+  }
+  /**
+   * Substitute `${user_config.*}` placeholders in env vars.
+   */
+  static substituteEnvVars(env, userConfigValues) {
+    if (!env) return {};
+    const result = {};
+    for (const [key, value] of Object.entries(env)) {
+      result[key] = value.replace(
+        /\$\{user_config\.([^}]+)\}/g,
+        (match, configKey) => userConfigValues[configKey] ?? match
+      );
+    }
+    return result;
+  }
+  /**
+   * Find a working Python executable. Tries `python3` first, falls back to `python`.
+   */
+  static findPythonCommand() {
+    const result = spawnSync("python3", ["--version"], { stdio: "pipe" });
+    if (result.status === 0) {
+      return "python3";
+    }
+    return "python";
+  }
+};
+
+// src/utils.ts
+function parsePackageSpec(spec) {
+  const lastAtIndex = spec.lastIndexOf("@");
+  let name;
+  let version;
+  if (lastAtIndex > 0) {
+    name = spec.substring(0, lastAtIndex);
+    version = spec.substring(lastAtIndex + 1);
+  } else {
+    name = spec;
+  }
+  if (!name.startsWith("@") || !name.includes("/")) {
+    throw new MpakError(
+      `Invalid package spec: "${spec}". Expected scoped format: @scope/name`,
+      "INVALID_SPEC"
+    );
+  }
+  return version ? { name, version } : { name };
+}
 export {
+  Mpak,
+  MpakBundleCache,
+  MpakCacheCorruptedError,
   MpakClient,
+  MpakConfigCorruptedError,
+  MpakConfigError,
+  MpakConfigManager,
   MpakError,
   MpakIntegrityError,
+  MpakInvalidBundleError,
   MpakNetworkError,
-  MpakNotFoundError
+  MpakNotFoundError,
+  parsePackageSpec
 };
 //# sourceMappingURL=index.js.map