aiwcli 0.9.0

package/dist/lib/template-installer.js

@@ -0,0 +1,375 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { IdePathResolver } from './ide-path-resolver.js';
+import { mergeTemplateContent } from './template-merger.js';
+/**
+ * Deep merge two settings objects, combining hook arrays.
+ * Used to merge _shared/settings.json into .claude/settings.json
+ */
+function deepMergeSettings(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        // Skip comment fields
+        if (key.startsWith('$') || key.startsWith('_')) {
+            continue;
+        }
+        const sourceValue = source[key];
+        const targetValue = result[key];
+        if (key === 'hooks' && typeof sourceValue === 'object' && sourceValue !== null) {
+            // Special handling for hooks - merge by event type
+            result[key] = mergeHooks(targetValue || {}, sourceValue);
+        }
+        else if (Array.isArray(sourceValue) && Array.isArray(targetValue)) {
+            // Concatenate arrays
+            result[key] = [...targetValue, ...sourceValue];
+        }
+        else if (typeof sourceValue === 'object' && sourceValue !== null && typeof targetValue === 'object' && targetValue !== null) {
+            // Recursively merge objects
+            result[key] = deepMergeSettings(targetValue, sourceValue);
+        }
+        else {
+            // Override with source value
+            result[key] = sourceValue;
+        }
+    }
+    return result;
+}
+/**
+ * Merge hook configurations, combining arrays for each event type.
+ */
+function mergeHooks(target, source) {
+    const result = { ...target };
+    for (const eventType of Object.keys(source)) {
+        const targetHooks = result[eventType];
+        const sourceHooks = source[eventType];
+        if (targetHooks && sourceHooks) {
+            // Append source hooks to existing event type
+            result[eventType] = [...targetHooks, ...sourceHooks];
+        }
+        else if (sourceHooks) {
+            // New event type
+            result[eventType] = sourceHooks;
+        }
+    }
+    return result;
+}
+/**
+ * Merge settings from a source settings.json file into the IDE settings file.
+ * Reads from the provided source path and merges into .claude/settings.json at project root.
+ *
+ * @param targetDir - Project root directory
+ * @param sourceSettingsPath - Absolute path to source settings.json file
+ * @returns true if merge successful, false otherwise
+ */
+async function mergeSharedSettingsFromSource(targetDir, sourceSettingsPath) {
+    const resolver = new IdePathResolver(targetDir);
+    const ideSettingsPath = resolver.getClaudeSettings();
+    // Check if source settings exists
+    if (!(await pathExists(sourceSettingsPath))) {
+        return false;
+    }
+    try {
+        // Read source settings
+        const sourceContent = await fs.readFile(sourceSettingsPath, 'utf8');
+        const sourceSettings = JSON.parse(sourceContent);
+        // Read IDE settings (create empty object if doesn't exist)
+        let ideSettings = {};
+        if (await pathExists(ideSettingsPath)) {
+            const ideContent = await fs.readFile(ideSettingsPath, 'utf8');
+            ideSettings = JSON.parse(ideContent);
+        }
+        else {
+            // Create .claude directory if it doesn't exist
+            await fs.mkdir(dirname(ideSettingsPath), { recursive: true });
+        }
+        // Merge source settings into IDE settings
+        const mergedSettings = deepMergeSettings(ideSettings, sourceSettings);
+        // Write merged settings back
+        await fs.writeFile(ideSettingsPath, JSON.stringify(mergedSettings, null, 4) + '\n', 'utf8');
+        return true;
+    }
+    catch {
+        // Silently fail on parse/write errors
+        return false;
+    }
+}
+/**
+ * Check if a path exists
+ */
+async function pathExists(path) {
+    try {
+        await fs.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check template installation status for a method.
+ * Returns which items exist and which are missing.
+ *
+ * @param templatePath - Path to the template directory
+ * @param targetDir - Target directory to check
+ * @param ides - List of IDEs to check (for dot folders)
+ * @param templateName - Name of the template (for identifying workflow folder)
+ * @returns Status of template items
+ */
+export async function checkTemplateStatus(templatePath, targetDir, ides, templateName) {
+    const existing = [];
+    const missing = [];
+    // Scan template directory
+    const entries = await fs.readdir(templatePath, { withFileTypes: true });
+    // Identify workflow folder based on template name
+    // Convention: _templatename (e.g., _gsd, _bmad)
+    const workflowFolderName = `_${templateName}`;
+    let workflowFolder = null;
+    let workflowFolderExists = false;
+    // Filter entries to only include relevant items (skip non-selected IDE folders and excluded patterns)
+    const relevantEntries = entries.filter((entry) => {
+        // Skip excluded patterns (test files, cache, etc.)
+        if (shouldExclude(entry.name)) {
+            return false;
+        }
+        if (entry.name.startsWith('.') && entry.isDirectory()) {
+            const ideName = entry.name.slice(1);
+            return ides.includes(ideName);
+        }
+        return true;
+    });
+    // Check all entries in parallel
+    // Non-dot folders go into .aiwcli/, dot folders stay at project root
+    const resolver = new IdePathResolver(targetDir);
+    const containerDir = resolver.getAiwcliContainer();
+    const statusChecks = relevantEntries.map(async (entry) => {
+        // Dot folders (IDE folders) are at project root, non-dot folders are in .aiwcli/
+        const targetPath = entry.name.startsWith('.')
+            ? resolver.getIdeDir(entry.name.slice(1))
+            : join(containerDir, entry.name);
+        const exists = await pathExists(targetPath);
+        return {
+            name: entry.name,
+            isDirectory: entry.isDirectory(),
+            exists,
+        };
+    });
+    const statuses = await Promise.all(statusChecks);
+    for (const status of statuses) {
+        if (status.exists) {
+            existing.push(status);
+        }
+        else {
+            missing.push(status);
+        }
+        // Track workflow folder
+        if (status.name === workflowFolderName) {
+            workflowFolder = workflowFolderName;
+            workflowFolderExists = status.exists;
+        }
+    }
+    return {
+        existing,
+        missing,
+        workflowFolder,
+        workflowFolderExists,
+    };
+}
+/**
+ * Patterns to exclude when copying template directories.
+ * These are development/test artifacts that shouldn't be packaged.
+ */
+const EXCLUDED_PATTERNS = [
+    '_output',
+    '__pycache__',
+    '.pytest_cache',
+    'conftest.py',
+    /^test_.*\.py$/,
+    /.*\.pyc$/,
+];
+/**
+ * Check if a filename should be excluded from copying
+ */
+function shouldExclude(name) {
+    return EXCLUDED_PATTERNS.some((pattern) => {
+        if (typeof pattern === 'string') {
+            return name === pattern;
+        }
+        return pattern.test(name);
+    });
+}
+/**
+ * Copy directory recursively with proper error handling.
+ * Excludes test files, cache directories, and output folders.
+ *
+ * @param src - Source directory path
+ * @param dest - Destination directory path
+ * @param excludeIdeFolders - If true, exclude IDE config folders (.claude, .windsurf, etc.)
+ */
+export async function copyDir(src, dest, excludeIdeFolders = false) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    const operations = entries
+        .filter((entry) => {
+        // Standard exclusions (test files, cache, etc.)
+        if (shouldExclude(entry.name)) {
+            return false;
+        }
+        // Exclude IDE config folders if requested (used for _shared folder)
+        // These folders are used for settings merging, not direct installation
+        if (excludeIdeFolders && entry.isDirectory() && entry.name.startsWith('.')) {
+            return false;
+        }
+        return true;
+    })
+        .map(async (entry) => {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        try {
+            return entry.isDirectory() ? await copyDir(srcPath, destPath, excludeIdeFolders) : await fs.copyFile(srcPath, destPath);
+        }
+        catch (error) {
+            const err = error;
+            throw new Error(`Failed to copy ${srcPath} to ${destPath}: ${err.message}`);
+        }
+    });
+    await Promise.all(operations);
+}
+/**
+ * Install template with IDE-specific folder selection.
+ * Supports selective installation - only installs items that don't already exist.
+ *
+ * Template structure:
+ * - Non-dot folders (e.g., _bmad/, GSR/) are installed if not already present
+ * - Dot folders (e.g., .claude/, .windsurf/) are installed only if matching IDE flag and not already present
+ *
+ * @param config - Installation configuration
+ * @param skipExisting - If true, skip items that already exist (default: true for regeneration support)
+ * @returns Installation result with list of installed and skipped folders
+ * @throws Error if template doesn't exist or requested IDE folder not found
+ */
+export async function installTemplate(config, skipExisting = true) {
+    const { templateName, targetDir, ides, templatePath } = config;
+    // Verify template exists
+    try {
+        await fs.access(templatePath);
+    }
+    catch {
+        throw new Error(`Template '${templateName}' not found at ${templatePath}. ` +
+            `This indicates a corrupted installation. Please reinstall aiwcli.`);
+    }
+    // Scan template directory to classify folders (excluding test/cache patterns)
+    const entries = await fs.readdir(templatePath, { withFileTypes: true });
+    const directories = entries.filter((entry) => entry.isDirectory() && !shouldExclude(entry.name));
+    const nonDotFolders = [];
+    const dotFolders = new Map(); // ide name -> folder name
+    for (const dir of directories) {
+        if (dir.name.startsWith('.')) {
+            // Extract IDE name from dot folder (e.g., '.claude' -> 'claude')
+            const ideName = dir.name.slice(1);
+            dotFolders.set(ideName, dir.name);
+        }
+        else {
+            nonDotFolders.push(dir.name);
+        }
+    }
+    // Validate requested IDE folders exist in template
+    const availableIdes = [...dotFolders.keys()];
+    const missingIdes = ides.filter((ide) => !dotFolders.has(ide));
+    if (missingIdes.length > 0) {
+        throw new Error(`IDE '${missingIdes[0]}' not available for template '${templateName}'. ` +
+            `Available: ${availableIdes.join(', ')}`);
+    }
+    const installedFolders = [];
+    const skippedFolders = [];
+    const mergedFolders = [];
+    let mergedFileCount = 0;
+    // Create .aiwcli container folder for method-specific files
+    const resolver = new IdePathResolver(targetDir);
+    const containerDir = resolver.getAiwcliContainer();
+    await fs.mkdir(containerDir, { recursive: true });
+    // Install non-dot folders into .aiwcli/ container (skip if already exist and skipExisting is true)
+    const nonDotInstalls = nonDotFolders.map(async (folder) => {
+        const srcPath = join(templatePath, folder);
+        // Destination is inside .aiwcli/ container
+        const destPath = join(containerDir, folder);
+        if (skipExisting && (await pathExists(destPath))) {
+            return { folder, skipped: true };
+        }
+        await copyDir(srcPath, destPath);
+        return { folder, skipped: false };
+    });
+    const nonDotResults = await Promise.all(nonDotInstalls);
+    for (const result of nonDotResults) {
+        if (result.skipped) {
+            skippedFolders.push(result.folder);
+        }
+        else {
+            installedFolders.push(result.folder);
+        }
+    }
+    // Install root-level _shared directory (shared across all templates)
+    // This is at templates/_shared, not inside the specific template directory
+    // Exclude IDE config folders (.claude, .windsurf) - they are used for settings merging only
+    const templatesRoot = dirname(templatePath);
+    const rootSharedSrc = join(templatesRoot, '_shared');
+    const rootSharedDest = join(containerDir, '_shared');
+    if (await pathExists(rootSharedSrc)) {
+        if (skipExisting && (await pathExists(rootSharedDest))) {
+            skippedFolders.push('_shared');
+        }
+        else {
+            await copyDir(rootSharedSrc, rootSharedDest, true); // excludeIdeFolders = true
+            installedFolders.push('_shared');
+        }
+    }
+    // Install matching IDE folders
+    // If folder exists, merge content recursively by looking for method name folders
+    const ideInstalls = ides.map(async (ide) => {
+        const folderName = dotFolders.get(ide);
+        if (folderName) {
+            const srcPath = join(templatePath, folderName);
+            const destPath = resolver.getIdeDir(ide);
+            if (await pathExists(destPath)) {
+                if (skipExisting) {
+                    // Folder exists - merge template content by finding method-named folders
+                    const mergeResult = await mergeTemplateContent(srcPath, destPath, templateName);
+                    return {
+                        folder: folderName,
+                        skipped: false,
+                        merged: true,
+                        mergedFiles: mergeResult.copiedFiles.length,
+                    };
+                }
+                // skipExisting is false, so overwrite
+                await copyDir(srcPath, destPath);
+                return { folder: folderName, skipped: false, merged: false, mergedFiles: 0 };
+            }
+            await copyDir(srcPath, destPath);
+            return { folder: folderName, skipped: false, merged: false, mergedFiles: 0 };
+        }
+        return null;
+    });
+    const ideResults = (await Promise.all(ideInstalls)).filter((result) => result !== null);
+    for (const result of ideResults) {
+        if (result.merged) {
+            mergedFolders.push(result.folder);
+            mergedFileCount += result.mergedFiles;
+        }
+        else if (result.skipped) {
+            skippedFolders.push(result.folder);
+        }
+        else {
+            installedFolders.push(result.folder);
+        }
+    }
+    // Settings merging is now handled by the caller via mergeMethodsSettings()
+    // This allows unified merging of _shared + method-specific settings
+    return {
+        installedFolders,
+        skippedFolders,
+        mergedFolders,
+        mergedFileCount,
+        sharedSettingsMerged: false, // Deprecated, kept for backwards compatibility
+        templatePath,
+    };
+}

package/dist/lib/template-linter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Template Linter
+ *
+ * Validates workflow markdown files within templates for:
+ * - Correct output paths (_output/{method}/)
+ * - No cross-method contamination (gsd referencing bmad paths)
+ * - Proper template references (_{method}/templates/)
+ * - Correct workflow references (/method:workflow)
+ */
+export interface LintViolation {
+    file: string;
+    line: number;
+    match: string;
+    message: string;
+    rule: string;
+}
+export interface LintRule {
+    description: string;
+    /** Message template - use {match} for the matched text */
+    message: string;
+    name: string;
+    /** Regex to find violations - matches indicate problems */
+    pattern: RegExp;
+}
+/**
+ * Generate lint rules for a specific method
+ * Rules detect when a method's workflows reference other methods incorrectly
+ */
+export declare function getRulesForMethod(method: string): LintRule[];
+/**
+ * Lint a single file's content
+ */
+export declare function lintFileContent(content: string, filePath: string, rules: LintRule[]): LintViolation[];
+/**
+ * Get all markdown files in a template method directory
+ */
+export declare function getTemplateMarkdownFiles(templatesDir: string, method: string): string[];
+/**
+ * Lint all markdown files for a specific template method
+ */
+export declare function lintTemplateMethod(templatesDir: string, method: string): LintViolation[];
+/**
+ * Lint all template methods in a templates directory
+ */
+export declare function lintAllTemplates(templatesDir: string): Map<string, LintViolation[]>;
+/**
+ * Format violations for display
+ */
+export declare function formatViolations(violations: LintViolation[], basePath?: string): string;

package/dist/lib/template-linter.js

@@ -0,0 +1,173 @@
+/**
+ * Template Linter
+ *
+ * Validates workflow markdown files within templates for:
+ * - Correct output paths (_output/{method}/)
+ * - No cross-method contamination (gsd referencing bmad paths)
+ * - Proper template references (_{method}/templates/)
+ * - Correct workflow references (/method:workflow)
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str) {
+    return str.replaceAll(/[$()*+.?[\\\]^{|}]/g, String.raw `\$&`);
+}
+/**
+ * Generate lint rules for a specific method
+ * Rules detect when a method's workflows reference other methods incorrectly
+ */
+export function getRulesForMethod(method) {
+    // Known methods to check against
+    const allMethods = ['cc-native'];
+    const otherMethods = allMethods.filter((m) => m !== method);
+    // Create regex pattern that matches other methods but not the current one
+    const otherMethodsPattern = otherMethods.map((m) => escapeRegex(m)).join('|');
+    return [
+        {
+            description: `Output paths should use _output/${method}/, not other methods`,
+            message: `Wrong method in output path: {match} (should be _output/${method}/)`,
+            name: 'wrong-output-path',
+            pattern: new RegExp(`_output/(${otherMethodsPattern})/`, 'g'),
+        },
+        {
+            description: `Template references should use _${method}/templates/, not other methods`,
+            message: `Wrong method in template reference: {match} (should be _${method}/templates/)`,
+            name: 'wrong-template-ref',
+            pattern: new RegExp(`_(${otherMethodsPattern})/templates/`, 'g'),
+        },
+        {
+            description: `Workflow references should use /${method}:, not other methods`,
+            message: `Wrong method in workflow reference: {match} (should be /${method}:)`,
+            name: 'wrong-workflow-ref',
+            pattern: new RegExp(`/(${otherMethodsPattern}):`, 'g'),
+        },
+        {
+            description: `Method folder references should use _${method}/, not other methods`,
+            message: `Wrong method in folder reference: {match} (should be _${method}/workflows/)`,
+            name: 'wrong-method-folder',
+            pattern: new RegExp(`_(${otherMethodsPattern})/workflows/`, 'g'),
+        },
+        // Note: bare-output-file rule removed as it produces too many false positives
+        // in README documentation that explains workflow outputs.
+        // The cross-method contamination rules are the primary value of this linter.
+    ];
+}
+/**
+ * Check a single line for violations of a rule
+ */
+function checkLineForViolations(line, lineNum, filePath, rule) {
+    const violations = [];
+    // Skip code block fences and comments
+    if (line.trim().startsWith('```') || line.trim().startsWith('<!--')) {
+        return violations;
+    }
+    // Reset regex for this line
+    rule.pattern.lastIndex = 0;
+    let match;
+    while ((match = rule.pattern.exec(line)) !== null) {
+        violations.push({
+            file: filePath,
+            line: lineNum + 1,
+            match: match[0],
+            message: rule.message.replace('{match}', match[0]),
+            rule: rule.name,
+        });
+    }
+    return violations;
+}
+/**
+ * Lint a single file's content
+ */
+export function lintFileContent(content, filePath, rules) {
+    const violations = [];
+    const lines = content.split('\n');
+    for (const rule of rules) {
+        // Reset regex state for each rule
+        rule.pattern.lastIndex = 0;
+        for (const [lineNum, line] of lines.entries()) {
+            const lineViolations = checkLineForViolations(line, lineNum, filePath, rule);
+            violations.push(...lineViolations);
+        }
+    }
+    return violations;
+}
+/**
+ * Get all markdown files in a template method directory
+ */
+export function getTemplateMarkdownFiles(templatesDir, method) {
+    const methodDir = path.join(templatesDir, method);
+    const files = [];
+    if (!existsSync(methodDir)) {
+        return files;
+    }
+    function walkDir(dir) {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                // Skip node_modules and hidden dirs (except .claude, .windsurf, .cursor)
+                if (entry.name === 'node_modules' ||
+                    (entry.name.startsWith('.') &&
+                        !entry.name.startsWith('.claude') &&
+                        !entry.name.startsWith('.windsurf') &&
+                        !entry.name.startsWith('.cursor'))) {
+                    continue;
+                }
+                walkDir(fullPath);
+            }
+            else if (entry.name.endsWith('.md') && !entry.name.endsWith('.template')) {
+                // Only lint .md files, not .md.template files (those have placeholders)
+                files.push(fullPath);
+            }
+        }
+    }
+    walkDir(methodDir);
+    return files;
+}
+/**
+ * Lint all markdown files for a specific template method
+ */
+export function lintTemplateMethod(templatesDir, method) {
+    const rules = getRulesForMethod(method);
+    const files = getTemplateMarkdownFiles(templatesDir, method);
+    const allViolations = [];
+    for (const filePath of files) {
+        const content = readFileSync(filePath, 'utf8');
+        const violations = lintFileContent(content, filePath, rules);
+        allViolations.push(...violations);
+    }
+    return allViolations;
+}
+/**
+ * Lint all template methods in a templates directory
+ */
+export function lintAllTemplates(templatesDir) {
+    const results = new Map();
+    const methods = ['cc-native'];
+    for (const method of methods) {
+        const methodDir = path.join(templatesDir, method);
+        if (existsSync(methodDir)) {
+            results.set(method, lintTemplateMethod(templatesDir, method));
+        }
+    }
+    return results;
+}
+/**
+ * Format violations for display
+ */
+export function formatViolations(violations, basePath) {
+    if (violations.length === 0) {
+        return 'No violations found.';
+    }
+    return violations
+        .map((v) => {
+        const relativePath = basePath
+            ? path.relative(basePath, v.file)
+            : v.file;
+        return `${relativePath}:${v.line} [${v.rule}] ${v.message}`;
+    })
+        .join('\n');
+}

package/dist/lib/template-merger.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Content folder types that should be recursively merged rather than skipped.
+ * These are the canonical folder names used in templates for organizing content.
+ */
+export declare const CONTENT_FOLDER_TYPES: readonly ["agents", "commands", "workflows", "tasks"];
+/**
+ * Result of merging content folders
+ */
+export interface MergeResult {
+    /** Files that were copied */
+    copiedFiles: string[];
+    /** Directories that were created */
+    createdDirs: string[];
+    /** Files that were skipped (already exist) */
+    skippedFiles: string[];
+}
+/**
+ * Recursively find folders matching the method name within a directory tree.
+ * This finds folders like `.claude/commands/bmad/` when methodName is 'bmad'.
+ *
+ * @param dir - Directory to search
+ * @param methodName - Method name to look for (e.g., 'bmad', 'gsd')
+ * @returns Array of paths to matching folders
+ */
+export declare function findMethodFolders(dir: string, methodName: string): Promise<string[]>;
+/**
+ * Merge template content into an existing IDE folder.
+ * Recursively finds folders matching the method name and merges their content.
+ *
+ * This enables adding new agents, commands, workflows, and tasks from a template
+ * even when the IDE folder (e.g., .claude) already exists.
+ *
+ * @param templateIdePath - Path to the template's IDE folder (e.g., template/.claude)
+ * @param targetIdePath - Path to the target's IDE folder (e.g., project/.claude)
+ * @param methodName - Method name to look for (e.g., 'bmad', 'gsd')
+ * @returns Merge results
+ */
+export declare function mergeTemplateContent(templateIdePath: string, targetIdePath: string, methodName: string): Promise<MergeResult>;
+/**
+ * Merge content type folders (agents, commands, workflows, tasks) from template to target.
+ * This is an alternative approach that looks for specific folder types rather than method names.
+ *
+ * @param templateIdePath - Path to the template's IDE folder
+ * @param targetIdePath - Path to the target's IDE folder
+ * @returns Merge results
+ */
+export declare function mergeContentTypeFolders(templateIdePath: string, targetIdePath: string): Promise<MergeResult>;