@indigoai-us/hq-cloud 5.24.0 → 5.26.0

package/src/cli/sync.ts

@@ -120,6 +120,28 @@ export type SyncProgressEvent =
       journalEtag: string;
       remoteEtag: string;
       reason: "stale-etag" | "legacy-no-etag";
+    }
+  | {
+      /**
+       * Emitted at most ONCE per `share()` call (push leg of a sync run) when
+       * `personalMode === true` and the personal-vault default-exclusion list
+       * blocked one or more files that would otherwise have uploaded. Gives
+       * the UI a single summary signal — "N files quietly excluded by default
+       * policy" — without firing one event per excluded file (which would
+       * dominate the event stream on first-sync of a dirty tree).
+       *
+       * `count` is the total number of paths the exclusion filter rejected
+       * (deduplicated across the walk). `samplePaths` carries up to 10
+       * forward-slash-separated relative paths for diagnostic display. `byId`
+       * is a per-exclusion-rule breakdown so the UI can render which class
+       * of exclusion did the work (secret / machine-local / scratch / …).
+       *
+       * Not emitted when `count === 0` — silent on a clean tree.
+       */
+      type: "personal-vault-out-of-policy";
+      count: number;
+      samplePaths: string[];
+      byId: Record<string, number>;
     };
 
 export interface SyncOptions {

package/src/index.ts

@@ -108,6 +108,16 @@ export {
   computePersonalVaultPaths,
 } from "./personal-vault.js";
 
+// Personal-vault default-exclusions (5.25+) — second-tier deep-walk filter
+// for secrets, machine-local state, scratch dirs, OS/build cruft.
+export {
+  PERSONAL_VAULT_DEFAULT_EXCLUSIONS,
+  isPersonalVaultExcluded,
+  matchPersonalVaultExclusion,
+  wrapFilterWithPersonalVaultDefaults,
+} from "./personal-vault-exclusions.js";
+export type { PersonalVaultExclusion } from "./personal-vault-exclusions.js";
+
 // VaultClient SDK (VLT-7)
 export { VaultClient, pickCanonicalPersonEntity } from "./vault-client.js";
 export {
@@ -271,3 +281,20 @@ 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,
+} from "./sync/index.js";
+export type {
+  PushEvent,
+  PushEventDecodeIssue,
+  PushTransport,
+} from "./sync/index.js";

package/src/personal-vault-exclusions.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Tests for `personal-vault-exclusions.ts`. Pin the regex / segment contracts
+ * for every entry in PERSONAL_VAULT_DEFAULT_EXCLUSIONS so a future edit that
+ * relaxes one (e.g. dropping the `_legacy-` prefix match, or changing the
+ * `.cache_*` shape) surfaces here instead of in the field.
+ *
+ * Two test layers:
+ *
+ *   1. Per-rule predicate tests. Each exclusion is exercised with at least
+ *      one match-positive and one match-negative path so the regex shape is
+ *      pinned. The `byId` event field on the runner uses `ex.id` directly,
+ *      so the id stability is part of the contract too — tests assert
+ *      against the literal id string.
+ *
+ *   2. Filter-wrap integration. Confirms that `wrapFilterWithPersonalVaultDefaults`
+ *      defers to the underlying filter, computes the relative path correctly,
+ *      and only fires the `onExcluded` callback when the underlying filter
+ *      WOULD have allowed the path (so the count tracks only "newly blocked
+ *      by these defaults", not "blocked by .hqignore too").
+ */
+
+import { describe, expect, it } from "vitest";
+import * as path from "node:path";
+import {
+  PERSONAL_VAULT_DEFAULT_EXCLUSIONS,
+  isPersonalVaultExcluded,
+  matchPersonalVaultExclusion,
+  wrapFilterWithPersonalVaultDefaults,
+  _testing,
+} from "./personal-vault-exclusions.js";
+
+describe("PERSONAL_VAULT_DEFAULT_EXCLUSIONS", () => {
+  it("exports a non-empty, frozen-shaped list", () => {
+    expect(PERSONAL_VAULT_DEFAULT_EXCLUSIONS.length).toBeGreaterThan(10);
+    // Every entry has the four required fields; this pins the public shape
+    // so a future addition without `category` or `id` fails fast.
+    for (const ex of PERSONAL_VAULT_DEFAULT_EXCLUSIONS) {
+      expect(typeof ex.id).toBe("string");
+      expect(ex.id.length).toBeGreaterThan(0);
+      expect(typeof ex.category).toBe("string");
+      expect(typeof ex.test).toBe("function");
+      expect(typeof ex.pattern).toBe("string");
+    }
+  });
+
+  it("has unique ids (event byId aggregation requires it)", () => {
+    const ids = new Set<string>();
+    for (const ex of PERSONAL_VAULT_DEFAULT_EXCLUSIONS) {
+      expect(ids.has(ex.id)).toBe(false);
+      ids.add(ex.id);
+    }
+  });
+});
+
+// ── Per-rule predicate matrix ───────────────────────────────────────────────
+//
+// One block per rule. The positives prove "this path SHOULD be excluded"; the
+// negatives prove "this path SHOULD NOT" (guards against over-broad regexes
+// that would block legitimate user content).
+
+describe("env-file exclusion (secrets)", () => {
+  it.each([".env", ".env.local", ".env.production", "core/.env", "personal/.env.local"])(
+    "matches %s",
+    (p) => {
+      expect(isPersonalVaultExcluded(p)).toBe(true);
+      expect(matchPersonalVaultExclusion(p)?.id).toBe("env-file");
+    },
+  );
+
+  it.each(["envconfig.md", ".env-example.md", "core/policies/env-vars.md"])(
+    "does NOT match %s",
+    (p) => {
+      // ".env-example.md" is intentionally a negative — the basename starts
+      // with ".env-", not ".env." (dot vs hyphen). We want to allow docs
+      // that reference env-vars without the regex grabbing them.
+      const m = matchPersonalVaultExclusion(p);
+      expect(m?.id).not.toBe("env-file");
+    },
+  );
+});
+
+describe("mcp-config exclusion (secrets)", () => {
+  it.each([".mcp.json", "personal/.mcp.json", "core/.claude/.mcp.json"])(
+    "matches %s",
+    (p) => {
+      expect(matchPersonalVaultExclusion(p)?.id).toBe("mcp-config");
+    },
+  );
+
+  it.each(["mcp.json", "core/policies/mcp.md", ".mcp.example.json"])(
+    "does NOT match %s",
+    (p) => {
+      expect(matchPersonalVaultExclusion(p)?.id).not.toBe("mcp-config");
+    },
+  );
+});
+
+describe("beads exclusion (machine-local SQLite)", () => {
+  it.each([
+    ".beads/beads.db",
+    ".beads/beads.db-wal",
+    ".beads/beads.db-shm",
+    ".beads/beads.left.jsonl",
+    "personal/.beads/issue.json",
+  ])("matches %s", (p) => {
+    expect(matchPersonalVaultExclusion(p)?.id).toBe("beads-db");
+  });
+
+  it.each(["beads.md", "core/knowledge/beads-guide.md"])("does NOT match %s", (p) => {
+    expect(matchPersonalVaultExclusion(p)?.id).not.toBe("beads-db");
+  });
+});
+
+describe("obsidian / vercel / cache exclusions", () => {
+  it("matches .obsidian/", () => {
+    expect(matchPersonalVaultExclusion(".obsidian/workspace.json")?.id).toBe("obsidian-workspace");
+  });
+  it("matches .vercel/", () => {
+    expect(matchPersonalVaultExclusion(".vercel/project.json")?.id).toBe("vercel-link");
+  });
+  it("matches .cache_ggshield", () => {
+    expect(matchPersonalVaultExclusion(".cache_ggshield")?.id).toBe("cache-dir");
+  });
+  it("matches .cache_anything", () => {
+    expect(matchPersonalVaultExclusion(".cache_foo")?.id).toBe("cache-dir");
+  });
+  it("does NOT match .cache (no underscore)", () => {
+    // `.cache_*` is the segment shape — bare `.cache` should be left for
+    // other rules / .hqignore. Pinned so a future widen-of-pattern surfaces here.
+    expect(matchPersonalVaultExclusion(".cache")).toBeUndefined();
+  });
+});
+
+describe("update-output / legacy / hq-conflicts exclusions (scratch)", () => {
+  it.each([
+    "output/hatch-pet/scaffold.md",
+    "personal/data/output/hatch-pet/file.md",
+    "core/output/x.md",
+  ])("matches %s as update-output", (p) => {
+    expect(matchPersonalVaultExclusion(p)?.id).toBe("update-output");
+  });
+
+  it.each([
+    "_legacy-pre14.2/x.md",
+    "personal/_legacy-2024/old.md",
+    "_legacy_v1/y.md",
+    "_legacy/z.md",
+  ])("matches %s as legacy-dir", (p) => {
+    expect(matchPersonalVaultExclusion(p)?.id).toBe("legacy-dir");
+  });
+
+  it.each([".hq-conflicts/file.md", "personal/.hq-conflicts/x.md"])(
+    "matches %s as hq-conflicts-dir",
+    (p) => {
+      expect(matchPersonalVaultExclusion(p)?.id).toBe("hq-conflicts-dir");
+    },
+  );
+
+  it("does NOT match 'output.md' (basename collision guard)", () => {
+    expect(matchPersonalVaultExclusion("core/output.md")).toBeUndefined();
+  });
+});
+
+describe("OS / build cruft exclusions", () => {
+  it("matches .DS_Store anywhere", () => {
+    expect(matchPersonalVaultExclusion(".DS_Store")?.id).toBe("ds-store");
+    expect(matchPersonalVaultExclusion("personal/.DS_Store")?.id).toBe("ds-store");
+  });
+
+  it.each([
+    ["node_modules/x.js", "node-modules"],
+    ["personal/x/node_modules/y.js", "node-modules"],
+    ["dist/bundle.js", "dist-dir"],
+    [".next/build/file.js", "next-dir"],
+    ["build/output.js", "build-dir"],
+  ])("matches %s as %s", (p, expectedId) => {
+    expect(matchPersonalVaultExclusion(p)?.id).toBe(expectedId);
+  });
+});
+
+// ── _testing internals ───────────────────────────────────────────────────────
+
+describe("_testing internals", () => {
+  it("hasSegment matches exact / prefix / middle / suffix forms", () => {
+    expect(_testing.hasSegment("foo", "foo")).toBe(true);
+    expect(_testing.hasSegment("foo/bar", "foo")).toBe(true);
+    expect(_testing.hasSegment("a/foo/b", "foo")).toBe(true);
+    expect(_testing.hasSegment("a/foo", "foo")).toBe(true);
+    expect(_testing.hasSegment("foobar", "foo")).toBe(false);
+    expect(_testing.hasSegment("a/foobar", "foo")).toBe(false);
+  });
+
+  it("basename returns the trailing segment", () => {
+    expect(_testing.basename("a/b/c.md")).toBe("c.md");
+    expect(_testing.basename("c.md")).toBe("c.md");
+    expect(_testing.basename("")).toBe("");
+  });
+});
+
+// ── Filter-wrap integration ──────────────────────────────────────────────────
+
+describe("wrapFilterWithPersonalVaultDefaults", () => {
+  // Use a syncRoot path independent of the test runner's cwd so the
+  // path.relative() calls inside the wrapper produce predictable results
+  // regardless of where the test runs from.
+  const syncRoot = "/tmp/hq-root";
+
+  it("defers to the underlying filter when it rejects", () => {
+    const calls: Array<{ rel: string; id: string }> = [];
+    const wrapped = wrapFilterWithPersonalVaultDefaults(
+      () => false, // underlying rejects everything
+      syncRoot,
+      (rel, match) => calls.push({ rel, id: match.id }),
+    );
+
+    // Even though `.env` matches a default exclusion, the underlying
+    // filter already rejected it — onExcluded must NOT fire (we only
+    // want to count things that would have made it past the user's
+    // .hqignore but are blocked by our defaults).
+    expect(wrapped(path.join(syncRoot, ".env"))).toBe(false);
+    expect(calls).toEqual([]);
+  });
+
+  it("rejects and tags onExcluded when underlying allows + default blocks", () => {
+    const calls: Array<{ rel: string; id: string }> = [];
+    const wrapped = wrapFilterWithPersonalVaultDefaults(
+      () => true, // underlying allows everything
+      syncRoot,
+      (rel, match) => calls.push({ rel, id: match.id }),
+    );
+
+    expect(wrapped(path.join(syncRoot, ".env"))).toBe(false);
+    expect(wrapped(path.join(syncRoot, "personal", ".env.local"))).toBe(false);
+    expect(wrapped(path.join(syncRoot, "personal", "agents.md"))).toBe(true);
+    expect(calls).toEqual([
+      { rel: ".env", id: "env-file" },
+      { rel: "personal/.env.local", id: "env-file" },
+      // "personal/agents.md" was allowed — no onExcluded callback fired.
+    ]);
+  });
+
+  it("does not fire onExcluded for paths outside syncRoot (defensive)", () => {
+    const calls: Array<{ rel: string; id: string }> = [];
+    const wrapped = wrapFilterWithPersonalVaultDefaults(
+      () => true,
+      syncRoot,
+      (rel, match) => calls.push({ rel, id: match.id }),
+    );
+
+    // Outside-syncRoot paths come back with a `..` prefix from path.relative;
+    // the wrapper defers (returns true) without consulting the exclusion
+    // list since "outside scope" is the upstream containment check's job.
+    expect(wrapped("/tmp/other/.env")).toBe(true);
+    expect(calls).toEqual([]);
+  });
+});

package/src/personal-vault-exclusions.ts

@@ -0,0 +1,277 @@
+/**
+ * Personal-vault default exclusions — second-tier scope filter that complements
+ * `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL` (`.git`, `companies`, `repos`,
+ * `workspace`) in `./personal-vault.ts`.
+ *
+ * Where the top-level constant filters the four big buckets at scope root, this
+ * file filters categories of nested files that ride along with an HQ install
+ * but have no business round-tripping to a personal vault — regardless of
+ * where they sit in the tree:
+ *
+ *   1. Secrets at root or nested. `.env`, `.env.local`, `.env.<anything>`,
+ *      `.mcp.json`. Pre-fix these were being uploaded if the user hadn't
+ *      added `.env` to their `.hqignore` (the default starter `.hqignore`
+ *      only listed `companies/*\/settings/`).
+ *
+ *   2. Machine-local state. `.beads/` (SQLite issue-tracker + WAL/SHM),
+ *      `.obsidian/`, `.vercel/`, `.cache_*`. Per-machine layouts/caches;
+ *      multi-device sync either corrupts (SQLite WAL) or causes spurious
+ *      churn (caches regenerate on demand).
+ *
+ *   3. Update-flow scratch. `output/`, `_legacy-*` directories. Created by
+ *      `/update-hq` / `/promote-hq-core` workflows as checkout scratch;
+ *      naming themselves "legacy" / sitting under "output" is a self-
+ *      declared "do not preserve" signal.
+ *
+ *   4. Pre-5.24 conflict mirror dir. `.hq-conflicts/` is a directory of
+ *      mirror copies from older sync runs (sibling to the now-fixed
+ *      `.conflict-YYYY-MM-DDTHH-MM-SSZ-{hash}.{ext}` ephemeral files
+ *      handled by `EPHEMERAL_PATH_PATTERN` in share.ts). Same logic
+ *      applies: these are local-only safety backups.
+ *
+ *   5. OS / build cruft. `.DS_Store`, `node_modules/`, `dist/`, `.next/`,
+ *      `build/`. Universally noise inside HQ (personal scope should not
+ *      contain code projects, but defense-in-depth catches anyone who
+ *      symlinks a project subtree in).
+ *
+ * Policy: refuse + warn (5.25 default). The walk filter drops these so they
+ * never upload; the delete-plan walker uses the same filter so already-
+ * journaled entries that match a new exclusion get orphaned in the journal
+ * (no DELETE issued, no churn). A one-shot purge script handles the cleanup
+ * of objects that landed on remote before this version.
+ *
+ * Application scope: personal vault only. Company vaults have separate
+ * first-push protection (settings/, data/, workers/, .git/ exclusion in
+ * `src-tauri/src/util/ignore.rs`) and may legitimately ship `output/` or
+ * `.env*` paths inside their data folders. Wired in `share.ts` only when
+ * `options.personalMode === true`.
+ *
+ * Wire-points (parallel to `EPHEMERAL_PATH_PATTERN`):
+ *   - `collectFiles` / `walkDir` (push) — wrap `shouldSync` so excluded
+ *     relative paths are rejected before upload.
+ *   - `computeDeletePlan` (delete) — same `shouldSync` wrap, so journal
+ *     entries matching an exclusion are skipped on the delete pass too.
+ */
+
+import * as path from "path";
+
+/**
+ * Each entry is matched against the relative path from the personal-vault
+ * sync root (which IS hq_root in personalMode), using forward-slash
+ * separators. Patterns:
+ *
+ *   - `prefix:foo/`   — match if the path starts with `foo/` or equals `foo`
+ *                       (handles both the dir itself and any descendant)
+ *   - `basename:.env` — match if any path segment equals `.env`
+ *   - `basename:.env-prefix:.env.` — match if the basename starts with `.env.`
+ *   - `segment:node_modules` — match if any path segment equals literally
+ *
+ * The literal-segment form catches nested cases (e.g., `repos/foo/node_modules/`
+ * is already excluded by top-level repos/ skip, but `personal/x/node_modules/`
+ * would slip through without segment matching).
+ */
+export interface PersonalVaultExclusion {
+  /** Internal id for telemetry / explainability in events. */
+  id: string;
+  /** Human-readable category for the warning event. */
+  category:
+    | "secret"
+    | "machine-local"
+    | "scratch"
+    | "conflict-mirror"
+    | "os-cruft"
+    | "build-output";
+  /**
+   * Predicate. Pure: relative path (forward-slash separated, no leading slash)
+   * + optional isDir hint. Returns true to EXCLUDE.
+   */
+  test: (relPath: string, isDir?: boolean) => boolean;
+  /** Doc-only — shown alongside `id` in the warning event sample. */
+  pattern: string;
+}
+
+/**
+ * Cheap segment-equality check. Avoids allocating a regex per call.
+ */
+function hasSegment(relPath: string, segment: string): boolean {
+  if (relPath === segment) return true;
+  if (relPath.startsWith(`${segment}/`)) return true;
+  return relPath.includes(`/${segment}/`) || relPath.endsWith(`/${segment}`);
+}
+
+function basename(relPath: string): string {
+  const i = relPath.lastIndexOf("/");
+  return i === -1 ? relPath : relPath.slice(i + 1);
+}
+
+export const PERSONAL_VAULT_DEFAULT_EXCLUSIONS: readonly PersonalVaultExclusion[] = [
+  // ── secrets ───────────────────────────────────────────────────────────
+  {
+    id: "env-file",
+    category: "secret",
+    pattern: "**/.env, **/.env.*",
+    test: (p) => {
+      const b = basename(p);
+      return b === ".env" || b.startsWith(".env.");
+    },
+  },
+  {
+    id: "mcp-config",
+    category: "secret",
+    pattern: "**/.mcp.json",
+    test: (p) => basename(p) === ".mcp.json",
+  },
+  // ── machine-local tooling state ───────────────────────────────────────
+  {
+    id: "beads-db",
+    category: "machine-local",
+    pattern: "**/.beads/**",
+    test: (p) => hasSegment(p, ".beads"),
+  },
+  {
+    id: "obsidian-workspace",
+    category: "machine-local",
+    pattern: "**/.obsidian/**",
+    test: (p) => hasSegment(p, ".obsidian"),
+  },
+  {
+    id: "vercel-link",
+    category: "machine-local",
+    pattern: "**/.vercel/**",
+    test: (p) => hasSegment(p, ".vercel"),
+  },
+  {
+    id: "cache-dir",
+    category: "machine-local",
+    pattern: "**/.cache_*",
+    test: (p) => basename(p).startsWith(".cache_"),
+  },
+  // ── update-flow scratch ───────────────────────────────────────────────
+  {
+    id: "update-output",
+    category: "scratch",
+    pattern: "**/output/**",
+    test: (p) => hasSegment(p, "output"),
+  },
+  {
+    id: "legacy-dir",
+    category: "scratch",
+    pattern: "**/_legacy-*/**",
+    test: (p) => {
+      // Match any segment that starts with `_legacy-` or `_legacy_` or equals `_legacy`.
+      const segs = p.split("/");
+      return segs.some(
+        (s) => s === "_legacy" || s.startsWith("_legacy-") || s.startsWith("_legacy_"),
+      );
+    },
+  },
+  // ── pre-5.24 conflict mirror directory ────────────────────────────────
+  // Sibling to EPHEMERAL_PATH_PATTERN (handles the .conflict-<iso>-<hash>.ext
+  // file form). This handles the older directory form some HQ installs
+  // accumulated.
+  {
+    id: "hq-conflicts-dir",
+    category: "conflict-mirror",
+    pattern: "**/.hq-conflicts/**",
+    test: (p) => hasSegment(p, ".hq-conflicts"),
+  },
+  // ── OS / build cruft ──────────────────────────────────────────────────
+  {
+    id: "ds-store",
+    category: "os-cruft",
+    pattern: "**/.DS_Store",
+    test: (p) => basename(p) === ".DS_Store",
+  },
+  {
+    id: "node-modules",
+    category: "build-output",
+    pattern: "**/node_modules/**",
+    test: (p) => hasSegment(p, "node_modules"),
+  },
+  {
+    id: "dist-dir",
+    category: "build-output",
+    pattern: "**/dist/**",
+    test: (p) => hasSegment(p, "dist"),
+  },
+  {
+    id: "next-dir",
+    category: "build-output",
+    pattern: "**/.next/**",
+    test: (p) => hasSegment(p, ".next"),
+  },
+  {
+    id: "build-dir",
+    category: "build-output",
+    pattern: "**/build/**",
+    test: (p) => hasSegment(p, "build"),
+  },
+];
+
+/**
+ * First-match result for a path. Returns the matching exclusion (so callers
+ * can surface category/id in events) or undefined for "not excluded".
+ */
+export function matchPersonalVaultExclusion(
+  relPath: string,
+  isDir?: boolean,
+): PersonalVaultExclusion | undefined {
+  for (const ex of PERSONAL_VAULT_DEFAULT_EXCLUSIONS) {
+    if (ex.test(relPath, isDir)) return ex;
+  }
+  return undefined;
+}
+
+/**
+ * Boolean version — true if any exclusion matches.
+ */
+export function isPersonalVaultExcluded(relPath: string, isDir?: boolean): boolean {
+  return matchPersonalVaultExclusion(relPath, isDir) !== undefined;
+}
+
+/**
+ * Wrap an existing path filter (typically from `createIgnoreFilter`) with the
+ * personal-vault default exclusions. The wrapper:
+ *
+ *   1. Calls the underlying filter first; if it already rejects, defer
+ *      (counter does not fire — we only want to count things the underlying
+ *      filter would have allowed but the personal-vault defaults reject).
+ *   2. Computes a relative path from `syncRoot` (the personal-vault sync
+ *      root, which is hq_root in personalMode).
+ *   3. Probes `matchPersonalVaultExclusion`; if it matches, returns false
+ *      and tags the match via `onExcluded` so the runner can emit a single
+ *      `personal-vault-out-of-policy` event with a count + sample at end of
+ *      run.
+ *
+ * The wrapper keeps the `(absolutePath, isDir) => boolean` shape the existing
+ * collectFiles / walkDir / computeDeletePlan code already uses, so wiring is
+ * a single line change at the share() filter construction site.
+ */
+export function wrapFilterWithPersonalVaultDefaults(
+  underlying: (absPath: string, isDir?: boolean) => boolean,
+  syncRoot: string,
+  onExcluded: (relPath: string, match: PersonalVaultExclusion) => void,
+): (absPath: string, isDir?: boolean) => boolean {
+  return (absPath: string, isDir?: boolean) => {
+    if (!underlying(absPath, isDir)) return false;
+    const rel = path.relative(syncRoot, absPath).split(path.sep).join("/");
+    if (rel === "" || rel.startsWith("..")) return true; // outside scope, defer
+    const match = matchPersonalVaultExclusion(rel, isDir);
+    if (match) {
+      onExcluded(rel, match);
+      return false;
+    }
+    return true;
+  };
+}
+
+/**
+ * Test-only export. Mirrors the `_testing` namespace pattern used by
+ * `share.ts` for `EPHEMERAL_PATH_PATTERN` — direct access to the list +
+ * internal helpers for regression-critical pinning without round-tripping
+ * through share().
+ */
+export const _testing = {
+  hasSegment,
+  basename,
+};

package/src/sync/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @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 } from "./push-transport.js";
+export type { PushTransport } from "./push-transport.js";