ci: Add PR previews via Codespaces

.devcontainer/Dockerfile

@@ -0,0 +1,28 @@
+# Node major here only needs to be close enough to bootstrap mise; the exact
+# toolchain (node + pnpm) is pinned in /.mise.toml and installed by setup.sh.
+# Pinned to bookworm: the floating `:24` tag now resolves to Debian trixie,
+# which several devcontainer features (notably docker-in-docker's Moby
+# packages) don't yet support.
+FROM mcr.microsoft.com/devcontainers/javascript-node:24-bookworm
+
+# mise manages the Node and pnpm versions pinned in the repo's .mise.toml.
+# `mise install` is run by .devcontainer/setup.sh once the repo is checked out.
+# Install to a global path: this RUN executes as root, so the default
+# ~/.local/bin/mise would land under /root and be invisible to the 'node' user
+# that Codespaces runs lifecycle commands as. A global binary is on PATH for
+# every user; per-user mise data still lives under each user's home.
+RUN curl https://mise.run | MISE_INSTALL_PATH=/usr/local/bin/mise sh && \
+    echo 'eval "$(mise activate bash)"' >> /etc/bash.bashrc
+
+# build-essential for node-gyp; the rest are the shared libraries Chromium
+# needs so puppeteer's bundled Chrome can launch for card prerendering
+# (the prerender service fails with "libatk-1.0.so.0: cannot open shared
+# object file" without them). Postgres, Matrix/Synapse and SMTP run as
+# Docker containers via the docker-in-docker feature, so they need nothing here.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+    libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
+    libgbm1 libpango-1.0-0 libcairo2 libasound2 libatspi2.0-0 \
+    libgtk-3-0 libx11-xcb1 libxcb1 libxss1 fonts-liberation \
+    && rm -rf /var/lib/apt/lists/*

.devcontainer/devcontainer.json

@@ -0,0 +1,56 @@
+{
+  "name": "Boxel PR Review",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "workspaceFolder": "/workspaces/boxel",
+
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "dockerDashComposeVersion": "v2",
+      "installDockerBuildx": false
+    },
+    "ghcr.io/devcontainers/features/python:1": {
+      "version": "3.11"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/sshd:1": {}
+  },
+
+  "forwardPorts": [4201, 4206, 8008],
+  "portsAttributes": {
+    "4201": { "label": "Realm Server", "onAutoForward": "silent" },
+    "4206": { "label": "Icons Server", "onAutoForward": "silent" },
+    "8008": { "label": "Matrix/Synapse", "onAutoForward": "silent" }
+  },
+
+  "postCreateCommand": "bash .devcontainer/setup.sh",
+  "postStartCommand": "nohup setsid bash .devcontainer/start-services.sh > /workspaces/.boxel-start-services.log 2>&1 < /dev/null &",
+
+  "customizations": {
+    "codespaces": {
+      "repositories": {
+        "cardstack/boxel-catalog": { "permissions": { "contents": "read" } },
+        "cardstack/boxel-skills": { "permissions": { "contents": "read" } }
+      }
+    },
+    "vscode": {
+      "extensions": [
+        "cardstack.boxel-tools",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "typed-ember.glint-vscode"
+      ],
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash"
+      }
+    }
+  },
+
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "16gb",
+    "storage": "64gb"
+  }
+}

.devcontainer/setup.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# One-time setup after the container is created.
+# Runs during Codespace build (or prebuild) — keep it idempotent.
+# The host app is NOT built here; it's deployed via GitHub Actions
+# (.github/workflows/codespaces-preview.yml) pointed back at this Codespace.
+set -euo pipefail
+
+cd /workspaces/boxel
+
+# mise installs the exact Node + pnpm versions pinned in .mise.toml. `mise
+# trust` is required because the repo's .mise.toml has not been trusted in a
+# fresh container. Activate mise for this shell so the pinned tools are on PATH.
+echo "==> Installing pinned toolchain via mise..."
+mise trust
+mise install
+eval "$(mise activate bash)"
+
+echo "==> Installing dependencies..."
+mise exec -- pnpm install --frozen-lockfile
+
+# Source-realm content lives in separate repos that are cloned on first setup.
+# The catalog/skills :setup scripts try an SSH clone (git@github.com:) first,
+# which blocks on an interactive host-key prompt in this non-interactive
+# context. A Codespace has an HTTPS token credential helper but no SSH key,
+# so rewrite SSH GitHub URLs to HTTPS — the clones then authenticate with the
+# token (the repos are granted in devcontainer.json customizations.codespaces).
+# These are also re-run idempotently when the realm server starts; doing them
+# here moves the clone cost into setup.
+git config --global url."https://github.com/".insteadOf "git@github.com:"
+
+echo "==> Setting up skills realm..."
+mise exec -- pnpm --dir=packages/skills-realm skills:setup
+
+echo "==> Setting up catalog realm..."
+mise exec -- pnpm --dir=packages/catalog catalog:setup
+mise exec -- pnpm --dir=packages/catalog catalog:update
+
+# No local TLS cert: the realm server serves plain HTTP, and GitHub's port
+# forwarding terminates TLS at its edge (it forwards plain HTTP to the
+# backend). If the realm served HTTPS it would 308-redirect the edge's
+# plain-HTTP request to https://localhost:4201 — bouncing the browser to
+# localhost. The prerender uses the public S3 host (already HTTPS), so
+# nothing here needs a local cert.
+
+# The host app is NOT built here. The realm server requires a reachable host
+# (it fetches distURL at startup) and the prerenderer renders cards against
+# it, but rather than build a second copy in the Codespace, start-services.sh
+# points both at the host the codespaces-preview workflow already builds and
+# deploys to S3 (a production, CloudFront-served bundle that loads far faster
+# than a local dev build).
+
+# Database schema is created on demand: infra:ensure-pg starts the boxel-pg
+# container and creates the databases, and the realm server runs with
+# --migrateDB to apply migrations. Both happen in start-services.sh.
+echo "==> Setup complete. Backend services will start automatically."