@lumpcode/cli-utils 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -5,6 +5,7 @@ var core = require('@lumpcode/core');
 var path = require('node:path');
 var os = require('node:os');
 var crypto = require('node:crypto');
+var fsSync = require('node:fs');
 var fs = require('node:fs/promises');
 var jsYaml = require('js-yaml');
 
@@ -28,6 +29,7 @@ function _interopNamespaceDefault(e) {
 var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 var os__namespace = /*#__PURE__*/_interopNamespaceDefault(os);
 var crypto__namespace = /*#__PURE__*/_interopNamespaceDefault(crypto);
+var fsSync__namespace = /*#__PURE__*/_interopNamespaceDefault(fsSync);
 var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
 
 const globalConfigFolderPath = path.join(os.homedir(), '.lumpcode');
@@ -99,6 +101,8 @@ function formatJsonFileContent(input) {
     return trailingNewline ? `${json}\n` : json;
 }
 
+const WORKSPACE_LOCK_WAIT_TIMEOUT_MS = 15 * 60 * 1000;
+const WORKSPACE_LOCK_WAIT_LOG_INTERVAL_MS = 30000;
 const WAIT_POLL_MS = 500;
 function workspaceLocksDirPath(input) {
     return path__namespace.join(input.globalConfigFolderPath, input.spec.locksSubdirName);
@@ -111,26 +115,53 @@ function workspaceLockFilePath(input) {
         spec: input.spec,
     }), `${hash}.lock.json`);
 }
-function formatBusyMessage(input) {
-    const { spec, workspacePath, holder } = input;
+function formatHolderClause(holder, style) {
     if (holder?.lumpName && holder.pid) {
-        return (`${spec.workspaceLabel} "${workspacePath}" is in use by another lumpcode run ` +
-            `(pid ${holder.pid}, lump "${holder.lumpName}"). Wait for it to finish or stop the daemon before running again.`);
+        return style === 'busy'
+            ? ` (pid ${holder.pid}, lump "${holder.lumpName}")`
+            : ` (held by lump "${holder.lumpName}" pid ${holder.pid})`;
     }
     if (holder?.pid) {
-        return (`${spec.workspaceLabel} "${workspacePath}" is in use by another lumpcode run ` +
-            `(pid ${holder.pid}). Wait for it to finish or stop the daemon before running again.`);
+        return style === 'busy' ? ` (pid ${holder.pid})` : ` (held by pid ${holder.pid})`;
+    }
+    return '';
+}
+function formatBusyMessage(input) {
+    const { spec, workspacePath, holder } = input;
+    const clause = formatHolderClause(holder, 'busy');
+    if (clause) {
+        return (`${spec.workspaceLabel} "${workspacePath}" is in use by another lumpcode run` +
+            `${clause}. Wait for it to finish or stop the daemon before running again.`);
     }
     return (`${spec.workspaceLabel} "${workspacePath}" is in use by another lumpcode run. ` +
         `Wait for it to finish or stop the daemon before running again.`);
 }
 function formatWorkspaceFileWaitMessage(input) {
     const { spec, workspacePath, holder } = input;
-    if (holder?.lumpName && holder.pid) {
-        return (`${spec.waitLogNoun} busy at "${workspacePath}" ` +
-            `(held by lump "${holder.lumpName}" pid ${holder.pid}); waiting…`);
-    }
-    return `${spec.waitLogNoun} busy at "${workspacePath}"; waiting…`;
+    return (`${spec.waitLogNoun} busy at "${workspacePath}"` +
+        `${formatHolderClause(holder, 'held')}; waiting…`);
+}
+function formatWorkspaceFileStillWaitingMessage(input) {
+    const { spec, workspacePath, holder, elapsedMs } = input;
+    const elapsedSec = Math.max(1, Math.round(elapsedMs / 1000));
+    return (`${spec.waitLogNoun} busy at "${workspacePath}"` +
+        `${formatHolderClause(holder, 'held')}; still waiting (${elapsedSec}s)…`);
+}
+function formatWaitTimeoutMessage(input) {
+    const { spec, workspacePath, holder, waitTimeoutMs } = input;
+    return (`Waited ${waitTimeoutMs}ms for ${spec.waitLogNoun} "${workspacePath}"` +
+        `${formatHolderClause(holder, 'held')}; giving up.`);
+}
+function toBusyError(input) {
+    const { spec, workspacePath, holder, message, reason } = input;
+    return {
+        code: spec.busyCode,
+        message,
+        [spec.workspacePathField]: workspacePath,
+        ...(holder?.pid !== undefined ? { holderPid: holder.pid } : {}),
+        ...(holder?.lumpName !== undefined ? { holderLumpName: holder.lumpName } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+    };
 }
 async function readLockHolder(lockFilePath) {
     const result = await readJsonFile({ filePath: lockFilePath, ifMissing: 'undefined' });
@@ -173,6 +204,8 @@ async function tryAcquireWorkspaceFileLockOnce(input) {
 }
 async function acquireWorkspaceFileLock(input) {
     const { spec, globalConfigFolderPath, workspacePath, lumpName, mode, projectName, logger } = input;
+    const waitTimeoutMs = input.waitTimeoutMs ?? WORKSPACE_LOCK_WAIT_TIMEOUT_MS;
+    const waitLogIntervalMs = input.waitLogIntervalMs ?? WORKSPACE_LOCK_WAIT_LOG_INTERVAL_MS;
     const normalizedWorkspacePath = path__namespace.resolve(workspacePath);
     const locksDir = workspaceLocksDirPath({ globalConfigFolderPath, spec });
     await fs__namespace.mkdir(locksDir, { recursive: true });
@@ -189,10 +222,12 @@ async function acquireWorkspaceFileLock(input) {
         ...(projectName !== undefined ? { projectName } : {}),
     };
     let loggedWait = false;
+    let lastWaitLogAt = 0;
+    const waitStartedAt = Date.now();
     for (;;) {
         const attempt = await tryAcquireWorkspaceFileLockOnce({ lockFilePath, payload, spec, logger });
         if (attempt.status === 'acquired') {
-            const release = async () => {
+            const releaseAsync = async () => {
                 try {
                     const holder = await readLockHolder(lockFilePath);
                     if (holder?.pid === process.pid) {
@@ -203,6 +238,20 @@ async function acquireWorkspaceFileLock(input) {
                     // lock already gone
                 }
             };
+            const release = Object.assign(releaseAsync, {
+                sync: () => {
+                    try {
+                        const raw = fsSync__namespace.readFileSync(lockFilePath, 'utf8');
+                        const holder = JSON.parse(raw);
+                        if (holder?.pid === process.pid) {
+                            fsSync__namespace.unlinkSync(lockFilePath);
+                        }
+                    }
+                    catch {
+                        // lock already gone or unreadable
+                    }
+                },
+            });
             return core.success(release);
         }
         if (attempt.status === 'stale_removed') {
@@ -210,29 +259,51 @@ async function acquireWorkspaceFileLock(input) {
             continue;
         }
         if (mode === 'fail') {
-            return core.failure({
-                code: spec.busyCode,
+            return core.failure(toBusyError({
+                spec,
+                workspacePath: normalizedWorkspacePath,
+                holder: attempt.holder,
                 message: formatBusyMessage({
                     spec,
                     workspacePath: normalizedWorkspacePath,
                     holder: attempt.holder,
                 }),
-                [spec.workspacePathField]: normalizedWorkspacePath,
-                ...(attempt.holder?.pid !== undefined ? { holderPid: attempt.holder.pid } : {}),
-                ...(attempt.holder?.lumpName !== undefined
-                    ? { holderLumpName: attempt.holder.lumpName }
-                    : {}),
-            });
+            }));
         }
-        if (!loggedWait) {
-            logger?.info(formatWorkspaceFileWaitMessage({
+        const now = Date.now();
+        const elapsedMs = now - waitStartedAt;
+        if (elapsedMs >= waitTimeoutMs) {
+            return core.failure(toBusyError({
                 spec,
                 workspacePath: normalizedWorkspacePath,
                 holder: attempt.holder,
+                reason: 'waitTimedOut',
+                message: formatWaitTimeoutMessage({
+                    spec,
+                    workspacePath: normalizedWorkspacePath,
+                    holder: attempt.holder,
+                    waitTimeoutMs,
+                }),
             }));
+        }
+        if (!loggedWait || now - lastWaitLogAt >= waitLogIntervalMs) {
+            logger?.info(loggedWait
+                ? formatWorkspaceFileStillWaitingMessage({
+                    spec,
+                    workspacePath: normalizedWorkspacePath,
+                    holder: attempt.holder,
+                    elapsedMs,
+                })
+                : formatWorkspaceFileWaitMessage({
+                    spec,
+                    workspacePath: normalizedWorkspacePath,
+                    holder: attempt.holder,
+                }));
             loggedWait = true;
+            lastWaitLogAt = now;
         }
-        await new Promise((resolve) => setTimeout(resolve, WAIT_POLL_MS));
+        const remainingMs = waitTimeoutMs - elapsedMs;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(WAIT_POLL_MS, Math.max(0, remainingMs))));
     }
 }
 
@@ -276,6 +347,8 @@ async function acquireGitCommonDirLock(input) {
         mode: input.lockMode,
         projectName: input.projectName,
         logger: input.logger,
+        waitTimeoutMs: input.waitTimeoutMs,
+        waitLogIntervalMs: input.waitLogIntervalMs,
     });
 }
 /** Acquire, run `fn`, always release. */

package/dist/index.d.ts

@@ -64,7 +64,7 @@ type LumpJsConfigStep<V extends LumpVariables = LumpVariables, SV extends StepVa
 type LumpJsConfigSoloStep<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = LumpJsConfigStep<V, SV> | LumpJsConfigStep<V, SV>['promptTemplate'] | LumpJsConfigStep<V, SV>['promptFn'];
 type LumpJsConfig<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = MergeObjs<Omit<{
     [K in keyof RunLumpInput<V, SV>]?: NonNullable<RunLumpInput<V, SV>[K]> extends Function ? (RunLumpInput<V, SV>[K] | FilePath) : RunLumpInput<V, SV>[K];
-}, 'gitCommitMessageFn' | 'projectRoot' | 'branchFn' | 'baseBranch' | 'setupWorkspaceFn' | 'teardownWorkspaceFn' | 'gitAddCommandFn' | 'gitCommitCommandFn' | 'gitPushCommandFn' | 'getContextListFn' | 'refreshRemoteTrackingRefsFn'>, {
+}, 'gitCommitMessageFn' | 'projectRoot' | 'branchFn' | 'baseBranch' | 'setupWorkspaceFn' | 'teardownWorkspaceFn' | 'gitAddCommitFn' | 'gitPushFn' | 'getContextListFn' | 'refreshRemoteTrackingRefsFn'>, {
     /**
      * Execution integration branch. Exact string, `BaseBranchFn`, or FilePath to a module.
      * Omit → concrete effective discovery branch. Pattern strings are rejected at resolve.

package/dist/index.js

@@ -5,6 +5,7 @@ import path__default from 'node:path';
 import * as os from 'node:os';
 import os__default from 'node:os';
 import * as crypto from 'node:crypto';
+import * as fsSync from 'node:fs';
 import * as fs from 'node:fs/promises';
 import { load } from 'js-yaml';
 
@@ -77,6 +78,8 @@ function formatJsonFileContent(input) {
     return trailingNewline ? `${json}\n` : json;
 }
 
+const WORKSPACE_LOCK_WAIT_TIMEOUT_MS = 15 * 60 * 1000;
+const WORKSPACE_LOCK_WAIT_LOG_INTERVAL_MS = 30000;
 const WAIT_POLL_MS = 500;
 function workspaceLocksDirPath(input) {
     return path.join(input.globalConfigFolderPath, input.spec.locksSubdirName);
@@ -89,26 +92,53 @@ function workspaceLockFilePath(input) {
         spec: input.spec,
     }), `${hash}.lock.json`);
 }
-function formatBusyMessage(input) {
-    const { spec, workspacePath, holder } = input;
+function formatHolderClause(holder, style) {
     if (holder?.lumpName && holder.pid) {
-        return (`${spec.workspaceLabel} "${workspacePath}" is in use by another lumpcode run ` +
-            `(pid ${holder.pid}, lump "${holder.lumpName}"). Wait for it to finish or stop the daemon before running again.`);
+        return style === 'busy'
+            ? ` (pid ${holder.pid}, lump "${holder.lumpName}")`
+            : ` (held by lump "${holder.lumpName}" pid ${holder.pid})`;
     }
     if (holder?.pid) {
-        return (`${spec.workspaceLabel} "${workspacePath}" is in use by another lumpcode run ` +
-            `(pid ${holder.pid}). Wait for it to finish or stop the daemon before running again.`);
+        return style === 'busy' ? ` (pid ${holder.pid})` : ` (held by pid ${holder.pid})`;
+    }
+    return '';
+}
+function formatBusyMessage(input) {
+    const { spec, workspacePath, holder } = input;
+    const clause = formatHolderClause(holder, 'busy');
+    if (clause) {
+        return (`${spec.workspaceLabel} "${workspacePath}" is in use by another lumpcode run` +
+            `${clause}. Wait for it to finish or stop the daemon before running again.`);
     }
     return (`${spec.workspaceLabel} "${workspacePath}" is in use by another lumpcode run. ` +
         `Wait for it to finish or stop the daemon before running again.`);
 }
 function formatWorkspaceFileWaitMessage(input) {
     const { spec, workspacePath, holder } = input;
-    if (holder?.lumpName && holder.pid) {
-        return (`${spec.waitLogNoun} busy at "${workspacePath}" ` +
-            `(held by lump "${holder.lumpName}" pid ${holder.pid}); waiting…`);
-    }
-    return `${spec.waitLogNoun} busy at "${workspacePath}"; waiting…`;
+    return (`${spec.waitLogNoun} busy at "${workspacePath}"` +
+        `${formatHolderClause(holder, 'held')}; waiting…`);
+}
+function formatWorkspaceFileStillWaitingMessage(input) {
+    const { spec, workspacePath, holder, elapsedMs } = input;
+    const elapsedSec = Math.max(1, Math.round(elapsedMs / 1000));
+    return (`${spec.waitLogNoun} busy at "${workspacePath}"` +
+        `${formatHolderClause(holder, 'held')}; still waiting (${elapsedSec}s)…`);
+}
+function formatWaitTimeoutMessage(input) {
+    const { spec, workspacePath, holder, waitTimeoutMs } = input;
+    return (`Waited ${waitTimeoutMs}ms for ${spec.waitLogNoun} "${workspacePath}"` +
+        `${formatHolderClause(holder, 'held')}; giving up.`);
+}
+function toBusyError(input) {
+    const { spec, workspacePath, holder, message, reason } = input;
+    return {
+        code: spec.busyCode,
+        message,
+        [spec.workspacePathField]: workspacePath,
+        ...(holder?.pid !== undefined ? { holderPid: holder.pid } : {}),
+        ...(holder?.lumpName !== undefined ? { holderLumpName: holder.lumpName } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+    };
 }
 async function readLockHolder(lockFilePath) {
     const result = await readJsonFile({ filePath: lockFilePath, ifMissing: 'undefined' });
@@ -151,6 +181,8 @@ async function tryAcquireWorkspaceFileLockOnce(input) {
 }
 async function acquireWorkspaceFileLock(input) {
     const { spec, globalConfigFolderPath, workspacePath, lumpName, mode, projectName, logger } = input;
+    const waitTimeoutMs = input.waitTimeoutMs ?? WORKSPACE_LOCK_WAIT_TIMEOUT_MS;
+    const waitLogIntervalMs = input.waitLogIntervalMs ?? WORKSPACE_LOCK_WAIT_LOG_INTERVAL_MS;
     const normalizedWorkspacePath = path.resolve(workspacePath);
     const locksDir = workspaceLocksDirPath({ globalConfigFolderPath, spec });
     await fs.mkdir(locksDir, { recursive: true });
@@ -167,10 +199,12 @@ async function acquireWorkspaceFileLock(input) {
         ...(projectName !== undefined ? { projectName } : {}),
     };
     let loggedWait = false;
+    let lastWaitLogAt = 0;
+    const waitStartedAt = Date.now();
     for (;;) {
         const attempt = await tryAcquireWorkspaceFileLockOnce({ lockFilePath, payload, spec, logger });
         if (attempt.status === 'acquired') {
-            const release = async () => {
+            const releaseAsync = async () => {
                 try {
                     const holder = await readLockHolder(lockFilePath);
                     if (holder?.pid === process.pid) {
@@ -181,6 +215,20 @@ async function acquireWorkspaceFileLock(input) {
                     // lock already gone
                 }
             };
+            const release = Object.assign(releaseAsync, {
+                sync: () => {
+                    try {
+                        const raw = fsSync.readFileSync(lockFilePath, 'utf8');
+                        const holder = JSON.parse(raw);
+                        if (holder?.pid === process.pid) {
+                            fsSync.unlinkSync(lockFilePath);
+                        }
+                    }
+                    catch {
+                        // lock already gone or unreadable
+                    }
+                },
+            });
             return success(release);
         }
         if (attempt.status === 'stale_removed') {
@@ -188,29 +236,51 @@ async function acquireWorkspaceFileLock(input) {
             continue;
         }
         if (mode === 'fail') {
-            return failure({
-                code: spec.busyCode,
+            return failure(toBusyError({
+                spec,
+                workspacePath: normalizedWorkspacePath,
+                holder: attempt.holder,
                 message: formatBusyMessage({
                     spec,
                     workspacePath: normalizedWorkspacePath,
                     holder: attempt.holder,
                 }),
-                [spec.workspacePathField]: normalizedWorkspacePath,
-                ...(attempt.holder?.pid !== undefined ? { holderPid: attempt.holder.pid } : {}),
-                ...(attempt.holder?.lumpName !== undefined
-                    ? { holderLumpName: attempt.holder.lumpName }
-                    : {}),
-            });
+            }));
         }
-        if (!loggedWait) {
-            logger?.info(formatWorkspaceFileWaitMessage({
+        const now = Date.now();
+        const elapsedMs = now - waitStartedAt;
+        if (elapsedMs >= waitTimeoutMs) {
+            return failure(toBusyError({
                 spec,
                 workspacePath: normalizedWorkspacePath,
                 holder: attempt.holder,
+                reason: 'waitTimedOut',
+                message: formatWaitTimeoutMessage({
+                    spec,
+                    workspacePath: normalizedWorkspacePath,
+                    holder: attempt.holder,
+                    waitTimeoutMs,
+                }),
             }));
+        }
+        if (!loggedWait || now - lastWaitLogAt >= waitLogIntervalMs) {
+            logger?.info(loggedWait
+                ? formatWorkspaceFileStillWaitingMessage({
+                    spec,
+                    workspacePath: normalizedWorkspacePath,
+                    holder: attempt.holder,
+                    elapsedMs,
+                })
+                : formatWorkspaceFileWaitMessage({
+                    spec,
+                    workspacePath: normalizedWorkspacePath,
+                    holder: attempt.holder,
+                }));
             loggedWait = true;
+            lastWaitLogAt = now;
         }
-        await new Promise((resolve) => setTimeout(resolve, WAIT_POLL_MS));
+        const remainingMs = waitTimeoutMs - elapsedMs;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(WAIT_POLL_MS, Math.max(0, remainingMs))));
     }
 }
 
@@ -254,6 +324,8 @@ async function acquireGitCommonDirLock(input) {
         mode: input.lockMode,
         projectName: input.projectName,
         logger: input.logger,
+        waitTimeoutMs: input.waitTimeoutMs,
+        waitLogIntervalMs: input.waitLogIntervalMs,
     });
 }
 /** Acquire, run `fn`, always release. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumpcode/cli-utils",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Types, defineX helpers, and runtime utilities for Lumpcode lump configs and recipes",
   "keywords": [
     "lumpcode",
@@ -43,8 +43,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@lumpcode/cli-types": "^0.1.0",
-    "@lumpcode/core": "^0.1.0",
+    "@lumpcode/cli-types": "^0.2.0",
+    "@lumpcode/core": "^0.2.0",
     "js-yaml": "^5.0.0"
   },
   "devDependencies": {