iriai-build 0.1.0

package/v3/review-sessions.js

@@ -0,0 +1,360 @@
+// review-sessions.js — Manages interactive review tool sessions for decisions.
+// Loosely coupled: uses iriai-feedback CLI (child_process.spawn) + HTTP API.
+// No direct imports from iriai-feedback.
+
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { get as httpGet } from "node:http";
+import { readFile } from "node:fs/promises";
+import * as queries from "./queries.js";
+import { get as configGet } from "../cli/config.js";
+
+const QA_FEEDBACK_BIN = configGet("qa_feedback_bin", "QA_FEEDBACK_BIN") || "iriai-feedback";
+const PORT_MIN = 9001;
+const PORT_MAX = 9020;
+
+export class ReviewSessionManager {
+  constructor() {
+    this._sessions = new Map(); // decisionId -> { sessionId, url, port, process, type, qa? }
+    this._nextPort = PORT_MIN;
+  }
+
+  _allocPort() {
+    const usedPorts = new Set(
+      [...this._sessions.values()].flatMap(s =>
+        [s.port, s.qa?.port].filter(Boolean)
+      )
+    );
+    let port = this._nextPort;
+    while (usedPorts.has(port)) {
+      port = port >= PORT_MAX ? PORT_MIN : port + 1;
+    }
+    this._nextPort = port >= PORT_MAX ? PORT_MIN : port + 1;
+    return port;
+  }
+
+  /**
+   * Start a doc review session for a decision.
+   * Spawns `iriai-feedback review <docPath> --port <port>`.
+   * Returns the review URL.
+   */
+  async startDocReview(decisionId, docPath, title, { featureId, port: preferredPort } = {}) {
+    const port = preferredPort || this._allocPort();
+    const args = ["review", docPath, "--port", String(port)];
+    if (title) args.push("--title", title);
+
+    try {
+      const { proc, sessionId } = await this._spawnAndParse(args);
+      const url = `http://localhost:${port}/doc-review`;
+      this._sessions.set(decisionId, { sessionId, url, port, process: proc, type: "doc", docPath });
+
+      // Persist to SQLite for restart recovery
+      if (featureId) {
+        queries.insertReviewSession({
+          decisionId, featureId, sessionId, port, docPath, type: "doc",
+        });
+      }
+
+      return url;
+    } catch (err) {
+      console.error(`[review-sessions] Failed to start doc review for ${decisionId}:`, err.message);
+      return null;
+    }
+  }
+
+  /**
+   * Start a mockup review session — serves an HTML file via a static server,
+   * then wraps it with the QA feedback proxy (screenshot + annotation overlay).
+   * Returns the QA proxy URL.
+   */
+  async startMockupReview(decisionId, htmlPath, { featureId } = {}) {
+    // 1. Spin up a tiny static file server for the HTML mockup
+    const staticPort = this._allocPort();
+    const staticServer = await this._startStaticServer(htmlPath, staticPort);
+
+    // 2. Wrap it with QA proxy
+    const qaUrl = await this.startQaSession(decisionId, `http://localhost:${staticPort}`, {
+      featureId,
+    });
+
+    if (!qaUrl) {
+      staticServer.close();
+      return null;
+    }
+
+    // Track the static server so we can kill it on stop()
+    const session = this._sessions.get(decisionId);
+    if (session) {
+      session._staticServer = staticServer;
+      session._staticPort = staticPort;
+      session.docPath = htmlPath;
+      session.type = "mockup";
+    }
+
+    // Persist as mockup type for restore
+    if (featureId) {
+      queries.insertReviewSession({
+        decisionId, featureId, sessionId: session?.sessionId || `mockup-${Date.now()}`,
+        port: session?.qa?.port || staticPort, docPath: htmlPath, type: "mockup",
+      });
+    }
+
+    return qaUrl;
+  }
+
+  /**
+   * Start a minimal static file server that serves a single HTML file at /.
+   */
+  _startStaticServer(htmlPath, port) {
+    return new Promise((resolve, reject) => {
+      const server = createServer(async (req, res) => {
+        try {
+          const content = await readFile(htmlPath, "utf-8");
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end(content);
+        } catch {
+          res.writeHead(404);
+          res.end("Not found");
+        }
+      });
+      server.listen(port, () => resolve(server));
+      server.on("error", reject);
+    });
+  }
+
+  /**
+   * Start a QA session (reverse proxy) for a running app.
+   * Spawns `iriai-feedback start <targetUrl> --port <port>`.
+   * Attaches to an existing decision entry if one exists.
+   */
+  async startQaSession(decisionId, targetUrl, { featureId, port: preferredPort } = {}) {
+    const port = preferredPort || this._allocPort();
+    const args = ["start", targetUrl, "--port", String(port)];
+
+    try {
+      const { proc, sessionId } = await this._spawnAndParse(args);
+      const qaUrl = `http://localhost:${port}`;
+      const existing = this._sessions.get(decisionId);
+
+      if (existing) {
+        existing.qa = { sessionId, url: qaUrl, port, process: proc };
+      } else {
+        this._sessions.set(decisionId, {
+          sessionId, url: qaUrl, port, process: proc, type: "qa",
+        });
+      }
+
+      // Persist QA session info
+      if (featureId) {
+        queries.updateReviewSessionQa(decisionId, { qaSessionId: sessionId, qaPort: port, qaTargetUrl: targetUrl });
+      }
+
+      return qaUrl;
+    } catch (err) {
+      console.error(`[review-sessions] Failed to start QA session for ${decisionId}:`, err.message);
+      return null;
+    }
+  }
+
+  /**
+   * Collect annotations from all active review servers for a decision.
+   * Returns array of annotations or null if none.
+   */
+  async collectFeedback(decisionId) {
+    const session = this._sessions.get(decisionId);
+    if (!session) return null;
+
+    const annotations = [];
+    if (session.port) {
+      const anns = await this._httpGetJson(session.port, "/__qa__/api/annotations");
+      if (anns && Array.isArray(anns)) annotations.push(...anns);
+    }
+    if (session.qa?.port) {
+      const anns = await this._httpGetJson(session.qa.port, "/__qa__/api/annotations");
+      if (anns && Array.isArray(anns)) annotations.push(...anns);
+    }
+
+    return annotations.length > 0 ? annotations : null;
+  }
+
+  /**
+   * Stop a review session: kill processes, remove from map and SQLite.
+   */
+  async stop(decisionId) {
+    const session = this._sessions.get(decisionId);
+    if (!session) return;
+
+    this._killProc(session.process);
+    if (session.qa) this._killProc(session.qa.process);
+    if (session._staticServer) {
+      try { session._staticServer.close(); } catch { /* ok */ }
+    }
+    this._sessions.delete(decisionId);
+
+    // Clean up SQLite
+    queries.deleteReviewSession(decisionId);
+  }
+
+  /**
+   * Stop all active review sessions. Called on shutdown.
+   */
+  async stopAll() {
+    for (const [id] of this._sessions) {
+      await this.stop(id);
+    }
+  }
+
+  /**
+   * Re-spawn review sessions from SQLite on restart.
+   * Called during recovery for features with pending decisions.
+   */
+  async restoreSession(decisionId) {
+    const row = queries.getReviewSession(decisionId);
+    if (!row) return null;
+
+    // Mockup sessions: restore via QA proxy (not doc-review)
+    if (row.type === "mockup" && row.doc_path) {
+      return this.startMockupReview(decisionId, row.doc_path, {
+        featureId: row.feature_id,
+      });
+    }
+
+    // Re-spawn the doc review server with the same port and doc path
+    const url = await this.startDocReview(decisionId, row.doc_path, null, {
+      featureId: row.feature_id,
+      port: row.port,
+    });
+
+    // Re-spawn QA session if one was active
+    if (row.qa_target_url && row.qa_port) {
+      await this.startQaSession(decisionId, row.qa_target_url, {
+        featureId: row.feature_id,
+        port: row.qa_port,
+      });
+    }
+
+    return url;
+  }
+
+  /**
+   * Check if a decision has an active review session.
+   */
+  hasSession(decisionId) {
+    return this._sessions.has(decisionId);
+  }
+
+  // ─── Internal helpers ────────────────────────────────────────────────
+
+  /**
+   * Spawn the iriai-feedback CLI and parse stdout for session info.
+   * Expects the CLI to print a line like: "Session: <id>" and "URL: <url>"
+   * within the first few seconds of output.
+   */
+  _spawnAndParse(args) {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(QA_FEEDBACK_BIN, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: false,
+      });
+
+      let stdout = "";
+      let resolved = false;
+
+      const timer = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          // Even if we didn't parse a session ID, the server may be running
+          resolve({ proc, sessionId: `session-${Date.now()}` });
+        }
+      }, 5000);
+
+      proc.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+        // Wait for both session ID and URL confirmation (server is listening)
+        // CLI outputs: "Doc review session <id> started\nReview: http://..."
+        // or: "QA session <id> started\nLocal: http://..."
+        const sessionMatch = stdout.match(/[Ss]ession\s+(\S+)\s+started/);
+        const urlReady = /(?:Review|Local):\s+http/i.test(stdout);
+        if (sessionMatch && urlReady && !resolved) {
+          resolved = true;
+          clearTimeout(timer);
+          resolve({ proc, sessionId: sessionMatch[1] });
+        }
+      });
+
+      proc.on("error", (err) => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timer);
+          reject(err);
+        }
+      });
+
+      proc.on("exit", (code) => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timer);
+          reject(new Error(`iriai-feedback exited with code ${code} before producing session ID`));
+        }
+      });
+    });
+  }
+
+  /**
+   * Simple HTTP GET returning parsed JSON.
+   */
+  _httpGetJson(port, urlPath) {
+    return new Promise((resolve) => {
+      const req = httpGet(`http://localhost:${port}${urlPath}`, (res) => {
+        let data = "";
+        res.on("data", (chunk) => { data += chunk; });
+        res.on("end", () => {
+          try {
+            resolve(JSON.parse(data));
+          } catch {
+            resolve(null);
+          }
+        });
+      });
+      req.on("error", () => resolve(null));
+      req.setTimeout(3000, () => { req.destroy(); resolve(null); });
+    });
+  }
+
+  _killProc(proc) {
+    if (!proc) return;
+    try {
+      proc.kill("SIGINT");
+    } catch {
+      // Process may already be dead
+    }
+  }
+}
+
+/**
+ * Format structured annotations into readable feedback text for agents.
+ */
+export function formatAnnotationsAsFeedback(annotations, userComment) {
+  const parts = [];
+
+  if (annotations && annotations.length > 0) {
+    parts.push("## User Annotations (from interactive review)");
+    for (let i = 0; i < annotations.length; i++) {
+      const ann = annotations[i];
+      const location = ann.line
+        ? `[Line ${ann.line}]`
+        : ann.section
+          ? `[Section: ${ann.section}]`
+          : "[General]";
+      parts.push(`${i + 1}. ${location} "${ann.text || ann.comment || ann.content || ""}"`);
+    }
+  }
+
+  if (userComment) {
+    parts.push("");
+    parts.push("## User Comment");
+    parts.push(userComment);
+  }
+
+  return parts.join("\n");
+}

package/v3/roles/accessibility-auditor/CLAUDE.md

@@ -0,0 +1,50 @@
+# Accessibility Auditor
+
+You are the Accessibility Auditor. You verify WCAG compliance and usability for assistive technologies. You assume the UI is inaccessible until proven otherwise.
+
+## Constraints
+- NEVER modify source code — report findings only
+- Check keyboard navigation, screen reader behavior, color contrast, focus management
+- Every interactive element needs an accessible name
+- Dynamic content changes need ARIA live regions
+- Modals/dialogs need proper focus trapping
+
+## Adversarial Stance
+Assume the UI is inaccessible. Check: missing alt text, unlabeled inputs, broken tab order, missing ARIA attributes, insufficient contrast, missing focus indicators. If you can't verify accessibility, it fails.
+
+## Input
+Your task arrives as a `.task` file with YAML frontmatter:
+- `review_focus` — accessibility-critical areas
+- `scope.read` — component files to audit
+
+## Output
+Write a structured verdict to `.output` with YAML frontmatter:
+```yaml
+task_id: [id]
+role: accessibility-auditor
+verdict: PASS|FAIL|CONDITIONAL
+summary_oneliner: "[counts]"
+checks:
+  - criterion: "[WCAG criterion]"
+    result: PASS|FAIL
+    detail: "[evidence]"
+issues:
+  - severity: blocker|major|minor|nit
+    description: "[accessibility issue]"
+    file: "[path]"
+    line: [number]
+duration_seconds: [elapsed]
+```
+Then signal completion: `echo DONE > .done`
+
+
+## Context Management — MANDATORY
+
+**Read:** `reference/context-management.md` for the full protocol.
+
+Monitor your context usage. **At 40% context remaining, you MUST:**
+1. Stop all current work — do not start new operations
+2. Write a structured `.handover` file to your signal directory with: completed work, current state, remaining work, files modified, and key decisions
+3. Signal: `echo "context_threshold" > $SIGNAL_DIR/.needs-restart`
+
+Do NOT try to finish "one more thing." Do NOT signal `.done` — the task is not done. The wrapper script will restart you with your handover context preserved. A premature handover costs 30 seconds. A late handover costs all your work.

package/v3/roles/analytics-engineer/CLAUDE.md

@@ -0,0 +1,40 @@
+# Analytics Engineer
+
+You are the Analytics Engineer. You add instrumentation and metrics tracking to new features.
+
+## Constraints
+- ONLY modify files listed in `scope.modify`
+- Track business events (user actions), not implementation details
+- Event names: `snake_case`, namespaced by feature (e.g., `bot_collaborator.invited`)
+- Include relevant context in event properties (user_id, app_id) but NEVER PII
+- Use existing analytics patterns in the codebase — don't introduce new libraries
+
+## Input
+Your task arrives as a `.task` file with YAML frontmatter:
+- `scope.modify` — only touch these files
+- `acceptance.user_criteria` — what events to track
+- `context_files` — existing analytics patterns to follow
+
+## Output
+Write a structured summary to `.output` with YAML frontmatter:
+```yaml
+task_id: [id]
+role: analytics-engineer
+summary_oneliner: "[one line]"
+files_created: [list]
+files_modified: [list]
+duration_seconds: [elapsed]
+```
+Then signal completion: `echo DONE > .done`
+
+
+## Context Management — MANDATORY
+
+**Read:** `reference/context-management.md` for the full protocol.
+
+Monitor your context usage. **At 40% context remaining, you MUST:**
+1. Stop all current work — do not start new operations
+2. Write a structured `.handover` file to your signal directory with: completed work, current state, remaining work, files modified, and key decisions
+3. Signal: `echo "context_threshold" > $SIGNAL_DIR/.needs-restart`
+
+Do NOT try to finish "one more thing." Do NOT signal `.done` — the task is not done. The wrapper script will restart you with your handover context preserved. A premature handover costs 30 seconds. A late handover costs all your work.