@nimblebrain/mpak 0.0.1 → 0.0.2

package/src/lib/api/skills-client.ts

@@ -0,0 +1,148 @@
+/**
+ * Skills API client for mpak registry
+ */
+
+import type {
+  SkillSearchResponse,
+  SkillDetail,
+  SkillDownloadInfo,
+} from '../../schemas/generated/skill.js';
+
+const DEFAULT_REGISTRY_URL = 'https://api.mpak.dev';
+
+function getRegistryUrl(): string {
+  return process.env.MPAK_REGISTRY_URL || DEFAULT_REGISTRY_URL;
+}
+
+/**
+ * Parse a scoped name into scope and name parts
+ * Handles both @scope/name and scope/name formats
+ */
+function parseScopedName(name: string): { scope: string; skillName: string } {
+  const normalizedName = name.startsWith('@') ? name.slice(1) : name;
+  const [scope, skillName] = normalizedName.split('/');
+  if (!scope || !skillName) {
+    throw new Error(`Invalid skill name format: ${name}. Expected @scope/name or scope/name`);
+  }
+  return { scope, skillName };
+}
+
+export interface SkillSearchOptions {
+  q?: string;
+  tags?: string;
+  category?: string;
+  surface?: string;
+  sort?: 'downloads' | 'recent' | 'name';
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Search for skills in the registry
+ */
+export async function searchSkills(options: SkillSearchOptions): Promise<SkillSearchResponse> {
+  const baseUrl = getRegistryUrl();
+  const params = new URLSearchParams();
+
+  if (options.q) params.set('q', options.q);
+  if (options.tags) params.set('tags', options.tags);
+  if (options.category) params.set('category', options.category);
+  if (options.surface) params.set('surface', options.surface);
+  if (options.sort) params.set('sort', options.sort);
+  if (options.limit) params.set('limit', options.limit.toString());
+  if (options.offset) params.set('offset', options.offset.toString());
+
+  const url = `${baseUrl}/v1/skills/search?${params.toString()}`;
+
+  const response = await fetch(url, {
+    headers: { Accept: 'application/json' },
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Search failed (${response.status}): ${text}`);
+  }
+
+  return response.json() as Promise<SkillSearchResponse>;
+}
+
+/**
+ * Get skill details from the registry
+ */
+export async function getSkillDetails(name: string): Promise<SkillDetail> {
+  const baseUrl = getRegistryUrl();
+  const { scope, skillName } = parseScopedName(name);
+
+  // Server expects: /v1/skills/@scope/name
+  const url = `${baseUrl}/v1/skills/@${scope}/${skillName}`;
+
+  const response = await fetch(url, {
+    headers: { Accept: 'application/json' },
+  });
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`Skill not found: ${name}`);
+    }
+    const text = await response.text();
+    throw new Error(`Failed to get skill details (${response.status}): ${text}`);
+  }
+
+  return response.json() as Promise<SkillDetail>;
+}
+
+/**
+ * Get download info for a skill
+ */
+export async function getSkillDownloadInfo(
+  name: string,
+  version?: string
+): Promise<SkillDownloadInfo> {
+  const baseUrl = getRegistryUrl();
+  const { scope, skillName } = parseScopedName(name);
+
+  // Server expects: /v1/skills/@scope/name/download or /v1/skills/@scope/name/versions/x.y.z/download
+  const versionPath = version ? `/versions/${version}` : '';
+  const url = `${baseUrl}/v1/skills/@${scope}/${skillName}${versionPath}/download`;
+
+  const response = await fetch(url, {
+    headers: { Accept: 'application/json' },
+  });
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`Skill not found: ${name}${version ? `@${version}` : ''}`);
+    }
+    const text = await response.text();
+    throw new Error(`Failed to get download info (${response.status}): ${text}`);
+  }
+
+  return response.json() as Promise<SkillDownloadInfo>;
+}
+
+/**
+ * Download a skill bundle
+ */
+export async function downloadSkillBundle(
+  downloadUrl: string,
+  expectedSha256?: string
+): Promise<Buffer> {
+  const response = await fetch(downloadUrl);
+
+  if (!response.ok) {
+    throw new Error(`Download failed (${response.status})`);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+
+  // Verify SHA256 if provided
+  if (expectedSha256) {
+    const { createHash } = await import('crypto');
+    const hash = createHash('sha256').update(buffer).digest('hex');
+    if (hash !== expectedSha256) {
+      throw new Error(`SHA256 mismatch: expected ${expectedSha256}, got ${hash}`);
+    }
+  }
+
+  return buffer;
+}

package/src/program.test.ts

@@ -9,9 +9,7 @@ describe('createProgram', () => {
 
   it('should have a description', () => {
     const program = createProgram();
-    expect(program.description()).toBe(
-      'CLI for downloading MCPB bundles from the package directory'
-    );
+    expect(program.description()).toBe('CLI for MCP bundles and Agent Skills');
   });
 
   it('should have version option', () => {

package/src/program.ts

@@ -1,26 +1,66 @@
 import { Command } from 'commander';
 import { getVersion } from './utils/version.js';
+import { handleUnifiedSearch } from './commands/search.js';
 import { handleSearch } from './commands/packages/search.js';
 import { handleShow } from './commands/packages/show.js';
 import { handlePull } from './commands/packages/pull.js';
 import { handleRun } from './commands/packages/run.js';
-import { handleConfigSet, handleConfigGet, handleConfigList, handleConfigClear } from './commands/config.js';
+import {
+  handleConfigSet,
+  handleConfigGet,
+  handleConfigList,
+  handleConfigClear,
+} from './commands/config.js';
+import {
+  handleSkillValidate,
+  handleSkillPack,
+  handleSkillSearch,
+  handleSkillShow,
+  handleSkillPull,
+  handleSkillInstall,
+  handleSkillList,
+} from './commands/skills/index.js';
 
 /**
  * Creates and configures the CLI program
  *
- * MVP: Unauthenticated commands only (v1 API)
+ * Command structure:
+ * - mpak search <query>    - Unified search (bundles + skills)
+ * - mpak bundle <command>  - MCP bundle commands
+ * - mpak skill <command>   - Agent skill commands
+ * - mpak config <command>  - Configuration commands
  */
 export function createProgram(): Command {
   const program = new Command();
 
   program
     .name('mpak')
-    .description('CLI for downloading MCPB bundles from the package directory')
+    .description('CLI for MCP bundles and Agent Skills')
     .version(getVersion(), '-v, --version', 'Output the current version');
 
-  // Search command
+  // ==========================================================================
+  // Unified search (bundles + skills)
+  // ==========================================================================
+
   program
+    .command('search <query>')
+    .description('Search bundles and skills')
+    .option('--type <type>', 'Filter by type (bundle, skill)')
+    .option('--sort <field>', 'Sort by: downloads, recent, name')
+    .option('--limit <number>', 'Limit results', parseInt)
+    .option('--offset <number>', 'Pagination offset', parseInt)
+    .option('--json', 'Output as JSON')
+    .action(async (query, options) => {
+      await handleUnifiedSearch(query, options);
+    });
+
+  // ==========================================================================
+  // Bundle namespace (MCP bundles)
+  // ==========================================================================
+
+  const bundle = program.command('bundle').description('MCP bundle commands');
+
+  bundle
     .command('search <query>')
     .description('Search public bundles')
     .option('--type <type>', 'Filter by server type (node, python, binary)')
@@ -32,8 +72,7 @@ export function createProgram(): Command {
       await handleSearch(query, options);
     });
 
-  // Show command
-  program
+  bundle
     .command('show <package>')
     .description('Show detailed information about a bundle')
     .option('--json', 'Output as JSON')
@@ -41,19 +80,9 @@ export function createProgram(): Command {
       await handleShow(packageName, options);
     });
 
-  // Info command (alias for show)
-  program
-    .command('info <package>')
-    .description('Show detailed information about a bundle (alias for show)')
-    .option('--json', 'Output as JSON')
-    .action(async (packageName, options) => {
-      await handleShow(packageName, options);
-    });
-
-  // Pull command
-  program
+  bundle
     .command('pull <package>')
-    .description('Download a bundle from the registry (e.g., @scope/name or @scope/name@1.0.0)')
+    .description('Download a bundle from the registry')
     .option('-o, --output <path>', 'Output file path')
     .option('--os <os>', 'Target OS (darwin, linux, win32)')
     .option('--arch <arch>', 'Target architecture (x64, arm64)')
@@ -62,35 +91,96 @@ export function createProgram(): Command {
       await handlePull(packageSpec, options);
     });
 
-  // Install command (alias for pull)
-  program
-    .command('install <package>')
-    .description('Download a bundle from the registry (alias for pull)')
-    .option('-o, --output <path>', 'Output file path')
-    .option('--os <os>', 'Target OS (darwin, linux, win32)')
-    .option('--arch <arch>', 'Target architecture (x64, arm64)')
-    .option('--json', 'Output download info as JSON')
-    .action(async (packageSpec, options) => {
-      await handlePull(packageSpec, options);
-    });
-
-  // Run command
-  program
+  bundle
     .command('run <package>')
-    .description('Run an MCP server from the registry (e.g., @scope/name or @scope/name@1.0.0)')
+    .description('Run an MCP server from the registry')
     .option('--update', 'Force re-download even if cached')
     .action(async (packageSpec, options) => {
       await handleRun(packageSpec, options);
     });
 
-  // Config command group
+  // ==========================================================================
+  // Skill namespace (Agent Skills)
+  // ==========================================================================
+
+  const skill = program.command('skill').description('Agent skill commands');
+
+  skill
+    .command('validate <path>')
+    .description('Validate a skill directory against the Agent Skills spec')
+    .option('--json', 'Output as JSON')
+    .action(async (path, options) => {
+      await handleSkillValidate(path, options);
+    });
+
+  skill
+    .command('pack <path>')
+    .description('Create a .skill bundle from a skill directory')
+    .option('-o, --output <path>', 'Output file path')
+    .option('--json', 'Output as JSON')
+    .action(async (path, options) => {
+      await handleSkillPack(path, options);
+    });
+
+  skill
+    .command('search <query>')
+    .description('Search skills in the registry')
+    .option('--tags <tags>', 'Filter by tags (comma-separated)')
+    .option('--category <category>', 'Filter by category')
+    .option('--surface <surface>', 'Filter by surface (claude-code, claude-api, claude-ai)')
+    .option('--sort <field>', 'Sort by: downloads, recent, name')
+    .option('--limit <number>', 'Limit results', parseInt)
+    .option('--offset <number>', 'Pagination offset', parseInt)
+    .option('--json', 'Output as JSON')
+    .action(async (query, options) => {
+      await handleSkillSearch(query, options);
+    });
+
+  skill
+    .command('show <name>')
+    .description('Show detailed information about a skill')
+    .option('--json', 'Output as JSON')
+    .action(async (name, options) => {
+      await handleSkillShow(name, options);
+    });
+
+  skill
+    .command('pull <name>')
+    .description('Download a .skill bundle from the registry')
+    .option('-o, --output <path>', 'Output file path')
+    .option('--json', 'Output as JSON')
+    .action(async (name, options) => {
+      await handleSkillPull(name, options);
+    });
+
+  skill
+    .command('install <name>')
+    .description('Install a skill to ~/.claude/skills/')
+    .option('--force', 'Overwrite existing installation')
+    .option('--json', 'Output as JSON')
+    .action(async (name, options) => {
+      await handleSkillInstall(name, options);
+    });
+
+  skill
+    .command('list')
+    .description('List installed skills')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      await handleSkillList(options);
+    });
+
+  // ==========================================================================
+  // Config commands (shared for bundles and skills)
+  // ==========================================================================
+
   const configCmd = program
     .command('config')
     .description('Manage per-package configuration values');
 
   configCmd
     .command('set <package> <key=value...>')
-    .description('Set config value(s) for a package (e.g., mpak config set @scope/name api_key=xxx)')
+    .description('Set config value(s) for a package')
     .action(async (packageName, keyValuePairs) => {
       await handleConfigSet(packageName, keyValuePairs);
     });

package/src/schemas/config.v1.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mpak.dev/schemas/config.v1.json",
+  "title": "mpak CLI Configuration v1",
+  "description": "Configuration file for the mpak CLI stored at ~/.mpak/config.json",
+  "type": "object",
+  "required": ["version", "lastUpdated"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "1.0.0",
+      "description": "Configuration schema version"
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last configuration update"
+    },
+    "registryUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "Custom registry URL (overrides default https://api.mpak.dev)"
+    },
+    "packages": {
+      "type": "object",
+      "description": "Per-package configuration values (user_config)",
+      "additionalProperties": {
+        "type": "object",
+        "description": "Configuration key-value pairs for a specific package",
+        "additionalProperties": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}