@garaje/base 0.1.0

package/extensions/role-commands.ts

@@ -0,0 +1,69 @@
+/**
+ * Role Commands Extension
+ *
+ * Thin wrappers over the `preset` extension for the canonical roles defined
+ * in `packages/base/prompts/roles/` (and emitted into `packages/base/presets.json`
+ * by `bin/build-roles`). Each command activates the matching preset and kicks
+ * off a templated user message.
+ *
+ *   /plan   [topic]     → preset planner    + plan request
+ *   /spec   [feature]   → preset planner    + spec request
+ *   /review [scope]     → preset reviewer   + review request
+ *
+ * `/spec` reuses the `planner` preset because spec'ing is read-only design
+ * work — what diverges is the kickoff message.
+ *
+ * Implementation: each handler sends `/preset <name>` as a user message
+ * (which pi dispatches to the preset extension's command, not to the LLM),
+ * then sends the kickoff as a normal user message that triggers a turn.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+type Wrapper = {
+	preset: string;
+	description: string;
+	kickoff: (args: string) => string;
+};
+
+const WRAPPERS: Record<string, Wrapper> = {
+	plan: {
+		preset: "planner",
+		description: "Switch to planner role and draft a plan [topic]",
+		kickoff: (args) =>
+			args
+				? `Draft an implementation plan for: ${args}`
+				: "Draft an implementation plan for the work we just discussed. If there is none, ask what to plan.",
+	},
+	spec: {
+		preset: "planner",
+		description: "Switch to planner role and write a spec [feature]",
+		kickoff: (args) =>
+			args
+				? `Write a short spec for: ${args}. Capture goal, non-goals, surface area, open questions, and acceptance proof.`
+				: "Write a short spec for the feature under discussion. Capture goal, non-goals, surface area, open questions, and acceptance proof.",
+	},
+	review: {
+		preset: "reviewer",
+		description: "Switch to reviewer role and review changes [scope]",
+		kickoff: (args) =>
+			args
+				? `Review: ${args}. Follow the reviewer role's report structure.`
+				: "Review the staged changes (fall back to the most recent commit if nothing is staged). Follow the reviewer role's report structure.",
+	},
+};
+
+export default function roleCommands(pi: ExtensionAPI) {
+	for (const [name, wrapper] of Object.entries(WRAPPERS)) {
+		pi.registerCommand(name, {
+			description: wrapper.description,
+			handler: async (args: string | undefined, _ctx: ExtensionCommandContext) => {
+				const kickoff = wrapper.kickoff((args ?? "").trim());
+				// First message is a slash command, dispatched synchronously by pi.
+				pi.sendUserMessage(`/preset ${wrapper.preset}`);
+				// Second message is the actual prompt; this one triggers the LLM turn.
+				pi.sendUserMessage(kickoff);
+			},
+		});
+	}
+}

package/extensions/session-name.ts

@@ -0,0 +1,27 @@
+/**
+ * Session naming example.
+ *
+ * Shows setSessionName/getSessionName to give sessions friendly names
+ * that appear in the session selector instead of the first message.
+ *
+ * Usage: /session-name [name] - set or show session name
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("session-name", {
+		description: "Set or show session name (usage: /session-name [new name])",
+		handler: async (args, ctx) => {
+			const name = args.trim();
+
+			if (name) {
+				pi.setSessionName(name);
+				ctx.ui.notify(`Session named: ${name}`, "info");
+			} else {
+				const current = pi.getSessionName();
+				ctx.ui.notify(current ? `Session: ${current}` : "No session name set", "info");
+			}
+		},
+	});
+}

package/extensions/standalone-commands.ts

@@ -0,0 +1,101 @@
+/**
+ * Standalone Commands Extension
+ *
+ * Repo-flavored slash commands that don't wrap a preset:
+ *
+ *   /checkpoint [label]  Create a named git stash checkpoint right now.
+ *                        Complements git-checkpoint.ts's per-turn auto-stash
+ *                        by giving the agent (or user) an on-demand snapshot.
+ *
+ *   /handoff [brief]     Write a handoff brief to scratch/HANDOFF.md and
+ *                        notify. Use when ending a session so the next
+ *                        session (or human) can pick up the thread.
+ *
+ *   /proof   [target]    Kick off a "prove the edit took effect" turn —
+ *                        nudges the agent to hit the affected parked bay's
+ *                        endpoint over the compose network and report results.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+function ts(): string {
+	return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+export default function standaloneCommands(pi: ExtensionAPI) {
+	pi.registerCommand("checkpoint", {
+		description: "Create a named git stash checkpoint [label]",
+		handler: async (args: string | undefined, ctx: ExtensionCommandContext) => {
+			const label = (args ?? "").trim() || "manual";
+			try {
+				const create = await pi.exec("git", ["stash", "create"]);
+				const ref = create.stdout.trim();
+				if (!ref) {
+					ctx.ui.notify("Nothing to checkpoint — working tree is clean.", "info");
+					return;
+				}
+				const message = `pi-checkpoint: ${label} @ ${new Date().toISOString()}`;
+				await pi.exec("git", ["stash", "store", "-m", message, ref]);
+				ctx.ui.notify(`Checkpoint stored: ${label} (${ref.slice(0, 8)})`, "info");
+			} catch (err) {
+				ctx.ui.notify(`Checkpoint failed: ${(err as Error).message}`, "error");
+			}
+		},
+	});
+
+	pi.registerCommand("handoff", {
+		description: "Write a handoff brief to scratch/HANDOFF.md [brief]",
+		handler: async (args: string | undefined, ctx: ExtensionCommandContext) => {
+			const brief = (args ?? "").trim();
+			const scratchDir = path.join(ctx.cwd, "scratch");
+			try {
+				fs.mkdirSync(scratchDir, { recursive: true });
+			} catch (err) {
+				ctx.ui.notify(`Cannot create scratch dir: ${(err as Error).message}`, "error");
+				return;
+			}
+
+			const file = path.join(scratchDir, "HANDOFF.md");
+			const session = ctx.sessionManager.getSessionFile() ?? "(unknown session)";
+			const header = [
+				`# Handoff — ${new Date().toISOString()}`,
+				"",
+				`- session: \`${session}\``,
+				"",
+			].join("\n");
+
+			if (!brief) {
+				// No brief provided — ask the agent to write one.
+				const archive = path.join(scratchDir, `HANDOFF-${ts()}.md`);
+				if (fs.existsSync(file)) fs.copyFileSync(file, archive);
+				fs.writeFileSync(file, `${header}\n_Awaiting brief from agent._\n`);
+				pi.sendUserMessage(
+					`Write a handoff brief to \`scratch/HANDOFF.md\` summarising: what was the goal, what shipped, what is left, what to read next, and any open questions. Overwrite the placeholder. Keep it under 30 lines.`,
+				);
+				return;
+			}
+
+			fs.writeFileSync(file, `${header}\n${brief}\n`);
+			ctx.ui.notify(`Handoff written: ${path.relative(ctx.cwd, file)}`, "info");
+		},
+	});
+
+	pi.registerCommand("proof", {
+		description: "Ask the agent to prove the recent edit took effect [target]",
+		handler: async (args: string | undefined, _ctx: ExtensionCommandContext) => {
+			const target = (args ?? "").trim();
+			const scope = target
+				? `Focus on: ${target}.`
+				: `Cover every service whose source you touched this session.`;
+			pi.sendUserMessage(
+				[
+					`Prove the recent edit took effect, per AGENTS.md → "Proving an edit took effect".`,
+					scope,
+					`For each affected service, wait a beat for that codebase's reloader, then \`curl\` it over the compose network (using the recipe's process name/port, e.g. \`curl http://<bay>-web:3000/up\`) and quote the response. If the response does not reflect the edit, stop and diagnose.`,
+				].join(" "),
+			);
+		},
+	});
+}

package/extensions/status-line.ts

@@ -0,0 +1,32 @@
+/**
+ * Status Line Extension
+ *
+ * Demonstrates ctx.ui.setStatus() for displaying persistent status text in the footer.
+ * Shows turn progress with themed colors.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	let turnCount = 0;
+
+	pi.on("session_start", async (_event, ctx) => {
+		const theme = ctx.ui.theme;
+		ctx.ui.setStatus("status-demo", theme.fg("dim", "Ready"));
+	});
+
+	pi.on("turn_start", async (_event, ctx) => {
+		turnCount++;
+		const theme = ctx.ui.theme;
+		const spinner = theme.fg("accent", "●");
+		const text = theme.fg("dim", ` Turn ${turnCount}...`);
+		ctx.ui.setStatus("status-demo", spinner + text);
+	});
+
+	pi.on("turn_end", async (_event, ctx) => {
+		const theme = ctx.ui.theme;
+		const check = theme.fg("success", "✓");
+		const text = theme.fg("dim", ` Turn ${turnCount} complete`);
+		ctx.ui.setStatus("status-demo", check + text);
+	});
+}

package/extensions/subagent/agents.ts

@@ -0,0 +1,125 @@
+/**
+ * Agent discovery and configuration
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { dedupeAgentsByName } from "../../lib/agents.ts";
+import { packageRoot } from "../../lib/base-paths.ts";
+
+export type AgentScope = "user" | "project" | "both";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: "user" | "project";
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+
+	if (!fs.existsSync(dir)) {
+		return agents;
+	}
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const filePath = path.join(dir, entry.name);
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+
+		if (!frontmatter.name || !frontmatter.description) {
+			continue;
+		}
+
+		const tools = frontmatter.tools
+			?.split(",")
+			.map((t: string) => t.trim())
+			.filter(Boolean);
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			model: frontmatter.model,
+			systemPrompt: body,
+			source,
+			filePath,
+		});
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const baseAgents = loadAgentsFromDir(path.join(packageRoot(), "agents"), "user"); // base layer, always available
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	const lists =
+		scope === "user"
+			? [baseAgents, userAgents]
+			: scope === "project"
+				? [baseAgents, projectAgents]
+				: [baseAgents, userAgents, projectAgents];
+
+	return { agents: dedupeAgentsByName(lists), projectAgentsDir };
+}
+
+export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	const remaining = agents.length - listed.length;
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining,
+	};
+}