moshcode 0.24.0

package/bin/moshscript.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// moshscript — thin alias for `moshcode run`, so `.mosh` files can use:
+//
+//   #!/usr/bin/env moshscript
+//
+// as a shebang and run themselves like shell scripts:
+//
+//   chmod +x deploy.mosh && ./deploy.mosh --dry-run staging
+//
+// All arguments are forwarded unchanged to `moshcode run`.
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const BIN = fileURLToPath(new URL("moshcode.mjs", import.meta.url));
+const args = process.argv.slice(2); // everything after `moshscript`
+
+const child = spawn(process.execPath, [BIN, "run", ...args], {
+  stdio: "inherit",
+  env: { ...process.env, MOSHCODE_NESTED: "1" },
+});
+child.on("error", (e) => { console.error(`moshscript: ${e.message}`); process.exit(1); });
+child.on("exit", (code, signal) => {
+  if (signal) {
+    try { process.kill(process.pid, signal); }
+    catch { process.exitCode = 1; }
+    return;
+  }
+  process.exitCode = code ?? 0;
+});

package/examples/alive.mosh

@@ -0,0 +1,6 @@
+while (alive) {
+  code();
+  mosh();
+  notify();
+  repeat();
+} // no bugs, only features

package/examples/scripting-the-cli.mosh

@@ -0,0 +1,21 @@
+#!/usr/bin/env moshscript
+// scripting-the-cli.mosh — secretly all JS is legal, and every CLI verb is just
+// `moshcode <cmd> ...args`. Try it safely first:
+//
+//   moshcode run examples/scripting-the-cli.mosh --dry-run
+//   chmod +x examples/scripting-the-cli.mosh && ./examples/scripting-the-cli.mosh claude
+//
+// argv[0] is the engine to drop into at the end (default: claude).
+
+const engine = argv[0] || "claude";
+const engines = ["claude", "codex"];
+
+say(`🎸 setting up ${engines.length} engines`);
+for (const e of engines) {
+  install(e);                                  // → moshcode install <e>
+}
+
+mcp("install", "https://mcp.sentry.dev/mcp");  // → moshcode mcp install ...
+notify(`moshcode ready — dropping into ${engine}`);
+
+agents(engine);                                // → moshcode agents <engine>

package/examples/team-secrets.mosh

@@ -0,0 +1,20 @@
+#!/usr/bin/env moshscript
+// team-secrets.mosh — pull a team's shared credentials, then start coding.
+//
+// `secrets(...)` is just `moshcode secrets ...args`, which passes through to the
+// logicsrc CLI — so a script can fetch end-to-end-encrypted team secrets into a
+// local .env instead of anyone passing .env files around. Try it safely first:
+//
+//   moshcode run examples/team-secrets.mosh --dry-run acme prod claude
+//
+// argv: <team> <vault> [engine]   (defaults: acme / prod / claude)
+
+const team = argv[0] || "acme";
+const vault = argv[1] || "prod";
+const engine = argv[2] || "claude";
+
+say(`🔐 pulling ${team}/${vault} secrets into .env (end-to-end encrypted)`);
+secrets("teams", "pull", team, vault, "--env", ".env");  // → moshcode secrets teams pull <team> <vault> --env .env
+
+say(`🎸 secrets in place — dropping into ${engine}`);
+agents(engine);                                          // → moshcode agents <engine>

package/examples/templates/bun-caddy-sqlite/.env.example

@@ -0,0 +1,14 @@
+# The name you registered in the Pit. Caddy matches on it; nothing resolves it
+# locally.
+MOSHPIT_NAME=foo.whatever
+
+# Where Bun listens. Loopback only — Caddy is the sole client.
+HOST=127.0.0.1
+PORT=3000
+
+# Leave both unset to use a local SQLite file at DB_PATH.
+DB_PATH=./data/app.db
+
+# Set both to use Turso instead. A URL without a token is refused at startup.
+# TURSO_DATABASE_URL=libsql://your-db-your-org.turso.io
+# TURSO_AUTH_TOKEN=

package/examples/templates/bun-caddy-sqlite/Caddyfile

@@ -0,0 +1,18 @@
+# Caddy in front of the Bun service, published at a Moshpit name.
+#
+# The `http://` is required and is not a style choice. A Moshpit ending is not
+# in the public DNS root, so no certificate authority will issue for it — leave
+# the scheme off and Caddy will try to provision a certificate, fail, and never
+# bring the site up. Everything served at a Moshpit name is plain HTTP.
+#
+# Nothing here resolves the name. The visitor's resolver did that; by the time a
+# request arrives Caddy has only a Host header to match on, which is why the
+# site address must be the name exactly as it is registered.
+
+http://{$MOSHPIT_NAME:foo.whatever} {
+	reverse_proxy {$APP_ADDR:127.0.0.1:3000}
+
+	log {
+		output file /var/log/caddy/moshpit-service.log
+	}
+}

package/examples/templates/bun-caddy-sqlite/README.md

@@ -0,0 +1,97 @@
+# bun-caddy-sqlite
+
+Bun serving an app, Caddy in front, SQLite underneath — local file in
+development, Turso in production — published at a Moshpit name over IPv6.
+
+## The part that surprises people
+
+Three machines' worth of concerns, and they fail independently:
+
+| | needs the resolver? | what it does |
+|---|---|---|
+| the box serving the name | **no** | Caddy matches a `Host` header, nothing more |
+| the registry | — | holds the address the name points at |
+| every visitor | **yes** | `sudo moshcode dns enable`, or the name resolves to nothing |
+
+Nothing on the server ever resolves its own name. That is why there is no DNS
+software in this template.
+
+## Locally
+
+```sh
+bun install
+cp .env.example .env
+bun dev
+curl -H "Host: foo.whatever" http://127.0.0.1:3000/
+```
+
+That runs against a SQLite file at `./data/app.db`. No Turso account needed
+until you deploy.
+
+## Deploying
+
+1. **Point the name at the box.** In the Pit, set `points at` to its public
+   IPv6 address — bare, no scheme, no brackets, no port:
+
+   ```sh
+   ip -6 addr show scope global | grep inet6
+   ```
+
+   Pick the globally routable one. An `fd..`/`fc..` address is unique-local
+   (Tailscale and friends live there) and the registry refuses it, because a
+   name pointed at one resolves somewhere only you can reach.
+
+2. **Move the database, if it should be hosted.** Set `TURSO_DATABASE_URL` and
+   `TURSO_AUTH_TOKEN` in `/etc/moshpit-service.env`. Leave them unset and the
+   service uses the local file under `/var/lib/moshpit-service`, which the unit
+   provisions. A URL without a token is refused at startup rather than failing
+   at the first query.
+
+3. **Serve it.**
+
+   ```sh
+   export MOSHPIT_NAME=foo.whatever
+   sudo cp Caddyfile /etc/caddy/Caddyfile
+   sudo cp deploy/moshpit-service.service /etc/systemd/system/
+   sudo systemctl enable --now moshpit-service caddy
+   sudo ufw allow 80/tcp
+   ```
+
+4. **Reach it,** on any machine that should see the name:
+
+   ```sh
+   sudo moshcode dns enable
+   sudo cp deploy/moshcode-dns.service /etc/systemd/system/   # survives reboot
+   sudo systemctl enable --now moshcode-dns
+   ```
+
+## Verifying, one layer at a time
+
+A failure at any layer looks identical in a browser, so do not start there.
+
+```sh
+# Server only — no DNS involved. Proves Caddy, the firewall, and the app.
+curl -6 -H "Host: foo.whatever" http://[YOUR:V6:ADDR]/
+
+# Resolver only. Proves the registry and the bridge.
+moshcode dns resolve foo.whatever
+
+# Both.
+curl -6 http://foo.whatever/
+```
+
+If the first works and the last does not, it is DNS. If the first fails, stop
+looking at DNS.
+
+## Known limits
+
+- **No HTTPS, ever.** No CA will issue for an ending outside the DNS root. That
+  rules out secure cookies, service workers, and WebCrypto in the browser. The
+  `http://` in the Caddyfile is what stops Caddy trying and failing.
+- **Only machines running the resolver can reach the name.** Not phones, not a
+  colleague who has not installed it, not webhooks.
+  `pit.moshcode.sh/n/foo.whatever` is the URL for people who installed nothing.
+- **One level deep.** `foo.whatever` works; `www.foo.whatever` does not.
+- **Port 80 only** on the resolver path. A DNS record carries an address and has
+  nowhere to put a port, so a target like `[addr]:8080` only works through the
+  `/n/` gateway.

package/examples/templates/bun-caddy-sqlite/deploy/moshcode-dns.service

@@ -0,0 +1,39 @@
+# The Moshpit resolver, kept running across reboots.
+#
+# `moshcode dns enable` sets up two halves: a systemd-resolved drop-in that
+# routes Moshpit endings at the bridge, and the bridge process itself. The
+# drop-in is a file and survives a reboot on its own. The process does not —
+# so after a restart the routing still points at a port with nothing behind it,
+# and every Moshpit name stops resolving with no obvious cause. This unit is
+# the missing half.
+#
+#   sudo cp deploy/moshcode-dns.service /etc/systemd/system/
+#   sudo systemctl enable --now moshcode-dns
+#
+# Install this on machines that need to REACH Moshpit names. A box that only
+# serves one does not need it — Caddy answers whatever Host header arrives and
+# never resolves its own name.
+
+[Unit]
+Description=Moshpit DNS bridge
+After=network-online.target
+Wants=network-online.target
+Before=systemd-resolved.service
+
+[Service]
+Type=simple
+# Port 5354 is unprivileged, so this does not need root. The trade-off is that
+# the parking responder cannot take port 80 and falls back to the public
+# parking address — which only affects names that point nowhere yet.
+ExecStart=/usr/bin/env moshcode dns start --port 5354
+Restart=always
+RestartSec=2
+
+DynamicUser=yes
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+
+[Install]
+WantedBy=multi-user.target

package/examples/templates/bun-caddy-sqlite/deploy/moshpit-service.service

@@ -0,0 +1,38 @@
+# The Bun service. Nothing Moshpit-specific here — it is a plain unit, and the
+# name it answers to is Caddy's problem, not this process's.
+#
+#   sudo cp deploy/moshpit-service.service /etc/systemd/system/
+#   sudo systemctl enable --now moshpit-service
+
+[Unit]
+Description=Bun service published at a Moshpit name
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/srv/moshpit-service
+ExecStart=/usr/bin/env bun src/server.ts
+EnvironmentFile=-/etc/moshpit-service.env
+Environment=HOST=127.0.0.1
+Environment=PORT=3000
+
+# ProtectSystem=strict makes the whole filesystem read-only, so the local
+# SQLite file needs somewhere it is allowed to live. StateDirectory creates
+# /var/lib/moshpit-service and hands it to the dynamic user. Unset DB_PATH and
+# point TURSO_DATABASE_URL somewhere instead if the database is hosted.
+StateDirectory=moshpit-service
+Environment=DB_PATH=/var/lib/moshpit-service/app.db
+
+Restart=always
+RestartSec=2
+
+# No reason for a web service to be root or to read anyone's home directory.
+DynamicUser=yes
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+
+[Install]
+WantedBy=multi-user.target

package/examples/templates/bun-caddy-sqlite/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "moshpit-service",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/server.ts",
+    "start": "bun src/server.ts"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.15.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/examples/templates/bun-caddy-sqlite/src/db.ts

@@ -0,0 +1,47 @@
+// One client for both shapes of the same database.
+//
+// Local development wants a file with nothing to sign up for; production wants
+// Turso. `@libsql/client` speaks both, so the only difference is the URL — and
+// keeping that difference in an env var rather than in a branch means the code
+// that runs against your laptop is the code that runs in production.
+
+import { createClient, type Client } from "@libsql/client";
+
+const remote = process.env.TURSO_DATABASE_URL?.trim();
+
+// A remote URL without a token fails at the first query with an auth error
+// several layers from the cause. Better to say so while the reason is obvious.
+if (remote && /^libsql:|^https:/i.test(remote) && !process.env.TURSO_AUTH_TOKEN?.trim()) {
+  throw new Error("TURSO_DATABASE_URL is set but TURSO_AUTH_TOKEN is not");
+}
+
+export const db: Client = createClient(
+  remote
+    ? { url: remote, authToken: process.env.TURSO_AUTH_TOKEN }
+    : { url: `file:${process.env.DB_PATH || "./data/app.db"}` },
+);
+
+/** Bring the schema up. Idempotent, so it is safe on every boot. */
+export async function migrate(): Promise<void> {
+  await db.execute(`
+    CREATE TABLE IF NOT EXISTS visits (
+      id     INTEGER PRIMARY KEY AUTOINCREMENT,
+      name   TEXT    NOT NULL,
+      path   TEXT    NOT NULL,
+      seen_at INTEGER NOT NULL
+    )
+  `);
+  await db.execute(`CREATE INDEX IF NOT EXISTS visits_name ON visits (name)`);
+}
+
+export async function recordVisit(name: string, path: string): Promise<number> {
+  await db.execute({
+    sql: `INSERT INTO visits (name, path, seen_at) VALUES (?, ?, ?)`,
+    args: [name, path, Date.now()],
+  });
+  const counted = await db.execute({
+    sql: `SELECT COUNT(*) AS n FROM visits WHERE name = ?`,
+    args: [name],
+  });
+  return Number(counted.rows[0]?.n ?? 0);
+}

package/examples/templates/bun-caddy-sqlite/src/server.ts

@@ -0,0 +1,44 @@
+// The service behind Caddy.
+//
+// Bound to loopback on purpose. Caddy is the only client, and binding this to
+// the public address would publish it on a port nothing virtual-hosts — which
+// hands anyone scanning the box the app with the name stripped off the front.
+
+import { migrate, recordVisit } from "./db";
+
+const PORT = Number(process.env.PORT || 3000);
+const HOSTNAME = process.env.HOST || "127.0.0.1";
+
+await migrate();
+
+const server = Bun.serve({
+  port: PORT,
+  hostname: HOSTNAME,
+
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    // The Moshpit name arrives in a header and nowhere else. Nothing on this
+    // box resolved it — the visitor's resolver did, then connected straight
+    // here. `x-moshpit-name` is set when the request came through the
+    // pit.moshcode.sh gateway; `host` is what a direct visit carries.
+    const name = req.headers.get("x-moshpit-name") || req.headers.get("host") || "(no host header)";
+
+    if (url.pathname === "/health") {
+      return Response.json({ ok: true, name });
+    }
+
+    const visits = await recordVisit(name, url.pathname);
+    return new Response(
+      `${name} is served from this box.\n\npath:   ${url.pathname}\nvisits: ${visits}\n`,
+      { headers: { "content-type": "text/plain; charset=utf-8" } },
+    );
+  },
+
+  error(err) {
+    console.error(err);
+    return new Response("internal error\n", { status: 500 });
+  },
+});
+
+console.log(`listening on ${server.hostname}:${server.port}`);

package/examples/templates/bun-caddy-sqlite/template.json

@@ -0,0 +1,10 @@
+{
+  "name": "bun-caddy-sqlite",
+  "description": "Bun service + Caddy + SQLite (local file or Turso), published at a Moshpit name over IPv6",
+  "vars": {
+    "MOSHPIT_NAME": "the registered name to serve, e.g. foo.whatever",
+    "APP_ADDR": "where Bun listens, loopback only (default 127.0.0.1:3000)",
+    "TURSO_DATABASE_URL": "libsql:// URL for a hosted database; omit to use a local file",
+    "TURSO_AUTH_TOKEN": "token for the Turso database, required when the URL is remote"
+  }
+}

package/examples/templates/caddy-proxy/Caddyfile

@@ -0,0 +1,36 @@
+# Caddy in front of a service already running on this box, published at a
+# Moshpit name.
+#
+# The `http://` is required and is not a style choice. A Moshpit ending is not
+# in the public DNS root, so no certificate authority will issue for it — leave
+# the scheme off and Caddy will try to provision a certificate, fail, and never
+# bring the site up. Everything served at a Moshpit name is plain HTTP.
+#
+# Nothing here resolves the name. The visitor's resolver did that; by the time a
+# request arrives Caddy has only a Host header to match on, which is why the
+# site address must be the name exactly as it is registered.
+
+http://{$MOSHPIT_NAME:foo.whatever} {
+	reverse_proxy {$APP_ADDR:127.0.0.1:8080}
+
+	log {
+		output file /var/log/caddy/moshpit-service.log
+	}
+}
+
+# Every subdomain too. This block answers only once the name publishes a
+# wildcard record — DNS Records tab in the Pit, the `*.` option with an AAAA
+# at this box — because until then `anything.foo.whatever` resolves to nothing
+# and no request reaches Caddy to match. Uncomment both together.
+#
+# The app sees which subdomain was asked for in the Host header, and Caddy
+# matches exactly one label deep: `api.foo.whatever` answers,
+# `a.b.foo.whatever` does not.
+#
+# http://*.{$MOSHPIT_NAME:foo.whatever} {
+# 	reverse_proxy {$APP_ADDR:127.0.0.1:8080}
+#
+# 	log {
+# 		output file /var/log/caddy/moshpit-service.log
+# 	}
+# }

package/examples/templates/caddy-proxy/README.md

@@ -0,0 +1,104 @@
+# caddy-proxy
+
+A name in front of something that is already running. No app, no database, no
+runtime to keep alive — Caddy answers the Moshpit name and hands every request
+to a local service on `127.0.0.1:8080` (or wherever `APP_ADDR` says).
+
+This is the template for "I have a thing on this box, put a name on it": a
+dev server, a dashboard, grafana, a game panel, anything that already listens
+on loopback.
+
+## The part that surprises people
+
+Three machines' worth of concerns, and they fail independently:
+
+| | needs the resolver? | what it does |
+|---|---|---|
+| the box serving the name | **no** | Caddy matches a `Host` header, nothing more |
+| the registry | — | holds the address the name points at |
+| every visitor | **yes** | `sudo moshcode dns enable`, or the name resolves to nothing |
+
+Nothing on the server ever resolves its own name. That is why there is no DNS
+software in this template.
+
+## Deploying
+
+1. **Point the name at the box.** In the Pit, set `points at` to its public
+   IPv6 address — bare, no scheme, no brackets, no port:
+
+   ```sh
+   ip -6 addr show scope global | grep inet6
+   ```
+
+   Pick the globally routable one. An `fd..`/`fc..` address is unique-local
+   (Tailscale and friends live there) and the registry refuses it, because a
+   name pointed at one resolves somewhere only you can reach.
+
+2. **Serve it.** The service stays bound to loopback — Caddy is its only
+   client, and binding it publicly publishes it on a port nothing
+   virtual-hosts.
+
+   ```sh
+   export MOSHPIT_NAME=foo.whatever
+   export APP_ADDR=127.0.0.1:8080   # the default; change only if the service differs
+   sudo cp Caddyfile /etc/caddy/Caddyfile
+   sudo systemctl reload caddy
+   sudo ufw allow 80/tcp
+   ```
+
+3. **Reach it,** on any machine that should see the name:
+
+   ```sh
+   sudo moshcode dns enable
+   sudo cp deploy/moshcode-dns.service /etc/systemd/system/   # survives reboot
+   sudo systemctl enable --now moshcode-dns
+   ```
+
+## Every subdomain at once
+
+One name covers one hostname. To answer `anything.foo.whatever` too — one
+service per subdomain, or a wildcard tenant app — do both halves, in either
+order, because neither works without the other:
+
+1. In the Pit's **DNS Records** tab, publish an **AAAA** record on the
+   `*.foo.whatever` option pointing at the same box. Until that exists the
+   subdomains resolve to nothing and no request ever reaches Caddy.
+2. Uncomment the wildcard block at the bottom of the Caddyfile and reload.
+   Caddy matches exactly one label deep, and the app reads which subdomain was
+   asked for from the `Host` header.
+
+`foo.whatever` itself is not covered by a wildcard — keep the apex block (and
+its own AAAA or `points at`) for that. This is how DNS wildcards work, not a
+choice Caddy made.
+
+## Verifying, one layer at a time
+
+A failure at any layer looks identical in a browser, so do not start there.
+
+```sh
+# Server only — no DNS involved. Proves Caddy, the firewall, and the service.
+curl -6 -H "Host: foo.whatever" http://[YOUR:V6:ADDR]/
+
+# Resolver only. Proves the registry and the bridge.
+moshcode dns resolve foo.whatever
+
+# Both.
+curl -6 http://foo.whatever/
+```
+
+If the first works and the last does not, it is DNS. If the first fails, stop
+looking at DNS.
+
+## Known limits
+
+- **No HTTPS, ever.** No CA will issue for an ending outside the DNS root. That
+  rules out secure cookies, service workers, and WebCrypto in the browser. The
+  `http://` in the Caddyfile is what stops Caddy trying and failing.
+- **Only machines running the resolver can reach the name.** Not phones, not a
+  colleague who has not installed it, not webhooks.
+  `pit.moshcode.sh/n/foo.whatever` is the URL for people who installed nothing.
+- **Subdomains are opt-in.** `foo.whatever` works out of the box;
+  `www.foo.whatever` works only with the wildcard record described above.
+- **Port 80 only** on the resolver path. A DNS record carries an address and
+  has nowhere to put a port, which is why Caddy listens on 80 and the
+  `host:port` part lives here, not in the registry.

package/examples/templates/caddy-proxy/deploy/moshcode-dns.service

@@ -0,0 +1,39 @@
+# The Moshpit resolver, kept running across reboots.
+#
+# `moshcode dns enable` sets up two halves: a systemd-resolved drop-in that
+# routes Moshpit endings at the bridge, and the bridge process itself. The
+# drop-in is a file and survives a reboot on its own. The process does not —
+# so after a restart the routing still points at a port with nothing behind it,
+# and every Moshpit name stops resolving with no obvious cause. This unit is
+# the missing half.
+#
+#   sudo cp deploy/moshcode-dns.service /etc/systemd/system/
+#   sudo systemctl enable --now moshcode-dns
+#
+# Install this on machines that need to REACH Moshpit names. A box that only
+# serves one does not need it — Caddy answers whatever Host header arrives and
+# never resolves its own name.
+
+[Unit]
+Description=Moshpit DNS bridge
+After=network-online.target
+Wants=network-online.target
+Before=systemd-resolved.service
+
+[Service]
+Type=simple
+# Port 5354 is unprivileged, so this does not need root. The trade-off is that
+# the parking responder cannot take port 80 and falls back to the public
+# parking address — which only affects names that point nowhere yet.
+ExecStart=/usr/bin/env moshcode dns start --port 5354
+Restart=always
+RestartSec=2
+
+DynamicUser=yes
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+
+[Install]
+WantedBy=multi-user.target

package/examples/templates/caddy-proxy/template.json

@@ -0,0 +1,8 @@
+{
+  "name": "caddy-proxy",
+  "description": "Caddy proxying a Moshpit name to a service already running on the box — no app, no database, just the name in front",
+  "vars": {
+    "MOSHPIT_NAME": "the registered name to serve, e.g. foo.whatever",
+    "APP_ADDR": "where the local service listens, loopback only (default 127.0.0.1:8080)"
+  }
+}

package/examples/templates/caddy-static/Caddyfile

@@ -0,0 +1,16 @@
+# Caddy serving files at a Moshpit name.
+#
+# The `http://` is required and is not a style choice. A Moshpit ending is not
+# in the public DNS root, so no certificate authority will issue for it — leave
+# the scheme off and Caddy will try to provision a certificate, fail, and never
+# bring the site up. Everything served at a Moshpit name is plain HTTP.
+
+http://{$MOSHPIT_NAME:foo.whatever} {
+	root * {$SITE_ROOT:/srv/moshpit-site}
+	file_server
+	encode gzip
+
+	log {
+		output file /var/log/caddy/moshpit-site.log
+	}
+}