tmux-ide 1.2.1 → 2.0.0

package/src/lib/tunnels/types.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+
+/** Shared status shape for tunnel providers (Tailscale Serve, ngrok, Cloudflare Quick Tunnel). */
+export type TunnelStatus = {
+  running: boolean;
+  publicUrl?: string | null;
+  port?: number;
+  lastError?: string;
+  /** Provider-specific fields (funnel, mode, etc.) */
+  meta?: Record<string, unknown>;
+};
+
+/**
+ * Common surface for tunnel integrations (see `tailscale.ts`, `ngrok.ts`, `cloudflare.ts`).
+ * Concrete classes may take additional constructor arguments (port, auth, etc.).
+ */
+export interface TunnelService {
+  start(...args: unknown[]): Promise<unknown>;
+  stop(): Promise<void>;
+  status(): Promise<TunnelStatus>;
+}
+
+export const tunnelConfigSchema = z.discriminatedUnion("provider", [
+  z.object({
+    provider: z.literal("tailscale"),
+    port: z.number().int().positive(),
+    enableFunnel: z.boolean().optional(),
+  }),
+  z.object({
+    provider: z.literal("ngrok"),
+    port: z.number().int().positive(),
+    authToken: z.string().optional(),
+    domain: z.string().optional(),
+    region: z.string().optional(),
+    startupTimeoutMs: z.number().positive().optional(),
+  }),
+  z.object({
+    provider: z.literal("cloudflare"),
+    port: z.number().int().positive(),
+    startupTimeoutMs: z.number().positive().optional(),
+  }),
+]);
+
+export type TunnelConfig = z.infer<typeof tunnelConfigSchema>;

package/src/lib/validation.test.ts

@@ -0,0 +1,289 @@
+import { describe, it, beforeEach, afterEach, expect } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  loadValidationContract,
+  loadValidationState,
+  saveValidationState,
+  isAllPassing,
+  getFailedAssertions,
+  parseAssertionIds,
+  checkCoverage,
+  type ValidationState,
+} from "./validation.ts";
+import { ensureTasksDir, saveTask } from "./task-store.ts";
+import { makeTask } from "../__tests__/support.ts";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "tmux-ide-validation-test-"));
+  mkdirSync(join(tmpDir, ".tasks"), { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("loadValidationContract", () => {
+  it("returns null when file does not exist", () => {
+    expect(loadValidationContract(tmpDir)).toBeNull();
+  });
+
+  it("reads the contract file", () => {
+    writeFileSync(join(tmpDir, ".tasks", "validation-contract.md"), "# Contract\n- [A1] test");
+    expect(loadValidationContract(tmpDir)).toBe("# Contract\n- [A1] test");
+  });
+});
+
+describe("loadValidationState / saveValidationState", () => {
+  it("returns null when file does not exist", () => {
+    expect(loadValidationState(tmpDir)).toBeNull();
+  });
+
+  it("round-trips state", () => {
+    const state: ValidationState = {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: "agent-1",
+          verifiedAt: "2026-01-01T00:00:00Z",
+          evidence: "tests pass",
+          blockedBy: null,
+        },
+        A2: {
+          status: "failing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+      },
+      lastVerified: "2026-01-01T00:00:00Z",
+    };
+    saveValidationState(tmpDir, state);
+    const loaded = loadValidationState(tmpDir);
+    expect(loaded).toEqual(state);
+  });
+
+  it("returns null for corrupted file", () => {
+    writeFileSync(join(tmpDir, ".tasks", "validation-state.json"), "not json");
+    expect(loadValidationState(tmpDir)).toBeNull();
+  });
+});
+
+describe("isAllPassing", () => {
+  it("returns true when all assertions pass", () => {
+    const state: ValidationState = {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+        A2: {
+          status: "passing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+      },
+      lastVerified: null,
+    };
+    expect(isAllPassing(state)).toBe(true);
+  });
+
+  it("returns false when any assertion is not passing", () => {
+    const state: ValidationState = {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+        A2: {
+          status: "pending",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+      },
+      lastVerified: null,
+    };
+    expect(isAllPassing(state)).toBe(false);
+  });
+
+  it("returns false for empty assertions", () => {
+    expect(isAllPassing({ assertions: {}, lastVerified: null })).toBe(false);
+  });
+});
+
+describe("getFailedAssertions", () => {
+  it("returns IDs of failing assertions", () => {
+    const state: ValidationState = {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+        A2: {
+          status: "failing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+        A3: {
+          status: "failing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+      },
+      lastVerified: null,
+    };
+    expect(getFailedAssertions(state)).toEqual(["A2", "A3"]);
+  });
+
+  it("returns empty array when no failures", () => {
+    const state: ValidationState = {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+      },
+      lastVerified: null,
+    };
+    expect(getFailedAssertions(state)).toEqual([]);
+  });
+
+  it("includes blocked assertions", () => {
+    const state: ValidationState = {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+        A2: {
+          status: "blocked",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: "needs infra",
+        },
+      },
+      lastVerified: null,
+    };
+    expect(getFailedAssertions(state)).toEqual(["A2"]);
+  });
+});
+
+describe("blocked assertion status", () => {
+  it("isAllPassing returns false when assertion is blocked", () => {
+    const state: ValidationState = {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: null,
+        },
+        A2: {
+          status: "blocked",
+          verifiedBy: null,
+          verifiedAt: null,
+          evidence: null,
+          blockedBy: "depends on deploy",
+        },
+      },
+      lastVerified: null,
+    };
+    expect(isAllPassing(state)).toBe(false);
+  });
+});
+
+describe("parseAssertionIds", () => {
+  it("parses ASSERT-style IDs", () => {
+    const contract = `# Contract\n**ASSERT01**: Auth works\n**ASSERT02**: Tests pass`;
+    expect(parseAssertionIds(contract)).toEqual(["ASSERT01", "ASSERT02"]);
+  });
+
+  it("parses VAL-style IDs", () => {
+    const contract = `**VAL-AUTH-001**: Endpoint returns 200\n**VAL-DB-002**: Data persists`;
+    expect(parseAssertionIds(contract)).toEqual(["VAL-AUTH-001", "VAL-DB-002"]);
+  });
+
+  it("deduplicates IDs", () => {
+    const contract = `**ASSERT01**: first mention\n**ASSERT01**: second mention`;
+    expect(parseAssertionIds(contract)).toEqual(["ASSERT01"]);
+  });
+
+  it("returns empty array for no matches", () => {
+    expect(parseAssertionIds("No assertions here")).toEqual([]);
+  });
+});
+
+describe("checkCoverage", () => {
+  it("reports unclaimed assertions", () => {
+    ensureTasksDir(tmpDir);
+    writeFileSync(
+      join(tmpDir, ".tasks", "validation-contract.md"),
+      "**ASSERT01**: Auth\n**ASSERT02**: Tests\n**ASSERT03**: Deploy",
+    );
+    // Only ASSERT01 is claimed
+    saveTask(tmpDir, makeTask({ id: "001", fulfills: ["ASSERT01"] }));
+
+    const result = checkCoverage(tmpDir);
+    expect(result.unclaimed).toEqual(["ASSERT02", "ASSERT03"]);
+  });
+
+  it("reports duplicate claims", () => {
+    ensureTasksDir(tmpDir);
+    writeFileSync(join(tmpDir, ".tasks", "validation-contract.md"), "**ASSERT01**: Auth");
+    saveTask(tmpDir, makeTask({ id: "001", fulfills: ["ASSERT01"] }));
+    saveTask(tmpDir, makeTask({ id: "002", title: "Other", fulfills: ["ASSERT01"] }));
+
+    const result = checkCoverage(tmpDir);
+    expect(result.unclaimed).toEqual([]);
+    expect(result.duplicates["ASSERT01"]).toEqual(["001", "002"]);
+  });
+
+  it("returns empty when no contract", () => {
+    ensureTasksDir(tmpDir);
+    const result = checkCoverage(tmpDir);
+    expect(result.unclaimed).toEqual([]);
+    expect(result.duplicates).toEqual({});
+  });
+
+  it("returns full coverage when all claimed", () => {
+    ensureTasksDir(tmpDir);
+    writeFileSync(
+      join(tmpDir, ".tasks", "validation-contract.md"),
+      "**ASSERT01**: Auth\n**ASSERT02**: Tests",
+    );
+    saveTask(tmpDir, makeTask({ id: "001", fulfills: ["ASSERT01", "ASSERT02"] }));
+
+    const result = checkCoverage(tmpDir);
+    expect(result.unclaimed).toEqual([]);
+    expect(result.duplicates).toEqual({});
+  });
+});

package/src/lib/validation.ts

@@ -0,0 +1,123 @@
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { loadTasks } from "./task-store.ts";
+
+export interface AssertionEntry {
+  status: "pending" | "passing" | "failing" | "blocked";
+  verifiedBy: string | null;
+  verifiedAt: string | null;
+  evidence: string | null;
+  blockedBy: string | null;
+}
+
+export interface ValidationState {
+  assertions: Record<string, AssertionEntry>;
+  lastVerified: string | null;
+}
+
+const TASKS_DIR = ".tasks";
+
+/**
+ * Read the validation contract markdown file.
+ * Returns the file contents, or null if it doesn't exist.
+ */
+export function loadValidationContract(dir: string): string | null {
+  const path = join(dir, TASKS_DIR, "validation-contract.md");
+  if (!existsSync(path)) return null;
+  return readFileSync(path, "utf-8");
+}
+
+/**
+ * Read the validation state JSON file.
+ * Returns the parsed state, or null if it doesn't exist or is corrupted.
+ */
+export function loadValidationState(dir: string): ValidationState | null {
+  const path = join(dir, TASKS_DIR, "validation-state.json");
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as ValidationState;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the validation state JSON file atomically.
+ */
+export function saveValidationState(dir: string, state: ValidationState): void {
+  const path = join(dir, TASKS_DIR, "validation-state.json");
+  const tmpPath = path + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(state, null, 2) + "\n");
+  renameSync(tmpPath, path);
+}
+
+/**
+ * Check if all assertions in a validation state are passing.
+ */
+export function isAllPassing(state: ValidationState): boolean {
+  const entries = Object.values(state.assertions);
+  if (entries.length === 0) return false;
+  return entries.every((e) => e.status === "passing");
+}
+
+/**
+ * Get the IDs of all failing or blocked assertions.
+ */
+export function getFailedAssertions(state: ValidationState): string[] {
+  return Object.entries(state.assertions)
+    .filter(([, e]) => e.status === "failing" || e.status === "blocked")
+    .map(([id]) => id);
+}
+
+// --- Coverage invariant ---
+
+const ASSERTION_ID_PATTERN = /\*\*((?:VAL|ASSERT)[A-Z0-9_-]+)\*\*/g;
+
+/**
+ * Parse assertion IDs from a validation contract markdown.
+ * Matches bold-wrapped IDs like **VAL-AUTH-001** or **ASSERT01**.
+ */
+export function parseAssertionIds(contract: string): string[] {
+  const ids = new Set<string>();
+  let match: RegExpExecArray | null;
+  while ((match = ASSERTION_ID_PATTERN.exec(contract)) !== null) {
+    ids.add(match[1]!);
+  }
+  return [...ids];
+}
+
+/**
+ * Check coverage: every assertion in the contract should be claimed
+ * by at least one task's fulfills.
+ */
+export function checkCoverage(dir: string): {
+  unclaimed: string[];
+  duplicates: Record<string, string[]>;
+} {
+  const contract = loadValidationContract(dir);
+  if (!contract) return { unclaimed: [], duplicates: {} };
+
+  const assertionIds = parseAssertionIds(contract);
+  if (assertionIds.length === 0) return { unclaimed: [], duplicates: {} };
+
+  const tasks = loadTasks(dir);
+  const claimMap = new Map<string, string[]>();
+
+  for (const task of tasks) {
+    for (const id of task.fulfills) {
+      const existing = claimMap.get(id) ?? [];
+      existing.push(task.id);
+      claimMap.set(id, existing);
+    }
+  }
+
+  const unclaimed = assertionIds.filter((id) => !claimMap.has(id));
+  const duplicates: Record<string, string[]> = {};
+  for (const [id, taskIds] of claimMap) {
+    if (taskIds.length > 1 && assertionIds.includes(id)) {
+      duplicates[id] = taskIds;
+    }
+  }
+
+  return { unclaimed, duplicates };
+}

package/src/lib/webhook.ts

@@ -0,0 +1,51 @@
+import { createHmac } from "node:crypto";
+import type { OrchestratorEvent, StructuredEvent } from "./event-log.ts";
+
+export interface WebhookConfig {
+  url: string;
+  events?: string[];
+  secret?: string;
+}
+
+/**
+ * Fire webhooks for an event. Fire-and-forget — never blocks the caller.
+ * Failures are silently ignored (logged only in debug mode).
+ */
+export function fireWebhooks(
+  webhooks: WebhookConfig[],
+  event: OrchestratorEvent | StructuredEvent,
+): void {
+  const eventType = event.type;
+
+  for (const hook of webhooks) {
+    // Filter by event type if configured
+    if (hook.events && hook.events.length > 0 && !hook.events.includes(eventType)) {
+      continue;
+    }
+
+    const body = JSON.stringify(event);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "User-Agent": "tmux-ide-webhook/1.0",
+    };
+
+    // HMAC-SHA256 signing
+    if (hook.secret) {
+      const signature = createHmac("sha256", hook.secret).update(body).digest("hex");
+      headers["X-Signature-256"] = `sha256=${signature}`;
+    }
+
+    // Fire-and-forget with 5s timeout
+    fetch(hook.url, {
+      method: "POST",
+      headers,
+      body,
+      signal: AbortSignal.timeout(5000),
+    }).catch(() => {
+      // Silently ignore webhook failures
+      if (process.env.TMUX_IDE_DEBUG === "1") {
+        process.stderr.write(`Webhook failed: ${hook.url}\n`);
+      }
+    });
+  }
+}