@lumpcode/cli-utils 0.1.1 → 0.3.0

package/dist/index.cjs

@@ -101,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);
@@ -113,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' });
@@ -175,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 });
@@ -191,6 +222,8 @@ 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') {
@@ -226,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))));
     }
 }
 
@@ -292,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

@@ -61,10 +61,38 @@ type LumpJsConfigStep<V extends LumpVariables = LumpVariables, SV extends StepVa
     command?: CommandTag | FilePath | Step<V, SV>['commandFn'];
 }>;
 
+/**
+ * How Lumpcode prepares the per-lump git workspace inside the preflight repo root.
+ *
+ * - `checkout`: switch the main worktree to a fresh lump branch (default).
+ * - `worktree`: add a linked worktree under `.lumpcode/worktrees/<branch>/`.
+ */
+type WorkspaceStrategy = 'checkout' | 'worktree';
+
+type PostSetupWorkspaceFnInput<V extends LumpVariables = LumpVariables> = {
+    baseBranch: string;
+    branchName: string;
+    contextList: ContextList;
+    /** Branch workspace. Already prepared on a real run. Read-only. */
+    workspacePath: string;
+    executionWorkspacePath: string;
+    workspaceStrategy: WorkspaceStrategy;
+    projectRoot: string;
+    lumpVariables: V;
+};
+
+type PostSetupWorkspaceFn<V extends LumpVariables = LumpVariables> = (input: PostSetupWorkspaceFnInput<V>) => MaybePromise<{
+    command?: string;
+} | void>;
+
+type PostTeardownWorkspaceFn<V extends LumpVariables = LumpVariables> = (input: PostSetupWorkspaceFnInput<V>) => MaybePromise<{
+    command?: string;
+} | void>;
+
 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.
@@ -89,6 +117,20 @@ type LumpJsConfig<V extends LumpVariables = LumpVariables, SV extends StepVariab
     registerCommands?: string[];
     keepHistory?: boolean;
     verbose?: boolean;
+    /**
+     * After generated checkout/worktree setup. Mutually exclusive with
+     * `postSetupWorkspaceCommand`.
+     */
+    postSetupWorkspaceFn?: FilePath | PostSetupWorkspaceFn<V>;
+    /** Shell fragment in the branch workspace. Mutually exclusive with `postSetupWorkspaceFn`. */
+    postSetupWorkspaceCommand?: string;
+    /**
+     * Before generated workspace teardown. Mutually exclusive with
+     * `postTeardownWorkspaceCommand`.
+     */
+    postTeardownWorkspaceFn?: FilePath | PostTeardownWorkspaceFn<V>;
+    /** Shell fragment in the branch workspace. Mutually exclusive with `postTeardownWorkspaceFn`. */
+    postTeardownWorkspaceCommand?: string;
 }>;
 
 declare function getContextStatuses(input: {

package/dist/index.js

@@ -78,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);
@@ -90,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' });
@@ -152,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 });
@@ -168,6 +199,8 @@ 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') {
@@ -203,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))));
     }
 }
 
@@ -269,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.1",
+  "version": "0.3.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.1",
-    "@lumpcode/core": "^0.1.1",
+    "@lumpcode/cli-types": "^0.3.0",
+    "@lumpcode/core": "^0.3.0",
     "js-yaml": "^5.0.0"
   },
   "devDependencies": {