@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/src/bin/sync-runner.ts

@@ -88,6 +88,17 @@ import type { ShareOptions, ShareResult } from "../cli/share.js";
 import type { ConflictStrategy } from "../cli/conflict.js";
 import type { UploadAuthor } from "../s3.js";
 import { collectAndSendTelemetry } from "../telemetry.js";
+import {
+  TreeWatcher,
+  WatchPushDriver,
+  systemClock,
+  type Clock,
+} from "../watcher.js";
+import {
+  NoopPushReceiver,
+  type PushReceiver,
+  type SyncEngineFn,
+} from "../sync/push-receiver.js";
 
 /**
  * Sync direction for a run.
@@ -442,6 +453,15 @@ interface ParsedArgs {
   watch: boolean;
   /** Auto-sync (Beta): ms between remote-pull passes. Required when watch=true. */
   pollRemoteMs?: number;
+  /**
+   * Event-driven push (Phase 1). When set (and `--watch` is on), the runner
+   * starts a {@link TreeWatcher} alongside the poll loop and pushes a targeted
+   * company/subtree within the debounce window of a local edit — instead of
+   * waiting up to a full `--poll-remote-ms` cycle. Gated OFF by default; the
+   * menubar passes it only for `@getindigo.ai` identities (see PRD decision).
+   * No-op without `--watch` (the one-shot path has nothing to keep alive).
+   */
+  eventPush: boolean;
   /**
    * Drop the personal target from the fanout. Combined with the
    * `HQ_SYNC_SKIP_PERSONAL` env var by `resolveSkipPersonal()` — either
@@ -460,6 +480,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let watch = false;
   let pollRemoteMs: number | undefined;
   let skipPersonal = false;
+  let eventPush = false;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -519,6 +540,12 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         // resolveSkipPersonal().
         skipPersonal = true;
         break;
+      case "--event-push":
+        // Phase 1 event-driven push enable flag. Requires --watch (validated
+        // below). Gated OFF by default; the menubar only passes it for
+        // @getindigo.ai identities for the first release.
+        eventPush = true;
+        break;
       default:
         return { error: `Unknown argument: ${arg}` };
     }
@@ -533,8 +560,21 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   if (pollRemoteMs !== undefined && !watch) {
     return { error: "--poll-remote-ms requires --watch" };
   }
+  if (eventPush && !watch) {
+    return { error: "--event-push requires --watch" };
+  }
 
-  return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs, skipPersonal };
+  return {
+    companies,
+    company,
+    onConflict,
+    hqRoot,
+    direction,
+    watch,
+    pollRemoteMs,
+    skipPersonal,
+    eventPush,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -1169,29 +1209,386 @@ const isDirectInvocation = (() => {
  * exit 0 today and so will retry — acceptable noise for the beta; deal with
  * it via a richer return shape if it shows up in Sentry.
  */
-export async function runRunnerWithLoop(argv: string[]): Promise<number> {
+/**
+ * Test/event-driven seam (US-001).
+ *
+ * `runRunnerWithLoop` performs an unbounded poll loop in production. To make
+ * the loop deterministically testable (US-003 wires the event-driven watcher
+ * into this same loop), the inter-pass sleep is injectable via `deps.sleep`.
+ * The default uses the host timer and preserves exact production behavior.
+ *
+ * A test (or US-003's wiring) injects a fake sleep that resolves immediately
+ * and/or coordinates with the {@link WatchPushDriver} seam in `../watcher.js`,
+ * so the loop can be exercised without a real 10-minute wait.
+ */
+export interface RunnerLoopDeps {
+  /** Sleep `ms` between passes. Default: host setTimeout. */
+  sleep?: (ms: number) => Promise<void>;
+  /**
+   * Run a single sync pass. Defaults to {@link runRunner}. Injected by tests
+   * (and the event-push wiring) so the poll loop and the watcher-triggered
+   * targeted push share one seam and one in-flight guard. The default ignores
+   * `deps` and forwards just the argv to `runRunner`.
+   */
+  runPass?: (passArgv: string[]) => Promise<number>;
+  /**
+   * Clock seam for the event-push watcher's debounce window. Defaults to
+   * {@link systemClock}; tests inject a `FakeClock` to advance the window
+   * deterministically. Only consulted when `--event-push` is on.
+   */
+  clock?: Clock;
+  /**
+   * Factory for the file watcher used in event-push mode. Defaults to a real
+   * {@link TreeWatcher} over `hqRoot`. Tests inject a stub exposing the same
+   * `onChange`/`start`/`stop`/`dispose` surface so no real chokidar runs.
+   */
+  createWatcher?: (opts: {
+    hqRoot: string;
+    debounceMs: number;
+    clock: Clock;
+  }) => WatcherSurface;
+  /**
+   * Register a one-shot shutdown signal handler. Defaults to listening for
+   * SIGTERM/SIGINT on `process`. Tests inject a controllable trigger to assert
+   * clean teardown without sending real signals. The returned fn detaches the
+   * handler (called during teardown so tests don't leak listeners).
+   */
+  onShutdownSignal?: (handler: () => void) => () => void;
+  /**
+   * Factory for the Phase 2 pull-on-event receiver (US-009). Defaults to a
+   * {@link NoopPushReceiver} — the daemon ships the receiver SEAM wired into
+   * the lifecycle (start after the watcher, dispose before exit) but stays
+   * DORMANT by default: the per-client SQS queue is provisioned server-side
+   * (an unbuilt follow-up) and the receiver is feature-flag gated. A future
+   * menubar/CLI release injects an {@link SqsPushReceiver} here once a queue
+   * URL is available. Only consulted when `--event-push` is on.
+   *
+   * The factory is handed a {@link SyncEngineFn} that bridges a received
+   * PushEvent to a TARGETED pull pass (`--company <slug> --direction pull`,
+   * or a personal `--companies --direction pull`) routed by the event's
+   * `relativePath`, funneled through the same in-flight guard as the poll
+   * loop and the watcher push so a pull-on-event never overlaps an in-flight
+   * pass.
+   */
+  createReceiver?: (opts: {
+    syncFn: SyncEngineFn;
+    hqRoot: string;
+  }) => PushReceiver;
+}
+
+/**
+ * The minimal watcher surface the loop drives. {@link TreeWatcher} satisfies
+ * it; tests inject a lighter stub. Kept narrow so the loop never reaches past
+ * the lifecycle + change-subscription contract.
+ *
+ * `onChange`'s listener receives an OPTIONAL changed relative path. The real
+ * {@link TreeWatcher} emits a bare debounced signal (no path) — in that case
+ * the loop routes the targeted push to the personal vault. A path-aware
+ * watcher (or a test stub) can pass the changed `companies/<slug>/...`
+ * relative path so the loop targets just that company.
+ */
+export interface WatcherSurface {
+  onChange(listener: (changedRelPath?: string) => void): () => void;
+  start(): void;
+  stop(): void;
+  dispose(): void;
+}
+
+/**
+ * Route a changed relative path to the push target that owns it.
+ *
+ * - `companies/<slug>/...` → a single-company push for `<slug>` (the targeted
+ *   pass per PRD decision — push only the changed company, not a full
+ *   `--companies` fanout).
+ * - anything else under hqRoot → the personal target (a `--companies` push
+ *   restricted to personal via the personal-vault scope; modeled here as the
+ *   "personal" route the caller maps to the right argv).
+ *
+ * Returns `null` for paths the routing cannot attribute (defensive — the
+ * watcher's filter already drops excluded top-levels, so this is belt-and-
+ * suspenders for synthetic events).
+ */
+export function routeChangeToTarget(
+  relPath: string,
+): { kind: "company"; slug: string } | { kind: "personal" } | null {
+  const norm = relPath.split(path.sep).join("/").replace(/^\.\//, "");
+  if (norm === "" || norm.startsWith("..")) return null;
+  const segments = norm.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) return null;
+  if (segments[0] === "companies") {
+    // companies/<slug>/... — need at least the slug segment to target.
+    if (segments.length < 2 || segments[1].length === 0) return null;
+    return { kind: "company", slug: segments[1] };
+  }
+  return { kind: "personal" };
+}
+
+/**
+ * Build the argv for a targeted push pass from a routed change. The push runs
+ * `--direction push` for just the routed target so a local edit propagates in
+ * seconds without a full fanout. Company routes use `--company <slug>`;
+ * personal routes use `--companies --direction push` (the personal-vault scope
+ * is resolved inside runRunner's fanout; skipUnchanged no-ops the company
+ * subtrees that didn't change). Inherits `--hq-root` / `--on-conflict` from
+ * the base argv. Pure helper, exported for unit testing the routing→argv map.
+ */
+export function buildTargetedPushArgv(
+  route: { kind: "company"; slug: string } | { kind: "personal" },
+  baseArgv: string[],
+): string[] {
+  const carried = carriedFlags(baseArgv);
+  if (route.kind === "company") {
+    return ["--company", route.slug, "--direction", "push", ...carried];
+  }
+  return ["--companies", "--direction", "push", ...carried];
+}
+
+/**
+ * Build the argv for a targeted PULL pass from a routed change (US-009 — the
+ * receiver's pull-on-event path). Mirrors {@link buildTargetedPushArgv} but
+ * with `--direction pull`: a peer device pushed a change, so this device pulls
+ * just the affected company/subtree instead of waiting for the next
+ * `--poll-remote-ms` cycle. Company routes use `--company <slug>`; personal
+ * routes use `--companies` (the personal-vault scope is resolved inside
+ * runRunner's fanout; skipUnchanged no-ops the subtrees that didn't change).
+ * Inherits `--hq-root` / `--on-conflict` from the base argv. Pure helper,
+ * exported for unit testing the event→argv map.
+ */
+export function buildTargetedPullArgv(
+  route: { kind: "company"; slug: string } | { kind: "personal" },
+  baseArgv: string[],
+): string[] {
+  const carried = carriedFlags(baseArgv);
+  if (route.kind === "company") {
+    return ["--company", route.slug, "--direction", "pull", ...carried];
+  }
+  return ["--companies", "--direction", "pull", ...carried];
+}
+
+export async function runRunnerWithLoop(
+  argv: string[],
+  deps: RunnerLoopDeps = {},
+): Promise<number> {
   if (!argv.includes("--watch")) {
     return runRunner(argv);
   }
+  const sleep =
+    deps.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const runPass = deps.runPass ?? ((passArgv: string[]) => runRunner(passArgv));
   const pollIdx = argv.indexOf("--poll-remote-ms");
   const pollMs =
     pollIdx >= 0 && argv[pollIdx + 1] ? Number(argv[pollIdx + 1]) : 600_000;
+  const eventPush = argv.includes("--event-push");
+  // In `--companies` mode the sync scope is companies/*/{knowledge,projects,…}
+  // (per .hqinclude), so the watcher must NOT apply the personal-vault
+  // top-level exclusions (PERSONAL_VAULT_EXCLUDED_TOP_LEVEL drops `companies/`
+  // and `workspace/`) — doing so would exclude exactly the paths being synced,
+  // and no local edit would ever trigger an instant push. The shared ignore
+  // stack (createIgnoreFilter / .hqignore / .hqinclude) already scopes the
+  // watch filter correctly in companies mode. personalMode is only for a
+  // personal-vault-as-root run, where companies/ et al. genuinely aren't synced.
+  const companiesMode = argv.includes("--companies");
+  const hqIdx = argv.indexOf("--hq-root");
+  const hqRoot =
+    hqIdx >= 0 && argv[hqIdx + 1] ? argv[hqIdx + 1] : DEFAULT_HQ_ROOT;
 
-  // Strip --watch / --poll-remote-ms before delegating: the parser inside
-  // runRunner accepts them, but we don't want runRunner to think it's
-  // re-entering watch mode each iteration.
+  // Strip the loop-only flags before delegating: the parser inside runRunner
+  // accepts --watch/--poll-remote-ms/--event-push, but we don't want a per-
+  // iteration pass to think it's re-entering watch mode.
   const passArgv = argv.filter((a, i) => {
     if (a === "--watch") return false;
     if (a === "--poll-remote-ms") return false;
+    if (a === "--event-push") return false;
     if (i > 0 && argv[i - 1] === "--poll-remote-ms") return false;
     return true;
   });
 
-  while (true) {
-    const code = await runRunner(passArgv);
-    if (code !== 0) return code;
-    await new Promise<void>((resolve) => setTimeout(resolve, pollMs));
+  // ---- shared in-flight guard ------------------------------------------
+  // The poll loop AND watcher-triggered targeted pushes funnel through this
+  // mutex so a watcher push never overlaps an in-flight pass (PRD AC). A
+  // trigger that arrives while a pass runs is collapsed by WatchPushDriver's
+  // own pending-while-pushing logic, then re-armed after the pass settles.
+  let inFlight = false;
+  let stopped = false;
+  const runGuarded = async (
+    pass: () => Promise<number>,
+  ): Promise<number | "skipped"> => {
+    if (inFlight) return "skipped";
+    inFlight = true;
+    try {
+      return await pass();
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  // ---- event-push wiring (Phase 1) -------------------------------------
+  let watcher: WatcherSurface | null = null;
+  let driver: WatchPushDriver | null = null;
+  let detachSignal: (() => void) | null = null;
+  let lastChangedRel: string | null = null;
+  // ---- pull-on-event receiver (Phase 2, US-009) ------------------------
+  // Started after the watcher, disposed before the watcher (mirror of the
+  // PushTransport ordering). Dormant by default: the default factory returns
+  // a NoopPushReceiver, and even a real receiver stays dormant unless the
+  // per-tenant feature flag is on AND a queue URL is provisioned server-side.
+  let receiver: PushReceiver | null = null;
+
+  if (eventPush) {
+    const clock = deps.clock ?? systemClock;
+    const debounceMs = 2000;
+    const createWatcher =
+      deps.createWatcher ??
+      ((opts) =>
+        new TreeWatcher({
+          hqRoot: opts.hqRoot,
+          debounceMs: opts.debounceMs,
+          clock: opts.clock,
+          // false in --companies mode so the watch filter matches the sync
+          // scope (companies/* are included via .hqinclude); true only for a
+          // personal-vault-as-root run.
+          personalMode: !companiesMode,
+        }));
+    watcher = createWatcher({ hqRoot, debounceMs, clock });
+
+    // The driver runs the targeted push when a debounced burst settles. Its
+    // concurrency guard collapses a trigger that lands mid-pass; we ALSO gate
+    // through `runGuarded` so a poll pass in flight is never overlapped.
+    driver = new WatchPushDriver({
+      debounceMs: 0, // TreeWatcher already debounces; the driver just guards.
+      clock,
+      push: async () => {
+        if (stopped) return;
+        const rel = lastChangedRel;
+        const route = rel
+          ? routeChangeToTarget(rel)
+          : { kind: "personal" as const };
+        if (!route) return;
+        const targetedArgv = buildTargetedPushArgv(route, passArgv);
+        await runGuarded(() => runPass(targetedArgv));
+      },
+    });
+
+    // A debounced TreeWatcher 'changed' signal feeds the driver, which fires
+    // the targeted push after its own (zero) window — i.e. immediately, but
+    // still serialized behind any in-flight pass. A path-aware watcher passes
+    // the changed relative path so the push targets just its owning company;
+    // the bare-signal TreeWatcher leaves it null → personal-vault route.
+    watcher.onChange((changedRelPath) => {
+      if (stopped) return;
+      lastChangedRel = changedRelPath ?? null;
+      driver?.notifyChange();
+    });
+    watcher.start();
+
+    // Pull-on-event receiver (US-009). The injected SyncEngineFn bridges a
+    // received PushEvent → a TARGETED pull pass routed by relativePath, funneled
+    // through the SAME `runGuarded` mutex as the poll loop + watcher push so a
+    // pull-on-event never overlaps an in-flight pass. Started AFTER the watcher
+    // so a live event can't race a half-built daemon. Default factory = noop
+    // (dormant); a real SqsPushReceiver is injected by a later release once the
+    // server-side per-client SQS queue is provisioned.
+    const receiverSyncFn: SyncEngineFn = async (ctx) => {
+      if (stopped) return;
+      const route = routeChangeToTarget(ctx.event.relativePath);
+      if (!route) return;
+      const targetedArgv = buildTargetedPullArgv(route, passArgv);
+      await runGuarded(() => runPass(targetedArgv));
+    };
+    const createReceiver =
+      deps.createReceiver ?? (() => new NoopPushReceiver());
+    receiver = createReceiver({ syncFn: receiverSyncFn, hqRoot });
+    // Fire-and-forget start: a receiver's start() kicks off its own poll loop
+    // (SqsPushReceiver) or trivially flips connected (noop) — it must NOT block
+    // the runner's poll loop from entering. Errors are swallowed; the cadence
+    // poll is the safety net regardless of receiver health. (The await-free
+    // start also keeps the poll loop's microtask timing identical to the
+    // pre-US-009 wiring.)
+    void Promise.resolve(receiver.start()).catch(() => undefined);
+  }
+
+  // ---- clean shutdown --------------------------------------------------
+  // SIGTERM (menubar stop_daemon) / SIGINT must tear down BOTH the watcher and
+  // the poll loop with no leaked timers or fds. We flip `stopped`, dispose the
+  // watcher + driver, and let the poll loop observe `stopped` on its next tick.
+  let resolveStopped: (() => void) | null = null;
+  const stoppedSignal = new Promise<void>((resolve) => {
+    resolveStopped = resolve;
+  });
+  const shutdown = (): void => {
+    if (stopped) return;
+    stopped = true;
+    // Dispose the receiver FIRST (mirror of the PushTransport ordering:
+    // inbound subscription torn down before the watcher) so no new
+    // pull-on-event fires mid-teardown. dispose() is async (it drains the
+    // in-flight pull up to its own deadline); fire-and-forget here — the
+    // receiver's internal drain + the runGuarded mutex bound the work, and
+    // SIGTERM teardown must not block. Errors are swallowed.
+    try {
+      void receiver?.dispose();
+    } catch {
+      /* ignore */
+    }
+    try {
+      driver?.dispose();
+    } catch {
+      /* ignore */
+    }
+    try {
+      watcher?.dispose();
+    } catch {
+      /* ignore */
+    }
+    resolveStopped?.();
+  };
+  const onShutdownSignal =
+    deps.onShutdownSignal ??
+    ((handler: () => void) => {
+      const wrapped = () => handler();
+      process.on("SIGTERM", wrapped);
+      process.on("SIGINT", wrapped);
+      return () => {
+        process.off("SIGTERM", wrapped);
+        process.off("SIGINT", wrapped);
+      };
+    });
+  detachSignal = onShutdownSignal(shutdown);
+
+  try {
+    while (!stopped) {
+      const result = await runGuarded(() => runPass(passArgv));
+      // A poll pass that was skipped because a watcher push held the guard is
+      // benign — the next iteration retries after the poll interval.
+      if (typeof result === "number" && result !== 0) {
+        return result;
+      }
+      // Sleep the poll interval, but wake early on shutdown so SIGTERM stops
+      // the loop promptly instead of waiting out a 10-minute cycle.
+      await Promise.race([sleep(pollMs), stoppedSignal]);
+    }
+    return 0;
+  } finally {
+    shutdown();
+    detachSignal?.();
+  }
+}
+
+/**
+ * Extract the `--hq-root` / `--on-conflict` pair-flags from a base argv so a
+ * re-targeted push pass inherits the same root and conflict policy. Pure
+ * helper used by the event-push targeted-push composer.
+ */
+function carriedFlags(baseArgv: string[]): string[] {
+  const carried: string[] = [];
+  for (let i = 0; i < baseArgv.length; i++) {
+    const a = baseArgv[i];
+    if (a === "--hq-root" || a === "--on-conflict") {
+      carried.push(a);
+      if (baseArgv[i + 1] !== undefined) carried.push(baseArgv[++i]);
+    }
   }
+  return carried;
 }
 
 if (isDirectInvocation) {

package/src/index.ts

@@ -281,3 +281,41 @@ export {
   _setSignalsS3Factory,
   _resetSignalsS3Factory,
 } from "./signals/internals.js";
+
+// Event-driven sync — PushEvent wire contract + PushTransport shipping seam
+// (ported from hq-pro PR #112 per project event-driven-sync-menubar US-007).
+export {
+  CONTENT_HASH_PATTERN,
+  ISO8601_DATETIME_PATTERN,
+  PushEventSchema,
+  PushEventDecodeError,
+  encodePushEvent,
+  decodePushEvent,
+  NoopPushTransport,
+  HttpPushTransport,
+  FEATURE_FLAG_TENANTS_ENV_VAR,
+  FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR,
+  EnvTenantListFlagProvider,
+  StaticFlagProvider,
+  defaultFlagProvider,
+} from "./sync/index.js";
+export type {
+  PushEvent,
+  PushEventDecodeIssue,
+  PushTransport,
+  HttpPushTransportOptions,
+  AuthTokenSource,
+  FetchLike,
+  EventDrivenPushFlagProvider,
+  FlagProviderWarnFn,
+  EnvTenantListFlagProviderOptions,
+} from "./sync/index.js";
+
+// US-008 — watcher PushEvent emitter (bridges TreeWatcher → PushTransport,
+// flag-gated, failure-safe).
+export { PushEventEmitter } from "./watcher.js";
+export type {
+  PushEventEmitterOptions,
+  TreeChangeBatch,
+  TreeChangeListener,
+} from "./watcher.js";