@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/src/sync/feature-flags.test.ts

@@ -0,0 +1,392 @@
+/**
+ * US-008 — client push transport unit tests.
+ *
+ * The PRD names this file as the home for US-008's coverage; it spans the
+ * four required assertions across the three US-008 modules:
+ *
+ *   1. flag gating          — feature-flags.ts (env list, legacy global,
+ *                              static provider, malformed-entry tolerance)
+ *   2. POST                 — push-transport.ts HttpPushTransport posts an
+ *                              encoded PushEvent to `<apiUrl>/sync/push` with
+ *                              a Bearer token (mocked fetch — no real server)
+ *   3. emit                 — watcher.ts PushEventEmitter builds a valid
+ *                              PushEvent (sha256 hash, monotonic seq, tenant)
+ *                              per debounced change and hands it to the
+ *                              transport; dormant when the flag is OFF
+ *   4. transport failure    — a publish rejection (or hash error) is caught,
+ *                              surfaced via onError, and never crashes / never
+ *                              propagates (cadence poll is the safety net)
+ *
+ * The live `/sync/push` endpoint is NOT deployed yet — every POST is asserted
+ * against a mocked fetch / mocked transport.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  EnvTenantListFlagProvider,
+  FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR,
+  FEATURE_FLAG_TENANTS_ENV_VAR,
+  StaticFlagProvider,
+  defaultFlagProvider,
+} from "./feature-flags.js";
+import {
+  HttpPushTransport,
+  NoopPushTransport,
+  type FetchLike,
+  type PushTransport,
+} from "./push-transport.js";
+import { decodePushEvent, type PushEvent } from "./push-event.js";
+import { PushEventEmitter } from "../watcher.js";
+import type { TreeChangeBatch } from "../watcher.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function fakePushEvent(overrides: Partial<PushEvent> = {}): PushEvent {
+  return {
+    relativePath: "personal/notes/a.md",
+    contentHash: `sha256:${"a".repeat(64)}`,
+    mtime: "2026-05-21T12:00:00.000Z",
+    originDeviceId: "device-1",
+    originTenantId: "indigo",
+    sequenceNumber: 0,
+    eventTimestamp: "2026-05-21T12:00:01.000Z",
+    ...overrides,
+  };
+}
+
+/** A fetch double that records calls and returns a configurable response. */
+function makeFetch(
+  res: { ok: boolean; status: number; body?: string } = {
+    ok: true,
+    status: 200,
+  },
+): { fetch: FetchLike; calls: Array<{ url: string; init: unknown }> } {
+  const calls: Array<{ url: string; init: unknown }> = [];
+  const fetch: FetchLike = async (url, init) => {
+    calls.push({ url, init });
+    return {
+      ok: res.ok,
+      status: res.status,
+      text: async () => res.body ?? "",
+    };
+  };
+  return { fetch, calls };
+}
+
+// ─── 1. Flag gating (feature-flags.ts) ────────────────────────────────────────
+
+describe("EventDrivenPush feature flags — gating", () => {
+  it("StaticFlagProvider enables only listed tenants", () => {
+    const p = new StaticFlagProvider(["indigo"]);
+    expect(p.isEnabled("indigo")).toBe(true);
+    expect(p.isEnabled("acme")).toBe(false);
+  });
+
+  it("env tenant list: empty/unset → all tenants OFF (default)", () => {
+    expect(new EnvTenantListFlagProvider({ env: {} }).isEnabled("indigo")).toBe(
+      false,
+    );
+    expect(
+      new EnvTenantListFlagProvider({
+        env: { [FEATURE_FLAG_TENANTS_ENV_VAR]: "" },
+      }).isEnabled("indigo"),
+    ).toBe(false);
+  });
+
+  it("env tenant list enables exact, case-sensitive matches only", () => {
+    const p = new EnvTenantListFlagProvider({
+      env: { [FEATURE_FLAG_TENANTS_ENV_VAR]: " indigo , acme " },
+    });
+    expect(p.isEnabled("indigo")).toBe(true);
+    expect(p.isEnabled("acme")).toBe(true);
+    expect(p.isEnabled("Indigo")).toBe(false);
+    expect(p.isEnabled("other")).toBe(false);
+    expect(p.enabledTenants).toEqual(new Set(["indigo", "acme"]));
+  });
+
+  it("legacy global=true overrides → every tenant enabled", () => {
+    const p = new EnvTenantListFlagProvider({
+      env: { [FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR]: "true" },
+    });
+    expect(p.isEnabled("anything")).toBe(true);
+    expect(p.globalOverride).toBe(true);
+  });
+
+  it("trailing/empty commas dropped silently; internal-whitespace warn-and-skipped (no throw)", () => {
+    const warn = vi.fn();
+    const p = new EnvTenantListFlagProvider({
+      env: { [FEATURE_FLAG_TENANTS_ENV_VAR]: ",,indigo,,bad tenant," },
+      warn,
+    });
+    expect(p.isEnabled("indigo")).toBe(true);
+    expect(p.isEnabled("bad tenant")).toBe(false);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][1]).toMatchObject({ rawEntry: "bad tenant" });
+  });
+
+  it("defaultFlagProvider reads from the supplied env snapshot", () => {
+    const p = defaultFlagProvider({
+      [FEATURE_FLAG_TENANTS_ENV_VAR]: "indigo",
+    });
+    expect(p.isEnabled("indigo")).toBe(true);
+    expect(p.isEnabled("acme")).toBe(false);
+  });
+
+  it("enabledTenants returns a defensive copy (mutation does not corrupt cache)", () => {
+    const p = new EnvTenantListFlagProvider({
+      env: { [FEATURE_FLAG_TENANTS_ENV_VAR]: "indigo" },
+    });
+    (p.enabledTenants as Set<string>).add("acme");
+    expect(p.isEnabled("acme")).toBe(false);
+  });
+});
+
+// ─── 2. POST (HttpPushTransport) ──────────────────────────────────────────────
+
+describe("HttpPushTransport — POST /sync/push", () => {
+  it("POSTs an encoded PushEvent to <apiUrl>/sync/push with a Bearer token", async () => {
+    const { fetch, calls } = makeFetch({ ok: true, status: 200 });
+    const transport = new HttpPushTransport({
+      apiUrl: "https://vault-api.example.com/",
+      authToken: "tok-123",
+      fetchImpl: fetch,
+    });
+    await transport.start();
+    expect(transport.connected).toBe(true);
+
+    const event = fakePushEvent();
+    await transport.publish(event);
+
+    expect(calls).toHaveLength(1);
+    const call = calls[0];
+    // Trailing slash on apiUrl is normalized; default path is /sync/push.
+    expect(call.url).toBe("https://vault-api.example.com/sync/push");
+    const init = call.init as {
+      method: string;
+      headers: Record<string, string>;
+      body: string;
+    };
+    expect(init.method).toBe("POST");
+    expect(init.headers.Authorization).toBe("Bearer tok-123");
+    expect(init.headers["Content-Type"]).toBe("application/json");
+    // Body is a valid encoded PushEvent that round-trips.
+    expect(decodePushEvent(init.body)).toEqual(event);
+  });
+
+  it("resolves the auth token per-request via an async getter (self-heals across refresh)", async () => {
+    const { fetch, calls } = makeFetch();
+    let n = 0;
+    const transport = new HttpPushTransport({
+      apiUrl: "https://api.example.com",
+      authToken: () => `tok-${n++}`,
+      fetchImpl: fetch,
+    });
+    await transport.publish(fakePushEvent());
+    await transport.publish(fakePushEvent());
+    expect((calls[0].init as any).headers.Authorization).toBe("Bearer tok-0");
+    expect((calls[1].init as any).headers.Authorization).toBe("Bearer tok-1");
+  });
+
+  it("honors a custom pushPath + extra headers", async () => {
+    const { fetch, calls } = makeFetch();
+    const transport = new HttpPushTransport({
+      apiUrl: "https://api.example.com",
+      pushPath: "v1/sync/push",
+      authToken: "t",
+      headers: { "x-hq-client-name": "hq-sync-runner" },
+      fetchImpl: fetch,
+    });
+    await transport.publish(fakePushEvent());
+    expect(calls[0].url).toBe("https://api.example.com/v1/sync/push");
+    expect((calls[0].init as any).headers["x-hq-client-name"]).toBe(
+      "hq-sync-runner",
+    );
+  });
+
+  it("rejects when apiUrl is missing", () => {
+    expect(
+      () => new HttpPushTransport({ apiUrl: "", authToken: "t" }),
+    ).toThrow(/apiUrl is required/);
+  });
+
+  it("rejects (does not swallow) on a non-2xx response", async () => {
+    const { fetch } = makeFetch({ ok: false, status: 403, body: "forbidden" });
+    const transport = new HttpPushTransport({
+      apiUrl: "https://api.example.com",
+      authToken: "t",
+      fetchImpl: fetch,
+    });
+    await expect(transport.publish(fakePushEvent())).rejects.toThrow(/403/);
+  });
+
+  it("rejects on a malformed event before hitting the network", async () => {
+    const { fetch, calls } = makeFetch();
+    const transport = new HttpPushTransport({
+      apiUrl: "https://api.example.com",
+      authToken: "t",
+      fetchImpl: fetch,
+    });
+    await expect(
+      transport.publish(fakePushEvent({ contentHash: "not-a-hash" })),
+    ).rejects.toBeTruthy();
+    expect(calls).toHaveLength(0);
+  });
+});
+
+// ─── 3 + 4. Emit + gating + failure handling (PushEventEmitter) ───────────────
+
+describe("PushEventEmitter — emit, gating, failure handling", () => {
+  let dir: string;
+  let filePath: string;
+  const REL = "a.md";
+
+  beforeEach(() => {
+    dir = mkdtempSync(path.join(tmpdir(), "us008-"));
+    filePath = path.join(dir, REL);
+    writeFileSync(filePath, "hello world");
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function batchFor(...rels: string[]): TreeChangeBatch {
+    const paths = new Map<string, string>();
+    for (const rel of rels) paths.set(path.join(dir, rel), rel);
+    return { paths };
+  }
+
+  it("emits a valid PushEvent (sha256 hash, tenant) per changed path and ships it", async () => {
+    const transport = new NoopPushTransport();
+    const published: PushEvent[] = [];
+    const spyTransport: PushTransport = {
+      start: () => transport.start(),
+      dispose: () => transport.dispose(),
+      get connected() {
+        return transport.connected;
+      },
+      publish: async (e) => {
+        published.push(e);
+      },
+    };
+    const emitter = new PushEventEmitter({
+      originTenantId: "indigo",
+      originDeviceId: "dev-1",
+      transport: spyTransport,
+      flagProvider: new StaticFlagProvider(["indigo"]),
+      now: () => new Date("2026-05-21T00:00:00.000Z"),
+    });
+
+    await emitter.emitForBatch(batchFor(REL));
+
+    expect(published).toHaveLength(1);
+    const e = published[0];
+    expect(e.relativePath).toBe(REL);
+    expect(e.originTenantId).toBe("indigo");
+    expect(e.originDeviceId).toBe("dev-1");
+    const expectedHex = createHash("sha256").update("hello world").digest("hex");
+    expect(e.contentHash).toBe(`sha256:${expectedHex}`);
+    // Round-trips through the wire contract.
+    expect(() => decodePushEvent(e)).not.toThrow();
+  });
+
+  it("assigns monotonic per-device sequence numbers across emits", async () => {
+    const published: PushEvent[] = [];
+    const emitter = new PushEventEmitter({
+      originTenantId: "indigo",
+      originDeviceId: "dev-1",
+      transport: { start: async () => {}, dispose: async () => {}, connected: true, publish: async (e) => { published.push(e); } },
+      flagProvider: new StaticFlagProvider(["indigo"]),
+    });
+    writeFileSync(path.join(dir, "b.md"), "second");
+    await emitter.emitForBatch(batchFor(REL));
+    await emitter.emitForBatch(batchFor("b.md"));
+    expect(published.map((e) => e.sequenceNumber)).toEqual([0, 1]);
+  });
+
+  it("is DORMANT when the flag is OFF: ships nothing, attach is a no-op", async () => {
+    const publish = vi.fn(async () => {});
+    const emitter = new PushEventEmitter({
+      originTenantId: "indigo",
+      originDeviceId: "dev-1",
+      transport: { start: async () => {}, dispose: async () => {}, connected: false, publish },
+      flagProvider: new StaticFlagProvider([]), // indigo NOT enabled
+    });
+    expect(emitter.enabled).toBe(false);
+    await emitter.emitForBatch(batchFor(REL));
+    expect(publish).not.toHaveBeenCalled();
+    // attach returns a callable no-op when dormant.
+    const fakeWatcher = { onChange: vi.fn() } as any;
+    const off = emitter.attach(fakeWatcher);
+    expect(fakeWatcher.onChange).not.toHaveBeenCalled();
+    expect(() => off()).not.toThrow();
+  });
+
+  it("transport publish failure is caught + surfaced, never throws (cadence safety net)", async () => {
+    const onError = vi.fn();
+    const emitter = new PushEventEmitter({
+      originTenantId: "indigo",
+      originDeviceId: "dev-1",
+      transport: {
+        start: async () => {},
+        dispose: async () => {},
+        connected: true,
+        publish: async () => {
+          throw new Error("network down");
+        },
+      },
+      flagProvider: new StaticFlagProvider(["indigo"]),
+      onError,
+    });
+    // Must not reject — the daemon stays alive.
+    await expect(emitter.emitForBatch(batchFor(REL))).resolves.toBeUndefined();
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0][0]).toBeInstanceOf(Error);
+    expect(onError.mock.calls[0][1]).toMatchObject({ relativePath: REL });
+  });
+
+  it("a missing file (hash/stat race) is surfaced, other paths still ship", async () => {
+    const published: PushEvent[] = [];
+    const onError = vi.fn();
+    const emitter = new PushEventEmitter({
+      originTenantId: "indigo",
+      originDeviceId: "dev-1",
+      transport: { start: async () => {}, dispose: async () => {}, connected: true, publish: async (e) => { published.push(e); } },
+      flagProvider: new StaticFlagProvider(["indigo"]),
+      onError,
+    });
+    // REL exists; "ghost.md" does not.
+    await emitter.emitForBatch(batchFor(REL, "ghost.md"));
+    expect(published.map((e) => e.relativePath)).toEqual([REL]);
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0][1]).toMatchObject({ relativePath: "ghost.md" });
+  });
+
+  it("end-to-end: emit → HttpPushTransport POST with a valid schema (mocked fetch)", async () => {
+    const { fetch, calls } = makeFetch({ ok: true, status: 200 });
+    const transport = new HttpPushTransport({
+      apiUrl: "https://api.example.com",
+      authToken: "tok",
+      fetchImpl: fetch,
+    });
+    const emitter = new PushEventEmitter({
+      originTenantId: "indigo",
+      originDeviceId: "dev-1",
+      transport,
+      flagProvider: new StaticFlagProvider(["indigo"]),
+    });
+    await transport.start();
+    await emitter.emitForBatch(batchFor(REL));
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe("https://api.example.com/sync/push");
+    const posted = decodePushEvent((calls[0].init as any).body);
+    expect(posted.relativePath).toBe(REL);
+    expect(posted.originTenantId).toBe("indigo");
+  });
+});

package/src/sync/feature-flags.ts

@@ -0,0 +1,229 @@
+/**
+ * Per-tenant feature-flag module for the event-driven push pipeline.
+ *
+ * Ported from indigoai-us/hq-pro PR #112 (src/sync/feature-flags.ts) into
+ * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-008.
+ *
+ * Why this exists
+ * ───────────────
+ * The event-driven push pipeline must default OFF for all tenants and be
+ * enabled per-tenant ("OFF for all tenants by default, ON for Indigo only").
+ * This module provides the read-only seam the watcher (and a later receiver)
+ * consult at start time to decide whether to emit/ship PushEvents at all:
+ *  - {@link EventDrivenPushFlagProvider} — the small read-only seam every
+ *    caller consults. Returns a boolean for a given tenantId.
+ *  - {@link EnvTenantListFlagProvider} — production implementation. Reads
+ *    a comma-separated allow-list from {@link FEATURE_FLAG_TENANTS_ENV_VAR}
+ *    AND honors the legacy global `HQ_SYNC_EVENT_DRIVEN_PUSH_ENABLED=true`
+ *    as a backwards-compat global override. The legacy global wins when set
+ *    — it enables all tenants.
+ *  - {@link StaticFlagProvider} — small test helper. Constructor takes an
+ *    iterable of enabled tenant IDs. Used by watcher + feature-flag tests.
+ *  - {@link defaultFlagProvider} — factory callers default to when no
+ *    provider is explicitly supplied.
+ *
+ * Validation posture
+ * ──────────────────
+ * Tenant IDs from the env are trimmed, empty entries are dropped, and
+ * entries containing internal whitespace are warn-and-skipped (NOT thrown).
+ * The watcher runs inside a long-lived daemon — a malformed env var must
+ * not crash daemon startup; it must surface in logs and fall through to the
+ * default-OFF behavior for the misconfigured entry.
+ *
+ * @see src/watcher.ts — the TreeWatcher consults this seam at start time to
+ *   decide whether to emit + ship PushEvents (dormant when OFF).
+ */
+
+// ─── Constants ─────────────────────────────────────────────────────────────
+
+/**
+ * Env var holding a comma-separated allow-list of tenant IDs for which the
+ * event-driven push pipeline is enabled. Empty/unset means no tenants are
+ * enabled (default OFF for all). Example: `indigo,acme`.
+ *
+ * Tenant matching is exact and case-sensitive after trimming. Whitespace
+ * around commas is tolerated; internal whitespace within a tenant ID is
+ * not (warned + skipped — see `parseTenantList` below).
+ */
+export const FEATURE_FLAG_TENANTS_ENV_VAR =
+  "HQ_SYNC_EVENT_DRIVEN_PUSH_ENABLED_TENANTS";
+
+/**
+ * Legacy process-wide env var. When set to the literal string `"true"`, the
+ * pipeline is unconditionally enabled. Preserved as a "global override that
+ * enables ALL tenants" so a single-flag rollout (or local dev) keeps working.
+ *
+ * Operators flipping rollout via deploy-time config should prefer the
+ * per-tenant {@link FEATURE_FLAG_TENANTS_ENV_VAR} instead.
+ */
+export const FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR =
+  "HQ_SYNC_EVENT_DRIVEN_PUSH_ENABLED";
+
+// ─── Public types ──────────────────────────────────────────────────────────
+
+/**
+ * Read-only seam for the per-tenant event-driven push feature flag.
+ *
+ * Implementations are pure / synchronous. Callers MUST treat the result as
+ * the truth at the moment of the call — a deploy-time env-var change does
+ * NOT propagate to running daemons until they restart.
+ */
+export interface EventDrivenPushFlagProvider {
+  /**
+   * Returns true iff the event-driven push pipeline is enabled for
+   * `tenantId`. Defaults to false. Case-sensitive exact match against the
+   * configured allow-list (or the legacy global override).
+   */
+  isEnabled(tenantId: string): boolean;
+}
+
+/**
+ * Optional injection seam for warnings emitted while parsing the env var
+ * (invalid entries). Defaults to `console.warn`.
+ */
+export type FlagProviderWarnFn = (
+  message: string,
+  context: Record<string, unknown>,
+) => void;
+
+// ─── Env-driven provider ───────────────────────────────────────────────────
+
+/**
+ * Options for {@link EnvTenantListFlagProvider}.
+ */
+export interface EnvTenantListFlagProviderOptions {
+  /**
+   * Env snapshot. Defaults to `process.env`. Tests inject `{}` or a
+   * synthetic object so they don't mutate real env state.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Where to send "invalid entry, skipping" warnings. Defaults to
+   * `console.warn`.
+   */
+  warn?: FlagProviderWarnFn;
+}
+
+/**
+ * Production flag provider. Reads {@link FEATURE_FLAG_TENANTS_ENV_VAR} at
+ * construction time and caches the parsed set — `isEnabled()` is O(1).
+ *
+ * The legacy {@link FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR} (set to literal
+ * `"true"`) acts as a global override: when set, `isEnabled()` returns
+ * true for every tenant.
+ *
+ * Parse rules:
+ *  - Empty / unset {@link FEATURE_FLAG_TENANTS_ENV_VAR} → no tenants enabled.
+ *  - Whitespace around commas is tolerated and trimmed.
+ *  - Empty entries (`",,foo,"`) are silently dropped.
+ *  - Entries with INTERNAL whitespace (`"indigo team"`) are warn-and-skipped.
+ *  - Matching is exact + case-sensitive.
+ */
+export class EnvTenantListFlagProvider implements EventDrivenPushFlagProvider {
+  private readonly tenants: ReadonlySet<string>;
+  private readonly legacyGlobal: boolean;
+
+  constructor(opts: EnvTenantListFlagProviderOptions = {}) {
+    const env = opts.env ?? process.env;
+    const warn = opts.warn ?? defaultWarn;
+    this.tenants = parseTenantList(env[FEATURE_FLAG_TENANTS_ENV_VAR], warn);
+    this.legacyGlobal = env[FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR] === "true";
+  }
+
+  isEnabled(tenantId: string): boolean {
+    if (this.legacyGlobal) return true;
+    return this.tenants.has(tenantId);
+  }
+
+  /**
+   * Debug-only accessor — returns a defensive copy of the cached allow-list.
+   * Used by tests and the daemon's startup log line.
+   */
+  get enabledTenants(): ReadonlySet<string> {
+    return new Set(this.tenants);
+  }
+
+  /** Debug-only accessor — true iff the legacy global override is in effect. */
+  get globalOverride(): boolean {
+    return this.legacyGlobal;
+  }
+}
+
+// ─── Static provider (tests) ───────────────────────────────────────────────
+
+/**
+ * In-memory provider for unit tests. The constructor takes the set of
+ * enabled tenant IDs; `isEnabled()` is a plain `Set.has` check.
+ *
+ * Production callers should NEVER construct this — use
+ * {@link EnvTenantListFlagProvider} via {@link defaultFlagProvider}.
+ */
+export class StaticFlagProvider implements EventDrivenPushFlagProvider {
+  private readonly tenants: ReadonlySet<string>;
+
+  constructor(enabledTenants: Iterable<string>) {
+    this.tenants = new Set(enabledTenants);
+  }
+
+  isEnabled(tenantId: string): boolean {
+    return this.tenants.has(tenantId);
+  }
+}
+
+// ─── Factory ───────────────────────────────────────────────────────────────
+
+/**
+ * Build the default {@link EventDrivenPushFlagProvider} from an env
+ * snapshot. Production callers use this with no args — `process.env` is
+ * the implicit input.
+ */
+export function defaultFlagProvider(
+  env: Record<string, string | undefined> = process.env,
+): EventDrivenPushFlagProvider {
+  return new EnvTenantListFlagProvider({ env });
+}
+
+// ─── Internals ─────────────────────────────────────────────────────────────
+
+/**
+ * Parse a raw env value into a Set of valid tenant IDs.
+ *
+ * Kept as a free function so unit tests can call it via the class accessor
+ * with a synthetic warn spy without exporting an internal symbol.
+ */
+function parseTenantList(
+  raw: string | undefined,
+  warn: FlagProviderWarnFn,
+): ReadonlySet<string> {
+  if (raw === undefined || raw === "") return new Set<string>();
+  const out = new Set<string>();
+  for (const piece of raw.split(",")) {
+    const trimmed = piece.trim();
+    if (trimmed === "") {
+      // Empty slot (`",,foo,"` or trailing commas) — silently skipped.
+      continue;
+    }
+    if (/\s/.test(trimmed)) {
+      // Internal whitespace — operator misconfiguration. Warn but don't
+      // throw: the daemon must keep starting, the misconfigured tenant
+      // just stays OFF.
+      warn("feature-flag: skipping tenant entry with internal whitespace", {
+        envVar: FEATURE_FLAG_TENANTS_ENV_VAR,
+        rawEntry: trimmed,
+      });
+      continue;
+    }
+    out.add(trimmed);
+  }
+  return out;
+}
+
+/**
+ * Default warn destination — plain `console.warn`.
+ */
+function defaultWarn(
+  message: string,
+  context: Record<string, unknown>,
+): void {
+  console.warn(message, context);
+}

package/src/sync/index.ts

@@ -0,0 +1,74 @@
+/**
+ * @indigoai-us/hq-cloud — event-driven sync (`src/sync`) barrel.
+ *
+ * Surfaces the PushEvent wire contract + the PushTransport shipping seam
+ * ported from hq-pro PR #112 (project event-driven-sync-menubar US-007).
+ */
+
+export {
+  CONTENT_HASH_PATTERN,
+  ISO8601_DATETIME_PATTERN,
+  PushEventSchema,
+  PushEventDecodeError,
+  encodePushEvent,
+  decodePushEvent,
+} from "./push-event.js";
+export type { PushEvent, PushEventDecodeIssue } from "./push-event.js";
+
+export { NoopPushTransport, HttpPushTransport } from "./push-transport.js";
+export type {
+  PushTransport,
+  HttpPushTransportOptions,
+  AuthTokenSource,
+  FetchLike,
+} from "./push-transport.js";
+
+export {
+  FEATURE_FLAG_TENANTS_ENV_VAR,
+  FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR,
+  EnvTenantListFlagProvider,
+  StaticFlagProvider,
+  defaultFlagProvider,
+} from "./feature-flags.js";
+export type {
+  EventDrivenPushFlagProvider,
+  FlagProviderWarnFn,
+  EnvTenantListFlagProviderOptions,
+} from "./feature-flags.js";
+
+export {
+  NoopPushReceiver,
+  SqsPushReceiver,
+  InMemoryFanout,
+  InMemoryPushReceiver,
+  createPushReceiver,
+  DEFAULT_RECEIVER_DISPOSE_DRAIN_MS,
+  DEFAULT_WAIT_TIME_SECONDS,
+  DEFAULT_MAX_MESSAGES,
+} from "./push-receiver.js";
+export type {
+  PushReceiver,
+  PushReceiverContext,
+  SyncEngineFn,
+  PublishMetricFn,
+  ReceiverLogger,
+  SqsClientLike,
+  SqsMessageLike,
+  SqsPushReceiverOptions,
+  InMemoryPushReceiverOptions,
+  CreatePushReceiverOptions,
+} from "./push-receiver.js";
+
+export {
+  SYNC_METRIC_NAMESPACE,
+  SYNC_LATENCY_METRIC_NAME,
+  _setSyncCloudWatchClient,
+  publishSyncLatencyMetric,
+} from "./metrics.js";
+export type {
+  SyncLatencyMetric,
+  PublishSyncLatencyMetricOptions,
+} from "./metrics.js";
+
+export { createLogger } from "./logger.js";
+export type { CreateLoggerOptions, Logger } from "./logger.js";