xtrm-tools 2.1.17 → 2.1.21

package/cli/package.json

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

package/config/pi/extensions/beads.ts

@@ -0,0 +1,185 @@
+import type { ExtensionAPI, ToolCallEvent, ToolResultEvent } from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType, isBashToolResult } from "@mariozechner/pi-coding-agent";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { SubprocessRunner, EventAdapter, Logger } from "./core";
+
+const logger = new Logger({ namespace: "beads" });
+
+export default function (pi: ExtensionAPI) {
+	const getCwd = (ctx: any) => ctx.cwd || process.cwd();
+	const isBeadsProject = (cwd: string) => fs.existsSync(path.join(cwd, ".beads"));
+
+	const getSessionClaim = async (sessionId: string, cwd: string): Promise<string | null> => {
+		const result = await SubprocessRunner.run("bd", ["kv", "get", `claimed:${sessionId}`], { cwd });
+		if (result.code === 0) return result.stdout.trim();
+		return null;
+	};
+
+	const setSessionClaim = async (sessionId: string, issueId: string, cwd: string): Promise<boolean> => {
+		const result = await SubprocessRunner.run("bd", ["kv", "set", `claimed:${sessionId}`, issueId], { cwd });
+		return result.code === 0;
+	};
+
+	const clearSessionClaim = async (sessionId: string, cwd: string): Promise<boolean> => {
+		const result = await SubprocessRunner.run("bd", ["kv", "clear", `claimed:${sessionId}`], { cwd });
+		return result.code === 0;
+	};
+
+	const getInProgressSummary = async (cwd: string): Promise<string | null> => {
+		const result = await SubprocessRunner.run("bd", ["list", "--status=in_progress"], { cwd });
+		if (result.code === 0 && result.stdout.includes("Total:")) {
+			return result.stdout.trim();
+		}
+		return null;
+	};
+
+	const hasTrackableWork = async (cwd: string): Promise<boolean> => {
+		const result = await SubprocessRunner.run("bd", ["list"], { cwd });
+		if (result.code === 0 && result.stdout.includes("Total:")) {
+			const m = result.stdout.match(/Total:\s*\d+\s+issues?\s*\((\d+)\s+open,\s*(\d+)\s+in progress\)/);
+			if (m) {
+				const open = parseInt(m[1], 10);
+				const inProgress = parseInt(m[2], 10);
+				return (open + inProgress) > 0;
+			}
+		}
+		return false;
+	};
+
+	// 0. Register Custom Commands
+	pi.registerCommand({
+		name: "claim",
+		description: "Claim a beads issue for this session",
+		async execute(args, ctx) {
+			const cwd = getCwd(ctx);
+			if (!isBeadsProject(cwd)) {
+				ctx.ui.notify("Not a beads project.", "error");
+				return;
+			}
+
+			const issueId = args[0];
+			if (!issueId) {
+				ctx.ui.notify("Usage: /claim <issue-id>", "warning");
+				return;
+			}
+
+			// Ensure issue is in_progress first
+			await SubprocessRunner.run("bd", ["update", issueId, "--status=in_progress"], { cwd });
+			
+			const ok = await setSessionClaim(ctx.sessionManager.sessionId, issueId, cwd);
+			if (ok) {
+				ctx.ui.notify(`Claimed issue: ${issueId}`, "info");
+			} else {
+				ctx.ui.notify(`Failed to claim issue: ${issueId}`, "error");
+			}
+		}
+	});
+
+	pi.registerCommand({
+		name: "unclaim",
+		description: "Clear the beads issue claim for this session",
+		async execute(_args, ctx) {
+			const cwd = getCwd(ctx);
+			if (!isBeadsProject(cwd)) return;
+
+			const ok = await clearSessionClaim(ctx.sessionManager.sessionId, cwd);
+			if (ok) {
+				ctx.ui.notify("Claim cleared.", "info");
+			}
+		}
+	});
+
+	// 1. Tool Call Interception (Edit Gate & Commit Gate)
+	pi.on("tool_call", async (event, ctx) => {
+		const cwd = getCwd(ctx);
+		if (!isBeadsProject(cwd)) return undefined;
+
+		const sessionId = ctx.sessionManager.sessionId;
+
+		// A. Edit Gate
+		if (EventAdapter.isMutatingFileTool(event)) {
+			const claim = await getSessionClaim(sessionId, cwd);
+			if (claim) return undefined;
+
+			const hasWork = await hasTrackableWork(cwd);
+			if (!hasWork) return undefined;
+
+			const reason = "No active issue claim for this session. Use `/claim <id>` to track your work.";
+			if (ctx.hasUI) {
+				ctx.ui.notify("Beads: Edit blocked. Claim an issue first.", "warning");
+			}
+			return { block: true, reason };
+		}
+
+		// B. Commit Gate
+		if (isToolCallEventType("bash", event)) {
+			const command = event.input.command;
+			if (/\bgit\s+commit\b/.test(command)) {
+				const claim = await getSessionClaim(sessionId, cwd);
+				if (claim) {
+					const inProgress = await getInProgressSummary(cwd);
+					const reason = `Resolve open claim [${claim}] before committing. Use \`bd close ${claim}\` first.\n\n${inProgress || ""}`;
+					if (ctx.hasUI) {
+						ctx.ui.notify("Beads: Commit blocked. Close active claim first.", "warning");
+					}
+					return { block: true, reason };
+				}
+			}
+		}
+
+		return undefined;
+	});
+
+	// 2. Tool Result Interception (Memory Gate)
+	pi.on("tool_result", async (event, ctx) => {
+		const cwd = getCwd(ctx);
+		if (!isBeadsProject(cwd)) return undefined;
+
+		if (isBashToolResult(event)) {
+			const command = event.input.command;
+			// Also clear claim on bd close
+			if (/\bbd\s+close\b/.test(command) && !event.isError) {
+				await clearSessionClaim(ctx.sessionManager.sessionId, cwd);
+
+				const reminder = "\n\n**Beads Insight**: Work completed. Consider if this session produced insights worth persisting via `bd remember`.";
+				const newContent = [...event.content];
+				newContent.push({ type: "text", text: reminder });
+				return { content: newContent };
+			}
+		}
+		return undefined;
+	});
+
+	// 3. Compaction Support
+	pi.on("session_before_compact", async (event, ctx) => {
+		const cwd = getCwd(ctx);
+		if (!isBeadsProject(cwd)) return undefined;
+
+		const sessionId = ctx.sessionManager.sessionId;
+		const claim = await getSessionClaim(sessionId, cwd);
+
+		if (claim) {
+			return {
+				compaction: {
+					summary: (event.compaction?.summary || "") + `\n\nActive Beads Claim: ${claim}`,
+					firstKeptEntryId: event.preparation.firstKeptEntryId,
+				}
+			};
+		}
+		return undefined;
+	});
+
+	// 4. Shutdown Warning
+	pi.on("session_shutdown", async (_event, ctx) => {
+		const cwd = getCwd(ctx);
+		if (!isBeadsProject(cwd)) return;
+
+		const sessionId = ctx.sessionManager.sessionId;
+		const claim = await getSessionClaim(sessionId, cwd);
+
+		if (claim && ctx.hasUI) {
+			ctx.ui.notify(`Warning: Exiting with active Beads claim [${claim}].`, "warning");
+		}
+	});
+}

package/config/pi/extensions/core/adapter.ts

@@ -0,0 +1,45 @@
+import type { ExtensionAPI, ToolCallEvent } from "@mariozechner/pi-coding-agent";
+
+export class EventAdapter {
+	/**
+	 * Checks if the tool event is a mutating file operation (write, edit, etc).
+	 */
+	static isMutatingFileTool(event: ToolCallEvent<any, any>): boolean {
+		const tools = [
+			"write",
+			"edit",
+			"replace_content",
+			"replace_lines",
+			"delete_lines",
+			"insert_at_line",
+			"create_text_file",
+			"rename_symbol",
+			"replace_symbol_body",
+			"insert_after_symbol",
+			"insert_before_symbol",
+		];
+		return tools.includes(event.toolName);
+	}
+
+	/**
+	 * Extracts the target path from a tool input, resolving against the current working directory.
+	 */
+	static extractPathFromToolInput(event: ToolCallEvent<any, any>, cwd: string): string | null {
+		const input = event.input;
+		if (!input) return null;
+
+		const pathRaw = input.path || input.file || input.filePath;
+		if (typeof pathRaw === "string") {
+			return pathRaw; // Usually Pi passes absolute paths anyway or paths relative to root
+		}
+
+		return null;
+	}
+
+	/**
+	 * Safely formats a block reason string to ensure UI readiness.
+	 */
+	static formatBlockReason(prefix: string, details: string): string {
+		return `${prefix}: ${details}`;
+	}
+}

package/config/pi/extensions/core/index.ts

@@ -0,0 +1,3 @@
+export * from "./logger";
+export * from "./runner";
+export * from "./adapter";

package/config/pi/extensions/core/logger.ts

@@ -0,0 +1,45 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LoggerOptions {
+	namespace: string;
+	level?: LogLevel;
+}
+
+export class Logger {
+	private namespace: string;
+	private level: LogLevel;
+
+	constructor(options: LoggerOptions) {
+		this.namespace = options.namespace;
+		this.level = options.level || "info";
+	}
+
+	private shouldLog(level: LogLevel): boolean {
+		const levels: LogLevel[] = ["debug", "info", "warn", "error"];
+		return levels.indexOf(level) >= levels.indexOf(this.level);
+	}
+
+	debug(message: string, ...args: any[]) {
+		if (this.shouldLog("debug")) {
+			console.debug(`[${this.namespace}] DEBUG: ${message}`, ...args);
+		}
+	}
+
+	info(message: string, ...args: any[]) {
+		if (this.shouldLog("info")) {
+			console.info(`[${this.namespace}] INFO: ${message}`, ...args);
+		}
+	}
+
+	warn(message: string, ...args: any[]) {
+		if (this.shouldLog("warn")) {
+			console.warn(`[${this.namespace}] WARN: ${message}`, ...args);
+		}
+	}
+
+	error(message: string, ...args: any[]) {
+		if (this.shouldLog("error")) {
+			console.error(`[${this.namespace}] ERROR: ${message}`, ...args);
+		}
+	}
+}

package/config/pi/extensions/core/runner.ts

@@ -0,0 +1,71 @@
+import { execFile, spawnSync } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface RunOptions {
+	timeoutMs?: number;
+	cwd?: string;
+	env?: Record<string, string>;
+	input?: string; // Standard input
+}
+
+export interface RunResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+export class SubprocessRunner {
+	/**
+	 * Run a command deterministically with a timeout and optional stdin.
+	 */
+	static async run(
+		command: string,
+		args: string[],
+		options: RunOptions = {}
+	): Promise<RunResult> {
+		const timeout = options.timeoutMs ?? 10000;
+		const cwd = options.cwd ?? process.cwd();
+		const env = { ...process.env, ...options.env };
+
+		if (options.input !== undefined) {
+			// Use spawnSync for stdin support if input is provided
+			const result = spawnSync(command, args, {
+				cwd,
+				env,
+				input: options.input,
+				encoding: "utf8",
+				timeout,
+				maxBuffer: 1024 * 1024 * 10,
+			});
+
+			return {
+				code: result.status ?? 1,
+				stdout: (result.stdout ?? "").trim(),
+				stderr: (result.stderr ?? "").trim(),
+			};
+		}
+
+		try {
+			const result = await execFileAsync(command, args, {
+				timeout,
+				cwd,
+				env,
+				maxBuffer: 1024 * 1024 * 10,
+			});
+
+			return {
+				code: 0,
+				stdout: result.stdout.trim(),
+				stderr: result.stderr.trim(),
+			};
+		} catch (error: any) {
+			return {
+				code: error.code ?? 1,
+				stdout: (error.stdout ?? "").trim(),
+				stderr: (error.stderr ?? error.message ?? "").trim(),
+			};
+		}
+	}
+}

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

@@ -1,68 +1,30 @@
 /**
- * Custom Footer Extension — Enhanced status bar
+ * XTRM Custom Footer Extension
  *
- * Displays: in/out/remaining tokens, cost, context%, elapsed, cwd, git branch, model
- * Color-coded context usage: green <50%, yellow 50-75%, red >75%
+ * Displays: XTRM brand, Turn count, Model, Context%, CWD, Git branch
  */
 
-import type { AssistantMessage } from "@mariozechner/pi-ai";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import { truncateToWidth } from "@mariozechner/pi-tui";
 
 export default function (pi: ExtensionAPI) {
-	let sessionStart = Date.now();
-
-	function formatElapsed(ms: number): string {
-		const s = Math.floor(ms / 1000);
-		if (s < 60) return `${s}s`;
-		const m = Math.floor(s / 60);
-		const rs = s % 60;
-		if (m < 60) return `${m}m${rs > 0 ? rs + "s" : ""}`;
-		const h = Math.floor(m / 60);
-		const rm = m % 60;
-		return `${h}h${rm > 0 ? rm + "m" : ""}`;
-	}
-
-	function fmt(n: number): string {
-		if (n < 1000) return `${n}`;
-		return `${(n / 1000).toFixed(1)}k`;
-	}
+	let turnCount = 0;
 
 	pi.on("session_start", async (_event, ctx) => {
-		sessionStart = Date.now();
-
 		ctx.ui.setFooter((tui, theme, footerData) => {
 			const unsub = footerData.onBranchChange(() => tui.requestRender());
-			const timer = setInterval(() => tui.requestRender(), 30000);
-
+			
 			return {
-				dispose() { unsub(); clearInterval(timer); },
+				dispose() { unsub(); },
 				invalidate() {},
 				render(width: number): string[] {
-					let input = 0, output = 0, cost = 0;
-					for (const e of ctx.sessionManager.getBranch()) {
-						if (e.type === "message" && e.message.role === "assistant") {
-							const m = e.message as AssistantMessage;
-							input += m.usage.input;
-							output += m.usage.output;
-							cost += m.usage.cost.total;
-						}
-					}
+					const brand = theme.fg("accent", "XTRM");
+					const turns = theme.fg("dim", `[Turn ${turnCount}]`);
 
 					const usage = ctx.getContextUsage();
-					const ctxWindow = usage?.contextWindow ?? 0;
 					const pct = usage?.percent ?? 0;
-					const remaining = Math.max(0, ctxWindow - (usage?.tokens ?? 0));
-
 					const pctColor = pct > 75 ? "error" : pct > 50 ? "warning" : "success";
-
-					const tokenStats = [
-						theme.fg("accent", `${fmt(input)}/${fmt(output)}`),
-						theme.fg("warning", `$${cost.toFixed(2)}`),
-						theme.fg(pctColor, `${pct.toFixed(0)}%`),
-					].join(" ");
-
-					const elapsed = theme.fg("dim", `⏱${formatElapsed(Date.now() - sessionStart)}`);
+					const usageStr = theme.fg(pctColor, `${pct.toFixed(0)}%`);
 
 					const parts = process.cwd().split("/");
 					const short = parts.length > 2 ? parts.slice(-2).join("/") : process.cwd();
@@ -71,25 +33,29 @@ export default function (pi: ExtensionAPI) {
 					const branch = footerData.getGitBranch();
 					const branchStr = branch ? theme.fg("accent", `⎇ ${branch}`) : "";
 
-					const thinking = pi.getThinkingLevel();
-					const thinkColor = thinking === "high" ? "warning" : thinking === "medium" ? "accent" : thinking === "low" ? "dim" : "muted";
 					const modelId = ctx.model?.id || "no-model";
-					const modelStr = theme.fg(thinkColor, "◆") + " " + theme.fg("accent", modelId);
+					const modelStr = theme.fg("accent", modelId);
 
 					const sep = theme.fg("dim", " | ");
-					const leftParts = [modelStr, tokenStats, elapsed, cwdStr];
+					
+					// Layout: XTRM [Turn 1] | model | 10% | ⌂ dir | ⎇ branch
+					const leftParts = [`${brand} ${turns}`, modelStr, usageStr, cwdStr];
 					if (branchStr) leftParts.push(branchStr);
+					
 					const left = leftParts.join(sep);
-
 					return [truncateToWidth(left, width)];
 				},
 			};
 		});
 	});
 
+	pi.on("turn_start", async () => {
+		turnCount++;
+	});
+
 	pi.on("session_switch", async (event, _ctx) => {
 		if (event.reason === "new") {
-			sessionStart = Date.now();
+			turnCount = 0;
 		}
 	});
 }

package/config/pi/extensions/main-guard-post-push.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI, ToolResultEvent } from "@mariozechner/pi-coding-agent";
+import { isBashToolResult } from "@mariozechner/pi-coding-agent";
+import { SubprocessRunner, Logger } from "./core";
+
+const logger = new Logger({ namespace: "main-guard-post-push" });
+
+export default function (pi: ExtensionAPI) {
+	const getProtectedBranches = (): string[] => {
+		const env = process.env.MAIN_GUARD_PROTECTED_BRANCHES;
+		if (env) return env.split(",").map(b => b.trim()).filter(Boolean);
+		return ["main", "master"];
+	};
+
+	pi.on("tool_result", async (event, ctx) => {
+		const cwd = ctx.cwd || process.cwd();
+		if (!isBashToolResult(event) || event.isError) return undefined;
+
+		const cmd = event.input.command.trim();
+		if (!/\bgit\s+push\b/.test(cmd)) return undefined;
+
+		// Check if we pushed to a protected branch
+		const protectedBranches = getProtectedBranches();
+		const tokens = cmd.split(/\s+/);
+		const lastToken = tokens[tokens.length - 1];
+		if (protectedBranches.some(b => lastToken === b || lastToken.endsWith(`:${b}`))) {
+			return undefined;
+		}
+
+		// Success! Suggest PR workflow
+		const reminder = "\n\n**Main-Guard**: Push successful. Next steps:\n" +
+			"  1. `gh pr create --fill` (if not already open)\n" +
+			"  2. `gh pr merge --squash` (once approved)\n" +
+			"  3. `git checkout main && git reset --hard origin/main` (sync local)";
+
+		const newContent = [...event.content];
+		newContent.push({ type: "text", text: reminder });
+
+		if (ctx.hasUI) {
+			ctx.ui.notify("Main-Guard: Suggesting PR workflow", "info");
+		}
+
+		return { content: newContent };
+	});
+}

package/config/pi/extensions/main-guard.ts

@@ -0,0 +1,126 @@
+import type { ExtensionAPI, ToolCallEvent } from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
+import { SubprocessRunner, EventAdapter, Logger } from "./core";
+
+const logger = new Logger({ namespace: "main-guard" });
+
+export default function (pi: ExtensionAPI) {
+	const getProtectedBranches = (): string[] => {
+		const env = process.env.MAIN_GUARD_PROTECTED_BRANCHES;
+		if (env) return env.split(",").map(b => b.trim()).filter(Boolean);
+		return ["main", "master"];
+	};
+
+	const getCurrentBranch = async (cwd: string): Promise<string | null> => {
+		const result = await SubprocessRunner.run("git", ["branch", "--show-current"], { cwd });
+		if (result.code === 0) return result.stdout;
+		return null;
+	};
+
+	const protectedPaths = [".env", ".git/", "node_modules/"];
+
+	pi.on("tool_call", async (event, ctx) => {
+		const cwd = ctx.cwd || process.cwd();
+		
+		// 1. Safety Check: Protected Paths (Global)
+		if (EventAdapter.isMutatingFileTool(event)) {
+			const path = EventAdapter.extractPathFromToolInput(event, cwd);
+			if (path && protectedPaths.some((p) => path.includes(p))) {
+				const reason = `Path "${path}" is protected. Edits to sensitive system files are restricted.`;
+				if (ctx.hasUI) {
+					ctx.ui.notify(`Safety: Blocked edit to protected path`, "error");
+				}
+				return { block: true, reason };
+			}
+		}
+
+		// 2. Safety Check: Dangerous Commands (Global)
+		if (isToolCallEventType("bash", event)) {
+			const cmd = event.input.command.trim();
+			if (cmd.includes("rm -rf") && !cmd.includes("--help")) {
+				if (ctx.hasUI) {
+					const ok = await ctx.ui.confirm("Dangerous Command", `Allow execution of: ${cmd}?`);
+					if (!ok) return { block: true, reason: "Blocked by user confirmation" };
+				} else {
+					return { block: true, reason: "Dangerous command 'rm -rf' blocked in non-interactive mode" };
+				}
+			}
+		}
+
+		// 3. Main-Guard: Branch Protection
+		const protectedBranches = getProtectedBranches();
+		const branch = await getCurrentBranch(cwd);
+
+		if (branch && protectedBranches.includes(branch)) {
+			// A. Mutating File Tools on Main
+			if (EventAdapter.isMutatingFileTool(event)) {
+				const reason = `On protected branch '${branch}'. Checkout a feature branch first: \`git checkout -b feature/<name>\``;
+				if (ctx.hasUI) {
+					ctx.ui.notify(`Main-Guard: Blocked edit on ${branch}`, "error");
+				}
+				return { block: true, reason };
+			}
+
+			// B. Bash Commands on Main
+			if (isToolCallEventType("bash", event)) {
+				const cmd = event.input.command.trim();
+
+				// Emergency override
+				if (process.env.MAIN_GUARD_ALLOW_BASH === "1") return undefined;
+
+				// Enforce squash-only PR merges
+				if (/^gh\s+pr\s+merge\b/.test(cmd)) {
+					if (!/--squash\b/.test(cmd)) {
+						const reason = "Squash only: use `gh pr merge --squash` (or MAIN_GUARD_ALLOW_BASH=1)";
+						return { block: true, reason };
+					}
+					return undefined;
+				}
+
+				// Safe allowlist
+				const SAFE_BASH_PATTERNS = [
+					/^git\s+(status|log|diff|branch|show|describe|fetch|remote|config)\b/,
+					/^git\s+pull\b/,
+					/^git\s+stash\b/,
+					/^git\s+worktree\b/,
+					/^git\s+checkout\s+-b\s+\S+/,
+					/^git\s+switch\s+-c\s+\S+/,
+					...protectedBranches.map(b => new RegExp(`^git\\s+reset\\s+--hard\\s+origin/${b}\\b`)),
+					/^gh\s+/,
+					/^bd\s+/,
+					/^touch\s+\.beads\//,
+				];
+
+				if (SAFE_BASH_PATTERNS.some(p => p.test(cmd))) {
+					return undefined;
+				}
+
+				// Specific blocks
+				if (/\bgit\s+commit\b/.test(cmd)) {
+					return { block: true, reason: `No commits on '${branch}' — use a feature branch.` };
+				}
+
+				if (/\bgit\s+push\b/.test(cmd)) {
+					const tokens = cmd.split(/\s+/);
+					const lastToken = tokens[tokens.length - 1];
+					const explicitProtected = protectedBranches.some(b => lastToken === b || lastToken.endsWith(`:${b}`));
+					const impliedProtected = tokens.length <= 3 && protectedBranches.includes(branch);
+					
+					if (explicitProtected || impliedProtected) {
+						return { block: true, reason: `No direct push to '${branch}' — push a feature branch and open a PR.` };
+					}
+					return undefined;
+				}
+
+				// Default deny
+				const reason = `Bash restricted on '${branch}'. Allowed: git status/log/diff/pull/stash, gh, bd.\n  Exit: git checkout -b feature/<name>`;
+				if (ctx.hasUI) {
+					ctx.ui.notify("Main-Guard: Command blocked", "error");
+				}
+				return { block: true, reason };
+			}
+		}
+
+		return undefined;
+	});
+}