@statewalker/webrun-files-sync 0.2.2

package/dist/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Public contract for the rclone-like file-synchronisation engine.
+ *
+ * The engine plans-then-executes over two {@link FilesApi} endpoints. {@link plan}
+ * is pure (mutates neither endpoint) and returns a serializable {@link SyncPlan};
+ * {@link execute} applies it, emitting {@link SyncEvent}s and resuming from an
+ * optional checkpoint after interruption.
+ */
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { Resolution, Conflict as SyncConflict } from "@statewalker/webrun-merge";
+export type { FilesApi, Resolution, SyncConflict };
+/** A stream of bytes, as produced by {@link FilesApi.read}. */
+export type ByteStream = AsyncIterable<Uint8Array>;
+/**
+ * Path predicate: return `true` to INCLUDE a path in the sync, `false` to skip.
+ * `webrun-files` does not export a `PathFilter`, so it is defined here.
+ */
+export type PathFilter = (path: string) => boolean;
+export type SyncOp = "copy" | "sync" | "bisync" | "move" | "check";
+/**
+ * How a transferred file is verified at the destination.
+ * `size` compares byte counts (cheap default); `content-hash`/`backend-hash`/
+ * `read-after-write` re-hash the destination bytes; `mtime` falls back to size
+ * (cross-endpoint mtime is not comparable).
+ */
+export type VerificationMode = "size" | "mtime" | "backend-hash" | "content-hash" | "read-after-write";
+/**
+ * A single typed step of a {@link SyncPlan}. Serializable by construction.
+ * `copy`/`update` read `path` from the `from` endpoint and write it to the other;
+ * `move` renames within one `side`; `delete` removes `path` from one `side`;
+ * `mkdir` creates an (empty) directory on the destination of a one-way op.
+ *
+ * (The grilled note also listed a `metadata` action; it is intentionally omitted
+ * — the same note puts "arbitrary metadata beyond FilesApi size/mtime" out of
+ * scope, and MemFilesApi exposes no metadata setter, so it would be dead code.)
+ */
+export type SyncAction = {
+    kind: "mkdir";
+    path: string;
+} | {
+    kind: "copy";
+    path: string;
+    from: "a" | "b";
+} | {
+    kind: "update";
+    path: string;
+    from: "a" | "b";
+} | {
+    kind: "move";
+    from: string;
+    to: string;
+    side: "a" | "b";
+} | {
+    kind: "delete";
+    path: string;
+    side: "a" | "b";
+};
+/** A serializable, dry-runnable, auditable plan. */
+export interface SyncPlan {
+    op: SyncOp;
+    actions: SyncAction[];
+    conflicts: SyncConflict[];
+    /** Non-fatal notices raised while planning (e.g. first bisync with no anchor). */
+    warnings?: string[];
+}
+/** Events streamed by {@link execute}. */
+export type SyncEvent = {
+    type: "warning";
+    message: string;
+} | {
+    type: "conflict";
+    conflict: SyncConflict;
+} | {
+    type: "start";
+    index: number;
+    action: SyncAction;
+} | {
+    type: "done";
+    index: number;
+    action: SyncAction;
+} | {
+    type: "skipped";
+    index: number;
+    action: SyncAction;
+    reason: string;
+} | {
+    type: "failed";
+    index: number;
+    action: SyncAction;
+    reason: string;
+};
+/**
+ * Executes a single copy/update. Injected so a later phase can plug a
+ * chunk-dedup transfer into the SAME seam; the default streams whole files.
+ */
+export interface Transfer {
+    run(action: SyncAction, from: FilesApi, to: FilesApi): Promise<void>;
+}
+/** Content-id + metadata manifest of the last successful sync (bisync base). */
+export interface SyncAnchor {
+    entries: Record<string, {
+        contentId: string;
+        size: number;
+        mtime: number;
+    }>;
+}
+/** Persistence for the {@link SyncAnchor} of an endpoint pair (bisync). */
+export interface AnchorStore {
+    read(pairKey: string): Promise<SyncAnchor | undefined>;
+    write(pairKey: string, anchor: SyncAnchor): Promise<void>;
+}
+/**
+ * Progress checkpoint enabling resume: records the indices of completed actions.
+ * `execute` skips completed indices and records each new one before yielding its
+ * `done` event, so an interrupted run resumes with no duplicate work.
+ */
+export interface CheckpointStore {
+    read(): Promise<Set<number>>;
+    add(index: number): Promise<void>;
+}
+export interface SyncOptions {
+    /** Content identity — the ladder terminal and the id shared with webrun-merge. */
+    hashContent: (input: ByteStream) => Promise<string>;
+    filter?: PathFilter;
+    /** Copy/update executor; defaults to whole-file streaming copy. */
+    transfer?: Transfer;
+    /** Destination verification mode; defaults to `size`. */
+    verify?: VerificationMode;
+    /** SyncAnchor persistence (bisync only). */
+    anchorStore?: AnchorStore;
+    /** Identifies the endpoint pair for the anchor store (bisync); defaults to "default". */
+    pairKey?: string;
+    /** Injected conflict-resolution policy (bisync). */
+    resolve?: (c: SyncConflict) => Resolution | undefined;
+    /** Enable the head/tail sample rung of the change-detection ladder. */
+    quickFingerprint?: boolean;
+    /** Resume support for {@link execute}. */
+    checkpoint?: CheckpointStore;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@statewalker/webrun-files-sync",
+  "version": "0.2.2",
+  "description": "rclone-like file-synchronisation engine (copy/sync/bisync/move/check) over the webrun-files FilesApi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/statewalker/webrun-vcs.git",
+    "directory": "packages/webrun-files-sync"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-files": "^0.10.0",
+    "@statewalker/webrun-merge": "^0.2.1"
+  },
+  "devDependencies": {
+    "@statewalker/webrun-files-mem": "^0.10.0",
+    "rolldown": "^1.2.12",
+    "vitest": "^5.0.3",
+    "typescript": "^7.0.2",
+    "@types/node": "^26.6.4"
+  },
+  "scripts": {
+    "build": "rm -rf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome check --write .",
+    "lint:check": "biome check .",
+    "lint:fix": "biome check --write --unsafe .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "format:fix": "biome check --write --unsafe .",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/anchor.ts

@@ -0,0 +1,107 @@
+/**
+ * {@link SyncAnchor} helpers — building a manifest from an endpoint and
+ * reconstructing a read-only "base" {@link FilesApi} view from a manifest.
+ */
+
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import type { ByteStream, SyncAnchor } from "./types.js";
+
+/** Build a fresh anchor manifest by hashing every file in an endpoint. */
+export async function buildAnchor(
+  files: FilesApi,
+  hashContent: (b: ByteStream) => Promise<string>,
+): Promise<SyncAnchor> {
+  const entries: SyncAnchor["entries"] = {};
+  for await (const info of files.list("/", { recursive: true })) {
+    if (info.kind !== "file") continue;
+    entries[info.path] = {
+      contentId: await hashContent(files.read(info.path)),
+      size: info.size ?? 0,
+      mtime: info.lastModified ?? 0,
+    };
+  }
+  return { entries };
+}
+
+/**
+ * A read-only base tree reconstructed from a {@link SyncAnchor}.
+ *
+ * Contract decision 1: the anchor stores NO base bytes. Base content is resolved
+ * ON DEMAND by content-id from whichever live endpoint still holds it (both `a`
+ * and `b` are searched, hashing lazily). When no endpoint holds the id — i.e.
+ * both sides changed the file — `read` yields nothing, and the both-modified
+ * path resolves to a conflict in webrun-merge rather than a bogus merge.
+ */
+export function anchorBaseView(
+  anchor: SyncAnchor,
+  a: FilesApi,
+  b: FilesApi,
+  hashContent: (input: ByteStream) => Promise<string>,
+): FilesApi {
+  // contentId -> {api, path}, built lazily across a then b on first miss.
+  let index: Map<string, { api: FilesApi; path: string }> | undefined;
+  const wanted = new Set(Object.values(anchor.entries).map((e) => e.contentId));
+
+  async function buildIndex(): Promise<Map<string, { api: FilesApi; path: string }>> {
+    const map = new Map<string, { api: FilesApi; path: string }>();
+    for (const api of [a, b]) {
+      for await (const info of api.list("/", { recursive: true })) {
+        if (info.kind !== "file") continue;
+        const id = await hashContent(api.read(info.path));
+        if (wanted.has(id) && !map.has(id)) map.set(id, { api, path: info.path });
+      }
+    }
+    return map;
+  }
+
+  async function locate(path: string): Promise<{ api: FilesApi; path: string } | undefined> {
+    const entry = anchor.entries[path];
+    if (!entry) return undefined;
+    if (!index) index = await buildIndex();
+    return index.get(entry.contentId);
+  }
+
+  const readOnly = (op: string) => async (): Promise<never> => {
+    throw new Error(`anchor base view is read-only (${op})`);
+  };
+
+  return {
+    async *read(path: string, _options?: ReadOptions): AsyncIterable<Uint8Array> {
+      const loc = await locate(path);
+      if (!loc) return; // unresolved base content ⇒ empty (both sides changed it)
+      yield* loc.api.read(loc.path);
+    },
+    async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+      const prefix = path === "/" ? "/" : `${path}/`;
+      for (const [p, e] of Object.entries(anchor.entries)) {
+        if (p !== path && !p.startsWith(prefix)) continue;
+        if (!options?.recursive && p.slice(prefix.length).includes("/")) continue;
+        yield {
+          name: p.slice(p.lastIndexOf("/") + 1),
+          path: p,
+          kind: "file",
+          size: e.size,
+          lastModified: e.mtime,
+        };
+      }
+    },
+    async stats(path: string): Promise<FileStats | undefined> {
+      const e = anchor.entries[path];
+      return e ? { kind: "file", size: e.size, lastModified: e.mtime } : undefined;
+    },
+    async exists(path: string): Promise<boolean> {
+      return path in anchor.entries;
+    },
+    write: readOnly("write"),
+    mkdir: readOnly("mkdir"),
+    remove: readOnly("remove"),
+    move: readOnly("move"),
+    copy: readOnly("copy"),
+  } as FilesApi;
+}

package/src/bisync.ts

@@ -0,0 +1,107 @@
+/**
+ * Bidirectional sync — a THREE-WAY merge over a sync-owned {@link SyncAnchor},
+ * delegated to `@statewalker/webrun-merge`. This is NEVER two chained one-way syncs.
+ *
+ * base  = the anchor manifest (with base bytes resolved on demand, see anchor.ts)
+ * left  = endpoint `a`   right = endpoint `b`
+ *
+ * webrun-merge returns operations relative to the merged tree; each is translated
+ * into {@link SyncAction}s applied to BOTH endpoints, and its conflicts are
+ * surfaced (or folded away by an injected `resolve`, inside webrun-merge).
+ *
+ * both-modified policy: files-sync installs a content merger that ALWAYS
+ * conflicts, so a file changed on both sides is a conflict (optionally resolved
+ * by the injected policy) — it is never silently line-merged.
+ *
+ * No-anchor first bisync: with no anchor there is no base, so a true 3-way merge
+ * is impossible. We fall back to a CONSERVATIVE UNION — propagate additions both
+ * ways, delete nothing — and emit a warning. Files present on both sides with
+ * differing content are surfaced as conflicts, never overwritten.
+ */
+
+import type { FilesApi } from "@statewalker/webrun-files";
+import { merge } from "@statewalker/webrun-merge";
+import { anchorBaseView } from "./anchor.js";
+import { isChanged, snapshot } from "./change-detection.js";
+import type { SyncAction, SyncConflict, SyncOptions, SyncPlan } from "./types.js";
+
+const alwaysConflictMerger = { merge: () => ({ conflict: true as const }) };
+
+export async function planBisync(a: FilesApi, b: FilesApi, opts: SyncOptions): Promise<SyncPlan> {
+  const pairKey = opts.pairKey ?? "default";
+  const anchor = await opts.anchorStore?.read(pairKey);
+
+  if (!anchor) return planUnion(a, b, opts);
+
+  const base = anchorBaseView(anchor, a, b, opts.hashContent);
+  const result = await merge(base, a, b, {
+    hashContent: opts.hashContent,
+    contentMerger: alwaysConflictMerger,
+    resolve: opts.resolve,
+  });
+
+  const [snapA, snapB] = await Promise.all([snapshot(a, opts.filter), snapshot(b, opts.filter)]);
+  const actions: SyncAction[] = [];
+
+  for (const op of result.operations) {
+    switch (op.op) {
+      case "add":
+      case "modify": {
+        if (!op.source) {
+          throw new Error(`bisync cannot apply an inline-content ${op.op} for ${op.path}`);
+        }
+        const from = op.source.side === "left" ? "a" : "b";
+        actions.push({ kind: op.op === "add" ? "copy" : "update", path: op.path, from });
+        break;
+      }
+      case "delete": {
+        // Propagate the deletion to whichever side still holds the file.
+        if (snapA.has(op.path)) actions.push({ kind: "delete", path: op.path, side: "a" });
+        if (snapB.has(op.path)) actions.push({ kind: "delete", path: op.path, side: "b" });
+        break;
+      }
+      case "rename": {
+        const from = op.from as string;
+        if (snapA.has(from)) actions.push({ kind: "move", from, to: op.path, side: "a" });
+        if (snapB.has(from)) actions.push({ kind: "move", from, to: op.path, side: "b" });
+        break;
+      }
+    }
+  }
+
+  return { op: "bisync", actions, conflicts: result.conflicts };
+}
+
+/** Conservative union used for the first bisync (no anchor yet). */
+async function planUnion(a: FilesApi, b: FilesApi, opts: SyncOptions): Promise<SyncPlan> {
+  const [snapA, snapB] = await Promise.all([snapshot(a, opts.filter), snapshot(b, opts.filter)]);
+  const actions: SyncAction[] = [];
+  const conflicts: SyncConflict[] = [];
+
+  for (const [path, entry] of snapA) {
+    if (entry.kind !== "file") continue;
+    const other = snapB.get(path);
+    if (!other) {
+      actions.push({ kind: "copy", path, from: "a" });
+    } else if (await isChanged(a, b, path, entry, other, opts)) {
+      // Both sides hold divergent content and there is no base to arbitrate.
+      conflicts.push({
+        kind: "content",
+        path,
+        left: { path, kind: "file" },
+        right: { path, kind: "file" },
+      });
+    }
+  }
+  for (const [path, entry] of snapB) {
+    if (entry.kind !== "file") continue;
+    if (!snapA.has(path)) actions.push({ kind: "copy", path, from: "b" });
+  }
+
+  return {
+    op: "bisync",
+    actions,
+    conflicts,
+    warnings: ["no sync anchor; performing conservative union (additions only, no deletions)"],
+  };
+}

package/src/change-detection.ts

@@ -0,0 +1,131 @@
+/**
+ * The cheap-first change-detection ladder.
+ *
+ * Short-circuits from the cheapest signal to the most expensive:
+ *   path/type  →  size  →  stable mtime  →  optional quick fingerprint  →
+ *   full content hash (injected `hashContent`).
+ *
+ * Each rung that can decide "same" or "changed" returns without paying for the
+ * next one — in particular a size difference marks a file changed WITHOUT ever
+ * hashing, and an equal size+mtime pair is treated as unchanged (rclone's
+ * default heuristic) without hashing either.
+ */
+
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { ByteStream, PathFilter } from "./types.js";
+
+export interface Entry {
+  path: string;
+  kind: "file" | "directory";
+  size?: number;
+  mtime?: number;
+}
+
+export type Snapshot = Map<string, Entry>;
+
+/** List a whole tree into a path-keyed snapshot, applying an optional filter. */
+export async function snapshot(files: FilesApi, filter?: PathFilter): Promise<Snapshot> {
+  const map: Snapshot = new Map();
+  for await (const info of files.list("/", { recursive: true })) {
+    if (filter && info.kind === "file" && !filter(info.path)) continue;
+    map.set(info.path, {
+      path: info.path,
+      kind: info.kind,
+      size: info.kind === "file" ? info.size : undefined,
+      mtime: info.kind === "file" ? info.lastModified : undefined,
+    });
+  }
+  return map;
+}
+
+const HEAD_TAIL = 64;
+
+/** Read a bounded byte range as a single buffer (for fingerprint sampling). */
+async function readRange(
+  files: FilesApi,
+  path: string,
+  start: number,
+  length: number,
+): Promise<Uint8Array> {
+  const parts: Uint8Array[] = [];
+  for await (const chunk of files.read(path, { start, length })) parts.push(chunk);
+  const total = parts.reduce((n, p) => n + p.length, 0);
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.length;
+  }
+  return out;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** head+tail sample of a file, used by the optional quick-fingerprint rung. */
+async function fingerprint(files: FilesApi, path: string, size: number): Promise<Uint8Array> {
+  if (size <= HEAD_TAIL * 2) return readRange(files, path, 0, size);
+  const head = await readRange(files, path, 0, HEAD_TAIL);
+  const tail = await readRange(files, path, size - HEAD_TAIL, HEAD_TAIL);
+  const out = new Uint8Array(head.length + tail.length);
+  out.set(head, 0);
+  out.set(tail, head.length);
+  return out;
+}
+
+export interface LadderOptions {
+  hashContent: (input: ByteStream) => Promise<string>;
+  quickFingerprint?: boolean;
+}
+
+/**
+ * Decide whether `from`'s file at `path` differs from `to`'s file, climbing the
+ * ladder only as far as needed. `fromEntry` must exist; `toEntry` may be absent.
+ */
+export async function isChanged(
+  from: FilesApi,
+  to: FilesApi,
+  path: string,
+  fromEntry: Entry,
+  toEntry: Entry | undefined,
+  opts: LadderOptions,
+): Promise<boolean> {
+  // path/type rung
+  if (!toEntry) return true;
+  if (fromEntry.kind !== toEntry.kind) return true;
+  if (fromEntry.kind === "directory") return false;
+
+  // size rung — a difference is decisive; never hashes.
+  if (fromEntry.size !== toEntry.size) return true;
+
+  // stable-mtime rung — equal size + equal mtime ⇒ unchanged, no hashing.
+  if (
+    fromEntry.mtime !== undefined &&
+    toEntry.mtime !== undefined &&
+    fromEntry.mtime === toEntry.mtime
+  ) {
+    return false;
+  }
+
+  const size = fromEntry.size ?? 0;
+
+  // optional quick-fingerprint rung — a sample mismatch decides "changed"
+  // without a full hash; a match is inconclusive and falls through.
+  if (opts.quickFingerprint) {
+    const [fa, fb] = await Promise.all([
+      fingerprint(from, path, size),
+      fingerprint(to, path, size),
+    ]);
+    if (!bytesEqual(fa, fb)) return true;
+  }
+
+  // full content-hash rung — the ambiguous case.
+  const [ha, hb] = await Promise.all([
+    opts.hashContent(from.read(path)),
+    opts.hashContent(to.read(path)),
+  ]);
+  return ha !== hb;
+}