@indigoai-us/hq-cloud 5.26.0 → 5.28.0

package/dist/sync/push-transport.d.ts

@@ -30,7 +30,7 @@
  * 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 type { PushEvent } from "./push-event.js";
+import { type PushEvent } from "./push-event.js";
 export interface PushTransport {
     /** Open sockets, refresh tokens. Awaited before the watcher starts. */
     start(): Promise<void>;
@@ -64,4 +64,87 @@ export declare class NoopPushTransport implements PushTransport {
     publish(_event: PushEvent): Promise<void>;
     dispose(): Promise<void>;
 }
+/**
+ * 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 declare class HttpPushTransport implements PushTransport {
+    private readonly apiUrl;
+    private readonly pushPath;
+    private readonly getAuthToken;
+    private readonly extraHeaders;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private _connected;
+    constructor(opts: HttpPushTransportOptions);
+    get connected(): boolean;
+    start(): Promise<void>;
+    publish(event: PushEvent): Promise<void>;
+    dispose(): Promise<void>;
+}
 //# sourceMappingURL=push-transport.d.ts.map

package/dist/sync/push-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"push-transport.d.ts","sourceRoot":"","sources":["../../src/sync/push-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,2EAA2E;IAC3E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAK;IAEnB,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,oEAAoE;IACpE,IAAI,cAAc,IAAI,MAAM,CAE3B;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}
+{"version":3,"file":"push-transport.d.ts","sourceRoot":"","sources":["../../src/sync/push-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,2EAA2E;IAC3E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAK;IAEnB,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,oEAAoE;IACpE,IAAI,cAAc,IAAI,MAAM,CAE3B;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAID;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,EAAE,eAAe,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwB;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,UAAU,CAAS;gBAEf,IAAI,EAAE,wBAAwB;IAmB1C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/sync/push-transport.js

@@ -30,6 +30,7 @@
  * 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 } from "./push-event.js";
 /**
  * Default `PushTransport` used until a real implementation lands.
  *
@@ -63,4 +64,87 @@ export class NoopPushTransport {
         this._connected = false;
     }
 }
+/**
+ * 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 {
+    apiUrl;
+    pushPath;
+    getAuthToken;
+    extraHeaders;
+    timeoutMs;
+    fetchImpl;
+    _connected = false;
+    constructor(opts) {
+        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(input, init));
+    }
+    get connected() {
+        return this._connected;
+    }
+    async start() {
+        this._connected = true;
+    }
+    async publish(event) {
+        // 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() {
+        this._connected = false;
+    }
+}
 //# sourceMappingURL=push-transport.js.map

package/dist/sync/push-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"push-transport.js","sourceRoot":"","sources":["../../src/sync/push-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAeH;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,iBAAiB;IACpB,UAAU,GAAG,KAAK,CAAC;IACnB,MAAM,GAAG,CAAC,CAAC;IAEnB,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,oEAAoE;IACpE,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAiB;QAC7B,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;CACF"}
+{"version":3,"file":"push-transport.js","sourceRoot":"","sources":["../../src/sync/push-transport.ts"],"names":[],"mappings":"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"}

package/dist/watcher.d.ts

@@ -8,6 +8,8 @@
  */
 import type { EntityContext } from "./types.js";
 import type { UploadAuthor } from "./s3.js";
+import type { PushTransport } from "./sync/push-transport.js";
+import type { EventDrivenPushFlagProvider } from "./sync/feature-flags.js";
 /**
  * Injectable clock seam (US-001).
  *
@@ -145,42 +147,156 @@ export interface TreeWatcherOptions {
  * closes the chokidar watcher (releasing fds) and cancels any pending debounce
  * timer. dispose() is stop() + permanent shutdown.
  */
+/**
+ * One settled change-burst, handed to {@link TreeWatcher} listeners. Carries
+ * the set of relative paths that changed during the quiet window so a listener
+ * (e.g. {@link PushEventEmitter}) can build one PushEvent per path. `paths` is
+ * absolute-path → relative-path; both are needed (relative for the wire shape,
+ * absolute for hashing/statting the file on disk).
+ */
+export interface TreeChangeBatch {
+    /** Map of absolutePath → relativePath for every path in the settled burst. */
+    paths: Map<string, string>;
+}
+/**
+ * Listener invoked once per settled debounce window.
+ *
+ * Backwards compatible with the US-003 `WatcherSurface` contract: the first
+ * argument is the OPTIONAL changed relative path the loop routes its targeted
+ * push to (the first path of the burst; undefined when the window settled with
+ * no captured path). US-008's {@link PushEventEmitter} consumes the SECOND
+ * argument — the full {@link TreeChangeBatch} of every path in the burst — to
+ * build one PushEvent per path. Listeners are free to ignore either argument.
+ */
+export type TreeChangeListener = (changedRelPath?: string, batch?: TreeChangeBatch) => void;
 export declare class TreeWatcher {
     private readonly hqRoot;
     private readonly debounceMs;
     private readonly clock;
     private readonly shouldEmit;
-    private watcher;
+    private backend;
     private timer;
     private listeners;
+    /** Paths accumulated for the current (in-flight) debounce window. */
+    private pending;
     private disposed;
     constructor(opts: TreeWatcherOptions);
-    /** Register a debounced-`changed` listener. Returns an unsubscribe fn. */
-    onChange(listener: () => void): () => void;
+    /**
+     * Register a debounced-`changed` listener. Returns an unsubscribe fn.
+     *
+     * Listeners receive a {@link TreeChangeBatch} of the paths that changed in
+     * the settled window. Existing US-003 callers that only need the "something
+     * changed" signal can ignore the argument — the contract is backwards
+     * compatible (a zero-arg callback still type-checks).
+     */
+    onChange(listener: TreeChangeListener): () => void;
     /**
      * Begin watching. Idempotent — a second call while already running is a
-     * no-op (no second chokidar instance, no leaked fds).
+     * no-op (no second watch backend, no leaked handles).
+     *
+     * Uses a SINGLE recursive `fs.watch` on macOS/Windows (1 OS handle for the
+     * whole tree) and falls back to chokidar on Linux. See {@link startTreeWatch}
+     * for why per-path watching is avoided (kqueue fd exhaustion → EMFILE).
      */
     start(): void;
     /**
-     * Test/seam entry point: feed a raw filesystem path as if chokidar reported
-     * it. Applies the emit filter then arms the debounce. Real chokidar events
-     * route through here too.
+     * Test/seam entry point: feed a raw filesystem path as if the backend
+     * reported it. Applies the emit filter then arms the debounce. Real watch
+     * events route through here too — and for the recursive backend this is the
+     * ONLY place filtering happens, so out-of-scope paths are dropped here.
      */
     handleEvent(absolutePath: string): void;
     private arm;
     private emit;
-    /** True while the chokidar watcher is active. */
+    /** True while the watch backend is active. */
     isWatching(): boolean;
     /** Number of pending debounce timers — a leak check for tests. */
     pendingTimerCount(): number;
     /**
-     * Stop watching: close the chokidar watcher (releasing fds) and cancel any
-     * pending debounce timer. Idempotent. The instance can be restarted with
-     * {@link start} unless {@link dispose} was called.
+     * Stop watching: close the watch backend (releasing its OS handle) and
+     * cancel any pending debounce timer. Idempotent. The instance can be
+     * restarted with {@link start} unless {@link dispose} was called.
      */
     stop(): void;
     /** Permanent shutdown: stop() + drop listeners; further events are no-ops. */
     dispose(): void;
 }
+export interface PushEventEmitterOptions {
+    /** Tenant identifier stamped onto every PushEvent + checked against the flag. */
+    originTenantId: string;
+    /** Device identifier stamped onto every PushEvent. */
+    originDeviceId: string;
+    /** Transport that ships each PushEvent (US-007 NoopPushTransport / HttpPushTransport). */
+    transport: PushTransport;
+    /**
+     * Feature-flag seam. When `isEnabled(originTenantId)` is false the emitter is
+     * dormant: {@link attach} subscribes nothing and {@link emitForBatch} is a
+     * no-op. Defaults are NOT supplied here — the caller injects an
+     * EventDrivenPushFlagProvider so dormancy is explicit.
+     */
+    flagProvider: EventDrivenPushFlagProvider;
+    /**
+     * Returns the next monotonic sequence number for this device. Default: an
+     * internal counter starting at 0. Inject to persist across daemon restarts.
+     */
+    getSequenceNumber?: () => number;
+    /** Clock for eventTimestamp. Default `() => new Date()`. */
+    now?: () => Date;
+    /**
+     * Where publish failures + hash/stat errors go. Default `console.error`.
+     * Receives the offending PushEvent (when known) so callers can correlate.
+     */
+    onError?: (err: Error, ctx: {
+        relativePath?: string;
+    }) => void;
+    /**
+     * Optional structured logger for the US-011 3-log diagnostic chain. When
+     * supplied, the emitter logs `event=watcher.emit` (the 1st correlated link)
+     * carrying the PushEvent's `sequenceNumber` — the same join key stamped by
+     * the server `push.receive` log and the client `fanout.receive` log. Default:
+     * no log (the daemon stays quiet unless wired with a logger).
+     */
+    logger?: EmitterLogger;
+}
+/**
+ * Minimal structured logger surface for {@link PushEventEmitter}. A pino
+ * `Logger` (from `./sync/logger.ts`) satisfies this; tests inject a fake.
+ */
+export interface EmitterLogger {
+    info(obj: Record<string, unknown>, msg?: string): void;
+}
+/**
+ * Bridges {@link TreeWatcher} change batches to a {@link PushTransport} as
+ * typed PushEvents. Construct once per daemon, then {@link attach} to a
+ * running TreeWatcher (returns an unsubscribe fn). Flag-gated + failure-safe.
+ */
+export declare class PushEventEmitter {
+    private readonly originTenantId;
+    private readonly originDeviceId;
+    private readonly transport;
+    private readonly flagProvider;
+    private readonly now;
+    private readonly onError;
+    private readonly logger;
+    private internalSeq;
+    private readonly nextSeq;
+    constructor(opts: PushEventEmitterOptions);
+    /** True iff event-driven push is enabled for this emitter's tenant. */
+    get enabled(): boolean;
+    /**
+     * Subscribe to a TreeWatcher's change batches. Dormant (no subscription)
+     * when the flag is OFF for this tenant. Returns an unsubscribe fn (a no-op
+     * when dormant).
+     */
+    attach(watcher: TreeWatcher): () => void;
+    /**
+     * Build + ship one PushEvent per changed path in the batch. No-op when the
+     * flag is OFF. Each path is independent: a hash/stat failure or a transport
+     * publish rejection for one path is caught + surfaced via `onError` and does
+     * NOT abort the others or propagate (the daemon must not crash; the cadence
+     * poll covers any miss).
+     */
+    emitForBatch(batch: TreeChangeBatch): Promise<void>;
+    private emitOne;
+}
 //# sourceMappingURL=watcher.d.ts.map

package/dist/watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"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"}