@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/backup-prune.ts

@@ -1,182 +0,0 @@
-/**
- * Safety-first inventory and retention policy for HQ rescue snapshots.
- *
- * This file deliberately separates policy from filesystem access.  In
- * particular, `planBackupPrune` cannot remove, create, or mutate anything.
- */
-import * as crypto from "crypto";
-import * as fs from "fs";
-import * as path from "path";
-
-export const SNAPSHOT_SCHEMA_VERSION = 1;
-export const SNAPSHOT_FILE = "SNAPSHOT.json";
-export const MANAGED_SNAPSHOT_RE = /^pre-update-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-[a-f0-9]{16}-[A-Za-z0-9_-]+$/;
-export type SnapshotStatus = "copying" | "ready" | "completed-good" | "failed-pre-mutation" | "recovery-required";
-
-export interface SnapshotManifest {
-  schemaVersion: 1;
-  status: SnapshotStatus;
-  canonicalHqRoot: string;
-  rootHash: string;
-  runId: string;
-  creatorPid: number;
-  creatorStartedAt: string;
-  source: string;
-  ref: string;
-  sourceSha: string;
-  createdAt: string;
-  completedAt?: string;
-  includedRoots: string[];
-  fileCount: number;
-  byteCount: number;
-}
-
-export interface BackupEntry {
-  name: string;
-  manifest: SnapshotManifest;
-  createdMs: number;
-  completedMs: number;
-  bytes: number;
-  identity?: { dev: number; ino: number };
-  copyingOwnerLive?: boolean;
-}
-export interface ProtectedEntry { entry: BackupEntry; reason: string }
-export interface DeletionCandidate { entry: BackupEntry; reason: string }
-export interface BackupPrunePlan { candidates: DeletionCandidate[]; protected: ProtectedEntry[]; unmanaged: { name: string; reason: string }[] }
-export interface RetentionConfig { keepGood: number; keepFailedPreMutation: number; maxAgeDays: number }
-
-export const DEFAULT_RETENTION: RetentionConfig = { keepGood: 2, keepFailedPreMutation: 1, maxAgeDays: 7 };
-const day = 24 * 60 * 60 * 1000;
-
-export function canonicalRootHash(root: string): string {
-  return crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
-}
-
-export function safeRetention(input: Partial<RetentionConfig> = {}): RetentionConfig {
-  const integer = (value: unknown, fallback: number, minimum: number) =>
-    typeof value === "number" && Number.isInteger(value) && value >= minimum ? value : fallback;
-  return {
-    keepGood: integer(input.keepGood, DEFAULT_RETENTION.keepGood, 1),
-    keepFailedPreMutation: integer(input.keepFailedPreMutation, DEFAULT_RETENTION.keepFailedPreMutation, 1),
-    maxAgeDays: integer(input.maxAgeDays, DEFAULT_RETENTION.maxAgeDays, 0),
-  };
-}
-
-const newestFirst = (a: BackupEntry, b: BackupEntry) => b.completedMs - a.completedMs || b.createdMs - a.createdMs || b.name.localeCompare(a.name);
-
-/** Every managed entry receives either a retention reason or a deletion reason. */
-export function planBackupPrune(entries: BackupEntry[], nowMs: number, input: Partial<RetentionConfig> = {}): BackupPrunePlan {
-  const cfg = safeRetention(input);
-  const candidates: DeletionCandidate[] = [];
-  const protectedEntries: ProtectedEntry[] = [];
-  const byRoot = new Map<string, BackupEntry[]>();
-  for (const entry of entries) {
-    const group = byRoot.get(entry.manifest.canonicalHqRoot) ?? [];
-    group.push(entry);
-    byRoot.set(entry.manifest.canonicalHqRoot, group);
-  }
-  for (const group of byRoot.values()) {
-    const good = group.filter((e) => e.manifest.status === "completed-good").sort(newestFirst);
-    const readyOrGood = group.filter((e) => e.manifest.status === "ready" || e.manifest.status === "completed-good").sort(newestFirst);
-    const laterGood = (e: BackupEntry) => good.some((g) => g.completedMs > e.completedMs || (g.completedMs === e.completedMs && g.name > e.name));
-    const newestRecovery = group.filter((e) => e.manifest.status === "recovery-required").sort(newestFirst)[0];
-    for (const entry of group) {
-      const status = entry.manifest.status;
-      if (status === "copying") {
-        protectedEntries.push({ entry, reason: entry.copyingOwnerLive ? "copying-owner-live" : "copying-not-superseded" });
-        continue;
-      }
-      if (status === "completed-good") {
-        const rank = good.indexOf(entry);
-        if (rank < cfg.keepGood) {
-          protectedEntries.push({ entry, reason: rank === 0 ? "newest-good" : "keep-newest-good" });
-        } else if (nowMs - entry.completedMs >= cfg.maxAgeDays * day) {
-          candidates.push({ entry, reason: "completed-good-age-and-rank" });
-        } else {
-          candidates.push({ entry, reason: "completed-good-rank" });
-        }
-        continue;
-      }
-      if (status === "failed-pre-mutation") {
-        const failures = group.filter((e) => e.manifest.status === status).sort(newestFirst);
-        const rank = failures.indexOf(entry);
-        const superseded = readyOrGood.some((other) => newestFirst(other, entry) < 0);
-        if (rank < cfg.keepFailedPreMutation || !superseded) protectedEntries.push({ entry, reason: !superseded ? "failed-pre-mutation-not-superseded" : "keep-failed-pre-mutation" });
-        else candidates.push({ entry, reason: "failed-pre-mutation-superseded" });
-        continue;
-      }
-      // A recovery-required copy is recovery evidence until a later known-good run.
-      if (!laterGood(entry)) {
-        protectedEntries.push({ entry, reason: "recovery-required-no-later-good" });
-      } else if (entry === newestRecovery && nowMs - entry.completedMs < cfg.maxAgeDays * day) {
-        protectedEntries.push({ entry, reason: "newest-recovery-required-grace" });
-      } else if (nowMs - entry.completedMs >= cfg.maxAgeDays * day || entry !== newestRecovery) {
-        candidates.push({ entry, reason: "recovery-required-superseded" });
-      } else {
-        protectedEntries.push({ entry, reason: "recovery-required-grace" });
-      }
-    }
-  }
-  return { candidates, protected: protectedEntries, unmanaged: [] };
-}
-
-function validManifest(value: unknown, canonicalRoot: string): value is SnapshotManifest {
-  const x = value as Partial<SnapshotManifest>;
-  return !!x && x.schemaVersion === SNAPSHOT_SCHEMA_VERSION && typeof x.canonicalHqRoot === "string" &&
-    x.canonicalHqRoot === canonicalRoot && x.rootHash === canonicalRootHash(canonicalRoot) &&
-    typeof x.runId === "string" && /^[A-Za-z0-9_-]+$/.test(x.runId) &&
-    ["copying", "ready", "completed-good", "failed-pre-mutation", "recovery-required"].includes(x.status ?? "") &&
-    typeof x.createdAt === "string" && Array.isArray(x.includedRoots) && typeof x.fileCount === "number" && typeof x.byteCount === "number";
-}
-
-export function inventoryManagedSnapshots(backupRoot: string, canonicalRoot: string, isCopyingOwnerLive: (m: SnapshotManifest) => boolean = () => false, retention: Partial<RetentionConfig> = {}): BackupPrunePlan & { entries: BackupEntry[] } {
-  const entries: BackupEntry[] = [];
-  const unmanaged: { name: string; reason: string }[] = [];
-  let names: string[] = [];
-  try { names = fs.readdirSync(backupRoot); } catch { return { entries, candidates: [], protected: [], unmanaged: [{ name: backupRoot, reason: "backup-root-unreadable" }] }; }
-  for (const name of names.sort()) {
-    // Never descend into categories such as mcp/; only direct, exact names qualify.
-    if (!MANAGED_SNAPSHOT_RE.test(name)) { unmanaged.push({ name, reason: "not-managed-snapshot-name" }); continue; }
-    const abs = path.join(backupRoot, name);
-    let st: fs.Stats;
-    try { st = fs.lstatSync(abs); } catch { unmanaged.push({ name, reason: "lstat-failed" }); continue; }
-    if (!st.isDirectory() || st.isSymbolicLink()) { unmanaged.push({ name, reason: "not-real-directory" }); continue; }
-    let manifest: unknown;
-    try { manifest = JSON.parse(fs.readFileSync(path.join(abs, SNAPSHOT_FILE), "utf8")); } catch { unmanaged.push({ name, reason: "missing-or-invalid-metadata" }); continue; }
-    if (!validManifest(manifest, canonicalRoot)) { unmanaged.push({ name, reason: "metadata-does-not-match-canonical-root" }); continue; }
-    const m = manifest;
-    const createdMs = Date.parse(m.createdAt);
-    const completedMs = Date.parse(m.completedAt ?? m.createdAt);
-    if (!Number.isFinite(createdMs) || !Number.isFinite(completedMs)) { unmanaged.push({ name, reason: "invalid-metadata-timestamp" }); continue; }
-    entries.push({ name, manifest: m, createdMs, completedMs, bytes: m.byteCount, identity: { dev: st.dev, ino: st.ino }, copyingOwnerLive: m.status === "copying" && isCopyingOwnerLive(m) });
-  }
-  const plan = planBackupPrune(entries, Date.now(), retention);
-  return { entries, ...plan, unmanaged: [...unmanaged, ...plan.unmanaged] };
-}
-
-/** Revalidates strict identity then renames before recursively removing it. */
-export function applyBackupPrune(backupRoot: string, canonicalRoot: string, plan: BackupPrunePlan, retention: Partial<RetentionConfig> = {}): { deleted: string[]; failures: string[] } {
-  const deleted: string[] = [], failures: string[] = [];
-  const lockPath = path.join(backupRoot, ".hq-backup-prune.lock");
-  let lockFd: number | undefined;
-  try { lockFd = fs.openSync(lockPath, "wx"); fs.writeSync(lockFd, `${process.pid}\n`); }
-  catch { return { deleted, failures: ["backup-root-lock-busy-or-unwritable"] }; }
-  try {
-    // This is deliberately after acquiring the backup-root lock and immediately
-    // before rename: a dry-run plan is never trusted across a filesystem race.
-    const fresh = inventoryManagedSnapshots(backupRoot, canonicalRoot, () => false, retention);
-    const freshByName = new Map(fresh.entries.map((e) => [e.name, e]));
-    const stillCandidates = new Set(fresh.candidates.map((e) => e.entry.name));
-    for (const candidate of plan.candidates) {
-      const current = freshByName.get(candidate.entry.name);
-      if (!current || !stillCandidates.has(candidate.entry.name) || current.manifest.runId !== candidate.entry.manifest.runId || current.identity?.dev !== candidate.entry.identity?.dev || current.identity?.ino !== candidate.entry.identity?.ino || current.manifest.status === "copying") { failures.push(`${candidate.entry.name}: changed-or-in-use`); continue; }
-      const from = path.join(backupRoot, current.name);
-      const tombstone = path.join(backupRoot, `.deleting-${current.manifest.runId}`);
-      try { fs.renameSync(from, tombstone); fs.rmSync(tombstone, { recursive: true, force: false }); deleted.push(current.name); }
-      catch (error) { failures.push(`${current.name}: ${error instanceof Error ? error.message : String(error)}`); }
-    }
-  } finally {
-    try { if (lockFd !== undefined) fs.closeSync(lockFd); fs.unlinkSync(lockPath); } catch { /* retained errors are safer than a delete race */ }
-  }
-  return { deleted, failures };
-}

package/src/bin/backup-prune-runner.ts

@@ -1,33 +0,0 @@
-#!/usr/bin/env node
-/** Explicit, local-only retention command. Defaults to dry-run. */
-import * as fs from "fs";
-import * as path from "path";
-import { applyBackupPrune, inventoryManagedSnapshots } from "../backup-prune.js";
-import { acquireOperationLock, OperationLockedError } from "../operation-lock.js";
-
-const args = process.argv.slice(2);
-const value = (flag: string) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
-const rootArg = value("--hq-root");
-const backupArg = value("--backup-dir");
-const mode = value("--mode") ?? "dry-run";
-if (!rootArg || !["dry-run", "apply"].includes(mode)) {
-  process.stderr.write("usage: hq-backup-prune --hq-root DIR [--backup-dir DIR] [--mode dry-run|apply]\n");
-  process.exit(2);
-}
-const root = fs.realpathSync(rootArg);
-const backupRoot = backupArg ? path.resolve(backupArg) : path.join(process.env.HOME ?? "", ".hq", "backups");
-let lock;
-try { lock = acquireOperationLock(root, "backup-prune", { timeoutSec: 0, onWaitStart: () => undefined }); }
-catch (error) {
-  if (error instanceof OperationLockedError) { process.stderr.write("hq-backup-prune: skipped-in-use\n"); process.exit(0); }
-  throw error;
-}
-try {
-  const inventory = inventoryManagedSnapshots(backupRoot, root, (m) => { try { process.kill(m.creatorPid, 0); return true; } catch { return false; } });
-  const plan = { candidates: inventory.candidates, protected: inventory.protected, unmanaged: inventory.unmanaged };
-  process.stdout.write(JSON.stringify({ mode, candidates: plan.candidates.map((x) => ({ name: x.entry.name, rootHash: x.entry.manifest.rootHash, status: x.entry.manifest.status, bytes: x.entry.bytes, reason: x.reason })), protected: plan.protected.map((x) => ({ name: x.entry.name, reason: x.reason })), unmanaged: plan.unmanaged }) + "\n");
-  if (mode === "apply") {
-    const result = applyBackupPrune(backupRoot, root, plan);
-    if (result.failures.length) { process.stderr.write(result.failures.join("\n") + "\n"); process.exitCode = 1; }
-  }
-} finally { lock.release(); }

package/src/bin/rescue-runner.ts

@@ -1,25 +0,0 @@
-#!/usr/bin/env node
-/**
- * hq-rescue — machine-targeted entrypoint for the drift-preserving HQ-core
- * re-sync ("rescue") shipped in `@indigoai-us/hq-cloud`.
- *
- * This is the rescue analogue of `hq-sync-runner`: the HQ Sync menubar app
- * (Tauri + Rust) spawns it the same way it spawns the sync runner —
- *   `npx -y --package=@indigoai-us/hq-cloud@<pin> hq-rescue <flags>`
- * — so the app invokes hq-cloud directly at runtime (pinned by the Rust
- * `HQ_CLOUD_VERSION` constant) rather than bundling a private copy of the
- * script. `hq rescue` in `@indigoai-us/hq-cli` is the human-facing sibling.
- *
- * All flags are forwarded verbatim to scripts/replace-rescue.sh — see that
- * script (and src/cli/rescue.ts) for the supported flags:
- *   --hq-root --source --ref --floor-sha --paths --preserve
- *   --preserve-subpath --no-history-check --no-backup --backup-dir
- *   --cloud-update --dry-run --yes
- *
- * stdout/stderr from the script are inherited so the caller (the menubar's
- * RescueRunResult tail capture) sees the scan log + trailing summary.
- */
-import { rescue } from "../cli/rescue.js";
-
-const { status } = rescue({ extraArgs: process.argv.slice(2) });
-process.exit(status);