diff --git a/.claude/skills/github-pages/SKILL.md b/.claude/skills/github-pages/SKILL.md index c0ed652..52010f0 100644 --- a/.claude/skills/github-pages/SKILL.md +++ b/.claude/skills/github-pages/SKILL.md @@ -35,6 +35,9 @@ one, redesign the feature. run on a developer's own machine against a checkout; nothing they serve is deployed, and the game never depends on them. Their code stays out of `_site/` (`src/agent/` is development-only, see `docs/adr/0004-dev-only-code.md`). +- **The container image is a tool too.** `docker/` packages those tools; `docker.yml` publishes it to GHCR for releases + (version tags only, no `latest`) and never to Pages. Someone may run its development server where they like; that is + not a host of the game, and the game never depends on it. ## How it deploys diff --git a/.dockerignore b/.dockerignore index dbdaf41..fbf5463 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,4 +1,10 @@ -.git -.github -node_modules -_site +# The image takes only what docker/Dockerfile copies; everything else (git history, tests, docs, local saves, +# node_modules, _site) stays out of the build context. +* +!package.json +!package-lock.json +!src/ +!site/ +!scripts/ +!tests/harness.js +!docker/docker-entrypoint.sh diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..48e0a5e --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,39 @@ +# Keeps what the workflows and the container image pin up to date: every GitHub Action is pinned to a commit SHA +# (Dependabot moves the SHA and its version comment together), the image's Node base to a digest, and the npm tools +# to the lockfile. Updates come as pull requests, one group per ecosystem, once a week. +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + day: monday + groups: + actions: + patterns: ["*"] + commit-message: + prefix: "CI" + + - package-ecosystem: docker + directory: /docker + schedule: + interval: weekly + day: monday + # The image runs the Node major CI tests on (ci.yml); a new major comes with CI, by hand. + ignore: + - dependency-name: node + update-types: ["version-update:semver-major"] + commit-message: + prefix: "Container" + + - package-ecosystem: npm + directory: / + schedule: + interval: weekly + day: monday + groups: + tools: + patterns: ["*"] + update-types: [minor, patch] + commit-message: + prefix: "Tools" diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml index aa3bdfc..4d41153 100644 --- a/.github/workflows/auto-release.yml +++ b/.github/workflows/auto-release.yml @@ -25,10 +25,10 @@ jobs: env: GH_TOKEN: ${{ github.token }} steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 - - uses: actions/setup-node@v7 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 24 cache: npm diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8bb0ed7..e135ebb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,8 +26,8 @@ jobs: matrix: part: [1, 2, 3, 4] steps: - - uses: actions/checkout@v7 - - uses: actions/setup-node@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 24 cache: npm @@ -38,8 +38,8 @@ jobs: name: build runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 - - uses: actions/setup-node@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 24 cache: npm @@ -61,8 +61,8 @@ jobs: translations: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 - - uses: actions/setup-node@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 24 cache: npm diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 8ff912c..12fba69 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -27,9 +27,9 @@ jobs: id-token: write actions: read steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 1 - - uses: anthropics/claude-code-action@v1 + - uses: anthropics/claude-code-action@c0949c50a78c1ec8ce2647db36629b870e715d0c # v1.0.268 with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index d62dc9a..2deeef2 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -1,72 +1,164 @@ -name: Build and push Docker image +name: Container image -# Every push to main publishes :latest and :. A release publishes : -# built from its tag: auto-release.yml dispatches this workflow alongside the Pages -# deploy, because releases created with the workflow token do not fire the -# "released" event. Hand-published releases fire it directly. +# Publishes ghcr.io//: for releases, and nothing else: auto-release.yml dispatches this workflow +# with the new tag (pre-releases too). There is no :latest and no image per commit. Pushes and pull requests that change +# what goes into the image only build it and try both modes; they never publish. The image packages the MCP server and +# the development server; the game itself is hosted on GitHub Pages only (docs/adr/0001-github-pages-only.md). on: - push: - branches: [main] - release: - types: [released, prereleased] workflow_dispatch: inputs: tag: - description: Existing release tag to build (e.g. v2.10.0); empty builds main - required: false + description: Release tag to build and publish (e.g. v2.10.1) + required: true + push: + branches: [main] + paths: + - docker/** + - .dockerignore + - package.json + - package-lock.json + - scripts/** + - tests/harness.js + - .github/workflows/docker.yml + pull_request: + paths: + - docker/** + - .dockerignore + - package.json + - package-lock.json + - scripts/** + - tests/harness.js + - .github/workflows/docker.yml permissions: contents: read - packages: write + +concurrency: + group: docker-${{ github.event_name }}-${{ inputs.tag || github.ref }} + cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }} jobs: - build: + test: runs-on: ubuntu-latest + timeout-minutes: 20 steps: - - name: Checkout - uses: actions/checkout@v4 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - ref: ${{ github.event.release.tag_name || inputs.tag }} + ref: ${{ inputs.tag || '' }} + persist-credentials: false - - name: Work out the image tags - id: tags - env: - TAG: ${{ github.event.release.tag_name || inputs.tag }} + - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 + + - name: Build for this runner + uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 + with: + context: . + file: docker/Dockerfile + platforms: linux/amd64 + load: true + push: false + tags: sot:test + cache-from: type=gha + cache-to: type=gha,mode=max + + - name: Try both modes run: | set -euo pipefail - # The image is named after this repository (ghcr.io//, lowercased). - image=ghcr.io/${GITHUB_REPOSITORY,,} - if [ -n "$TAG" ]; then - want="v$(jq -r .version package.json)" - if [ "$TAG" != "$want" ]; then - echo "::error::Release tag $TAG does not match package.json version ($want)" - exit 1 - fi - echo "tags=$image:${TAG#v}" >> "$GITHUB_OUTPUT" - else - echo "tags=$image:latest,$image:$GITHUB_SHA" >> "$GITHUB_OUTPUT" - fi + init='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"ci","version":"1"}}}' + mcp() { curl -sS -o /tmp/out -w '%{http_code}' -X POST http://127.0.0.1:7777/mcp \ + -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' "$@" -d "$init"; } + until_up() { for i in $(seq 1 60); do curl -s -o /dev/null "$1" && return 0; sleep 1; done; docker logs "$2"; exit 1; } - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 + # Headless, with a token: refused without it, answered with it. + docker run -d --name h -p 127.0.0.1:7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=ci-token sot:test + until_up http://127.0.0.1:7777/ h + test "$(mcp)" = 401 + test "$(mcp -H 'authorization: Bearer ci-token')" = 200 + grep -q serverInfo /tmp/out + docker rm -f h - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 + # No token given: the container makes one, says so, and wants it. + docker run -d --name t -p 127.0.0.1:7777:7777 -e MCP_MODE=headless sot:test + until_up http://127.0.0.1:7777/ t + test "$(mcp)" = 401 + tok=$(docker logs t 2>&1 | sed -n "s/.*this run's token is //p" | head -1) + test -n "$tok" + test "$(mcp -H "authorization: Bearer $tok")" = 200 + docker rm -f t - - name: Log in to GitHub Container Registry - uses: docker/login-action@v3 + # Browser mode: the development page and the MCP server. + docker run -d --name b -p 127.0.0.1:8080:8080 -p 127.0.0.1:7777:7777 -e SOT_MCP_TOKEN=ci-token sot:test + until_up http://127.0.0.1:8080/ b + test "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/)" = 200 + until_up http://127.0.0.1:7777/ b + test "$(mcp -H 'authorization: Bearer ci-token')" = 200 + docker rm -f b + + # The server runs as node, not root. + test "$(docker run --rm --entrypoint id sot:test -u)" != 0 + + publish: + if: github.event_name == 'workflow_dispatch' + needs: test + runs-on: ubuntu-latest + timeout-minutes: 45 + permissions: + contents: read + packages: write + steps: + - name: Check the tag + env: + TAG: ${{ inputs.tag }} + run: | + [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]] || { echo "::error::Not a release tag: $TAG"; exit 1; } + + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.tag }} + persist-credentials: false + + - name: Work out the image name and version + id: meta + env: + TAG: ${{ inputs.tag }} + run: | + set -euo pipefail + want="v$(jq -r .version package.json)" + if [ "$TAG" != "$want" ]; then echo "::error::Release tag $TAG does not match package.json ($want)"; exit 1; fi + # Named after this repository (ghcr.io//, lowercased), so forks publish their own. + echo "image=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT" + echo "version=${TAG#v}" >> "$GITHUB_OUTPUT" + echo "revision=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT" + echo "created=$(git log -1 --format=%cI)" >> "$GITHUB_OUTPUT" + + - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0 + + - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 + + - uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - - name: Build and push - uses: docker/build-push-action@v6 + - name: Build and push the release's version + uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 with: context: . file: docker/Dockerfile platforms: linux/amd64,linux/arm64 push: true - tags: ${{ steps.tags.outputs.tags }} + tags: ${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.version }} + labels: | + org.opencontainers.image.title=Series of Tubes MCP server + org.opencontainers.image.description=The Series of Tubes MCP server and development server, so an AI client can play the game. + org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }} + org.opencontainers.image.documentation=${{ github.server_url }}/${{ github.repository }}/blob/${{ inputs.tag }}/docs/MCP.md + org.opencontainers.image.version=${{ steps.meta.outputs.version }} + org.opencontainers.image.revision=${{ steps.meta.outputs.revision }} + org.opencontainers.image.created=${{ steps.meta.outputs.created }} + org.opencontainers.image.licenses=MIT + provenance: mode=max + sbom: true cache-from: type=gha cache-to: type=gha,mode=max diff --git a/.github/workflows/perf-comment.yml b/.github/workflows/perf-comment.yml index 2f6c286..ca461da 100644 --- a/.github/workflows/perf-comment.yml +++ b/.github/workflows/perf-comment.yml @@ -17,7 +17,7 @@ jobs: if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' runs-on: ubuntu-latest steps: - - uses: actions/download-artifact@v4 + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 with: name: perf run-id: ${{ github.event.workflow_run.id }} diff --git a/.github/workflows/perf.yml b/.github/workflows/perf.yml index 48c05e4..00ffce2 100644 --- a/.github/workflows/perf.yml +++ b/.github/workflows/perf.yml @@ -22,8 +22,8 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 40 steps: - - uses: actions/checkout@v7 - - uses: actions/setup-node@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 24 cache: npm @@ -48,7 +48,7 @@ jobs: env: PR: ${{ github.event.pull_request.number }} run: echo "$PR" > pr-number.txt - - uses: actions/upload-artifact@v4 + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 if: github.event_name == 'pull_request' with: name: perf diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c9e813f..b77850e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -42,10 +42,10 @@ jobs: ALLOW_OLDER: ${{ inputs.allow_older || false }} GH_TOKEN: ${{ github.token }} steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: ${{ env.TAG }} - - uses: actions/setup-node@v7 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 24 cache: npm @@ -100,7 +100,7 @@ jobs: run: npm test -- tests/weekly-puzzle.test.js tests/puzzles.test.js $(ls tests/weekly-scenario.test.js tests/weekly-architect.test.js 2>/dev/null) - name: Build site run: VERSION="${TAG#v}" REQUIRE_NOTES=1 npm run build - - uses: actions/upload-pages-artifact@v5 + - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 with: path: ./_site @@ -115,9 +115,7 @@ jobs: url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment - uses: actions/deploy-pages@v5 - - # Tell IndexNow (Bing, Yandex, Seznam, …) about the new version, only after + uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 # the site is live. indexnow: needs: deploy diff --git a/.github/workflows/weekly-puzzle.yml b/.github/workflows/weekly-puzzle.yml index fdff934..6cfa3d5 100644 --- a/.github/workflows/weekly-puzzle.yml +++ b/.github/workflows/weekly-puzzle.yml @@ -38,10 +38,10 @@ jobs: GH_TOKEN: ${{ github.token }} KEY: ${{ inputs.key }} steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: main - - uses: actions/setup-node@v7 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 24 cache: npm diff --git a/docker/Dockerfile b/docker/Dockerfile index 1228b19..1ce5130 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -1,16 +1,28 @@ -FROM node:26-slim +# The MCP server and the development server in one image (docs/MCP.md, "In a container"). docker.yml builds it and +# publishes it to GHCR for releases only; nothing here is ever deployed to GitHub Pages (docs/adr/0001-github-pages-only.md). +# The base is pinned by digest and kept current by Dependabot (.github/dependabot.yml); CI tests on the same Node major. +FROM node:24-slim@sha256:01d566e8d94d8c619591d78652babfccd3c6992a3dffa9ed5ab39e11cf6c70e9 -COPY . /series-of-tubes WORKDIR /series-of-tubes -RUN npm install +# Dependencies first, exactly as locked, so a change to the code reuses this layer. Every dependency is a dev one (the +# game has none), and the servers need them all. No install scripts run. +COPY package.json package-lock.json ./ +RUN npm ci --no-audit --no-fund --ignore-scripts && npm cache clean --force -COPY docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh -RUN chmod +x /usr/local/bin/docker-entrypoint.sh \ - && chown -R node:node /series-of-tubes +# Only what the servers read: the game's source and static files, the scripts, and the harness the MCP server plays +# through. Owned by root and read-only to the server, which runs as node. +COPY src ./src +COPY site ./site +COPY scripts ./scripts +COPY tests/harness.js ./tests/harness.js +COPY --chmod=0755 docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh + +# --save-dir /saves needs somewhere the server may write: a volume mounted here takes this ownership. +RUN mkdir /saves && chown node:node /saves +VOLUME /saves USER node - +ENV NPM_CONFIG_UPDATE_NOTIFIER=false EXPOSE 8080 7777 - ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"] diff --git a/docker/docker-entrypoint.sh b/docker/docker-entrypoint.sh index 1d5938d..355af5a 100644 --- a/docker/docker-entrypoint.sh +++ b/docker/docker-entrypoint.sh @@ -1,42 +1,55 @@ #!/usr/bin/env bash -set -u +# Starts the container's servers (docker/Dockerfile, docs/MCP.md "In a container"). +# MCP_MODE=browser (default): the development server on :8080, with the relay a player's tab dials, and the MCP server +# on :7777 driving that tab. +# MCP_MODE=headless: only the MCP server, with a game of its own. +# Everything after the image name goes to scripts/mcp.js (node scripts/mcp.js --help lists the options). +set -uo pipefail cd /series-of-tubes -# MCP_MODE picks what runs: browser (default) serves the game page and relays the -# player's tab to the MCP server; headless runs a game of its own, no page needed. mode=${MCP_MODE:-browser} case "$mode" in browser|headless) ;; *) echo "[entrypoint] MCP_MODE must be browser or headless, not '$mode'" >&2; exit 1 ;; esac -# Everything after the image name is passed to the MCP server as well -# (node scripts/mcp.js --help lists the options). extra=("$@") +has() { local a; for a in "${extra[@]}"; do [ "$a" = "$1" ] && return 0; done; return 1; } -# A container needs 0.0.0.0 to be reachable at all; default --http unless given. +# A container must listen beyond loopback to be reachable at all; --http in the arguments overrides it. http=(--http 0.0.0.0:7777) -for a in "${extra[@]}"; do [ "$a" = --http ] && http=(); done +has --http && http=() + +# Listening beyond loopback, the MCP server would take orders from anyone who reaches the port (its Host check stops +# browsers, not other clients), so it gets a token. None given (SOT_MCP_TOKEN or --token-file): this run makes one and +# prints it. MCP_NO_TOKEN=1 turns that off, for a port published to 127.0.0.1 only. +if [ -z "${SOT_MCP_TOKEN:-}" ] && ! has --token-file && [ "${MCP_NO_TOKEN:-}" != 1 ]; then + SOT_MCP_TOKEN=$(node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('base64url'))") + export SOT_MCP_TOKEN + echo "[entrypoint] No SOT_MCP_TOKEN given: this run's token is $SOT_MCP_TOKEN" >&2 + echo "[entrypoint] claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp --header \"Authorization: Bearer $SOT_MCP_TOKEN\"" >&2 +fi pids=() start() { "$@" & pids+=("$!"); } - shutdown() { trap '' TERM INT - kill -TERM "${pids[@]}" 2>/dev/null - wait "${pids[@]}" 2>/dev/null - exit 0 + kill -TERM "${pids[@]}" 2>/dev/null || true + wait "${pids[@]}" 2>/dev/null || true + exit "${1:-0}" } trap shutdown TERM INT +# node directly, not npm run: one process less, and signals reach the server. if [ "$mode" = browser ]; then - start npm run dev -- --host 0.0.0.0 --port 8080 - start npm run mcp -- --browser "${http[@]}" "${extra[@]}" + start node scripts/dev.js --host 0.0.0.0 --port 8080 + start node scripts/mcp.js --browser "${http[@]}" "${extra[@]}" else - start npm run mcp -- "${http[@]}" "${extra[@]}" + start node scripts/mcp.js "${http[@]}" "${extra[@]}" fi +# One server stopping stops the container, with its status, so a restart policy can bring both back. status=0 wait -n || status=$? -echo "[entrypoint] a process exited with status $status; stopping the container" >&2 -shutdown +echo "[entrypoint] a server exited with status $status; stopping the container" >&2 +shutdown "$status" diff --git a/docs/MCP.md b/docs/MCP.md index 4c6b590..a93ef93 100644 --- a/docs/MCP.md +++ b/docs/MCP.md @@ -79,36 +79,49 @@ claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp ### In a container -Every push to `main` and every release publishes a multi-arch (amd64/arm64) image at -`ghcr.io/fjaeckel/seriesoftubes`, built from the repo by the `docker.yml` workflow: `latest` and the commit SHA on -pushes, the release's version (pre-releases included) on releases. It packages the dev server and the MCP server; -`node scripts/mcp.js --help` options go after the image name, and `--http 0.0.0.0:7777` is the default (a container -bound to loopback would be unreachable; pass your own `--http` to override). +Every release publishes a multi-arch (amd64/arm64) image at `ghcr.io/fjaeckel/seriesoftubes:` +(`docker.yml`, dispatched by the release; pre-releases too). There is no `latest` and no image per commit: pick a +version from the [releases](https://github.com/fjaeckel/seriesoftubes/releases). It holds the MCP server and the +development server, nothing else from the repository, and runs as `node`, not root. It is published to GHCR only; the +game itself is served from GitHub Pages and nowhere else. -`MCP_MODE=headless` runs just the MCP server with a game of its own; the default (`browser`) also serves the -development page so a browser tab can play it, as above. +- **`MCP_MODE=browser`** (the default) serves the development page on 8080, with the relay, and runs the MCP server on + 7777 driving that tab. **`MCP_MODE=headless`** runs only the MCP server, with a game of its own. +- **Options** go after the image name, to `scripts/mcp.js` (`node scripts/mcp.js --help`). The MCP server listens on + `0.0.0.0:7777` inside the container, since loopback there is unreachable; pass your own `--http` to change it. +- **A token, always.** The Host check stops browsers, not other clients, so a published port without a token is open to + anyone who reaches it. Give one with `-e SOT_MCP_TOKEN=…` (or `--token-file`); without one the container makes a + token for this run and prints it, with the `claude mcp add` line to use it. `MCP_NO_TOKEN=1` turns that off. +- **Publish the ports to loopback** (`-p 127.0.0.1:7777:7777`), as below. A bare `-p 7777:7777` listens on every + interface of the host, and Docker's rules go around ufw and firewalld. To reach it from elsewhere, keep the token, + add `--allow-host NAME` for the name or address clients use (requests naming the host's address are refused + otherwise, since that is not an address inside the container), and put TLS in front. +- **The relay has no token** (as with `npm run dev -- --host`): in browser mode, anyone who reaches port 8080 can drive + a game whose player turned agent mode on. Publish it to loopback too. ```sh -docker run -d -p 7777:7777 -e MCP_MODE=headless ghcr.io/fjaeckel/seriesoftubes -claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp +V=2.10.1 # a release -# Options are passed to scripts/mcp.js; the token is its own env var. -docker run -d -p 7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=secret \ - ghcr.io/fjaeckel/seriesoftubes --clock realtime --pace 60000 +# Headless, with your own token +docker run -d --name sot -p 127.0.0.1:7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=secret \ + ghcr.io/fjaeckel/seriesoftubes:$V --clock realtime --pace 60000 +claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp --header "Authorization: Bearer secret" -# The browser session: open http://localhost:8080, then Settings → Agent API. -docker run -d -p 8080:8080 -p 7777:7777 ghcr.io/fjaeckel/seriesoftubes +# The browser session: open http://localhost:8080, then Settings → Agent API. The token is in `docker logs sot`. +docker run -d --name sot -p 127.0.0.1:8080:8080 -p 127.0.0.1:7777:7777 ghcr.io/fjaeckel/seriesoftubes:$V ``` -`load_save` and `export_save` take JSON only unless the server runs with `--save-dir`; mount a volume for it: +`load_save` and `export_save` take JSON only unless the server runs with `--save-dir`; the image has `/saves` for it, +owned by the server's user, so mount a volume there: ```sh -docker run -d -p 7777:7777 -e MCP_MODE=headless -v sot-saves:/saves \ - ghcr.io/fjaeckel/seriesoftubes --save-dir /saves +docker run -d -p 127.0.0.1:7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=secret -v sot-saves:/saves \ + ghcr.io/fjaeckel/seriesoftubes:$V --save-dir /saves ``` -What "Over HTTP" says applies to the container too: the mapped port is reachable by anything that can reach the host, -so set a token before exposing one, and there is no TLS. +The image's Node base is pinned by digest, its dependencies by the lockfile, and every workflow action by commit; +Dependabot (`.github/dependabot.yml`) keeps them current. Pull requests that touch the image build it and try both modes +without publishing. ## The clock diff --git a/docs/adr/0001-github-pages-only.md b/docs/adr/0001-github-pages-only.md index 039db57..d435457 100644 --- a/docs/adr/0001-github-pages-only.md +++ b/docs/adr/0001-github-pages-only.md @@ -41,6 +41,9 @@ Anything that needs data at runtime fetches it from the same origin as a static what is cached for offline play, versioned by the release. - **Deploys only come from releases.** `release.yml` is the only workflow with `pages: write`. Pushes to `main` never deploy. +- **Tools are not hosting.** `npm run dev`, the MCP server and the container image that packages them + (`docker/`, published to GHCR for releases) are tools. What someone serves with them is theirs; seriesoftub.es is + the game, and nothing is ever deployed anywhere but GitHub Pages. - **Tests guard it.** `tests/pages.test.js` checks that a build is plain static files that GitHub Pages can serve as they are: no server or host configuration files, every local reference resolving inside `_site/`, nothing over the size limits, `CNAME` and `404.html` in place, and the deploy going diff --git a/tests/docker.test.js b/tests/docker.test.js new file mode 100644 index 0000000..b541998 --- /dev/null +++ b/tests/docker.test.js @@ -0,0 +1,78 @@ +// The container image and the workflows that build things: what is published, how, and that every third-party piece is +// pinned. The image goes to GHCR for releases only (no :latest, no image per commit), never to Pages; it runs as node, +// from a base pinned by digest, with only what the servers read; its MCP server gets a token unless told otherwise; every +// GitHub Action is pinned to a commit; Dependabot keeps all of it current. docs/MCP.md, "In a container". +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const ROOT = path.join(__dirname, '..'); +const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8'); +// Without comments: what a file says about itself is not what it does. +const code = (p) => read(p).split('\n').map((l) => l.replace(/(^|\s)#.*$/, '')).join('\n'); +const WF = path.join(ROOT, '.github', 'workflows'); + +test('every GitHub Action in every workflow is pinned to a commit, with its version beside it', () => { + const loose = []; + for (const f of fs.readdirSync(WF).filter((f) => /\.ya?ml$/.test(f))) + for (const [i, line] of read(`.github/workflows/${f}`).split('\n').entries()) { + const m = /^\s*(?:-\s*)?uses:\s*(\S+)(.*)$/.exec(line); + if (!m || m[1].startsWith('./')) continue; + if (!/^[\w.-]+\/[\w./-]+@[0-9a-f]{40}$/.test(m[1]) || !/#\s*v\d+(\.\d+)*/.test(m[2])) loose.push(`${f}:${i + 1} ${m[1]}`); + } + assert.deepEqual(loose, []); +}); + +test('Dependabot keeps the actions, the image’s base and the npm tools current', () => { + const d = read('.github/dependabot.yml'); + for (const [eco, dir] of [['github-actions', '/'], ['docker', '/docker'], ['npm', '/']]) + assert.match(d, new RegExp(`package-ecosystem: ${eco}\\s+directory: ${dir.replace('/', '\\/')}\\n`), eco); +}); + +test('the image is published for releases only, as their version, never as latest', () => { + const w = code('.github/workflows/docker.yml'); + assert.doesNotMatch(w, /:latest\b|\blatest\b.*tags|tags:.*latest/, 'no latest'); + assert.doesNotMatch(w, /\$GITHUB_SHA|github\.sha\b.*tags/, 'no image per commit'); + assert.doesNotMatch(w, /^\s+release:/m, 'releases dispatch it; the release event does not'); + // Only the publish job may push or hold packages: write, and it runs only when a release dispatches it. + const pub = w.slice(w.indexOf('\n publish:')); + const tst = w.slice(w.indexOf('\n test:'), w.indexOf('\n publish:')); + assert.match(pub, /if: github\.event_name == 'workflow_dispatch'/); + assert.match(pub, /needs: test/, 'only an image that passed the smoke test'); + assert.match(pub, /push: true/); + assert.match(pub, /tags: \$\{\{ steps\.meta\.outputs\.image \}\}:\$\{\{ steps\.meta\.outputs\.version \}\}\n/, 'one tag: the version'); + assert.match(pub, /does not match package\.json/, 'the tag must be the release in package.json'); + assert.doesNotMatch(tst, /push: true|packages: write/, 'the test job never publishes'); + assert.match(w, /^permissions:\n {2}contents: read\n/m, 'read-only unless publishing'); + assert.doesNotMatch(w, /pages: write|deploy-pages/, 'never to Pages'); + // auto-release.yml is what dispatches it, with the new tag. + assert.match(read('.github/workflows/auto-release.yml'), /gh workflow run docker\.yml [^\n]*-f tag=/); +}); + +test('the image: pinned base, locked dependencies, only what the servers need, not root', () => { + const d = code('docker/Dockerfile'); + assert.match(d, /^FROM node:\d+-slim@sha256:[0-9a-f]{64}$/m, 'the base is pinned by digest'); + const nodeMajor = /FROM node:(\d+)/.exec(d)[1]; + for (const m of read('.github/workflows/ci.yml').matchAll(/node-version: (\d+)/g)) assert.equal(m[1], nodeMajor, 'the Node major CI tests on'); + assert.match(d, /npm ci\b/); assert.doesNotMatch(d, /npm install\b/); + assert.ok(d.indexOf('COPY package.json package-lock.json') < d.indexOf('npm ci') && d.indexOf('npm ci') < d.indexOf('COPY src'), 'dependencies are their own layer'); + assert.doesNotMatch(d, /^COPY \. /m, 'not the whole repository'); + assert.doesNotMatch(d, /chown -R/, 'no second copy of every file just to change its owner'); + assert.match(d, /^USER node$/m); + const ig = read('.dockerignore').split('\n').filter((l) => l && !l.startsWith('#')); + assert.equal(ig[0], '*', 'the build context is an allow-list'); + for (const m of d.matchAll(/^COPY (?:--\S+ )*(\S+)/gm)) if (m[1] !== 'package.json') assert.ok(ig.includes('!' + m[1]) || ig.includes('!' + m[1] + '/'), `${m[1]} is let into the context`); +}); + +test('the entrypoint: both modes, a token unless told otherwise, and the servers run directly', () => { + const e = code('docker/docker-entrypoint.sh'); + assert.match(e, /browser\|headless/); + assert.match(e, /SOT_MCP_TOKEN=\$\(node -e/, 'makes a token when none is given'); + assert.match(e, /MCP_NO_TOKEN/, 'and can be told not to'); + assert.match(e, /start node scripts\/dev\.js --host 0\.0\.0\.0 --port 8080/); + assert.match(e, /start node scripts\/mcp\.js --browser/); + assert.doesNotMatch(e, /npm run/); + // Every file the image's servers load at start is in the image. + for (const f of ['scripts/mcp.js', 'scripts/dev.js', 'tests/harness.js', 'scripts/lib/page.js']) assert.ok(fs.existsSync(path.join(ROOT, f)), f); +});