@shanepadgett/tau-agent 0.1.0

package/extensions/branch/index.ts

@@ -0,0 +1,145 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { createGitRunner, type GitRunner } from "../../shared/git.ts";
+import { errorText } from "../../shared/text.ts";
+import { type BranchChoice, showBranchPanel } from "./panel.ts";
+
+const GIT_FETCH_TIMEOUT_MS = 120_000;
+
+const LIST_BRANCH_REFS_ARGS = [
+	"for-each-ref",
+	"--sort=-committerdate",
+	"--format=%(refname)%00%(committerdate:unix)%00%(HEAD)%00%(symref)",
+	"refs/heads",
+	"refs/remotes",
+];
+
+export function normalizeBranchName(name: string): string {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
+export default function branchExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("branch", {
+		description: "Switch branches, or create one with /branch new",
+		getArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+			const value = prefix.trimStart();
+			if (/\s/.test(value)) return null;
+
+			const item = { value: "new", label: "new", description: "Create a new branch" };
+			return item.value.startsWith(value) ? [item] : null;
+		},
+		handler: async (args, ctx) => {
+			await ctx.waitForIdle();
+
+			const action = args.trim();
+			if (action && action !== "new") {
+				ctx.ui.notify("Usage: /branch or /branch new", "error");
+				return;
+			}
+
+			if (!ctx.hasUI) {
+				const operation = action === "new" ? "creation" : "switching";
+				ctx.ui.notify(`Branch ${operation} requires interactive UI.`, "error");
+				return;
+			}
+			if (action !== "new" && ctx.mode !== "tui") {
+				ctx.ui.notify("Branch switching requires interactive TUI.", "error");
+				return;
+			}
+
+			const git = createGitRunner(pi, ctx);
+			try {
+				if (action === "new") await createBranch(git, ctx);
+				else await chooseBranch(git, ctx);
+			} catch (error) {
+				const operation = action === "new" ? "creation" : "switch";
+				ctx.ui.notify(`Branch ${operation} failed: ${errorText(error)}`, "error");
+			}
+		},
+	});
+}
+
+async function createBranch(git: GitRunner, ctx: ExtensionCommandContext): Promise<void> {
+	const type = await ctx.ui.select("Branch type", ["feature", "fix", "chore"]);
+	if (!type) return;
+
+	const input = await ctx.ui.input("Branch name", "add branch command");
+	if (input === undefined) return;
+
+	const name = normalizeBranchName(input);
+	if (!name) {
+		ctx.ui.notify("Branch name must contain letters or numbers.", "error");
+		return;
+	}
+
+	const root = await git.run(["rev-parse", "--show-toplevel"], { optional: true });
+	if (!root) {
+		ctx.ui.notify("No Git repository found.", "error");
+		return;
+	}
+
+	const branch = `${type}/${name}`;
+	await git.run(["switch", "-c", branch], { cwd: root });
+	ctx.ui.notify(`Created and switched to ${branch}.`, "info");
+}
+
+async function chooseBranch(git: GitRunner, ctx: ExtensionCommandContext): Promise<void> {
+	const root = await git.run(["rev-parse", "--show-toplevel"], { optional: true });
+	if (!root) {
+		ctx.ui.notify("No Git repository found.", "error");
+		return;
+	}
+
+	const choice = await showBranchPanel(ctx, await loadBranchChoices(git, root), async () => {
+		await git.run(["fetch", "--all"], { cwd: root, timeout: GIT_FETCH_TIMEOUT_MS });
+		return loadBranchChoices(git, root);
+	});
+	if (!choice) return;
+
+	if (choice.kind === "local") await git.run(["switch", choice.name], { cwd: root });
+	else await git.run(["switch", "--track", "-c", choice.name, choice.upstream], { cwd: root });
+	ctx.ui.notify(`Switched to ${choice.name}.`, "info");
+}
+
+async function loadBranchChoices(git: GitRunner, root: string): Promise<BranchChoice[]> {
+	return parseBranchChoices(await git.run(LIST_BRANCH_REFS_ARGS, { cwd: root }));
+}
+
+function parseBranchChoices(output: string): BranchChoice[] {
+	const refs = output
+		.split("\n")
+		.filter(Boolean)
+		.map((line) => {
+			const [ref = "", seconds = "0", head = "", symref = ""] = line.split("\0");
+			return { ref, updatedAt: Number(seconds) * 1000, current: head.trim() === "*", symbolic: Boolean(symref) };
+		});
+	const localPrefix = "refs/heads/";
+	const remotePrefix = "refs/remotes/";
+	const localNames = new Set(
+		refs.filter(({ ref }) => ref.startsWith(localPrefix)).map(({ ref }) => ref.slice(localPrefix.length)),
+	);
+	const choices: BranchChoice[] = [];
+
+	for (const ref of refs) {
+		if (ref.ref.startsWith(localPrefix)) {
+			const name = ref.ref.slice(localPrefix.length);
+			if (name && !ref.current)
+				choices.push({ id: `local:${name}`, kind: "local", label: name, name, updatedAt: ref.updatedAt });
+			continue;
+		}
+		if (!ref.ref.startsWith(remotePrefix) || ref.symbolic) continue;
+
+		const upstream = ref.ref.slice(remotePrefix.length);
+		const separator = upstream.indexOf("/");
+		if (separator < 1) continue;
+		const name = upstream.slice(separator + 1);
+		if (!name || name === "HEAD" || localNames.has(name)) continue;
+		const label = localNames.has(upstream) ? `${upstream} (remote)` : upstream;
+		choices.push({ id: `remote:${upstream}`, kind: "remote", label, name, upstream, updatedAt: ref.updatedAt });
+	}
+
+	return choices.sort((left, right) => right.updatedAt - left.updatedAt || left.label.localeCompare(right.label));
+}

package/extensions/branch/panel.ts

@@ -0,0 +1,148 @@
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Key, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+import { errorText } from "../../shared/text.ts";
+import { bindingHint, rawHint } from "@shanepadgett/tau-tui";
+import { SelectableList, type SelectableListResult } from "@shanepadgett/tau-tui";
+import { ToolPanel, type ToolPanelConfig, type ToolPanelFooter } from "@shanepadgett/tau-tui";
+
+const MAX_VISIBLE_BRANCHES = 10;
+
+export type BranchChoice =
+	| { id: string; kind: "local"; label: string; name: string; updatedAt: number }
+	| { id: string; kind: "remote"; label: string; name: string; upstream: string; updatedAt: number };
+
+export function showBranchPanel(
+	ctx: ExtensionCommandContext,
+	initial: readonly BranchChoice[],
+	refresh: () => Promise<readonly BranchChoice[]>,
+): Promise<BranchChoice | undefined> {
+	return ctx.ui.custom<BranchChoice | undefined>(
+		(tui, theme, _keybindings, done) =>
+			new BranchPanel(
+				tui,
+				theme,
+				initial,
+				refresh,
+				(error) => {
+					ctx.ui.notify(`Branch fetch failed: ${errorText(error)}`, "error");
+				},
+				done,
+			),
+	);
+}
+
+class BranchPanel implements Component {
+	private readonly tui: TUI;
+	private readonly refresh: () => Promise<readonly BranchChoice[]>;
+	private readonly onFetchError: (error: unknown) => void;
+	private readonly done: (choice: BranchChoice | undefined) => void;
+	private readonly list: SelectableList<BranchChoice>;
+	private readonly panelConfig: ToolPanelConfig;
+	private readonly panel: ToolPanel;
+	private itemCount: number;
+	private fetching = false;
+	private closed = false;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		initial: readonly BranchChoice[],
+		refresh: () => Promise<readonly BranchChoice[]>,
+		onFetchError: (error: unknown) => void,
+		done: (choice: BranchChoice | undefined) => void,
+	) {
+		this.tui = tui;
+		this.refresh = refresh;
+		this.onFetchError = onFetchError;
+		this.done = done;
+		this.itemCount = initial.length;
+		this.list = new SelectableList(theme, {
+			items: initial,
+			emptyMessage: "No cached branches. Press ctrl+f to fetch.",
+			selection: { kind: "single", primaryLabel: "switch" },
+			actions: [{ id: "fetch", key: Key.ctrl("f"), hint: rawHint("ctrl+f", "fetch") }],
+			cancelLabel: "cancel",
+			maxVisible: MAX_VISIBLE_BRANCHES,
+			renderItem: (item, state, width) => [
+				truncateToWidth(theme.fg(state.active ? "accent" : "text", item.label), width, ""),
+			],
+			onResult: (result) => this.handleResult(result),
+		});
+		this.panelConfig = {
+			title: "Branches",
+			secondary: this.secondaryText(),
+			body: this.list,
+			footer: this.footer(),
+		};
+		this.panel = new ToolPanel(theme, this.panelConfig);
+	}
+
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+
+	handleInput(data: string): void {
+		this.list.handleInput(data);
+		if (!this.closed) this.syncPanel();
+	}
+
+	private handleResult(result: SelectableListResult<BranchChoice>): void {
+		if (result.kind === "cancel") {
+			this.closed = true;
+			this.done(undefined);
+			return;
+		}
+		if (this.fetching) return;
+		if (result.kind === "primary") {
+			const choice = result.items[0];
+			if (!choice) return;
+			this.closed = true;
+			this.done(choice);
+			return;
+		}
+		if (result.actionId === "fetch") void this.fetchBranches();
+	}
+
+	private async fetchBranches(): Promise<void> {
+		const activeId = this.list.getCurrentItem()?.id;
+		this.fetching = true;
+		this.syncPanel();
+		try {
+			const choices = await this.refresh();
+			if (this.closed) return;
+			this.itemCount = choices.length;
+			this.list.setItems(choices, activeId);
+		} catch (error) {
+			if (!this.closed) this.onFetchError(error);
+		} finally {
+			if (!this.closed) {
+				this.fetching = false;
+				this.syncPanel();
+			}
+		}
+	}
+
+	private syncPanel(): void {
+		this.panelConfig.secondary = this.secondaryText();
+		this.panelConfig.footer = this.footer();
+		this.tui.requestRender();
+	}
+
+	private secondaryText(): string {
+		return `${this.itemCount} branch${this.itemCount === 1 ? "" : "es"}`;
+	}
+
+	private footer(): ToolPanelFooter {
+		return this.fetching
+			? {
+					kind: "infoAck",
+					message: "Fetching branches…",
+					hints: [bindingHint("tui.select.cancel", "cancel")],
+				}
+			: { kind: "hints", hints: this.list.getKeyHints() };
+	}
+}

package/extensions/clear-screen/README.md

@@ -0,0 +1,29 @@
+# Clear Screen
+
+Clears the terminal viewport and scrollback when Pi starts, then clears again when Pi quits.
+
+It does **not** clear on `/reload`, `/resume`, `/new`, or `/fork`, so Pi hot reloads and session switches keep the current TUI flow intact.
+
+## Behavior
+
+- Runs only when `process.stdout` is a TTY.
+- Clears once per process on startup. Reloads do not re-clear.
+- Clears on process exit only when the final `session_shutdown` reason is `"quit"`.
+- Uses ANSI clear sequences (`\x1b[2J\x1b[3J`) on Unix and modern Windows consoles.
+- Falls back to a newline-fill on older Windows consoles that do not support the scrollback escape.
+
+## Limits
+
+- TTY-only. Pipe, socket, and script runs are a no-op.
+- Old Windows consoles get a best-effort visible clear, not a guaranteed scrollback clear.
+- Process-level state is keyed on a `globalThis` symbol so reloads reuse a single startup clear and a single exit hook.
+
+## Usage
+
+Load extension, then reload Pi:
+
+```text
+/reload
+```
+
+The package manifest glob `./extensions/*/index.ts` auto-loads this extension.

package/extensions/clear-screen/index.ts

@@ -0,0 +1,75 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type ClearScreenState = {
+	startupCleared: boolean;
+	exitHooked: boolean;
+	clearOnExit: boolean;
+};
+
+const STATE_KEY = Symbol.for("@tau-agent/clear-screen/state");
+
+function getState(): ClearScreenState {
+	const globalState = globalThis as typeof globalThis & {
+		[key: symbol]: ClearScreenState | undefined;
+	};
+	const state =
+		globalState[STATE_KEY] ??
+		({
+			startupCleared: false,
+			exitHooked: false,
+			clearOnExit: false,
+		} satisfies ClearScreenState);
+	globalState[STATE_KEY] = state;
+	return state;
+}
+
+function supportsAnsiClear(): boolean {
+	if (process.platform !== "win32") return true;
+
+	return Boolean(
+		process.env.WT_SESSION ||
+		process.env.TERM_PROGRAM === "vscode" ||
+		process.env.TERM?.includes("xterm") ||
+		process.env.ANSICON ||
+		process.env.ConEmuANSI === "ON",
+	);
+}
+
+function getClearSequence(): string {
+	if (!supportsAnsiClear()) {
+		return "\n".repeat(process.stdout.rows || 30);
+	}
+
+	return "\x1b[0m\x1b[?25h\x1b[H\x1b[2J\x1b[3J";
+}
+
+function clearTerminal(): void {
+	try {
+		process.stdout.write(getClearSequence());
+	} catch {
+		// Ignore terminal write failures during process shutdown.
+	}
+}
+
+export default function clearScreenExtension(pi: ExtensionAPI): void {
+	if (!process.stdout.isTTY) return;
+
+	const state = getState();
+	state.clearOnExit = false;
+
+	pi.on("session_shutdown", (event) => {
+		state.clearOnExit = event.reason === "quit";
+	});
+
+	if (!state.exitHooked) {
+		state.exitHooked = true;
+		process.on("exit", () => {
+			if (state.clearOnExit) clearTerminal();
+		});
+	}
+
+	if (!state.startupCleared) {
+		state.startupCleared = true;
+		clearTerminal();
+	}
+}

package/extensions/commit/README.md

@@ -0,0 +1,15 @@
+# Commit
+
+Generate a semantic commit plan from current repository changes, review it, then create one or more commits.
+
+## Usage
+
+```text
+/commit
+```
+
+## Overview
+
+`/commit` looks at staged, unstaged, and untracked files, gathers bounded change evidence, and asks a model for a small set of meaningful conventional commits. You can review the plan in the TUI, edit messages, move files between commits, regenerate messages, and then commit the approved groups.
+
+Unassigned files are left uncommitted. After successful commits, Tau asks whether to run `git push`.