gsd-pi 2.10.12 → 2.12.0

package/dist/resources/extensions/gsd/tests/run-uat.test.ts

@@ -0,0 +1,316 @@
+// Tests for extractUatType — the core UAT classification primitive — plus
+// prompt template loading and dispatch precondition assertions (via
+// resolveSliceFile / extractUatType on real fixture files).
+//
+// Sections:
+//   (a)–(j)  extractUatType classification (17 assertions from T01)
+//   (k)      run-uat prompt template loading and content integrity (8 assertions)
+//   (l)      dispatch precondition assertions via resolveSliceFile (4 assertions)
+
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { extractUatType } from '../files.ts';
+import { resolveSliceFile } from '../paths.ts';
+import { createTestContext } from './test-helpers.ts';
+
+// ─── Worktree-aware prompt loader ──────────────────────────────────────────
+// Resolves prompts relative to this test file so the worktree copy is used
+// instead of the main checkout copy (matches complete-milestone.test.ts pattern).
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const worktreePromptsDir = join(__dirname, '..', 'prompts');
+
+function loadPromptFromWorktree(name: string, vars: Record<string, string> = {}): string {
+  const path = join(worktreePromptsDir, `${name}.md`);
+  let content = readFileSync(path, 'utf-8');
+  for (const [key, value] of Object.entries(vars)) {
+    content = content.replaceAll(`{{${key}}}`, value);
+  }
+  return content.trim();
+}
+
+
+const { assertEq, assertTrue, report } = createTestContext();
+// ─── Fixture helpers ───────────────────────────────────────────────────────
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-run-uat-test-'));
+  mkdirSync(join(base, '.gsd', 'milestones'), { recursive: true });
+  return base;
+}
+
+function writeSliceFile(
+  base: string,
+  mid: string,
+  sid: string,
+  suffix: string,
+  content: string,
+): void {
+  const dir = join(base, '.gsd', 'milestones', mid, 'slices', sid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${sid}-${suffix}.md`), content);
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+function makeUatContent(mode: string): string {
+  return `# UAT File\n\n## UAT Type\n\n- UAT mode: ${mode}\n- Some other bullet: value\n`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main(): Promise<void> {
+
+  // ─── (a) artifact-driven ──────────────────────────────────────────────────
+  console.log('\n── (a) artifact-driven');
+
+  assertEq(
+    extractUatType(makeUatContent('artifact-driven')),
+    'artifact-driven',
+    'plain artifact-driven → artifact-driven',
+  );
+
+  assertEq(
+    extractUatType('## UAT Type\n\n- UAT mode: artifact-driven\n'),
+    'artifact-driven',
+    'minimal content, artifact-driven',
+  );
+
+  // ─── (b) live-runtime ─────────────────────────────────────────────────────
+  console.log('\n── (b) live-runtime');
+
+  assertEq(
+    extractUatType(makeUatContent('live-runtime')),
+    'live-runtime',
+    'plain live-runtime → live-runtime',
+  );
+
+  // ─── (c) human-experience ─────────────────────────────────────────────────
+  console.log('\n── (c) human-experience');
+
+  assertEq(
+    extractUatType(makeUatContent('human-experience')),
+    'human-experience',
+    'plain human-experience → human-experience',
+  );
+
+  // ─── (d) mixed standalone ─────────────────────────────────────────────────
+  console.log('\n── (d) mixed standalone');
+
+  assertEq(
+    extractUatType(makeUatContent('mixed')),
+    'mixed',
+    'plain mixed → mixed',
+  );
+
+  // ─── (e) mixed with parenthetical ─────────────────────────────────────────
+  console.log('\n── (e) mixed parenthetical');
+
+  assertEq(
+    extractUatType(makeUatContent('mixed (artifact-driven + live-runtime)')),
+    'mixed',
+    'mixed (artifact-driven + live-runtime) → mixed (leading keyword only)',
+  );
+
+  assertEq(
+    extractUatType(makeUatContent('mixed (some other description)')),
+    'mixed',
+    'mixed with arbitrary parenthetical → mixed',
+  );
+
+  // ─── (f) missing ## UAT Type section ──────────────────────────────────────
+  console.log('\n── (f) missing UAT Type section');
+
+  assertEq(
+    extractUatType('# UAT File\n\n## Overview\n\nSome content.\n'),
+    undefined,
+    'no ## UAT Type section → undefined',
+  );
+
+  assertEq(
+    extractUatType(''),
+    undefined,
+    'empty content → undefined',
+  );
+
+  // ─── (g) ## UAT Type present but no UAT mode: bullet ─────────────────────
+  console.log('\n── (g) UAT Type section present, no UAT mode: bullet');
+
+  assertEq(
+    extractUatType('## UAT Type\n\n- Some other bullet: value\n- Another bullet\n'),
+    undefined,
+    'section present but no UAT mode: bullet → undefined',
+  );
+
+  assertEq(
+    extractUatType('## UAT Type\n\n'),
+    undefined,
+    'section present but empty → undefined',
+  );
+
+  // ─── (h) unknown keyword ──────────────────────────────────────────────────
+  console.log('\n── (h) unknown keyword');
+
+  assertEq(
+    extractUatType(makeUatContent('automated')),
+    undefined,
+    'unknown keyword automated → undefined',
+  );
+
+  assertEq(
+    extractUatType(makeUatContent('fully-automated')),
+    undefined,
+    'unknown keyword fully-automated → undefined',
+  );
+
+  // ─── (i) extra whitespace around value ────────────────────────────────────
+  console.log('\n── (i) extra whitespace');
+
+  assertEq(
+    extractUatType('## UAT Type\n\n- UAT mode:   artifact-driven   \n'),
+    'artifact-driven',
+    'leading/trailing whitespace around value → still classified correctly',
+  );
+
+  assertEq(
+    extractUatType('## UAT Type\n\n- UAT mode:  mixed (artifact-driven + live-runtime)  \n'),
+    'mixed',
+    'whitespace around mixed parenthetical → mixed',
+  );
+
+  // ─── (j) case sensitivity ─────────────────────────────────────────────────
+  console.log('\n── (j) case sensitivity');
+
+  assertEq(
+    extractUatType(makeUatContent('Artifact-Driven')),
+    'artifact-driven',
+    'Artifact-Driven (title case) → artifact-driven (function lowercases before matching)',
+  );
+
+  assertEq(
+    extractUatType(makeUatContent('MIXED')),
+    'mixed',
+    'MIXED (upper case) → mixed (function lowercases before matching)',
+  );
+
+  // ─── (k) prompt template loading and content integrity ────────────────────
+  console.log('\n── (k) run-uat prompt template');
+
+  const milestoneId = 'M001';
+  const sliceId = 'S01';
+  const uatPath = '.gsd/milestones/M001/slices/S01/S01-UAT.md';
+  const uatResultPath = '.gsd/milestones/M001/slices/S01/S01-UAT-RESULT.md';
+  const uatType = 'artifact-driven';
+  const inlinedContext = '<!-- no context -->';
+
+  let promptResult: string | undefined;
+  let promptThrew = false;
+  try {
+    promptResult = loadPromptFromWorktree('run-uat', {
+      milestoneId,
+      sliceId,
+      uatPath,
+      uatResultPath,
+      uatType,
+      inlinedContext,
+    });
+  } catch {
+    promptThrew = true;
+  }
+
+  assertTrue(!promptThrew, 'loadPromptFromWorktree("run-uat", vars) does not throw');
+  assertTrue(
+    typeof promptResult === 'string' && promptResult.length > 0,
+    'run-uat prompt result is a non-empty string',
+  );
+  assertTrue(
+    promptResult?.includes(milestoneId) ?? false,
+    `prompt contains milestoneId value "${milestoneId}" after substitution`,
+  );
+  assertTrue(
+    promptResult?.includes(sliceId) ?? false,
+    `prompt contains sliceId value "${sliceId}" after substitution`,
+  );
+  assertTrue(
+    promptResult?.includes(uatResultPath) ?? false,
+    `prompt contains uatResultPath value after substitution`,
+  );
+  assertTrue(
+    !/\{\{[^}]+\}\}/.test(promptResult ?? ''),
+    'no unreplaced {{...}} tokens remain after variable substitution',
+  );
+  assertTrue(
+    /artifact|execute|run/i.test(promptResult ?? ''),
+    'prompt contains artifact-driven execution language (artifact/execute/run)',
+  );
+  assertTrue(
+    /surfaced for human review/i.test(promptResult ?? ''),
+    'prompt contains "surfaced for human review" text for non-artifact-driven path',
+  );
+
+  // ─── (l) dispatch precondition assertions via resolveSliceFile ────────────
+  console.log('\n── (l) dispatch preconditions via resolveSliceFile');
+
+  // State A: UAT file exists, UAT-RESULT file does NOT — triggers dispatch
+  {
+    const base = createFixtureBase();
+    const uatContent = makeUatContent('artifact-driven');
+    try {
+      writeSliceFile(base, 'M001', 'S01', 'UAT', uatContent);
+
+      const uatFilePath = resolveSliceFile(base, 'M001', 'S01', 'UAT');
+      assertTrue(
+        uatFilePath !== null,
+        'resolveSliceFile(..., "UAT") returns non-null when UAT file exists (dispatch trigger state)',
+      );
+
+      const uatResultFilePath = resolveSliceFile(base, 'M001', 'S01', 'UAT-RESULT');
+      assertEq(
+        uatResultFilePath,
+        null,
+        'resolveSliceFile(..., "UAT-RESULT") returns null when result file missing (dispatch trigger state)',
+      );
+
+      // End-to-end: file content → parse → classify
+      const rawContent = readFileSync(uatFilePath!, 'utf-8');
+      assertEq(
+        extractUatType(rawContent),
+        'artifact-driven',
+        'extractUatType on fixture UAT file returns expected type (end-to-end data flow)',
+      );
+    } finally {
+      cleanup(base);
+    }
+  }
+
+  // State B: UAT-RESULT file exists — dispatch is skipped (idempotent)
+  {
+    const base = createFixtureBase();
+    try {
+      writeSliceFile(base, 'M001', 'S01', 'UAT', makeUatContent('artifact-driven'));
+      writeSliceFile(base, 'M001', 'S01', 'UAT-RESULT', '# UAT Result\n\nverdict: PASS\n');
+
+      const uatResultFilePath = resolveSliceFile(base, 'M001', 'S01', 'UAT-RESULT');
+      assertTrue(
+        uatResultFilePath !== null,
+        'resolveSliceFile(..., "UAT-RESULT") returns non-null when result file exists (idempotent skip state)',
+      );
+    } finally {
+      cleanup(base);
+    }
+  }
+
+  report();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/resources/extensions/gsd/tests/secure-env-collect.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Tests for secure_env_collect utility functions:
+ * - checkExistingEnvKeys: detects keys already present in .env file or process.env
+ * - detectDestination: infers write destination from project files
+ *
+ * Uses temp directories for filesystem isolation.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { checkExistingEnvKeys, detectDestination } from "../../get-secrets-from-user.ts";
+
+function makeTempDir(prefix: string): string {
+	const dir = join(tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+// ─── checkExistingEnvKeys ─────────────────────────────────────────────────────
+
+test("secure_env_collect: checkExistingEnvKeys — key found in .env file", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	try {
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "API_KEY=secret123\nOTHER=val\n");
+		const result = await checkExistingEnvKeys(["API_KEY"], envPath);
+		assert.deepStrictEqual(result, ["API_KEY"]);
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — key found in process.env", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const savedVal = process.env.GSD_TEST_ENV_KEY_12345;
+	try {
+		process.env.GSD_TEST_ENV_KEY_12345 = "some-value";
+		const envPath = join(tmp, ".env"); // file doesn't exist
+		const result = await checkExistingEnvKeys(["GSD_TEST_ENV_KEY_12345"], envPath);
+		assert.deepStrictEqual(result, ["GSD_TEST_ENV_KEY_12345"]);
+	} finally {
+		delete process.env.GSD_TEST_ENV_KEY_12345;
+		if (savedVal !== undefined) process.env.GSD_TEST_ENV_KEY_12345 = savedVal;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — key found in both .env and process.env", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const savedVal = process.env.GSD_TEST_BOTH_KEY;
+	try {
+		process.env.GSD_TEST_BOTH_KEY = "from-env";
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "GSD_TEST_BOTH_KEY=from-file\n");
+		const result = await checkExistingEnvKeys(["GSD_TEST_BOTH_KEY"], envPath);
+		assert.deepStrictEqual(result, ["GSD_TEST_BOTH_KEY"]);
+	} finally {
+		delete process.env.GSD_TEST_BOTH_KEY;
+		if (savedVal !== undefined) process.env.GSD_TEST_BOTH_KEY = savedVal;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — key not found anywhere", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	try {
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "OTHER_KEY=val\n");
+		// Ensure it's not in process.env
+		delete process.env.DEFINITELY_NOT_SET_KEY_XYZ;
+		const result = await checkExistingEnvKeys(["DEFINITELY_NOT_SET_KEY_XYZ"], envPath);
+		assert.deepStrictEqual(result, []);
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — .env file doesn't exist (ENOENT), still checks process.env", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const savedVal = process.env.GSD_TEST_ENOENT_KEY;
+	try {
+		process.env.GSD_TEST_ENOENT_KEY = "exists-in-process";
+		const envPath = join(tmp, "nonexistent.env");
+		const result = await checkExistingEnvKeys(["GSD_TEST_ENOENT_KEY", "MISSING_KEY_XYZ"], envPath);
+		assert.deepStrictEqual(result, ["GSD_TEST_ENOENT_KEY"]);
+	} finally {
+		delete process.env.GSD_TEST_ENOENT_KEY;
+		if (savedVal !== undefined) process.env.GSD_TEST_ENOENT_KEY = savedVal;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — empty-string value in process.env counts as existing", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const savedVal = process.env.GSD_TEST_EMPTY_KEY;
+	try {
+		process.env.GSD_TEST_EMPTY_KEY = "";
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "");
+		const result = await checkExistingEnvKeys(["GSD_TEST_EMPTY_KEY"], envPath);
+		assert.deepStrictEqual(result, ["GSD_TEST_EMPTY_KEY"]);
+	} finally {
+		delete process.env.GSD_TEST_EMPTY_KEY;
+		if (savedVal !== undefined) process.env.GSD_TEST_EMPTY_KEY = savedVal;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: checkExistingEnvKeys — returns only existing keys from input list", async () => {
+	const tmp = makeTempDir("sec-env-test");
+	const saved1 = process.env.GSD_TEST_EXISTS_A;
+	const saved2 = process.env.GSD_TEST_EXISTS_B;
+	try {
+		process.env.GSD_TEST_EXISTS_A = "val-a";
+		delete process.env.GSD_TEST_EXISTS_B;
+		const envPath = join(tmp, ".env");
+		writeFileSync(envPath, "FILE_KEY=val\n");
+		const result = await checkExistingEnvKeys(
+			["GSD_TEST_EXISTS_A", "GSD_TEST_EXISTS_B", "FILE_KEY", "NOPE_KEY"],
+			envPath,
+		);
+		assert.deepStrictEqual(result.sort(), ["FILE_KEY", "GSD_TEST_EXISTS_A"]);
+	} finally {
+		delete process.env.GSD_TEST_EXISTS_A;
+		delete process.env.GSD_TEST_EXISTS_B;
+		if (saved1 !== undefined) process.env.GSD_TEST_EXISTS_A = saved1;
+		if (saved2 !== undefined) process.env.GSD_TEST_EXISTS_B = saved2;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+// ─── detectDestination ────────────────────────────────────────────────────────
+
+test("secure_env_collect: detectDestination — returns 'vercel' when vercel.json exists", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		writeFileSync(join(tmp, "vercel.json"), "{}");
+		assert.equal(detectDestination(tmp), "vercel");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: detectDestination — returns 'convex' when convex/ dir exists", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		mkdirSync(join(tmp, "convex"));
+		assert.equal(detectDestination(tmp), "convex");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: detectDestination — returns 'dotenv' when neither exists", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		assert.equal(detectDestination(tmp), "dotenv");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: detectDestination — vercel takes priority when both exist", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		writeFileSync(join(tmp, "vercel.json"), "{}");
+		mkdirSync(join(tmp, "convex"));
+		assert.equal(detectDestination(tmp), "vercel");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("secure_env_collect: detectDestination — convex file (not dir) does not trigger convex", () => {
+	const tmp = makeTempDir("sec-dest-test");
+	try {
+		writeFileSync(join(tmp, "convex"), "not a directory");
+		assert.equal(detectDestination(tmp), "dotenv");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});

package/dist/resources/extensions/gsd/tests/smart-entry-draft.test.ts

@@ -0,0 +1,123 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { deriveState } from "../state.js";
+import { resolveMilestoneFile } from "../paths.js";
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, message: string): void {
+  if (condition) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${message}`);
+  }
+}
+
+// ─── Fixture: milestone with only CONTEXT-DRAFT.md ──────────────────────
+
+const tmpBase = mkdtempSync(join(tmpdir(), "gsd-smart-entry-draft-test-"));
+const gsd = join(tmpBase, ".gsd");
+
+mkdirSync(join(gsd, "milestones", "M001"), { recursive: true });
+
+const draftContent = `# M001: Test Milestone — Context\n\n**Status:** Draft\n\nSeed material from a prior discussion.\n`;
+writeFileSync(
+  join(gsd, "milestones", "M001", "M001-CONTEXT-DRAFT.md"),
+  draftContent,
+);
+
+// ─── Test: deriveState returns 'needs-discussion' for draft-only milestone ───
+
+const state = await deriveState(tmpBase);
+
+assert(
+  state.phase === "needs-discussion",
+  `phase should be 'needs-discussion' for draft-only milestone, got: "${state.phase}"`,
+);
+
+assert(
+  state.activeMilestone?.id === "M001",
+  `active milestone should be M001, got: "${state.activeMilestone?.id}"`,
+);
+
+// ─── Test: resolveMilestoneFile resolves CONTEXT-DRAFT ─────────────────────
+
+const draftFile = resolveMilestoneFile(tmpBase, "M001", "CONTEXT-DRAFT");
+
+assert(
+  draftFile !== null && draftFile !== undefined,
+  `resolveMilestoneFile should resolve CONTEXT-DRAFT, got: ${draftFile}`,
+);
+
+assert(
+  draftFile!.endsWith("M001-CONTEXT-DRAFT.md"),
+  `resolved path should end with M001-CONTEXT-DRAFT.md, got: "${draftFile}"`,
+);
+
+// ─── Test: CONTEXT.md is NOT resolved (only draft exists) ──────────────────
+
+const contextFile = resolveMilestoneFile(tmpBase, "M001", "CONTEXT");
+
+assert(
+  contextFile === null || contextFile === undefined,
+  `resolveMilestoneFile should NOT resolve CONTEXT when only CONTEXT-DRAFT exists, got: "${contextFile}"`,
+);
+
+// ─── Static: guided-flow.ts has 'needs-discussion' branch ─────────────────
+
+const guidedFlowSource = readFileSync(
+  join(import.meta.dirname, "..", "guided-flow.ts"),
+  "utf-8",
+);
+
+assert(
+  guidedFlowSource.includes('state.phase === "needs-discussion"'),
+  "guided-flow.ts should have 'needs-discussion' phase check in showSmartEntry",
+);
+
+// Check the branch has draft-aware menu options
+const branchIdx = guidedFlowSource.indexOf('state.phase === "needs-discussion"');
+const branchChunk = guidedFlowSource.slice(branchIdx, branchIdx + 3000);
+
+assert(
+  branchChunk.includes("discuss_draft"),
+  "needs-discussion branch should have 'discuss_draft' option",
+);
+
+assert(
+  branchChunk.includes("discuss_fresh"),
+  "needs-discussion branch should have 'discuss_fresh' option",
+);
+
+assert(
+  branchChunk.includes("skip_milestone"),
+  "needs-discussion branch should have 'skip_milestone' option",
+);
+
+assert(
+  branchChunk.includes("CONTEXT-DRAFT"),
+  "needs-discussion branch should load CONTEXT-DRAFT via resolveMilestoneFile",
+);
+
+assert(
+  branchChunk.includes("Draft Seed") || branchChunk.includes("draftContent"),
+  "discuss_draft path should include draft content as seed in the dispatched prompt",
+);
+
+assert(
+  branchChunk.includes("return"),
+  "needs-discussion branch should return early (not fall through to generic no-roadmap menu)",
+);
+
+// ─── Cleanup ──────────────────────────────────────────────────────────────
+
+rmSync(tmpBase, { recursive: true, force: true });
+
+// ─── Results ──────────────────────────────────────────────────────────────
+
+console.log(`\nsmart-entry-draft: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/dist/resources/extensions/gsd/tests/test-helpers.ts

@@ -0,0 +1,61 @@
+// Shared assertion helpers for GSD test files.
+//
+// Usage:
+//   import { createTestContext } from './test-helpers.ts';
+//   const { assertEq, assertTrue, assertMatch, assertNoMatch, report } = createTestContext();
+
+/**
+ * Create an isolated set of assertion helpers with their own pass/fail counters.
+ * Each test file gets its own context to avoid shared state across vitest workers.
+ */
+export function createTestContext() {
+  let passed = 0;
+  let failed = 0;
+
+  function assertEq<T>(actual: T, expected: T, message: string): void {
+    if (JSON.stringify(actual) === JSON.stringify(expected)) {
+      passed++;
+    } else {
+      failed++;
+      console.error(`  FAIL: ${message} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+    }
+  }
+
+  function assertTrue(condition: boolean, message: string): void {
+    if (condition) {
+      passed++;
+    } else {
+      failed++;
+      console.error(`  FAIL: ${message}`);
+    }
+  }
+
+  function assertMatch(value: string, pattern: RegExp, message: string): void {
+    if (pattern.test(value)) {
+      passed++;
+    } else {
+      failed++;
+      console.error(`  FAIL: ${message} — "${value}" did not match ${pattern}`);
+    }
+  }
+
+  function assertNoMatch(value: string, pattern: RegExp, message: string): void {
+    if (!pattern.test(value)) {
+      passed++;
+    } else {
+      failed++;
+      console.error(`  FAIL: ${message} — "${value}" should not have matched ${pattern}`);
+    }
+  }
+
+  function report(): void {
+    console.log(`\nResults: ${passed} passed, ${failed} failed`);
+    if (failed > 0) {
+      process.exit(1);
+    } else {
+      console.log('All tests passed');
+    }
+  }
+
+  return { assertEq, assertTrue, assertMatch, assertNoMatch, report };
+}