get-tbd 0.1.9 → 0.1.11

package/README.md

@@ -94,7 +94,7 @@ status or context or knowledge and know what to do next:
 | What you say | What happens | What runs |
 | --- | --- | --- |
 | "Let's plan a new feature that …" | Agent creates a spec from a template | `tbd shortcut new-plan-spec` |
-| "Break this spec into beads" | Agent creates implementation beads from the spec | `tbd shortcut new-implementation-beads-from-spec` |
+| "Break this spec into beads" | Agent creates implementation beads from the spec | `tbd shortcut plan-implementation-with-beads` |
 | "Implement these beads" | Agent works through beads systematically | `tbd shortcut implement-beads` |
 | "Create a bead for the bug where …" | Agent creates and tracks a bead | `tbd create "..." --type=bug` |
 | "Let's work on current beads" | Agent finds ready beads and starts working | `tbd ready` |
@@ -340,7 +340,7 @@ tbd template --add=<url> --name=<name>
 | `new-research-brief` | Create a research document |
 | `new-architecture-doc` | Create an architecture document |
 | `new-validation-plan` | Create a test/validation plan |
-| `new-implementation-beads-from-spec` | Break a spec into implementation beads |
+| `plan-implementation-with-beads` | Break a spec into implementation beads |
 | `implement-beads` | Implement beads from a spec |
 | `precommit-process` | Pre-commit review and testing |
 | `commit-code` | Commit with pre-commit checks |
@@ -386,7 +386,7 @@ For non-trivial features, tbd supports a full spec-driven workflow:
 
 1. **Plan**: Create a planning spec (`tbd shortcut new-plan-spec`)
 2. **Break down**: Convert spec into implementation beads
-   (`tbd shortcut new-implementation-beads-from-spec`)
+   (`tbd shortcut plan-implementation-with-beads`)
 3. **Implement**: Work through beads systematically (`tbd shortcut implement-beads`)
 4. **Validate**: Create validation plan, run tests (`tbd shortcut new-validation-plan`)
 5. **Ship**: Commit, create PR (`tbd shortcut create-or-update-pr-with-validation-plan`)

package/dist/bin.mjs

@@ -13576,7 +13576,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.9";
+const VERSION$1 = "0.1.11";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -98364,6 +98364,26 @@ async function repairWorktree(baseDir, status, remote = "origin", syncBranch = S
 	}
 }
 /**
+* Ensure worktree is attached to sync branch, not detached HEAD.
+* Old tbd versions (pre-v0.1.9) created worktrees with --detach flag.
+* This repairs them automatically.
+*
+* @param worktreePath - Path to the worktree directory
+* @returns true if worktree was detached and repaired, false if already attached
+*/
+async function ensureWorktreeAttached(worktreePath) {
+	try {
+		if (!await git("-C", worktreePath, "branch", "--show-current").catch(() => "")) {
+			await git("-C", worktreePath, "checkout", SYNC_BRANCH);
+			return true;
+		}
+		return false;
+	} catch (error) {
+		console.warn("Warning: Could not check worktree HEAD status:", error);
+		return false;
+	}
+}
+/**
 * Migrate data from wrong location (.tbd/data-sync/) to worktree.
 *
 * Used when data was incorrectly written to the direct path instead of the worktree.
@@ -98383,6 +98403,7 @@ async function migrateDataToWorktree(baseDir, removeSource = false) {
 	const correctPath = join(baseDir, WORKTREE_DIR, TBD_DIR, DATA_SYNC_DIR_NAME);
 	const worktreePath = join(baseDir, WORKTREE_DIR);
 	try {
+		await ensureWorktreeAttached(worktreePath);
 		const wrongIssuesPath = join(wrongPath, "issues");
 		const wrongMappingsPath = join(wrongPath, "mappings");
 		let issueFiles = [];
@@ -101152,6 +101173,7 @@ var SyncHandler = class extends BaseCommand {
 	async commitWorktreeChanges() {
 		const worktreePath = join(this.tbdRoot, WORKTREE_DIR);
 		try {
+			await ensureWorktreeAttached(worktreePath);
 			const status = await git("-C", worktreePath, "status", "--porcelain");
 			if (!status || status.trim() === "") return emptyTallies();
 			const tallies = parseGitStatus(status);
@@ -101492,6 +101514,158 @@ const searchCommand = new Command("search").description("Search issues by text")
 	await new SearchHandler(command).run(query, options);
 });
 
+//#endregion
+//#region src/cli/lib/sections.ts
+/**
+* Render the REPOSITORY section.
+*
+* Used by: status, doctor
+*
+* Shows:
+* - tbd version
+* - Repository path
+* - Initialization status
+* - Git repository status and branch
+* - Git version (with support warning if needed)
+*
+* @param data - Repository data to render
+* @param colors - Color functions
+* @param options - Rendering options
+*/
+function renderRepositorySection(data, colors, options) {
+	if (options?.showHeading) console.log(colors.bold(formatHeading("Repository")));
+	console.log(`${colors.bold("tbd")} v${data.version}`);
+	console.log(`Repository: ${data.workingDirectory}`);
+	if (data.initialized) console.log(`  ${colors.success(ICONS.SUCCESS)} Initialized (.tbd/)`);
+	else console.log(`  ${colors.error(ICONS.ERROR)} Not initialized`);
+	if (data.gitRepository) {
+		const branchInfo = data.gitBranch ? ` (${data.gitBranch})` : "";
+		console.log(`  ${colors.success(ICONS.SUCCESS)} Git repository${branchInfo}`);
+		if (data.gitVersion) {
+			const versionIcon = data.gitVersionSupported ? colors.success(ICONS.SUCCESS) : colors.warn(ICONS.WARN);
+			const versionNote = data.gitVersionSupported ? "" : ` ${colors.dim(`(requires ${MIN_GIT_VERSION}+)`)}`;
+			console.log(`  ${versionIcon} Git ${data.gitVersion}${versionNote}`);
+		}
+	} else console.log(`  ${colors.error(ICONS.ERROR)} Git repository not found`);
+}
+/**
+* Render the CONFIG section (sync branch, remote, prefix).
+*
+* Used by: status, doctor
+*
+* Shows key-value pairs with dim keys.
+*
+* @param data - Config data to render
+* @param colors - Color functions
+*/
+function renderConfigSection(data, colors) {
+	if (!data.syncBranch && !data.remote && !data.displayPrefix) return;
+	console.log("");
+	if (data.syncBranch) console.log(`${colors.dim("Sync branch:")} ${data.syncBranch}`);
+	if (data.remote) console.log(`${colors.dim("Remote:")} ${data.remote}`);
+	if (data.displayPrefix) console.log(`${colors.dim("ID prefix:")} ${data.displayPrefix}-`);
+}
+/**
+* Render the INTEGRATIONS section.
+*
+* Used by: status, doctor
+*
+* Shows diagnostic lines for each integration check.
+*
+* @param checks - Array of integration checks
+* @param colors - Color functions
+* @returns Whether any integrations are missing (for follow-up suggestions)
+*/
+function renderIntegrationsSection(checks, colors) {
+	console.log("");
+	console.log(colors.bold(formatHeading("Integrations")));
+	let hasMissing = false;
+	for (const check of checks) {
+		const icon = check.installed ? colors.success(ICONS.SUCCESS) : colors.dim(ICONS.ERROR);
+		const pathDim = colors.dim(`(${check.path})`);
+		console.log(`  ${icon} ${check.name} ${pathDim}`);
+		if (!check.installed) hasMissing = true;
+	}
+	return hasMissing;
+}
+/**
+* Render the STATISTICS section.
+*
+* Used by: stats, doctor
+*
+* Shows aligned statistic block with labels and values.
+*
+* @param data - Statistics data to render
+* @param colors - Color functions
+* @param options - Rendering options
+*/
+function renderStatisticsSection(data, colors, options) {
+	if (options?.showHeading !== false) {
+		console.log("");
+		console.log(colors.bold(formatHeading("Statistics")));
+	}
+	const maxLabelLen = Math.max(...[
+		"Ready",
+		"In progress",
+		"Blocked",
+		"Open",
+		"Total"
+	].map((l) => l.length));
+	const formatLine = (label, value) => {
+		return `  ${label}:${" ".repeat(maxLabelLen - label.length + 1)}${value}`;
+	};
+	console.log(formatLine("Ready", data.ready));
+	console.log(formatLine("In progress", data.inProgress));
+	console.log(formatLine("Blocked", data.blocked));
+	console.log(formatLine("Open", data.open));
+	console.log(formatLine("Total", data.total));
+}
+/**
+* Render a warning block about beads coexistence.
+*
+* Used by: status
+*
+* @param colors - Color functions
+*/
+function renderBeadsWarning(colors) {
+	console.log("");
+	console.log(`${colors.warn(ICONS.WARN)} Beads directory detected alongside tbd`);
+	console.log("This may cause confusion for AI agents.");
+	console.log(`Run ${colors.bold("tbd setup beads --disable")} for migration options`);
+}
+/**
+* Render worktree status line.
+*
+* Used by: status
+*
+* @param path - Worktree path
+* @param healthy - Whether worktree is healthy
+* @param colors - Color functions
+*/
+function renderWorktreeStatus(path, healthy, colors) {
+	console.log("");
+	if (healthy) console.log(`${colors.dim("Worktree:")} ${path} (healthy)`);
+	else {
+		console.log(`${colors.warn("Worktree:")} ${path} (${colors.error("unhealthy")})`);
+		console.log("  Run: tbd doctor --fix");
+	}
+}
+/**
+* Render footer with command suggestions.
+*
+* Used by: status, doctor, stats
+*
+* @param suggestions - Array of {command, description} pairs
+* @param colors - Color functions
+*/
+function renderFooter(suggestions, colors) {
+	console.log("");
+	if (suggestions.length === 0) return;
+	const parts = suggestions.map((s) => `${colors.bold(`'${s.command}'`)} for ${s.description}`);
+	if (parts.length === 1) console.log(`Use ${parts[0]}.`);
+	else console.log(`Use ${parts.join(", ")}.`);
+}
+
 //#endregion
 //#region src/cli/commands/status.ts
 /**
@@ -101628,82 +101802,72 @@ var StatusHandler = class extends BaseCommand {
 	renderText(data) {
 		const colors = this.output.getColors();
 		if (!data.initialized) {
-			console.log(`${colors.warn("Not a tbd repository.")}`);
-			console.log("");
-			console.log("Detected:");
-			if (data.git_repository) {
-				const branchInfo = data.git_branch ? ` (${data.git_branch} branch)` : "";
-				console.log(`  ${colors.success("✓")} Git repository${branchInfo}`);
-				if (data.git_version) {
-					const versionStatus = data.git_version_supported ? colors.success("✓") : colors.warn("⚠");
-					const versionNote = data.git_version_supported ? "" : ` ${colors.dim(`(requires ${MIN_GIT_VERSION}+)`)}`;
-					console.log(`  ${versionStatus} Git ${data.git_version}${versionNote}`);
-				}
-			} else console.log(`  ${colors.error("✗")} Git repository not found`);
-			if (data.beads_detected) {
-				const countInfo = data.beads_issue_count !== null ? ` (.beads/ with ${data.beads_issue_count} issues)` : "";
-				console.log(`  ${colors.success("✓")} Beads repository${countInfo}`);
-			} else console.log(`  ${colors.dim("✗")} Beads not detected`);
-			console.log(`  ${colors.error("✗")} tbd not initialized`);
-			console.log("");
-			console.log("To get started:");
-			if (data.beads_detected) console.log(`  ${colors.bold("tbd setup --auto")}          # Migrate from Beads (recommended)`);
-			else console.log(`  ${colors.bold("tbd setup --auto --prefix=<name>")}   # Full setup with prefix`);
-			console.log(`  ${colors.bold("tbd init --prefix=X")}       # Surgical init only`);
+			this.renderPreInitText(data, colors);
 			return;
 		}
-		console.log(`${colors.bold("tbd")} v${data.tbd_version}`);
+		renderRepositorySection({
+			version: data.tbd_version,
+			workingDirectory: data.working_directory,
+			initialized: data.initialized,
+			gitRepository: data.git_repository,
+			gitBranch: data.git_branch,
+			gitVersion: data.git_version,
+			gitVersionSupported: data.git_version_supported
+		}, colors);
+		if (data.beads_detected) renderBeadsWarning(colors);
+		renderConfigSection({
+			syncBranch: data.sync_branch,
+			remote: data.remote,
+			displayPrefix: data.display_prefix
+		}, colors);
+		if (renderIntegrationsSection([{
+			name: "Claude Code hooks",
+			installed: data.integrations.claude_code,
+			path: data.integrations.claude_code_path
+		}, {
+			name: "Codex AGENTS.md",
+			installed: data.integrations.codex,
+			path: data.integrations.codex_path
+		}], colors)) {
+			console.log("");
+			console.log(`Run ${colors.bold("tbd setup auto")} to configure detected agents`);
+		}
+		if (data.worktree_healthy !== null && data.worktree_path) renderWorktreeStatus(data.worktree_path, data.worktree_healthy, colors);
+		renderFooter([{
+			command: "tbd stats",
+			description: "issue statistics"
+		}, {
+			command: "tbd doctor",
+			description: "health checks"
+		}], colors);
+	}
+	/**
+	* Render pre-init text (unique to status command).
+	* This is not shared with doctor since doctor requires initialization.
+	*/
+	renderPreInitText(data, colors) {
+		console.log(`${colors.warn("Not a tbd repository.")}`);
 		console.log("");
-		console.log(`Repository: ${data.working_directory}`);
-		console.log(`  ${colors.success("✓")} Initialized (.tbd/)`);
+		console.log("Detected:");
 		if (data.git_repository) {
-			const branchInfo = data.git_branch ? ` (${data.git_branch})` : "";
-			console.log(`  ${colors.success("✓")} Git repository${branchInfo}`);
+			const branchInfo = data.git_branch ? ` (${data.git_branch} branch)` : "";
+			console.log(`  ${colors.success(ICONS.SUCCESS)} Git repository${branchInfo}`);
 			if (data.git_version) {
-				const versionStatus = data.git_version_supported ? colors.success("✓") : colors.warn("⚠");
+				const versionStatus = data.git_version_supported ? colors.success(ICONS.SUCCESS) : colors.warn(ICONS.WARN);
 				const versionNote = data.git_version_supported ? "" : ` ${colors.dim(`(requires ${MIN_GIT_VERSION}+)`)}`;
 				console.log(`  ${versionStatus} Git ${data.git_version}${versionNote}`);
 			}
-		}
+		} else console.log(`  ${colors.error(ICONS.ERROR)} Git repository not found`);
 		if (data.beads_detected) {
-			console.log("");
-			console.log(`${colors.warn("⚠")}  Beads directory detected alongside tbd`);
-			console.log(`   This may cause confusion for AI agents.`);
-			console.log(`   Run ${colors.bold("tbd setup beads --disable")} for migration options`);
-		}
-		if (data.sync_branch || data.remote || data.display_prefix) {
-			console.log("");
-			if (data.sync_branch) console.log(`${colors.dim("Sync branch:")} ${data.sync_branch}`);
-			if (data.remote) console.log(`${colors.dim("Remote:")} ${data.remote}`);
-			if (data.display_prefix) console.log(`${colors.dim("ID prefix:")} ${data.display_prefix}-`);
-		}
+			const countInfo = data.beads_issue_count !== null ? ` (.beads/ with ${data.beads_issue_count} issues)` : "";
+			console.log(`  ${colors.success(ICONS.SUCCESS)} Beads repository${countInfo}`);
+		} else console.log(`  ${colors.dim(ICONS.ERROR)} Beads not detected`);
+		console.log(`  ${colors.error(ICONS.ERROR)} tbd not initialized`);
 		console.log("");
-		console.log(colors.bold(formatHeading("Integrations")));
-		let hasMissingIntegrations = false;
-		if (data.integrations.claude_code) console.log(`  ${colors.success("✓")} Claude Code hooks ${colors.dim(`(${data.integrations.claude_code_path})`)}`);
-		else {
-			console.log(`  ${colors.dim("✗")} Claude Code hooks ${colors.dim(`(${data.integrations.claude_code_path})`)}`);
-			hasMissingIntegrations = true;
-		}
-		if (data.integrations.codex) console.log(`  ${colors.success("✓")} Codex AGENTS.md ${colors.dim(`(${data.integrations.codex_path})`)}`);
-		else {
-			console.log(`  ${colors.dim("✗")} Codex AGENTS.md ${colors.dim(`(${data.integrations.codex_path})`)}`);
-			hasMissingIntegrations = true;
-		}
-		if (hasMissingIntegrations) {
-			console.log("");
-			console.log(`Run ${colors.bold("tbd setup auto")} to configure detected agents`);
-		}
-		if (data.worktree_healthy !== null) {
-			console.log("");
-			if (data.worktree_healthy) console.log(`${colors.dim("Worktree:")} ${data.worktree_path} (healthy)`);
-			else {
-				console.log(`${colors.warn("Worktree:")} ${data.worktree_path} (${colors.error("unhealthy")})`);
-				console.log(`  Run: tbd doctor --fix`);
-			}
-		}
-		console.log("");
-		console.log(`Use ${colors.bold("'tbd stats'")} for issue statistics, ${colors.bold("'tbd doctor'")} for health checks.`);
+		console.log("To get started:");
+		if (data.beads_detected) console.log(`  ${colors.bold("tbd setup --auto")}          # Migrate from Beads (recommended)`);
+		else console.log(`  ${colors.bold("tbd setup --auto --prefix=<name>")}   # Full setup with prefix`);
+		console.log(`  ${colors.bold("tbd init --prefix=X")}       # Surgical init only`);
 	}
 };
 const statusCommand = new Command("status").description("Show repository status and orientation").action(async (_options, command) => {
@@ -101770,14 +101934,21 @@ var StatsHandler = class extends BaseCommand {
 		this.output.data(stats, () => {
 			const colors = this.output.getColors();
 			console.log(colors.bold("Summary:"));
-			console.log(`  Ready:       ${stats.ready}`);
-			console.log(`  In progress: ${stats.byStatus.in_progress}`);
-			console.log(`  Blocked:     ${stats.blocked}`);
-			console.log(`  Open:        ${stats.byStatus.open}`);
-			console.log(`  Total:       ${stats.total}`);
+			renderStatisticsSection({
+				ready: stats.ready,
+				inProgress: stats.byStatus.in_progress,
+				blocked: stats.blocked,
+				open: stats.byStatus.open,
+				total: stats.total
+			}, colors, { showHeading: false });
 			if (stats.total === 0) {
-				console.log("");
-				console.log(`Use ${colors.bold("'tbd status'")} for setup info, ${colors.bold("'tbd doctor'")} for health checks.`);
+				renderFooter([{
+					command: "tbd status",
+					description: "setup info"
+				}, {
+					command: "tbd doctor",
+					description: "health checks"
+				}], colors);
 				return;
 			}
 			console.log("");
@@ -101799,8 +101970,13 @@ var StatsHandler = class extends BaseCommand {
 				const count = stats.byPriority[i];
 				if (count !== void 0 && count > 0) console.log(`  ${formatPriority(i)} (${priorityLabels[i].padEnd(8)}) ${count}`);
 			}
-			console.log("");
-			console.log(`Use ${colors.bold("'tbd status'")} for setup info, ${colors.bold("'tbd doctor'")} for health checks.`);
+			renderFooter([{
+				command: "tbd status",
+				description: "setup info"
+			}, {
+				command: "tbd doctor",
+				description: "health checks"
+			}], colors);
 		});
 	}
 };
@@ -101908,24 +102084,21 @@ var DoctorHandler = class extends BaseCommand {
 			healthy: allOk
 		}, () => {
 			const colors = this.output.getColors();
-			console.log(colors.bold(formatHeading("Repository")));
-			console.log(`tbd v${VERSION}`);
-			console.log(`Repository: ${this.cwd}`);
-			console.log(`  ${colors.success("✓")} Initialized (.tbd/)`);
-			if (statusInfo.gitBranch) console.log(`  ${colors.success("✓")} Git repository (${statusInfo.gitBranch})`);
-			if (this.config) {
-				console.log("");
-				console.log(`${colors.dim("Sync branch:")} ${this.config.sync.branch}`);
-				console.log(`${colors.dim("Remote:")} ${this.config.sync.remote}`);
-				if (this.config.display.id_prefix) console.log(`${colors.dim("ID prefix:")} ${this.config.display.id_prefix}-`);
-			}
-			console.log("");
-			console.log(colors.bold(formatHeading("Statistics")));
-			console.log(`  Ready:       ${statsInfo.ready}`);
-			console.log(`  In progress: ${statsInfo.inProgress}`);
-			console.log(`  Blocked:     ${statsInfo.blocked}`);
-			console.log(`  Open:        ${statsInfo.open}`);
-			console.log(`  Total:       ${statsInfo.total}`);
+			renderRepositorySection({
+				version: VERSION,
+				workingDirectory: this.cwd,
+				initialized: true,
+				gitRepository: !!statusInfo.gitBranch,
+				gitBranch: statusInfo.gitBranch,
+				gitVersion: null,
+				gitVersionSupported: true
+			}, colors, { showHeading: true });
+			if (this.config) renderConfigSection({
+				syncBranch: this.config.sync.branch,
+				remote: this.config.sync.remote,
+				displayPrefix: this.config.display.id_prefix
+			}, colors);
+			renderStatisticsSection(statsInfo, colors);
 			console.log("");
 			console.log(colors.bold(formatHeading("Integrations")));
 			renderDiagnostics(integrationChecks, colors);
@@ -105731,8 +105904,18 @@ const TBD_SESSION_SCRIPT = `#!/bin/bash
 # Installed by: tbd setup --auto
 # This script runs on SessionStart and PreCompact
 
+# Get npm global bin directory (if npm is available)
+NPM_GLOBAL_BIN=""
+if command -v npm &> /dev/null; then
+    NPM_PREFIX=$(npm config get prefix 2>/dev/null)
+    if [ -n "$NPM_PREFIX" ] && [ -d "$NPM_PREFIX/bin" ]; then
+        NPM_GLOBAL_BIN="$NPM_PREFIX/bin"
+    fi
+fi
+
 # Add common binary locations to PATH (persists for entire script)
-export PATH="$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
+# Include npm global bin if found
+export PATH="$NPM_GLOBAL_BIN:$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
 
 # Function to ensure tbd is available
 ensure_tbd() {
@@ -105775,9 +105958,9 @@ ensure_tbd() {
     else
         echo "[tbd] WARNING: tbd installed but not found in PATH"
         echo "[tbd] Checking common locations..."
-        # Try to find and add to path
-        for dir in ~/.local/bin ~/.local/node_modules/.bin /usr/local/bin; do
-            if [ -x "$dir/tbd" ]; then
+        # Try to find and add to path (include npm global bin)
+        for dir in "$NPM_GLOBAL_BIN" ~/.local/bin ~/.local/node_modules/.bin /usr/local/bin; do
+            if [ -n "$dir" ] && [ -x "$dir/tbd" ]; then
                 export PATH="$dir:$PATH"
                 echo "[tbd] Found at $dir/tbd"
                 return 0