gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

package/src/resources/extensions/gsd/tests/extension-bootstrap-isolation.test.ts

@@ -1,154 +1,164 @@
-// Structural contracts for GSD extension bootstrap isolation.
+// Behavioural contract for GSD extension bootstrap isolation (#4168, #4172).
 //
-// The /gsd command must survive failures in the full extension bootstrap
-// (register-extension.ts). This guards against the regression where a
-// Windows-specific import failure in register-shortcuts.ts silently
-// prevented /gsd from being registered at all (#4168, #4172).
+// Guarantee: the `/gsd` slash command must be registered on pi even if the
+// full bootstrap (shortcuts, tools, hooks, ecosystem) throws during import or
+// execution. Prior regressions: a Windows-specific failure in register-
+// shortcuts.ts silently prevented /gsd from being registered at all because
+// registerGSDCommand was called inside the same try that loaded shortcuts.
+//
+// These tests exercise the real default export of index.ts (which calls
+// registerGSDCommand via dynamic import, then attempts the full bootstrap)
+// with a minimal mock ExtensionAPI and verify the observable behaviour
+// directly: /gsd is registered in both the happy path and the degraded path.
+//
+// Anti-regression proof (documented in commit):
+//   neuter index.ts to register /gsd inside the same try{} as
+//   register-extension → the degraded-path test fails (no /gsd command
+//   registered when register-extension throws). Restore → passes.
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const indexSrc = readFileSync(join(__dirname, "../index.ts"), "utf-8");
-const registerExtSrc = readFileSync(
-  join(__dirname, "../bootstrap/register-extension.ts"),
-  "utf-8",
-);
-
-// ─── index.ts: core /gsd command must be registered before full bootstrap ─────
-
-describe("index.ts bootstrap isolation", () => {
-  test("imports registerGSDCommand from commands/index.js separately", () => {
-    assert.ok(
-      indexSrc.includes('./commands/index.js"') || indexSrc.includes("./commands/index.js'"),
-      "index.ts must import registerGSDCommand from ./commands/index.js",
-    );
-  });
-
-  test("calls registerGSDCommand before importing register-extension.js", () => {
-    const gsdCommandCallPos = indexSrc.indexOf("registerGSDCommand(pi)");
-    const bootstrapImportPos = indexSrc.indexOf(
-      './bootstrap/register-extension.js"',
-    );
 
-    assert.ok(gsdCommandCallPos >= 0, "must call registerGSDCommand(pi)");
-    assert.ok(bootstrapImportPos >= 0, "must import register-extension.js");
+import registerExtension from "../index.ts";
+
+type RegisterFn = (name: string, def: unknown) => void;
+
+function makePi(overrides: Partial<Record<string, unknown>> = {}) {
+  const registered: Array<[string, unknown]> = [];
+  const registerCommand: RegisterFn = (name, def) => {
+    registered.push([name, def]);
+  };
+  const events = {
+    on: () => {},
+    off: () => {},
+    emit: () => {},
+  };
+  const pi = {
+    registerCommand,
+    registerTool: () => {},
+    registerHook: () => {},
+    registerShortcut: () => {},
+    events,
+    ...overrides,
+  };
+  return { pi, registered };
+}
+
+describe("extension bootstrap isolation (#4168, #4172)", () => {
+  test("happy path: /gsd command is registered", async () => {
+    const { pi, registered } = makePi();
+    await registerExtension(pi as any);
+    const names = registered.map(([n]) => n);
     assert.ok(
-      gsdCommandCallPos < bootstrapImportPos,
-      "registerGSDCommand(pi) must be called BEFORE importing register-extension.js",
+      names.includes("gsd"),
+      `expected 'gsd' in registered commands, got ${JSON.stringify(names)}`,
     );
   });
 
-  test("wraps register-extension.js import in try-catch", () => {
-    // The dynamic import of register-extension.js must be inside a try block
-    const tryPos = indexSrc.indexOf("try {");
-    const bootstrapImportPos = indexSrc.indexOf(
-      './bootstrap/register-extension.js"',
-    );
-    const catchPos = indexSrc.indexOf("catch (err)");
-
-    assert.ok(tryPos >= 0, "must have try block");
-    assert.ok(catchPos >= 0, "must have catch block");
+  test("degraded path: /gsd still registered when registerCommand throws for non-core commands", async () => {
+    // Simulate the Windows-style failure: pi.registerCommand throws for a
+    // specific non-core command ('kill' is a simple target registered by
+    // the full bootstrap) — the full bootstrap must fail but /gsd must
+    // already be registered before the failure occurs.
+    const registered: Array<[string, unknown]> = [];
+    const pi = {
+      registerCommand: (name: string, def: unknown) => {
+        if (name !== "gsd" && name !== "worktree" && name !== "exit") {
+          // Let /gsd, /worktree, /exit succeed (they precede the non-core
+          // loop); throw when the first non-core registration fires.
+        }
+        if (name === "kill") throw new Error("simulated windows failure");
+        registered.push([name, def]);
+      },
+      registerTool: () => {},
+      registerHook: () => {},
+      registerShortcut: () => {},
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+    };
+
+    // registerExtension must not throw — the outer try/catch in index.ts
+    // swallows bootstrap failures after /gsd is already registered.
+    await registerExtension(pi as any);
+
+    const names = registered.map(([n]) => n);
     assert.ok(
-      tryPos < bootstrapImportPos && bootstrapImportPos < catchPos,
-      "register-extension.js import must be wrapped in try-catch",
+      names.includes("gsd"),
+      "expected 'gsd' to be registered even when a later command registration throws",
     );
   });
 
-  test("logs warning on bootstrap failure via workflow-logger", () => {
-    assert.ok(
-      indexSrc.includes("logWarning"),
-      "must use logWarning when bootstrap fails",
-    );
-    assert.ok(
-      indexSrc.includes("Extension setup partially failed"),
-      "warning message must indicate partial failure with /gsd still available",
+  test("degraded path: /gsd registered BEFORE any non-core command", async () => {
+    // Ordering guard: the first registerCommand call must be for 'gsd',
+    // because index.ts awaits registerGSDCommand(pi) before importing
+    // register-extension. Regression scenario: if a future refactor moves
+    // registerGSDCommand into the try block or after other registrations,
+    // a failure in those earlier registrations would take /gsd down too.
+    const calls: string[] = [];
+    const pi = {
+      registerCommand: (name: string) => {
+        calls.push(name);
+      },
+      registerTool: () => {},
+      registerHook: () => {},
+      registerShortcut: () => {},
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+    };
+    await registerExtension(pi as any);
+    assert.ok(calls.length > 0, "expected at least one registerCommand call");
+    assert.equal(
+      calls[0],
+      "gsd",
+      `expected 'gsd' to be the first command registered, got ${JSON.stringify(calls)}`,
     );
   });
 });
 
-// ─── register-extension.ts: no double-registration + defensive wrapping ───────
-
-describe("register-extension.ts defensive registration", () => {
-  test("does NOT import or call registerGSDCommand (avoids double-registration)", () => {
-    // registerGSDCommand is now called by index.ts, not register-extension.ts
-    assert.ok(
-      !registerExtSrc.includes("import { registerGSDCommand }"),
-      "register-extension.ts must NOT import registerGSDCommand",
-    );
-
-    // Check the function body of registerGsdExtension doesn't call it
-    const funcBodyStart = registerExtSrc.indexOf(
-      "export function registerGsdExtension",
-    );
-    const funcBody = registerExtSrc.slice(funcBodyStart);
-    assert.ok(
-      !funcBody.includes("registerGSDCommand(pi)"),
-      "registerGsdExtension must NOT call registerGSDCommand(pi)",
-    );
-  });
-
-  test("still registers worktree, exit, and kill commands", () => {
-    const funcBodyStart = registerExtSrc.indexOf(
-      "export function registerGsdExtension",
-    );
-    const funcBody = registerExtSrc.slice(funcBodyStart);
-
-    assert.ok(
-      funcBody.includes("registerWorktreeCommand(pi)"),
-      "must register worktree command",
-    );
-    assert.ok(
-      funcBody.includes("registerExitCommand(pi)"),
-      "must register exit command",
-    );
-    assert.ok(
-      funcBody.includes('"kill"'),
-      "must register kill command",
-    );
-  });
-
-  test("wraps non-critical registrations in individual try-catch blocks", () => {
-    const funcBodyStart = registerExtSrc.indexOf(
-      "export function registerGsdExtension",
-    );
-    const funcBody = registerExtSrc.slice(funcBodyStart);
-
-    // Each non-critical registration should be wrapped with error handling
-    const registrationNames = [
-      "dynamic-tools",
-      "db-tools",
-      "journal-tools",
-      "query-tools",
-      "shortcuts",
-      "hooks",
-    ];
-
-    for (const name of registrationNames) {
-      assert.ok(
-        funcBody.includes(`"${name}"`),
-        `non-critical registration "${name}" must be present`,
-      );
-    }
-
-    // Must have try-catch inside the registration loop
+// Behavioural contract for registerGsdExtension itself: each non-core
+// registration is wrapped in its own try/catch so one failure does not
+// prevent siblings from loading.
+
+import { registerGsdExtension } from "../bootstrap/register-extension.ts";
+
+describe("registerGsdExtension defensive registration", () => {
+  test("a failing shortcut registration does not prevent kill command registration", async () => {
+    // `shortcuts` is registered via a non-critical slot that is wrapped in
+    // its own try/catch. `kill` is registered before the non-critical loop
+    // as a critical command. Simulate: registerShortcut throws. Expect:
+    // 'kill' is still registered, registerGsdExtension does not throw.
+    const registered: string[] = [];
+    const pi = {
+      registerCommand: (name: string) => {
+        registered.push(name);
+      },
+      registerTool: () => {},
+      registerHook: () => {},
+      registerShortcut: () => {
+        throw new Error("simulated platform-specific shortcut failure");
+      },
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+    };
+    assert.doesNotThrow(() => registerGsdExtension(pi as any));
     assert.ok(
-      funcBody.includes("try {") && funcBody.includes("catch (err)"),
-      "must have try-catch for non-critical registrations",
+      registered.includes("kill"),
+      `expected 'kill' to be registered despite shortcut failure, got ${JSON.stringify(registered)}`,
     );
   });
 
-  test("logs warning when a non-critical registration fails", () => {
-    assert.ok(
-      registerExtSrc.includes("Failed to register"),
-      "must log descriptive warning for individual registration failures",
-    );
+  test("does NOT register /gsd (caller's responsibility, avoids double-registration)", () => {
+    const registered: string[] = [];
+    const pi = {
+      registerCommand: (name: string) => {
+        registered.push(name);
+      },
+      registerTool: () => {},
+      registerHook: () => {},
+      registerShortcut: () => {},
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+    };
+    registerGsdExtension(pi as any);
     assert.ok(
-      registerExtSrc.includes("logWarning"),
-      "must use logWarning from workflow-logger",
+      !registered.includes("gsd"),
+      `registerGsdExtension must NOT register 'gsd' (it is registered separately by index.ts), got ${JSON.stringify(registered)}`,
     );
   });
 });

package/src/resources/extensions/gsd/tests/file-change-validator.test.ts

@@ -15,6 +15,64 @@ function git(cwd: string, ...args: string[]): string {
   }).trim();
 }
 
+test("validateFileChanges works on repos with a single commit (no HEAD~1)", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  git(base, "init");
+  git(base, "config", "user.email", "test@example.com");
+  git(base, "config", "user.name", "Test User");
+
+  writeFileSync(join(base, "foo.ts"), "export const x = 1;\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "initial");
+
+  // With only one commit, HEAD~1 doesn't exist — this must not throw
+  const audit = validateFileChanges(base, ["foo.ts"], []);
+
+  assert.ok(audit, "audit should be produced for single-commit repo");
+  assert.deepEqual(audit.unexpectedFiles, []);
+  assert.deepEqual(audit.missingFiles, []);
+});
+
+test("validateFileChanges excludes allowlisted files from unexpected-change warnings", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  mkdirSync(join(base, "tracking", "history"), { recursive: true });
+  git(base, "init");
+  git(base, "config", "user.email", "test@example.com");
+  git(base, "config", "user.name", "Test User");
+
+  writeFileSync(join(base, "src.ts"), "initial\n");
+  writeFileSync(join(base, "tracking", "history", "2026-04-20-snapshot.md"), "initial\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "initial");
+
+  writeFileSync(join(base, "src.ts"), "updated\n");
+  writeFileSync(join(base, "tracking", "history", "2026-04-20-snapshot.md"), "updated\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "update");
+
+  // Without allowlist: tracking/history snapshot is unexpected
+  const auditWithout = validateFileChanges(base, ["src.ts"], []);
+  assert.ok(auditWithout, "audit should be produced");
+  assert.ok(
+    auditWithout.unexpectedFiles.includes("tracking/history/2026-04-20-snapshot.md"),
+    "snapshot should be unexpected without allowlist",
+  );
+
+  // With glob allowlist: snapshot is excluded
+  const auditWith = validateFileChanges(base, ["src.ts"], [], ["tracking/history/**"]);
+  assert.ok(auditWith, "audit should be produced with allowlist");
+  assert.deepEqual(auditWith.unexpectedFiles, [], "no unexpected files when snapshot is allowlisted");
+  assert.equal(
+    auditWith.violations.filter(v => v.severity === "warning").length,
+    0,
+    "no warnings when all unexpected files are allowlisted",
+  );
+});
+
 test("validateFileChanges ignores inline descriptions in expected output paths", (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));

package/src/resources/extensions/gsd/tests/file-lock.test.ts

@@ -52,7 +52,7 @@ test("withFileLock: executes callback when file does not exist", async () => {
   }
 });
 
-test("withFileLockSync: falls back to unlocked callback on ELOCKED", () => {
+test("withFileLockSync: throws ELOCKED by default (no silent fallback)", () => {
   if (!hasProperLockfile() || process.platform === "win32") {
     return;
   }
@@ -65,19 +65,56 @@ test("withFileLockSync: falls back to unlocked callback on ELOCKED", () => {
   const release = lockfile.lockSync(filePath, { retries: 0, stale: 10000 });
   try {
     let called = 0;
-    const result = withFileLockSync(filePath, () => {
-      called++;
-      return "fallback-ok";
-    });
+    assert.throws(
+      () => {
+        withFileLockSync(
+          filePath,
+          () => {
+            called++;
+            return "should-not-return";
+          },
+          { retries: 0 },
+        );
+      },
+      (err: any) => err?.code === "ELOCKED",
+    );
+    assert.equal(called, 0, "callback must not run when lock cannot be acquired");
+  } finally {
+    release();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("withFileLockSync: onLocked=\"skip\" runs callback unlocked on ELOCKED", () => {
+  if (!hasProperLockfile() || process.platform === "win32") {
+    return;
+  }
+
+  const lockfile = require("proper-lockfile");
+  const dir = mkdtempSync(join(tmpdir(), "gsd-file-lock-test-"));
+  const filePath = join(dir, "locked.jsonl");
+  writeFileSync(filePath, "{}\n", "utf-8");
+
+  const release = lockfile.lockSync(filePath, { retries: 0, stale: 10000 });
+  try {
+    let called = 0;
+    const result = withFileLockSync(
+      filePath,
+      () => {
+        called++;
+        return "fallback-ok";
+      },
+      { retries: 0, onLocked: "skip" },
+    );
     assert.equal(result, "fallback-ok");
-    assert.equal(called, 1, "callback should run even when lock acquisition fails");
+    assert.equal(called, 1, "callback should run when onLocked is skip");
   } finally {
     release();
     rmSync(dir, { recursive: true, force: true });
   }
 });
 
-test("withFileLock: falls back to unlocked callback on ELOCKED", async () => {
+test("withFileLock: throws ELOCKED by default (no silent fallback)", async () => {
   if (!hasProperLockfile() || process.platform === "win32") {
     return;
   }
@@ -90,12 +127,49 @@ test("withFileLock: falls back to unlocked callback on ELOCKED", async () => {
   const release = await lockfile.lock(filePath, { retries: 0, stale: 10000 });
   try {
     let called = 0;
-    const result = await withFileLock(filePath, async () => {
-      called++;
-      return "fallback-ok";
-    });
+    await assert.rejects(
+      async () => {
+        await withFileLock(
+          filePath,
+          async () => {
+            called++;
+            return "should-not-return";
+          },
+          { retries: 0 },
+        );
+      },
+      (err: any) => err?.code === "ELOCKED",
+    );
+    assert.equal(called, 0, "callback must not run when lock cannot be acquired");
+  } finally {
+    await release();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("withFileLock: onLocked=\"skip\" runs callback unlocked on ELOCKED", async () => {
+  if (!hasProperLockfile() || process.platform === "win32") {
+    return;
+  }
+
+  const lockfile = require("proper-lockfile");
+  const dir = mkdtempSync(join(tmpdir(), "gsd-file-lock-test-"));
+  const filePath = join(dir, "locked.jsonl");
+  writeFileSync(filePath, "{}\n", "utf-8");
+
+  const release = await lockfile.lock(filePath, { retries: 0, stale: 10000 });
+  try {
+    let called = 0;
+    const result = await withFileLock(
+      filePath,
+      async () => {
+        called++;
+        return "fallback-ok";
+      },
+      { retries: 0, onLocked: "skip" },
+    );
     assert.equal(result, "fallback-ok");
-    assert.equal(called, 1, "callback should run even when lock acquisition fails");
+    assert.equal(called, 1, "callback should run when onLocked is skip");
   } finally {
     await release();
     rmSync(dir, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/finalize-timeout-guard.test.ts

@@ -26,14 +26,6 @@ import { MAX_FINALIZE_TIMEOUTS } from "../auto/types.ts";
 
 const { assertTrue, assertEq, report } = createTestContext();
 
-function getRunFinalizeBody(phasesSource: string): string {
-  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
-  assertTrue(fnIdx > 0, "runFinalize function should exist in phases.ts");
-
-  const nextExportIdx = phasesSource.indexOf("\nexport ", fnIdx + 1);
-  return phasesSource.slice(fnIdx, nextExportIdx > fnIdx ? nextExportIdx : undefined);
-}
-
 // ═══ Test: withTimeout resolves when inner promise resolves promptly ══════════
 
 {
@@ -142,45 +134,6 @@ function getRunFinalizeBody(phasesSource: string): string {
   assertEq(result.timedOut, false, "should not time out");
 }
 
-// ═══ Test: runFinalize wraps BOTH pre and post verification with withTimeout ═
-
-{
-  console.log("\n=== #3757: runFinalize wraps preVerification with timeout guard ===");
-
-  const { readFileSync } = await import("node:fs");
-  const phasesSource = readFileSync(
-    new URL("../auto/phases.ts", import.meta.url),
-    "utf-8",
-  );
-
-  const fnBody = getRunFinalizeBody(phasesSource);
-
-  // postUnitPreVerification must be wrapped in withTimeout
-  const preTimeoutIdx = fnBody.indexOf("withTimeout(");
-  assertTrue(preTimeoutIdx > 0, "withTimeout should appear in runFinalize");
-
-  const preVerIdx = fnBody.indexOf("postUnitPreVerification");
-  assertTrue(preVerIdx > 0, "postUnitPreVerification should appear in runFinalize");
-
-  // The first withTimeout should wrap postUnitPreVerification (not postUnitPostVerification)
-  const firstWithTimeout = fnBody.slice(preTimeoutIdx, preTimeoutIdx + 200);
-  assertTrue(
-    firstWithTimeout.includes("postUnitPreVerification"),
-    "first withTimeout in runFinalize should wrap postUnitPreVerification",
-  );
-
-  // postUnitPostVerification must also be wrapped
-  const postVerIdx = fnBody.indexOf("postUnitPostVerification");
-  assertTrue(postVerIdx > 0, "postUnitPostVerification should appear in runFinalize");
-
-  // Count withTimeout occurrences — should be at least 2 (pre + post)
-  const timeoutCount = (fnBody.match(/withTimeout\(/g) || []).length;
-  assertTrue(
-    timeoutCount >= 2,
-    `runFinalize should have at least 2 withTimeout guards (found ${timeoutCount})`,
-  );
-}
-
 // ═══ Test: MAX_FINALIZE_TIMEOUTS is defined and reasonable ═══════════════════
 
 {
@@ -200,62 +153,13 @@ function getRunFinalizeBody(phasesSource: string): string {
   );
 }
 
-// ═══ Test: timeout handlers escalate after consecutive timeouts ══════════════
-
-{
-  console.log("\n=== #3757: timeout handlers escalate and detach currentUnit ===");
-
-  const { readFileSync } = await import("node:fs");
-  const phasesSource = readFileSync(
-    new URL("../auto/phases.ts", import.meta.url),
-    "utf-8",
-  );
-
-  const fnBody = getRunFinalizeBody(phasesSource);
-
-  const helperCallCount = (fnBody.match(/failClosedOnFinalizeTimeout\(/g) || []).length;
-  assertTrue(
-    helperCallCount >= 2,
-    `runFinalize should route both timeout branches through failClosedOnFinalizeTimeout (found ${helperCallCount})`,
-  );
-
-  const helperStart = phasesSource.indexOf("async function failClosedOnFinalizeTimeout");
-  assertTrue(helperStart > 0, "failClosedOnFinalizeTimeout helper should exist");
-  const helperEnd = phasesSource.indexOf("// ─── runPreDispatch", helperStart);
-  const helperBody = phasesSource.slice(helperStart, helperEnd > helperStart ? helperEnd : undefined);
-
-  const incrementCount = (helperBody.match(/consecutiveFinalizeTimeouts\+\+/g) || []).length;
-  assertTrue(
-    incrementCount >= 1,
-    `timeout helper should increment consecutiveFinalizeTimeouts (found ${incrementCount})`,
-  );
-
-  const detachCount = (helperBody.match(/s\.currentUnit\s*=\s*null/g) || []).length;
-  assertTrue(
-    detachCount >= 1,
-    `timeout helper should detach s.currentUnit (found ${detachCount})`,
-  );
-
-  const pauseCount = (helperBody.match(/pauseAuto\(/g) || []).length;
-  assertTrue(
-    pauseCount >= 1,
-    `timeout helper should pause auto-mode (found ${pauseCount})`,
-  );
-
-  assertTrue(
-    helperBody.includes('eventType: "unit-end"'),
-    "timeout helper should emit a terminal unit-end event",
-  );
-  assertTrue(
-    helperBody.includes('phase: "finalize-timeout"'),
-    "timeout helper should persist finalize-timeout runtime state",
-  );
-
-  // Successful finalize should reset the counter
-  assertTrue(
-    fnBody.includes("consecutiveFinalizeTimeouts = 0"),
-    "should reset consecutiveFinalizeTimeouts on successful finalize",
-  );
-}
+// Note: the two previous source-grep blocks that scanned phases.ts for
+// `withTimeout(` / `failClosedOnFinalizeTimeout(` occurrences were removed
+// under #4825 — they encoded implementation shape (Goodhart) and broke on
+// any helper/loop refactor without catching a real regression. The intended
+// behavioural invariant (pre+post verification hangs → pauseAuto called,
+// unit-end emitted, escalation counter incremented) should be covered by a
+// runFinalize integration test with mocked hanging verification — tracked
+// separately. Refs #4825.
 
 report();