xtrm-tools 2.4.2 → 2.4.4

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "main": "./dist/index.js",
   "type": "module",

package/config/pi/extensions/beads.ts

@@ -78,7 +78,7 @@ export default function (pi: ExtensionAPI) {
 					if (inProgress) {
 						return {
 							block: true,
-							reason: `Active claim [${claim}] — close it first.\n  bd close ${claim}\n  git push -u origin <feature-branch>\n  gh pr create --fill && gh pr merge --squash\n`,
+							reason: `Active claim [${claim}] — close it first.\n  bd close ${claim}\n  (Pi workflow) publish/merge are external steps; do not rely on xtrm finish.\n`,
 						};
 					}
 				}

package/config/pi/extensions/core/guard-rules.ts

@@ -16,6 +16,7 @@ export const PI_MUTATING_FILE_TOOLS = [
 ];
 
 export const SAFE_BASH_PREFIXES = [
+	// Git read-only
 	"git status",
 	"git log",
 	"git diff",
@@ -30,10 +31,41 @@ export const SAFE_BASH_PREFIXES = [
 	"git worktree",
 	"git checkout -b",
 	"git switch -c",
+	// Tools
 	"gh",
 	"bd",
-	"touch .beads/",
 	"npx gitnexus",
+	"xtrm finish",
+	// Read-only filesystem
+	"cat",
+	"ls",
+	"head",
+	"tail",
+	"pwd",
+	"which",
+	"type",
+	"env",
+	"printenv",
+	"find",
+	"grep",
+	"rg",
+	"fd",
+	"wc",
+	"sort",
+	"uniq",
+	"cut",
+	"awk",
+	"jq",
+	"yq",
+	"bat",
+	"less",
+	"more",
+	"file",
+	"stat",
+	"du",
+	"tree",
+	// Allowed writes (specific paths)
+	"touch .beads/",
 ];
 
 export const DANGEROUS_BASH_PATTERNS = [
@@ -67,4 +99,4 @@ export const DANGEROUS_BASH_PATTERNS = [
 	"(?:^|\\s)python\\s+-c\\b",
 	"(?:^|\\s)perl\\s+-e\\b",
 	"(?:^|\\s)ruby\\s+-e\\b",
-];
+];

package/config/pi/extensions/custom-footer.ts

@@ -132,14 +132,14 @@ export default function (pi: ExtensionAPI) {
 					const modelId = ctx.model?.id || "no-model";
 					const modelChip = chip(modelId);
 
-					const sep = theme.fg("dim", " | ");
+					const sep = " ";
 
 					const brandModel = `${brand} ${modelChip}`;
-					const leftParts = [brandModel, usageStr, cwdStr];
-					
 					const beadChip = buildBeadChip();
-					const branchWithChip = branchStr ? `${branchStr} ${beadChip}`.trim() : beadChip;
-					if (branchWithChip) leftParts.push(branchWithChip);
+					const leftParts = [brandModel, usageStr];
+					if (beadChip) leftParts.push(beadChip);
+					leftParts.push(cwdStr);
+					if (branchStr) leftParts.push(branchStr);
 
 					const left = leftParts.join(sep);
 					return [truncateToWidth(left, width)];

package/config/pi/extensions/plan-mode/index.ts

@@ -16,7 +16,17 @@ import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import type { AssistantMessage, TextContent } from "@mariozechner/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { Key } from "@mariozechner/pi-tui";
-import { extractTodoItems, isSafeCommand, markCompletedSteps, type TodoItem } from "./utils.js";
+import {
+	extractTodoItems,
+	isSafeCommand,
+	markCompletedSteps,
+	type TodoItem,
+	getShortId,
+	isBeadsProject,
+	deriveEpicTitle,
+	createPlanIssues,
+	bdClaim,
+} from "./utils.js";
 
 // Tools
 const PLAN_MODE_TOOLS = ["read", "bash", "grep", "find", "ls", "questionnaire"];
@@ -39,6 +49,8 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 	let planModeEnabled = false;
 	let executionMode = false;
 	let todoItems: TodoItem[] = [];
+	let epicId: string | null = null;
+	let issueIds: Map<number, string> = new Map(); // step -> issue ID
 
 	pi.registerFlag("plan", {
 		description: "Start in plan mode (read-only exploration)",
@@ -57,15 +69,17 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 			ctx.ui.setStatus("plan-mode", undefined);
 		}
 
-		// Widget showing todo list
+		// Widget showing todo list with bd issue IDs
 		if (executionMode && todoItems.length > 0) {
 			const lines = todoItems.map((item) => {
+				const issueId = issueIds.get(item.step);
+				const idLabel = issueId ? `[${getShortId(issueId)}] ` : "";
 				if (item.completed) {
 					return (
-						ctx.ui.theme.fg("success", "☑ ") + ctx.ui.theme.fg("muted", ctx.ui.theme.strikethrough(item.text))
+						ctx.ui.theme.fg("success", "☑ ") + ctx.ui.theme.fg("muted", ctx.ui.theme.strikethrough(`${idLabel}${item.text}`))
 					);
 				}
-				return `${ctx.ui.theme.fg("muted", "☐ ")}${item.text}`;
+				return `${ctx.ui.theme.fg("muted", "☐ ")}${idLabel}${item.text}`;
 			});
 			ctx.ui.setWidget("plan-todos", lines);
 		} else {
@@ -77,6 +91,8 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		planModeEnabled = !planModeEnabled;
 		executionMode = false;
 		todoItems = [];
+		epicId = null;
+		issueIds.clear();
 
 		if (planModeEnabled) {
 			pi.setActiveTools(PLAN_MODE_TOOLS);
@@ -93,6 +109,8 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 			enabled: planModeEnabled,
 			todos: todoItems,
 			executing: executionMode,
+			epicId,
+			issueIds: Object.fromEntries(issueIds),
 		});
 	}
 
@@ -108,7 +126,11 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 				ctx.ui.notify("No todos. Create a plan first with /plan", "info");
 				return;
 			}
-			const list = todoItems.map((item, i) => `${i + 1}. ${item.completed ? "✓" : "○"} ${item.text}`).join("\n");
+			const list = todoItems.map((item, i) => {
+				const issueId = issueIds.get(item.step);
+				const idLabel = issueId ? `[${getShortId(issueId)}] ` : "";
+				return `${i + 1}. ${item.completed ? "✓" : "○"} ${idLabel}${item.text}`;
+			}).join("\n");
 			ctx.ui.notify(`Plan Progress:\n${list}`, "info");
 		},
 	});
@@ -187,7 +209,11 @@ Do NOT attempt to make changes - just describe what you would do.`,
 
 		if (executionMode && todoItems.length > 0) {
 			const remaining = todoItems.filter((t) => !t.completed);
-			const todoList = remaining.map((t) => `${t.step}. ${t.text}`).join("\n");
+			const todoList = remaining.map((t) => {
+				const issueId = issueIds.get(t.step);
+				const idLabel = issueId ? `[${getShortId(issueId)}] ` : "";
+				return `${t.step}. ${idLabel}${t.text}`;
+			}).join("\n");
 			return {
 				message: {
 					customType: "plan-execution-context",
@@ -221,13 +247,19 @@ After completing a step, include a [DONE:n] tag in your response.`,
 		// Check if execution is complete
 		if (executionMode && todoItems.length > 0) {
 			if (todoItems.every((t) => t.completed)) {
-				const completedList = todoItems.map((t) => `~~${t.text}~~`).join("\n");
+				const completedList = todoItems.map((t) => {
+					const issueId = issueIds.get(t.step);
+					const idLabel = issueId ? `[${getShortId(issueId)}] ` : "";
+					return `~~${idLabel}${t.text}~~`;
+				}).join("\n");
 				pi.sendMessage(
 					{ customType: "plan-complete", content: `**Plan Complete!** ✓\n\n${completedList}`, display: true },
 					{ triggerTurn: false },
 				);
 				executionMode = false;
 				todoItems = [];
+				epicId = null;
+				issueIds.clear();
 				pi.setActiveTools(NORMAL_MODE_TOOLS);
 				updateStatus(ctx);
 				persistState(); // Save cleared state so resume doesn't restore old execution mode
@@ -246,31 +278,72 @@ After completing a step, include a [DONE:n] tag in your response.`,
 			}
 		}
 
-		// Show plan steps and prompt for next action
+		// Auto-create epic + issues if in a beads project
+		const cwd = ctx.cwd || process.cwd();
+		if (todoItems.length > 0 && isBeadsProject(cwd) && !epicId) {
+			// Derive epic title from user prompt or first step
+			const epicTitle = deriveEpicTitle(event.messages);
+			
+			ctx.ui.notify("Creating epic and issues in bd...", "info");
+			const result = await createPlanIssues(epicTitle, todoItems, cwd);
+			
+			if (result) {
+				epicId = result.epic.id;
+				for (const issue of result.issues) {
+					// Match issue to todo by title similarity
+					const matchingTodo = todoItems.find(t => 
+						issue.title.toLowerCase().includes(t.text.toLowerCase().slice(0, 30)) ||
+						t.text.toLowerCase().includes(issue.title.toLowerCase().slice(0, 30))
+					);
+					if (matchingTodo) {
+						issueIds.set(matchingTodo.step, issue.id);
+					}
+				}
+				ctx.ui.notify(`Created epic ${getShortId(epicId)} with ${result.issues.length} issues`, "info");
+			}
+		}
+
+		// Show plan steps with bd issue IDs
 		if (todoItems.length > 0) {
-			const todoListText = todoItems.map((t, i) => `${i + 1}. ☐ ${t.text}`).join("\n");
+			const todoListText = todoItems.map((t, i) => {
+				const issueId = issueIds.get(t.step);
+				const idLabel = issueId ? `[${getShortId(issueId)}] ` : "";
+				return `${i + 1}. ☐ ${idLabel}${t.text}`;
+			}).join("\n");
+			
+			const epicLabel = epicId ? `\n\nEpic: ${getShortId(epicId)}` : "";
 			pi.sendMessage(
 				{
 					customType: "plan-todo-list",
-					content: `**Plan Steps (${todoItems.length}):**\n\n${todoListText}`,
+					content: `**Plan Steps (${todoItems.length}):**${epicLabel}\n\n${todoListText}`,
 					display: true,
 				},
 				{ triggerTurn: false },
 			);
 		}
 
-		const choice = await ctx.ui.select("Plan mode - what next?", [
-			todoItems.length > 0 ? "Execute the plan (track progress)" : "Execute the plan",
+		// Show "Start implementation?" prompt (no approval dialog for issue creation)
+		const choice = await ctx.ui.select("Start implementation?", [
+			todoItems.length > 0 ? "Yes, start with first step" : "Yes",
 			"Stay in plan mode",
 			"Refine the plan",
 		]);
 
-		if (choice?.startsWith("Execute")) {
+		if (choice?.startsWith("Yes")) {
+			// Auto-exit plan mode and start execution
 			planModeEnabled = false;
 			executionMode = todoItems.length > 0;
 			pi.setActiveTools(NORMAL_MODE_TOOLS);
 			updateStatus(ctx);
 
+			// Auto-claim first issue if available
+			if (todoItems.length > 0 && issueIds.size > 0) {
+				const firstIssueId = issueIds.get(todoItems[0].step);
+				if (firstIssueId) {
+					await bdClaim(firstIssueId, cwd);
+				}
+			}
+
 			const execMessage =
 				todoItems.length > 0
 					? `Execute the plan. Start with: ${todoItems[0].text}`
@@ -298,12 +371,16 @@ After completing a step, include a [DONE:n] tag in your response.`,
 		// Restore persisted state
 		const planModeEntry = entries
 			.filter((e: { type: string; customType?: string }) => e.type === "custom" && e.customType === "plan-mode")
-			.pop() as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean } } | undefined;
+			.pop() as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean; epicId?: string; issueIds?: Record<number, string> } } | undefined;
 
 		if (planModeEntry?.data) {
 			planModeEnabled = planModeEntry.data.enabled ?? planModeEnabled;
 			todoItems = planModeEntry.data.todos ?? todoItems;
 			executionMode = planModeEntry.data.executing ?? executionMode;
+			epicId = planModeEntry.data.epicId ?? null;
+			if (planModeEntry.data.issueIds) {
+				issueIds = new Map(Object.entries(planModeEntry.data.issueIds).map(([k, v]) => [Number(k), v]));
+			}
 		}
 
 		// On resume: re-scan messages to rebuild completion state

package/config/pi/extensions/plan-mode/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@xtrm/pi-plan-mode",
+  "version": "1.0.0",
+  "description": "Plan mode extension for Pi - read-only exploration with plan extraction and bd integration",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": ["pi", "extension", "plan-mode", "xtrm"],
+  "author": "xtrm",
+  "license": "MIT"
+}

package/config/pi/extensions/plan-mode/utils.ts

@@ -3,6 +3,10 @@
  * Extracted for testability.
  */
 
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
 // Destructive commands blocked in plan mode
 const DESTRUCTIVE_PATTERNS = [
 	/\brm\b/i,
@@ -134,7 +138,8 @@ export function extractTodoItems(message: string): TodoItem[] {
 	const planSection = message.slice(message.indexOf(headerMatch[0]) + headerMatch[0].length);
 	const numberedPattern = /^\s*(\d+)[.)]\s+\*{0,2}([^*\n]+)/gm;
 
-	for (const match of planSection.matchAll(numberedPattern)) {
+	const matches = Array.from(planSection.matchAll(numberedPattern));
+	for (const match of matches) {
 		const text = match[2]
 			.trim()
 			.replace(/\*{1,2}$/, "")
@@ -151,7 +156,8 @@ export function extractTodoItems(message: string): TodoItem[] {
 
 export function extractDoneSteps(message: string): number[] {
 	const steps: number[] = [];
-	for (const match of message.matchAll(/\[DONE:(\d+)\]/gi)) {
+	const matches = Array.from(message.matchAll(/\[DONE:(\d+)\]/gi));
+	for (const match of matches) {
 		const step = Number(match[1]);
 		if (Number.isFinite(step)) steps.push(step);
 	}
@@ -166,3 +172,153 @@ export function markCompletedSteps(text: string, items: TodoItem[]): number {
 	}
 	return doneSteps.length;
 }
+
+// =============================================================================
+// bd (beads) Integration Functions
+// =============================================================================
+
+/**
+ * Extract short ID from full bd issue ID.
+ * Example: "jaggers-agent-tools-xr9b.1" → "xr9b.1"
+ */
+export function getShortId(fullId: string): string {
+	const parts = fullId.split("-");
+	// Last part is the ID (e.g., "xr9b.1")
+	return parts[parts.length - 1];
+}
+
+/**
+ * Check if a directory is a beads project (has .beads directory).
+ */
+export function isBeadsProject(cwd: string): boolean {
+	return existsSync(join(cwd, ".beads"));
+}
+
+/**
+ * Derive epic title from user prompt or conversation messages.
+ */
+export function deriveEpicTitle(messages: Array<{ role: string; content?: unknown }>): string {
+	// Find the last user message
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "user") {
+			const content = msg.content;
+			if (typeof content === "string") {
+				// Extract first sentence or first 50 chars
+				const firstSentence = content.split(/[.!?\n]/)[0].trim();
+				if (firstSentence.length > 10 && firstSentence.length < 80) {
+					return firstSentence;
+				}
+				if (firstSentence.length >= 80) {
+					return `${firstSentence.slice(0, 77)}...`;
+				}
+			}
+		}
+	}
+	return "Plan execution";
+}
+
+/**
+ * Run a bd command and return the result.
+ */
+function runBd(args: string[], cwd: string): { stdout: string; stderr: string; status: number } {
+	const result = spawnSync("bd", args, {
+		cwd,
+		encoding: "utf8",
+		timeout: 30000,
+	});
+	return {
+		stdout: result.stdout || "",
+		stderr: result.stderr || "",
+		status: result.status ?? 1,
+	};
+}
+
+/**
+ * Create an epic in bd.
+ */
+export function bdCreateEpic(title: string, cwd: string): { id: string; title: string } | null {
+	const result = runBd(["create", title, "-t", "epic", "-p", "1", "--json"], cwd);
+	if (result.status === 0) {
+		try {
+			const data = JSON.parse(result.stdout);
+			if (Array.isArray(data) && data[0]) {
+				return { id: data[0].id, title: data[0].title };
+			}
+		} catch {
+			// Parse the ID from stdout if JSON parse fails
+			const match = result.stdout.match(/Created issue:\s*(\S+)/);
+			if (match) {
+				return { id: match[1], title };
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Create a task issue in bd under an epic.
+ */
+export function bdCreateIssue(
+	title: string,
+	description: string,
+	parentId: string,
+	cwd: string,
+): { id: string; title: string } | null {
+	const result = runBd(
+		["create", title, "-t", "task", "-p", "1", "--parent", parentId, "-d", description, "--json"],
+		cwd,
+	);
+	if (result.status === 0) {
+		try {
+			const data = JSON.parse(result.stdout);
+			if (Array.isArray(data) && data[0]) {
+				return { id: data[0].id, title: data[0].title };
+			}
+		} catch {
+			const match = result.stdout.match(/Created issue:\s*(\S+)/);
+			if (match) {
+				return { id: match[1], title };
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Claim an issue in bd.
+ */
+export function bdClaim(issueId: string, cwd: string): boolean {
+	const result = runBd(["update", issueId, "--claim"], cwd);
+	return result.status === 0;
+}
+
+/**
+ * Result of creating plan issues.
+ */
+export interface PlanIssuesResult {
+	epic: { id: string; title: string };
+	issues: Array<{ id: string; title: string }>;
+}
+
+/**
+ * Create an epic and issues from todo items.
+ */
+export function createPlanIssues(
+	epicTitle: string,
+	todos: TodoItem[],
+	cwd: string,
+): PlanIssuesResult | null {
+	const epic = bdCreateEpic(epicTitle, cwd);
+	if (!epic) return null;
+
+	const issues: Array<{ id: string; title: string }> = [];
+	for (const todo of todos) {
+		const issue = bdCreateIssue(todo.text, `Step ${todo.step} of plan: ${epicTitle}`, epic.id, cwd);
+		if (issue) {
+			issues.push(issue);
+		}
+	}
+
+	return { epic, issues };
+}

package/config/pi/extensions/session-flow.ts

@@ -84,7 +84,12 @@ export default function (pi: ExtensionAPI) {
 
 		const ensured = await ensureWorktreeSessionState(cwd, issueId);
 		if (ensured.ok) {
-			const text = `\n\n🧭 Session Flow: ${ensured.message}`;
+			const state = readSessionState(cwd);
+			const worktreePath = state?.worktreePath;
+			const nextStep = worktreePath
+				? `\nNext: cd ${worktreePath} && pi  (sandboxed session)`
+				: "";
+			const text = `\n\n🧭 Session Flow: ${ensured.message}${nextStep}`;
 			return { content: [...event.content, { type: "text", text }] };
 		}
 		return undefined;
@@ -99,18 +104,27 @@ export default function (pi: ExtensionAPI) {
 		if (state.phase === "waiting-merge" || state.phase === "pending-cleanup") {
 			const pr = state.prNumber != null ? `#${state.prNumber}` : "(pending PR)";
 			const url = state.prUrl ? ` ${state.prUrl}` : "";
-			pi.sendUserMessage(`🚫 PR ${pr}${url} not yet merged. Run: xtrm finish`);
+			pi.sendUserMessage(
+				`⚠ PR ${pr}${url} is still pending. xtrm finish is deprecated for Pi workflow. ` +
+				"Use xtpi publish (when available) and external merge/cleanup steps.",
+			);
 			return undefined;
 		}
 
 		if (state.phase === "conflicting") {
 			const files = state.conflictFiles?.length ? state.conflictFiles.join(", ") : "unknown files";
-			pi.sendUserMessage(`🚫 Merge conflicts in: ${files}. Resolve, push, then: xtrm finish`);
+			pi.sendUserMessage(
+				`⚠ Conflicts in: ${files}. xtrm finish is deprecated for Pi workflow. ` +
+				"Resolve conflicts, then continue with publish-only flow.",
+			);
 			return undefined;
 		}
 
 		if (state.phase === "claimed" || state.phase === "phase1-done") {
-			pi.sendUserMessage(`⚠ Session has an active worktree at ${state.worktreePath}. Consider running: xtrm finish`);
+			pi.sendUserMessage(
+				`⚠ Session has an active worktree at ${state.worktreePath}. ` +
+				"Use publish-only workflow (no automatic push/PR/merge).",
+			);
 		}
 		return undefined;
 	});