@lumenflow/cli 1.6.0 → 2.1.0

package/dist/trace-gen.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * Trace Generator CLI Command
+ *
+ * Creates traceability reports linking WUs to code changes.
+ * Useful for audit trails, compliance documentation, and understanding
+ * what code was changed as part of each WU.
+ *
+ * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ *
+ * Usage:
+ *   pnpm trace:gen --wu WU-1112
+ *   pnpm trace:gen --since 2024-01-01 --format json
+ *   pnpm trace:gen --format markdown --output trace.md
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { parse as parseYaml } from 'yaml';
+import { EXIT_CODES, DIRECTORIES, FILE_SYSTEM } from '@lumenflow/core/dist/wu-constants.js';
+import { runCLI } from './cli-entry-point.js';
+/** Log prefix for console output */
+const LOG_PREFIX = '[trace:gen]';
+/**
+ * Output formats for trace report
+ */
+export var TraceFormat;
+(function (TraceFormat) {
+    TraceFormat["JSON"] = "json";
+    TraceFormat["MARKDOWN"] = "markdown";
+    TraceFormat["CSV"] = "csv";
+})(TraceFormat || (TraceFormat = {}));
+/**
+ * Parse command line arguments for trace-gen
+ *
+ * @param argv - Process argv array
+ * @returns Parsed arguments
+ */
+export function parseTraceArgs(argv) {
+    const args = {};
+    // Skip node and script name
+    const cliArgs = argv.slice(2);
+    for (let i = 0; i < cliArgs.length; i++) {
+        const arg = cliArgs[i];
+        if (arg === '--help' || arg === '-h') {
+            args.help = true;
+        }
+        else if (arg === '--wu' || arg === '-w') {
+            args.wuId = cliArgs[++i];
+        }
+        else if (arg === '--format' || arg === '-f') {
+            args.format = cliArgs[++i];
+        }
+        else if (arg === '--output' || arg === '-o') {
+            args.output = cliArgs[++i];
+        }
+        else if (arg === '--since' || arg === '-s') {
+            args.since = cliArgs[++i];
+        }
+    }
+    return args;
+}
+/**
+ * Build a trace entry from WU and commit data
+ *
+ * @param input - Input data containing WU info, commits, and files
+ * @returns Trace entry with summary statistics
+ */
+export function buildTraceEntry(input) {
+    const { wuId, title, status, commits, files } = input;
+    const entry = {
+        wuId,
+        title,
+        status,
+        commitCount: commits.length,
+        fileCount: files.length,
+    };
+    if (commits.length > 0) {
+        // Sort commits by date
+        const sorted = [...commits].sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+        entry.firstCommit = sorted[0].date;
+        entry.lastCommit = sorted[sorted.length - 1].date;
+        entry.commits = sorted;
+    }
+    if (files.length > 0) {
+        entry.files = files;
+    }
+    return entry;
+}
+/**
+ * Get commits for a WU by searching git log
+ */
+function getWuCommits(wuId) {
+    try {
+        const output = execSync(`git log --all --oneline --date=iso-strict --format="%H|%ad|%s" --grep="${wuId}"`, { encoding: FILE_SYSTEM.ENCODING });
+        const commits = [];
+        for (const line of output.trim().split('\n')) {
+            if (!line)
+                continue;
+            const [sha, date, ...messageParts] = line.split('|');
+            commits.push({
+                sha: sha.slice(0, 8),
+                date,
+                message: messageParts.join('|'),
+            });
+        }
+        return commits;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get files changed by a WU
+ */
+function getWuFiles(wuId) {
+    try {
+        const output = execSync(`git log --all --name-only --format="" --grep="${wuId}" | sort -u`, {
+            encoding: FILE_SYSTEM.ENCODING,
+        });
+        return output
+            .trim()
+            .split('\n')
+            .filter((f) => f.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get WU info from YAML file
+ */
+function getWuInfo(wuId) {
+    const yamlPath = join(process.cwd(), DIRECTORIES.WU_DIR, `${wuId}.yaml`);
+    if (!existsSync(yamlPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(yamlPath, { encoding: FILE_SYSTEM.ENCODING });
+        const yaml = parseYaml(content);
+        return {
+            title: yaml?.title || wuId,
+            status: yaml?.status || 'unknown',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Format trace report as JSON
+ */
+function formatJson(entries) {
+    return JSON.stringify(entries, null, 2);
+}
+/**
+ * Format trace report as Markdown
+ */
+function formatMarkdown(entries) {
+    const lines = [
+        '# Traceability Report',
+        '',
+        `Generated: ${new Date().toISOString()}`,
+        '',
+        '## WU Summary',
+        '',
+        '| WU ID | Title | Status | Commits | Files |',
+        '|-------|-------|--------|---------|-------|',
+    ];
+    for (const entry of entries) {
+        lines.push(`| ${entry.wuId} | ${entry.title.slice(0, 30)} | ${entry.status} | ${entry.commitCount} | ${entry.fileCount} |`);
+    }
+    lines.push('', '## Details', '');
+    for (const entry of entries) {
+        lines.push(`### ${entry.wuId}: ${entry.title}`, '');
+        lines.push(`- **Status:** ${entry.status}`);
+        lines.push(`- **Commits:** ${entry.commitCount}`);
+        lines.push(`- **Files:** ${entry.fileCount}`);
+        if (entry.firstCommit) {
+            lines.push(`- **First commit:** ${entry.firstCommit}`);
+            lines.push(`- **Last commit:** ${entry.lastCommit}`);
+        }
+        if (entry.files && entry.files.length > 0) {
+            lines.push('', '**Files changed:**');
+            for (const file of entry.files.slice(0, 20)) {
+                lines.push(`- ${file}`);
+            }
+            if (entry.files.length > 20) {
+                lines.push(`- ... and ${entry.files.length - 20} more`);
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Format trace report as CSV
+ */
+function formatCsv(entries) {
+    const lines = ['WU ID,Title,Status,Commits,Files,First Commit,Last Commit'];
+    for (const entry of entries) {
+        const title = entry.title.replace(/,/g, ';');
+        lines.push(`${entry.wuId},"${title}",${entry.status},${entry.commitCount},${entry.fileCount},${entry.firstCommit || ''},${entry.lastCommit || ''}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Print help message for trace-gen
+ */
+/* istanbul ignore next -- CLI entry point */
+function printHelp() {
+    console.log(`
+Usage: trace-gen [options]
+
+Generate traceability reports linking WUs to code changes.
+
+Options:
+  -w, --wu <id>       Trace specific WU (otherwise traces all)
+  -f, --format <fmt>  Output format: json, markdown, csv (default: json)
+  -o, --output <file> Write output to file (default: stdout)
+  -s, --since <date>  Only trace WUs modified since date (ISO format)
+  -h, --help          Show this help message
+
+Examples:
+  trace:gen --wu WU-1112                    # Trace single WU
+  trace:gen --format markdown --output report.md  # Markdown report
+  trace:gen --since 2024-01-01 --format csv       # CSV report since date
+
+Output includes:
+  - WU ID and title
+  - Status
+  - Number of commits
+  - Number of files changed
+  - First and last commit dates
+  - List of changed files
+`);
+}
+/**
+ * Main entry point for trace-gen command
+ */
+/* istanbul ignore next -- CLI entry point */
+async function main() {
+    const args = parseTraceArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    const format = args.format || TraceFormat.JSON;
+    const entries = [];
+    if (args.wuId) {
+        // Trace single WU
+        console.error(`${LOG_PREFIX} Tracing ${args.wuId}...`);
+        const info = getWuInfo(args.wuId);
+        if (!info) {
+            console.error(`${LOG_PREFIX} Error: WU ${args.wuId} not found`);
+            process.exit(EXIT_CODES.ERROR);
+        }
+        const commits = getWuCommits(args.wuId);
+        const files = getWuFiles(args.wuId);
+        entries.push(buildTraceEntry({
+            wuId: args.wuId,
+            title: info.title,
+            status: info.status,
+            commits,
+            files,
+        }));
+    }
+    else {
+        // Trace all WUs
+        console.error(`${LOG_PREFIX} Scanning all WUs...`);
+        const wuDir = join(process.cwd(), DIRECTORIES.WU_DIR);
+        if (!existsSync(wuDir)) {
+            console.error(`${LOG_PREFIX} Error: WU directory not found`);
+            process.exit(EXIT_CODES.ERROR);
+        }
+        const files = readdirSync(wuDir);
+        for (const file of files) {
+            if (!file.endsWith('.yaml') && !file.endsWith('.yml'))
+                continue;
+            const wuId = file.replace(/\.ya?ml$/, '');
+            const info = getWuInfo(wuId);
+            if (!info)
+                continue;
+            // Filter by since date if specified
+            if (args.since) {
+                const commits = getWuCommits(wuId);
+                if (commits.length === 0)
+                    continue;
+                const lastCommitDate = new Date(commits[commits.length - 1]?.date || 0);
+                if (lastCommitDate < new Date(args.since))
+                    continue;
+            }
+            const commits = getWuCommits(wuId);
+            const wuFiles = getWuFiles(wuId);
+            entries.push(buildTraceEntry({
+                wuId,
+                title: info.title,
+                status: info.status,
+                commits,
+                files: wuFiles,
+            }));
+        }
+        console.error(`${LOG_PREFIX} Found ${entries.length} WU(s)`);
+    }
+    // Format output
+    let output;
+    switch (format) {
+        case TraceFormat.MARKDOWN:
+            output = formatMarkdown(entries);
+            break;
+        case TraceFormat.CSV:
+            output = formatCsv(entries);
+            break;
+        case TraceFormat.JSON:
+        default:
+            output = formatJson(entries);
+            break;
+    }
+    // Write output
+    if (args.output) {
+        writeFileSync(args.output, output, { encoding: FILE_SYSTEM.ENCODING });
+        console.error(`${LOG_PREFIX} ✅ Report written to ${args.output}`);
+    }
+    else {
+        console.log(output);
+    }
+}
+// Run main if executed directly
+if (import.meta.main) {
+    runCLI(main);
+}

package/dist/validate-agent-skills.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * @file validate-agent-skills.ts
+ * @description Validates agent skill definitions (WU-1111)
+ *
+ * Validates that skill files in .claude/skills/ follow the expected format
+ * and contain required sections.
+ *
+ * Usage:
+ *   validate-agent-skills                    # Validate all skills
+ *   validate-agent-skills --skill wu-lifecycle  # Validate specific skill
+ *
+ * Exit codes:
+ *   0 - All skills valid
+ *   1 - Validation errors found
+ *
+ * @see {@link .claude/skills/} - Skill definitions
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FILE_SYSTEM, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
+const LOG_PREFIX = '[validate-agent-skills]';
+/**
+ * Required sections in a skill file
+ */
+const REQUIRED_SECTIONS = ['When to Use'];
+/**
+ * Recommended sections (produce warnings if missing)
+ */
+const RECOMMENDED_SECTIONS = ['Examples', 'Key Concepts', 'Core Concepts'];
+/**
+ * Validate a single skill file
+ *
+ * @param skillPath - Path to SKILL.md file
+ * @returns Validation result
+ */
+export function validateSkillFile(skillPath) {
+    const errors = [];
+    const warnings = [];
+    if (!existsSync(skillPath)) {
+        errors.push(`Skill file not found: ${skillPath}`);
+        return { valid: false, errors, warnings };
+    }
+    const content = readFileSync(skillPath, { encoding: FILE_SYSTEM.UTF8 });
+    const lines = content.split('\n');
+    // Check for title heading
+    const hasTitle = lines.some((line) => line.startsWith('# '));
+    if (!hasTitle) {
+        errors.push('Missing title heading (# Skill Name)');
+    }
+    // Check for required sections
+    for (const section of REQUIRED_SECTIONS) {
+        const sectionPattern = new RegExp(`^##\\s+${section}`, 'im');
+        if (!sectionPattern.test(content)) {
+            errors.push(`Missing required section: "## ${section}"`);
+        }
+    }
+    // Check for recommended sections
+    for (const section of RECOMMENDED_SECTIONS) {
+        const sectionPattern = new RegExp(`^##\\s+${section}`, 'im');
+        if (!sectionPattern.test(content)) {
+            warnings.push(`Missing recommended section: "## ${section}"`);
+        }
+    }
+    // Check for minimum content
+    if (content.length < 100) {
+        warnings.push('Skill content is very short (< 100 characters)');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Validate all skills in a directory
+ *
+ * @param skillsDir - Path to skills directory
+ * @returns Validation summary
+ */
+export function validateAllSkills(skillsDir) {
+    const results = [];
+    let totalValid = 0;
+    let totalInvalid = 0;
+    if (!existsSync(skillsDir)) {
+        return {
+            totalValid: 0,
+            totalInvalid: 1,
+            results: [
+                {
+                    skillName: 'DIRECTORY',
+                    valid: false,
+                    errors: [`Skills directory not found: ${skillsDir}`],
+                    warnings: [],
+                },
+            ],
+        };
+    }
+    const entries = readdirSync(skillsDir);
+    for (const entry of entries) {
+        const entryPath = path.join(skillsDir, entry);
+        const stat = statSync(entryPath);
+        if (!stat.isDirectory()) {
+            continue;
+        }
+        // Check for SKILL.md in the skill directory
+        const skillFile = path.join(entryPath, 'SKILL.md');
+        if (!existsSync(skillFile)) {
+            results.push({
+                skillName: entry,
+                valid: false,
+                errors: [`Missing SKILL.md in ${entry}/`],
+                warnings: [],
+            });
+            totalInvalid++;
+            continue;
+        }
+        const result = validateSkillFile(skillFile);
+        results.push({ skillName: entry, ...result });
+        if (result.valid) {
+            totalValid++;
+        }
+        else {
+            totalInvalid++;
+        }
+    }
+    return { totalValid, totalInvalid, results };
+}
+/**
+ * Get default skills directory based on cwd
+ */
+function getDefaultSkillsDir() {
+    return path.join(process.cwd(), '.claude', 'skills');
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse arguments
+    let skillName;
+    let skillsDir = getDefaultSkillsDir();
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--skill' || arg === '-s') {
+            skillName = args[++i];
+        }
+        else if (arg === '--dir' || arg === '-d') {
+            skillsDir = args[++i];
+        }
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`Usage: validate-agent-skills [options]
+
+Validate agent skill definitions.
+
+Options:
+  --skill, -s NAME  Validate specific skill
+  --dir, -d DIR     Skills directory (default: .claude/skills)
+  -h, --help        Show this help message
+
+Examples:
+  validate-agent-skills                    # Validate all skills
+  validate-agent-skills --skill wu-lifecycle  # Validate specific skill
+`);
+            process.exit(0);
+        }
+    }
+    if (skillName) {
+        // Validate specific skill
+        const skillPath = path.join(skillsDir, skillName, 'SKILL.md');
+        console.log(`${LOG_PREFIX} Validating skill: ${skillName}...`);
+        const result = validateSkillFile(skillPath);
+        if (result.errors.length > 0) {
+            console.log(`${EMOJI.FAILURE} Validation failed:`);
+            result.errors.forEach((e) => console.log(`  ${e}`));
+        }
+        if (result.warnings.length > 0) {
+            console.log(`${EMOJI.WARNING} Warnings:`);
+            result.warnings.forEach((w) => console.log(`  ${w}`));
+        }
+        if (result.valid) {
+            console.log(`${EMOJI.SUCCESS} ${skillName} is valid`);
+        }
+        else {
+            process.exit(1);
+        }
+    }
+    else {
+        // Validate all skills
+        console.log(`${LOG_PREFIX} Validating all skills in ${skillsDir}...`);
+        const { totalValid, totalInvalid, results } = validateAllSkills(skillsDir);
+        // Print results
+        for (const result of results) {
+            if (result.errors.length > 0) {
+                console.log(`${EMOJI.FAILURE} ${result.skillName}:`);
+                result.errors.forEach((e) => console.log(`    ${e}`));
+            }
+            if (result.warnings.length > 0) {
+                console.log(`${EMOJI.WARNING} ${result.skillName}: ${result.warnings.length} warning(s)`);
+            }
+        }
+        console.log('');
+        console.log(`${LOG_PREFIX} Summary:`);
+        console.log(`  ${EMOJI.SUCCESS} Valid: ${totalValid}`);
+        console.log(`  ${EMOJI.FAILURE} Invalid: ${totalInvalid}`);
+        if (totalInvalid > 0) {
+            process.exit(1);
+        }
+    }
+}
+// Guard main() for testability
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(`${LOG_PREFIX} Unexpected error:`, error);
+        process.exit(1);
+    });
+}

package/dist/validate-agent-sync.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * @file validate-agent-sync.ts
+ * @description Validates agent sync state (WU-1111)
+ *
+ * Validates that agent configuration files exist and are properly structured.
+ * Checks .claude/agents/ for valid agent definitions.
+ *
+ * Usage:
+ *   validate-agent-sync                # Validate agent configuration
+ *
+ * Exit codes:
+ *   0 - Agent configuration valid
+ *   1 - Validation errors found
+ *
+ * @see {@link .claude/agents/} - Agent definitions
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FILE_SYSTEM, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
+const LOG_PREFIX = '[validate-agent-sync]';
+/**
+ * Validate agent sync state
+ *
+ * @param options - Validation options
+ * @param options.cwd - Working directory (default: process.cwd())
+ * @returns Validation result
+ */
+export async function validateAgentSync(options = {}) {
+    const { cwd = process.cwd() } = options;
+    const errors = [];
+    const warnings = [];
+    const agents = [];
+    const agentDir = path.join(cwd, '.claude', 'agents');
+    // Check if agents directory exists
+    if (!existsSync(agentDir)) {
+        errors.push(`Agents directory not found: ${agentDir}`);
+        return { valid: false, errors, warnings, agents };
+    }
+    // Read agent definitions
+    const files = readdirSync(agentDir).filter((f) => f.endsWith('.json') || f.endsWith('.md'));
+    if (files.length === 0) {
+        warnings.push('No agent definitions found in .claude/agents/');
+        return { valid: true, errors, warnings, agents };
+    }
+    for (const file of files) {
+        const filePath = path.join(agentDir, file);
+        const agentName = path.basename(file, path.extname(file));
+        agents.push(agentName);
+        if (file.endsWith('.json')) {
+            // Validate JSON agent definition
+            try {
+                const content = readFileSync(filePath, { encoding: FILE_SYSTEM.UTF8 });
+                const agentDef = JSON.parse(content);
+                // Check required fields
+                if (!agentDef.name) {
+                    warnings.push(`${agentName}: Missing "name" field`);
+                }
+                if (!agentDef.description) {
+                    warnings.push(`${agentName}: Missing "description" field`);
+                }
+            }
+            catch (e) {
+                errors.push(`${agentName}: Failed to parse JSON: ${e.message}`);
+            }
+        }
+        else if (file.endsWith('.md')) {
+            // Validate markdown agent definition
+            try {
+                const content = readFileSync(filePath, { encoding: FILE_SYSTEM.UTF8 });
+                // Check for title
+                if (!content.includes('# ')) {
+                    warnings.push(`${agentName}: Missing title heading`);
+                }
+                // Check for minimum content
+                if (content.length < 50) {
+                    warnings.push(`${agentName}: Agent definition is very short`);
+                }
+            }
+            catch (e) {
+                errors.push(`${agentName}: Failed to read file: ${e.message}`);
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        agents,
+    };
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse arguments
+    let cwd = process.cwd();
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--cwd' || arg === '-C') {
+            cwd = args[++i];
+        }
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`Usage: validate-agent-sync [options]
+
+Validate agent configuration and sync state.
+
+Options:
+  --cwd, -C DIR  Working directory (default: current directory)
+  -h, --help     Show this help message
+
+Examples:
+  validate-agent-sync
+  validate-agent-sync --cwd /path/to/project
+`);
+            process.exit(0);
+        }
+    }
+    console.log(`${LOG_PREFIX} Validating agent sync...`);
+    const result = await validateAgentSync({ cwd });
+    if (result.errors.length > 0) {
+        console.log(`${EMOJI.FAILURE} Validation errors:`);
+        result.errors.forEach((e) => console.log(`  ${e}`));
+    }
+    if (result.warnings.length > 0) {
+        console.log(`${EMOJI.WARNING} Warnings:`);
+        result.warnings.forEach((w) => console.log(`  ${w}`));
+    }
+    if (result.agents.length > 0) {
+        console.log(`${LOG_PREFIX} Found ${result.agents.length} agent(s):`);
+        result.agents.forEach((a) => console.log(`  - ${a}`));
+    }
+    if (result.valid) {
+        console.log(`${EMOJI.SUCCESS} Agent sync validation passed`);
+    }
+    else {
+        process.exit(1);
+    }
+}
+// Guard main() for testability
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(`${LOG_PREFIX} Unexpected error:`, error);
+        process.exit(1);
+    });
+}