create-githolon 0.96.0 → 0.97.0

package/index.mjs

@@ -1,106 +1,77 @@
 #!/usr/bin/env node
-// `npm create githolon <dir>` — scaffold a Nomos domain package (the starter
-// guestbook domain + compile config + live e2e) into <dir> and init it as a
-// git repo. The holon itself is MINTED LOCALLY after compile (`githolon ledger
-// init holon` — genesis + your law under YOUR identity, verified by the same
-// wasm gate the cloud runs), so it is yours from the first byte. Plain node,
-// zero dependencies; the heavy lifting (compile, codegen, the engine) lives in
-// @githolon/dsl and githolon and arrives with the scaffold's `npm install`.
-//
-// Everything scaffolded here belongs to the user — see LICENSE.md ("You may /
-// keep everything that's yours").
+
+// src/index.ts
 import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-
-const TEMPLATE = path.join(path.dirname(fileURLToPath(import.meta.url)), "template");
-
-const args = process.argv.slice(2);
+var HERE = path.dirname(fileURLToPath(import.meta.url));
+var TEMPLATE = path.join(HERE, "template");
+var NOMOS_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(path.join(HERE, "package.json"), "utf8")).version || "latest";
+  } catch {
+    return "latest";
+  }
+})();
+var args = process.argv.slice(2);
 if (args.includes("-h") || args.includes("--help")) {
   process.stdout.write(
-    "create-githolon — scaffold a Nomos domain package\n\n" +
-      "Usage:\n  npm create githolon <dir>        (or: npx create-githolon <dir>)\n\n" +
-      "Scaffolds the starter domain + compile config + live e2e into <dir>\n" +
-      "(default: my-holon-app) and inits a git repo. After `githolon compile`,\n" +
-      "`githolon ledger init holon` mints YOUR holon locally — verified by the\n" +
-      "same wasm gate the cloud runs, ready to birth by git push.\n\n" +
-      "Flags:\n  --no-git    skip git init\n",
+    "create-githolon \u2014 scaffold a Nomos domain package\n\nUsage:\n  npm create githolon <dir>        (or: npx create-githolon <dir>)\n\nScaffolds the starter domain + compile config + live e2e into <dir>\n(default: my-holon-app) and inits a git repo. After `githolon compile`,\n`githolon ledger init holon` mints YOUR holon locally \u2014 verified by the\nsame wasm gate the cloud runs, ready to birth by git push.\n\nFlags:\n  --no-git    skip git init\n"
   );
   process.exit(0);
 }
-const noGit = args.includes("--no-git");
-const dirArg = args.find((a) => !a.startsWith("-"));
-
-const targetDir = path.resolve(process.cwd(), dirArg ?? "my-holon-app");
-const appName = path
-  .basename(targetDir)
-  .toLowerCase()
-  .replace(/[^a-z0-9-_.]+/g, "-")
-  .replace(/^[-_.]+|[-_.]+$/g, "");
+var noGit = args.includes("--no-git");
+var dirArg = args.find((a) => !a.startsWith("-"));
+var targetDir = path.resolve(process.cwd(), dirArg ?? "my-holon-app");
+var appName = path.basename(targetDir).toLowerCase().replace(/[^a-z0-9-_.]+/g, "-").replace(/^[-_.]+|[-_.]+$/g, "");
 if (!appName) {
   console.error(`create-githolon: '${path.basename(targetDir)}' does not reduce to a valid package name`);
   process.exit(1);
 }
-
 if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
   console.error(`create-githolon: refusing to scaffold into non-empty directory: ${targetDir}`);
   process.exit(1);
 }
-
 mkdirSync(targetDir, { recursive: true });
 cpSync(TEMPLATE, targetDir, { recursive: true });
-
-// npm strips dotfiles from published packages — the template ships `gitignore`
-// and the scaffold restores the dot.
 renameSync(path.join(targetDir, "gitignore"), path.join(targetDir, ".gitignore"));
-
-// Same dotfile-restore for the VS Code workspace recommendation: the template ships
-// `vscode/` (no dot; a leading-dot dir does not reliably survive `npm publish`), and
-// the scaffold restores `.vscode/` so opening the project prompts installing the
-// Nomos Law extension (the author-time check gate as red squiggles while typing).
 if (existsSync(path.join(targetDir, "vscode"))) {
   renameSync(path.join(targetDir, "vscode"), path.join(targetDir, ".vscode"));
 }
-
-// Parameterize the scaffold to the app name. The generated typed client + its baked
-// hash const are NAMED off the package name (`__APP_NAME__`): the artifact filename
-// keeps the raw name (build/<app>.client.ts), the hash SYMBOL normalizes it to
-// UPPER_SNAKE (the same transform `githolon compile` uses — see codegen_ts.ts). The
-// client FACTORY (`todoClient`) is named off the DOMAIN key, which stays `todo`.
-const appHash = `${appName.replace(/[-\s]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}_DOMAIN_HASH`;
-const subst = (s) => s.replaceAll("__APP_NAME__", appName).replaceAll("__APP_HASH__", appHash);
+var appHash = `${appName.replace(/[-\s]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}_DOMAIN_HASH`;
+var subst = (s) => s.replaceAll("__APP_NAME__", appName).replaceAll("__APP_HASH__", appHash).replaceAll("__NOMOS_VERSION__", NOMOS_VERSION);
 for (const f of ["package.json", "README.md", "nomos.package.mjs", "CLAUDE.md", "domains/todo.ts", "test/e2e.mts"]) {
   const p = path.join(targetDir, f);
   if (existsSync(p)) writeFileSync(p, subst(readFileSync(p, "utf8")), "utf8");
 }
-
-const git = (cmd) => spawnSync("git", cmd, { cwd: targetDir, stdio: "ignore" }).status === 0;
-
-// git init. Degrades gracefully: no git leaves a perfectly usable scaffold.
-let gitInited = false;
+var git = (cmd) => spawnSync("git", cmd, { cwd: targetDir, stdio: "ignore" }).status === 0;
+var gitInited = false;
 if (!noGit) {
   gitInited = git(["init", "-b", "main"]) || git(["init"]);
   if (gitInited) {
     git(["add", "-A"]);
-    // Identity fallback keeps the initial commit working on unconfigured machines.
-    git(["commit", "-m", "scaffold: create-githolon starter"]) ||
-      git(["-c", "user.name=create-githolon", "-c", "user.email=create-githolon@nomos", "commit", "-m", "scaffold: create-githolon starter"]);
+    git(["commit", "-m", "scaffold: create-githolon starter"]) || git(["-c", "user.name=create-githolon", "-c", "user.email=create-githolon@nomos", "commit", "-m", "scaffold: create-githolon starter"]);
   }
 }
-
-const rel = path.relative(process.cwd(), targetDir) || ".";
+var rel = path.relative(process.cwd(), targetDir) || ".";
 process.stdout.write(
-  `\nScaffolded ${appName} into ${rel}/${gitInited ? " (git repo)" : ""}\n` +
-    `\nRead docs/01-mental-model.md first — the docs travel with you, offline.\n` +
-    `\nNext:\n` +
-    `  cd ${rel}\n` +
-    `  npm install\n` +
-    `  npx githolon compile        # → build/: deployable package + manifests + typed client + a generated proof\n` +
-    `  npx githolon proof          # run that proof live — GENERATED from your own law, no test rewriting\n` +
-    `  npx githolon login --agent  # a verified identity, no browser\n\n` +
-    `Then pick a path (README.md walks both):\n` +
-    `  A) npx githolon ws create <ws> && npx githolon deploy <ws>\n` +
-    `  B) npx githolon ledger init holon   # YOUR holon, minted + verified LOCALLY\n` +
-    `     cd holon && npx githolon git remote <ws> && git push nomos main\n`,
+  `
+Scaffolded ${appName} into ${rel}/${gitInited ? " (git repo)" : ""}
+
+Read docs/01-mental-model.md first \u2014 the docs travel with you, offline.
+
+Next:
+  cd ${rel}
+  npm install
+  npx githolon compile        # \u2192 build/: deployable package + manifests + typed client + a generated proof
+  npx githolon proof          # run that proof live \u2014 GENERATED from your own law, no test rewriting
+  npx githolon login --agent  # a verified identity, no browser
+
+Your law compiles + proves OFFLINE today (compile + proof above \u2014 no cloud, no account).
+To run it LIVE, deploy to a workspace you own: a workspace is born by its PARENT (a platform
+you control births homes/children \u2014 birthHome/birthChild). There is no host-side create \u2014 the
+flat 'ws create' lane is retired (orphanless holarchy). See docs/04-cloud.md for the birth-on-
+parent flow; self-serve keyless birth-under-root is in flight.
+`
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "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",
@@ -18,5 +18,16 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsx build.ts",
+    "prepublishOnly": "tsx build.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "@types/node": "^25.9.2"
   }
 }

package/template/README.md

@@ -43,8 +43,9 @@ before serving anything. Authority lives in the git; no holon outranks another.
 npx githolon ledger init holon    # mint + assert locally: chain VALID, head <h>, under YOUR uid
 npx githolon ledger verify holon  # re-assert any time
 cd holon
-npx githolon git remote <ws>      # wires the remote + credential helper; mints + stores the owner secret
-git push nomos main            # the upload birth — the cloud re-derives the verdict, byte-identical adoption
+npx githolon ws create <ws>       # birth the workspace (its parent's offer-effect); no secret minted
+npx githolon git remote <ws>      # wire the remote + credential helper for syncing
+git push nomos refs/heads/session/<id>  # sync your writes to the edge (main is not push-writable)
 npx githolon deploy <ws>          # idempotent (alreadyInstalled) + stages the read manifests so queries route
 cd ..
 ```

package/template/docs/04-cloud.md

@@ -19,29 +19,24 @@ the principal births will ride; sessions auto-refresh from
 
 ## Two deploy lanes, one destination
 
-**Path A — deploy your law** (the cloud births the workspace):
+**Deploy your law** (the cloud births the workspace by its parent's offer-effect):
 
 ```bash
 npx githolon ws create <ws>   # birth; NO secret is minted — ownership is a law fact in the chain
 npx githolon deploy <ws>      # POST build/<pkg>.deploy.json, authenticated as your principal
 ```
 
-**Path B — the upload birth** (you birth it, the cloud verifies):
-
-```bash
-npx githolon ledger init holon
-cd holon && npx githolon git remote <ws> && git push nomos main
-```
-
-Both end in the same place — all holons are equal in authority; the chain
-proves itself either way ([05-superpowers.md](./05-superpowers.md) walks B).
+A workspace is born ONLY by its PARENT authoring its birth (an offer-effect that records the
+child in the parent's own chain). There is no "push a repo to create a workspace" — pushing
+`refs/heads/main` to an unborn name is refused. You sync your work by pushing session branches
+(`refs/heads/session/<client-id>`) to an EXISTING workspace; child workspaces you author offline
+(e.g. an estate under a home in local custody) materialize on the cloud when you sync the parent.
 
 ## Ownership
 
-There is no host secret. Ownership is a LAW FACT bound IN THE CHAIN —
-`sha256(the push password)` written onto the law record at the upload birth (push
-with no password ⇒ born OPEN). Born-ness derives from custody (the ledger has a
-`main`); `/boot` returns no secret. DEPLOY write-authority is judged by the
+There is no host secret. Ownership is a LAW FACT bound IN THE CHAIN — the principal the parent's
+birth records as the owner (e.g. `HomeOwner.principal`). Born-ness derives from custody (the ledger
+has a `main`); `/boot` returns no secret. DEPLOY write-authority is judged by the
 KERNEL at the offer gate — you authenticate as a principal the law grants deploy
 authority (`x-nomos-auth`, or transitionally `x-nomos-principal`), not a Bearer
 secret. End-user apps carry no credential: reads and session pushes are open,

package/template/docs/05-superpowers.md

@@ -16,26 +16,29 @@ identity>` — and verifies the chain with the SAME byte-identical wasm gate the
 cloud runs. This is not a mock or a dev server. It is a holon, born valid,
 and you can assert that yourself, offline, before any network exists.
 
-## The upload birth — the cloud re-derives YOUR verdict
+## Offline birth — the parent births the child, the cloud re-derives it on sync
+
+A workspace is born ONLY by its PARENT authoring its birth. You don't push a repo to create a
+workspace; you author the birth on a parent you hold, and the child materializes when the parent
+syncs (or when you offer the birth to the parent's edge online). A home you hold in local custody
+can birth an estate OFFLINE — no network — and the cloud materializes that estate, byte-identical,
+the moment the home syncs:
 
 ```bash
 cd holon
-npx githolon git remote <ws>   # wires the remote + credential helper, mints the owner secret
-git push nomos main            # stock git; the credential helper answers the 401
+npx githolon git remote <ws>              # wire the remote + credential helper for THIS workspace
+git push nomos refs/heads/session/<id>    # sync your writes (incl. any births you authored) to the edge
 ```
 
-Pushing `refs/heads/main` to an unborn workspace births it FROM YOUR REPO. The
-cloud replay-verifies the whole chain from genesis — contiguity, every intent
-re-admitted against the state folded from the chain prefix, every plan re-run
-and byte-compared — and re-derives your exact local verdict: same head, same
-plans. Valid ⇒ custody adopts your head BYTE-IDENTICAL (no re-seal), and
-sha256 of your push password becomes the owner credential. Invalid ⇒ archived
-under `refs/heads/refused/`, the workspace stays unborn, the verdict rides
-`githolon ws status <ws>`. The pushed bytes buy nothing; the chain proves
-itself. The git holon executes — and thus validates — itself.
-
-Why this matters: deployment is `git push`, the audit trail is `git log`, and
-"does the cloud agree with my machine?" is a checkable equation, not a hope.
+The cloud replay-verifies every synced intent — contiguity, each intent re-admitted against the
+state folded from the chain prefix, every plan re-run and byte-compared — and re-derives your exact
+local verdict: same head, same plans. A birth intent's consequence is the child, materialized in
+cloud custody with an immutable `nomos-birth-record` on the parent (so the whole tree is walkable
+from root — no orphans). Pushing `refs/heads/main` to an unborn name is REFUSED: the pushed bytes
+buy nothing; a workspace comes to exist through its parent's law, not a push.
+
+Why this matters: authorship is `git log`, "does the cloud agree with my machine?" is a checkable
+equation, and every workspace's parentage is a verifiable ledger fact — no host says what exists.
 
 ## Byte-identical wasm everywhere
 

package/template/package.json

@@ -11,12 +11,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@githolon/dsl": "^0.16.0",
-    "@githolon/client": "^0.16.0",
+    "@githolon/dsl": "^__NOMOS_VERSION__",
+    "@githolon/client": "^__NOMOS_VERSION__",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "githolon": "^0.16.0",
+    "githolon": "^__NOMOS_VERSION__",
     "@types/node": "^25.9.2",
     "tsx": "^4.19.2",
     "typescript": "^5.6.3"