@lumenflow/cli 1.6.0 → 2.1.0

package/dist/git-log.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * Git Log CLI Tool
+ *
+ * Provides WU-aware git log with:
+ * - Oneline and custom format output
+ * - Max count limiting
+ * - Date and author filtering
+ *
+ * Usage:
+ *   node git-log.js [ref] [--oneline] [-n <count>] [--format <format>]
+ *
+ * WU-1109: INIT-003 Phase 4b - Migrate git operations
+ */
+import { createGitForPath, getGitForCwd } from '@lumenflow/core';
+/**
+ * Parse command line arguments for git-log
+ */
+export function parseGitLogArgs(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 === '--oneline') {
+            args.oneline = true;
+        }
+        else if (arg === '-n') {
+            const val = cliArgs[++i];
+            if (val)
+                args.maxCount = parseInt(val, 10);
+        }
+        else if (arg === '--max-count') {
+            const val = cliArgs[++i];
+            if (val)
+                args.maxCount = parseInt(val, 10);
+        }
+        else if (arg.startsWith('-n') && arg.length > 2) {
+            // Handle -n5 format
+            args.maxCount = parseInt(arg.slice(2), 10);
+        }
+        else if (arg === '--format') {
+            args.format = cliArgs[++i];
+        }
+        else if (arg === '--since') {
+            args.since = cliArgs[++i];
+        }
+        else if (arg === '--author') {
+            args.author = cliArgs[++i];
+        }
+        else if (arg === '--base-dir') {
+            args.baseDir = cliArgs[++i];
+        }
+        else if (!arg.startsWith('-') && !args.ref) {
+            // Positional argument for ref
+            args.ref = arg;
+        }
+    }
+    return args;
+}
+/**
+ * Parse structured log output
+ */
+function parseLogOutput(output) {
+    if (!output.trim()) {
+        return [];
+    }
+    const commits = [];
+    // Parse format: hash|message|author|date (separated by |||)
+    const lines = output.trim().split('\n');
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const parts = line.split('|||');
+        if (parts.length >= 2) {
+            commits.push({
+                hash: parts[0].trim(),
+                message: parts[1].trim(),
+                author: parts[2]?.trim(),
+                date: parts[3]?.trim(),
+            });
+        }
+        else {
+            // Fallback for oneline format (hash + message)
+            const match = line.match(/^([a-f0-9]+)\s+(.*)$/);
+            if (match) {
+                commits.push({
+                    hash: match[1],
+                    message: match[2],
+                });
+            }
+        }
+    }
+    return commits;
+}
+/**
+ * Get git log with audit logging
+ */
+export async function getGitLog(args) {
+    try {
+        const git = args.baseDir ? createGitForPath(args.baseDir) : getGitForCwd();
+        // Build log arguments
+        const rawArgs = ['log'];
+        if (args.maxCount) {
+            rawArgs.push(`-n`, String(args.maxCount));
+        }
+        if (args.oneline) {
+            rawArgs.push('--oneline');
+        }
+        else if (args.format) {
+            rawArgs.push(`--format=${args.format}`);
+        }
+        else {
+            // Use structured format for parsing
+            rawArgs.push('--format=%H|||%s|||%an|||%ai');
+        }
+        if (args.since) {
+            rawArgs.push(`--since=${args.since}`);
+        }
+        if (args.author) {
+            rawArgs.push(`--author=${args.author}`);
+        }
+        if (args.ref) {
+            rawArgs.push(args.ref);
+        }
+        const output = await git.raw(rawArgs);
+        const trimmedOutput = output.trim();
+        // Parse commits
+        const commits = args.oneline || args.format ? [] : parseLogOutput(trimmedOutput);
+        return {
+            success: true,
+            commits,
+            output: args.oneline || args.format ? trimmedOutput : undefined,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Handle case of repo with no commits
+        if (errorMessage.includes('does not have any commits') ||
+            errorMessage.includes('fatal: bad revision') ||
+            errorMessage.includes("fatal: your current branch 'main' does not have any commits")) {
+            return {
+                success: true,
+                commits: [],
+            };
+        }
+        return {
+            success: false,
+            error: errorMessage,
+            commits: [],
+        };
+    }
+}
+/**
+ * Print help message
+ */
+/* istanbul ignore next -- CLI entry point tested via subprocess */
+function printHelp() {
+    console.log(`
+Usage: git-log [ref] [options]
+
+Show commit logs.
+
+Arguments:
+  ref                   Revision range (e.g., main..feature)
+
+Options:
+  --base-dir <dir>      Base directory for git operations
+  --oneline             Show each commit on a single line
+  -n <number>           Limit the number of commits
+  --max-count <number>  Limit the number of commits
+  --format <format>     Pretty-print format string
+  --since <date>        Show commits more recent than a date
+  --author <pattern>    Limit to commits by author
+  -h, --help            Show this help message
+
+Examples:
+  git-log
+  git-log --oneline
+  git-log -n 10
+  git-log main..feature
+  git-log --since="2024-01-01"
+  git-log --author="test@example.com"
+`);
+}
+/**
+ * Main entry point
+ */
+/* istanbul ignore next -- CLI entry point tested via subprocess */
+async function main() {
+    const args = parseGitLogArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(0);
+    }
+    const result = await getGitLog(args);
+    if (result.success) {
+        if (result.output !== undefined) {
+            // Custom format or oneline mode
+            if (result.output) {
+                console.log(result.output);
+            }
+        }
+        else {
+            // Structured output
+            for (const commit of result.commits) {
+                console.log(`commit ${commit.hash}`);
+                if (commit.author)
+                    console.log(`Author: ${commit.author}`);
+                if (commit.date)
+                    console.log(`Date:   ${commit.date}`);
+                console.log('');
+                console.log(`    ${commit.message}`);
+                console.log('');
+            }
+        }
+    }
+    else {
+        console.error(`Error: ${result.error}`);
+        process.exit(1);
+    }
+}
+// Run main if executed directly
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
+}

package/dist/git-status.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * Git Status CLI Tool
+ *
+ * Provides WU-aware git status with:
+ * - Porcelain and short output formats
+ * - Parsed file status (staged, modified, untracked)
+ * - Clean/dirty state detection
+ *
+ * Usage:
+ *   node git-status.js [path] [--porcelain] [--short]
+ *
+ * WU-1109: INIT-003 Phase 4b - Migrate git operations
+ */
+import { createGitForPath, getGitForCwd } from '@lumenflow/core';
+/**
+ * Parse command line arguments for git-status
+ */
+export function parseGitStatusArgs(argv) {
+    const args = {
+        porcelain: false,
+        short: false,
+    };
+    // 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 === '--porcelain') {
+            args.porcelain = true;
+        }
+        else if (arg === '--short' || arg === '-s') {
+            args.short = true;
+        }
+        else if (arg === '--base-dir') {
+            args.baseDir = cliArgs[++i];
+        }
+        else if (!arg.startsWith('-')) {
+            // Positional argument for path
+            args.path = arg;
+        }
+    }
+    return args;
+}
+/**
+ * Parse porcelain status output into categorized files
+ */
+function parseStatusOutput(output) {
+    const staged = [];
+    const modified = [];
+    const untracked = [];
+    const deleted = [];
+    // Don't filter based on trim - leading spaces are significant in git status
+    const lines = output.split('\n').filter((line) => line.length > 0);
+    for (const line of lines) {
+        if (line.length < 3)
+            continue;
+        const indexStatus = line[0];
+        const workTreeStatus = line[1];
+        const filePath = line.slice(3).trim();
+        // Handle renames (e.g., "R  old -> new")
+        const fileName = filePath.includes(' -> ') ? filePath.split(' -> ')[1] : filePath;
+        // Untracked files
+        if (indexStatus === '?' && workTreeStatus === '?') {
+            untracked.push(fileName);
+            continue;
+        }
+        // Staged changes (index has status)
+        if (indexStatus !== ' ' && indexStatus !== '?') {
+            staged.push(fileName);
+            if (indexStatus === 'D') {
+                deleted.push(fileName);
+            }
+        }
+        // Working tree changes (unstaged modifications)
+        if (workTreeStatus === 'M') {
+            modified.push(fileName);
+        }
+        else if (workTreeStatus === 'D' && indexStatus === ' ') {
+            // Only count as deleted in working tree if not already staged for deletion
+            deleted.push(fileName);
+        }
+    }
+    return { staged, modified, untracked, deleted };
+}
+/**
+ * Get git status with audit logging
+ */
+export async function getGitStatus(args) {
+    try {
+        const git = args.baseDir ? createGitForPath(args.baseDir) : getGitForCwd();
+        // Get porcelain status
+        const rawArgs = ['status', '--porcelain'];
+        if (args.path) {
+            rawArgs.push('--', args.path);
+        }
+        const output = await git.raw(rawArgs);
+        // Don't trim the entire output - leading spaces in lines are significant for git status
+        // Only trim trailing newlines
+        const trimmedOutput = output.replace(/\n+$/, '');
+        const isClean = trimmedOutput === '';
+        // If porcelain mode requested, return raw output
+        if (args.porcelain) {
+            return {
+                success: true,
+                isClean,
+                output: trimmedOutput,
+            };
+        }
+        // Parse the status output
+        const { staged, modified, untracked, deleted } = parseStatusOutput(trimmedOutput);
+        return {
+            success: true,
+            isClean,
+            staged,
+            modified,
+            untracked,
+            deleted,
+            output: args.short ? trimmedOutput : undefined,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: errorMessage,
+        };
+    }
+}
+/**
+ * Print help message
+ */
+/* istanbul ignore next -- CLI entry point tested via subprocess */
+function printHelp() {
+    console.log(`
+Usage: git-status [path] [options]
+
+Show the working tree status.
+
+Arguments:
+  path                  Path to filter status
+
+Options:
+  --base-dir <dir>      Base directory for git operations
+  --porcelain           Give the output in an easy-to-parse format
+  --short, -s           Give the output in short format
+  -h, --help            Show this help message
+
+Examples:
+  git-status
+  git-status src/
+  git-status --porcelain
+  git-status --short
+`);
+}
+/**
+ * Main entry point
+ */
+/* istanbul ignore next -- CLI entry point tested via subprocess */
+async function main() {
+    const args = parseGitStatusArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(0);
+    }
+    const result = await getGitStatus(args);
+    if (result.success) {
+        if (result.output !== undefined) {
+            // Porcelain or short mode
+            if (result.output) {
+                console.log(result.output);
+            }
+        }
+        else {
+            // Human-readable output
+            if (result.isClean) {
+                console.log('nothing to commit, working tree clean');
+            }
+            else {
+                if (result.staged && result.staged.length > 0) {
+                    console.log('Changes to be committed:');
+                    result.staged.forEach((f) => console.log(`  ${f}`));
+                    console.log('');
+                }
+                if (result.modified && result.modified.length > 0) {
+                    console.log('Changes not staged for commit:');
+                    result.modified.forEach((f) => console.log(`  modified:   ${f}`));
+                    console.log('');
+                }
+                if (result.untracked && result.untracked.length > 0) {
+                    console.log('Untracked files:');
+                    result.untracked.forEach((f) => console.log(`  ${f}`));
+                }
+            }
+        }
+    }
+    else {
+        console.error(`Error: ${result.error}`);
+        process.exit(1);
+    }
+}
+// Run main if executed directly
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
+}

package/dist/guard-locked.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * @file guard-locked.ts
+ * @description Guard that prevents changes to locked WUs (WU-1111)
+ *
+ * Validates that a WU is not locked before allowing modifications.
+ * Used by git hooks and wu: commands to enforce workflow discipline.
+ *
+ * Usage:
+ *   guard-locked WU-123        # Check if WU-123 is locked
+ *   guard-locked --wu WU-123   # Same with explicit flag
+ *
+ * Exit codes:
+ *   0 - WU is not locked (safe to proceed)
+ *   1 - WU is locked (block operation)
+ *
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - WU lifecycle
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { PATTERNS, FILE_SYSTEM } from '@lumenflow/core/dist/wu-constants.js';
+const LOG_PREFIX = '[guard-locked]';
+/**
+ * Check if a WU is locked
+ *
+ * @param wuPath - Path to WU YAML file
+ * @returns true if WU has locked: true, false otherwise
+ * @throws Error if WU file does not exist or cannot be parsed
+ *
+ * @example
+ * if (isWULocked('/path/to/WU-123.yaml')) {
+ *   console.log('WU is locked, cannot modify');
+ * }
+ */
+export function isWULocked(wuPath) {
+    if (!existsSync(wuPath)) {
+        throw new Error(`WU file not found: ${wuPath}`);
+    }
+    const content = readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 });
+    const doc = parseYAML(content);
+    return doc.locked === true;
+}
+/**
+ * Assert that a WU is not locked
+ *
+ * @param wuPath - Path to WU YAML file
+ * @throws Error if WU is locked, with actionable fix instructions
+ *
+ * @example
+ * try {
+ *   assertWUNotLocked('/path/to/WU-123.yaml');
+ *   // Safe to modify
+ * } catch (error) {
+ *   console.error(error.message);
+ *   process.exit(1);
+ * }
+ */
+export function assertWUNotLocked(wuPath) {
+    if (!existsSync(wuPath)) {
+        throw new Error(`WU file not found: ${wuPath}`);
+    }
+    const content = readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 });
+    const doc = parseYAML(content);
+    if (doc.locked === true) {
+        const wuId = doc.id || path.basename(wuPath, '.yaml');
+        throw new Error(`${LOG_PREFIX} WU ${wuId} is locked.
+
+Locked WUs cannot be modified. This prevents accidental changes to completed work.
+
+If you need to modify this WU:
+  1. Check if modification is really necessary (locked WUs are done)
+  2. Use wu:unlock to unlock the WU first:
+     pnpm wu:unlock --id ${wuId} --reason "reason for unlocking"
+
+For more information:
+  See docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+`);
+    }
+}
+/**
+ * Check if a WU ID is locked by looking up the YAML file
+ *
+ * @param wuId - WU ID (e.g., "WU-123")
+ * @returns true if WU has locked: true, false otherwise
+ * @throws Error if WU file does not exist
+ */
+export function isWUIdLocked(wuId) {
+    const wuPath = WU_PATHS.WU(wuId);
+    return isWULocked(wuPath);
+}
+/**
+ * Assert that a WU ID is not locked
+ *
+ * @param wuId - WU ID (e.g., "WU-123")
+ * @throws Error if WU is locked
+ */
+export function assertWUIdNotLocked(wuId) {
+    const wuPath = WU_PATHS.WU(wuId);
+    assertWUNotLocked(wuPath);
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse arguments
+    let wuId;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--wu' || arg === '--id') {
+            wuId = args[++i];
+        }
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`Usage: guard-locked [--wu] WU-XXX
+
+Check if a WU is locked. Exits with code 1 if locked.
+
+Options:
+  --wu, --id WU-XXX  WU ID to check
+  -h, --help         Show this help message
+
+Examples:
+  guard-locked WU-123
+  guard-locked --wu WU-123
+`);
+            process.exit(0);
+        }
+        else if (PATTERNS.WU_ID.test(arg.toUpperCase())) {
+            wuId = arg.toUpperCase();
+        }
+    }
+    if (!wuId) {
+        console.error(`${LOG_PREFIX} Error: WU ID required`);
+        console.error('Usage: guard-locked [--wu] WU-XXX');
+        process.exit(1);
+    }
+    // Normalize WU ID
+    wuId = wuId.toUpperCase();
+    if (!PATTERNS.WU_ID.test(wuId)) {
+        console.error(`${LOG_PREFIX} Invalid WU ID: ${wuId}`);
+        console.error('Expected format: WU-123');
+        process.exit(1);
+    }
+    try {
+        if (isWUIdLocked(wuId)) {
+            console.error(`${LOG_PREFIX} ${wuId} is locked`);
+            console.error('');
+            console.error('Locked WUs cannot be modified.');
+            console.error(`To unlock: pnpm wu:unlock --id ${wuId} --reason "your reason"`);
+            process.exit(1);
+        }
+        console.log(`${LOG_PREFIX} ${wuId} is not locked (OK)`);
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`${LOG_PREFIX} Error: ${error.message}`);
+        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);
+    });
+}