sandwich-hime-tutorial/README.md

Sandwich Hime tutorial starter

This is the runnable companion to the official Walk the path tutorial. The website owns the lesson; this repository is the small application you can clone, run, take apart, and turn into something of your own. It takes the lesson's minimal Link model one small step further with a described Trail and adds visible per-request proof, while preserving the same component structure.

Use this, change it, or don’t—we’re just glad you’re here with us.

The starter demonstrates the boundary plainly:

• Hime-san compiles three typed .sando templates into committed Go during development.
• Badge, Home, and Layout nest through the same sando.Component contract.
• An ordinary net/http handler builds the trail list and typed view data on every request.
• ?name= is untrusted input and is contextually escaped by generated code.
• Each successful response contains a fresh UTC timestamp and process-local request number, uses Cache-Control: no-store, and reports buffered render time through Server-Timing.
• Production imports the Apache-2.0 sando runtime, not the compiler.

Walk the path with Beta 1

Install Go 1.25 or newer, then resolve the tiny runtime before installing the immutable classroom compiler:

git clone https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial.git
cd sandwich-hime-tutorial
GOWORK=off go mod download gamertan.com/sandwich-hime/sando@v1.0.0-beta.1
go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.1
./scripts/verify.sh
GOWORK=off go run ./cmd/site

On Windows PowerShell, use the native verifier:

git clone https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial.git
Set-Location sandwich-hime-tutorial
$env:GOWORK = "off"
go mod download gamertan.com/sandwich-hime/sando@v1.0.0-beta.1
go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.1
.\scripts\verify.ps1
go run ./cmd/site

Make sure Go's install directory—normally $(go env GOPATH)/bin—is on PATH, or set HIMESAN_BIN to the full compiler path before running either verifier. The starter deliberately runs with GOWORK=off: it proves the application resolves the published Apache-2.0 runtime rather than a neighboring development checkout. The verification scripts also reject any compiler or runtime version other than v1.0.0-beta.1.

Beta 1 is intended for classrooms, learning, prototypes, and evaluation. Its interfaces may still change before final v1. Linux and Windows have been maintainer-tested; macOS is provisional while native maintainer testing is pending. Useful Mac compatibility reports are welcome on canonical Gitea.

Open http://127.0.0.1:8080/?name=Hime-san, refresh it, and watch the request number and UTC time change. Then try:

http://127.0.0.1:8080/?name=<script>alert("no")</script>

The browser displays those characters as text. They do not become markup or script. The tests also prove that an ordinary javascript: URL is rejected at render time.

Project map

cmd/site/main.go              application-owned listener
internal/server/handler.go    router, typed request data, and HTTP policy
internal/views/views.go       typed template contracts
internal/views/*.sando        templates people edit
internal/views/*.sando.go     committed generated Go
scripts/verify.sh             generation, tests, build, and dependency gate
scripts/verify.ps1            the same gate for native Windows PowerShell

The application owns the server, routing, headers, data, and deployment. Sandwich Hime owns template compilation; sando owns the tiny runtime render contract. Read the language and security documentation before accepting real user content.

What the verification gate proves

./scripts/verify.sh and scripts/verify.ps1 check committed output, generate twice and compare digests, run all tests and go vet, build the server into a temporary directory, and inspect its Go dependency graph. The only production Sandwich Hime package allowed by that graph is gamertan.com/sandwich-hime/sando.

The human-authored starter is 0BSD, specifically so copying it does not drag a complicated license conversation into your application.