@indigoai-us/hq-cloud 5.24.0 → 5.26.0

package/src/bin/sync-runner.test.ts

@@ -11,12 +11,21 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { runRunner, resolveDeletePolicy } from "./sync-runner.js";
+import {
+  runRunner,
+  runRunnerWithLoop,
+  resolveDeletePolicy,
+  resolveSkipPersonal,
+  routeChangeToTarget,
+  buildTargetedPushArgv,
+} from "./sync-runner.js";
 import type {
   RunnerEvent,
   RunnerDeps,
   VaultClientSurface,
+  WatcherSurface,
 } from "./sync-runner.js";
+import { FakeClock } from "../watcher.js";
 import type { SyncResult, SyncOptions } from "../cli/sync.js";
 import type { ShareResult, ShareOptions } from "../cli/share.js";
 import type {
@@ -80,6 +89,7 @@ function defaultShareResult(overrides: Partial<ShareResult> = {}): ShareResult {
     filesDeleted: 0,
     filesTombstoned: 0,
     filesRefusedStale: 0,
+    filesExcludedByPolicy: 0,
     conflictPaths: [],
     aborted: false,
     ...overrides,
@@ -687,7 +697,9 @@ describe("per-company fanout", () => {
     const complete = deps.stdout
       .events()
       .find((e) => e.type === "complete") as Extract<RunnerEvent, { type: "complete" }>;
-    // Pull-only run: upload counters are 0.
+    // Pull-only run: upload counters are 0. Push-side counters added in
+    // 5.25 (filesTombstoned/filesRefusedStale/filesExcludedByPolicy) are
+    // also 0 because no push leg ran.
     expect(complete).toEqual({
       type: "complete",
       company: "acme",
@@ -699,6 +711,9 @@ describe("per-company fanout", () => {
       aborted: result.aborted,
       filesUploaded: 0,
       bytesUploaded: 0,
+      filesTombstoned: 0,
+      filesRefusedStale: 0,
+      filesExcludedByPolicy: 0,
       newFiles: result.newFiles,
       newFilesCount: result.newFilesCount,
     });
@@ -1696,6 +1711,483 @@ describe("watch mode argv parsing", () => {
     expect(code).toBe(1);
     expect(deps.stderr.raw()).toContain("--poll-remote-ms requires --watch");
   });
+
+  it("accepts --event-push together with --watch (parser-level)", async () => {
+    const deps = makeDeps({
+      createVaultClient: () => makeVaultStub({ memberships: [] }),
+    });
+    // One-shot single pass via runRunner (no loop) — the parser must accept
+    // --event-push as a known flag. No memberships → setup-needed → exit 0.
+    const code = await runRunner(
+      ["--companies", "--watch", "--event-push"],
+      deps,
+    );
+    expect(deps.stderr.raw()).not.toContain("Unknown argument");
+    expect(code).toBe(0);
+  });
+
+  it("rejects --event-push without --watch (the flag has no meaning otherwise)", async () => {
+    const deps = makeDeps();
+    const code = await runRunner(["--companies", "--event-push"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("--event-push requires --watch");
+  });
+
+  it("is OFF by default — plain --watch run does not require/accept event flags implicitly", async () => {
+    const deps = makeDeps({
+      createVaultClient: () => makeVaultStub({ memberships: [] }),
+    });
+    const code = await runRunner(["--companies", "--watch"], deps);
+    expect(deps.stderr.raw()).not.toContain("Unknown argument");
+    expect(code).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// US-003 — event-driven push routing helpers (pure)
+// ---------------------------------------------------------------------------
+
+describe("routeChangeToTarget", () => {
+  it("routes companies/<slug>/... to a targeted company push", () => {
+    expect(routeChangeToTarget("companies/indigo/board.json")).toEqual({
+      kind: "company",
+      slug: "indigo",
+    });
+    expect(
+      routeChangeToTarget("companies/acme/projects/x/prd.json"),
+    ).toEqual({ kind: "company", slug: "acme" });
+  });
+
+  it("routes non-company top-levels to the personal target", () => {
+    expect(routeChangeToTarget("personal/notes.md")).toEqual({
+      kind: "personal",
+    });
+    expect(routeChangeToTarget("core/policies/x.md")).toEqual({
+      kind: "personal",
+    });
+    expect(routeChangeToTarget("README.md")).toEqual({ kind: "personal" });
+  });
+
+  it("normalizes OS path separators and ./ prefixes", () => {
+    expect(
+      routeChangeToTarget(["companies", "indigo", "f.json"].join(path.sep)),
+    ).toEqual({ kind: "company", slug: "indigo" });
+    expect(routeChangeToTarget("./companies/indigo/f.json")).toEqual({
+      kind: "company",
+      slug: "indigo",
+    });
+  });
+
+  it("returns null for unattributable paths (defensive)", () => {
+    expect(routeChangeToTarget("")).toBeNull();
+    expect(routeChangeToTarget("..")).toBeNull();
+    expect(routeChangeToTarget("../escape")).toBeNull();
+    // companies top-level with no slug segment is unattributable — a real
+    // edit always lands at companies/<slug>/..., never at bare "companies".
+    expect(routeChangeToTarget("companies")).toBeNull();
+    expect(routeChangeToTarget("companies/")).toBeNull();
+  });
+});
+
+describe("buildTargetedPushArgv", () => {
+  it("company route → --company <slug> --direction push", () => {
+    expect(
+      buildTargetedPushArgv({ kind: "company", slug: "indigo" }, [
+        "--companies",
+        "--hq-root",
+        "/tmp/hq",
+        "--on-conflict",
+        "keep",
+      ]),
+    ).toEqual([
+      "--company",
+      "indigo",
+      "--direction",
+      "push",
+      "--hq-root",
+      "/tmp/hq",
+      "--on-conflict",
+      "keep",
+    ]);
+  });
+
+  it("personal route → --companies --direction push (inherits root/conflict)", () => {
+    expect(
+      buildTargetedPushArgv({ kind: "personal" }, [
+        "--companies",
+        "--hq-root",
+        "/tmp/hq",
+      ]),
+    ).toEqual(["--companies", "--direction", "push", "--hq-root", "/tmp/hq"]);
+  });
+
+  it("carries no flags when the base argv has none", () => {
+    expect(buildTargetedPushArgv({ kind: "personal" }, ["--companies"])).toEqual(
+      ["--companies", "--direction", "push"],
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// US-003 — runRunnerWithLoop event-push wiring (deterministic, no real timers)
+// ---------------------------------------------------------------------------
+//
+// These exercise the full Phase 1 wiring through injectable seams:
+//   - runPass: a spy standing in for runRunner (no real S3/auth)
+//   - clock:   FakeClock to advance the debounce window deterministically
+//   - createWatcher: a controllable stub satisfying WatcherSurface
+//   - sleep / onShutdownSignal: drive the poll loop + shutdown without real
+//     timers or process signals
+//
+// The loop is an infinite poll; we drive ONE pass then trigger shutdown so the
+// promise resolves. A test helper wires everything and returns the controls.
+
+interface WatcherStub extends WatcherSurface {
+  emit(changedRelPath?: string): void;
+  started: boolean;
+  disposed: boolean;
+}
+
+function makeWatcherStub(): WatcherStub {
+  const listeners = new Set<(p?: string) => void>();
+  const stub: WatcherStub = {
+    started: false,
+    disposed: false,
+    onChange(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start() {
+      this.started = true;
+    },
+    stop() {
+      /* no-op for the stub */
+    },
+    dispose() {
+      this.disposed = true;
+      listeners.clear();
+    },
+    emit(changedRelPath?: string) {
+      for (const l of [...listeners]) l(changedRelPath);
+    },
+  };
+  return stub;
+}
+
+describe("runRunnerWithLoop — event-push wiring", () => {
+  it("starts the watcher alongside the poll loop when --event-push is on", async () => {
+    const watcher = makeWatcherStub();
+    let triggerShutdown = () => {};
+    const runPass = vi.fn().mockResolvedValue(0);
+
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock: new FakeClock(),
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}), // never resolves; shutdown ends it
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+
+    // Let the first poll pass run, then shut down.
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(watcher.started).toBe(true);
+    triggerShutdown();
+    await loop;
+    // The poll pass ran at least once (safety-net path still runs).
+    expect(runPass).toHaveBeenCalled();
+    expect(watcher.disposed).toBe(true);
+  });
+
+  it("trigger-on-change: a debounced changed signal runs a targeted company push", async () => {
+    const watcher = makeWatcherStub();
+    const clock = new FakeClock();
+    let triggerShutdown = () => {};
+    const runPass = vi.fn().mockResolvedValue(0);
+
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock,
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}),
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+
+    // Drain the initial poll pass.
+    await Promise.resolve();
+    await Promise.resolve();
+    runPass.mockClear();
+
+    // Fire a change for an indigo file; advance the (zero) driver window.
+    watcher.emit("companies/indigo/board.json");
+    clock.advance(0);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const targetedCall = runPass.mock.calls.find((c) =>
+      (c[0] as string[]).includes("--company"),
+    );
+    expect(targetedCall).toBeDefined();
+    expect(targetedCall![0]).toEqual([
+      "--company",
+      "indigo",
+      "--direction",
+      "push",
+      "--hq-root",
+      "/tmp/hq",
+    ]);
+
+    triggerShutdown();
+    await loop;
+  });
+
+  it("bare signal (no path) routes the targeted push to the personal vault", async () => {
+    const watcher = makeWatcherStub();
+    const clock = new FakeClock();
+    let triggerShutdown = () => {};
+    const runPass = vi.fn().mockResolvedValue(0);
+
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock,
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}),
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+
+    await Promise.resolve();
+    await Promise.resolve();
+    runPass.mockClear();
+
+    watcher.emit(); // no path — TreeWatcher's bare signal shape
+    clock.advance(0);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const personalCall = runPass.mock.calls.find(
+      (c) =>
+        (c[0] as string[]).includes("--companies") &&
+        (c[0] as string[]).includes("--direction"),
+    );
+    expect(personalCall).toBeDefined();
+    expect(personalCall![0]).toEqual([
+      "--companies",
+      "--direction",
+      "push",
+      "--hq-root",
+      "/tmp/hq",
+    ]);
+
+    triggerShutdown();
+    await loop;
+  });
+
+  it("overlap guard: a change during an in-flight pass does not start a concurrent pass", async () => {
+    const watcher = makeWatcherStub();
+    const clock = new FakeClock();
+    let triggerShutdown = () => {};
+
+    // A controllable in-flight pass: the first call hangs until we release it.
+    let release: () => void = () => {};
+    const firstGate = new Promise<void>((r) => {
+      release = r;
+    });
+    let callCount = 0;
+    let maxConcurrent = 0;
+    let active = 0;
+    const runPass = vi.fn().mockImplementation(async () => {
+      active++;
+      maxConcurrent = Math.max(maxConcurrent, active);
+      callCount++;
+      if (callCount === 1) await firstGate; // hold the first (poll) pass
+      active--;
+      return 0;
+    });
+
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock,
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}),
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+
+    // The first poll pass is now in flight and gated.
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(active).toBe(1);
+
+    // Fire a change while the pass is in flight → must be collapsed, not run.
+    watcher.emit("companies/indigo/x.json");
+    clock.advance(0);
+    await Promise.resolve();
+    await Promise.resolve();
+    // Still exactly one active pass; the watcher trigger did not overlap.
+    expect(maxConcurrent).toBe(1);
+
+    // Release the gated pass; the collapsed change re-arms and runs next.
+    release();
+    await Promise.resolve();
+    await Promise.resolve();
+    clock.advance(0);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Never more than one pass concurrently across the whole run.
+    expect(maxConcurrent).toBe(1);
+
+    triggerShutdown();
+    await loop;
+  });
+
+  it("poll-still-runs: the poll loop fires passes independent of the watcher", async () => {
+    const watcher = makeWatcherStub();
+    let triggerShutdown = () => {};
+    let passes = 0;
+    // Box the resolver so TS control-flow doesn't narrow it to `null` at the
+    // call sites below (the assignment happens inside a deferred closure).
+    const poll: { resolve: (() => void) | null } = { resolve: null };
+    const runPass = vi.fn().mockImplementation(async () => {
+      passes++;
+      return 0;
+    });
+    // A sleep we can step: resolve once to allow a second poll pass.
+    const sleep = () =>
+      new Promise<void>((resolve) => {
+        poll.resolve = resolve;
+      });
+
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock: new FakeClock(),
+        createWatcher: () => watcher,
+        sleep,
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+
+    // First poll pass runs, then awaits sleep.
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(passes).toBe(1);
+
+    // Step the poll interval → a second poll pass runs (safety net cadence).
+    poll.resolve?.();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(passes).toBeGreaterThanOrEqual(2);
+
+    triggerShutdown();
+    // Release any pending sleep so the loop can observe shutdown and exit.
+    poll.resolve?.();
+    await loop;
+  });
+
+  it("clean shutdown: SIGTERM disposes the watcher and resolves the loop with no leaks", async () => {
+    const watcher = makeWatcherStub();
+    const clock = new FakeClock();
+    let triggerShutdown = () => {};
+    let detached = false;
+    const runPass = vi.fn().mockResolvedValue(0);
+
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock,
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}),
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {
+            detached = true;
+          };
+        },
+      },
+    );
+
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(watcher.started).toBe(true);
+
+    triggerShutdown();
+    const code = await loop;
+    expect(code).toBe(0);
+    expect(watcher.disposed).toBe(true); // watcher torn down
+    expect(detached).toBe(true); // signal handler detached (no leaked listener)
+    // No pending FakeClock timers left behind by the driver's debounce.
+    expect(clock.pendingTimerCount()).toBe(0);
+  });
+
+  it("a non-zero poll pass exit returns immediately (hard error surfaces)", async () => {
+    const watcher = makeWatcherStub();
+    const runPass = vi.fn().mockResolvedValue(2);
+
+    const code = await runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock: new FakeClock(),
+        createWatcher: () => watcher,
+        sleep: () => Promise.resolve(),
+        onShutdownSignal: () => () => {},
+      },
+    );
+    expect(code).toBe(2);
+    expect(watcher.disposed).toBe(true);
+  });
+
+  it("without --event-push, no watcher is created (poll-only safety net)", async () => {
+    let triggerShutdown = () => {};
+    const createWatcher = vi.fn(() => makeWatcherStub());
+    const runPass = vi.fn().mockResolvedValue(0);
+
+    const loop = runRunnerWithLoop(["--companies", "--watch"], {
+      runPass,
+      createWatcher,
+      sleep: () => new Promise<void>(() => {}),
+      onShutdownSignal: (handler) => {
+        triggerShutdown = handler;
+        return () => {};
+      },
+    });
+
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(createWatcher).not.toHaveBeenCalled();
+    expect(runPass).toHaveBeenCalled();
+    triggerShutdown();
+    await loop;
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -1709,11 +2201,11 @@ beforeEach(() => {
 // ── resolveDeletePolicy: env-var contract ───────────────────────────────────
 //
 // `HQ_SYNC_DELETE_POLICY` is the documented rollback knob for the
-// currency-gated default landed in 5.24. The helper centralizes the
-// allowlist + default so every callsite (both the personal and company push
-// paths in the runner) gets identical semantics. Tests pin the four expected
-// behaviors so a future regression on the allowlist or default surfaces here
-// instead of in the field.
+// currency-gated default that became default in 5.25 (after a 5.24 soak).
+// The helper centralizes the allowlist + default so every callsite (both
+// the personal and company push paths in the runner) gets identical
+// semantics. Tests pin the four expected behaviors so a future regression
+// on the allowlist or default surfaces here instead of in the field.
 
 describe("resolveDeletePolicy", () => {
   let originalEnv: string | undefined;
@@ -1731,12 +2223,11 @@ describe("resolveDeletePolicy", () => {
     }
   });
 
-  it("defaults to 'owned-only' in 5.24 (staged-default rollout, flip in 5.25)", () => {
-    // 5.24 ships the currency-gated CODE PATH but holds the default flip
-    // for a soak window. When the default flips to 'currency-gated' in
-    // 5.25, this assertion changes — both edits live next to each other so
-    // the rollout sequence is obvious from the diff.
-    expect(resolveDeletePolicy()).toBe("owned-only");
+  it("defaults to 'currency-gated' in 5.25 (post-soak default flip)", () => {
+    // 5.24 shipped the code path with `owned-only` as default; 5.25 flips
+    // the default to `currency-gated` after the soak window. Rollback knob
+    // is `HQ_SYNC_DELETE_POLICY=owned-only` for anyone surprised.
+    expect(resolveDeletePolicy()).toBe("currency-gated");
   });
 
   it.each(["currency-gated", "owned-only", "all"] as const)(
@@ -1749,11 +2240,62 @@ describe("resolveDeletePolicy", () => {
 
   it("falls back to default on unknown env values (no silent corruption)", () => {
     process.env.HQ_SYNC_DELETE_POLICY = "yolo";
-    expect(resolveDeletePolicy()).toBe("owned-only");
+    expect(resolveDeletePolicy()).toBe("currency-gated");
   });
 
   it("treats empty string as unset → default", () => {
     process.env.HQ_SYNC_DELETE_POLICY = "";
-    expect(resolveDeletePolicy()).toBe("owned-only");
+    expect(resolveDeletePolicy()).toBe("currency-gated");
+  });
+});
+
+// ── resolveSkipPersonal: flag-OR-env combination ───────────────────────────
+//
+// Two inputs combine: the `--skip-personal` CLI flag and the
+// `HQ_SYNC_SKIP_PERSONAL` env var. Either being truthy skips personal sync.
+// The flag is the explicit-for-this-invocation knob (menubar passes it when
+// the user toggled "Sync personal vault" off); the env is the persistent
+// child-process default. Both surfaces tested so a regression on either
+// short-circuit path surfaces here.
+
+describe("resolveSkipPersonal", () => {
+  let originalEnv: string | undefined;
+
+  beforeEach(() => {
+    originalEnv = process.env.HQ_SYNC_SKIP_PERSONAL;
+    delete process.env.HQ_SYNC_SKIP_PERSONAL;
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.HQ_SYNC_SKIP_PERSONAL;
+    } else {
+      process.env.HQ_SYNC_SKIP_PERSONAL = originalEnv;
+    }
   });
+
+  it("defaults to false (personal sync enabled, current behavior)", () => {
+    expect(resolveSkipPersonal(false)).toBe(false);
+  });
+
+  it("flag=true short-circuits to true regardless of env", () => {
+    process.env.HQ_SYNC_SKIP_PERSONAL = "no"; // explicit "no" in env
+    expect(resolveSkipPersonal(true)).toBe(true);
+  });
+
+  it.each(["1", "true", "yes", "TRUE", "Yes"])(
+    "env value '%s' (truthy) -> true",
+    (val) => {
+      process.env.HQ_SYNC_SKIP_PERSONAL = val;
+      expect(resolveSkipPersonal(false)).toBe(true);
+    },
+  );
+
+  it.each(["0", "false", "no", "", "unset-equiv"])(
+    "env value '%s' (falsy) -> false",
+    (val) => {
+      process.env.HQ_SYNC_SKIP_PERSONAL = val;
+      expect(resolveSkipPersonal(false)).toBe(false);
+    },
+  );
 });