@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/smiths/skillsmith/collision-detector.js

@@ -0,0 +1,249 @@
+/**
+ * Skill Deployment Collision Detector
+ *
+ * Scans target platform directories before `aiwg use` to identify name conflicts
+ * between skills being deployed and existing skills already present.
+ *
+ * Severity levels:
+ * - none    — target path does not exist, deploy silently
+ * - info    — target exists and is owned by the same namespace, overwrite silently
+ * - warn    — target exists and is owned by a different namespace or user, prompt user
+ * - error   — name matches a known platform built-in or AIWG CLI command, block deployment
+ *
+ * @see adr-skill-namespace-strategy.md
+ * @implements #698
+ * @implements #804
+ */
+import { promises as fs } from 'fs';
+import { createHash } from 'crypto';
+import * as path from 'path';
+// ============================================
+// Platform Built-in Blocklists
+// ============================================
+/**
+ * Platform built-in commands that must never be overwritten.
+ * Attempting to deploy a skill with one of these names is an ERROR.
+ */
+const PLATFORM_BUILTINS = {
+    'claude': [
+        'help', 'clear', 'compact', 'review', 'init', 'doctor',
+        'memory', 'settings', 'logout', 'login', 'mcp', 'migrate',
+    ],
+    'cursor': ['settings', 'chat', 'edit'],
+    'codex': ['help', 'run', 'exec'],
+    'copilot': ['help', 'explain', 'fix', 'tests', 'review'],
+    'windsurf': ['help', 'settings'],
+    'opencode': ['help', 'run'],
+    'warp': ['help', 'settings'],
+    'hermes': [],
+    'openclaw': [],
+    'openhuman': [],
+    'factory': [],
+    'generic': [],
+};
+// Note: previously this module also blocked `aiwg-{cliCommand}` slugs (e.g.
+// `aiwg-doctor`) as "shadowing" the AIWG CLI. That check was removed because
+// it directly contradicted the namespace migration strategy: `/aiwg-doctor`
+// IS the canonical slug for the doctor skill (the bare `doctor` collides with
+// Claude's built-in). Slash commands and shell CLI commands live on different
+// surfaces and do not actually conflict at runtime.
+// See: docs/migration/skill-namespace-migration.md, .aiwg/architecture/adr-skill-namespace-strategy.md
+// ============================================
+// Ownership Attribution
+// ============================================
+/**
+ * Determine if an existing skill directory is owned by the given namespace.
+ *
+ * A skill is owned by `namespace` when ANY of:
+ * 1. Its SKILL.md frontmatter contains `namespace: {namespace}`
+ * 2. Its parent directory is named after the namespace (e.g. `.claude/skills/aiwg/`)
+ *
+ * This generalises the original AIWG-only check to support any package namespace,
+ * enabling correct cross-namespace collision severity for third-party packages (#804).
+ *
+ * @param skillPath - Absolute path to the skill directory
+ * @param namespace - Namespace to test ownership against (default: 'aiwg')
+ */
+export async function isOwnedByNamespace(skillPath, namespace = 'aiwg') {
+    // Check 1: namespace in SKILL.md frontmatter
+    const skillFile = path.join(skillPath, 'SKILL.md');
+    try {
+        const content = await fs.readFile(skillFile, 'utf-8');
+        // Match `namespace: <value>` line where value equals the queried namespace
+        const nsMatch = content.match(/^namespace:\s*(.+?)\s*$/m);
+        if (nsMatch && nsMatch[1] === namespace) {
+            return true;
+        }
+    }
+    catch {
+        // file doesn't exist or unreadable — not owned
+    }
+    // Check 2: deployed under a namespace subdirectory
+    const parentDir = path.basename(path.dirname(skillPath));
+    if (parentDir === namespace) {
+        return true;
+    }
+    return false;
+}
+// ============================================
+// Content Hash Comparison
+// ============================================
+/**
+ * Compute MD5 hash of a file's content. Returns null if unreadable.
+ */
+async function fileHash(filePath) {
+    try {
+        const content = await fs.readFile(filePath);
+        return createHash('md5').update(content).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if the source skill SKILL.md matches the deployed SKILL.md by content hash.
+ * Returns true when both exist and have identical content (no update needed).
+ */
+async function skillContentUnchanged(sourceDir, deployedDir) {
+    const srcFile = path.join(sourceDir, 'SKILL.md');
+    const dstFile = path.join(deployedDir, 'SKILL.md');
+    const [srcHash, dstHash] = await Promise.all([fileHash(srcFile), fileHash(dstFile)]);
+    if (!srcHash || !dstHash)
+        return false;
+    return srcHash === dstHash;
+}
+// ============================================
+// Collision Check
+// ============================================
+/**
+ * Check for deployment collisions before writing skills to a platform directory.
+ *
+ * Ownership comparison uses the deploying package's namespace:
+ * - Same namespace overwrites → `info` severity (silent upgrade)
+ * - Cross-namespace or user-owned overwrites → `warn` severity (user confirmation)
+ *
+ * @param options - Collision check parameters
+ * @returns Array of collision results, one per skill name. Only non-`none` results
+ *          are returned (clean deployments are omitted).
+ */
+export async function checkCollisions(options) {
+    const { platform, projectPath, skillNames, skillsBaseDir, sourceSkillsDir, namespace = 'aiwg' } = options;
+    const platformBuiltins = new Set(PLATFORM_BUILTINS[platform] ?? []);
+    const results = [];
+    for (const skillName of skillNames) {
+        const targetPath = skillsBaseDir
+            ? path.join(skillsBaseDir, skillName)
+            : path.join(projectPath, `.${platform}/skills`, skillName);
+        // Check 1: Platform built-in collision (literal slug only).
+        //
+        // The namespaced canonical slug (e.g. `aiwg-doctor`) is the actual command
+        // registered with the platform — it does NOT collide with the platform's bare
+        // built-in (`doctor`). The whole point of the `aiwg-` prefix per
+        // `docs/migration/skill-namespace-migration.md` is to side-step platform built-ins.
+        //
+        // Only check the literal skillName here. Bare names like `doctor` (no prefix)
+        // are still caught and blocked.
+        if (platformBuiltins.has(skillName)) {
+            results.push({
+                skillName,
+                targetPath,
+                severity: 'error',
+                reason: `'${skillName}' matches a ${platform} platform built-in command`,
+                blocksDeployment: true,
+            });
+            continue;
+        }
+        // Check 2: Target path existence
+        let exists = false;
+        try {
+            await fs.access(targetPath);
+            exists = true;
+        }
+        catch {
+            // doesn't exist — no collision
+        }
+        if (!exists) {
+            // No collision, don't add to results
+            continue;
+        }
+        // Check 3: Ownership of existing skill
+        // Same-namespace overwrites are silent upgrades (info).
+        // Cross-namespace or unowned overwrites require user confirmation (warn).
+        const ownedBySameNamespace = await isOwnedByNamespace(targetPath, namespace);
+        if (ownedBySameNamespace) {
+            // Check if content is actually unchanged — skip silently if identical
+            if (sourceSkillsDir) {
+                const sourceDir = path.join(sourceSkillsDir, skillName);
+                const unchanged = await skillContentUnchanged(sourceDir, targetPath);
+                if (unchanged) {
+                    // Identical content — no collision, no output needed
+                    continue;
+                }
+            }
+            results.push({
+                skillName,
+                targetPath,
+                severity: 'info',
+                reason: `'${skillName}' updating`,
+                blocksDeployment: false,
+            });
+        }
+        else {
+            results.push({
+                skillName,
+                targetPath,
+                severity: 'warn',
+                reason: `'${skillName}' already exists at ${targetPath} and is not owned by namespace '${namespace}' — will overwrite existing skill`,
+                blocksDeployment: false,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Format collision results as a human-readable warning block.
+ *
+ * @param results - Collision results from `checkCollisions()`
+ * @param options - Formatting options
+ * @param options.verbose - When false, suppress info-level messages (same-namespace updates)
+ * @returns Formatted string for CLI output, or empty string if no results
+ */
+export function formatCollisionReport(results, options = {}) {
+    if (results.length === 0)
+        return '';
+    const { verbose = false } = options;
+    const errors = results.filter((r) => r.severity === 'error');
+    const warnings = results.filter((r) => r.severity === 'warn');
+    const infos = results.filter((r) => r.severity === 'info');
+    const lines = [];
+    if (errors.length > 0) {
+        lines.push('');
+        lines.push('ERROR: Deployment blocked for the following skills:');
+        for (const r of errors) {
+            lines.push(`  ✗ ${r.skillName}: ${r.reason}`);
+        }
+    }
+    if (warnings.length > 0) {
+        lines.push('');
+        lines.push('WARNING: The following skills will overwrite content from a different namespace:');
+        for (const r of warnings) {
+            lines.push(`  ⚠ ${r.skillName}: ${r.reason}`);
+        }
+        lines.push('');
+        lines.push('  Use --force to overwrite, or --skip-conflicts to skip these skills.');
+    }
+    // Info-level (same-namespace updates) only shown in verbose mode
+    if (verbose && infos.length > 0 && errors.length === 0 && warnings.length === 0) {
+        for (const r of infos) {
+            lines.push(`  ℹ ${r.skillName}: ${r.reason}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Check if any collision results block deployment.
+ */
+export function hasBlockingCollisions(results) {
+    return results.some((r) => r.blocksDeployment);
+}
+//# sourceMappingURL=collision-detector.js.map

package/dist/src/smiths/skillsmith/demo.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * SkillSmith Demo
+ *
+ * Demonstrates SkillSmith functionality.
+ * Run: node --loader ts-node/esm src/smiths/skillsmith/demo.ts
+ *
+ * @module smiths/skillsmith/demo
+ */
+import { generateSkill, deploySkill } from './generator.js';
+import { PlatformSkillResolver } from './platform-resolver.js';
+// SkillOptions type used inline in generateSkill calls
+async function demo() {
+    console.log('=== SkillSmith Demo ===\n');
+    // Example 1: Generate a basic skill
+    console.log('1. Generating basic skill...');
+    const basicSkill = await generateSkill({
+        name: 'hello-world',
+        description: 'A simple hello world skill',
+        platform: 'claude',
+        projectPath: '/tmp/demo',
+        triggerPhrases: ['hello', 'say hello', 'greet'],
+    });
+    console.log(`   Generated: ${basicSkill.name}`);
+    console.log(`   Platform: ${basicSkill.platform}`);
+    console.log(`   Deploy path: ${basicSkill.path}\n`);
+    // Example 2: Generate skill with tools
+    console.log('2. Generating skill with tools...');
+    const toolSkill = await generateSkill({
+        name: 'file-analyzer',
+        description: 'Analyzes file structure and content',
+        platform: 'claude',
+        projectPath: '/tmp/demo',
+        tools: ['Read', 'Glob', 'Grep'],
+        triggerPhrases: ['analyze files', 'check structure', 'review files'],
+        createReferences: true,
+    });
+    console.log(`   Generated: ${toolSkill.name}`);
+    console.log(`   Tools: ${toolSkill.content.match(/tools: (.+)/)?.[1] || 'none'}`);
+    console.log(`   References: ${toolSkill.references?.length || 0} files\n`);
+    // Example 3: Platform-specific paths
+    console.log('3. Platform-specific deployment paths:');
+    const platforms = ['claude', 'factory', 'cursor'];
+    platforms.forEach((platform) => {
+        const basePath = PlatformSkillResolver.getBaseDir(platform, '/project');
+        const supports = PlatformSkillResolver.supportsSkills(platform);
+        const alternative = PlatformSkillResolver.getAlternativeStrategy(platform);
+        console.log(`   ${platform}:`);
+        console.log(`     Base: ${basePath}`);
+        console.log(`     Native support: ${supports}`);
+        if (!supports && alternative) {
+            console.log(`     Alternative: ${alternative}`);
+        }
+    });
+    console.log();
+    // Example 4: Skill name validation
+    console.log('4. Skill name validation:');
+    const names = ['valid-skill', 'Invalid_Name', 'also-valid', '-invalid'];
+    names.forEach((name) => {
+        const result = PlatformSkillResolver.validateSkillName(name);
+        console.log(`   "${name}": ${result.valid ? '✓ valid' : '✗ ' + result.error}`);
+    });
+    console.log();
+    // Example 5: Dry run deployment
+    console.log('5. Dry run deployment...');
+    const result = await deploySkill(basicSkill, '/tmp/demo', true);
+    console.log(`   Success: ${result.success}`);
+    console.log(`   Deploy path: ${result.deployPath}`);
+    console.log(`   Files created: ${result.filesCreated.length}\n`);
+    // Example 6: Show generated content
+    console.log('6. Sample generated content:');
+    console.log('   ---');
+    const lines = basicSkill.content.split('\n').slice(0, 20);
+    lines.forEach((line) => console.log(`   ${line}`));
+    console.log('   ...\n');
+    console.log('=== Demo Complete ===');
+}
+// Run demo if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    demo().catch(console.error);
+}
+export { demo };
+//# sourceMappingURL=demo.js.map

package/dist/src/smiths/skillsmith/examples.js

@@ -0,0 +1,161 @@
+/**
+ * SkillSmith Usage Examples
+ *
+ * Demonstrates how to use SkillSmith to generate skills.
+ *
+ * @module smiths/skillsmith/examples
+ */
+import { generateSkill, deploySkill } from './generator.js';
+/**
+ * Example 1: Generate a basic voice application skill
+ */
+export async function generateVoiceApplySkill(projectPath) {
+    const options = {
+        name: 'voice-apply',
+        description: 'Applies voice profiles to transform content',
+        platform: 'claude',
+        projectPath,
+        triggerPhrases: [
+            'apply voice',
+            'use voice',
+            'write in voice',
+            'transform to voice',
+        ],
+        tools: ['Read', 'Write'],
+        createReferences: true,
+        version: '1.0.0',
+    };
+    const skill = await generateSkill(options);
+    const result = await deploySkill(skill, projectPath);
+    console.log(`Deployed voice-apply skill to: ${result.deployPath}`);
+    console.log(`Files created: ${result.filesCreated.length}`);
+    return result;
+}
+/**
+ * Example 2: Generate a code analysis skill
+ */
+export async function generateCodeAnalyzerSkill(projectPath) {
+    const options = {
+        name: 'code-analyzer',
+        description: 'Analyzes code quality, patterns, and potential issues',
+        platform: 'claude',
+        projectPath,
+        triggerPhrases: [
+            'analyze code',
+            'check code quality',
+            'review code',
+            'find code issues',
+        ],
+        tools: ['Read', 'Glob', 'Grep', 'Bash'],
+        createReferences: true,
+    };
+    const skill = await generateSkill(options);
+    const result = await deploySkill(skill, projectPath);
+    return result;
+}
+/**
+ * Example 3: Generate a test generation skill
+ */
+export async function generateTestGeneratorSkill(projectPath) {
+    const options = {
+        name: 'test-generator',
+        description: 'Generates comprehensive test suites from code',
+        platform: 'claude',
+        projectPath,
+        triggerPhrases: ['generate tests', 'create test suite', 'write tests for'],
+        tools: ['Read', 'Write', 'Glob', 'Grep'],
+        guidance: 'Focus on edge cases and integration scenarios',
+    };
+    const skill = await generateSkill(options);
+    return deploySkill(skill, projectPath);
+}
+/**
+ * Example 4: Generate skill with dry-run
+ */
+export async function previewSkillGeneration(projectPath) {
+    const skill = await generateSkill({
+        name: 'example-skill',
+        description: 'An example skill',
+        platform: 'claude',
+        projectPath,
+        triggerPhrases: ['example', 'demo skill'],
+    });
+    // Preview without writing files
+    const result = await deploySkill(skill, projectPath, true);
+    console.log('Dry run result:', result);
+    return result;
+}
+/**
+ * Example 5: Generate skill for multiple platforms
+ */
+export async function generateMultiPlatformSkill(projectPath) {
+    const platforms = ['claude', 'factory', 'cursor'];
+    const results = [];
+    for (const platform of platforms) {
+        const skill = await generateSkill({
+            name: 'multi-platform-skill',
+            description: 'A skill that works across platforms',
+            platform,
+            projectPath,
+            triggerPhrases: ['multi platform', 'cross platform'],
+        });
+        const result = await deploySkill(skill, projectPath);
+        results.push(result);
+        console.log(`Deployed to ${platform}: ${result.deployPath}`);
+    }
+    return results;
+}
+/**
+ * Example 6: Generate skill with custom version
+ */
+export async function generateVersionedSkill(projectPath) {
+    const skill = await generateSkill({
+        name: 'versioned-skill',
+        description: 'A skill with version control',
+        platform: 'claude',
+        projectPath,
+        version: '2.1.0',
+        triggerPhrases: ['versioned example'],
+    });
+    return deploySkill(skill, projectPath);
+}
+/**
+ * Example 7: Batch generate skills from configuration
+ */
+export async function batchGenerateSkills(projectPath, skillConfigs) {
+    const results = [];
+    for (const config of skillConfigs) {
+        const skill = await generateSkill({
+            ...config,
+            projectPath,
+        });
+        const result = await deploySkill(skill, projectPath);
+        results.push(result);
+    }
+    console.log(`Generated ${results.length} skills`);
+    return results;
+}
+/**
+ * Example usage in a CLI or script
+ */
+export async function exampleCliUsage() {
+    const projectPath = process.cwd();
+    // Generate a single skill
+    await generateVoiceApplySkill(projectPath);
+    // Generate multiple skills
+    await batchGenerateSkills(projectPath, [
+        {
+            name: 'skill-one',
+            description: 'First skill',
+            platform: 'claude',
+            triggerPhrases: ['skill one'],
+        },
+        {
+            name: 'skill-two',
+            description: 'Second skill',
+            platform: 'claude',
+            triggerPhrases: ['skill two'],
+        },
+    ]);
+}
+//# sourceMappingURL=examples.js.map