@winspan/claude-forge 8.39.0 → 8.50.6

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');
+  });
+});
+