@indigoai-us/hq-cloud 5.23.0 → 5.25.0

package/src/bin/sync-runner.ts

@@ -14,6 +14,10 @@
  *   --company <slug-or-uid>   Sync a single company (alternative to --companies)
  *   --on-conflict <strategy>  abort | overwrite | keep (default: abort)
  *   --hq-root <path>          Local HQ directory (default: $HOME/hq)
+ *   --skip-personal           Drop the personal target from the --companies
+ *                             fanout. Combined with HQ_SYNC_SKIP_PERSONAL env
+ *                             (either truthy disables personal sync). No-op
+ *                             outside --companies mode.
  *   --json                    Ignored — ndjson on stdout is the default and
  *                             only output mode. Accepted for symmetry with the
  *                             AppBar's argv in case someone passes it.
@@ -120,6 +124,63 @@ const DEFAULT_VAULT_API_URL =
 
 const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
 
+/**
+ * Delete-propagation policy honored by the push leg of bidirectional sync.
+ *
+ * Default `"currency-gated"` in 5.25 — flipped from `"owned-only"` after
+ * one machine (Indigo / corey) ran the 5.24 code path through real syncs
+ * for a week without surfacing surprise behavior. Currency-gated does a
+ * per-file ETag HEAD before propagating any local-delete to S3: if the
+ * remote object's current ETag no longer matches the journal's last-
+ * recorded one, the delete is refused and the next pull leg re-pulls the
+ * file via the standard 3-way merge path. This is strictly safer than
+ * `owned-only` (which propagates any local-delete the journal can prove
+ * came from this device) — the only delete-class that changes behavior
+ * is "deleted locally + modified remotely by another device", which
+ * previously destroyed remote work and now becomes a pull-and-conflict.
+ *
+ * Env override `HQ_SYNC_DELETE_POLICY=owned-only|all|currency-gated` is
+ * also the rollback knob — anyone surprised by 5.25's flip can revert
+ * to `owned-only` without redeploying. `all` is the unsafe-mirror mode
+ * previously used by the runner pre-5.20 — included only as an
+ * emergency reconcile lever, not a recommended default.
+ */
+export type DeletePropagationPolicy = "currency-gated" | "owned-only" | "all";
+
+export function resolveDeletePolicy(): DeletePropagationPolicy {
+  const env = process.env.HQ_SYNC_DELETE_POLICY;
+  if (env === "owned-only" || env === "all" || env === "currency-gated") {
+    return env;
+  }
+  return "currency-gated";
+}
+
+/**
+ * Resolve whether to skip the personal target in a `--companies` fanout.
+ *
+ * Two inputs combine: the `--skip-personal` CLI flag (parsed into
+ * `ParsedArgs.skipPersonal`) and the `HQ_SYNC_SKIP_PERSONAL` env var. Either
+ * being truthy skips the personal target — flag wins on conflict (CLI
+ * flag is the explicit-for-this-invocation knob, env is the persistent
+ * default usually set by the menubar in the spawned child process).
+ *
+ * Env truthy values: `1`, `true`, `yes` (case-insensitive). Anything else
+ * (including missing) is treated as falsy — same shape as classic
+ * Unix opt-in env conventions; conservative to avoid surprising opt-outs.
+ *
+ * Use case: the menubar app exposes a "Sync personal vault" toggle in
+ * Settings (default ON, matching the auto-provisioning UX). When the user
+ * flips it off, the menubar spawns `hq sync` with this env set so the
+ * fanout drops the personal target before walking the user's entire HQ
+ * tree (a sync that would otherwise scan thousands of files, including
+ * the new personal-vault default exclusions, just to do nothing useful).
+ */
+export function resolveSkipPersonal(flag: boolean): boolean {
+  if (flag) return true;
+  const env = (process.env.HQ_SYNC_SKIP_PERSONAL ?? "").toLowerCase();
+  return env === "1" || env === "true" || env === "yes";
+}
+
 // Personal-vault scope (exclusion list + path computer) lives in
 // `../personal-vault.ts` so the `hq sync` CLI and this runner share the same
 // rules. Re-exported here for back-compat with any callers still importing
@@ -169,12 +230,19 @@ export type RunnerEvent =
       /**
        * Upload counters. Always emitted (0 when the run was pull-only) so
        * downstream consumers don't need to conditionally read the field.
-       * Tauri's `SyncCompleteEvent` ignores extra fields today; adding them
-       * to the Rust struct is a follow-up when the UI needs to surface push
-       * totals.
        */
       filesUploaded: number;
       bytesUploaded: number;
+      /**
+       * Push-side counters added in 5.25. Always emitted as numbers (0
+       * when no push leg ran). Tauri's `SyncCompleteEvent` carries them
+       * as Option<u32> for back-compat with <5.25 engines that don't
+       * include them; structural-typing-wise, the union just adds
+       * properties on top of `SyncResult`.
+       */
+      filesTombstoned: number;
+      filesRefusedStale: number;
+      filesExcludedByPolicy: number;
     } & SyncResult)
   | {
       type: "all-complete";
@@ -374,6 +442,13 @@ interface ParsedArgs {
   watch: boolean;
   /** Auto-sync (Beta): ms between remote-pull passes. Required when watch=true. */
   pollRemoteMs?: number;
+  /**
+   * Drop the personal target from the fanout. Combined with the
+   * `HQ_SYNC_SKIP_PERSONAL` env var by `resolveSkipPersonal()` — either
+   * truthy disables personal sync for this run. No-op outside `--companies`
+   * mode (single-company runs never visit the personal target).
+   */
+  skipPersonal: boolean;
 }
 
 function parseArgs(argv: string[]): ParsedArgs | { error: string } {
@@ -384,6 +459,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let direction: Direction = "pull";
   let watch = false;
   let pollRemoteMs: number | undefined;
+  let skipPersonal = false;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -437,6 +513,12 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
       case "--json":
         // Accepted but ignored — ndjson is the only output mode.
         break;
+      case "--skip-personal":
+        // Drop the personal target from the fanout. No-op outside
+        // --companies mode. Combined with HQ_SYNC_SKIP_PERSONAL env via
+        // resolveSkipPersonal().
+        skipPersonal = true;
+        break;
       default:
         return { error: `Unknown argument: ${arg}` };
     }
@@ -452,7 +534,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
     return { error: "--poll-remote-ms requires --watch" };
   }
 
-  return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs };
+  return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs, skipPersonal };
 }
 
 // ---------------------------------------------------------------------------
@@ -670,7 +752,15 @@ export async function runRunner(
     plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
   }
 
-  if (parsed.companies) {
+  if (parsed.companies && !resolveSkipPersonal(parsed.skipPersonal)) {
+    // Personal-target fanout slot. Skipped entirely when --skip-personal
+    // (or HQ_SYNC_SKIP_PERSONAL=1) is set — see resolveSkipPersonal doc for
+    // the rationale (menubar opt-out for users who only want company sync).
+    // When skipped, the fanout-plan event below carries only company
+    // memberships and no "personal" slug; downstream consumers (menubar
+    // workspaces row, status surfaces) should already tolerate that
+    // shape since pre-5.25 fanout often had it (a user with no person
+    // entity yet, or before the canonical-person-entity machinery landed).
     const persons = await client.entity.listByType("person");
     const pick = pickCanonicalPersonEntity(persons);
     if (pick?.bucketName) {
@@ -799,6 +889,9 @@ export async function runRunner(
         bytesUploaded: 0,
         filesSkipped: 0,
         filesDeleted: 0,
+        filesTombstoned: 0,
+        filesRefusedStale: 0,
+        filesExcludedByPolicy: 0,
         conflictPaths: [],
         aborted: false,
       };
@@ -834,7 +927,16 @@ export async function runRunner(
           // — DeleteObject writes a delete-marker, prior versions remain
           // recoverable). Without this, a deleted file resurfaces on the
           // next pull because the remote object is still listable.
+          //
+          // Policy default in 5.24 is `owned-only` (pre-5.24 behavior;
+          // preserved for the soak window). `HQ_SYNC_DELETE_POLICY` env
+          // can opt INTO the safer `currency-gated` (per-file HEAD + ETag
+          // verification) or the unsafe `all` (emergency reconcile only).
+          // Default flips to `currency-gated` in 5.25 after at least one
+          // machine has soaked the new path. Both personal and company
+          // targets use the same resolver — same engine, same flip.
           propagateDeletes: true,
+          propagateDeletePolicy: resolveDeletePolicy(),
           onEvent: tagAndEmit,
           ...(uploadAuthor ? { author: uploadAuthor } : {}),
           // Mirror the pull-side seam: only spread these for the personal
@@ -891,6 +993,17 @@ export async function runRunner(
         filesUploaded: pushResult.filesUploaded,
         bytesUploaded: pushResult.bytesUploaded,
         filesSkipped: pullResult.filesSkipped + pushResult.filesSkipped,
+        // Push-side counters surfaced on `complete` so the menubar's
+        // `SyncCompleteEvent` (which carries them as Option<u32> for
+        // back-compat with pre-5.25 engines) can render the new totals.
+        // Always emitted as numbers (0 when no push leg ran) so Rust's
+        // serde decodes them as `Some(0)` rather than `None` — distinct
+        // from the legacy-engine `None` and useful when the UI wants to
+        // distinguish "engine ran, nothing tombstoned" from "engine
+        // didn't report".
+        filesTombstoned: pushResult.filesTombstoned,
+        filesRefusedStale: pushResult.filesRefusedStale,
+        filesExcludedByPolicy: pushResult.filesExcludedByPolicy,
         // Sourced from the merged path list so push-side conflicts are
         // counted too — `ShareResult` doesn't expose a numeric counter,
         // and using `pullResult.conflicts` alone silently dropped any
@@ -928,6 +1041,13 @@ export async function runRunner(
         filesUploaded: state.filesUploaded,
         bytesUploaded: state.bytesUploaded,
         filesSkipped: 0,
+        // Mid-flight throw: we have no clean ShareResult to read these
+        // from. Report 0 so the event shape stays stable; the partial
+        // counts above already reflect what actually moved before the
+        // throw.
+        filesTombstoned: 0,
+        filesRefusedStale: 0,
+        filesExcludedByPolicy: 0,
         conflicts: 0,
         conflictPaths: [],
         aborted: true,