@opengsd/gsd-pi 1.2.0-dev.0b870afa → 1.2.0-dev.23d85b63

package/src/resources/extensions/gsd/tests/uok-audit.test.ts

@@ -0,0 +1,194 @@
+// gsd-pi UOK Audit Sink Tests
+//
+// Dedicated coverage for `uok/audit.ts` — the structured audit-event sink that
+// every workflow-logger / journal / metrics path funnels through when the
+// unified-audit toggle is on. The contract test (`uok-contracts.test.ts`)
+// exercises the happy DB+jsonl path and timeline precedence, but none of the
+// four error/control branches below:
+//   1. stale-turn write drop          (isStaleWrite early return)
+//   2. validation failure throw        (malformed envelope)
+//   3. DB authoritative write failure  (re-throw to caller)
+//   4. jsonl projection swallow        (best-effort, never throws)
+// These tests pin each branch so regressions surface as clear failures.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { AuditEventEnvelope } from "../uok/contracts.ts";
+import { CURRENT_UOK_CONTRACT_VERSION } from "../uok/contracts.ts";
+import { buildAuditEnvelope, emitUokAuditEvent } from "../uok/audit.ts";
+import { closeDatabase, openDatabase, _getAdapter } from "../gsd-db.ts";
+import {
+  bumpTurnGeneration,
+  runWithTurnGeneration,
+  _resetTurnEpoch,
+} from "../auto/turn-epoch.ts";
+
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+function auditEventsPath(basePath: string): string {
+  return join(basePath, ".gsd", "audit", "events.jsonl");
+}
+
+function readAuditEvents(basePath: string): AuditEventEnvelope[] {
+  const path = auditEventsPath(basePath);
+  if (!existsSync(path)) return [];
+  const raw = readFileSync(path, "utf-8").trim();
+  if (!raw) return [];
+  return raw
+    .split("\n")
+    .map((line) => JSON.parse(line) as AuditEventEnvelope);
+}
+
+function makeBasePath(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-uok-audit-sink-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  return dir;
+}
+
+function validEnvelope(overrides: Partial<AuditEventEnvelope> = {}): AuditEventEnvelope {
+  return buildAuditEnvelope({
+    traceId: "trace-sink",
+    turnId: "turn-sink",
+    category: "orchestration",
+    type: "audit-sink-test",
+    payload: {},
+    ...overrides,
+  });
+}
+
+test("buildAuditEnvelope stamps version, eventId, and ts", () => {
+  const event = buildAuditEnvelope({
+    traceId: "trace-1",
+    category: "orchestration",
+    type: "turn-start",
+    payload: { unitType: "execute-task" },
+  });
+
+  assert.equal(event.version, CURRENT_UOK_CONTRACT_VERSION);
+  assert.equal(typeof event.eventId, "string");
+  assert.ok(event.eventId.length > 0, "eventId must be populated");
+  assert.equal(event.traceId, "trace-1");
+  assert.equal(event.turnId, undefined, "turnId is optional and omitted");
+  assert.equal(event.causedBy, undefined, "causedBy is optional and omitted");
+  assert.equal(event.category, "orchestration");
+  assert.equal(event.type, "turn-start");
+  assert.deepEqual(event.payload, { unitType: "execute-task" });
+  assert.match(event.ts, ISO_RE);
+});
+
+test("buildAuditEnvelope defaults payload to empty object when omitted", () => {
+  const event = buildAuditEnvelope({
+    traceId: "trace-2",
+    category: "orchestration",
+    type: "minimal",
+  });
+  assert.deepEqual(event.payload, {});
+});
+
+test("buildAuditEnvelope mints a unique eventId per call", () => {
+  const a = buildAuditEnvelope({ traceId: "t", category: "orchestration", type: "x" });
+  const b = buildAuditEnvelope({ traceId: "t", category: "orchestration", type: "x" });
+  assert.notEqual(a.eventId, b.eventId, "each call must mint a fresh eventId");
+});
+
+test("emitUokAuditEvent writes the jsonl projection when DB is unavailable", () => {
+  const basePath = makeBasePath();
+  try {
+    // No openDatabase() call → isDbAvailable() is false → DB branch skipped,
+    // envelope lands only in the jsonl projection.
+    emitUokAuditEvent(basePath, validEnvelope({ traceId: "trace-jsonl-only" }));
+
+    const events = readAuditEvents(basePath);
+    assert.equal(events.length, 1);
+    assert.equal(events[0].traceId, "trace-jsonl-only");
+    assert.equal(events[0].category, "orchestration");
+    assert.equal(events[0].type, "audit-sink-test");
+  } finally {
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});
+
+test("emitUokAuditEvent drops the write when the turn is stale", () => {
+  _resetTurnEpoch();
+  const basePath = makeBasePath();
+  try {
+    // Capture generation 0, then bump to 1 so the captured turn is superseded.
+    bumpTurnGeneration("test: simulate timeout recovery");
+    const emitted = runWithTurnGeneration(0, () => {
+      emitUokAuditEvent(basePath, validEnvelope({ traceId: "trace-stale" }));
+      return true;
+    });
+
+    assert.equal(emitted, true, "emit must return without throwing on a stale turn");
+    assert.equal(existsSync(auditEventsPath(basePath)), false, "stale write must not create the projection");
+    assert.equal(readAuditEvents(basePath).length, 0, "stale write must not persist anything");
+  } finally {
+    _resetTurnEpoch();
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});
+
+test("emitUokAuditEvent throws on an invalid envelope", () => {
+  const basePath = makeBasePath();
+  try {
+    // Missing required string fields (traceId/category/type) → validator reports issues.
+    const invalid = {
+      version: CURRENT_UOK_CONTRACT_VERSION,
+      eventId: "evt-bad",
+      ts: new Date().toISOString(),
+      payload: {},
+    } as unknown as AuditEventEnvelope;
+
+    assert.throws(
+      () => emitUokAuditEvent(basePath, invalid),
+      /Invalid UOK audit event:.*traceId/u,
+      "validation failure must throw with the offending field path",
+    );
+    assert.equal(readAuditEvents(basePath).length, 0, "invalid event must not be persisted");
+  } finally {
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});
+
+test("emitUokAuditEvent re-throws when the authoritative DB write fails", (t) => {
+  const basePath = makeBasePath();
+  const dbPath = join(basePath, ".gsd", "gsd.db");
+  assert.equal(openDatabase(dbPath), true, "DB must open for this scenario");
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  // Break the authoritative sink: drop the audit_events table so the prepared
+  // INSERT inside insertAuditEvent throws. This proves the DB failure surfaces
+  // to the caller as a wrapped error rather than being silently swallowed.
+  _getAdapter()!.exec("DROP TABLE audit_events");
+
+  assert.throws(
+    () => emitUokAuditEvent(basePath, validEnvelope({ traceId: "trace-db-fail" })),
+    /DB authoritative audit write failed/u,
+    "a failed authoritative DB write must re-throw to the caller",
+  );
+});
+
+test("emitUokAuditEvent swallows jsonl projection failures (best-effort)", (t) => {
+  const basePath = makeBasePath();
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+
+  // Point the envelope at a path whose parent directory cannot be created:
+  // gsdRoot() resolves under basePath, so a basePath whose .gsd is a regular
+  // file makes mkdirSync(audit/) throw — exercising the silent catch.
+  // We pre-create .gsd as a file so ensureAuditDir()'s recursive mkdir fails.
+  rmSync(join(basePath, ".gsd"), { recursive: true, force: true });
+  writeFileSync(join(basePath, ".gsd"), "not-a-directory");
+
+  // With no DB open and an unwritable projection path, emit must NOT throw —
+  // audit writes are explicitly best-effort and must never break orchestration.
+  assert.doesNotThrow(() => {
+    emitUokAuditEvent(basePath, validEnvelope({ traceId: "trace-swallow" }));
+  }, "jsonl projection failure must be swallowed, not propagated");
+});

package/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts

@@ -22,7 +22,7 @@ import {
   _needsPlanV2GateForTest,
   _runPlanV2GateForTest,
 } from "../guided-flow.ts";
-import { shouldRunPlanV2Gate } from "../auto/phases.ts";
+import { shouldRunPlanV2Gate } from "../auto/phase-helpers.ts";
 import { resolveUokFlags } from "../uok/flags.ts";
 
 const MILESTONE_ID = "M001";

package/src/resources/extensions/gsd/tests/workflow-mcp-readiness-cache.test.ts

@@ -0,0 +1,119 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for shared workflow MCP probe cache.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  cachedWorkflowMcpCoversRequired,
+  clearWorkflowMcpProbeCache,
+  getCachedWorkflowMcpProbe,
+  probeAndCacheWorkflowMcp,
+  recordWorkflowMcpProbe,
+  beginWorkflowMcpSdkSession,
+  endWorkflowMcpSdkSession,
+  warmWorkflowMcpProbeInBackground,
+} from "../workflow-mcp-readiness-cache.ts";
+
+describe("workflow-mcp-readiness-cache", () => {
+  test("returns cached probe without reconnecting", async () => {
+    clearWorkflowMcpProbeCache();
+    const projectRoot = "/tmp/gsd-cache-project";
+    recordWorkflowMcpProbe(projectRoot, "gsd-workflow", ["gsd_status", "gsd_plan_slice"]);
+
+    const result = await probeAndCacheWorkflowMcp(projectRoot, { timeoutMs: 1000 });
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.tools, ["gsd_status", "gsd_plan_slice"]);
+    assert.equal(result.serverName, "gsd-workflow");
+  });
+
+  test("cachedWorkflowMcpCoversRequired matches required workflow tools", () => {
+    clearWorkflowMcpProbeCache();
+    const projectRoot = "/tmp/gsd-cache-required";
+    recordWorkflowMcpProbe(projectRoot, "gsd-workflow", ["gsd_plan_slice", "gsd_milestone_status"]);
+
+    assert.equal(
+      cachedWorkflowMcpCoversRequired(projectRoot, "gsd-workflow", ["gsd_plan_slice"]),
+      true,
+    );
+    assert.equal(
+      cachedWorkflowMcpCoversRequired(projectRoot, "gsd-workflow", ["gsd_uat_exec"]),
+      false,
+    );
+    assert.equal(getCachedWorkflowMcpProbe(projectRoot)?.serverName, "gsd-workflow");
+  });
+
+  test("warmWorkflowMcpProbeInBackground is suppressed during active SDK sessions", async () => {
+    clearWorkflowMcpProbeCache();
+    beginWorkflowMcpSdkSession();
+    try {
+      const projectRoot = "/tmp/gsd-sdk-session-guard";
+      warmWorkflowMcpProbeInBackground(projectRoot);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      assert.equal(getCachedWorkflowMcpProbe(projectRoot), null);
+    } finally {
+      endWorkflowMcpSdkSession();
+    }
+  });
+
+  test("warmWorkflowMcpProbeInBackground uses project root without double cache-keying", async () => {
+    clearWorkflowMcpProbeCache();
+    const projectRoot = "/tmp/gsd-warm-cache-key";
+    recordWorkflowMcpProbe(projectRoot, "gsd-workflow", ["gsd_status", "gsd_plan_slice"]);
+    warmWorkflowMcpProbeInBackground(projectRoot);
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.equal(getCachedWorkflowMcpProbe(projectRoot)?.serverName, "gsd-workflow");
+  });
+
+  test("probeAndCacheWorkflowMcp reads project .mcp.json when no env launch config exists", async () => {
+    clearWorkflowMcpProbeCache();
+    const previousGsdHome = process.env.GSD_HOME;
+    const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-cache-project-"));
+    const gsdHomeDir = mkdtempSync(join(tmpdir(), "gsd-mcp-cache-home-"));
+    try {
+      process.env.GSD_HOME = gsdHomeDir;
+      mkdirSync(join(projectRoot, ".gsd"), { recursive: true });
+
+      const require = createRequire(import.meta.url);
+      const mcpModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/mcp.js")).href;
+      const stdioModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/stdio.js")).href;
+      const serverPath = join(projectRoot, "fake-workflow-mcp-server.mjs");
+      writeFileSync(
+        serverPath,
+        [
+          `const { McpServer } = await import(${JSON.stringify(mcpModuleUrl)});`,
+          `const { StdioServerTransport } = await import(${JSON.stringify(stdioModuleUrl)});`,
+          'const server = new McpServer({ name: "fake", version: "1.0.0" }, { capabilities: { tools: {} } });',
+          'server.tool("ask_user_questions", "Ask questions", {}, async () => ({ content: [{ type: "text", text: "ok" }] }));',
+          'await server.connect(new StdioServerTransport());',
+        ].join("\n"),
+        "utf-8",
+      );
+      writeFileSync(
+        join(projectRoot, ".mcp.json"),
+        JSON.stringify({ mcpServers: { "gsd-workflow": { command: process.execPath, args: [serverPath] } } }),
+        "utf-8",
+      );
+
+      const result = await probeAndCacheWorkflowMcp(projectRoot, { timeoutMs: 5_000 });
+
+      assert.equal(result.ok, true);
+      assert.equal(result.serverName, "gsd-workflow");
+      assert.deepEqual(result.tools, ["ask_user_questions"]);
+      assert.deepEqual(getCachedWorkflowMcpProbe(projectRoot)?.tools, ["ask_user_questions"]);
+    } finally {
+      if (previousGsdHome === undefined) {
+        delete process.env.GSD_HOME;
+      } else {
+        process.env.GSD_HOME = previousGsdHome;
+      }
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(gsdHomeDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -22,6 +22,7 @@ import {
   usesWorkflowMcpTransport,
 } from "../workflow-mcp.ts";
 import { DB_WORKFLOW_TOOL_NAMES } from "../workflow-tool-surface.ts";
+import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.ts";
 
 const MCP_STDIO_TIMEOUT_MS = 90_000;
 
@@ -43,11 +44,25 @@ test("resolveWorkflowMcpProjectRoot maps milestone worktree cwd to project root"
 });
 
 test("guided execute-task requires canonical task completion tool", () => {
-  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("execute-task"), ["gsd_task_complete"]);
+  const expected = [
+    "gsd_task_complete",
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_capture_thought",
+  ];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("execute-task"), expected);
 });
 
 test("auto execute-task requires canonical task completion tool", () => {
-  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), ["gsd_task_complete"]);
+  const expected = [
+    "gsd_task_complete",
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_capture_thought",
+  ];
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), expected);
 });
 
 test("plan-slice requires planning and roadmap reassessment tools", () => {
@@ -69,6 +84,8 @@ test("refine-slice requires canonical slice planning tool", () => {
 
 test("complete-slice requires closeout and execution handoff tools", () => {
   const expected = [
+    "gsd_exec",
+    "gsd_capture_thought",
     "gsd_slice_complete",
     "gsd_task_reopen",
     "gsd_replan_slice",
@@ -526,6 +543,52 @@ test("workflow MCP launch config reaches mutation tools over stdio", async () =>
   }
 });
 
+test("workflow MCP stdio surface exposes every unit's required workflow tool", async () => {
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-all-unit-tools-"));
+  const isolatedGsdHome = mkdtempSync(join(tmpdir(), "gsd-workflow-all-unit-home-"));
+  mkdirSync(join(projectRoot, ".gsd"), { recursive: true });
+
+  const launch = detectWorkflowMcpLaunchConfig(projectRoot, {});
+  assert.ok(launch, "expected a workflow MCP launch config");
+
+  const client = new Client({ name: "workflow-mcp-contract-test", version: "1.0.0" });
+  const transport = new StdioClientTransport({
+    command: launch.command,
+    args: launch.args,
+    env: {
+      ...process.env,
+      ...launch.env,
+      GSD_HOME: isolatedGsdHome,
+      DISCORD_BOT_TOKEN: "",
+      SLACK_BOT_TOKEN: "",
+      TELEGRAM_BOT_TOKEN: "",
+    } as Record<string, string>,
+    cwd: launch.cwd,
+    stderr: "pipe",
+  });
+
+  try {
+    await client.connect(transport, { timeout: MCP_STDIO_TIMEOUT_MS });
+    const listed = await client.listTools(undefined, { timeout: MCP_STDIO_TIMEOUT_MS });
+    const exposedTools = new Set((listed.tools ?? []).map((tool) => tool.name));
+
+    for (const [unitType, contract] of Object.entries(UNIT_TOOL_CONTRACTS)) {
+      for (const toolName of contract.requiredWorkflowTools) {
+        if (!toolName.startsWith("gsd_") && toolName !== "ask_user_questions") continue;
+        assert.ok(
+          exposedTools.has(toolName),
+          `${unitType} requires ${toolName}, but workflow MCP exposed ${JSON.stringify([...exposedTools].sort())}`,
+        );
+      }
+    }
+  } finally {
+    await client.close().catch(() => undefined);
+    await transport.close().catch(() => undefined);
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(isolatedGsdHome, { recursive: true, force: true });
+  }
+});
+
 test("workflow MCP ask_user_questions uses stdio elicitation round-trip", async () => {
   const projectRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-elicit-"));
   mkdirSync(join(projectRoot, ".gsd"), { recursive: true });