sdd-mcp-server 1.8.0 → 2.0.0

package/dist/skills/SkillManager.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Descriptor for an SDD skill
+ */
+export interface SkillDescriptor {
+    /** Skill name (e.g., 'sdd-requirements') */
+    name: string;
+    /** Brief description of the skill */
+    description: string;
+    /** Path to the skill directory */
+    path: string;
+}
+/**
+ * Result of skill installation
+ */
+export interface InstallResult {
+    /** Successfully installed skills */
+    installed: string[];
+    /** Failed installations with error details */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/**
+ * Parsed skill metadata from SKILL.md frontmatter
+ */
+export interface SkillMetadata {
+    name?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+/**
+ * Manages SDD skills - discovery, listing, and installation
+ *
+ * Skills are markdown files in the skills directory that provide
+ * guidance for Claude Code agent interactions.
+ */
+export declare class SkillManager {
+    private readonly skillsPath;
+    /**
+     * Create a new SkillManager
+     * @param skillsPath - Path to the skills directory in the package
+     */
+    constructor(skillsPath: string);
+    /**
+     * List all available skills
+     * @returns Array of skill descriptors
+     */
+    listSkills(): Promise<SkillDescriptor[]>;
+    /**
+     * Get the path to a specific skill
+     * @param skillName - Name of the skill
+     * @returns Path to the skill directory
+     * @throws Error if skill not found
+     */
+    getSkillPath(skillName: string): Promise<string>;
+    /**
+     * Install skills to a target directory
+     * @param targetPath - Target directory (e.g., /project/.claude/skills)
+     * @returns Installation result with success and failure details
+     */
+    installSkills(targetPath: string): Promise<InstallResult>;
+    /**
+     * Parse YAML frontmatter from SKILL.md content
+     * @param content - Content of SKILL.md file
+     * @returns Parsed metadata
+     */
+    parseSkillMetadata(content: string): SkillMetadata;
+}

package/dist/skills/SkillManager.js

@@ -0,0 +1,138 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Manages SDD skills - discovery, listing, and installation
+ *
+ * Skills are markdown files in the skills directory that provide
+ * guidance for Claude Code agent interactions.
+ */
+export class SkillManager {
+    skillsPath;
+    /**
+     * Create a new SkillManager
+     * @param skillsPath - Path to the skills directory in the package
+     */
+    constructor(skillsPath) {
+        this.skillsPath = skillsPath;
+    }
+    /**
+     * List all available skills
+     * @returns Array of skill descriptors
+     */
+    async listSkills() {
+        const skills = [];
+        try {
+            const entries = await fs.promises.readdir(this.skillsPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const skillDir = entry.name;
+                    const skillMdPath = path.join(this.skillsPath, skillDir, 'SKILL.md');
+                    try {
+                        const content = await fs.promises.readFile(skillMdPath, 'utf-8');
+                        const metadata = this.parseSkillMetadata(content);
+                        skills.push({
+                            name: metadata.name || skillDir,
+                            description: metadata.description || '',
+                            path: path.join(this.skillsPath, skillDir),
+                        });
+                    }
+                    catch {
+                        // Skip directories without SKILL.md
+                        continue;
+                    }
+                }
+            }
+        }
+        catch {
+            // Return empty array if skills directory doesn't exist
+            return [];
+        }
+        return skills;
+    }
+    /**
+     * Get the path to a specific skill
+     * @param skillName - Name of the skill
+     * @returns Path to the skill directory
+     * @throws Error if skill not found
+     */
+    async getSkillPath(skillName) {
+        const skillPath = path.join(this.skillsPath, skillName);
+        if (!fs.existsSync(skillPath)) {
+            throw new Error(`Skill "${skillName}" not found`);
+        }
+        return skillPath;
+    }
+    /**
+     * Install skills to a target directory
+     * @param targetPath - Target directory (e.g., /project/.claude/skills)
+     * @returns Installation result with success and failure details
+     */
+    async installSkills(targetPath) {
+        const result = {
+            installed: [],
+            failed: [],
+        };
+        // Create target directory
+        await fs.promises.mkdir(targetPath, { recursive: true });
+        try {
+            const entries = await fs.promises.readdir(this.skillsPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const skillName = entry.name;
+                const sourceDir = path.join(this.skillsPath, skillName);
+                const destDir = path.join(targetPath, skillName);
+                try {
+                    // Create skill destination directory
+                    await fs.promises.mkdir(destDir, { recursive: true });
+                    // Copy all files in the skill directory
+                    const files = await fs.promises.readdir(sourceDir, { withFileTypes: true });
+                    for (const file of files) {
+                        if (!file.isDirectory()) {
+                            const sourceFile = path.join(sourceDir, file.name);
+                            const destFile = path.join(destDir, file.name);
+                            await fs.promises.copyFile(sourceFile, destFile);
+                        }
+                    }
+                    result.installed.push(skillName);
+                }
+                catch (error) {
+                    result.failed.push({
+                        name: skillName,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        catch {
+            // Return current result if reading skills directory fails
+        }
+        return result;
+    }
+    /**
+     * Parse YAML frontmatter from SKILL.md content
+     * @param content - Content of SKILL.md file
+     * @returns Parsed metadata
+     */
+    parseSkillMetadata(content) {
+        const metadata = {};
+        // Match YAML frontmatter between --- delimiters
+        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!frontmatterMatch) {
+            return metadata;
+        }
+        const frontmatter = frontmatterMatch[1];
+        // Simple YAML parsing for key: value pairs
+        const lines = frontmatter.split('\n');
+        for (const line of lines) {
+            const colonIndex = line.indexOf(':');
+            if (colonIndex > 0) {
+                const key = line.slice(0, colonIndex).trim();
+                const value = line.slice(colonIndex + 1).trim();
+                metadata[key] = value;
+            }
+        }
+        return metadata;
+    }
+}
+//# sourceMappingURL=SkillManager.js.map

package/dist/skills/SkillManager.js.map

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

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "sdd-mcp-server",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "MCP server for spec-driven development workflows across AI-agent CLIs and IDEs",
   "main": "dist/index.js",
   "bin": {
     "sdd-mcp-server": "mcp-server.js",
-    "sdd-mcp": "dist/index.js"
+    "sdd-mcp": "dist/index.js",
+    "sdd-install-skills": "dist/cli/install-skills.js"
   },
   "type": "module",
   "files": [
     "dist/**/*",
+    "skills/**/*",
     "mcp-server.js",
     "documentGenerator.js",
     "specGenerator.js",
@@ -66,7 +68,8 @@
     "inversify": "^6.0.2",
     "os-locale": "^6.0.2",
     "reflect-metadata": "^0.2.2",
-    "uuid": "^10.0.0"
+    "uuid": "^10.0.0",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/esprima": "^4.0.6",

package/skills/sdd-commit/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: sdd-commit
+description: Guide commit message and PR creation for SDD workflow. Use when committing changes, creating pull requests, or documenting changes. Invoked via /sdd-commit.
+---
+
+# SDD Commit & PR Guidelines
+
+Create clear, consistent commit messages and pull requests that document changes effectively.
+
+## Commit Message Format
+
+Follow the Conventional Commits specification:
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Type Prefixes
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `feat` | New feature | `feat(auth): add JWT refresh token` |
+| `fix` | Bug fix | `fix(api): handle null user response` |
+| `docs` | Documentation only | `docs(readme): update installation steps` |
+| `style` | Formatting, no code change | `style(lint): fix linter warnings` |
+| `refactor` | Code change, no new feature or fix | `refactor(user): extract validation logic` |
+| `perf` | Performance improvement | `perf(query): add index for user lookup` |
+| `test` | Adding/updating tests | `test(auth): add login failure tests` |
+| `build` | Build system changes | `build(deps): update dependencies` |
+| `ci` | CI/CD changes | `ci(github): add test workflow` |
+| `chore` | Other changes | `chore(deps): bump lodash version` |
+| `revert` | Revert previous commit | `revert: feat(auth): add JWT refresh` |
+
+### Scope
+
+The scope should indicate the area affected:
+
+```
+feat(auth):       # Authentication module
+fix(api/users):   # Users API endpoint
+docs(readme):     # README file
+test(e2e):        # End-to-end tests
+refactor(db):     # Database layer
+```
+
+### Subject Line
+
+- Use imperative mood: "add" not "added" or "adds"
+- Don't capitalize first letter
+- No period at the end
+- Max 50 characters
+
+```
+# GOOD
+feat(auth): add password reset flow
+fix(cart): prevent duplicate items
+
+# BAD
+feat(auth): Added password reset flow.
+fix(cart): Fixes the duplicate items bug
+```
+
+### Body (Optional)
+
+Use for explaining:
+- **What** changed and **why**
+- Breaking changes
+- Related issues
+
+```
+feat(auth): add multi-factor authentication
+
+Implement TOTP-based 2FA for enhanced security.
+Users can now enable 2FA from their profile settings.
+
+- Add TOTP secret generation
+- Add QR code for authenticator apps
+- Add backup codes for recovery
+
+Closes #123
+```
+
+### Footer (Optional)
+
+```
+BREAKING CHANGE: API endpoint changed from /users to /api/v1/users
+
+Refs: #123, #456
+Co-authored-by: Name <email@example.com>
+```
+
+## Pull Request Template
+
+```markdown
+## Summary
+<!-- 1-3 bullet points describing the changes -->
+- Add user authentication with JWT
+- Implement password reset flow
+- Add comprehensive test coverage
+
+## Motivation
+<!-- Why is this change needed? -->
+Users need secure authentication to access protected resources.
+
+## Changes
+<!-- Detailed list of changes -->
+### Added
+- `AuthService` for handling authentication logic
+- `JWTProvider` for token generation/validation
+- Unit and integration tests for auth flow
+
+### Changed
+- Updated `UserController` to use AuthService
+- Modified API routes to require authentication
+
+### Removed
+- Deprecated session-based authentication
+
+## Testing
+<!-- How was this tested? -->
+- [x] Unit tests pass
+- [x] Integration tests pass
+- [x] Manual testing completed
+- [ ] E2E tests (pending)
+
+## Screenshots
+<!-- If applicable -->
+
+## Checklist
+- [x] Code follows project style guidelines
+- [x] Tests added/updated
+- [x] Documentation updated
+- [x] No breaking changes (or documented)
+- [x] Security considerations reviewed
+
+## Related Issues
+Closes #123
+Refs #456
+```
+
+## Commit Best Practices
+
+### Atomic Commits
+Each commit should be one logical change:
+
+```bash
+# GOOD: Separate commits for separate changes
+git commit -m "feat(user): add email validation"
+git commit -m "test(user): add email validation tests"
+
+# BAD: Multiple unrelated changes
+git commit -m "add email validation, fix bug, update docs"
+```
+
+### Commit Frequency
+- Commit when a logical unit is complete
+- Don't commit broken code
+- Small, frequent commits are better than large, infrequent ones
+
+### Commit Message Examples
+
+#### Feature
+```
+feat(cart): add quantity update functionality
+
+Allow users to update item quantities directly from the cart.
+Includes optimistic UI updates and error handling.
+
+- Add updateQuantity method to CartService
+- Add quantity input component
+- Add debounced API calls
+
+Closes #234
+```
+
+#### Bug Fix
+```
+fix(auth): prevent session fixation attack
+
+Regenerate session ID after successful login to prevent
+session fixation attacks.
+
+Security: OWASP A7 - Identification and Authentication Failures
+```
+
+#### Refactor
+```
+refactor(api): extract common error handling
+
+Move error handling logic to middleware for consistency
+across all API endpoints.
+
+- Create ErrorHandlerMiddleware
+- Add custom error classes
+- Update all controllers to throw custom errors
+
+No functional changes.
+```
+
+#### Breaking Change
+```
+feat(api)!: change user endpoint response format
+
+BREAKING CHANGE: The /api/users endpoint now returns
+a paginated response instead of an array.
+
+Before:
+[{ id: 1, name: "John" }, ...]
+
+After:
+{
+  data: [{ id: 1, name: "John" }, ...],
+  pagination: { page: 1, total: 100 }
+}
+
+Migration: Update all clients to handle the new response format.
+```
+
+## Branch Naming
+
+```
+<type>/<ticket>-<description>
+
+Examples:
+feature/AUTH-123-jwt-authentication
+bugfix/CART-456-duplicate-items
+hotfix/PROD-789-security-patch
+chore/update-dependencies
+```
+
+## Git Workflow
+
+### Before Committing
+```bash
+# Check status
+git status
+
+# Review changes
+git diff
+
+# Stage specific files
+git add src/auth/
+
+# Or stage all
+git add -A
+```
+
+### Creating Commit
+```bash
+# With message
+git commit -m "feat(auth): add login endpoint"
+
+# Open editor for longer message
+git commit
+```
+
+### Before PR
+```bash
+# Update from main
+git fetch origin main
+git rebase origin/main
+
+# Run tests
+{your test command}  # e.g., npm test, pytest, cargo test, go test
+
+# Push
+git push origin feature/AUTH-123-jwt-auth
+```
+
+## Quality Checklist
+
+- [ ] Commit message follows format
+- [ ] Type prefix is appropriate
+- [ ] Scope is specific
+- [ ] Subject is imperative and concise
+- [ ] Body explains why (if needed)
+- [ ] Breaking changes documented
+- [ ] Related issues linked
+- [ ] Branch name follows convention
+- [ ] Tests pass before commit
+- [ ] PR description complete