@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/sync-core.ts

@@ -1,58 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { normalizeEtag } from "./journal.js";
-
-/**
- * Is this error the S3/STS "access denied" class? Expected when a scoped
- * member/guest credential touches a key outside its granted ACL prefixes
- * (the server's `SCOPE_EXCEEDS_PARENT` surfaces as a 403 AccessDenied /
- * Forbidden).
- */
-export function isAccessDenied(err: unknown): boolean {
-  if (err && typeof err === "object" && "name" in err) {
-    const name = (err as { name?: unknown }).name;
-    return name === "AccessDenied" || name === "Forbidden";
-  }
-  return false;
-}
-
-export function resolveTransferConcurrency(): number {
-  const raw = process.env.HQ_SYNC_TRANSFER_CONCURRENCY;
-  if (raw === undefined || raw === "") return 16;
-  const parsed = Number.parseInt(raw, 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : 16;
-}
-
-/**
- * Resolve active company from .hq/config.json.
- */
-export function resolveActiveCompany(hqRoot: string): string | undefined {
-  const configPath = path.join(hqRoot, ".hq", "config.json");
-  if (fs.existsSync(configPath)) {
-    try {
-      const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-      return config.activeCompany ?? config.companySlug;
-    } catch {
-      // Ignore parse errors
-    }
-  }
-  return undefined;
-}
-
-/**
- * Returns true when the remote object appears to have moved since the
- * journal entry's last-recorded sync. Prefers ETag equality; falls back to
- * `lastModified > syncedAt` for legacy entries written before remoteEtag
- * was tracked. Conservative on tie (`<=` skews "remote unchanged") so an
- * S3-side mtime that exactly equals our syncedAt is not treated as drift.
- */
-export function hasRemoteChanged(
-  remote: { lastModified: Date; etag: string },
-  entry: { syncedAt: string; remoteEtag?: string },
-): boolean {
-  if (entry.remoteEtag) {
-    return normalizeEtag(remote.etag) !== entry.remoteEtag;
-  }
-  const syncedAt = new Date(entry.syncedAt).getTime();
-  return remote.lastModified.getTime() > syncedAt;
-}

package/src/sync-progress.test.ts

@@ -1,94 +0,0 @@
-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("writes an initial syncing snapshot on creation, before any event", () => {
-    // The menubar must show the sync as active the moment it initialises —
-    // before the remote listing/planning that produces the first `plan` event.
-    createSyncProgressRecorder({ company: "acme", phase: "pull" });
-    const snap = readSyncProgress();
-    expect(snap).not.toBeNull();
-    expect(snap!.status).toBe("syncing");
-    expect(snap!.company).toBe("acme");
-    expect(snap!.phase).toBe("pull");
-    expect(snap!.filesTotal).toBe(0);
-    expect(snap!.filesDone).toBe(0);
-  });
-
-  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

@@ -1,140 +0,0 @@
-/**
- * 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.
-    }
-  };
-
-  // Write an initial "syncing" snapshot the moment the recorder is created —
-  // i.e. as the sync initialises, BEFORE the (potentially slow) entity-context
-  // resolution, remote listing, and journal read/planning that produce the
-  // first `plan` event. Without this the file — and the menubar's "syncing"
-  // state — only appeared after planning, so a long remote listing looked idle.
-  flush();
-
-  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;
-  }
-}

package/src/telemetry-events.test.ts

@@ -1,88 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import {
-  emitCloudTelemetry,
-  type CloudTelemetryClient,
-  type TelemetryEvent,
-} from "./telemetry-events.js";
-import type { TelemetryEventsBatch } from "./vault-client.js";
-
-describe("emitCloudTelemetry", () => {
-  it("is best-effort, stamps metadata, caps batches, and sanitizes properties", async () => {
-    const posts: TelemetryEventsBatch[] = [];
-    const client: CloudTelemetryClient = {
-      postTelemetryEvents: vi.fn(async (batch) => {
-        posts.push(batch);
-        throw new Error("vault unavailable");
-      }),
-    };
-    const logs: string[] = [];
-    const events: TelemetryEvent[] = Array.from({ length: 55 }, (_, i) => ({
-      eventName: `sync_completed_${i}`,
-      source: "hq-sync",
-      companyUid: "cmp_abc",
-      sessionId: "sync_123",
-      properties:
-        i === 0
-          ? ({
-              fileCount: 2,
-              result: "success",
-              companyUid: "cmp_abc",
-              labels: ["completed", "has spaces", "cmp_abc"],
-              path: "/Users/alice/company/secret.md",
-              filename: "secret.md",
-              secretToken: "tok_123",
-              message: "free text should not leave the process",
-              unsafeLabel: "contains spaces",
-              nanCount: Number.NaN,
-              enabled: true,
-              nested: { value: "nope" },
-              "bad-key": "nope",
-            } as unknown as TelemetryEvent["properties"])
-          : { fileCount: i },
-    }));
-
-    await expect(
-      emitCloudTelemetry(client, events, {
-        claims: {
-          "custom:entityType": "agent",
-          "custom:entityUid": "agt_runner",
-        },
-        timeoutMs: 25,
-        log: (message) => logs.push(message),
-      }),
-    ).resolves.toBeUndefined();
-
-    expect(client.postTelemetryEvents).toHaveBeenCalledTimes(1);
-    expect(client.postTelemetryEvents).toHaveBeenCalledWith(
-      { events: expect.any(Array) },
-      { timeoutMs: 25 },
-    );
-    expect(posts).toHaveLength(1);
-    expect(posts[0].events).toHaveLength(50);
-
-    const first = posts[0].events[0];
-    expect(first).toMatchObject({
-      eventName: "sync_completed_0",
-      app: "hq-cloud",
-      source: "hq-sync",
-      companyUid: "cmp_abc",
-      agentUid: "agt_runner",
-      sessionId: "sync_123",
-      schemaVersion: 1,
-      properties: {
-        fileCount: 2,
-        result: "success",
-        companyUid: "cmp_abc",
-        labels: ["completed", "cmp_abc"],
-      },
-    });
-    expect(Number.isNaN(Date.parse(first.occurredAt))).toBe(false);
-    expect(JSON.stringify(posts[0])).not.toContain("personUid");
-    expect(JSON.stringify(posts[0])).not.toContain("/Users/alice");
-    expect(JSON.stringify(posts[0])).not.toContain("secret.md");
-    expect(JSON.stringify(posts[0])).not.toContain("free text");
-    expect(JSON.stringify(posts[0])).not.toContain("tok_123");
-    expect(logs.join("\n")).toContain("postTelemetryEvents failed");
-  });
-});

package/src/telemetry-events.ts

@@ -1,205 +0,0 @@
-import type {
-  TelemetryEventsBatch,
-  TelemetryEventsIngestResult,
-} from "./vault-client.js";
-
-const MAX_EVENTS_PER_BATCH = 50;
-const DEFAULT_TIMEOUT_MS = 1500;
-const MAX_PROPERTIES = 40;
-const MAX_ARRAY_VALUES = 20;
-
-type TelemetryPrimitive = string | number;
-export type TelemetryProperties = Record<
-  string,
-  TelemetryPrimitive | TelemetryPrimitive[] | null | undefined
->;
-
-export interface TelemetryEvent {
-  eventName: string;
-  source: string;
-  occurredAt?: string;
-  companyUid?: string;
-  agentUid?: string;
-  sessionId?: string;
-  schemaVersion?: 1;
-  properties?: TelemetryProperties;
-}
-
-export interface TelemetryClaims {
-  "custom:entityType"?: unknown;
-  "custom:entityUid"?: unknown;
-}
-
-export interface CloudTelemetryClient {
-  postTelemetryEvents?: (
-    batch: TelemetryEventsBatch,
-    options?: { timeoutMs?: number },
-  ) => Promise<TelemetryEventsIngestResult>;
-}
-
-export interface EmitCloudTelemetryOptions {
-  claims?: TelemetryClaims | null;
-  timeoutMs?: number;
-  log?: (message: string) => void;
-}
-
-const SAFE_KEY = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
-const SAFE_LABEL = /^[A-Za-z0-9._:-]{1,128}$/;
-const BLOCKED_STRING_PROPERTY_KEY =
-  /(path|filename|name|email|secret|token|text|message|prompt|body|content|cwd|dir|url|uri|prefix|link)/i;
-
-export function agentUidFromClaims(
-  claims: TelemetryClaims | null | undefined,
-): string | undefined {
-  if (
-    claims?.["custom:entityType"] === "agent" &&
-    typeof claims["custom:entityUid"] === "string" &&
-    claims["custom:entityUid"].startsWith("agt_")
-  ) {
-    return claims["custom:entityUid"];
-  }
-  return undefined;
-}
-
-export async function emitCloudTelemetry(
-  client: CloudTelemetryClient | null | undefined,
-  events: TelemetryEvent | TelemetryEvent[],
-  options: EmitCloudTelemetryOptions = {},
-): Promise<void> {
-  if (!client?.postTelemetryEvents) return;
-
-  const derivedAgentUid = agentUidFromClaims(options.claims);
-  const now = new Date().toISOString();
-  const sanitized = (Array.isArray(events) ? events : [events])
-    .slice(0, MAX_EVENTS_PER_BATCH)
-    .map((event) => sanitizeEvent(event, now, derivedAgentUid))
-    .filter((event): event is TelemetryEventsBatch["events"][number] => event !== null);
-
-  if (sanitized.length === 0) return;
-
-  const timeoutMs = normalizeTimeout(options.timeoutMs);
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  const timeoutPromise = new Promise<never>((_, reject) => {
-    timeout = setTimeout(
-      () => reject(new Error(`telemetry events timed out after ${timeoutMs}ms`)),
-      timeoutMs,
-    );
-    timeout.unref?.();
-  });
-
-  const postPromise = client
-    .postTelemetryEvents({ events: sanitized }, { timeoutMs })
-    .catch((err) => {
-      throw err;
-    });
-  postPromise.catch(() => undefined);
-
-  try {
-    await Promise.race([postPromise, timeoutPromise]);
-  } catch (err) {
-    warn(options.log, `postTelemetryEvents failed (${describeError(err)})`);
-  } finally {
-    if (timeout !== undefined) clearTimeout(timeout);
-  }
-}
-
-function sanitizeEvent(
-  event: TelemetryEvent,
-  fallbackOccurredAt: string,
-  derivedAgentUid: string | undefined,
-): TelemetryEventsBatch["events"][number] | null {
-  const eventName = safeLabel(event.eventName);
-  const source = safeLabel(event.source);
-  if (!eventName || !source) return null;
-
-  const occurredAt = safeIso(event.occurredAt) ?? fallbackOccurredAt;
-  const properties = sanitizeProperties(event.properties);
-  const companyUid = safeLabel(event.companyUid);
-  const agentUid = safeLabel(event.agentUid) ?? derivedAgentUid;
-  const sessionId = safeLabel(event.sessionId);
-
-  return {
-    eventName,
-    app: "hq-cloud",
-    source,
-    occurredAt,
-    ...(companyUid ? { companyUid } : {}),
-    ...(agentUid ? { agentUid } : {}),
-    ...(sessionId ? { sessionId } : {}),
-    schemaVersion: 1,
-    ...(properties ? { properties } : {}),
-  };
-}
-
-function sanitizeProperties(
-  properties: TelemetryProperties | undefined,
-): Record<string, unknown> | undefined {
-  if (!properties) return undefined;
-  const out: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(properties)) {
-    if (Object.keys(out).length >= MAX_PROPERTIES) break;
-    if (!SAFE_KEY.test(key)) continue;
-    const sanitized = sanitizePropertyValue(key, value);
-    if (sanitized !== undefined) out[key] = sanitized;
-  }
-  return Object.keys(out).length > 0 ? out : undefined;
-}
-
-function sanitizePropertyValue(
-  key: string,
-  value: unknown,
-): TelemetryPrimitive | TelemetryPrimitive[] | undefined {
-  if (value === null || value === undefined) return undefined;
-  if (Array.isArray(value)) {
-    const values = value
-      .slice(0, MAX_ARRAY_VALUES)
-      .map((item) => sanitizeScalar(key, item))
-      .filter((item): item is TelemetryPrimitive => item !== undefined);
-    return values.length > 0 ? values : undefined;
-  }
-  return sanitizeScalar(key, value);
-}
-
-function sanitizeScalar(
-  key: string,
-  value: unknown,
-): TelemetryPrimitive | undefined {
-  if (typeof value === "number") {
-    return Number.isFinite(value) ? value : undefined;
-  }
-  if (typeof value !== "string") return undefined;
-  if (BLOCKED_STRING_PROPERTY_KEY.test(key)) return undefined;
-  return safeLabel(value);
-}
-
-function safeLabel(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  if (!SAFE_LABEL.test(trimmed)) return undefined;
-  return trimmed;
-}
-
-function safeIso(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : undefined;
-}
-
-function normalizeTimeout(value: number | undefined): number {
-  if (value !== undefined && Number.isFinite(value) && value > 0) {
-    return Math.trunc(value);
-  }
-  return DEFAULT_TIMEOUT_MS;
-}
-
-function warn(log: ((message: string) => void) | undefined, message: string): void {
-  try {
-    (log ?? console.warn)(`[telemetry-events] ${message}`);
-  } catch {
-    /* diagnostics must never affect the caller */
-  }
-}
-
-function describeError(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}