@soleri/core 9.14.4 → 9.16.7

package/src/skills/validate-skills.ts

@@ -0,0 +1,470 @@
+/**
+ * Validator for user-installed SKILL.md op-call examples.
+ *
+ * Reads all SKILL.md files from a given skills directory (e.g. ~/.claude/skills/),
+ * extracts inline op-call examples, and validates their params against the actual
+ * Zod schemas from the facade layer.
+ *
+ * Returns structured results rather than printing or exiting — the CLI layer owns I/O.
+ */
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ZodType, ZodError } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from '../runtime/types.js';
+
+// ── Facade factory imports ──────────────────────────────────────────────
+import { createVaultFacadeOps } from '../runtime/facades/vault-facade.js';
+import { createPlanFacadeOps } from '../runtime/facades/plan-facade.js';
+import { createBrainFacadeOps } from '../runtime/facades/brain-facade.js';
+import { createMemoryFacadeOps } from '../runtime/facades/memory-facade.js';
+import { createAdminFacadeOps } from '../runtime/facades/admin-facade.js';
+import { createCuratorFacadeOps } from '../runtime/facades/curator-facade.js';
+import { createLoopFacadeOps } from '../runtime/facades/loop-facade.js';
+import { createOrchestrateFacadeOps } from '../runtime/facades/orchestrate-facade.js';
+import { createControlFacadeOps } from '../runtime/facades/control-facade.js';
+import { createContextFacadeOps } from '../runtime/facades/context-facade.js';
+import { createAgencyFacadeOps } from '../runtime/facades/agency-facade.js';
+import { createChatFacadeOps } from '../runtime/facades/chat-facade.js';
+import { createOperatorFacadeOps } from '../runtime/facades/operator-facade.js';
+import { createArchiveFacadeOps } from '../runtime/facades/archive-facade.js';
+import { createSyncFacadeOps } from '../runtime/facades/sync-facade.js';
+import { createReviewFacadeOps } from '../runtime/facades/review-facade.js';
+import { createIntakeFacadeOps } from '../runtime/facades/intake-facade.js';
+import { createLinksFacadeOps } from '../runtime/facades/links-facade.js';
+import { createBranchingFacadeOps } from '../runtime/facades/branching-facade.js';
+import { createTierFacadeOps } from '../runtime/facades/tier-facade.js';
+import { createEmbeddingFacadeOps } from '../runtime/facades/embedding-facade.js';
+
+// ── Public types ────────────────────────────────────────────────────────
+
+export interface SkillValidationError {
+  file: string;
+  op: string;
+  message: string;
+  line?: number;
+}
+
+export interface SkillValidationResult {
+  valid: boolean;
+  errors: SkillValidationError[];
+  totalFiles: number;
+  totalExamples: number;
+  registrySize: number;
+}
+
+// ── Internal types ──────────────────────────────────────────────────────
+
+interface OpExample {
+  file: string;
+  line: number;
+  opName: string;
+  rawParams: string;
+  parsedParams: Record<string, unknown> | null;
+  parseError?: string;
+}
+
+// ── Mock runtime ────────────────────────────────────────────────────────
+// Schemas are constructed during factory calls but handlers are never invoked.
+
+function createNoopProxy(): AgentRuntime {
+  const handler: ProxyHandler<object> = {
+    get(_target, prop) {
+      if (prop === Symbol.toPrimitive) return () => '';
+      if (prop === Symbol.iterator) return undefined;
+      if (prop === 'then') return undefined;
+      if (prop === 'toString') return () => '[mock]';
+      if (prop === 'valueOf') return () => 0;
+      if (prop === 'length') return 0;
+      return new Proxy(function () {}, handler);
+    },
+    apply() {
+      return new Proxy({}, handler);
+    },
+  };
+  return new Proxy({}, handler) as unknown as AgentRuntime;
+}
+
+// ── Schema registry ─────────────────────────────────────────────────────
+
+function buildSchemaRegistry(): Map<string, ZodType> {
+  const runtime = createNoopProxy();
+  const registry = new Map<string, ZodType>();
+
+  const facadeFactories: Array<(rt: AgentRuntime) => OpDefinition[]> = [
+    createVaultFacadeOps,
+    createPlanFacadeOps,
+    createBrainFacadeOps,
+    createMemoryFacadeOps,
+    createAdminFacadeOps,
+    createCuratorFacadeOps,
+    createLoopFacadeOps,
+    createOrchestrateFacadeOps,
+    createControlFacadeOps,
+    createContextFacadeOps,
+    createAgencyFacadeOps,
+    createChatFacadeOps,
+    createOperatorFacadeOps,
+    createArchiveFacadeOps,
+    createSyncFacadeOps,
+    createReviewFacadeOps,
+    createIntakeFacadeOps,
+    createLinksFacadeOps,
+    createBranchingFacadeOps,
+    createTierFacadeOps,
+    createEmbeddingFacadeOps,
+  ];
+
+  for (const factory of facadeFactories) {
+    try {
+      const ops = factory(runtime);
+      for (const op of ops) {
+        if (op.schema) {
+          registry.set(op.name, op.schema);
+        }
+      }
+    } catch {
+      // Some facades may fail with the mock runtime — skip them.
+    }
+  }
+
+  return registry;
+}
+
+// ── SKILL.md discovery ──────────────────────────────────────────────────
+// Discovers all SKILL.md files directly inside skillsDir.
+// Supports both layouts:
+//   - skillsDir/{name}/SKILL.md  (directory layout)
+//   - skillsDir/{name}.md        (flat file layout)
+
+function discoverSkillFiles(skillsDir: string): string[] {
+  const paths: string[] = [];
+
+  if (!existsSync(skillsDir)) return paths;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(skillsDir);
+  } catch {
+    return paths;
+  }
+
+  for (const entry of entries) {
+    const entryPath = join(skillsDir, entry);
+    try {
+      const stat = statSync(entryPath);
+      if (stat.isDirectory()) {
+        const skillMd = join(entryPath, 'SKILL.md');
+        if (existsSync(skillMd)) {
+          paths.push(skillMd);
+        }
+      } else if (entry.endsWith('.md')) {
+        paths.push(entryPath);
+      }
+    } catch {
+      // Skip unreadable entries
+    }
+  }
+
+  return paths;
+}
+
+// ── SKILL.md parser ─────────────────────────────────────────────────────
+
+function extractOpExamples(filePath: string): OpExample[] {
+  let content: string;
+  try {
+    content = readFileSync(filePath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  const lines = content.split('\n');
+  const examples: OpExample[] = [];
+
+  let inCodeBlock = false;
+  let codeBlockStart = -1;
+  let codeBlockLines: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trimStart().startsWith('```')) {
+      if (!inCodeBlock) {
+        inCodeBlock = true;
+        codeBlockStart = i + 1;
+        codeBlockLines = [];
+      } else {
+        extractFromCodeBlock(filePath, codeBlockStart, codeBlockLines, examples);
+        inCodeBlock = false;
+        codeBlockLines = [];
+      }
+      continue;
+    }
+    if (inCodeBlock) {
+      codeBlockLines.push(line);
+    }
+  }
+
+  return examples;
+}
+
+function extractFromCodeBlock(
+  filePath: string,
+  startLine: number,
+  blockLines: string[],
+  results: OpExample[],
+): void {
+  const opPattern = /(?:YOUR_AGENT_\w+\s+)?op:(\w+)(?:\s+params:\s*(.*))?/;
+
+  for (let i = 0; i < blockLines.length; i++) {
+    const line = blockLines[i];
+    const match = line.match(opPattern);
+    if (!match) continue;
+
+    const opName = match[1];
+    const lineNum = startLine + i + 1;
+
+    let rawParams = '';
+
+    if (match[2]) {
+      rawParams = match[2].trim();
+    } else if (i + 1 < blockLines.length && blockLines[i + 1].trim().startsWith('params:')) {
+      const paramsLine = blockLines[i + 1].trim();
+      const paramsMatch = paramsLine.match(/^params:\s*(.*)/);
+      if (paramsMatch) {
+        rawParams = paramsMatch[1].trim();
+      }
+    }
+
+    if (rawParams) {
+      const fullParams = collectMultiLineParams(blockLines, i, rawParams);
+      const { parsed, error } = parseLooseJson(fullParams);
+
+      results.push({
+        file: filePath,
+        line: lineNum,
+        opName,
+        rawParams: fullParams,
+        parsedParams: parsed,
+        parseError: error,
+      });
+    }
+  }
+}
+
+function collectMultiLineParams(blockLines: string[], opLineIdx: number, initial: string): string {
+  if (isBalanced(initial)) return initial;
+
+  let startIdx = opLineIdx + 1;
+  if (!blockLines[opLineIdx].includes('params:') && startIdx < blockLines.length) {
+    if (blockLines[startIdx].trim().startsWith('params:')) {
+      startIdx++;
+    }
+  }
+
+  let result = initial;
+  for (let j = startIdx; j < blockLines.length; j++) {
+    const nextLine = blockLines[j].trim();
+    if (!nextLine) continue;
+    if (nextLine.match(/(?:YOUR_AGENT_\w+\s+)?op:\w+/)) break;
+    result += '\n' + nextLine;
+    if (isBalanced(result)) break;
+  }
+
+  return result;
+}
+
+function isBalanced(s: string): boolean {
+  let depth = 0;
+  for (const ch of s) {
+    if (ch === '{' || ch === '[') depth++;
+    if (ch === '}' || ch === ']') depth--;
+    if (depth < 0) return false;
+  }
+  return depth === 0;
+}
+
+function parseLooseJson(raw: string): {
+  parsed: Record<string, unknown> | null;
+  error?: string;
+} {
+  if (!raw.trim()) return { parsed: null };
+
+  try {
+    const normalized = raw
+      .replace(/"<([^">]+)>"/g, '"$1"')
+      .replace(/([{,]\s*)(\w+)\s*:/g, '$1"$2":')
+      .replace(/'/g, '"')
+      .replace(/,\s*([}\]])/g, '$1')
+      .replace(/\.\.\./g, '')
+      .replace(/\["?<[^>]+>"?\]/g, '["placeholder"]');
+
+    const result = JSON.parse(normalized);
+    return { parsed: result };
+  } catch (e) {
+    try {
+      const result = extractFlatParams(raw);
+      if (result && Object.keys(result).length > 0) {
+        return { parsed: result };
+      }
+    } catch {
+      // fall through
+    }
+    return {
+      parsed: null,
+      error: `Cannot parse params: ${(e as Error).message}`,
+    };
+  }
+}
+
+function extractFlatParams(raw: string): Record<string, unknown> | null {
+  const result: Record<string, unknown> = {};
+  const kvPattern = /(\w+)\s*:\s*(?:"([^"]*)"|\[([^\]]*)\]|(\{[^}]*\})|(\w+))/g;
+  let match;
+  let found = false;
+
+  while ((match = kvPattern.exec(raw)) !== null) {
+    found = true;
+    const key = match[1];
+    if (match[2] !== undefined) {
+      result[key] = match[2].replace(/<[^>]+>/g, 'placeholder');
+    } else if (match[3] !== undefined) {
+      result[key] = ['placeholder'];
+    } else if (match[4] !== undefined) {
+      result[key] = {};
+    } else if (match[5] !== undefined) {
+      const val = match[5];
+      if (val === 'true') result[key] = true;
+      else if (val === 'false') result[key] = false;
+      else if (/^\d+$/.test(val)) result[key] = parseInt(val, 10);
+      else result[key] = val;
+    }
+  }
+
+  return found ? result : null;
+}
+
+// ── Validation ──────────────────────────────────────────────────────────
+
+function isPlaceholder(value: unknown): boolean {
+  if (typeof value !== 'string') return false;
+  if (value.includes('|')) return true;
+  if (/^<.*>$/.test(value)) return true;
+  if (/^(placeholder|example|value|name|id|title|description|type|domain)$/i.test(value))
+    return true;
+  if (
+    /^[\w]+-[\w]+$/.test(value) &&
+    /\b(correct|your|my|the|this|some|new|old|entry|item|current)\b/i.test(value)
+  )
+    return true;
+  return false;
+}
+
+function isPlaceholderIssue(
+  issue: { code: string; path: (string | number)[]; received?: unknown; message: string },
+  params: Record<string, unknown>,
+): boolean {
+  if (issue.code === 'invalid_enum_value') {
+    const received = issue.received ?? getNestedValue(params, issue.path);
+    if (isPlaceholder(received)) return true;
+  }
+  return false;
+}
+
+function getNestedValue(obj: Record<string, unknown>, path: (string | number)[]): unknown {
+  let current: unknown = obj;
+  for (const key of path) {
+    if (current === null || current === undefined || typeof current !== 'object') return undefined;
+    current = (current as Record<string | number, unknown>)[key];
+  }
+  return current;
+}
+
+function validateExamples(
+  examples: OpExample[],
+  registry: Map<string, ZodType>,
+): SkillValidationError[] {
+  const errors: SkillValidationError[] = [];
+
+  for (const ex of examples) {
+    if (ex.parseError) continue;
+    if (!ex.parsedParams) continue;
+
+    const schema = registry.get(ex.opName);
+    if (!schema) {
+      errors.push({
+        file: ex.file,
+        op: ex.opName,
+        line: ex.line,
+        message: `unknown op — not found in any facade schema registry`,
+      });
+      continue;
+    }
+
+    const result = (
+      schema as {
+        safeParse: (p: unknown) => { success: boolean; error?: ZodError };
+      }
+    ).safeParse(ex.parsedParams);
+
+    if (!result.success && result.error) {
+      for (const issue of result.error.issues) {
+        if (
+          isPlaceholderIssue(
+            issue as {
+              code: string;
+              path: (string | number)[];
+              received?: unknown;
+              message: string;
+            },
+            ex.parsedParams,
+          )
+        ) {
+          continue;
+        }
+        const path = issue.path.join('.');
+        errors.push({
+          file: ex.file,
+          op: ex.opName,
+          line: ex.line,
+          message: `${path ? path + ': ' : ''}${issue.message}`,
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+// ── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Validate all SKILL.md files found in `skillsDir`.
+ *
+ * `skillsDir` is the directory that contains skill subdirectories, e.g. ~/.claude/skills/.
+ * Each subdirectory is expected to have a SKILL.md file.
+ *
+ * @returns Structured result with errors, counts, and whether all examples are valid.
+ */
+export function validateSkillDocs(skillsDir: string): SkillValidationResult {
+  const registry = buildSchemaRegistry();
+  const skillFiles = discoverSkillFiles(skillsDir);
+  let totalExamples = 0;
+  const allErrors: SkillValidationError[] = [];
+
+  for (const file of skillFiles) {
+    const examples = extractOpExamples(file);
+    totalExamples += examples.length;
+    const errors = validateExamples(examples, registry);
+    allErrors.push(...errors);
+  }
+
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    totalFiles: skillFiles.length,
+    totalExamples,
+    registrySize: registry.size,
+  };
+}

package/src/telemetry/telemetry.test.ts

@@ -36,6 +36,7 @@ describe('Telemetry', () => {
       expect(stats.callsByOp).toEqual({});
       expect(stats.errorsByOp).toEqual({});
       expect(stats.slowestOps).toEqual([]);
+      expect(typeof stats.since).toBe('number');
       expect(stats.since).toBeLessThanOrEqual(Date.now());
     });
 

package/src/transport/http-server.test.ts

@@ -128,7 +128,10 @@ describe('HttpMcpServer', () => {
     it('starts and stops without error', async () => {
       await server.start();
       const stats = server.getStats();
+      expect(typeof stats.uptime).toBe('number');
+      // uptime is elapsed ms since start — should be a small non-negative number
       expect(stats.uptime).toBeGreaterThanOrEqual(0);
+      expect(stats.uptime).toBeLessThan(5000); // must have completed in under 5s
       await server.stop();
     });
 

package/src/transport/session-manager.test.ts

@@ -30,11 +30,13 @@ describe('SessionManager', () => {
 
   describe('add / get / remove', () => {
     it('adds and retrieves a session', () => {
+      const before = Date.now();
       const session = manager.add('s1', 'transport', 'server');
       expect(session.id).toBe('s1');
       expect(session.transport).toBe('transport');
       expect(session.server).toBe('server');
-      expect(session.createdAt).toBeGreaterThan(0);
+      expect(session.createdAt).toBeGreaterThanOrEqual(before);
+      expect(session.createdAt).toBeLessThanOrEqual(Date.now());
       expect(manager.get('s1')).toBe(session);
     });
 

package/src/transport/token-auth.test.ts

@@ -121,16 +121,13 @@ describe('loadToken / saveToken / getOrGenerateToken', () => {
     expect(result).toBe('trimmed-token');
   });
 
-  it('loadToken returns undefined for empty env var', () => {
+  it('skips whitespace-only env var and does not return the raw whitespace value', () => {
     vi.stubEnv('MY_AGENT_HTTP_TOKEN', '   ');
+    // env var is whitespace-only — function must skip it and NOT return whitespace
     const result = loadToken('my-agent');
-    // Falls through to file-based lookup
-    expect(result === undefined || typeof result === 'string').toBe(true);
-  });
-
-  it('generateToken produces different tokens each call', () => {
-    const t1 = generateToken();
-    const t2 = generateToken();
-    expect(t1).not.toBe(t2);
+    expect(result).not.toBe('   ');
+    if (result !== undefined) {
+      expect(result.trim().length).toBeGreaterThan(0);
+    }
   });
 });

package/src/transport/ws-server.test.ts

@@ -124,7 +124,11 @@ describe('WsMcpServer', () => {
   describe('standalone start / stop', () => {
     it('starts and stops without error', async () => {
       await server.start(0);
-      expect(server.getStats().uptime).toBeGreaterThanOrEqual(0);
+      const uptime = server.getStats().uptime;
+      expect(typeof uptime).toBe('number');
+      // uptime is elapsed ms since start — should be a small non-negative number
+      expect(uptime).toBeGreaterThanOrEqual(0);
+      expect(uptime).toBeLessThan(5000); // must have started in under 5s
       await server.stop();
     });
 
@@ -145,7 +149,11 @@ describe('WsMcpServer', () => {
         callbacks,
       );
       wsServer.attachTo(httpServer);
-      expect(wsServer.getStats().uptime).toBeGreaterThanOrEqual(0);
+      const attachUptime = wsServer.getStats().uptime;
+      expect(typeof attachUptime).toBe('number');
+      // uptime is elapsed ms since attach — valid non-negative number
+      expect(attachUptime).toBeGreaterThanOrEqual(0);
+      expect(attachUptime).toBeLessThan(5000);
 
       await wsServer.stop();
       await new Promise<void>((resolve, reject) => {

package/src/utils/worktree-reaper.ts

@@ -0,0 +1,113 @@
+/**
+ * Worktree reaper — cleans up stale .claude/worktrees/ entries left by subagent execution.
+ *
+ * Claude Code creates worktrees via `isolation: "worktree"` for parallel subagent runs.
+ * If the agent commits changes, the worktree persists — nobody reaps it automatically.
+ *
+ * Usage: call worktreeReap() at session start and after plan completion (best-effort).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface ReapReport {
+  /** Number of worktrees successfully reaped */
+  reaped: number;
+  /** Paths of stale worktrees found */
+  found: string[];
+  /** Any errors encountered (non-fatal) */
+  errors: string[];
+  /** Whether git worktree prune ran successfully */
+  pruned: boolean;
+}
+
+export interface WorktreeStatus {
+  /** All .claude/worktrees/ entries found */
+  stale: Array<{ path: string; branch: string; commit: string }>;
+  /** Total count */
+  total: number;
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into structured entries.
+ */
+function parseWorktreeList(
+  output: string,
+): Array<{ path: string; branch: string; commit: string }> {
+  const entries: Array<{ path: string; branch: string; commit: string }> = [];
+  const blocks = output.trim().split(/\n\n+/);
+
+  for (const block of blocks) {
+    const lines = block.trim().split('\n');
+    let path = '';
+    let branch = '';
+    let commit = '';
+
+    for (const line of lines) {
+      if (line.startsWith('worktree ')) path = line.slice(9).trim();
+      else if (line.startsWith('HEAD ')) commit = line.slice(5).trim();
+      else if (line.startsWith('branch ')) branch = line.slice(7).trim();
+    }
+
+    if (path) entries.push({ path, branch, commit });
+  }
+
+  return entries;
+}
+
+/**
+ * Get status of stale worktrees under .claude/worktrees/ without removing them.
+ */
+export function worktreeStatus(projectPath: string): WorktreeStatus {
+  const result = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+    cwd: projectPath,
+    encoding: 'utf-8',
+  });
+
+  if (result.status !== 0 || !result.stdout) {
+    return { stale: [], total: 0 };
+  }
+
+  const all = parseWorktreeList(result.stdout);
+  const worktreeBase = join(projectPath, '.claude', 'worktrees');
+  const stale = all.filter((e) => e.path.startsWith(worktreeBase) && existsSync(e.path));
+
+  return { stale, total: stale.length };
+}
+
+/**
+ * Reap stale worktrees under .claude/worktrees/.
+ * Best-effort — errors are collected but never thrown.
+ */
+export function worktreeReap(projectPath: string): ReapReport {
+  const report: ReapReport = { reaped: 0, found: [], errors: [], pruned: false };
+
+  try {
+    const { stale } = worktreeStatus(projectPath);
+
+    for (const { path } of stale) {
+      report.found.push(path);
+      const rm = spawnSync('git', ['worktree', 'remove', '--force', path], {
+        cwd: projectPath,
+        encoding: 'utf-8',
+      });
+      if (rm.status === 0) {
+        report.reaped++;
+      } else {
+        report.errors.push(`Failed to remove ${path}: ${rm.stderr?.trim() ?? 'unknown error'}`);
+      }
+    }
+
+    // Prune dangling refs
+    const prune = spawnSync('git', ['worktree', 'prune'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+    });
+    report.pruned = prune.status === 0;
+  } catch (err) {
+    report.errors.push(err instanceof Error ? err.message : String(err));
+  }
+
+  return report;
+}