@nimblebrain/mpak 0.0.1 → 0.0.2

package/src/schemas/generated/skill.ts

@@ -0,0 +1,271 @@
+import { z } from 'zod';
+
+// =============================================================================
+// Agent Skills Specification - Skill Frontmatter Schema
+// https://agentskills.io/specification
+// =============================================================================
+
+/**
+ * Skill name validation
+ * - 1-64 characters
+ * - Lowercase alphanumeric with single hyphens
+ * - Cannot start or end with hyphen
+ * - Must match directory name (validated separately)
+ */
+export const SkillNameSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(
+    /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/,
+    'Lowercase alphanumeric with single hyphens, cannot start/end with hyphen'
+  );
+
+/**
+ * Skill description
+ * - 1-1024 characters
+ * - Should describe what the skill does AND when to use it
+ */
+export const SkillDescriptionSchema = z.string().min(1).max(1024);
+
+// =============================================================================
+// Discovery Metadata Extension (via metadata: field)
+// =============================================================================
+
+/**
+ * Category taxonomy for skill discovery
+ */
+export const SkillCategorySchema = z.enum([
+  'development', // Code, debugging, architecture
+  'writing', // Documentation, content, editing
+  'research', // Investigation, analysis, learning
+  'consulting', // Strategy, decisions, planning
+  'data', // Analysis, visualization, processing
+  'design', // UI/UX, visual, creative
+  'operations', // DevOps, infrastructure, automation
+  'security', // Auditing, compliance, protection
+  'other', // Uncategorized
+]);
+
+/**
+ * Surfaces where the skill works
+ */
+export const SkillSurfaceSchema = z.enum([
+  'claude-code', // Claude Code CLI
+  'claude-api', // Claude API with code execution
+  'claude-ai', // claude.ai web interface
+]);
+
+/**
+ * Author information for attribution
+ */
+export const SkillAuthorSchema = z.object({
+  name: z.string().min(1),
+  url: z.string().url().optional(),
+  email: z.string().email().optional(),
+});
+
+/**
+ * Example usage for discovery
+ */
+export const SkillExampleSchema = z.object({
+  prompt: z.string().min(1),
+  context: z.string().optional(),
+});
+
+/**
+ * Discovery metadata (via metadata: field in frontmatter)
+ * All fields optional - skills can start minimal and add discovery metadata later
+ */
+export const SkillDiscoveryMetadataSchema = z
+  .object({
+    // Discovery
+    tags: z.array(z.string().max(32)).max(10).optional(),
+    category: SkillCategorySchema.optional(),
+    triggers: z.array(z.string().max(128)).max(20).optional(),
+    keywords: z.array(z.string().max(32)).max(30).optional(),
+    surfaces: z.array(SkillSurfaceSchema).optional(),
+
+    // Attribution
+    author: SkillAuthorSchema.optional(),
+
+    // Version (for registry tracking)
+    version: z.string().optional(),
+
+    // Examples
+    examples: z.array(SkillExampleSchema).max(5).optional(),
+  })
+  .passthrough(); // Allow additional custom keys
+
+// =============================================================================
+// Complete SKILL.md Frontmatter Schema
+// =============================================================================
+
+/**
+ * Complete SKILL.md frontmatter schema
+ * Combines official Agent Skills spec with discovery metadata extension
+ */
+export const SkillFrontmatterSchema = z.object({
+  // Required (official spec)
+  name: SkillNameSchema,
+  description: SkillDescriptionSchema,
+
+  // Optional (official spec - informational pass-through)
+  license: z.string().optional(),
+  compatibility: z.string().max(500).optional(),
+  'allowed-tools': z.string().optional(), // space-delimited, experimental
+
+  // Extensible metadata (official spec) - our discovery extension
+  metadata: SkillDiscoveryMetadataSchema.optional(),
+});
+
+// =============================================================================
+// Registry API Schemas
+// =============================================================================
+
+/**
+ * Scoped skill name for registry (e.g., @nimblebraininc/strategic-thought-partner)
+ */
+export const ScopedSkillNameSchema = z
+  .string()
+  .regex(
+    /^@[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/,
+    'Scoped name format: @scope/name'
+  );
+
+/**
+ * Skill artifact info for announce endpoint
+ */
+export const SkillArtifactSchema = z.object({
+  filename: z.string().regex(/\.skill$/, 'Must have .skill extension'),
+  sha256: z.string().length(64),
+  size: z.number().int().positive(),
+});
+
+/**
+ * Announce request schema for POST /v1/skills/announce
+ */
+export const SkillAnnounceRequestSchema = z.object({
+  name: ScopedSkillNameSchema,
+  version: z.string(),
+  skill: SkillFrontmatterSchema,
+  release_tag: z.string(),
+  prerelease: z.boolean().optional().default(false),
+  artifact: SkillArtifactSchema,
+});
+
+/**
+ * Announce response schema
+ */
+export const SkillAnnounceResponseSchema = z.object({
+  skill: z.string(),
+  version: z.string(),
+  status: z.enum(['created', 'exists']),
+});
+
+// =============================================================================
+// Search/List API Schemas
+// =============================================================================
+
+/**
+ * Skill search parameters
+ */
+export const SkillSearchParamsSchema = z.object({
+  q: z.string().optional(),
+  tags: z.string().optional(), // comma-separated
+  category: SkillCategorySchema.optional(),
+  surface: SkillSurfaceSchema.optional(),
+  sort: z.enum(['downloads', 'recent', 'name']).optional(),
+  limit: z.union([z.string(), z.number()]).optional(),
+  offset: z.union([z.string(), z.number()]).optional(),
+});
+
+/**
+ * Skill summary for search results
+ */
+export const SkillSummarySchema = z.object({
+  name: z.string(), // scoped name
+  description: z.string(),
+  latest_version: z.string(),
+  tags: z.array(z.string()).optional(),
+  category: SkillCategorySchema.optional(),
+  surfaces: z.array(SkillSurfaceSchema).optional(),
+  downloads: z.number(),
+  published_at: z.string(),
+  author: SkillAuthorSchema.optional(),
+});
+
+/**
+ * Skill search response
+ */
+export const SkillSearchResponseSchema = z.object({
+  skills: z.array(SkillSummarySchema),
+  total: z.number(),
+  pagination: z.object({
+    limit: z.number(),
+    offset: z.number(),
+    has_more: z.boolean(),
+  }),
+});
+
+/**
+ * Skill detail response
+ */
+export const SkillDetailSchema = z.object({
+  name: z.string(), // scoped name
+  description: z.string(),
+  latest_version: z.string(),
+  license: z.string().optional(),
+  compatibility: z.string().optional(),
+  allowed_tools: z.array(z.string()).optional(),
+  tags: z.array(z.string()).optional(),
+  category: SkillCategorySchema.optional(),
+  triggers: z.array(z.string()).optional(),
+  surfaces: z.array(SkillSurfaceSchema).optional(),
+  downloads: z.number(),
+  published_at: z.string(),
+  author: SkillAuthorSchema.optional(),
+  examples: z.array(SkillExampleSchema).optional(),
+  versions: z.array(
+    z.object({
+      version: z.string(),
+      published_at: z.string(),
+      downloads: z.number(),
+    })
+  ),
+});
+
+/**
+ * Skill download info response
+ */
+export const SkillDownloadInfoSchema = z.object({
+  url: z.string(),
+  skill: z.object({
+    name: z.string(),
+    version: z.string(),
+    sha256: z.string(),
+    size: z.number(),
+  }),
+  expires_at: z.string(),
+});
+
+// =============================================================================
+// TypeScript Types
+// =============================================================================
+
+export type SkillName = z.infer<typeof SkillNameSchema>;
+export type SkillCategory = z.infer<typeof SkillCategorySchema>;
+export type SkillSurface = z.infer<typeof SkillSurfaceSchema>;
+export type SkillAuthor = z.infer<typeof SkillAuthorSchema>;
+export type SkillExample = z.infer<typeof SkillExampleSchema>;
+export type SkillDiscoveryMetadata = z.infer<typeof SkillDiscoveryMetadataSchema>;
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>;
+export type ScopedSkillName = z.infer<typeof ScopedSkillNameSchema>;
+export type SkillArtifact = z.infer<typeof SkillArtifactSchema>;
+export type SkillAnnounceRequest = z.infer<typeof SkillAnnounceRequestSchema>;
+export type SkillAnnounceResponse = z.infer<typeof SkillAnnounceResponseSchema>;
+export type SkillSearchParams = z.infer<typeof SkillSearchParamsSchema>;
+export type SkillSummary = z.infer<typeof SkillSummarySchema>;
+export type SkillSearchResponse = z.infer<typeof SkillSearchResponseSchema>;
+export type SkillDetail = z.infer<typeof SkillDetailSchema>;
+export type SkillDownloadInfo = z.infer<typeof SkillDownloadInfoSchema>;

package/src/utils/config-manager.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { ConfigManager } from './config-manager.js';
-import { existsSync, rmSync } from 'fs';
+import { ConfigManager, ConfigCorruptedError } from './config-manager.js';
+import { existsSync, rmSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
@@ -147,4 +147,184 @@ describe('ConfigManager', () => {
     });
   });
 
+  describe('config validation', () => {
+    beforeEach(() => {
+      // Ensure config directory exists for writing test files
+      if (!existsSync(testConfigDir)) {
+        mkdirSync(testConfigDir, { recursive: true, mode: 0o700 });
+      }
+    });
+
+    it('should throw ConfigCorruptedError for invalid JSON', () => {
+      writeFileSync(testConfigFile, 'not valid json {{{', { mode: 0o600 });
+
+      const manager = new ConfigManager();
+      expect(() => manager.loadConfig()).toThrow(ConfigCorruptedError);
+      expect(() => manager.loadConfig()).toThrow(/invalid JSON/);
+    });
+
+    it('should throw ConfigCorruptedError when version is missing', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({ lastUpdated: '2024-01-01T00:00:00Z' }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      expect(() => manager.loadConfig()).toThrow(ConfigCorruptedError);
+      expect(() => manager.loadConfig()).toThrow(/version/);
+    });
+
+    it('should throw ConfigCorruptedError when lastUpdated is missing', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({ version: '1.0.0' }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      expect(() => manager.loadConfig()).toThrow(ConfigCorruptedError);
+      expect(() => manager.loadConfig()).toThrow(/lastUpdated/);
+    });
+
+    it('should throw ConfigCorruptedError when registryUrl is not a string', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({
+          version: '1.0.0',
+          lastUpdated: '2024-01-01T00:00:00Z',
+          registryUrl: 12345,
+        }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      expect(() => manager.loadConfig()).toThrow(ConfigCorruptedError);
+      expect(() => manager.loadConfig()).toThrow(/registryUrl must be a string/);
+    });
+
+    it('should throw ConfigCorruptedError when packages is not an object', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({
+          version: '1.0.0',
+          lastUpdated: '2024-01-01T00:00:00Z',
+          packages: 'not an object',
+        }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      expect(() => manager.loadConfig()).toThrow(ConfigCorruptedError);
+      expect(() => manager.loadConfig()).toThrow(/packages must be an object/);
+    });
+
+    it('should throw ConfigCorruptedError when package config is not an object', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({
+          version: '1.0.0',
+          lastUpdated: '2024-01-01T00:00:00Z',
+          packages: {
+            '@scope/pkg': 'not an object',
+          },
+        }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      expect(() => manager.loadConfig()).toThrow(ConfigCorruptedError);
+      expect(() => manager.loadConfig()).toThrow(/packages.@scope\/pkg must be an object/);
+    });
+
+    it('should throw ConfigCorruptedError when package config value is not a string', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({
+          version: '1.0.0',
+          lastUpdated: '2024-01-01T00:00:00Z',
+          packages: {
+            '@scope/pkg': {
+              api_key: 12345,
+            },
+          },
+        }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      expect(() => manager.loadConfig()).toThrow(ConfigCorruptedError);
+      expect(() => manager.loadConfig()).toThrow(/packages.@scope\/pkg.api_key must be a string/);
+    });
+
+    it('should throw ConfigCorruptedError for unknown fields', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({
+          version: '1.0.0',
+          lastUpdated: '2024-01-01T00:00:00Z',
+          unknownField: 'should not be here',
+        }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      expect(() => manager.loadConfig()).toThrow(ConfigCorruptedError);
+      expect(() => manager.loadConfig()).toThrow(/unknown field: unknownField/);
+    });
+
+    it('should include config path in error', () => {
+      writeFileSync(testConfigFile, 'invalid json', { mode: 0o600 });
+
+      const manager = new ConfigManager();
+      try {
+        manager.loadConfig();
+        expect.fail('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(ConfigCorruptedError);
+        expect((err as ConfigCorruptedError).configPath).toBe(testConfigFile);
+      }
+    });
+
+    it('should load valid minimal config', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({
+          version: '1.0.0',
+          lastUpdated: '2024-01-01T00:00:00Z',
+        }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      const config = manager.loadConfig();
+      expect(config.version).toBe('1.0.0');
+      expect(config.lastUpdated).toBe('2024-01-01T00:00:00Z');
+    });
+
+    it('should load valid full config', () => {
+      writeFileSync(
+        testConfigFile,
+        JSON.stringify({
+          version: '1.0.0',
+          lastUpdated: '2024-01-01T00:00:00Z',
+          registryUrl: 'https://custom.registry.com',
+          packages: {
+            '@scope/pkg': {
+              api_key: 'secret',
+              other_key: 'value',
+            },
+          },
+        }),
+        { mode: 0o600 }
+      );
+
+      const manager = new ConfigManager();
+      const config = manager.loadConfig();
+      expect(config.version).toBe('1.0.0');
+      expect(config.registryUrl).toBe('https://custom.registry.com');
+      expect(config.packages?.['@scope/pkg']?.api_key).toBe('secret');
+    });
+  });
+
 });

package/src/utils/config-manager.ts

@@ -2,6 +2,11 @@ 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';
+
 /**
  * Per-package user configuration (stores user_config values)
  */
@@ -10,7 +15,7 @@ export interface PackageConfig {
 }
 
 /**
- * Configuration structure
+ * Configuration structure (v1.0.0)
  */
 export interface MpakConfig {
   version: string;
@@ -19,6 +24,102 @@ export interface MpakConfig {
   packages?: Record<string, PackageConfig>;
 }
 
+/**
+ * Error thrown when config file is corrupted or invalid
+ */
+export class ConfigCorruptedError extends Error {
+  constructor(
+    message: string,
+    public readonly configPath: string,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'ConfigCorruptedError';
+  }
+}
+
+/**
+ * Validates that a parsed object conforms to the MpakConfig schema
+ */
+function validateConfig(data: unknown, configPath: string): MpakConfig {
+  if (typeof data !== 'object' || data === null) {
+    throw new ConfigCorruptedError(
+      'Config file must be a JSON object',
+      configPath
+    );
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  // 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 as Record<string, unknown>
+    )) {
+      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 as Record<string, unknown>
+      )) {
+        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 as MpakConfig;
+}
+
 /**
  * Configuration manager for CLI settings in ~/.mpak/config.json
  */
@@ -46,25 +147,38 @@ 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: string;
     try {
-      const configJson = readFileSync(this.configFile, 'utf8');
-      this.config = JSON.parse(configJson) as MpakConfig;
-      return this.config;
-    } catch {
-      this.config = {
-        version: '1.0.0',
-        lastUpdated: new Date().toISOString(),
-      };
-      this.saveConfig();
-      return this.config;
+      configJson = readFileSync(this.configFile, 'utf8');
+    } 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: unknown;
+    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;
   }
 
   private saveConfig(): void {