@indigoai-us/hq-cloud 6.14.36 → 6.14.39

package/dist/lib/readlink-safe.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Read a link target without turning an expected filesystem race or an
+ * unsupported link shape into a caller-wide failure.
+ *
+ * A `null` result is deliberately distinct from an empty target string: it
+ * means the caller must preserve the link boundary and choose its conservative
+ * skip/defer path. Non-filesystem exceptions still propagate so programming
+ * errors cannot be mistaken for an unreadable link.
+ */
+export declare function readlinkOrNull(linkPath: string, readlink?: (path: string) => string): string | null;
+//# sourceMappingURL=readlink-safe.d.ts.map

package/dist/lib/readlink-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readlink-safe.d.ts","sourceRoot":"","sources":["../../src/lib/readlink-safe.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAgD,GAC3E,MAAM,GAAG,IAAI,CAcf"}

package/dist/lib/readlink-safe.js

@@ -0,0 +1,27 @@
+import * as fs from "fs";
+/**
+ * Read a link target without turning an expected filesystem race or an
+ * unsupported link shape into a caller-wide failure.
+ *
+ * A `null` result is deliberately distinct from an empty target string: it
+ * means the caller must preserve the link boundary and choose its conservative
+ * skip/defer path. Non-filesystem exceptions still propagate so programming
+ * errors cannot be mistaken for an unreadable link.
+ */
+export function readlinkOrNull(linkPath, readlink = (path) => fs.readlinkSync(path, "utf8")) {
+    try {
+        return readlink(linkPath);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" && "code" in err
+            ? err.code
+            : undefined;
+        // Node system errors use POSIX-style errno names such as EINVAL and
+        // ENOENT. Runtime/programming errors use ERR_* codes; those must remain
+        // loud rather than being misclassified as an unreadable link.
+        if (typeof code === "string" && /^E[A-Z0-9]+$/.test(code))
+            return null;
+        throw err;
+    }
+}
+//# sourceMappingURL=readlink-safe.js.map

package/dist/lib/readlink-safe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readlink-safe.js","sourceRoot":"","sources":["../../src/lib/readlink-safe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,WAAqC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;IAE5E,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GACR,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,IAAI,GAAG;YAC7C,CAAC,CAAE,GAA0B,CAAC,IAAI;YAClC,CAAC,CAAC,SAAS,CAAC;QAChB,oEAAoE;QACpE,wEAAwE;QACxE,8DAA8D;QAC9D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACvE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/lib/readlink-safe.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=readlink-safe.test.d.ts.map

package/dist/lib/readlink-safe.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readlink-safe.test.d.ts","sourceRoot":"","sources":["../../src/lib/readlink-safe.test.ts"],"names":[],"mappings":""}

package/dist/lib/readlink-safe.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { readlinkOrNull } from "./readlink-safe.js";
+function errnoError(code) {
+    const err = new Error(`${code}: scripted readlink failure`);
+    err.code = code;
+    return err;
+}
+describe("readlinkOrNull", () => {
+    it("uses the filesystem reader by default", () => {
+        expect(readlinkOrNull(`/hq-cloud-missing-link-${process.pid}`)).toBeNull();
+    });
+    it("returns the target string verbatim when readlink succeeds", () => {
+        expect(readlinkOrNull("/test/link", () => "../target with spaces")).toBe("../target with spaces");
+    });
+    it.each(["EINVAL", "ENOENT", "EPERM"])("returns null for %s", (code) => {
+        expect(readlinkOrNull("/test/link", () => {
+            throw errnoError(code);
+        })).toBeNull();
+    });
+    it("rethrows non-filesystem failures", () => {
+        const defect = new Error("unexpected test defect");
+        expect(() => readlinkOrNull("/test/link", () => {
+            throw defect;
+        })).toThrow(defect);
+    });
+    it("rethrows code-bearing programming errors", () => {
+        const defect = new TypeError("path must be a string");
+        defect.code = "ERR_INVALID_ARG_TYPE";
+        expect(() => readlinkOrNull("/test/link", () => {
+            throw defect;
+        })).toThrow(defect);
+    });
+});
+//# sourceMappingURL=readlink-safe.test.js.map

package/dist/lib/readlink-safe.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readlink-safe.test.js","sourceRoot":"","sources":["../../src/lib/readlink-safe.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,6BAA6B,CAA0B,CAAC;IACrF,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,CAAC,cAAc,CAAC,0BAA0B,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC,IAAI,CACtE,uBAAuB,CACxB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC,IAAI,EAAE,EAAE;QACrE,MAAM,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE;YACvC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAEnD,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE;YAC7C,MAAM,MAAM,CAAC;QACf,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,uBAAuB,CAAiC,CAAC;QACtF,MAAM,CAAC,IAAI,GAAG,sBAAsB,CAAC;QAErC,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE;YAC7C,MAAM,MAAM,CAAC;QACf,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.14.36",
+  "version": "6.14.39",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/bin/sync-runner-company.ts

@@ -183,15 +183,20 @@ export async function executeCompanyFanout(options: {
           ...(event.errorCode ? { errorCode: event.errorCode } : {}),
         });
       } else if (event.type === "skip-junk-key-spelling") {
-        // Deliberate skip: forwarded for visibility, NEVER pushed into
-        // errors[] (policy hq-sync-deliberate-skip-not-fatal-error-exit2 —
-        // a benign recurring skip must not gate exit 2 / Sentry alerts).
         options.emit({
           type: "skip-junk-key-spelling",
           company: companyLabel,
           path: event.path,
           journaledKey: event.journaledKey,
         });
+      } else if (event.type === "not-shipped") {
+        options.emit({
+          type: "not-shipped",
+          company: companyLabel,
+          reason: event.reason,
+          count: event.count,
+          samplePaths: event.samplePaths,
+        });
       }
     };
 
@@ -208,6 +213,8 @@ export async function executeCompanyFanout(options: {
         filesExcludedByPolicy: 0,
         filesExcludedByScope: 0,
         filesExcludedByIgnore: 0,
+        unreachablePaths: [],
+        linkedSubtreesNotShipped: [],
         conflictPaths: [],
         aborted: false,
       };
@@ -288,6 +295,15 @@ export async function executeCompanyFanout(options: {
           skipUnchanged: true,
           propagateDeletes: true,
           propagateDeletePolicy: options.resolveDeletePolicy(),
+          // `pushPaths` are INTERNAL walk roots (the company folder / the
+          // personal-vault dirs), never user input, so an unreachable entry
+          // here is a benign race — a directory removed between the scan and
+          // the push — and must not fail an unattended background sync. Record
+          // + report it (`not-shipped` event, `ShareResult.unreachablePaths`)
+          // and carry on. The interactive `hq sync push <path>` keeps the
+          // default "error" policy, which is where a user-typed path that
+          // silently ships nothing is a real bug (feedback_a51cb63d ask #2).
+          unreachablePathPolicy: "warn",
           onEvent: tagAndEmit,
           ...(options.uploadAuthor ? { author: options.uploadAuthor } : {}),
           ...(target.personalMode !== undefined

package/src/bin/sync-runner.test.ts

@@ -157,6 +157,8 @@ function defaultShareResult(overrides: Partial<ShareResult> = {}): ShareResult {
     filesExcludedByPolicy: 0,
     filesExcludedByScope: 0,
     filesExcludedByIgnore: 0,
+    unreachablePaths: [],
+    linkedSubtreesNotShipped: [],
     conflictPaths: [],
     aborted: false,
     ...overrides,
@@ -2025,6 +2027,58 @@ describe("per-company fanout", () => {
 // ---------------------------------------------------------------------------
 
 describe("all-complete aggregate", () => {
+  it("reports every unreadable-link fallback by path without turning the company leg into PARTIAL_SYNC_EXIT", async () => {
+    const unreadablePaths = [
+      "policies/scope-invalid-tombstone",
+      "docs/conflict-convergence-probe",
+      "skills/downloaded-link-hash",
+    ];
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [{ companyUid: "cmp_a" }],
+          entityGet: (uid: string) =>
+            Promise.resolve({
+              uid,
+              type: "company",
+              slug: "acme",
+              bucketName: "hq-vault-acme-test",
+              status: "active",
+            } as unknown as EntityInfo),
+        }),
+      share: vi.fn(async (options: ShareOptions) => {
+        for (const path of unreadablePaths) {
+          options.onEvent?.({
+            type: "not-shipped",
+            reason: "unreadable-link",
+            count: 1,
+            samplePaths: [path],
+          });
+        }
+        return defaultShareResult();
+      }),
+    });
+
+    const code = await runRunner(["--companies", "--direction", "push"], deps);
+
+    for (const path of unreadablePaths) {
+      expect(deps.stdout.events()).toContainEqual({
+        type: "not-shipped",
+        company: "acme",
+        reason: "unreadable-link",
+        count: 1,
+        samplePaths: [path],
+      });
+    }
+    const all = deps.stdout.events().find(
+      (event): event is Extract<RunnerEvent, { type: "all-complete" }> =>
+        event.type === "all-complete",
+    );
+    expect(all?.errors).toEqual([]);
+    expect(all?.partial).toBe(false);
+    expect(code).toBe(0);
+  });
+
   it("emits all-complete when telemetry never resolves", async () => {
     const deps = makeDeps({
       createVaultClient: () =>

package/src/bin/sync-runner.ts

@@ -402,6 +402,10 @@ export type RunnerEvent =
       Extract<SyncProgressEvent, { type: "skip-junk-key-spelling" }>,
       "type"
     >)
+  | ({ type: "not-shipped"; company: string } & Omit<
+      Extract<SyncProgressEvent, { type: "not-shipped" }>,
+      "type"
+    >)
   | ({
       type: "complete";
       company: string;

package/src/cli/reindex.ts

@@ -22,6 +22,7 @@ import { spawnSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { readlinkOrNull } from "../lib/readlink-safe.js";
 import {
   acquireOperationLock,
   OperationLockedError,
@@ -126,15 +127,6 @@ function lstatOrNull(p: string): fs.Stats | null {
   }
 }
 
-/** readlink without throwing (null when not a symlink / missing). */
-function readlinkOrNull(p: string): string | null {
-  try {
-    return fs.readlinkSync(p);
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Entries of `dir` matching a bash `dir/*` glob: dotfiles excluded (no
  * dotglob), sorted lexicographically (bash glob order). Missing dir → [].