@stravica-ai/digital-operator-pa 0.1.21 → 0.1.23

package/dist/engineering-pa-cli/src/sync/pending-store.mjs

@@ -0,0 +1,318 @@
+// estate-sync — pending-conflict store.
+//
+// On a rebase conflict that lands OUTSIDE the regenerated-artifacts
+// allowlist, estate-sync now (a) captures our own version of every
+// conflicting path, (b) drops the local commit that made the conflict, and
+// (c) queues the captured content for retry on subsequent ticks. This
+// module owns the on-disk representation of that queue.
+//
+// Layout under `<repoRoot>/.cache/estate-sync/pending/`:
+//   <pathSlug>__<firstSeenTsSlug>            — raw bytes of estate-sync's version
+//   <pathSlug>__<firstSeenTsSlug>.json       — sidecar with metadata
+//
+// The pending id is the shared basename; the raw file and the sidecar
+// share it verbatim (sidecar just has `.json` on the end). Path slug is
+// the original path with `/` replaced by `__` and any characters outside
+// [A-Za-z0-9._-] replaced with `-`. First-seen timestamp is stripped of
+// separators (`2026-08-11T16:30:07Z` → `20260811T163007Z`).
+//
+// Two invariants this module enforces:
+//   1. Content-safety on queue — the raw file is opened, written, fsynced,
+//      and closed BEFORE the sidecar is written. Sidecar in turn is
+//      write-tmp-then-rename (with fsync of the tmp handle and of the
+//      containing directory) so a crash never leaves a sidecar pointing at
+//      unwritten content.
+//   2. Upsert by originalPath — a second conflict on the SAME workspace
+//      path replaces the raw file with our new version, keeps `firstSeen`
+//      unchanged (so the file's id stays stable across retries), and
+//      bumps `attemptCount`. This is what stops the drain-then-re-conflict
+//      loop from flooding the pending dir with parallel entries for one
+//      logical conflict.
+//
+// Sidecar fields (see loadAll for canonical field names):
+//   id, originalPath, firstSeen, lastAttemptAt, attemptCount,
+//   conflictingUpstreamCommitSha, upstreamBlobShaAtQueue (nullable —
+//     null when origin had no such path at queue time), ourContentSha,
+//   existedInParent (was HEAD^:originalPath present? drives the tree-
+//     cleanup branch), alertLevel ('warn' | 'error' | 'needs-human').
+
+import { open, mkdir, readFile, readdir, rename, rm, writeFile, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+
+// Slug rules: replace path separators with `__`, then any character not in
+// [A-Za-z0-9._-] with `-`, then collapse runs of `-` to one, then trim
+// leading/trailing `.-_`. Bounded to 120 chars (rare-long-path safety on
+// filesystems with 255-byte name limits — the timestamp adds ~16 chars and
+// the `.json` suffix adds 5, leaving headroom).
+export function slugifyPath(p) {
+  const out = p
+    .replace(/[\/\\]+/g, '__')
+    .replace(/[^A-Za-z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[.\-_]+|[.\-_]+$/g, '');
+  return out.slice(0, 120) || 'path';
+}
+
+// Turn an ISO timestamp (`2026-08-11T16:30:07Z`) into a filename-safe
+// compact form (`20260811T163007Z`). Non-matching input is passed through
+// unchanged after the same non-alnum sweep as the path slug.
+export function slugifyTs(ts) {
+  return String(ts).replace(/[^A-Za-z0-9]/g, '');
+}
+
+// Build the canonical pending id for an (originalPath, firstSeen) pair.
+// The `__` separator between the path slug and the ts slug is deliberate:
+// path slugs never contain `__` (single `_` may appear, `__` is our
+// literal separator token because paths already collapsed `/` to `__` —
+// see slugifyPath which uses `__` for `/` only after the char scrub, so a
+// raw `_` in a filename becomes `_` alone). Adding a further `__` gives
+// an unambiguous split point when reading id fields back out for logs.
+export function pendingId(originalPath, firstSeen) {
+  return `${slugifyPath(originalPath)}__${slugifyTs(firstSeen)}`;
+}
+
+export function pendingContentPath(pendingDir, id) {
+  return join(pendingDir, id);
+}
+
+export function pendingSidecarPath(pendingDir, id) {
+  return join(pendingDir, `${id}.json`);
+}
+
+function sha256Hex(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+// Atomic-ish sidecar write: write to `<name>.tmp`, fsync the tmp handle,
+// rename over `<name>`, then fsync the containing directory so the
+// rename is durable. If the directory fsync throws (unsupported on some
+// filesystems / Windows), swallow that specific failure — the rename
+// itself has already landed on POSIX, and durability was best-effort by
+// contract on non-POSIX. The write + rename ordering is what actually
+// guarantees no half-written sidecars on the read path.
+async function writeJsonAtomic(filePath, obj) {
+  const tmp = `${filePath}.tmp`;
+  const payload = `${JSON.stringify(obj, null, 2)}\n`;
+  const fh = await open(tmp, 'w');
+  try {
+    await fh.writeFile(payload, 'utf8');
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await rename(tmp, filePath);
+  try {
+    const dh = await open(dirname(filePath), 'r');
+    try { await dh.sync(); } finally { await dh.close(); }
+  } catch {
+    // Directory fsync unsupported on this filesystem — best-effort only.
+  }
+}
+
+// Content-write with the same durability contract as the sidecar. Content
+// is written as bytes (Buffer or string) — callers pass the raw file
+// content captured from the working tree.
+async function writeBytesAtomic(filePath, buf) {
+  const tmp = `${filePath}.tmp`;
+  const fh = await open(tmp, 'w');
+  try {
+    await fh.writeFile(buf);
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await rename(tmp, filePath);
+  try {
+    const dh = await open(dirname(filePath), 'r');
+    try { await dh.sync(); } finally { await dh.close(); }
+  } catch {
+    // See writeJsonAtomic — filesystem may not support directory fsync.
+  }
+}
+
+// Ensure the pending dir exists. Idempotent; safe to call on every tick.
+export async function ensurePendingDir(pendingDir) {
+  await mkdir(pendingDir, { recursive: true });
+}
+
+// Compose a canonical sidecar object from a queue-time payload. Kept as a
+// pure function so tests can assert the exact shape without file I/O.
+export function makeSidecar({
+  id,
+  originalPath,
+  firstSeen,
+  attemptCount = 1,
+  conflictingUpstreamCommitSha,
+  upstreamBlobShaAtQueue = null,
+  ourContentSha,
+  existedInParent,
+  alertLevel = 'warn',
+}) {
+  return {
+    id,
+    originalPath,
+    firstSeen,
+    lastAttemptAt: firstSeen,
+    attemptCount,
+    conflictingUpstreamCommitSha: conflictingUpstreamCommitSha ?? null,
+    upstreamBlobShaAtQueue,
+    ourContentSha,
+    existedInParent: Boolean(existedInParent),
+    alertLevel,
+  };
+}
+
+// Look up an existing sidecar for `originalPath`, if any. Used by upsert
+// to preserve `firstSeen` and bump `attemptCount` across a re-queue for
+// the same path.
+export async function findByOriginalPath(pendingDir, originalPath) {
+  let entries;
+  try {
+    entries = await readdir(pendingDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    let text;
+    try {
+      text = await readFile(join(pendingDir, name), 'utf8');
+    } catch {
+      continue;
+    }
+    let obj;
+    try { obj = JSON.parse(text); } catch { continue; }
+    if (obj && obj.originalPath === originalPath) return obj;
+  }
+  return null;
+}
+
+// Queue (or re-queue) a conflict. Contract:
+//   - Raw content is written and fsynced BEFORE the sidecar is written —
+//     if we crash mid-queue, a sidecar-less raw file is orphan (safe:
+//     next tick's cleanup can rm it, or leave it as forensic evidence)
+//     but there is never a sidecar pointing at unwritten content.
+//   - On upsert, `firstSeen` stays anchored to the earliest queue for
+//     this path, `attemptCount` is (prevAttempt + 1) if the caller doesn't
+//     override, and `alertLevel` follows the escalation ladder (warn →
+//     error at attemptCount >= escalateAt; needs-human is caller-set and
+//     sticky — divergence detected at drain time never de-escalates).
+//   - Returns the fully-populated sidecar object plus its content path.
+export async function queueConflict(pendingDir, {
+  originalPath,
+  content,
+  firstSeen,
+  conflictingUpstreamCommitSha,
+  upstreamBlobShaAtQueue = null,
+  existedInParent,
+  escalateAt = 5,
+  forceAlertLevel = null,
+}) {
+  await ensurePendingDir(pendingDir);
+
+  const existing = await findByOriginalPath(pendingDir, originalPath);
+  const anchoredFirstSeen = existing ? existing.firstSeen : firstSeen;
+  const nextAttempt = existing ? (existing.attemptCount || 0) + 1 : 1;
+  const priorAlert = existing?.alertLevel || 'warn';
+  const escalated = nextAttempt >= escalateAt ? 'error' : 'warn';
+  // needs-human is sticky — a caller sets it (divergence detected at drain
+  // time) and later requeues never step it back down to warn/error.
+  const alertLevel = forceAlertLevel
+    || (priorAlert === 'needs-human' ? 'needs-human' : escalated);
+
+  const id = pendingId(originalPath, anchoredFirstSeen);
+  const contentPath = pendingContentPath(pendingDir, id);
+  const sidecarPath = pendingSidecarPath(pendingDir, id);
+
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content);
+  await writeBytesAtomic(contentPath, buf);
+
+  const sidecar = makeSidecar({
+    id,
+    originalPath,
+    firstSeen: anchoredFirstSeen,
+    attemptCount: nextAttempt,
+    conflictingUpstreamCommitSha,
+    upstreamBlobShaAtQueue,
+    ourContentSha: sha256Hex(buf),
+    existedInParent,
+    alertLevel,
+  });
+  sidecar.lastAttemptAt = firstSeen;
+
+  await writeJsonAtomic(sidecarPath, sidecar);
+
+  return { sidecar, contentPath, sidecarPath };
+}
+
+// Read all pending sidecars, oldest-firstSeen-first. Corrupt sidecars are
+// SKIPPED with a warning attached to the return object — a broken sidecar
+// must never block the drain of well-formed ones.
+export async function loadAll(pendingDir) {
+  const out = [];
+  const warnings = [];
+  let names;
+  try {
+    names = await readdir(pendingDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { entries: [], warnings };
+    throw err;
+  }
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const sidecarPath = join(pendingDir, name);
+    let text;
+    try {
+      text = await readFile(sidecarPath, 'utf8');
+    } catch (err) {
+      warnings.push({ sidecar: name, reason: `read failed: ${err.message}` });
+      continue;
+    }
+    let obj;
+    try { obj = JSON.parse(text); } catch (err) {
+      warnings.push({ sidecar: name, reason: `parse failed: ${err.message}` });
+      continue;
+    }
+    if (!obj || typeof obj !== 'object' || !obj.originalPath || !obj.id) {
+      warnings.push({ sidecar: name, reason: 'malformed sidecar (missing id / originalPath)' });
+      continue;
+    }
+    const contentPath = pendingContentPath(pendingDir, obj.id);
+    let contentStat;
+    try { contentStat = await stat(contentPath); } catch {
+      warnings.push({ sidecar: name, reason: 'content file missing — sidecar orphan; skipping' });
+      continue;
+    }
+    out.push({ sidecar: obj, sidecarPath, contentPath, contentSize: contentStat.size });
+  }
+  out.sort((a, b) => (a.sidecar.firstSeen < b.sidecar.firstSeen ? -1 : 1));
+  return { entries: out, warnings };
+}
+
+// Rewrite a sidecar (durably) — used to bump attemptCount / alertLevel
+// without touching the content file. Callers typically compose the next
+// sidecar from the loaded one with `{ ...sidecar, attemptCount: n }`.
+export async function writeSidecar(pendingDir, sidecar) {
+  await ensurePendingDir(pendingDir);
+  const sidecarPath = pendingSidecarPath(pendingDir, sidecar.id);
+  await writeJsonAtomic(sidecarPath, sidecar);
+  return { sidecarPath };
+}
+
+// Remove a pending entry — both the content file and the sidecar. Contract:
+// removal happens ONLY after the sync has committed AND pushed the
+// pending content upstream. Removal is best-effort per file: either half
+// missing is not an error (idempotent cleanup after a crash mid-remove).
+export async function removePending(pendingDir, id) {
+  const contentPath = pendingContentPath(pendingDir, id);
+  const sidecarPath = pendingSidecarPath(pendingDir, id);
+  await rm(contentPath, { force: true });
+  await rm(sidecarPath, { force: true });
+}
+
+// Read the raw content bytes for a pending id.
+export async function readContent(pendingDir, id) {
+  return readFile(pendingContentPath(pendingDir, id));
+}