@bongos/core 1.17.0

package/.devcontainer/post-create.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# post-create.sh — first-run provisioning for the Amazonprimea Dev Box.
+#
+# Runs once, as the `vscode` user, after the container is created and the repo is
+# mounted at /workspace (devcontainer.json: postCreateCommand). This is where
+# ADR 0031 §3's "fold setup-builder.sh into the container's first-run step"
+# actually happens:
+#
+#   1. scripts/setup-builder.sh --no-auth --skip-keys
+#        → verifies the toolchain, runs `npm ci`, seeds .env.local from the
+#          (secret-free) example. The --no-auth flag skips the interactive
+#          GitHub Device Flow, which can't run in a non-interactive postCreate —
+#          the builder authenticates on first attach instead (see the banner).
+#   2. pip install the pinned art-pipeline deps INTO the venv the image created.
+#        → setup-builder.sh doesn't touch Python deps; the container layer owns
+#          that, installing from the repo's manifest so it stays reproducible.
+#   3. A full-stack verification (sharp loads, art libs import) so a green
+#        first-run means the box is genuinely ready, not just "built".
+#
+# No secrets are written here (ADR 0022): .env.local is copied from the example
+# with blank placeholders; the per-builder Gemini key and GDS session arrive at
+# runtime via the mounted ~/.config/otb volume and /builder-setup.
+
+set -uo pipefail
+
+cd /workspace 2>/dev/null || cd "$(git rev-parse --show-toplevel 2>/dev/null || echo .)"
+
+bold=$'\033[1m'; green=$'\033[32m'; yellow=$'\033[33m'; dim=$'\033[2m'; reset=$'\033[0m'
+say()  { echo "${bold}$*${reset}"; }
+
+say "Amazonprimea Dev Box — first-run provisioning"
+echo
+
+# git trusts the mounted workspace even though its owner differs from the
+# container user (avoids "detected dubious ownership" on every git command).
+git config --global --add safe.directory /workspace 2>/dev/null || true
+
+# node_modules is a container-isolated named volume (see devcontainer.json). A
+# fresh volume mounts root-owned, so hand it to the runtime user before the
+# npm ci inside setup-builder.sh tries to populate it.
+if [ -d node_modules ]; then
+  sudo chown vscode:vscode node_modules 2>/dev/null || true
+fi
+
+# --- 1. Bring up the firewall BEFORE installing dependencies ------------------
+# postStartCommand also runs the firewall on every start, but that's AFTER this
+# postCreate step — which would leave `npm ci` + `pip install` below running with
+# unrestricted egress on first create, a window a malicious (post)install script
+# could exfiltrate through. Apply default-deny up front so dependency installs
+# happen behind the allow-list (npm + PyPI + GitHub are allow-listed, so they
+# still work). Non-fatal: if it can't apply (e.g. a laptop without NET_ADMIN),
+# postStart will report it; we don't block provisioning here.
+say "1/4  Securing egress (default-deny firewall, before dependency installs)"
+if sudo /usr/local/bin/otb-init-firewall.sh; then
+  echo "  ${green}ok${reset}  firewall active — installs run behind the allow-list"
+else
+  echo "  ${yellow}!!${reset} firewall did not apply (see above); dependency installs will run with open egress this once"
+fi
+echo
+
+# --- 2. Fold in setup-builder.sh (toolchain + npm ci + .env.local) ------------
+say "2/4  Toolchain + dependencies (scripts/setup-builder.sh --no-auth)"
+if [ -x scripts/setup-builder.sh ]; then
+  if bash scripts/setup-builder.sh --no-auth --skip-keys; then
+    echo "  ${green}ok${reset}  setup-builder.sh completed"
+  else
+    echo "  ${yellow}!!${reset} setup-builder.sh reported a problem — review the output above"
+  fi
+else
+  echo "  ${yellow}!!${reset} scripts/setup-builder.sh not found/executable — running npm ci directly"
+  npm ci --no-audit --no-fund || echo "  ${yellow}!!${reset} npm ci failed"
+fi
+echo
+
+# --- 2. Art pipeline Python deps into the venv --------------------------------
+# Non-fatal: a box without art deps is still fully usable for game/GDS work.
+# Retry a few times — on a macOS Docker Desktop bind mount, VirtioFS can
+# transiently return EDEADLK ("Resource deadlock avoided") reading repo files;
+# a retry (and a fresh container) usually clears it. The DO box (#598) has no
+# bind mount, so this never bites there.
+say "3/4  Art-pipeline Python deps (into ${OTB_VENV:-venv})"
+if [ -f modules/art-pipeline/pipeline/requirements.txt ]; then
+  art_ok=0
+  for attempt in 1 2 3; do
+    if pip install --no-cache-dir -r modules/art-pipeline/pipeline/requirements.txt; then
+      echo "  ${green}ok${reset}  art deps installed"
+      art_ok=1
+      break
+    fi
+    echo "  ${dim}--${reset}  attempt ${attempt} failed; retrying…"
+  done
+  if [ "$art_ok" -eq 0 ]; then
+    echo "  ${yellow}!!${reset} pip install failed after retries — the art pipeline won't run until resolved."
+    echo "     On a macOS laptop this is usually Docker Desktop's VirtioFS (EDEADLK):"
+    echo "     rebuild the container, or switch Docker Desktop → Settings → General →"
+    echo "     file sharing to 'gRPC FUSE'. (The box is otherwise ready.)"
+  fi
+else
+  echo "  ${dim}--${reset}  no modules/art-pipeline/pipeline/requirements.txt; skipping"
+fi
+echo
+
+# --- 3. Full-stack verification -----------------------------------------------
+say "4/4  Verifying the box is ready"
+# sharp: the native image dep — proves npm ci produced a working binary on this
+# arch (x64 or arm64).
+if node -e "require('sharp'); console.log('sharp', require('sharp/package.json').version)" >/dev/null 2>&1; then
+  echo "  ${green}ok${reset}  sharp loads ($(node -e "console.log(require('sharp/package.json').version)" 2>/dev/null))"
+else
+  echo "  ${yellow}!!${reset} sharp failed to load — the game/art build will break"
+fi
+# The five art libs must import in the venv.
+if python3 -c "import PIL, numpy, scipy, sklearn, certifi" >/dev/null 2>&1; then
+  echo "  ${green}ok${reset}  art libs import (Pillow, numpy, scipy, scikit-learn, certifi)"
+else
+  echo "  ${yellow}!!${reset} one or more art libs failed to import"
+fi
+echo
+
+# --- Claude Code default permission mode (task 1251) --------------------------
+# Match the host (infra/box-source-fetch.sh): default this container's interactive
+# Claude Code to bypassPermissions so `claude` never stops for a prompt on the
+# (isolated, often unattended) dev box. USER-level (~/.claude/settings.json — the
+# persisted otb-claude-config volume), NEVER the repo's project .claude/settings.json,
+# so laptops / local clones are unaffected; it merges with the project settings
+# (which set no defaultMode). Idempotent — only sets the one key, preserving the rest.
+say "Defaulting Claude Code to bypassPermissions (box-only ~/.claude/settings.json)"
+if mkdir -p "$HOME/.claude" 2>/dev/null && node -e '
+  const fs = require("fs"), p = process.argv[1];
+  let s = {}; try { s = JSON.parse(fs.readFileSync(p, "utf8")) || {}; } catch (e) {}
+  if (typeof s !== "object" || s === null || Array.isArray(s)) s = {};
+  s.permissions = (s.permissions && typeof s.permissions === "object") ? s.permissions : {};
+  s.permissions.defaultMode = "bypassPermissions";
+  fs.writeFileSync(p, JSON.stringify(s, null, 2) + "\n");
+' "$HOME/.claude/settings.json" 2>/dev/null; then
+  echo "  ${green}ok${reset}  defaultMode=bypassPermissions written"
+else
+  echo "  ${yellow}!!${reset} could not write ~/.claude/settings.json (claude will prompt normally)"
+fi
+echo
+
+say "${green}Box provisioned.${reset}"
+cat <<'BANNER'
+
+  Next, on first connect:
+    1. Authenticate the GDS CLI:   node scripts/gds/setup.js   (or /builder-setup)
+    2. See what you can claim:      /builder-start
+
+  The pixel-art pipeline needs a Google AI Studio key in ~/.config/otb/env
+  (that path is a persisted volume, so it survives box rebuilds). Skip if you
+  are not running the art pipeline.
+
+BANNER

package/.dockerignore

@@ -0,0 +1,36 @@
+# Cloud Bongos self-host image build context (V4.R63, task 1202).
+#
+# Two jobs: (1) keep the image lean, (2) make it VANILLA — the host instance's
+# brand/module packs are excluded, so the image resolves to the neutral Cloud
+# Bongos brand with every feature module off. To brand your instance, mount your
+# own config/branding.json + config/modules.json at runtime (docs/recipes/self-host.md).
+
+# --- make the image vanilla: exclude the host (customer-1) packs ---
+config/branding.json
+config/modules.json
+
+# --- never copy installed deps or VCS into the image ---
+node_modules
+.git
+.gitignore
+
+# --- game + art assets: a GDS-only instance never serves them ---
+public/
+art/
+
+# --- self-contained Electron app (own package.json, not part of the server) ---
+devbox-app/
+
+# --- not needed at runtime ---
+# (docs/ is KEPT: the Archon security route serves docs/adr/* at runtime.
+#  Both web surfaces — modules/status-ui/public/ + modules/hall-ui/public/ (carved
+#  to modules/ in BV1.R84/R85) — are KEPT: the platform server serves them.)
+tests/
+.github/
+.claude/
+limitations/
+blockers/
+*.log
+npm-debug.log*
+.DS_Store
+scratchpad/

package/.env.local.example

@@ -0,0 +1,32 @@
+# .env.local — local environment for an OTB builder checkout.
+#
+# This file is gitignored. Copy it to .env.local (the setup script does this
+# for you) and fill in the values you have. Most builders only need
+# GOOGLE_AI_STUDIO_KEY; the rest are for builders running their own droplet or
+# debugging the GDS auth surface locally.
+#
+# The pixel-art pipeline (art/pipeline/gen_api.py) reads GOOGLE_AI_STUDIO_KEY
+# in this order:
+#   1. process env
+#   2. this file (.env.local)
+#   3. ~/.config/otb/env   <-- recommended; survives `git worktree add`
+#
+# If you only build the GDS / game and never run the art pipeline, you can
+# leave GOOGLE_AI_STUDIO_KEY blank.
+
+# --- Pixel-art pipeline -------------------------------------------------------
+# Google AI Studio key (https://aistudio.google.com/app/apikey). Required to
+# generate tiles via art/pipeline/*.
+GOOGLE_AI_STUDIO_KEY=
+
+# --- GDS CLI ------------------------------------------------------------------
+# Where the /builder-* CLI talks to. Defaults to production when unset; only
+# override if you're running the server locally.
+# GDS_API_BASE=http://localhost:3000
+
+# --- GitHub OAuth (server only) -----------------------------------------------
+# Needed only if you are running the GDS server yourself (server.js) and want
+# Device Flow auth to work. The production droplet has these in
+# /etc/amazonprimea/ — builders do NOT need these for normal day-to-day work.
+# GDS_GITHUB_CLIENT_ID=
+# GDS_GITHUB_CLIENT_SECRET=

package/.gitattributes

@@ -0,0 +1,83 @@
+# Line-ending policy (#670 — cross-platform builder support).
+#
+# Why this file exists: this project is run on macOS, Linux (the droplet), AND
+# Windows (multi-builder, GDS-V3). The repo has 35+ shell scripts plus an
+# extensionless husky hook, all executed by bash. On a Windows checkout with
+# the common `core.autocrlf=true`, git rewrites text files to CRLF on checkout
+# and bash then dies with `bad interpreter: /usr/bin/env bash^M`. These rules
+# pin line endings deterministically so the same clone behaves identically on
+# every OS — independent of each builder's local git config.
+
+# Default: treat as text, auto-detect binary, and normalize to LF in the repo.
+# On checkout git may still emit native endings for plain text, but the
+# explicit rules below override that for anything an interpreter executes.
+* text=auto
+
+# Executed scripts MUST be LF on every platform (CRLF breaks the shebang line).
+*.sh           text eol=lf
+*.bash         text eol=lf
+.husky/pre-commit text eol=lf
+
+# Node / Python sources: keep LF everywhere too. Node tolerates CRLF, but LF
+# keeps diffs clean and avoids surprises when these are sourced or piped.
+*.js           text eol=lf
+*.cjs          text eol=lf
+*.mjs          text eol=lf
+*.py           text eol=lf
+*.json         text eol=lf
+
+# Future Windows-only wrappers (none today) must be CRLF — cmd.exe/PowerShell
+# expect it. Declared up front so a later setup-builder.cmd lands correct.
+*.bat          text eol=crlf
+*.cmd          text eol=crlf
+*.ps1          text eol=crlf
+
+# Binary assets — never normalize (line-ending rewriting would corrupt them).
+*.png          binary
+*.jpg          binary
+*.jpeg         binary
+*.gif          binary
+*.webp         binary
+*.ico          binary
+*.woff         binary
+*.woff2        binary
+*.ttf          binary
+*.otf          binary
+*.pdf          binary
+
+# Generated files (task 1243 — auto-heal merge conflicts). These are regenerated
+# from code by gen-repo-map.js (ADR 0063) / gen-file-map.js (ADR 0066) /
+# gen-session-index.js (ADR 0062 §8), so two parallel branches reliably conflict
+# on them. The `otb-regen` merge driver (scripts/gds/git-merge-regen.js)
+# regenerates them from the merged tree instead of conflicting. It is registered
+# per-clone by scripts/gds/install-git-hooks.js; where it is NOT registered git
+# falls back to a normal conflict (harmless), and ship.js's pre-stage merge
+# self-heals the same set. task 1385 (ADR 0082): the SERVER also self-heals — the
+# publish-reconciler runs a temp-clone merge with this driver registered, so a PR
+# that conflicts only on these files lands without a human (GitHub's own auto-merge
+# can't run a custom driver, hence the server does the merge locally then pushes).
+# NB: the TOP-LEVEL CLAUDE.md is hand-written and deliberately NOT listed here —
+# only the three nested CLAUDE.md docs carry a generated block. docs/file-map.md
+# carries two generated section blocks (.claude/skills/ + .claude/scheduled-tasks/,
+# ADR 0066, gen-file-map.js), so it joins the set; docs/session-log-index.md is
+# whole-file generated (gen-session-index.js), so it joins too.
+# NB (ADR 0110, task 1926): docs/repo-map.md + docs/session-log-index.md are now
+# GITIGNORED (regenerated at deploy/box-fetch, never committed), so they can no longer
+# appear in a merge and these two driver entries never fire. They are KEPT — harmless —
+# as a transition backstop for any in-flight branch that still carries a committed copy;
+# once none remain they can be dropped. The other four entries stay load-bearing.
+docs/repo-map.md           merge=otb-regen
+docs/file-map.md           merge=otb-regen
+docs/session-log-index.md  merge=otb-regen
+src/bongos/CLAUDE.md          merge=otb-regen
+src/bongos/routes/CLAUDE.md   merge=otb-regen
+scripts/gds/CLAUDE.md      merge=otb-regen
+
+# Append-only index tables (task 1385 / ADR 0082). docs/adr/README.md is a
+# hand-maintained ADR index whose ONLY recurring conflict is two branches each
+# appending a new row — there is no generator to regen it from, so `otb-regen`
+# can't help. The built-in `union` driver keeps BOTH sides' lines, which is the
+# correct resolution for an append list (the exact stall behind PR #300 / #167).
+# `union` is a core git driver (no per-clone registration needed) and is honored
+# by every local merge — the server resolver, /merge-mode, and ship's pre-stage.
+docs/adr/README.md         merge=union

package/.gitignore

@@ -0,0 +1,91 @@
+# Dependencies
+node_modules/
+
+# Per-session git worktrees live under here; each is itself a git checkout
+# and must NEVER be committed (would create embedded-repo references).
+.claude/worktrees/
+
+# Environment / secrets
+.env
+.env.local
+.env.*.local
+
+# Google Chat OAuth credentials — must NEVER be committed.
+# Live on the droplet at /etc/amazonprimea/ instead.
+google-chat-credentials.json
+google-chat-refresh-token.json
+*.credentials.json
+
+# Build output
+dist/
+build/
+
+# Logs
+*.log
+npm-debug.log*
+
+# OS files
+.DS_Store
+
+# Pixel art generation artifacts (iterations are huge; keep references + finals only)
+modules/art-pipeline/iterations/*
+# ...but keep the anti-grid FFT baselines tracked (idea 27): they're tiny + the smoke suite
+# (tests/anti_grid.mjs) compares against them. `modules/art-pipeline/iterations/*` (not the bare
+# dir) lets this negation re-include the file — git can't re-include under a fully-excluded dir.
+!modules/art-pipeline/iterations/anti_grid_baselines.json
+modules/art-pipeline/generated/raw/
+modules/art-pipeline/generated/*/raw/
+# Derived from references/ via slice_references.py — easy to regenerate, no need in git
+modules/art-pipeline/template/ref_tiles/
+modules/art-pipeline/template/ref_clusters/
+# Autotile cross-verify snapshot — regenerated on every smoke_test run.
+modules/art-pipeline/pipeline/_autotile_tables.json
+__pycache__/
+*.pyc
+
+
+# World snapshots — generated on the droplet by scripts/snapshots/render-world.mjs.
+# Untracked so git reset --hard on deploy doesn't wipe them.
+public-status/snapshots/*.png
+public-status/snapshots/manifest.json
+
+# Repo Atlas data — generated on the droplet by scripts/gds/gen-atlas.js on every
+# deploy (ADR 0094). Untracked so git reset --hard doesn't wipe it; the deploy
+# step rewrites it fresh each time, so a committed copy would only go stale.
+# (The hall surface carved to modules/hall-ui/public/ in BV1.R85.)
+modules/hall-ui/public/atlas.json
+
+# Whole-file generated navigation docs — untracked since ADR 0110 (task 1926), the
+# same reasoning as the atlas above. docs/repo-map.md (symbol skeleton, ADR 0063) and
+# docs/session-log-index.md (session index, ADR 0062 §8) are 100%-generated and were
+# regenerated + committed on EVERY ship, so two parallel builder branches collided on
+# them constantly. Untracked + regenerated at deploy (scripts/deploy/deploy-prod.sh) and
+# at box-source-fetch, they can never appear in a branch diff → the conflict class is
+# gone at the source. Their generators are dual-duty: the nested CLAUDE.md symbol blocks
+# and the CLAUDE.md §13 snippet stay TRACKED and CI-gated (gen-*.js --check-block).
+docs/repo-map.md
+docs/session-log-index.md
+
+# Onboarding diagram RENDERS — untracked since ADR 0110 pt.3 / ADR 0122 (task 2027),
+# the deferred diagram half of ADR 0110. The .svg/.png are regenerated + committed on
+# every render-capable ship, so parallel builder branches collided on them (same class
+# as the nav docs above). Untracked + re-rendered at deploy (scripts/deploy/deploy-prod.sh
+# runs scripts/render-diagrams.sh against the tracked .mmd, using the host's installed
+# Chrome — never puppeteer's own droplet-stalling download) and best-effort at
+# box-source-fetch. The .mmd SOURCES + assertions.json stay TRACKED (git reset --hard
+# restores them; the render regenerates the images from them), so the nightly
+# diagram-drift cron (reads assertions.json) is unaffected.
+docs/onboarding/diagrams/*.svg
+docs/onboarding/diagrams/*.png
+
+# Re-hosted #bugs screenshots (task #936). Downloaded from Discord and served
+# by routes/bug-attachments.js. Outside git so a deploy never wipes them.
+var/bug-attachments/
+
+# Custom merge-driver scratch files. The regen merge driver
+# (scripts/gds/git-merge-regen.js, installed by scripts/gds/install-git-hooks.js)
+# writes `.merge_file_*` temp files while resolving conflicts. They are pure
+# scratch — never source — but a `git add -A` once staged one onto main
+# (.merge_file_IKo9KW, merge 3e9f1f81). Ignore the pattern so it can't recur.
+.merge_file_*
+scratchpad/