@indigoai-us/hq-cloud 6.11.13 → 6.11.15

package/src/index.ts

@@ -57,6 +57,15 @@ export {
 
 export type { JournalSummary } from "./journal.js";
 
+// Cross-process sync progress — every sync path writes one shared snapshot so
+// a watcher (the hq-sync menubar) can show live progress for ANY sync.
+export {
+  createSyncProgressRecorder,
+  readSyncProgress,
+  syncProgressPath,
+} from "./sync-progress.js";
+export type { SyncProgressSnapshot } from "./sync-progress.js";
+
 // Prefix coalescing helper (US-005)
 export {
   coalescePrefixes,

package/src/qmd-reindex.ts

@@ -56,6 +56,13 @@ export interface ReindexOptions {
   readCompanies?: (companiesDir: string) => string[];
   /** Returns true if the knowledge dir has at least one indexable .md file. */
   hasIndexableMarkdown?: (knowledgeDir: string) => boolean;
+  /** Optional diagnostic sink for unexpected swallowed failures. */
+  log?: (diagnostic: {
+    event: string;
+    message: string;
+    err: unknown;
+    context?: Record<string, unknown>;
+  }) => void;
 }
 
 /**
@@ -110,7 +117,17 @@ export function reindexAfterSync(
       const embed = exec(["embed"]);
       result.embedded = embed.status === 0;
     }
-  } catch {
+  } catch (err) {
+    try {
+      opts.log?.({
+        event: "runner.qmd_reindex.internal_failed",
+        message: "post-sync qmd reindex failed",
+        err,
+        context: { hqRoot },
+      });
+    } catch {
+      /* diagnostics must never affect sync */
+    }
     // Reindex is best-effort; the sync result is authoritative. Swallow.
   }
 

package/src/sync-progress.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import type { SyncProgressEvent } from "./cli/sync.js";
+import {
+  createSyncProgressRecorder,
+  readSyncProgress,
+} from "./sync-progress.js";
+
+const planEvent = (download: number, upload: number, del: number): SyncProgressEvent =>
+  ({
+    type: "plan",
+    filesToDownload: download,
+    bytesToDownload: 0,
+    filesToUpload: upload,
+    bytesToUpload: 0,
+    filesToSkip: 0,
+    filesToConflict: 0,
+    filesToDelete: del,
+  }) as SyncProgressEvent;
+
+describe("sync-progress", () => {
+  let stateDir: string;
+  beforeEach(() => {
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-progress-test-"));
+    process.env.HQ_STATE_DIR = stateDir;
+  });
+  afterEach(() => {
+    delete process.env.HQ_STATE_DIR;
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  });
+
+  it("returns null when no sync has written a snapshot", () => {
+    expect(readSyncProgress()).toBeNull();
+  });
+
+  it("accumulates plan totals, progress, and conflicts into the shared snapshot", () => {
+    const record = createSyncProgressRecorder({ company: "acme", phase: "pull" });
+    record(planEvent(3, 0, 1)); // 3 to download + 1 to delete = 4 total
+    record({ type: "progress", path: "a.md", bytes: 10 } as SyncProgressEvent);
+    record({ type: "progress", path: "b.md", bytes: 10 } as SyncProgressEvent);
+    record({
+      type: "conflict",
+      path: "c.md",
+      direction: "pull",
+      resolution: "keep",
+    } as SyncProgressEvent);
+
+    const snap = readSyncProgress();
+    expect(snap).not.toBeNull();
+    expect(snap!.company).toBe("acme");
+    expect(snap!.phase).toBe("pull");
+    expect(snap!.filesTotal).toBe(4);
+    expect(snap!.filesDone).toBe(2);
+    expect(snap!.conflicts).toBe(1);
+    expect(snap!.currentFile).toBe("b.md");
+    expect(snap!.status).toBe("syncing");
+    expect(snap!.pid).toBe(process.pid);
+    expect(typeof snap!.updatedAt).toBe("string");
+  });
+
+  it("records the push leg + personal scope (company null)", () => {
+    const record = createSyncProgressRecorder({ company: null, phase: "push" });
+    record(planEvent(0, 5, 0));
+    const snap = readSyncProgress();
+    expect(snap!.phase).toBe("push");
+    expect(snap!.company).toBeNull();
+    expect(snap!.filesTotal).toBe(5);
+  });
+
+  it("ignores non-progress events (no churn from new-files/reconciled)", () => {
+    const record = createSyncProgressRecorder({ company: "acme", phase: "pull" });
+    record(planEvent(1, 0, 0));
+    record({ type: "new-files", files: [] } as SyncProgressEvent);
+    record({ type: "reconciled", path: "x.md", direction: "pull" } as SyncProgressEvent);
+    const snap = readSyncProgress();
+    expect(snap!.filesDone).toBe(0);
+    expect(snap!.filesTotal).toBe(1);
+  });
+});

package/src/sync-progress.ts

@@ -0,0 +1,133 @@
+/**
+ * Cross-process sync progress.
+ *
+ * Every sync path — the menubar watch daemon (auto-sync), "Sync Now", and a
+ * CLI `hq sync` — runs through the same engine (`sync()` pull + `share()`
+ * push). Each writes one shared status snapshot here so a watcher (the menubar)
+ * can show LIVE progress for ANY sync, not just the one it spawned over stdout.
+ *
+ * Because syncs are serialized (the op-lock; the watch daemon coordinates with
+ * one-shots), there is at most one active sync, so this single file is
+ * unambiguous. Writes are atomic (temp + rename) — a torn read at worst shows
+ * slightly stale progress. There is intentionally no explicit "done": the
+ * engine simply stops writing when a sync ends, so a consumer treats the file
+ * as idle once `updatedAt` is older than a few seconds. Progress reporting must
+ * never break a sync, so every fs error here is swallowed.
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import type { SyncProgressEvent } from "./cli/sync.js";
+
+/** Mirror operation-lock's stateDir so the file lands next to the journal/lock. */
+function stateDir(): string {
+  return process.env.HQ_STATE_DIR || path.join(os.homedir(), ".hq");
+}
+
+/** Absolute path of the shared progress snapshot. Exported for the watcher + tests. */
+export function syncProgressPath(): string {
+  return path.join(stateDir(), "sync-progress.json");
+}
+
+export interface SyncProgressSnapshot {
+  schema: 1;
+  /** PID of the writing sync — lets a watcher detect a dead/stale holder. */
+  pid: number;
+  /** Company slug being synced, or null for the personal vault. */
+  company: string | null;
+  /** Which leg is running. */
+  phase: "pull" | "push";
+  filesTotal: number;
+  filesDone: number;
+  conflicts: number;
+  /** Path of the file currently transferring, or null before the first one. */
+  currentFile: string | null;
+  startedAt: string;
+  updatedAt: string;
+  status: "syncing";
+}
+
+export interface SyncProgressRecorderOptions {
+  company?: string | null;
+  phase: "pull" | "push";
+}
+
+/**
+ * Build an event sink that accumulates a sync's progress and atomic-writes the
+ * shared snapshot on each meaningful event. Wrap the engine's `onEvent` with
+ * it: `const emit = (e) => { baseEmit(e); record(e); }`.
+ */
+export function createSyncProgressRecorder(
+  opts: SyncProgressRecorderOptions,
+): (event: SyncProgressEvent) => void {
+  let filesTotal = 0;
+  let filesDone = 0;
+  let conflicts = 0;
+  let currentFile: string | null = null;
+  const startedAt = new Date().toISOString();
+  const file = syncProgressPath();
+
+  const flush = (): void => {
+    const snap: SyncProgressSnapshot = {
+      schema: 1,
+      pid: process.pid,
+      company: opts.company ?? null,
+      phase: opts.phase,
+      filesTotal,
+      filesDone,
+      conflicts,
+      currentFile,
+      startedAt,
+      updatedAt: new Date().toISOString(),
+      status: "syncing",
+    };
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(snap));
+      fs.renameSync(tmp, file);
+    } catch {
+      // Progress reporting is best-effort and must never break a sync.
+    }
+  };
+
+  return (event: SyncProgressEvent): void => {
+    switch (event.type) {
+      case "plan":
+        // Sum the work this leg will do. `plan` arrives once before any
+        // progress events for the leg.
+        filesTotal +=
+          event.filesToDownload + event.filesToUpload + event.filesToDelete;
+        flush();
+        break;
+      case "progress":
+        filesDone += 1;
+        currentFile = event.path;
+        flush();
+        break;
+      case "conflict":
+        conflicts += 1;
+        flush();
+        break;
+      default:
+        // error / new-files / reconciled / delete-refused etc. don't move the
+        // bar — skip the write to keep the file churn-free.
+        break;
+    }
+  };
+}
+
+/**
+ * Read the current snapshot, or null if absent/unreadable. Consumers should
+ * additionally treat a snapshot whose `updatedAt` is older than a few seconds
+ * (or whose `pid` is dead) as idle.
+ */
+export function readSyncProgress(): SyncProgressSnapshot | null {
+  try {
+    const raw = fs.readFileSync(syncProgressPath(), "utf8");
+    const parsed = JSON.parse(raw) as SyncProgressSnapshot;
+    return parsed && parsed.schema === 1 ? parsed : null;
+  } catch {
+    return null;
+  }
+}