supipowers 0.2.7 → 0.4.0

package/src/qa/session.ts

@@ -0,0 +1,104 @@
+import type { QaPhase, QaPhaseStatus, QaSessionLedger, QaTestCase, QaTestResult } from "../types.js";
+import { generateSessionId, createSession, updateSession } from "../storage/qa-sessions.js";
+
+const PHASE_ORDER: QaPhase[] = ["discovery", "matrix", "execution", "reporting"];
+
+/** Create a new QA session with all phases pending */
+export function createNewSession(cwd: string, framework: string): QaSessionLedger {
+  const now = new Date().toISOString();
+  const ledger: QaSessionLedger = {
+    id: generateSessionId(),
+    createdAt: now,
+    updatedAt: now,
+    framework,
+    phases: {
+      discovery: { status: "pending" },
+      matrix: { status: "pending" },
+      execution: { status: "pending" },
+      reporting: { status: "pending" },
+    },
+    tests: [],
+    matrix: [],
+    results: [],
+  };
+  createSession(cwd, ledger);
+  return ledger;
+}
+
+/** Update a phase's status and timestamps, persist to disk */
+export function advancePhase(
+  cwd: string,
+  ledger: QaSessionLedger,
+  phase: QaPhase,
+  status: QaPhaseStatus
+): QaSessionLedger {
+  const now = new Date().toISOString();
+  const record = { ...ledger.phases[phase] };
+
+  record.status = status;
+  if (status === "running" && !record.startedAt) {
+    record.startedAt = now;
+  }
+  if (status === "completed" || status === "failed") {
+    record.completedAt = now;
+  }
+
+  const updated: QaSessionLedger = {
+    ...ledger,
+    updatedAt: now,
+    phases: { ...ledger.phases, [phase]: record },
+  };
+  updateSession(cwd, updated);
+  return updated;
+}
+
+/** Merge new test results into the ledger, upserting by testId */
+export function mergeTestResults(
+  ledger: QaSessionLedger,
+  newResults: QaTestResult[]
+): QaSessionLedger {
+  const resultMap = new Map(ledger.results.map((r) => [r.testId, r]));
+
+  for (const incoming of newResults) {
+    const existing = resultMap.get(incoming.testId);
+    if (existing) {
+      resultMap.set(incoming.testId, {
+        ...incoming,
+        retryCount: existing.retryCount + 1,
+      });
+    } else {
+      resultMap.set(incoming.testId, incoming);
+    }
+  }
+
+  return {
+    ...ledger,
+    updatedAt: new Date().toISOString(),
+    results: Array.from(resultMap.values()),
+  };
+}
+
+/** Get test cases whose latest result is "fail" */
+export function getFailedTests(ledger: QaSessionLedger): QaTestCase[] {
+  const failedIds = new Set(
+    ledger.results.filter((r) => r.status === "fail").map((r) => r.testId)
+  );
+  return ledger.tests.filter((t) => failedIds.has(t.id));
+}
+
+/** Get the next phase that is not completed */
+export function getNextPhase(ledger: QaSessionLedger): QaPhase | null {
+  for (const phase of PHASE_ORDER) {
+    if (ledger.phases[phase].status !== "completed") return phase;
+  }
+  return null;
+}
+
+/** Format phase status for TUI display */
+export function getPhaseStatusLine(ledger: QaSessionLedger): string {
+  return PHASE_ORDER.map((phase) => {
+    const label = phase.charAt(0).toUpperCase() + phase.slice(1);
+    const done = ledger.phases[phase].status === "completed";
+    return done ? `[done] ${label}` : `[ ] ${label}`;
+  }).join(" · ");
+}

package/src/storage/fix-pr-sessions.ts

@@ -0,0 +1,59 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { FixPrSessionLedger } from "../fix-pr/types.js";
+
+const SESSIONS_DIR = "fix-pr-sessions";
+
+function getBaseDir(cwd: string): string {
+  return path.join(cwd, ".omp", "supipowers", SESSIONS_DIR);
+}
+
+export function getSessionDir(cwd: string, sessionId: string): string {
+  return path.join(getBaseDir(cwd), sessionId);
+}
+
+export function generateFixPrSessionId(): string {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const time = now.toTimeString().slice(0, 8).replace(/:/g, "");
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `fpr-${date}-${time}-${rand}`;
+}
+
+export function createFixPrSession(cwd: string, ledger: FixPrSessionLedger): void {
+  const sessionDir = getSessionDir(cwd, ledger.id);
+  fs.mkdirSync(path.join(sessionDir, "snapshots"), { recursive: true });
+  fs.writeFileSync(path.join(sessionDir, "ledger.json"), JSON.stringify(ledger, null, 2));
+}
+
+export function loadFixPrSession(cwd: string, sessionId: string): FixPrSessionLedger | null {
+  const ledgerPath = path.join(getSessionDir(cwd, sessionId), "ledger.json");
+  if (!fs.existsSync(ledgerPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(ledgerPath, "utf-8")) as FixPrSessionLedger;
+  } catch {
+    return null;
+  }
+}
+
+export function updateFixPrSession(cwd: string, ledger: FixPrSessionLedger): void {
+  const ledgerPath = path.join(getSessionDir(cwd, ledger.id), "ledger.json");
+  ledger.updatedAt = new Date().toISOString();
+  fs.writeFileSync(ledgerPath, JSON.stringify(ledger, null, 2));
+}
+
+export function findActiveFixPrSession(cwd: string): FixPrSessionLedger | null {
+  const baseDir = getBaseDir(cwd);
+  if (!fs.existsSync(baseDir)) return null;
+
+  const dirs = fs.readdirSync(baseDir)
+    .filter((d) => d.startsWith("fpr-"))
+    .sort()
+    .reverse();
+
+  for (const dir of dirs) {
+    const ledger = loadFixPrSession(cwd, dir);
+    if (ledger && ledger.status === "running") return ledger;
+  }
+  return null;
+}

package/src/storage/qa-sessions.ts

@@ -0,0 +1,83 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { QaSessionLedger } from "../types.js";
+
+const SESSIONS_DIR = [".omp", "supipowers", "qa-sessions"];
+
+function getSessionsDir(cwd: string): string {
+  return path.join(cwd, ...SESSIONS_DIR);
+}
+
+function getSessionDir(cwd: string, sessionId: string): string {
+  return path.join(getSessionsDir(cwd), sessionId);
+}
+
+/** Generate a unique QA session ID */
+export function generateSessionId(): string {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const time = now.toISOString().slice(11, 19).replace(/:/g, "");
+  const suffix = Math.random().toString(36).slice(2, 6);
+  return `qa-${date}-${time}-${suffix}`;
+}
+
+/** Create a new QA session */
+export function createSession(cwd: string, ledger: QaSessionLedger): void {
+  const sessionDir = getSessionDir(cwd, ledger.id);
+  fs.mkdirSync(sessionDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessionDir, "ledger.json"),
+    JSON.stringify(ledger, null, 2) + "\n"
+  );
+}
+
+/** Load a QA session ledger */
+export function loadSession(cwd: string, sessionId: string): QaSessionLedger | null {
+  const filePath = path.join(getSessionDir(cwd, sessionId), "ledger.json");
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Update a QA session ledger */
+export function updateSession(cwd: string, ledger: QaSessionLedger): void {
+  const filePath = path.join(getSessionDir(cwd, ledger.id), "ledger.json");
+  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2) + "\n");
+}
+
+/** List all QA sessions, newest first */
+export function listSessions(cwd: string): string[] {
+  const dir = getSessionsDir(cwd);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.startsWith("qa-"))
+    .sort()
+    .reverse();
+}
+
+/** Find the latest session with incomplete phases */
+export function findActiveSession(cwd: string): QaSessionLedger | null {
+  for (const sessionId of listSessions(cwd)) {
+    const ledger = loadSession(cwd, sessionId);
+    if (!ledger) continue;
+    const allCompleted = Object.values(ledger.phases).every(
+      (p) => p.status === "completed"
+    );
+    if (!allCompleted) return ledger;
+  }
+  return null;
+}
+
+/** Find the latest session with failed test results */
+export function findSessionWithFailures(cwd: string): QaSessionLedger | null {
+  for (const sessionId of listSessions(cwd)) {
+    const ledger = loadSession(cwd, sessionId);
+    if (!ledger) continue;
+    if (ledger.results.some((r) => r.status === "fail")) return ledger;
+  }
+  return null;
+}

package/src/storage/specs.ts

@@ -0,0 +1,36 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const SPECS_DIR = ["docs", "supipowers", "specs"];
+
+/** Get the specs directory path */
+export function getSpecsDir(cwd: string): string {
+  return path.join(cwd, ...SPECS_DIR);
+}
+
+/** Save a spec markdown file */
+export function saveSpec(cwd: string, filename: string, content: string): string {
+  const dir = getSpecsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, filename);
+  fs.writeFileSync(filePath, content);
+  return filePath;
+}
+
+/** Read a spec file by name */
+export function readSpec(cwd: string, name: string): string | null {
+  const filePath = path.join(getSpecsDir(cwd), name);
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, "utf-8");
+}
+
+/** List all spec files, newest first */
+export function listSpecs(cwd: string): string[] {
+  const dir = getSpecsDir(cwd);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .sort()
+    .reverse();
+}

package/src/types.ts

@@ -124,6 +124,76 @@ export interface SupipowersConfig {
   };
 }
 
+// ── QA Session Management ──────────────────────────────────────────
+
+/** QA pipeline phase */
+export type QaPhase = "discovery" | "matrix" | "execution" | "reporting";
+
+/** Phase completion status */
+export type QaPhaseStatus = "pending" | "running" | "completed" | "failed";
+
+/** Per-test result status */
+export type TestResultStatus = "pass" | "fail" | "skip";
+
+/** A discovered test case */
+export interface QaTestCase {
+  id: string;
+  filePath: string;
+  testName: string;
+  suiteName?: string;
+  tags?: string[];
+}
+
+/** Traceability matrix entry — one requirement mapped to its tests */
+export interface QaMatrixEntry {
+  requirement: string;
+  testIds: string[];
+  platforms?: string[];
+  coverage: "full" | "partial" | "none";
+}
+
+/** Per-test execution result */
+export interface QaTestResult {
+  testId: string;
+  status: TestResultStatus;
+  duration?: number;
+  error?: string;
+  retryCount: number;
+  lastRunAt: string;
+}
+
+/** Report summary generated in the Reporting phase */
+export interface QaReportSummary {
+  generatedAt: string;
+  total: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  passRate: number;
+  failedTests: { testId: string; testName: string; error?: string }[];
+  coverageSummary?: string;
+}
+
+/** Phase record within a session */
+export interface QaPhaseRecord {
+  status: QaPhaseStatus;
+  startedAt?: string;
+  completedAt?: string;
+}
+
+/** The full QA session ledger */
+export interface QaSessionLedger {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  framework: string;
+  phases: Record<QaPhase, QaPhaseRecord>;
+  tests: QaTestCase[];
+  matrix: QaMatrixEntry[];
+  results: QaTestResult[];
+  report?: QaReportSummary;
+}
+
 /** Profile shape */
 export interface Profile {
   name: string;

package/src/visual/companion.ts

@@ -0,0 +1,115 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { VisualServerInfo, VisualEvent } from "./types.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const VISUAL_DIR = [".omp", "supipowers", "visual"];
+
+/** Generate a unique visual session ID */
+export function generateVisualSessionId(): string {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const time = now.toISOString().slice(11, 19).replace(/:/g, "");
+  const suffix = Math.random().toString(36).slice(2, 6);
+  return `visual-${date}-${time}-${suffix}`;
+}
+
+/** Create the session directory and return its path */
+export function createSessionDir(cwd: string, sessionId: string): string {
+  const sessionDir = path.join(cwd, ...VISUAL_DIR, sessionId);
+  fs.mkdirSync(sessionDir, { recursive: true });
+  return sessionDir;
+}
+
+/** Write an HTML screen to the session directory */
+export function writeScreen(sessionDir: string, filename: string, html: string): void {
+  fs.writeFileSync(path.join(sessionDir, filename), html);
+}
+
+/** Read user events from the .events file */
+export function readEvents(sessionDir: string): VisualEvent[] {
+  const eventsFile = path.join(sessionDir, ".events");
+  if (!fs.existsSync(eventsFile)) return [];
+
+  const content = fs.readFileSync(eventsFile, "utf-8");
+  const events: VisualEvent[] = [];
+
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // Skip invalid lines
+    }
+  }
+
+  return events;
+}
+
+/** Clear the events file */
+export function clearEvents(sessionDir: string): void {
+  const eventsFile = path.join(sessionDir, ".events");
+  if (fs.existsSync(eventsFile)) {
+    fs.unlinkSync(eventsFile);
+  }
+}
+
+/** Get the path to the scripts directory */
+export function getScriptsDir(): string {
+  return path.join(__dirname, "scripts");
+}
+
+/** Parse server info from start-server.sh JSON output */
+export function parseServerInfo(stdout: string): VisualServerInfo | null {
+  for (const line of stdout.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const data = JSON.parse(line);
+      if (data.type === "server-started") {
+        return {
+          port: data.port,
+          host: data.host,
+          url: data.url,
+          screenDir: data.screen_dir,
+        };
+      }
+    } catch {
+      // Skip non-JSON lines
+    }
+  }
+  return null;
+}
+
+/** Check if a server is running for the given session dir */
+export function isServerRunning(sessionDir: string): boolean {
+  const pidFile = path.join(sessionDir, ".server.pid");
+  if (!fs.existsSync(pidFile)) return false;
+
+  try {
+    const pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10);
+    process.kill(pid, 0); // signal 0 = check existence
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Read server info from .server-info file */
+export function readServerInfo(sessionDir: string): VisualServerInfo | null {
+  const infoFile = path.join(sessionDir, ".server-info");
+  if (!fs.existsSync(infoFile)) return null;
+
+  try {
+    const data = JSON.parse(fs.readFileSync(infoFile, "utf-8").trim());
+    return {
+      port: data.port,
+      host: data.host,
+      url: data.url,
+      screenDir: data.screen_dir,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/visual/prompt-instructions.ts

@@ -0,0 +1,102 @@
+/**
+ * Build the visual companion instruction block to append to sub-agent prompts.
+ * Tells the agent how to write HTML screens, what CSS classes are available,
+ * and how to read user interaction events.
+ */
+export function buildVisualInstructions(url: string, sessionDir: string): string {
+  const fence = "```";
+
+  const sections: string[] = [
+    "## Visual Companion Active",
+    "",
+    `A browser companion is running at ${url}. The user can see visual content there.`,
+    "",
+    "### When to Use Browser vs Terminal",
+    "",
+    "- **Use the browser** for content that IS visual: mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs, A/B/C option cards, pros/cons tables",
+    "- **Use the terminal** for content that is text: requirements questions, conceptual choices, discussion, final plan output",
+    "",
+    "A question about a UI topic is not automatically a visual question. Conceptual questions go to the terminal. Visual comparisons go to the browser.",
+    "",
+    "### How to Write HTML Screens",
+    "",
+    `Write HTML fragment files to \`${sessionDir}/\` with descriptive filenames:`,
+    "- `screen-001-approaches.html`",
+    "- `screen-002-architecture.html`",
+    "",
+    "The server auto-wraps fragments in a styled frame with dark/light theme support. You do NOT need to write full HTML documents — just the content inside `<body>`.",
+    "",
+    "### Available CSS Classes",
+    "",
+    "Your HTML fragments can use these classes (provided by the frame template):",
+    "",
+    "**Choices (A/B/C options):**",
+    "- `.options` > `.option[data-choice=\"x\"]` with `.letter` + `.content` children",
+    "",
+    `${fence}html`,
+    '<div class="options">',
+    '  <div class="option" data-choice="a" onclick="toggleSelect(this)">',
+    '    <div class="letter">A</div>',
+    '    <div class="content">',
+    "      <h3>Option Title</h3>",
+    "      <p>Description text</p>",
+    "    </div>",
+    "  </div>",
+    "</div>",
+    fence,
+    "",
+    "**Cards (grid layout, multi-select with `data-multiselect`):**",
+    '- `.cards` > `.card[data-choice="x"]` with `.card-image` + `.card-body`',
+    "",
+    "**Mockup containers:**",
+    "- `.mockup` > `.mockup-header` + `.mockup-body`",
+    "",
+    "**Side-by-side comparison:**",
+    "- `.split` — two-column grid (responsive)",
+    "",
+    "**Pros/Cons:**",
+    "- `.pros-cons` > `.pros` + `.cons` — color-coded green/red headers",
+    "",
+    "**Placeholders:**",
+    "- `.placeholder` — dashed border boxes for areas to be filled",
+    "",
+    "**Mock UI elements:**",
+    "- `.mock-nav`, `.mock-sidebar`, `.mock-content`, `.mock-button`, `.mock-input`",
+    "",
+    "**Typography:**",
+    "- `h2` (page title), `h3` (section heading), `.subtitle`, `.label`, `.section`",
+    "",
+    "### Example Screen",
+    "",
+    `${fence}html`,
+    '<h2>Architecture Approach</h2>',
+    '<p class="subtitle">Choose the approach that best fits your needs</p>',
+    '<div class="options">',
+    '  <div class="option" data-choice="monolith" onclick="toggleSelect(this)">',
+    '    <div class="letter">A</div>',
+    '    <div class="content">',
+    "      <h3>Monolith</h3>",
+    "      <p>Single service, simpler deployment</p>",
+    "    </div>",
+    "  </div>",
+    '  <div class="option" data-choice="microservices" onclick="toggleSelect(this)">',
+    '    <div class="letter">B</div>',
+    '    <div class="content">',
+    "      <h3>Microservices</h3>",
+    "      <p>Distributed, independently scalable</p>",
+    "    </div>",
+    "  </div>",
+    "</div>",
+    fence,
+    "",
+    "### Reading User Choices",
+    "",
+    "When you present choices in the browser, the user clicks `[data-choice]` elements.",
+    `Read \`${sessionDir}/.events\` to see their selections (newline-delimited JSON).`,
+    'Each event: `{ "type": "click", "choice": "a", "text": "Option Title", "timestamp": 1234 }`',
+    "",
+    "After presenting a visual screen, tell the user to check their browser and respond in the terminal. Then read the .events file to see what they clicked.",
+  ];
+
+  return sections.join("\n");
+}