@pennyfarthing/shared 7.5.0 → 9.3.0

package/dist/skill-suggest.test.js

@@ -0,0 +1,257 @@
+/**
+ * Tests for Story 9-3: Add Skill Suggestions to Agents
+ *
+ * These tests verify:
+ * - AC1: Session-aware suggestions based on story context
+ * - AC2: Keyword-triggered suggestions with scoring
+ * - AC3: Non-intrusive presentation (confidence threshold, limits)
+ *
+ * Run with: npm test -- packages/shared/src/skill-suggest.test.ts
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+// Import functions to test - these don't exist yet, tests should fail (RED)
+import { suggestSkills, suggestFromSession, suggestFromKeywords, } from './skill-suggest.js';
+describe('Story 9-3: Skill Suggestions', () => {
+    describe('AC1: Session-aware suggestions', () => {
+        it('should suggest skills based on story acceptance criteria', async () => {
+            // AC1: Agents suggest skills when relevant (session-aware)
+            const sessionContext = {
+                storyId: '9-3',
+                acceptanceCriteria: [
+                    'Write failing tests for the feature',
+                    'Implement TDD workflow',
+                ],
+                phase: 'testing',
+            };
+            const suggestions = await suggestFromSession(sessionContext);
+            assert.ok(Array.isArray(suggestions), 'Should return array of suggestions');
+            assert.ok(suggestions.length > 0, 'Should suggest at least one skill');
+            const skillNames = suggestions.map(s => s.name);
+            assert.ok(skillNames.includes('testing'), 'Should suggest testing skill for TDD-related ACs');
+        });
+        it('should suggest skills based on current workflow phase', async () => {
+            // AC1: Phase-aware suggestions
+            const sessionContext = {
+                storyId: '9-3',
+                acceptanceCriteria: ['Deploy the feature'],
+                phase: 'review',
+            };
+            const suggestions = await suggestFromSession(sessionContext);
+            // Review phase should suggest code-review skill
+            const skillNames = suggestions.map(s => s.name);
+            assert.ok(skillNames.includes('code-review'), 'Should suggest code-review skill during review phase');
+        });
+        it('should include relevance reason for each suggestion', async () => {
+            // AC1: Suggestions should explain why they're relevant
+            const sessionContext = {
+                storyId: '9-3',
+                acceptanceCriteria: ['Add unit tests'],
+                phase: 'testing',
+            };
+            const suggestions = await suggestFromSession(sessionContext);
+            assert.ok(suggestions.length > 0, 'Should have suggestions');
+            for (const suggestion of suggestions) {
+                assert.ok(suggestion.reason, `Suggestion ${suggestion.name} should have a reason`);
+                assert.ok(suggestion.reason.length > 10, `Reason should be descriptive: ${suggestion.reason}`);
+            }
+        });
+        it('should return empty array when no story context available', async () => {
+            // AC1: Graceful handling of missing context
+            const emptyContext = {
+                storyId: '',
+                acceptanceCriteria: [],
+                phase: 'unknown',
+            };
+            const suggestions = await suggestFromSession(emptyContext);
+            assert.ok(Array.isArray(suggestions), 'Should return array');
+            assert.strictEqual(suggestions.length, 0, 'Should return empty array for no context');
+        });
+        it('should suggest jira skill when story has Jira reference', async () => {
+            // AC1: Detect Jira context
+            const sessionContext = {
+                storyId: '9-3',
+                jiraKey: 'MSSCI-11518',
+                acceptanceCriteria: ['Update Jira status'],
+                phase: 'development',
+            };
+            const suggestions = await suggestFromSession(sessionContext);
+            const skillNames = suggestions.map(s => s.name);
+            assert.ok(skillNames.includes('jira'), 'Should suggest jira skill when Jira key is present');
+        });
+    });
+    describe('AC2: Keyword-triggered suggestions', () => {
+        it('should extract keywords from user input and match skills', async () => {
+            // AC2: Suggestions based on task analysis (keyword extraction)
+            const userInput = 'I need to write some tests for this feature';
+            const suggestions = await suggestFromKeywords(userInput);
+            assert.ok(Array.isArray(suggestions), 'Should return array');
+            assert.ok(suggestions.length > 0, 'Should find matching skills');
+            const skillNames = suggestions.map(s => s.name);
+            assert.ok(skillNames.includes('testing'), 'Should suggest testing skill for "tests" keyword');
+        });
+        it('should match skills by their registered keywords', async () => {
+            // AC2: Registry matching
+            const userInput = 'How do I use vitest for unit testing?';
+            const suggestions = await suggestFromKeywords(userInput);
+            // vitest is a keyword for testing skill
+            const testingSuggestion = suggestions.find(s => s.name === 'testing');
+            assert.ok(testingSuggestion, 'Should find testing skill via vitest keyword');
+        });
+        it('should score suggestions by keyword match count', async () => {
+            // AC2: Scoring mechanism
+            const userInput = 'I need to run tests, write tests, and check test coverage';
+            const suggestions = await suggestFromKeywords(userInput);
+            assert.ok(suggestions.length > 0, 'Should have suggestions');
+            // First suggestion should have highest score
+            for (let i = 1; i < suggestions.length; i++) {
+                assert.ok(suggestions[i - 1].score >= suggestions[i].score, 'Suggestions should be sorted by score descending');
+            }
+        });
+        it('should include score in each suggestion', async () => {
+            // AC2: Each suggestion has a relevance score
+            const userInput = 'deploy the application to production';
+            const suggestions = await suggestFromKeywords(userInput);
+            for (const suggestion of suggestions) {
+                assert.ok(typeof suggestion.score === 'number', `Suggestion ${suggestion.name} should have numeric score`);
+                assert.ok(suggestion.score >= 0 && suggestion.score <= 1, `Score should be between 0 and 1: ${suggestion.score}`);
+            }
+        });
+        it('should return empty array for input with no skill keywords', async () => {
+            // AC2: Graceful handling of no matches
+            const userInput = 'hello world this is random text';
+            const suggestions = await suggestFromKeywords(userInput);
+            assert.ok(Array.isArray(suggestions), 'Should return array');
+            assert.strictEqual(suggestions.length, 0, 'Should return empty for no keyword matches');
+        });
+        it('should handle case-insensitive keyword matching', async () => {
+            // AC2: Case insensitivity
+            const lowerInput = 'run jest tests';
+            const upperInput = 'Run JEST Tests';
+            const lowerSuggestions = await suggestFromKeywords(lowerInput);
+            const upperSuggestions = await suggestFromKeywords(upperInput);
+            assert.deepStrictEqual(lowerSuggestions.map(s => s.name).sort(), upperSuggestions.map(s => s.name).sort(), 'Keyword matching should be case-insensitive');
+        });
+        it('should match skill tags in addition to keywords', async () => {
+            // AC2: Tag matching
+            const userInput = 'I need help with quality assurance';
+            const suggestions = await suggestFromKeywords(userInput);
+            // 'quality' is a tag, should match skills with that tag
+            const hasQualitySkill = suggestions.some(s => s.matchedOn?.includes('tag:quality'));
+            assert.ok(hasQualitySkill, 'Should match skills by tag');
+        });
+    });
+    describe('AC3: Non-intrusive presentation', () => {
+        it('should only return suggestions above confidence threshold', async () => {
+            // AC3: Contextual, not every message
+            const options = {
+                confidenceThreshold: 0.5,
+            };
+            const userInput = 'maybe something about testing I guess';
+            const suggestions = await suggestSkills(userInput, options);
+            for (const suggestion of suggestions) {
+                assert.ok(suggestion.score >= 0.5, `All suggestions should be above threshold: ${suggestion.name} has ${suggestion.score}`);
+            }
+        });
+        it('should limit number of suggestions returned', async () => {
+            // AC3: Non-intrusive - don't overwhelm with suggestions
+            const options = {
+                maxResults: 3,
+            };
+            const userInput = 'I need to test, deploy, review, document everything';
+            const suggestions = await suggestSkills(userInput, options);
+            assert.ok(suggestions.length <= 3, `Should return at most ${options.maxResults} suggestions`);
+        });
+        it('should exclude already-used skills from suggestions', async () => {
+            // AC3: Contextual - don't suggest what they're already using
+            const options = {
+                excludeSkills: ['testing'],
+            };
+            const userInput = 'I need to write more tests';
+            const suggestions = await suggestSkills(userInput, options);
+            const skillNames = suggestions.map(s => s.name);
+            assert.ok(!skillNames.includes('testing'), 'Should not suggest excluded skills');
+        });
+        it('should return empty array when all matches are below threshold', async () => {
+            // AC3: Don't suggest low-confidence matches
+            const options = {
+                confidenceThreshold: 0.99,
+            };
+            const userInput = 'something vaguely related to code';
+            const suggestions = await suggestSkills(userInput, options);
+            assert.ok(Array.isArray(suggestions), 'Should return array');
+            assert.strictEqual(suggestions.length, 0, 'Should return empty when below threshold');
+        });
+        it('should combine session context and keywords when both provided', async () => {
+            // AC3: Proactive - detect helpful moments
+            const sessionContext = {
+                storyId: '9-3',
+                acceptanceCriteria: ['Add documentation'],
+                phase: 'development',
+            };
+            const options = {
+                sessionContext,
+            };
+            const userInput = 'how do I write good docs?';
+            const suggestions = await suggestSkills(userInput, options);
+            // Should boost documentation-related skills
+            assert.ok(suggestions.length > 0, 'Should have suggestions');
+            // First suggestion should be docs-related given both context and input mention it
+            const topSuggestion = suggestions[0];
+            assert.ok(topSuggestion.name.includes('changelog') ||
+                topSuggestion.reason?.toLowerCase().includes('document'), 'Top suggestion should be documentation-related');
+        });
+        it('should respect default options when none provided', async () => {
+            // AC3: Sensible defaults
+            const userInput = 'run the tests';
+            const suggestions = await suggestSkills(userInput);
+            // Should work with defaults
+            assert.ok(Array.isArray(suggestions), 'Should return array with default options');
+            // Default threshold should filter out very low matches
+            for (const suggestion of suggestions) {
+                assert.ok(suggestion.score >= 0.3, 'Default threshold should be at least 0.3');
+            }
+        });
+    });
+    describe('SkillSuggestion interface', () => {
+        it('should include name, description, score, and reason', async () => {
+            // Verify the shape of returned suggestions
+            const userInput = 'write tests';
+            const suggestions = await suggestSkills(userInput);
+            assert.ok(suggestions.length > 0, 'Should have suggestions');
+            const suggestion = suggestions[0];
+            assert.ok('name' in suggestion, 'Should have name');
+            assert.ok('description' in suggestion, 'Should have description');
+            assert.ok('score' in suggestion, 'Should have score');
+            assert.ok('reason' in suggestion, 'Should have reason');
+        });
+        it('should optionally include matchedOn for debugging', async () => {
+            // Shows what triggered the suggestion
+            const userInput = 'run jest tests';
+            const suggestions = await suggestSkills(userInput);
+            const testingSuggestion = suggestions.find(s => s.name === 'testing');
+            if (testingSuggestion) {
+                assert.ok('matchedOn' in testingSuggestion, 'Should include matchedOn field');
+                assert.ok(Array.isArray(testingSuggestion.matchedOn), 'matchedOn should be array');
+            }
+        });
+    });
+    describe('Error handling', () => {
+        it('should handle invalid input gracefully', async () => {
+            // Empty input
+            const suggestions = await suggestSkills('');
+            assert.ok(Array.isArray(suggestions), 'Should return array for empty input');
+            assert.strictEqual(suggestions.length, 0, 'Should return empty for empty input');
+        });
+        it('should handle missing registry gracefully', async () => {
+            // If registry not found, should return empty (not crash)
+            const options = {
+                registryPath: '/nonexistent/path/registry.yaml',
+            };
+            const suggestions = await suggestSkills('test something', options);
+            // Should gracefully return empty, not throw
+            assert.ok(Array.isArray(suggestions), 'Should return array even with missing registry');
+        });
+    });
+});
+//# sourceMappingURL=skill-suggest.test.js.map

package/dist/skill-suggest.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-suggest.test.js","sourceRoot":"","sources":["../src/skill-suggest.test.ts"],"names":[],"mappings":"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"}

package/dist/theme-loader.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Theme Loader - Unified theme discovery, loading, and metadata for Pennyfarthing
+ *
+ * This is the ONE canonical implementation of theme loading. All other packages
+ * (core CLI, cyclist, Python scripts, bash scripts) should delegate here.
+ *
+ * Discovery algorithm (checked in order, deduped by theme ID):
+ *   1. Core themes: resolvePennyfarthingDist()/personas/themes/
+ *   2. Theme packages: node_modules/@pennyfarthing/themes-* /themes/
+ *   3. Project custom: {projectRoot}/.claude/pennyfarthing/themes/
+ *   4. User custom: ~/.claude/pennyfarthing/themes/
+ */
+export interface ThemeAgent {
+    character: string;
+    style: string;
+    role: string;
+    trait: string;
+    catchphrases: string[];
+    helper?: string;
+}
+export interface Theme {
+    name: string;
+    description: string;
+    agents: Record<string, ThemeAgent>;
+}
+export interface ThemePackageInfo {
+    packageName: string;
+    themesDir: string;
+    portraitsDir: string;
+}
+export interface ThemeMetadata {
+    id: string;
+    name: string;
+    description: string;
+    source: string;
+    tier: 'S' | 'A' | 'B' | 'U';
+    category: string;
+    agentCount: number;
+}
+export declare const CATEGORY_MAP: Record<string, string>;
+/**
+ * Derive category from theme ID and source text.
+ * Uses CATEGORY_MAP for known themes, falls back to pattern matching.
+ */
+export declare function deriveCategory(themeId: string, source: string): string;
+/**
+ * Discover installed @pennyfarthing/themes-* packages.
+ * Walks up from projectRoot looking for node_modules/@pennyfarthing/,
+ * then checks each themes-* directory for a valid theme pack.
+ */
+export declare function discoverThemePackages(projectRoot?: string): ThemePackageInfo[];
+/**
+ * Discover all directories containing theme YAML files.
+ * Returns dirs in priority order (core, theme packages, project custom, user custom).
+ */
+export declare function discoverAllThemeDirs(projectRoot?: string): string[];
+/**
+ * Resolve the file path for a specific theme across all sources.
+ * Returns the first match found in priority order, or null.
+ */
+export declare function resolveThemePath(themeId: string, projectRoot?: string): string | null;
+/**
+ * Load metadata for all discoverable themes.
+ * Deduplicates by theme ID (first source wins).
+ */
+export declare function loadAllThemeMetadata(projectRoot?: string): ThemeMetadata[];
+/**
+ * Load a theme configuration by name.
+ * Searches all theme sources in priority order.
+ */
+export declare function loadTheme(themeName: string): Theme | null;
+/**
+ * List all available theme IDs across all sources.
+ * Deduplicates — first source wins.
+ */
+export declare function listThemes(projectRoot?: string): string[];
+/**
+ * Get agent persona from a theme.
+ */
+export declare function getAgentPersona(themeName: string, agentName: string): ThemeAgent | null;
+//# sourceMappingURL=theme-loader.d.ts.map

package/dist/theme-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-loader.d.ts","sourceRoot":"","sources":["../src/theme-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC;AAMD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AA8BD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgK/C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA0CtE;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAoF9E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAmCnE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASrF;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAyC1E;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CA8BzD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAsBzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAMvF"}