@operor/skills 0.1.0

package/src/__tests__/catalog.test.ts

@@ -0,0 +1,383 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import {
+  loadSkillCatalogFrom,
+  querySkillCatalog,
+  findSkillInCatalog,
+  catalogEntryToConfig,
+} from '../catalog.js';
+import type { SkillCatalog, SkillCatalogEntry } from '../catalog.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── Test Data ──────────────────────────────────────────────────────────────
+
+function makeCatalog(skills: SkillCatalogEntry[]): SkillCatalog {
+  return { version: 1, updatedAt: '2026-01-01T00:00:00.000Z', skills };
+}
+
+const shopifyEntry: SkillCatalogEntry = {
+  name: 'shopify',
+  displayName: 'Shopify',
+  description: 'Manage Shopify store — products, orders, customers',
+  category: 'commerce',
+  tags: ['ecommerce', 'shopify', 'orders'],
+  transport: 'stdio',
+  package: 'shopify-mcp',
+  command: 'npx',
+  args: ['-y', 'shopify-mcp'],
+  envVars: {
+    SHOPIFY_ACCESS_TOKEN: {
+      description: 'Shopify Admin API access token',
+      required: true,
+      placeholder: 'shpat_...',
+    },
+  },
+  tools: [
+    { name: 'get_products', description: 'List products' },
+    { name: 'get_orders', description: 'List orders' },
+  ],
+  maturity: 'official',
+  vendor: 'Shopify',
+  docsUrl: 'https://github.com/Shopify/shopify-mcp',
+};
+
+const stripeEntry: SkillCatalogEntry = {
+  name: 'stripe',
+  displayName: 'Stripe',
+  description: 'Process payments and manage subscriptions via Stripe',
+  category: 'payments',
+  tags: ['payments', 'stripe', 'billing'],
+  transport: 'stdio',
+  package: '@stripe/mcp',
+  command: 'npx',
+  args: ['-y', '@stripe/mcp', '--tools=all'],
+  envVars: {
+    STRIPE_SECRET_KEY: {
+      description: 'Stripe secret API key',
+      required: true,
+    },
+  },
+  tools: [
+    { name: 'create_payment_intent', description: 'Create a payment' },
+  ],
+  maturity: 'official',
+  vendor: 'Stripe',
+};
+
+const searchEntry: SkillCatalogEntry = {
+  name: 'search',
+  displayName: 'Brave Search',
+  description: 'Web search via Brave Search API',
+  category: 'search',
+  tags: ['search', 'web', 'brave'],
+  transport: 'stdio',
+  package: '@modelcontextprotocol/server-brave-search',
+  envVars: {
+    BRAVE_API_KEY: { description: 'Brave API key', required: true },
+  },
+  tools: [
+    { name: 'brave_web_search', description: 'Search the web' },
+  ],
+  maturity: 'official',
+  vendor: 'Anthropic',
+};
+
+const httpEntry: SkillCatalogEntry = {
+  name: 'remote-api',
+  displayName: 'Remote API',
+  description: 'A remote HTTP-based skill',
+  category: 'other',
+  tags: ['remote', 'api'],
+  transport: 'http',
+  url: 'https://api.example.com/mcp',
+  envVars: {},
+  tools: [{ name: 'call_api', description: 'Call the API' }],
+  maturity: 'community',
+  vendor: 'Example Inc',
+};
+
+// ─── loadSkillCatalogFrom ───────────────────────────────────────────────────
+
+describe('loadSkillCatalogFrom', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = join(tmpdir(), `catalog-test-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('loads a valid catalog JSON file', () => {
+    const catalog = makeCatalog([shopifyEntry]);
+    const filePath = join(tmpDir, 'catalog.json');
+    writeFileSync(filePath, JSON.stringify(catalog));
+
+    const loaded = loadSkillCatalogFrom(filePath);
+    expect(loaded.version).toBe(1);
+    expect(loaded.skills).toHaveLength(1);
+    expect(loaded.skills[0].name).toBe('shopify');
+  });
+
+  it('throws on invalid JSON', () => {
+    const filePath = join(tmpDir, 'bad.json');
+    writeFileSync(filePath, '{ not valid json !!!');
+    expect(() => loadSkillCatalogFrom(filePath)).toThrow();
+  });
+
+  it('throws on missing file', () => {
+    expect(() => loadSkillCatalogFrom(join(tmpDir, 'nope.json'))).toThrow();
+  });
+});
+
+// ─── querySkillCatalog ──────────────────────────────────────────────────────
+
+describe('querySkillCatalog', () => {
+  const catalog = makeCatalog([shopifyEntry, stripeEntry, searchEntry, httpEntry]);
+
+  it('returns all skills when no filter is provided', () => {
+    const results = querySkillCatalog(catalog);
+    expect(results).toHaveLength(4);
+  });
+
+  it('returns all skills with empty filter object', () => {
+    const results = querySkillCatalog(catalog, {});
+    expect(results).toHaveLength(4);
+  });
+
+  it('filters by category', () => {
+    const results = querySkillCatalog(catalog, { category: 'commerce' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('shopify');
+  });
+
+  it('returns empty for non-matching category', () => {
+    const results = querySkillCatalog(catalog, { category: 'crm' });
+    expect(results).toHaveLength(0);
+  });
+
+  it('filters by maturity', () => {
+    const results = querySkillCatalog(catalog, { maturity: 'community' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('remote-api');
+  });
+
+  it('filters by tags', () => {
+    const results = querySkillCatalog(catalog, { tags: ['payments'] });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('stripe');
+  });
+
+  it('filters by multiple tags (OR logic)', () => {
+    const results = querySkillCatalog(catalog, { tags: ['ecommerce', 'web'] });
+    expect(results).toHaveLength(2);
+    const names = results.map(r => r.name);
+    expect(names).toContain('shopify');
+    expect(names).toContain('search');
+  });
+
+  it('searches by name', () => {
+    const results = querySkillCatalog(catalog, { search: 'shopify' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('shopify');
+  });
+
+  it('searches by displayName', () => {
+    const results = querySkillCatalog(catalog, { search: 'Brave' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('search');
+  });
+
+  it('searches by description', () => {
+    const results = querySkillCatalog(catalog, { search: 'subscriptions' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('stripe');
+  });
+
+  it('search is case-insensitive', () => {
+    const results = querySkillCatalog(catalog, { search: 'SHOPIFY' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('shopify');
+  });
+
+  it('combines category + search filters', () => {
+    // Both shopify and stripe are official, but only shopify matches "orders"
+    const results = querySkillCatalog(catalog, { maturity: 'official', search: 'orders' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('shopify');
+  });
+
+  it('returns empty when combined filters match nothing', () => {
+    const results = querySkillCatalog(catalog, { category: 'commerce', search: 'payments' });
+    expect(results).toHaveLength(0);
+  });
+
+  it('searches tags too', () => {
+    const results = querySkillCatalog(catalog, { search: 'billing' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('stripe');
+  });
+});
+
+// ─── findSkillInCatalog ─────────────────────────────────────────────────────
+
+describe('findSkillInCatalog', () => {
+  const catalog = makeCatalog([shopifyEntry, stripeEntry]);
+
+  it('finds a skill by exact name', () => {
+    const result = findSkillInCatalog(catalog, 'shopify');
+    expect(result).toBeDefined();
+    expect(result!.displayName).toBe('Shopify');
+  });
+
+  it('returns undefined for non-existent skill', () => {
+    const result = findSkillInCatalog(catalog, 'nonexistent');
+    expect(result).toBeUndefined();
+  });
+
+  it('is case-sensitive', () => {
+    const result = findSkillInCatalog(catalog, 'Shopify');
+    expect(result).toBeUndefined();
+  });
+});
+
+// ─── catalogEntryToConfig ───────────────────────────────────────────────────
+
+describe('catalogEntryToConfig', () => {
+  it('converts a stdio skill with package', () => {
+    const config = catalogEntryToConfig(shopifyEntry);
+    expect(config.name).toBe('shopify');
+    expect(config.transport).toBe('stdio');
+    expect(config.command).toBe('npx');
+    expect(config.args).toEqual(['-y', 'shopify-mcp']);
+    expect(config.enabled).toBe(true);
+    expect(config.env).toEqual({ SHOPIFY_ACCESS_TOKEN: '${SHOPIFY_ACCESS_TOKEN}' });
+  });
+
+  it('converts a stdio skill with explicit args', () => {
+    const config = catalogEntryToConfig(stripeEntry);
+    expect(config.args).toEqual(['-y', '@stripe/mcp', '--tools=all']);
+  });
+
+  it('converts a stdio skill without explicit command (defaults to npx)', () => {
+    const config = catalogEntryToConfig(searchEntry);
+    expect(config.command).toBe('npx');
+    expect(config.args).toEqual(['-y', '@modelcontextprotocol/server-brave-search']);
+  });
+
+  it('converts an http skill with url', () => {
+    const config = catalogEntryToConfig(httpEntry);
+    expect(config.transport).toBe('http');
+    expect(config.url).toBe('https://api.example.com/mcp');
+    expect(config.command).toBeUndefined();
+    expect(config.args).toBeUndefined();
+  });
+
+  it('omits env when no envVars', () => {
+    const config = catalogEntryToConfig(httpEntry);
+    expect(config.env).toBeUndefined();
+  });
+
+  it('maps multiple env vars to placeholder syntax', () => {
+    const entry: SkillCatalogEntry = {
+      ...shopifyEntry,
+      envVars: {
+        TOKEN_A: { description: 'Token A', required: true },
+        TOKEN_B: { description: 'Token B', required: false },
+      },
+    };
+    const config = catalogEntryToConfig(entry);
+    expect(config.env).toEqual({
+      TOKEN_A: '${TOKEN_A}',
+      TOKEN_B: '${TOKEN_B}',
+    });
+  });
+
+  it('converts an sse skill with url', () => {
+    const sseEntry: SkillCatalogEntry = {
+      ...httpEntry,
+      name: 'sse-skill',
+      transport: 'sse',
+      url: 'https://sse.example.com/events',
+    };
+    const config = catalogEntryToConfig(sseEntry);
+    expect(config.transport).toBe('sse');
+    expect(config.url).toBe('https://sse.example.com/events');
+  });
+});
+
+// ─── Shipped skill-catalog.json Integration ─────────────────────────────────
+
+describe('shipped skill-catalog.json', () => {
+  const catalogPath = resolve(__dirname, '..', '..', 'skill-catalog.json');
+
+  it('file exists at expected path', () => {
+    expect(existsSync(catalogPath)).toBe(true);
+  });
+
+  it('loads and parses without errors', () => {
+    const catalog = loadSkillCatalogFrom(catalogPath);
+    expect(catalog.version).toBe(1);
+    expect(catalog.updatedAt).toBeDefined();
+    expect(Array.isArray(catalog.skills)).toBe(true);
+  });
+
+  it('contains at least one skill', () => {
+    const catalog = loadSkillCatalogFrom(catalogPath);
+    expect(catalog.skills.length).toBeGreaterThan(0);
+  });
+
+  it('every entry has required fields', () => {
+    const catalog = loadSkillCatalogFrom(catalogPath);
+    for (const skill of catalog.skills) {
+      expect(skill.name).toBeTruthy();
+      expect(skill.displayName).toBeTruthy();
+      expect(skill.description).toBeTruthy();
+      expect(skill.category).toBeTruthy();
+      expect(skill.maturity).toMatch(/^(official|community|experimental)$/);
+      expect(skill.vendor).toBeTruthy();
+      expect(Array.isArray(skill.tags)).toBe(true);
+      if ((skill as any).type === 'prompt') {
+        expect((skill as any).content).toBeTruthy();
+      } else {
+        expect((skill as any).transport).toMatch(/^(stdio|http|sse)$/);
+        expect(Array.isArray((skill as any).tools)).toBe(true);
+        expect((skill as any).tools.length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it('every entry converts to a valid config', () => {
+    const catalog = loadSkillCatalogFrom(catalogPath);
+    for (const skill of catalog.skills) {
+      const config = catalogEntryToConfig(skill);
+      expect(config.name).toBe(skill.name);
+      expect(config.enabled).toBe(true);
+      if ((skill as any).type === 'prompt') {
+        expect(config.type).toBe('prompt');
+        expect(config.content).toBeTruthy();
+      } else {
+        expect(config.transport).toBe((skill as any).transport);
+      }
+    }
+  });
+
+  it('query helpers work against real data', () => {
+    const catalog = loadSkillCatalogFrom(catalogPath);
+    // findSkillInCatalog should find the first skill by name
+    const first = catalog.skills[0];
+    const found = findSkillInCatalog(catalog, first.name);
+    expect(found).toBeDefined();
+    expect(found!.name).toBe(first.name);
+
+    // querySkillCatalog with no filter returns all
+    const all = querySkillCatalog(catalog);
+    expect(all).toHaveLength(catalog.skills.length);
+  });
+});

package/src/__tests__/config.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { resolveEnvVars, resolveEnvRecord, loadSkillsConfig } from '../config.js';
+import { SkillManager } from '../SkillManager.js';
+import { writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('resolveEnvVars', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('resolves a single env var', () => {
+    process.env.MY_TOKEN = 'secret123';
+    expect(resolveEnvVars('Bearer ${MY_TOKEN}')).toBe('Bearer secret123');
+  });
+
+  it('resolves multiple env vars', () => {
+    process.env.HOST = 'localhost';
+    process.env.PORT = '3000';
+    expect(resolveEnvVars('http://${HOST}:${PORT}')).toBe('http://localhost:3000');
+  });
+
+  it('returns empty string for missing env vars', () => {
+    expect(resolveEnvVars('${DOES_NOT_EXIST}')).toBe('');
+  });
+
+  it('passes through strings without env vars', () => {
+    expect(resolveEnvVars('plain text')).toBe('plain text');
+  });
+});
+
+describe('resolveEnvRecord', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('resolves all values in a record', () => {
+    process.env.API_KEY = 'key123';
+    process.env.SECRET = 'sec456';
+    const result = resolveEnvRecord({
+      Authorization: 'Bearer ${API_KEY}',
+      'X-Secret': '${SECRET}',
+    });
+    expect(result).toEqual({
+      Authorization: 'Bearer key123',
+      'X-Secret': 'sec456',
+    });
+  });
+});
+
+describe('loadSkillsConfig', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = join(tmpdir(), `skills-test-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns empty skills when no mcp.json exists', () => {
+    const config = loadSkillsConfig(tmpDir);
+    expect(config.skills).toEqual([]);
+  });
+
+  it('loads skills from mcp.json', () => {
+    const mcpConfig = {
+      skills: [
+        {
+          name: 'shopify',
+          transport: 'stdio',
+          command: 'npx',
+          args: ['-y', 'shopify-mcp'],
+          env: { SHOPIFY_TOKEN: '${SHOPIFY_ACCESS_TOKEN}' },
+        },
+        {
+          name: 'search',
+          transport: 'http',
+          url: 'https://search.example.com/mcp',
+          enabled: false,
+        },
+      ],
+    };
+    writeFileSync(join(tmpDir, 'mcp.json'), JSON.stringify(mcpConfig));
+
+    const config = loadSkillsConfig(tmpDir);
+    expect(config.skills).toHaveLength(2);
+    expect(config.skills[0].name).toBe('shopify');
+    expect(config.skills[0].transport).toBe('stdio');
+    expect(config.skills[1].enabled).toBe(false);
+  });
+
+  it('handles empty mcp.json', () => {
+    writeFileSync(join(tmpDir, 'mcp.json'), '{}');
+    const config = loadSkillsConfig(tmpDir);
+    expect(config.skills).toEqual([]);
+  });
+
+  it('throws on invalid JSON', () => {
+    writeFileSync(join(tmpDir, 'mcp.json'), '{ broken json !!!');
+    expect(() => loadSkillsConfig(tmpDir)).toThrow('Invalid JSON');
+  });
+});
+
+describe('SkillManager.validateConfig', () => {
+  it('returns null for valid stdio config', () => {
+    expect(SkillManager.validateConfig({
+      name: 'test',
+      transport: 'stdio',
+      command: 'node',
+      args: ['server.js'],
+    })).toBeNull();
+  });
+
+  it('returns null for valid http config', () => {
+    expect(SkillManager.validateConfig({
+      name: 'test',
+      transport: 'http',
+      url: 'http://localhost:3000/mcp',
+    })).toBeNull();
+  });
+
+  it('returns null for valid sse config', () => {
+    expect(SkillManager.validateConfig({
+      name: 'test',
+      transport: 'sse',
+      url: 'http://localhost:3000/sse',
+    })).toBeNull();
+  });
+
+  it('returns error for missing name', () => {
+    expect(SkillManager.validateConfig({
+      name: '',
+      transport: 'stdio',
+      command: 'node',
+    })).toContain('name');
+  });
+
+  it('returns error for invalid transport', () => {
+    expect(SkillManager.validateConfig({
+      name: 'test',
+      transport: 'invalid' as any,
+    })).toContain('transport');
+  });
+
+  it('returns error for stdio without command', () => {
+    expect(SkillManager.validateConfig({
+      name: 'test',
+      transport: 'stdio',
+    })).toContain('command');
+  });
+
+  it('returns error for http without url', () => {
+    expect(SkillManager.validateConfig({
+      name: 'test',
+      transport: 'http',
+    })).toContain('url');
+  });
+
+  it('returns error for sse without url', () => {
+    expect(SkillManager.validateConfig({
+      name: 'test',
+      transport: 'sse',
+    })).toContain('url');
+  });
+});