@nimblebrain/mpak 0.0.1 → 0.1.0

package/dist/utils/config-manager.js

@@ -1,6 +1,67 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+/**
+ * Current config schema version
+ */
+export const CONFIG_VERSION = '1.0.0';
+/**
+ * Error thrown when config file is corrupted or invalid
+ */
+export class ConfigCorruptedError extends Error {
+    configPath;
+    cause;
+    constructor(message, configPath, cause) {
+        super(message);
+        this.configPath = configPath;
+        this.cause = cause;
+        this.name = 'ConfigCorruptedError';
+    }
+}
+/**
+ * Validates that a parsed object conforms to the MpakConfig schema
+ */
+function validateConfig(data, configPath) {
+    if (typeof data !== 'object' || data === null) {
+        throw new ConfigCorruptedError('Config file must be a JSON object', configPath);
+    }
+    const obj = data;
+    // Required fields
+    if (typeof obj.version !== 'string') {
+        throw new ConfigCorruptedError('Config missing required field: version (string)', configPath);
+    }
+    if (typeof obj.lastUpdated !== 'string') {
+        throw new ConfigCorruptedError('Config missing required field: lastUpdated (string)', configPath);
+    }
+    // Optional fields with type validation
+    if (obj.registryUrl !== undefined && typeof obj.registryUrl !== 'string') {
+        throw new ConfigCorruptedError('Config field registryUrl must be a string', configPath);
+    }
+    if (obj.packages !== undefined) {
+        if (typeof obj.packages !== 'object' || obj.packages === null) {
+            throw new ConfigCorruptedError('Config field packages must be an object', configPath);
+        }
+        // Validate each package config
+        for (const [pkgName, pkgConfig] of Object.entries(obj.packages)) {
+            if (typeof pkgConfig !== 'object' || pkgConfig === null) {
+                throw new ConfigCorruptedError(`Config packages.${pkgName} must be an object`, configPath);
+            }
+            for (const [key, value] of Object.entries(pkgConfig)) {
+                if (typeof value !== 'string') {
+                    throw new ConfigCorruptedError(`Config packages.${pkgName}.${key} must be a string`, configPath);
+                }
+            }
+        }
+    }
+    // Check for unknown fields (additionalProperties: false in schema)
+    const knownFields = new Set(['version', 'lastUpdated', 'registryUrl', 'packages']);
+    for (const key of Object.keys(obj)) {
+        if (!knownFields.has(key)) {
+            throw new ConfigCorruptedError(`Config contains unknown field: ${key}`, configPath);
+        }
+    }
+    return data;
+}
 /**
  * Configuration manager for CLI settings in ~/.mpak/config.json
  */
@@ -24,25 +85,29 @@ export class ConfigManager {
         }
         if (!existsSync(this.configFile)) {
             this.config = {
-                version: '1.0.0',
+                version: CONFIG_VERSION,
                 lastUpdated: new Date().toISOString(),
             };
             this.saveConfig();
             return this.config;
         }
+        let configJson;
         try {
-            const configJson = readFileSync(this.configFile, 'utf8');
-            this.config = JSON.parse(configJson);
-            return this.config;
+            configJson = readFileSync(this.configFile, 'utf8');
         }
-        catch {
-            this.config = {
-                version: '1.0.0',
-                lastUpdated: new Date().toISOString(),
-            };
-            this.saveConfig();
-            return this.config;
+        catch (err) {
+            throw new ConfigCorruptedError(`Failed to read config file: ${err instanceof Error ? err.message : String(err)}`, this.configFile, err instanceof Error ? err : undefined);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(configJson);
+        }
+        catch (err) {
+            throw new ConfigCorruptedError(`Config file contains invalid JSON: ${err instanceof Error ? err.message : String(err)}`, this.configFile, err instanceof Error ? err : undefined);
         }
+        // Validate structure against schema
+        this.config = validateConfig(parsed, this.configFile);
+        return this.config;
     }
     saveConfig() {
         if (!this.config) {

package/dist/utils/config-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../../src/utils/config-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../../src/utils/config-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimblebrain/mpak",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "CLI for downloading MCPB bundles from the mpak registry",
   "main": "dist/index.js",
   "type": "module",
@@ -37,9 +37,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "commander": "^14.0.2"
+    "archiver": "^7.0.1",
+    "commander": "^14.0.2",
+    "gray-matter": "^4.0.3",
+    "zod": "^4.3.5"
   },
   "devDependencies": {
+    "@types/archiver": "^7.0.0",
     "@types/node": "^25.0.3",
     "@vitest/ui": "^4.0.16",
     "openapi-typescript": "^7.10.1",

package/src/commands/packages/run.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { homedir } from 'os';
 import { join } from 'path';
-import { parsePackageSpec, getCacheDir, resolveArgs, substituteUserConfig, substituteEnvVars } from './run.js';
+import { parsePackageSpec, getCacheDir, resolveArgs, substituteUserConfig, substituteEnvVars, getLocalCacheDir, localBundleNeedsExtract } from './run.js';
 
 describe('parsePackageSpec', () => {
   describe('scoped packages', () => {
@@ -220,3 +220,42 @@ describe('substituteEnvVars', () => {
     });
   });
 });
+
+describe('getLocalCacheDir', () => {
+  const expectedBase = join(homedir(), '.mpak', 'cache', '_local');
+
+  it('returns consistent hash for same path', () => {
+    const dir1 = getLocalCacheDir('/path/to/bundle.mcpb');
+    const dir2 = getLocalCacheDir('/path/to/bundle.mcpb');
+    expect(dir1).toBe(dir2);
+  });
+
+  it('returns different hash for different paths', () => {
+    const dir1 = getLocalCacheDir('/path/to/bundle1.mcpb');
+    const dir2 = getLocalCacheDir('/path/to/bundle2.mcpb');
+    expect(dir1).not.toBe(dir2);
+  });
+
+  it('includes _local in path', () => {
+    const dir = getLocalCacheDir('/path/to/bundle.mcpb');
+    expect(dir).toContain('_local');
+    expect(dir.startsWith(expectedBase)).toBe(true);
+  });
+
+  it('produces a 12-character hash suffix', () => {
+    const dir = getLocalCacheDir('/path/to/bundle.mcpb');
+    const hashPart = dir.split('/').pop();
+    expect(hashPart).toHaveLength(12);
+  });
+});
+
+describe('localBundleNeedsExtract', () => {
+  it('returns true when cache directory does not exist', () => {
+    expect(localBundleNeedsExtract('/any/path.mcpb', '/nonexistent/cache')).toBe(true);
+  });
+
+  it('returns true when meta file does not exist in cache dir', () => {
+    // Using a directory that exists but has no .mpak-meta.json
+    expect(localBundleNeedsExtract('/any/path.mcpb', '/tmp')).toBe(true);
+  });
+});

package/src/commands/packages/run.ts

@@ -1,13 +1,15 @@
 import { spawn, spawnSync } from 'child_process';
 import { createInterface } from 'readline';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, rmSync, statSync } from 'fs';
+import { createHash } from 'crypto';
 import { homedir } from 'os';
-import { join, dirname } from 'path';
+import { join, dirname, resolve, basename } from 'path';
 import { RegistryClient } from '../../lib/api/registry-client.js';
 import { ConfigManager } from '../../utils/config-manager.js';
 
 export interface RunOptions {
   update?: boolean;
+  local?: string;  // Path to local .mcpb file
 }
 
 interface McpConfig {
@@ -169,6 +171,33 @@ export function substituteEnvVars(
   return result;
 }
 
+/**
+ * Get cache directory for a local bundle.
+ * Uses hash of absolute path to avoid collisions.
+ */
+export function getLocalCacheDir(bundlePath: string): string {
+  const absolutePath = resolve(bundlePath);
+  const hash = createHash('md5').update(absolutePath).digest('hex').slice(0, 12);
+  return join(homedir(), '.mpak', 'cache', '_local', hash);
+}
+
+/**
+ * Check if local bundle needs re-extraction.
+ * Returns true if cache doesn't exist or bundle was modified after extraction.
+ */
+export function localBundleNeedsExtract(bundlePath: string, cacheDir: string): boolean {
+  const metaPath = join(cacheDir, '.mpak-meta.json');
+  if (!existsSync(metaPath)) return true;
+
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+    const bundleStat = statSync(bundlePath);
+    return bundleStat.mtimeMs > new Date(meta.extractedAt).getTime();
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Prompt user for a config value (interactive terminal input)
  */
@@ -295,69 +324,125 @@ function findPythonCommand(): string {
 }
 
 /**
- * Run a package from the registry
+ * Run a package from the registry or a local bundle file
  */
 export async function handleRun(
   packageSpec: string,
   options: RunOptions = {}
 ): Promise<void> {
-  const { name, version: requestedVersion } = parsePackageSpec(packageSpec);
-  const client = new RegistryClient();
-  const platform = RegistryClient.detectPlatform();
-  const cacheDir = getCacheDir(name);
-
-  let needsPull = true;
-  let cachedMeta = getCacheMetadata(cacheDir);
-
-  // Check if we have a cached version
-  if (cachedMeta && !options.update) {
-    if (requestedVersion) {
-      // Specific version requested - check if cached version matches
-      needsPull = cachedMeta.version !== requestedVersion;
-    } else {
-      // Latest requested - use cache (user can --update to refresh)
-      needsPull = false;
-    }
+  // Validate that either --local or package spec is provided
+  if (!options.local && !packageSpec) {
+    process.stderr.write(`=> Error: Either provide a package name or use --local <path>\n`);
+    process.exit(1);
   }
 
-  if (needsPull) {
-    // Fetch download info
-    const downloadInfo = await client.getDownloadInfo(name, requestedVersion, platform);
-    const bundle = downloadInfo.bundle;
+  let cacheDir: string;
+  let packageName: string;
+
+  if (options.local) {
+    // === LOCAL BUNDLE MODE ===
+    const bundlePath = resolve(options.local);
 
-    // Check if cached version is already the latest
-    if (cachedMeta && cachedMeta.version === bundle.version && !options.update) {
-      needsPull = false;
+    // Validate bundle exists
+    if (!existsSync(bundlePath)) {
+      process.stderr.write(`=> Error: Bundle not found: ${bundlePath}\n`);
+      process.exit(1);
     }
 
-    if (needsPull) {
-      // Download to temp file
-      const tempPath = join(homedir(), '.mpak', 'tmp', `${Date.now()}.mcpb`);
-      mkdirSync(dirname(tempPath), { recursive: true });
+    // Validate .mcpb extension
+    if (!bundlePath.endsWith('.mcpb')) {
+      process.stderr.write(`=> Error: Not an MCPB bundle: ${bundlePath}\n`);
+      process.exit(1);
+    }
 
-      process.stderr.write(`=> Pulling ${name}@${bundle.version}...\n`);
-      await client.downloadBundle(downloadInfo.url, tempPath);
+    cacheDir = getLocalCacheDir(bundlePath);
+    const needsExtract = options.update || localBundleNeedsExtract(bundlePath, cacheDir);
 
-      // Clear old cache and extract
-      const { rmSync } = await import('fs');
+    if (needsExtract) {
+      // Clear old extraction
       if (existsSync(cacheDir)) {
         rmSync(cacheDir, { recursive: true, force: true });
       }
       mkdirSync(cacheDir, { recursive: true });
 
-      await extractZip(tempPath, cacheDir);
+      process.stderr.write(`=> Extracting ${basename(bundlePath)}...\n`);
+      await extractZip(bundlePath, cacheDir);
+
+      // Write local metadata
+      writeFileSync(
+        join(cacheDir, '.mpak-meta.json'),
+        JSON.stringify({
+          localPath: bundlePath,
+          extractedAt: new Date().toISOString(),
+        })
+      );
+    }
 
-      // Write metadata
-      writeCacheMetadata(cacheDir, {
-        version: bundle.version,
-        pulledAt: new Date().toISOString(),
-        platform: bundle.platform,
-      });
+    // Read manifest to get package name for config lookup
+    const manifest = readManifest(cacheDir);
+    packageName = manifest.name;
+    process.stderr.write(`=> Running ${packageName} (local)\n`);
+
+  } else {
+    // === REGISTRY MODE ===
+    const { name, version: requestedVersion } = parsePackageSpec(packageSpec);
+    packageName = name;
+    const client = new RegistryClient();
+    const platform = RegistryClient.detectPlatform();
+    cacheDir = getCacheDir(name);
+
+    let needsPull = true;
+    let cachedMeta = getCacheMetadata(cacheDir);
+
+    // Check if we have a cached version
+    if (cachedMeta && !options.update) {
+      if (requestedVersion) {
+        // Specific version requested - check if cached version matches
+        needsPull = cachedMeta.version !== requestedVersion;
+      } else {
+        // Latest requested - use cache (user can --update to refresh)
+        needsPull = false;
+      }
+    }
+
+    if (needsPull) {
+      // Fetch download info
+      const downloadInfo = await client.getDownloadInfo(name, requestedVersion, platform);
+      const bundle = downloadInfo.bundle;
 
-      // Cleanup temp file
-      rmSync(tempPath, { force: true });
+      // Check if cached version is already the latest
+      if (cachedMeta && cachedMeta.version === bundle.version && !options.update) {
+        needsPull = false;
+      }
 
-      process.stderr.write(`=> Cached ${name}@${bundle.version}\n`);
+      if (needsPull) {
+        // Download to temp file
+        const tempPath = join(homedir(), '.mpak', 'tmp', `${Date.now()}.mcpb`);
+        mkdirSync(dirname(tempPath), { recursive: true });
+
+        process.stderr.write(`=> Pulling ${name}@${bundle.version}...\n`);
+        await client.downloadBundle(downloadInfo.url, tempPath);
+
+        // Clear old cache and extract
+        if (existsSync(cacheDir)) {
+          rmSync(cacheDir, { recursive: true, force: true });
+        }
+        mkdirSync(cacheDir, { recursive: true });
+
+        await extractZip(tempPath, cacheDir);
+
+        // Write metadata
+        writeCacheMetadata(cacheDir, {
+          version: bundle.version,
+          pulledAt: new Date().toISOString(),
+          platform: bundle.platform,
+        });
+
+        // Cleanup temp file
+        rmSync(tempPath, { force: true });
+
+        process.stderr.write(`=> Cached ${name}@${bundle.version}\n`);
+      }
     }
   }
 
@@ -369,7 +454,7 @@ export async function handleRun(
   let userConfigValues: Record<string, string> = {};
   if (manifest.user_config && Object.keys(manifest.user_config).length > 0) {
     const configManager = new ConfigManager();
-    userConfigValues = await gatherUserConfigValues(name, manifest.user_config, configManager);
+    userConfigValues = await gatherUserConfigValues(packageName, manifest.user_config, configManager);
   }
 
   // Substitute user_config placeholders in env vars

package/src/commands/search.ts

@@ -0,0 +1,191 @@
+import { RegistryClient } from '../lib/api/registry-client.js';
+import { searchSkills } from '../lib/api/skills-client.js';
+
+export interface UnifiedSearchOptions {
+  type?: 'bundle' | 'skill';
+  sort?: 'downloads' | 'recent' | 'name';
+  limit?: number;
+  offset?: number;
+  json?: boolean;
+}
+
+interface UnifiedResult {
+  type: 'bundle' | 'skill';
+  name: string;
+  description: string;
+  downloads: number;
+  version: string;
+  author?: string;
+  // Bundle-specific
+  serverType?: string;
+  verified?: boolean;
+  provenance?: boolean;
+  // Skill-specific
+  category?: string;
+}
+
+/**
+ * Unified search across bundles and skills
+ */
+export async function handleUnifiedSearch(
+  query: string,
+  options: UnifiedSearchOptions = {}
+): Promise<void> {
+  try {
+    const results: UnifiedResult[] = [];
+    let bundleTotal = 0;
+    let skillTotal = 0;
+
+    // Search both in parallel (unless filtered by type)
+    const searchBundles = !options.type || options.type === 'bundle';
+    const searchSkillsFlag = !options.type || options.type === 'skill';
+
+    const [bundleResult, skillResult] = await Promise.all([
+      searchBundles
+        ? new RegistryClient().searchBundles(query, {
+            sort: options.sort,
+            limit: options.limit,
+            offset: options.offset,
+          })
+        : null,
+      searchSkillsFlag
+        ? searchSkills({
+            q: query,
+            sort: options.sort as any,
+            limit: options.limit,
+            offset: options.offset,
+          }).catch(() => null) // Skills API may not be deployed yet
+        : null,
+    ]);
+
+    // Process bundle results
+    if (bundleResult) {
+      bundleTotal = bundleResult.total;
+      for (const bundle of bundleResult.bundles) {
+        results.push({
+          type: 'bundle',
+          name: bundle.name,
+          description: bundle.description || '',
+          downloads: bundle.downloads || 0,
+          version: bundle.latest_version,
+          author: bundle.author?.name || undefined,
+          serverType: bundle.server_type || undefined,
+          verified: bundle.verified,
+          provenance: !!bundle.provenance,
+        });
+      }
+    }
+
+    // Process skill results
+    if (skillResult) {
+      skillTotal = skillResult.total;
+      for (const skill of skillResult.skills) {
+        results.push({
+          type: 'skill',
+          name: skill.name,
+          description: skill.description || '',
+          downloads: skill.downloads || 0,
+          version: skill.latest_version,
+          author: skill.author?.name || undefined,
+          category: skill.category || undefined,
+        });
+      }
+    }
+
+    // Sort combined results
+    if (options.sort === 'downloads') {
+      results.sort((a, b) => b.downloads - a.downloads);
+    } else if (options.sort === 'name') {
+      results.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    // 'recent' sorting would require timestamps, skip for now
+
+    // JSON output
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            results,
+            totals: { bundles: bundleTotal, skills: skillTotal },
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+
+    // No results
+    if (results.length === 0) {
+      console.log(`\nNo results found for "${query}"`);
+      if (!searchBundles) console.log('  (searched skills only)');
+      if (!searchSkillsFlag) console.log('  (searched bundles only)');
+      return;
+    }
+
+    // Summary
+    const totalResults = bundleTotal + skillTotal;
+    const typeFilter = options.type ? ` (${options.type}s only)` : '';
+    console.log(`\nFound ${totalResults} result(s) for "${query}"${typeFilter}:\n`);
+
+    // Table header
+    const typeWidth = 10;
+    const nameWidth = 38;
+    const versionWidth = 12;
+    const downloadsWidth = 10;
+
+    console.log(
+      'TYPE'.padEnd(typeWidth) +
+        'NAME'.padEnd(nameWidth) +
+        'VERSION'.padEnd(versionWidth) +
+        'DOWNLOADS'.padStart(downloadsWidth)
+    );
+
+    // Table rows
+    for (const result of results) {
+      const typeLabel = result.type === 'bundle' ? 'bundle' : 'skill';
+      const name =
+        result.name.length > nameWidth - 2
+          ? result.name.slice(0, nameWidth - 5) + '...'
+          : result.name;
+      const version = result.version || '-';
+      const downloads = result.downloads.toLocaleString();
+
+      console.log(
+        typeLabel.padEnd(typeWidth) +
+          name.padEnd(nameWidth) +
+          version.padEnd(versionWidth) +
+          downloads.padStart(downloadsWidth)
+      );
+    }
+
+    console.log('');
+
+    // Show breakdown
+    if (!options.type) {
+      const parts = [];
+      if (bundleTotal > 0) parts.push(`${bundleTotal} bundle(s)`);
+      if (skillTotal > 0) parts.push(`${skillTotal} skill(s)`);
+      if (parts.length > 1) {
+        console.log(`  ${parts.join(', ')}`);
+      }
+    }
+
+    // Pagination hint
+    const currentLimit = options.limit || 20;
+    const currentOffset = options.offset || 0;
+    if (bundleTotal + skillTotal > currentOffset + results.length) {
+      console.log(`  Use --offset ${currentOffset + currentLimit} to see more results.`);
+    }
+
+    // Hint for more details
+    console.log('');
+    console.log('Use "mpak bundle show <name>" or "mpak skill show <name>" for details.');
+  } catch (error) {
+    console.error('Search failed');
+    if (error instanceof Error) {
+      console.error(`  ${error.message}`);
+    }
+    process.exit(1);
+  }
+}

package/src/commands/skills/index.ts

@@ -0,0 +1,7 @@
+export { handleSkillValidate, validateSkillDirectory } from './validate.js';
+export { handleSkillPack, packSkill } from './pack.js';
+export { handleSkillSearch } from './search.js';
+export { handleSkillShow } from './show.js';
+export { handleSkillPull } from './pull.js';
+export { handleSkillInstall } from './install.js';
+export { handleSkillList } from './list.js';