vellum 0.2.1 → 0.2.7

package/src/commands/__tests__/cc-command-registry.test.ts

@@ -0,0 +1,319 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  discoverCCCommands,
+  getCCCommand,
+  loadCCCommandTemplate,
+  invalidateCCCommandCache,
+} from '../cc-command-registry.js';
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), 'cc-cmd-test-'));
+  invalidateCCCommandCache();
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+  invalidateCCCommandCache();
+});
+
+/** Helper to create a .claude/commands/ directory with markdown files. */
+function createCommandsDir(base: string, files: Record<string, string>): void {
+  const commandsDir = join(base, '.claude', 'commands');
+  mkdirSync(commandsDir, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    writeFileSync(join(commandsDir, name), content, 'utf-8');
+  }
+}
+
+describe('discoverCCCommands', () => {
+  test('discovers commands in .claude/commands/', () => {
+    createCommandsDir(tmpDir, {
+      'hello.md': '# Hello World\nThis is the hello command.',
+      'deploy.md': 'Deploy the application to production.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.size).toBe(2);
+
+    const hello = registry.entries.get('hello');
+    expect(hello).toBeDefined();
+    expect(hello!.name).toBe('hello');
+    expect(hello!.summary).toBe('Hello World');
+    expect(hello!.source).toBe(tmpDir);
+
+    const deploy = registry.entries.get('deploy');
+    expect(deploy).toBeDefined();
+    expect(deploy!.name).toBe('deploy');
+    expect(deploy!.summary).toBe('Deploy the application to production.');
+  });
+
+  test('child directory commands override parent on name collisions', () => {
+    // Create parent commands
+    createCommandsDir(tmpDir, {
+      'shared.md': 'Parent version of shared command.',
+    });
+
+    // Create child directory with overriding command
+    const childDir = join(tmpDir, 'project');
+    mkdirSync(childDir, { recursive: true });
+    createCommandsDir(childDir, {
+      'shared.md': 'Child version of shared command.',
+    });
+
+    const registry = discoverCCCommands(childDir);
+    const shared = registry.entries.get('shared');
+    expect(shared).toBeDefined();
+    expect(shared!.summary).toBe('Child version of shared command.');
+    expect(shared!.source).toBe(childDir);
+  });
+
+  test('invalid filenames are skipped', () => {
+    createCommandsDir(tmpDir, {
+      'valid-name.md': 'A valid command.',
+      '.hidden.md': 'Hidden file should be skipped.',
+      '-starts-with-dash.md': 'Invalid start character.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.size).toBe(1);
+    expect(registry.entries.has('valid-name')).toBe(true);
+    expect(registry.entries.has('.hidden')).toBe(false);
+    expect(registry.entries.has('-starts-with-dash')).toBe(false);
+  });
+
+  test('non-.md files are ignored', () => {
+    createCommandsDir(tmpDir, {
+      'readme.txt': 'Not a markdown file.',
+      'command.md': 'A real command.',
+      'notes.json': '{}',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.size).toBe(1);
+    expect(registry.entries.has('command')).toBe(true);
+  });
+
+  test('empty directory returns empty registry', () => {
+    const commandsDir = join(tmpDir, '.claude', 'commands');
+    mkdirSync(commandsDir, { recursive: true });
+
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.size).toBe(0);
+  });
+
+  test('no .claude/commands/ directory returns empty registry', () => {
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.size).toBe(0);
+  });
+
+  test('commands from multiple ancestor levels are merged', () => {
+    // Parent has a unique command
+    createCommandsDir(tmpDir, {
+      'parent-only.md': 'Only in parent.',
+    });
+
+    // Child has a different command
+    const childDir = join(tmpDir, 'child');
+    mkdirSync(childDir, { recursive: true });
+    createCommandsDir(childDir, {
+      'child-only.md': 'Only in child.',
+    });
+
+    const registry = discoverCCCommands(childDir);
+    expect(registry.entries.size).toBe(2);
+    expect(registry.entries.has('parent-only')).toBe(true);
+    expect(registry.entries.has('child-only')).toBe(true);
+  });
+});
+
+describe('caching', () => {
+  test('cache returns same instance within TTL', () => {
+    createCommandsDir(tmpDir, {
+      'test.md': 'Test command.',
+    });
+
+    const first = discoverCCCommands(tmpDir);
+    const second = discoverCCCommands(tmpDir);
+    expect(first).toBe(second); // same object reference
+  });
+
+  test('invalidateCCCommandCache forces re-discovery', () => {
+    createCommandsDir(tmpDir, {
+      'test.md': 'Test command.',
+    });
+
+    const first = discoverCCCommands(tmpDir);
+
+    invalidateCCCommandCache();
+
+    const second = discoverCCCommands(tmpDir);
+    expect(first).not.toBe(second); // different object reference
+    expect(second.entries.size).toBe(1);
+  });
+
+  test('expired TTL forces re-discovery', () => {
+    createCommandsDir(tmpDir, {
+      'test.md': 'Test command.',
+    });
+
+    // Use a very short TTL
+    const first = discoverCCCommands(tmpDir, 0);
+    const second = discoverCCCommands(tmpDir, 0);
+    expect(first).not.toBe(second); // different object reference due to expired TTL
+  });
+});
+
+describe('getCCCommand', () => {
+  test('looks up command by name (case-insensitive)', () => {
+    createCommandsDir(tmpDir, {
+      'MyCommand.md': 'My command description.',
+    });
+
+    const entry = getCCCommand(tmpDir, 'mycommand');
+    expect(entry).toBeDefined();
+    expect(entry!.name).toBe('MyCommand');
+
+    const entryUpper = getCCCommand(tmpDir, 'MYCOMMAND');
+    expect(entryUpper).toBeDefined();
+    expect(entryUpper!.name).toBe('MyCommand');
+  });
+
+  test('returns undefined for non-existent command', () => {
+    createCommandsDir(tmpDir, {
+      'exists.md': 'I exist.',
+    });
+
+    const entry = getCCCommand(tmpDir, 'nonexistent');
+    expect(entry).toBeUndefined();
+  });
+});
+
+describe('loadCCCommandTemplate', () => {
+  test('reads full file content at execution time', () => {
+    const fullContent = '---\ntitle: Test\n---\n\n# Test Command\n\nThis is the full template body.\n\n## Arguments\n- arg1: required\n- arg2: optional\n';
+    createCommandsDir(tmpDir, {
+      'test.md': fullContent,
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('test')!;
+    expect(entry).toBeDefined();
+
+    const template = loadCCCommandTemplate(entry);
+    expect(template).toBe(fullContent);
+  });
+});
+
+describe('summary extraction', () => {
+  test('skips YAML frontmatter', () => {
+    createCommandsDir(tmpDir, {
+      'with-frontmatter.md': '---\ntitle: My Command\nauthor: test\n---\n\nActual summary line.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('with-frontmatter');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('Actual summary line.');
+  });
+
+  test('strips heading markers', () => {
+    createCommandsDir(tmpDir, {
+      'heading.md': '## This is a heading',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('heading');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('This is a heading');
+  });
+
+  test('strips multiple heading levels', () => {
+    createCommandsDir(tmpDir, {
+      'h1.md': '# H1 Heading',
+      'h3.md': '### H3 Heading',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.get('h1')!.summary).toBe('H1 Heading');
+    expect(registry.entries.get('h3')!.summary).toBe('H3 Heading');
+  });
+
+  test('skips empty lines before summary', () => {
+    createCommandsDir(tmpDir, {
+      'empty-lines.md': '\n\n\nFirst real line.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.get('empty-lines')!.summary).toBe('First real line.');
+  });
+
+  test('truncates summary to 100 characters', () => {
+    const longLine = 'A'.repeat(150);
+    createCommandsDir(tmpDir, {
+      'long.md': longLine,
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('long');
+    expect(entry).toBeDefined();
+    expect(entry!.summary.length).toBe(100);
+    expect(entry!.summary).toBe('A'.repeat(100));
+  });
+
+  test('handles file with only frontmatter and no content', () => {
+    createCommandsDir(tmpDir, {
+      'empty-body.md': '---\ntitle: Empty\n---\n',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('empty-body');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('');
+  });
+
+  test('handles frontmatter with Windows-style line endings', () => {
+    createCommandsDir(tmpDir, {
+      'crlf.md': '---\r\ntitle: Test\r\n---\r\n\r\nSummary with CRLF.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('crlf');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('Summary with CRLF.');
+  });
+});
+
+describe('command name validation', () => {
+  test('accepts valid names with dots, dashes, underscores', () => {
+    createCommandsDir(tmpDir, {
+      'my-command.md': 'Dashed name.',
+      'my_command.md': 'Underscored name.',
+      'my.command.md': 'Dotted name.',
+      'Command123.md': 'Alphanumeric.',
+      'a.md': 'Single char.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.has('my-command')).toBe(true);
+    expect(registry.entries.has('my_command')).toBe(true);
+    expect(registry.entries.has('my.command')).toBe(true);
+    expect(registry.entries.has('command123')).toBe(true);
+    expect(registry.entries.has('a')).toBe(true);
+  });
+
+  test('rejects names starting with special characters', () => {
+    createCommandsDir(tmpDir, {
+      '_start.md': 'Starts with underscore.',
+      '.start.md': 'Starts with dot.',
+      '-start.md': 'Starts with dash.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    expect(registry.entries.size).toBe(0);
+  });
+});

package/src/commands/cc-command-registry.ts

@@ -0,0 +1,209 @@
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('cc-commands');
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface CCCommandEntry {
+  /** Command name: basename without .md extension. */
+  name: string;
+  /** First non-empty line after frontmatter, stripped of heading markers. */
+  summary: string;
+  /** Absolute path to the .md file. */
+  filePath: string;
+  /** Directory containing the `.claude/commands/` folder. */
+  source: string;
+}
+
+export interface CCCommandRegistry {
+  /** Commands keyed by lowercase name. */
+  entries: Map<string, CCCommandEntry>;
+  /** Timestamp (ms) when discovery was performed. */
+  discoveredAt: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const COMMAND_NAME_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const FRONTMATTER_REGEX = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/;
+const DEFAULT_CACHE_TTL_MS = 30_000;
+const MAX_SUMMARY_LENGTH = 100;
+
+/**
+ * Maximum bytes to read from each command file during discovery.
+ * 1 KiB is enough for frontmatter (typically < 200 B) plus several content
+ * lines, which is all we need to extract a one-line summary.
+ */
+const SUMMARY_READ_BYTES = 1024;
+
+// ─── Cache ───────────────────────────────────────────────────────────────────
+
+const cache = new Map<string, CCCommandRegistry>();
+
+/** Clear all cached registries. */
+export function invalidateCCCommandCache(): void {
+  cache.clear();
+  log.debug('CC command cache invalidated');
+}
+
+// ─── Partial I/O ─────────────────────────────────────────────────────────────
+
+/**
+ * Read at most `maxBytes` from the beginning of a file.
+ * Uses low-level `openSync`/`readSync` so we never pull the entire file into
+ * memory — important when command templates are large but we only need the
+ * first few lines for summary extraction.
+ */
+function readFileHead(filePath: string, maxBytes: number): string {
+  const fd = openSync(filePath, 'r');
+  try {
+    const buf = Buffer.alloc(maxBytes);
+    const bytesRead = readSync(fd, buf, 0, maxBytes, 0);
+    return buf.toString('utf-8', 0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// ─── Summary extraction ──────────────────────────────────────────────────────
+
+/**
+ * Extract a one-line summary from the beginning of a markdown file.
+ * Skips YAML frontmatter if present, then returns the first non-empty line
+ * with leading `#` heading markers stripped. Truncates to 100 chars.
+ */
+function extractSummary(content: string): string {
+  // Strip frontmatter if present
+  let body = content;
+  const fmMatch = content.match(FRONTMATTER_REGEX);
+  if (fmMatch) {
+    body = content.slice(fmMatch[0].length);
+  }
+
+  // Find first non-empty line
+  const lines = body.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Strip leading # heading markers
+    const stripped = trimmed.replace(/^#+\s*/, '');
+    if (!stripped) continue;
+
+    // Truncate if needed
+    if (stripped.length > MAX_SUMMARY_LENGTH) {
+      return stripped.slice(0, MAX_SUMMARY_LENGTH);
+    }
+    return stripped;
+  }
+
+  return '';
+}
+
+// ─── Discovery ───────────────────────────────────────────────────────────────
+
+/**
+ * Discover `.claude/commands/*.md` files by walking up from `cwd`.
+ * Nearest directory wins on name collisions (child overrides parent).
+ * Results are cached per cwd with a 30-second TTL.
+ */
+export function discoverCCCommands(cwd: string, ttlMs: number = DEFAULT_CACHE_TTL_MS): CCCommandRegistry {
+  const resolvedCwd = resolve(cwd);
+
+  // Check cache
+  const cached = cache.get(resolvedCwd);
+  if (cached && (Date.now() - cached.discoveredAt) < ttlMs) {
+    log.debug({ cwd: resolvedCwd }, 'CC command cache hit');
+    return cached;
+  }
+
+  log.debug({ cwd: resolvedCwd }, 'CC command cache miss, discovering commands');
+
+  const entries = new Map<string, CCCommandEntry>();
+  let current = resolvedCwd;
+
+  // Walk up the directory tree; collect commands from each level.
+  // Since child directories should win on name collisions, we only add entries
+  // that haven't been seen yet (first occurrence = nearest ancestor).
+  while (true) {
+    const commandsDir = join(current, '.claude', 'commands');
+
+    if (existsSync(commandsDir)) {
+      try {
+        const files = readdirSync(commandsDir, { withFileTypes: true });
+        for (const file of files) {
+          if (!file.isFile()) continue;
+          if (!file.name.endsWith('.md')) continue;
+
+          const nameWithoutExt = basename(file.name, '.md');
+
+          // Validate command name
+          if (!COMMAND_NAME_REGEX.test(nameWithoutExt)) {
+            log.warn({ fileName: file.name, dir: commandsDir }, 'Skipping invalid CC command filename');
+            continue;
+          }
+
+          const key = nameWithoutExt.toLowerCase();
+
+          // Child directories win — skip if already discovered from a closer ancestor
+          if (entries.has(key)) continue;
+
+          const filePath = join(commandsDir, file.name);
+
+          let summary = '';
+          try {
+            const head = readFileHead(filePath, SUMMARY_READ_BYTES);
+            summary = extractSummary(head);
+          } catch (err) {
+            log.warn({ err, filePath }, 'Failed to read CC command file for summary extraction');
+          }
+
+          entries.set(key, {
+            name: nameWithoutExt,
+            summary,
+            filePath,
+            source: current,
+          });
+        }
+      } catch (err) {
+        log.warn({ err, commandsDir }, 'Failed to read CC commands directory');
+      }
+    }
+
+    const parent = dirname(current);
+    if (parent === current) break; // reached filesystem root
+    current = parent;
+  }
+
+  log.debug({ cwd: resolvedCwd, count: entries.size }, 'CC command discovery complete');
+
+  const registry: CCCommandRegistry = {
+    entries,
+    discoveredAt: Date.now(),
+  };
+
+  cache.set(resolvedCwd, registry);
+  return registry;
+}
+
+// ─── Lookup ──────────────────────────────────────────────────────────────────
+
+/**
+ * Look up a single CC command by name (case-insensitive).
+ */
+export function getCCCommand(cwd: string, name: string): CCCommandEntry | undefined {
+  const registry = discoverCCCommands(cwd);
+  return registry.entries.get(name.toLowerCase());
+}
+
+// ─── Template loading ────────────────────────────────────────────────────────
+
+/**
+ * Load the full markdown content of a CC command file.
+ * This is deferred to execution time to avoid reading full files during discovery.
+ */
+export function loadCCCommandTemplate(entry: CCCommandEntry): string {
+  return readFileSync(entry.filePath, 'utf-8');
+}

package/src/config/bundled-skills/contacts/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: "Contacts"
+description: "Contact and relationship graph with multi-channel tracking and importance scoring"
+metadata: {"vellum": {"emoji": "\ud83d\udcca"}}
+---
+
+Manage the user's contact and relationship graph. Each contact can have multiple communication channels, an importance score, and interaction tracking.
+
+## Contact Fields
+
+- **display_name** -- the contact's name (required)
+- **relationship** -- e.g. colleague, friend, manager, client, family
+- **importance** -- score from 0 to 1 (default 0.5), higher means more important
+- **response_expectation** -- expected response speed: immediate, within_hours, within_day, casual
+- **preferred_tone** -- communication tone: formal, casual, friendly, professional
+- **channels** -- list of communication channels (email, slack, whatsapp, phone, telegram, discord, other)
+
+## Channel Types
+
+Supported channel types: `email`, `slack`, `whatsapp`, `phone`, `telegram`, `discord`, `other`
+
+Each channel has:
+- **type** -- one of the supported channel types
+- **address** -- the channel-specific identifier (email address, phone number, handle, etc.)
+- **is_primary** -- whether this is the primary channel for its type
+
+## Merging Contacts
+
+When you discover two contacts are the same person (e.g. same person on email and Slack), use `contact_merge` to consolidate them. Merging:
+- Combines all channels from both contacts
+- Keeps the higher importance score
+- Sums interaction counts
+- Deletes the donor contact
+
+## Tips
+
+- Use `contact_search` with `channel_address` to find contacts by their email, phone, or handle.
+- When creating follow-ups, provide a `contact_id` to link the follow-up to a specific contact for grace period calculations.
+- Contacts with higher importance scores get shorter default response deadlines.

package/src/config/bundled-skills/contacts/TOOLS.json

@@ -0,0 +1,122 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "contact_upsert",
+      "description": "Create or update a contact in the relationship graph. Use this to track people the user interacts with across channels (email, Slack, etc.).",
+      "category": "contacts",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Contact ID to update. Omit to create a new contact (or auto-match by channel address)."
+          },
+          "display_name": {
+            "type": "string",
+            "description": "Display name for the contact"
+          },
+          "relationship": {
+            "type": "string",
+            "description": "Relationship type (e.g. colleague, friend, manager, client, family)"
+          },
+          "importance": {
+            "type": "number",
+            "description": "Importance score 0-1 (default 0.5). Higher = more important."
+          },
+          "response_expectation": {
+            "type": "string",
+            "description": "Expected response speed (e.g. immediate, within_hours, within_day, casual)"
+          },
+          "preferred_tone": {
+            "type": "string",
+            "description": "Preferred communication tone (e.g. formal, casual, friendly, professional)"
+          },
+          "channels": {
+            "type": "array",
+            "description": "Communication channels for this contact",
+            "items": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": ["email", "slack", "whatsapp", "phone", "telegram", "discord", "other"],
+                  "description": "Channel type"
+                },
+                "address": {
+                  "type": "string",
+                  "description": "Channel address (email address, Slack handle, phone number, etc.)"
+                },
+                "is_primary": {
+                  "type": "boolean",
+                  "description": "Whether this is the primary channel for this type"
+                }
+              },
+              "required": ["type", "address"]
+            }
+          }
+        },
+        "required": ["display_name"]
+      },
+      "executor": "tools/contact-upsert.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "contact_search",
+      "description": "Search for contacts by name, channel address, relationship type, or other criteria. Returns matching contacts with their channel information.",
+      "category": "contacts",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search by display name (partial match)"
+          },
+          "channel_address": {
+            "type": "string",
+            "description": "Search by channel address (email, phone, handle — partial match)"
+          },
+          "channel_type": {
+            "type": "string",
+            "description": "Filter by channel type when searching by address (email, slack, whatsapp, phone, etc.)"
+          },
+          "relationship": {
+            "type": "string",
+            "description": "Filter by relationship type (exact match)"
+          },
+          "limit": {
+            "type": "number",
+            "description": "Maximum results to return (default 20, max 100)"
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/contact-search.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "contact_merge",
+      "description": "Merge two contacts when you discover they are the same person (e.g. same person on email and Slack). Combines channels, keeps the higher importance, and deletes the donor contact.",
+      "category": "contacts",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "keep_id": {
+            "type": "string",
+            "description": "ID of the contact to keep (the surviving contact)"
+          },
+          "merge_id": {
+            "type": "string",
+            "description": "ID of the contact to merge into the kept contact (will be deleted)"
+          }
+        },
+        "required": ["keep_id", "merge_id"]
+      },
+      "executor": "tools/contact-merge.ts",
+      "execution_target": "host"
+    }
+  ]
+}