pi-interview 0.3.0

package/README.md

@@ -0,0 +1,346 @@
+# Interview Tool
+
+A custom tool for pi-agent that opens a web-based form to gather user responses to clarification questions.
+
+https://github.com/user-attachments/assets/52285bd9-956e-4020-aca5-9fbd82916934
+
+## Installation
+
+Clone or copy this directory to your pi-agent extensions folder:
+
+```bash
+# Clone to user extensions directory (available in all projects)
+git clone https://github.com/nicobailon/pi-interview-tool ~/.pi/agent/extensions/interview
+
+# Or copy manually
+cp -r /path/to/interview ~/.pi/agent/extensions/
+```
+
+The tool is automatically discovered on next pi session. No build step required.
+
+**Requirements:**
+- pi-agent v0.35.0 or later (extensions API)
+
+## Features
+
+- **Question Types**: Single-select, multi-select, text input, and image upload
+- **"Other" Option**: Single/multi select questions support custom text input
+- **Per-Question Attachments**: Attach images to any question via button, paste, or drag & drop
+- **Keyboard Navigation**: Full keyboard support with arrow keys, Tab, Enter
+- **Auto-save**: Responses saved to localStorage, restored on reload
+- **Session Timeout**: Configurable timeout with countdown badge, refreshes on activity
+- **Multi-Agent Support**: Queue detection prevents focus stealing when multiple agents run interviews
+- **Queue Toast Switcher**: Active interviews show a top-right toast with a dropdown to open queued sessions
+- **Session Recovery**: Abandoned/timed-out interviews save questions for later retry
+- **Session Status Bar**: Shows project path, git branch, and session ID for identification
+- **Image Support**: Drag & drop anywhere on question, file picker, paste image or path
+- **Path Normalization**: Handles shell-escaped paths (`\ `) and macOS screenshot filenames (narrow no-break space before AM/PM)
+- **Themes**: Built-in default + optional light/dark + custom theme CSS
+
+## How It Works
+
+```
+┌─────────┐      ┌──────────────────────────────────────────┐      ┌─────────┐
+│  Agent  │      │              Browser Form                │      │  Agent  │
+│ invokes ├─────►│                                          ├─────►│receives │
+│interview│      │  answer → answer → attach img → answer   │      │responses│
+└─────────┘      │     ↑                                    │      └─────────┘
+                 │     └── auto-save, timeout resets ───────┤
+                 └──────────────────────────────────────────┘
+```
+
+**Lifecycle:**
+1. Agent calls `interview()` → local server starts → browser opens form
+2. User answers at their own pace; each change auto-saves and resets the timeout
+3. Session ends via:
+   - **Submit** (`⌘+Enter`) → responses returned to agent
+   - **Timeout** → warning overlay, option to stay or close
+   - **Escape × 2** → quick cancel
+4. Window closes automatically; agent receives responses (or `null` if cancelled)
+
+**Timeout behavior:** The countdown (visible in corner) resets on any activity - typing, clicking, or mouse movement. When it expires, an overlay appears giving the user a chance to continue. Progress is never lost thanks to localStorage auto-save.
+
+**Multi-agent behavior:** When multiple agents run interviews simultaneously, only the first auto-opens the browser. Subsequent interviews are queued and shown as a URL in the tool output, preventing focus stealing. Active interviews also surface a top-right toast with a dropdown to open queued sessions. A session status bar at the top of each form shows the project path, git branch, and session ID for easy identification.
+
+## Usage
+
+The interview tool is invoked by pi-agent, not imported directly:
+
+```javascript
+// Create a questions JSON file, then call the tool
+await interview({
+  questions: '/path/to/questions.json',
+  timeout: 600,  // optional, seconds (default: 600)
+  verbose: false // optional, debug logging
+});
+```
+
+## Question Schema
+
+```json
+{
+  "title": "Project Setup",
+  "description": "Optional description text",
+  "questions": [
+    {
+      "id": "framework",
+      "type": "single",
+      "question": "Which framework?",
+      "options": ["React", "Vue", "Svelte"],
+      "recommended": "React"
+    },
+    {
+      "id": "features",
+      "type": "multi",
+      "question": "Which features?",
+      "context": "Select all that apply",
+      "options": ["Auth", "Database", "API"],
+      "recommended": ["Auth", "Database"]
+    },
+    {
+      "id": "notes",
+      "type": "text",
+      "question": "Additional requirements?"
+    },
+    {
+      "id": "mockup",
+      "type": "image",
+      "question": "Upload a design mockup"
+    }
+  ]
+}
+```
+
+### Question Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier |
+| `type` | string | `single`, `multi`, `text`, or `image` |
+| `question` | string | Question text |
+| `options` | string[] or object[] | Choices (required for single/multi). Can be strings or `{ label, code? }` objects |
+| `recommended` | string or string[] | Highlighted option(s) with `*` indicator |
+| `context` | string | Help text shown below question |
+| `codeBlock` | object | Code block displayed below question text |
+
+### Code Blocks
+
+Questions and options can include code blocks for displaying code snippets, diffs, and file references.
+
+**Question-level code block** (displayed above options):
+```json
+{
+  "id": "review",
+  "type": "single",
+  "question": "Review this implementation",
+  "codeBlock": {
+    "code": "function add(a, b) {\n  return a + b;\n}",
+    "lang": "ts",
+    "file": "src/math.ts",
+    "lines": "10-12",
+    "highlights": [2]
+  },
+  "options": ["Approve", "Request changes"]
+}
+```
+
+**Options with code blocks**:
+```json
+{
+  "options": [
+    {
+      "label": "Use async/await",
+      "code": { "code": "const data = await fetch(url);", "lang": "ts" }
+    },
+    {
+      "label": "Use promises",
+      "code": { "code": "fetch(url).then(data => ...);", "lang": "ts" }
+    },
+    "Keep current implementation"
+  ]
+}
+```
+
+**Diff display** (set `lang: "diff"`):
+```json
+{
+  "codeBlock": {
+    "code": "--- a/file.ts\n+++ b/file.ts\n@@ -1,3 +1,4 @@\n const x = 1;\n+const y = 2;\n const z = 3;",
+    "lang": "diff",
+    "file": "src/file.ts"
+  }
+}
+```
+
+| CodeBlock Field | Type | Description |
+|-----------------|------|-------------|
+| `code` | string | The code content (required) |
+| `lang` | string | Language for display (e.g., "ts", "diff") |
+| `file` | string | File path to display in header |
+| `lines` | string | Line range to display (e.g., "10-25") |
+| `highlights` | number[] | Line numbers to highlight |
+| `title` | string | Optional title above code |
+
+Line numbers are shown when `file` or `lines` is specified. Diff syntax (`+`/`-` lines) is automatically styled when `lang` is "diff".
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `↑` `↓` | Navigate options |
+| `←` `→` | Navigate between questions |
+| `Tab` | Cycle through options |
+| `Enter` / `Space` | Select option |
+| `⌘+V` | Paste image or file path |
+| `⌘+Enter` | Submit form |
+| `Esc` | Show exit overlay (press twice to quit) |
+| `⌘+Shift+L` | Toggle theme (if enabled; appears in shortcuts bar) |
+
+## Configuration
+
+Settings in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "interview": {
+    "timeout": 600,
+    "port": 19847,
+    "theme": {
+      "mode": "auto",
+      "name": "default",
+      "lightPath": "/path/to/light.css",
+      "darkPath": "/path/to/dark.css",
+      "toggleHotkey": "mod+shift+l"
+    }
+  }
+}
+```
+
+**Timeout precedence**: params > settings > default (600s)
+
+**Port setting**: Set a fixed `port` (e.g., `19847`) to use a consistent port across sessions.
+
+**Theme notes:**
+- `mode`: `dark` (default), `light`, or `auto` (follows OS unless overridden)
+- `name`: built-in themes are `default` and `tufte`
+- `lightPath` / `darkPath`: optional CSS file paths (absolute or relative to cwd)
+- `toggleHotkey`: optional; when set, toggles light/dark and persists per browser profile
+
+## Theming
+
+The interview form supports light/dark themes with automatic OS detection and user override.
+
+### Built-in Themes
+
+| Theme | Description |
+|-------|-------------|
+| `default` | Monospace, IDE-inspired aesthetic |
+| `tufte` | Serif fonts (Cormorant Garamond), book-like feel |
+
+### Theme Modes
+
+- **`dark`** (default): Dark background, light text
+- **`light`**: Light background, dark text  
+- **`auto`**: Follows OS preference, user can toggle and override persists in localStorage
+
+### Custom Themes
+
+Create custom CSS files that override the default variables:
+
+```css
+:root {
+  --bg-body: #f8f8f8;
+  --bg-card: #ffffff;
+  --bg-elevated: #f0f0f0;
+  --bg-selected: #d0d0e0;
+  --bg-hover: #e8e8e8;
+  --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;
+  --focus-ring: rgba(95, 135, 175, 0.2);
+}
+```
+
+Then reference in settings or params:
+
+```json
+{
+  "interview": {
+    "theme": {
+      "mode": "auto",
+      "lightPath": "~/my-themes/light.css",
+      "darkPath": "~/my-themes/dark.css",
+      "toggleHotkey": "mod+shift+l"
+    }
+  }
+}
+```
+
+### Toggle Hotkey
+
+When `toggleHotkey` is set (e.g., `"mod+shift+l"`), users can switch between light/dark modes. The preference persists in the browser's localStorage across sessions.
+
+## Response Format
+
+```typescript
+interface Response {
+  id: string;
+  value: string | string[];
+  attachments?: string[];  // image paths attached to non-image questions
+}
+```
+
+Example:
+```
+- framework: React [attachments: /path/to/diagram.png]
+- features: Auth, Database
+- notes: Need SSO support
+- mockup: /tmp/uploaded-image.png
+```
+
+## File Structure
+
+```
+interview/
+├── index.ts       # Tool entry point, parameter schema
+├── settings.ts    # Shared settings module
+├── server.ts      # HTTP server, request handling
+├── schema.ts      # TypeScript interfaces for questions/responses
+└── form/
+    ├── index.html # Form template
+    ├── styles.css # Base styles (dark tokens)
+    ├── themes/    # Theme overrides (light/dark)
+    └── script.js  # Form logic, keyboard nav, image handling
+```
+
+## Session Recovery
+
+If an interview times out or is abandoned (tab closed, lost connection), the questions are automatically saved to `~/.pi/interview-recovery/` for later retry.
+
+**Recovery files:**
+- Location: `~/.pi/interview-recovery/`
+- Format: `{date}_{time}_{project}_{branch}_{sessionId}.json`
+- Example: `2026-01-02_093000_myproject_main_65bec3f4.json`
+- Auto-cleanup: Files older than 7 days are deleted
+
+**To retry an abandoned interview:**
+```javascript
+interview({ questions: "~/.pi/interview-recovery/2026-01-02_093000_myproject_main_65bec3f4.json" })
+```
+
+## Limits
+
+- Max 12 images total per submission
+- Max 5MB per image
+- Max 4096x4096 pixels per image
+- Allowed types: PNG, JPG, GIF, WebP

package/bin/install.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const EXTENSION_NAME = "interview";
+const TARGET_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", EXTENSION_NAME);
+const SOURCE_DIR = path.join(__dirname, "..");
+
+const FILES_TO_COPY = [
+  "index.ts",
+  "schema.ts", 
+  "server.ts",
+  "settings.ts",
+];
+
+const DIRS_TO_COPY = ["form"];
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyFile(src, dest) {
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(src, dest) {
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFile(srcPath, destPath);
+    }
+  }
+}
+
+function getVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(SOURCE_DIR, "package.json"), "utf-8"));
+    return pkg.version;
+  } catch {
+    return "unknown";
+  }
+}
+
+function main() {
+  const version = getVersion();
+  console.log(`\npi-interview v${version}`);
+  console.log("Installing to:", TARGET_DIR);
+  console.log("");
+
+  ensureDir(TARGET_DIR);
+
+  // Copy individual files
+  for (const file of FILES_TO_COPY) {
+    const src = path.join(SOURCE_DIR, file);
+    const dest = path.join(TARGET_DIR, file);
+    if (fs.existsSync(src)) {
+      copyFile(src, dest);
+      console.log("  Copied:", file);
+    }
+  }
+
+  // Copy directories
+  for (const dir of DIRS_TO_COPY) {
+    const src = path.join(SOURCE_DIR, dir);
+    const dest = path.join(TARGET_DIR, dir);
+    if (fs.existsSync(src)) {
+      copyDir(src, dest);
+      console.log("  Copied:", dir + "/");
+    }
+  }
+
+  console.log("");
+  console.log("Installation complete!");
+  console.log("Restart pi to load the extension.");
+  console.log("");
+}
+
+main();

package/form/index.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Interview</title>
+  <link rel="stylesheet" href="/styles.css?session=__SESSION_TOKEN__">
+  <link rel="stylesheet" href="/theme-light.css?session=__SESSION_TOKEN__" data-theme-link="light" media="(prefers-color-scheme: light)">
+  <link rel="stylesheet" href="/theme-dark.css?session=__SESSION_TOKEN__" data-theme-link="dark" media="(prefers-color-scheme: dark)">
+</head>
+<body>
+  <main class="interview-container">
+    <div class="session-bar">
+      <span class="session-project" id="session-project"></span>
+      <span class="session-id" id="session-id"></span>
+    </div>
+    <header class="interview-header">
+      <div class="header-row">
+        <h1 id="form-title"></h1>
+      </div>
+      <p id="form-description"></p>
+    </header>
+
+    <form id="interview-form" novalidate>
+      <div id="questions-container" role="list"></div>
+
+      <div id="error-container" aria-live="polite" class="error-message hidden"></div>
+
+      <footer class="form-footer">
+        <button type="submit" id="submit-btn" class="btn-primary">Submit</button>
+      </footer>
+    </form>
+
+    <nav class="shortcuts-bar" aria-label="Keyboard shortcuts">
+      <div class="shortcut">
+        <span class="shortcut-keys"><kbd>↑</kbd><kbd>↓</kbd> <kbd>Tab</kbd></span>
+        <span class="shortcut-label">Options</span>
+      </div>
+      <div class="shortcut">
+        <span class="shortcut-keys"><kbd>←</kbd><kbd>→</kbd></span>
+        <span class="shortcut-label">Questions</span>
+      </div>
+      <div class="shortcut-divider"></div>
+      <div class="shortcut">
+        <span class="shortcut-keys"><kbd>Enter</kbd> <kbd>Space</kbd></span>
+        <span class="shortcut-label">Select</span>
+      </div>
+      <div class="shortcut">
+        <span class="shortcut-keys"><kbd class="mod-key">⌘</kbd><kbd>Enter</kbd></span>
+        <span class="shortcut-label">Submit</span>
+      </div>
+      <div class="shortcut-divider"></div>
+      <div class="shortcut">
+        <span class="shortcut-keys"><kbd>Esc</kbd></span>
+        <span class="shortcut-label">Cancel</span>
+      </div>
+      <div class="shortcut-divider"></div>
+      <div class="shortcut recommended-hint">
+        <span class="shortcut-keys"><span class="star">*</span></span>
+        <span class="shortcut-label">Recommended</span>
+      </div>
+      <div class="shortcut hidden" data-theme-shortcut>
+        <span class="shortcut-keys" data-theme-keys></span>
+        <span class="shortcut-label">Theme</span>
+      </div>
+    </nav>
+
+    <div id="success-overlay" class="success-overlay hidden" aria-live="polite">
+      <div class="success-icon">OK</div>
+      <p>Responses submitted</p>
+    </div>
+
+    <div id="countdown-badge" class="countdown-badge hidden" aria-live="polite">
+      <svg class="countdown-ring" viewBox="0 0 36 36">
+        <circle class="countdown-ring-bg" cx="18" cy="18" r="16" />
+        <circle class="countdown-ring-progress" cx="18" cy="18" r="16" />
+      </svg>
+      <span class="countdown-value"></span>
+    </div>
+
+    <div id="queue-toast" class="queue-toast hidden" role="status" aria-live="polite">
+      <div class="queue-toast-header">
+        <span>Another interview started</span>
+        <button type="button" class="queue-toast-close" aria-label="Dismiss">×</button>
+      </div>
+      <div class="queue-toast-body">
+        <label class="queue-toast-label" for="queue-session-select">Switch to:</label>
+        <div class="queue-toast-controls">
+          <select id="queue-session-select" class="queue-toast-select"></select>
+          <button type="button" id="queue-open-btn" class="btn-secondary">Open</button>
+        </div>
+      </div>
+    </div>
+
+    <div id="expired-overlay" class="expired-overlay hidden" aria-live="polite">
+      <div class="expired-content">
+        <div class="expired-icon">!</div>
+        <h2>Session Ended</h2>
+        <p>The interview session has timed out. Your responses are saved locally and will be restored if restarted.</p>
+        <div class="expired-countdown">Closing in <span id="close-countdown">10</span>s</div>
+        <div class="expired-actions">
+          <button type="button" id="stay-btn" class="btn-primary">Stay Here</button>
+          <button type="button" id="close-tab-btn" class="btn-secondary">Close Now</button>
+        </div>
+        <div class="expired-shortcuts">
+          <span><kbd>Enter</kbd> Confirm</span>
+          <span><kbd>Tab</kbd> Switch</span>
+          <span><kbd>Esc</kbd> Close</span>
+        </div>
+      </div>
+    </div>
+  </main>
+
+  <script>
+    window.__INTERVIEW_DATA__ = /* __INTERVIEW_DATA_PLACEHOLDER__ */;
+  </script>
+  <script src="/script.js?session=__SESSION_TOKEN__"></script>
+</body>
+</html>