Move bundle runtime, config, and cache from CLI to SDK (#59)

[shwetank-dev]

Summary

• Stage 1: Clean up SDK exports — remove type aliases, use schema types directly. Consumers import response types from @nimblebrain/mpak-schemas.
• Stage 2: Add ConfigManager class to SDK — manages ~/.mpak/config.json with per-package user config, registry URL, and file permissions.
• Stage 3: Add BundleCache class and MpakSDK facade — local cache management (loadBundle, checkForUpdateAsync, extractZip), plus a top-level facade wiring config, client, and cache together.
• Stage 4: Add prepareServer and parsePackageSpec to MpakSDK — resolves a registry bundle into a ready-to-spawn ServerCommand (command, args, env, cwd). Handles node/python/binary server types, user config substitution, and manifest validation via Zod schema. Narrows public exports to facade + types + errors only.

Stages 5 (update CLI to import from SDK) and 6 (adopt Biome) are planned as follow-ups.

Key design decisions

• MpakSDK facade is the primary entry point — internal classes (MpakClient, ConfigManager, BundleCache) are accessed via mpak.client, mpak.config, mpak.cache
• prepareServer returns a ServerCommand (command/args/env/cwd) rather than spawning — consumers control process lifecycle
• parsePackageSpec is a public static method that validates scoped @scope/name[@version] format
• --local bundle handling stays in CLI — it's a CLI-only developer workflow, not an SDK concern
• Missing required user config throws — SDK validates, CLI catches and handles interactive prompting

Test plan

• 171 unit tests pass (pnpm --filter @nimblebrain/mpak-sdk test)
• 31 integration tests pass against live registry (pnpm --filter @nimblebrain/mpak-sdk test:integration)
• Typecheck passes (pnpm --filter @nimblebrain/mpak-sdk typecheck)
• Verify README accurately documents all public methods
• Review manifest Zod schema against MCPB v0.3 spec

🤖 Generated with Claude Code

[shwetank-dev]

@mgoldsborough Claude on why no run in the SDK

1. Flexibility — different consumers want different spawn behavior.
   The CLI wants stdio: 'inherit' (transparent passthrough). A
   programmatic consumer might want stdio: 'pipe' to read/write MCP
   JSON-RPC messages. Someone else might want to run it in Docker. If
   the SDK spawns, it has to either pick one or expose a growing set of
   options.
2. Process lifecycle is the caller's concern — signal forwarding,
   exit handling, restart logic, timeouts. The CLI does
   process.on('SIGINT', () => child.kill('SIGINT')) and
   child.on('exit', (code) => process.exit(code)). Other consumers
   would handle this differently. The SDK shouldn't own any of that.
3. The hard part is resolution, not spawning — downloading, caching,
   manifest parsing, config validation, command resolution across
   node/python/binary types — that's what takes work. The actual
   spawn(command, args, { env, cwd }) call is one line. The SDK does
   the complex part, the consumer does the trivial part.

[mgoldsborough]

Solid foundation - a few things before merge:

The facade design is right. prepareServer → ServerCommand is exactly the interface both consumers need. Three things to address:

1. Export the components from index.ts

Right now only MpakSDK is exported. The CLI needs ConfigManager standalone (for config set), MpakClient standalone (for search), BundleCache standalone (for outdated). Export all three classes plus their public types (CachedBundle, PackageConfig, MpakConfig, ConfigCorruptedError). The facade is the recommended path, not the only path.

Ideal Public API Surface

// ─── Facade (80% use case) ───
export { MpakSDK } from './MpakSDK.js';                                                                                           
export type { MpakSDKOptions, PrepareServerOptions, ServerCommand } from './MpakSDK.js';                                          
                                                                                                                                    
// ─── Components (advanced / CLI use) ───                                                                                        
export { MpakClient } from './client.js';                                                                                         
export { BundleCache } from './cache.js';                                                                                         
export { ConfigManager } from './config-manager.js';
                                                                                                                                    
// ─── Utilities ───                                                                                                              
export { parsePackageSpec } from './utils.js';
                                                                                                                                    
// ─── Types ───                                                
export type { MpakClientConfig, BundleSearchParams, SkillSearchParams } from './types.js';
export type { McpbManifest, UserConfigField, CachedBundle } from './cache.js';
export type { MpakConfig, PackageConfig } from './config-manager.js';

// ─── Errors (all typed, all catchable) ───
export {
  MpakError,
  MpakNotFoundError,
  MpakIntegrityError,
  MpakNetworkError,
  MpakConfigError,       // NEW: missing credentials, carries structured field list
  MpakManifestError,     // NEW: corrupt/missing manifest                                                                         
  ConfigCorruptedError,  // EXISTS but not exported                                                                               
} from './errors.js';                                        

2. Typed error for missing credentials

prepareServer throws a bare Error with a formatted string when required config is missing. The CLI needs to catch this, figure out which fields are missing, prompt for them, and retry. An agent consumer needs the same structured data for vault lookups. Add a MpakConfigError that carries packageName and a missingFields array (key, title, sensitive). Same treatment for the other bare Error throws (manifest missing, unsupported server type) — use MpakError subclasses so consumers can instanceof instead of string-matching.

3. parsePackageSpec as a standalone export

It's duplicated in run.ts, pull.ts, and as a static method on MpakSDK. It's a pure string function — export it from index.ts directly. Every CLI command needs it and shouldn't have to import the facade class to get it.

None of this changes the architecture. This is about surfacing what's already there and making the error contract reliable for programmatic consumers.

[mgoldsborough]

BundleCache.downloadAndExtract and MpakClient.fetchWithTimeout both call global fetch directly. Every test that touches downloads or registry calls will need to mock the global, which bleeds between tests. Accept an optional fetch function in the constructor options now. Retrofitting it later is a breaking change to the public API.

[mgoldsborough]

Other items to consider:

• Move ensureConfigDir() from constructor to first write — mpak search shouldn't mkdir ~/.mpak/
• Local .mcpb support in prepareServer (the ~90 lines in run.ts are pure logic with no TTY deps — they belong in the SDK)
• CachedBundle interface isn't exported from cache.ts

[mgoldsborough]

The SDK has zero test files. This is the shared foundation for both CLI and agent — it needs coverage before merge. The CLI already has a thorough config-manager.test.ts (~450 lines) that should move with the code. prepareServer needs at minimum: cache-hit, cache-miss, and missing-credentials paths covered. BundleCache.loadBundle needs: fresh download, cached version match, and force-redownload.

[shwetank-dev]

Re: injectable fetch

Good callout on testability. I looked into this and since Vitest isolates each test file in its own worker context, vi.stubGlobal scoped with afterEach cleanup gives solid isolation without cross-file bleed — so I'm comfortable with the testing story as-is.

On the API design side — injectable fetch is a nice pattern for things like proxy support or custom retry wrappers, but there's no concrete consumer need for it today. Since adding an optional fetch param to an options object is non-breaking, I can add it later when there's a real use case.

Happy to revisit if you feel strongly though.