@lumpcode/cli-utils 0.0.16 → 0.1.0

package/README.md

@@ -49,7 +49,8 @@ npm run build -w=@lumpcode/cli-utils
 
 ## Runtime exports
 
-- `getContextStatus` — remote marker-commit status for a context
+- `getContextStatus` — remote marker-commit status for a context (locked one-shot fetch)
+- `getContextStatuses` — batch status map (one locked fetch, then local reads)
 - `makeGitCommitMessageFnFromLumpName` — default `LUMP:<lump> - <context>` messages
 - `getGitCommitMessage`, `getLumpCommitPrefixForLump` — commit message helpers
 - `readYamlList` — read a YAML file as a flat list (`[]` when missing or not an array)

package/dist/index.cjs

@@ -4,6 +4,7 @@ var cliTypes = require('@lumpcode/cli-types');
 var core = require('@lumpcode/core');
 var path = require('node:path');
 var os = require('node:os');
+var crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var jsYaml = require('js-yaml');
 
@@ -26,8 +27,12 @@ function _interopNamespaceDefault(e) {
 
 var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 var os__namespace = /*#__PURE__*/_interopNamespaceDefault(os);
+var crypto__namespace = /*#__PURE__*/_interopNamespaceDefault(crypto);
 var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
 
+const globalConfigFolderPath = path.join(os.homedir(), '.lumpcode');
+path.join(process.cwd(), '.lumpcode');
+
 path__namespace.join(os__namespace.homedir(), '.lumpcode', 'auth.json');
 const LUMP_COMMIT_PREFIX = "LUMP: ";
 
@@ -52,14 +57,294 @@ function makeGitCommitMessageFnFromLumpName(lumpName) {
     };
 }
 
-async function getContextStatus(input) {
-    const { projectRoot, contextName, lumpName, baseBranch } = input;
-    return core.getContextStatus({
+async function readJsonFile(input) {
+    const { filePath, ifMissing = 'fail', missingFileFailure } = input;
+    let raw;
+    try {
+        raw = await fs__namespace.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        const code = core.nodeErrnoCode(error);
+        if (code === 'ENOENT') {
+            if (ifMissing === 'undefined') {
+                return core.success(undefined);
+            }
+            if (typeof ifMissing === 'object') {
+                return core.success(ifMissing.defaultValue);
+            }
+            return core.failure(missingFileFailure ?? `File not found: ${filePath}`);
+        }
+        return core.failure(`Cannot read ${filePath}: ${String(error)}`);
+    }
+    try {
+        return core.success(JSON.parse(raw));
+    }
+    catch (error) {
+        return core.failure(`Invalid JSON in ${filePath}: ${String(error)}`);
+    }
+}
+
+function resolvePrettySpace(pretty) {
+    if (pretty === true)
+        return 2;
+    if (typeof pretty === 'number')
+        return pretty;
+    return undefined;
+}
+/** Pure formatter shared with callers that write via an open handle (e.g. workspace locks). */
+function formatJsonFileContent(input) {
+    const { data, pretty, trailingNewline = false } = input;
+    const space = resolvePrettySpace(pretty);
+    const json = space === undefined ? JSON.stringify(data) : JSON.stringify(data, null, space);
+    return trailingNewline ? `${json}\n` : json;
+}
+
+const WAIT_POLL_MS = 500;
+function workspaceLocksDirPath(input) {
+    return path__namespace.join(input.globalConfigFolderPath, input.spec.locksSubdirName);
+}
+function workspaceLockFilePath(input) {
+    const normalizedPath = path__namespace.resolve(input.workspacePath);
+    const hash = crypto__namespace.createHash('sha256').update(normalizedPath).digest('hex');
+    return path__namespace.join(workspaceLocksDirPath({
+        globalConfigFolderPath: input.globalConfigFolderPath,
+        spec: input.spec,
+    }), `${hash}.lock.json`);
+}
+function formatBusyMessage(input) {
+    const { spec, workspacePath, holder } = input;
+    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.`);
+    }
+    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 (`${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…`;
+}
+async function readLockHolder(lockFilePath) {
+    const result = await readJsonFile({ filePath: lockFilePath, ifMissing: 'undefined' });
+    if (!result.success || result.data === undefined) {
+        return undefined;
+    }
+    const parsed = result.data;
+    if (typeof parsed.pid !== 'number' || Number.isNaN(parsed.pid)) {
+        return undefined;
+    }
+    return parsed;
+}
+async function tryAcquireWorkspaceFileLockOnce(input) {
+    const { lockFilePath, payload, spec, logger } = input;
+    try {
+        const handle = await fs__namespace.open(lockFilePath, 'wx');
+        try {
+            await handle.writeFile(formatJsonFileContent({ data: payload, trailingNewline: true }), 'utf8');
+        }
+        finally {
+            await handle.close();
+        }
+        return { status: 'acquired' };
+    }
+    catch (e) {
+        const code = core.nodeErrnoCode(e);
+        if (code !== 'EEXIST') {
+            throw e;
+        }
+    }
+    const holder = await readLockHolder(lockFilePath);
+    if (holder && core.isProcessAlive(holder.pid, { onProbeError: 'alive' })) {
+        return { status: 'busy', holder };
+    }
+    const stalePid = holder?.pid;
+    logger?.warn(`Removing stale ${spec.staleLogNoun} at "${lockFilePath}"` +
+        (stalePid !== undefined ? ` (pid ${stalePid} is not running)` : ''));
+    await fs__namespace.unlink(lockFilePath).catch(() => { });
+    return { status: 'stale_removed' };
+}
+async function acquireWorkspaceFileLock(input) {
+    const { spec, globalConfigFolderPath, workspacePath, lumpName, mode, projectName, logger } = input;
+    const normalizedWorkspacePath = path__namespace.resolve(workspacePath);
+    const locksDir = workspaceLocksDirPath({ globalConfigFolderPath, spec });
+    await fs__namespace.mkdir(locksDir, { recursive: true });
+    const lockFilePath = workspaceLockFilePath({
+        globalConfigFolderPath,
+        workspacePath: normalizedWorkspacePath,
+        spec,
+    });
+    const payload = {
+        pid: process.pid,
+        lumpName,
+        startedAt: new Date().toISOString(),
+        [spec.workspacePathField]: normalizedWorkspacePath,
+        ...(projectName !== undefined ? { projectName } : {}),
+    };
+    let loggedWait = false;
+    for (;;) {
+        const attempt = await tryAcquireWorkspaceFileLockOnce({ lockFilePath, payload, spec, logger });
+        if (attempt.status === 'acquired') {
+            const release = async () => {
+                try {
+                    const holder = await readLockHolder(lockFilePath);
+                    if (holder?.pid === process.pid) {
+                        await fs__namespace.unlink(lockFilePath);
+                    }
+                }
+                catch {
+                    // lock already gone
+                }
+            };
+            return core.success(release);
+        }
+        if (attempt.status === 'stale_removed') {
+            loggedWait = false;
+            continue;
+        }
+        if (mode === 'fail') {
+            return core.failure({
+                code: spec.busyCode,
+                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({
+                spec,
+                workspacePath: normalizedWorkspacePath,
+                holder: attempt.holder,
+            }));
+            loggedWait = true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, WAIT_POLL_MS));
+    }
+}
+
+/**
+ * Resolves the absolute git common directory for a worktree or main checkout
+ * (`git rev-parse --git-common-dir`).
+ */
+async function resolveGitCommonDir(input) {
+    const { cwd } = input;
+    const result = await core.execAsync('git rev-parse --path-format=absolute --git-common-dir', { cwd });
+    if (!result.success) {
+        // Older git without --path-format=absolute
+        const fallback = await core.execAsync('git rev-parse --git-common-dir', { cwd });
+        if (!fallback.success) {
+            return core.failure(`Failed to resolve git common dir: ${fallback.data.message}`);
+        }
+        const raw = fallback.data.stdout.trim();
+        return core.success(path__namespace.resolve(cwd, raw));
+    }
+    return core.success(path__namespace.resolve(result.data.stdout.trim()));
+}
+
+const GIT_COMMON_DIR_LOCK_SPEC = {
+    locksSubdirName: 'git-common-dir-locks',
+    busyCode: 'gitCommonDirBusy',
+    workspacePathField: 'gitCommonDir',
+    workspaceLabel: 'Git common dir',
+    waitLogNoun: 'git common dir',
+    staleLogNoun: 'git common dir lock',
+};
+async function acquireGitCommonDirLock(input) {
+    const commonDirResult = await resolveGitCommonDir({ cwd: input.gitCwd });
+    if (!commonDirResult.success) {
+        return commonDirResult;
+    }
+    return acquireWorkspaceFileLock({
+        spec: GIT_COMMON_DIR_LOCK_SPEC,
+        globalConfigFolderPath: input.globalConfigFolderPath,
+        workspacePath: commonDirResult.data,
+        lumpName: input.lumpName,
+        mode: input.lockMode,
+        projectName: input.projectName,
+        logger: input.logger,
+    });
+}
+/** Acquire, run `fn`, always release. */
+async function withGitCommonDirLock(input) {
+    const lockResult = await acquireGitCommonDirLock(input.lock);
+    if (!lockResult.success) {
+        return lockResult;
+    }
+    const releaseLock = lockResult.data;
+    try {
+        return core.success(await input.fn());
+    }
+    finally {
+        await releaseLock();
+    }
+}
+
+/**
+ * One locked `git fetch --prune --no-write-fetch-head` for context-status refresh.
+ * Uses `projectRoot` from the refresh call as `gitCwd` (overrides lock default).
+ */
+function makeLockedRefreshRemoteTrackingRefsFn(input) {
+    const { gitLock } = input;
+    return async ({ projectRoot, remoteName }) => {
+        const locked = await withGitCommonDirLock({
+            lock: { ...gitLock, gitCwd: projectRoot },
+            fn: async () => core.refreshRemoteTrackingRefs({ projectRoot, remoteName }),
+        });
+        if (!locked.success) {
+            return core.failure(typeof locked.data === 'string' ? locked.data : locked.data.message);
+        }
+        return locked.data;
+    };
+}
+
+async function getContextStatuses(input) {
+    const { projectRoot, lumpName, baseBranch, contextNames, skipRefresh = false } = input;
+    const uniqueNames = [...new Set(contextNames)];
+    const gitCommitMessageFn = makeGitCommitMessageFnFromLumpName(lumpName);
+    if (!skipRefresh) {
+        const refreshRemoteTrackingRefsFn = makeLockedRefreshRemoteTrackingRefsFn({
+            gitLock: {
+                globalConfigFolderPath: globalConfigFolderPath,
+                gitCwd: projectRoot,
+                lumpName,
+                lockMode: 'wait',
+            },
+        });
+        const refreshResult = await refreshRemoteTrackingRefsFn({ projectRoot });
+        if (!refreshResult.success) {
+            return new Map(uniqueNames.map((name) => [name, 'toDo']));
+        }
+    }
+    const statuses = await Promise.all(uniqueNames.map((contextName) => core.getContextStatus({
         contextName,
-        gitCommitMessageFn: makeGitCommitMessageFnFromLumpName(lumpName),
+        gitCommitMessageFn,
         projectRoot,
         baseBranch,
+        skipFetch: true,
+    })));
+    return new Map(uniqueNames.map((name, i) => [name, statuses[i]]));
+}
+async function getContextStatus(input) {
+    const { contextName, ...rest } = input;
+    const statuses = await getContextStatuses({
+        ...rest,
+        contextNames: [contextName],
     });
+    return statuses.get(contextName) ?? 'toDo';
 }
 
 function parseYamlList(raw) {
@@ -104,6 +389,7 @@ function normalizePromptAndSteps({ prompt, jsSteps, }) {
 }
 
 exports.getContextStatus = getContextStatus;
+exports.getContextStatuses = getContextStatuses;
 exports.getGitCommitMessage = getGitCommitMessage;
 exports.getLumpCommitPrefixForLump = getLumpCommitPrefixForLump;
 exports.makeGitCommitMessageFnFromLumpName = makeGitCommitMessageFnFromLumpName;

package/dist/index.d.ts

@@ -1,5 +1,12 @@
 export * from '@lumpcode/cli-types';
-import { LumpVariables, CodeBasePath, MaybePromise, Maybe, Context, ContextStatus, StepVariables, PromptFnInput, PostCommandExecFn, Step, PromptFn, RunLumpInput, GitCommitMessageFn } from '@lumpcode/core';
+import { ContextList, MaybePromise, LumpVariables, CodeBasePath, Maybe, Context, ContextStatus, GetContextListFnOutput, StepVariables, PromptFnInput, PostCommandExecFn, Step, PromptFn, RunLumpInput, GitCommitMessageFn } from '@lumpcode/core';
+
+type BaseBranchFnInput = {
+    effectiveDiscoveryBranch: string;
+    /** Pre-status raw list from the context source (not todo-filtered). */
+    contexts: ContextList;
+};
+type BaseBranchFn = (input: BaseBranchFnInput) => MaybePromise<string>;
 
 type CommandTag = string;
 
@@ -7,6 +14,7 @@ type ContextMatchFn<V extends LumpVariables = LumpVariables> = (params: {
     codeBasePath: CodeBasePath;
     codeBasePaths: CodeBasePath[];
     lumpVariables: V;
+    discoveryBranch: string;
 }) => MaybePromise<Maybe<{
     contextName: Context['name'];
     filePathVariableName: string;
@@ -27,6 +35,17 @@ type FilePath = string;
 
 type FilePathOrString = FilePath | string;
 
+/**
+ * Author-facing CLI context list fn. Requires concrete `discoveryBranch`.
+ * At the run boundary, CLI adapts this to core `GetContextListFn` (no discovery field).
+ */
+type GetContextListFnInput<V extends LumpVariables = LumpVariables> = {
+    codeBasePaths: CodeBasePath[];
+    lumpVariables: V;
+    discoveryBranch: string;
+};
+type GetContextListFn<V extends LumpVariables = LumpVariables> = (params: GetContextListFnInput<V>) => GetContextListFnOutput;
+
 type MergeObjs<T, U> = Omit<T, keyof U> & U;
 
 type LumpJsConfigStepsFn<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = (input: Omit<PromptFnInput<V, SV>, 'stepVariables'>) => MaybePromise<LumpJsConfigSteps<V, SV> | LumpJsConfigStepsItem<V, SV>>;
@@ -45,14 +64,24 @@ 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'>, {
-    baseBranch?: RunLumpInput<V, SV>['baseBranch'];
-    /** Which integration line this lump is discovered and scheduled on (defaults to primary branch from local.json). */
+}, 'gitCommitMessageFn' | 'projectRoot' | 'branchFn' | 'baseBranch' | 'setupWorkspaceFn' | 'teardownWorkspaceFn' | 'gitAddCommandFn' | 'gitCommitCommandFn' | 'gitPushCommandFn' | 'getContextListFn' | 'refreshRemoteTrackingRefsFn'>, {
+    /**
+     * Execution integration branch. Exact string, `BaseBranchFn`, or FilePath to a module.
+     * Omit → concrete effective discovery branch. Pattern strings are rejected at resolve.
+     */
+    baseBranch?: string | BaseBranchFn | FilePath;
+    /** Which integration line this lump is discovered and scheduled on (defaults to primary). Exact or git-glob. */
     discoveryBranch?: string;
+    /**
+     * Discovery rules (exact and/or git-glob). Mutually exclusive with `discoveryBranch`.
+     */
+    discoveryBranches?: string[];
     command?: LumpJsConfigStep<V, SV>['command'];
     contextListJson?: FilePath | Record<string, string>;
     contextMatchFn?: FilePath | ContextMatchFn<V>;
     contextOptionsFn?: FilePath | ContextOptionsFn;
+    /** Author context list fn (CLI shape with required `discoveryBranch`). */
+    getContextListFn?: FilePath | GetContextListFn<V>;
     disabled?: boolean | (() => MaybePromise<boolean>) | FilePath;
     maximumNumberOfConcurrentBranches?: number;
     prompt?: LumpJsConfigSoloStep<V, SV>;
@@ -62,6 +91,17 @@ type LumpJsConfig<V extends LumpVariables = LumpVariables, SV extends StepVariab
     verbose?: boolean;
 }>;
 
+declare function getContextStatuses(input: {
+    projectRoot: string;
+    lumpName: string;
+    baseBranch: string;
+    contextNames: string[];
+    /**
+     * When true, skip the locked remote refresh and classify from existing
+     * remote-tracking refs. Caller must have refreshed already when freshness matters.
+     */
+    skipRefresh?: boolean;
+}): Promise<Map<string, ContextStatus>>;
 declare function getContextStatus(input: {
     projectRoot: string;
     contextName: string;
@@ -145,5 +185,5 @@ type CodexPresetLumpVariables = {
 };
 type CodexPresetStepVariables = CodexPresetLumpVariables & PresetSessionStepVariables;
 
-export { getContextStatus, getGitCommitMessage, getLumpCommitPrefixForLump, makeGitCommitMessageFnFromLumpName, normalizeSteps, readYamlList };
+export { getContextStatus, getContextStatuses, getGitCommitMessage, getLumpCommitPrefixForLump, makeGitCommitMessageFnFromLumpName, normalizeSteps, readYamlList };
 export type { ClaudeCodeAgentPermissions, ClaudeCodePresetLumpVariables, ClaudeCodePresetStepVariables, CodexAgentPermissions, CodexPresetLumpVariables, CodexPresetStepVariables, CopilotAgentPermissions, CopilotPresetLumpVariables, CopilotPresetStepVariables, CursorAgentPermissions, CursorPresetLumpVariables, CursorPresetStepVariables, OpenCodeAgentPermissions, OpenCodePresetLumpVariables, OpenCodePresetStepVariables, PresetSessionStepVariables };

package/dist/index.js

@@ -1,10 +1,16 @@
 export * from '@lumpcode/cli-types';
-import { getContextStatus as getContextStatus$1 } from '@lumpcode/core';
+import { nodeErrnoCode, success, failure, isProcessAlive, execAsync, refreshRemoteTrackingRefs, getContextStatus as getContextStatus$1 } from '@lumpcode/core';
 import * as path from 'node:path';
+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 fs from 'node:fs/promises';
 import { load } from 'js-yaml';
 
+const globalConfigFolderPath = path__default.join(os__default.homedir(), '.lumpcode');
+path__default.join(process.cwd(), '.lumpcode');
+
 path.join(os.homedir(), '.lumpcode', 'auth.json');
 const LUMP_COMMIT_PREFIX = "LUMP: ";
 
@@ -29,14 +35,294 @@ function makeGitCommitMessageFnFromLumpName(lumpName) {
     };
 }
 
-async function getContextStatus(input) {
-    const { projectRoot, contextName, lumpName, baseBranch } = input;
-    return getContextStatus$1({
+async function readJsonFile(input) {
+    const { filePath, ifMissing = 'fail', missingFileFailure } = input;
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        const code = nodeErrnoCode(error);
+        if (code === 'ENOENT') {
+            if (ifMissing === 'undefined') {
+                return success(undefined);
+            }
+            if (typeof ifMissing === 'object') {
+                return success(ifMissing.defaultValue);
+            }
+            return failure(missingFileFailure ?? `File not found: ${filePath}`);
+        }
+        return failure(`Cannot read ${filePath}: ${String(error)}`);
+    }
+    try {
+        return success(JSON.parse(raw));
+    }
+    catch (error) {
+        return failure(`Invalid JSON in ${filePath}: ${String(error)}`);
+    }
+}
+
+function resolvePrettySpace(pretty) {
+    if (pretty === true)
+        return 2;
+    if (typeof pretty === 'number')
+        return pretty;
+    return undefined;
+}
+/** Pure formatter shared with callers that write via an open handle (e.g. workspace locks). */
+function formatJsonFileContent(input) {
+    const { data, pretty, trailingNewline = false } = input;
+    const space = resolvePrettySpace(pretty);
+    const json = space === undefined ? JSON.stringify(data) : JSON.stringify(data, null, space);
+    return trailingNewline ? `${json}\n` : json;
+}
+
+const WAIT_POLL_MS = 500;
+function workspaceLocksDirPath(input) {
+    return path.join(input.globalConfigFolderPath, input.spec.locksSubdirName);
+}
+function workspaceLockFilePath(input) {
+    const normalizedPath = path.resolve(input.workspacePath);
+    const hash = crypto.createHash('sha256').update(normalizedPath).digest('hex');
+    return path.join(workspaceLocksDirPath({
+        globalConfigFolderPath: input.globalConfigFolderPath,
+        spec: input.spec,
+    }), `${hash}.lock.json`);
+}
+function formatBusyMessage(input) {
+    const { spec, workspacePath, holder } = input;
+    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.`);
+    }
+    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 (`${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…`;
+}
+async function readLockHolder(lockFilePath) {
+    const result = await readJsonFile({ filePath: lockFilePath, ifMissing: 'undefined' });
+    if (!result.success || result.data === undefined) {
+        return undefined;
+    }
+    const parsed = result.data;
+    if (typeof parsed.pid !== 'number' || Number.isNaN(parsed.pid)) {
+        return undefined;
+    }
+    return parsed;
+}
+async function tryAcquireWorkspaceFileLockOnce(input) {
+    const { lockFilePath, payload, spec, logger } = input;
+    try {
+        const handle = await fs.open(lockFilePath, 'wx');
+        try {
+            await handle.writeFile(formatJsonFileContent({ data: payload, trailingNewline: true }), 'utf8');
+        }
+        finally {
+            await handle.close();
+        }
+        return { status: 'acquired' };
+    }
+    catch (e) {
+        const code = nodeErrnoCode(e);
+        if (code !== 'EEXIST') {
+            throw e;
+        }
+    }
+    const holder = await readLockHolder(lockFilePath);
+    if (holder && isProcessAlive(holder.pid, { onProbeError: 'alive' })) {
+        return { status: 'busy', holder };
+    }
+    const stalePid = holder?.pid;
+    logger?.warn(`Removing stale ${spec.staleLogNoun} at "${lockFilePath}"` +
+        (stalePid !== undefined ? ` (pid ${stalePid} is not running)` : ''));
+    await fs.unlink(lockFilePath).catch(() => { });
+    return { status: 'stale_removed' };
+}
+async function acquireWorkspaceFileLock(input) {
+    const { spec, globalConfigFolderPath, workspacePath, lumpName, mode, projectName, logger } = input;
+    const normalizedWorkspacePath = path.resolve(workspacePath);
+    const locksDir = workspaceLocksDirPath({ globalConfigFolderPath, spec });
+    await fs.mkdir(locksDir, { recursive: true });
+    const lockFilePath = workspaceLockFilePath({
+        globalConfigFolderPath,
+        workspacePath: normalizedWorkspacePath,
+        spec,
+    });
+    const payload = {
+        pid: process.pid,
+        lumpName,
+        startedAt: new Date().toISOString(),
+        [spec.workspacePathField]: normalizedWorkspacePath,
+        ...(projectName !== undefined ? { projectName } : {}),
+    };
+    let loggedWait = false;
+    for (;;) {
+        const attempt = await tryAcquireWorkspaceFileLockOnce({ lockFilePath, payload, spec, logger });
+        if (attempt.status === 'acquired') {
+            const release = async () => {
+                try {
+                    const holder = await readLockHolder(lockFilePath);
+                    if (holder?.pid === process.pid) {
+                        await fs.unlink(lockFilePath);
+                    }
+                }
+                catch {
+                    // lock already gone
+                }
+            };
+            return success(release);
+        }
+        if (attempt.status === 'stale_removed') {
+            loggedWait = false;
+            continue;
+        }
+        if (mode === 'fail') {
+            return failure({
+                code: spec.busyCode,
+                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({
+                spec,
+                workspacePath: normalizedWorkspacePath,
+                holder: attempt.holder,
+            }));
+            loggedWait = true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, WAIT_POLL_MS));
+    }
+}
+
+/**
+ * Resolves the absolute git common directory for a worktree or main checkout
+ * (`git rev-parse --git-common-dir`).
+ */
+async function resolveGitCommonDir(input) {
+    const { cwd } = input;
+    const result = await execAsync('git rev-parse --path-format=absolute --git-common-dir', { cwd });
+    if (!result.success) {
+        // Older git without --path-format=absolute
+        const fallback = await execAsync('git rev-parse --git-common-dir', { cwd });
+        if (!fallback.success) {
+            return failure(`Failed to resolve git common dir: ${fallback.data.message}`);
+        }
+        const raw = fallback.data.stdout.trim();
+        return success(path.resolve(cwd, raw));
+    }
+    return success(path.resolve(result.data.stdout.trim()));
+}
+
+const GIT_COMMON_DIR_LOCK_SPEC = {
+    locksSubdirName: 'git-common-dir-locks',
+    busyCode: 'gitCommonDirBusy',
+    workspacePathField: 'gitCommonDir',
+    workspaceLabel: 'Git common dir',
+    waitLogNoun: 'git common dir',
+    staleLogNoun: 'git common dir lock',
+};
+async function acquireGitCommonDirLock(input) {
+    const commonDirResult = await resolveGitCommonDir({ cwd: input.gitCwd });
+    if (!commonDirResult.success) {
+        return commonDirResult;
+    }
+    return acquireWorkspaceFileLock({
+        spec: GIT_COMMON_DIR_LOCK_SPEC,
+        globalConfigFolderPath: input.globalConfigFolderPath,
+        workspacePath: commonDirResult.data,
+        lumpName: input.lumpName,
+        mode: input.lockMode,
+        projectName: input.projectName,
+        logger: input.logger,
+    });
+}
+/** Acquire, run `fn`, always release. */
+async function withGitCommonDirLock(input) {
+    const lockResult = await acquireGitCommonDirLock(input.lock);
+    if (!lockResult.success) {
+        return lockResult;
+    }
+    const releaseLock = lockResult.data;
+    try {
+        return success(await input.fn());
+    }
+    finally {
+        await releaseLock();
+    }
+}
+
+/**
+ * One locked `git fetch --prune --no-write-fetch-head` for context-status refresh.
+ * Uses `projectRoot` from the refresh call as `gitCwd` (overrides lock default).
+ */
+function makeLockedRefreshRemoteTrackingRefsFn(input) {
+    const { gitLock } = input;
+    return async ({ projectRoot, remoteName }) => {
+        const locked = await withGitCommonDirLock({
+            lock: { ...gitLock, gitCwd: projectRoot },
+            fn: async () => refreshRemoteTrackingRefs({ projectRoot, remoteName }),
+        });
+        if (!locked.success) {
+            return failure(typeof locked.data === 'string' ? locked.data : locked.data.message);
+        }
+        return locked.data;
+    };
+}
+
+async function getContextStatuses(input) {
+    const { projectRoot, lumpName, baseBranch, contextNames, skipRefresh = false } = input;
+    const uniqueNames = [...new Set(contextNames)];
+    const gitCommitMessageFn = makeGitCommitMessageFnFromLumpName(lumpName);
+    if (!skipRefresh) {
+        const refreshRemoteTrackingRefsFn = makeLockedRefreshRemoteTrackingRefsFn({
+            gitLock: {
+                globalConfigFolderPath: globalConfigFolderPath,
+                gitCwd: projectRoot,
+                lumpName,
+                lockMode: 'wait',
+            },
+        });
+        const refreshResult = await refreshRemoteTrackingRefsFn({ projectRoot });
+        if (!refreshResult.success) {
+            return new Map(uniqueNames.map((name) => [name, 'toDo']));
+        }
+    }
+    const statuses = await Promise.all(uniqueNames.map((contextName) => getContextStatus$1({
         contextName,
-        gitCommitMessageFn: makeGitCommitMessageFnFromLumpName(lumpName),
+        gitCommitMessageFn,
         projectRoot,
         baseBranch,
+        skipFetch: true,
+    })));
+    return new Map(uniqueNames.map((name, i) => [name, statuses[i]]));
+}
+async function getContextStatus(input) {
+    const { contextName, ...rest } = input;
+    const statuses = await getContextStatuses({
+        ...rest,
+        contextNames: [contextName],
     });
+    return statuses.get(contextName) ?? 'toDo';
 }
 
 function parseYamlList(raw) {
@@ -80,4 +366,4 @@ function normalizePromptAndSteps({ prompt, jsSteps, }) {
     return { prompt, jsSteps };
 }
 
-export { getContextStatus, getGitCommitMessage, getLumpCommitPrefixForLump, makeGitCommitMessageFnFromLumpName, normalizeSteps, readYamlList };
+export { getContextStatus, getContextStatuses, getGitCommitMessage, getLumpCommitPrefixForLump, makeGitCommitMessageFnFromLumpName, normalizeSteps, readYamlList };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumpcode/cli-utils",
-  "version": "0.0.16",
+  "version": "0.1.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.0.16",
-    "@lumpcode/core": "^0.0.16",
+    "@lumpcode/cli-types": "^0.1.0",
+    "@lumpcode/core": "^0.1.0",
     "js-yaml": "^5.0.0"
   },
   "devDependencies": {