@terminus-ai/cli 0.0.1

package/bin/sync.mjs

@@ -0,0 +1,357 @@
+/**
+ * A working copy's memory of the draft it matches — what git keeps as
+ * `origin/main`. Terminus keeps every draft commit; this file is how a folder
+ * knows which one it last matched, so that:
+ *
+ *   - push refuses when the draft has commits the folder has not seen, the
+ *     way git refuses a push that is not a fast-forward;
+ *   - pull merges instead of replacing: a file changed only in the draft is
+ *     brought in, one changed only here is kept, and one changed on both
+ *     sides is merged line by line or named as a conflict;
+ *   - status can say ahead, behind, or both, and list what changed here.
+ *
+ * It lives at `.terminus/sync.json`, which every package walk skips, beside a
+ * `.gitignore` that keeps it out of the developer's own repository. Each file
+ * it tracks is recorded twice: as the folder had it after the sync (`local`)
+ * and as the draft stores it (`draft`). They differ only where the CLI
+ * rewrites a file on the way in — terminus.json is written in its canonical
+ * form — and keeping both is what stops that rewrite from reading as an edit
+ * on either side.
+ *
+ * Pure data and text: no network, no Terminus API. apps.mjs does the I/O.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { TERMINUS_DIRECTORY } from "./files.mjs";
+
+export const SYNC_DIRECTORY = TERMINUS_DIRECTORY;
+const SYNC_FILE = "sync.json";
+const FORMAT = 1;
+
+export function syncRecordPath(dir) {
+  return path.join(dir, SYNC_DIRECTORY, SYNC_FILE);
+}
+
+/**
+ * The folder's record, or null when it has none (or one this CLI cannot read).
+ *
+ * A file whose two sides agree is written with one hash, so reading fills
+ * the other back in: every caller sees both, and only the files the CLI
+ * rewrote on the way in cost a second line.
+ */
+export async function readSyncRecord(dir) {
+  try {
+    const record = JSON.parse(await readFile(syncRecordPath(dir), "utf8"));
+    if (!record || record.format !== FORMAT || !Array.isArray(record.files)) return null;
+    return {
+      ...record,
+      files: record.files.map((file) => ({ ...file, local: file.local ?? file.draft })),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the record. `source` says what the folder follows: `"draft"` (one of
+ * your creations; `commit` is the draft commit it matches) or `"release"` (a
+ * read-only copy of someone else's open-source work; `release` is the
+ * version it matches).
+ */
+export async function writeSyncRecord(dir, record) {
+  const folder = path.join(dir, SYNC_DIRECTORY);
+  await mkdir(folder, { recursive: true });
+  // Git reads nested ignore files, so this one keeps the whole folder out of
+  // the developer's repository without touching their own .gitignore.
+  await writeFile(path.join(folder, ".gitignore"), "*\n");
+  const files = [...(record.files ?? [])]
+    .sort((left, right) => entryKey(left).localeCompare(entryKey(right)))
+    // The folder holds what the draft holds, except where the CLI writes a
+    // file in canonical form; only that difference is worth recording.
+    .map(({ local, ...file }) => (local === file.draft ? file : { ...file, local }));
+  await writeFile(
+    syncRecordPath(dir),
+    `${JSON.stringify({ format: FORMAT, ...record, files }, null, 2)}\n`,
+  );
+}
+
+/** A file's identity: its plane and its path, as everywhere in Terminus. */
+export function entryKey(entry) {
+  return `${entry.role ?? ""}\u0000${entry.path}`;
+}
+
+export function byKey(entries) {
+  return new Map((entries ?? []).map((entry) => [entryKey(entry), entry]));
+}
+
+/**
+ * The files a working copy holds, out of a package's full material list: an
+ * app's authoring (source) plane — its build is derived, and rebuilt, not
+ * merged — and everything for an agent or a service, whose files are the
+ * package. A draft made on the web is single-plane: its files carry no
+ * role, and all of them are the working copy.
+ */
+export function trackedEntries(manifest) {
+  const materials = manifest?.materials ?? [];
+  const source = materials.filter((material) => material.role === "source");
+  const chosen = manifest?.kind === "agent" || !source.length ? materials : source;
+  return chosen.map((material) => ({
+    path: material.path,
+    ...(material.role ? { role: material.role } : {}),
+    sha256: material.sha256 ?? null,
+    ...(material.encoding ? { encoding: material.encoding } : {}),
+  }));
+}
+
+/**
+ * What changed in the folder since it last matched the draft: each tracked
+ * file compared with the record's `local` side.
+ */
+export function localChanges(record, entries) {
+  const before = new Map((record?.files ?? []).map((file) => [entryKey(file), file]));
+  const now = byKey(entries);
+  const changes = [];
+  for (const [key, entry] of now) {
+    const was = before.get(key);
+    if (!was) changes.push({ path: entry.path, role: entry.role, status: "added" });
+    else if (was.local !== entry.sha256) changes.push({ path: entry.path, role: entry.role, status: "modified" });
+  }
+  for (const [key, was] of before) {
+    if (!now.has(key)) changes.push({ path: was.path, role: was.role, status: "deleted" });
+  }
+  return changes.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+/* ── Lines ──────────────────────────────────────────────────────────────── */
+
+/** Beyond this many line pairs a file is compared whole, not line by line. */
+const LINE_BUDGET = 4_000_000;
+
+export function splitLines(text) {
+  if (text === "") return [];
+  const lines = text.split("\n");
+  // A trailing newline ends the last line rather than starting an empty one.
+  if (lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+function joinLines(lines, trailingNewline) {
+  if (!lines.length) return "";
+  return lines.join("\n") + (trailingNewline ? "\n" : "");
+}
+
+/**
+ * The longest common subsequence of two line lists, as matched index pairs
+ * [[i, j], …] in order. Common prefixes and suffixes are matched first, so
+ * the quadratic part only sees the region that actually changed; null when
+ * even that is too large to compare line by line.
+ */
+export function matchLines(left, right) {
+  let start = 0;
+  while (start < left.length && start < right.length && left[start] === right[start]) start += 1;
+  let leftEnd = left.length;
+  let rightEnd = right.length;
+  while (leftEnd > start && rightEnd > start && left[leftEnd - 1] === right[rightEnd - 1]) {
+    leftEnd -= 1;
+    rightEnd -= 1;
+  }
+  const n = leftEnd - start;
+  const m = rightEnd - start;
+  if (n * m > LINE_BUDGET) return null;
+  const pairs = [];
+  for (let index = 0; index < start; index += 1) pairs.push([index, index]);
+  if (n && m) {
+    // lengths[i][j] = LCS of left[start+i..] and right[start+j..]
+    const width = m + 1;
+    const lengths = new Uint32Array((n + 1) * width);
+    for (let i = n - 1; i >= 0; i -= 1) {
+      for (let j = m - 1; j >= 0; j -= 1) {
+        lengths[i * width + j] = left[start + i] === right[start + j]
+          ? lengths[(i + 1) * width + j + 1] + 1
+          : Math.max(lengths[(i + 1) * width + j], lengths[i * width + j + 1]);
+      }
+    }
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+      if (left[start + i] === right[start + j]) {
+        pairs.push([start + i, start + j]);
+        i += 1;
+        j += 1;
+      } else if (lengths[(i + 1) * width + j] >= lengths[i * width + j + 1]) {
+        i += 1;
+      } else {
+        j += 1;
+      }
+    }
+  }
+  for (let offset = 0; offset < left.length - leftEnd; offset += 1) {
+    pairs.push([leftEnd + offset, rightEnd + offset]);
+  }
+  return pairs;
+}
+
+/**
+ * A line diff as operations: { kind: "same" | "remove" | "add", line }.
+ * Null when the texts are too large to compare line by line.
+ */
+export function diffLines(beforeText, afterText) {
+  const before = splitLines(beforeText);
+  const after = splitLines(afterText);
+  const pairs = matchLines(before, after);
+  if (!pairs) return null;
+  const operations = [];
+  let i = 0;
+  let j = 0;
+  for (const [pi, pj] of [...pairs, [before.length, after.length]]) {
+    while (i < pi) operations.push({ kind: "remove", line: before[i++] });
+    while (j < pj) operations.push({ kind: "add", line: after[j++] });
+    if (pi < before.length) {
+      operations.push({ kind: "same", line: before[pi] });
+      i = pi + 1;
+      j = pj + 1;
+    }
+  }
+  return operations;
+}
+
+/**
+ * The operations grouped into git-style hunks with `context` unchanged lines
+ * around each change: [{ header: "@@ -a,b +c,d @@", lines: ["+x", "-y", " z"] }].
+ */
+export function hunks(operations, context = 3) {
+  const out = [];
+  let oldLine = 1;
+  let newLine = 1;
+  const positions = operations.map((operation) => {
+    const at = { operation, oldLine, newLine };
+    if (operation.kind !== "add") oldLine += 1;
+    if (operation.kind !== "remove") newLine += 1;
+    return at;
+  });
+  const changed = positions
+    .map((position, index) => (position.operation.kind === "same" ? -1 : index))
+    .filter((index) => index >= 0);
+  let index = 0;
+  while (index < changed.length) {
+    const first = changed[index];
+    let last = first;
+    while (index + 1 < changed.length && changed[index + 1] - last <= context * 2 + 1) {
+      index += 1;
+      last = changed[index];
+    }
+    index += 1;
+    const from = Math.max(0, first - context);
+    const to = Math.min(positions.length - 1, last + context);
+    const slice = positions.slice(from, to + 1);
+    const oldCount = slice.filter((position) => position.operation.kind !== "add").length;
+    const newCount = slice.filter((position) => position.operation.kind !== "remove").length;
+    const oldStart = oldCount ? slice.find((position) => position.operation.kind !== "add").oldLine : slice[0].oldLine - 1;
+    const newStart = newCount ? slice.find((position) => position.operation.kind !== "remove").newLine : slice[0].newLine - 1;
+    out.push({
+      header: `@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`,
+      lines: slice.map(({ operation }) => (
+        `${operation.kind === "add" ? "+" : operation.kind === "remove" ? "-" : " "}${operation.line}`
+      )),
+    });
+  }
+  return out;
+}
+
+/* ── Merging ────────────────────────────────────────────────────────────── */
+
+export const CONFLICT_START = "<<<<<<< yours";
+export const CONFLICT_SPLIT = "=======";
+export const CONFLICT_END = ">>>>>>> draft";
+
+/** Whether a text still holds a conflict a pull wrote into it. */
+export function hasConflictMarkers(text) {
+  const lines = text.split("\n");
+  return lines.includes(CONFLICT_START) && lines.includes(CONFLICT_END);
+}
+
+function sameLines(left, right) {
+  return left.length === right.length && left.every((line, index) => line === right[index]);
+}
+
+/**
+ * Three-way merge of texts: what both sides started from, yours, and the
+ * draft's. Regions only one side changed take that side; regions both changed
+ * the same way are taken once; regions both changed differently become a
+ * conflict, written between git-style markers. Null when the texts are too
+ * large to merge line by line.
+ */
+export function mergeText(baseText, oursText, theirsText) {
+  const base = splitLines(baseText);
+  const ours = splitLines(oursText);
+  const theirs = splitLines(theirsText);
+  const toOurs = matchLines(base, ours);
+  const toTheirs = matchLines(base, theirs);
+  if (!toOurs || !toTheirs) return null;
+  const ourIndex = new Map(toOurs);
+  const theirIndex = new Map(toTheirs);
+  const out = [];
+  let conflicts = 0;
+  let b = 0;
+  let o = 0;
+  let t = 0;
+  for (;;) {
+    // The next base line both sides kept is an anchor both agree on.
+    let anchor = b;
+    while (anchor < base.length && !(ourIndex.has(anchor) && theirIndex.has(anchor))) anchor += 1;
+    const oursEnd = anchor < base.length ? ourIndex.get(anchor) : ours.length;
+    const theirsEnd = anchor < base.length ? theirIndex.get(anchor) : theirs.length;
+    const was = base.slice(b, anchor);
+    const mine = ours.slice(o, oursEnd);
+    const draft = theirs.slice(t, theirsEnd);
+    if (sameLines(mine, was)) out.push(...draft);
+    else if (sameLines(draft, was) || sameLines(mine, draft)) out.push(...mine);
+    else {
+      conflicts += 1;
+      out.push(CONFLICT_START, ...mine, CONFLICT_SPLIT, ...draft, CONFLICT_END);
+    }
+    if (anchor >= base.length) break;
+    out.push(base[anchor]);
+    b = anchor + 1;
+    o = oursEnd + 1;
+    t = theirsEnd + 1;
+  }
+  // Text files end with a newline; the merge keeps one when either side has it.
+  const trailing = oursText.endsWith("\n") || theirsText.endsWith("\n");
+  return { text: joinLines(out, trailing), conflicts };
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Three-way merge of two JSON objects key by key — how terminus.json merges,
+ * because markers inside JSON would leave a package the CLI cannot read. A
+ * key both sides changed differently keeps yours and is named.
+ */
+export function mergeObjects(base, ours, theirs) {
+  const merged = {};
+  const conflicts = [];
+  const keys = new Set([...Object.keys(base ?? {}), ...Object.keys(ours ?? {}), ...Object.keys(theirs ?? {})]);
+  for (const key of keys) {
+    const was = canonical(base?.[key]);
+    const mine = canonical(ours?.[key]);
+    const draft = canonical(theirs?.[key]);
+    let value;
+    if (mine === draft || draft === was) value = ours?.[key];
+    else if (mine === was) value = theirs?.[key];
+    else {
+      value = ours?.[key];
+      conflicts.push(key);
+    }
+    if (value !== undefined) merged[key] = value;
+  }
+  return { merged, conflicts };
+}