pi-interview 0.3.0

package/form/themes/default-dark.css

@@ -0,0 +1,5 @@
+/* Default dark theme uses base styles.css tokens. */
+:root {
+  --overlay-bg: rgba(24, 24, 30, 0.95);
+  --error-bg: rgba(204, 102, 102, 0.12);
+}

package/form/themes/default-light.css

@@ -0,0 +1,24 @@
+:root {
+  --bg-body: #f8f8f8;
+  --bg-card: #ffffff;
+  --bg-elevated: #f0f0f0;
+  --bg-selected: #d0d0e0;
+  --bg-hover: #e8e8e8;
+  --bg-active-tint: rgba(95, 135, 135, 0.12);
+  --fg: #1a1a1a;
+  --fg-muted: #6c6c6c;
+  --fg-dim: #8a8a8a;
+  --accent: #5f8787;
+  --accent-hover: #4a7272;
+  --accent-muted: rgba(95, 135, 135, 0.15);
+  --border: #5f87af;
+  --border-muted: #b0b0b0;
+  --border-focus: #8a8a9a;
+  --border-active: #9090a0;
+  --success: #87af87;
+  --warning: #d7af5f;
+  --error: #af5f5f;
+  --error-bg: rgba(175, 95, 95, 0.12);
+  --focus-ring: rgba(95, 135, 175, 0.2);
+  --overlay-bg: rgba(255, 255, 255, 0.95);
+}

package/form/themes/tufte-dark.css

@@ -0,0 +1,29 @@
+:root {
+  --bg-body: #1c1917;
+  --bg-card: #201d1b;
+  --bg-elevated: #252220;
+  --bg-selected: #2d2925;
+  --bg-hover: #302b26;
+  --bg-active-tint: rgba(201, 183, 154, 0.1);
+  --fg: #e7e2d9;
+  --fg-muted: #a9a194;
+  --fg-dim: #8d8476;
+  --accent: #c9b79a;
+  --accent-hover: #d8c5a5;
+  --accent-muted: rgba(201, 183, 154, 0.15);
+  --border: #5a5046;
+  --border-muted: #423a31;
+  --border-focus: #6a6050;
+  --border-active: #5a5046;
+  --success: #b5bd68;
+  --warning: #d2a456;
+  --error: #cc6666;
+  --error-bg: rgba(204, 102, 102, 0.12);
+  --focus-ring: rgba(201, 183, 154, 0.2);
+  --overlay-bg: rgba(28, 25, 23, 0.95);
+
+  --font-body: "Cormorant Garamond", Cormorant, "Crimson Pro", "Libre Baskerville", Georgia, serif;
+  --font-ui: "Cormorant Garamond", Cormorant, "Crimson Pro", "Libre Baskerville", Georgia, serif;
+  --font-mono: "IBM Plex Mono", "JetBrains Mono", "SF Mono", Consolas, monospace;
+  --font-size-base: 15px;
+}

package/form/themes/tufte-light.css

@@ -0,0 +1,29 @@
+:root {
+  --bg-body: #f9f7f3;
+  --bg-card: #fbfaf7;
+  --bg-elevated: #f2ede5;
+  --bg-selected: #e8e1d6;
+  --bg-hover: #eee6db;
+  --bg-active-tint: rgba(125, 104, 80, 0.12);
+  --fg: #2a2520;
+  --fg-muted: #635c52;
+  --fg-dim: #7a7267;
+  --accent: #7d6850;
+  --accent-hover: #927b61;
+  --accent-muted: rgba(125, 104, 80, 0.15);
+  --border: #a09080;
+  --border-muted: #d9cfc0;
+  --border-focus: #8a7a6a;
+  --border-active: #b0a090;
+  --success: #7a8b5a;
+  --warning: #b9833a;
+  --error: #b05a5a;
+  --error-bg: rgba(176, 90, 90, 0.12);
+  --focus-ring: rgba(125, 104, 80, 0.2);
+  --overlay-bg: rgba(251, 250, 247, 0.95);
+
+  --font-body: "Cormorant Garamond", Cormorant, "Crimson Pro", "Libre Baskerville", Georgia, serif;
+  --font-ui: "Cormorant Garamond", Cormorant, "Crimson Pro", "Libre Baskerville", Georgia, serif;
+  --font-mono: "IBM Plex Mono", "JetBrains Mono", "SF Mono", Consolas, monospace;
+  --font-size-base: 15px;
+}

package/index.ts

@@ -0,0 +1,354 @@
+import { Type } from "@sinclair/typebox";
+import { Text } from "@mariozechner/pi-tui";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import { execSync } from "node:child_process";
+import { startInterviewServer, getActiveSessions, type ResponseItem } from "./server.js";
+import { validateQuestions, type QuestionsFile } from "./schema.js";
+import { loadSettings, type InterviewThemeSettings } from "./settings.js";
+
+function formatTimeAgo(timestamp: number): string {
+	const seconds = Math.floor((Date.now() - timestamp) / 1000);
+	if (seconds < 0) return "just now";
+	if (seconds < 60) return `${seconds} seconds ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return minutes === 1 ? "1 minute ago" : `${minutes} minutes ago`;
+	const hours = Math.floor(minutes / 60);
+	return hours === 1 ? "1 hour ago" : `${hours} hours ago`;
+}
+
+async function openUrl(pi: ExtensionAPI, url: string, browser?: string): Promise<void> {
+	const platform = os.platform();
+	let result;
+	if (platform === "darwin") {
+		if (browser) {
+			result = await pi.exec("open", ["-a", browser, url]);
+		} else {
+			result = await pi.exec("open", [url]);
+		}
+	} else if (platform === "win32") {
+		if (browser) {
+			result = await pi.exec("cmd", ["/c", "start", "", browser, url]);
+		} else {
+			result = await pi.exec("cmd", ["/c", "start", "", url]);
+		}
+	} else {
+		if (browser) {
+			result = await pi.exec(browser, [url]);
+		} else {
+			result = await pi.exec("xdg-open", [url]);
+		}
+	}
+	if (result.code !== 0) {
+		throw new Error(result.stderr || `Failed to open browser (exit code ${result.code})`);
+	}
+}
+
+interface InterviewDetails {
+	status: "completed" | "cancelled" | "timeout" | "aborted" | "queued";
+	responses: ResponseItem[];
+	url: string;
+	queuedMessage?: string;
+}
+
+const InterviewParams = Type.Object({
+	questions: Type.String({ description: "Path to questions JSON file" }),
+	timeout: Type.Optional(
+		Type.Number({ description: "Seconds before auto-timeout", default: 600 })
+	),
+	verbose: Type.Optional(Type.Boolean({ description: "Enable debug logging", default: false })),
+	theme: Type.Optional(
+		Type.Object(
+			{
+				mode: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("light"), Type.Literal("dark")])),
+				name: Type.Optional(Type.String()),
+				lightPath: Type.Optional(Type.String()),
+				darkPath: Type.Optional(Type.String()),
+				toggleHotkey: Type.Optional(Type.String()),
+			},
+			{ additionalProperties: false }
+		)
+	),
+});
+
+function expandHome(value: string): string {
+	if (value.startsWith("~" + path.sep)) {
+		return path.join(os.homedir(), value.slice(2));
+	}
+	return value;
+}
+
+function resolveOptionalPath(value: string | undefined, cwd: string): string | undefined {
+	if (!value) return undefined;
+	const expanded = expandHome(value);
+	return path.isAbsolute(expanded) ? expanded : path.join(cwd, expanded);
+}
+
+const DEFAULT_THEME_HOTKEY = "mod+shift+l";
+
+function mergeThemeConfig(
+	base: InterviewThemeSettings | undefined,
+	override: InterviewThemeSettings | undefined,
+	cwd: string
+): InterviewThemeSettings {
+	const merged: InterviewThemeSettings = { ...(base ?? {}), ...(override ?? {}) };
+	return {
+		...merged,
+		toggleHotkey: merged.toggleHotkey ?? DEFAULT_THEME_HOTKEY,
+		lightPath: resolveOptionalPath(merged.lightPath, cwd),
+		darkPath: resolveOptionalPath(merged.darkPath, cwd),
+	};
+}
+
+function loadQuestions(questionsPath: string, cwd: string): QuestionsFile {
+	const absolutePath = path.isAbsolute(questionsPath)
+		? questionsPath
+		: path.join(cwd, questionsPath);
+
+	if (!fs.existsSync(absolutePath)) {
+		throw new Error(`Questions file not found: ${absolutePath}`);
+	}
+
+	let data: unknown;
+	try {
+		const content = fs.readFileSync(absolutePath, "utf-8");
+		data = JSON.parse(content);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Invalid JSON in questions file: ${message}`);
+	}
+
+	return validateQuestions(data);
+}
+
+function formatResponses(responses: ResponseItem[]): string {
+	if (responses.length === 0) return "(none)";
+	return responses
+		.map((resp) => {
+			const value = Array.isArray(resp.value) ? resp.value.join(", ") : resp.value;
+			let line = `- ${resp.id}: ${value}`;
+			if (resp.attachments && resp.attachments.length > 0) {
+				line += ` [attachments: ${resp.attachments.join(", ")}]`;
+			}
+			return line;
+		})
+		.join("\n");
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "interview",
+		label: "Interview",
+		description:
+			"Present an interactive form to gather user responses. " +
+			"Use proactively when: choosing between multiple approaches, gathering requirements before implementation, " +
+			"exploring design tradeoffs, or when decisions have multiple dimensions worth discussing. " +
+			"Provides better UX than back-and-forth chat for structured input. " +
+			"Image responses and attachments are returned as file paths - use read tool directly to display them. " +
+			'Questions JSON format: { "title": "...", "questions": [{ "id": "q1", "type": "single|multi|text|image", "question": "...", "options": ["A", "B"], "codeBlock": { "code": "...", "lang": "ts" } }] }. ' +
+			"Options can be strings or objects: { label: string, code?: { code, lang?, file?, lines?, highlights? } }. " +
+			"Questions can have a codeBlock field to display code above options. Types: single (radio), multi (checkbox), text (textarea), image (file upload).",
+		parameters: InterviewParams,
+
+		async execute(_toolCallId, params, onUpdate, ctx, signal) {
+			const { questions, timeout, verbose, theme } = params as {
+				questions: string;
+				timeout?: number;
+				verbose?: boolean;
+				theme?: InterviewThemeSettings;
+			};
+
+			if (!ctx.hasUI) {
+				throw new Error(
+					"Interview tool requires interactive mode with browser support. " +
+						"Cannot run in headless/RPC/print mode."
+				);
+			}
+
+			if (typeof ctx.hasQueuedMessages === "function" && ctx.hasQueuedMessages()) {
+				return {
+					content: [{ type: "text", text: "Interview skipped - user has queued input." }],
+					details: { status: "cancelled", url: "", responses: [] },
+				};
+			}
+
+			const settings = loadSettings();
+			const timeoutSeconds = timeout ?? settings.timeout ?? 600;
+			const themeConfig = mergeThemeConfig(settings.theme, theme, ctx.cwd);
+			const questionsData = loadQuestions(questions, ctx.cwd);
+
+			if (signal?.aborted) {
+				return {
+					content: [{ type: "text", text: "Interview was aborted." }],
+					details: { status: "aborted", url: "", responses: [] },
+				};
+			}
+
+			const sessionId = randomUUID();
+			const sessionToken = randomUUID();
+			let server: { close: () => void } | null = null;
+			let resolved = false;
+			let url = "";
+
+			const cleanup = () => {
+				if (server) {
+					server.close();
+					server = null;
+				}
+			};
+
+			return new Promise((resolve, reject) => {
+				const finish = (
+					status: InterviewDetails["status"],
+					responses: ResponseItem[] = [],
+					cancelReason?: "timeout" | "user" | "stale"
+				) => {
+					if (resolved) return;
+					resolved = true;
+					cleanup();
+
+					let text = "";
+					if (status === "completed") {
+						text = `User completed the interview form.\n\nResponses:\n${formatResponses(responses)}`;
+					} else if (status === "cancelled") {
+						if (cancelReason === "stale") {
+							text =
+								"Interview session ended due to lost heartbeat.\n\nQuestions saved to: ~/.pi/interview-recovery/";
+						} else {
+							text = "User cancelled the interview form.";
+						}
+					} else if (status === "timeout") {
+						text = `Interview form timed out after ${timeoutSeconds} seconds.\n\nQuestions saved to: ~/.pi/interview-recovery/`;
+					} else {
+						text = "Interview was aborted.";
+					}
+
+					resolve({
+						content: [{ type: "text", text }],
+						details: { status, url, responses },
+					});
+				};
+
+				const handleAbort = () => finish("aborted");
+				signal?.addEventListener("abort", handleAbort, { once: true });
+
+				startInterviewServer(
+					{
+						questions: questionsData,
+						sessionToken,
+						sessionId,
+						cwd: ctx.cwd,
+						timeout: timeoutSeconds,
+						port: settings.port,
+						verbose,
+						theme: themeConfig,
+					},
+					{
+						onSubmit: (responses) => finish("completed", responses),
+						onCancel: (reason) =>
+							reason === "timeout" ? finish("timeout") : finish("cancelled", [], reason),
+					}
+				)
+					.then(async (handle) => {
+						server = handle;
+						url = handle.url;
+
+						const activeSessions = getActiveSessions();
+						const otherActive = activeSessions.filter((s) => s.id !== sessionId);
+
+						if (otherActive.length > 0) {
+							const active = otherActive[0];
+							const queuedLines = [
+								"Interview already active in browser:",
+								`  Title: ${active.title}`,
+								`  Project: ${active.cwd}${active.gitBranch ? ` (${active.gitBranch})` : ""}`,
+								`  Session: ${active.id.slice(0, 8)}`,
+								`  Started: ${formatTimeAgo(active.startedAt)}`,
+								"",
+								"New interview ready:",
+								`  Title: ${questionsData.title || "Interview"}`,
+							];
+							const normalizedCwd = ctx.cwd.startsWith(os.homedir())
+								? "~" + ctx.cwd.slice(os.homedir().length)
+								: ctx.cwd;
+							const gitBranch = (() => {
+								try {
+									return execSync("git rev-parse --abbrev-ref HEAD", {
+										cwd: ctx.cwd,
+										encoding: "utf8",
+										timeout: 2000,
+										stdio: ["pipe", "pipe", "pipe"],
+									}).trim() || null;
+								} catch {
+									return null;
+								}
+							})();
+							queuedLines.push(`  Project: ${normalizedCwd}${gitBranch ? ` (${gitBranch})` : ""}`);
+							queuedLines.push(`  Session: ${sessionId.slice(0, 8)}`);
+							queuedLines.push("");
+							queuedLines.push(`Open when ready: ${url}`);
+							queuedLines.push("");
+							queuedLines.push("Server waiting until you open the link.");
+							const queuedMessage = queuedLines.join("\n");
+							const queuedSummary = "Interview queued; see tool panel for link.";
+							if (onUpdate) {
+								onUpdate({
+									content: [{ type: "text", text: queuedSummary }],
+									details: { status: "queued", url, responses: [], queuedMessage },
+								});
+							} else if (pi.hasUI) {
+								pi.ui.notify(queuedSummary, "info");
+							}
+						} else {
+							try {
+								await openUrl(pi, url, settings.browser);
+							} catch (err) {
+								cleanup();
+								const message = err instanceof Error ? err.message : String(err);
+								reject(new Error(`Failed to open browser: ${message}`));
+								return;
+							}
+						}
+					})
+					.catch((err) => {
+						cleanup();
+						reject(err);
+					});
+			});
+		},
+
+		renderCall(args, theme) {
+			const { questions } = args as { questions?: string };
+			const label = questions ? `Interview: ${questions}` : "Interview";
+			return new Text(theme.fg("toolTitle", theme.bold(label)), 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as InterviewDetails | undefined;
+			if (!details) return new Text("Interview", 0, 0);
+
+			if (details.status === "queued" && details.queuedMessage) {
+				const header = theme.fg("warning", "QUEUED");
+				const body = theme.fg("dim", details.queuedMessage);
+				return new Text(`${header}\n${body}`, 0, 0);
+			}
+
+			const statusColor =
+				details.status === "completed"
+					? "success"
+					: details.status === "cancelled"
+						? "warning"
+						: details.status === "timeout"
+							? "warning"
+							: details.status === "queued"
+								? "warning"
+								: "error";
+
+			const line = `${details.status.toUpperCase()} (${details.responses.length} responses)`;
+			return new Text(theme.fg(statusColor, line), 0, 0);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "pi-interview",
+  "version": "0.3.0",
+  "description": "Interactive interview form extension for pi coding agent",
+  "author": "Nico Bailon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicobailon/pi-interview-tool.git"
+  },
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "interview",
+    "form",
+    "extension",
+    "cli"
+  ],
+  "bin": {
+    "pi-interview": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "form/",
+    "index.ts",
+    "schema.ts",
+    "server.ts",
+    "settings.ts",
+    "README.md"
+  ]
+}