@indigoai-us/hq-cloud 6.14.50 → 6.15.1

package/src/cli/rescue-snapshot.ts

@@ -1,51 +0,0 @@
-/** Filesystem shape captured during rescue classification. */
-export type RescuePathKind = "missing" | "file" | "directory" | "symlink" | "other";
-
-
-/** Raised when a path changes shape between read-only classification and apply. */
-export class RescuePathChangedError extends Error {
-  constructor(
-    public readonly rel: string,
-    public readonly expected: RescuePathKind,
-    public readonly actual: RescuePathKind,
-  ) {
-    super(
-      `rescue path changed after classification: ${rel} (expected ${expected}, found ${actual}); ` +
-        "another process may be rebuilding generated HQ paths, so rescue stopped before mutation",
-    );
-    this.name = "RescuePathChangedError";
-  }
-}
-
-/** Return whether a directory is reproducible state that rescue must not snapshot or classify. */
-export function isRescueTransientDirectory(rel: string): boolean {
-  const normalized = rel.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
-  if (
-    normalized === "worktrees" ||
-    normalized.startsWith("worktrees/") ||
-    normalized === ".worktrees" ||
-    normalized.startsWith(".worktrees/") ||
-    normalized === ".sst-sandbox-home" ||
-    normalized.startsWith(".sst-sandbox-home/") ||
-    normalized === ".tmp-codex-asar" ||
-    normalized.startsWith(".tmp-codex-asar/") ||
-    normalized === ".claude/worktrees" ||
-    normalized.startsWith(".claude/worktrees/")
-  ) {
-    return true;
-  }
-  return normalized
-    .split("/")
-    .some((part) =>
-      ["node_modules", ".git", ".pnpm-store", ".sst", ".next", "target"].includes(part),
-    );
-}
-
-/** Fail safely when apply observes a different path shape than classification did. */
-export function assertRescuePathTypeUnchanged(
-  rel: string,
-  expected: RescuePathKind,
-  actual: RescuePathKind,
-): void {
-  if (expected !== actual) throw new RescuePathChangedError(rel, expected, actual);
-}

package/src/cli/rescue.reindex.test.ts

@@ -1,63 +0,0 @@
-/**
- * Wiring tests: `rescue()` runs `reindex()` after a successful, non-dry-run
- * rescue so the generated skill wrappers / workers registry are refreshed once
- * core/ has been re-laid-down (the personal overlay is read directly, not
- * mirrored, so there are no personal mirror symlinks to refresh).
- *
- * The rescue algorithm (./rescue-core.js) is mocked so no real clone/overlay
- * runs, and ./reindex.js is mocked to a spy so we assert the call without
- * touching disk.
- */
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-
-vi.mock("./rescue-core.js", () => ({
-  runRescue: vi.fn(() => ({ status: 0 })),
-}));
-vi.mock("./reindex.js", () => ({
-  reindex: vi.fn(() => ({ status: 0 })),
-}));
-
-import { runRescue } from "./rescue-core.js";
-import { reindex } from "./reindex.js";
-import { rescue } from "./rescue.js";
-
-describe("rescue → reindex", () => {
-  let stateDir: string;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    (runRescue as unknown as ReturnType<typeof vi.fn>).mockReturnValue({ status: 0 });
-    // rescue() now takes the per-root operation lock; redirect it to a tmp dir.
-    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "rescue-reindex-state-"));
-    process.env.HQ_STATE_DIR = stateDir;
-  });
-
-  afterEach(() => {
-    fs.rmSync(stateDir, { recursive: true, force: true });
-    delete process.env.HQ_STATE_DIR;
-  });
-
-  it("refreshes via reindex after a successful rescue", () => {
-    const r = rescue({ hqRoot: "/tmp/hq", assumeYes: true });
-    expect(r.status).toBe(0);
-    expect(reindex).toHaveBeenCalledTimes(1);
-    // skipLock: rescue already holds the per-root operation lock, so the
-    // internal reindex must not try to re-acquire it.
-    expect(reindex).toHaveBeenCalledWith({ repoRoot: "/tmp/hq", skipLock: true });
-  });
-
-  it("does NOT run reindex on a dry-run", () => {
-    rescue({ hqRoot: "/tmp/hq", dryRun: true });
-    expect(reindex).not.toHaveBeenCalled();
-  });
-
-  it("does NOT run reindex when the rescue fails", () => {
-    (runRescue as unknown as ReturnType<typeof vi.fn>).mockReturnValueOnce({ status: 1 });
-    const r = rescue({ hqRoot: "/tmp/hq", assumeYes: true });
-    expect(r.status).toBe(1);
-    expect(reindex).not.toHaveBeenCalled();
-  });
-});

package/src/cli/rescue.test.ts

@@ -1,131 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { buildRescueArgs, extractLockTimeout } from "./rescue.js";
-import { toCygwinRsyncPath } from "./rescue-core.js";
-import {
-  decodeLocalVaultSegment,
-  encodeLocalVaultSegment,
-  localPathForVaultKey,
-  vaultKeyForLocalPath,
-} from "../local-path-codec.js";
-
-describe("extractLockTimeout", () => {
-  it("returns the explicit option untouched when extraArgs is empty/absent", () => {
-    expect(extractLockTimeout({ lockTimeoutSec: 5 })).toEqual({
-      lockTimeoutSec: 5,
-      cleanedExtraArgs: undefined,
-    });
-    expect(extractLockTimeout({ lockTimeoutSec: 5, extraArgs: [] })).toEqual({
-      lockTimeoutSec: 5,
-      cleanedExtraArgs: [],
-    });
-  });
-
-  it("pulls --lock-timeout <secs> out of extraArgs and strips it from the forwarded args", () => {
-    const r = extractLockTimeout({
-      extraArgs: ["--lock-timeout", "30", "--dry-run", "--yes"],
-    });
-    expect(r.lockTimeoutSec).toBe(30);
-    // The flag + its value never reach the rescue script.
-    expect(r.cleanedExtraArgs).toEqual(["--dry-run", "--yes"]);
-  });
-
-  it("honors --lock-timeout 0 (refuse immediately)", () => {
-    const r = extractLockTimeout({ extraArgs: ["--lock-timeout", "0"] });
-    expect(r.lockTimeoutSec).toBe(0);
-    expect(r.cleanedExtraArgs).toEqual([]);
-  });
-
-  it("explicit option wins over a flag in extraArgs", () => {
-    const r = extractLockTimeout({
-      lockTimeoutSec: 0,
-      extraArgs: ["--lock-timeout", "60"],
-    });
-    expect(r.lockTimeoutSec).toBe(0);
-    expect(r.cleanedExtraArgs).toEqual([]);
-  });
-
-  it("ignores a non-numeric / negative --lock-timeout value (treated as unset)", () => {
-    expect(extractLockTimeout({ extraArgs: ["--lock-timeout", "abc"] }).lockTimeoutSec).toBeUndefined();
-    expect(extractLockTimeout({ extraArgs: ["--lock-timeout", "-3"] }).lockTimeoutSec).toBeUndefined();
-  });
-});
-
-describe("buildRescueArgs", () => {
-  it("emits no args for an empty option set (script defaults apply)", () => {
-    expect(buildRescueArgs()).toEqual([]);
-  });
-
-  it("maps the prod-update shape the menubar app uses", () => {
-    const args = buildRescueArgs({
-      hqRoot: "/Users/x/HQ",
-      source: "indigoai-us/hq-core",
-      ref: "v12.3.0",
-      floorSha: "a".repeat(40),
-      assumeYes: true,
-    });
-    expect(args).toEqual([
-      "--hq-root",
-      "/Users/x/HQ",
-      "--source",
-      "indigoai-us/hq-core",
-      "--ref",
-      "v12.3.0",
-      "--floor-sha",
-      "a".repeat(40),
-      "--yes",
-    ]);
-  });
-
-  it("joins narrow paths and repeats preserve flags", () => {
-    const args = buildRescueArgs({
-      paths: ["core", ".claude"],
-      preserve: ["foo", "bar"],
-      preserveSubpaths: ["core/keep.md"],
-    });
-    expect(args).toContain("--paths");
-    expect(args[args.indexOf("--paths") + 1]).toBe("core,.claude");
-    expect(args.filter((a) => a === "--preserve")).toHaveLength(2);
-    expect(args).toContain("foo");
-    expect(args).toContain("bar");
-    expect(args).toContain("--preserve-subpath");
-    expect(args).toContain("core/keep.md");
-  });
-
-  it("passes dry-run and no-backup toggles through", () => {
-    const args = buildRescueArgs({ dryRun: true, noBackup: true, noHistoryCheck: true });
-    expect(args).toContain("--dry-run");
-    expect(args).toContain("--no-backup");
-    expect(args).toContain("--no-history-check");
-  });
-
-  it("does not emit --paths for an empty path list", () => {
-    expect(buildRescueArgs({ paths: [] })).toEqual([]);
-  });
-});
-
-describe("Windows sync path adapters", () => {
-  it("converts drive-letter and UNC rsync arguments to Cygwin paths", () => {
-    expect(toCygwinRsyncPath("C:\\HQ\\core\\")).toBe("/cygdrive/c/HQ/core/");
-    expect(toCygwinRsyncPath("D:/HQ/workspace")).toBe("/cygdrive/d/HQ/workspace");
-    expect(toCygwinRsyncPath("\\\\fileserver\\hq-share\\HQ\\")).toBe(
-      "//fileserver/hq-share/HQ/",
-    );
-  });
-
-  it("round-trips Windows-safe local names without changing canonical vault keys", () => {
-    const win32 = true;
-    expect(encodeLocalVaultSegment("core:skill", win32)).toBe("core%3Askill");
-    expect(encodeLocalVaultSegment("core%3Askill", win32)).toBe("core%253Askill");
-    expect(encodeLocalVaultSegment("core\u0000skill", win32)).toBe("core%00skill");
-    expect(decodeLocalVaultSegment("core%3Askill", win32)).toBe("core:skill");
-
-    // Pull materializes the key under a safe filename, while the journal and
-    // the following push retain the original canonical S3 key.
-    const canonicalKey = "factory:slack/apps/web/oauth-token.json";
-    const pulledLocalPath = localPathForVaultKey("C:\\HQ\\companies\\acme", canonicalKey, win32);
-    expect(pulledLocalPath).toContain("factory%3Aslack");
-    const journalKey = canonicalKey;
-    const pushedKey = vaultKeyForLocalPath("C:\\HQ\\companies\\acme", pulledLocalPath, win32);
-    expect(pushedKey).toBe(journalKey);
-  });
-});

package/src/cli/rescue.ts

@@ -1,182 +0,0 @@
-/**
- * hq rescue — re-sync a local HQ tree to an upstream hq-core release (or a
- * staging branch) WITHOUT destroying the user's local edits ("drift").
- *
- * The implementation is native TypeScript in ./rescue-core.ts (the former
- * scripts/replace-rescue.sh, ported and removed). This module owns the public
- * option surface + flag mapping and the post-rescue reindex wiring; the heavy
- * classify/overlay/stamp algorithm lives in rescue-core. BOTH consumers — the
- * HQ Sync menubar app (which spawns `hq-rescue` from this package) and
- * `@indigoai-us/hq-cli`'s `hq rescue` command — drive the exact same logic.
- *
- * Channel-agnostic: `--source <repo>` + `--ref <tag|branch>` select prod vs
- * staging, and `--floor-sha` pins the three-way history floor.
- */
-import { reindex } from "./reindex.js";
-import { runRescue } from "./rescue-core.js";
-import {
-  acquireOperationLock,
-  OperationLockedError,
-  OPERATION_LOCKED_EXIT,
-} from "../operation-lock.js";
-
-export interface RescueOptions {
-  /** HQ root to operate on. Passed as `--hq-root`. Defaults to the script's
-   *  own resolution (cwd-based) when omitted. */
-  hqRoot?: string;
-  /** Upstream repo, e.g. `indigoai-us/hq-core`. Script default:
-   *  `indigoai-us/hq-core-staging`. */
-  source?: string;
-  /** Git ref (tag or branch). Script default: `main`. */
-  ref?: string;
-  /** 40-char lowercase hex SHA pinning the three-way history floor. When
-   *  omitted the script reads the on-disk sync stamp from core/core.yaml. */
-  floorSha?: string;
-  /** Narrow the wipe set to an explicit list of top-level paths (`--paths`,
-   *  comma-joined). */
-  paths?: string[];
-  /** Extra top-level entries to always preserve (`--preserve`, repeatable). */
-  preserve?: string[];
-  /** Extra relative subpaths to carve out + restore (`--preserve-subpath`,
-   *  repeatable). */
-  preserveSubpaths?: string[];
-  /** Plan only — classify + report, change nothing on disk (`--dry-run`). */
-  dryRun?: boolean;
-  /** Skip the interactive confirmation prompt (`--yes`). Required for any
-   *  non-interactive caller. */
-  assumeYes?: boolean;
-  /** Skip the pre-op safety snapshot under ~/.hq/backups (`--no-backup`). */
-  noBackup?: boolean;
-  /** Override the backup root (`--backup-dir`). */
-  backupDir?: string;
-  /** Shallow-clone the source and skip the history-floor compare
-   *  (`--no-history-check`). */
-  noHistoryCheck?: boolean;
-  /** Cloud-update mode (`--cloud-update`). */
-  cloudUpdate?: boolean;
-  /** GitHub token forwarded to the script as `GH_TOKEN` (avoids the
-   *  anonymous-clone rate limit; required for private sources). */
-  ghToken?: string;
-  /**
-   * Bounded wait (seconds) for the per-root operation lock when a sync/reindex
-   * is already running. `0` → refuse immediately; omitted → inherit
-   * `HQ_OP_LOCK_TIMEOUT` / infinite wait. Also accepted as `--lock-timeout
-   * <secs>` inside {@link extraArgs} (the machine `hq-rescue` entrypoint
-   * forwards raw argv) — it is consumed here and never passed to the rescue
-   * script, which doesn't understand it.
-   */
-  lockTimeoutSec?: number;
-  /** Escape hatch — additional raw args appended verbatim. */
-  extraArgs?: string[];
-}
-
-/**
- * Pull `--lock-timeout <secs>` out of `extraArgs` (the raw argv the machine
- * `hq-rescue` entrypoint forwards) so it controls the operation-lock wait
- * instead of leaking to the rescue script. Returns the resolved timeout
- * (explicit `opts.lockTimeoutSec` wins) and a copy of extraArgs with the flag
- * removed.
- */
-export function extractLockTimeout(opts: RescueOptions): {
-  lockTimeoutSec: number | undefined;
-  cleanedExtraArgs: string[] | undefined;
-} {
-  const raw = opts.extraArgs;
-  if (!raw || raw.length === 0) {
-    return { lockTimeoutSec: opts.lockTimeoutSec, cleanedExtraArgs: raw };
-  }
-  const cleaned: string[] = [];
-  let fromArgs: number | undefined;
-  for (let i = 0; i < raw.length; i++) {
-    if (raw[i] === "--lock-timeout") {
-      const val = Number(raw[i + 1]);
-      if (Number.isInteger(val) && val >= 0) fromArgs = val;
-      i++; // skip the value too
-      continue;
-    }
-    cleaned.push(raw[i]);
-  }
-  // Explicit option beats the parsed flag.
-  return {
-    lockTimeoutSec: opts.lockTimeoutSec ?? fromArgs,
-    cleanedExtraArgs: cleaned,
-  };
-}
-
-export interface RescueResult {
-  /** Exit status of the underlying script (0 = success). */
-  status: number;
-}
-
-/**
- * Build the argv passed to bash (after the script path itself). Pure +
- * exported so callers and tests can assert the flag mapping without spawning.
- */
-export function buildRescueArgs(opts: RescueOptions = {}): string[] {
-  const args: string[] = [];
-  if (opts.hqRoot) args.push("--hq-root", opts.hqRoot);
-  if (opts.source) args.push("--source", opts.source);
-  if (opts.ref) args.push("--ref", opts.ref);
-  if (opts.floorSha) args.push("--floor-sha", opts.floorSha);
-  if (opts.paths && opts.paths.length > 0) args.push("--paths", opts.paths.join(","));
-  for (const p of opts.preserve ?? []) args.push("--preserve", p);
-  for (const sp of opts.preserveSubpaths ?? []) args.push("--preserve-subpath", sp);
-  if (opts.noHistoryCheck) args.push("--no-history-check");
-  if (opts.noBackup) args.push("--no-backup");
-  if (opts.backupDir) args.push("--backup-dir", opts.backupDir);
-  if (opts.cloudUpdate) args.push("--cloud-update");
-  if (opts.dryRun) args.push("--dry-run");
-  if (opts.assumeYes) args.push("--yes");
-  for (const extra of opts.extraArgs ?? []) args.push(extra);
-  return args;
-}
-
-/**
- * Run the rescue against an HQ root. Synchronous — the work is long-running
- * (clone + scan + overlay) and callers want the exit status + live output.
- * stdout/stderr are written directly so the user sees the scan log and the
- * confirmation prompt (unless `assumeYes` is set).
- */
-export function rescue(opts: RescueOptions = {}): RescueResult {
-  // Rescue is mutually exclusive with sync/reindex on this HQ root. Key the
-  // lock on the same root the rescue script resolves (cwd when --hq-root is
-  // omitted). Rescue is never the exempt push watcher, so it always locks.
-  const lockRoot = opts.hqRoot ?? process.cwd();
-  // Consume --lock-timeout from extraArgs (machine entrypoint) before it can
-  // reach the rescue script, which doesn't understand it.
-  const { lockTimeoutSec, cleanedExtraArgs } = extractLockTimeout(opts);
-  const rescueOpts: RescueOptions = { ...opts, extraArgs: cleanedExtraArgs };
-  let handle;
-  try {
-    handle = acquireOperationLock(lockRoot, "rescue", { timeoutSec: lockTimeoutSec });
-  } catch (err) {
-    if (err instanceof OperationLockedError) {
-      process.stderr.write(err.message + "\n");
-      return { status: OPERATION_LOCKED_EXIT };
-    }
-    throw err;
-  }
-  try {
-    const args = buildRescueArgs(rescueOpts);
-    const env: NodeJS.ProcessEnv = { ...process.env };
-    if (opts.ghToken) env.GH_TOKEN = opts.ghToken;
-    const { status } = runRescue(args, { env });
-    // A successful, non-dry-run rescue re-lays-down core/, so refresh the
-    // generated skill wrappers, personal-overlay mirrors, and workers registry.
-    // Best-effort + idempotent — never overrides the rescue's own exit status.
-    // repoRoot falls back to process.cwd() (reindex's default) when hqRoot is
-    // omitted, matching the rescue script's own cwd-based default. `skipLock`
-    // because we already hold the per-root lock — reindex's own acquire would
-    // otherwise see our live PID and refuse.
-    if (status === 0 && !opts.dryRun) {
-      try {
-        reindex({ repoRoot: opts.hqRoot, skipLock: true });
-      } catch {
-        // best-effort
-      }
-    }
-    return { status };
-  } finally {
-    handle.release();
-  }
-}