@intentius/behold 0.4.1 → 0.5.0

package/README.md

@@ -28,6 +28,10 @@ npx @intentius/behold demo            # copies the example to ./behold-demo, ins
 ```
 
 The copied project is yours: edit its source and watch the graph change live.
+There's a whole catalog — `behold demo --list` names the rest (`behold demo
+k8s` stands the same loop up on a throwaway k3d cluster: runtime Pods, field
+ownership). Every loaded demo lands in the panel's recents, so switching
+between them is the Scope tab.
 
 Already have a chant project?
 

package/demos.json

@@ -0,0 +1,30 @@
+{
+  "demos": [
+    {
+      "name": "writes",
+      "description": "One S3 bucket + policy on a local Floci emulator — blue to green in five minutes. The default.",
+      "source": "bundled",
+      "dir": "example-writes",
+      "requires": ["docker"],
+      "serve": { "local": true, "env": "prod" }
+    },
+    {
+      "name": "k8s",
+      "description": "An nginx Deployment + Service on a throwaway k3d cluster — runtime children (Pods), field ownership, honest unobserved. Cluster persists across runs; scripts/local/local-down.sh removes it.",
+      "source": "bundled",
+      "dir": "example-k8s",
+      "requires": ["docker", "k3d", "kubectl"],
+      "setup": "bash scripts/local/local-up.sh",
+      "serve": { "local": true, "env": "local" }
+    },
+    {
+      "name": "fountain",
+      "description": "The mature estate: self-hosted fountain (a real app) on a throwaway k3d cluster — tiers (try the ha tier picker), seams, drift, runtime Pods. Clones INTENTIUS/fountain-ops; ~5 minutes, mostly image pulls. `just down` in the clone removes the cluster.",
+      "source": "git",
+      "repo": "https://github.com/INTENTIUS/fountain-ops",
+      "requires": ["docker", "k3d", "kubectl", "jq", "just"],
+      "setup": "just up",
+      "serve": { "env": "local" }
+    }
+  ]
+}

package/dist/cli.js

@@ -1,7 +1,7 @@
 // src/cli.ts
-import { resolve as resolve3, dirname as dirname5, join as join12, relative as relative2, sep } from "node:path";
+import { resolve as resolve3, dirname as dirname5, join as join13, relative as relative2, sep } from "node:path";
 import { realpathSync, existsSync as existsSync10, cpSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/server.ts
@@ -4611,6 +4611,9 @@ async function startServer(cfg) {
       );
     }
   }
+  for (const dir of cfg.projectDirs ?? [cfg.projectDir]) {
+    if (existsSync9(join10(dir, "chant.config.ts"))) addRecent(dir);
+  }
   const broadcaster = new Broadcaster();
   const frames = new FrameBuffer();
   const runner = new OpRunner({
@@ -4714,9 +4717,43 @@ async function startServer(cfg) {
   });
 }
 
+// src/demos.ts
+import { readFileSync as readFileSync8 } from "node:fs";
+import { join as join11 } from "node:path";
+import { spawnSync } from "node:child_process";
+function loadDemoRegistry(pkgRoot) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync8(join11(pkgRoot, "demos.json"), "utf8"));
+  } catch {
+    return [];
+  }
+  const list = raw?.demos;
+  if (!Array.isArray(list)) return [];
+  return list.filter((e) => {
+    const d = e;
+    if (!d || typeof d.name !== "string" || !d.name || typeof d.description !== "string") return false;
+    if (d.source === "bundled") {
+      if (typeof d.dir !== "string" || !d.dir) return false;
+    } else if (d.source === "git") {
+      if (typeof d.repo !== "string" || !d.repo) return false;
+    } else {
+      return false;
+    }
+    if (!Array.isArray(d.requires) || d.requires.some((r) => typeof r !== "string")) return false;
+    if (!d.serve || typeof d.serve !== "object") return false;
+    return true;
+  });
+}
+function missingRequirements(entry) {
+  const bins = entry.source === "git" && !entry.requires.includes("git") ? [...entry.requires, "git"] : entry.requires;
+  const finder = process.platform === "win32" ? "where" : "which";
+  return bins.filter((bin) => spawnSync(finder, [bin], { stdio: "ignore" }).status !== 0);
+}
+
 // src/export.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync8, readdirSync as readdirSync4 } from "node:fs";
-import { join as join11, dirname as dirname4, basename } from "node:path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync9, readdirSync as readdirSync4 } from "node:fs";
+import { join as join12, dirname as dirname4, basename } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var LENS_PARAMS = ["components", "detail", "env", "logical", "radial", "tier"];
 function canonicalKey(path, params) {
@@ -4764,7 +4801,7 @@ function captureKeys(axes) {
   return [...keys];
 }
 function webDir() {
-  return join11(dirname4(fileURLToPath2(import.meta.url)), "..", "web");
+  return join12(dirname4(fileURLToPath2(import.meta.url)), "..", "web");
 }
 function workerName(project, override) {
   const raw = override ?? `behold-${basename(project)}`;
@@ -4775,7 +4812,7 @@ async function runExport(cfg, outDir, opts = {}) {
   const app = createApp(cfg);
   const proj = await (await app.request("/api/project")).json();
   const axes = { environments: proj.environments ?? [], tiers: proj.tiers ?? [] };
-  const snapDir = join11(outDir, "snapshots");
+  const snapDir = join12(outDir, "snapshots");
   mkdirSync2(snapDir, { recursive: true });
   const keyToFile = {};
   let ok = 0;
@@ -4784,7 +4821,7 @@ async function runExport(cfg, outDir, opts = {}) {
     const res = await app.request(key);
     const body = await res.text();
     const file = slug(key);
-    writeFileSync2(join11(snapDir, file), body);
+    writeFileSync2(join12(snapDir, file), body);
     keyToFile[key] = `snapshots/${file}`;
     if (res.ok) ok++;
     else failed++;
@@ -4796,21 +4833,21 @@ async function runExport(cfg, outDir, opts = {}) {
     axes,
     keyToFile
   };
-  writeFileSync2(join11(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-  const html = readFileSync8(join11(webDir(), "index.html"), "utf8").replace(
+  writeFileSync2(join12(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  const html = readFileSync9(join12(webDir(), "index.html"), "utf8").replace(
     /<\/head>/i,
     `  <script>window.__BEHOLD_STATIC__ = true;</script>
   </head>`
   );
-  writeFileSync2(join11(outDir, "index.html"), html);
+  writeFileSync2(join12(outDir, "index.html"), html);
   for (const f of readdirSync4(webDir())) {
     if (f === "index.html") continue;
-    copyFileSync(join11(webDir(), f), join11(outDir, f));
+    copyFileSync(join12(webDir(), f), join12(outDir, f));
   }
-  writeFileSync2(join11(outDir, "README.md"), BUNDLE_README);
+  writeFileSync2(join12(outDir, "README.md"), BUNDLE_README);
   const name = workerName(cfg.projectDir, opts.name);
   writeFileSync2(
-    join11(outDir, "wrangler.jsonc"),
+    join12(outDir, "wrangler.jsonc"),
     JSON.stringify(
       { $schema: "node_modules/wrangler/config-schema.json", name, compatibility_date: "2025-06-01", assets: { directory: "." } },
       null,
@@ -4861,17 +4898,20 @@ It's just files \u2014 GitHub Pages, S3, nginx, or Cloudflare Pages
 var USAGE = `behold \u2014 a live control plane on chant (read-only core)
 
 Usage:
-  behold demo [target-dir] [--port <n>]
+  behold demo [name] [target-dir] [--port <n>] [--list]
   behold preview [project-dir] [--port <n>] [--emulator]
   behold export [project-dir] [--out <dir>] [--env <name>] [--name <worker>] [--emulator]
   behold serve <project-dir\u2026> [--port <n>] [--env <name>] [--poll <secs>] [--local]
 
-  demo    The five-minute path from npm \u2014 no chant project needed. Copies the
-          bundled example (an S3 bucket + policy) into ./behold-demo (or
-          [target-dir]), installs its dependencies, and serves it against a
-          local emulator: blue = declared, click Deploy, watch it turn green.
-          Needs Docker. The copy is yours \u2014 edit its source and watch the
-          graph change live.
+  demo    The five-minute path from npm \u2014 no chant project needed. A catalog
+          of demo estates (behold demo --list): bundled ones copy out of the
+          package into a directory that's yours to edit; git ones shallow-
+          clone a public estate. Bare \`behold demo\` is the AWS example \u2014 an
+          S3 bucket + policy on a local emulator: blue = declared, click
+          Deploy, watch it turn green. \`behold demo k8s\` stands a workload
+          up on a throwaway k3d cluster instead. Needs Docker (and per-demo
+          tools --list names). Loaded demos land in the panel's recents, so
+          switching between them is the Scope tab.
 
   export  Capture the live estate into a self-contained, interactive STATIC
           bundle (default ./behold-export) \u2014 every env/tier \xD7 zoom \xD7 radial,
@@ -5020,7 +5060,7 @@ ${USAGE}`);
   });
 }
 function warnIfNotChantProject(dir) {
-  if (existsSync10(join12(dir, "chant.config.ts"))) return;
+  if (existsSync10(join13(dir, "chant.config.ts"))) return;
   process.stderr.write(
     `behold: warning \u2014 ${dir} has no chant.config.ts; this doesn't look like a chant project.
         No project yet? \`behold demo\` serves a bundled working example (needs Docker).
@@ -5028,14 +5068,37 @@ function warnIfNotChantProject(dir) {
   );
 }
 async function runDemo(rest) {
+  const pkgRoot = join13(dirname5(fileURLToPath3(import.meta.url)), "..");
+  const registry = loadDemoRegistry(pkgRoot);
   let port = 4600;
+  let name;
   let dirArg;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--port") port = Number(rest[++i]);
-    else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
-    else if (!a.startsWith("-")) dirArg = a;
-    else {
+    else if (a === "--list") {
+      if (!registry.length) {
+        process.stdout.write("behold demo: no catalog in this install (demos.json missing)\n");
+        return;
+      }
+      for (const e of registry) {
+        const missing2 = missingRequirements(e);
+        const ready = missing2.length ? `needs ${missing2.join(", ")}` : "ready";
+        process.stdout.write(`  ${e.name.padEnd(14)} ${ready.padEnd(20)} ${e.description}
+`);
+      }
+      process.stdout.write("\nRun one: behold demo <name>   (bare `behold demo` = writes)\n");
+      return;
+    } else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
+    else if (!a.startsWith("-")) {
+      if (!name && registry.some((e) => e.name === a)) name = a;
+      else if (!dirArg) dirArg = a;
+      else {
+        process.stderr.write(`behold demo: unexpected argument '${a}'
+`);
+        process.exit(2);
+      }
+    } else {
       process.stderr.write(`behold demo: unexpected argument '${a}'
 `);
       process.exit(2);
@@ -5045,34 +5108,75 @@ async function runDemo(rest) {
     process.stderr.write("behold demo: --port must be a number\n");
     process.exit(2);
   }
-  const bundled = join12(dirname5(fileURLToPath3(import.meta.url)), "..", "example-writes");
-  if (!existsSync10(bundled)) {
-    process.stderr.write("behold demo: this install has no bundled example project (example-writes)\n");
+  const entry = registry.find((e) => e.name === (name ?? "writes"));
+  if (!entry) {
+    process.stderr.write(`behold demo: no "${name ?? "writes"}" in this install's catalog \u2014 behold demo --list
+`);
+    process.exit(2);
+  }
+  const missing = missingRequirements(entry);
+  if (missing.length) {
+    process.stderr.write(`behold demo ${entry.name}: missing ${missing.join(", ")} \u2014 install and re-run.
+`);
     process.exit(2);
   }
-  const target = resolve3(dirArg ?? "behold-demo");
+  const target = resolve3(
+    dirArg ?? (entry.name === "writes" && existsSync10("behold-demo") ? "behold-demo" : join13("behold-demos", entry.name))
+  );
   if (!existsSync10(target)) {
-    process.stdout.write(`behold demo \u2192 copying the example project to ${target} (it's yours \u2014 edit it)
+    if (entry.source === "bundled") {
+      const bundled = join13(pkgRoot, entry.dir);
+      if (!existsSync10(bundled)) {
+        process.stderr.write(`behold demo ${entry.name}: this install has no bundled ${entry.dir}
 `);
-    cpSync(bundled, target, {
-      recursive: true,
-      filter: (src) => !relative2(bundled, src).split(sep).includes("node_modules")
-    });
+        process.exit(2);
+      }
+      process.stdout.write(`behold demo ${entry.name} \u2192 copying to ${target} (it's yours \u2014 edit it)
+`);
+      cpSync(bundled, target, {
+        recursive: true,
+        filter: (src) => !relative2(bundled, src).split(sep).includes("node_modules")
+      });
+    } else {
+      process.stdout.write(`behold demo ${entry.name} \u2192 cloning ${entry.repo} to ${target}
+`);
+      const r = spawnSync2("git", ["clone", "--depth", "1", entry.repo, target], { stdio: "inherit" });
+      if (r.status !== 0) {
+        process.stderr.write(`behold demo ${entry.name}: clone failed
+`);
+        process.exit(r.status ?? 1);
+      }
+    }
   } else {
-    process.stdout.write(`behold demo \u2192 reusing ${target}
+    process.stdout.write(`behold demo ${entry.name} \u2192 reusing ${target}
 `);
   }
-  if (!existsSync10(join12(target, "node_modules"))) {
-    process.stdout.write("behold demo \u2192 npm install (the example's own chant + lexicons)\u2026\n");
-    const r = spawnSync("npm", ["install"], { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
+  if (existsSync10(join13(target, "package.json")) && !existsSync10(join13(target, "node_modules"))) {
+    process.stdout.write(`behold demo ${entry.name} \u2192 npm install\u2026
+`);
+    const r = spawnSync2("npm", ["install"], { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
     if (r.status !== 0) {
       process.stderr.write(`behold demo: npm install failed in ${target}${r.error ? ` (${r.error.message})` : ""}
 `);
       process.exit(r.status ?? 1);
     }
   }
-  process.stdout.write("behold demo \u2192 serving with a local emulator (Docker). Blue = declared; Deploy turns it green.\n");
-  await run3(["serve", target, "--local", "--env", "prod", "--port", String(port)]);
+  if (entry.setup) {
+    process.stdout.write(`behold demo ${entry.name} \u2192 ${entry.setup}
+`);
+    const r = spawnSync2(entry.setup, { cwd: target, stdio: "inherit", shell: true });
+    if (r.status !== 0) {
+      process.stderr.write(`behold demo ${entry.name}: setup failed (${entry.setup})
+`);
+      process.exit(r.status ?? 1);
+    }
+  }
+  process.stdout.write(`behold demo ${entry.name} \u2192 serving. Blue = declared; Deploy turns it green.
+`);
+  const serveArgs = ["serve", target, "--port", String(port)];
+  if (entry.serve.local) serveArgs.push("--local");
+  if (entry.serve.env) serveArgs.push("--env", entry.serve.env);
+  await run3(serveArgs);
 }
 function injectEmulatorEnv(env) {
   process.env.LOOM_ENV ??= env ?? "local";

package/example-k8s/README.md

@@ -0,0 +1,120 @@
+# The k3d turnkey demo — behold's Kubernetes counterpart to Loom-on-Floci
+
+The smallest real thing on Kubernetes: one `nginx` Deployment + Service (+ a
+PodDisruptionBudget), deployed from the browser with the **▶ Deploy
+(k3d-apply)** header button, against a local, single-node
+[k3d](https://k3d.io) cluster — no cloud account, no credentials.
+
+```
+src/config.ts        static config — app name, pinned image tag
+src/web.ts            WebApp composite → Deployment + Service + PodDisruptionBudget
+ops/k3d-apply.op.ts   ApplyOp "k3d-apply" — code → local k3d, server-side apply
+chant.config.ts       lexicons [k8s, temporal], k8s.profiles.local bound to k3d-behold-k3d-demo
+scripts/local/        local-up.sh / local-down.sh — the k3d cluster's own lifecycle
+```
+
+## Run it
+
+From the **behold** repo root:
+
+```sh
+npm run demo:k8s
+#   → brings up a single-node k3d cluster ("behold-k3d-demo"),
+#     then serves this project at http://localhost:4600
+```
+
+That one command does two things: `scripts/local/local-up.sh` creates the
+cluster (idempotent — reuses one already up), then `behold serve --local`
+points its live overlay at it. `--local`'s usual boot step (`chant emulator
+up`) is a no-op here — chant's k8s lexicon has no local-emulator capability
+the way Floci does for aws — so the cluster comes up via the same generic
+substrate **Bring up** mechanism the Floci demo's `scripts/local/local-up.sh`
+convention already uses (see `src/substrates.ts`), just run up front instead
+of from a click. Ctrl-C stops `behold serve` and tears the cluster back down;
+Docker or k3d missing degrades to the source graph with a clear message
+instead of crashing.
+
+1. Open **http://localhost:4600**. The graph shows the Deployment, Service and
+   PodDisruptionBudget — **blue** (declared, not yet deployed).
+2. Click **▶ Deploy (k3d-apply)** in the header (or ⌘K → "Deploy: Sync"). The
+   now-line streams Build → Plan (a live
+   diff) → Apply: a Kubernetes **server-side apply**, field manager
+   `chant:behold-k3d-demo` (chant#1074/#1075) — deletes are **owned-only**, a
+   marker-scoped prune that only ever touches what chant itself applied.
+3. The three nodes flip **blue → green (managed)**. Zoom in on the Deployment
+   and its two Pods appear **nested underneath it** — the runtime tier
+   (chant#1077/behold#86): live children a Deployment's controller created,
+   never declared here, never classified as drift or an orphan.
+
+## The four things this proves live (epic #84)
+
+behold's k8s parity (#85–#87) shipped against fixtures; this is it against a
+real cluster.
+
+**Declared, not yet deployed.** Before step 2, `/api/overlay` reports all
+three nodes `_status: accent` (pending) — chant knows about them, the cluster
+doesn't yet.
+
+**Runtime children.** After apply, `/api/overlay`'s `ir.groups.byContainer`
+nests the Deployment's Pods under it, each `_status: runtime` — a tier below
+what's declared, sourced from the cluster's own `ownerReferences`, that
+behold's zoom dial can descend into.
+
+**Managed-fields drift.** Scale or label the Deployment out of band —
+`kubectl scale deployment/web --replicas=3`, bypassing chant entirely — and
+`/api/diff`'s `fieldDrift` reports `spec.replicas: { kind: "changed", declared:
+2, live: 3 }`: chant's own SSA-tracked field, now diverged from a competing
+field manager (`kubectl`, visible in `kubectl get deploy/web -o json`'s
+`metadata.managedFields`). Re-running `k3d-apply` at that point doesn't
+silently overwrite it: chant's server-side apply refuses —
+
+```
+k8s: server-side apply of apps/v1 Deployment web was refused — 1 field is owned by another field manager.
+
+  "kubectl" owns:
+    .spec.replicas
+
+chant applied as field manager "chant:behold-k3d-demo". Taking these fields means the managers above
+stop owning them, and will contest them again on their next apply.
+```
+
+— naming the contested path and the competing manager, and leaving the field
+alone rather than force-resolving it. (One honest gap found running this
+live: a **new** out-of-band key with no chant-declared counterpart at all —
+`kubectl label deployment/web team=platform`, which has no corresponding
+`web.spec` field in `src/web.ts` — doesn't currently surface in `fieldDrift`,
+only a value change to a field chant *does* declare does. Worth a follow-up
+issue on the chant side; noted here rather than papered over.)
+
+**Unobserved.** `chant.config.ts` binds environment `local` to kubectl context
+`k3d-behold-k3d-demo` (chant#1100) — every read/apply checks that binding
+against whatever context is actually ambient, and refuses rather than reading
+the wrong cluster. Switch away from it for a moment —
+
+```sh
+kubectl config use-context <anything-else>
+```
+
+— and `/api/overlay` flips every node to `_status: neutral` with
+`unobservedReason: "read-failed"`, Pods and all: an honest "did not look",
+never a false "these are all gone." Switch back
+(`kubectl config use-context k3d-behold-k3d-demo`) and the next refresh
+recovers cleanly.
+
+## Cleanup
+
+`Ctrl-C` on `npm run demo:k8s` runs `scripts/local/local-down.sh`
+automatically: deletes the `behold-k3d-demo` cluster and restores whatever
+kubectl context was current before `local-up.sh` ran. Safe to run by hand too:
+
+```sh
+bash scripts/local/local-down.sh
+```
+
+## Note for chant#1179
+
+This Op's `delete: "owned-only"` exercises the same typed, marker-scoped
+prune path chant#1179 wants a live k3d E2E for. This demo isn't that test —
+it's a manual walkthrough, not an automated assertion of "exactly the orphan
+and nothing else was deleted" — but it does confirm the path runs against a
+real cluster, not just `fakeCluster`.

package/example-k8s/chant.config.ts

@@ -0,0 +1,21 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// Bound to the demo's own cluster (scripts/local/local-up.sh creates it, k3d
+// names the context "k3d-behold-k3d-demo") rather than whatever kubectl
+// context happens to be ambient — chant#1100. A declared binding is checked
+// against the ambient context on every live read/apply; a mismatch refuses
+// loudly instead of silently reading the wrong cluster. The walkthrough's
+// "unobserved" step (README.md) is exactly that refusal, produced on purpose
+// by switching away from this context for a moment.
+export default {
+  lexicons: ["k8s", "temporal"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "behold-k3d-demo", env: "local" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-k3d-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-k8s/ops/k3d-apply.op.ts

@@ -0,0 +1,18 @@
+import { ApplyOp } from "@intentius/chant-lexicon-temporal";
+
+// code → local k3d (chant#704), no cloud account. scripts/local/local-up.sh
+// (run by `npm run demo:k8s` before behold starts serving) brings the cluster
+// up; behold's Run button on this Op deploys the declared app to it —
+// build → plan (live diff) → server-side apply, field manager
+// "chant:behold-k3d-demo" (chant#1074/#1075). Deletes are owned-only: a
+// marker-scoped prune that never touches anything chant didn't declare — the
+// same path chant#1179 wants a live E2E for; this Op exercises it, but isn't
+// that test.
+const { op } = ApplyOp({
+  name: "k3d-apply",
+  env: "local",
+  target: "kubectl",
+  output: "app.yaml",
+  delete: "owned-only",
+});
+export default op;