@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/src/sync/push-transport.ts

@@ -0,0 +1,231 @@
+/**
+ * PushTransport — outbound shipping seam for the watcher daemon.
+ *
+ * The daemon wires file-watcher events into a transport that ships each
+ * PushEvent to the cloud. Defining the interface here lets the daemon ship
+ * with a swappable boundary — tests inject a fake, a later story swaps in a
+ * concrete WebSocket/HTTP implementation, and the daemon entry point never
+ * changes.
+ *
+ * Lifecycle
+ * ─────────
+ *  - `start()` is awaited BEFORE the watcher is started. It's the place
+ *    to open sockets, refresh tokens, etc.
+ *  - `publish(event)` is called for every coalesced PushEvent the watcher
+ *    emits. Implementations decide whether to buffer, batch, or send
+ *    inline; the daemon awaits the returned promise so back-pressure can
+ *    be honored.
+ *  - `dispose()` is awaited DURING shutdown, AFTER the watcher has been
+ *    torn down. Implementations should drain in-flight publishes (with
+ *    their own internal timeout) and close any sockets.
+ *  - `connected` is a passive boolean used by the health endpoint. It MAY
+ *    flap during reconnect attempts — that's fine; consumers treat it as
+ *    advisory, not a contract.
+ *
+ * The `NoopPushTransport` shipped here is the default when no transport
+ * is wired in: it counts publishes (so unit tests can assert delivery)
+ * and logs nothing — observers should rely on the watcher's `onEvent`
+ * counter on the daemon side, not the transport's internals.
+ *
+ * Ported from indigoai-us/hq-pro PR #112 (src/sync/push-transport.ts) into
+ * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
+ */
+
+import { encodePushEvent, type PushEvent } from "./push-event.js";
+
+export interface PushTransport {
+  /** Open sockets, refresh tokens. Awaited before the watcher starts. */
+  start(): Promise<void>;
+  /** Ship one coalesced PushEvent. Awaited per event for back-pressure. */
+  publish(event: PushEvent): Promise<void>;
+  /** Drain + close. Awaited during daemon shutdown after watcher.dispose. */
+  dispose(): Promise<void>;
+  /** Advisory: is the transport currently believed to be connected? */
+  readonly connected: boolean;
+}
+
+/**
+ * Default `PushTransport` used until a real implementation lands.
+ *
+ * Behavior:
+ *  - `start()` flips `connected` to true.
+ *  - `publish()` increments a counter (visible via `publishedCount`).
+ *  - `dispose()` flips `connected` back to false.
+ *
+ * Deliberately silent: when the daemon runs with this default, the
+ * watcher's per-event log line (emitted by the daemon itself, not the
+ * transport) is the only observability. That keeps the noop from drowning
+ * the log when high-rate writes hit a dev machine.
+ */
+export class NoopPushTransport implements PushTransport {
+  private _connected = false;
+  private _count = 0;
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  /** Test/observability hook: how many events have been published. */
+  get publishedCount(): number {
+    return this._count;
+  }
+
+  async start(): Promise<void> {
+    this._connected = true;
+  }
+
+  async publish(_event: PushEvent): Promise<void> {
+    this._count += 1;
+  }
+
+  async dispose(): Promise<void> {
+    this._connected = false;
+  }
+}
+
+// ─── HttpPushTransport ───────────────────────────────────────────────────────
+
+/**
+ * Minimal fetch surface so tests can inject a mocked `fetch` without pulling
+ * in DOM/undici types. Matches the subset of the global `fetch` we use.
+ */
+export type FetchLike = (
+  input: string,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+  },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+/**
+ * Async getter for the current Cognito access token. Long-running daemons MUST
+ * pass a getter (not a captured string) so each publish resolves the freshest
+ * token — mirrors {@link VaultServiceConfig.authToken} semantics in types.ts.
+ * A static string is also accepted for short-lived tools and tests.
+ */
+export type AuthTokenSource = string | (() => string | Promise<string>);
+
+export interface HttpPushTransportOptions {
+  /**
+   * Vault API base URL (e.g. `https://vault-api.example.com`). The same
+   * `apiUrl` the runner already resolves for VaultClient. Trailing slashes
+   * are stripped. Required — config/env-driven, no hard-coded default.
+   */
+  apiUrl: string;
+  /**
+   * Endpoint path the PushEvent is POSTed to. Defaults to `/sync/push`
+   * (matches the deployed hq-pro endpoint from US-006). Override for testing
+   * or future endpoint moves.
+   */
+  pushPath?: string;
+  /** Cognito JWT — static string OR async getter. See {@link AuthTokenSource}. */
+  authToken: AuthTokenSource;
+  /**
+   * Optional extra headers (e.g. client identification) merged onto every
+   * request. Authorization + Content-Type are always set by the transport.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Per-request timeout in milliseconds. Default 10_000. On timeout the
+   * publish rejects — the daemon treats a rejected publish as a transient
+   * miss (the cadence poll still covers it) and MUST NOT crash.
+   */
+  timeoutMs?: number;
+  /** Injectable fetch (tests). Defaults to the global `fetch`. */
+  fetchImpl?: FetchLike;
+}
+
+/**
+ * Real client `PushTransport` that POSTs encoded PushEvents to the deployed
+ * `/sync/push` endpoint, authenticating with the menubar's existing Cognito
+ * bearer token — the same auth path VaultClient uses (Authorization: Bearer
+ * <accessToken>, token resolved per-request via the supplied getter so it
+ * self-heals across refreshes).
+ *
+ * Failure posture
+ * ───────────────
+ * `publish()` rejects on a network error, a non-2xx response, or a timeout.
+ * The DAEMON is responsible for not letting that rejection crash it — the
+ * watcher's emit path catches publish errors and logs them; the periodic
+ * cadence poll remains the safety net that eventually ships the change. This
+ * transport never swallows errors itself, so callers retain full visibility.
+ *
+ * `connected` flips true on `start()` and false on `dispose()`. It is purely
+ * advisory (HTTP is connectionless); the health endpoint may read it but it
+ * carries no delivery guarantee.
+ */
+export class HttpPushTransport implements PushTransport {
+  private readonly apiUrl: string;
+  private readonly pushPath: string;
+  private readonly getAuthToken: () => Promise<string>;
+  private readonly extraHeaders: Record<string, string>;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: FetchLike;
+  private _connected = false;
+
+  constructor(opts: HttpPushTransportOptions) {
+    if (!opts.apiUrl || opts.apiUrl.trim() === "") {
+      throw new Error("HttpPushTransport: apiUrl is required");
+    }
+    this.apiUrl = opts.apiUrl.replace(/\/+$/, "");
+    const path = opts.pushPath ?? "/sync/push";
+    this.pushPath = path.startsWith("/") ? path : `/${path}`;
+    const tok = opts.authToken;
+    // Normalize string|getter into a single async getter (mirrors VaultClient).
+    this.getAuthToken =
+      typeof tok === "function" ? async () => tok() : async () => tok;
+    this.extraHeaders = opts.headers ?? {};
+    this.timeoutMs = opts.timeoutMs ?? 10_000;
+    // Bind so a destructured global fetch keeps its receiver.
+    this.fetchImpl =
+      opts.fetchImpl ??
+      ((input, init) => (globalThis.fetch as unknown as FetchLike)(input, init));
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  async start(): Promise<void> {
+    this._connected = true;
+  }
+
+  async publish(event: PushEvent): Promise<void> {
+    // Validate-on-encode (US-007 contract) — a malformed event throws a typed
+    // PushEventDecodeError BEFORE we hit the network.
+    const body = encodePushEvent(event);
+    const token = await this.getAuthToken();
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(`${this.apiUrl}${this.pushPath}`, {
+        method: "POST",
+        headers: {
+          ...this.extraHeaders,
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body,
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(
+          `HttpPushTransport: POST ${this.pushPath} failed (${res.status})${
+            text ? `: ${text}` : ""
+          }`,
+        );
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async dispose(): Promise<void> {
+    this._connected = false;
+  }
+}

package/src/watcher.test.ts

@@ -0,0 +1,388 @@
+import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  FakeClock,
+  WatchPushDriver,
+  TreeWatcher,
+  createWatchPathFilter,
+} from "./watcher.js";
+
+/**
+ * US-001 — Phase 1 test harness: watch-triggered push seam + latency assertion.
+ *
+ * These tests drive the debounce/coalesce core ({@link WatchPushDriver}) with an
+ * injected {@link FakeClock} and an injected spy push fn — no real chokidar
+ * watcher, no real S3, no real 10-minute sleep. US-002/US-003 build the real
+ * watcher + targeted-push fn on top of this same seam, so the tests here also
+ * serve as regression guards for the contract those stories depend on.
+ */
+
+const DEBOUNCE = 2000;
+
+/**
+ * Build a driver wired to a FakeClock and a spy push fn. Returns everything a
+ * test needs to drive and assert against the seam. This helper is the reusable
+ * "test harness" the story asks for.
+ */
+function makeHarness(opts?: { debounceMs?: number }) {
+  const clock = new FakeClock();
+  const push = vi.fn(() => {});
+  const driver = new WatchPushDriver({
+    debounceMs: opts?.debounceMs ?? DEBOUNCE,
+    clock,
+    push,
+  });
+  return {
+    clock,
+    push,
+    driver,
+    /** Emit a synthetic file-change event into the driver. */
+    emitChange: () => driver.notifyChange(),
+    /** Advance virtual time. */
+    advance: (ms: number) => clock.advance(ms),
+  };
+}
+
+describe("FakeClock", () => {
+  it("fires a timer exactly when its deadline is reached", () => {
+    const clock = new FakeClock();
+    const fn = vi.fn();
+    clock.setTimeout(fn, 100);
+    clock.advance(99);
+    expect(fn).not.toHaveBeenCalled();
+    clock.advance(1);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire a cleared timer", () => {
+    const clock = new FakeClock();
+    const fn = vi.fn();
+    const handle = clock.setTimeout(fn, 100);
+    clock.clearTimeout(handle);
+    clock.advance(1000);
+    expect(fn).not.toHaveBeenCalled();
+    expect(clock.pendingTimerCount()).toBe(0);
+  });
+
+  it("reports pending timer count for leak checks", () => {
+    const clock = new FakeClock();
+    clock.setTimeout(() => {}, 100);
+    clock.setTimeout(() => {}, 200);
+    expect(clock.pendingTimerCount()).toBe(2);
+    clock.advance(100);
+    expect(clock.pendingTimerCount()).toBe(1);
+  });
+});
+
+describe("US-001: WatchPushDriver — debounced push seam", () => {
+  it("calls the injected push fn exactly once within debounce+grace after a synthetic change", async () => {
+    const h = makeHarness();
+
+    h.emitChange();
+    // Before the window elapses, no push.
+    h.advance(DEBOUNCE - 1);
+    expect(h.push).not.toHaveBeenCalled();
+
+    // Crossing the debounce boundary fires the push exactly once.
+    h.advance(1);
+    await Promise.resolve();
+    expect(h.push).toHaveBeenCalledTimes(1);
+  });
+
+  it("coalesces N rapid changes within the window to exactly 1 push", async () => {
+    const h = makeHarness();
+
+    // 5 synthetic changes spread across less than one debounce window.
+    for (let i = 0; i < 5; i++) {
+      h.emitChange();
+      h.advance(100); // total 500ms << 2000ms debounce
+    }
+    // Window has not fully elapsed since the LAST change yet.
+    expect(h.push).not.toHaveBeenCalled();
+
+    // Let the quiet window after the final change elapse.
+    h.advance(DEBOUNCE);
+    await Promise.resolve();
+    expect(h.push).toHaveBeenCalledTimes(1);
+  });
+
+  it("treats two separate bursts as two pushes", async () => {
+    const h = makeHarness();
+
+    h.emitChange();
+    h.advance(DEBOUNCE);
+    await Promise.resolve();
+    expect(h.push).toHaveBeenCalledTimes(1);
+
+    h.emitChange();
+    h.advance(DEBOUNCE);
+    await Promise.resolve();
+    expect(h.push).toHaveBeenCalledTimes(2);
+  });
+
+  it("never overlaps an in-flight push; a mid-push change re-triggers one follow-up pass", async () => {
+    const clock = new FakeClock();
+    let release!: () => void;
+    const inFlight = new Promise<void>((r) => {
+      release = r;
+    });
+    let calls = 0;
+    const push = vi.fn(() => {
+      calls += 1;
+      // First push hangs until released; later pushes resolve immediately.
+      return calls === 1 ? inFlight : Promise.resolve();
+    });
+    const driver = new WatchPushDriver({ debounceMs: DEBOUNCE, clock, push });
+
+    // First burst -> first push starts and hangs.
+    driver.notifyChange();
+    clock.advance(DEBOUNCE);
+    await Promise.resolve();
+    expect(push).toHaveBeenCalledTimes(1);
+    expect(driver.isPushing()).toBe(true);
+
+    // A change arrives while the first push is in flight: must NOT start a
+    // concurrent push.
+    driver.notifyChange();
+    clock.advance(DEBOUNCE);
+    await Promise.resolve();
+    expect(push).toHaveBeenCalledTimes(1);
+
+    // Release the first push; the collapsed mid-push change re-arms.
+    release();
+    await inFlight;
+    await Promise.resolve();
+    // Re-armed window must elapse before the follow-up push fires.
+    clock.advance(DEBOUNCE);
+    await Promise.resolve();
+    expect(push).toHaveBeenCalledTimes(2);
+
+    driver.dispose();
+  });
+
+  it("respects a custom debounce window", async () => {
+    const h = makeHarness({ debounceMs: 500 });
+    h.emitChange();
+    h.advance(499);
+    expect(h.push).not.toHaveBeenCalled();
+    h.advance(1);
+    await Promise.resolve();
+    expect(h.push).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("US-001: WatchPushDriver — teardown leaves no leaked timers", () => {
+  it("dispose() cancels a pending debounce timer", () => {
+    const h = makeHarness();
+    h.emitChange();
+    expect(h.clock.pendingTimerCount()).toBe(1);
+
+    h.driver.dispose();
+    expect(h.clock.pendingTimerCount()).toBe(0);
+
+    // A push must not fire after dispose, even if time advances.
+    h.advance(DEBOUNCE * 10);
+    expect(h.push).not.toHaveBeenCalled();
+  });
+
+  it("notifyChange() after dispose is a no-op and schedules nothing", () => {
+    const h = makeHarness();
+    h.driver.dispose();
+    h.emitChange();
+    expect(h.clock.pendingTimerCount()).toBe(0);
+    h.advance(DEBOUNCE * 10);
+    expect(h.push).not.toHaveBeenCalled();
+  });
+
+  it("dispose() is idempotent", () => {
+    const h = makeHarness();
+    h.emitChange();
+    h.driver.dispose();
+    h.driver.dispose();
+    expect(h.clock.pendingTimerCount()).toBe(0);
+  });
+
+  it("a fully drained burst leaves zero pending timers", async () => {
+    const h = makeHarness();
+    for (let i = 0; i < 5; i++) h.emitChange();
+    h.advance(DEBOUNCE);
+    await Promise.resolve();
+    expect(h.push).toHaveBeenCalledTimes(1);
+    expect(h.clock.pendingTimerCount()).toBe(0);
+  });
+});
+
+/**
+ * US-002 — file-watcher module (debounced, ignore-aware, exclusion-aware).
+ *
+ * `createWatchPathFilter` is pure (no chokidar) so the exclusion logic is
+ * tested directly against absolute paths. `TreeWatcher` is then exercised via
+ * its `handleEvent` seam + FakeClock so debounce/coalesce/lifecycle assert
+ * deterministically without spinning a real chokidar instance.
+ */
+
+const ROOT = "/tmp/hq-root";
+
+describe("US-002: createWatchPathFilter — ignore-list matching", () => {
+  const filter = createWatchPathFilter(ROOT, false);
+
+  it("emits for an ordinary tracked file", () => {
+    expect(filter(path.join(ROOT, "personal/notes.md"))).toBe(true);
+  });
+
+  it("does NOT emit for a .env file (DEFAULT_IGNORES secret)", () => {
+    expect(filter(path.join(ROOT, ".env"))).toBe(false);
+    expect(filter(path.join(ROOT, "personal/.env.local"))).toBe(false);
+  });
+
+  it("does NOT emit for node_modules / dist build artifacts", () => {
+    expect(filter(path.join(ROOT, "node_modules/foo/index.js"))).toBe(false);
+    expect(filter(path.join(ROOT, "dist/bundle.js"))).toBe(false);
+  });
+
+  it("does NOT emit for the watched root itself or paths outside it", () => {
+    expect(filter(ROOT)).toBe(false);
+    expect(filter("/some/other/place/file.txt")).toBe(false);
+  });
+});
+
+describe("US-002: createWatchPathFilter — personal-vault exclusions", () => {
+  const personal = createWatchPathFilter(ROOT, true);
+  const nonPersonal = createWatchPathFilter(ROOT, false);
+
+  it("does NOT emit for PERSONAL_VAULT_DEFAULT_EXCLUSIONS in personalMode (output/, .beads/)", () => {
+    expect(personal(path.join(ROOT, "personal/output/x.txt"))).toBe(false);
+    expect(personal(path.join(ROOT, "personal/.beads/issues.db"))).toBe(false);
+  });
+
+  it("does NOT emit for PERSONAL_VAULT_EXCLUDED_TOP_LEVEL in personalMode (.git/companies/repos/workspace)", () => {
+    expect(personal(path.join(ROOT, "companies/indigo/board.json"))).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/threads/x.json"))).toBe(false);
+    expect(personal(path.join(ROOT, "repos/private/foo/file.ts"))).toBe(false);
+  });
+
+  it("DOES emit for an included top-level personal path in personalMode", () => {
+    expect(personal(path.join(ROOT, "personal/notes.md"))).toBe(true);
+    expect(personal(path.join(ROOT, "core/policies/x.md"))).toBe(true);
+  });
+
+  it("non-personal mode does NOT apply the excluded-top-level buckets", () => {
+    // companies/ is only excluded by the personal-vault layer; in non-personal
+    // mode the ignore stack alone governs and lets it through.
+    expect(nonPersonal(path.join(ROOT, "companies/indigo/board.json"))).toBe(true);
+  });
+});
+
+describe("US-002: TreeWatcher — debounce coalesce (FakeClock seam)", () => {
+  function makeWatcher(opts?: { debounceMs?: number; personalMode?: boolean }) {
+    const clock = new FakeClock();
+    const changed = vi.fn();
+    const watcher = new TreeWatcher({
+      hqRoot: ROOT,
+      debounceMs: opts?.debounceMs ?? DEBOUNCE,
+      personalMode: opts?.personalMode ?? false,
+      clock,
+    });
+    watcher.onChange(changed);
+    return { clock, changed, watcher };
+  }
+
+  it("coalesces 5 rapid changes within the window into exactly 1 changed signal", () => {
+    const { clock, changed, watcher } = makeWatcher();
+    for (let i = 0; i < 5; i++) {
+      watcher.handleEvent(path.join(ROOT, `personal/file-${i}.md`));
+      clock.advance(20); // 100ms total << 2000ms debounce
+    }
+    expect(changed).not.toHaveBeenCalled();
+    clock.advance(DEBOUNCE);
+    expect(changed).toHaveBeenCalledTimes(1);
+    expect(watcher.pendingTimerCount()).toBe(0);
+  });
+
+  it("fires once after the quiet window for a single change", () => {
+    const { clock, changed, watcher } = makeWatcher();
+    watcher.handleEvent(path.join(ROOT, "personal/a.md"));
+    clock.advance(DEBOUNCE - 1);
+    expect(changed).not.toHaveBeenCalled();
+    clock.advance(1);
+    expect(changed).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT emit for an ignored / excluded path", () => {
+    const { clock, changed, watcher } = makeWatcher({ personalMode: true });
+    watcher.handleEvent(path.join(ROOT, ".env"));
+    watcher.handleEvent(path.join(ROOT, "personal/output/big.bin"));
+    watcher.handleEvent(path.join(ROOT, "companies/indigo/board.json"));
+    clock.advance(DEBOUNCE * 2);
+    expect(changed).not.toHaveBeenCalled();
+    expect(watcher.pendingTimerCount()).toBe(0);
+  });
+
+  it("treats two separate bursts as two changed signals", () => {
+    const { clock, changed, watcher } = makeWatcher();
+    watcher.handleEvent(path.join(ROOT, "personal/a.md"));
+    clock.advance(DEBOUNCE);
+    expect(changed).toHaveBeenCalledTimes(1);
+    watcher.handleEvent(path.join(ROOT, "personal/b.md"));
+    clock.advance(DEBOUNCE);
+    expect(changed).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("US-002: TreeWatcher — lifecycle (real chokidar over a temp dir)", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    // realpathSync resolves macOS's /var -> /private/var symlink so chokidar's
+    // canonicalized event paths stay inside hqRoot (path.relative would
+    // otherwise yield a `..`-prefixed path and the filter would reject them).
+    dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "treewatcher-")));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("start() is idempotent — a second start does not open a second watcher", () => {
+    const w = new TreeWatcher({ hqRoot: dir });
+    w.start();
+    expect(w.isWatching()).toBe(true);
+    w.start(); // no throw, no second instance
+    expect(w.isWatching()).toBe(true);
+    w.stop();
+    expect(w.isWatching()).toBe(false);
+  });
+
+  it("stop() closes the watcher and clears pending timers; dispose() is permanent", () => {
+    const clock = new FakeClock();
+    const w = new TreeWatcher({ hqRoot: dir, clock });
+    w.start();
+    w.handleEvent(path.join(dir, "x.md"));
+    expect(w.pendingTimerCount()).toBe(1);
+    w.stop();
+    expect(w.pendingTimerCount()).toBe(0);
+    expect(w.isWatching()).toBe(false);
+
+    // After dispose, events are inert and start is a no-op.
+    w.dispose();
+    w.handleEvent(path.join(dir, "y.md"));
+    expect(w.pendingTimerCount()).toBe(0);
+    w.start();
+    expect(w.isWatching()).toBe(false);
+  });
+
+  it("emits a debounced changed signal for a real file write", async () => {
+    const w = new TreeWatcher({ hqRoot: dir, debounceMs: 50 });
+    const changed = vi.fn();
+    w.onChange(changed);
+    w.start();
+    // Give chokidar a beat to set up its watch before writing.
+    await new Promise((r) => setTimeout(r, 200));
+    fs.writeFileSync(path.join(dir, "hello.md"), "hi");
+    await new Promise((r) => setTimeout(r, 1500));
+    expect(changed).toHaveBeenCalled();
+    w.dispose();
+  }, 10_000);
+});