@indigoai-us/hq-cloud 5.24.0 → 5.26.0

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

@@ -0,0 +1,110 @@
+/**
+ * PushEvent — the wire-shared payload exchanged between every link in the
+ * event-driven-hq-cloud-sync pipeline.
+ *
+ * Producers (the watcher) emit one PushEvent per local content change.
+ * Consumers (the push endpoint / receiver / coalescer) decode the payload,
+ * validate it, and act on it. Because the same shape crosses a network
+ * boundary, it has its own dedicated module.
+ *
+ * Conventions
+ * ───────────
+ * - `contentHash` is `sha256:<64-lowercase-hex>`. The `<algorithm>:<hex>`
+ *   prefix lets a future hash migration ship without breaking the wire
+ *   format — consumers can branch on the prefix and fall back to refusing
+ *   unknown algorithms.
+ * - `mtime` and `eventTimestamp` are strict ISO-8601 datetime strings.
+ *   `mtime` is the filesystem modification time of the source file at the
+ *   moment of capture; `eventTimestamp` is when the watcher emitted the
+ *   event. They diverge whenever the watcher coalesces or retries.
+ * - `sequenceNumber` is a non-negative safe integer. Monotonicity per
+ *   `originDeviceId` is a producer-side invariant — a single PushEvent
+ *   can't be self-monotonic, so the schema only validates the bounds.
+ * - Unknown extra fields are dropped silently by `decodePushEvent` to
+ *   permit forwards-compatible additions on the producer side without
+ *   forcing every consumer to upgrade in lockstep.
+ *
+ * Ported from indigoai-us/hq-pro PR #112 (src/sync/push-event.ts) into
+ * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
+ */
+import { z } from "zod";
+/**
+ * `sha256:` + 64 lowercase hex chars. The algorithm prefix is mandatory so
+ * future hash migrations stay non-breaking; consumers can switch on the
+ * prefix and reject unknown algorithms explicitly.
+ */
+export declare const CONTENT_HASH_PATTERN: RegExp;
+/**
+ * Strict ISO-8601 datetime regex matching what `z.iso.datetime()` produces.
+ *
+ * Format: `YYYY-MM-DDTHH:MM:SS(.fff)?(Z|±HH:MM)`
+ */
+export declare const ISO8601_DATETIME_PATTERN: RegExp;
+/**
+ * Runtime schema for PushEvent. Unknown extra keys are dropped via the zod
+ * default `.strip()` behavior — that is load-bearing for forwards
+ * compatibility (see module JSDoc).
+ */
+export declare const PushEventSchema: z.ZodObject<{
+    relativePath: z.ZodString;
+    contentHash: z.ZodString;
+    mtime: z.ZodString;
+    originDeviceId: z.ZodString;
+    originTenantId: z.ZodString;
+    sequenceNumber: z.ZodNumber;
+    eventTimestamp: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The canonical PushEvent type. All fields are required; producers and
+ * consumers share this exact shape.
+ */
+export type PushEvent = z.infer<typeof PushEventSchema>;
+/**
+ * Public alias for a single decode issue. Aliased here (rather than re-exporting
+ * the `$`-prefixed zod internal symbol directly) so consumers can annotate
+ * against `PushEventDecodeIssue` without importing zod internals. The alias is
+ * structurally identical to `z.core.$ZodIssue`, so this is a non-breaking
+ * narrowing of the public surface.
+ */
+export type PushEventDecodeIssue = z.core.$ZodIssue;
+/**
+ * Thrown by `decodePushEvent` (and `encodePushEvent` on invalid input) when
+ * the payload fails validation. `.issues` carries the underlying zod issues
+ * so callers can render structured diagnostics — see the test suite for an
+ * example of asserting on the issue path.
+ */
+export declare class PushEventDecodeError extends Error {
+    readonly issues: readonly PushEventDecodeIssue[];
+    readonly stage: "json-parse" | "schema-validation";
+    constructor(message: string, args: {
+        issues: readonly PushEventDecodeIssue[];
+        stage: "json-parse" | "schema-validation";
+        cause?: unknown;
+    });
+}
+/**
+ * Validate `event` against `PushEventSchema` and return the canonical JSON
+ * serialization. Validating on encode catches producer-side mistakes early
+ * (and ensures the output always round-trips through `decodePushEvent`).
+ *
+ * Extra keys on `event` are dropped — the returned JSON string contains
+ * only the declared PushEvent fields.
+ */
+export declare function encodePushEvent(event: PushEvent): string;
+/**
+ * Parse and validate an incoming PushEvent. Accepts either a raw JSON string
+ * (the on-the-wire form) or an already-parsed object (handy for in-process
+ * wiring and tests).
+ *
+ * - Unknown extra fields are dropped silently — see module JSDoc.
+ * - Missing required fields throw `PushEventDecodeError` whose `.issues`
+ *   exposes the underlying zod issues.
+ * - Malformed JSON throws `PushEventDecodeError` with `stage:"json-parse"`
+ *   and a synthetic issue at the root path.
+ * - A JSON string that parses to a non-object value (e.g. `'42'`, `'"text"'`,
+ *   `'null'`) surfaces as `stage: 'schema-validation'` — the JSON itself was
+ *   syntactically valid, so it clears the parse stage before failing the
+ *   object-shape check.
+ */
+export declare function decodePushEvent(input: unknown): PushEvent;
+//# sourceMappingURL=push-event.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"push-event.d.ts","sourceRoot":"","sources":["../../src/sync/push-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAA0B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAC+B,CAAC;AAIrE;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;iBAqClB,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;AAEpD;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,mBAAmB,CAAC;gBAGjD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QACJ,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;QACxC,KAAK,EAAE,YAAY,GAAG,mBAAmB,CAAC;QAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAOJ;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CASxD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAkCzD"}

package/dist/sync/push-event.js

@@ -0,0 +1,153 @@
+/**
+ * PushEvent — the wire-shared payload exchanged between every link in the
+ * event-driven-hq-cloud-sync pipeline.
+ *
+ * Producers (the watcher) emit one PushEvent per local content change.
+ * Consumers (the push endpoint / receiver / coalescer) decode the payload,
+ * validate it, and act on it. Because the same shape crosses a network
+ * boundary, it has its own dedicated module.
+ *
+ * Conventions
+ * ───────────
+ * - `contentHash` is `sha256:<64-lowercase-hex>`. The `<algorithm>:<hex>`
+ *   prefix lets a future hash migration ship without breaking the wire
+ *   format — consumers can branch on the prefix and fall back to refusing
+ *   unknown algorithms.
+ * - `mtime` and `eventTimestamp` are strict ISO-8601 datetime strings.
+ *   `mtime` is the filesystem modification time of the source file at the
+ *   moment of capture; `eventTimestamp` is when the watcher emitted the
+ *   event. They diverge whenever the watcher coalesces or retries.
+ * - `sequenceNumber` is a non-negative safe integer. Monotonicity per
+ *   `originDeviceId` is a producer-side invariant — a single PushEvent
+ *   can't be self-monotonic, so the schema only validates the bounds.
+ * - Unknown extra fields are dropped silently by `decodePushEvent` to
+ *   permit forwards-compatible additions on the producer side without
+ *   forcing every consumer to upgrade in lockstep.
+ *
+ * Ported from indigoai-us/hq-pro PR #112 (src/sync/push-event.ts) into
+ * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
+ */
+import { z } from "zod";
+// ─── Constants ─────────────────────────────────────────────────────────────
+/**
+ * `sha256:` + 64 lowercase hex chars. The algorithm prefix is mandatory so
+ * future hash migrations stay non-breaking; consumers can switch on the
+ * prefix and reject unknown algorithms explicitly.
+ */
+export const CONTENT_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/**
+ * Strict ISO-8601 datetime regex matching what `z.iso.datetime()` produces.
+ *
+ * Format: `YYYY-MM-DDTHH:MM:SS(.fff)?(Z|±HH:MM)`
+ */
+export const ISO8601_DATETIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+// ─── Zod schema ────────────────────────────────────────────────────────────
+/**
+ * Runtime schema for PushEvent. Unknown extra keys are dropped via the zod
+ * default `.strip()` behavior — that is load-bearing for forwards
+ * compatibility (see module JSDoc).
+ */
+export const PushEventSchema = z
+    .object({
+    relativePath: z
+        .string()
+        .min(1, "relativePath must be a non-empty string"),
+    contentHash: z
+        .string()
+        .regex(CONTENT_HASH_PATTERN, "contentHash must match `sha256:<64 lowercase hex>`"),
+    mtime: z
+        .string()
+        .regex(ISO8601_DATETIME_PATTERN, "mtime must be an ISO-8601 datetime"),
+    originDeviceId: z
+        .string()
+        .min(1, "originDeviceId must be a non-empty string"),
+    originTenantId: z
+        .string()
+        .min(1, "originTenantId must be a non-empty string"),
+    sequenceNumber: z
+        .number()
+        .int("sequenceNumber must be an integer")
+        .min(0, "sequenceNumber must be non-negative")
+        .max(Number.MAX_SAFE_INTEGER, "sequenceNumber must be <= Number.MAX_SAFE_INTEGER"),
+    eventTimestamp: z
+        .string()
+        .regex(ISO8601_DATETIME_PATTERN, "eventTimestamp must be an ISO-8601 datetime"),
+})
+    // `.strip()` is the zod 4 default; called explicitly here so the intent is
+    // obvious to future readers. Unknown keys MUST NOT throw — see module JSDoc.
+    .strip();
+/**
+ * Thrown by `decodePushEvent` (and `encodePushEvent` on invalid input) when
+ * the payload fails validation. `.issues` carries the underlying zod issues
+ * so callers can render structured diagnostics — see the test suite for an
+ * example of asserting on the issue path.
+ */
+export class PushEventDecodeError extends Error {
+    issues;
+    stage;
+    constructor(message, args) {
+        super(message, args.cause === undefined ? undefined : { cause: args.cause });
+        this.name = "PushEventDecodeError";
+        this.issues = args.issues;
+        this.stage = args.stage;
+    }
+}
+// ─── Encode / Decode ───────────────────────────────────────────────────────
+/**
+ * Validate `event` against `PushEventSchema` and return the canonical JSON
+ * serialization. Validating on encode catches producer-side mistakes early
+ * (and ensures the output always round-trips through `decodePushEvent`).
+ *
+ * Extra keys on `event` are dropped — the returned JSON string contains
+ * only the declared PushEvent fields.
+ */
+export function encodePushEvent(event) {
+    const parsed = PushEventSchema.safeParse(event);
+    if (!parsed.success) {
+        throw new PushEventDecodeError("encodePushEvent: input failed PushEvent schema validation", { issues: parsed.error.issues, stage: "schema-validation" });
+    }
+    return JSON.stringify(parsed.data);
+}
+/**
+ * Parse and validate an incoming PushEvent. Accepts either a raw JSON string
+ * (the on-the-wire form) or an already-parsed object (handy for in-process
+ * wiring and tests).
+ *
+ * - Unknown extra fields are dropped silently — see module JSDoc.
+ * - Missing required fields throw `PushEventDecodeError` whose `.issues`
+ *   exposes the underlying zod issues.
+ * - Malformed JSON throws `PushEventDecodeError` with `stage:"json-parse"`
+ *   and a synthetic issue at the root path.
+ * - A JSON string that parses to a non-object value (e.g. `'42'`, `'"text"'`,
+ *   `'null'`) surfaces as `stage: 'schema-validation'` — the JSON itself was
+ *   syntactically valid, so it clears the parse stage before failing the
+ *   object-shape check.
+ */
+export function decodePushEvent(input) {
+    let candidate = input;
+    if (typeof input === "string") {
+        try {
+            candidate = JSON.parse(input);
+        }
+        catch (err) {
+            throw new PushEventDecodeError("decodePushEvent: input string is not valid JSON", {
+                issues: [
+                    {
+                        code: "custom",
+                        message: err instanceof Error ? err.message : "invalid JSON input",
+                        path: [],
+                        input,
+                    },
+                ],
+                stage: "json-parse",
+                cause: err,
+            });
+        }
+    }
+    const parsed = PushEventSchema.safeParse(candidate);
+    if (!parsed.success) {
+        throw new PushEventDecodeError("decodePushEvent: payload failed PushEvent schema validation", { issues: parsed.error.issues, stage: "schema-validation" });
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=push-event.js.map

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

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

package/dist/sync/push-event.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Unit tests for `src/sync/push-event.ts` (US-007 port).
+ *
+ * Covers the three required acceptance assertions:
+ *  1. A known-good fixture round-trips through encode → decode unchanged.
+ *  2. Unknown extra fields on the input are dropped silently (no throw).
+ *  3. Missing required fields throw a typed `PushEventDecodeError` whose
+ *     `.issues` exposes the underlying zod issues.
+ *
+ * Also covers the supporting invariants needed to keep the wire contract
+ * stable across the watcher → server → receiver hop: malformed JSON, bad
+ * hash/timestamp formats, and the integer/range bounds on `sequenceNumber`.
+ */
+export {};
+//# sourceMappingURL=push-event.test.d.ts.map

package/dist/sync/push-event.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-event.test.d.ts","sourceRoot":"","sources":["../../src/sync/push-event.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/sync/push-event.test.js

@@ -0,0 +1,188 @@
+/**
+ * Unit tests for `src/sync/push-event.ts` (US-007 port).
+ *
+ * Covers the three required acceptance assertions:
+ *  1. A known-good fixture round-trips through encode → decode unchanged.
+ *  2. Unknown extra fields on the input are dropped silently (no throw).
+ *  3. Missing required fields throw a typed `PushEventDecodeError` whose
+ *     `.issues` exposes the underlying zod issues.
+ *
+ * Also covers the supporting invariants needed to keep the wire contract
+ * stable across the watcher → server → receiver hop: malformed JSON, bad
+ * hash/timestamp formats, and the integer/range bounds on `sequenceNumber`.
+ */
+import { describe, expect, it } from "vitest";
+import { PushEventDecodeError, decodePushEvent, encodePushEvent, } from "../../src/sync/index.js";
+// A canonical, valid PushEvent. All other tests derive from this fixture so
+// any single field mutation can't accidentally pass for the wrong reason.
+const validFixture = {
+    relativePath: "docs/architecture/overview.md",
+    contentHash: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    mtime: "2026-05-18T12:34:56.789Z",
+    originDeviceId: "device-laptop-a",
+    originTenantId: "tenant-indigo",
+    sequenceNumber: 42,
+    eventTimestamp: "2026-05-18T12:35:00.000Z",
+};
+describe("PushEvent encode/decode", () => {
+    // ── Acceptance #1: round-trip ──────────────────────────────────────────
+    it("round-trips a known-good fixture through encode → decode", () => {
+        const encoded = encodePushEvent(validFixture);
+        expect(typeof encoded).toBe("string");
+        const decoded = decodePushEvent(encoded);
+        expect(decoded).toEqual(validFixture);
+        // Re-encoding the decoded value must produce byte-identical output —
+        // catches accidental field re-ordering or coercion drift.
+        expect(encodePushEvent(decoded)).toBe(encoded);
+    });
+    it("decodes from a pre-parsed object as well as from a JSON string", () => {
+        const fromObject = decodePushEvent({ ...validFixture });
+        const fromString = decodePushEvent(JSON.stringify(validFixture));
+        expect(fromObject).toEqual(validFixture);
+        expect(fromString).toEqual(validFixture);
+    });
+    // ── Acceptance #2: unknown fields dropped ──────────────────────────────
+    it("drops unknown extra fields silently (does not throw)", () => {
+        const withExtras = {
+            ...validFixture,
+            // Future producers may add fields like `originAppVersion`; today's
+            // consumers must not crash on them.
+            originAppVersion: "1.2.3",
+            experimentalFlag: true,
+            nested: { ignored: "yes" },
+        };
+        const decoded = decodePushEvent(withExtras);
+        expect(decoded).toEqual(validFixture);
+        expect(decoded).not.toHaveProperty("originAppVersion");
+        expect(decoded).not.toHaveProperty("experimentalFlag");
+        expect(decoded).not.toHaveProperty("nested");
+        // Round-tripping through JSON behaves the same way.
+        const decodedFromJson = decodePushEvent(JSON.stringify(withExtras));
+        expect(decodedFromJson).toEqual(validFixture);
+    });
+    // ── Acceptance #3: missing required fields throw typed error ───────────
+    it.each([
+        "relativePath",
+        "contentHash",
+        "mtime",
+        "originDeviceId",
+        "originTenantId",
+        "sequenceNumber",
+        "eventTimestamp",
+    ])("throws PushEventDecodeError when %s is missing", (field) => {
+        const partial = { ...validFixture };
+        delete partial[field];
+        let caught;
+        try {
+            decodePushEvent(partial);
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(PushEventDecodeError);
+        const error = caught;
+        expect(error.stage).toBe("schema-validation");
+        expect(error.issues.length).toBeGreaterThan(0);
+        // The zod issue path must point at the missing field — that's what
+        // downstream callers rely on to render structured diagnostics.
+        expect(error.issues.some((issue) => issue.path.includes(field))).toBe(true);
+    });
+    it("PushEventDecodeError carries the underlying zod issues array", () => {
+        // Multiple missing fields → multiple issues, all reachable via `.issues`.
+        const sparse = { relativePath: "x.md" };
+        let caught;
+        try {
+            decodePushEvent(sparse);
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(PushEventDecodeError);
+        const error = caught;
+        expect(error.issues.length).toBeGreaterThanOrEqual(6);
+    });
+    // ── Supporting wire-contract invariants ────────────────────────────────
+    it("throws PushEventDecodeError on malformed JSON input", () => {
+        let caught;
+        try {
+            decodePushEvent("{not valid json");
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(PushEventDecodeError);
+        const error = caught;
+        expect(error.stage).toBe("json-parse");
+        expect(error.issues.length).toBe(1);
+    });
+    it("surfaces a JSON-parseable non-object payload as schema-validation, not json-parse", () => {
+        // `'42'` is syntactically valid JSON, so the parse stage clears; the
+        // object-shape check is what fails. Pinning this here keeps the JSDoc
+        // contract (see decodePushEvent docs) honest.
+        let caught;
+        try {
+            decodePushEvent("42");
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(PushEventDecodeError);
+        const error = caught;
+        expect(error.stage).toBe("schema-validation");
+    });
+    it.each([
+        ["raw hex without `sha256:` prefix", "e".repeat(64)],
+        ["wrong algorithm prefix", `md5:${"a".repeat(64)}`],
+        ["uppercase hex", `sha256:${"A".repeat(64)}`],
+        ["too few hex chars", `sha256:${"a".repeat(63)}`],
+    ])("rejects contentHash: %s", (_label, badHash) => {
+        expect(() => decodePushEvent({ ...validFixture, contentHash: badHash })).toThrow(PushEventDecodeError);
+    });
+    it.each([
+        ["missing timezone", "2026-05-18T12:34:56.789"],
+        ["space separator", "2026-05-18 12:34:56Z"],
+        ["date only", "2026-05-18"],
+    ])("rejects ISO-8601 timestamps: %s", (_label, badTimestamp) => {
+        expect(() => decodePushEvent({ ...validFixture, mtime: badTimestamp })).toThrow(PushEventDecodeError);
+        expect(() => decodePushEvent({ ...validFixture, eventTimestamp: badTimestamp })).toThrow(PushEventDecodeError);
+    });
+    it("accepts a sequenceNumber of 0 and rejects negative / fractional / oversized values", () => {
+        // 0 is allowed — sequence numbers are non-negative, not strictly positive.
+        expect(decodePushEvent({ ...validFixture, sequenceNumber: 0 })).toEqual({
+            ...validFixture,
+            sequenceNumber: 0,
+        });
+        expect(() => decodePushEvent({ ...validFixture, sequenceNumber: -1 })).toThrow(PushEventDecodeError);
+        expect(() => decodePushEvent({ ...validFixture, sequenceNumber: 1.5 })).toThrow(PushEventDecodeError);
+        expect(() => decodePushEvent({
+            ...validFixture,
+            sequenceNumber: Number.MAX_SAFE_INTEGER + 1,
+        })).toThrow(PushEventDecodeError);
+    });
+    it("encodePushEvent validates and drops unknown fields from the output", () => {
+        // We cast through `unknown` because the public type forbids extra keys —
+        // this models a producer that hands us a wider object by mistake.
+        const wider = {
+            ...validFixture,
+            stray: "field",
+        };
+        const encoded = encodePushEvent(wider);
+        expect(encoded.includes("stray")).toBe(false);
+        expect(JSON.parse(encoded)).toEqual(validFixture);
+    });
+    it("encodePushEvent throws PushEventDecodeError when input is invalid", () => {
+        const bad = { ...validFixture, contentHash: "not-a-hash" };
+        let caught;
+        try {
+            encodePushEvent(bad);
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(PushEventDecodeError);
+        const error = caught;
+        expect(error.stage).toBe("schema-validation");
+        expect(error.issues.some((issue) => issue.path.includes("contentHash"))).toBe(true);
+    });
+});
+//# sourceMappingURL=push-event.test.js.map

package/dist/sync/push-event.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-event.test.js","sourceRoot":"","sources":["../../src/sync/push-event.test.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,67 @@
+/**
+ * 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 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 declare class NoopPushTransport implements PushTransport {
+    private _connected;
+    private _count;
+    get connected(): boolean;
+    /** Test/observability hook: how many events have been published. */
+    get publishedCount(): number;
+    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

@@ -0,0 +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"}

package/dist/sync/push-transport.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+/**
+ * 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 {
+    _connected = false;
+    _count = 0;
+    get connected() {
+        return this._connected;
+    }
+    /** Test/observability hook: how many events have been published. */
+    get publishedCount() {
+        return this._count;
+    }
+    async start() {
+        this._connected = true;
+    }
+    async publish(_event) {
+        this._count += 1;
+    }
+    async dispose() {
+        this._connected = false;
+    }
+}
+//# sourceMappingURL=push-transport.js.map

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

@@ -0,0 +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"}