@operor/skills 0.1.0

package/src/catalog.ts

@@ -0,0 +1,213 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ─── Catalog Schema ─────────────────────────────────────────────────────────
+
+/** A single MCP skill entry in the catalog. */
+export interface MCPSkillCatalogEntry {
+  type?: 'mcp';
+  name: string;
+  displayName: string;
+  description: string;
+  category: SkillCategory;
+  tags: string[];
+  transport: 'stdio' | 'http' | 'sse';
+  package?: string;
+  command?: string;
+  args?: string[];
+  url?: string;
+  envVars: Record<string, EnvVarSpec>;
+  tools: SkillToolSummary[];
+  maturity: 'official' | 'community' | 'experimental';
+  vendor: string;
+  docsUrl?: string;
+  version?: string;
+  updatedAt?: string;
+}
+
+/** A prompt skill entry in the catalog — behavioral instructions, no tools. */
+export interface PromptSkillCatalogEntry {
+  type: 'prompt';
+  name: string;
+  displayName: string;
+  description: string;
+  category: SkillCategory;
+  tags: string[];
+  content: string;
+  maturity: 'official' | 'community' | 'experimental';
+  vendor: string;
+  version?: string;
+  updatedAt?: string;
+}
+
+/** A single skill entry in the catalog — the "app store" listing. */
+export type SkillCatalogEntry = MCPSkillCatalogEntry | PromptSkillCatalogEntry;
+
+export function isPromptCatalogEntry(entry: SkillCatalogEntry): entry is PromptSkillCatalogEntry {
+  return (entry as any).type === 'prompt';
+}
+
+export type SkillCategory =
+  | 'commerce'
+  | 'payments'
+  | 'crm'
+  | 'support'
+  | 'marketing'
+  | 'search'
+  | 'analytics'
+  | 'communication'
+  | 'productivity'
+  | 'developer'
+  | 'other';
+
+/** Describes an env var a skill needs. */
+export interface EnvVarSpec {
+  /** What this env var is for */
+  description: string;
+  /** Whether the skill cannot function without it */
+  required: boolean;
+  /** Hint for the setup wizard (e.g. "sk-..." or "https://...") */
+  placeholder?: string;
+}
+
+/** Summary of a tool exposed by a skill — for catalog display, not runtime. */
+export interface SkillToolSummary {
+  /** Tool name as exposed by the MCP server */
+  name: string;
+  /** What this tool does */
+  description: string;
+}
+
+/** The top-level catalog file structure. */
+export interface SkillCatalog {
+  /** Schema version for forward compatibility */
+  version: number;
+  /** When the catalog was last generated */
+  updatedAt: string;
+  /** The skill entries */
+  skills: SkillCatalogEntry[];
+}
+
+// ─── Catalog Loader ─────────────────────────────────────────────────────────
+
+/**
+ * Load the built-in skill catalog shipped with @operor/skills.
+ * Falls back to empty catalog if file is missing.
+ */
+export function loadSkillCatalog(): SkillCatalog {
+  const catalogPath = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    '..',
+    'skill-catalog.json',
+  );
+
+  if (!existsSync(catalogPath)) {
+    return { version: 1, updatedAt: new Date().toISOString(), skills: [] };
+  }
+
+  const raw = readFileSync(catalogPath, 'utf-8');
+  return JSON.parse(raw) as SkillCatalog;
+}
+
+/**
+ * Load a custom/override catalog from a specific path.
+ */
+export function loadSkillCatalogFrom(filePath: string): SkillCatalog {
+  const raw = readFileSync(filePath, 'utf-8');
+  return JSON.parse(raw) as SkillCatalog;
+}
+
+// ─── Catalog Query Helpers ──────────────────────────────────────────────────
+
+/** Filter options for querying the catalog. */
+export interface CatalogFilter {
+  category?: SkillCategory;
+  maturity?: SkillCatalogEntry['maturity'];
+  search?: string;
+  tags?: string[];
+}
+
+/**
+ * Query the catalog with optional filters.
+ * Search matches against name, displayName, description, and tags.
+ */
+export function querySkillCatalog(
+  catalog: SkillCatalog,
+  filter?: CatalogFilter,
+): SkillCatalogEntry[] {
+  let results = catalog.skills;
+
+  if (filter?.category) {
+    results = results.filter((s) => s.category === filter.category);
+  }
+
+  if (filter?.maturity) {
+    results = results.filter((s) => s.maturity === filter.maturity);
+  }
+
+  if (filter?.tags && filter.tags.length > 0) {
+    const filterTags = filter.tags.map((t) => t.toLowerCase());
+    results = results.filter((s) =>
+      filterTags.some((ft) => s.tags.some((st) => st.toLowerCase().includes(ft))),
+    );
+  }
+
+  if (filter?.search) {
+    const q = filter.search.toLowerCase();
+    results = results.filter(
+      (s) =>
+        s.name.toLowerCase().includes(q) ||
+        s.displayName.toLowerCase().includes(q) ||
+        s.description.toLowerCase().includes(q) ||
+        s.tags.some((t) => t.toLowerCase().includes(q)),
+    );
+  }
+
+  return results;
+}
+
+/**
+ * Look up a single skill by name.
+ */
+export function findSkillInCatalog(
+  catalog: SkillCatalog,
+  name: string,
+): SkillCatalogEntry | undefined {
+  return catalog.skills.find((s) => s.name === name);
+}
+
+/**
+ * Convert a catalog entry into a config suitable for mcp.json.
+ * Handles both MCP and prompt skill entries.
+ */
+export function catalogEntryToConfig(entry: SkillCatalogEntry): Record<string, any> {
+  if (isPromptCatalogEntry(entry)) {
+    return { type: 'prompt', name: entry.name, content: entry.content, enabled: true };
+  }
+
+  const config: Record<string, any> = {
+    name: entry.name,
+    transport: entry.transport,
+    enabled: true,
+  };
+
+  if (entry.transport === 'stdio') {
+    config.command = entry.command ?? 'npx';
+    config.args = entry.args ?? (entry.package ? ['-y', entry.package] : []);
+  }
+
+  if ((entry.transport === 'http' || entry.transport === 'sse') && entry.url) {
+    config.url = entry.url;
+  }
+
+  const envKeys = Object.keys(entry.envVars);
+  if (envKeys.length > 0) {
+    config.env = {};
+    for (const key of envKeys) {
+      config.env[key] = `\${${key}}`;
+    }
+  }
+
+  return config;
+}

package/src/config.ts

@@ -0,0 +1,95 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export interface MCPSkillConfig {
+  name: string;
+  transport: 'stdio' | 'http' | 'sse';
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  headers?: Record<string, string>;
+  toolPrefix?: string;
+  enabled?: boolean;
+}
+
+export interface PromptSkillConfig {
+  type: 'prompt';
+  name: string;
+  summary?: string;
+  version?: string;
+  tags?: string[];
+  author?: string;
+  content: string;
+  enabled?: boolean;
+}
+
+export type AnySkillConfig = (MCPSkillConfig & { type?: 'mcp' }) | PromptSkillConfig;
+
+export function isPromptSkillConfig(config: AnySkillConfig): config is PromptSkillConfig {
+  return (config as any).type === 'prompt';
+}
+
+export function isMCPSkillConfig(config: AnySkillConfig): config is MCPSkillConfig & { type?: 'mcp' } {
+  return !isPromptSkillConfig(config);
+}
+
+export interface SkillsConfig {
+  skills: AnySkillConfig[];
+}
+
+/**
+ * Resolve `${ENV_VAR}` placeholders in a string value.
+ */
+export function resolveEnvVars(value: string): string {
+  return value.replace(/\$\{([^}]+)\}/g, (_match, envVar) => {
+    return process.env[envVar] ?? '';
+  });
+}
+
+/**
+ * Resolve env vars in all values of a record.
+ */
+export function resolveEnvRecord(record: Record<string, string>): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(record)) {
+    resolved[key] = resolveEnvVars(value);
+  }
+  return resolved;
+}
+
+/**
+ * Load skills config from `mcp.json` at the given root (defaults to cwd).
+ * Returns empty config if file doesn't exist.
+ */
+export function loadSkillsConfig(root?: string): SkillsConfig {
+  const configPath = resolve(root ?? process.cwd(), 'mcp.json');
+
+  if (!existsSync(configPath)) {
+    return { skills: [] };
+  }
+
+  const raw = readFileSync(configPath, 'utf-8');
+
+  let parsed: any;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Invalid JSON in ${configPath}`);
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    return { skills: [] };
+  }
+
+  const skills: AnySkillConfig[] = Array.isArray(parsed.skills) ? parsed.skills : [];
+  return { skills };
+}
+
+/**
+ * Save skills config to `mcp.json` at the given root (defaults to cwd).
+ */
+export function saveSkillsConfig(config: SkillsConfig, root?: string): void {
+  const configPath = resolve(root ?? process.cwd(), 'mcp.json');
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export { MCPSkill } from './MCPSkill.js';
+export { PromptSkill } from './PromptSkill.js';
+export { SkillManager } from './SkillManager.js';
+export {
+  loadSkillsConfig,
+  saveSkillsConfig,
+  resolveEnvVars,
+  resolveEnvRecord,
+  isPromptSkillConfig,
+  isMCPSkillConfig,
+} from './config.js';
+export type { MCPSkillConfig, PromptSkillConfig, AnySkillConfig, SkillsConfig } from './config.js';
+export {
+  loadSkillCatalog,
+  loadSkillCatalogFrom,
+  querySkillCatalog,
+  findSkillInCatalog,
+  catalogEntryToConfig,
+  isPromptCatalogEntry,
+} from './catalog.js';
+export type {
+  SkillCatalog,
+  SkillCatalogEntry,
+  MCPSkillCatalogEntry,
+  PromptSkillCatalogEntry,
+  SkillCategory,
+  SkillToolSummary,
+  EnvVarSpec,
+  CatalogFilter,
+} from './catalog.js';

package/test/catalog.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect } from 'vitest';
+import {
+  loadSkillCatalog,
+  loadSkillCatalogFrom,
+  querySkillCatalog,
+  findSkillInCatalog,
+  catalogEntryToConfig,
+} from '../src/catalog.js';
+import type { SkillCatalog, SkillCatalogEntry } from '../src/catalog.js';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+function makeEntry(overrides: Partial<SkillCatalogEntry> = {}): SkillCatalogEntry {
+  return {
+    name: 'test-skill',
+    displayName: 'Test Skill',
+    description: 'A test skill for unit tests',
+    category: 'commerce',
+    tags: ['test', 'ecommerce'],
+    transport: 'stdio',
+    package: 'test-mcp',
+    command: 'npx',
+    args: ['-y', 'test-mcp'],
+    envVars: {
+      TEST_API_KEY: { description: 'API key', required: true, placeholder: 'sk_...' },
+    },
+    tools: [{ name: 'do_thing', description: 'Does a thing' }],
+    maturity: 'community',
+    vendor: 'test-vendor',
+    ...overrides,
+  };
+}
+
+function makeCatalog(skills: SkillCatalogEntry[]): SkillCatalog {
+  return { version: 1, updatedAt: '2026-01-01T00:00:00.000Z', skills };
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('loadSkillCatalog', () => {
+  it('should load the built-in catalog', () => {
+    const catalog = loadSkillCatalog();
+    expect(catalog.version).toBe(1);
+    expect(catalog.skills.length).toBeGreaterThan(0);
+    expect(catalog.skills[0]).toHaveProperty('name');
+    expect(catalog.skills[0]).toHaveProperty('transport');
+  });
+
+  it('should include expected skills', () => {
+    const catalog = loadSkillCatalog();
+    const names = catalog.skills.map((s) => s.name);
+    expect(names).toContain('shopify');
+    expect(names).toContain('stripe');
+  });
+});
+
+describe('loadSkillCatalogFrom', () => {
+  it('should load catalog from a custom path', () => {
+    const catalogPath = resolve(__dirname, '..', 'skill-catalog.json');
+    const catalog = loadSkillCatalogFrom(catalogPath);
+    expect(catalog.version).toBe(1);
+    expect(catalog.skills.length).toBeGreaterThan(0);
+  });
+
+  it('should throw on missing file', () => {
+    expect(() => loadSkillCatalogFrom('/nonexistent/catalog.json')).toThrow();
+  });
+});
+
+describe('querySkillCatalog', () => {
+  const shopify = makeEntry({ name: 'shopify', category: 'commerce', tags: ['ecommerce', 'shopify'], maturity: 'community' });
+  const stripe = makeEntry({ name: 'stripe', category: 'payments', tags: ['payments', 'billing'], maturity: 'official' });
+  const zendesk = makeEntry({ name: 'zendesk', displayName: 'Zendesk', category: 'support', tags: ['support', 'tickets'], maturity: 'community' });
+  const catalog = makeCatalog([shopify, stripe, zendesk]);
+
+  it('should return all skills with no filter', () => {
+    const results = querySkillCatalog(catalog);
+    expect(results).toHaveLength(3);
+  });
+
+  it('should filter by category', () => {
+    const results = querySkillCatalog(catalog, { category: 'commerce' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('shopify');
+  });
+
+  it('should filter by maturity', () => {
+    const results = querySkillCatalog(catalog, { maturity: 'official' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('stripe');
+  });
+
+  it('should filter by tags', () => {
+    const results = querySkillCatalog(catalog, { tags: ['support'] });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('zendesk');
+  });
+
+  it('should search by name', () => {
+    const results = querySkillCatalog(catalog, { search: 'stripe' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('stripe');
+  });
+
+  it('should search by displayName', () => {
+    const results = querySkillCatalog(catalog, { search: 'Zendesk' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('zendesk');
+  });
+
+  it('should search case-insensitively', () => {
+    const results = querySkillCatalog(catalog, { search: 'SHOPIFY' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('shopify');
+  });
+
+  it('should combine category and search filters', () => {
+    const results = querySkillCatalog(catalog, { category: 'commerce', search: 'shopify' });
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('shopify');
+  });
+
+  it('should return empty for non-matching filters', () => {
+    const results = querySkillCatalog(catalog, { search: 'nonexistent' });
+    expect(results).toHaveLength(0);
+  });
+});
+
+describe('findSkillInCatalog', () => {
+  const catalog = makeCatalog([
+    makeEntry({ name: 'shopify' }),
+    makeEntry({ name: 'stripe' }),
+  ]);
+
+  it('should find a skill by name', () => {
+    const skill = findSkillInCatalog(catalog, 'shopify');
+    expect(skill).toBeDefined();
+    expect(skill!.name).toBe('shopify');
+  });
+
+  it('should return undefined for unknown skill', () => {
+    const skill = findSkillInCatalog(catalog, 'unknown');
+    expect(skill).toBeUndefined();
+  });
+});
+
+describe('catalogEntryToConfig', () => {
+  it('should convert a stdio skill to config', () => {
+    const entry = makeEntry({
+      name: 'shopify',
+      transport: 'stdio',
+      command: 'npx',
+      args: ['-y', 'shopify-mcp'],
+      envVars: {
+        SHOPIFY_TOKEN: { description: 'Token', required: true },
+      },
+    });
+
+    const config = catalogEntryToConfig(entry);
+    expect(config.name).toBe('shopify');
+    expect(config.transport).toBe('stdio');
+    expect(config.command).toBe('npx');
+    expect(config.args).toEqual(['-y', 'shopify-mcp']);
+    expect(config.env).toEqual({ SHOPIFY_TOKEN: '${SHOPIFY_TOKEN}' });
+    expect(config.enabled).toBe(true);
+  });
+
+  it('should default command to npx and args from package', () => {
+    const entry = makeEntry({
+      name: 'test',
+      transport: 'stdio',
+      package: 'test-mcp',
+      command: undefined,
+      args: undefined,
+    });
+
+    const config = catalogEntryToConfig(entry);
+    expect(config.command).toBe('npx');
+    expect(config.args).toEqual(['-y', 'test-mcp']);
+  });
+
+  it('should convert an http skill to config', () => {
+    const entry = makeEntry({
+      name: 'remote-skill',
+      transport: 'http',
+      url: 'https://api.example.com/mcp',
+      envVars: {},
+    });
+
+    const config = catalogEntryToConfig(entry);
+    expect(config.transport).toBe('http');
+    expect(config.url).toBe('https://api.example.com/mcp');
+    expect(config.command).toBeUndefined();
+    expect(config.env).toBeUndefined();
+  });
+
+  it('should omit env when no envVars', () => {
+    const entry = makeEntry({ envVars: {} });
+    const config = catalogEntryToConfig(entry);
+    expect(config.env).toBeUndefined();
+  });
+
+  it('should map multiple env vars to placeholder syntax', () => {
+    const entry = makeEntry({
+      envVars: {
+        API_KEY: { description: 'Key', required: true },
+        API_SECRET: { description: 'Secret', required: true },
+      },
+    });
+
+    const config = catalogEntryToConfig(entry);
+    expect(config.env).toEqual({
+      API_KEY: '${API_KEY}',
+      API_SECRET: '${API_SECRET}',
+    });
+  });
+});