Move bundle runtime, config, and cache functions from CLI to SDK

Open
#59 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Stale
Tech stack
node.js, typescript

Research direction

Read packages/cli/src/commands/packages/run.ts, packages/cli/src/utils/config-manager.ts, and packages/cli/src/utils/cache.ts, then inspect the SDK exports in packages/sdk-typescript/src/index.ts. Move the listed runtime, config, and cache functions into the SDK and update CLI imports. Done means the SDK exports them, the CLI uses those exports, and the monorepo typecheck and tests pass.

Written by the indexing model from the issue text.

Description

Summary

NimbleBrain Platform needs to import mpak's bundle resolution, config management, and cache functions as a library — not shell out to the mpak CLI. Currently these functions live in packages/cli/ but they're pure logic with no CLI-specific dependencies (no readline prompts, no console formatting). They should move to packages/sdk-typescript/ so any TypeScript consumer (NimbleBrain, future integrations) can use them directly.

Motivation

NimbleBrain's agent runtime currently does Bun.spawn(["mpak", "run", name]) and Bun.spawn(["mpak", "search", query, "--json"]) to interact with mpak. This:

  • Requires mpak CLI to be globally installed
  • Adds subprocess overhead for every operation
  • Makes credential resolution harder (NimbleBrain has its own TUI for masked credential prompts, can't use mpak's readline)
  • Prevents proper TypeScript type safety across the boundary

The SDK already has MpakClient for registry API calls. It needs the runtime functions too.

What to Move

Bundle Runtime (from packages/cli/src/commands/packages/run.ts)
Function Lines Purpose
parsePackageSpec() 67-85 Parse @scope/name@version specs
readManifest() 90-96 Read manifest.json from cache dir
resolveArgs() 102-106 Substitute ${__dirname} in command args
resolveWorkspace() 112-117 Resolve MPAK_WORKSPACE env var
substituteUserConfig() 123-133 Substitute ${user_config.*} placeholders
substituteEnvVars() 138-148 Apply user config substitution to all env vars
getLocalCacheDir() 154-161 Deterministic cache dir for local .mcpb bundles
localBundleNeedsExtract() 167-181 Check if local bundle needs re-extraction
findPythonCommand() 317-325 Auto-detect python3 vs python
Config Management (from packages/cli/src/utils/config-manager.ts)
Symbol Lines Purpose
ConfigManager class 134-291 Read/write ~/.mpak/config.json — get/set/clear per-package credentials
MpakConfig interface 20-25 Config file schema
PackageConfig interface 13-15 Per-package config shape
ConfigCorruptedError class 30-39 Error type for corrupt config
validateConfig() 44-129 Config file validation + migration
CONFIG_VERSION constant 8 Schema version
Cache Management (from packages/cli/src/utils/cache.ts)
Symbol Lines Purpose
getCacheDir() 25-30 Map package name → cache directory path
getCacheMetadata() 35-45 Read .mpak-meta.json
writeCacheMetadata() 50-56 Write .mpak-meta.json
checkForUpdateAsync() 65-97 Background version check with 1hr TTL
listCachedBundles() 110-141 Enumerate cached bundles
extractZip() 152-183 Extract .mcpb ZIP with zip-bomb protection
resolveBundle() 194-205 Resolve bundle from registry (get download URL)
downloadAndExtract() 211-251 Download + extract + write metadata
CacheMetadata interface 14-19 Cache metadata type
CachedBundle interface 99-104 Cached bundle entry type
What Stays in CLI

These are CLI-specific (interactive prompts, console formatting) and should NOT move:

  • promptForValue() — readline-based interactive prompt
  • gatherUserConfigValues() — interactive config gathering with save prompts
  • fmtError(), table(), certLabel(), formatSize(), truncate() — console formatting
  • handleRun() — CLI command handler (calls the SDK functions)

Proposed SDK Structure

packages/sdk-typescript/src/
├── client.ts          # MpakClient (existing — registry API)
├── types.ts           # Existing types
├── errors.ts          # Existing errors
├── bundle-runtime.ts  # NEW: parsePackageSpec, readManifest, resolveArgs, substituteEnvVars, etc.
├── config-manager.ts  # NEW: ConfigManager class + types
├── cache.ts           # NEW: getCacheDir, downloadAndExtract, extractZip, etc.
└── index.ts           # Re-exports everything

Migration Steps

  1. Copy functions to SDK, update imports (change .js extensions, adjust paths)
  2. Add node:fs, node:path, node:os, node:crypto to SDK dependencies (these functions use filesystem APIs)
  3. Export from SDK's index.ts
  4. Update CLI to import from @nimblebrain/mpak-sdk instead of local paths
  5. Run pnpm typecheck && pnpm test across the monorepo
  6. Publish new SDK version

Consumer Usage (NimbleBrain)

After this change, NimbleBrain can do:

import {
  ConfigManager,
  getCacheDir,
  resolveBundle,
  downloadAndExtract,
  readManifest,
  substituteEnvVars,
  parsePackageSpec,
  findPythonCommand,
} from '@nimblebrain/mpak-sdk';

// Resolve + download
const downloadInfo = await resolveBundle(name, client);
const { cacheDir } = await downloadAndExtract(name, downloadInfo);

// Read manifest + resolve credentials
const manifest = readManifest(cacheDir);
const configMgr = new ConfigManager();
const storedConfig = configMgr.getPackageConfig(name);
const env = substituteEnvVars(manifest.server.mcp_config.env, storedConfig);

// Spawn MCP server directly — no `mpak run` subprocess
const source = new McpSource(serverName, { command, args, env });

No more Bun.spawn(["mpak", ...]).

Dominant language
TypeScript
Stars
14
Forks
13
Avg merge
16m
Merged PRs (30d)
4

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from NimbleBrainInc/mpak

All issues in NimbleBrainInc/mpak

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.