get-tbd 0.1.24 → 0.1.26

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

@@ -13735,6 +13735,18 @@ const ordering = {
 * IMPORTANT: Always use these utilities instead of raw yaml package functions.
 * This ensures consistent formatting and proper error handling across the codebase.
 */
+var yaml_utils_exports = /* @__PURE__ */ __exportAll({
+	MergeConflictError: () => MergeConflictError,
+	YAML_STRINGIFY_OPTIONS: () => YAML_STRINGIFY_OPTIONS,
+	YAML_STRINGIFY_OPTIONS_COMPACT: () => YAML_STRINGIFY_OPTIONS_COMPACT,
+	detectDuplicateYamlKeys: () => detectDuplicateYamlKeys,
+	hasMergeConflictMarkers: () => hasMergeConflictMarkers,
+	parseYamlToleratingDuplicateKeys: () => parseYamlToleratingDuplicateKeys,
+	parseYamlWithConflictDetection: () => parseYamlWithConflictDetection,
+	sortKeys: () => sortKeys,
+	stringifyYaml: () => stringifyYaml,
+	stringifyYamlCompact: () => stringifyYamlCompact
+});
 /**
 * Serialize data to YAML with readable formatting.
 *
@@ -14033,7 +14045,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.24";
+const VERSION$1 = "0.1.26";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -99037,6 +99049,7 @@ async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH
 		await writeFile(join(dataSyncPath, "meta.yml"), "schema_version: 1\n");
 		await writeFile(join(dataSyncPath, "issues", ".gitkeep"), "");
 		await writeFile(join(dataSyncPath, "mappings", ".gitkeep"), "");
+		await writeFile(join(dataSyncPath, "mappings", ".gitattributes"), "ids.yml merge=union\n");
 		await git("-C", worktreePath, "add", ".");
 		await git("-C", worktreePath, "commit", "--no-verify", "-m", "Initialize tbd-sync branch");
 		return {
@@ -99274,9 +99287,16 @@ async function migrateDataToWorktree(baseDir, removeSource = false) {
 		await mkdir(correctMappingsPath, { recursive: true });
 		for (const file of issueFiles) await cp(join(wrongIssuesPath, file), join(correctIssuesPath, 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));
+			const { readFile } = await import("node:fs/promises");
+			const { loadIdMapping, mergeIdMappings, saveIdMapping, resolveIdMappingConflicts } = await Promise.resolve().then(() => id_mapping_exports);
+			const sourceMapping = resolveIdMappingConflicts(await readFile(join(wrongMappingsPath, file), "utf-8"));
+			let targetMapping;
+			try {
+				targetMapping = resolveIdMappingConflicts(await readFile(join(correctMappingsPath, file), "utf-8"));
+			} catch {
+				targetMapping = await loadIdMapping(correctPath);
+			}
+			await saveIdMapping(correctPath, mergeIdMappings(targetMapping, sourceMapping));
 		} else await cp(join(wrongMappingsPath, file), join(correctMappingsPath, file));
 		const totalFiles = issueFiles.length + mappingFiles.length;
 		await git("-C", worktreePath, "add", "-A");
@@ -99751,28 +99771,32 @@ 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);
-		try {
-			return {
-				file,
-				content: await readFile(filePath, "utf-8")
-			};
-		} catch {
-			return {
-				file,
-				content: null
-			};
-		}
-	}));
+	const BATCH_SIZE = 200;
 	const issues = [];
-	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);
+	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;
@@ -99814,30 +99838,44 @@ async function listIssues(baseDir) {
 *    crashed and break the lock. This is a heuristic — safe when the critical
 *    section is short-lived (sub-second for file I/O).
 *
-* ## Degraded mode
+* ## 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`).
 *
-* If the lock cannot be acquired within the timeout (e.g., due to a stuck
-* lockfile that isn't old enough to break), the critical section runs anyway.
-* Callers should design their critical sections to be safe without the lock
-* (e.g., using read-merge-write for append-only data).
+* 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 = 2e3;
+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, `fn` is still executed (degraded mode).
-* This ensures a stuck lockfile never permanently blocks the CLI.
+* 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
@@ -99859,7 +99897,7 @@ async function withLockfile(lockPath, fn, options) {
 		acquired = true;
 		break;
 	} catch (error) {
-		if (error.code !== "EEXIST") break;
+		if (error.code !== "EEXIST") throw error;
 		try {
 			const lockStat = await stat(lockPath);
 			if (Date.now() - lockStat.mtimeMs > staleMs) {
@@ -99873,10 +99911,11 @@ async function withLockfile(lockPath, fn, options) {
 		}
 		await new Promise((resolve) => setTimeout(resolve, pollMs));
 	}
+	if (!acquired) throw new LockAcquisitionError(lockPath, timeoutMs);
 	try {
 		return await fn();
 	} finally {
-		if (acquired) try {
+		try {
 			await rmdir(lockPath);
 		} catch {}
 	}
@@ -99984,6 +100023,7 @@ var id_mapping_exports = /* @__PURE__ */ __exportAll({
 	mergeIdMappings: () => mergeIdMappings,
 	parseIdMappingFromYaml: () => parseIdMappingFromYaml,
 	reconcileMappings: () => reconcileMappings,
+	resolveIdMappingConflicts: () => resolveIdMappingConflicts,
 	resolveToInternalId: () => resolveToInternalId,
 	saveIdMapping: () => saveIdMapping
 });
@@ -100033,8 +100073,8 @@ async function loadIdMapping(baseDir) {
 * commands run in parallel.
 *
 * The merge is safe because ID mappings are append-only — entries are never
-* intentionally removed. Even if the lock acquisition fails (degraded mode),
-* the read-merge-write provides a fallback that preserves entries from other writers.
+* 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);
@@ -100247,6 +100287,43 @@ function mergeIdMappings(local, remote) {
 	}
 	return merged;
 }
+/**
+* Resolve merge conflicts in ids.yml content by extracting both sides and merging.
+*
+* ids.yml is a sorted key-value YAML map where entries are append-only.
+* The most common merge conflict is both sides adding non-overlapping keys,
+* which is trivially auto-resolvable by keeping all entries from both sides.
+*
+* @param content - Raw file content that may contain git merge conflict markers
+* @returns Merged IdMapping with entries from both sides
+*/
+function resolveIdMappingConflicts(content) {
+	if (!hasMergeConflictMarkers(content)) return parseIdMappingFromYaml(content);
+	const lines = content.split("\n");
+	const oursLines = [];
+	const theirsLines = [];
+	let inConflict = "none";
+	for (const line of lines) {
+		if (line.startsWith("<<<<<<< ")) {
+			inConflict = "ours";
+			continue;
+		}
+		if (line === "=======" && inConflict === "ours") {
+			inConflict = "theirs";
+			continue;
+		}
+		if (line.startsWith(">>>>>>> ") && inConflict === "theirs") {
+			inConflict = "none";
+			continue;
+		}
+		if (inConflict === "none") {
+			oursLines.push(line);
+			theirsLines.push(line);
+		} else if (inConflict === "ours") oursLines.push(line);
+		else theirsLines.push(line);
+	}
+	return mergeIdMappings(parseIdMappingFromYaml(oursLines.join("\n")), parseIdMappingFromYaml(theirsLines.join("\n")));
+}
 
 //#endregion
 //#region src/lib/priority.ts
@@ -101017,10 +101094,7 @@ function matchesSpecPath(storedPath, queryPath) {
 	if (!normalizedStored || !normalizedQuery) return false;
 	if (normalizedStored === normalizedQuery) return true;
 	if (normalizedStored.endsWith("/" + normalizedQuery)) return true;
-	const storedFilename = basename(normalizedStored);
-	const queryFilename = basename(normalizedQuery);
-	if (!normalizedQuery.includes("/") && storedFilename === normalizedQuery) return true;
-	if (!normalizedQuery.includes("/") && storedFilename === queryFilename) return true;
+	if (!normalizedQuery.includes("/") && basename(normalizedStored) === normalizedQuery) return true;
 	return false;
 }
 /**
@@ -102365,7 +102439,7 @@ async function fetchWithGhFallback(url, options) {
 * See: docs/project/specs/active/plan-2026-01-26-configurable-doc-cache-sync.md
 */
 /** Prefix for internal bundled doc sources */
-const INTERNAL_PREFIX = "internal:";
+const INTERNAL_SOURCE_PREFIX = "internal:";
 /**
 * Syncs documentation files from configured sources.
 *
@@ -102398,7 +102472,7 @@ var DocSync = class {
 	* // => { type: 'url', location: 'https://...' }
 	*/
 	parseSource(source) {
-		if (source.startsWith(INTERNAL_PREFIX)) return {
+		if (source.startsWith(INTERNAL_SOURCE_PREFIX)) return {
 			type: "internal",
 			location: source.slice(9)
 		};
@@ -102577,7 +102651,7 @@ async function generateDefaultDocCacheConfig() {
 			const entries = await readdir(fullDir, { withFileTypes: true });
 			for (const entry of entries) if (entry.isFile() && entry.name.endsWith(".md")) {
 				const relativePath = `${prefix}/${entry.name}`;
-				config[relativePath] = `${INTERNAL_PREFIX}${relativePath}`;
+				config[relativePath] = `${INTERNAL_SOURCE_PREFIX}${relativePath}`;
 			}
 		} catch {}
 	}
@@ -102614,8 +102688,6 @@ function isDocsStale(lastSyncAt, autoSyncHours) {
 	const lastSync = new Date(lastSyncAt).getTime();
 	return (Date.now() - lastSync) / (1e3 * 60 * 60) >= autoSyncHours;
 }
-/** Prefix for internal bundled doc sources */
-const INTERNAL_SOURCE_PREFIX = "internal:";
 /**
 * Check if an internal bundled doc exists.
 *
@@ -103440,6 +103512,19 @@ var SyncHandler = class extends BaseCommand {
 			} catch {
 				this.output.debug("Remote sync branch does not exist yet");
 			}
+			{
+				const { access, writeFile } = await import("node:fs/promises");
+				const attrPath = join(this.dataSyncDir, "mappings", ".gitattributes");
+				try {
+					await access(attrPath);
+				} catch {
+					await writeFile(attrPath, "ids.yml merge=union\n");
+					await git("-C", worktreePath, "add", attrPath);
+					try {
+						await git("-C", worktreePath, "commit", "--no-verify", "-m", "chore: add merge=union for ids.yml");
+					} catch {}
+				}
+			}
 			if (behindCommits > 0) {
 				let headBeforeMerge = "";
 				try {
@@ -103484,7 +103569,8 @@ var SyncHandler = class extends BaseCommand {
 						const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
 						if (remoteIdsContent) {
 							conflictRemoteMapping = parseIdMappingFromYaml(remoteIdsContent);
-							const localMapping = await loadIdMapping(this.dataSyncDir);
+							const { readFile } = await import("node:fs/promises");
+							const localMapping = resolveIdMappingConflicts(await readFile(join(this.dataSyncDir, "mappings", "ids.yml"), "utf-8"));
 							const mergedMapping = mergeIdMappings(localMapping, conflictRemoteMapping);
 							await saveIdMapping(this.dataSyncDir, mergedMapping);
 							this.output.debug(`Merged ID mappings: ${localMapping.shortToUlid.size} local + ${conflictRemoteMapping.shortToUlid.size} remote = ${mergedMapping.shortToUlid.size} total`);
@@ -104600,14 +104686,22 @@ var DoctorHandler = class extends BaseCommand {
 		healthChecks.push(await this.checkIssuesDirectory());
 		healthChecks.push(this.checkOrphanedDependencies(this.issues));
 		healthChecks.push(this.checkDuplicateIds(this.issues));
+		healthChecks.push(await this.checkIdMappingConflicts(options.fix));
 		healthChecks.push(await this.checkIdMappingDuplicates(options.fix));
 		healthChecks.push(await this.checkTempFiles(options.fix));
 		healthChecks.push(this.checkIssueValidity(this.issues));
+		healthChecks.push(await this.checkWorktree(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.checkWorktree(options.fix));
-		healthChecks.push(await this.checkDataLocation(options.fix));
 		healthChecks.push(await this.checkLocalSyncBranch());
 		healthChecks.push(await this.checkRemoteSyncBranch());
 		healthChecks.push(await this.checkLocalVsRemoteData());
@@ -104805,6 +104899,58 @@ var DoctorHandler = class extends BaseCommand {
 		};
 	}
 	/**
+	* Check 5b: Merge conflict markers in ids.yml.
+	*
+	* After a failed git merge during sync, ids.yml may retain unresolved
+	* conflict markers (<<<<<<< / ======= / >>>>>>>). This blocks all tbd
+	* commands since YAML parsing throws MergeConflictError.
+	*
+	* For ids.yml, both sides are simple key-value pairs that are append-only,
+	* so the resolution is trivial: keep all entries from both sides.
+	*
+	* With --fix, extracts both sides, merges them, and re-saves.
+	*/
+	async checkIdMappingConflicts(fix) {
+		const mappingPath = join(this.dataSyncDir, "mappings", "ids.yml");
+		let content;
+		try {
+			content = await readFile(mappingPath, "utf-8");
+		} catch {
+			return {
+				name: "ID mapping conflicts",
+				status: "ok"
+			};
+		}
+		const { hasMergeConflictMarkers } = await Promise.resolve().then(() => yaml_utils_exports);
+		if (!hasMergeConflictMarkers(content)) return {
+			name: "ID mapping conflicts",
+			status: "ok"
+		};
+		if (fix && !this.checkDryRun("Resolve merge conflicts in ids.yml")) try {
+			const { resolveIdMappingConflicts, saveIdMapping } = await Promise.resolve().then(() => id_mapping_exports);
+			const resolved = resolveIdMappingConflicts(content);
+			await saveIdMapping(this.dataSyncDir, resolved);
+			return {
+				name: "ID mapping conflicts",
+				status: "ok",
+				message: `resolved merge conflicts (${resolved.shortToUlid.size} entries)`
+			};
+		} catch (error) {
+			return {
+				name: "ID mapping conflicts",
+				status: "error",
+				message: `failed to resolve conflicts: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+		return {
+			name: "ID mapping conflicts",
+			status: "error",
+			message: "ids.yml contains unresolved merge conflict markers",
+			fixable: true,
+			suggestion: "Run: tbd doctor --fix to auto-resolve"
+		};
+	}
+	/**
 	* Check for duplicate keys in the ID mapping file (ids.yml).
 	*
 	* After a git merge conflict resolution that keeps entries from both sides,