@indigoai-us/hq-cloud 6.2.1 → 6.2.2

package/src/cli/share.test.ts

@@ -39,7 +39,7 @@ vi.mock("readline", () => ({
 
 import * as readline from "readline";
 import { share, _testing as shareTesting } from "./share.js";
-import { deleteRemoteFile, headRemoteFile, uploadFile, uploadSymlink } from "../s3.js";
+import { deleteRemoteFile, downloadFile, headRemoteFile, uploadFile, uploadSymlink } from "../s3.js";
 import type { EntityContext } from "../types.js";
 
 const mockConfig: VaultServiceConfig = {
@@ -482,6 +482,110 @@ describe("share", () => {
     expect(result.filesUploaded).toBe(0);
   });
 
+  it("fresh-install multipart collision: byte-identical remote is NOT a conflict (reconciled, no mirror)", async () => {
+    // Root cause of "HQ installs with conflicts": on a first push the
+    // journal is empty, so the fresh-collision branch decides conflict-vs-
+    // identical from the remote etag alone. A multipart remote etag
+    // (\`<md5>-<partCount>\`) is NOT a content hash, so the OLD code assumed
+    // a collision for ANY multipart object — minting a false conflict for
+    // the most common fresh-install case: re-pushing a byte-identical
+    // core/ scaffold file whose remote copy happened to be multipart-
+    // uploaded. The fix fetches the remote bytes once and compares content
+    // hashes; identical content reconciles (journal re-stamped, PUT
+    // skipped) instead of producing a conflict + \`.conflict-*\` mirror.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "core-scaffold.md");
+    const scaffoldBytes = "identical-scaffold-content-shipped-to-every-user";
+    fs.writeFileSync(testFile, scaffoldBytes);
+
+    // Remote exists with a MULTIPART etag and NO journal entry (first push).
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"d41d8cd98f00b204e9800998ecf8427e-2"',
+      size: scaffoldBytes.length,
+    });
+    // The convergence probe downloads the remote bytes — which are
+    // byte-identical to local — so the content hashes match.
+    vi.mocked(downloadFile).mockImplementationOnce(async (_ctx, _key, dest) => {
+      fs.writeFileSync(dest as string, scaffoldBytes);
+      return undefined as never;
+    });
+
+    const events: unknown[] = [];
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onConflict: "keep",
+      onEvent: (e) => events.push(e),
+    });
+
+    // No conflict, no upload (bytes already there), counted as a skip.
+    expect(result.conflictPaths).toEqual([]);
+    expect(result.filesUploaded).toBe(0);
+    expect(result.filesSkipped).toBe(1);
+    const conflicts = events.filter(
+      (e) => typeof e === "object" && e !== null && (e as { type?: string }).type === "conflict",
+    );
+    expect(conflicts).toHaveLength(0);
+    const reconciled = events.filter(
+      (e) => typeof e === "object" && e !== null && (e as { type?: string }).type === "reconciled",
+    );
+    expect(reconciled).toHaveLength(1);
+    expect(reconciled[0]).toMatchObject({ path: "core-scaffold.md", direction: "push" });
+    // No conflict-mirror litter on disk.
+    const litter = fs
+      .readdirSync(companyRoot)
+      .filter((n) => n.includes(".conflict-"));
+    expect(litter).toEqual([]);
+    // Local file untouched.
+    expect(fs.readFileSync(testFile, "utf-8")).toBe(scaffoldBytes);
+  });
+
+  it("fresh-install multipart collision: genuinely different remote IS a conflict (Bug #7 preserved)", async () => {
+    // The convergence probe must not weaken Bug #7 protection: a multipart
+    // remote whose CONTENT actually differs from local is still a real
+    // fresh collision and must surface a conflict (so a peer's content
+    // isn't silently clobbered).
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "diverged-multipart.md");
+    fs.writeFileSync(testFile, "my-local-version");
+
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"0123456789abcdef0123456789abcdef-3"',
+      size: 32,
+    });
+    // The probe (and the subsequent keep-mirror download) return DIFFERENT
+    // remote bytes.
+    vi.mocked(downloadFile).mockImplementation(async (_ctx, _key, dest) => {
+      fs.writeFileSync(dest as string, "a-peers-different-version");
+      return undefined as never;
+    });
+
+    const events: unknown[] = [];
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onConflict: "keep",
+      onEvent: (e) => events.push(e),
+    });
+
+    expect(result.conflictPaths).toEqual(["diverged-multipart.md"]);
+    expect(result.filesUploaded).toBe(0);
+    const conflicts = events.filter(
+      (e) => typeof e === "object" && e !== null && (e as { type?: string }).type === "conflict",
+    );
+    expect(conflicts).toHaveLength(1);
+    // Local file untouched under keep.
+    expect(fs.readFileSync(testFile, "utf-8")).toBe("my-local-version");
+  });
+
   it("uploads (no conflict) when only the local side changed since last sync", async () => {
     // Regression for hq-cloud#<conflict-detection>: a local edit to a file
     // that exists on S3 used to trigger a push conflict because the

package/src/cli/share.ts

@@ -6,6 +6,7 @@
  */
 
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 import type { EntityContext, VaultServiceConfig, SyncJournal } from "../types.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
@@ -45,6 +46,59 @@ import {
 } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
 
+/**
+ * Push-side fresh-collision convergence probe.
+ *
+ * For a first push (no journal entry) where the remote object already
+ * exists AND was multipart-uploaded, the remote etag (`<md5>-<partCount>`)
+ * is not a content hash, so we cannot tell "byte-identical" from "genuine
+ * divergence" without looking at the bytes. Fetch the remote object once to
+ * a throwaway temp file, hash it the same symlink-aware way the planner
+ * hashed local, and report whether the two contents DIFFER.
+ *
+ * Returns `true` on a genuine difference (a real fresh collision) and
+ * `false` when the bytes are identical. Fails safe to `true` on any
+ * fetch/hash error — a false positive merely prompts the operator, while a
+ * false negative could silently clobber a peer's content. Mirrors the
+ * pull-side convergence guard in `sync.ts`.
+ *
+ * The temp file lives in the OS temp dir (never under hqRoot) so it can
+ * never round-trip to S3, and is removed in a `finally` regardless of
+ * outcome. The name is derived from the relative path so concurrent probes
+ * for distinct files never collide on disk.
+ */
+async function remoteContentDiffers(
+  ctx: EntityContext,
+  relativePath: string,
+  localHash: string,
+  hqRoot: string,
+): Promise<boolean> {
+  const probeKey = crypto
+    .createHash("sha256")
+    .update(relativePath)
+    .digest("hex")
+    .slice(0, 16);
+  const probePath = path.join(
+    os.tmpdir(),
+    `hq-conflict-probe-${readShortMachineId(hqRoot)}-${probeKey}.tmp`,
+  );
+  try {
+    await downloadFile(ctx, relativePath, probePath);
+    const remoteHash = fs.lstatSync(probePath).isSymbolicLink()
+      ? hashSymlinkTarget(fs.readlinkSync(probePath))
+      : hashFile(probePath);
+    return remoteHash !== localHash;
+  } catch {
+    return true;
+  } finally {
+    try {
+      fs.rmSync(probePath, { force: true });
+    } catch {
+      /* best-effort cleanup; a stray temp probe is harmless */
+    }
+  }
+}
+
 /**
  * Local-only ephemeral artifacts: conflict-mirror files written by the pull
  * leg whenever a 3-way merge keeps local AND wants to preserve the remote
@@ -940,12 +994,10 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       const remoteChanged = !!journalEntry && hasRemoteChanged(remoteMeta, journalEntry);
 
       let isFreshCollision = false;
+      let multipartConverged = false;
       if (!journalEntry && item.kind === "file") {
         // Single-part S3 PUT etag is MD5 of the body. Multipart uploads
-        // produce \`<md5>-<partCount>\`; we treat any non-single-part etag
-        // as ambiguous and DO classify as a conflict (safer for the
-        // first-time path — false positives prompt the operator, false
-        // negatives lose data). Symlink records (\`kind: "symlink"\`)
+        // produce \`<md5>-<partCount>\`. Symlink records (\`kind: "symlink"\`)
         // skip the check entirely — the wire body shape (\`hq-symlink:\`
         // prefix + target) isn't a pure byte mirror and would mis-
         // classify; symlink overwrites are rare and an audit pass after
@@ -962,13 +1014,55 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
           // path which is idempotent (S3 will overwrite with identical
           // content + carry our metadata). Cheap, no behavior change.
         } else {
-          // Multipart object pre-exists with unknown body shape — assume
-          // collision rather than risk a silent overwrite. The operator
-          // can resolve via the standard conflict prompt.
-          isFreshCollision = true;
+          // Multipart remote etag is \`<md5>-<partCount>\`, NOT a usable
+          // content hash, so — unlike the single-part branch — we cannot
+          // decide collision-vs-identical from the etag alone. The old
+          // behavior assumed a collision here, which minted a FALSE
+          // conflict for the most common fresh-install case: re-pushing a
+          // byte-identical \`core/\` scaffold file whose remote copy happened
+          // to be multipart-uploaded. Every fresh install that hit an
+          // already-populated bucket therefore came up "with conflicts".
+          //
+          // Instead, fetch the remote bytes once and compare content
+          // hashes directly — the same convergence guard the pull side
+          // uses (sync.ts). Identical content is NOT a conflict. On any
+          // fetch/hash failure we fail safe to "conflict" (false positives
+          // prompt the operator; false negatives risk clobbering a peer).
+          const remoteDiffers = await remoteContentDiffers(
+            ctx,
+            relativePath,
+            localHash,
+            hqRoot,
+          );
+          if (remoteDiffers) {
+            isFreshCollision = true;
+          } else {
+            // Byte-identical multipart object already present. Seed the
+            // journal baseline from the remote so the next sync sees no
+            // change on either side, and skip the redundant PUT —
+            // re-uploading would needlessly rewrite remote and churn its
+            // etag from multipart to single-part.
+            multipartConverged = true;
+          }
         }
       }
 
+      if (multipartConverged) {
+        const lstat = fs.lstatSync(absolutePath);
+        updateEntry(
+          journal,
+          relativePath,
+          localHash,
+          lstat.size,
+          "up",
+          remoteMeta.etag,
+          lstat.mtimeMs,
+        );
+        emit({ type: "reconciled", path: relativePath, direction: "push" });
+        filesSkipped++;
+        return;
+      }
+
       if ((localChanged && remoteChanged) || isFreshCollision) {
         conflictPaths.push(relativePath);
 

package/src/cli/sync.ts

@@ -149,7 +149,7 @@ export type SyncProgressEvent =
        */
       type: "reconciled";
       path: string;
-      direction: "pull";
+      direction: "pull" | "push";
     }
   | {
       type: "new-files";