get-tbd 0.1.23 → 0.1.25

package/README.md

@@ -279,7 +279,7 @@ npm install -g get-tbd@latest
 ### Setup
 
 ```bash
-# Fresh project (--prefix is REQUIRED—2-8 alphabetic chars, e.g. myapp-a1b2)
+# Fresh project (--prefix is REQUIRED—a short alphabetic name used as an issue ID prefix, e.g. myapp → issues like myapp-a1b2)
 tbd setup --auto --prefix=myapp
 
 # Joining an existing tbd project (no prefix needed—reads existing config)
@@ -299,7 +299,7 @@ tbd setup --from-beads
 **First contributor:**
 ```bash
 npm install -g get-tbd@latest
-tbd setup --auto --prefix=myproject
+tbd setup --auto --prefix=proj   # Short alphabetic prefix for issue IDs
 git add .tbd/ .claude/ && git commit -m "Initialize tbd"
 git push
 ```

package/dist/bin.mjs

@@ -8,7 +8,7 @@ import process$1 from "node:process";
 import matter from "gray-matter";
 import os, { homedir } from "node:os";
 import tty from "node:tty";
-import { access, chmod, cp, mkdir, readFile, readdir, rename, rm, stat, unlink } from "node:fs/promises";
+import { access, chmod, cp, mkdir, readFile, readdir, rename, rm, rmdir, stat, unlink } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { promisify } from "node:util";
 import crypto, { randomBytes } from "node:crypto";
@@ -14033,7 +14033,7 @@ function serializeIssue(issue) {
 * Package version, derived from git at build time.
 * Format: X.Y.Z for releases, X.Y.Z-dev.N.hash for dev builds.
 */
-const VERSION$1 = "0.1.23";
+const VERSION$1 = "0.1.25";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -99273,7 +99273,11 @@ async function migrateDataToWorktree(baseDir, removeSource = false) {
 		await mkdir(correctIssuesPath, { recursive: true });
 		await mkdir(correctMappingsPath, { recursive: true });
 		for (const file of issueFiles) await cp(join(wrongIssuesPath, file), join(correctIssuesPath, file));
-		for (const file of mappingFiles) await cp(join(wrongMappingsPath, file), join(correctMappingsPath, file));
+		for (const file of mappingFiles) if (file === "ids.yml") {
+			const { loadIdMapping, mergeIdMappings, saveIdMapping } = await Promise.resolve().then(() => id_mapping_exports);
+			const sourceMapping = await loadIdMapping(wrongPath);
+			await saveIdMapping(correctPath, mergeIdMappings(await loadIdMapping(correctPath), sourceMapping));
+		} else await cp(join(wrongMappingsPath, file), join(correctMappingsPath, file));
 		const totalFiles = issueFiles.length + mappingFiles.length;
 		await git("-C", worktreePath, "add", "-A");
 		if (await git("-C", worktreePath, "diff", "--cached", "--quiet").then(() => false).catch(() => true)) await git("-C", worktreePath, "commit", "--no-verify", "-m", `tbd: migrate ${totalFiles} file(s) from incorrect location`);
@@ -99747,31 +99751,154 @@ async function listIssues(baseDir) {
 		return [];
 	}
 	const mdFiles = files.filter((f) => f.endsWith(".md"));
-	const fileContents = await Promise.all(mdFiles.map(async (file) => {
-		const filePath = join(issuesDir, file);
+	const BATCH_SIZE = 200;
+	const issues = [];
+	for (let i = 0; i < mdFiles.length; i += BATCH_SIZE) {
+		const batch = mdFiles.slice(i, i + BATCH_SIZE);
+		const fileContents = await Promise.all(batch.map(async (file) => {
+			const filePath = join(issuesDir, file);
+			try {
+				return {
+					file,
+					content: await readFile(filePath, "utf-8")
+				};
+			} catch {
+				return {
+					file,
+					content: null
+				};
+			}
+		}));
+		for (const { file, content } of fileContents) {
+			if (content === null) continue;
+			try {
+				const issue = parseIssue(content);
+				issues.push(issue);
+			} catch (error) {
+				console.warn(`Skipping invalid issue file: ${file}`, error);
+			}
+		}
+	}
+	return issues;
+}
+
+//#endregion
+//#region src/utils/lockfile.ts
+/**
+* Directory-based mutual exclusion for concurrent file access.
+*
+* Note: Despite the name "lockfile", this is NOT a POSIX file lock (flock/fcntl).
+* It uses mkdir to create a lock *directory* as a coordination convention — no
+* OS-level file locking syscalls are involved. This makes it portable across all
+* filesystems, including NFS and other network mounts where flock/fcntl locks
+* are unreliable or unsupported.
+*
+* This is the same strategy used by:
+*
+* - **Git** for ref updates (e.g., `.git/refs/heads/main.lock`)
+*   See: https://git-scm.com/docs/gitrepository-layout ("lockfile protocol")
+* - **npm** for package-lock.json concurrent access
+*
+* ## Why mkdir?
+*
+* `mkdir(2)` is atomic on all common filesystems (local and network): it either
+* creates the directory or returns EEXIST. Unlike `open(O_CREAT|O_EXCL)`,
+* a directory lock is trivially distinguishable from normal files.
+*
+* Node.js `fs.mkdir` maps directly to the mkdir(2) syscall, preserving
+* the atomicity guarantee:
+*   https://nodejs.org/api/fs.html#fsmkdirpath-options-callback
+*
+* ## Lock lifecycle
+*
+* 1. **Acquire**: `mkdir(lockDir)` — fails with EEXIST if held by another process
+* 2. **Hold**: Execute the critical section
+* 3. **Release**: `rmdir(lockDir)` — in a finally block
+* 4. **Stale detection**: If lock mtime exceeds a threshold, assume the holder
+*    crashed and break the lock. This is a heuristic — safe when the critical
+*    section is short-lived (sub-second for file I/O).
+*
+* ## Failure on timeout
+*
+* If the lock cannot be acquired within the timeout, a LockAcquisitionError is
+* thrown. This prevents the dangerous "degraded mode" where the critical section
+* runs without mutual exclusion, which can cause data loss (e.g., lost ID
+* mappings during concurrent `tbd create`).
+*
+* IMPORTANT: `timeoutMs` must be greater than `staleMs` so stale locks from
+* crashed processes are always detected and broken before the timeout expires.
+*/
+const DEFAULT_TIMEOUT_MS = 1e4;
+const DEFAULT_POLL_MS = 50;
+const DEFAULT_STALE_MS = 5e3;
+/**
+* Error thrown when the lock cannot be acquired within the timeout.
+*/
+var LockAcquisitionError = class extends Error {
+	constructor(lockPath, timeoutMs) {
+		super(`Failed to acquire lock at ${lockPath} within ${timeoutMs}ms. Another process may be holding the lock. If this persists, delete the lock directory manually and retry.`);
+		this.name = "LockAcquisitionError";
+	}
+};
+/**
+* Execute `fn` while holding a lockfile.
+*
+* The lock is a directory at `lockPath` (typically `<target-file>.lock`).
+* Concurrent callers will wait up to `timeoutMs` for the lock, polling
+* every `pollMs`. Stale locks older than `staleMs` are broken automatically.
+*
+* If the lock cannot be acquired within the timeout, a LockAcquisitionError
+* is thrown. This ensures mutual exclusion is never silently bypassed, which
+* prevents data loss from concurrent writes.
+*
+* @param lockPath - Path to use as the lock directory (e.g., "/path/to/ids.yml.lock")
+* @param fn - Critical section to execute under the lock
+* @param options - Timing parameters for lock acquisition
+* @returns The return value of `fn`
+* @throws LockAcquisitionError if the lock cannot be acquired within the timeout
+*
+* @example
+* ```ts
+* await withLockfile('/path/to/ids.yml.lock', async () => {
+*   const data = await readFile('/path/to/ids.yml', 'utf-8');
+*   const updated = mergeEntries(data, newEntries);
+*   await writeFile('/path/to/ids.yml', updated);
+* });
+* ```
+*/
+async function withLockfile(lockPath, fn, options) {
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;
+	const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;
+	const deadline = Date.now() + timeoutMs;
+	let acquired = false;
+	while (Date.now() < deadline) try {
+		await mkdir(lockPath);
+		acquired = true;
+		break;
+	} catch (error) {
+		if (error.code !== "EEXIST") break;
 		try {
-			return {
-				file,
-				content: await readFile(filePath, "utf-8")
-			};
+			const lockStat = await stat(lockPath);
+			if (Date.now() - lockStat.mtimeMs > staleMs) {
+				try {
+					await rmdir(lockPath);
+				} catch {}
+				continue;
+			}
 		} catch {
-			return {
-				file,
-				content: null
-			};
+			continue;
 		}
-	}));
-	const issues = [];
-	for (const { file, content } of fileContents) {
-		if (content === null) continue;
+		await new Promise((resolve) => setTimeout(resolve, pollMs));
+	}
+	if (!acquired) throw new LockAcquisitionError(lockPath, timeoutMs);
+	try {
+		return await fn();
+	} finally {
 		try {
-			const issue = parseIssue(content);
-			issues.push(issue);
-		} catch (error) {
-			console.warn(`Skipping invalid issue file: ${file}`, error);
-		}
+			await rmdir(lockPath);
+		} catch {}
 	}
-	return issues;
 }
 
 //#endregion
@@ -99918,15 +100045,54 @@ async function loadIdMapping(baseDir) {
 	};
 }
 /**
-* Save the ID mapping to disk.
+* Save the ID mapping to disk with mutual exclusion.
+*
+* Uses a lockfile to serialize concurrent writers, then performs read-merge-write
+* inside the lock. This prevents the lost-update problem when multiple `tbd create`
+* commands run in parallel.
+*
+* The merge is safe because ID mappings are append-only — entries are never
+* intentionally removed. If the lock cannot be acquired within the timeout,
+* a LockAcquisitionError is thrown rather than proceeding without protection.
 */
 async function saveIdMapping(baseDir, mapping) {
 	const filePath = getMappingPath(baseDir);
 	await mkdir(dirname(filePath), { recursive: true });
-	const data = {};
-	const sortedKeys = naturalSort(Array.from(mapping.shortToUlid.keys()));
-	for (const key of sortedKeys) data[key] = mapping.shortToUlid.get(key);
-	await writeFile(filePath, stringifyYaml(data));
+	await withLockfile(filePath + ".lock", async () => {
+		let merged = mapping;
+		let onDiskSize = 0;
+		try {
+			const onDisk = await loadIdMappingRaw(filePath);
+			onDiskSize = onDisk.shortToUlid.size;
+			if (onDiskSize > 0) merged = mergeIdMappings(mapping, onDisk);
+		} catch {}
+		if (merged.shortToUlid.size < onDiskSize) throw new Error(`Refusing to save ID mapping: would lose ${onDiskSize - merged.shortToUlid.size} entries (on-disk: ${onDiskSize}, proposed: ${merged.shortToUlid.size}). ID mappings are append-only — this indicates a bug.`);
+		const data = {};
+		const sortedKeys = naturalSort(Array.from(merged.shortToUlid.keys()));
+		for (const key of sortedKeys) data[key] = merged.shortToUlid.get(key);
+		await writeFile(filePath, stringifyYaml(data));
+	});
+}
+/**
+* Load an ID mapping directly from a file path (internal helper for save merging).
+* Separated from loadIdMapping to avoid coupling the save path to baseDir resolution.
+*/
+async function loadIdMappingRaw(filePath) {
+	const { data: rawData } = parseYamlToleratingDuplicateKeys(await readFile(filePath, "utf-8"), filePath);
+	const data = rawData ?? {};
+	const parseResult = IdMappingYamlSchema.safeParse(data);
+	if (!parseResult.success) throw new Error(`Invalid ID mapping format in ${filePath}: ${parseResult.error.message}`);
+	const validData = parseResult.data;
+	const shortToUlid = /* @__PURE__ */ new Map();
+	const ulidToShort = /* @__PURE__ */ new Map();
+	for (const [shortId, ulid] of Object.entries(validData)) {
+		shortToUlid.set(shortId, ulid);
+		ulidToShort.set(ulid, shortId);
+	}
+	return {
+		shortToUlid,
+		ulidToShort
+	};
 }
 /**
 * Calculate the optimal short ID length based on existing ID count.
@@ -104456,9 +104622,18 @@ var DoctorHandler = class extends BaseCommand {
 		healthChecks.push(await this.checkIdMappingDuplicates(options.fix));
 		healthChecks.push(await this.checkTempFiles(options.fix));
 		healthChecks.push(this.checkIssueValidity(this.issues));
-		healthChecks.push(await this.checkMissingMappings(options.fix));
 		healthChecks.push(await this.checkWorktree(options.fix));
-		healthChecks.push(await this.checkDataLocation(options.fix));
+		const dataLocationResult = await this.checkDataLocation(options.fix);
+		healthChecks.push(dataLocationResult);
+		if (dataLocationResult.status === "ok" && dataLocationResult.message?.includes("migrated")) {
+			this.dataSyncDir = await resolveDataSyncDir(this.cwd);
+			try {
+				this.issues = await listIssues(this.dataSyncDir);
+			} catch {}
+		}
+		const parsedMaxHistory = options.maxHistory ? parseInt(options.maxHistory, 10) : 50;
+		const maxHistory = Number.isNaN(parsedMaxHistory) || parsedMaxHistory < 0 ? 50 : parsedMaxHistory;
+		healthChecks.push(await this.checkMissingMappings(options.fix, maxHistory));
 		healthChecks.push(await this.checkLocalSyncBranch());
 		healthChecks.push(await this.checkRemoteSyncBranch());
 		healthChecks.push(await this.checkLocalVsRemoteData());
@@ -104810,7 +104985,7 @@ var DoctorHandler = class extends BaseCommand {
 	*
 	* With --fix, creates missing mappings automatically.
 	*/
-	async checkMissingMappings(fix) {
+	async checkMissingMappings(fix, maxHistory = 50) {
 		if (this.issues.length === 0) return {
 			name: "ID mapping coverage",
 			status: "ok"
@@ -104827,25 +105002,41 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Create missing ID mappings")) {
-			const { parseIdMappingFromYaml } = await Promise.resolve().then(() => id_mapping_exports);
+			const { parseIdMappingFromYaml, mergeIdMappings } = await Promise.resolve().then(() => id_mapping_exports);
 			let historicalMapping;
 			try {
 				const syncBranch = (await Promise.resolve().then(() => config_exports).then((m) => m.readConfig(this.cwd))).sync.branch;
-				const priorContent = await git("log", "-1", "--format=%H", syncBranch, "--", `${DATA_SYNC_DIR}/mappings/ids.yml`);
-				if (priorContent.trim()) {
-					const idsContent = await git("show", `${priorContent.trim()}:${DATA_SYNC_DIR}/mappings/ids.yml`);
-					if (idsContent) historicalMapping = parseIdMappingFromYaml(idsContent);
-				}
+				const logArgs = ["log", "--format=%H"];
+				if (maxHistory > 0) logArgs.push(`-${maxHistory}`);
+				logArgs.push(syncBranch, "--", `${DATA_SYNC_DIR}/mappings/ids.yml`);
+				const commitHashes = (await git(...logArgs)).trim().split("\n").filter(Boolean);
+				for (const commitHash of commitHashes) try {
+					const idsContent = await git("show", `${commitHash}:${DATA_SYNC_DIR}/mappings/ids.yml`);
+					if (idsContent) {
+						const versionMapping = parseIdMappingFromYaml(idsContent);
+						if (!historicalMapping) historicalMapping = versionMapping;
+						else historicalMapping = mergeIdMappings(historicalMapping, versionMapping);
+					}
+				} catch {}
 			} catch {}
+			const historicalCount = historicalMapping?.shortToUlid.size ?? 0;
 			const result = reconcileMappings(missingIds, mapping, historicalMapping);
 			await saveIdMapping(this.dataSyncDir, mapping);
 			const parts = [];
 			if (result.recovered.length > 0) parts.push(`recovered ${result.recovered.length} from git history`);
 			if (result.created.length > 0) parts.push(`created ${result.created.length} new`);
+			const details = [
+				`Scanned ${maxHistory > 0 ? `up to ${maxHistory}` : "all"} git commits for ids.yml history`,
+				`Found ${historicalCount} historical mapping(s) to use for recovery`,
+				`${missingIds.length} issue(s) were missing short ID mappings`
+			];
+			if (result.recovered.length > 0) details.push(`Recovered ${result.recovered.length} original short ID(s) from git history`);
+			if (result.created.length > 0) details.push(`Generated ${result.created.length} new short ID(s) (originals not found in history)`);
 			return {
 				name: "ID mapping coverage",
 				status: "ok",
-				message: parts.join(", ")
+				message: parts.join(", "),
+				details
 			};
 		}
 		return {
@@ -105004,13 +105195,19 @@ var DoctorHandler = class extends BaseCommand {
 				path: wrongIssuesPath,
 				details: ["Cannot migrate: worktree must be repaired first.", "The worktree repair should have run before this check."]
 			};
-			const result = await migrateDataToWorktree(this.cwd);
-			if (result.success) return {
-				name: "Data location",
-				status: "ok",
-				message: result.backupPath ? `migrated ${result.migratedCount} file(s), backed up to ${result.backupPath}` : `migrated ${result.migratedCount} file(s)`,
-				path: wrongIssuesPath
-			};
+			const result = await migrateDataToWorktree(this.cwd, true);
+			if (result.success) {
+				const details = [];
+				if (result.backupPath) details.push(`Backed up to ${result.backupPath}`);
+				details.push(`Migrated ${result.migratedCount} file(s) from .tbd/data-sync/ to worktree`, "Source files removed after successful migration");
+				return {
+					name: "Data location",
+					status: "ok",
+					message: result.backupPath ? `migrated ${result.migratedCount} file(s), backed up to ${result.backupPath}` : `migrated ${result.migratedCount} file(s)`,
+					path: wrongIssuesPath,
+					details
+				};
+			}
 			return {
 				name: "Data location",
 				status: "error",
@@ -105207,15 +105404,13 @@ var DoctorHandler = class extends BaseCommand {
 			};
 			if (consistency.localAhead > 0) return {
 				name: "Sync consistency",
-				status: "warn",
-				message: `${consistency.localAhead} commit(s) ahead of remote`,
-				suggestion: "Run: tbd sync to push changes"
+				status: "ok",
+				message: `${consistency.localAhead} local commit(s) not yet pushed — run \`tbd sync\` to push`
 			};
 			if (consistency.localBehind > 0) return {
 				name: "Sync consistency",
-				status: "warn",
-				message: `${consistency.localBehind} commit(s) behind remote`,
-				suggestion: "Run: tbd sync to pull changes"
+				status: "ok",
+				message: `${consistency.localBehind} remote commit(s) not yet pulled — run \`tbd sync\` to pull`
 			};
 			return {
 				name: "Sync consistency",
@@ -105236,7 +105431,7 @@ var DoctorHandler = class extends BaseCommand {
 		}
 	}
 };
-const doctorCommand = new Command("doctor").description("Diagnose and repair repository").option("--fix", "Attempt to fix issues").action(async (options, command) => {
+const doctorCommand = new Command("doctor").description("Diagnose and repair repository").option("--fix", "Attempt to fix issues").option("--max-history <n>", "Max git commits to scan for ID mapping recovery (0 = full history)", "50").action(async (options, command) => {
 	await new DoctorHandler(command).run(options);
 });