@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/personal-vault.ts

@@ -1,496 +0,0 @@
-/**
- * Personal-vault scope helpers — shared between the menubar runner
- * (`hq-sync-runner`) and the `hq sync` CLI so every composer of a personal
- * push uses the same exclusion list.
- *
- * The exclusion list mirrors the Rust constant of the same name in
- * `hq-sync/src-tauri/src/commands/personal.rs` so the Tauri menubar's
- * first-push and this Node engine's steady-state push enforce identical
- * scope. Every other top-level entry under hq_root (e.g. `.claude/`,
- * `knowledge/`, `modules/`, `README.md`, `.codex/`, `core/`, `data/`,
- * `personal/`) is included, subject to the usual `.hqignore` filter.
- *
- * Excluded entries (and why):
- *   - `.git`: a git repo's own metadata is hostile to multi-machine
- *     sync; .gitignore alone doesn't cover `.git/` because it's the repo
- *     itself, not a tracked path.
- *   - `companies/`: the top-level `companies/` directory is never enumerated
- *     wholesale. Team-backed companies are synced by the runner's
- *     per-membership fanout (one bucket per company). Individual
- *     `companies/{slug}/` subdirs are added back via
- *     `computePersonalCompanySubdirs()` for every LOCAL (non-cloud) company
- *     — i.e. any company that is not in the operator's team-synced membership
- *     set and is not explicitly marked `cloud: true` in `company.yaml`. Those
- *     land under the personal bucket as `companies/{slug}/...` keys. (The
- *     single `companies/manifest.yaml` is also carved in unconditionally as
- *     the routing source-of-truth.)
- *   - `repos/`, `workspace/`: per user directive — heavy local-only
- *     content (cloned remotes, session threads) that has no business in
- *     the personal vault. Three explicit sub-paths pierce this exclusion and
- *     DO round-trip: `workspace/threads/handoff.json` (+ its active thread) via
- *     {@link computeContinuityPointerPaths}, `workspace/agency/` via
- *     {@link computeAgencySyncPaths}, and `workspace/.session-logs/` (the
- *     reindex-captured Claude Code transcripts) via
- *     {@link computeSessionLogsSyncPaths}.
- *
- * Note: `core/`, `data/`, and `personal/` were previously excluded but are
- * INCLUDED as of user directive 2026-05-13. `core/` ships the hq-core
- * scaffold — policies/, settings/, skills/, workers/, plus the rules
- * manifest at core/core.yaml. `data/` and `personal/` carry per-user data,
- * policies, hooks, and skills that follow the user across machines. A
- * root-level `core.yaml` (at hq_root, distinct from `core/core.yaml`) is
- * filtered layout-aware in `createIgnoreFilter`: excluded only when
- * `core/core.yaml` exists (v15+, where root core.yaml is a stale duplicate);
- * on v12–v14 roots with no `core/core.yaml`, the root `core.yaml` IS the
- * scaffold/version manifest and round-trips like any other top-level file.
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import { isGeneratedCommandWrapperPath } from "./personal-vault-exclusions.js";
-
-export const PERSONAL_VAULT_EXCLUDED_TOP_LEVEL: readonly string[] = [
-  ".git",
-  "companies",
-  "repos",
-  "workspace",
-];
-
-/**
- * Company slugs that are never eligible for the personal-bucket fallback,
- * regardless of their `cloud:` marker. `_template` is the scaffolding
- * source for `/newcompany` — copying it into the personal vault would
- * pollute every machine's vault with the template tree.
- */
-export const PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS: readonly string[] = [
-  "_template",
-];
-
-export interface PersonalVaultOptions {
-  /**
-   * Slugs of companies that already have their own team bucket (i.e. the
-   * operator has an active Membership row for them). These are excluded
-   * from the personal-bucket fallback so a single company's content never
-   * ends up in two buckets. This membership-derived set is the single
-   * "cloud-backed" signal: when a company becomes cloud-true (gains an
-   * active membership), its slug lands here and the personal vault both
-   * stops pushing it and decommissions its stale copy.
-   */
-  teamSyncedSlugs?: ReadonlySet<string>;
-}
-
-/**
- * Compute absolute paths to share for the personal vault.
- *
- * Two sources are concatenated:
- *   1. Every top-level entry under `hqRoot` whose basename is NOT in
- *      `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL`.
- *   2. Every local (non-cloud) `companies/{slug}/` subdir, after excluding
- *      (a) `_template`, (b) slugs already in `opts.teamSyncedSlugs`
- *      (cloud-backed — they sync to their own team bucket), (c) slugs with
- *      `cloud_uid: cmp_*` in `companies/manifest.yaml`, and (d) any
- *      subdir explicitly marked `cloud: true` in its `company.yaml`.
- *      A company with no `company.yaml` (or one without a `cloud:` marker)
- *      is included — local companies sync to the personal vault by default.
- *
- * Order is whatever `fs.readdirSync` returns — share() doesn't care, and
- * the per-file walk inside share() handles recursion uniformly. Missing
- * hqRoot returns []; callers treat that as "no personal content to push"
- * rather than a hard error.
- */
-/**
- * S3 key (hq-root-relative, forward-slash) of the companies manifest — the
- * routing source-of-truth — carved into the personal vault even though
- * `companies/` is otherwise excluded. Exported so the PULL plan applies the
- * SAME exemption: skipping it on the pull leaves it unjournaled, which re-fires
- * a transient push-side conflict every sync (no journal baseline).
- */
-export const PERSONAL_VAULT_MANIFEST_KEY = "companies/manifest.yaml";
-
-/**
- * Return true for a path where HQ materializes generated links into the
- * release-owned `core/` surface. The caller must additionally establish that
- * the entry is a symlink: regular files in these namespaces remain canonical
- * core content and must continue to sync.
- *
- * The generated links point at canonical content in `personal/` or
- * `core/packages/`. Reindex / package wiring may remove and recreate them, so
- * treating the links themselves as personal-vault data creates a pull →
- * reindex → pull oscillation.
- */
-export function isGeneratedCoreMirrorKey(key: string): boolean {
-  const parts = key.split("\\").join("/").replace(/^\.\//, "").split("/");
-  return (
-    parts.length >= 3 &&
-    parts[0] === "core" &&
-    (parts[1] === "knowledge" ||
-      parts[1] === "policies" ||
-      parts[1] === "workers" ||
-      parts[1] === "settings")
-  );
-}
-
-/**
- * Release-owned scaffold and reindex-generated wrappers must never be
- * delete-propagated from the personal vault. They are recreated locally by a
- * release or `hq reindex`, so an ordinary local absence is not user intent.
- */
-export function isPersonalVaultDeletionExcluded(key: string): boolean {
-  const normalized = key.split("\\").join("/").replace(/^\.\//, "");
-  return (
-    normalized === "core" ||
-    normalized.startsWith("core/") ||
-    normalized === ".claude/skills" ||
-    normalized.startsWith(".claude/skills/") ||
-    // reindex surfaces slash commands as `.claude/commands/<ns>:<cmd>.md`
-    // links. Unlike `.claude/skills/` (entirely generated, so blanket-excluded
-    // above), `.claude/commands/` may ALSO hold hand-authored native commands
-    // whose deletion IS user intent — so protect ONLY the reindex-generated
-    // `<ns>:<cmd>` links from delete-propagation, matching the same shape the
-    // push-side `generated-command-wrapper` exclusion filters.
-    isGeneratedCommandWrapperPath(normalized)
-  );
-}
-
-export function computePersonalVaultPaths(
-  hqRoot: string,
-  opts: PersonalVaultOptions = {},
-): string[] {
-  let entries: string[];
-  try {
-    entries = fs.readdirSync(hqRoot);
-  } catch {
-    return [];
-  }
-  const topLevel = entries
-    .filter((name) => !PERSONAL_VAULT_EXCLUDED_TOP_LEVEL.includes(name))
-    .map((name) => path.join(hqRoot, name));
-  // companies/manifest.yaml is the routing source-of-truth (which slugs
-  // exist, which are cloud-backed, what their UIDs are). It must travel
-  // with every machine's personal vault so a fresh install can enumerate
-  // expected non-cloud companies before its first pull. Special-cased
-  // because the parent `companies/` is in PERSONAL_VAULT_EXCLUDED_TOP_LEVEL
-  // (we never enumerate the whole companies tree wholesale).
-  const manifest: string[] = [];
-  const manifestPath = path.join(hqRoot, PERSONAL_VAULT_MANIFEST_KEY);
-  try {
-    if (fs.statSync(manifestPath).isFile()) {
-      manifest.push(manifestPath);
-    }
-  } catch {
-    // Missing or unreadable — silently omit. Callers tolerate empty arrays.
-  }
-  const companySubdirs = computePersonalCompanySubdirs(
-    hqRoot,
-    opts.teamSyncedSlugs,
-  );
-  const continuity = computeContinuityPointerPaths(hqRoot);
-  const agency = computeAgencySyncPaths(hqRoot);
-  const sessionLogs = computeSessionLogsSyncPaths(hqRoot);
-  return [
-    ...topLevel,
-    ...manifest,
-    ...companySubdirs,
-    ...continuity,
-    ...agency,
-    ...sessionLogs,
-  ];
-}
-
-/**
- * Fixed relative path (forward-slash, hq-root-relative) of the session
- * continuity pointer. The continuity pointer is the ONE file under the
- * otherwise machine-local `workspace/` that must travel across machines:
- * `/handoff` writes it on machine A so a fresh session on machine B can
- * resume via `/startwork`. See {@link computeContinuityPointerPaths}.
- */
-export const CONTINUITY_POINTER_REL = "workspace/threads/handoff.json";
-
-/**
- * Compute the absolute paths of the session-continuity pointer carve-out:
- * `workspace/threads/handoff.json` plus the single thread file it points to.
- *
- * `workspace/` is in {@link PERSONAL_VAULT_EXCLUDED_TOP_LEVEL} — it is
- * machine-local by design (session scratch, locks, reports, the full thread
- * history). The continuity pointer is the one exception: without it a
- * `/handoff` on one machine never reaches a second machine, so the session
- * pointer doesn't follow the user even though the durable output already
- * syncs. This carve-out pierces the exclusion for EXACTLY two files and
- * nothing else, mirroring the `companies/manifest.yaml` special-case above
- * (a single file pushed back in despite its parent dir being excluded).
- *
- * The "active thread file" is not a fixed name — it is resolved from
- * `handoff.json.thread_path` (the pointer the finalize script writes). We
- * read + parse `handoff.json`, then include `thread_path` ONLY when it is a
- * relative path that resolves to an existing regular file strictly within
- * `<hqRoot>/workspace/threads/`. This containment check is a hard security
- * boundary: a malformed or tampered `handoff.json` must never be able to
- * smuggle an arbitrary file (e.g. `../../.env`, an absolute path, or a
- * symlink escaping the threads dir) into the personal vault.
- *
- * Fail-soft throughout: a missing/unreadable/malformed `handoff.json`, or an
- * out-of-bounds / missing `thread_path`, silently degrades to "include
- * whatever is valid" (handoff.json alone, or `[]`). Callers tolerate empty
- * arrays — same contract as the manifest special-case.
- */
-export function computeContinuityPointerPaths(hqRoot: string): string[] {
-  const out: string[] = [];
-  const threadsDir = path.join(hqRoot, "workspace", "threads");
-  const handoffPath = path.join(threadsDir, "handoff.json");
-
-  let raw: string;
-  try {
-    if (!fs.statSync(handoffPath).isFile()) return out;
-    raw = fs.readFileSync(handoffPath, "utf8");
-  } catch {
-    // No pointer on this machine yet (or unreadable) — nothing to carry.
-    return out;
-  }
-  out.push(handoffPath);
-
-  // Resolve the active thread file from the pointer's `thread_path`. Any
-  // failure leaves the pointer itself in `out` and skips the thread body —
-  // the next handoff (or a peer's push) re-converges it.
-  let threadPath: unknown;
-  try {
-    threadPath = (JSON.parse(raw) as { thread_path?: unknown })?.thread_path;
-  } catch {
-    return out;
-  }
-  if (typeof threadPath !== "string" || threadPath.length === 0) return out;
-
-  // Containment: the resolved file must live strictly inside the threads dir.
-  // Reject absolute paths, traversal, and symlink escapes. thread_path is
-  // hq-root-relative as written by handoff-finalize.sh, so resolve against
-  // hqRoot and re-check the realpath is still under the threads dir.
-  if (path.isAbsolute(threadPath)) return out;
-  const resolvedThreads = path.resolve(threadsDir);
-  const candidate = path.resolve(hqRoot, threadPath);
-  const withinThreads = (p: string): boolean =>
-    p === resolvedThreads || p.startsWith(resolvedThreads + path.sep);
-  if (!withinThreads(candidate)) return out;
-  try {
-    const realHqRoot = fs.realpathSync.native(hqRoot);
-    const expectedRealThreads = path.join(realHqRoot, "workspace", "threads");
-    const realThreads = fs.realpathSync.native(threadsDir);
-    if (realThreads !== expectedRealThreads) return out;
-    const withinRealThreads = (p: string): boolean =>
-      p === realThreads || p.startsWith(realThreads + path.sep);
-    const real = fs.realpathSync.native(candidate);
-    if (!withinRealThreads(real)) return out;
-    if (!fs.statSync(real).isFile()) return out;
-  } catch {
-    // Pointer references a thread file that doesn't exist here — skip it.
-    return out;
-  }
-  out.push(candidate);
-  return out;
-}
-
-/**
- * Fixed relative path (forward-slash, hq-root-relative) of the agency
- * workspace subtree. See {@link computeAgencySyncPaths}.
- */
-export const AGENCY_SYNC_REL = "workspace/agency";
-
-/**
- * Compute the absolute path of the agency-workspace carve-out:
- * `workspace/agency/` (the whole subtree).
- *
- * Like the session-continuity pointer above, this pierces the `workspace/`
- * top-level exclusion for ONE specific subtree. hq-pack-agency teams keep
- * their cross-session chat.jsonl inboxes and roster/state under
- * `workspace/agency/<company>/<team>/`; that state must travel across machines
- * so an agency team picked up on machine B sees the same conversation and
- * roster it had on machine A. The rest of `workspace/` (session scratch,
- * locks, reports, full thread history) stays machine-local.
- *
- * Returns the directory path when it exists; share()'s per-file walk handles
- * recursion, and the nested personal-vault exclusions still apply to files
- * inside it (e.g. a stray `node_modules/` or `.env`). Fail-soft: a missing or
- * unreadable `workspace/agency/` returns []. Callers tolerate empty arrays —
- * same contract as the manifest + continuity special-cases.
- */
-export function computeAgencySyncPaths(hqRoot: string): string[] {
-  const agencyDir = path.join(hqRoot, "workspace", "agency");
-  try {
-    if (fs.statSync(agencyDir).isDirectory()) return [agencyDir];
-  } catch {
-    // No agency workspace on this machine — nothing to carry.
-  }
-  return [];
-}
-
-/**
- * Fixed relative path (forward-slash, hq-root-relative) of the session-logs
- * subtree. See {@link computeSessionLogsSyncPaths}.
- */
-export const SESSION_LOGS_SYNC_REL = "workspace/.session-logs";
-
-/**
- * Compute the absolute path of the session-logs carve-out:
- * `workspace/.session-logs/` (the whole subtree).
- *
- * `hq reindex` copies this HQ root's Claude Code session transcripts here (see
- * reindex's copySessionLogs). Like the agency carve-out above, this pierces the
- * `workspace/` top-level exclusion for ONE specific subtree so those raw
- * transcripts round-trip to the personal vault / S3 — the operator's explicit
- * directive is that the session logs travel with the vault. The rest of
- * `workspace/` (session scratch, locks, reports, worktrees) stays machine-local.
- *
- * Returns the directory path when it exists; share()'s per-file walk handles
- * recursion, and the nested personal-vault exclusions still apply to files
- * inside it. Fail-soft: a missing or unreadable `workspace/.session-logs/`
- * returns []. Callers tolerate empty arrays — same contract as the manifest,
- * continuity, and agency special-cases.
- */
-export function computeSessionLogsSyncPaths(hqRoot: string): string[] {
-  const sessionLogsDir = path.join(hqRoot, "workspace", ".session-logs");
-  try {
-    if (fs.statSync(sessionLogsDir).isDirectory()) return [sessionLogsDir];
-  } catch {
-    // No session logs captured on this machine yet — nothing to carry.
-  }
-  return [];
-}
-
-/**
- * Discover `companies/{slug}/` subdirs that should sync to the personal
- * bucket as a fallback for companies the operator has not designated as
- * team-backed. Filter rules (all must hold):
- *
- *   1. The subdir is a directory (skip stray files).
- *   2. The slug is NOT in `PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS`
- *      (currently just `_template`).
- *   3. The slug is NOT in `teamSyncedSlugs` (membership-backed slugs sync
- *      to their own bucket and must not be double-written).
- *   4. The slug is NOT listed with a `cloud_uid: cmp_*` in
- *      `companies/manifest.yaml`. Full-HQ agent boxes often run
- *      `--personal` alone (no company fanout targets), so
- *      `teamSyncedSlugs` is empty even though indigo (etc.) is
- *      cloud-backed; without this check the multi-GB company tree is
- *      re-mirrored into the agent personal vault every ritual and
- *      times out the 180s personal push.
- *   5. `companies/{slug}/company.yaml` does NOT contain an explicit
- *      `cloud: true` line. Local companies sync to the personal vault by
- *      default, so a missing/markerless `company.yaml` is INCLUDED; only an
- *      explicit `cloud: true` marker opts the directory OUT (belt-and-braces
- *      with `teamSyncedSlugs` / manifest `cloud_uid` for a company designated
- *      cloud-backed before its membership has resolved).
- *
- * Returns absolute paths.
- */
-export function computePersonalCompanySubdirs(
-  hqRoot: string,
-  teamSyncedSlugs: ReadonlySet<string> = new Set(),
-): string[] {
-  const companiesRoot = path.join(hqRoot, "companies");
-  let slugs: string[];
-  try {
-    slugs = fs.readdirSync(companiesRoot);
-  } catch {
-    return [];
-  }
-  // Manifest cloud_uid is the durable routing signal for cloud-backed
-  // companies. Prefer it over relying solely on runner membership fanout
-  // (empty for --personal-only agent ritual) or company.yaml (often missing
-  // on full-HQ agent boxes that never ran /designate-team locally).
-  const cloudManifestSlugs = readCloudBackedSlugsFromManifest(hqRoot);
-  const eligible: string[] = [];
-  for (const slug of slugs) {
-    if (PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS.includes(slug)) continue;
-    if (teamSyncedSlugs.has(slug)) continue;
-    if (cloudManifestSlugs.has(slug)) continue;
-    const subdir = path.join(companiesRoot, slug);
-    let isDir = false;
-    try {
-      isDir = fs.statSync(subdir).isDirectory();
-    } catch {
-      continue;
-    }
-    if (!isDir) continue;
-    if (companyHasCloudTrueMarker(subdir)) continue;
-    eligible.push(subdir);
-  }
-  return eligible;
-}
-
-/**
- * Slugs whose `companies/manifest.yaml` entry carries a `cloud_uid: cmp_*`.
- * These are cloud-backed team companies and must not personal-vault mirror.
- *
- * Lightweight line parse (no YAML dep): fail-open on missing/unreadable
- * manifest → empty set → companies stay eligible for personal fallback.
- * Only `cmp_*` uids count (same rule as company-resolver / telemetry).
- */
-export function readCloudBackedSlugsFromManifest(hqRoot: string): Set<string> {
-  const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
-  let text: string;
-  try {
-    text = fs.readFileSync(manifestPath, "utf8");
-  } catch {
-    return new Set();
-  }
-  const out = new Set<string>();
-  let currentSlug: string | null = null;
-  let inCompanies = false;
-  for (const line of text.split(/\r?\n/)) {
-    // Top-level key (no indent). Only track entries under `companies:`.
-    if (/^[A-Za-z0-9_.-]+:\s*(?:#.*)?$/.test(line)) {
-      inCompanies = /^companies:\s*(?:#.*)?$/.test(line);
-      currentSlug = null;
-      continue;
-    }
-    if (!inCompanies) continue;
-    // Two-space indent: company slug under companies:
-    const slugMatch = /^ {2}([A-Za-z0-9][A-Za-z0-9_-]*):\s*(?:#.*)?$/.exec(line);
-    if (slugMatch) {
-      currentSlug = slugMatch[1];
-      continue;
-    }
-    if (
-      currentSlug &&
-      /^\s{2,}cloud_uid:\s*cmp_[A-Za-z0-9]+\b/.test(line)
-    ) {
-      out.add(currentSlug);
-      // Keep currentSlug so a later key on the same company is fine; next
-      // sibling slug line will replace it.
-    }
-  }
-  return out;
-}
-
-/**
- * True iff `{subdir}/company.yaml` exists and contains an explicit
- * top-level `cloud: true` line — the marker `/designate-team` writes when a
- * company is promoted to cloud-backed. That command's awk is the only
- * producer of this key, and it always emits `cloud: <bool>` at column zero
- * with no indentation, no quoting, lowercase boolean, optional trailing
- * comment. A `true` marker excludes the directory from the personal-vault
- * fallback; everything else (missing file, no marker, `cloud: false`)
- * leaves it eligible — local companies sync to the personal vault by default.
- *
- * Anchored at column 0 deliberately:
- *   - rejects `meta:\n  cloud: true` (nested key, would be `meta.cloud`
- *     in a real YAML parser — false positive for us if we allowed
- *     arbitrary leading whitespace)
- *   - rejects `- cloud: true` (list item, also a nested key)
- *   - rejects flow mappings like `{ cloud: true }`
- *
- * Other intentional rejections (lowercase `true` only, no YAML-alt
- * boolean spellings): `cloud: True`, `cloud: TRUE`, `cloud: yes`,
- * `cloud: on`, `cloud: "true"`, `cloud: 'true'`. None of these are
- * produced by `/designate-team`; matching them risks confusing
- * round-trips with hand-edited YAML. (A misspelled marker fails OPEN —
- * the company stays in the personal vault — which is the safe default.)
- */
-function companyHasCloudTrueMarker(subdir: string): boolean {
-  const yamlPath = path.join(subdir, "company.yaml");
-  let text: string;
-  try {
-    text = fs.readFileSync(yamlPath, "utf8");
-  } catch {
-    return false;
-  }
-  return /^cloud:\s*true\b/m.test(text);
-}