Main

.agents/rules/nextjs_turbopack.md

@@ -0,0 +1,68 @@
+# Node builtins and the browser bundle
+
+**Classification:** Rule
+
+## Rationale
+
+A build that fails with
+
+```
+the chunking context (unknown) does not support external modules (request: node:fs)
+```
+
+is telling you that something reachable from a **client** module imports a Node
+builtin. The bundler is not misconfigured; the import graph is wrong.
+
+## What actually happened here
+
+`e2bd6351` added `apps/editor/components/mcp-relay-client.tsx`:
+
+```tsx
+'use client'
+import { createPascalMcpServer } from '@pascal-app/mcp/server'
+```
+
+`'use client'` sends a module to the browser, and with it **every module it
+imports, at any depth**. The chain ran:
+
+```
+mcp-relay-client.tsx  ('use client')
+  └─ @pascal-app/mcp/server
+       └─ registerTools()
+            └─ tools/scene-lifecycle/metadata.ts
+                 └─ import { createHash } from 'node:crypto'
+```
+
+Four commits then tried to fix it through configuration —
+`transpilePackages`, removing plugins from the bundle, bumping Next — and all
+four failed, because none of them touched the chain.
+
+## Directives
+
+1. **No module reachable from a `'use client'` file may import `node:*`,** at
+   any import depth. Trace the chain from the client file to the builtin before
+   changing any config; that is where the fix belongs.
+
+2. **Do not use `'use server'` for this.** It does not mean "keep this on the
+   server". It marks a file as a *Server Actions* module and requires every
+   export in it to be an async function — adding it to a `page.tsx`, which
+   default-exports a component, is a hard build error. `9720d493` tried exactly
+   this and its deploy failed.
+
+3. **The mechanisms that do work:** `import 'server-only'` (fails at build time
+   if the module reaches the client), simply not writing `'use client'` (App
+   Router modules are server modules by default), or `serverExternalPackages` in
+   `next.config.ts` for a package that must stay on Node.
+
+4. **A package needed on both sides needs a browser-safe entry point.** If the
+   browser genuinely has to run something the server package provides, the
+   package exports a second entry built without Node builtins — Web Crypto in
+   place of `node:crypto`, and so on. There is no config that makes a Node
+   builtin resolve in a browser bundle.
+
+## Note on placement
+
+Agent tooling in this repo reads `.agents/skills/`, not `.agents/rules/` —
+`.claude/`, `.cursor/` and `.codex/` symlink only `skills`. Nothing loads this
+file automatically today; it is kept as the written record of a four-day
+outage, and it is correct if someone does read it.

.github/deploy/README.md

@@ -0,0 +1,120 @@
+# digitaltwin
+
+Pascal Editor, compiled and ready to run on Hostinger's Node.js hosting. Built
+from [pascalorg/editor](https://github.com/pascalorg/editor) at commit
+`08e2279`, plus the MySQL scene store from
+[ovurrsl/editor](https://github.com/ovurrsl/editor).
+
+The application sits at the root of this repository — there is one
+`package.json` and one entry point, so the host cannot pick the wrong
+directory. It follows the stock sequence: `npm install` fetches the runtime
+packages, `npm run build` has nothing to compile and exits cleanly, and
+`server.js` starts the app. `PORT` and `HOSTNAME` are read from the
+environment.
+
+## hPanel settings
+
+Everything is the default except the output directory.
+
+| Field | Value |
+|---|---|
+| Repository | `ovurrsl/digitaltwin` |
+| Branch | `main` |
+| Framework preset | Other |
+| Root directory | `./` |
+| Node.js version | 22.x |
+| Package manager | npm |
+| Build command | `npm run build` |
+| Output directory | `./` |
+| Entry file | `server.js` |
+
+## Environment variables
+
+| Name | Value |
+|---|---|
+| `DIGITALTWIN_MYSQL_HOST` | `localhost` |
+| `DIGITALTWIN_MYSQL_USER` | database user |
+| `DIGITALTWIN_MYSQL_PASSWORD` | database password |
+| `DIGITALTWIN_MYSQL_DATABASE` | database name |
+| `DIGITALTWIN_MYSQL_PORT` | `3306` (optional) |
+
+or, as a single value:
+
+| Name | Value |
+|---|---|
+| `DIGITALTWIN_MYSQL_URL` | `mysql://user:password@localhost:3306/database` |
+
+In `DIGITALTWIN_MYSQL_URL`, percent-encode any of `@ : / ? # [ ] %` that appear
+in the password — `@` becomes `%40`, `#` becomes `%23`. The separate fields
+need no encoding, which is why they are listed first.
+
+Optional:
+
+| Name | Value |
+|---|---|
+| `DIGITALTWIN_ADMIN_EMAIL` | the address that gets the admin role on sign-up |
+
+**MySQL is required.** Without a database configured the server refuses to
+start — check the runtime log for the reason. Tables are created on first
+connection. `/api/health` reports the selected backend
+(`"backend":"mysql"`) and whether the database answers (`"db":"ok"`), so one
+curl verifies a deploy. There is **no override**: `DIGITALTWIN_ALLOW_SQLITE`
+used to grant one and was removed, because a variable that quietly moves a
+customer's scenes onto a filesystem the host wipes every release is not worth
+the convenience it bought.
+
+Every variable is also read under its older `PASCAL_` name, so an existing
+deployment keeps working until it is renamed.
+
+## When the panel forgets its variables
+
+Some panels drop their environment variables on redeploy, which takes the
+database down with them. The same settings can come from a file instead. A real
+environment variable always wins, so the panel stays in charge wherever it is
+configured.
+
+Two locations are read, in this order:
+
+| Path | Survives a redeploy? |
+|---|---|
+| `.env` next to `server.js` | only until the next release replaces this tree |
+| `~/.digitaltwin.env` | yes — it sits outside the deployed directory |
+
+Prefer the second. Create it once with the host's file manager:
+
+    DIGITALTWIN_MYSQL_HOST=127.0.0.1
+    DIGITALTWIN_MYSQL_PORT=3306
+    DIGITALTWIN_MYSQL_USER=your_user
+    DIGITALTWIN_MYSQL_PASSWORD=your_password
+    DIGITALTWIN_MYSQL_DATABASE=your_database
+
+`KEY=value` per line; `#` starts a comment; surrounding quotes are stripped.
+Values are never expanded, so a `$` in a password is a literal `$`.
+
+The boot log names the files it read and how many settings each supplied — the
+values are credentials and are never logged. `DIGITALTWIN_ENV_FILE` points at a
+different path when neither default suits.
+
+A `.env` committed here is carried across by the publish workflow, which
+otherwise replaces this tree wholesale. It is still a credential in git
+history — the home-directory file avoids that.
+
+## Layout
+
+    server.js         entry point, generated by the standalone build
+    package.json      runtime dependencies and the build/start scripts
+    .next/            the compiled application
+    public/           static assets: models, textures, icons, sounds
+
+## Regenerating
+
+Build the source with `output: 'standalone'` in `apps/editor/next.config.ts`.
+From the resulting `apps/editor/.next/standalone` tree, lift `apps/editor/.next`,
+`apps/editor/public` and `apps/editor/server.js` to the top level and drop the
+rest — the vendored `node_modules` is replaced by the dependency list in
+`package.json`, and the app's original manifest cannot be reused because it
+names workspace packages that are not published to npm. Two things the
+standalone build leaves out: copy `apps/editor/public` and
+`apps/editor/.next/static` into the tree before lifting, and add `mysql2` to
+the dependency list by hand — the store imports it dynamically, so file
+tracing does not see it.

.github/deploy/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "digitaltwin",
+  "version": "2.15.0",
+  "private": true,
+  "type": "module",
+  "description": "DigitalTwin, compiled and ready to run. Nothing is built at deploy time.",
+  "engines": {
+    "node": ">=20.9"
+  },
+  "scripts": {
+    "build": "node setup-native.mjs",
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "@node-rs/argon2": "2.0.2",
+    "@opentelemetry/api": "1.9.1",
+    "mysql2": "3.23.2",
+    "next": "16.3.0",
+    "nodemailer": "9.0.3",
+    "otpauth": "9.5.1",
+    "qrcode": "1.5.4",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "sharp": "0.34.5",
+    "ulid": "3.0.2"
+  }
+}

.github/deploy/setup-native.mjs

@@ -0,0 +1,22 @@
+// Turbopack requires an externalized native package under a build-specific
+// hashed alias (e.g. "@node-rs/argon2-4d195bca84303183") but emits no package
+// by that name. Recreate the alias as a symlink to the real install. Runs as
+// the bundle's "build" step, i.e. right after npm install on the host.
+import { readdirSync, readFileSync, mkdirSync, symlinkSync, existsSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+const chunks = join('.next', 'server', 'chunks')
+const found = new Set()
+for (const f of readdirSync(chunks)) {
+  if (!f.endsWith('.js')) continue
+  const m = readFileSync(join(chunks, f), 'utf8').matchAll(/@node-rs\/argon2-[a-f0-9]{16}/g)
+  for (const hit of m) found.add(hit[0])
+}
+for (const alias of found) {
+  const target = join('node_modules', alias)
+  if (existsSync(target)) rmSync(target, { recursive: true })
+  mkdirSync(join('node_modules', '@node-rs'), { recursive: true })
+  symlinkSync('argon2', target)
+  console.log(`[setup-native] ${alias} -> @node-rs/argon2`)
+}
+if (found.size === 0) console.log('[setup-native] no hashed native aliases found')

.github/workflows/bump-plugin.yml

@@ -0,0 +1,104 @@
+name: Bump warehouse plugin
+
+# The warehouse plugin is a git dependency pinned to an exact sha, and it
+# compiles into the app — so a plugin release reaches the site only when this
+# repository moves the pin AND the bundle is rebuilt. Doing that by hand is
+# what left a set of freeze fixes sitting unreleased: the plugin's main had
+# moved on for weeks while the pin, and therefore production, had not.
+#
+# Needs no secret. The plugin repository is public, so reading its head and
+# resolving the dependency both work with nothing configured.
+on:
+  workflow_dispatch:
+  # ovurrsl/plugin-warehouse can fire this on a push to main; the schedule is
+  # what keeps the pin current until it does.
+  repository_dispatch:
+    types: [plugin-updated]
+  schedule:
+    - cron: '42 * * * *'
+
+concurrency:
+  group: bump-plugin
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  # To hand off to the deploy — see the last step.
+  actions: write
+
+env:
+  PLUGIN_REPO: https://github.com/ovurrsl/plugin-warehouse.git
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      # A scheduled run starts on the default branch, so the branch to update
+      # is named rather than inherited. Set the INTEGRATION_BRANCH repository
+      # variable to move it; the fallback is the branch it is today.
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ vars.INTEGRATION_BRANCH || 'integration' }}
+
+      - name: Compare the pin with the plugin's head
+        id: compare
+        run: |
+          head=$(git ls-remote "$PLUGIN_REPO" refs/heads/main | cut -f1)
+          pinned=$(grep -o 'plugin-warehouse\.git#[0-9a-f]\{40\}' apps/editor/package.json | cut -d'#' -f2)
+          echo "head=$head"     >> "$GITHUB_OUTPUT"
+          echo "pinned=$pinned" >> "$GITHUB_OUTPUT"
+          if [ -z "$head" ] || [ -z "$pinned" ]; then
+            echo "could not read one of them (head='$head' pinned='$pinned')" >&2
+            exit 1
+          fi
+          if [ "$head" = "$pinned" ]; then
+            echo 'the pin is current'
+            echo 'changed=false' >> "$GITHUB_OUTPUT"
+          else
+            echo "pin $pinned -> $head"
+            echo 'changed=true' >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: oven-sh/setup-bun@v2
+        if: steps.compare.outputs.changed == 'true'
+        with:
+          bun-version: 1.3.0
+
+      # The lockfile records the sha512 of the resolved tarball, so it is
+      # regenerated by a real install rather than edited — the same reason
+      # `relock.yml` exists.
+      - name: Move the pin and relock
+        if: steps.compare.outputs.changed == 'true'
+        run: |
+          sed -i "s|plugin-warehouse\.git#${{ steps.compare.outputs.pinned }}|plugin-warehouse.git#${{ steps.compare.outputs.head }}|" \
+            apps/editor/package.json
+          bun install
+
+      # The gate. A plugin release that does not compile against this editor
+      # must not reach the branch the bundle is built from — which is exactly
+      # the failure a version range would hide and an exact pin makes visible.
+      - name: Type check
+        if: steps.compare.outputs.changed == 'true'
+        run: bun run check-types
+
+      - name: Commit to the integration branch
+        if: steps.compare.outputs.changed == 'true'
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          git add apps/editor/package.json bun.lock
+          git commit -m "$(printf 'chore: pin plugin-warehouse %s\n\nWas %s.' \
+            "$(echo '${{ steps.compare.outputs.head }}' | cut -c1-7)" \
+            "$(echo '${{ steps.compare.outputs.pinned }}' | cut -c1-7)")"
+          git push
+
+      # Handed off explicitly: a push made with GITHUB_TOKEN starts no workflow
+      # runs, so without this the pin moves and the site never rebuilds.
+      - name: Build and publish
+        if: steps.compare.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh workflow run deploy-bundle.yml \
+            --repo "$GITHUB_REPOSITORY" \
+            --ref "${{ vars.INTEGRATION_BRANCH || 'integration' }}"