@winspan/claude-forge 8.41.0 → 8.51.0

package/tests/unit/skills/invocation-guard-ttl.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { InvocationGuard } from '../../../src/skills/invocation-guard.js';
+
+describe('InvocationGuard - TTL Mechanism', () => {
+  let guard: InvocationGuard;
+
+  beforeEach(() => {
+    guard = new InvocationGuard();
+  });
+
+  afterEach(() => {
+    guard.stopCleanupTimer();
+  });
+
+  describe('TTL expiration', () => {
+    it('should allow invocation after session expires', () => {
+      const sessionId = 'test-session-1';
+      const skillId = 'test-skill';
+
+      // Record initial invocation
+      guard.record(sessionId, skillId);
+
+      // Verify skill is blocked (idempotent guard)
+      let result = guard.check(sessionId, skillId);
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain('already invoked');
+
+      // Fast-forward time by 31 minutes (beyond TTL)
+      const stats = guard.getStats(sessionId);
+      if (stats) {
+        stats.lastAccessTime = Date.now() - 31 * 60 * 1000;
+      }
+
+      // Should allow invocation after expiration
+      result = guard.check(sessionId, skillId);
+      expect(result.allowed).toBe(true);
+    });
+
+    it('should update lastAccessTime on record', () => {
+      const sessionId = 'test-session-2';
+      const skillId = 'test-skill';
+
+      const before = Date.now();
+      guard.record(sessionId, skillId);
+      const after = Date.now();
+
+      const stats = guard.getStats(sessionId);
+      expect(stats).not.toBeNull();
+      expect(stats!.lastAccessTime).toBeGreaterThanOrEqual(before);
+      expect(stats!.lastAccessTime).toBeLessThanOrEqual(after);
+    });
+
+    it('should update lastAccessTime on complete', () => {
+      const sessionId = 'test-session-3';
+      const skillId = 'test-skill';
+
+      guard.record(sessionId, skillId);
+      const initialTime = guard.getStats(sessionId)!.lastAccessTime;
+
+      // Wait a bit
+      vi.useFakeTimers();
+      vi.advanceTimersByTime(1000);
+
+      guard.complete(sessionId);
+      const updatedTime = guard.getStats(sessionId)!.lastAccessTime;
+
+      expect(updatedTime).toBeGreaterThan(initialTime);
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('automatic cleanup', () => {
+    it('should clean up expired sessions', () => {
+      const sessionId1 = 'expired-session-1';
+      const sessionId2 = 'active-session-2';
+
+      // Record two sessions
+      guard.record(sessionId1, 'skill-1');
+      guard.record(sessionId2, 'skill-2');
+
+      expect(guard.getSessionCount()).toBe(2);
+
+      // Expire first session
+      const stats1 = guard.getStats(sessionId1);
+      if (stats1) {
+        stats1.lastAccessTime = Date.now() - 31 * 60 * 1000;
+      }
+
+      // Trigger cleanup manually
+      (guard as any).cleanupExpiredSessions();
+
+      // Only active session should remain
+      expect(guard.getSessionCount()).toBe(1);
+      expect(guard.getStats(sessionId1)).toBeNull();
+      expect(guard.getStats(sessionId2)).not.toBeNull();
+    });
+
+    it('should not clean up active sessions', () => {
+      const sessionId = 'active-session';
+
+      guard.record(sessionId, 'skill-1');
+      expect(guard.getSessionCount()).toBe(1);
+
+      // Trigger cleanup
+      (guard as any).cleanupExpiredSessions();
+
+      // Session should still exist
+      expect(guard.getSessionCount()).toBe(1);
+      expect(guard.getStats(sessionId)).not.toBeNull();
+    });
+
+    it('should handle empty sessions map', () => {
+      expect(guard.getSessionCount()).toBe(0);
+
+      // Should not throw
+      expect(() => {
+        (guard as any).cleanupExpiredSessions();
+      }).not.toThrow();
+
+      expect(guard.getSessionCount()).toBe(0);
+    });
+  });
+
+  describe('cleanup timer', () => {
+    it('should start cleanup timer on construction', () => {
+      const newGuard = new InvocationGuard();
+      expect((newGuard as any).cleanupTimer).not.toBeNull();
+      newGuard.stopCleanupTimer();
+    });
+
+    it('should stop cleanup timer', () => {
+      guard.stopCleanupTimer();
+      expect((guard as any).cleanupTimer).toBeNull();
+    });
+
+    it('should not start multiple timers', () => {
+      const timer1 = (guard as any).cleanupTimer;
+      (guard as any).startCleanupTimer();
+      const timer2 = (guard as any).cleanupTimer;
+
+      expect(timer1).toBe(timer2);
+    });
+  });
+
+  describe('getSessionCount', () => {
+    it('should return 0 for empty guard', () => {
+      expect(guard.getSessionCount()).toBe(0);
+    });
+
+    it('should return correct count after recording', () => {
+      guard.record('session-1', 'skill-1');
+      expect(guard.getSessionCount()).toBe(1);
+
+      guard.record('session-2', 'skill-2');
+      expect(guard.getSessionCount()).toBe(2);
+    });
+
+    it('should decrease count after clear', () => {
+      guard.record('session-1', 'skill-1');
+      guard.record('session-2', 'skill-2');
+      expect(guard.getSessionCount()).toBe(2);
+
+      guard.clear('session-1');
+      expect(guard.getSessionCount()).toBe(1);
+    });
+  });
+
+  describe('integration with existing functionality', () => {
+    it('should maintain depth tracking with TTL', () => {
+      const sessionId = 'test-session';
+
+      guard.record(sessionId, 'skill-1');
+      expect(guard.getStats(sessionId)!.depth).toBe(1);
+
+      guard.record(sessionId, 'skill-2');
+      expect(guard.getStats(sessionId)!.depth).toBe(2);
+
+      guard.complete(sessionId);
+      expect(guard.getStats(sessionId)!.depth).toBe(1);
+
+      // lastAccessTime should be updated
+      expect(guard.getStats(sessionId)!.lastAccessTime).toBeLessThanOrEqual(Date.now());
+    });
+
+    it('should maintain total count with TTL', () => {
+      const sessionId = 'test-session';
+
+      guard.record(sessionId, 'skill-1');
+      expect(guard.getStats(sessionId)!.total).toBe(1);
+
+      guard.record(sessionId, 'skill-2');
+      expect(guard.getStats(sessionId)!.total).toBe(2);
+
+      // lastAccessTime should be updated
+      expect(guard.getStats(sessionId)!.lastAccessTime).toBeLessThanOrEqual(Date.now());
+    });
+
+    it('should maintain calledSkills set with TTL', () => {
+      const sessionId = 'test-session';
+
+      guard.record(sessionId, 'skill-1');
+      guard.record(sessionId, 'skill-2');
+
+      const stats = guard.getStats(sessionId);
+      expect(stats!.calledSkills.has('skill-1')).toBe(true);
+      expect(stats!.calledSkills.has('skill-2')).toBe(true);
+      expect(stats!.lastAccessTime).toBeLessThanOrEqual(Date.now());
+    });
+  });
+});

package/tests/unit/skills/official-skills-loader.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadOfficialSkills } from '../../../src/skills/official-skills.js';
+
+describe('loadOfficialSkills', () => {
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'forge-official-skills-test-'));
+  });
+
+  afterAll(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('loads all .md files from the given directory', () => {
+    writeFileSync(
+      join(tempDir, 'test-skill-a.md'),
+      `---\nname: test-skill-a\nversion: 1.0.0\ndescription: "Test skill A"\ntags: [tag1, tag2]\n---\n\n# Test Skill A\n\nBody content here.`
+    );
+    writeFileSync(
+      join(tempDir, 'test-skill-b.md'),
+      `---\nname: test-skill-b\nversion: 2.0.0\ndescription: "Test skill B"\nkeywords: [kw1, kw2]\n---\n\n# Test Skill B\n\nMore content.`
+    );
+
+    const skills = loadOfficialSkills(tempDir);
+    const names = skills.map(s => s.name);
+    expect(names).toContain('test-skill-a');
+    expect(names).toContain('test-skill-b');
+    expect(skills.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('parses frontmatter correctly (name, version, description, keywords from tags)', () => {
+    const skillDir = mkdtempSync(join(tmpdir(), 'forge-frontmatter-test-'));
+    try {
+      writeFileSync(
+        join(skillDir, 'my-skill.md'),
+        `---\nname: my-skill\nversion: 3.1.0\ndescription: "My test skill"\ntags: [alpha, beta, gamma]\n---\n\n# My Skill\n\nContent.`
+      );
+
+      const skills = loadOfficialSkills(skillDir);
+      expect(skills).toHaveLength(1);
+      const skill = skills[0];
+      expect(skill.name).toBe('my-skill');
+      expect(skill.version).toBe('3.1.0');
+      expect(skill.description).toBe('My test skill');
+      expect(skill.keywords).toEqual(['alpha', 'beta', 'gamma']);
+    } finally {
+      rmSync(skillDir, { recursive: true, force: true });
+    }
+  });
+
+  it('parses frontmatter correctly (keywords field takes precedence over tags)', () => {
+    const skillDir = mkdtempSync(join(tmpdir(), 'forge-kw-test-'));
+    try {
+      writeFileSync(
+        join(skillDir, 'kw-skill.md'),
+        `---\nname: kw-skill\nversion: 1.0.0\ndescription: "KW skill"\nkeywords: [kw-a, kw-b]\ntags: [tag-a]\n---\n\n# KW Skill`
+      );
+
+      const skills = loadOfficialSkills(skillDir);
+      expect(skills).toHaveLength(1);
+      // keywords takes precedence (data.keywords ?? data.tags => keywords wins)
+      expect(skills[0].keywords).toEqual(['kw-a', 'kw-b']);
+    } finally {
+      rmSync(skillDir, { recursive: true, force: true });
+    }
+  });
+
+  it('falls back to filename as name when frontmatter name is missing', () => {
+    const skillDir = mkdtempSync(join(tmpdir(), 'forge-fallback-test-'));
+    try {
+      writeFileSync(
+        join(skillDir, 'unnamed-skill.md'),
+        `---\nversion: 1.0.0\n---\n\n# Unnamed Skill`
+      );
+
+      const skills = loadOfficialSkills(skillDir);
+      expect(skills).toHaveLength(1);
+      expect(skills[0].name).toBe('unnamed-skill');
+    } finally {
+      rmSync(skillDir, { recursive: true, force: true });
+    }
+  });
+
+  it('ignores non-.md files in the directory', () => {
+    const skillDir = mkdtempSync(join(tmpdir(), 'forge-nonmd-test-'));
+    try {
+      writeFileSync(join(skillDir, 'skill.md'), `---\nname: skill\n---\n# Skill`);
+      writeFileSync(join(skillDir, 'README.txt'), 'not a skill');
+      writeFileSync(join(skillDir, 'index.json'), '{}');
+
+      const skills = loadOfficialSkills(skillDir);
+      expect(skills).toHaveLength(1);
+      expect(skills[0].name).toBe('skill');
+    } finally {
+      rmSync(skillDir, { recursive: true, force: true });
+    }
+  });
+
+  it('throws a meaningful error when directory does not exist', () => {
+    const nonExistentDir = join(tmpdir(), 'forge-does-not-exist-' + Date.now());
+    expect(() => loadOfficialSkills(nonExistentDir)).toThrow(/Official skills directory not found/);
+  });
+
+  it('loads all official skills from the actual built-in directory', async () => {
+    // Verify the real built-in directory works end-to-end
+    const { fileURLToPath } = await import('node:url');
+    const { dirname, join: pathJoin } = await import('node:path');
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const builtinDir = pathJoin(thisDir, '../../../src/skills/official');
+
+    const skills = loadOfficialSkills(builtinDir);
+    // Should have 17 official skills
+    expect(skills.length).toBeGreaterThanOrEqual(17);
+    // Spot-check a known skill
+    const harness = skills.find(s => s.name === 'official-harness-engineering');
+    expect(harness).toBeDefined();
+    expect(harness!.version).toBe('2.0.1');
+    expect(harness!.description).toContain('Harness Engineering');
+    // path should NOT be '<built-in>'
+    expect(harness!.name).toBe('official-harness-engineering');
+  });
+});

package/tests/unit/skills/registry-multiformat.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Unit tests for SkillRegistry multi-format support
+ * Tests both flat .md and directory-based SKILL.md formats
+ */
+
+import { describe, it, expect } from 'vitest';
+import matter from 'gray-matter';
+
+describe('SkillRegistry - Multi-format Support', () => {
+  it('should parse flat .md format with description', () => {
+    const flatSkillContent = `---
+name: flat-skill
+description: A flat format skill for testing
+keywords: [test, flat, format]
+---
+
+# Flat Skill
+
+This is a flat format skill.`;
+
+    const parsed = matter(flatSkillContent);
+    expect(parsed.data.name).toBe('flat-skill');
+    expect(parsed.data.description).toBe('A flat format skill for testing');
+    expect(parsed.data.keywords).toEqual(['test', 'flat', 'format']);
+    expect(parsed.content.trim()).toContain('# Flat Skill');
+  });
+
+  it('should parse directory format SKILL.md with description', () => {
+    const dirSkillContent = `---
+name: dir-skill
+description: A directory format skill from agent-skills
+keywords: [agent, directory, skill]
+---
+
+# Directory Skill
+
+This is a directory format skill (agent-skills format).`;
+
+    const parsed = matter(dirSkillContent);
+    expect(parsed.data.name).toBe('dir-skill');
+    expect(parsed.data.description).toBe('A directory format skill from agent-skills');
+    expect(parsed.data.keywords).toEqual(['agent', 'directory', 'skill']);
+    expect(parsed.content.trim()).toContain('# Directory Skill');
+  });
+
+  it('should handle skills without keywords', () => {
+    const noKeywordsContent = `---
+name: no-keywords-skill
+description: A skill without keywords for fallback testing
+---
+
+# No Keywords Skill
+
+This skill has no keywords, should fallback to description matching.`;
+
+    const parsed = matter(noKeywordsContent);
+    expect(parsed.data.name).toBe('no-keywords-skill');
+    expect(parsed.data.description).toBe('A skill without keywords for fallback testing');
+    expect(parsed.data.keywords).toBeUndefined();
+    expect(parsed.content.trim()).toContain('# No Keywords Skill');
+  });
+
+  it('should handle skills without description', () => {
+    const noDescContent = `---
+name: no-desc-skill
+keywords: [test, nodesc]
+---
+
+# No Description Skill
+
+This skill has no description field.`;
+
+    const parsed = matter(noDescContent);
+    expect(parsed.data.name).toBe('no-desc-skill');
+    expect(parsed.data.description).toBeUndefined();
+    expect(parsed.data.keywords).toEqual(['test', 'nodesc']);
+  });
+
+  it('should handle empty frontmatter gracefully', () => {
+    const emptyFrontmatterContent = `---
+---
+
+# Minimal Skill
+
+Just content, no metadata.`;
+
+    const parsed = matter(emptyFrontmatterContent);
+    expect(parsed.data).toEqual({});
+    expect(parsed.content.trim()).toContain('# Minimal Skill');
+  });
+});
+

package/tests/unit/socket-server.test.ts

@@ -0,0 +1,183 @@
+/**
+ * SocketServer behavior tests
+ *
+ * 重点验证 L3 性能修复：buffer 分片到达时，仅在遇到换行符后才解析，
+ * 避免大事件每个 chunk 都跑一次完整 JSON.parse 的 N² 行为。
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { SocketServer } from '../../src/daemon/server.js';
+import { EventParser } from '../../src/daemon/event-parser.js';
+
+function makeSockPath(): string {
+  const name = `forge-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.sock`;
+  return path.join(os.tmpdir(), name);
+}
+
+function makeEvent(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    hook_type: 'PostToolUse',
+    timestamp: new Date().toISOString(),
+    session_id: 'test-session',
+    project_path: '/tmp/test',
+    tool_name: 'Read',
+    ...overrides,
+  };
+}
+
+function sendOnSocket(sockPath: string, chunks: string[], delayMs = 5): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(sockPath);
+    let response = '';
+    client.on('connect', async () => {
+      for (const chunk of chunks) {
+        client.write(chunk);
+        if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+      }
+    });
+    client.on('data', (data) => {
+      response += data.toString();
+    });
+    client.on('end', () => resolve(response));
+    client.on('close', () => resolve(response));
+    client.on('error', reject);
+  });
+}
+
+describe('SocketServer — L3 chunked-parse behavior', () => {
+  const servers: SocketServer[] = [];
+  const sockPaths: string[] = [];
+
+  afterEach(async () => {
+    for (const s of servers) await s.close();
+    servers.length = 0;
+    for (const p of sockPaths) {
+      try { fs.unlinkSync(p); } catch { /* ignore */ }
+    }
+    sockPaths.length = 0;
+  });
+
+  it('parses a complete single-chunk message (with trailing newline)', async () => {
+    const sockPath = makeSockPath();
+    sockPaths.push(sockPath);
+
+    const handler = vi.fn().mockReturnValue({ allow: true });
+    const server = new SocketServer(sockPath, handler);
+    servers.push(server);
+    await new Promise((r) => setTimeout(r, 30));
+
+    const event = makeEvent();
+    const payload = JSON.stringify(event) + '\n';
+    await sendOnSocket(sockPath, [payload]);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    const passed = handler.mock.calls[0][0];
+    expect(passed.hook_type).toBe('PostToolUse');
+    expect(passed.session_id).toBe('test-session');
+  });
+
+  it('parses a large message split across many chunks WITHOUT per-chunk JSON.parse', async () => {
+    const sockPath = makeSockPath();
+    sockPaths.push(sockPath);
+
+    // 监视 JSON.parse —— 用于断言不再 N²（不能为每个 chunk 都 parse 一次）
+    const parseSpy = vi.spyOn(JSON, 'parse');
+
+    const handler = vi.fn().mockReturnValue({ allow: true });
+    const server = new SocketServer(sockPath, handler);
+    servers.push(server);
+    await new Promise((r) => setTimeout(r, 30));
+
+    // 构造大事件（约 50KB tool_output），分成 ~20 个 chunk 喂入
+    const bigOutput = 'x'.repeat(50_000);
+    const event = makeEvent({ tool_output: { data: bigOutput } });
+    const payload = JSON.stringify(event) + '\n';
+    const chunkSize = Math.ceil(payload.length / 20);
+    const chunks: string[] = [];
+    for (let i = 0; i < payload.length; i += chunkSize) {
+      chunks.push(payload.slice(i, i + chunkSize));
+    }
+    expect(chunks.length).toBeGreaterThan(10);
+
+    const callsBefore = parseSpy.mock.calls.length;
+    await sendOnSocket(sockPath, chunks, 2);
+    const callsAfter = parseSpy.mock.calls.length;
+
+    // 关键断言：handler 必须收到完整事件
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // 关键断言：JSON.parse 调用次数远少于 chunk 数（旧代码会 ≈ chunks.length 次）
+    // 现在应该只有：可能 1 次（无 auth 时）或 2 次（有 auth 时——auth 检查 + EventParser）
+    const parseDelta = callsAfter - callsBefore;
+    expect(parseDelta).toBeLessThanOrEqual(3);
+    expect(parseDelta).toBeLessThan(chunks.length); // 强对比旧 N² 行为
+
+    parseSpy.mockRestore();
+  });
+
+  it('rejects oversized buffer that never sees a newline', async () => {
+    const sockPath = makeSockPath();
+    sockPaths.push(sockPath);
+
+    const handler = vi.fn();
+    const server = new SocketServer(sockPath, handler);
+    servers.push(server);
+    await new Promise((r) => setTimeout(r, 30));
+
+    // 600KB 无换行 —— 必须超过 MAX_BUFFER_SIZE (512KB) 并被丢弃
+    // 注意：服务端 destroy 后客户端继续 write 会触发 EPIPE，要容错
+    const oversized = 'a'.repeat(600 * 1024);
+    await new Promise<void>((resolve) => {
+      const client = net.createConnection(sockPath);
+      client.on('error', () => { /* EPIPE 预期 */ });
+      client.on('close', () => resolve());
+      client.on('connect', () => {
+        client.write(oversized, () => {
+          // 给服务端处理时间
+          setTimeout(() => client.destroy(), 80);
+        });
+      });
+    });
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('uses fallback parse on socket end() for messages without trailing newline', async () => {
+    const sockPath = makeSockPath();
+    sockPaths.push(sockPath);
+
+    const handler = vi.fn().mockReturnValue({ allow: true });
+    const server = new SocketServer(sockPath, handler);
+    servers.push(server);
+    await new Promise((r) => setTimeout(r, 30));
+
+    // 无换行结尾 —— 走 socket.end() 兜底
+    const event = makeEvent();
+    const payload = JSON.stringify(event);
+    await new Promise<void>((resolve, reject) => {
+      const client = net.createConnection(sockPath);
+      client.on('connect', () => {
+        client.end(payload); // 写完即关闭：触发 server 的 'end' 事件
+      });
+      client.on('close', () => resolve());
+      client.on('error', reject);
+    });
+    // 等 server 端处理完
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('EventParser — sanity', () => {
+  it('parses a valid event JSON', () => {
+    const parser = new EventParser();
+    const raw = JSON.stringify(makeEvent());
+    const out = parser.parse(raw);
+    expect(out.session_id).toBe('test-session');
+    expect(out.hook_type).toBe('PostToolUse');
+  });
+});