Add the embeddable reference host + shellcade-kit CLI to the module

.changeset/reference-host-and-cli.md

@@ -0,0 +1,16 @@
+---
+"kit": minor
+---
+
+feat: the embeddable reference host and the `shellcade-kit` CLI now ship in the module
+
+The host that runs a wasm game against the ABI is now public under `host/`:
+`host/gameabi` (the wasm host), `host/sdk` (the room engine + service
+interfaces), `host/render` + `host/canvas` (the 80×24 framebuffer and ANSI
+render), `host/blobstore` (hibernation snapshots), `host/memsvc` (in-memory
+service implementations), and `host/gameabi/conformance` (the game conformance
+harness). `cmd/shellcade-kit` (`new` / `check` / `play` / `smoke`) is built from
+that reference host, so the CLI and the conformance gate run the exact host a
+game runs on — no separate host binary required.
+
+Additive only: the guest SDK and the ABI are unchanged.

.github/workflows/ci.yml

@@ -18,67 +18,6 @@ env:
   SHELLCADE_KIT_SHA256: "9db05e285fb0d9ea41c1f2e772d1658814d9048bc9bee0e18e89d3b2a2be203d"
 
 jobs:
-  # Toolchain pin lockstep: the SHELLCADE_KIT_VERSION pin above is a manual
-  # mirror of the newest published shellcade-kit binary release, and it has
-  # drifted before (2.2.0 lingered after v2.3.0 shipped). Two mechanical
-  # checks keep it honest:
-  #   1. the binary fetched at tag vX must EMBED kit vX — parse the `kit`
-  #      line of `shellcade-kit version` (the kit module version baked in via
-  #      debug.ReadBuildInfo, NOT the binary's own version line);
-  #   2. the pin must equal the newest release that actually carries
-  #      shellcade-kit binaries (binaries attach to existing kit releases, so
-  #      bare module tags without assets don't count).
-  # Runs on the nightly schedule too: staleness appears without a push.
-  kit-pin:
-    runs-on: ubuntu-latest
-    steps:
-      - name: fetch pinned shellcade-kit (sha256-verified)
-        run: |
-          set -euo pipefail
-          ver="${SHELLCADE_KIT_VERSION}"
-          asset="shellcade-kit_${ver}_linux_amd64.tar.gz"
-          base="https://github.com/shellcade/kit/releases/download/v${ver}"
-          curl -fsSL -o "${asset}" "${base}/${asset}"
-          echo "${SHELLCADE_KIT_SHA256}  ${asset}" | sha256sum -c -
-          tar -xzf "${asset}" shellcade-kit
-          sudo install shellcade-kit /usr/local/bin/shellcade-kit
-      - name: pinned binary embeds the pinned kit version (lockstep)
-        run: |
-          set -euo pipefail
-          shellcade-kit version
-          embedded="$(shellcade-kit version | awk '$1 == "kit" { print $2 }')"
-          if [ "${embedded}" != "v${SHELLCADE_KIT_VERSION}" ]; then
-            echo "::error::lockstep violation: the v${SHELLCADE_KIT_VERSION} shellcade-kit binary embeds kit ${embedded}."
-            echo "A binary released at tag vX must be built against kit vX (see CLAUDE.md 'Lockstep')."
-            echo "Bump SHELLCADE_KIT_VERSION and SHELLCADE_KIT_SHA256 in ci.yml to a release whose binary matches its tag."
-            exit 1
-          fi
-      - name: pin is the newest published binary release
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -euo pipefail
-          # Newest release carrying shellcade-kit binaries — NOT releases/latest
-          # blindly, and not bare module tags: the private repo attaches the
-          # binaries to this repo's existing releases after a kit tag, so only
-          # releases with a shellcade-kit linux/amd64 asset are candidates.
-          newest="$(gh api "repos/${GITHUB_REPOSITORY}/releases?per_page=30" --jq \
-            '[.[] | select(.draft or .prerelease | not)
-                  | select(any(.assets[].name; startswith("shellcade-kit_") and endswith("_linux_amd64.tar.gz")))
-             ][0].tag_name')"
-          echo "pin: v${SHELLCADE_KIT_VERSION}  newest binary release: ${newest}"
-          if [ -z "${newest}" ] || [ "${newest}" = "null" ]; then
-            echo "::error::could not determine the newest shellcade-kit binary release"
-            exit 1
-          fi
-          if [ "${newest}" != "v${SHELLCADE_KIT_VERSION}" ] && \
-             [ "$(printf '%s\n' "v${SHELLCADE_KIT_VERSION}" "${newest}" | sort -V | tail -n1)" = "${newest}" ]; then
-            echo "::error::SHELLCADE_KIT_VERSION (${SHELLCADE_KIT_VERSION}) is stale: the newest published shellcade-kit binary release is ${newest}."
-            echo "Bump SHELLCADE_KIT_VERSION to ${newest#v} and SHELLCADE_KIT_SHA256 to the"
-            echo "linux/amd64 entry of that release's checksums.txt in .github/workflows/ci.yml."
-            exit 1
-          fi
-
   test:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -3,3 +3,6 @@ go.work*
 node_modules/
 dist/
 target/
+
+# Conformance/host test fixtures are committed (small, deterministic ABI inputs).
+!host/gameabi/testdata/**/*.wasm

cmd/shellcade-kit/artifact.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+)
+
+// resolveArtifact turns a check/play/smoke argument into (wasm path, game
+// dir): a .wasm is used as-is; a directory is built per its module marker —
+// go.mod via the pinned TinyGo profile, Cargo.toml via cargo wasm32-wasip1 —
+// into a temp artifact (cleanup removes it). This is the whole-toolchain
+// inner loop in one command: `shellcade-kit play .` (or check/smoke) builds
+// and runs the real artifact regardless of the game's source language.
+func resolveArtifact(arg string) (wasm, dir string, cleanup func(), err error) {
+	if strings.HasSuffix(arg, ".wasm") {
+		return arg, filepath.Dir(arg), nil, nil
+	}
+	info, err := os.Stat(arg)
+	if err != nil {
+		return "", "", nil, err
+	}
+	if !info.IsDir() {
+		return "", "", nil, fmt.Errorf("%s is neither a .wasm nor a game directory", arg)
+	}
+	dir = arg
+
+	tmp, err := os.MkdirTemp("", "shellcade-kit-*")
+	if err != nil {
+		return "", "", nil, err
+	}
+	cleanup = func() { os.RemoveAll(tmp) }
+	wasm = filepath.Join(tmp, "game.wasm")
+
+	var cmd *exec.Cmd
+	switch {
+	case exists(filepath.Join(dir, "go.mod")):
+		// The pinned TinyGo profile — the same build games CI runs.
+		cmd = exec.Command("tinygo", "build", "-opt=1", "-no-debug", "-gc=conservative",
+			"-o", wasm, "-target", "wasip1", "-buildmode=c-shared", ".")
+	case exists(filepath.Join(dir, "Cargo.toml")):
+		cmd = exec.Command("cargo", "build", "--release", "--target", "wasm32-wasip1")
+	default:
+		cleanup()
+		return "", "", nil, fmt.Errorf("%s has neither go.mod nor Cargo.toml", dir)
+	}
+	cmd.Dir = dir
+	cmd.Stdout, cmd.Stderr = os.Stderr, os.Stderr
+	if err := cmd.Run(); err != nil {
+		cleanup()
+		return "", "", nil, fmt.Errorf("build %s: %w", dir, err)
+	}
+
+	if exists(filepath.Join(dir, "Cargo.toml")) {
+		// cargo writes into target/; find the produced cdylib.
+		matches, _ := filepath.Glob(filepath.Join(dir, "target", "wasm32-wasip1", "release", "*.wasm"))
+		if len(matches) != 1 {
+			cleanup()
+			return "", "", nil, fmt.Errorf("expected exactly one wasm under target/wasm32-wasip1/release, found %d", len(matches))
+		}
+		wasm = matches[0]
+	}
+	return wasm, dir, cleanup, nil
+}
+
+func exists(p string) bool {
+	_, err := os.Stat(p)
+	return err == nil
+}

cmd/shellcade-kit/artifact_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+)
+
+// TestResolveArtifactPassthroughAndErrors pins the shared check/play/smoke
+// argument contract: a .wasm passes through untouched (its directory is the
+// game dir), and everything that is neither a .wasm nor a buildable game
+// directory fails before any toolchain is invoked.
+func TestResolveArtifactPassthroughAndErrors(t *testing.T) {
+	wasm, dir, cleanup, err := resolveArtifact(filepath.Join("some", "path", "game.wasm"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if wasm != filepath.Join("some", "path", "game.wasm") {
+		t.Errorf("a .wasm must pass through untouched, got %q", wasm)
+	}
+	if dir != filepath.Join("some", "path") {
+		t.Errorf("game dir must be the artifact's directory, got %q", dir)
+	}
+	if cleanup != nil {
+		t.Error("passthrough must not allocate a temp dir")
+	}
+
+	if _, _, _, err := resolveArtifact(filepath.Join(t.TempDir(), "absent")); err == nil {
+		t.Error("a nonexistent path must be refused")
+	}
+
+	plain := filepath.Join(t.TempDir(), "notes.txt")
+	if err := os.WriteFile(plain, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, _, _, err := resolveArtifact(plain); err == nil {
+		t.Error("a non-.wasm regular file must be refused")
+	}
+
+	if _, _, _, err := resolveArtifact(t.TempDir()); err == nil {
+		t.Error("a directory without go.mod or Cargo.toml must be refused")
+	}
+}
+
+// TestCheckAcceptsGameDirectory is the dir-aware inner-loop contract for
+// `check` (and, via the same resolveArtifact, `play`): pointing it at a game
+// directory builds the artifact and runs the full harness. Requires tinygo;
+// skipped when missing.
+func TestCheckAcceptsGameDirectory(t *testing.T) {
+	if testing.Short() {
+		t.Skip("short mode")
+	}
+	if _, err := exec.LookPath("tinygo"); err != nil {
+		t.Skip("tinygo not on PATH")
+	}
+	dir, err := filepath.Abs(filepath.Join("testdata", "paritygame"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := check(dir); err != nil {
+		t.Fatalf("check <gamedir>: %v", err)
+	}
+}

cmd/shellcade-kit/license.go

@@ -0,0 +1,144 @@
+package main
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+// licenseText renders the LICENSE body for an allowlisted license id
+// (case-insensitive SPDX id), substituting the current year and a
+// "the <name> authors" copyright holder. The allowlist mirrors the games
+// catalog CI validator (validate_game_dir.py), which recognizes a license
+// from the first five lines of the file — so every body below leads with its
+// canonical title line.
+func licenseText(id, name string) (string, error) {
+	for spdx, tmpl := range licenses {
+		if strings.EqualFold(spdx, id) {
+			s := strings.ReplaceAll(tmpl, "YEAR", fmt.Sprint(time.Now().Year()))
+			return strings.ReplaceAll(s, "HOLDER", "the "+name+" authors"), nil
+		}
+	}
+	return "", fmt.Errorf("unknown license %q — the catalog allowlist is %s", id, strings.Join(licenseIDs(), ", "))
+}
+
+// licenseIDs lists the allowlisted SPDX ids, sorted, for error/usage text.
+func licenseIDs() []string {
+	ids := make([]string, 0, len(licenses))
+	for id := range licenses {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+	return ids
+}
+
+// licenses maps each catalog-allowlisted SPDX id to its LICENSE body.
+// MIT, BSD-3-Clause, and Unlicense embed the full canonical text. Apache-2.0
+// and MPL-2.0 use their licenses' own incorporation-by-reference forms (both
+// texts explicitly provide one), with the canonical URL; the catalog
+// validator recognizes them from the leading title line.
+var licenses = map[string]string{
+	"MIT": `MIT License
+
+Copyright (c) YEAR HOLDER
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+`,
+
+	"Apache-2.0": `Apache License, Version 2.0
+
+Copyright YEAR HOLDER
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+`,
+
+	"BSD-3-Clause": `BSD 3-Clause License
+
+Copyright (c) YEAR, HOLDER
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+`,
+
+	"MPL-2.0": `Mozilla Public License Version 2.0
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+`,
+
+	"Unlicense": `This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>
+`,
+}