create-githolon 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Scaffold a Nomos domain package: the starter domain + compile config + live e2e. `npm create githolon my-app`.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -19,4 +19,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/template/README.md

@@ -43,6 +43,34 @@ After birth, `holon/` tracks YOUR workspace: new writes admitted on main arrive
 with `git pull`. (`githolon git setup` installed a git credential helper, so plain
 git just works against the cloud.)
 
+## Make it YOURS — the five-minute walkthrough
+
+The starter is the tutorial; this is the exact path from guestbook to your own law.
+
+1. **Rename the law file** and reshape it:
+   `git mv domains/guestbook.ts domains/<yours>.ts` — keep the patterns
+   (aggregate fields each tagged a merge driver; directives = zod payload → pure
+   plan; `addToSet` for AddWins sets — `set()` on a set field is refused).
+2. **Point the compile config at it** — `nomos.package.mjs`:
+   ```js
+   export default { name: "<pkg>", domains: [{ key: "<pkg>", modules: ["./domains/<yours>.ts"] }] };
+   ```
+   **Naming convention:** make `<pkg>` ONE lowercase word (`potluck`, `studygroup`).
+   It becomes the generated symbols verbatim: `build/<pkg>.client.ts` exporting
+   `<pkg>Client(holon)` and `<PKG>_DOMAIN_HASH`.
+3. **Compile and read what you built:**
+   ```bash
+   npx githolon compile && cat build/<pkg>.summary.txt
+   ```
+4. **Re-point the proof** — in `test/e2e.mts`, update the client import and the
+   directive/query/count names to yours; `npm run typecheck` names every stale
+   reference until it's clean.
+5. **Prove it live:** `npm run e2e` — your law deploys to a throwaway workspace,
+   an offline write syncs through admission, the cloud answers your declared
+   query and count, and two blind clients prove the AddWins merge.
+
+Then deploy it for real: `npx githolon login --agent && npx githolon ws create <ws> && npx githolon deploy <ws>`.
+
 ## What's here
 
 - `domains/guestbook.ts` — the starter domain (the law): one aggregate, two

package/template/domains/guestbook.ts

@@ -24,6 +24,7 @@ import {
   instance,
   set,
   setEntry,
+  addToSet,
   query,
   derived,
   count,
@@ -76,6 +77,17 @@ export const signGuestbook = directive("signGuestbook")
     return [];
   });
 
+/**
+ * Tag an entry — the ADDITIVE set write. Two people tagging the SAME entry at
+ * the SAME time both win: AddWins unions the adds, nothing is lost. (addToSet
+ * is the ONLY additive write to an AddWins set — set() would overwrite, and is
+ * refused at both the type level and runtime.)
+ */
+export const tagEntry = directive("tagEntry")
+  .mutates(GuestbookEntry)
+  .payload(z.object({ entryId: z.string(), tags: z.array(z.string()).min(1) }))
+  .plan((p) => [addToSet(instance(GuestbookEntry, p.entryId), "tags", p.tags)]);
+
 /** React to an entry: a map-PUT at the reactor's key (concurrent reactors commute). */
 export const reactToEntry = directive("reactToEntry")
   .mutates(GuestbookEntry)

package/template/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@githolon/dsl": "^0.1.0",
-    "githolonent": "^0.1.0",
+    "@githolon/client": "^0.1.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/template/test/e2e.mts

@@ -8,14 +8,14 @@
 //
 // Run from this directory AFTER `npx nomos-compile`:  npx tsx test/e2e.mts
 import { readFileSync } from "node:fs";
-// @ts-expect-error — plain-JS package (no type declarations); structurally satisfies NomosHolon
-import { connect } from "githolonent";
+import { connect } from "@githolon/client";
 import { guestbookClient, GUESTBOOK_DOMAIN_HASH } from "../build/guestbook.client.ts";
 
 const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\/+$/, "");
 const WS = process.env.NOMOS_WS || "gb-e2e-" + Math.random().toString(36).slice(2, 8);
 
-const fail = (m: string): never => { console.error("✗ " + m); process.exit(1); };
+// explicit annotation on the const so TS's never-call narrowing applies after fail(...)
+const fail: (m: string) => never = (m) => { console.error("✗ " + m); process.exit(1); };
 const ok = (m: string) => console.log("✓ " + m);
 
 const deploy = JSON.parse(readFileSync(new URL("../build/guestbook.deploy.json", import.meta.url), "utf8"));
@@ -99,7 +99,23 @@ d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/counts/entriesPerMood?group
 if (!(d.ok && d.count === 1)) fail(`cloud count: ${JSON.stringify(d)}`);
 ok("cloud count endpoint — entriesPerMood[delighted] = 1 (O(1) maintained read)");
 
-// 9. CONVERGENCE: the same instance adopts canonical main inside sync() — no reconnect
+// 9. CONCURRENCY — the canonical AddWins demo: two writers = two connect()s with
+//    DIFFERENT clientIds; each tags the same entry OFFLINE, blind to the other;
+//    admission merges both and the AddWins union keeps every add.
+const taggerA = await connect({ cloud: CLOUD, workspace: WS, clientId: "tagger-a" });
+const taggerB = await connect({ cloud: CLOUD, workspace: WS, clientId: "tagger-b" });
+await guestbookClient(taggerA).tagEntry({ entryId, tags: ["vegan"] });
+await guestbookClient(taggerB).tagEntry({ entryId, tags: ["gluten-free"] });
+await taggerA.sync({ admit: true });
+await taggerB.sync({ admit: true });
+d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/aggregates/${encodeURIComponent(entryId)}`)).json();
+const mergedTags: string[] = d.rows?.[0]?.data?.tags ?? [];
+if (!(mergedTags.includes("vegan") && mergedTags.includes("gluten-free"))) fail(`AddWins union lost an add: ${JSON.stringify(mergedTags)}`);
+ok(`concurrent tags from two offline clients ALL survive the merge — [${[...mergedTags].sort().join(", ")}]`);
+
+// 10. CONVERGENCE: the ORIGINAL instance adopts canonical main — including the two
+//     taggers' admitted writes — inside a pull; no reconnect, no rebuild.
+await holon.pull();
 const head = await holon.head();
 const refsAdv = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/git/info/refs?service=git-upload-pack`)).text();
 const remoteMain = (refsAdv.match(/([0-9a-f]{40}) refs\/heads\/main/) || [])[1];