@wildwinter/toolkit 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @wildwinter/toolkit
 
+## 0.2.3
+
+### Added
+
+- **`@wildwinter/toolkit/vcs`: version-control setup for git, Perforce, Plastic SCM and SVN**, lifted from Patter so
+  both families take one copy. `vcsConfigFiles(format, vcs, posture)` writes the `vcs-setup.md` guide, git's
+  `.gitattributes` and the system's ignore file for a format that says what its files are (`VcsFormat`);
+  `bundlePostureOf` reads back whether the compiled bundle is committed or ignored; `runMergetool` is the wrapper a
+  system with one global merge tool calls, sending the format's source to its structured merge and anything else to
+  the team's own tool. Node-only, as `./archive` is.
+
+## 0.2.2
+
+### Added
+
+- **Comment threads merge message by message** (`./extensions`): `mergeComments(base, ours, theirs)`, and the
+  `comments` strategy (`COMMENTS`) for `mergeTree`, lifted from Patter's merge so both families take one rule.
+  Two replies to one thread both land, oldest first; a withdrawn message stays withdrawn, and one a side removed
+  outright, or lost with its thread, counts as withdrawn by that side; one message edited two ways is a clash.
+  A thread's own fields (anchor, marker, `resolved`) merge one by one, and a thread with nothing readable left
+  goes. Threads come back oldest first.
+
 ## 0.2.1
 
 ### Changed

package/README.md

@@ -3,8 +3,8 @@
 Small shared pieces of the **authoring tooling** behind
 [Storylet Studio](https://github.com/storylet-studio) and
 [Patter](https://patterkit.com): opaque ids, a stable hash, JSON5 source parsing,
-find/replace matching, the archive guards, and (in `./extensions`) the spec and merge
-for Patter extensions and Storylet extensions.
+find/replace matching, the archive guards, version-control setup (in `./vcs`), and (in
+`./extensions`) the spec and merge for Patter extensions and Storylet extensions.
 
 **Nothing here runs in a game.** This is the editor/CLI/pipeline side. The
 runtime language lives in [`@wildwinter/expr`](../expr), and unlike that package
@@ -93,6 +93,21 @@ pack **deterministic**: a fixed entry timestamp, no folder entries, no streaming
 A pack of an unchanged project must be byte-identical to the last one, or every
 delivery churns. That is easy to leave out, and silent when you do.
 
+## Version control
+
+A separate, node-only entry point, because `runMergetool` starts the team's own merge tool:
+
+```ts
+import { VCS_KINDS, vcsConfigFiles, bundlePostureOf, runMergetool } from "@wildwinter/toolkit/vcs";
+```
+
+A format says what it is called and what its files are (`VcsFormat`: the tool, the git driver's name, the source
+extensions, the bundle, the packed document, the conflict sidecar). `vcsConfigFiles(format, vcs, posture)` is then
+everything a project is set up with for git, Perforce, Plastic SCM or SVN: the `vcs-setup.md` guide, git's
+`.gitattributes`, and the system's ignore file, with the compiled bundle committed or ignored. `bundlePostureOf`
+reads the posture back, so a switch of system keeps it. `runMergetool` is the one global merge tool Perforce,
+Plastic SCM and SVN allow: the format's source goes to its structured merge, anything else to the team's own tool.
+
 ## Licence
 
 MIT

package/conformance/extensions/merge.json

@@ -49,7 +49,52 @@
       "base": { "k": { "a": 1 } }, "ours": { "k": { "a": 2 } }, "theirs": { "k": { "a": 1, "b": 1 } },
       "merged": { "k": { "a": 2, "b": 1 } }, "conflicts": [] },
     { "name": "a value whose shape no longer fits its strategy merges as one value", "strategy": { "kind": "map", "of": { "kind": "atomic" } },
-      "base": { "a": 1 }, "ours": "gone", "theirs": { "a": 2 }, "merged": "gone", "conflicts": [{ "path": "", "kind": "both-changed" }] }
+      "base": { "a": 1 }, "ours": "gone", "theirs": { "a": 2 }, "merged": "gone", "conflicts": [{ "path": "", "kind": "both-changed" }] },
+    { "name": "comments: two replies to one thread both land, in time order", "strategy": { "kind": "comments" },
+      "base": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }] }],
+      "ours": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T12:00", "body": "Pacing." }] }],
+      "theirs": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Cy", "ts": "2026-01-01T11:00", "body": "Ask Bo." }] }],
+      "merged": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Cy", "ts": "2026-01-01T11:00", "body": "Ask Bo." }, { "author": "Bo", "ts": "2026-01-01T12:00", "body": "Pacing." }] }],
+      "conflicts": [] },
+    { "name": "comments: a message withdrawn on one side stays withdrawn", "strategy": { "kind": "comments" },
+      "base": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T11:00", "body": "Oops" }] }],
+      "ours": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T11:00", "body": "", "deleted": true }] }],
+      "theirs": [{ "id": "t1", "anchor": "c1", "resolved": true, "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T11:00", "body": "Oops" }] }],
+      "merged": [{ "id": "t1", "anchor": "c1", "resolved": true, "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T11:00", "body": "", "deleted": true }] }],
+      "conflicts": [] },
+    { "name": "comments: a message one side removed outright is withdrawn, not brought back", "strategy": { "kind": "comments" },
+      "base": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T11:00", "body": "Oops" }] }],
+      "ours": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }] }],
+      "theirs": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T11:00", "body": "Oops" }] }],
+      "merged": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T11:00", "body": "", "deleted": true }] }],
+      "conflicts": [] },
+    { "name": "comments: a thread one side removed goes, unless the other side replied", "strategy": { "kind": "comments" },
+      "base": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }] },
+               { "id": "t2", "anchor": "c2", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:30", "body": "Typo" }] }],
+      "ours": [],
+      "theirs": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }, { "author": "Bo", "ts": "2026-01-01T12:00", "body": "Pacing." }] },
+                 { "id": "t2", "anchor": "c2", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:30", "body": "Typo" }] }],
+      "merged": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "", "deleted": true }, { "author": "Bo", "ts": "2026-01-01T12:00", "body": "Pacing." }] }],
+      "conflicts": [] },
+    { "name": "comments: one message edited two ways clashes and keeps ours", "strategy": { "kind": "comments" },
+      "base": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }] }],
+      "ours": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why this?" }] }],
+      "theirs": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why that?" }] }],
+      "merged": [{ "id": "t1", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why this?" }] }],
+      "conflicts": [{ "path": "[t1].messages[Ann|2026-01-01T10:00]", "kind": "both-changed" }] },
+    { "name": "comments: a thread's own fields merge one by one, a marker moved two ways clashes", "strategy": { "kind": "comments" },
+      "base": [{ "id": "t1", "anchor": "c1", "mark": { "canvas": "d1", "x": 0, "y": 0 }, "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }] }],
+      "ours": [{ "id": "t1", "anchor": "c1", "mark": { "canvas": "d1", "x": 5, "y": 0 }, "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }] }],
+      "theirs": [{ "id": "t1", "anchor": "c1", "resolved": true, "mark": { "canvas": "d1", "x": 9, "y": 9 }, "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }] }],
+      "merged": [{ "id": "t1", "anchor": "c1", "resolved": true, "mark": { "canvas": "d1", "x": 5, "y": 0 }, "messages": [{ "author": "Ann", "ts": "2026-01-01T10:00", "body": "Why?" }] }],
+      "conflicts": [{ "path": "[t1].mark", "kind": "both-changed" }] },
+    { "name": "comments: threads come back oldest first, whatever their ids", "strategy": { "kind": "comments" },
+      "base": [],
+      "ours": [{ "id": "zz", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T09:00", "body": "First" }] }],
+      "theirs": [{ "id": "aa", "anchor": "c2", "messages": [{ "author": "Bo", "ts": "2026-01-02T09:00", "body": "Second" }] }],
+      "merged": [{ "id": "zz", "anchor": "c1", "messages": [{ "author": "Ann", "ts": "2026-01-01T09:00", "body": "First" }] },
+                 { "id": "aa", "anchor": "c2", "messages": [{ "author": "Bo", "ts": "2026-01-02T09:00", "body": "Second" }] }],
+      "conflicts": [] }
   ],
   "manifest": {
     "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",

package/dist/extensions.cjs

@@ -641,6 +641,7 @@ function effectiveClaim(claim, hostDecl) {
 // src/extensions/merge.ts
 var ATOMIC = { kind: "atomic" };
 var SET = { kind: "set" };
+var COMMENTS = { kind: "comments" };
 var mapOf = (of) => ({ kind: "map", of });
 var keyedBy = (key, of, opts) => ({
   kind: "keyed",
@@ -683,6 +684,7 @@ function hasShape(spec, v) {
       return true;
     case "set":
     case "keyed":
+    case "comments":
       return Array.isArray(v);
     case "map":
     case "object":
@@ -722,6 +724,8 @@ function mergeValue(spec, b, o, t, id, path, ctx) {
     }
     case "keyed":
       return mergeKeyed(spec, asArr(b), o, t, path, ctx);
+    case "comments":
+      return mergeThreads(asArr(b), o, t, path, ctx);
   }
 }
 function mergeKeyed(spec, B, O, T, path, ctx) {
@@ -800,6 +804,70 @@ function preservedOrder(B, O, T, survivors, path, ctx) {
   for (const k of [...survivors.keys()].sort()) if (!result.includes(k)) result.push(k);
   return result;
 }
+function mergeComments(base, ours, theirs, opts) {
+  return mergeTree(COMMENTS, base, ours, theirs, opts);
+}
+function mergeThreads(B, O, T, path, ctx) {
+  const index = (arr) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const c of arr) if (isObject(c) && typeof c["id"] === "string") m.set(c["id"], c);
+    return m;
+  };
+  const Bm = index(B), Om = index(O), Tm = index(T);
+  const out = [];
+  for (const id of /* @__PURE__ */ new Set([...Bm.keys(), ...Om.keys(), ...Tm.keys()])) {
+    const b = Bm.get(id), o = Om.get(id), t = Tm.get(id);
+    const here = `${path}[${id}]`;
+    if (o === void 0 && t === void 0) continue;
+    if (![b, o, t].some((c) => Array.isArray(c?.["messages"]))) {
+      const v = o !== void 0 && t !== void 0 ? merge3(b, o, t, id, here, ctx) : b !== void 0 && ctx.eq(o ?? t, b) ? void 0 : o ?? t;
+      if (isObject(v)) out.push(v);
+      continue;
+    }
+    const messages = mergeMessages(b, o, t, id, here, ctx);
+    if (messages.length === 0 || messages.every((m) => m["deleted"] === true)) continue;
+    const fields = {};
+    if (o !== void 0 && t !== void 0) {
+      const B0 = b ?? {};
+      const flag = (c, k) => k === "resolved" ? c[k] === true ? true : void 0 : c[k];
+      for (const k of /* @__PURE__ */ new Set([...Object.keys(o), ...Object.keys(t), ...Object.keys(B0)])) {
+        if (k === "messages") continue;
+        const v = merge3(flag(B0, k), flag(o, k), flag(t, k), id, `${here}.${k}`, ctx);
+        if (v !== void 0) fields[k] = v;
+      }
+    } else {
+      for (const [k, v] of Object.entries(o ?? t)) if (k !== "messages") fields[k] = v;
+    }
+    out.push({ ...fields, messages });
+  }
+  const first = (c) => {
+    const m = asArr(c["messages"])[0];
+    return isObject(m) && typeof m["ts"] === "string" ? m["ts"] : "";
+  };
+  return out.sort((x, y) => first(x).localeCompare(first(y)) || String(x["id"]).localeCompare(String(y["id"])));
+}
+function mergeMessages(b, o, t, id, here, ctx) {
+  const keyOf = (m) => `${String(m["author"] ?? "")}|${String(m["ts"] ?? "")}`;
+  const index = (c) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const x of asArr(c?.["messages"])) if (isObject(x)) m.set(keyOf(x), x);
+    return m;
+  };
+  const Bm = index(b), Om = index(o), Tm = index(t);
+  const out = [];
+  for (const k of /* @__PURE__ */ new Set([...Bm.keys(), ...Om.keys(), ...Tm.keys()])) {
+    const mb = Bm.get(k), mo = Om.get(k), mt = Tm.get(k);
+    if ([mb, mo, mt].some((m) => m?.["deleted"] === true) || mb !== void 0 && (mo === void 0 || mt === void 0)) {
+      out.push({ ...mo ?? mt ?? mb, body: "", deleted: true });
+    } else if (mo !== void 0 && mt !== void 0) {
+      out.push(merge3(mb, mo, mt, id, `${here}.messages[${k}]`, ctx));
+    } else {
+      out.push(mo ?? mt);
+    }
+  }
+  const ts = (m) => String(m["ts"] ?? "");
+  return out.sort((x, y) => ts(x).localeCompare(ts(y)) || String(x["author"] ?? "").localeCompare(String(y["author"] ?? "")));
+}
 function strategyForType(decl) {
   switch (decl.type) {
     case "flags":
@@ -908,6 +976,7 @@ function orphanedEntries(data, exists) {
 }
 
 exports.ATOMIC = ATOMIC;
+exports.COMMENTS = COMMENTS;
 exports.HOSTS = HOSTS;
 exports.MANIFEST_FILE_SUFFIX = MANIFEST_FILE_SUFFIX;
 exports.MANIFEST_SCHEMA = MANIFEST_SCHEMA;
@@ -928,6 +997,7 @@ exports.keyedBy = keyedBy;
 exports.manifestProblems = manifestProblems;
 exports.mapOf = mapOf;
 exports.markUnresolved = markUnresolved;
+exports.mergeComments = mergeComments;
 exports.mergeExtensionData = mergeExtensionData;
 exports.mergeTree = mergeTree;
 exports.objectOf = objectOf;