@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/lib/cloud-authoritative.test.ts

@@ -1,45 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { isCloudAuthoritative } from "./cloud-authoritative.js";
-
-describe("isCloudAuthoritative", () => {
-  it("matches server-regenerated root files (both path forms)", () => {
-    for (const p of [
-      "companies/indigo/company-brief.md",
-      "company-brief.md",
-      "companies/acme/board.json",
-      "board.json",
-    ]) {
-      expect(isCloudAuthoritative(p)).toBe(true);
-    }
-  });
-
-  it("matches the pipeline-authored dirs", () => {
-    for (const p of [
-      "companies/indigo/ontology/entities/concept/grok.md",
-      "ontology/entities/person/x.md",
-      "companies/indigo/signals/slack-dm/action_item/a.md",
-      "signals/decision/b.md",
-      "companies/indigo/sources/slack/T1-2.md",
-      "sources/meetings/m.md",
-    ]) {
-      expect(isCloudAuthoritative(p)).toBe(true);
-    }
-  });
-
-  it("does NOT match client-owned files", () => {
-    for (const p of [
-      "companies/indigo/skills/work-mesh/SKILL.md",
-      "companies/indigo/projects/company-agents/release/index.html",
-      "companies/indigo/workers/hq-notify/emails/notice.template.html",
-      "companies/indigo/knowledge/readme.md",
-      "company-brief.md.conflict-2026-06-18T00-00-00Z-501bc8.md", // a mirror, not the brief
-      "docs/handoff.md",
-    ]) {
-      expect(isCloudAuthoritative(p)).toBe(false);
-    }
-  });
-
-  it("normalizes windows separators", () => {
-    expect(isCloudAuthoritative("companies\\indigo\\ontology\\entities\\x.md")).toBe(true);
-  });
-});

package/src/lib/cloud-authoritative.ts

@@ -1,59 +0,0 @@
-/**
- * Cloud-authoritative vault paths — files the SERVER regenerates and owns, so
- * on a sync conflict the cloud version always wins (pull-wins) and NO
- * `.conflict-` mirror is minted.
- *
- * Why this exists
- * ---------------
- * Some vault files are written/regenerated server-side on a schedule, not by
- * the client:
- *   - `company-brief.md`  — rewritten by the ontology gardener's brief-generator
- *                           on every run.
- *   - `board.json`        — rewritten by board automation.
- *   - `ontology/**`, `signals/**`, `sources/**` — the gardener / sources+signals
- *                           pipeline are the sole authors; clients only consume.
- *
- * A client that also holds these locally diverges from the server copy on
- * essentially every sync. Under `--on-conflict keep` (what outposts run) that
- * produced two compounding bugs:
- *   1. CONFLICT LOOP — each sync minted a fresh `<file>.conflict-<ts>-<machine>`
- *      mirror that was never cleaned up (e.g. ~50 `company-brief.md.conflict-*`
- *      piled up on an outpost over a few days).
- *   2. SILENT DRIFT — the keep path stamped the journal with the REMOTE etag
- *      while leaving the divergent LOCAL content in place, so the journal
- *      reported "in sync" forever and the file never reconciled.
- *
- * Treating these paths as cloud-authoritative resolves both: the conflict path
- * short-circuits to a normal overwrite-from-cloud (correct journal stamp, no
- * mirror), because for a server-owned file the cloud copy is the truth.
- *
- * Extending
- * ---------
- * Add a pattern to {@link CLOUD_AUTHORITATIVE_PATTERNS}. Patterns are matched
- * against the VAULT-RELATIVE path (a leading `companies/<slug>/` is stripped
- * first), so both call sites — the pull leg (hqRoot-relative
- * `companies/<slug>/…`) and the push leg (company-relative `…`) — work.
- */
-
-/** Vault-relative patterns for server-owned, cloud-wins files. */
-export const CLOUD_AUTHORITATIVE_PATTERNS: readonly RegExp[] = [
-  /^company-brief\.md$/,
-  /^board\.json$/,
-  /^ontology\//,
-  /^signals\//,
-  /^sources\//,
-];
-
-/**
- * True iff `relPath` is a server-regenerated, cloud-authoritative vault file.
- * Accepts either an hqRoot-relative path (`companies/<slug>/…`) or a
- * vault-relative path (`…`); Windows separators are normalized.
- */
-export function isCloudAuthoritative(relPath: string): boolean {
-  const vaultRel = relPath
-    .split("\\")
-    .join("/")
-    .replace(/^\.?\//, "")
-    .replace(/^companies\/[^/]+\//, "");
-  return CLOUD_AUTHORITATIVE_PATTERNS.some((re) => re.test(vaultRel));
-}

package/src/lib/conflict-file.ts

@@ -1,86 +0,0 @@
-/**
- * Conflict file naming + writing.
- *
- * When share/sync detects divergence, the cloud's version of the file is
- * written next to the original with a name encoding the timestamp and the
- * machine that detected the conflict. Lets multiple machines independently
- * surface their own conflicts without name collisions, and lets the user
- * (or the `/resolve-conflicts` HQ skill) see local + cloud side-by-side
- * in their file browser.
- *
- * Machine-id provisioning lives in `./machine-id.ts` — hq-cloud owns the
- * source-of-truth file `<hqRoot>/.hq/machine-id` so every sync host
- * (including Linux outposts with no menubar app) gets a stable id. This
- * module re-exports `readShortMachineId` for back-compat with existing
- * callers; new callers should import directly from `./machine-id.js`.
- */
-
-import * as fs from "fs";
-import * as path from "path";
-
-import { localPathForVaultKey } from "../local-path-codec.js";
-
-export { readShortMachineId, getOrCreateMachineId } from "./machine-id.js";
-
-/**
- * Build the conflict file path for an original. ISO uses `-` instead of
- * `:` so the result is filesystem-safe on every OS, and the original
- * extension is preserved at the end so editors syntax-highlight correctly.
- *
- *   knowledge/notes.md, 2026-04-27T22:05:14Z, abc123
- *     → knowledge/notes.md.conflict-2026-04-27T22-05-14Z-abc123.md
- *
- *   projects/foo/prd.json, ..., abc123
- *     → projects/foo/prd.json.conflict-...-abc123.json
- *
- * Files without an extension get the `.conflict-...` suffix appended verbatim.
- */
-export function buildConflictPath(
-  originalRelative: string,
-  detectedAt: string,
-  shortMachineId: string,
-): string {
-  const safeTs = detectedAt.replace(/:/g, "-").replace(/\.\d+/, "");
-  const ext = path.extname(originalRelative); // ".md" or "" if none
-  // The full original path is preserved (extension and all) so users can
-  // visually pair `notes.md` with `notes.md.conflict-…md` in their file
-  // browser. The trailing `<ext>` after the timestamp keeps the file
-  // syntax-highlighted in editors that key off the final extension.
-  const suffix = `.conflict-${safeTs}-${shortMachineId}${ext}`;
-  return `${originalRelative}${suffix}`;
-}
-
-/**
- * Write the cloud-side bytes to the conflict path. Creates parent dirs as
- * needed (the conflict file always lives next to the original, so the
- * parent already exists in the steady-state — but defense-in-depth).
- */
-export function writeConflictFile(
-  hqRoot: string,
-  conflictRelative: string,
-  contents: Buffer,
-): void {
-  // Codec boundary: conflict paths are canonical (hq-root-relative,
-  // forward-slash) keys, so the mirror must land at the encoded local name
-  // on win32 — a raw join of a colon key can never be created there.
-  const abs = localPathForVaultKey(hqRoot, conflictRelative);
-  fs.mkdirSync(path.dirname(abs), { recursive: true });
-  fs.writeFileSync(abs, contents);
-}
-
-/**
- * Stable conflict ID — used to dedupe re-detections of the same conflict.
- * Re-running sync after a conflict but before the user has resolved should
- * NOT pile up duplicate entries. The id is derived from the original path
- * and the detection timestamp; if the same original conflicts twice with
- * the user resolving in between, that's a new id (different timestamp),
- * which is correct.
- */
-export function buildConflictId(
-  originalRelative: string,
-  detectedAt: string,
-): string {
-  const safeTs = detectedAt.replace(/:/g, "-").replace(/\.\d+/, "");
-  const safePath = originalRelative.replace(/[/\\.]/g, "-");
-  return `${safePath}-${safeTs}`;
-}

package/src/lib/conflict-index.ts

@@ -1,289 +0,0 @@
-/**
- * Conflict index — durable record of pending divergences awaiting resolution.
- *
- * Lives at `<hq_root>/.hq-conflicts/index.json` (inside HQ content, NOT in
- * `~/.hq/`). Two reasons it sits in HQ content rather than in the state dir:
- *   1. The `/resolve-conflicts` HQ skill discovers it relative to the user's
- *      HQ folder — that's the user's mental anchor for "where my files are."
- *   2. The conflict-side files themselves live in HQ content, so the index
- *      and the files it references stay co-located. If the user moves HQ,
- *      the index moves with it.
- *
- * Excluded from cross-machine sync via `.hqignore` — each machine resolves
- * its own queue. We never propagate conflict files (they'd just create more
- * conflicts on the other side).
- *
- * Writes are atomic (tmp + rename). The resolution skill mutates this file
- * mid-walk; a torn write would corrupt the only record of pending conflicts
- * and could lose track of files we'd written to disk. Higher stakes than the
- * journal, which the next sync can rebuild.
- */
-
-import * as crypto from "crypto";
-import * as fs from "fs";
-import * as path from "path";
-import { localPathForVaultKey } from "../local-path-codec.js";
-import type { ConflictIndex, ConflictIndexEntry } from "../types.js";
-
-const CONFLICTS_DIR = ".hq-conflicts";
-const INDEX_FILENAME = "index.json";
-
-/**
- * Absolute path to the conflict index for a given HQ root.
- */
-export function getConflictIndexPath(hqRoot: string): string {
-  return path.join(hqRoot, CONFLICTS_DIR, INDEX_FILENAME);
-}
-
-/**
- * Read the conflict index. Returns an empty index if the file doesn't exist
- * yet (first-conflict-ever case).
- *
- * Throws on corrupt JSON — we deliberately don't auto-repair, since the only
- * record of pending conflicts is too important to silently overwrite. The
- * `/resolve-conflicts` skill surfaces this case to the user with a manual
- * inspection prompt.
- */
-export function readConflictIndex(hqRoot: string): ConflictIndex {
-  const indexPath = getConflictIndexPath(hqRoot);
-  if (!fs.existsSync(indexPath)) {
-    return { version: 1, conflicts: [] };
-  }
-  const raw = fs.readFileSync(indexPath, "utf-8");
-  const parsed = JSON.parse(raw) as ConflictIndex;
-  // Defensive: an empty file or wrong-shape JSON shouldn't crash callers.
-  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.conflicts)) {
-    return { version: 1, conflicts: [] };
-  }
-  return parsed;
-}
-
-/**
- * Atomically write the conflict index. Writes to `<index>.tmp.<random>` then
- * renames into place — `rename(2)` is atomic on POSIX, so a crash mid-write
- * leaves either the old file or the new one, never a half-written one.
- *
- * Always sorts conflicts by `detectedAt` ascending before writing — keeps
- * the file diff-friendly across runs and makes "oldest-first walk" the
- * natural read order in the resolution skill.
- */
-export function writeConflictIndex(
-  hqRoot: string,
-  index: ConflictIndex,
-): void {
-  const indexPath = getConflictIndexPath(hqRoot);
-  fs.mkdirSync(path.dirname(indexPath), { recursive: true });
-
-  const sorted: ConflictIndex = {
-    version: index.version,
-    conflicts: [...index.conflicts].sort((a, b) =>
-      a.detectedAt.localeCompare(b.detectedAt),
-    ),
-  };
-
-  // Random suffix in tmp name avoids collision if two sync runs ever overlap
-  // (shouldn't happen — the runner serializes — but cheap insurance).
-  const tmpPath = `${indexPath}.tmp.${crypto.randomBytes(6).toString("hex")}`;
-  fs.writeFileSync(tmpPath, JSON.stringify(sorted, null, 2));
-  fs.renameSync(tmpPath, indexPath);
-}
-
-/**
- * Idempotent append. If an entry with the same `id` already exists (same
- * original path, same detection timestamp), update it in place rather than
- * duplicating. This matters because re-running sync after a conflict but
- * before resolution will re-detect the same divergence — without dedup the
- * index would grow unboundedly.
- *
- * The "update in place" path also covers the case where the cloud advanced
- * again between detections: we want the latest `remoteVersionId` and
- * `remoteHash` so the resolution skill shows the user the *current* cloud
- * state, not stale data from the first detection.
- */
-export function appendConflictEntry(
-  hqRoot: string,
-  entry: ConflictIndexEntry,
-): void {
-  const index = readConflictIndex(hqRoot);
-  const existingIdx = index.conflicts.findIndex((c) => c.id === entry.id);
-  if (existingIdx >= 0) {
-    index.conflicts[existingIdx] = entry;
-  } else {
-    index.conflicts.push(entry);
-  }
-  writeConflictIndex(hqRoot, index);
-}
-
-/**
- * Remove an entry by id. Used by the `/resolve-conflicts` skill after the
- * user picks a resolution and the conflict file is cleaned up. No-op if the
- * id isn't present (e.g. user manually removed the file then re-ran the
- * skill — we want that to be a clean exit, not an error).
- */
-export function removeConflictEntry(hqRoot: string, id: string): void {
-  const index = readConflictIndex(hqRoot);
-  const filtered = index.conflicts.filter((c) => c.id !== id);
-  if (filtered.length === index.conflicts.length) return;
-  writeConflictIndex(hqRoot, { version: index.version, conflicts: filtered });
-}
-
-/** Summary of what a {@link pruneConflictIndex} pass reclaimed. */
-export interface PruneConflictIndexResult {
-  /** Rows dropped because their `.conflict-*` mirror no longer exists. */
-  prunedOrphans: number;
-  /** Rows dropped because the original file and its mirror are byte-identical. */
-  prunedIdentical: number;
-  /** Byte-identical mirror files deleted from disk during the pass. */
-  removedMirrors: number;
-  /** Rows kept (genuine divergence, or unprovable — fail-safe retained). */
-  kept: number;
-  /**
-   * Up to 10 ORIGINAL (non-mirror) paths of the kept rows, for a
-   * post-sync reconcile surface (`conflicts-remaining`). Empty when
-   * `kept === 0`. Lets a caller name the preserved conflict variants a human
-   * still has to resolve without re-reading the index. feedback_d2082110.
-   */
-  keptSamplePaths: string[];
-}
-
-/**
- * Byte-identity check used by the prune pass. Symlink-aware: two symlinks are
- * identical iff their link targets match (mirroring how the detector hashes a
- * symlink record — `hashSymlinkTarget`, not the followed content). A symlink
- * compared against a regular file is never identical. Regular files reject on a
- * size mismatch first (cheap), then compare full bytes.
- *
- * Throws if either side can't be read — callers treat that as "unprovable" and
- * keep the entry rather than risk dropping a real conflict.
- */
-function entryFilesAreIdentical(
-  aPath: string,
-  aStat: fs.Stats,
-  bPath: string,
-  bStat: fs.Stats,
-): boolean {
-  const aLink = aStat.isSymbolicLink();
-  const bLink = bStat.isSymbolicLink();
-  if (aLink || bLink) {
-    if (aLink !== bLink) return false;
-    return fs.readlinkSync(aPath) === fs.readlinkSync(bPath);
-  }
-  if (aStat.size !== bStat.size) return false;
-  return fs.readFileSync(aPath).equals(fs.readFileSync(bPath));
-}
-
-/**
- * Garbage-collect the conflict index so it self-heals instead of growing
- * without bound. Before this pass existed the ledger only ever shrank when a
- * human resolved a conflict via `/resolve-conflicts`; every false positive and
- * every orphaned row lingered forever, so the index over-reported the real
- * pending-conflict count (the menubar's journal-derived count stayed correct,
- * but `.hq-conflicts/index.json` did not).
- *
- * Two classes of entry are dropped — both provably not a pending conflict:
- *
- *   1. **Orphaned** — the `.conflict-*` mirror file is gone from disk. The
- *      mirror is the only artifact a human resolves against; once it's missing
- *      the row can never be acted on, so it's pure litter (the "missing-cloud"
- *      rows operators reported climbing into the dozens).
- *
- *   2. **Byte-identical false positives** — the original file and its conflict
- *      mirror both still exist and are byte-for-byte identical. The mirror
- *      holds the remote bytes captured at detection time, so identical bytes
- *      mean there was never a real divergence (this is exactly the manual
- *      safe-purge operators have been doing by hand). The stale mirror file is
- *      deleted and the row dropped.
- *
- * Conservative by construction — an entry is kept whenever it might be a real
- * conflict: the original file is missing (a genuine local-delete-vs-remote
- * divergence), the bytes differ, or either side can't be read. The index file
- * is only rewritten when at least one row is actually dropped, so a clean
- * ledger keeps its mtime untouched.
- */
-export function pruneConflictIndex(hqRoot: string): PruneConflictIndexResult {
-  const result: PruneConflictIndexResult = {
-    prunedOrphans: 0,
-    prunedIdentical: 0,
-    removedMirrors: 0,
-    kept: 0,
-    keptSamplePaths: [],
-  };
-
-  const index = readConflictIndex(hqRoot);
-  if (index.conflicts.length === 0) return result;
-
-  const kept: ConflictIndexEntry[] = [];
-  const mirrorsToRemove: string[] = [];
-
-  for (const entry of index.conflicts) {
-    // Codec boundary: index rows store canonical (hq-root-relative) keys, so
-    // both probes must resolve through the codec — a raw join of a win32
-    // colon key always lstat-fails, which would mis-classify a live encoded
-    // mirror as an orphaned row and silently drop it.
-    const mirrorAbs = localPathForVaultKey(hqRoot, entry.conflictPath);
-    const originalAbs = localPathForVaultKey(hqRoot, entry.originalPath);
-
-    let mirrorStat: fs.Stats;
-    try {
-      mirrorStat = fs.lstatSync(mirrorAbs);
-    } catch {
-      // Mirror is gone — orphaned row, drop it. Nothing on disk to clean up.
-      result.prunedOrphans++;
-      continue;
-    }
-
-    // Both sides must exist to compare. A missing original is a real
-    // local-delete divergence — keep it for the human to resolve.
-    let originalStat: fs.Stats;
-    try {
-      originalStat = fs.lstatSync(originalAbs);
-    } catch {
-      kept.push(entry);
-      result.kept++;
-      continue;
-    }
-
-    let identical: boolean;
-    try {
-      identical = entryFilesAreIdentical(
-        originalAbs,
-        originalStat,
-        mirrorAbs,
-        mirrorStat,
-      );
-    } catch {
-      // Couldn't read one side — fail safe, keep the row.
-      kept.push(entry);
-      result.kept++;
-      continue;
-    }
-
-    if (identical) {
-      result.prunedIdentical++;
-      mirrorsToRemove.push(mirrorAbs);
-    } else {
-      kept.push(entry);
-      result.kept++;
-    }
-  }
-
-  // Name the preserved divergences for the post-sync reconcile surface.
-  result.keptSamplePaths = kept.slice(0, 10).map((e) => e.originalPath);
-
-  // No row dropped → leave the file (and its mtime) untouched.
-  if (kept.length === index.conflicts.length) return result;
-
-  // Delete the byte-identical mirror litter. Best-effort: a leftover identical
-  // mirror is cosmetic, never corrupting, so a failed unlink doesn't abort.
-  for (const mirrorAbs of mirrorsToRemove) {
-    try {
-      fs.rmSync(mirrorAbs, { force: true });
-      result.removedMirrors++;
-    } catch {
-      /* best-effort cleanup */
-    }
-  }
-
-  writeConflictIndex(hqRoot, { version: index.version, conflicts: kept });
-  return result;
-}