wehandoff 0.0.1 → 0.1.0

package/bin/_whf/shared-asset.mjs

@@ -0,0 +1,124 @@
+// shared-asset working-copy store + 3-way merge (shared-asset P1.4 / spec §4).
+//
+// `whf share/pull/push` keep a LOCAL working copy of a cloud `shared_asset` under
+// `~/.wehandoff/shared/<id>/`:
+//   issue.md     — the editable working copy (what the user edits between syncs)
+//   .meta.json   — { cloud_rev, base_body, sha } sync bookkeeping
+//   .merged      — written ONLY on an unresolved 3-way conflict (git-style markers)
+//
+// `cloud_rev` is the server-assigned optimistic-lock counter (spec §4 / blocker ②):
+// the client carries the rev its `base_body` was last synced to and sends it as
+// `expected_rev`; it NEVER picks rev itself. `base_body` is the common ancestor
+// for the diff3 merge and advances at exactly three points (spec §4):
+//   - clean push success  → base := the body just pushed, rev := server rev
+//   - push 409            → base does NOT advance; re-pull remote → 3-way merge
+//   - resolved + re-push   → base := the body actually pushed, rev := re-push rev
+//
+// The merge engine is node-diff3 (`merge`, excludeFalseConflicts:true by default)
+// — a pure-JS three-way merge with no system dependency (blocker ①). We never
+// reimplement CAS here: the server returns 409 and we react.
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { merge as diff3Merge } from 'node-diff3';
+
+const WORKING_FILE = 'issue.md';
+const META_FILE = '.meta.json';
+const MERGED_FILE = '.merged';
+
+/** Root of the per-asset working-copy store: `<home>/.wehandoff/shared/<id>/`. */
+export function assetDir(assetId, home = homedir()) {
+  return join(home, '.wehandoff', 'shared', String(assetId));
+}
+
+/** content sha — used to detect a dirty working copy (working !== base). */
+export function sha256(body) {
+  return createHash('sha256').update(body ?? '', 'utf8').digest('hex');
+}
+
+/**
+ * Persist a working copy + its sync metadata for `assetId`. `baseBody` is the
+ * common-ancestor body the next push/merge diffs against; `cloudRev` is the rev
+ * that base corresponds to. The working copy is seeded to `baseBody` on a fresh
+ * share/pull (caller may overwrite issue.md afterwards while editing).
+ */
+export function writeWorkingCopy({ assetId, home = homedir(), body, cloudRev }) {
+  const dir = assetDir(assetId, home);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, WORKING_FILE), body, 'utf8');
+  writeMeta({ assetId, home, cloudRev, baseBody: body });
+}
+
+export function writeMeta({ assetId, home = homedir(), cloudRev, baseBody }) {
+  const dir = assetDir(assetId, home);
+  mkdirSync(dir, { recursive: true });
+  const meta = { cloud_rev: cloudRev, base_body: baseBody, sha: sha256(baseBody) };
+  writeFileSync(join(dir, META_FILE), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+  return meta;
+}
+
+/** Read `.meta.json`, or null if this asset has no local working copy yet. */
+export function readMeta({ assetId, home = homedir() }) {
+  const path = join(assetDir(assetId, home), META_FILE);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/** Read the editable working copy (`issue.md`), or null if absent. */
+export function readWorkingCopy({ assetId, home = homedir() }) {
+  const path = join(assetDir(assetId, home), WORKING_FILE);
+  if (!existsSync(path)) return null;
+  return readFileSync(path, 'utf8');
+}
+
+export function writeWorkingBody({ assetId, home = homedir(), body }) {
+  const dir = assetDir(assetId, home);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, WORKING_FILE), body, 'utf8');
+}
+
+/** Write the conflict-marked `.merged` so the user can resolve it by hand. */
+export function writeMergedConflict({ assetId, home = homedir(), body }) {
+  const dir = assetDir(assetId, home);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, MERGED_FILE);
+  writeFileSync(path, body, 'utf8');
+  return path;
+}
+
+/** Clear a stale `.merged` once a sync resolves cleanly. */
+export function clearMerged({ assetId, home = homedir() }) {
+  const path = join(assetDir(assetId, home), MERGED_FILE);
+  if (existsSync(path)) rmSync(path);
+}
+
+/** working copy differs from the synced base → has un-pushed local edits. */
+export function isDirty({ assetId, home = homedir() }) {
+  const meta = readMeta({ assetId, home });
+  const working = readWorkingCopy({ assetId, home });
+  if (meta == null || working == null) return false;
+  return sha256(working) !== meta.sha;
+}
+
+/**
+ * Three-way merge {base (ancestor), local (mine), remote (theirs)} via node-diff3.
+ * Returns { conflict, body } where `body` carries git-style conflict markers
+ * (<<<<<<< local / ======= / >>>>>>> remote) when `conflict` is true. Newline
+ * granularity (stringSeparator:'\n') so issue-md merges line-by-line.
+ */
+export function threeWayMerge(base, local, remote) {
+  const { conflict, result } = diff3Merge(local, base, remote, {
+    stringSeparator: '\n',
+    label: { a: 'local', o: 'base', b: 'remote' },
+  });
+  return { conflict, body: result.join('\n') };
+}