@lumenflow/cli 1.5.0 → 2.0.0

package/dist/validate-backlog-sync.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * @file validate-backlog-sync.ts
+ * @description Validates backlog.md is in sync with WU YAML files (WU-1111)
+ *
+ * Checks that all WU YAML files are referenced in backlog.md and vice versa.
+ * This is the TypeScript replacement for tools/validate-backlog-sync.js.
+ *
+ * Usage:
+ *   validate-backlog-sync              # Validate sync
+ *
+ * Exit codes:
+ *   0 - Backlog is in sync
+ *   1 - Sync issues found
+ *
+ * @see {@link docs/04-operations/tasks/backlog.md} - Backlog file
+ */
+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-backlog-sync]';
+/**
+ * Extract WU IDs from backlog.md content
+ *
+ * @param content - backlog.md content
+ * @returns Array of WU IDs found
+ */
+function extractWUIDsFromBacklog(content) {
+    const wuIds = [];
+    const pattern = /WU-\d+/gi;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const wuId = match[0].toUpperCase();
+        if (!wuIds.includes(wuId)) {
+            wuIds.push(wuId);
+        }
+    }
+    return wuIds;
+}
+/**
+ * Get all WU IDs from YAML files
+ *
+ * @param wuDir - Path to WU directory
+ * @returns Array of WU IDs
+ */
+function getWUIDsFromFiles(wuDir) {
+    if (!existsSync(wuDir)) {
+        return [];
+    }
+    return readdirSync(wuDir)
+        .filter((f) => f.endsWith('.yaml'))
+        .map((f) => f.replace('.yaml', '').toUpperCase());
+}
+/**
+ * Validate that backlog.md is in sync with WU YAML files
+ *
+ * @param options - Validation options
+ * @param options.cwd - Working directory (default: process.cwd())
+ * @returns Validation result
+ */
+export async function validateBacklogSync(options = {}) {
+    const { cwd = process.cwd() } = options;
+    const errors = [];
+    const warnings = [];
+    // Paths
+    const backlogPath = path.join(cwd, 'docs', '04-operations', 'tasks', 'backlog.md');
+    const wuDir = path.join(cwd, 'docs', '04-operations', 'tasks', 'wu');
+    // Check backlog.md exists
+    if (!existsSync(backlogPath)) {
+        errors.push(`Backlog file not found: ${backlogPath}`);
+        return { valid: false, errors, warnings, wuCount: 0, backlogCount: 0 };
+    }
+    // Get WU IDs from files
+    const wuIdsFromFiles = getWUIDsFromFiles(wuDir);
+    // Get WU IDs from backlog
+    const backlogContent = readFileSync(backlogPath, {
+        encoding: FILE_SYSTEM.UTF8,
+    });
+    const wuIdsFromBacklog = extractWUIDsFromBacklog(backlogContent);
+    // Check for WUs in files but not in backlog
+    for (const wuId of wuIdsFromFiles) {
+        if (!wuIdsFromBacklog.includes(wuId)) {
+            errors.push(`${wuId} not found in backlog.md (exists as ${wuId}.yaml)`);
+        }
+    }
+    // Check for WUs in backlog but not as files (warning only)
+    for (const wuId of wuIdsFromBacklog) {
+        if (!wuIdsFromFiles.includes(wuId)) {
+            warnings.push(`${wuId} referenced in backlog.md but ${wuId}.yaml not found`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        wuCount: wuIdsFromFiles.length,
+        backlogCount: wuIdsFromBacklog.length,
+    };
+}
+/**
+ * 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-backlog-sync [options]
+
+Validate that backlog.md is in sync with WU YAML files.
+
+Options:
+  --cwd, -C DIR  Working directory (default: current directory)
+  -h, --help     Show this help message
+
+Examples:
+  validate-backlog-sync
+`);
+            process.exit(0);
+        }
+    }
+    console.log(`${LOG_PREFIX} Validating backlog sync...`);
+    const result = await validateBacklogSync({ cwd });
+    if (result.errors.length > 0) {
+        console.log(`${EMOJI.FAILURE} Sync 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}`));
+    }
+    console.log(`${LOG_PREFIX} WU files: ${result.wuCount}, Backlog references: ${result.backlogCount}`);
+    if (result.valid) {
+        console.log(`${EMOJI.SUCCESS} Backlog is in sync`);
+    }
+    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);
+    });
+}

package/dist/validate-skills-spec.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * @file validate-skills-spec.ts
+ * @description Validates skills spec format (WU-1111)
+ *
+ * Validates that skill specification files follow the required format
+ * with proper sections and structure.
+ *
+ * Usage:
+ *   validate-skills-spec SKILL.md          # Validate specific file
+ *   validate-skills-spec --dir ./skills    # Validate all in directory
+ *
+ * Exit codes:
+ *   0 - Validation passed
+ *   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-skills-spec]';
+/**
+ * Required sections for a valid skill spec
+ */
+const REQUIRED_SECTIONS = ['When to Use'];
+/**
+ * Recommended sections (produce warnings if missing)
+ */
+const RECOMMENDED_SECTIONS = ['Examples'];
+/**
+ * Validate a skill specification file
+ *
+ * @param skillPath - Path to skill spec file
+ * @returns Validation result
+ */
+export function validateSkillsSpec(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 (# Title)
+    const hasTitle = lines.some((line) => /^#\s+\S/.test(line));
+    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 "When to Use" section has content
+    const whenToUseMatch = content.match(/##\s+When to Use\s*\n([\s\S]*?)(?=\n##|$)/i);
+    if (whenToUseMatch) {
+        const sectionContent = whenToUseMatch[1].trim();
+        if (sectionContent.length < 20) {
+            warnings.push('"When to Use" section has minimal content');
+        }
+    }
+    // Check for minimum overall content
+    if (content.length < 100) {
+        warnings.push('Skill spec is very short (< 100 characters)');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Validate all skill specs in a directory
+ *
+ * @param dir - Directory to scan
+ * @returns Map of file path to validation result
+ */
+export function validateSkillsSpecDir(dir) {
+    const results = new Map();
+    if (!existsSync(dir)) {
+        results.set(dir, {
+            valid: false,
+            errors: [`Directory not found: ${dir}`],
+            warnings: [],
+        });
+        return results;
+    }
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+        const entryPath = path.join(dir, entry);
+        const stat = statSync(entryPath);
+        if (stat.isDirectory()) {
+            // Check for SKILL.md in subdirectory
+            const skillFile = path.join(entryPath, 'SKILL.md');
+            if (existsSync(skillFile)) {
+                results.set(entry, validateSkillsSpec(skillFile));
+            }
+        }
+        else if (entry.endsWith('.md')) {
+            results.set(entry, validateSkillsSpec(entryPath));
+        }
+    }
+    return results;
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse arguments
+    let skillPath;
+    let dir;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--dir' || arg === '-d') {
+            dir = args[++i];
+        }
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`Usage: validate-skills-spec [file.md] [options]
+
+Validate skill specification format.
+
+Options:
+  --dir, -d DIR  Validate all specs in directory
+  -h, --help     Show this help message
+
+Examples:
+  validate-skills-spec SKILL.md
+  validate-skills-spec --dir .claude/skills
+`);
+            process.exit(0);
+        }
+        else if (!skillPath) {
+            skillPath = arg;
+        }
+    }
+    if (!skillPath && !dir) {
+        console.error(`${LOG_PREFIX} Error: Provide a skill file or --dir option`);
+        process.exit(1);
+    }
+    if (skillPath) {
+        // Validate single file
+        console.log(`${LOG_PREFIX} Validating ${skillPath}...`);
+        const result = validateSkillsSpec(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} Skill spec is valid`);
+        }
+        else {
+            process.exit(1);
+        }
+    }
+    else if (dir) {
+        // Validate directory
+        console.log(`${LOG_PREFIX} Validating skills in ${dir}...`);
+        const results = validateSkillsSpecDir(dir);
+        let totalValid = 0;
+        let totalInvalid = 0;
+        for (const [name, result] of results) {
+            if (result.errors.length > 0) {
+                console.log(`${EMOJI.FAILURE} ${name}:`);
+                result.errors.forEach((e) => console.log(`    ${e}`));
+                totalInvalid++;
+            }
+            else {
+                totalValid++;
+            }
+            if (result.warnings.length > 0) {
+                console.log(`${EMOJI.WARNING} ${name}: ${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.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * @file validate.ts
+ * @description Main WU YAML validator CLI (WU-1111)
+ *
+ * Validates WU tasks and status consistency. This is the replacement for
+ * tools/validate.js that was previously a stub.
+ *
+ * Usage:
+ *   validate                     # Validate all WUs
+ *   validate --id WU-123         # Validate specific WU
+ *   validate --strict            # Fail on warnings too
+ *   validate --done-only         # Only validate done WUs
+ *
+ * Exit codes:
+ *   0 - All validations passed
+ *   1 - Validation errors found
+ *
+ * @see {@link wu-validate.ts} - Detailed WU validation with schema
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - WU lifecycle
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { parseYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { validateWU, validateWUCompleteness } from '@lumenflow/core/dist/wu-schema.js';
+import { FILE_SYSTEM, EMOJI, PATTERNS } from '@lumenflow/core/dist/wu-constants.js';
+const LOG_PREFIX = '[validate]';
+/**
+ * Validate a single WU file
+ *
+ * @param wuPath - Path to WU YAML file
+ * @param options - Validation options
+ * @returns Validation result
+ */
+export function validateSingleWU(wuPath, options = {}) {
+    const { strict = false } = options;
+    const errors = [];
+    const warnings = [];
+    // Check file exists
+    if (!existsSync(wuPath)) {
+        errors.push(`WU file not found: ${wuPath}`);
+        return { valid: false, warnings, errors };
+    }
+    // Read and parse YAML
+    let doc;
+    try {
+        const text = readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 });
+        doc = parseYAML(text);
+    }
+    catch (e) {
+        errors.push(`Failed to parse YAML: ${e.message}`);
+        return { valid: false, warnings, errors };
+    }
+    // Schema validation
+    const schemaResult = validateWU(doc);
+    if (!schemaResult.success) {
+        const schemaErrors = schemaResult.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+        errors.push(...schemaErrors);
+        return { valid: false, warnings, errors };
+    }
+    // Completeness validation (soft warnings)
+    const completenessResult = validateWUCompleteness(schemaResult.data);
+    warnings.push(...completenessResult.warnings);
+    // In strict mode, warnings become errors
+    if (strict && warnings.length > 0) {
+        errors.push(...warnings.map((w) => `[STRICT] ${w}`));
+        return { valid: false, warnings: [], errors };
+    }
+    return { valid: true, warnings, errors };
+}
+/**
+ * Validate all WU files in the WU directory
+ *
+ * @param options - Validation options
+ * @returns Summary of all validations
+ */
+export function validateAllWUs(options = {}) {
+    const { strict = false, doneOnly = false } = options;
+    const wuDir = WU_PATHS.WU_DIR();
+    if (!existsSync(wuDir)) {
+        return {
+            totalValid: 0,
+            totalInvalid: 1,
+            totalWarnings: 0,
+            results: [
+                {
+                    wuId: 'DIRECTORY',
+                    valid: false,
+                    warnings: [],
+                    errors: [`WU directory not found: ${wuDir}`],
+                },
+            ],
+        };
+    }
+    const files = readdirSync(wuDir).filter((f) => f.endsWith('.yaml'));
+    const results = [];
+    let totalValid = 0;
+    let totalInvalid = 0;
+    let totalWarnings = 0;
+    for (const file of files) {
+        const wuPath = `${wuDir}/${file}`;
+        const wuId = file.replace('.yaml', '');
+        // Skip if only validating done WUs
+        if (doneOnly) {
+            try {
+                const text = readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 });
+                const doc = parseYAML(text);
+                if (doc.status !== 'done') {
+                    continue;
+                }
+            }
+            catch {
+                // If we can't read, still validate to catch the error
+            }
+        }
+        const result = validateSingleWU(wuPath, { strict });
+        results.push({ wuId, ...result });
+        if (result.valid) {
+            totalValid++;
+            totalWarnings += result.warnings.length;
+        }
+        else {
+            totalInvalid++;
+        }
+    }
+    return { totalValid, totalInvalid, totalWarnings, results };
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse arguments
+    let wuId;
+    let strict = false;
+    let doneOnly = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--id' || arg === '--wu') {
+            wuId = args[++i];
+        }
+        else if (arg === '--strict' || arg === '-s') {
+            strict = true;
+        }
+        else if (arg === '--done-only') {
+            doneOnly = true;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`Usage: validate [options]
+
+Validate WU YAML files for schema and quality.
+
+Options:
+  --id, --wu WU-XXX  Validate specific WU
+  --strict, -s       Fail on warnings too
+  --done-only        Only validate done WUs
+  -h, --help         Show this help message
+
+Examples:
+  validate                     # Validate all WUs
+  validate --id WU-123         # Validate specific WU
+  validate --strict            # Strict mode
+`);
+            process.exit(0);
+        }
+        else if (PATTERNS.WU_ID.test(arg.toUpperCase())) {
+            wuId = arg.toUpperCase();
+        }
+    }
+    if (wuId) {
+        // Validate single WU
+        wuId = wuId.toUpperCase();
+        if (!PATTERNS.WU_ID.test(wuId)) {
+            console.error(`${LOG_PREFIX} Invalid WU ID: ${wuId}`);
+            process.exit(1);
+        }
+        const wuPath = WU_PATHS.WU(wuId);
+        console.log(`${LOG_PREFIX} Validating ${wuId}...`);
+        const result = validateSingleWU(wuPath, { strict });
+        if (result.errors.length > 0) {
+            console.log(`${EMOJI.FAILURE} Validation failed:`);
+            result.errors.forEach((e) => console.log(`  ${e}`));
+            process.exit(1);
+        }
+        if (result.warnings.length > 0) {
+            console.log(`${EMOJI.WARNING} Validation passed with warnings:`);
+            result.warnings.forEach((w) => console.log(`  ${w}`));
+        }
+        else {
+            console.log(`${EMOJI.SUCCESS} ${wuId} is valid`);
+        }
+    }
+    else {
+        // Validate all WUs
+        console.log(`${LOG_PREFIX} Validating all WUs${doneOnly ? ' (done only)' : ''}...`);
+        const { totalValid, totalInvalid, totalWarnings, results } = validateAllWUs({
+            strict,
+            doneOnly,
+        });
+        // Print results
+        for (const result of results) {
+            if (result.errors.length > 0) {
+                console.log(`${EMOJI.FAILURE} ${result.wuId}:`);
+                result.errors.forEach((e) => console.log(`    ${e}`));
+            }
+            else if (result.warnings.length > 0) {
+                console.log(`${EMOJI.WARNING} ${result.wuId}: ${result.warnings.length} warning(s)`);
+                if (process.env.VERBOSE) {
+                    result.warnings.forEach((w) => console.log(`    ${w}`));
+                }
+            }
+        }
+        console.log('');
+        console.log(`${LOG_PREFIX} Summary:`);
+        console.log(`  ${EMOJI.SUCCESS} Valid: ${totalValid}`);
+        console.log(`  ${EMOJI.FAILURE} Invalid: ${totalInvalid}`);
+        console.log(`  ${EMOJI.WARNING} Warnings: ${totalWarnings}`);
+        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);
+    });
+}