@lumenflow/cli 1.3.5 → 1.4.0

package/dist/release.js

@@ -20,9 +20,10 @@
  * WU-1074: Add release command for npm publishing
  */
 import { Command } from 'commander';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, unlinkSync, } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
 import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
@@ -46,6 +47,16 @@ const NPM_REGISTRY = 'https://registry.npmjs.org';
 const NPM_TOKEN_ENV = 'NPM_TOKEN';
 /** Environment variable for alternative npm auth */
 const NODE_AUTH_TOKEN_ENV = 'NODE_AUTH_TOKEN';
+/** Pattern to detect npm auth token in .npmrc files */
+const NPMRC_AUTH_TOKEN_PATTERN = /_authToken=/;
+/** Changeset pre.json filename */
+const CHANGESET_PRE_JSON = 'pre.json';
+/** Changeset directory name */
+const CHANGESET_DIR = '.changeset';
+/** Environment variable to force bypass hooks */
+const LUMENFLOW_FORCE_ENV = 'LUMENFLOW_FORCE';
+/** Environment variable to provide reason for force bypass */
+const LUMENFLOW_FORCE_REASON_ENV = 'LUMENFLOW_FORCE_REASON';
 /**
  * Validate that a string is a valid semver version
  *
@@ -160,10 +171,94 @@ function runCommand(cmd, options = {}) {
 /**
  * Check if npm authentication is available
  *
- * @returns true if NPM_TOKEN or NODE_AUTH_TOKEN is set
+ * Checks for auth in this order:
+ * 1. NPM_TOKEN environment variable
+ * 2. NODE_AUTH_TOKEN environment variable
+ * 3. Auth token in specified .npmrc file (or ~/.npmrc by default)
+ *
+ * @param npmrcPath - Optional path to .npmrc file (defaults to ~/.npmrc)
+ * @returns true if any auth method is found
+ */
+export function hasNpmAuth(npmrcPath) {
+    // Check environment variables first
+    if (process.env[NPM_TOKEN_ENV] || process.env[NODE_AUTH_TOKEN_ENV]) {
+        return true;
+    }
+    // Check .npmrc file
+    const npmrcFile = npmrcPath ?? join(homedir(), '.npmrc');
+    if (existsSync(npmrcFile)) {
+        try {
+            const content = readFileSync(npmrcFile, { encoding: FILE_SYSTEM.UTF8 });
+            // Look for authToken lines (e.g., //registry.npmjs.org/:_authToken=...)
+            return NPMRC_AUTH_TOKEN_PATTERN.test(content);
+        }
+        catch {
+            // If we can't read the file, assume no auth
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Check if the project is in changeset pre-release mode
+ *
+ * Changeset pre mode is indicated by the presence of .changeset/pre.json
+ *
+ * @param baseDir - Base directory to check (defaults to cwd)
+ * @returns true if in pre-release mode
+ */
+export function isInChangesetPreMode(baseDir = process.cwd()) {
+    const preJsonPath = join(baseDir, CHANGESET_DIR, CHANGESET_PRE_JSON);
+    return existsSync(preJsonPath);
+}
+/**
+ * Exit changeset pre-release mode by removing .changeset/pre.json
+ *
+ * This is safe to call even if not in pre mode (no-op if file doesn't exist)
+ *
+ * @param baseDir - Base directory to operate in (defaults to cwd)
+ */
+export function exitChangesetPreMode(baseDir = process.cwd()) {
+    const preJsonPath = join(baseDir, CHANGESET_DIR, CHANGESET_PRE_JSON);
+    if (existsSync(preJsonPath)) {
+        unlinkSync(preJsonPath);
+    }
+}
+/**
+ * Push a git tag to origin, bypassing pre-push hooks via LUMENFLOW_FORCE
+ *
+ * This is necessary because the release script runs in a micro-worktree context
+ * and pre-push hooks may block tag pushes. The force is logged and requires
+ * a reason for audit purposes.
+ *
+ * @param git - SimpleGit instance
+ * @param tagName - Name of the tag to push
+ * @param reason - Reason for bypassing hooks (for audit log)
  */
-function hasNpmAuth() {
-    return Boolean(process.env[NPM_TOKEN_ENV] || process.env[NODE_AUTH_TOKEN_ENV]);
+export async function pushTagWithForce(git, tagName, reason = 'release: tag push from micro-worktree') {
+    // Set environment variables to bypass hooks
+    const originalForce = process.env[LUMENFLOW_FORCE_ENV];
+    const originalReason = process.env[LUMENFLOW_FORCE_REASON_ENV];
+    try {
+        process.env[LUMENFLOW_FORCE_ENV] = '1';
+        process.env[LUMENFLOW_FORCE_REASON_ENV] = reason;
+        await git.push(REMOTES.ORIGIN, tagName);
+    }
+    finally {
+        // Restore original environment
+        if (originalForce === undefined) {
+            delete process.env[LUMENFLOW_FORCE_ENV];
+        }
+        else {
+            process.env[LUMENFLOW_FORCE_ENV] = originalForce;
+        }
+        if (originalReason === undefined) {
+            delete process.env[LUMENFLOW_FORCE_REASON_ENV];
+        }
+        else {
+            process.env[LUMENFLOW_FORCE_REASON_ENV] = originalReason;
+        }
+    }
 }
 /**
  * Main release function
@@ -231,6 +326,12 @@ async function main() {
             id: `v${version}`,
             logPrefix: LOG_PREFIX,
             execute: async ({ worktreePath }) => {
+                // Check and exit changeset pre mode if active
+                if (isInChangesetPreMode(worktreePath)) {
+                    console.log(`${LOG_PREFIX} Detected changeset pre-release mode, exiting...`);
+                    exitChangesetPreMode(worktreePath);
+                    console.log(`${LOG_PREFIX} ✅ Exited changeset pre mode`);
+                }
                 // Find package paths within the worktree
                 const worktreePackagePaths = findPackageJsonPaths(worktreePath);
                 // Update versions
@@ -238,10 +339,15 @@ async function main() {
                 await updatePackageVersions(worktreePackagePaths, version);
                 // Get relative paths for commit
                 const relativePaths = worktreePackagePaths.map((p) => getRelativePath(p, worktreePath));
+                // If we exited pre mode, include the deleted pre.json in files to commit
+                // (the deletion will be staged automatically by git add -A behavior)
+                const changesetPrePath = join(CHANGESET_DIR, CHANGESET_PRE_JSON);
+                const filesToCommit = [...relativePaths];
+                // Note: Deletion of pre.json is handled by git detecting the missing file
                 console.log(`${LOG_PREFIX} ✅ Versions updated to ${version}`);
                 return {
                     commitMessage: buildCommitMessage(version),
-                    files: relativePaths,
+                    files: filesToCommit,
                 };
             },
         });
@@ -266,7 +372,7 @@ async function main() {
         await git.raw(['tag', '-a', tagName, '-m', `Release ${tagName}`]);
         console.log(`${LOG_PREFIX} ✅ Tag created: ${tagName}`);
         console.log(`${LOG_PREFIX} Pushing tag to ${REMOTES.ORIGIN}...`);
-        await git.push(REMOTES.ORIGIN, tagName);
+        await pushTagWithForce(git, tagName, 'release: pushing version tag');
         console.log(`${LOG_PREFIX} ✅ Tag pushed`);
     }
     // Publish to npm

package/dist/wu-done.js

@@ -534,6 +534,32 @@ async function ensureCleanWorkingTree() {
             `  - Leftover changes from previous session`);
     }
 }
+/**
+ * WU-1084: Check for uncommitted changes on main after merge completes.
+ *
+ * This catches cases where pnpm format (or other tooling) touched files
+ * outside the WU's code_paths during worktree work. These changes survive
+ * the merge and would be silently left behind when the worktree is removed.
+ *
+ * @param gitStatus - Output from git status (porcelain format)
+ * @param wuId - The WU ID for error messaging
+ * @returns Object with isDirty flag and optional error message
+ */
+export function checkPostMergeDirtyState(gitStatus, wuId) {
+    const trimmedStatus = gitStatus.trim();
+    if (!trimmedStatus) {
+        return { isDirty: false };
+    }
+    const error = `Main branch has uncommitted changes after merge:\n\n${trimmedStatus}\n\n` +
+        `This indicates files were modified outside the WU's code_paths.\n` +
+        `Common cause: pnpm format touched files outside the WU scope.\n\n` +
+        `The worktree has NOT been removed to allow investigation.\n\n` +
+        `Options:\n` +
+        `  1. Review and commit the changes: git add . && git commit -m "format: fix formatting"\n` +
+        `  2. Discard if unwanted: git checkout -- .\n` +
+        `  3. Then re-run: pnpm wu:done --id ${wuId} --skip-worktree-completion`;
+    return { isDirty: true, error };
+}
 /**
  * Extract completed WU IDs from git log output.
  * @param {string} logOutput - Git log output (one commit per line)
@@ -2033,6 +2059,13 @@ async function main() {
     else {
         await ensureNoAutoStagedOrNoop([WU_PATH, STATUS_PATH, BACKLOG_PATH, STAMPS_DIR]);
     }
+    // WU-1084: Check for uncommitted changes on main after merge
+    // This catches cases where pnpm format touched files outside code_paths
+    const postMergeStatus = await getGitForCwd().getStatus();
+    const dirtyCheck = checkPostMergeDirtyState(postMergeStatus, id);
+    if (dirtyCheck.isDirty) {
+        die(dirtyCheck.error);
+    }
     // Step 6 & 7: Cleanup (remove worktree, delete branch) - WU-1215
     // WU-1811: Only run cleanup if all completion steps succeeded
     if (completionResult.cleanupSafe !== false) {

package/dist/wu-release.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * WU Release Command (WU-1080)
+ *
+ * Releases an orphaned WU from in_progress back to ready state.
+ * Use when an agent is interrupted mid-WU and the WU needs to be reclaimed.
+ *
+ * Sequence (micro-worktree pattern):
+ * 1) Validate WU is in_progress
+ * 2) Create micro-worktree from main
+ * 3) Append release event to state store
+ * 4) Regenerate backlog.md and status.md
+ * 5) Commit in micro-worktree, push directly to origin/main
+ * 6) Optionally remove the work worktree
+ *
+ * Usage:
+ *   pnpm wu:release --id WU-1080 --reason "Agent interrupted"
+ */
+import { writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { generateBacklog, generateStatus } from '@lumenflow/core/dist/backlog-generator.js';
+import { todayISO } from '@lumenflow/core/dist/date-utils.js';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { readWU, writeWU, appendNote } from '@lumenflow/core/dist/wu-yaml.js';
+import { REMOTES, BRANCHES, WU_STATUS, PATTERNS, FILE_SYSTEM, EXIT_CODES, MICRO_WORKTREE_OPERATIONS, } from '@lumenflow/core/dist/wu-constants.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { WUStateStore } from '@lumenflow/core/dist/wu-state-store.js';
+import { releaseLaneLock } from '@lumenflow/core/dist/lane-lock.js';
+const PREFIX = '[wu-release]';
+async function main() {
+    const args = createWUParser({
+        name: 'wu-release',
+        description: 'Release an orphaned WU from in_progress back to ready state for reclaiming',
+        options: [WU_OPTIONS.id, WU_OPTIONS.reason],
+        required: ['id', 'reason'],
+        allowPositionalId: true,
+    });
+    const id = args.id.toUpperCase();
+    if (!PATTERNS.WU_ID.test(id))
+        die(`Invalid WU id '${args.id}'. Expected format WU-123`);
+    if (!args.reason) {
+        die('Reason is required for releasing a WU. Use --reason "..."');
+    }
+    await ensureOnMain(getGitForCwd());
+    // Read WU doc from main to validate state
+    const mainWUPath = WU_PATHS.WU(id);
+    let doc;
+    try {
+        doc = readWU(mainWUPath, id);
+    }
+    catch (error) {
+        die(`Failed to read WU ${id}: ${error.message}\n\n` +
+            `Options:\n` +
+            `  1. Check if WU file exists: ls -la ${mainWUPath}\n` +
+            `  2. Validate YAML syntax: pnpm wu:validate --id ${id}\n` +
+            `  3. Create WU if missing: pnpm wu:create --id ${id} --lane "<lane>" --title "..."`);
+    }
+    const title = doc.title || '';
+    const lane = doc.lane || 'Unknown';
+    // Validate current status is in_progress
+    const currentStatus = doc.status || WU_STATUS.READY;
+    if (currentStatus !== WU_STATUS.IN_PROGRESS) {
+        die(`Cannot release WU ${id}: current status is '${currentStatus}', expected 'in_progress'.\n\n` +
+            `The wu:release command is only for releasing orphaned WUs that are stuck in in_progress state.\n\n` +
+            `Current state transitions:\n` +
+            `  - If status is 'ready': WU has not been claimed yet\n` +
+            `  - If status is 'blocked': Use wu:unblock to resume work\n` +
+            `  - If status is 'done': WU is already complete`);
+    }
+    const baseMsg = `wu(${id.toLowerCase()}): release`;
+    const commitMsg = `${baseMsg} — ${args.reason}`;
+    // Use micro-worktree pattern to avoid pre-commit hook blocking commits to main
+    await withMicroWorktree({
+        operation: MICRO_WORKTREE_OPERATIONS.WU_BLOCK, // Reuse block operation type
+        id,
+        logPrefix: PREFIX,
+        pushOnly: true, // Push directly to origin/main without touching local main
+        execute: async ({ worktreePath }) => {
+            // Build paths relative to micro-worktree
+            const microWUPath = path.join(worktreePath, WU_PATHS.WU(id));
+            const microStatusPath = path.join(worktreePath, WU_PATHS.STATUS());
+            const microBacklogPath = path.join(worktreePath, WU_PATHS.BACKLOG());
+            // Update WU YAML in micro-worktree - set status back to ready
+            const microDoc = readWU(microWUPath, id);
+            microDoc.status = WU_STATUS.READY;
+            const noteLine = `Released (${todayISO()}): ${args.reason}`;
+            appendNote(microDoc, noteLine);
+            writeWU(microWUPath, microDoc);
+            // Append release event to WUStateStore
+            const stateDir = path.join(worktreePath, '.lumenflow', 'state');
+            const store = new WUStateStore(stateDir);
+            await store.load();
+            await store.release(id, args.reason);
+            // Generate backlog.md and status.md from state store
+            const backlogContent = await generateBacklog(store);
+            writeFileSync(microBacklogPath, backlogContent, {
+                encoding: FILE_SYSTEM.UTF8,
+            });
+            const statusContent = await generateStatus(store);
+            writeFileSync(microStatusPath, statusContent, {
+                encoding: FILE_SYSTEM.UTF8,
+            });
+            return {
+                commitMessage: commitMsg,
+                files: [
+                    WU_PATHS.WU(id),
+                    WU_PATHS.STATUS(),
+                    WU_PATHS.BACKLOG(),
+                    '.lumenflow/state/wu-events.jsonl',
+                ],
+            };
+        },
+    });
+    // Fetch to update local main tracking
+    await getGitForCwd().fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
+    // Release lane lock so another WU can be claimed
+    try {
+        if (lane) {
+            const releaseResult = releaseLaneLock(lane, { wuId: id });
+            if (releaseResult.released && !releaseResult.notFound) {
+                console.log(`${PREFIX} Lane lock released for "${lane}"`);
+            }
+        }
+    }
+    catch (err) {
+        // Non-blocking: lock release failure should not block the release operation
+        console.warn(`${PREFIX} Warning: Could not release lane lock: ${err.message}`);
+    }
+    console.log(`\n${PREFIX} WU released and pushed.`);
+    console.log(`- WU: ${id} — ${title}`);
+    console.log(`- Status: in_progress → ready`);
+    console.log(`- Reason: ${args.reason}`);
+    console.log(`\n${PREFIX} The WU can now be reclaimed with: pnpm wu:claim --id ${id} --lane "${lane}"`);
+}
+main().catch((e) => {
+    console.error(e.message);
+    process.exit(EXIT_CODES.ERROR);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -38,6 +38,7 @@
     "wu-infer-lane": "./dist/wu-infer-lane.js",
     "wu-delete": "./dist/wu-delete.js",
     "wu-unlock-lane": "./dist/wu-unlock-lane.js",
+    "wu-release": "./dist/wu-release.js",
     "mem-init": "./dist/mem-init.js",
     "mem-checkpoint": "./dist/mem-checkpoint.js",
     "mem-start": "./dist/mem-start.js",
@@ -69,7 +70,8 @@
     "lumenflow-gates": "./dist/gates.js",
     "lumenflow-init": "./dist/init.js",
     "lumenflow": "./dist/init.js",
-    "lumenflow-release": "./dist/release.js"
+    "lumenflow-release": "./dist/release.js",
+    "lumenflow-docs-sync": "./dist/docs-sync.js"
   },
   "files": [
     "dist",
@@ -86,11 +88,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "1.3.5",
-    "@lumenflow/metrics": "1.3.5",
-    "@lumenflow/initiatives": "1.3.5",
-    "@lumenflow/agent": "1.3.5",
-    "@lumenflow/memory": "1.3.5"
+    "@lumenflow/core": "1.4.0",
+    "@lumenflow/metrics": "1.4.0",
+    "@lumenflow/memory": "1.4.0",
+    "@lumenflow/initiatives": "1.4.0",
+    "@lumenflow/agent": "1.4.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",