Move bundle runtime, config, and cache functions from CLI to SDK
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
- Domain
- cli, developer-experience
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
mpakCLI 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 promptgatherUserConfigValues()— interactive config gathering with save promptsfmtError(),table(),certLabel(),formatSize(),truncate()— console formattinghandleRun()— 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
- Copy functions to SDK, update imports (change
.jsextensions, adjust paths) - Add
node:fs,node:path,node:os,node:cryptoto SDK dependencies (these functions use filesystem APIs) - Export from SDK's
index.ts - Update CLI to import from
@nimblebrain/mpak-sdkinstead of local paths - Run
pnpm typecheck && pnpm testacross the monorepo - 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
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from NimbleBrainInc/mpak
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
NimbleBrainInc/mpak#180 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
NimbleBrainInc/mpak#175 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
NimbleBrainInc/mpak#159 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
NimbleBrainInc/mpak#120 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
NimbleBrainInc/mpak#112 ·
All issues in NimbleBrainInc/mpak
Similar issues
-
bug documentation
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Potential Bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Comfy-Org/ComfyUI_frontend#23773 ·
Maintainers usually reply within 1 day
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 85/100
lingdojo/kana-dojo#34301 · 1 comment · 5 reactions ·
Maintainers usually reply within 1 day
-
code-quality refactoring
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
github/gh-aw-firewall#11797 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
code-yeongyu/senpi#7007 ·
Maintainers usually reply within 1 day