V0.3.0

.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(kubectl *)"
+    ]
+  }
+}

.devcontainer/check.mjs

@@ -0,0 +1,21 @@
+// Checks that the dev container's Playwright Chromium matches the Playwright in
+// package-lock.json. Dependabot bumps the lockfile but not devcontainer.json, and
+// a mismatch means every new container downloads Chromium again. Run by CI.
+import { readFileSync } from 'node:fs';
+
+const read = (path) => readFileSync(new URL(path, import.meta.url), 'utf8');
+
+const locked = JSON.parse(read('../package-lock.json')).packages['node_modules/playwright']?.version;
+const pinned = read('./devcontainer.json')
+  .match(/"\.\/features\/playwright-chromium":\s*\{\s*"version":\s*"([^"]+)"/)?.[1];
+
+if (!locked || !pinned) {
+  console.error(`Couldn't find Playwright's version (package-lock.json: ${locked}, devcontainer.json: ${pinned}).`);
+  process.exit(1);
+}
+if (locked !== pinned) {
+  console.error(`package-lock.json has Playwright ${locked}, but .devcontainer/devcontainer.json installs ${pinned}.`);
+  console.error(`Set "./features/playwright-chromium": { "version": "${locked}" } in devcontainer.json.`);
+  process.exit(1);
+}
+console.log(`Playwright ${locked}: devcontainer.json matches package-lock.json.`);

.devcontainer/devcontainer.json

@@ -1,24 +1,80 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the
-// README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
+// Format: https://containers.dev/implementors/json_reference/
 {
-	"name": "Node.js & TypeScript",
-	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-	"image": "mcr.microsoft.com/devcontainers/typescript-node:5-24-trixie",
+	"name": "Blockout",
+	"image": "mcr.microsoft.com/devcontainers/typescript-node:5-26-trixie",
+	"hostRequirements": { "cpus": 1, "memory": "4gb", "storage": "10gb" },
 
-	// Features to add to the dev container. More info: https://containers.dev/features.
-	// "features": {},
+	// Features: https://containers.dev/features. Local ones live in ./features:
+	// cloudflared for tunnels, Chromium for the Playwright browser tests,
+	// python3-venv for the docs site, Agent Skills for Claude Code (user-level, in
+	// ~/.claude/skills), and the coder CLI from the Coder deployment (always that
+	// server's version). The other versions are pinned so a rebuild gets the same
+	// tools; .devcontainer/check.mjs keeps Playwright in step with package-lock.json.
+	"features": {
+		"ghcr.io/devcontainers/features/github-cli:1": {},
+		// kubectl and helm, for the services the workspace's cluster runs (like Keycloak)
+		"ghcr.io/devcontainers/features/kubectl-helm-minikube:1": { "minikube": "none" },
+		"./features/cloudflared": { "version": "2026.10.0" },
+		"./features/playwright-chromium": { "version": "1.63.0" },
+		"./features/python-venv": {},
+		"./features/agent-skills": {
+			"source": "DeepSpaceCartel/skills",
+			"ref": "5642bd7c6c82a1fdc5f36ddadadf02723951f296"
+		},
+		"./features/coder-cli": { "url": "https://coder.deepspacecartel.com" },
+		// op, for reading deploy secrets from 1Password (deploy/blockout/.env.1password)
+		"./features/1password-cli": { "version": "latest" },
+		// On every start: Blockout's clients in the shared Keycloak (keycloak-clients.json),
+		// with this workspace's URLs for the ports labelled [sign-in] below
+		"./features/keycloak-clients": {}
+	},
 
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// The classroom server (npm run classroom)
-	"forwardPorts": [8080],
+	// The workspace has 4 GiB, shared by the editor, its servers and everything
+	// run here. Each Node process gets at most 1.5 GiB of heap, so a runaway build
+	// or dev server fails on its own instead of taking the whole container (every
+	// terminal and session) down with it. Processes that set their own limit (VS
+	// Code's servers) keep theirs; native memory (bundler workers) isn't covered.
+	// Clocks and logs in Los Angeles time (CI stays on UTC).
+	"containerEnv": {
+		"NODE_OPTIONS": "--max-old-space-size=1536",
+		"TZ": "America/Los_Angeles",
+		// The shared Keycloak, for BLOCKOUT_AUTH=keycloak npm start (docs/guides/set-up-keycloak.md)
+		"KEYCLOAK_ISSUER": "https://id.deepspacecartel.com/realms/dev",
+		"KEYCLOAK_CLIENT_ID": "blockout"
+	},
 
-	// Use 'postCreateCommand' to run commands after the container is created.
-	// Playwright + Chromium for the browser tests, and cloudflared for tunnels
-	"postCreateCommand": "bash .devcontainer/postCreateCommand.sh"
+	// The Blockout server (npm start), the Vite dev server (npm run dev), the
+	// docs site (mkdocs serve) and Metro for the phone app (npm run tunnel
+	// --workspace @blockout/mobile). [sign-in]: the port's Coder URL may sign in
+	// through Keycloak (the keycloak-clients Feature adds it to the client)
+	"forwardPorts": [8080, 5173, 8000, 8081],
+	"portsAttributes": {
+		"8080": { "label": "Blockout server [sign-in]" },
+		"5173": { "label": "Vite [sign-in]" },
+		"8000": { "label": "Docs (mkdocs serve)" },
+		"8081": { "label": "Metro (phone app)" },
+		// Throwaway servers that Playwright test scripts start
+		"8134-8199": { "onAutoForward": "ignore" }
+	},
 
-	// Configure tool-specific properties.
-	// "customizations": {},
+	// npm packages and the docs venv, which need the workspace (features can't see it)
+	"postCreateCommand": "bash .devcontainer/postCreateCommand.sh",
 
-	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-	// "remoteUser": "root"
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"anthropic.claude-code",
+				"dbaeumer.vscode-eslint",
+				"redhat.vscode-yaml"
+			],
+			"settings": {
+				// mkdocs.yml uses Material's !!python/name tags
+				"yaml.customTags": [
+					"!!python/name:material.extensions.emoji.twemoji",
+					"!!python/name:material.extensions.emoji.to_svg",
+					"!!python/name:pymdownx.superfences.fence_code_format"
+				]
+			}
+		}
+	}
 }

.devcontainer/features/1password-cli/devcontainer-feature.json

@@ -0,0 +1,13 @@
+{
+	"id": "1password-cli",
+	"version": "1.0.0",
+	"name": "1Password CLI",
+	"description": "The 1Password CLI (op) from 1Password's signed apt repository, for reading deploy secrets (like the Google OAuth client secret) instead of typing them.",
+	"options": {
+		"version": {
+			"type": "string",
+			"default": "2.40.0",
+			"description": "An op version in 1Password's apt repository (like 2.40.0), or latest."
+		}
+	}
+}

.devcontainer/features/1password-cli/install.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Installs the 1Password CLI (op) from 1Password's apt repository, following
+# https://developer.1password.com/docs/cli/get-started/. apt checks the packages'
+# signatures with 1Password's key, and the key itself is checked against the
+# fingerprint 1Password publishes before anything trusts it.
+set -euo pipefail
+
+VERSION="${VERSION:-2.40.0}"
+FINGERPRINT=3FEF9748469ADBE15DA7CA80AC2D62742012EA22
+KEY_ID=AC2D62742012EA22
+arch="$(dpkg --print-architecture)" # amd64 or arm64
+
+export DEBIAN_FRONTEND=noninteractive
+missing=()
+for tool in curl gpg; do command -v "$tool" >/dev/null 2>&1 || missing+=("$tool"); done
+if [ "${#missing[@]}" -gt 0 ]; then
+  apt-get update -qq
+  apt-get install -y -qq --no-install-recommends curl ca-certificates gnupg
+fi
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+export GNUPGHOME="$tmp/gnupg" # no keyring left behind in root's home
+mkdir -m 700 "$GNUPGHOME"
+curl -fsSL https://downloads.1password.com/linux/keys/1password.asc -o "$tmp/1password.asc"
+got="$(gpg --batch --quiet --show-keys --with-colons "$tmp/1password.asc" | awk -F: '/^fpr:/ { print $10; exit }')"
+if [ "$got" != "$FINGERPRINT" ]; then
+  echo "1password-cli: the signing key's fingerprint is $got, expected $FINGERPRINT." >&2
+  exit 1
+fi
+
+gpg --batch --quiet --dearmor < "$tmp/1password.asc" > /usr/share/keyrings/1password-archive-keyring.gpg
+echo "deb [arch=${arch} signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/${arch} stable main" \
+  > /etc/apt/sources.list.d/1password.list
+# debsig policy: the package files are signed too, not only the repository
+mkdir -p "/etc/debsig/policies/${KEY_ID}" "/usr/share/debsig/keyrings/${KEY_ID}"
+curl -fsSL https://downloads.1password.com/linux/debian/debsig/1password.pol -o "/etc/debsig/policies/${KEY_ID}/1password.pol"
+cp /usr/share/keyrings/1password-archive-keyring.gpg "/usr/share/debsig/keyrings/${KEY_ID}/debsig.gpg"
+
+apt-get update -qq
+if [ "$VERSION" = latest ]; then
+  apt-get install -y -qq --no-install-recommends 1password-cli
+else
+  apt-get install -y -qq --no-install-recommends "1password-cli=${VERSION}-*"
+fi
+rm -rf /var/lib/apt/lists/*
+op --version

.devcontainer/features/agent-skills/devcontainer-feature.json

@@ -0,0 +1,33 @@
+{
+	"id": "agent-skills",
+	"version": "1.1.0",
+	"name": "Agent Skills",
+	"description": "Agent Skills from a GitHub repo, installed user-level (~/.claude/skills) for the container user with the skills CLI.",
+	"options": {
+		"source": {
+			"type": "string",
+			"default": "DeepSpaceCartel/skills",
+			"description": "The skills repo on GitHub (owner/repo)."
+		},
+		"ref": {
+			"type": "string",
+			"default": "",
+			"description": "A commit, branch or tag to install from. Empty means the default branch; a commit SHA makes builds reproducible."
+		},
+		"skills": {
+			"type": "string",
+			"default": "*",
+			"description": "Space-separated skill names to install, or * for all of them."
+		},
+		"agent": {
+			"type": "string",
+			"default": "claude-code",
+			"description": "The agent to install for (the skills CLI's --agent)."
+		},
+		"cliVersion": {
+			"type": "string",
+			"default": "1.7.1",
+			"description": "The skills CLI (npm package skills) version to run."
+		}
+	}
+}

.devcontainer/features/agent-skills/install.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Installs Agent Skills user-level for the container user. Features run before the
+# workspace is mounted, so they can't go in the project's .claude/skills.
+# Needs Node (npx) and git, which the base image has.
+set -euo pipefail
+
+SOURCE="${SOURCE:-DeepSpaceCartel/skills}"
+REF="${REF:-}"
+SKILLS="${SKILLS:-*}"
+AGENT="${AGENT:-claude-code}"
+CLIVERSION="${CLIVERSION:-1.7.1}"
+user="${_REMOTE_USER:-root}"
+
+if ! command -v npx >/dev/null 2>&1; then
+  echo "agent-skills: needs Node (npx) in the base image." >&2
+  exit 1
+fi
+
+# The skills CLI takes a ref as a GitHub tree URL
+from="$SOURCE"
+[ -n "$REF" ] && from="https://github.com/${SOURCE}/tree/${REF}"
+
+# As the container user, so the files land in (and belong to) their home
+cmd="npx --yes 'skills@${CLIVERSION}' add '${from}' --global --copy --yes --agent '${AGENT}'"
+set -f
+for s in $SKILLS; do cmd+=" --skill '${s}'"; done
+set +f
+
+su "$user" -s /bin/bash -c "
+  set -euo pipefail
+  export DO_NOT_TRACK=1 DISABLE_TELEMETRY=1 npm_config_update_notifier=false
+  export npm_config_cache=\"\$(mktemp -d)\"
+  $cmd
+  rm -rf \"\$npm_config_cache\"
+"

.devcontainer/features/cloudflared/devcontainer-feature.json

@@ -0,0 +1,13 @@
+{
+	"id": "cloudflared",
+	"version": "1.1.0",
+	"name": "cloudflared",
+	"description": "Cloudflare's tunnel client, for sharing the classroom server through a quick tunnel.",
+	"options": {
+		"version": {
+			"type": "string",
+			"default": "2026.10.0",
+			"description": "A cloudflared release tag (like 2026.10.0), or latest."
+		}
+	}
+}

.devcontainer/features/cloudflared/install.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Installs cloudflared from Cloudflare's GitHub release .deb.
+set -euo pipefail
+
+VERSION="${VERSION:-2026.10.0}"
+arch="$(dpkg --print-architecture)" # amd64 or arm64
+
+if [ "$VERSION" = latest ]; then
+  url="https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${arch}.deb"
+else
+  url="https://github.com/cloudflare/cloudflared/releases/download/${VERSION}/cloudflared-linux-${arch}.deb"
+fi
+
+if ! command -v curl >/dev/null 2>&1; then
+  apt-get update -qq
+  DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends curl ca-certificates
+fi
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+curl -fsSL -o "$tmp/cloudflared.deb" "$url"
+dpkg -i "$tmp/cloudflared.deb"
+cloudflared --version | head -n 1

.devcontainer/features/coder-cli/devcontainer-feature.json

@@ -0,0 +1,13 @@
+{
+	"id": "coder-cli",
+	"version": "1.0.0",
+	"name": "Coder CLI",
+	"description": "The coder CLI, downloaded from a Coder deployment so it matches that server's version.",
+	"options": {
+		"url": {
+			"type": "string",
+			"default": "https://coder.deepspacecartel.com",
+			"description": "The Coder deployment to download the CLI from (what CODER_AGENT_URL points at in a workspace)."
+		}
+	}
+}

.devcontainer/features/coder-cli/install.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Installs the coder CLI from a Coder deployment's /bin endpoint, so the CLI is the
+# same version as the server. CODER_AGENT_URL only exists at runtime, hence the option.
+set -euo pipefail
+
+URL="${URL:-https://coder.deepspacecartel.com}"
+URL="${URL%/}"
+arch="$(dpkg --print-architecture)" # amd64 or arm64
+
+if ! command -v curl >/dev/null 2>&1; then
+  apt-get update -qq
+  DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends curl ca-certificates
+  rm -rf /var/lib/apt/lists/*
+fi
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+curl -fsSL -o "$tmp/coder" "${URL}/bin/coder-linux-${arch}"
+install -m 0755 "$tmp/coder" /usr/local/bin/coder
+coder version

.devcontainer/features/keycloak-clients/devcontainer-feature.json

@@ -0,0 +1,30 @@
+{
+	"id": "keycloak-clients",
+	"version": "1.0.0",
+	"name": "Keycloak clients for Coder workspaces",
+	"description": "On every start, creates or updates the project's Keycloak clients (from a JSON file in the repository) and adds this Coder workspace's URLs to them, so apps on Coder's port URLs can sign in. Needs python3 and kubectl, and the platform's registrar Secret (keycloak/workspace-registrar).",
+	"options": {
+		"file": {
+			"type": "string",
+			"default": ".devcontainer/keycloak-clients.json",
+			"description": "The project's clients, relative to the repository root."
+		},
+		"marker": {
+			"type": "string",
+			"default": "sign-in",
+			"description": "A forwarded port's URL is added when its portsAttributes label ends in [<marker>]."
+		},
+		"domain": {
+			"type": "string",
+			"default": "",
+			"description": "Coder's wildcard domain (the part after <port>--<agent>--<workspace>--<owner>.). Empty: the host of CODER_AGENT_URL."
+		},
+		"secret": {
+			"type": "string",
+			"default": "keycloak/workspace-registrar",
+			"description": "The registrar's Secret, as <namespace>/<name>."
+		}
+	},
+	"postStartCommand": "keycloak-clients sync",
+	"installsAfter": ["ghcr.io/devcontainers/features/kubectl-helm-minikube"]
+}

.devcontainer/features/keycloak-clients/install.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Installs keycloak-clients (a Python 3 script, standard library only) and
+# writes the Feature's options as its defaults: options only reach this script,
+# at build time, so the command reads them back from a file on every start.
+# kubectl comes from another Feature (kubectl-helm-minikube).
+set -euo pipefail
+
+here="$(cd "$(dirname "$0")" && pwd)"
+
+if ! command -v python3 >/dev/null 2>&1; then
+  if command -v apt-get >/dev/null 2>&1; then
+    apt-get update && apt-get install -y --no-install-recommends python3 && rm -rf /var/lib/apt/lists/*
+  else
+    echo "keycloak-clients: needs python3 in the base image." >&2
+    exit 1
+  fi
+fi
+command -v kubectl >/dev/null 2>&1 || echo "keycloak-clients: no kubectl yet (add the kubectl-helm-minikube Feature)." >&2
+
+install -m 0755 "$here/keycloak-clients" /usr/local/bin/keycloak-clients
+
+# (as JSON, so values are never run by a shell)
+python3 - "${FILE:-}" "${MARKER:-}" "${DOMAIN:-}" "${SECRET:-}" > /usr/local/etc/keycloak-clients.json <<'EOF'
+import json, sys
+keys = ['KEYCLOAK_CLIENTS_FILE', 'KEYCLOAK_CLIENTS_MARKER', 'KEYCLOAK_CLIENTS_DOMAIN', 'KEYCLOAK_CLIENTS_SECRET']
+print(json.dumps(dict(zip(keys, sys.argv[1:])), indent=2))
+EOF