@lumenflow/cli 1.5.0 → 2.0.0

package/dist/init-plan.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/* eslint-disable security/detect-non-literal-fs-filename */
+/**
+ * Init Plan Command (WU-1105)
+ *
+ * Links plan files to initiatives by setting the `related_plan` field
+ * in the initiative YAML.
+ *
+ * Usage:
+ *   pnpm init:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md
+ *   pnpm init:plan --initiative INIT-001 --create  # Create new plan template
+ *
+ * Features:
+ * - Validates initiative exists before modifying
+ * - Formats plan path as lumenflow:// URI
+ * - Idempotent: no error if same plan already linked
+ * - Warns if replacing existing plan link
+ * - Can create plan templates with --create
+ *
+ * Context: WU-1105 (INIT-003 Phase 3a: Migrate init:plan command)
+ */
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { existsSync, writeFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { INIT_PATHS } from '@lumenflow/initiatives/dist/initiative-paths.js';
+import { INIT_PATTERNS } from '@lumenflow/initiatives/dist/initiative-constants.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { readInitiative } from '@lumenflow/initiatives/dist/initiative-yaml.js';
+import { parseYAML, stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { LOG_PREFIX as CORE_LOG_PREFIX } from '@lumenflow/core/dist/wu-constants.js';
+/** Log prefix for console output */
+export const LOG_PREFIX = CORE_LOG_PREFIX.INIT_PLAN;
+/** Micro-worktree operation name */
+const OPERATION_NAME = 'init-plan';
+/** Standard plans directory relative to repo root */
+const PLANS_DIR = 'docs/04-operations/plans';
+/** LumenFlow URI scheme for plan references */
+const PLAN_URI_SCHEME = 'lumenflow://plans/';
+/**
+ * Custom option for plan file path
+ */
+const PLAN_OPTION = {
+    name: 'plan',
+    flags: '--plan <path>',
+    description: 'Path to plan file (markdown)',
+};
+/**
+ * Custom option for creating new plan template
+ */
+const CREATE_OPTION = {
+    name: 'create',
+    flags: '--create',
+    description: 'Create a new plan template instead of linking existing file',
+};
+/**
+ * Validate Initiative ID format
+ * @param id - Initiative ID to validate
+ * @throws Error if format is invalid
+ */
+export function validateInitIdFormat(id) {
+    if (!INIT_PATTERNS.INIT_ID.test(id)) {
+        die(`Invalid Initiative ID format: "${id}"\n\n` +
+            `Expected format: INIT-<number> or INIT-NAME (e.g., INIT-001, INIT-TOOLING)`);
+    }
+}
+/**
+ * Validate plan file path
+ * @param planPath - Path to plan file
+ * @throws Error if path is invalid or file doesn't exist
+ */
+export function validatePlanPath(planPath) {
+    if (!planPath.endsWith('.md')) {
+        die(`Invalid plan file format: "${planPath}"\n\nPlan files must be markdown (.md)`);
+    }
+    if (!existsSync(planPath)) {
+        die(`Plan file not found: "${planPath}"\n\nUse --create to create a new plan template`);
+    }
+}
+/**
+ * Format plan path as lumenflow:// URI
+ *
+ * Extracts the filename (and any subdirectory within plans/) and creates
+ * a standardized URI for the plan reference.
+ *
+ * @param planPath - Path to plan file (can be relative or absolute)
+ * @returns lumenflow://plans/<filename> URI
+ */
+export function formatPlanUri(planPath) {
+    // Try to extract path relative to plans directory
+    const plansMarker = '/plans/';
+    const plansIndex = planPath.indexOf(plansMarker);
+    if (plansIndex !== -1) {
+        // Extract everything after /plans/
+        const relativePath = planPath.substring(plansIndex + plansMarker.length);
+        return `${PLAN_URI_SCHEME}${relativePath}`;
+    }
+    // Fallback: just use the filename
+    const filename = basename(planPath);
+    return `${PLAN_URI_SCHEME}${filename}`;
+}
+/**
+ * Check if initiative exists and return the document
+ * @param initId - Initiative ID to check
+ * @returns Initiative document
+ * @throws Error if initiative not found
+ */
+export function checkInitiativeExists(initId) {
+    const initPath = INIT_PATHS.INITIATIVE(initId);
+    if (!existsSync(initPath)) {
+        die(`Initiative not found: ${initId}\n\nFile does not exist: ${initPath}`);
+    }
+    return readInitiative(initPath, initId);
+}
+/**
+ * Update initiative with plan reference in micro-worktree
+ *
+ * Uses raw YAML parsing to preserve unknown fields like related_plan
+ * that are not in the strict initiative schema.
+ *
+ * @param worktreePath - Path to micro-worktree
+ * @param initId - Initiative ID
+ * @param planUri - Plan URI to set
+ * @returns True if changes were made, false if already linked
+ */
+export function updateInitiativeWithPlan(worktreePath, initId, planUri) {
+    const initRelPath = INIT_PATHS.INITIATIVE(initId);
+    const initAbsPath = join(worktreePath, initRelPath);
+    // Read raw YAML to preserve unknown fields like related_plan
+    // (readInitiative strips them via zod schema validation)
+    const rawText = readFileSync(initAbsPath, { encoding: 'utf-8' });
+    const doc = parseYAML(rawText);
+    // Validate ID matches
+    if (doc.id !== initId) {
+        die(`Initiative YAML id mismatch. Expected ${initId}, found ${doc.id}`);
+    }
+    // Check for existing plan link
+    const existingPlan = doc.related_plan;
+    if (existingPlan === planUri) {
+        // Already linked to same plan - idempotent
+        return false;
+    }
+    if (existingPlan && existingPlan !== planUri) {
+        // Different plan already linked - warn but proceed
+        console.warn(`${LOG_PREFIX} Replacing existing related_plan: ${existingPlan} -> ${planUri}`);
+    }
+    // Update related_plan field
+    doc.related_plan = planUri;
+    const out = stringifyYAML(doc);
+    writeFileSync(initAbsPath, out, { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Updated ${initId} with related_plan: ${planUri}`);
+    return true;
+}
+/**
+ * Create a plan template file
+ *
+ * @param worktreePath - Path to repo root or worktree
+ * @param initId - Initiative ID
+ * @param title - Initiative title
+ * @returns Path to created file
+ * @throws Error if file already exists
+ */
+export function createPlanTemplate(worktreePath, initId, title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .substring(0, 30);
+    const filename = `${initId}-${slug}.md`;
+    const plansDir = join(worktreePath, PLANS_DIR);
+    const planPath = join(plansDir, filename);
+    if (existsSync(planPath)) {
+        die(`Plan file already exists: ${planPath}\n\nUse --plan to link an existing file`);
+    }
+    // Ensure plans directory exists
+    if (!existsSync(plansDir)) {
+        mkdirSync(plansDir, { recursive: true });
+    }
+    const template = `# ${initId} Plan - ${title}
+
+## Goal
+
+<!-- What is the primary objective of this initiative? -->
+
+## Scope
+
+<!-- What is in scope and out of scope? -->
+
+## Approach
+
+<!-- How will you achieve the goal? Key phases or milestones? -->
+
+## Success Criteria
+
+<!-- How will you know when this is complete? Measurable outcomes? -->
+
+## Risks
+
+<!-- What could go wrong? How will you mitigate? -->
+
+## References
+
+- Initiative: ${initId}
+- Created: ${new Date().toISOString().split('T')[0]}
+`;
+    writeFileSync(planPath, template, { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Created plan template: ${planPath}`);
+    return planPath;
+}
+/**
+ * Generate commit message for plan link operation
+ */
+export function getCommitMessage(initId, planUri) {
+    const filename = planUri.replace(PLAN_URI_SCHEME, '');
+    return `docs: link plan ${filename} to ${initId.toLowerCase()}`;
+}
+async function main() {
+    const args = createWUParser({
+        name: 'init-plan',
+        description: 'Link a plan file to an initiative',
+        options: [WU_OPTIONS.initiative, PLAN_OPTION, CREATE_OPTION],
+        required: ['initiative'],
+        allowPositionalId: false,
+    });
+    const initId = args.initiative;
+    const planPath = args.plan;
+    const shouldCreate = args.create;
+    // Validate inputs
+    validateInitIdFormat(initId);
+    // Check initiative exists first (before any mutations)
+    const initDoc = checkInitiativeExists(initId);
+    const initTitle = initDoc.title;
+    // Determine plan path and URI
+    let targetPlanPath;
+    let planUri;
+    if (shouldCreate) {
+        // Create mode - will create template and link it
+        console.log(`${LOG_PREFIX} Creating plan template for ${initId}...`);
+        // Ensure on main for micro-worktree operations
+        await ensureOnMain(getGitForCwd());
+        try {
+            await withMicroWorktree({
+                operation: OPERATION_NAME,
+                id: initId,
+                logPrefix: LOG_PREFIX,
+                pushOnly: true,
+                execute: async ({ worktreePath }) => {
+                    // Create plan template
+                    targetPlanPath = createPlanTemplate(worktreePath, initId, initTitle);
+                    planUri = formatPlanUri(targetPlanPath);
+                    // Update initiative with plan link
+                    updateInitiativeWithPlan(worktreePath, initId, planUri);
+                    // Return files to commit
+                    const planRelPath = targetPlanPath.replace(worktreePath + '/', '');
+                    return {
+                        commitMessage: getCommitMessage(initId, planUri),
+                        files: [planRelPath, INIT_PATHS.INITIATIVE(initId)],
+                    };
+                },
+            });
+            console.log(`\n${LOG_PREFIX} Transaction complete!`);
+            console.log(`\nPlan Linked:`);
+            console.log(`  Initiative: ${initId}`);
+            console.log(`  Plan URI:   ${planUri}`);
+            console.log(`  File:       ${targetPlanPath}`);
+            console.log(`\nNext steps:`);
+            console.log(`  1. Edit the plan file with your goals and approach`);
+            console.log(`  2. View initiative: pnpm initiative:status ${initId}`);
+        }
+        catch (error) {
+            die(`Transaction failed: ${error.message}\n\n` +
+                `Micro-worktree cleanup was attempted automatically.\n` +
+                `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
+        }
+    }
+    else if (planPath) {
+        // Link existing file mode
+        validatePlanPath(planPath);
+        planUri = formatPlanUri(planPath);
+        console.log(`${LOG_PREFIX} Linking plan to ${initId}...`);
+        // Check for idempotent case before micro-worktree
+        const existingPlan = initDoc.related_plan;
+        if (existingPlan === planUri) {
+            console.log(`${LOG_PREFIX} Plan already linked (idempotent - no changes needed)`);
+            console.log(`\n${LOG_PREFIX} ${initId} already has related_plan: ${planUri}`);
+            return;
+        }
+        // Ensure on main for micro-worktree operations
+        await ensureOnMain(getGitForCwd());
+        try {
+            await withMicroWorktree({
+                operation: OPERATION_NAME,
+                id: initId,
+                logPrefix: LOG_PREFIX,
+                pushOnly: true,
+                execute: async ({ worktreePath }) => {
+                    // Update initiative with plan link
+                    const changed = updateInitiativeWithPlan(worktreePath, initId, planUri);
+                    if (!changed) {
+                        console.log(`${LOG_PREFIX} No changes detected (concurrent link operation)`);
+                    }
+                    return {
+                        commitMessage: getCommitMessage(initId, planUri),
+                        files: [INIT_PATHS.INITIATIVE(initId)],
+                    };
+                },
+            });
+            console.log(`\n${LOG_PREFIX} Transaction complete!`);
+            console.log(`\nPlan Linked:`);
+            console.log(`  Initiative: ${initId}`);
+            console.log(`  Plan URI:   ${planUri}`);
+            console.log(`  File:       ${planPath}`);
+            console.log(`\nNext steps:`);
+            console.log(`  - View initiative: pnpm initiative:status ${initId}`);
+        }
+        catch (error) {
+            die(`Transaction failed: ${error.message}\n\n` +
+                `Micro-worktree cleanup was attempted automatically.\n` +
+                `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
+        }
+    }
+    else {
+        die('Either --plan or --create is required\n\n' +
+            'Usage:\n' +
+            '  pnpm init:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md\n' +
+            '  pnpm init:plan --initiative INIT-001 --create');
+    }
+}
+// Guard main() for testability - use import.meta.main (WU-1071)
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
+}
+// Export for testing
+export { main };

package/dist/lumenflow-upgrade.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * LumenFlow Upgrade CLI Command
+ *
+ * Updates all @lumenflow/* packages to a specified version or latest.
+ * Uses worktree pattern to ensure pnpm install runs in worktree, not main.
+ *
+ * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ *
+ * Key requirements (from WU acceptance criteria):
+ * - Uses worktree pattern (install runs in worktree, not main)
+ * - Checks all 7 @lumenflow/* packages (not just 4)
+ *
+ * Usage:
+ *   pnpm lumenflow:upgrade --version 1.5.0
+ *   pnpm lumenflow:upgrade --latest
+ *   pnpm lumenflow:upgrade --latest --dry-run
+ */
+import { execSync } from 'node:child_process';
+import { STDIO_MODES, EXIT_CODES, PKG_MANAGER, } from '@lumenflow/core/dist/wu-constants.js';
+import { runCLI } from './cli-entry-point.js';
+import { validateWorktreeContext } from './deps-add.js';
+/** Log prefix for console output */
+const LOG_PREFIX = '[lumenflow:upgrade]';
+/**
+ * All @lumenflow/* packages that should be upgraded together
+ *
+ * WU-1112: Must include all 7 packages (not just 4 as before)
+ * Kept in alphabetical order for consistency
+ */
+export const LUMENFLOW_PACKAGES = [
+    '@lumenflow/agent',
+    '@lumenflow/cli',
+    '@lumenflow/core',
+    '@lumenflow/initiatives',
+    '@lumenflow/memory',
+    '@lumenflow/metrics',
+    '@lumenflow/shims',
+];
+/**
+ * Parse command line arguments for lumenflow-upgrade
+ *
+ * @param argv - Process argv array
+ * @returns Parsed arguments
+ */
+export function parseUpgradeArgs(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 === '--version' || arg === '-v') {
+            args.version = cliArgs[++i];
+        }
+        else if (arg === '--latest' || arg === '-l') {
+            args.latest = true;
+        }
+        else if (arg === '--dry-run' || arg === '-n') {
+            args.dryRun = true;
+        }
+    }
+    return args;
+}
+/**
+ * Build the upgrade commands based on arguments
+ *
+ * Creates pnpm add command for all @lumenflow/* packages.
+ * Uses --save-dev since these are development dependencies.
+ *
+ * @param args - Parsed upgrade arguments
+ * @returns Object containing the commands to run
+ */
+export function buildUpgradeCommands(args) {
+    // Determine version specifier
+    const versionSpec = args.latest ? 'latest' : args.version || 'latest';
+    // Build package list with version
+    const packages = LUMENFLOW_PACKAGES.map((pkg) => `${pkg}@${versionSpec}`);
+    // Build pnpm add command
+    const addCommand = `${PKG_MANAGER} add --save-dev ${packages.join(' ')}`;
+    return {
+        addCommand,
+        versionSpec,
+    };
+}
+/**
+ * Print help message for lumenflow-upgrade
+ */
+/* istanbul ignore next -- CLI entry point */
+function printHelp() {
+    console.log(`
+Usage: lumenflow-upgrade [options]
+
+Upgrade all @lumenflow/* packages to a specified version.
+Must be run from inside a worktree to enforce worktree discipline.
+
+Options:
+  -v, --version <ver>   Upgrade to specific version (e.g., 1.5.0)
+  -l, --latest          Upgrade to latest version
+  -n, --dry-run         Show commands without executing
+  -h, --help            Show this help message
+
+Packages upgraded (all 7):
+${LUMENFLOW_PACKAGES.map((p) => `  - ${p}`).join('\n')}
+
+Examples:
+  lumenflow:upgrade --version 1.5.0    # Upgrade to specific version
+  lumenflow:upgrade --latest           # Upgrade to latest
+  lumenflow:upgrade --latest --dry-run # Preview upgrade commands
+
+Worktree Discipline:
+  This command only works inside a worktree to prevent lockfile
+  conflicts on main checkout. Claim a WU first:
+
+    pnpm wu:claim --id WU-XXXX --lane "Your Lane"
+    cd worktrees/<lane>-wu-<id>/
+    lumenflow:upgrade --latest
+`);
+}
+/**
+ * Main entry point for lumenflow-upgrade command
+ */
+/* istanbul ignore next -- CLI entry point */
+async function main() {
+    const args = parseUpgradeArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // Require either --version or --latest
+    if (!args.version && !args.latest) {
+        console.error(`${LOG_PREFIX} Error: Must specify --version <ver> or --latest`);
+        printHelp();
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // Validate worktree context (WU-1112 requirement: must run in worktree)
+    const validation = validateWorktreeContext(process.cwd());
+    if (!validation.valid) {
+        console.error(`${LOG_PREFIX} ${validation.error}`);
+        console.error(`\nTo fix:\n${validation.fixCommand}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // Build upgrade commands
+    const { addCommand, versionSpec } = buildUpgradeCommands(args);
+    console.log(`${LOG_PREFIX} Upgrading @lumenflow/* packages to ${versionSpec}`);
+    console.log(`${LOG_PREFIX} Packages: ${LUMENFLOW_PACKAGES.length} packages`);
+    if (args.dryRun) {
+        console.log(`\n${LOG_PREFIX} DRY RUN - Commands that would be executed:`);
+        console.log(`  ${addCommand}`);
+        console.log(`\n${LOG_PREFIX} No changes made.`);
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // Execute upgrade
+    console.log(`${LOG_PREFIX} Running: ${addCommand}`);
+    try {
+        execSync(addCommand, {
+            stdio: STDIO_MODES.INHERIT,
+            cwd: process.cwd(),
+        });
+        console.log(`\n${LOG_PREFIX} ✅ Upgrade complete!`);
+        console.log(`${LOG_PREFIX} Upgraded to ${versionSpec}`);
+        console.log(`\n${LOG_PREFIX} Next steps:`);
+        console.log(`  1. Run 'pnpm build' to rebuild with new versions`);
+        console.log(`  2. Run 'pnpm gates' to verify everything works`);
+        console.log(`  3. Commit the changes`);
+    }
+    catch (error) {
+        console.error(`\n${LOG_PREFIX} ❌ Upgrade failed`);
+        console.error(`${LOG_PREFIX} Check the error above and try again.`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+}
+// Run main if executed directly
+if (import.meta.main) {
+    runCLI(main);
+}