get-tbd 0.1.18 → 0.1.20

package/dist/bin.mjs

@@ -13576,6 +13576,12 @@ const YAML_STRINGIFY_OPTIONS_COMPACT = {
 * ~50 lines is slightly more than one terminal screen.
 */
 const PAGINATION_LINE_THRESHOLD = 50;
+/**
+* Maximum lines to display when showing parent bead context in `tbd show`.
+* The parent's full serialized output is truncated to this many lines,
+* with an ellipsis and omitted-line count appended if exceeded.
+*/
+const PARENT_CONTEXT_MAX_LINES = 50;
 
 //#endregion
 //#region src/utils/yaml-utils.ts
@@ -13878,7 +13884,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.18";
+const VERSION$1 = "0.1.20";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -97286,17 +97292,15 @@ async function writeFileAsync(filePath, data, options = DEFAULT_WRITE_OPTIONS) {
 *
 * On main/dev branches:
 *   .tbd/
-*     config.yml              - Project configuration (tracked)
-*     state.yml               - Local state (gitignored)
-*     .gitignore              - Ignores docs/, data-sync-worktree/, data-sync/
-*     docs/                   - Installed documentation (gitignored, regenerated on setup)
-*     data-sync-worktree/     - Hidden worktree checkout of tbd-sync branch
-*       .tbd/
-*         data-sync/
-*           issues/
-*           mappings/
-*           attic/
-*           meta.yml
+*     Committed to the repo:
+*       config.yml            - Project configuration
+*       .gitignore            - Controls what's gitignored below
+*       workspaces/           - Persistent state (outbox, named workspaces)
+*     Gitignored (local only):
+*       state.yml             - Local state
+*       docs/                 - Installed documentation (regenerated on setup)
+*       data-sync-worktree/   - Hidden worktree checkout of tbd-sync branch
+*         .tbd/data-sync/     - issues/, mappings/, attic/, meta.yml
 *
 * On tbd-sync branch:
 *   .tbd/
@@ -97444,14 +97448,14 @@ let _resolvedAllowFallback = null;
 * 1. Worktree path if worktree exists: .tbd/data-sync-worktree/.tbd/data-sync/
 * 2. Direct path as fallback (only if allowFallback: true)
 *
-* @param baseDir - The base directory of the repository (default: process.cwd())
+* @param baseDir - The tbd root directory (from requireInit or findTbdRoot)
 * @param options - Options for path resolution
 * @returns Resolved data sync directory path
 * @throws WorktreeMissingError if worktree missing and allowFallback is false
 *
 * See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md
 */
-async function resolveDataSyncDir(baseDir = process.cwd(), options) {
+async function resolveDataSyncDir(baseDir, options) {
 	const allowFallback = options?.allowFallback ?? true;
 	if (_resolvedDataSyncDir && _resolvedBaseDir === baseDir && _resolvedAllowFallback === allowFallback) return _resolvedDataSyncDir;
 	const worktreePath = join(baseDir, DATA_SYNC_DIR_VIA_WORKTREE);
@@ -97474,7 +97478,7 @@ async function resolveDataSyncDir(baseDir = process.cwd(), options) {
 /**
 * Resolve attic directory path.
 */
-async function resolveAtticDir(baseDir = process.cwd(), options) {
+async function resolveAtticDir(baseDir, options) {
 	return join(await resolveDataSyncDir(baseDir, options), "attic");
 }
 /**
@@ -97807,13 +97811,17 @@ async function writeConfig(baseDir, config) {
 	await writeFile(configPath, content);
 }
 /**
-* Check if tbd is initialized in the given directory (immediate check only).
-* Returns true if .tbd/ directory exists directly in baseDir.
+* Check if tbd is properly initialized in the given directory.
+* Returns true only if .tbd/config.yml exists (not just a .tbd/ directory).
+*
+* This prevents spurious .tbd/ directories (e.g., containing only state.yml
+* created by a bug) from being mistaken for tbd roots. A valid tbd root
+* always has config.yml created during `tbd init`.
 */
 async function hasTbdDir(dir) {
-	const tbdDir = join(dir, ".tbd");
+	const configPath = join(dir, CONFIG_FILE);
 	try {
-		await access(tbdDir);
+		await access(configPath);
 		return true;
 	} catch {
 		return false;
@@ -97858,11 +97866,20 @@ async function readLocalState(baseDir) {
 }
 /**
 * Write local state to .tbd/state.yml
+*
+* Uses `atomically` for safe writes (atomic rename, auto parent-dir creation).
+* However, we intentionally guard against .tbd/ not existing: `atomically`
+* would auto-create it, which is wrong if baseDir is a subdirectory rather
+* than the true tbd root. Only `tbd init` (via initConfig) should create .tbd/.
 */
 async function writeLocalState(baseDir, state) {
-	const statePath = join(baseDir, STATE_FILE);
-	await mkdir(join(baseDir, ".tbd"), { recursive: true });
-	await writeFile(statePath, stringifyYaml(state, { lineWidth: 0 }));
+	const tbdDir = join(baseDir, ".tbd");
+	try {
+		await access(tbdDir);
+	} catch {
+		throw new Error(`Cannot write state: .tbd/ directory does not exist at ${baseDir}. Run 'tbd init' first or ensure the correct tbd root is being used.`);
+	}
+	await writeFile(join(baseDir, STATE_FILE), stringifyYaml(state, { lineWidth: 0 }));
 }
 /**
 * Update specific fields in local state (merge with existing).
@@ -99137,7 +99154,10 @@ Example:
 				"",
 				"# Temporary files",
 				"*.tmp",
-				"*.temp"
+				"*.temp",
+				"",
+				"# workspaces/ stores state (including outbox) committed to the working branch",
+				"!workspaces/"
 			]);
 			this.output.debug(`Created ${TBD_DIR}/.gitignore`);
 			await mkdir(join(cwd, TBD_SHORTCUTS_SYSTEM), { recursive: true });
@@ -100789,6 +100809,45 @@ const listCommand = new Command("list").description("List issues").option("--sta
 *
 * See: tbd-design.md §4.4 Show
 */
+/**
+* Render a serialized issue with colorized output, optionally truncated.
+*
+* @param issue - The issue to render
+* @param colors - Color functions
+* @param maxLines - If set, truncate output to this many lines with an omission notice
+* @returns Array of formatted lines
+*/
+function renderIssueLines(issue, colors) {
+	const serialized = serializeIssue(issue);
+	const output = [];
+	for (const line of serialized.split("\n")) if (line === "---") output.push(colors.dim(line));
+	else if (line.startsWith("id:")) output.push(`${colors.dim("id:")} ${colors.id(line.slice(4))}`);
+	else if (line.startsWith("status:")) {
+		const status = line.slice(8).trim();
+		const statusColor = getStatusColor(status, colors);
+		output.push(`${colors.dim("status:")} ${statusColor(status)}`);
+	} else if (line.startsWith("priority:")) {
+		const priority = parseInt(line.slice(10).trim(), 10);
+		const priorityColor = getPriorityColor(priority, colors);
+		output.push(`${colors.dim("priority:")} ${priorityColor(formatPriority(priority))}`);
+	} else if (line.startsWith("title:")) output.push(`${colors.dim("title:")} ${colors.bold(line.slice(7))}`);
+	else if (line.startsWith("spec_path:")) output.push(`${colors.dim("spec_path:")} ${colors.id(line.slice(11))}`);
+	else if (line.startsWith("## Notes")) output.push(colors.bold(line));
+	else if (line.startsWith("  - ")) output.push(`  - ${colors.label(line.slice(4))}`);
+	else output.push(line);
+	return output;
+}
+/**
+* Print lines with optional max-lines truncation.
+* If maxLines is set and the output exceeds it, truncates and appends an omission notice.
+*/
+function printWithTruncation(lines, colors, maxLines) {
+	if (maxLines && lines.length > maxLines) {
+		const omitted = lines.length - maxLines;
+		for (const line of lines.slice(0, maxLines)) console.log(line);
+		console.log(colors.dim(`… [${omitted} line${omitted === 1 ? "" : "s"} omitted]`));
+	} else for (const line of lines) console.log(line);
+}
 var ShowHandler = class extends BaseCommand {
 	async run(id, command, options) {
 		const ctx = await loadFullContext(command);
@@ -100799,29 +100858,28 @@ var ShowHandler = class extends BaseCommand {
 		} catch {
 			throw new NotFoundError("Issue", id);
 		}
+		let parentIssue;
+		if (issue.parent_id && options.parent !== false) try {
+			parentIssue = await readIssue(ctx.dataSyncDir, issue.parent_id);
+		} catch {}
+		const maxLines = options.maxLines ? parseInt(options.maxLines, 10) : void 0;
 		const displayId = ctx.displayId(issue.id);
 		const displayIssue = {
 			...issue,
-			displayId
+			displayId,
+			...parentIssue ? { parent: {
+				...parentIssue,
+				displayId: ctx.displayId(parentIssue.id)
+			} } : {}
 		};
 		this.output.data(displayIssue, () => {
 			const colors = this.output.getColors();
-			const lines = serializeIssue(issue).split("\n");
-			for (const line of lines) if (line === "---") console.log(colors.dim(line));
-			else if (line.startsWith("id:")) console.log(`${colors.dim("id:")} ${colors.id(line.slice(4))}`);
-			else if (line.startsWith("status:")) {
-				const status = line.slice(8).trim();
-				const statusColor = getStatusColor(status, colors);
-				console.log(`${colors.dim("status:")} ${statusColor(status)}`);
-			} else if (line.startsWith("priority:")) {
-				const priority = parseInt(line.slice(10).trim(), 10);
-				const priorityColor = getPriorityColor(priority, colors);
-				console.log(`${colors.dim("priority:")} ${priorityColor(formatPriority(priority))}`);
-			} else if (line.startsWith("title:")) console.log(`${colors.dim("title:")} ${colors.bold(line.slice(7))}`);
-			else if (line.startsWith("spec_path:")) console.log(`${colors.dim("spec_path:")} ${colors.id(line.slice(11))}`);
-			else if (line.startsWith("## Notes")) console.log(colors.bold(line));
-			else if (line.startsWith("  - ")) console.log(`  - ${colors.label(line.slice(4))}`);
-			else console.log(line);
+			printWithTruncation(renderIssueLines(issue, colors), colors, maxLines);
+			if (parentIssue) {
+				console.log("");
+				console.log(colors.dim("The parent of this bead is:"));
+				printWithTruncation(renderIssueLines(parentIssue, colors), colors, PARENT_CONTEXT_MAX_LINES);
+			}
 			if (options.showOrder) {
 				console.log("");
 				console.log(colors.dim("child_order_hints:"));
@@ -100834,7 +100892,7 @@ var ShowHandler = class extends BaseCommand {
 		});
 	}
 };
-const showCommand = new Command("show").description("Show issue details").argument("<id>", "Issue ID").option("--show-order", "Display children ordering hints").action(async (id, options, command) => {
+const showCommand = new Command("show").description("Show issue details").argument("<id>", "Issue ID").option("--show-order", "Display children ordering hints").option("--no-parent", "Suppress automatic parent context display").option("--max-lines <n>", "Truncate output to N lines").action(async (id, options, command) => {
 	await new ShowHandler(command).run(id, command, options);
 });
 
@@ -103165,6 +103223,8 @@ var SyncHandler = class extends BaseCommand {
 				console.log("    1. Commit:  git add .tbd/workspaces && git commit -m 'tbd: save outbox'");
 				console.log("    2. Push your working branch:  git push");
 				console.log("    3. Run 'tbd sync' when push access is available");
+				console.log("");
+				console.log("  WARNING: Do NOT add .tbd/workspaces/ to .gitignore -- that would cause data loss.");
 			} else {
 				const totalInOutbox = existingOutboxCount + result.saved;
 				if (existingOutboxCount > 0) {
@@ -103180,6 +103240,8 @@ var SyncHandler = class extends BaseCommand {
 				console.log("    2. Push your working branch:  git push");
 				console.log("    3. Run 'tbd sync' when push access is available");
 				console.log("       (outbox will be imported automatically on successful sync)");
+				console.log("");
+				console.log("  WARNING: Do NOT add .tbd/workspaces/ to .gitignore -- that would cause data loss.");
 			}
 		} catch (saveError) {
 			const saveErrorMsg = saveError instanceof Error ? saveError.message : String(saveError);
@@ -103295,44 +103357,17 @@ function formatTimestampAgo(timestamp) {
 * See: tbd-design.md §4.8 Search Commands
 */
 const STALE_THRESHOLD_MS = 300 * 1e3;
-/**
-* Read local state file.
-*/
-async function readState() {
-	try {
-		return (0, import_dist$2.parse)(await readFile(STATE_FILE, "utf-8"));
-	} catch {
-		return {};
-	}
-}
-/**
-* Update local state file.
-*/
-async function updateState(updates) {
-	await writeFile(STATE_FILE, stringifyYaml({
-		...await readState(),
-		...updates
-	}));
-}
-/**
-* Check if worktree is stale and needs refresh.
-*/
-async function isWorktreeStale() {
-	const state = await readState();
-	if (!state.last_sync_at) return true;
-	const lastSync = new Date(state.last_sync_at).getTime();
-	return Date.now() - lastSync > STALE_THRESHOLD_MS;
-}
 var SearchHandler = class extends BaseCommand {
 	async run(query, options) {
 		const tbdRoot = await requireInit();
 		if (!options.noRefresh) {
-			const state = await readState();
-			if (await isWorktreeStale()) {
+			const state = await readLocalState(tbdRoot);
+			const lastSync = state.last_sync_at ? new Date(state.last_sync_at).getTime() : 0;
+			if (Date.now() - lastSync > STALE_THRESHOLD_MS) {
 				const lastSyncAgo = formatTimestampAgo(state.last_sync_at);
 				const staleInfo = lastSyncAgo ? ` (last synced ${lastSyncAgo})` : "";
 				this.output.info(`Refreshing worktree${staleInfo}...`);
-				await updateState({ last_sync_at: now() });
+				await updateLocalState(tbdRoot, { last_sync_at: now() });
 			}
 		}
 		let issues;
@@ -103961,10 +103996,10 @@ const PRIORITY_LABELS = [
 ];
 var StatsHandler = class extends BaseCommand {
 	async run() {
-		await requireInit();
+		const tbdRoot = await requireInit();
 		let issues;
 		try {
-			issues = await listIssues(await resolveDataSyncDir());
+			issues = await listIssues(await resolveDataSyncDir(tbdRoot));
 		} catch {
 			throw new NotInitializedError("No issue store found. Run `tbd init` first.");
 		}
@@ -104909,10 +104944,10 @@ const doctorCommand = new Command("doctor").description("Diagnose and repair rep
 */
 var ConfigShowHandler = class extends BaseCommand {
 	async run() {
-		await requireInit();
+		const tbdRoot = await requireInit();
 		let config;
 		try {
-			config = await readConfig(".");
+			config = await readConfig(tbdRoot);
 		} catch {
 			throw new NotInitializedError("No configuration found. Run `tbd init` first.");
 		}
@@ -104931,10 +104966,10 @@ var ConfigShowHandler = class extends BaseCommand {
 };
 var ConfigSetHandler = class extends BaseCommand {
 	async run(key, value) {
-		await requireInit();
+		const tbdRoot = await requireInit();
 		let config;
 		try {
-			config = await readConfig(".");
+			config = await readConfig(tbdRoot);
 		} catch {
 			throw new NotInitializedError("No configuration found. Run `tbd init` first.");
 		}
@@ -104950,7 +104985,7 @@ var ConfigSetHandler = class extends BaseCommand {
 			throw new ValidationError(`Invalid key: ${key}`);
 		}
 		await this.execute(async () => {
-			await writeConfig(".", config);
+			await writeConfig(tbdRoot, config);
 		}, "Failed to write config");
 		this.output.success(`Set ${key} = ${value}`);
 	}
@@ -104975,10 +105010,10 @@ var ConfigSetHandler = class extends BaseCommand {
 };
 var ConfigGetHandler = class extends BaseCommand {
 	async run(key) {
-		await requireInit();
+		const tbdRoot = await requireInit();
 		let config;
 		try {
-			config = await readConfig(".");
+			config = await readConfig(tbdRoot);
 		} catch {
 			throw new NotInitializedError("No configuration found. Run `tbd init` first.");
 		}
@@ -105030,8 +105065,8 @@ function parseAtticFilename(filename) {
 /**
 * List all attic entries.
 */
-async function listAtticEntries(filterById) {
-	const atticPath = await resolveAtticDir();
+async function listAtticEntries(tbdRoot, filterById) {
+	const atticPath = await resolveAtticDir(tbdRoot);
 	let files;
 	try {
 		files = await readdir(atticPath);
@@ -105057,7 +105092,7 @@ async function listAtticEntries(filterById) {
 var AtticListHandler = class extends BaseCommand {
 	async run(id) {
 		const tbdRoot = await requireInit();
-		const entries = await listAtticEntries(id ? normalizeIssueId(id) : void 0);
+		const entries = await listAtticEntries(tbdRoot, id ? normalizeIssueId(id) : void 0);
 		const mapping = await loadIdMapping(await resolveDataSyncDir(tbdRoot));
 		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
 		const showDebug = this.ctx.debug;
@@ -105084,7 +105119,7 @@ var AtticListHandler = class extends BaseCommand {
 var AtticShowHandler = class extends BaseCommand {
 	async run(id, timestamp) {
 		const tbdRoot = await requireInit();
-		const entry = (await listAtticEntries(normalizeIssueId(id))).find((e) => e.timestamp === timestamp || e.timestamp.replace(/:/g, "-") === timestamp);
+		const entry = (await listAtticEntries(tbdRoot, normalizeIssueId(id))).find((e) => e.timestamp === timestamp || e.timestamp.replace(/:/g, "-") === timestamp);
 		if (!entry) throw new NotFoundError("Attic entry", `${id} at ${timestamp}`);
 		const mapping = await loadIdMapping(await resolveDataSyncDir(tbdRoot));
 		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
@@ -105114,7 +105149,7 @@ var AtticRestoreHandler = class extends BaseCommand {
 	async run(id, timestamp) {
 		const tbdRoot = await requireInit();
 		const normalizedId = normalizeIssueId(id);
-		const entry = (await listAtticEntries(normalizedId)).find((e) => e.timestamp === timestamp || e.timestamp.replace(/:/g, "-") === timestamp);
+		const entry = (await listAtticEntries(tbdRoot, normalizedId)).find((e) => e.timestamp === timestamp || e.timestamp.replace(/:/g, "-") === timestamp);
 		if (!entry) throw new NotFoundError("Attic entry", `${id} at ${timestamp}`);
 		if (this.checkDryRun("Would restore from attic", {
 			id: normalizedId,
@@ -105991,27 +106026,26 @@ const readmeCommand = new Command("readme").description("Display the README (sam
 var UninstallHandler = class extends BaseCommand {
 	async run(options) {
 		const colors = this.output.getColors();
-		try {
-			await access(".tbd");
-		} catch {
-			throw new NotInitializedError("No .tbd directory found. Nothing to uninstall.");
-		}
+		const tbdRoot = await findTbdRoot(process.cwd());
+		if (!tbdRoot) throw new NotInitializedError("No .tbd directory found. Nothing to uninstall.");
 		let config;
 		try {
-			config = await readConfig(".");
+			config = await readConfig(tbdRoot);
 		} catch {
 			config = null;
 		}
 		const syncBranch = config?.sync.branch ?? SYNC_BRANCH;
 		const remote = config?.sync.remote ?? "origin";
-		const worktreePath = join(".tbd", "data-sync-worktree");
+		const tbdDir = join(tbdRoot, ".tbd");
+		const worktreePath = join(tbdDir, "data-sync-worktree");
+		const displayPath = (p) => relative(process.cwd(), p) || p;
 		const items = [];
 		let worktreeExists = false;
 		try {
 			await access(worktreePath);
 			worktreeExists = true;
 			const worktreeStats = await this.getDirectoryStats(worktreePath);
-			items.push(`  - Worktree: ${worktreePath} (${worktreeStats.files} files)`);
+			items.push(`  - Worktree: ${displayPath(worktreePath)} (${worktreeStats.files} files)`);
 		} catch {}
 		let localBranchExists = false;
 		try {
@@ -106039,8 +106073,8 @@ var UninstallHandler = class extends BaseCommand {
 			remoteBranchExists = true;
 			items.push(`  - Remote branch: ${remote}/${syncBranch}`);
 		} catch {}
-		const tbdStats = await this.getDirectoryStats(".tbd");
-		items.push(`  - Directory: .tbd/ (${tbdStats.files} files)`);
+		const tbdStats = await this.getDirectoryStats(tbdDir);
+		items.push(`  - Directory: ${displayPath(tbdDir)}/ (${tbdStats.files} files)`);
 		console.log(colors.bold("The following will be removed:"));
 		console.log("");
 		for (const item of items) console.log(colors.warn(item));
@@ -106113,7 +106147,7 @@ var UninstallHandler = class extends BaseCommand {
 			});
 		} catch {}
 		try {
-			await rm(".tbd", {
+			await rm(tbdDir, {
 				recursive: true,
 				force: true
 			});
@@ -107381,7 +107415,7 @@ function inferGuidelineCategory(name) {
 	if (name.startsWith("typescript-")) return "typescript";
 	if (name.startsWith("python-")) return "python";
 	if (name.includes("tdd") || name.includes("testing") || name.includes("golden")) return "testing";
-	if (name.startsWith("general-") || name.includes("rules") || name.includes("patterns") || name.startsWith("backward-") || name.startsWith("convex-") || name.startsWith("release-")) return "general";
+	if (name.startsWith("general-") || name.includes("rules") || name.includes("patterns") || name.startsWith("backward-") || name.startsWith("convex-") || name.startsWith("release-") || name.startsWith("writing-")) return "general";
 }
 var GuidelinesHandler = class extends DocCommandHandler {
 	constructor(command) {
@@ -108285,7 +108319,10 @@ var SetupDefaultHandler = class extends BaseCommand {
 			"",
 			"# Temporary files",
 			"*.tmp",
-			"*.temp"
+			"*.temp",
+			"",
+			"# workspaces/ stores state (including outbox) committed to the working branch",
+			"!workspaces/"
 		]);
 		if (tbdGitignoreResult.created) console.log(`  ${colors.success("✓")} Created .tbd/.gitignore`);
 		else if (tbdGitignoreResult.added.length > 0) console.log(`  ${colors.success("✓")} Updated .tbd/.gitignore with new patterns`);
@@ -108412,7 +108449,10 @@ Example:
 			"",
 			"# Temporary files",
 			"*.tmp",
-			"*.temp"
+			"*.temp",
+			"",
+			"# workspaces/ stores state (including outbox) committed to the working branch",
+			"!workspaces/"
 		]);
 		if (tbdGitignoreResult.created) console.log(`  ${colors.success("✓")} Created .tbd/.gitignore`);
 		else if (tbdGitignoreResult.added.length > 0) console.log(`  ${colors.success("✓")} Updated .tbd/.gitignore`);