@indigoai-us/hq-cloud 5.1.10 → 5.1.11

package/src/cli/share.test.ts

@@ -198,4 +198,146 @@ describe("share", () => {
 
     expect(result.filesUploaded).toBe(1);
   });
+
+  it("skipUnchanged=true skips files whose local hash matches the journal", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "unchanged.md");
+    fs.writeFileSync(testFile, "stable content");
+
+    // Precompute the hash of the file so the journal matches exactly.
+    const { hashFile } = await import("../journal.js");
+    const hash = hashFile(testFile);
+
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "unchanged.md": {
+            hash,
+            size: 15,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+    });
+
+    expect(result.filesUploaded).toBe(0);
+    expect(result.filesSkipped).toBe(1);
+    expect(uploadFile).not.toHaveBeenCalled();
+  });
+
+  it("skipUnchanged=true still uploads files whose hash differs from the journal", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "changed.md");
+    fs.writeFileSync(testFile, "new content");
+
+    // Journal has a stale hash for this path — simulating "local has been
+    // edited since the last push".
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "changed.md": {
+            hash: "stale-hash-from-previous-sync",
+            size: 10,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+    });
+
+    expect(result.filesUploaded).toBe(1);
+    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "changed.md");
+  });
+
+  it("skipUnchanged=false (default) uploads even when hash matches", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "unchanged.md");
+    fs.writeFileSync(testFile, "stable content");
+
+    const { hashFile } = await import("../journal.js");
+    const hash = hashFile(testFile);
+
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "unchanged.md": {
+            hash,
+            size: 15,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      // skipUnchanged omitted — preserves `hq share <file>` semantics
+    });
+
+    expect(result.filesUploaded).toBe(1);
+    expect(uploadFile).toHaveBeenCalled();
+  });
+
+  it("onEvent receives progress events instead of console output", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "a.md"), "aaa");
+    fs.writeFileSync(path.join(companyRoot, "b.md"), "bbb");
+
+    const events: Array<{ type: string; path: string; bytes?: number }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => {
+        events.push({
+          type: e.type,
+          path: e.path,
+          ...(e.type === "progress" ? { bytes: e.bytes } : {}),
+        });
+      },
+    });
+
+    expect(result.filesUploaded).toBe(2);
+    expect(events).toHaveLength(2);
+    expect(events.every((e) => e.type === "progress")).toBe(true);
+    expect(events.map((e) => e.path).sort()).toEqual(["a.md", "b.md"]);
+  });
 });

package/src/cli/share.ts

@@ -14,6 +14,7 @@ import { readJournal, writeJournal, hashFile, updateEntry } from "../journal.js"
 import { createIgnoreFilter, isWithinSizeLimit } from "../ignore.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
+import type { SyncProgressEvent } from "./sync.js";
 
 export interface ShareOptions {
   /** Path(s) to share (files or directories) */
@@ -28,6 +29,23 @@ export interface ShareOptions {
   vaultConfig: VaultServiceConfig;
   /** HQ root directory */
   hqRoot: string;
+  /**
+   * Per-file event callback. When present, suppresses the default
+   * `console.log`/`console.error` human output — same contract as `sync()`.
+   * This is the seam `hq-sync-runner` uses to stream ndjson for push events.
+   */
+  onEvent?: (event: SyncProgressEvent) => void;
+  /**
+   * When true, files whose local hash matches the journal entry from the
+   * last sync are skipped (no remote HEAD, no upload). This is the gate
+   * that makes "push everything that changed" efficient — without it, a
+   * bidirectional Sync Now would re-upload every file each tick.
+   *
+   * Default false to preserve `hq share <file>` semantics: when a user
+   * explicitly names a file, they expect it to be sent even if the local
+   * hash matches the last-sync state (e.g. to re-heal a bucket).
+   */
+  skipUnchanged?: boolean;
 }
 
 export interface ShareResult {
@@ -41,7 +59,8 @@ export interface ShareResult {
  * Share local file(s) to the entity vault.
  */
 export async function share(options: ShareOptions): Promise<ShareResult> {
-  const { paths, company, message, onConflict, vaultConfig, hqRoot } = options;
+  const { paths, company, message, onConflict, vaultConfig, hqRoot, skipUnchanged } = options;
+  const emit = options.onEvent ?? defaultConsoleLogger;
 
   // Resolve company — slug, UID, or from active config
   const companyRef = company ?? resolveActiveCompany(hqRoot);
@@ -70,11 +89,28 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
   for (const { absolutePath, relativePath } of filesToShare) {
     if (!isWithinSizeLimit(absolutePath)) {
-      console.error(`  Skipped (too large): ${relativePath}`);
+      emit({
+        type: "error",
+        path: relativePath,
+        message: "file exceeds size limit",
+      });
       filesSkipped++;
       continue;
     }
 
+    // Skip-if-unchanged gate: the hot path for bidirectional Sync Now. When
+    // walking an entire company folder, this is what keeps us from re-uploading
+    // every file every tick. Off by default so `hq share <file>` keeps its
+    // explicit-intent semantics (user named it, user wants it sent).
+    const localHash = hashFile(absolutePath);
+    if (skipUnchanged) {
+      const existing = journal.files[relativePath];
+      if (existing && existing.hash === localHash) {
+        filesSkipped++;
+        continue;
+      }
+    }
+
     // Auto-refresh context if credentials expiring
     if (isExpiringSoon(ctx.expiresAt)) {
       ctx = await refreshEntityContext(companyRef, vaultConfig);
@@ -84,7 +120,6 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     const remoteMeta = await headRemoteFile(ctx, relativePath);
     if (remoteMeta) {
       const journalEntry = journal.files[relativePath];
-      const localHash = hashFile(absolutePath);
 
       // If remote has changed since our last sync, it's a conflict
       if (journalEntry && journalEntry.hash !== localHash) {
@@ -113,12 +148,11 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // Upload
     try {
       const stat = fs.statSync(absolutePath);
-      const hash = hashFile(absolutePath);
 
       await uploadFile(ctx, absolutePath, relativePath);
 
       // Update journal with optional message
-      updateEntry(journal, relativePath, hash, stat.size, "up");
+      updateEntry(journal, relativePath, localHash, stat.size, "up");
       if (message) {
         journal.files[relativePath] = {
           ...journal.files[relativePath],
@@ -128,11 +162,18 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
       filesUploaded++;
       bytesUploaded += stat.size;
-      console.log(`  ✓ ${relativePath}`);
+      emit({
+        type: "progress",
+        path: relativePath,
+        bytes: stat.size,
+        ...(message ? { message } : {}),
+      });
     } catch (err) {
-      console.error(
-        `  ✗ ${relativePath} — ${err instanceof Error ? err.message : err}`,
-      );
+      emit({
+        type: "error",
+        path: relativePath,
+        message: err instanceof Error ? err.message : String(err),
+      });
     }
   }
 
@@ -141,6 +182,22 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   return { filesUploaded, bytesUploaded, filesSkipped, aborted: false };
 }
 
+/**
+ * Default human-readable share output. Preserves the exact format the CLI
+ * emitted before `onEvent` was added — tty users see no change.
+ */
+function defaultConsoleLogger(event: SyncProgressEvent): void {
+  if (event.type === "progress") {
+    if (event.message) {
+      console.log(`  ✓ ${event.path} — "${event.message}"`);
+    } else {
+      console.log(`  ✓ ${event.path}`);
+    }
+  } else {
+    console.error(`  ✗ ${event.path} — ${event.message}`);
+  }
+}
+
 /**
  * Resolve active company from .hq/config.json or parent directory chain.
  */

package/src/vault-client.test.ts

@@ -560,4 +560,64 @@ describe("VaultClient identity bootstrap", () => {
     const body = JSON.parse(init.body as string);
     expect(body.slug).toBe("user-12345678");
   });
+
+  it("listByType_roundtrips_createdAt", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          {
+            uid: "prs_x",
+            slug: "alice",
+            type: "person",
+            status: "active",
+            createdAt: "2026-01-01T00:00:00Z",
+          },
+        ],
+      }),
+    );
+
+    const entities = await client.entity.listByType("person");
+    expect(entities).toHaveLength(1);
+    expect(entities[0].createdAt).toBe("2026-01-01T00:00:00Z");
+  });
+
+  it("ensureMyPersonEntity_picks_oldest_when_multiple", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          { uid: "prs_b", slug: "b", type: "person", status: "active", createdAt: "2026-03-01T00:00:00Z" },
+          { uid: "prs_a", slug: "a", type: "person", status: "active", createdAt: "2026-01-01T00:00:00Z" },
+          { uid: "prs_c", slug: "c", type: "person", status: "active", createdAt: "2026-06-01T00:00:00Z" },
+        ],
+      }),
+    );
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub: "sub-multi",
+      displayName: "Multi User",
+    });
+
+    expect(person.uid).toBe("prs_a");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("ensureMyPersonEntity_handles_missing_createdAt_deterministically", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          { uid: "prs_z", slug: "z", type: "person", status: "active" },
+          { uid: "prs_a", slug: "a", type: "person", status: "active" },
+        ],
+      }),
+    );
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub: "sub-nodates",
+      displayName: "No Dates User",
+    });
+
+    // Both missing createdAt → "" tie, uid tiebreak selects prs_a
+    expect(person.uid).toBe("prs_a");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
 });

package/src/vault-client.ts

@@ -109,6 +109,7 @@ export interface EntityInfo {
   name?: string;
   bucketName?: string;
   status: string;
+  createdAt: string;
 }
 
 export interface PendingInviteByEmail {
@@ -343,7 +344,13 @@ export class VaultClient {
     displayName: string;
   }): Promise<EntityInfo> {
     const existing = await this.entity.listByType("person");
-    if (existing.length > 0) return existing[0];
+    const sorted = [...existing].sort((a, b) => {
+      const ac = (a.createdAt as string | undefined) ?? "";
+      const bc = (b.createdAt as string | undefined) ?? "";
+      if (ac !== bc) return ac < bc ? -1 : 1;
+      return a.uid < b.uid ? -1 : 1;
+    });
+    if (sorted.length > 0) return sorted[0];
 
     const slug =
       hints.displayName