diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c0613fd..c69c727 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -13,15 +13,71 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- - uses: dtolnay/rust-toolchain@stable
+ with:
+ submodules: recursive
+ - uses: pnpm/action-setup@v4
+ with:
+ version: 10.11.0
+ - uses: actions/setup-node@v4
+ with:
+ node-version-file: .nvmrc
+ cache: pnpm
+ cache-dependency-path: uhura/web/pnpm-lock.yaml
+ - name: build the canonical Uhura provider
+ run: |
+ pnpm -C uhura/web install --frozen-lockfile
+ pnpm -C uhura/web build:provider
+ - uses: dtolnay/rust-toolchain@1.92.0
with:
components: rustfmt, clippy
- uses: Swatinem/rust-cache@v2
- name: fmt
run: cargo fmt --all --check
- name: clippy
- run: cargo clippy --workspace --all-targets -- -D warnings
+ run: cargo clippy --locked --workspace --all-targets -- -D warnings
- name: test
- run: cargo test --workspace
+ run: cargo test --locked --workspace
- name: check the example
- run: cargo run -p spock-cli -- check examples/instagram/v0.spock
+ run: cargo run --locked -p spock-cli -- check examples/instagram/v0.spock
+
+ uhura:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: uhura
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ submodules: recursive
+ - uses: dtolnay/rust-toolchain@1.92.0
+ with:
+ components: rustfmt, clippy
+ - uses: Swatinem/rust-cache@v2
+ with:
+ key: uhura
+ workspaces: uhura -> target
+ - uses: pnpm/action-setup@v4
+ with:
+ version: 10.11.0
+ - uses: actions/setup-node@v4
+ with:
+ node-version-file: .nvmrc
+ cache: pnpm
+ cache-dependency-path: uhura/web/pnpm-lock.yaml
+ # Canonical host integration consumes the ignored provider bundle built
+ # from authoritative TypeScript, so build browser products before Rust.
+ - name: check the Uhura browser and provider
+ run: |
+ pnpm -C web install --frozen-lockfile
+ pnpm -C web check
+ - name: fmt
+ run: cargo fmt --all --check
+ - name: clippy
+ run: cargo clippy --locked --workspace --all-targets -- -D warnings
+ - name: test
+ run: cargo test --locked --workspace --all-targets
+ - name: check the canonical Uhura project
+ run: |
+ cargo run --locked -p uhura-cli -- fmt --check examples/instagram-uhura
+ cargo run --locked -p uhura-cli -- check examples/instagram-uhura --deny-warnings
+ cargo run --locked -p uhura-cli -- trace examples/instagram-uhura --script=demo >/dev/null
diff --git a/.github/workflows/npm.yml b/.github/workflows/npm.yml
index 27912dc..802b385 100644
--- a/.github/workflows/npm.yml
+++ b/.github/workflows/npm.yml
@@ -1,22 +1,23 @@
name: npm
-# Distribution of the `spock` CLI over npm (RFD 0020). One package bundles a
-# prebuilt binary per platform; a Node shim (npm/bin/spock.js) execs the one
+# Distribution of the `spock` framework CLI over npm (RFDs 0020 and 0022). One
+# package bundles a prebuilt binary per platform and one platform-independent
+# Uhura web/Wasm sidecar; a Node shim (npm/bin/spock.js) owns the binary
# matching the host. Publishing is tokenless via npm Trusted Publishing (OIDC):
# this workflow file name (npm.yml) is what the trusted-publisher config on
# npmjs.com is pinned to, and `id-token: write` lets `npm publish` authenticate
# without a token.
#
# Trigger it manually (Actions -> npm -> Run workflow) to dry-run or publish a
-# prerelease under a dist-tag; push a `vX.Y.Z` tag to cut a real `latest`.
+# prerelease under a dist-tag; stable tags publish `latest` and prerelease tags
+# publish `next`.
on:
workflow_dispatch:
inputs:
version:
- description: "Version to publish (e.g. 0.1.0 or 0.1.0-rc.1)"
- required: true
- default: "0.1.0-rc.1"
+ description: "Optional version assertion (defaults to Cargo.toml)"
+ required: false
dist_tag:
description: "npm dist-tag (keeps prereleases off `latest`)"
required: true
@@ -32,6 +33,9 @@ on:
permissions:
contents: read
+env:
+ NPM_CLI_VERSION: 11.6.2
+
concurrency:
group: npm-publish
cancel-in-progress: false
@@ -41,19 +45,104 @@ defaults:
shell: bash
jobs:
+ assets:
+ name: build shared framework assets
+ runs-on: ubuntu-22.04
+ timeout-minutes: 45
+ outputs:
+ manifest_sha256: ${{ steps.sidecar.outputs.manifest_sha256 }}
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ submodules: recursive
+
+ - uses: pnpm/action-setup@v4
+ with:
+ version: 10.11.0
+ - uses: actions/setup-node@v4
+ with:
+ node-version-file: .nvmrc
+ cache: pnpm
+ cache-dependency-path: uhura/web/pnpm-lock.yaml
+
+ - name: self-test sidecar tooling
+ run: node npm/scripts/sidecar.mjs self-test
+
+ - uses: dtolnay/rust-toolchain@1.92.0
+ with:
+ targets: wasm32-unknown-unknown
+ - uses: Swatinem/rust-cache@v2
+ with:
+ key: npm-uhura-wasm
+ workspaces: uhura -> target
+ cache-directories: uhura/target/tools
+
+ - name: check and build Uhura Editor, Play, and provider
+ run: |
+ pnpm -C uhura/web install --frozen-lockfile
+ pnpm -C uhura/web check
+
+ - name: install lockfile-exact wasm-bindgen CLI
+ run: |
+ version="$(sed -n '/name = "wasm-bindgen"/{n;s/version = "\([^"]*\)"/\1/p;q;}' uhura/Cargo.lock)"
+ test -n "$version"
+ installed=""
+ if [ -x uhura/target/tools/bin/wasm-bindgen ]; then
+ installed="$(uhura/target/tools/bin/wasm-bindgen --version | awk '{print $2}')"
+ fi
+ if [ "$installed" != "$version" ]; then
+ cargo install wasm-bindgen-cli \
+ --version "$version" \
+ --locked \
+ --force \
+ --root uhura/target/tools
+ fi
+ test "$(uhura/target/tools/bin/wasm-bindgen --version | awk '{print $2}')" = "$version"
+
+ - name: build Uhura WebAssembly bundle
+ run: WASM_BINDGEN="$GITHUB_WORKSPACE/uhura/target/tools/bin/wasm-bindgen" bash uhura/scripts/build-wasm.sh
+
+ - name: assemble and guard shared sidecar
+ id: sidecar
+ run: |
+ node npm/scripts/sidecar.mjs assemble \
+ --web-dir uhura/web/dist \
+ --wasm-dir uhura/crates/uhura-wasm/pkg/web \
+ --out-dir npm/share/spock/uhura \
+ --spock-commit "$(git rev-parse HEAD)" \
+ --uhura-commit "$(git -C uhura rev-parse HEAD)"
+ node npm/scripts/sidecar.mjs verify --root npm/share/spock/uhura
+ manifest_sha256="$(sha256sum npm/share/spock/uhura/manifest.json | awk '{print $1}')"
+ if [[ ! "$manifest_sha256" =~ ^[0-9a-f]{64}$ ]]; then
+ echo "::error::could not derive the sidecar manifest SHA-256"
+ exit 1
+ fi
+ printf 'manifest_sha256=%s\n' "$manifest_sha256" >> "$GITHUB_OUTPUT"
+ echo "sidecar manifest SHA-256: $manifest_sha256"
+
+ - uses: actions/upload-artifact@v4
+ with:
+ name: framework-assets
+ path: npm/share/spock/uhura/
+ if-no-files-found: error
+ retention-days: 1
+
build:
name: build ${{ matrix.key }}
+ needs: assets
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
include:
- { key: darwin-arm64, os: macos-14, target: aarch64-apple-darwin, smoke: true }
- - { key: darwin-x64, os: macos-14, target: x86_64-apple-darwin, smoke: false }
+ - { key: darwin-x64, os: macos-14, target: x86_64-apple-darwin, smoke: false, rosetta: true }
- { key: linux-x64, os: ubuntu-22.04, target: x86_64-unknown-linux-gnu, smoke: true }
- { key: win32-x64, os: windows-2025, target: x86_64-pc-windows-msvc, smoke: true }
steps:
- uses: actions/checkout@v4
+ with:
+ submodules: recursive
- uses: pnpm/action-setup@v4
with:
@@ -77,7 +166,7 @@ jobs:
test "$bytes" -gt 200 || { echo "::error::$f is only $bytes bytes"; exit 1; }
echo "studio dist/index.html: $bytes bytes"
- - uses: dtolnay/rust-toolchain@stable
+ - uses: dtolnay/rust-toolchain@1.92.0
with:
targets: ${{ matrix.target }}
- uses: Swatinem/rust-cache@v2
@@ -85,7 +174,14 @@ jobs:
key: ${{ matrix.target }}
- name: cargo build --release
- run: cargo build --release -p spock-cli --target ${{ matrix.target }}
+ env:
+ SPOCK_PACKAGED_UHURA_MANIFEST_SHA256: ${{ needs.assets.outputs.manifest_sha256 }}
+ run: |
+ if [[ ! "$SPOCK_PACKAGED_UHURA_MANIFEST_SHA256" =~ ^[0-9a-f]{64}$ ]]; then
+ echo "::error::missing or malformed executable-bound sidecar manifest identity"
+ exit 1
+ fi
+ cargo build --locked --release -p spock-cli --target ${{ matrix.target }}
- name: smoke test (native arch only)
if: matrix.smoke
@@ -95,6 +191,24 @@ jobs:
"$bin" --version
"$bin" check examples/instagram/v0.spock
+ - name: smoke test (macOS x64 through Rosetta)
+ if: matrix.rosetta
+ run: |
+ bin="target/${{ matrix.target }}/release/spock"
+ if ! file "$bin" | grep -q 'Mach-O 64-bit executable x86_64'; then
+ echo "::error::$bin is not an x86_64 Mach-O executable"
+ file "$bin"
+ exit 1
+ fi
+ if ! arch -x86_64 "$bin" --version; then
+ echo "::error::the advertised macOS x64 binary did not run through Rosetta"
+ exit 1
+ fi
+ if ! arch -x86_64 "$bin" check examples/instagram/v0.spock; then
+ echo "::error::the advertised macOS x64 binary could not load and check a Spock program through Rosetta"
+ exit 1
+ fi
+
- name: stage binary
run: |
exe=spock; [ "${{ runner.os }}" = "Windows" ] && exe=spock.exe
@@ -110,43 +224,93 @@ jobs:
publish:
name: publish
- needs: build
+ needs: [assets, build]
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write # required for OIDC trusted publishing
outputs:
version: ${{ steps.resolve.outputs.version }}
+ cargo_version: ${{ steps.resolve.outputs.cargo_version }}
dist_tag: ${{ steps.resolve.outputs.dist_tag }}
dry_run: ${{ steps.resolve.outputs.dry_run }}
steps:
- uses: actions/checkout@v4
+ with:
+ submodules: recursive
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
registry-url: "https://registry.npmjs.org"
- - name: use latest npm (Trusted Publishing needs >= 11.5.1)
- run: npm install -g npm@latest
+ - name: install pinned Trusted-Publishing-capable npm
+ run: npm install -g "npm@$NPM_CLI_VERSION"
- name: resolve version, tag, dry_run
id: resolve
+ env:
+ EVENT_NAME: ${{ github.event_name }}
+ INPUT_VERSION: ${{ inputs.version }}
+ INPUT_DIST_TAG: ${{ inputs.dist_tag }}
+ INPUT_DRY_RUN: ${{ inputs.dry_run }}
run: |
- if [ "${{ github.event_name }}" = "push" ]; then
- v="${GITHUB_REF_NAME#v}"; tag="latest"; dry="false"
+ cargo_version="$(awk '
+ /^\[workspace.package\]$/ { section = 1; next }
+ /^\[/ { section = 0 }
+ section && /^version = / {
+ gsub(/^version = "|"$/, ""); print; exit
+ }
+ ' Cargo.toml)"
+ test -n "$cargo_version"
+ if [ "$EVENT_NAME" = "push" ]; then
+ v="${GITHUB_REF_NAME#v}"; dry="false"
else
- v="${{ inputs.version }}"; tag="${{ inputs.dist_tag }}"; dry="${{ inputs.dry_run }}"
+ v="${INPUT_VERSION:-$cargo_version}"; tag="$INPUT_DIST_TAG"; dry="$INPUT_DRY_RUN"
fi
- printf 'version=%s\n' "$v" >> "$GITHUB_OUTPUT"
- printf 'dist_tag=%s\n' "$tag" >> "$GITHUB_OUTPUT"
- printf 'dry_run=%s\n' "$dry" >> "$GITHUB_OUTPUT"
- echo "resolved: version=$v dist_tag=$tag dry_run=$dry"
+ # Every successful matrix build has already made Cargo parse this
+ # workspace version. Keep Cargo authoritative instead of maintaining
+ # a second, inevitably incomplete SemVer grammar in bash.
+ if [ "$v" != "$cargo_version" ]; then
+ echo "::error::release version $v does not match Cargo workspace version $cargo_version"
+ exit 1
+ fi
+ package_version="${cargo_version%%+*}"
+ if [[ "$package_version" == *-* ]]; then
+ prerelease="true"
+ else
+ prerelease="false"
+ fi
+ if [ "$EVENT_NAME" = "push" ]; then
+ if [ "$prerelease" = "true" ]; then tag="next"; else tag="latest"; fi
+ fi
+ if [[ ! "$tag" =~ ^[A-Za-z][A-Za-z0-9._-]*$ ]]; then
+ echo "::error::invalid npm dist-tag: $tag"
+ exit 1
+ fi
+ if [ "$prerelease" = "true" ] && [ "$tag" = "latest" ]; then
+ echo "::error::prerelease version $v may not publish to the latest dist-tag"
+ exit 1
+ fi
+ if [ "$dry" != "true" ] && [ "$dry" != "false" ]; then
+ echo "::error::dry_run must be true or false"
+ exit 1
+ fi
+ printf 'version=%s\n' "$package_version" >> "$GITHUB_OUTPUT"
+ printf 'cargo_version=%s\n' "$cargo_version" >> "$GITHUB_OUTPUT"
+ printf 'dist_tag=%s\n' "$tag" >> "$GITHUB_OUTPUT"
+ printf 'dry_run=%s\n' "$dry" >> "$GITHUB_OUTPUT"
+ echo "resolved: cargo_version=$cargo_version package_version=$package_version dist_tag=$tag dry_run=$dry"
- uses: actions/download-artifact@v4
with:
path: artifacts
pattern: bin-*
+ - uses: actions/download-artifact@v4
+ with:
+ name: framework-assets
+ path: npm/share/spock/uhura
+
- name: assemble platform binaries into the package
run: |
set -e
@@ -155,9 +319,10 @@ jobs:
exe=spock; [ "$key" = "win32-x64" ] && exe=spock.exe
mkdir -p "npm/binaries/$key"
cp "$d/$exe" "npm/binaries/$key/$exe"
- [ "$key" = "win32-x64" ] || chmod +x "npm/binaries/$key/$exe"
+ [ "$key" = "win32-x64" ] || chmod 0755 "npm/binaries/$key/$exe"
done
- echo "=== assembled ==="; ls -laR npm/binaries
+ echo "=== assembled ==="
+ ls -laR npm/binaries
- name: guard — all four platforms present
run: |
@@ -167,12 +332,99 @@ jobs:
test -s "npm/binaries/$key/$exe" || { echo "::error::missing binary for $key"; exit 1; }
done
+ - name: guard — shared framework sidecar is complete
+ run: node npm/scripts/sidecar.mjs verify --root npm/share/spock/uhura
+
- name: stamp version
- run: cd npm && npm version "${{ steps.resolve.outputs.version }}" --no-git-tag-version --allow-same-version
+ env:
+ PACKAGE_VERSION: ${{ steps.resolve.outputs.version }}
+ run: cd npm && npm version "$PACKAGE_VERSION" --no-git-tag-version --allow-same-version
+
+ - name: guard — packed package is complete and within 25 MiB
+ env:
+ PACKAGE_VERSION: ${{ steps.resolve.outputs.version }}
+ run: |
+ mkdir -p "$RUNNER_TEMP/npm-pack"
+ (cd npm && npm pack --json --pack-destination "$RUNNER_TEMP/npm-pack") \
+ > "$RUNNER_TEMP/npm-pack.json"
+ shopt -s nullglob
+ packages=("$RUNNER_TEMP/npm-pack/"*.tgz)
+ if [ "${#packages[@]}" -ne 1 ]; then
+ echo "::error::expected exactly one guarded npm tarball; found ${#packages[@]}"
+ exit 1
+ fi
+ node - "$RUNNER_TEMP/npm-pack.json" <<'NODE'
+ const fs = require("node:fs");
+ const [entry] = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+ if (!entry || !Number.isSafeInteger(entry.size)) {
+ throw new Error("npm pack did not report a package size");
+ }
+ if (entry.version !== process.env.PACKAGE_VERSION) {
+ throw new Error(
+ `packed npm version ${entry.version} does not match ${process.env.PACKAGE_VERSION}`,
+ );
+ }
+ const manifest = JSON.parse(
+ fs.readFileSync("npm/share/spock/uhura/manifest.json", "utf8"),
+ );
+ const expected = new Set([
+ "LICENSE",
+ "README.md",
+ "THIRD_PARTY_NOTICES.md",
+ "bin/spock.js",
+ "binaries/darwin-arm64/spock",
+ "binaries/darwin-x64/spock",
+ "binaries/linux-x64/spock",
+ "binaries/win32-x64/spock.exe",
+ "package.json",
+ "share/spock/uhura/manifest.json",
+ ...manifest.files.map((file) => `share/spock/uhura/${file.path}`),
+ ]);
+ const packed = new Map(entry.files.map((file) => [file.path, file]));
+ for (const required of expected) {
+ if (!packed.has(required)) throw new Error(`packed package is missing ${required}`);
+ }
+ for (const actual of packed.keys()) {
+ if (!expected.has(actual)) throw new Error(`packed package has unexpected ${actual}`);
+ }
+ for (const path of [
+ "bin/spock.js",
+ "binaries/darwin-arm64/spock",
+ "binaries/darwin-x64/spock",
+ "binaries/linux-x64/spock",
+ ]) {
+ const mode = packed.get(path)?.mode;
+ if (!Number.isSafeInteger(mode) || (mode & 0o777) !== 0o755) {
+ throw new Error(`packed executable must have mode 0755: ${path} (mode ${mode})`);
+ }
+ }
+ const limit = 25 * 1024 * 1024;
+ if (entry.size > limit) {
+ throw new Error(`packed package is ${entry.size} bytes; limit is ${limit} bytes`);
+ }
+ console.log(`packed package: ${entry.size} bytes (${entry.unpackedSize} unpacked)`);
+ NODE
+
+ - name: upload guarded npm tarball
+ uses: actions/upload-artifact@v4
+ with:
+ name: npm-package
+ path: ${{ runner.temp }}/npm-pack/*.tgz
+ if-no-files-found: error
+ retention-days: 1
- name: npm publish (dry run)
if: steps.resolve.outputs.dry_run == 'true'
- run: cd npm && npm publish --dry-run --tag "${{ steps.resolve.outputs.dist_tag }}"
+ env:
+ DIST_TAG: ${{ steps.resolve.outputs.dist_tag }}
+ run: |
+ shopt -s nullglob
+ packages=("$RUNNER_TEMP/npm-pack/"*.tgz)
+ if [ "${#packages[@]}" -ne 1 ]; then
+ echo "::error::expected exactly one guarded npm tarball; found ${#packages[@]}"
+ exit 1
+ fi
+ npm publish "${packages[0]}" --dry-run --tag "$DIST_TAG"
- name: npm publish
if: steps.resolve.outputs.dry_run != 'true'
@@ -180,12 +432,20 @@ jobs:
# races the tarball PUT and returns a false "cannot publish over
# previously published version" (npm/cli). Tokenless OIDC auth is
# independent of provenance and still applies.
- run: cd npm && npm publish --tag "${{ steps.resolve.outputs.dist_tag }}" --no-provenance
+ env:
+ DIST_TAG: ${{ steps.resolve.outputs.dist_tag }}
+ run: |
+ shopt -s nullglob
+ packages=("$RUNNER_TEMP/npm-pack/"*.tgz)
+ if [ "${#packages[@]}" -ne 1 ]; then
+ echo "::error::expected exactly one guarded npm tarball; found ${#packages[@]}"
+ exit 1
+ fi
+ npm publish "${packages[0]}" --tag "$DIST_TAG" --no-provenance
verify:
name: verify ${{ matrix.key }}
needs: publish
- if: needs.publish.outputs.dry_run != 'true'
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
@@ -196,18 +456,60 @@ jobs:
- { key: win32-x64, os: windows-2025 }
steps:
- uses: actions/checkout@v4
+ with:
+ submodules: recursive
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
- - name: install spock from npm
+ - name: download guarded npm tarball
+ if: needs.publish.outputs.dry_run == 'true'
+ uses: actions/download-artifact@v4
+ with:
+ name: npm-package
+ path: packed-npm
+
+ - name: install spock from guarded tarball
+ if: needs.publish.outputs.dry_run == 'true'
+ run: |
+ shopt -s nullglob
+ packages=(packed-npm/*.tgz)
+ if [ "${#packages[@]}" -ne 1 ]; then
+ echo "::error::expected exactly one guarded npm tarball; found ${#packages[@]}"
+ exit 1
+ fi
+ package_path="$(pwd)/${packages[0]}"
+ npm install -g "$package_path"
+ echo "installed $package_path"
+
+ - name: install spock from npm registry
+ if: needs.publish.outputs.dry_run != 'true'
+ env:
+ PACKAGE_VERSION: ${{ needs.publish.outputs.version }}
run: |
- v="${{ needs.publish.outputs.version }}"
+ installed=""
for i in $(seq 1 12); do
- if npm install -g "spock@$v"; then echo "installed spock@$v"; break; fi
- echo "attempt $i: spock@$v not visible yet; waiting"; sleep 6
+ if npm install -g "spock@$PACKAGE_VERSION"; then installed=1; echo "installed spock@$PACKAGE_VERSION"; break; fi
+ echo "attempt $i: spock@$PACKAGE_VERSION not visible yet; waiting"; sleep 6
done
- spock --version
+ test -n "$installed" || { echo "::error::spock@$PACKAGE_VERSION was not installable"; exit 1; }
+
+ - name: verify installed npm and Cargo versions
+ env:
+ PACKAGE_VERSION: ${{ needs.publish.outputs.version }}
+ CARGO_VERSION: ${{ needs.publish.outputs.cargo_version }}
+ run: |
+ package_root="$(npm root -g)"
+ installed_version="$(node -e '
+ const path = require("node:path");
+ const manifest = require(path.join(process.argv[1], "spock", "package.json"));
+ process.stdout.write(manifest.version);
+ ' "$package_root")"
+ test "$installed_version" = "$PACKAGE_VERSION"
+ test "$(spock --version)" = "spock $CARGO_VERSION"
+
+ - name: verify installed framework sidecar
+ run: node npm/scripts/sidecar.mjs verify --root "$(npm root -g)/spock/share/spock/uhura"
- name: spock check
run: spock check examples/instagram/v0.spock
@@ -225,3 +527,97 @@ jobs:
if [ -z "$ok" ]; then echo "::error::server did not start"; kill "$pid" 2>/dev/null || true; exit 1; fi
curl -fsS http://127.0.0.1:4123/~studio | grep -qi "/dev/null || true
+
+ - name: spock framework routes + shared assets served
+ if: runner.os != 'Windows'
+ run: |
+ smoke_root="$RUNNER_TEMP/spock-framework-smoke"
+ mkdir -p "$smoke_root"
+ (cd "$smoke_root" && spock new npm-smoke)
+ spock start "$smoke_root/npm-smoke" --port 4124 >"$smoke_root/server.log" 2>&1 &
+ pid=$!
+ cleanup() {
+ kill "$pid" 2>/dev/null || true
+ wait "$pid" 2>/dev/null || true
+ }
+ trap cleanup EXIT
+ ok=""
+ for i in $(seq 1 40); do
+ if curl -fsS http://127.0.0.1:4124/~health >/dev/null 2>&1; then ok=1; break; fi
+ if ! kill -0 "$pid" 2>/dev/null; then break; fi
+ sleep 0.25
+ done
+ if [ -z "$ok" ]; then
+ echo "::error::framework server did not become ready"
+ cat "$smoke_root/server.log"
+ exit 1
+ fi
+ curl -fsS http://127.0.0.1:4124/ | grep -qi "/dev/null
+ curl -fsS http://127.0.0.1:4124/api/play/wasm/uhura_wasm_bg.wasm >/dev/null
+ curl -fsS http://127.0.0.1:4124/~project/status | grep -q '"protocol":"spock-project-status/1"'
+ curl -fsS http://127.0.0.1:4124/~project/environment | grep -q '"protocol":"spock-host-environment/1"'
+
+ - name: spock framework routes + shared assets served (Windows)
+ if: runner.os == 'Windows'
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $smokeRoot = Join-Path $env:RUNNER_TEMP "spock-framework-smoke"
+ $project = Join-Path $smokeRoot "npm-smoke"
+ $stdout = Join-Path $smokeRoot "server.stdout.log"
+ $stderr = Join-Path $smokeRoot "server.stderr.log"
+ New-Item -ItemType Directory -Force -Path $smokeRoot | Out-Null
+
+ $packageRoot = (& npm root -g).Trim()
+ $shim = Join-Path $packageRoot "spock/bin/spock.js"
+ Push-Location $smokeRoot
+ try {
+ & node $shim new npm-smoke
+ if ($LASTEXITCODE -ne 0) { throw "spock new failed with exit code $LASTEXITCODE" }
+ } finally {
+ Pop-Location
+ }
+
+ $node = (Get-Command node -ErrorAction Stop).Source
+ $arguments = @("`"$shim`"", "start", "`"$project`"", "--port", "4124")
+ $process = Start-Process -FilePath $node -ArgumentList $arguments -PassThru `
+ -RedirectStandardOutput $stdout -RedirectStandardError $stderr
+ try {
+ $ready = $false
+ for ($attempt = 0; $attempt -lt 40; $attempt += 1) {
+ if ($process.HasExited) { break }
+ try {
+ $health = Invoke-RestMethod -Uri "http://127.0.0.1:4124/~health" -TimeoutSec 1
+ if ($health.ready -eq $true) { $ready = $true; break }
+ } catch {
+ Start-Sleep -Milliseconds 250
+ }
+ }
+ if (-not $ready) {
+ if (Test-Path $stdout) { Get-Content $stdout }
+ if (Test-Path $stderr) { Get-Content $stderr }
+ throw "framework server did not become ready"
+ }
+
+ $editor = (Invoke-WebRequest -Uri "http://127.0.0.1:4124/").Content
+ $play = (Invoke-WebRequest -Uri "http://127.0.0.1:4124/play").Content
+ if ($editor -notmatch " It's only logical.
-Spock is an early programming language for prototyping application backends as
-a small, inspectable source of truth.
+Spock is an early meta-framework for prototyping an application as one small,
+inspectable source of truth: a Spock authority backend plus an optional Uhura
+client, checked and served by one `spock` command on one origin. The Spock
+language remains independently usable for backend-only experiments.
Most application backends spread the same intent across too many layers:
database schema, API serializers, mutation handlers, validation, authorization,
@@ -19,11 +21,24 @@ the spec.
## Install
-Spock ships as a single npm package with a prebuilt binary for macOS, Linux,
-and Windows — no build step, no toolchain:
+Spock ships as a single npm package with prebuilt binaries for macOS arm64/x64,
+GNU-libc Linux x64, and Windows x64 — no build step, no toolchain. Alpine and
+other musl-based Linux distributions are not supported yet. Framework commands
+begin with `0.5.0`; registry releases through `0.4.0` expose only the standalone
+language commands.
+
+With the `0.5.0` framework npm release:
+
+```sh
+npx spock new demo
+cd demo
+npx spock dev
+```
+
+Standalone programs keep the same entry points:
```sh
-# run without installing
+npx spock check app.spock
npx spock run app.spock
# or install globally
@@ -31,11 +46,64 @@ npm i -g spock
```
```sh
-spock check app.spock # parse + check a program
-spock run app.spock # materialize + serve (GraphQL, REST, /~studio)
+spock new demo # create backend + Uhura client + spock.toml
+spock check # check the whole nearest project
+spock dev # watch client; observe backend as restart-required
+spock start # serve one fixed combined generation
+
+# standalone language escape hatches stay available
+spock check app.spock # parse + fully load-check one program
+spock run app.spock # materialize + serve GraphQL, REST, and Studio
spock gen types app.spock # emit TypeScript types
```
+## Framework projects
+
+`spock new NAME` creates this canonical topology; `--backend-only` omits the
+client. `spock init [PATH]` adopts unambiguous existing sources without moving
+or overwriting them.
+
+```text
+demo/
+├── spock.toml
+├── backend/
+│ └── app.spock
+└── client/
+ ├── uhura.toml
+ └── ...
+```
+
+The manifest is required, as is its configured `.spock` entry. A project whose
+authority is not designed yet should keep that file empty; the client, health,
+status, contract metadata, Editor, and Play can still run.
+
+`spock dev` deliberately has asymmetric reload semantics today. Valid Uhura
+client saves publish live. Invalid saves retain the last good Play generation
+when one exists; an initially invalid client is reported as `cold_invalid`
+while Editor diagnostics remain available. Backend inputs—including the
+`.spock` source and referenced seed assets—and topology-affecting `spock.toml`
+saves are detected and reported as `restart_required`, but they never reopen,
+reseed, migrate, or replace the active database. Restarting reconstructs
+backend state from seed. This keeps the current behavior honest while the
+development-state model in
+[RFD 0023](docs/rfd/0023-development-state-reload.md) remains open.
+
+Framework composition changes the operational envelope, not the doctrine.
+Spock still owns durable product truth, policy, and guarded mutations; Uhura
+owns presentation, experience transitions, and non-authoritative UI-session
+state. `spock.toml` only composes their roots and lifecycle—it does not merge
+their languages or move authority into the client. No fact may become
+authoritative in both systems just because one command serves them together.
+
+For a project with a configured client, both framework commands serve Uhura
+Editor at `/` and Play at `/play`. Both modes serve Spock Studio at `/~studio`
+and the authority protocols on the same origin; the combined host grants no
+cross-origin CORS access by default. A backend-only project's `/` redirects to
+Studio and its client routes return structured 404 responses.
+`/~project/status` makes the active and merely observed generations explicit;
+`/~health` remains ready-but-degraded when a client candidate is rejected or a
+backend restart is required.
+
## The picture
Today, one product rule — say, *"a member may publish a draft post"* — is
@@ -623,8 +691,11 @@ types` turns the contract into TypeScript — row and write shapes plus the
derived error codes as literal unions — and `spock gen graphql-schema`
prints the SDL for offline schema tooling.
-The npm package metadata lives under `npm/` only to reserve the package name.
-It is not the primary implementation target.
+The package source under `npm/` is the primary no-checkout distribution path.
+Starting with `0.5.0`, it carries all four native binaries plus one
+platform-independent Uhura Editor/Play and WebAssembly sidecar; the small Node
+shim only selects and owns the matching native process. Releases through
+`0.4.0` predate that framework package and remain standalone-only.
## Uhura, the client language
@@ -637,43 +708,57 @@ UI-session state and experience behavior, with Spock as its canonical
provider. No fact may be authoritative in both languages.
Uhura is a subsystem of the Spock project: its canonical source lives in its
-own repository and is included here as a git submodule at `uhura/`. Spock's
-core workspace, default build, and CI remain independent of the submodule, so
-`cargo` builds work without it; clone with `--recurse-submodules` for the
-explicit composition runner below. Once Uhura is minimally stable, its tooling
-ships through the unified `spock` toolchain, and the runtime integration lands
-as contract projection plus a provider adapter.
+own repository and is included here as a git submodule at `uhura/`. The root
+Cargo workspace deliberately excludes Uhura's own workspace, while
+`spock-host` consumes `uhura-host` through a path dependency. Consequently a
+source build of the framework requires an initialized recursive submodule;
+framework npm releases contain the resulting runtime and assets.
-From an umbrella checkout, the general composition runner accepts any Spock
-program and Uhura project. For the Instagram example:
+For a source checkout, build the Uhura web and WebAssembly assets, then provide
+both roots together when running the framework host. Build Studio first too:
+its `dist/` directory exists in a clean checkout but is intentionally empty
+until the SPA build runs.
```sh
-./scripts/spock-uhura.sh \
- examples/instagram-poc/app.spock \
- uhura/examples/instagram-uhura
+git submodule update --init --recursive
+corepack pnpm@10.11.0 -C crates/spock-runtime/studio install --frozen-lockfile
+corepack pnpm@10.11.0 -C crates/spock-runtime/studio build
+corepack pnpm@10.11.0 -C uhura/web install --frozen-lockfile
+corepack pnpm@10.11.0 -C uhura/web check
+bash uhura/scripts/build-wasm.sh
+
+cargo run --locked -p spock-cli -- new demo
+
+SPOCK_UHURA_WEB_DIST="$PWD/uhura/web/dist" \
+SPOCK_UHURA_WASM_DIST="$PWD/uhura/crates/uhura-wasm/pkg/web" \
+cargo run --locked -p spock-cli -- dev demo
```
-It builds the two Rust launchers, starts the requested Spock authority on port
-4000, waits for it to become ready, and opens the requested Uhura project
-through its read-only Editor on . The Editor's Play
-button enters the live prototype at `/play` without starting another process.
-`--spock-port` and `--uhura-port` override those defaults; the project's
-provider configuration must address the same Spock port. `Ctrl-C` stops both
-runtimes. Contributor frontend tooling in Spock and Uhura uses the same Node 24
-LTS pin from their respective `.nvmrc` files and pnpm 10.11.0; the runner uses
-them to build Uhura's web application before launch, but neither running server
-depends on a Node process.
+`build-wasm.sh` reports the lockfile-exact `wasm-bindgen-cli` install command
+when that tool is missing. The two asset overrides are a pair: setting only one
+is rejected, so a source host cannot accidentally combine incompatible web and
+Wasm generations. A distributed `spock` finds the sidecar beside its installed
+executable, verifies the executable-bound manifest identity and its file
+inventory, and needs neither override nor a Node process at runtime. The paired
+overrides are an explicit unanchored source/test trust boundary.
+
+The historical `scripts/spock-uhura.sh` two-process runner remains a transition
+and comparison oracle for examples whose backend and client still live in
+separate roots. It is not the canonical framework topology; `spock start` and
+`spock dev` own one project, listener, origin, and lifecycle.
## Repository Layout
-- `examples/` contains product requirements and current-valid Spock examples.
-- `docs/rfd/` contains discussion drafts and proposal-only language ideas.
-- `npm/` contains package metadata for npm name reservation.
-- `scripts/` contains umbrella composition tooling that keeps Spock and Uhura
- independently buildable.
-- `uhura/` is the Uhura client language (git submodule of
- [gridaco/uhura](https://github.com/gridaco/uhura); not yet wired into the
- build).
+- `crates/spock-lang/` parses and checks the Spock language and contract IR.
+- `crates/spock-runtime/` materializes and serves one authority backend.
+- `crates/spock-project/` owns `spock.toml`, discovery, and project validation.
+- `crates/spock-host/` coordinates combined generations, routes, and assets.
+- `crates/spock-cli/` exposes framework, project, and language commands as the
+ single `spock` binary.
+- `npm/` is the real four-platform distribution package and shared sidecar.
+- `uhura/` is the wired Uhura client-language submodule with its own workspace.
+- `scripts/` retains transition and comparison tooling, not a second canonical
+ runtime topology.
## References and prior work
@@ -698,8 +783,9 @@ complete mediation, information hiding, and the rule of least power.
## Status
-Spock is currently a design-stage proposal. There is no compiler, runtime, or
-stable specification yet.
+Spock is an early prototype with a working compiler, embedded runtime,
+standalone language server, and combined framework host. Its language and host
+protocols remain pre-1.0 and may change; it is for prototyping, not production.
The older, more ambitious draft has been moved to
`docs/rfd/0000-vision.spock`. It is a sketch of possible direction, not the v0
diff --git a/crates/spock-cli/Cargo.toml b/crates/spock-cli/Cargo.toml
index 18c1ff9..33b5432 100644
--- a/crates/spock-cli/Cargo.toml
+++ b/crates/spock-cli/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "spock-cli"
-description = "The spock command: check, build, run"
+description = "The Spock framework, project, and language command"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
@@ -14,11 +14,25 @@ path = "src/main.rs"
[dependencies]
spock-lang = { path = "../spock-lang" }
spock-runtime = { path = "../spock-runtime" }
+spock-project = { path = "../spock-project" }
+spock-host = { path = "../spock-host" }
serde_json.workspace = true
clap.workspace = true
anyhow.workspace = true
tokio.workspace = true
+thiserror.workspace = true
+
+[target.'cfg(unix)'.dependencies]
+rustix = { version = "1.1", features = ["fs"] }
+
+[target.'cfg(windows)'.dependencies]
+cap-fs-ext = "4.0.2"
+cap-std = "4.0.2"
+fs_at = "0.2.1"
+same-file.workspace = true
+windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem", "Wdk_Storage_FileSystem"] }
[dev-dependencies]
assert_cmd.workspace = true
predicates.workspace = true
+tempfile.workspace = true
diff --git a/crates/spock-cli/src/lib.rs b/crates/spock-cli/src/lib.rs
new file mode 100644
index 0000000..d5248f6
--- /dev/null
+++ b/crates/spock-cli/src/lib.rs
@@ -0,0 +1,491 @@
+#![forbid(unsafe_code)]
+
+//! Reusable implementation of Spock's project and standalone-language commands.
+//!
+//! This crate deliberately keeps argument parsing and terminal presentation in
+//! the `spock` binary. It owns the command-layer workflows for discovering,
+//! checking, creating, and adopting framework projects, while retaining the
+//! language-level escape hatches that load one `.spock` file, derive
+//! build/codegen artifacts, or prepare the historical standalone server.
+//! Callers can reuse those workflows without going through Clap or spawning a
+//! child process; runtime generation and HTTP hosting remain in `spock-host`.
+
+mod project_commands;
+mod write_plan;
+
+pub use project_commands::{
+ check_target, create_project, init_project, resolve_project_for_serve, CheckTargetError,
+ CheckTargetSummary, NewProjectNameError, ProjectWriteError, ProjectWriteOperation,
+ ProjectWriteSummary, ResolveProjectForServeError,
+};
+
+pub use write_plan::{
+ ApplyError, ApplyStage, ApplySummary, CreatedPathKind, RollbackReport, RollbackResidual,
+};
+
+use std::fmt;
+use std::future::Future;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::pin::Pin;
+use std::sync::Arc;
+
+use spock_lang::diag::Diagnostic;
+use spock_lang::ir::Contract;
+
+/// A source file and the checked contract derived from its exact contents.
+#[derive(Debug)]
+pub struct FileProgram {
+ /// The caller's spelling, retained for byte-compatible diagnostics.
+ path: PathBuf,
+ /// The path used for I/O and relative `file(...)` seed assets.
+ read_path: PathBuf,
+ source: String,
+ contract: Contract,
+}
+
+impl FileProgram {
+ /// Read and compile one `.spock` source file.
+ pub fn load(path: impl AsRef) -> Result {
+ let path = path.as_ref();
+ Self::load_from(path, path)
+ }
+
+ /// Load a caller-spelled path as though the process were running in `cwd`.
+ ///
+ /// Project target resolution canonicalizes directories, but standalone
+ /// file mode must not canonicalize the final `.spock` component: doing so
+ /// changes both rendered diagnostics and the directory used by seed
+ /// `file(...)` references when the source itself is a symlink.
+ pub(crate) fn load_from_cwd(path: &Path, cwd: &Path) -> Result {
+ let read_path = if path.is_absolute() {
+ path.to_path_buf()
+ } else {
+ cwd.join(path)
+ };
+ Self::load_from(path, &read_path)
+ }
+
+ fn load_from(display_path: &Path, read_path: &Path) -> Result {
+ let path = display_path.to_path_buf();
+ let read_path = read_path.to_path_buf();
+ let source =
+ std::fs::read_to_string(&read_path).map_err(|error| ProgramLoadError::Read {
+ path: path.clone(),
+ error,
+ })?;
+ let contract =
+ spock_lang::compile(&source).map_err(|diagnostics| ProgramLoadError::Diagnostics {
+ path: path.clone(),
+ source: source.clone(),
+ diagnostics,
+ })?;
+ Ok(Self {
+ path,
+ read_path,
+ source,
+ contract,
+ })
+ }
+
+ pub fn path(&self) -> &Path {
+ &self.path
+ }
+
+ pub fn source(&self) -> &str {
+ &self.source
+ }
+
+ pub fn source_dir(&self) -> PathBuf {
+ source_dir(&self.read_path)
+ }
+
+ pub fn contract(&self) -> &Contract {
+ &self.contract
+ }
+
+ pub fn into_contract(self) -> Contract {
+ self.contract
+ }
+}
+
+/// Failure to read or compile a file program.
+#[derive(Debug)]
+pub enum ProgramLoadError {
+ Read {
+ path: PathBuf,
+ error: std::io::Error,
+ },
+ Diagnostics {
+ path: PathBuf,
+ source: String,
+ diagnostics: Vec,
+ },
+}
+
+impl ProgramLoadError {
+ pub fn diagnostics(&self) -> Option<&[Diagnostic]> {
+ match self {
+ Self::Diagnostics { diagnostics, .. } => Some(diagnostics),
+ Self::Read { .. } => None,
+ }
+ }
+}
+
+impl fmt::Display for ProgramLoadError {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self {
+ Self::Read { path, error } => {
+ write!(f, "error: could not read {}: {error}", path.display())
+ }
+ Self::Diagnostics {
+ path,
+ source,
+ diagnostics,
+ } => {
+ let display_path = path.display().to_string();
+ for diagnostic in diagnostics {
+ writeln!(f, "{}", diagnostic.render(source, &display_path))?;
+ }
+ write!(
+ f,
+ "error: {} diagnostic(s), contract not produced",
+ diagnostics.len()
+ )
+ }
+ }
+ }
+}
+
+impl std::error::Error for ProgramLoadError {
+ fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+ match self {
+ Self::Read { error, .. } => Some(error),
+ Self::Diagnostics { .. } => None,
+ }
+ }
+}
+
+/// The directory a `.spock` file lives in: the root for seed `file("...")`
+/// assets. A path with no parent retains the historical empty, cwd-relative
+/// base directory.
+pub fn source_dir(file: impl AsRef) -> PathBuf {
+ file.as_ref()
+ .parent()
+ .map(Path::to_path_buf)
+ .unwrap_or_default()
+}
+
+/// Successful result of the full `check` load proof.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct CheckSummary {
+ pub tables: usize,
+ pub records: usize,
+ pub functions: usize,
+ pub unchecked_escapes: usize,
+ pub seed_rows: usize,
+}
+
+impl fmt::Display for CheckSummary {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ let functions = if self.functions == 0 {
+ "0 fn(s)".to_string()
+ } else {
+ format!(
+ "{} fn(s) ({} unchecked escapes)",
+ self.functions, self.unchecked_escapes
+ )
+ };
+ write!(
+ f,
+ "ok: {} table(s), {} record(s), {functions}, {} seed row(s)",
+ self.tables, self.records, self.seed_rows
+ )
+ }
+}
+
+/// Materialize in memory, validate function bodies and checks, prove defaults,
+/// and replay seed data: everything `spock run` would reject before serving.
+pub fn full_load_check(
+ contract: &Contract,
+ base_dir: impl AsRef,
+) -> anyhow::Result {
+ spock_runtime::engine::open(contract, None, Some(base_dir.as_ref()))?;
+ Ok(CheckSummary {
+ tables: contract.tables.len(),
+ records: contract.records.len(),
+ functions: contract.fns.len(),
+ unchecked_escapes: contract.fns.iter().map(|function| function.sql.len()).sum(),
+ seed_rows: contract.seed.len(),
+ })
+}
+
+/// Pretty JSON emitted by `spock build`.
+pub fn build_artifact(contract: &Contract) -> String {
+ serde_json::to_string_pretty(contract).expect("contract serializes")
+}
+
+/// A derived `spock gen` artifact.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum GenerationTarget {
+ Types,
+ GraphqlSchema,
+}
+
+pub fn generate_artifact(contract: &Contract, target: GenerationTarget) -> anyhow::Result {
+ match target {
+ GenerationTarget::Types => {
+ spock_lang::typescript::typescript(contract).map_err(anyhow::Error::from)
+ }
+ GenerationTarget::GraphqlSchema => graphql_sdl(contract),
+ }
+}
+
+/// Derive the runtime's GraphQL SDL without letting seed-data failures gate a
+/// data-independent artifact.
+fn graphql_sdl(contract: &Contract) -> anyhow::Result {
+ let mut contract = contract.clone();
+ contract.seed.clear();
+ let conn = spock_runtime::engine::open(&contract, None, None)?;
+ let app = Arc::new(spock_runtime::App::new(contract, conn));
+ Ok(spock_runtime::graphql::schema(app)?.sdl())
+}
+
+/// Counts and capabilities reported when a standalone run has materialized.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct StandaloneRunSummary {
+ pub tables: usize,
+ pub functions: usize,
+ pub seed_rows: usize,
+ pub storage: bool,
+}
+
+impl fmt::Display for StandaloneRunSummary {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(
+ f,
+ "spock v0 — contract loaded: {} table(s), {} fn(s), {} seed row(s) replayed",
+ self.tables, self.functions, self.seed_rows
+ )
+ }
+}
+
+/// A fully materialized historical standalone Spock server.
+///
+/// Construction is independent of Clap and terminal output. The app accessor
+/// also lets an embedding host reuse the exact runtime state without binding a
+/// second listener.
+pub struct StandaloneRun {
+ app: Arc,
+ summary: StandaloneRunSummary,
+ // Declared last so the database-backed app is dropped before its
+ // process-lifetime advisory lock is released.
+ _named_state_lock: Option,
+}
+
+impl StandaloneRun {
+ pub fn construct(
+ contract: Contract,
+ database_path: Option<&Path>,
+ base_dir: impl AsRef,
+ ) -> anyhow::Result {
+ // `engine::open` deliberately deletes an existing database, WAL, and
+ // SHM before reconstructing from seed. Acquire the shared framework
+ // lock first so a second standalone/framework process can never race
+ // that destructive boundary.
+ let named_state_lock = database_path
+ .map(spock_host::NamedStateLock::acquire)
+ .transpose()?;
+ let resolved_database_path = named_state_lock
+ .as_ref()
+ .map(spock_host::NamedStateLock::resolved_database_path);
+ let conn = spock_runtime::engine::open(
+ &contract,
+ resolved_database_path,
+ Some(base_dir.as_ref()),
+ )?;
+ let summary = StandaloneRunSummary {
+ tables: contract.tables.len(),
+ functions: contract.fns.len(),
+ seed_rows: contract.seed.len(),
+ storage: spock_runtime::storage::storage_active(&contract),
+ };
+ Ok(Self {
+ app: Arc::new(spock_runtime::App::new(contract, conn)),
+ summary,
+ _named_state_lock: named_state_lock,
+ })
+ }
+
+ pub fn app(&self) -> Arc {
+ Arc::clone(&self.app)
+ }
+
+ pub fn summary(&self) -> StandaloneRunSummary {
+ self.summary
+ }
+
+ /// Bind the historical loopback listener and serve until an interactive
+ /// process-shutdown signal or a server failure. `on_listening` runs after
+ /// a successful bind so the binary can retain its exact presentation
+ /// without coupling it here.
+ pub fn serve_until_ctrl_c(self, port: u16, on_listening: impl FnOnce()) -> anyhow::Result<()> {
+ let runtime = tokio::runtime::Runtime::new()?;
+ let shutdown = {
+ let _runtime_guard = runtime.enter();
+ install_standalone_shutdown_signal()?
+ };
+ runtime.block_on(async move {
+ let listener = tokio::net::TcpListener::bind(("127.0.0.1", port)).await?;
+ on_listening();
+ tokio::select! {
+ result = spock_runtime::http::serve(self.app, listener) => result?,
+ result = shutdown => result?,
+ }
+ Ok::<(), anyhow::Error>(())
+ })
+ }
+}
+
+type StandaloneShutdownSignal = Pin> + Send>>;
+
+#[cfg(unix)]
+fn install_standalone_shutdown_signal() -> io::Result {
+ use tokio::signal::unix::{signal, SignalKind};
+
+ let mut interrupt = signal(SignalKind::interrupt())?;
+ let mut terminate = signal(SignalKind::terminate())?;
+ Ok(Box::pin(async move {
+ tokio::select! {
+ received = interrupt.recv() => require_standalone_signal(received, "SIGINT"),
+ received = terminate.recv() => require_standalone_signal(received, "SIGTERM"),
+ }
+ }))
+}
+
+#[cfg(windows)]
+fn install_standalone_shutdown_signal() -> io::Result {
+ use tokio::signal::windows::{ctrl_break, ctrl_c, ctrl_close};
+
+ let mut interrupt = ctrl_c()?;
+ let mut break_signal = ctrl_break()?;
+ let mut close = ctrl_close()?;
+ Ok(Box::pin(async move {
+ tokio::select! {
+ received = interrupt.recv() => require_standalone_signal(received, "Ctrl-C"),
+ received = break_signal.recv() => require_standalone_signal(received, "Ctrl-Break"),
+ received = close.recv() => require_standalone_signal(received, "console close"),
+ }
+ }))
+}
+
+#[cfg(not(any(unix, windows)))]
+fn install_standalone_shutdown_signal() -> io::Result {
+ Ok(Box::pin(tokio::signal::ctrl_c()))
+}
+
+#[cfg(any(unix, windows))]
+fn require_standalone_signal(received: Option<()>, name: &str) -> io::Result<()> {
+ received.ok_or_else(|| {
+ io::Error::new(
+ io::ErrorKind::BrokenPipe,
+ format!("{name} signal stream closed before delivering a signal"),
+ )
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn load_error_owns_stably_rendered_diagnostics() {
+ let path = std::env::temp_dir().join(format!(
+ "spock-cli-library-diagnostic-{}.spock",
+ std::process::id()
+ ));
+ std::fs::write(&path, "table a { x: nope }").expect("write source");
+
+ let error = FileProgram::load(&path).expect_err("source must fail checking");
+ let rendered = error.to_string();
+ assert!(rendered.contains("error[E003]"), "{rendered}");
+ assert!(rendered.contains("error[E005]"), "{rendered}");
+ assert!(rendered.ends_with("error: 2 diagnostic(s), contract not produced"));
+
+ let _ = std::fs::remove_file(path);
+ }
+
+ #[test]
+ fn full_load_summary_and_build_artifact_are_reusable() {
+ let contract = spock_lang::compile(
+ "table user { key id: uuid = auto\n username: text unique }\n\
+ seed { user { username: \"maya\" } }",
+ )
+ .expect("contract");
+
+ let summary = full_load_check(&contract, "").expect("full load proof");
+ assert_eq!(
+ summary.to_string(),
+ "ok: 1 table(s), 0 record(s), 0 fn(s), 1 seed row(s)"
+ );
+ let artifact: serde_json::Value =
+ serde_json::from_str(&build_artifact(&contract)).expect("contract JSON");
+ assert_eq!(artifact["tables"][0]["name"], "user");
+ }
+
+ #[test]
+ fn generation_and_standalone_construction_are_library_operations() {
+ let contract =
+ spock_lang::compile("table user { key id: uuid = auto\n username: text unique }")
+ .expect("contract");
+
+ let types = generate_artifact(&contract, GenerationTarget::Types).expect("types");
+ assert!(types.contains("export interface user {"), "{types}");
+ let schema = generate_artifact(&contract, GenerationTarget::GraphqlSchema).expect("SDL");
+ assert!(schema.contains("type Query"), "{schema}");
+ assert!(schema.contains("user("), "{schema}");
+
+ let run = StandaloneRun::construct(contract, None, "").expect("standalone run");
+ assert_eq!(
+ run.summary(),
+ StandaloneRunSummary {
+ tables: 1,
+ functions: 0,
+ seed_rows: 0,
+ storage: false,
+ }
+ );
+ assert_eq!(run.app().contract.tables[0].name, "user");
+ }
+
+ #[test]
+ fn standalone_named_database_is_locked_before_reset_for_the_run_lifetime() {
+ let temporary = tempfile::tempdir().unwrap();
+ let database = temporary.path().join("shared.sqlite");
+ let sentinel = b"another process owns these bytes";
+ std::fs::write(&database, sentinel).unwrap();
+ let external_lock = spock_host::NamedStateLock::acquire(&database).unwrap();
+ let contract =
+ spock_lang::compile("table user { key id: uuid = auto\n username: text unique }")
+ .unwrap();
+
+ let blocked = StandaloneRun::construct(contract.clone(), Some(&database), "")
+ .err()
+ .expect("a live framework lock must block standalone reset");
+ assert!(blocked.to_string().contains("already owned"), "{blocked}");
+ assert_eq!(std::fs::read(&database).unwrap(), sentinel);
+
+ drop(external_lock);
+ let run = StandaloneRun::construct(contract, Some(&database), "").unwrap();
+ let contended = spock_host::NamedStateLock::acquire(&database)
+ .expect_err("standalone run must retain the lock");
+ assert!(
+ contended.to_string().contains("already owned"),
+ "{contended}"
+ );
+
+ drop(run);
+ let released = spock_host::NamedStateLock::acquire(&database).unwrap();
+ drop(released);
+ }
+}
diff --git a/crates/spock-cli/src/main.rs b/crates/spock-cli/src/main.rs
index dd1f911..1d75958 100644
--- a/crates/spock-cli/src/main.rs
+++ b/crates/spock-cli/src/main.rs
@@ -1,16 +1,27 @@
-//! The `spock` command: `check` (diagnostics), `build` (emit the contract),
-//! `gen` (derived artifacts — TypeScript types, GraphQL SDL; RFD 0010),
-//! `run` (materialize + serve the HTTP protocol). docs/spec/v0.md.
+//! The public `spock` command: framework projects plus the retained standalone
+//! language-file tools.
+use std::collections::BTreeSet;
+use std::future::Future;
+use std::io::{self, Write};
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::path::{Path, PathBuf};
+use std::pin::Pin;
use std::process::ExitCode;
-use std::sync::Arc;
+use std::sync::{Arc, Mutex};
use clap::{Parser, Subcommand};
-use spock_lang::ir::Contract;
+use spock_cli::{
+ CheckTargetError, CheckTargetSummary, FileProgram, GenerationTarget, StandaloneRun,
+};
+use spock_host::{HostMode, HostNotice, HostNoticeSink, ProjectCheckFailure, ServeOptions};
#[derive(Parser)]
-#[command(name = "spock", version, about = "The Spock v0 toolchain")]
+#[command(
+ name = "spock",
+ version,
+ about = "The Spock framework and language toolchain"
+)]
struct Cli {
#[command(subcommand)]
command: Command,
@@ -18,15 +29,51 @@ struct Cli {
#[derive(Subcommand)]
enum Command {
- /// Parse and check a program; print diagnostics.
- Check { file: PathBuf },
- /// Compile a program to its contract (JSON on stdout, or -o FILE).
+ /// Check a framework project, or an explicit standalone .spock file.
+ Check {
+ #[arg(value_name = "PATH")]
+ target: Option,
+ },
+ /// Create a new framework project.
+ New {
+ #[arg(value_name = "NAME")]
+ name: String,
+ /// Create the required Spock backend without an Uhura client.
+ #[arg(long)]
+ backend_only: bool,
+ },
+ /// Adopt an existing directory as a framework project.
+ Init {
+ #[arg(value_name = "PATH")]
+ target: Option,
+ },
+ /// Check once and serve one fixed framework generation.
+ Start {
+ #[arg(value_name = "PATH")]
+ target: Option,
+ #[arg(long, default_value_t = 4000)]
+ port: u16,
+ /// Disposable database file, reconstructed from seed on process start.
+ #[arg(long)]
+ db: Option,
+ },
+ /// Serve a framework project with live client publication.
+ Dev {
+ #[arg(value_name = "PATH")]
+ target: Option,
+ #[arg(long, default_value_t = 4000)]
+ port: u16,
+ /// Disposable database file, reconstructed from seed on process start.
+ #[arg(long)]
+ db: Option,
+ },
+ /// Compile a standalone program to its contract (JSON on stdout, or -o FILE).
Build {
file: PathBuf,
#[arg(short, long)]
out: Option,
},
- /// Compile, materialize the database, replay the seed, and serve HTTP.
+ /// Compile, materialize, seed, and serve one standalone .spock program.
Run {
file: PathBuf,
#[arg(long, default_value_t = 4000)]
@@ -35,7 +82,7 @@ enum Command {
#[arg(long)]
db: Option,
},
- /// Generate derived artifacts from a program (RFD 0010).
+ /// Generate derived artifacts from a standalone program (RFD 0010).
Gen {
#[command(subcommand)]
target: GenTarget,
@@ -59,50 +106,68 @@ enum GenTarget {
}
fn main() -> ExitCode {
- match Cli::parse().command {
- Command::Check { file } => {
- let Some(contract) = load(&file) else {
+ execute(Cli::parse().command)
+}
+
+fn execute(command: Command) -> ExitCode {
+ match command {
+ Command::Check { target } => {
+ let Some(cwd) = current_dir_or_report() else {
return ExitCode::FAILURE;
};
- // The full load proof (RFD 0013): materialize the schema in
- // memory, validate every fn body and inlined check, prove
- // defaults against their checks, and replay the seed — so
- // anything `spock run` would reject at load surfaces here,
- // without starting a server.
- if let Err(e) = spock_runtime::engine::open(&contract, None, Some(&source_dir(&file))) {
- eprintln!("error: {e}");
+ match spock_cli::check_target(target.as_deref(), &cwd) {
+ Ok(summary) => {
+ println!("{summary}");
+ if let CheckTargetSummary::Project { report, .. } = summary {
+ print_project_warnings(report.warnings);
+ }
+ ExitCode::SUCCESS
+ }
+ Err(error) => report_check_error(error),
+ }
+ }
+ Command::New { name, backend_only } => {
+ let Some(cwd) = current_dir_or_report() else {
return ExitCode::FAILURE;
+ };
+ match spock_cli::create_project(&cwd, &name, backend_only) {
+ Ok(summary) => {
+ println!("{summary}");
+ println!("next: run `spock dev` from the project directory above");
+ ExitCode::SUCCESS
+ }
+ Err(error) => report_error(error),
}
- // every v0 fn statement is an SQL escape — the unchecked count
- // is the ledger (RFD 0011 §4), trending to zero as native
- // bodies arrive
- let fns = if contract.fns.is_empty() {
- "0 fn(s)".to_string()
- } else {
- format!(
- "{} fn(s) ({} unchecked escapes)",
- contract.fns.len(),
- contract.fns.iter().map(|f| f.sql.len()).sum::()
- )
+ }
+ Command::Init { target } => {
+ let Some(cwd) = current_dir_or_report() else {
+ return ExitCode::FAILURE;
};
- println!(
- "ok: {} table(s), {} record(s), {fns}, {} seed row(s)",
- contract.tables.len(),
- contract.records.len(),
- contract.seed.len()
- );
- ExitCode::SUCCESS
+ match spock_cli::init_project(target.as_deref(), &cwd) {
+ Ok(summary) => {
+ println!("{summary}");
+ println!("next: run `spock dev` from the project directory above");
+ ExitCode::SUCCESS
+ }
+ Err(error) => report_error(error),
+ }
+ }
+ Command::Start { target, port, db } => {
+ serve_framework(target.as_deref(), port, db, HostMode::Start)
+ }
+ Command::Dev { target, port, db } => {
+ serve_framework(target.as_deref(), port, db, HostMode::Dev)
}
Command::Build { file, out } => {
- let Some(contract) = load(&file) else {
+ let Some(program) = load_or_report(&file) else {
return ExitCode::FAILURE;
};
- let json = serde_json::to_string_pretty(&contract).expect("contract serializes");
+ let json = spock_cli::build_artifact(program.contract());
match out {
None => println!("{json}"),
Some(path) => {
- if let Err(e) = std::fs::write(&path, json) {
- eprintln!("error: could not write {}: {e}", path.display());
+ if let Err(error) = std::fs::write(&path, json) {
+ eprintln!("error: could not write {}: {error}", path.display());
return ExitCode::FAILURE;
}
println!("wrote {}", path.display());
@@ -111,15 +176,20 @@ fn main() -> ExitCode {
ExitCode::SUCCESS
}
Command::Run { file, port, db } => {
- let Some(contract) = load(&file) else {
+ let Some(program) = load_or_report(&file) else {
return ExitCode::FAILURE;
};
- match run(contract, port, db, source_dir(&file)) {
+ let base_dir = program.source_dir();
+ let run = StandaloneRun::construct(program.into_contract(), db.as_deref(), base_dir);
+ match run.and_then(|run| {
+ let summary = run.summary();
+ println!("{summary}");
+ run.serve_until_ctrl_c(port, move || {
+ print_standalone_listening(port, summary.storage)
+ })
+ }) {
Ok(()) => ExitCode::SUCCESS,
- Err(e) => {
- eprintln!("error: {e}");
- ExitCode::FAILURE
- }
+ Err(error) => report_error(error),
}
}
Command::Gen { target } => {
@@ -128,37 +198,195 @@ fn main() -> ExitCode {
(file.clone(), out.clone())
}
};
- let Some(contract) = load(&file) else {
+ let Some(program) = load_or_report(&file) else {
return ExitCode::FAILURE;
};
let artifact = match target {
GenTarget::Types { .. } => {
- spock_lang::typescript::typescript(&contract).map_err(anyhow::Error::from)
+ spock_cli::generate_artifact(program.contract(), GenerationTarget::Types)
}
- GenTarget::GraphqlSchema { .. } => graphql_sdl(contract),
+ GenTarget::GraphqlSchema { .. } => spock_cli::generate_artifact(
+ program.contract(),
+ GenerationTarget::GraphqlSchema,
+ ),
};
match artifact {
Ok(content) => emit(out, content),
- Err(e) => {
- eprintln!("error: {e}");
- ExitCode::FAILURE
- }
+ Err(error) => report_error(error),
}
}
}
}
-/// The SDL of the schema the runtime would serve — derived through the
-/// same builder as `run`, so it cannot drift. The in-memory engine exists
-/// only because the builder wants a full `App`; no resolver ever runs,
-/// and the seed is dropped first: the SDL is a pure function of the
-/// tables, so a data problem (say, a seed unique conflict) must not gate
-/// a data-independent artifact.
-fn graphql_sdl(mut contract: Contract) -> anyhow::Result {
- contract.seed.clear();
- let conn = spock_runtime::engine::open(&contract, None, None)?;
- let app = Arc::new(spock_runtime::App::new(contract, conn));
- Ok(spock_runtime::graphql::schema(app)?.sdl())
+fn serve_framework(
+ target: Option<&Path>,
+ port: u16,
+ database_path: Option,
+ mode: HostMode,
+) -> ExitCode {
+ let Some(cwd) = current_dir_or_report() else {
+ return ExitCode::FAILURE;
+ };
+ let layout = match spock_cli::resolve_project_for_serve(target, &cwd) {
+ Ok(layout) => layout,
+ Err(error) => return report_error(error),
+ };
+ let runtime = match tokio::runtime::Builder::new_multi_thread()
+ .enable_all()
+ .build()
+ {
+ Ok(runtime) => runtime,
+ Err(error) => return report_error(error),
+ };
+ let options = ServeOptions {
+ bind: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), port),
+ database_path,
+ ..ServeOptions::default()
+ };
+ let notices = HostNoticeSink::new(print_framework_notice);
+ let shutdown_signal = {
+ let _runtime_guard = runtime.enter();
+ match install_framework_shutdown_signal() {
+ Ok(signal) => signal,
+ Err(error) => {
+ return report_error(format!(
+ "could not install shutdown signal handler: {error}"
+ ))
+ }
+ }
+ };
+ let shutdown_error = Arc::new(Mutex::new(None));
+ let shutdown_error_for_signal = Arc::clone(&shutdown_error);
+ let shutdown = async move {
+ if let Err(error) = shutdown_signal.await {
+ *shutdown_error_for_signal
+ .lock()
+ .expect("shutdown error lock") = Some(error);
+ }
+ };
+ let result = runtime.block_on(spock_host::serve_project(
+ layout, mode, options, notices, shutdown,
+ ));
+ if let Some(error) = shutdown_error.lock().expect("shutdown error lock").take() {
+ return report_error(format!("shutdown signal handling failed: {error}"));
+ }
+ match result {
+ Ok(_) => ExitCode::SUCCESS,
+ Err(error) => report_error(error),
+ }
+}
+
+type ShutdownSignal = Pin> + Send>>;
+
+#[cfg(unix)]
+fn install_framework_shutdown_signal() -> io::Result {
+ use tokio::signal::unix::{signal, SignalKind};
+
+ let mut interrupt = signal(SignalKind::interrupt())?;
+ let mut terminate = signal(SignalKind::terminate())?;
+ Ok(Box::pin(async move {
+ tokio::select! {
+ received = interrupt.recv() => require_signal(received, "SIGINT"),
+ received = terminate.recv() => require_signal(received, "SIGTERM"),
+ }
+ }))
+}
+
+#[cfg(windows)]
+fn install_framework_shutdown_signal() -> io::Result {
+ use tokio::signal::windows::{ctrl_break, ctrl_c, ctrl_close};
+
+ let mut interrupt = ctrl_c()?;
+ let mut break_signal = ctrl_break()?;
+ let mut close = ctrl_close()?;
+ Ok(Box::pin(async move {
+ tokio::select! {
+ received = interrupt.recv() => require_signal(received, "Ctrl-C"),
+ received = break_signal.recv() => require_signal(received, "Ctrl-Break"),
+ received = close.recv() => require_signal(received, "console close"),
+ }
+ }))
+}
+
+#[cfg(not(any(unix, windows)))]
+fn install_framework_shutdown_signal() -> io::Result {
+ Ok(Box::pin(tokio::signal::ctrl_c()))
+}
+
+#[cfg(any(unix, windows))]
+fn require_signal(received: Option<()>, name: &str) -> io::Result<()> {
+ received.ok_or_else(|| {
+ io::Error::new(
+ io::ErrorKind::BrokenPipe,
+ format!("{name} signal stream closed before delivering a signal"),
+ )
+ })
+}
+
+fn print_framework_notice(notice: HostNotice) {
+ match notice {
+ HostNotice::DevelopmentPolicy => eprintln!(
+ "warning: backend inputs (including referenced seed assets) and spock.toml topology changes are observed but not applied; restart `spock dev` to reconstruct backend state from seed"
+ ),
+ HostNotice::Listening {
+ address,
+ client_configured,
+ } => {
+ println!("listening on http://{address}");
+ if client_configured {
+ println!(" GET / Uhura Editor");
+ println!(" GET /play Uhura Play");
+ }
+ println!(" GET /~studio Spock Studio");
+ println!(" GET /~contract active Spock contract");
+ println!(" GET /~project/status framework generation status");
+ println!(" GET /~health aggregate readiness");
+ println!(" * /rest/v1/* authority REST and RPC");
+ println!(" POST /graphql/v1 GraphQL when the contract is non-empty");
+ }
+ HostNotice::ClientBuilding { observed_revision } => {
+ println!("client: building revision {observed_revision}");
+ }
+ HostNotice::ClientPublished {
+ observed_revision,
+ source_revision,
+ play_generation,
+ } => println!(
+ "client: published revision {observed_revision} (source {source_revision}, Play generation {play_generation})"
+ ),
+ HostNotice::ClientRejected {
+ observed_revision,
+ diagnostics,
+ serving_last_good,
+ } => {
+ eprintln!(
+ "client: rejected revision {observed_revision}; serving_last_good={serving_last_good}"
+ );
+ for diagnostic in diagnostics {
+ eprintln!(" {diagnostic}");
+ }
+ }
+ HostNotice::BackendRestartRequired {
+ changed_inputs,
+ diagnostics,
+ } => {
+ eprintln!(
+ "backend: restart required; active state remains pinned (changed: {})",
+ changed_inputs.join(", ")
+ );
+ for diagnostic in diagnostics {
+ eprintln!(" {diagnostic}");
+ }
+ }
+ HostNotice::BackendReverted => {
+ println!("backend: inputs match the active generation again");
+ }
+ HostNotice::ObserverError { message } => {
+ eprintln!("warning: development observer: {message}");
+ }
+ }
+ let _ = io::stdout().flush();
+ let _ = io::stderr().flush();
}
/// Print to stdout, or write to `-o FILE`.
@@ -169,8 +397,8 @@ fn emit(out: Option, content: String) -> ExitCode {
ExitCode::SUCCESS
}
Some(path) => {
- if let Err(e) = std::fs::write(&path, content) {
- eprintln!("error: could not write {}: {e}", path.display());
+ if let Err(error) = std::fs::write(&path, content) {
+ eprintln!("error: could not write {}: {error}", path.display());
return ExitCode::FAILURE;
}
println!("wrote {}", path.display());
@@ -179,71 +407,81 @@ fn emit(out: Option, content: String) -> ExitCode {
}
}
-/// The directory a `.spock` file lives in — the root for `file("...")` seed
-/// assets (RFD 0018). Empty (cwd-relative) when the path has no parent.
-fn source_dir(file: &Path) -> PathBuf {
- file.parent().map(|p| p.to_path_buf()).unwrap_or_default()
+fn current_dir_or_report() -> Option {
+ match std::env::current_dir() {
+ Ok(path) => Some(path),
+ Err(error) => {
+ eprintln!("error: could not resolve the working directory: {error}");
+ None
+ }
+ }
}
-/// Read, compile, and (on failure) render every diagnostic.
-fn load(path: &PathBuf) -> Option {
- let source = match std::fs::read_to_string(path) {
- Ok(s) => s,
- Err(e) => {
- eprintln!("error: could not read {}: {e}", path.display());
- return None;
- }
- };
- match spock_lang::compile(&source) {
- Ok(contract) => Some(contract),
- Err(diags) => {
- for diag in &diags {
- eprintln!("{}", diag.render(&source, &path.display().to_string()));
- }
- eprintln!(
- "error: {} diagnostic(s), contract not produced",
- diags.len()
- );
+/// Binary-only presentation adapter for the library's structured load error.
+fn load_or_report(path: &Path) -> Option {
+ match FileProgram::load(path) {
+ Ok(program) => Some(program),
+ Err(error) => {
+ eprintln!("{error}");
None
}
}
}
-fn run(
- contract: Contract,
- port: u16,
- db: Option,
- base_dir: PathBuf,
-) -> anyhow::Result<()> {
- let conn = spock_runtime::engine::open(&contract, db.as_deref(), Some(base_dir.as_path()))?;
- println!(
- "spock v0 — contract loaded: {} table(s), {} fn(s), {} seed row(s) replayed",
- contract.tables.len(),
- contract.fns.len(),
- contract.seed.len()
- );
-
- let app = Arc::new(spock_runtime::App::new(contract, conn));
- let storage = spock_runtime::storage::storage_active(&app.contract);
- let runtime = tokio::runtime::Runtime::new()?;
- runtime.block_on(async move {
- let listener = tokio::net::TcpListener::bind(("127.0.0.1", port)).await?;
- println!("listening on http://127.0.0.1:{port}");
- println!(" GET /~studio the developer console — browse, impersonate, run");
- println!(" GET /~contract the contract, as data");
- println!(" GET /rest/v1/{{table}} open reads (identity view)");
- println!(" POST /rest/v1/rpc/{{fn}} call a declared fn");
- println!(" POST /graphql/v1 GraphQL reads + writes (GraphiQL in the browser)");
- if storage {
- println!(" * /storage/v1/object upload + serve files (signed URLs)");
- }
- // `serve` owns the in-process orphan sweep for a storage contract
- // (RFD 0018 §1.6); the binary only decides when to stop.
- tokio::select! {
- result = spock_runtime::http::serve(app.clone(), listener) => result?,
- _ = tokio::signal::ctrl_c() => {}
+fn report_error(error: impl std::fmt::Display) -> ExitCode {
+ eprintln!("error: {error}");
+ ExitCode::FAILURE
+}
+
+fn report_check_error(error: CheckTargetError) -> ExitCode {
+ match error {
+ // These two preserve the historical standalone rendering, which
+ // already owns its `error:` prefix and source diagnostics.
+ CheckTargetError::FileLoad(error) => eprintln!("{error}"),
+ CheckTargetError::FileLoadProof { source, .. } => eprintln!("error: {source}"),
+ CheckTargetError::ProjectCheck(error) => report_project_check_failure(&error),
+ error => eprintln!("error: {error}"),
+ }
+ ExitCode::FAILURE
+}
+
+fn print_project_warnings(warnings: Vec) {
+ let mut seen = BTreeSet::new();
+ for warning in warnings {
+ if seen.insert(warning.clone()) {
+ eprintln!("warning: {warning}");
+ }
+ }
+}
+
+fn report_project_check_failure(error: &ProjectCheckFailure) {
+ let mut seen = BTreeSet::new();
+ let mut first = true;
+ for diagnostic in error.diagnostics() {
+ if !seen.insert(diagnostic.clone()) {
+ continue;
}
- Ok::<(), anyhow::Error>(())
- })?;
- Ok(())
+ let rendered = diagnostic.to_string();
+ if first {
+ eprintln!("error: {rendered}");
+ first = false;
+ } else {
+ eprintln!("{rendered}");
+ }
+ }
+ if first {
+ eprintln!("error: project check failed without diagnostics");
+ }
+}
+
+fn print_standalone_listening(port: u16, storage: bool) {
+ println!("listening on http://127.0.0.1:{port}");
+ println!(" GET /~studio the developer console — browse, impersonate, run");
+ println!(" GET /~contract the contract, as data");
+ println!(" GET /rest/v1/{{table}} open reads (identity view)");
+ println!(" POST /rest/v1/rpc/{{fn}} call a declared fn");
+ println!(" POST /graphql/v1 GraphQL reads + writes (GraphiQL in the browser)");
+ if storage {
+ println!(" * /storage/v1/object upload + serve files (signed URLs)");
+ }
}
diff --git a/crates/spock-cli/src/project_commands.rs b/crates/spock-cli/src/project_commands.rs
new file mode 100644
index 0000000..b2846cf
--- /dev/null
+++ b/crates/spock-cli/src/project_commands.rs
@@ -0,0 +1,635 @@
+//! Reusable command boundaries for framework-project operations.
+//!
+//! Target selection, checking, and filesystem mutation live here rather than
+//! in the Clap presentation layer. An explicit `.spock` target keeps the
+//! historical language-file check; every other accepted check target resolves
+//! to a validated framework project.
+
+use std::collections::BTreeSet;
+use std::fmt;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use spock_host::{ProjectCheckFailure, ProjectCheckReport};
+use spock_project::{
+ adoption_plan, load_project, minimal_uhura_client_template, parse_manifest, resolve_target,
+ scaffold_plan, Diagnostics, NormalizedRelativePath, ProjectInventory, ProjectLayout,
+ ProjectName, ResolvedTarget, MANIFEST_FILE,
+};
+use thiserror::Error;
+
+use crate::write_plan::{apply_prepared_write_plan, PreparedWriteRoot, PreparedWriteTarget};
+use crate::{full_load_check, ApplyError, CheckSummary, FileProgram, ProgramLoadError};
+
+/// A successful polymorphic `spock check` result.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum CheckTargetSummary {
+ /// The historical one-file language/runtime proof.
+ File {
+ path: PathBuf,
+ summary: CheckSummary,
+ },
+ /// A manifest, backend, client, and currently provable link check.
+ Project {
+ root: PathBuf,
+ project_name: String,
+ report: ProjectCheckReport,
+ },
+}
+
+impl CheckTargetSummary {
+ #[must_use]
+ pub fn path(&self) -> &Path {
+ match self {
+ Self::File { path, .. } => path,
+ Self::Project { root, .. } => root,
+ }
+ }
+}
+
+impl fmt::Display for CheckTargetSummary {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self {
+ Self::File { summary, .. } => summary.fmt(formatter),
+ Self::Project {
+ project_name,
+ report,
+ ..
+ } => {
+ write!(
+ formatter,
+ "ok: project `{project_name}` — {} table(s), {} record(s), {} fn(s), {} seed row(s)",
+ report.backend.tables,
+ report.backend.records,
+ report.backend.functions,
+ report.backend.seed_rows,
+ )?;
+ match &report.client {
+ Some(client) => write!(
+ formatter,
+ ", {} preview(s), {} replay-derived preview(s)",
+ client.preview_count, client.replay_derived_count,
+ )?,
+ None => formatter.write_str(", backend only")?,
+ }
+ write!(
+ formatter,
+ ", {} unchecked link(s), {} warning(s)",
+ report.unchecked_links,
+ report.warnings.len(),
+ )
+ }
+ }
+ }
+}
+
+/// Failure from polymorphic `spock check` target selection or checking.
+#[derive(Debug, Error)]
+pub enum CheckTargetError {
+ #[error(transparent)]
+ ProjectTopology(#[from] Diagnostics),
+ #[error(transparent)]
+ FileLoad(#[from] ProgramLoadError),
+ #[error("error: {source}")]
+ FileLoadProof {
+ path: PathBuf,
+ #[source]
+ source: anyhow::Error,
+ },
+ #[error(transparent)]
+ ProjectCheck(#[from] ProjectCheckFailure),
+}
+
+/// Select and fully check either an explicit `.spock` file or a project.
+///
+/// File mode deliberately calls the same [`FileProgram`] and
+/// [`full_load_check`] boundary used by the legacy CLI. In project mode the
+/// framework manifest is loaded first, then every configured subsystem is
+/// checked without binding a listener or touching named state.
+pub fn check_target(
+ target: Option<&Path>,
+ cwd: &Path,
+) -> Result {
+ if let Some(path) = target.filter(|path| has_spock_extension(path)) {
+ let program = FileProgram::load_from_cwd(path, cwd)?;
+ let summary =
+ full_load_check(program.contract(), program.source_dir()).map_err(|source| {
+ CheckTargetError::FileLoadProof {
+ path: path.to_path_buf(),
+ source,
+ }
+ })?;
+ return Ok(CheckTargetSummary::File {
+ path: path.to_path_buf(),
+ summary,
+ });
+ }
+
+ match resolve_target(target, cwd)? {
+ ResolvedTarget::SpockFile(path) => {
+ // `resolve_target` selects file mode only by the extension checked
+ // above. Keep this fallback defensive for future resolver modes.
+ let program = FileProgram::load(&path)?;
+ let summary =
+ full_load_check(program.contract(), program.source_dir()).map_err(|source| {
+ CheckTargetError::FileLoadProof {
+ path: path.clone(),
+ source,
+ }
+ })?;
+ Ok(CheckTargetSummary::File { path, summary })
+ }
+ ResolvedTarget::Project(root) => {
+ let layout = load_project(&root)?;
+ let project_name = layout.manifest.project().as_str().to_string();
+ let mut report = spock_host::check_project(&layout)?;
+ deduplicate_warnings(&mut report);
+ Ok(CheckTargetSummary::Project {
+ root: layout.root,
+ project_name,
+ report,
+ })
+ }
+ }
+}
+
+/// Failure while selecting a framework project for `start` or `dev`.
+#[derive(Debug, Error)]
+pub enum ResolveProjectForServeError {
+ #[error(transparent)]
+ ProjectTopology(#[from] Diagnostics),
+ #[error("`{}` selects standalone `.spock` file mode; run `spock run` with that file instead", path.display())]
+ StandaloneFile { path: PathBuf },
+}
+
+/// Resolve and validate a project target for a framework serving command.
+///
+/// `start` and `dev` never silently reinterpret a `.spock` file as a project;
+/// their error points at the retained standalone `spock run` escape hatch.
+pub fn resolve_project_for_serve(
+ target: Option<&Path>,
+ cwd: &Path,
+) -> Result {
+ if let Some(path) = target.filter(|path| has_spock_extension(path)) {
+ return Err(ResolveProjectForServeError::StandaloneFile {
+ path: path.to_path_buf(),
+ });
+ }
+
+ match resolve_target(target, cwd)? {
+ ResolvedTarget::Project(root) => Ok(load_project(&root)?),
+ ResolvedTarget::SpockFile(path) => {
+ Err(ResolveProjectForServeError::StandaloneFile { path })
+ }
+ }
+}
+
+fn has_spock_extension(path: &Path) -> bool {
+ path.extension().and_then(|extension| extension.to_str()) == Some("spock")
+}
+
+fn deduplicate_warnings(report: &mut ProjectCheckReport) {
+ let mut seen = BTreeSet::new();
+ report
+ .warnings
+ .retain(|warning| seen.insert(warning.clone()));
+}
+
+/// Whether a successful project write created a new root or adopted one.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ProjectWriteOperation {
+ New,
+ Init,
+}
+
+/// Exact, presentation-independent effects of `spock new` or `spock init`.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ProjectWriteSummary {
+ pub operation: ProjectWriteOperation,
+ pub root: PathBuf,
+ pub project_name: String,
+ pub includes_client: bool,
+ pub created_files: Vec,
+ pub created_directories: Vec,
+}
+
+impl fmt::Display for ProjectWriteSummary {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ let verb = match self.operation {
+ ProjectWriteOperation::New => "created",
+ ProjectWriteOperation::Init => "initialized",
+ };
+ let shape = if self.includes_client {
+ "full-stack"
+ } else {
+ "backend-only"
+ };
+ write!(
+ formatter,
+ "{verb} {shape} project `{}` at {}",
+ self.project_name,
+ self.root.display(),
+ )
+ }
+}
+
+/// A rejected `spock new NAME` before any path is created.
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+#[error("invalid project name `{name}`: {reason}; NAME must be one safe path component")]
+pub struct NewProjectNameError {
+ pub name: String,
+ pub reason: String,
+}
+
+/// Failure while planning or safely applying `spock new`/`spock init`.
+#[derive(Debug, Error)]
+pub enum ProjectWriteError {
+ #[error(transparent)]
+ InvalidName(#[from] NewProjectNameError),
+ #[error("could not resolve {role} `{}`: {source}", path.display())]
+ ResolveDirectory {
+ role: &'static str,
+ path: PathBuf,
+ #[source]
+ source: std::io::Error,
+ },
+ #[error("{role} `{}` is not a directory", path.display())]
+ NotDirectory { role: &'static str, path: PathBuf },
+ #[error(transparent)]
+ ProjectPlan(#[from] Diagnostics),
+ #[error(transparent)]
+ Apply(#[from] ApplyError),
+}
+
+/// Create the canonical project as a direct child of `cwd`.
+///
+/// Full stack is the default; `backend_only` is the explicit opt-out. The
+/// destination is preflighted as empty and then created with the race-safe
+/// new-destination policy.
+pub fn create_project(
+ cwd: &Path,
+ name: &str,
+ backend_only: bool,
+) -> Result {
+ validate_new_project_name(name)?;
+ let cwd = canonical_directory(cwd, "working directory")?;
+ let prepared_parent = prepare_write_root(&cwd, "working directory")?;
+ let destination = prepared_parent.path().join(name);
+ let client = (!backend_only).then(minimal_uhura_client_template);
+ let plan = scaffold_plan(&destination, name, client.as_ref())?;
+ let inventory = ProjectInventory::empty(destination.clone());
+ plan.preflight(&inventory)?;
+ apply_project_plan(
+ &plan,
+ PreparedWriteTarget::new_child(prepared_parent, name),
+ ProjectWriteOperation::New,
+ )
+}
+
+/// Adopt exactly `target`, or `cwd` when no target is supplied.
+///
+/// Unlike project discovery, initialization does not walk to a parent
+/// manifest: it inventories the selected directory itself and lets the pure
+/// adoption planner reject existing projects, ambiguity, and conflicts before
+/// the race-safe apply boundary runs.
+pub fn init_project(
+ target: Option<&Path>,
+ cwd: &Path,
+) -> Result {
+ let cwd = canonical_directory(cwd, "working directory")?;
+ let selected = match target {
+ Some(path) if path.is_absolute() => path.to_path_buf(),
+ Some(path) => cwd.join(path),
+ None => cwd,
+ };
+ let selected = canonical_directory(&selected, "adoption root")?;
+ let prepared_root = prepare_write_root(&selected, "adoption root")?;
+ let inventory = prepared_root.inventory()?;
+ prepared_root
+ .validate()
+ .map_err(|source| ProjectWriteError::ResolveDirectory {
+ role: "adoption root",
+ path: selected,
+ source,
+ })?;
+ let plan = adoption_plan(&inventory, None)?;
+ plan.preflight(&inventory)?;
+ apply_project_plan(
+ &plan,
+ PreparedWriteTarget::existing(prepared_root),
+ ProjectWriteOperation::Init,
+ )
+}
+
+fn validate_new_project_name(name: &str) -> Result<(), NewProjectNameError> {
+ ProjectName::parse(name).map_err(|reason| NewProjectNameError {
+ name: name.to_string(),
+ reason,
+ })?;
+
+ let path = NormalizedRelativePath::file(name).map_err(|error| NewProjectNameError {
+ name: name.to_string(),
+ reason: error.to_string(),
+ })?;
+ if !path.parent().is_project_root() {
+ return Err(NewProjectNameError {
+ name: name.to_string(),
+ reason: "nested paths are not allowed".to_string(),
+ });
+ }
+ Ok(())
+}
+
+fn canonical_directory(path: &Path, role: &'static str) -> Result {
+ let canonical =
+ fs::canonicalize(path).map_err(|source| ProjectWriteError::ResolveDirectory {
+ role,
+ path: path.to_path_buf(),
+ source,
+ })?;
+ if !canonical.is_dir() {
+ return Err(ProjectWriteError::NotDirectory {
+ role,
+ path: canonical,
+ });
+ }
+ Ok(canonical)
+}
+
+fn prepare_write_root(
+ path: &Path,
+ role: &'static str,
+) -> Result {
+ PreparedWriteRoot::open(path).map_err(|source| ProjectWriteError::ResolveDirectory {
+ role,
+ path: path.to_path_buf(),
+ source,
+ })
+}
+
+fn apply_project_plan(
+ plan: &spock_project::WritePlan,
+ target: PreparedWriteTarget,
+ operation: ProjectWriteOperation,
+) -> Result {
+ let manifest_write = plan
+ .write(MANIFEST_FILE)
+ .expect("project plans always include their manifest commit marker");
+ let manifest_source = std::str::from_utf8(&manifest_write.contents)
+ .expect("project planners emit a UTF-8 manifest");
+ let manifest = parse_manifest(manifest_source)?;
+ let project_name = manifest.project().as_str().to_string();
+ let includes_client = manifest.client().is_some();
+
+ let applied = apply_prepared_write_plan(plan, target)?;
+ Ok(ProjectWriteSummary {
+ operation,
+ root: applied.root().to_path_buf(),
+ project_name,
+ includes_client,
+ created_files: applied.created_files().to_vec(),
+ created_directories: applied.created_directories().to_vec(),
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::io;
+ use std::sync::atomic::{AtomicU64, Ordering};
+
+ static NEXT_TEST_DIRECTORY: AtomicU64 = AtomicU64::new(0);
+
+ struct TestDirectory(PathBuf);
+
+ impl TestDirectory {
+ fn new() -> Self {
+ loop {
+ let id = NEXT_TEST_DIRECTORY.fetch_add(1, Ordering::Relaxed);
+ let path = std::env::temp_dir().join(format!(
+ "spock-project-commands-{}-{id}",
+ std::process::id()
+ ));
+ match fs::create_dir(&path) {
+ Ok(()) => return Self(path),
+ Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue,
+ Err(error) => panic!("could not create test directory: {error}"),
+ }
+ }
+ }
+
+ fn path(&self) -> &Path {
+ &self.0
+ }
+ }
+
+ impl Drop for TestDirectory {
+ fn drop(&mut self) {
+ let _ = fs::remove_dir_all(&self.0);
+ }
+ }
+
+ #[test]
+ fn explicit_spock_check_keeps_the_file_load_proof_and_summary() {
+ let temporary = TestDirectory::new();
+ let source = temporary.path().join("standalone.spock");
+ fs::write(
+ &source,
+ "table user { key id: uuid = auto\n name: text }\n\
+ seed { user { name: \"Ada\" } }\n",
+ )
+ .unwrap();
+
+ let result = check_target(Some(Path::new("standalone.spock")), temporary.path()).unwrap();
+
+ assert_eq!(
+ result,
+ CheckTargetSummary::File {
+ path: PathBuf::from("standalone.spock"),
+ summary: CheckSummary {
+ tables: 1,
+ records: 0,
+ functions: 0,
+ unchecked_escapes: 0,
+ seed_rows: 1,
+ },
+ }
+ );
+ assert_eq!(
+ result.to_string(),
+ "ok: 1 table(s), 0 record(s), 0 fn(s), 1 seed row(s)"
+ );
+ }
+
+ #[test]
+ fn omitted_check_target_checks_the_nearest_project() {
+ let temporary = TestDirectory::new();
+ let created = create_project(temporary.path(), "demo", true).unwrap();
+ let nested = created.root.join("backend");
+
+ let checked = check_target(None, &nested).unwrap();
+
+ let CheckTargetSummary::Project {
+ root,
+ project_name,
+ report,
+ } = checked
+ else {
+ panic!("omitted target did not select project mode");
+ };
+ assert_eq!(root, created.root);
+ assert_eq!(project_name, "demo");
+ assert_eq!(report.backend.tables, 0);
+ assert!(report.client.is_none());
+ assert!(report.warnings.is_empty());
+ }
+
+ #[test]
+ fn framework_serve_rejects_file_mode_with_run_guidance() {
+ let temporary = TestDirectory::new();
+ let error =
+ resolve_project_for_serve(Some(Path::new("api.spock")), temporary.path()).unwrap_err();
+
+ assert!(matches!(
+ error,
+ ResolveProjectForServeError::StandaloneFile { .. }
+ ));
+ let rendered = error.to_string();
+ assert!(rendered.contains("spock run"), "{rendered}");
+ assert!(rendered.contains("api.spock"), "{rendered}");
+ }
+
+ #[test]
+ fn new_defaults_to_the_embedded_full_stack_template() {
+ let temporary = TestDirectory::new();
+
+ let summary = create_project(temporary.path(), "demo", false).unwrap();
+
+ assert_eq!(summary.operation, ProjectWriteOperation::New);
+ assert_eq!(summary.project_name, "demo");
+ assert!(summary.includes_client);
+ assert!(summary.root.join("backend/app.spock").is_file());
+ for file in minimal_uhura_client_template().files() {
+ assert_eq!(
+ fs::read(summary.root.join("client").join(file.path().as_path())).unwrap(),
+ file.contents(),
+ );
+ }
+ assert_eq!(
+ summary.created_files.last(),
+ Some(&summary.root.join(MANIFEST_FILE)),
+ "manifest remains the final commit marker"
+ );
+ }
+
+ #[test]
+ fn backend_only_new_omits_client_topology() {
+ let temporary = TestDirectory::new();
+
+ let summary = create_project(temporary.path(), "authority", true).unwrap();
+
+ assert!(!summary.includes_client);
+ assert!(!summary.root.join("client").exists());
+ let manifest = fs::read_to_string(summary.root.join(MANIFEST_FILE)).unwrap();
+ assert!(!manifest.contains("[client]"));
+ }
+
+ #[test]
+ fn unsafe_new_names_fail_without_filesystem_effects() {
+ let temporary = TestDirectory::new();
+
+ for name in [
+ "",
+ ".",
+ "..",
+ "../escape",
+ "nested/name",
+ "nested\\name",
+ "C:",
+ ] {
+ let error = create_project(temporary.path(), name, false).unwrap_err();
+ assert!(matches!(error, ProjectWriteError::InvalidName(_)), "{name}");
+ }
+
+ assert_eq!(fs::read_dir(temporary.path()).unwrap().count(), 0);
+ }
+
+ #[test]
+ fn init_adopts_the_exact_selected_directory_without_moving_sources() {
+ let temporary = TestDirectory::new();
+ let adoption = temporary.path().join("existing");
+ fs::create_dir(&adoption).unwrap();
+ fs::write(adoption.join("main.spock"), "").unwrap();
+ fs::write(adoption.join("owned.txt"), "keep\n").unwrap();
+
+ let summary = init_project(Some(Path::new("existing")), temporary.path()).unwrap();
+
+ assert_eq!(summary.operation, ProjectWriteOperation::Init);
+ assert_eq!(summary.root, fs::canonicalize(&adoption).unwrap());
+ assert_eq!(
+ fs::read_to_string(adoption.join("owned.txt")).unwrap(),
+ "keep\n"
+ );
+ assert!(adoption.join("main.spock").is_file());
+ assert!(!adoption.join("backend/app.spock").exists());
+ let manifest = fs::read_to_string(adoption.join(MANIFEST_FILE)).unwrap();
+ assert!(manifest.contains("root = \".\""), "{manifest}");
+ assert!(manifest.contains("entry = \"main.spock\""), "{manifest}");
+ }
+
+ #[test]
+ fn init_of_uhura_only_root_adds_the_required_empty_backend_and_checks() {
+ let temporary = TestDirectory::new();
+ for file in minimal_uhura_client_template().files() {
+ let destination = temporary.path().join(file.path().as_path());
+ fs::create_dir_all(destination.parent().unwrap()).unwrap();
+ fs::write(destination, file.contents()).unwrap();
+ }
+
+ let summary = init_project(None, temporary.path()).unwrap();
+
+ assert!(summary.includes_client);
+ assert!(temporary.path().join("backend/app.spock").is_file());
+ let checked = check_target(None, temporary.path()).unwrap();
+ let CheckTargetSummary::Project { report, .. } = checked else {
+ panic!("adopted root did not select project mode");
+ };
+ assert!(report.client.is_some());
+ assert_eq!(report.unchecked_links, 1);
+ assert_eq!(report.warnings.len(), 1);
+ }
+
+ #[test]
+ fn init_ambiguity_fails_before_writing_a_manifest() {
+ let temporary = TestDirectory::new();
+ fs::write(temporary.path().join("one.spock"), "").unwrap();
+ fs::write(temporary.path().join("two.spock"), "").unwrap();
+
+ let error = init_project(None, temporary.path()).unwrap_err();
+
+ let ProjectWriteError::ProjectPlan(diagnostics) = error else {
+ panic!("ambiguity did not remain a structured project diagnostic");
+ };
+ assert_eq!(
+ diagnostics.iter().next().map(|diagnostic| diagnostic.code),
+ Some(spock_project::DiagnosticCode::AmbiguousBackend),
+ );
+ assert!(!temporary.path().join(MANIFEST_FILE).exists());
+ }
+
+ #[test]
+ fn init_rejects_portable_manifest_alias_before_other_writes() {
+ let temporary = TestDirectory::new();
+ let aliased_manifest = temporary.path().join("SPOCK.TOML");
+ fs::write(&aliased_manifest, "owned-by-existing-project\n").unwrap();
+
+ let error = init_project(None, temporary.path()).unwrap_err();
+
+ assert!(matches!(error, ProjectWriteError::ProjectPlan(_)));
+ assert_eq!(
+ fs::read_to_string(aliased_manifest).unwrap(),
+ "owned-by-existing-project\n"
+ );
+ assert!(!temporary.path().join("backend").exists());
+ }
+}
diff --git a/crates/spock-cli/src/write_plan.rs b/crates/spock-cli/src/write_plan.rs
new file mode 100644
index 0000000..f910894
--- /dev/null
+++ b/crates/spock-cli/src/write_plan.rs
@@ -0,0 +1,2771 @@
+//! Race-safe filesystem application for [`spock_project::WritePlan`].
+//!
+//! Planning remains mutation-free in `spock-project`. This module owns the
+//! imperative boundary used by `spock new` and `spock init`: it creates every
+//! file with `create_new`, treats `spock.toml` as the final commit marker, and
+//! handles failure without touching pre-existing paths. Unix rollback removes
+//! exact invocation-owned files through retained parent handles but preserves
+//! created directories because `mkdir` cannot atomically return an ownership
+//! handle. Windows deliberately preserves and reports every known creation
+//! because the available rename APIs cannot safely restore without replacement.
+
+#[cfg(windows)]
+use std::collections::BTreeMap;
+use std::ffi::{OsStr, OsString};
+use std::fmt;
+use std::fs;
+#[cfg(not(unix))]
+use std::fs::OpenOptions;
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+#[cfg(not(windows))]
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use spock_project::{
+ is_ignored_inventory_directory, Diagnostic, DiagnosticCode, Diagnostics, InventoryEntryKind,
+ NormalizedRelativePath, PlanKind, ProjectInventory, ProjectResult, WritePlan, MANIFEST_FILE,
+};
+
+#[cfg(not(windows))]
+static NEXT_QUARANTINE: AtomicU64 = AtomicU64::new(0);
+
+/// Filesystem policy for the root of a write plan.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum RootPolicy {
+ /// `spock new`: the destination itself must not exist.
+ NewDestination,
+ /// `spock init`: the adoption root must already be a real directory.
+ ExistingAdoptionRoot,
+}
+
+impl RootPolicy {
+ fn accepts(self, kind: PlanKind) -> bool {
+ matches!(
+ (self, kind),
+ (Self::NewDestination, PlanKind::Scaffold)
+ | (Self::ExistingAdoptionRoot, PlanKind::Adopt)
+ )
+ }
+}
+
+/// A live filesystem capability retained between project inventory and apply.
+///
+/// The public project commands use this lease so planning and mutation cannot
+/// silently select different directories at the same pathname. On Windows the
+/// retained directory handle also denies delete sharing, preventing rename or
+/// replacement for the lifetime of the lease.
+#[derive(Debug)]
+pub(crate) struct PreparedWriteRoot(PinnedRoot);
+
+impl PreparedWriteRoot {
+ pub(crate) fn open(path: &Path) -> io::Result {
+ PinnedRoot::open(path).map(Self)
+ }
+
+ pub(crate) fn path(&self) -> &Path {
+ &self.0.path
+ }
+
+ pub(crate) fn validate(&self) -> io::Result<()> {
+ self.0.validate()
+ }
+
+ /// Inventory exactly the retained directory used by the later apply.
+ pub(crate) fn inventory(&self) -> ProjectResult {
+ scan_prepared_inventory(&self.0)
+ }
+}
+
+fn inventory_io(
+ root: &Path,
+ relative: &Path,
+ action: &str,
+ error: impl fmt::Display,
+) -> Diagnostics {
+ Diagnostics::one(
+ Diagnostic::new(DiagnosticCode::Io, format!("could not {action}: {error}"))
+ .at_path(root.join(relative)),
+ )
+}
+
+fn normalized_inventory_path(
+ root: &Path,
+ relative: &Path,
+) -> ProjectResult {
+ let mut segments = Vec::new();
+ for component in relative.components() {
+ let std::path::Component::Normal(segment) = component else {
+ return Err(Diagnostic::new(
+ DiagnosticCode::InvalidManifestPath,
+ "scanned path cannot be represented in a project manifest",
+ )
+ .at_path(root.join(relative))
+ .into());
+ };
+ let Some(segment) = segment.to_str() else {
+ return Err(Diagnostic::new(
+ DiagnosticCode::InvalidManifestPath,
+ "scanned path is not UTF-8 and cannot be represented in a project manifest",
+ )
+ .at_path(root.join(relative))
+ .into());
+ };
+ segments.push(segment);
+ }
+ NormalizedRelativePath::file(&segments.join("/")).map_err(|error| {
+ Diagnostics::one(
+ Diagnostic::new(
+ DiagnosticCode::InvalidManifestPath,
+ format!("scanned path is not a valid project path: {error}"),
+ )
+ .at_path(root.join(relative)),
+ )
+ })
+}
+
+#[cfg(unix)]
+fn scan_prepared_inventory(root: &PinnedRoot) -> ProjectResult {
+ let mut entries = Vec::new();
+ scan_unix_inventory_directory(&root.directory, Path::new(""), &root.path, &mut entries)?;
+ ProjectInventory::from_entries(root.path.clone(), entries)
+}
+
+#[cfg(unix)]
+fn scan_unix_inventory_directory(
+ directory: &fs::File,
+ relative_parent: &Path,
+ root: &Path,
+ entries: &mut Vec<(NormalizedRelativePath, InventoryEntryKind)>,
+) -> ProjectResult<()> {
+ use std::os::unix::ffi::OsStrExt;
+
+ let reader = rustix::fs::Dir::read_from(directory)
+ .map_err(|error| inventory_io(root, relative_parent, "scan directory", error))?;
+ let mut names = reader
+ .map(|entry| {
+ let entry = entry.map_err(|error| {
+ inventory_io(root, relative_parent, "scan directory entry", error)
+ })?;
+ Ok(OsStr::from_bytes(entry.file_name().to_bytes()).to_os_string())
+ })
+ .collect::>>()?;
+ names.retain(|name| name != "." && name != "..");
+ names.sort();
+
+ for name in names {
+ let relative = relative_parent.join(&name);
+ let metadata = rustix::fs::statat(directory, &name, rustix::fs::AtFlags::SYMLINK_NOFOLLOW)
+ .map_err(|error| inventory_io(root, &relative, "inspect directory entry", error))?;
+ let kind = match rustix::fs::FileType::from_raw_mode(metadata.st_mode) {
+ rustix::fs::FileType::Directory => InventoryEntryKind::Directory,
+ rustix::fs::FileType::Symlink => InventoryEntryKind::Symlink,
+ rustix::fs::FileType::RegularFile => InventoryEntryKind::File,
+ _ => InventoryEntryKind::Unsupported,
+ };
+ let normalized = normalized_inventory_path(root, &relative)?;
+ let ignored = kind == InventoryEntryKind::Directory
+ && normalized
+ .file_name()
+ .is_some_and(is_ignored_inventory_directory);
+ entries.push((normalized, kind));
+ if kind == InventoryEntryKind::Directory && !ignored {
+ let child = open_directory_at(directory, &name)
+ .map_err(|error| inventory_io(root, &relative, "open directory", error))?;
+ scan_unix_inventory_directory(&child, &relative, root, entries)?;
+ }
+ }
+ Ok(())
+}
+
+#[cfg(windows)]
+fn scan_prepared_inventory(root: &PinnedRoot) -> ProjectResult {
+ let mut entries = Vec::new();
+ scan_windows_inventory_directory(&root.directory, Path::new(""), &root.path, &mut entries)?;
+ ProjectInventory::from_entries(root.path.clone(), entries)
+}
+
+#[cfg(windows)]
+fn scan_windows_inventory_directory(
+ directory: &cap_std::fs::Dir,
+ relative_parent: &Path,
+ root: &Path,
+ entries: &mut Vec<(NormalizedRelativePath, InventoryEntryKind)>,
+) -> ProjectResult<()> {
+ use cap_fs_ext::DirExt as _;
+
+ let reader = directory
+ .entries()
+ .map_err(|error| inventory_io(root, relative_parent, "scan directory", error))?;
+ let mut children = reader
+ .map(|entry| {
+ let entry = entry.map_err(|error| {
+ inventory_io(root, relative_parent, "scan directory entry", error)
+ })?;
+ let name = entry.file_name();
+ let kind = entry.file_type().map_err(|error| {
+ inventory_io(
+ root,
+ &relative_parent.join(&name),
+ "inspect directory entry",
+ error,
+ )
+ })?;
+ Ok((name, kind))
+ })
+ .collect::>>()?;
+ children.sort_by(|left, right| left.0.cmp(&right.0));
+
+ for (name, file_type) in children {
+ let relative = relative_parent.join(&name);
+ let kind = if file_type.is_symlink() {
+ InventoryEntryKind::Symlink
+ } else if file_type.is_dir() {
+ InventoryEntryKind::Directory
+ } else if file_type.is_file() {
+ InventoryEntryKind::File
+ } else {
+ InventoryEntryKind::Unsupported
+ };
+ let normalized = normalized_inventory_path(root, &relative)?;
+ let ignored = kind == InventoryEntryKind::Directory
+ && normalized
+ .file_name()
+ .is_some_and(is_ignored_inventory_directory);
+ entries.push((normalized, kind));
+ if kind == InventoryEntryKind::Directory && !ignored {
+ let child = directory
+ .open_dir_nofollow(&name)
+ .map_err(|error| inventory_io(root, &relative, "open directory", error))?;
+ scan_windows_inventory_directory(&child, &relative, root, entries)?;
+ }
+ }
+ Ok(())
+}
+
+#[cfg(not(any(unix, windows)))]
+fn scan_prepared_inventory(root: &PinnedRoot) -> ProjectResult {
+ root.validate().map_err(|error| {
+ inventory_io(&root.path, Path::new(""), "validate adoption root", error)
+ })?;
+ ProjectInventory::scan(&root.path)
+}
+
+#[derive(Debug)]
+pub(crate) enum PreparedWriteTarget {
+ NewChild {
+ parent: PreparedWriteRoot,
+ child: OsString,
+ },
+ Existing(PreparedWriteRoot),
+}
+
+impl PreparedWriteTarget {
+ pub(crate) fn new_child(parent: PreparedWriteRoot, child: impl Into) -> Self {
+ Self::NewChild {
+ parent,
+ child: child.into(),
+ }
+ }
+
+ pub(crate) fn existing(root: PreparedWriteRoot) -> Self {
+ Self::Existing(root)
+ }
+
+ fn policy(&self) -> RootPolicy {
+ match self {
+ Self::NewChild { .. } => RootPolicy::NewDestination,
+ Self::Existing(_) => RootPolicy::ExistingAdoptionRoot,
+ }
+ }
+}
+
+/// The operation that failed while applying a plan.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ApplyStage {
+ ValidatePolicy,
+ ValidateRoot,
+ CreateRoot,
+ CreateDirectory,
+ CreateFile,
+ RecordOwnership,
+ WriteFile,
+}
+
+impl fmt::Display for ApplyStage {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ let description = match self {
+ Self::ValidatePolicy => "validate write-plan policy",
+ Self::ValidateRoot => "validate project root",
+ Self::CreateRoot => "create project root",
+ Self::CreateDirectory => "create project directory",
+ Self::CreateFile => "create project file",
+ Self::RecordOwnership => "record project path ownership",
+ Self::WriteFile => "write project file",
+ };
+ f.write_str(description)
+ }
+}
+
+/// Kind of invocation-created path considered during rollback.
+#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
+pub enum CreatedPathKind {
+ File,
+ Directory,
+}
+
+/// One invocation-created path that could not be removed during rollback.
+#[derive(Debug)]
+pub struct RollbackResidual {
+ path: PathBuf,
+ kind: CreatedPathKind,
+ error: io::Error,
+}
+
+impl RollbackResidual {
+ pub fn path(&self) -> &Path {
+ &self.path
+ }
+
+ pub fn kind(&self) -> CreatedPathKind {
+ self.kind
+ }
+
+ pub fn error(&self) -> &io::Error {
+ &self.error
+ }
+}
+
+/// Result of the best-effort rollback performed after an apply failure.
+#[derive(Debug, Default)]
+pub struct RollbackReport {
+ residuals: Vec,
+}
+
+impl RollbackReport {
+ /// True when every invocation-created path is gone.
+ pub fn is_complete(&self) -> bool {
+ self.residuals.is_empty()
+ }
+
+ /// Invocation-created paths that still exist or could not be inspected.
+ pub fn residuals(&self) -> &[RollbackResidual] {
+ &self.residuals
+ }
+}
+
+/// Successful filesystem effects of one plan application.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ApplySummary {
+ root: PathBuf,
+ created_files: Vec,
+ created_directories: Vec,
+}
+
+impl ApplySummary {
+ pub fn root(&self) -> &Path {
+ &self.root
+ }
+
+ /// Files in creation order. `spock.toml` is always last.
+ pub fn created_files(&self) -> &[PathBuf] {
+ &self.created_files
+ }
+
+ /// Directories in parent-before-child creation order.
+ pub fn created_directories(&self) -> &[PathBuf] {
+ &self.created_directories
+ }
+}
+
+/// A failed plan application together with its rollback outcome.
+#[derive(Debug)]
+pub struct ApplyError {
+ stage: ApplyStage,
+ path: PathBuf,
+ source: io::Error,
+ rollback: RollbackReport,
+}
+
+impl ApplyError {
+ pub fn stage(&self) -> ApplyStage {
+ self.stage
+ }
+
+ pub fn path(&self) -> &Path {
+ &self.path
+ }
+
+ pub fn io_error(&self) -> &io::Error {
+ &self.source
+ }
+
+ pub fn rollback(&self) -> &RollbackReport {
+ &self.rollback
+ }
+}
+
+impl fmt::Display for ApplyError {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(
+ f,
+ "could not {} `{}`: {}",
+ self.stage,
+ self.path.display(),
+ self.source
+ )?;
+ if !self.rollback.is_complete() {
+ write!(f, "; rollback left")?;
+ for residual in self.rollback.residuals() {
+ write!(f, " `{}` ({})", residual.path().display(), residual.error())?;
+ }
+ }
+ Ok(())
+ }
+}
+
+impl std::error::Error for ApplyError {
+ fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+ Some(&self.source)
+ }
+}
+
+/// Apply a pure project write plan without overwriting any existing file.
+///
+/// Non-manifest files are created first. `spock.toml` is created last so its
+/// presence means all preceding template writes succeeded. A later conflict
+/// triggers a platform-specific best-effort rollback. Unix removes exact
+/// invocation-owned files through retained parent handles and reports created
+/// directories as residuals. Windows performs no rollback mutation and reports
+/// every known creation as a residual. These conservative rules avoid deleting
+/// or overwriting an entry concurrently installed under a created name.
+#[cfg(test)]
+fn apply_write_plan(plan: &WritePlan, root_policy: RootPolicy) -> Result {
+ apply_write_plan_inner(plan, root_policy, |_| {})
+}
+
+pub(crate) fn apply_prepared_write_plan(
+ plan: &WritePlan,
+ target: PreparedWriteTarget,
+) -> Result {
+ let policy = target.policy();
+ apply_write_plan_inner_with_target(plan, policy, Some(target), |_| {})
+}
+
+#[cfg(test)]
+fn apply_write_plan_inner(
+ plan: &WritePlan,
+ root_policy: RootPolicy,
+ after_write: F,
+) -> Result
+where
+ F: FnMut(&Path),
+{
+ apply_write_plan_inner_with_target(plan, root_policy, None, after_write)
+}
+
+fn apply_write_plan_inner_with_target(
+ plan: &WritePlan,
+ root_policy: RootPolicy,
+ prepared_target: Option,
+ mut after_write: F,
+) -> Result
+where
+ F: FnMut(&Path),
+{
+ let mut journal = CreationJournal::default();
+
+ if !root_policy.accepts(plan.kind) {
+ let source = io::Error::new(
+ io::ErrorKind::InvalidInput,
+ format!(
+ "root policy {root_policy:?} does not accept a {:?} plan",
+ plan.kind
+ ),
+ );
+ return Err(failed(
+ ApplyStage::ValidatePolicy,
+ &plan.root,
+ source,
+ journal,
+ ));
+ }
+
+ let root = match prepare_root(&plan.root, root_policy, prepared_target, &mut journal) {
+ Ok(root) => root,
+ Err(failure) => {
+ return Err(failed(failure.stage, failure.path, failure.error, journal));
+ }
+ };
+ let mut directory_cache = DirectoryCache::new();
+
+ let mut writes = plan.writes().iter().collect::>();
+ writes.sort_by(|left, right| {
+ let left_is_manifest = left.relative_path.as_str() == MANIFEST_FILE;
+ let right_is_manifest = right.relative_path.as_str() == MANIFEST_FILE;
+ left_is_manifest
+ .cmp(&right_is_manifest)
+ .then_with(|| left.relative_path.cmp(&right.relative_path))
+ });
+
+ for write in writes {
+ let relative_parent = write
+ .relative_path
+ .as_path()
+ .parent()
+ .expect("a planned file always has a parent");
+ let parent = match ensure_relative_directories(
+ &root,
+ relative_parent,
+ &mut journal,
+ &mut directory_cache,
+ ) {
+ Ok(parent) => parent,
+ Err(failure) => {
+ return Err(failed(failure.stage, failure.path, failure.error, journal));
+ }
+ };
+
+ let destination = plan.root.join(write.relative_path.as_path());
+ let file_name = write
+ .relative_path
+ .as_path()
+ .file_name()
+ .expect("a planned file has a file name");
+ let (mut file, anchor) = match parent.create_new_file(file_name) {
+ Ok(created) => created,
+ Err(error) => {
+ return Err(failed(ApplyStage::CreateFile, destination, error, journal));
+ }
+ };
+ // Retain an open handle until success or rollback. Comparing a current
+ // directory entry to this live file object avoids inode/file-index
+ // reuse after an editor atomically replaces the path.
+ let identity = match journal_identity_from_file(&file) {
+ Ok(identity) => identity,
+ Err(error) => {
+ journal
+ .files
+ .push(JournalEntry::file(destination.clone(), file, None, anchor));
+ return Err(failed(
+ ApplyStage::RecordOwnership,
+ destination,
+ error,
+ journal,
+ ));
+ }
+ };
+
+ if let Err(error) = file.write_all(&write.contents) {
+ journal.files.push(JournalEntry::file(
+ destination.clone(),
+ file,
+ identity,
+ anchor,
+ ));
+ return Err(failed(ApplyStage::WriteFile, destination, error, journal));
+ }
+ journal.files.push(JournalEntry::file(
+ destination.clone(),
+ file,
+ identity,
+ anchor,
+ ));
+ after_write(&destination);
+ }
+
+ if let Err(error) = root.validate() {
+ return Err(failed(ApplyStage::ValidateRoot, &plan.root, error, journal));
+ }
+
+ let CreationJournal { files, directories } = journal;
+ Ok(ApplySummary {
+ root: plan.root.clone(),
+ created_files: files.into_iter().map(|entry| entry.path).collect(),
+ created_directories: directories.into_iter().map(|entry| entry.path).collect(),
+ })
+}
+
+#[derive(Debug)]
+struct OperationFailure {
+ stage: ApplyStage,
+ path: PathBuf,
+ error: io::Error,
+}
+
+fn prepare_root(
+ root: &Path,
+ root_policy: RootPolicy,
+ prepared_target: Option,
+ journal: &mut CreationJournal,
+) -> Result {
+ if let Some(prepared_target) = prepared_target {
+ return match prepared_target {
+ PreparedWriteTarget::Existing(PreparedWriteRoot(prepared)) => {
+ if root_policy != RootPolicy::ExistingAdoptionRoot || prepared.path != root {
+ return Err(prepared_target_mismatch(root));
+ }
+ prepared.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ Ok(prepared)
+ }
+ PreparedWriteTarget::NewChild {
+ parent: PreparedWriteRoot(parent),
+ child,
+ } => {
+ let expected = parent.path.join(&child);
+ let mut components = Path::new(&child).components();
+ let is_normal_child = matches!(
+ (components.next(), components.next()),
+ (Some(std::path::Component::Normal(_)), None)
+ );
+ if root_policy != RootPolicy::NewDestination || expected != root || !is_normal_child
+ {
+ return Err(prepared_target_mismatch(root));
+ }
+ create_new_root_from_prepared_parent(root, &child, parent, journal)
+ }
+ };
+ }
+
+ match root_policy {
+ RootPolicy::NewDestination => create_new_root(root, journal),
+ RootPolicy::ExistingAdoptionRoot => {
+ validate_existing_root(root)?;
+ PinnedRoot::open(root).map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.to_path_buf(),
+ error,
+ })
+ }
+ }
+}
+
+fn prepared_target_mismatch(root: &Path) -> OperationFailure {
+ OperationFailure {
+ stage: ApplyStage::ValidatePolicy,
+ path: root.to_path_buf(),
+ error: io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "prepared filesystem target does not match the write plan root and kind",
+ ),
+ }
+}
+
+#[cfg(windows)]
+fn create_new_root_from_prepared_parent(
+ root: &Path,
+ child: &OsStr,
+ parent: PinnedRoot,
+ journal: &mut CreationJournal,
+) -> Result {
+ parent.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: parent.path.clone(),
+ error,
+ })?;
+ let created = create_windows_directory_at(&parent.directory, child).map_err(|error| {
+ OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error,
+ }
+ })?;
+ let directory = retain_windows_created_directory(
+ &parent.directory,
+ child,
+ root.to_path_buf(),
+ created,
+ journal,
+ )?;
+ let identity =
+ windows_identity_from_directory(&directory).map_err(|error| OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ let PinnedRoot {
+ directory: parent_directory,
+ mut ancestor_guards,
+ ..
+ } = parent;
+ ancestor_guards.push(parent_directory);
+ let pinned = PinnedRoot {
+ directory,
+ identity,
+ path: root.to_path_buf(),
+ ancestor_guards,
+ };
+ pinned.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ Ok(pinned)
+}
+
+#[cfg(unix)]
+fn create_new_root_from_prepared_parent(
+ root: &Path,
+ child: &OsStr,
+ parent: PinnedRoot,
+ journal: &mut CreationJournal,
+) -> Result {
+ parent.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: parent.path.clone(),
+ error,
+ })?;
+ create_directory_at(&parent.directory, child).map_err(|error| OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ // Journal immediately after mkdirat. The retained child handle is opened
+ // in a second syscall, so rollback must preserve this directory even when
+ // that open or any following validation fails.
+ journal
+ .directories
+ .push(JournalEntry::directory_without_identity(
+ root.to_path_buf(),
+ None,
+ ));
+ let directory =
+ open_directory_at(&parent.directory, child).map_err(|error| OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ parent.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: parent.path.clone(),
+ error,
+ })?;
+ let metadata = directory.metadata().map_err(|error| OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ let identity = entry_identity(&metadata).expect("Unix directory identity");
+ let pinned = PinnedRoot {
+ directory,
+ identity,
+ path: root.to_path_buf(),
+ };
+ pinned.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ Ok(pinned)
+}
+
+#[cfg(not(any(unix, windows)))]
+fn create_new_root_from_prepared_parent(
+ root: &Path,
+ _child: &OsStr,
+ parent: PinnedRoot,
+ journal: &mut CreationJournal,
+) -> Result {
+ parent.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: parent.path.clone(),
+ error,
+ })?;
+ let result = create_new_root(root, journal);
+ parent.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: parent.path.clone(),
+ error,
+ })?;
+ result
+}
+
+#[cfg(not(windows))]
+fn create_new_root(
+ root: &Path,
+ journal: &mut CreationJournal,
+) -> Result {
+ match fs::symlink_metadata(root) {
+ Ok(_) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error: io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "new project destination already exists",
+ ),
+ });
+ }
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error,
+ });
+ }
+ }
+
+ if let Some(parent) = nonempty_parent(root) {
+ ensure_directory_tree(parent, journal)?;
+ }
+
+ fs::create_dir(root).map_err(|error| OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ record_created_directory(root, journal)?;
+ PinnedRoot::open(root).map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.to_path_buf(),
+ error,
+ })
+}
+
+#[cfg(windows)]
+fn create_new_root(
+ root: &Path,
+ journal: &mut CreationJournal,
+) -> Result {
+ match fs::symlink_metadata(root) {
+ Ok(_) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error: io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "new project destination already exists",
+ ),
+ });
+ }
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error,
+ });
+ }
+ }
+
+ // Walk upward without mutating until one real ancestor can be pinned.
+ // Every missing component is then created relative to the retained handle;
+ // the newly created root handle itself becomes `PinnedRoot` and is never
+ // reopened through its mutable pathname.
+ let mut missing = Vec::<(PathBuf, OsString)>::new();
+ let mut existing = root.to_path_buf();
+ loop {
+ match fs::symlink_metadata(&existing) {
+ Ok(metadata) => {
+ require_real_directory(&existing, &metadata)?;
+ break;
+ }
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {
+ let name = existing.file_name().ok_or_else(|| OperationFailure {
+ stage: ApplyStage::CreateRoot,
+ path: root.to_path_buf(),
+ error: io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "new project destination has no creatable path component",
+ ),
+ })?;
+ missing.push((existing.clone(), name.to_os_string()));
+ existing = existing
+ .parent()
+ .filter(|parent| !parent.as_os_str().is_empty())
+ .map(Path::to_path_buf)
+ .unwrap_or_else(|| PathBuf::from("."));
+ }
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: existing,
+ error,
+ });
+ }
+ }
+ }
+
+ let pinned_ancestor = PinnedRoot::open(&existing).map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: existing.clone(),
+ error,
+ })?;
+ let PinnedRoot {
+ directory: mut current,
+ mut ancestor_guards,
+ ..
+ } = pinned_ancestor;
+
+ let missing_count = missing.len();
+ for (index, (path, name)) in missing.into_iter().rev().enumerate() {
+ ancestor_guards.push(current.try_clone().map_err(|error| OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: path.clone(),
+ error,
+ })?);
+ let created = match create_windows_directory_at(¤t, &name) {
+ Ok(created) => created,
+ Err(error)
+ if error.kind() == io::ErrorKind::AlreadyExists && index + 1 != missing_count =>
+ {
+ use cap_fs_ext::DirExt as _;
+
+ current = current
+ .open_dir_nofollow(&name)
+ .map_err(|error| OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path,
+ error,
+ })?;
+ continue;
+ }
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: if index + 1 == missing_count {
+ ApplyStage::CreateRoot
+ } else {
+ ApplyStage::CreateDirectory
+ },
+ path,
+ error,
+ });
+ }
+ };
+ current = retain_windows_created_directory(¤t, &name, path, created, journal)?;
+ }
+
+ let identity = windows_identity_from_directory(¤t).map_err(|error| OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ let pinned = PinnedRoot {
+ directory: current,
+ identity,
+ path: root.to_path_buf(),
+ ancestor_guards,
+ };
+ pinned.validate().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ Ok(pinned)
+}
+
+fn validate_existing_root(root: &Path) -> Result<(), OperationFailure> {
+ let metadata = fs::symlink_metadata(root).map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.to_path_buf(),
+ error,
+ })?;
+ if !metadata.file_type().is_dir() {
+ return Err(OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.to_path_buf(),
+ error: io::Error::new(
+ io::ErrorKind::NotADirectory,
+ "adoption root is not a real directory",
+ ),
+ });
+ }
+ Ok(())
+}
+
+#[cfg(not(windows))]
+fn nonempty_parent(path: &Path) -> Option<&Path> {
+ path.parent()
+ .filter(|parent| !parent.as_os_str().is_empty())
+}
+
+/// Ensure a possibly-outside-root ancestor path for a new destination.
+/// Existing ancestors terminate recursion; only directories created while
+/// unwinding are journaled.
+#[cfg(not(windows))]
+fn ensure_directory_tree(
+ directory: &Path,
+ journal: &mut CreationJournal,
+) -> Result<(), OperationFailure> {
+ match fs::symlink_metadata(directory) {
+ Ok(metadata) => return require_real_directory(directory, &metadata),
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: directory.to_path_buf(),
+ error,
+ });
+ }
+ }
+
+ if let Some(parent) = nonempty_parent(directory) {
+ ensure_directory_tree(parent, journal)?;
+ }
+ create_directory_if_missing(directory, journal)
+}
+
+#[cfg(unix)]
+#[derive(Debug)]
+struct PinnedRoot {
+ directory: fs::File,
+ identity: EntryIdentity,
+ path: PathBuf,
+}
+
+#[cfg(not(windows))]
+#[derive(Debug)]
+struct DirectoryCache;
+
+#[cfg(not(windows))]
+impl DirectoryCache {
+ fn new() -> Self {
+ Self
+ }
+}
+
+#[cfg(windows)]
+#[derive(Debug, Default)]
+struct DirectoryCache {
+ directories: BTreeMap,
+}
+
+#[cfg(windows)]
+impl DirectoryCache {
+ fn new() -> Self {
+ Self::default()
+ }
+}
+
+#[cfg(unix)]
+impl PinnedRoot {
+ fn open(path: &Path) -> io::Result {
+ let directory = open_directory_path(path)?;
+ let identity = entry_identity(&directory.metadata()?).expect("Unix directory identity");
+ let root = Self {
+ directory,
+ identity,
+ path: path.to_path_buf(),
+ };
+ root.validate()?;
+ Ok(root)
+ }
+
+ fn validate(&self) -> io::Result<()> {
+ let metadata = fs::symlink_metadata(&self.path)?;
+ if !metadata.file_type().is_dir()
+ || entry_identity(&metadata) != Some(self.identity)
+ || entry_identity(&self.directory.metadata()?) != Some(self.identity)
+ {
+ return Err(io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "project root identity changed while applying the write plan",
+ ));
+ }
+ Ok(())
+ }
+
+ fn cursor(&self) -> io::Result {
+ self.validate()?;
+ Ok(DirectoryCursor {
+ directory: self.directory.try_clone()?,
+ path: self.path.clone(),
+ })
+ }
+}
+
+#[cfg(unix)]
+#[derive(Debug)]
+struct DirectoryCursor {
+ directory: fs::File,
+ path: PathBuf,
+}
+
+#[cfg(unix)]
+impl DirectoryCursor {
+ fn create_new_file(&self, name: &OsStr) -> io::Result<(fs::File, Option)> {
+ // Duplicate the parent capability before the mutating openat. If the
+ // process is out of descriptors, fail before creating a file that the
+ // caller cannot journal through its retained parent anchor.
+ let parent = self.directory.try_clone()?;
+ let descriptor = rustix::fs::openat(
+ &self.directory,
+ name,
+ rustix::fs::OFlags::WRONLY
+ | rustix::fs::OFlags::CREATE
+ | rustix::fs::OFlags::EXCL
+ | rustix::fs::OFlags::NOFOLLOW
+ | rustix::fs::OFlags::CLOEXEC,
+ rustix::fs::Mode::from_raw_mode(0o666),
+ )?;
+ let file = fs::File::from(descriptor);
+ let anchor = PathAnchor {
+ parent,
+ name: name.to_os_string(),
+ };
+ Ok((file, Some(anchor)))
+ }
+}
+
+#[cfg(windows)]
+#[derive(Debug)]
+struct PinnedRoot {
+ directory: cap_std::fs::Dir,
+ identity: EntryIdentity,
+ path: PathBuf,
+ // `spock new` may create a missing chain below the nearest existing
+ // ancestor. Keep every ancestor locked until the plan commits so moving a
+ // parent cannot carry the pinned project outside the requested pathname.
+ ancestor_guards: Vec,
+}
+
+#[cfg(windows)]
+impl PinnedRoot {
+ fn open(path: &Path) -> io::Result {
+ let metadata = fs::symlink_metadata(path)?;
+ if !metadata.file_type().is_dir() {
+ return Err(io::Error::new(
+ io::ErrorKind::NotADirectory,
+ "project root is not a real directory",
+ ));
+ }
+ let directory = cap_std::fs::Dir::from_std_file(open_directory_path(path)?);
+ let identity = windows_identity_from_directory(&directory)?;
+ let root = Self {
+ directory,
+ identity,
+ path: path.to_path_buf(),
+ ancestor_guards: Vec::new(),
+ };
+ root.validate()?;
+ Ok(root)
+ }
+
+ fn validate(&self) -> io::Result<()> {
+ let metadata = fs::symlink_metadata(&self.path)?;
+ if !metadata.file_type().is_dir()
+ || !windows_path_matches_identity(&self.path, &self.identity)?
+ || windows_identity_from_directory(&self.directory)? != self.identity
+ {
+ return Err(io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "project root identity changed while applying the write plan",
+ ));
+ }
+ Ok(())
+ }
+
+ fn cursor(&self) -> io::Result {
+ self.validate()?;
+ let root = self.directory.try_clone()?;
+ Ok(DirectoryCursor {
+ directory: root.try_clone()?,
+ root_identity: windows_identity_from_directory(&root)?,
+ root,
+ root_path: self.path.clone(),
+ })
+ }
+}
+
+#[cfg(windows)]
+#[derive(Debug)]
+struct DirectoryCursor {
+ directory: cap_std::fs::Dir,
+ root: cap_std::fs::Dir,
+ root_identity: EntryIdentity,
+ root_path: PathBuf,
+}
+
+#[cfg(windows)]
+impl DirectoryCursor {
+ fn validate_root(&self) -> io::Result<()> {
+ let metadata = fs::symlink_metadata(&self.root_path)?;
+ if !metadata.file_type().is_dir()
+ || !windows_path_matches_identity(&self.root_path, &self.root_identity)?
+ || windows_identity_from_directory(&self.root)? != self.root_identity
+ {
+ return Err(io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "project root identity changed while applying the write plan",
+ ));
+ }
+ Ok(())
+ }
+
+ fn create_new_file(&self, name: &OsStr) -> io::Result<(fs::File, Option)> {
+ use cap_fs_ext::{FollowSymlinks, OpenOptionsFollowExt};
+ use cap_std::fs::OpenOptionsExt as _;
+ use windows_sys::Win32::Storage::FileSystem::{
+ FILE_FLAG_OPEN_REPARSE_POINT, FILE_SHARE_READ, FILE_SHARE_WRITE,
+ };
+
+ self.validate_root()?;
+ let mut options = cap_std::fs::OpenOptions::new();
+ options
+ .write(true)
+ .create_new(true)
+ .follow(FollowSymlinks::No)
+ // `create_new` already guarantees the final component did not
+ // exist. Supplying the no-follow flag explicitly prevents
+ // cap-std from performing a fallible metadata probe after the
+ // successful create syscall, so the returned handle can always be
+ // journaled by the caller before any later fallible operation.
+ .custom_flags(FILE_FLAG_OPEN_REPARSE_POINT)
+ .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE);
+ let file = self.directory.open_with(name, &options)?.into_std();
+ Ok((file, None))
+ }
+}
+
+#[cfg(not(any(unix, windows)))]
+#[derive(Debug)]
+struct PinnedRoot {
+ directory: fs::File,
+ identity: Option,
+ path: PathBuf,
+}
+
+#[cfg(not(any(unix, windows)))]
+impl PinnedRoot {
+ fn open(path: &Path) -> io::Result {
+ let metadata = fs::symlink_metadata(path)?;
+ if !metadata.file_type().is_dir() {
+ return Err(io::Error::new(
+ io::ErrorKind::NotADirectory,
+ "project root is not a real directory",
+ ));
+ }
+ let directory = open_directory_path(path)?;
+ let identity = entry_identity(&directory.metadata()?);
+ let root = Self {
+ directory,
+ identity,
+ path: path.to_path_buf(),
+ };
+ root.validate()?;
+ Ok(root)
+ }
+
+ fn validate(&self) -> io::Result<()> {
+ let metadata = fs::symlink_metadata(&self.path)?;
+ if !metadata.file_type().is_dir()
+ || self.identity.is_none()
+ || entry_identity(&metadata) != self.identity
+ || entry_identity(&self.directory.metadata()?) != self.identity
+ {
+ return Err(io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "project root identity changed while applying the write plan",
+ ));
+ }
+ Ok(())
+ }
+
+ fn cursor(&self) -> io::Result {
+ self.validate()?;
+ Ok(DirectoryCursor {
+ root: self.directory.try_clone()?,
+ root_identity: self.identity,
+ root_path: self.path.clone(),
+ path: self.path.clone(),
+ })
+ }
+}
+
+#[cfg(not(any(unix, windows)))]
+#[derive(Debug)]
+struct DirectoryCursor {
+ root: fs::File,
+ root_identity: Option,
+ root_path: PathBuf,
+ path: PathBuf,
+}
+
+#[cfg(not(any(unix, windows)))]
+impl DirectoryCursor {
+ fn validate_root(&self) -> io::Result<()> {
+ let metadata = fs::symlink_metadata(&self.root_path)?;
+ if !metadata.file_type().is_dir()
+ || self.root_identity.is_none()
+ || entry_identity(&metadata) != self.root_identity
+ || entry_identity(&self.root.metadata()?) != self.root_identity
+ {
+ return Err(io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "project root identity changed while applying the write plan",
+ ));
+ }
+ Ok(())
+ }
+
+ fn create_new_file(&self, name: &OsStr) -> io::Result<(fs::File, Option)> {
+ self.validate_root()?;
+ let file = OpenOptions::new()
+ .write(true)
+ .create_new(true)
+ .open(self.path.join(name))?;
+ self.validate_root()?;
+ Ok((file, None))
+ }
+}
+
+#[cfg(unix)]
+fn ensure_relative_directories(
+ root: &PinnedRoot,
+ relative: &Path,
+ journal: &mut CreationJournal,
+ _cache: &mut DirectoryCache,
+) -> Result {
+ let mut current = root.cursor().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.path.clone(),
+ error,
+ })?;
+ for component in relative.components() {
+ let std::path::Component::Normal(segment) = component else {
+ return Err(invalid_planned_parent(&root.path, relative));
+ };
+ let path = current.path.join(segment);
+ match open_directory_at(¤t.directory, segment) {
+ Ok(directory) => current = DirectoryCursor { directory, path },
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {
+ let created = match create_directory_at(¤t.directory, segment) {
+ Ok(()) => true,
+ Err(error) if error.kind() == io::ErrorKind::AlreadyExists => false,
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path,
+ error,
+ });
+ }
+ };
+ if created {
+ // `mkdirat` has already mutated the filesystem and does
+ // not return a handle. Record the logical creation before
+ // any fallible open or metadata call. Directory rollback
+ // is deliberately non-mutating because ownership cannot be
+ // proven across this gap.
+ journal
+ .directories
+ .push(JournalEntry::directory_without_identity(path.clone(), None));
+ }
+ let directory =
+ open_directory_at(¤t.directory, segment).map_err(|error| {
+ OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: path.clone(),
+ error,
+ }
+ })?;
+ current = DirectoryCursor { directory, path };
+ }
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path,
+ error,
+ });
+ }
+ }
+ }
+ Ok(current)
+}
+
+#[cfg(windows)]
+fn ensure_relative_directories(
+ root: &PinnedRoot,
+ relative: &Path,
+ journal: &mut CreationJournal,
+ cache: &mut DirectoryCache,
+) -> Result {
+ use cap_fs_ext::DirExt as _;
+
+ let mut current = root.cursor().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.path.clone(),
+ error,
+ })?;
+ let mut relative_cursor = PathBuf::new();
+ for component in relative.components() {
+ let std::path::Component::Normal(segment) = component else {
+ return Err(invalid_planned_parent(&root.path, relative));
+ };
+ relative_cursor.push(segment);
+ let path = root.path.join(&relative_cursor);
+
+ current.validate_root().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.path.clone(),
+ error,
+ })?;
+
+ let directory = if let Some(cached) = cache.directories.get(&relative_cursor) {
+ cached.try_clone().map_err(|error| OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: path.clone(),
+ error,
+ })?
+ } else {
+ let directory = match current.directory.open_dir_nofollow(segment) {
+ Ok(directory) => directory,
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {
+ match create_windows_directory_at(¤t.directory, segment) {
+ Ok(created) => retain_windows_created_directory(
+ ¤t.directory,
+ segment,
+ path.clone(),
+ created,
+ journal,
+ )?,
+ Err(error) if error.kind() == io::ErrorKind::AlreadyExists => current
+ .directory
+ .open_dir_nofollow(segment)
+ .map_err(|error| OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: path.clone(),
+ error,
+ })?,
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path,
+ error,
+ });
+ }
+ }
+ }
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path,
+ error,
+ });
+ }
+ };
+ cache.directories.insert(
+ relative_cursor.clone(),
+ directory.try_clone().map_err(|error| OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: path.clone(),
+ error,
+ })?,
+ );
+ directory
+ };
+ current = DirectoryCursor {
+ directory,
+ root: current.root.try_clone().map_err(|error| OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: path.clone(),
+ error,
+ })?,
+ root_identity: windows_identity_from_directory(¤t.root).map_err(|error| {
+ OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: path.clone(),
+ error,
+ }
+ })?,
+ root_path: current.root_path.clone(),
+ };
+ }
+ Ok(current)
+}
+
+#[cfg(not(any(unix, windows)))]
+fn ensure_relative_directories(
+ root: &PinnedRoot,
+ relative: &Path,
+ journal: &mut CreationJournal,
+ _cache: &mut DirectoryCache,
+) -> Result {
+ let mut current = root.cursor().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.path.clone(),
+ error,
+ })?;
+ for component in relative.components() {
+ let std::path::Component::Normal(segment) = component else {
+ return Err(invalid_planned_parent(&root.path, relative));
+ };
+ current.validate_root().map_err(|error| OperationFailure {
+ stage: ApplyStage::ValidateRoot,
+ path: root.path.clone(),
+ error,
+ })?;
+ current.path.push(segment);
+ match fs::symlink_metadata(¤t.path) {
+ Ok(metadata) => require_real_directory(¤t.path, &metadata)?,
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {
+ create_directory_if_missing(¤t.path, journal)?;
+ }
+ Err(error) => {
+ return Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: current.path,
+ error,
+ });
+ }
+ }
+ }
+ Ok(current)
+}
+
+fn invalid_planned_parent(root: &Path, relative: &Path) -> OperationFailure {
+ OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: root.join(relative),
+ error: io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "planned parent is not a normalized relative path",
+ ),
+ }
+}
+
+#[cfg(not(windows))]
+fn create_directory_if_missing(
+ directory: &Path,
+ journal: &mut CreationJournal,
+) -> Result<(), OperationFailure> {
+ match fs::create_dir(directory) {
+ Ok(()) => record_created_directory(directory, journal),
+ Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {
+ // Another creator won the race. Accept only a real directory and
+ // do not journal it: this invocation does not own that path.
+ let metadata = fs::symlink_metadata(directory).map_err(|error| OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: directory.to_path_buf(),
+ error,
+ })?;
+ require_real_directory(directory, &metadata)
+ }
+ Err(error) => Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: directory.to_path_buf(),
+ error,
+ }),
+ }
+}
+
+fn require_real_directory(
+ directory: &Path,
+ metadata: &fs::Metadata,
+) -> Result<(), OperationFailure> {
+ if metadata.file_type().is_dir() {
+ Ok(())
+ } else {
+ Err(OperationFailure {
+ stage: ApplyStage::CreateDirectory,
+ path: directory.to_path_buf(),
+ error: io::Error::new(
+ io::ErrorKind::NotADirectory,
+ "path exists but is not a real directory",
+ ),
+ })
+ }
+}
+
+#[cfg(unix)]
+fn open_directory_path(path: &Path) -> io::Result {
+ let descriptor = rustix::fs::openat(
+ rustix::fs::CWD,
+ path,
+ rustix::fs::OFlags::RDONLY
+ | rustix::fs::OFlags::DIRECTORY
+ | rustix::fs::OFlags::NOFOLLOW
+ | rustix::fs::OFlags::CLOEXEC,
+ rustix::fs::Mode::empty(),
+ )?;
+ Ok(fs::File::from(descriptor))
+}
+
+#[cfg(windows)]
+fn open_directory_path(path: &Path) -> io::Result {
+ open_windows_entry_path(path)
+}
+
+#[cfg(windows)]
+fn open_windows_entry_path(path: &Path) -> io::Result {
+ use std::os::windows::fs::OpenOptionsExt;
+ use windows_sys::Win32::Storage::FileSystem::{FILE_SHARE_READ, FILE_SHARE_WRITE};
+
+ const FILE_FLAG_BACKUP_SEMANTICS: u32 = 0x0200_0000;
+ const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
+ OpenOptions::new()
+ .read(true)
+ // A retained directory handle is a filesystem capability on Windows.
+ // Denying delete sharing prevents the directory from being renamed or
+ // removed while descendant operations are resolved through it.
+ .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE)
+ .custom_flags(FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT)
+ .open(path)
+}
+
+#[cfg(windows)]
+fn create_windows_directory_at(parent: &cap_std::fs::Dir, name: &OsStr) -> io::Result {
+ use fs_at::os::windows::OpenOptionsExt as _;
+ use windows_sys::Wdk::Storage::FileSystem::{FILE_DIRECTORY_FILE, FILE_OPEN_REPARSE_POINT};
+ use windows_sys::Win32::Storage::FileSystem::{
+ FILE_LIST_DIRECTORY, FILE_READ_ATTRIBUTES, FILE_TRAVERSE, FILE_WRITE_ATTRIBUTES,
+ };
+
+ let parent = parent.try_clone()?.into_std_file();
+ let mut options = fs_at::OpenOptions::default();
+ options
+ .create_new(true)
+ .desired_access(
+ FILE_LIST_DIRECTORY | FILE_READ_ATTRIBUTES | FILE_TRAVERSE | FILE_WRITE_ATTRIBUTES,
+ )
+ // `mkdir_at` performs a second reparse probe after creating on
+ // Windows. Requesting FILE_CREATE through `open_at` gives us the
+ // created directory handle in one operation, so every mutation can be
+ // journaled even if later validation fails.
+ .create_options(FILE_DIRECTORY_FILE | FILE_OPEN_REPARSE_POINT);
+ options.open_at(&parent, name)
+}
+
+#[cfg(windows)]
+fn retain_windows_created_directory(
+ parent: &cap_std::fs::Dir,
+ name: &OsStr,
+ path: PathBuf,
+ created: fs::File,
+ journal: &mut CreationJournal,
+) -> Result {
+ use cap_fs_ext::DirExt as _;
+
+ let identity = match windows_identity_from_file(&created) {
+ Ok(identity) => identity,
+ Err(error) => {
+ journal
+ .directories
+ .push(JournalEntry::directory_without_identity_with_live_file(
+ path.clone(),
+ None,
+ created,
+ ));
+ return Err(OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path,
+ error,
+ });
+ }
+ };
+ let locked = match parent.open_dir_nofollow(name) {
+ Ok(locked) => locked,
+ Err(error) => {
+ journal
+ .directories
+ .push(JournalEntry::directory_with_live_file(
+ path.clone(),
+ Some(identity),
+ None,
+ created,
+ ));
+ return Err(OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path,
+ error,
+ });
+ }
+ };
+ let locked_identity = match windows_identity_from_directory(&locked) {
+ Ok(identity) => identity,
+ Err(error) => {
+ journal
+ .directories
+ .push(JournalEntry::directory_with_live_file(
+ path.clone(),
+ Some(identity),
+ None,
+ created,
+ ));
+ return Err(OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path,
+ error,
+ });
+ }
+ };
+ if locked_identity != identity {
+ journal
+ .directories
+ .push(JournalEntry::directory_with_live_file(
+ path.clone(),
+ Some(identity),
+ None,
+ created,
+ ));
+ return Err(OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path,
+ error: io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "created directory identity changed before it could be pinned",
+ ),
+ });
+ }
+
+ let live = match locked.try_clone().map(cap_std::fs::Dir::into_std_file) {
+ Ok(live) => live,
+ Err(error) => {
+ journal
+ .directories
+ .push(JournalEntry::directory_with_live_file(
+ path.clone(),
+ Some(identity),
+ None,
+ created,
+ ));
+ return Err(OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path,
+ error,
+ });
+ }
+ };
+ journal
+ .directories
+ .push(JournalEntry::directory_with_live_file(
+ path,
+ Some(identity),
+ None,
+ live,
+ ));
+ Ok(locked)
+}
+
+#[cfg(not(any(unix, windows)))]
+fn open_directory_path(path: &Path) -> io::Result {
+ fs::File::open(path)
+}
+
+#[cfg(unix)]
+fn open_directory_at(parent: &fs::File, name: &OsStr) -> io::Result {
+ let descriptor = rustix::fs::openat(
+ parent,
+ name,
+ rustix::fs::OFlags::RDONLY
+ | rustix::fs::OFlags::DIRECTORY
+ | rustix::fs::OFlags::NOFOLLOW
+ | rustix::fs::OFlags::CLOEXEC,
+ rustix::fs::Mode::empty(),
+ )?;
+ Ok(fs::File::from(descriptor))
+}
+
+#[cfg(unix)]
+fn create_directory_at(parent: &fs::File, name: &OsStr) -> io::Result<()> {
+ Ok(rustix::fs::mkdirat(
+ parent,
+ name,
+ rustix::fs::Mode::from_raw_mode(0o777),
+ )?)
+}
+
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "macos"))]
+fn rename_noreplace_at(
+ from_parent: &fs::File,
+ from: &OsStr,
+ to_parent: &fs::File,
+ to: &OsStr,
+) -> io::Result<()> {
+ Ok(rustix::fs::renameat_with(
+ from_parent,
+ from,
+ to_parent,
+ to,
+ rustix::fs::RenameFlags::NOREPLACE,
+ )?)
+}
+
+#[cfg(all(
+ unix,
+ not(any(target_os = "linux", target_os = "android", target_os = "macos"))
+))]
+fn rename_noreplace_at(
+ _from_parent: &fs::File,
+ _from: &OsStr,
+ _to_parent: &fs::File,
+ _to: &OsStr,
+) -> io::Result<()> {
+ Err(io::Error::new(
+ io::ErrorKind::Unsupported,
+ "atomic no-replace restore is unavailable on this Unix platform",
+ ))
+}
+
+#[cfg(unix)]
+fn identity_at(parent: &fs::File, name: &OsStr) -> io::Result {
+ let metadata = rustix::fs::statat(parent, name, rustix::fs::AtFlags::SYMLINK_NOFOLLOW)?;
+ Ok(EntryIdentity {
+ volume: stat_identity_part(metadata.st_dev)?,
+ file: stat_identity_part(metadata.st_ino)?,
+ })
+}
+
+#[cfg(unix)]
+fn stat_identity_part(value: T) -> io::Result
+where
+ T: TryInto,
+ T::Error: fmt::Display,
+{
+ value.try_into().map_err(|error| {
+ io::Error::new(
+ io::ErrorKind::InvalidData,
+ format!("filesystem identity does not fit u64: {error}"),
+ )
+ })
+}
+
+#[cfg(unix)]
+fn unlink_at(parent: &fs::File, name: &OsStr, kind: CreatedPathKind) -> io::Result<()> {
+ let flags = match kind {
+ CreatedPathKind::File => rustix::fs::AtFlags::empty(),
+ CreatedPathKind::Directory => rustix::fs::AtFlags::REMOVEDIR,
+ };
+ Ok(rustix::fs::unlinkat(parent, name, flags)?)
+}
+
+#[derive(Debug)]
+struct PathAnchor {
+ #[cfg(unix)]
+ parent: fs::File,
+ #[cfg(unix)]
+ name: OsString,
+}
+
+#[cfg(unix)]
+fn path_anchor(path: &Path) -> io::Result {
+ let parent = path
+ .parent()
+ .filter(|path| !path.as_os_str().is_empty())
+ .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidInput, "created path has no parent"))?;
+ let name = path.file_name().ok_or_else(|| {
+ io::Error::new(io::ErrorKind::InvalidInput, "created path has no file name")
+ })?;
+ Ok(PathAnchor {
+ parent: open_directory_path(parent)?,
+ name: name.to_os_string(),
+ })
+}
+
+#[cfg(not(any(unix, windows)))]
+fn path_anchor(_path: &Path) -> io::Result {
+ Ok(PathAnchor {})
+}
+
+#[cfg(unix)]
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+struct EntryIdentity {
+ volume: u64,
+ file: u64,
+}
+
+#[cfg(windows)]
+type EntryIdentity = same_file::Handle;
+
+#[cfg(not(any(unix, windows)))]
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+struct EntryIdentity;
+
+#[cfg(unix)]
+fn entry_identity(metadata: &fs::Metadata) -> Option {
+ use std::os::unix::fs::MetadataExt;
+
+ Some(EntryIdentity {
+ volume: metadata.dev(),
+ file: metadata.ino(),
+ })
+}
+
+#[cfg(not(any(unix, windows)))]
+fn entry_identity(_metadata: &fs::Metadata) -> Option {
+ None
+}
+
+#[cfg(unix)]
+fn journal_identity_from_file(file: &fs::File) -> io::Result> {
+ file.metadata().map(|metadata| entry_identity(&metadata))
+}
+
+#[cfg(windows)]
+fn windows_identity_from_file(file: &fs::File) -> io::Result {
+ same_file::Handle::from_file(file.try_clone()?)
+}
+
+#[cfg(windows)]
+fn windows_identity_from_directory(directory: &cap_std::fs::Dir) -> io::Result {
+ let file = directory.try_clone()?.into_std_file();
+ windows_identity_from_file(&file)
+}
+
+#[cfg(windows)]
+fn windows_file_matches_identity(file: &fs::File, expected: &EntryIdentity) -> io::Result {
+ windows_identity_from_file(file).map(|current| ¤t == expected)
+}
+
+#[cfg(windows)]
+fn windows_path_matches_identity(path: &Path, expected: &EntryIdentity) -> io::Result {
+ let current = open_windows_entry_path(path)?;
+ windows_file_matches_identity(¤t, expected)
+}
+
+#[cfg(windows)]
+fn journal_identity_from_file(file: &fs::File) -> io::Result> {
+ windows_identity_from_file(file).map(Some)
+}
+
+#[cfg(not(any(unix, windows)))]
+fn journal_identity_from_file(file: &fs::File) -> io::Result> {
+ file.metadata().map(|_| None)
+}
+
+#[cfg(unix)]
+fn journal_identity_from_directory(
+ _path: &Path,
+ metadata: &fs::Metadata,
+) -> io::Result> {
+ Ok(entry_identity(metadata))
+}
+
+#[cfg(not(any(unix, windows)))]
+fn journal_identity_from_directory(
+ _path: &Path,
+ metadata: &fs::Metadata,
+) -> io::Result> {
+ Ok(entry_identity(metadata))
+}
+
+#[cfg(all(windows, test))]
+fn identity_from_path(path: &Path) -> io::Result> {
+ let entry = open_windows_entry_path(path)?;
+ windows_identity_from_file(&entry).map(Some)
+}
+
+#[cfg(not(any(unix, windows)))]
+fn identity_from_path(path: &Path) -> io::Result> {
+ fs::symlink_metadata(path).map(|metadata| entry_identity(&metadata))
+}
+
+#[derive(Debug)]
+struct JournalEntry {
+ path: PathBuf,
+ #[cfg_attr(windows, allow(dead_code))]
+ identity: Option,
+ _live_file: Option,
+ #[cfg_attr(windows, allow(dead_code))]
+ anchor: Option,
+}
+
+impl JournalEntry {
+ #[cfg(not(windows))]
+ fn directory(
+ path: PathBuf,
+ identity: Option,
+ anchor: Option,
+ ) -> Self {
+ Self {
+ path,
+ identity,
+ _live_file: None,
+ anchor,
+ }
+ }
+
+ fn file(
+ path: PathBuf,
+ file: fs::File,
+ identity: Option,
+ anchor: Option,
+ ) -> Self {
+ Self {
+ path,
+ identity,
+ _live_file: Some(file),
+ anchor,
+ }
+ }
+
+ #[cfg(not(windows))]
+ fn directory_without_identity(path: PathBuf, anchor: Option) -> Self {
+ Self {
+ path,
+ identity: None,
+ _live_file: None,
+ anchor,
+ }
+ }
+
+ #[cfg(windows)]
+ fn directory_with_live_file(
+ path: PathBuf,
+ identity: Option,
+ anchor: Option,
+ live_file: fs::File,
+ ) -> Self {
+ Self {
+ path,
+ identity,
+ _live_file: Some(live_file),
+ anchor,
+ }
+ }
+
+ #[cfg(windows)]
+ fn directory_without_identity_with_live_file(
+ path: PathBuf,
+ anchor: Option,
+ live_file: fs::File,
+ ) -> Self {
+ Self::directory_with_live_file(path, None, anchor, live_file)
+ }
+}
+
+#[cfg(not(windows))]
+fn record_created_directory(
+ directory: &Path,
+ journal: &mut CreationJournal,
+) -> Result<(), OperationFailure> {
+ let anchor = path_anchor(directory).map_err(|error| {
+ journal
+ .directories
+ .push(JournalEntry::directory_without_identity(
+ directory.to_path_buf(),
+ None,
+ ));
+ OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: directory.to_path_buf(),
+ error,
+ }
+ })?;
+ match fs::symlink_metadata(directory) {
+ Ok(metadata) => match journal_identity_from_directory(directory, &metadata) {
+ Ok(identity) => {
+ journal.directories.push(JournalEntry::directory(
+ directory.to_path_buf(),
+ identity,
+ Some(anchor),
+ ));
+ Ok(())
+ }
+ Err(error) => {
+ journal
+ .directories
+ .push(JournalEntry::directory_without_identity(
+ directory.to_path_buf(),
+ Some(anchor),
+ ));
+ Err(OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: directory.to_path_buf(),
+ error,
+ })
+ }
+ },
+ Err(error) => {
+ journal
+ .directories
+ .push(JournalEntry::directory_without_identity(
+ directory.to_path_buf(),
+ Some(anchor),
+ ));
+ Err(OperationFailure {
+ stage: ApplyStage::RecordOwnership,
+ path: directory.to_path_buf(),
+ error,
+ })
+ }
+ }
+}
+
+#[derive(Debug, Default)]
+struct CreationJournal {
+ files: Vec,
+ directories: Vec,
+}
+
+fn failed(
+ stage: ApplyStage,
+ path: impl Into,
+ source: io::Error,
+ journal: CreationJournal,
+) -> ApplyError {
+ ApplyError {
+ stage,
+ path: path.into(),
+ source,
+ rollback: journal.rollback(),
+ }
+}
+
+impl CreationJournal {
+ fn rollback(self) -> RollbackReport {
+ let mut residuals = Vec::new();
+
+ for entry in self.files.into_iter().rev() {
+ rollback_entry(entry, CreatedPathKind::File, &mut residuals);
+ }
+ for entry in self.directories.into_iter().rev() {
+ rollback_entry(entry, CreatedPathKind::Directory, &mut residuals);
+ }
+
+ RollbackReport { residuals }
+ }
+}
+
+fn rollback_entry(
+ entry: JournalEntry,
+ kind: CreatedPathKind,
+ residuals: &mut Vec,
+) {
+ #[cfg(windows)]
+ {
+ // Windows has no safe, stable, no-replace restore primitive in the
+ // APIs used by this crate. In particular, `std::fs::rename` may replace
+ // its destination. Preserve every known creation and report it rather
+ // than risk removing or overwriting a concurrent replacement. The
+ // recorded path is the logical creation path; another process may have
+ // moved the entry after its retained handle is released.
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error: io::Error::other(
+ "Windows rollback is intentionally non-mutating; the created entry was preserved and its recorded path may no longer be current",
+ ),
+ });
+ }
+
+ #[cfg(not(windows))]
+ if kind == CreatedPathKind::Directory {
+ // `mkdir`/`mkdirat` does not return a live handle. A concurrent actor
+ // can move the new directory and install another directory before we
+ // open and record its identity. Never remove a directory based on that
+ // post-create observation: the replacement may belong to somebody
+ // else. The logical path is still useful for cleanup guidance, though
+ // it may no longer name the invocation-created directory.
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error: io::Error::other(
+ "directory rollback is intentionally non-mutating because directory creation cannot be atomically bound to an ownership handle; the recorded path may no longer be current",
+ ),
+ });
+ return;
+ }
+
+ #[cfg(not(windows))]
+ if entry.identity.is_none() {
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error: io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "created path has no stable identity; preserved it during rollback",
+ ),
+ });
+ return;
+ }
+
+ #[cfg(unix)]
+ if entry.anchor.is_some() {
+ rollback_anchored_unix(entry, kind, residuals);
+ } else {
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error: io::Error::other(
+ "created path lost its retained parent anchor; preserved it during rollback",
+ ),
+ });
+ }
+
+ #[cfg(not(any(unix, windows)))]
+ rollback_quarantined_path(entry, kind, residuals);
+}
+
+#[cfg(not(windows))]
+fn quarantine_name() -> OsString {
+ OsString::from(format!(
+ ".spock-rollback-{}-{}",
+ std::process::id(),
+ NEXT_QUARANTINE.fetch_add(1, Ordering::Relaxed)
+ ))
+}
+
+#[cfg(unix)]
+fn move_to_quarantine_at(parent: &fs::File, source: &OsStr) -> io::Result {
+ loop {
+ let quarantine = quarantine_name();
+ match rename_noreplace_at(parent, source, parent, &quarantine) {
+ Ok(()) => return Ok(quarantine),
+ Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue,
+ Err(error) => return Err(error),
+ }
+ }
+}
+
+#[cfg(unix)]
+fn rollback_anchored_unix(
+ entry: JournalEntry,
+ kind: CreatedPathKind,
+ residuals: &mut Vec,
+) {
+ let anchor = entry.anchor.as_ref().expect("checked anchored entry");
+ let quarantine_name = match move_to_quarantine_at(&anchor.parent, &anchor.name) {
+ Ok(quarantine) => quarantine,
+ Err(error) if error.kind() == io::ErrorKind::NotFound => return,
+ Err(error) => {
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error,
+ });
+ return;
+ }
+ };
+ let quarantine_path = entry
+ .path
+ .parent()
+ .unwrap_or_else(|| Path::new("."))
+ .join(&quarantine_name);
+
+ let current_identity = identity_at(&anchor.parent, &quarantine_name);
+ if current_identity
+ .as_ref()
+ .is_ok_and(|identity| entry.identity.as_ref() == Some(identity))
+ {
+ let removal = unlink_at(&anchor.parent, &quarantine_name, kind);
+ if let Err(error) = removal {
+ match rename_noreplace_at(
+ &anchor.parent,
+ &quarantine_name,
+ &anchor.parent,
+ &anchor.name,
+ ) {
+ Ok(()) => {
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error,
+ });
+ }
+ Err(restore_error) => residuals.push(RollbackResidual {
+ path: quarantine_path,
+ kind,
+ error: io::Error::new(
+ restore_error.kind(),
+ format!(
+ "could not remove invocation-owned path or restore it from rollback quarantine ({error}; {restore_error})"
+ ),
+ ),
+ }),
+ }
+ return;
+ }
+ return;
+ }
+
+ let identity_error = current_identity.err();
+ match rename_noreplace_at(
+ &anchor.parent,
+ &quarantine_name,
+ &anchor.parent,
+ &anchor.name,
+ ) {
+ Ok(()) => {
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error: identity_error.unwrap_or_else(|| {
+ io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "path identity changed after creation; restored concurrent replacement",
+ )
+ }),
+ });
+ }
+ Err(restore_error) => {
+ residuals.push(RollbackResidual {
+ path: quarantine_path,
+ kind,
+ error: io::Error::new(
+ restore_error.kind(),
+ format!(
+ "path identity changed; preserved replacement in rollback quarantine ({restore_error})"
+ ),
+ ),
+ });
+ }
+ }
+}
+
+#[cfg(not(any(unix, windows)))]
+fn rollback_quarantined_path(
+ entry: JournalEntry,
+ kind: CreatedPathKind,
+ residuals: &mut Vec,
+) {
+ let parent = entry.path.parent().unwrap_or_else(|| Path::new("."));
+ let (quarantine_path, quarantined_entry) = loop {
+ let quarantine_path = parent.join(quarantine_name());
+ match fs::create_dir(&quarantine_path) {
+ Ok(()) => break (quarantine_path.clone(), quarantine_path.join("entry")),
+ Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue,
+ Err(error) => {
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error,
+ });
+ return;
+ }
+ }
+ };
+
+ if let Err(error) = fs::rename(&entry.path, &quarantined_entry) {
+ let _ = fs::remove_dir(&quarantine_path);
+ if error.kind() != io::ErrorKind::NotFound {
+ residuals.push(RollbackResidual {
+ path: entry.path,
+ kind,
+ error,
+ });
+ }
+ return;
+ }
+
+ let current_identity = identity_from_path(&quarantined_entry).ok().flatten();
+ if current_identity.as_ref() == entry.identity.as_ref() {
+ let removal = match kind {
+ CreatedPathKind::File => fs::remove_file(&quarantined_entry),
+ CreatedPathKind::Directory => fs::remove_dir(&quarantined_entry),
+ };
+ if let Err(error) = removal {
+ residuals.push(RollbackResidual {
+ path: quarantined_entry,
+ kind,
+ error,
+ });
+ return;
+ }
+ let _ = fs::remove_dir(quarantine_path);
+ return;
+ }
+
+ residuals.push(RollbackResidual {
+ path: quarantined_entry,
+ kind,
+ error: io::Error::new(
+ io::ErrorKind::AlreadyExists,
+ "path identity changed; preserved replacement in rollback quarantine",
+ ),
+ });
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::sync::atomic::{AtomicU64, Ordering};
+
+ use spock_project::{adoption_plan, scaffold_plan, ProjectInventory};
+
+ static NEXT_TEST_DIRECTORY: AtomicU64 = AtomicU64::new(0);
+
+ struct TestDirectory(PathBuf);
+
+ impl TestDirectory {
+ fn new() -> Self {
+ loop {
+ let id = NEXT_TEST_DIRECTORY.fetch_add(1, Ordering::Relaxed);
+ let path = std::env::temp_dir()
+ .join(format!("spock-write-plan-{}-{id}", std::process::id()));
+ match fs::create_dir(&path) {
+ Ok(()) => return Self(path),
+ Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue,
+ Err(error) => panic!("could not create test directory: {error}"),
+ }
+ }
+ }
+
+ fn path(&self) -> &Path {
+ &self.0
+ }
+ }
+
+ impl Drop for TestDirectory {
+ fn drop(&mut self) {
+ let _ = fs::remove_dir_all(&self.0);
+ }
+ }
+
+ #[test]
+ fn applies_scaffold_with_manifest_last_and_reports_exact_effects() {
+ let temporary = TestDirectory::new();
+ let destination = temporary.path().join("demo");
+ let plan = scaffold_plan(&destination, "demo", None).unwrap();
+
+ let summary = apply_write_plan(&plan, RootPolicy::NewDestination).unwrap();
+
+ assert_eq!(summary.root(), destination);
+ assert_eq!(
+ summary.created_files(),
+ [
+ destination.join("backend/app.spock"),
+ destination.join(MANIFEST_FILE),
+ ]
+ );
+ assert_eq!(
+ summary.created_directories(),
+ [destination.clone(), destination.join("backend")]
+ );
+ assert!(destination.join("backend/app.spock").is_file());
+ assert!(destination.join(MANIFEST_FILE).is_file());
+ }
+
+ #[test]
+ fn new_destination_may_create_and_reports_missing_parent_directories() {
+ let temporary = TestDirectory::new();
+ let parent = temporary.path().join("nested");
+ let destination = parent.join("demo");
+ let plan = scaffold_plan(&destination, "demo", None).unwrap();
+
+ let summary = apply_write_plan(&plan, RootPolicy::NewDestination).unwrap();
+
+ assert_eq!(
+ summary.created_directories(),
+ [parent, destination.clone(), destination.join("backend"),]
+ );
+ }
+
+ #[test]
+ fn existing_new_destination_is_never_modified() {
+ let temporary = TestDirectory::new();
+ let destination = temporary.path().join("demo");
+ fs::create_dir(&destination).unwrap();
+ fs::write(destination.join("owned.txt"), "keep").unwrap();
+ let plan = scaffold_plan(&destination, "demo", None).unwrap();
+
+ let error = apply_write_plan(&plan, RootPolicy::NewDestination).unwrap_err();
+
+ assert_eq!(error.stage(), ApplyStage::CreateRoot);
+ assert_eq!(error.io_error().kind(), io::ErrorKind::AlreadyExists);
+ assert!(error.rollback().is_complete());
+ assert_eq!(
+ fs::read_to_string(destination.join("owned.txt")).unwrap(),
+ "keep"
+ );
+ assert!(!destination.join(MANIFEST_FILE).exists());
+ }
+
+ #[test]
+ fn adoption_conflict_rolls_back_created_files_but_preserves_racer_file() {
+ let temporary = TestDirectory::new();
+ let inventory = ProjectInventory::scan(temporary.path()).unwrap();
+ let plan = adoption_plan(&inventory, Some("demo")).unwrap();
+ let racer_manifest = plan.root.join(MANIFEST_FILE);
+ fs::write(&racer_manifest, "racer-owned\n").unwrap();
+
+ let error = apply_write_plan(&plan, RootPolicy::ExistingAdoptionRoot).unwrap_err();
+
+ assert_eq!(error.stage(), ApplyStage::CreateFile);
+ assert_eq!(error.path(), racer_manifest);
+ assert_eq!(error.io_error().kind(), io::ErrorKind::AlreadyExists);
+ assert_eq!(fs::read_to_string(racer_manifest).unwrap(), "racer-owned\n");
+ #[cfg(not(windows))]
+ {
+ assert_eq!(error.rollback().residuals().len(), 1);
+ let residual = &error.rollback().residuals()[0];
+ assert_eq!(residual.kind(), CreatedPathKind::Directory);
+ assert_eq!(residual.path(), plan.root.join("backend"));
+ assert!(!plan.root.join("backend/app.spock").exists());
+ assert!(plan.root.join("backend").is_dir());
+ }
+ #[cfg(windows)]
+ {
+ let residuals = error
+ .rollback()
+ .residuals()
+ .iter()
+ .map(|residual| (residual.path().to_path_buf(), residual.kind()))
+ .collect::>();
+ assert_eq!(
+ residuals,
+ std::collections::BTreeSet::from([
+ (plan.root.join("backend/app.spock"), CreatedPathKind::File,),
+ (plan.root.join("backend"), CreatedPathKind::Directory),
+ ])
+ );
+ assert!(plan.root.join("backend/app.spock").is_file());
+ assert!(plan.root.join("backend").is_dir());
+ assert!(fs::read_dir(&plan.root).unwrap().all(|entry| {
+ !entry
+ .unwrap()
+ .file_name()
+ .to_string_lossy()
+ .starts_with(".spock-rollback-")
+ }));
+ }
+ }
+
+ #[cfg(not(windows))]
+ #[test]
+ fn rollback_preserves_a_file_replaced_after_this_invocation_created_it() {
+ let temporary = TestDirectory::new();
+ let inventory = ProjectInventory::scan(temporary.path()).unwrap();
+ let plan = adoption_plan(&inventory, Some("demo")).unwrap();
+ fs::write(plan.root.join(MANIFEST_FILE), "racer-owned\n").unwrap();
+ let backend = plan.root.join("backend/app.spock");
+ let moved_invocation_file = temporary.path().join("invocation-file-moved-away");
+
+ let error = apply_write_plan_inner(&plan, RootPolicy::ExistingAdoptionRoot, |written| {
+ if written == backend {
+ fs::rename(written, &moved_invocation_file).unwrap();
+ fs::write(written, "replacement-owned-by-another-writer\n").unwrap();
+ }
+ })
+ .unwrap_err();
+
+ assert_eq!(
+ fs::read_to_string(&backend).unwrap(),
+ "replacement-owned-by-another-writer\n"
+ );
+ assert!(moved_invocation_file.is_file());
+ assert!(error.rollback().residuals().iter().any(|residual| {
+ residual.kind() == CreatedPathKind::File && residual.path() == backend
+ }));
+ }
+
+ #[cfg(windows)]
+ #[test]
+ fn windows_live_identity_distinguishes_a_replacement_from_the_retained_file() {
+ let temporary = TestDirectory::new();
+ let original = temporary.path().join("created.txt");
+ let moved = temporary.path().join("created-moved-away.txt");
+ let file = OpenOptions::new()
+ .write(true)
+ .create_new(true)
+ .open(&original)
+ .unwrap();
+ let original_identity = journal_identity_from_file(&file).unwrap().unwrap();
+
+ fs::rename(&original, &moved).unwrap();
+ fs::write(&original, "replacement-owned-by-another-writer\n").unwrap();
+
+ let replacement_identity = identity_from_path(&original).unwrap().unwrap();
+ let moved_identity = identity_from_path(&moved).unwrap().unwrap();
+ assert_ne!(original_identity, replacement_identity);
+ assert_eq!(original_identity, moved_identity);
+ }
+
+ #[test]
+ fn rollback_reports_a_directory_that_gained_concurrent_content() {
+ let temporary = TestDirectory::new();
+ let inventory = ProjectInventory::scan(temporary.path()).unwrap();
+ let plan = adoption_plan(&inventory, Some("demo")).unwrap();
+ fs::write(plan.root.join(MANIFEST_FILE), "racer-owned\n").unwrap();
+ let concurrent_file = plan.root.join("backend/concurrent.txt");
+
+ let error = apply_write_plan_inner(&plan, RootPolicy::ExistingAdoptionRoot, |written| {
+ if written.ends_with("backend/app.spock") {
+ fs::write(&concurrent_file, "keep").unwrap();
+ }
+ })
+ .unwrap_err();
+
+ assert_eq!(fs::read_to_string(concurrent_file).unwrap(), "keep");
+ #[cfg(not(windows))]
+ {
+ assert_eq!(error.rollback().residuals().len(), 1);
+ let residual = &error.rollback().residuals()[0];
+ assert_eq!(residual.kind(), CreatedPathKind::Directory);
+ assert_eq!(residual.path(), plan.root.join("backend"));
+ assert!(!plan.root.join("backend/app.spock").exists());
+ }
+ #[cfg(windows)]
+ {
+ assert_eq!(error.rollback().residuals().len(), 2);
+ assert!(plan.root.join("backend/app.spock").is_file());
+ }
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn writes_remain_confined_to_the_pinned_root_after_path_replacement() {
+ use std::os::unix::fs::symlink;
+
+ let temporary = TestDirectory::new();
+ let temporary_root = fs::canonicalize(temporary.path()).unwrap();
+ let project = temporary_root.join("project");
+ let moved_project = temporary_root.join("moved-project");
+ let replacement_target = temporary_root.join("replacement-target");
+ fs::create_dir(&project).unwrap();
+ fs::create_dir(&replacement_target).unwrap();
+ let inventory = ProjectInventory::scan(&project).unwrap();
+ let plan = adoption_plan(&inventory, Some("demo")).unwrap();
+ let error = apply_write_plan_inner(&plan, RootPolicy::ExistingAdoptionRoot, |written| {
+ if written.ends_with(MANIFEST_FILE) {
+ fs::rename(&project, &moved_project).unwrap();
+ symlink(&replacement_target, &project).unwrap();
+ }
+ })
+ .unwrap_err();
+
+ assert_eq!(error.stage(), ApplyStage::ValidateRoot);
+ assert_eq!(error.rollback().residuals().len(), 1);
+ assert_eq!(
+ error.rollback().residuals()[0].path(),
+ project.join("backend")
+ );
+ assert!(!moved_project.join("backend/app.spock").exists());
+ assert!(!moved_project.join(MANIFEST_FILE).exists());
+ assert!(moved_project.join("backend").is_dir());
+ assert!(fs::read_dir(&replacement_target).unwrap().next().is_none());
+ }
+
+ #[cfg(windows)]
+ #[test]
+ fn windows_pinned_root_blocks_replacement_until_the_lease_is_dropped() {
+ let temporary = TestDirectory::new();
+ let project = temporary.path().join("project");
+ let moved_project = temporary.path().join("moved-project");
+ fs::create_dir(&project).unwrap();
+ let root = PinnedRoot::open(&project).unwrap();
+
+ let error = fs::rename(&project, &moved_project).unwrap_err();
+ assert!(matches!(
+ error.kind(),
+ io::ErrorKind::PermissionDenied | io::ErrorKind::Other
+ ));
+ assert!(project.is_dir());
+
+ drop(root);
+ fs::rename(&project, &moved_project).unwrap();
+ fs::create_dir(&project).unwrap();
+ assert!(fs::read_dir(&project).unwrap().next().is_none());
+ assert!(moved_project.is_dir());
+ }
+
+ #[test]
+ fn prepared_target_mismatch_fails_before_mutation() {
+ let temporary = TestDirectory::new();
+ let destination = temporary.path().join("demo");
+ let plan = scaffold_plan(&destination, "demo", None).unwrap();
+ let parent = PreparedWriteRoot::open(temporary.path()).unwrap();
+
+ let error =
+ apply_prepared_write_plan(&plan, PreparedWriteTarget::new_child(parent, "different"))
+ .unwrap_err();
+
+ assert_eq!(error.stage(), ApplyStage::ValidatePolicy);
+ assert_eq!(error.io_error().kind(), io::ErrorKind::InvalidInput);
+ assert!(error.rollback().is_complete());
+ assert!(!destination.exists());
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn prepared_inventory_reads_the_retained_root_across_a_path_aba() {
+ let temporary = TestDirectory::new();
+ let project = temporary.path().join("project");
+ let moved_project = temporary.path().join("moved-project");
+ fs::create_dir(&project).unwrap();
+ fs::write(project.join("original.spock"), "").unwrap();
+ let prepared = PreparedWriteRoot::open(&project).unwrap();
+
+ fs::rename(&project, &moved_project).unwrap();
+ fs::create_dir(&project).unwrap();
+ fs::write(project.join("foreign.spock"), "").unwrap();
+ let inventory = prepared.inventory().unwrap();
+
+ fs::remove_dir_all(&project).unwrap();
+ fs::rename(&moved_project, &project).unwrap();
+ prepared.validate().unwrap();
+ let paths = inventory
+ .entries()
+ .map(|(path, _)| path.as_str())
+ .collect::>();
+ assert_eq!(paths, ["original.spock"]);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn prepared_inventory_preserves_unsupported_entry_kinds() {
+ use std::os::unix::net::UnixListener;
+
+ let temporary = TestDirectory::new();
+ let socket_path = temporary.path().join("app.spock");
+ let _socket = UnixListener::bind(&socket_path).unwrap();
+ let prepared = PreparedWriteRoot::open(temporary.path()).unwrap();
+
+ let inventory = prepared.inventory().unwrap();
+ let socket = NormalizedRelativePath::file("app.spock").unwrap();
+ assert_eq!(
+ inventory.kind(&socket),
+ Some(InventoryEntryKind::Unsupported)
+ );
+ }
+
+ #[cfg(windows)]
+ #[test]
+ fn windows_prepared_parent_and_created_entries_stay_leased_through_commit() {
+ let temporary = TestDirectory::new();
+ let workspace = temporary.path().join("workspace");
+ let moved_workspace = temporary.path().join("moved-workspace");
+ fs::create_dir(&workspace).unwrap();
+ let parent = PreparedWriteRoot::open(&workspace).unwrap();
+ assert!(fs::rename(&workspace, &moved_workspace).is_err());
+
+ let destination = workspace.join("demo");
+ let moved_root = workspace.join("moved-demo");
+ let moved_backend = destination.join("moved-backend");
+ let moved_file = destination.join("backend/moved-app.spock");
+ let backend = destination.join("backend");
+ let backend_file = backend.join("app.spock");
+ let plan = scaffold_plan(&destination, "demo", None).unwrap();
+ let mut root_rename_blocked = false;
+ let mut directory_rename_blocked = false;
+ let mut file_rename_blocked = false;
+
+ let summary = apply_write_plan_inner_with_target(
+ &plan,
+ RootPolicy::NewDestination,
+ Some(PreparedWriteTarget::new_child(parent, "demo")),
+ |written| {
+ if written == backend_file {
+ root_rename_blocked = fs::rename(&destination, &moved_root).is_err();
+ directory_rename_blocked = fs::rename(&backend, &moved_backend).is_err();
+ file_rename_blocked = fs::rename(&backend_file, &moved_file).is_err();
+ }
+ },
+ )
+ .unwrap();
+
+ assert!(root_rename_blocked);
+ assert!(directory_rename_blocked);
+ assert!(file_rename_blocked);
+ assert_eq!(summary.root(), destination);
+ assert!(backend_file.is_file());
+ assert!(destination.join(MANIFEST_FILE).is_file());
+ }
+
+ #[test]
+ fn root_policy_mismatch_fails_before_mutation() {
+ let temporary = TestDirectory::new();
+ let destination = temporary.path().join("demo");
+ let plan = scaffold_plan(&destination, "demo", None).unwrap();
+
+ let error = apply_write_plan(&plan, RootPolicy::ExistingAdoptionRoot).unwrap_err();
+
+ assert_eq!(error.stage(), ApplyStage::ValidatePolicy);
+ assert_eq!(error.io_error().kind(), io::ErrorKind::InvalidInput);
+ assert!(error.rollback().is_complete());
+ assert!(!destination.exists());
+ }
+}
diff --git a/crates/spock-cli/tests/cli.rs b/crates/spock-cli/tests/cli.rs
index 0b6bf9e..f1a131e 100644
--- a/crates/spock-cli/tests/cli.rs
+++ b/crates/spock-cli/tests/cli.rs
@@ -3,6 +3,9 @@
use assert_cmd::Command;
use predicates::prelude::*;
+#[cfg(unix)]
+use assert_cmd::prelude::CommandCargoExt;
+
fn spock() -> Command {
Command::cargo_bin("spock").expect("binary builds")
}
@@ -13,6 +16,68 @@ fn write_program(dir: &std::path::Path, source: &str) -> std::path::PathBuf {
path
}
+#[cfg(unix)]
+fn assert_sigterm_shutdown(cwd: &std::path::Path, command_name: &str, arguments: &[&str]) {
+ use std::net::{TcpListener, TcpStream};
+ use std::process::Stdio;
+ use std::thread;
+ use std::time::{Duration, Instant};
+
+ let probe = TcpListener::bind(("127.0.0.1", 0)).unwrap();
+ let port = probe.local_addr().unwrap().port();
+ drop(probe);
+
+ let mut command = std::process::Command::cargo_bin("spock").unwrap();
+ let mut child = command
+ .current_dir(cwd)
+ .arg(command_name)
+ .args(arguments)
+ .args(["--port", &port.to_string()])
+ .stdout(Stdio::null())
+ .stderr(Stdio::null())
+ .spawn()
+ .unwrap();
+
+ let ready_deadline = Instant::now() + Duration::from_secs(5);
+ loop {
+ if TcpStream::connect(("127.0.0.1", port)).is_ok() {
+ break;
+ }
+ if let Some(status) = child.try_wait().unwrap() {
+ panic!("server exited before readiness: {status}");
+ }
+ if Instant::now() >= ready_deadline {
+ child.kill().ok();
+ child.wait().ok();
+ panic!("server did not become ready");
+ }
+ thread::sleep(Duration::from_millis(25));
+ }
+
+ let signal = std::process::Command::new("kill")
+ .args(["-TERM", &child.id().to_string()])
+ .status()
+ .unwrap();
+ assert!(signal.success());
+
+ let shutdown_deadline = Instant::now() + Duration::from_secs(2);
+ let status = loop {
+ if let Some(status) = child.try_wait().unwrap() {
+ break status;
+ }
+ if Instant::now() >= shutdown_deadline {
+ child.kill().ok();
+ child.wait().ok();
+ panic!("server did not terminate after SIGTERM");
+ }
+ thread::sleep(Duration::from_millis(25));
+ };
+ assert!(status.success(), "server exited with {status}");
+
+ let rebound = TcpListener::bind(("127.0.0.1", port)).unwrap();
+ drop(rebound);
+}
+
#[test]
fn check_accepts_a_valid_program() {
let dir = std::env::temp_dir().join("spock-cli-test-ok");
@@ -48,6 +113,52 @@ fn check_renders_diagnostics_and_fails() {
.stderr(predicate::str::contains("app.spock:1:"));
}
+#[test]
+fn relative_standalone_diagnostics_keep_the_caller_spelling() {
+ let temporary = tempfile::tempdir().unwrap();
+ write_program(temporary.path(), "table a { x: nope }");
+
+ spock()
+ .current_dir(temporary.path())
+ .args(["check", "app.spock"])
+ .assert()
+ .failure()
+ .stderr(predicate::str::starts_with("app.spock:1:"))
+ .stderr(predicate::str::contains(temporary.path().to_string_lossy().as_ref()).not());
+}
+
+#[cfg(unix)]
+#[test]
+fn standalone_check_resolves_seed_assets_beside_a_symlink_spelling() {
+ use std::os::unix::fs::symlink;
+
+ let temporary = tempfile::tempdir().unwrap();
+ let source_root = temporary.path().join("source");
+ let invocation_root = temporary.path().join("invocation");
+ std::fs::create_dir(&source_root).unwrap();
+ std::fs::create_dir(&invocation_root).unwrap();
+ std::fs::write(
+ source_root.join("app.spock"),
+ "auth table user { key id: uuid = auto\n \
+ username: text unique\n avatar: storage_object? }\n\
+ seed { u = user { username: \"u\", avatar: file(\"./pic.png\") } }\n",
+ )
+ .unwrap();
+ std::fs::write(
+ invocation_root.join("pic.png"),
+ b"\x89PNG\r\n\x1a\nseed-bytes",
+ )
+ .unwrap();
+ symlink("../source/app.spock", invocation_root.join("app.spock")).unwrap();
+
+ spock()
+ .current_dir(invocation_root)
+ .args(["check", "app.spock"])
+ .assert()
+ .success()
+ .stdout(predicate::str::contains("1 seed row(s)"));
+}
+
#[test]
fn check_is_the_full_load_proof() {
// `check` now materializes in memory, so a body that compiles but
@@ -99,5 +210,148 @@ fn missing_file_is_a_clean_error() {
.args(["check", "/definitely/not/a/file.spock"])
.assert()
.failure()
- .stderr(predicate::str::contains("could not read"));
+ .stderr(predicate::str::starts_with("error: could not read"))
+ .stderr(predicate::str::contains("error: error:").not());
+}
+
+#[test]
+fn help_exposes_framework_commands_and_retained_file_tools() {
+ spock()
+ .arg("--help")
+ .assert()
+ .success()
+ .stdout(predicate::str::contains("new"))
+ .stdout(predicate::str::contains("init"))
+ .stdout(predicate::str::contains("start"))
+ .stdout(predicate::str::contains("dev"))
+ .stdout(predicate::str::contains("run"))
+ .stdout(predicate::str::contains("build"))
+ .stdout(predicate::str::contains("gen"));
+}
+
+#[test]
+fn new_defaults_to_a_checkable_full_stack_project() {
+ let temporary = tempfile::tempdir().unwrap();
+
+ spock()
+ .current_dir(temporary.path())
+ .args(["new", "demo"])
+ .assert()
+ .success()
+ .stdout(predicate::str::contains(
+ "created full-stack project `demo`",
+ ));
+
+ let project = temporary.path().join("demo");
+ assert!(project.join("spock.toml").is_file());
+ assert!(project.join("backend/app.spock").is_file());
+ assert!(project.join("client/uhura.toml").is_file());
+ spock()
+ .current_dir(&project)
+ .arg("check")
+ .assert()
+ .success()
+ .stdout(predicate::str::contains("ok: project `demo`"));
+}
+
+#[test]
+fn backend_only_new_omits_the_client_tree() {
+ let temporary = tempfile::tempdir().unwrap();
+
+ spock()
+ .current_dir(temporary.path())
+ .args(["new", "authority", "--backend-only"])
+ .assert()
+ .success()
+ .stdout(predicate::str::contains(
+ "created backend-only project `authority`",
+ ));
+
+ let project = temporary.path().join("authority");
+ assert!(!project.join("client").exists());
+ spock()
+ .current_dir(project)
+ .arg("check")
+ .assert()
+ .success()
+ .stdout(predicate::str::contains("backend only"));
+}
+
+#[test]
+fn next_step_text_is_not_an_executable_command() {
+ let temporary = tempfile::tempdir().unwrap();
+
+ spock()
+ .current_dir(temporary.path())
+ .args(["new", "demo;touch PWN", "--backend-only"])
+ .assert()
+ .success()
+ .stdout(predicate::str::contains(
+ "next: run `spock dev` from the project directory above",
+ ))
+ .stdout(predicate::str::contains("next: cd").not());
+
+ assert!(!temporary.path().join("PWN").exists());
+}
+
+#[test]
+fn project_check_deduplicates_shared_editor_and_play_diagnostics() {
+ let temporary = tempfile::tempdir().unwrap();
+ spock()
+ .current_dir(temporary.path())
+ .args(["new", "demo"])
+ .assert()
+ .success();
+ std::fs::write(
+ temporary.path().join("demo/client/app/home/page.uhura"),
+ "not valid uhura\n",
+ )
+ .unwrap();
+
+ let assertion = spock()
+ .current_dir(temporary.path().join("demo"))
+ .arg("check")
+ .assert()
+ .failure();
+ let stderr = String::from_utf8(assertion.get_output().stderr.clone()).unwrap();
+ let repeated = "`not` is not a definition kind";
+ assert_eq!(stderr.matches(repeated).count(), 1, "{stderr}");
+ assert!(stderr.contains("app/home/page.uhura:"), "{stderr}");
+}
+
+#[test]
+fn framework_serve_commands_reject_explicit_file_mode() {
+ let temporary = tempfile::tempdir().unwrap();
+ let source = write_program(temporary.path(), "");
+
+ for command in ["start", "dev"] {
+ spock()
+ .current_dir(temporary.path())
+ .args([command, source.to_str().unwrap()])
+ .assert()
+ .failure()
+ .stderr(predicate::str::contains("spock run"));
+ }
+}
+
+#[cfg(unix)]
+#[test]
+fn standalone_sigterm_shutdown_is_clean_and_releases_the_port() {
+ let temporary = tempfile::tempdir().unwrap();
+ write_program(temporary.path(), "");
+
+ assert_sigterm_shutdown(temporary.path(), "run", &["app.spock"]);
+}
+
+#[cfg(unix)]
+#[test]
+fn framework_sigterm_shutdown_is_clean_and_releases_the_port() {
+ let temporary = tempfile::tempdir().unwrap();
+ spock()
+ .current_dir(temporary.path())
+ .args(["new", "authority", "--backend-only"])
+ .assert()
+ .success();
+
+ assert_sigterm_shutdown(&temporary.path().join("authority"), "start", &[]);
}
diff --git a/crates/spock-host/.gitignore b/crates/spock-host/.gitignore
new file mode 100644
index 0000000..b83d222
--- /dev/null
+++ b/crates/spock-host/.gitignore
@@ -0,0 +1 @@
+/target/
diff --git a/crates/spock-host/Cargo.toml b/crates/spock-host/Cargo.toml
new file mode 100644
index 0000000..6c94da3
--- /dev/null
+++ b/crates/spock-host/Cargo.toml
@@ -0,0 +1,36 @@
+[package]
+name = "spock-host"
+description = "Project generation coordination and the combined Spock framework host"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+spock-lang = { path = "../spock-lang" }
+spock-project = { path = "../spock-project" }
+spock-runtime = { path = "../spock-runtime" }
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+axum.workspace = true
+tokio.workspace = true
+tokio-stream.workspace = true
+sha2.workspace = true
+unicode-normalization.workspace = true
+uuid.workspace = true
+uhura-host = { path = "../../uhura/crates/uhura-host" }
+cap-fs-ext = "4.0.2"
+cap-std = "4.0.2"
+
+[target.'cfg(unix)'.dependencies]
+rustix = { version = "1.1", features = ["fs"] }
+
+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem"] }
+
+[dev-dependencies]
+tempfile.workspace = true
+reqwest.workspace = true
+tower = { version = "0.5", features = ["util"] }
diff --git a/crates/spock-host/src/assets.rs b/crates/spock-host/src/assets.rs
new file mode 100644
index 0000000..6fc51c2
--- /dev/null
+++ b/crates/spock-host/src/assets.rs
@@ -0,0 +1,1065 @@
+use std::{
+ collections::{BTreeMap, BTreeSet},
+ fs,
+ io::{BufReader, Read},
+ path::{Component, Path, PathBuf},
+};
+
+use serde::Deserialize;
+use sha2::{Digest, Sha256};
+use uhura_host::WebAssets;
+
+pub const SPOCK_UHURA_WEB_DIST: &str = "SPOCK_UHURA_WEB_DIST";
+pub const SPOCK_UHURA_WASM_DIST: &str = "SPOCK_UHURA_WASM_DIST";
+
+// This value is captured by rustc, not read from the process environment.
+// Official distribution builds bind it to the exact sidecar manifest produced
+// earlier in the same release workflow. Source/test builds intentionally leave
+// it unset and use the explicit paired asset-root override above.
+const PACKAGED_UHURA_MANIFEST_SHA256: Option<&str> =
+ option_env!("SPOCK_PACKAGED_UHURA_MANIFEST_SHA256");
+const SIDECAR_PROTOCOL: &str = "spock-asset-sidecar/1";
+const HOST_ENVIRONMENT_PROTOCOL: &str = "spock-host-environment/1";
+const PROJECT_STATUS_PROTOCOL: &str = "spock-project-status/1";
+const PROJECT_EVENT_PROTOCOL: &str = "spock-project-event/1";
+const EDITOR_STATE_PROTOCOL: &str = "uhura-editor-state/1";
+const EDITOR_EVENT_PROTOCOL: &str = "uhura-editor-event/0";
+const IR_PROTOCOL: &str = "uhura-ir/0";
+const INSPECT_PROTOCOL: &str = "uhura-inspect/0";
+const VIEW_PROTOCOL: &str = "uhura-view/0";
+const PROVIDER_PROTOCOL: &str = "uhura-provider/0";
+const SIDECAR_PROTOCOLS: [(&str, &str); 9] = [
+ ("environment", HOST_ENVIRONMENT_PROTOCOL),
+ ("project_status", PROJECT_STATUS_PROTOCOL),
+ ("project_event", PROJECT_EVENT_PROTOCOL),
+ ("editor_state", EDITOR_STATE_PROTOCOL),
+ ("editor_event", EDITOR_EVENT_PROTOCOL),
+ ("ir", IR_PROTOCOL),
+ ("inspect", INSPECT_PROTOCOL),
+ ("view", VIEW_PROTOCOL),
+ ("provider", PROVIDER_PROTOCOL),
+];
+const MAX_MANIFEST_BYTES: u64 = 8 * 1024 * 1024;
+const REQUIRED_FILES: [&str; 3] = [
+ "web/index.html",
+ "wasm/uhura_wasm.js",
+ "wasm/uhura_wasm_bg.wasm",
+];
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct UhuraAssetRoots {
+ pub web: PathBuf,
+ pub wasm: PathBuf,
+}
+
+impl UhuraAssetRoots {
+ pub fn load(&self) -> Result {
+ WebAssets::from_directories(&self.web, &self.wasm).map_err(|message| {
+ AssetError::InvalidBundle {
+ roots: self.clone(),
+ message,
+ }
+ })
+ }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum AssetError {
+ #[error("{variable} must be set together with {other}")]
+ PartialOverride {
+ variable: &'static str,
+ other: &'static str,
+ },
+ #[error(
+ "could not locate the packaged Uhura web and Wasm bundles (looked in {attempted}); \
+ set {SPOCK_UHURA_WEB_DIST} and {SPOCK_UHURA_WASM_DIST} for a source/test override"
+ )]
+ NotFound { attempted: String },
+ #[error(
+ "invalid Uhura asset bundle at web={} wasm={}: {message}",
+ roots.web.display(),
+ roots.wasm.display()
+ )]
+ InvalidBundle {
+ roots: UhuraAssetRoots,
+ message: String,
+ },
+ #[error("invalid packaged Uhura asset sidecar: {message}")]
+ InvalidSidecar { message: String },
+ #[error("could not resolve the current executable while locating Uhura assets: {0}")]
+ Executable(std::io::Error),
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct SidecarManifest {
+ protocol: String,
+ spock_commit: String,
+ uhura_commit: String,
+ protocols: BTreeMap,
+ files: Vec,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct SidecarFile {
+ path: String,
+ sha256: String,
+ size: u64,
+}
+
+#[derive(Debug, Eq, PartialEq)]
+struct ObservedFile {
+ path: String,
+ sha256: String,
+ size: u64,
+}
+
+struct LocatedUhuraAssets {
+ roots: UhuraAssetRoots,
+ manifest: Option,
+}
+
+/// The reusable `uhura-host` never searches a checkout. This aggregate-host
+/// adapter checks an explicit paired override, executable-relative package
+/// locations. Source builds opt in through the paired environment override;
+/// `uhura-host` itself never searches a checkout.
+///
+/// Load the exact package-owned bytes whose manifest is bound to this
+/// executable and whose inventory matches that manifest. Explicit development
+/// overrides have no package identity and are still captured once into the
+/// same immutable [`WebAssets`] representation.
+///
+/// The executable binding detects a changed or coherently replaced sidecar
+/// while the binary remains trusted. It is not a signature over the binary and
+/// cannot defend against replacement of both artifacts or a compromised build.
+pub fn load_uhura_assets() -> Result {
+ let located = locate_uhura_asset_source()?;
+ let assets = located.roots.load()?;
+ if let Some(manifest) = located.manifest {
+ validate_loaded_assets(&manifest, &assets)
+ .map_err(|message| AssetError::InvalidSidecar { message })?;
+ }
+ Ok(assets)
+}
+
+fn locate_uhura_asset_source() -> Result {
+ let web_override = std::env::var_os(SPOCK_UHURA_WEB_DIST).map(PathBuf::from);
+ let wasm_override = std::env::var_os(SPOCK_UHURA_WASM_DIST).map(PathBuf::from);
+ match (web_override, wasm_override) {
+ (Some(web), Some(wasm)) => {
+ return Ok(LocatedUhuraAssets {
+ roots: UhuraAssetRoots { web, wasm },
+ manifest: None,
+ });
+ }
+ (Some(_), None) => {
+ return Err(AssetError::PartialOverride {
+ variable: SPOCK_UHURA_WEB_DIST,
+ other: SPOCK_UHURA_WASM_DIST,
+ });
+ }
+ (None, Some(_)) => {
+ return Err(AssetError::PartialOverride {
+ variable: SPOCK_UHURA_WASM_DIST,
+ other: SPOCK_UHURA_WEB_DIST,
+ });
+ }
+ (None, None) => {}
+ }
+
+ let executable = std::env::current_exe().map_err(AssetError::Executable)?;
+ let mut candidates = Vec::new();
+ if let Some(bin) = executable.parent() {
+ // Conventional prefix install: /bin/spock plus
+ // /share/spock/uhura/{web,wasm}.
+ let root = bin.join("../share/spock/uhura");
+ candidates.push((
+ root.clone(),
+ UhuraAssetRoots {
+ web: root.join("web"),
+ wasm: root.join("wasm"),
+ },
+ ));
+ // npm: /binaries//spock plus one shared sidecar.
+ let root = bin.join("../../share/spock/uhura");
+ candidates.push((
+ root.clone(),
+ UhuraAssetRoots {
+ web: root.join("web"),
+ wasm: root.join("wasm"),
+ },
+ ));
+ }
+ let mut attempted = Vec::new();
+ let mut invalid = Vec::new();
+ for (root, roots) in candidates {
+ if attempted.contains(&roots) {
+ continue;
+ }
+ let manifest = root.join("manifest.json");
+ let mut candidate_present = false;
+ for path in [&manifest, &roots.web, &roots.wasm] {
+ match fs::symlink_metadata(path) {
+ Ok(_) => candidate_present = true,
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+ Err(error) => {
+ candidate_present = true;
+ invalid.push(format!("{}: {error}", path.display()));
+ }
+ }
+ }
+ if candidate_present {
+ match validate_packaged_sidecar(&root, &roots) {
+ Ok(manifest) => {
+ return Ok(LocatedUhuraAssets {
+ roots,
+ manifest: Some(manifest),
+ });
+ }
+ Err(message) => invalid.push(format!("{}: {message}", root.display())),
+ }
+ }
+ attempted.push(roots);
+ }
+
+ if !invalid.is_empty() {
+ return Err(AssetError::InvalidSidecar {
+ message: invalid.join("; "),
+ });
+ }
+
+ Err(AssetError::NotFound {
+ attempted: attempted
+ .iter()
+ .map(|roots| format!("{} + {}", roots.web.display(), roots.wasm.display()))
+ .collect::>()
+ .join(", "),
+ })
+}
+
+fn validate_packaged_sidecar(
+ sidecar_root: &Path,
+ roots: &UhuraAssetRoots,
+) -> Result {
+ let expected_manifest_sha256 =
+ require_packaged_manifest_sha256(PACKAGED_UHURA_MANIFEST_SHA256)?;
+ validate_packaged_sidecar_with_digest(sidecar_root, roots, expected_manifest_sha256)
+}
+
+fn validate_packaged_sidecar_with_digest(
+ sidecar_root: &Path,
+ roots: &UhuraAssetRoots,
+ expected_manifest_sha256: &str,
+) -> Result {
+ let root_metadata = fs::symlink_metadata(sidecar_root)
+ .map_err(|error| format!("could not inspect {}: {error}", sidecar_root.display()))?;
+ if root_metadata.file_type().is_symlink() || !root_metadata.is_dir() {
+ return Err(format!(
+ "sidecar root {} must be a real directory, not a symlink or special file",
+ sidecar_root.display()
+ ));
+ }
+
+ let expected_roots = UhuraAssetRoots {
+ web: sidecar_root.join("web"),
+ wasm: sidecar_root.join("wasm"),
+ };
+ if roots != &expected_roots {
+ return Err("asset roots do not belong to the declared sidecar root".to_owned());
+ }
+
+ let manifest_path = sidecar_root.join("manifest.json");
+ let manifest_metadata = symlink_free_file_metadata(&manifest_path, "manifest")?;
+ if manifest_metadata.len() > MAX_MANIFEST_BYTES {
+ return Err(format!(
+ "manifest is {} bytes; maximum is {MAX_MANIFEST_BYTES}",
+ manifest_metadata.len()
+ ));
+ }
+ let manifest_bytes = fs::read(&manifest_path)
+ .map_err(|error| format!("could not read {}: {error}", manifest_path.display()))?;
+ validate_manifest_binding(&manifest_bytes, expected_manifest_sha256)?;
+ let manifest: SidecarManifest = serde_json::from_slice(&manifest_bytes)
+ .map_err(|error| format!("could not parse {}: {error}", manifest_path.display()))?;
+
+ validate_manifest_header(&manifest)?;
+ validate_manifest_files(&manifest.files)?;
+
+ let mut observed = Vec::new();
+ collect_observed_files(sidecar_root, &roots.web, &mut observed)?;
+ collect_observed_files(sidecar_root, &roots.wasm, &mut observed)?;
+ observed.sort_by(|left, right| left.path.cmp(&right.path));
+ validate_case_insensitive_uniqueness(observed.iter().map(|file| file.path.as_str()))?;
+
+ if manifest.files.len() != observed.len() {
+ return Err(format!(
+ "manifest lists {} files but the sidecar contains {} files",
+ manifest.files.len(),
+ observed.len()
+ ));
+ }
+ for (declared, actual) in manifest.files.iter().zip(&observed) {
+ if declared.path != actual.path {
+ return Err(format!(
+ "file inventory mismatch: manifest has {} where sidecar has {}",
+ declared.path, actual.path
+ ));
+ }
+ if declared.size != actual.size {
+ return Err(format!(
+ "size mismatch for {}: manifest has {} but sidecar has {}",
+ declared.path, declared.size, actual.size
+ ));
+ }
+ if declared.sha256 != actual.sha256 {
+ return Err(format!(
+ "SHA-256 mismatch for {}: manifest has {} but sidecar has {}",
+ declared.path, declared.sha256, actual.sha256
+ ));
+ }
+ }
+
+ for required in REQUIRED_FILES {
+ if observed
+ .binary_search_by_key(&required, |file| file.path.as_str())
+ .is_err()
+ {
+ return Err(format!("required sidecar file {required} is missing"));
+ }
+ }
+
+ Ok(manifest)
+}
+
+fn require_packaged_manifest_sha256(configured: Option<&str>) -> Result<&str, String> {
+ let configured = configured.ok_or_else(|| {
+ format!(
+ "this executable has no trusted Uhura sidecar manifest identity; packaged sidecar loading is disabled (source/test builds must set the paired {SPOCK_UHURA_WEB_DIST} and {SPOCK_UHURA_WASM_DIST} overrides)"
+ )
+ })?;
+ if !lowercase_sha256(configured) {
+ return Err(
+ "the executable's trusted Uhura sidecar manifest identity is not a 64-character lowercase SHA-256 digest"
+ .to_owned(),
+ );
+ }
+ Ok(configured)
+}
+
+fn validate_manifest_binding(
+ manifest_bytes: &[u8],
+ expected_manifest_sha256: &str,
+) -> Result<(), String> {
+ if !lowercase_sha256(expected_manifest_sha256) {
+ return Err("trusted sidecar manifest SHA-256 is malformed".to_owned());
+ }
+ let observed = sha256_bytes(manifest_bytes);
+ if observed != expected_manifest_sha256 {
+ return Err(format!(
+ "manifest SHA-256 {observed} does not match executable-bound identity {expected_manifest_sha256}"
+ ));
+ }
+ Ok(())
+}
+
+fn lowercase_sha256(value: &str) -> bool {
+ value.len() == 64
+ && value
+ .bytes()
+ .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+}
+
+fn sha256_bytes(bytes: &[u8]) -> String {
+ format!("{:x}", Sha256::digest(bytes))
+}
+
+fn validate_loaded_assets(manifest: &SidecarManifest, assets: &WebAssets) -> Result<(), String> {
+ let observed = assets.inventory();
+ if manifest.files.len() != observed.len() {
+ return Err(format!(
+ "manifest lists {} files but the immutable asset snapshot contains {} files",
+ manifest.files.len(),
+ observed.len()
+ ));
+ }
+ for (declared, actual) in manifest.files.iter().zip(&observed) {
+ if declared.path != actual.path {
+ return Err(format!(
+ "file inventory mismatch: manifest has {} where the immutable asset snapshot has {}",
+ declared.path, actual.path
+ ));
+ }
+ if declared.size != actual.size {
+ return Err(format!(
+ "size mismatch for {}: manifest has {} but the immutable asset snapshot has {}",
+ declared.path, declared.size, actual.size
+ ));
+ }
+ if declared.sha256 != actual.sha256 {
+ return Err(format!(
+ "SHA-256 mismatch for {}: manifest has {} but the immutable asset snapshot has {}",
+ declared.path, declared.sha256, actual.sha256
+ ));
+ }
+ }
+ Ok(())
+}
+
+fn validate_manifest_header(manifest: &SidecarManifest) -> Result<(), String> {
+ if manifest.protocol != SIDECAR_PROTOCOL {
+ return Err(format!(
+ "unsupported manifest protocol {}; expected {SIDECAR_PROTOCOL}",
+ manifest.protocol
+ ));
+ }
+ for (name, commit) in [
+ ("spock_commit", manifest.spock_commit.as_str()),
+ ("uhura_commit", manifest.uhura_commit.as_str()),
+ ] {
+ if commit.len() != 40
+ || !commit
+ .bytes()
+ .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+ {
+ return Err(format!(
+ "manifest {name} must be exactly 40 lowercase hexadecimal characters"
+ ));
+ }
+ }
+ for (name, expected) in SIDECAR_PROTOCOLS {
+ match manifest.protocols.get(name) {
+ Some(actual) if actual == expected => {}
+ Some(actual) => {
+ return Err(format!("protocol {name} is {actual}; expected {expected}"));
+ }
+ None => return Err(format!("required protocol {name} is missing")),
+ }
+ }
+ for name in manifest.protocols.keys() {
+ if !SIDECAR_PROTOCOLS
+ .iter()
+ .any(|(expected, _)| name == expected)
+ {
+ return Err(format!("unsupported protocol key {name}"));
+ }
+ }
+ Ok(())
+}
+
+fn validate_manifest_files(files: &[SidecarFile]) -> Result<(), String> {
+ let mut previous: Option<&str> = None;
+ for file in files {
+ validate_relative_asset_path(&file.path)?;
+ if let Some(previous) = previous {
+ if previous >= file.path.as_str() {
+ let reason = if previous == file.path {
+ "contains a duplicate"
+ } else {
+ "is not sorted"
+ };
+ return Err(format!("manifest file inventory {reason} at {}", file.path));
+ }
+ }
+ previous = Some(&file.path);
+ if file.size == 0 {
+ return Err(format!("manifest size for {} must be positive", file.path));
+ }
+ if file.sha256.len() != 64
+ || !file
+ .sha256
+ .bytes()
+ .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+ {
+ return Err(format!(
+ "manifest SHA-256 for {} must be 64 lowercase hexadecimal characters",
+ file.path
+ ));
+ }
+ }
+ validate_case_insensitive_uniqueness(files.iter().map(|file| file.path.as_str()))
+}
+
+fn validate_relative_asset_path(path: &str) -> Result<(), String> {
+ if path.is_empty() || path.contains('\\') {
+ return Err(format!("unsafe manifest file path {path:?}"));
+ }
+ let segments = path.split('/').collect::>();
+ if segments.len() < 2
+ || !matches!(segments.first(), Some(&"web" | &"wasm"))
+ || segments
+ .iter()
+ .any(|segment| !portable_asset_segment(segment))
+ || Path::new(path)
+ .components()
+ .any(|component| !matches!(component, Component::Normal(_)))
+ {
+ return Err(format!("unsafe manifest file path {path:?}"));
+ }
+ Ok(())
+}
+
+fn portable_asset_segment(segment: &str) -> bool {
+ let bytes = segment.as_bytes();
+ bytes.first().is_some_and(u8::is_ascii_alphanumeric)
+ && bytes
+ .iter()
+ .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
+ && !segment.ends_with('.')
+ && !windows_device_segment(segment)
+}
+
+fn windows_device_segment(segment: &str) -> bool {
+ let stem = segment.split_once('.').map_or(segment, |(stem, _)| stem);
+ if stem.eq_ignore_ascii_case("con")
+ || stem.eq_ignore_ascii_case("prn")
+ || stem.eq_ignore_ascii_case("aux")
+ || stem.eq_ignore_ascii_case("nul")
+ {
+ return true;
+ }
+ let bytes = stem.as_bytes();
+ bytes.len() == 4
+ && (bytes[..3].eq_ignore_ascii_case(b"com") || bytes[..3].eq_ignore_ascii_case(b"lpt"))
+ && matches!(bytes[3], b'1'..=b'9')
+}
+
+fn validate_case_insensitive_uniqueness<'a>(
+ paths: impl Iterator- ,
+) -> Result<(), String> {
+ let mut folded = BTreeSet::new();
+ for path in paths {
+ if !folded.insert(path.to_lowercase()) {
+ return Err(format!(
+ "sidecar contains a case-insensitive path collision at {path}"
+ ));
+ }
+ }
+ Ok(())
+}
+
+fn collect_observed_files(
+ sidecar_root: &Path,
+ directory: &Path,
+ observed: &mut Vec,
+) -> Result<(), String> {
+ let metadata = fs::symlink_metadata(directory)
+ .map_err(|error| format!("could not inspect {}: {error}", directory.display()))?;
+ if metadata.file_type().is_symlink() || !metadata.is_dir() {
+ return Err(format!(
+ "{} must be a real directory, not a symlink or special file",
+ directory.display()
+ ));
+ }
+
+ let entries = fs::read_dir(directory)
+ .map_err(|error| format!("could not read {}: {error}", directory.display()))?;
+ for entry in entries {
+ let entry = entry.map_err(|error| {
+ format!(
+ "could not read an entry in {}: {error}",
+ directory.display()
+ )
+ })?;
+ let path = entry.path();
+ let metadata = fs::symlink_metadata(&path)
+ .map_err(|error| format!("could not inspect {}: {error}", path.display()))?;
+ if metadata.file_type().is_symlink() {
+ return Err(format!(
+ "sidecar path {} must not be a symlink",
+ path.display()
+ ));
+ }
+ if metadata.is_dir() {
+ collect_observed_files(sidecar_root, &path, observed)?;
+ continue;
+ }
+ if !metadata.is_file() {
+ return Err(format!(
+ "sidecar path {} is not a regular file",
+ path.display()
+ ));
+ }
+ if metadata.len() == 0 {
+ return Err(format!("sidecar file {} must not be empty", path.display()));
+ }
+ let relative = path.strip_prefix(sidecar_root).map_err(|_| {
+ format!(
+ "sidecar path {} escaped root {}",
+ path.display(),
+ sidecar_root.display()
+ )
+ })?;
+ let relative = manifest_path(relative)?;
+ validate_relative_asset_path(&relative)?;
+ observed.push(ObservedFile {
+ path: relative,
+ sha256: hash_file(&path)?,
+ size: metadata.len(),
+ });
+ }
+ Ok(())
+}
+
+fn manifest_path(relative: &Path) -> Result {
+ let mut segments = Vec::new();
+ for component in relative.components() {
+ let Component::Normal(segment) = component else {
+ return Err(format!(
+ "sidecar path {} is not a safe relative path",
+ relative.display()
+ ));
+ };
+ segments.push(
+ segment
+ .to_str()
+ .ok_or_else(|| {
+ format!(
+ "sidecar path {} cannot be represented as UTF-8",
+ relative.display()
+ )
+ })?
+ .to_owned(),
+ );
+ }
+ Ok(segments.join("/"))
+}
+
+fn symlink_free_file_metadata(path: &Path, label: &str) -> Result {
+ let metadata = fs::symlink_metadata(path)
+ .map_err(|error| format!("could not inspect {label} {}: {error}", path.display()))?;
+ if metadata.file_type().is_symlink() || !metadata.is_file() {
+ return Err(format!(
+ "{label} {} must be a regular file, not a symlink",
+ path.display()
+ ));
+ }
+ Ok(metadata)
+}
+
+fn hash_file(path: &Path) -> Result {
+ let file = fs::File::open(path)
+ .map_err(|error| format!("could not open {} for hashing: {error}", path.display()))?;
+ let mut reader = BufReader::new(file);
+ let mut hasher = Sha256::new();
+ let mut buffer = [0_u8; 64 * 1024];
+ loop {
+ let read = reader
+ .read(&mut buffer)
+ .map_err(|error| format!("could not hash {}: {error}", path.display()))?;
+ if read == 0 {
+ break;
+ }
+ hasher.update(&buffer[..read]);
+ }
+ Ok(format!("{:x}", hasher.finalize()))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::{json, Value};
+ use tempfile::tempdir;
+
+ // Most validation tests deliberately mutate one manifest field and need
+ // the executable binding to follow that fixture so they can reach the
+ // lower-level protocol or inventory assertion under test.
+ fn validate_packaged_sidecar(
+ sidecar_root: &Path,
+ roots: &UhuraAssetRoots,
+ ) -> Result {
+ let expected = hash_file(&sidecar_root.join("manifest.json"))?;
+ validate_packaged_sidecar_with_digest(sidecar_root, roots, &expected)
+ }
+
+ #[test]
+ fn explicit_asset_roots_are_snapshotted_as_one_bundle() {
+ let temp = tempdir().expect("temporary asset root");
+ let web = temp.path().join("web");
+ let wasm = temp.path().join("wasm");
+ std::fs::create_dir_all(web.join("assets")).expect("web assets");
+ std::fs::create_dir_all(&wasm).expect("wasm directory");
+ std::fs::write(
+ web.join("index.html"),
+ r#""#,
+ )
+ .expect("web index");
+ std::fs::write(web.join("assets/app.js"), "export {};\n").expect("web script");
+ std::fs::write(wasm.join("uhura_wasm.js"), "export {};\n").expect("wasm loader");
+ std::fs::write(wasm.join("uhura_wasm_bg.wasm"), b"wasm").expect("wasm module");
+
+ let roots = UhuraAssetRoots { web, wasm };
+ let assets = roots.load().expect("valid immutable web assets");
+ drop(assets);
+ }
+
+ #[test]
+ fn packaged_sidecar_accepts_an_exact_manifest() {
+ let fixture = SidecarFixture::new();
+
+ validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect("exact sidecar manifest should validate");
+ }
+
+ #[test]
+ fn packaged_sidecar_requires_an_executable_bound_manifest_identity() {
+ let error = require_packaged_manifest_sha256(None)
+ .expect_err("a source binary must not accept an executable-relative sidecar");
+ assert!(
+ error.contains("no trusted Uhura sidecar manifest identity"),
+ "{error}"
+ );
+
+ let error = require_packaged_manifest_sha256(Some("not-a-digest"))
+ .expect_err("a malformed build identity must fail closed");
+ assert!(
+ error.contains("not a 64-character lowercase SHA-256"),
+ "{error}"
+ );
+ }
+
+ #[test]
+ fn executable_binding_rejects_a_coherently_rehashed_sidecar() {
+ let mut fixture = SidecarFixture::new();
+ let trusted = fixture.manifest_sha256();
+
+ fs::write(
+ fixture.root.join("web/assets/app.js"),
+ "export const coherently_rehashed = true;\n",
+ )
+ .expect("replace asset bytes");
+ fixture.refresh_manifest_entry("web/assets/app.js");
+ fixture.write_manifest();
+
+ validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect("the rewritten manifest remains internally consistent");
+ let error = validate_packaged_sidecar_with_digest(&fixture.root, &fixture.roots, &trusted)
+ .expect_err("the executable must retain the original manifest identity");
+ assert!(
+ error.contains("does not match executable-bound identity"),
+ "{error}"
+ );
+ }
+
+ #[test]
+ fn packaged_sidecar_rejects_protocol_mismatches() {
+ let mut fixture = SidecarFixture::new();
+ fixture.manifest["protocol"] = json!("spock-asset-sidecar/2");
+ fixture.write_manifest();
+
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("unknown sidecar protocol must fail closed");
+ assert!(error.contains("unsupported manifest protocol"), "{error}");
+
+ fixture.manifest["protocol"] = json!(SIDECAR_PROTOCOL);
+ fixture.manifest["protocols"]["project_event"] = json!("wrong/1");
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("framework protocol mismatch must fail closed");
+ assert!(error.contains("protocol project_event"), "{error}");
+
+ let mut fixture = SidecarFixture::new();
+ fixture.manifest["protocols"]
+ .as_object_mut()
+ .expect("protocol object")
+ .remove("provider");
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("missing protocol must fail closed");
+ assert!(
+ error.contains("required protocol provider is missing"),
+ "{error}"
+ );
+
+ let mut fixture = SidecarFixture::new();
+ fixture.manifest["protocols"]["future"] = json!("future/1");
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("unknown protocol key must fail closed");
+ assert!(error.contains("unsupported protocol key future"), "{error}");
+ }
+
+ #[test]
+ fn packaged_sidecar_requires_full_git_object_ids() {
+ let mut fixture = SidecarFixture::new();
+ fixture.manifest["spock_commit"] = json!("unknown");
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("non-object commit must fail closed");
+ assert!(error.contains("spock_commit must be exactly 40"), "{error}");
+
+ fixture.manifest["spock_commit"] = json!("ABCDEF0123456789abcdef0123456789abcdef01");
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("uppercase object id must fail closed");
+ assert!(error.contains("spock_commit must be exactly 40"), "{error}");
+ }
+
+ #[test]
+ fn packaged_sidecar_rejects_unsafe_duplicate_and_unsorted_paths() {
+ let mut fixture = SidecarFixture::new();
+ fixture.manifest["files"][0]["path"] = json!("web/../escape");
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("unsafe path must fail closed");
+ assert!(error.contains("unsafe manifest file path"), "{error}");
+
+ let mut fixture = SidecarFixture::new();
+ let duplicate = fixture.manifest["files"][0].clone();
+ fixture.manifest["files"]
+ .as_array_mut()
+ .expect("file array")
+ .insert(1, duplicate);
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("duplicate path must fail closed");
+ assert!(error.contains("contains a duplicate"), "{error}");
+
+ let mut fixture = SidecarFixture::new();
+ fixture.manifest["files"]
+ .as_array_mut()
+ .expect("file array")
+ .reverse();
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("unsorted paths must fail closed");
+ assert!(error.contains("is not sorted"), "{error}");
+ }
+
+ #[test]
+ fn packaged_sidecar_paths_use_the_portable_ascii_grammar() {
+ for path in [
+ "web/café.js",
+ "web/.hidden.js",
+ "web/-app.js",
+ "web/trailing.",
+ "web/CON",
+ "web/com1.js",
+ "wasm/LPT9.bin",
+ ] {
+ let error = validate_relative_asset_path(path)
+ .expect_err("non-portable package path must fail closed");
+ assert!(
+ error.contains("unsafe manifest file path"),
+ "{path}: {error}"
+ );
+ }
+ for path in [
+ "web/index.html",
+ "web/assets/app-ABC_123.js",
+ "wasm/uhura_wasm_bg.wasm",
+ "web/console.js",
+ "web/com10.js",
+ ] {
+ validate_relative_asset_path(path)
+ .unwrap_or_else(|error| panic!("{path} should be portable: {error}"));
+ }
+ }
+
+ #[test]
+ fn packaged_sidecar_rejects_missing_extra_and_case_colliding_files() {
+ let fixture = SidecarFixture::new();
+ fs::remove_file(fixture.root.join("web/assets/app.js")).expect("remove declared file");
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("missing file must fail closed");
+ assert!(error.contains("manifest lists"), "{error}");
+
+ let fixture = SidecarFixture::new();
+ fs::write(fixture.root.join("web/extra.js"), "extra\n").expect("extra file");
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("unlisted file must fail closed");
+ assert!(error.contains("manifest lists"), "{error}");
+
+ let mut fixture = SidecarFixture::new();
+ let mut collision = fixture.manifest["files"]
+ .as_array()
+ .expect("file array")
+ .iter()
+ .find(|file| file["path"] == "web/index.html")
+ .expect("index manifest entry")
+ .clone();
+ collision["path"] = json!("web/INDEX.html");
+ let files = fixture.manifest["files"]
+ .as_array_mut()
+ .expect("file array");
+ files.push(collision);
+ files.sort_by(|left, right| {
+ left["path"]
+ .as_str()
+ .expect("path")
+ .cmp(right["path"].as_str().expect("path"))
+ });
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("case-insensitive collision must fail closed");
+ assert!(error.contains("case-insensitive path collision"), "{error}");
+ }
+
+ #[test]
+ fn packaged_sidecar_rejects_size_and_hash_mismatches() {
+ let mut fixture = SidecarFixture::new();
+ fixture.manifest["files"][0]["size"] = json!(999);
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("size mismatch must fail closed");
+ assert!(error.contains("size mismatch"), "{error}");
+
+ let mut fixture = SidecarFixture::new();
+ fixture.manifest["files"][0]["sha256"] =
+ json!("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+ fixture.write_manifest();
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("hash mismatch must fail closed");
+ assert!(error.contains("SHA-256 mismatch"), "{error}");
+ }
+
+ #[test]
+ fn manifest_integrity_covers_the_exact_immutable_bytes_that_will_be_served() {
+ let fixture = SidecarFixture::new();
+ let manifest = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect("initial sidecar should validate");
+ let captured = fixture.roots.load().expect("capture validated assets");
+
+ fs::write(
+ fixture.root.join("web/assets/app.js"),
+ "export const tampered = true;\n",
+ )
+ .expect("mutate source after capture");
+
+ validate_loaded_assets(&manifest, &captured)
+ .expect("filesystem mutation cannot alter an immutable captured snapshot");
+ let tampered = fixture.roots.load().expect("capture mutated assets");
+ let error = validate_loaded_assets(&manifest, &tampered)
+ .expect_err("mutated captured bytes must fail manifest integrity validation");
+ assert!(error.contains("mismatch"), "{error}");
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn packaged_sidecar_rejects_symlinks() {
+ use std::os::unix::fs::symlink;
+
+ let fixture = SidecarFixture::new();
+ symlink(
+ fixture.root.join("web/index.html"),
+ fixture.root.join("web/link.html"),
+ )
+ .expect("asset symlink");
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("asset symlink must fail closed");
+ assert!(error.contains("must not be a symlink"), "{error}");
+
+ let fixture = SidecarFixture::new();
+ fs::rename(
+ fixture.root.join("manifest.json"),
+ fixture.root.join("real-manifest.json"),
+ )
+ .expect("move manifest");
+ symlink(
+ fixture.root.join("real-manifest.json"),
+ fixture.root.join("manifest.json"),
+ )
+ .expect("manifest symlink");
+ let error = validate_packaged_sidecar(&fixture.root, &fixture.roots)
+ .expect_err("manifest symlink must fail closed");
+ assert!(error.contains("must be a regular file"), "{error}");
+ }
+
+ struct SidecarFixture {
+ _temp: tempfile::TempDir,
+ root: PathBuf,
+ roots: UhuraAssetRoots,
+ manifest: Value,
+ }
+
+ impl SidecarFixture {
+ fn new() -> Self {
+ let temp = tempdir().expect("temporary sidecar");
+ let root = temp.path().join("uhura");
+ let roots = UhuraAssetRoots {
+ web: root.join("web"),
+ wasm: root.join("wasm"),
+ };
+ fs::create_dir_all(roots.web.join("assets")).expect("web directories");
+ fs::create_dir_all(&roots.wasm).expect("wasm directory");
+ fs::write(
+ roots.web.join("index.html"),
+ r#""#,
+ )
+ .expect("web index");
+ fs::write(roots.web.join("assets/app.js"), "export {};\n").expect("web script");
+ fs::write(roots.wasm.join("uhura_wasm.js"), "export {};\n").expect("wasm loader");
+ fs::write(roots.wasm.join("uhura_wasm_bg.wasm"), b"wasm").expect("wasm module");
+
+ let mut files = Vec::new();
+ for relative in [
+ "wasm/uhura_wasm.js",
+ "wasm/uhura_wasm_bg.wasm",
+ "web/assets/app.js",
+ "web/index.html",
+ ] {
+ let path = root.join(relative);
+ files.push(json!({
+ "path": relative,
+ "sha256": hash_file(&path).expect("fixture hash"),
+ "size": fs::metadata(path).expect("fixture metadata").len(),
+ }));
+ }
+ files.sort_by(|left, right| {
+ left["path"]
+ .as_str()
+ .expect("path")
+ .cmp(right["path"].as_str().expect("path"))
+ });
+ let manifest = json!({
+ "protocol": SIDECAR_PROTOCOL,
+ "spock_commit": "0123456789abcdef0123456789abcdef01234567",
+ "uhura_commit": "89abcdef0123456789abcdef0123456789abcdef",
+ "protocols": {
+ "environment": HOST_ENVIRONMENT_PROTOCOL,
+ "project_status": PROJECT_STATUS_PROTOCOL,
+ "project_event": PROJECT_EVENT_PROTOCOL,
+ "editor_state": EDITOR_STATE_PROTOCOL,
+ "editor_event": EDITOR_EVENT_PROTOCOL,
+ "ir": IR_PROTOCOL,
+ "inspect": INSPECT_PROTOCOL,
+ "view": VIEW_PROTOCOL,
+ "provider": PROVIDER_PROTOCOL
+ },
+ "files": files,
+ });
+ let fixture = Self {
+ _temp: temp,
+ root,
+ roots,
+ manifest,
+ };
+ fixture.write_manifest();
+ fixture
+ }
+
+ fn write_manifest(&self) {
+ fs::write(
+ self.root.join("manifest.json"),
+ serde_json::to_vec_pretty(&self.manifest).expect("serialize fixture manifest"),
+ )
+ .expect("write fixture manifest");
+ }
+
+ fn manifest_sha256(&self) -> String {
+ hash_file(&self.root.join("manifest.json")).expect("hash fixture manifest")
+ }
+
+ fn refresh_manifest_entry(&mut self, relative: &str) {
+ let path = self.root.join(relative);
+ let entry = self.manifest["files"]
+ .as_array_mut()
+ .expect("file array")
+ .iter_mut()
+ .find(|entry| entry["path"] == relative)
+ .expect("manifest entry");
+ entry["sha256"] = json!(hash_file(&path).expect("asset hash"));
+ entry["size"] = json!(fs::metadata(path).expect("asset metadata").len());
+ }
+ }
+}
diff --git a/crates/spock-host/src/backend_capture.rs b/crates/spock-host/src/backend_capture.rs
new file mode 100644
index 0000000..12b0cd6
--- /dev/null
+++ b/crates/spock-host/src/backend_capture.rs
@@ -0,0 +1,1182 @@
+//! Coherent, database-free observation of Spock backend inputs.
+//!
+//! The observer captures the configured source and every checked
+//! `file("...")` seed dependency as one immutable byte bundle. It never opens a
+//! runtime generation or touches a database; activation policy belongs to the
+//! generation coordinator and process supervisor.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::fmt;
+use std::fs;
+use std::io::{self, Read};
+use std::ops::Range;
+use std::path::{Path, PathBuf};
+
+use cap_fs_ext::{DirExt as _, FollowSymlinks, OpenOptionsFollowExt as _, OpenOptionsSyncExt as _};
+use spock_lang::ir::SeedValue;
+use spock_project::ProjectLayout;
+use spock_runtime::generation::CapturedBackend;
+
+use crate::Fingerprint;
+
+const MAX_STABILITY_SAMPLES: usize = 4;
+const INVALID_OBSERVATION_PROTOCOL: &[u8] = b"spock-invalid-backend-observation/1";
+
+/// Stable categories for backend-capture failures.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum BackendDiagnosticCode {
+ Io,
+ InvalidUtf8,
+ Language,
+ PathEscape,
+ WrongEntryKind,
+ UnstableInputs,
+}
+
+impl BackendDiagnosticCode {
+ #[must_use]
+ pub const fn as_str(self) -> &'static str {
+ match self {
+ Self::Io => "SPH001",
+ Self::InvalidUtf8 => "SPH002",
+ Self::Language => "SPH003",
+ Self::PathEscape => "SPH004",
+ Self::WrongEntryKind => "SPH005",
+ Self::UnstableInputs => "SPH006",
+ }
+ }
+}
+
+impl fmt::Display for BackendDiagnosticCode {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ formatter.write_str(self.as_str())
+ }
+}
+
+/// One diagnostic from a coherent backend observation.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct BackendDiagnostic {
+ pub code: BackendDiagnosticCode,
+ pub message: String,
+ pub path: Option,
+ pub span: Option>,
+ /// The Spock language diagnostic code when `code` is `Language`.
+ pub language_code: Option<&'static str>,
+}
+
+impl BackendDiagnostic {
+ fn new(code: BackendDiagnosticCode, message: impl Into) -> Self {
+ Self {
+ code,
+ message: message.into(),
+ path: None,
+ span: None,
+ language_code: None,
+ }
+ }
+
+ fn at_path(mut self, path: impl Into) -> Self {
+ self.path = Some(path.into());
+ self
+ }
+
+ fn stable_bytes(&self) -> Vec {
+ let mut bytes = Vec::new();
+ push_field(&mut bytes, self.code.as_str().as_bytes());
+ push_field(
+ &mut bytes,
+ self.path
+ .as_deref()
+ .unwrap_or_else(|| Path::new(""))
+ .as_os_str()
+ .to_string_lossy()
+ .as_bytes(),
+ );
+ push_field(
+ &mut bytes,
+ self.language_code.unwrap_or_default().as_bytes(),
+ );
+ if let Some(span) = &self.span {
+ push_field(&mut bytes, &span.start.to_be_bytes());
+ push_field(&mut bytes, &span.end.to_be_bytes());
+ } else {
+ push_field(&mut bytes, &[]);
+ push_field(&mut bytes, &[]);
+ }
+ push_field(&mut bytes, self.message.as_bytes());
+ bytes
+ }
+}
+
+impl fmt::Display for BackendDiagnostic {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(formatter, "{}: ", self.code)?;
+ if let Some(path) = &self.path {
+ write!(formatter, "{}: ", path.display())?;
+ }
+ if let Some(language_code) = self.language_code {
+ write!(formatter, "error[{language_code}]: ")?;
+ }
+ formatter.write_str(&self.message)
+ }
+}
+
+/// Deterministically ordered diagnostics from one backend observation.
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct BackendDiagnostics(Vec);
+
+impl BackendDiagnostics {
+ #[must_use]
+ pub fn is_empty(&self) -> bool {
+ self.0.is_empty()
+ }
+
+ #[must_use]
+ pub fn len(&self) -> usize {
+ self.0.len()
+ }
+
+ pub fn iter(&self) -> impl ExactSizeIterator
- {
+ self.0.iter()
+ }
+
+ fn push(&mut self, diagnostic: BackendDiagnostic) {
+ self.0.push(diagnostic);
+ }
+}
+
+impl fmt::Display for BackendDiagnostics {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ for (index, diagnostic) in self.0.iter().enumerate() {
+ if index != 0 {
+ formatter.write_str("\n")?;
+ }
+ diagnostic.fmt(formatter)?;
+ }
+ Ok(())
+ }
+}
+
+impl std::error::Error for BackendDiagnostics {}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct ObservedInput {
+ display_name: String,
+ fingerprint: Fingerprint,
+}
+
+/// One stable filesystem observation, valid or invalid.
+///
+/// Invalid source states still have an identity, allowing `spock dev` to
+/// report transitions and recovery without constructing a database-backed
+/// runtime candidate.
+#[derive(Clone, Debug)]
+pub struct BackendObservation {
+ fingerprint: Fingerprint,
+ inputs: BTreeMap,
+ captured: Option,
+ diagnostics: BackendDiagnostics,
+}
+
+impl BackendObservation {
+ #[must_use]
+ pub fn fingerprint(&self) -> &Fingerprint {
+ &self.fingerprint
+ }
+
+ #[must_use]
+ pub fn captured_backend(&self) -> Option<&CapturedBackend> {
+ self.captured.as_ref()
+ }
+
+ #[must_use]
+ pub fn diagnostics(&self) -> &BackendDiagnostics {
+ &self.diagnostics
+ }
+
+ #[must_use]
+ pub fn is_valid(&self) -> bool {
+ self.captured.is_some()
+ }
+
+ /// Human-facing names for inputs whose value or availability differs.
+ #[must_use]
+ pub fn changed_inputs_since(&self, previous: &Self) -> Vec {
+ let identities = self
+ .inputs
+ .keys()
+ .chain(previous.inputs.keys())
+ .collect::>();
+ identities
+ .into_iter()
+ .filter_map(|identity| {
+ let current = self.inputs.get(identity);
+ let previous = previous.inputs.get(identity);
+ (current != previous).then(|| {
+ current
+ .or(previous)
+ .expect("identity came from one input map")
+ .display_name
+ .clone()
+ })
+ })
+ .collect::>()
+ .into_iter()
+ .collect()
+ }
+
+ pub fn into_captured_backend(self) -> Result {
+ match self.captured {
+ Some(captured) => Ok(captured),
+ None => Err(self.diagnostics),
+ }
+ }
+}
+
+/// Observe the backend without constructing, opening, reseeding, or swapping
+/// any runtime generation.
+#[must_use]
+pub fn observe_backend(layout: &ProjectLayout) -> BackendObservation {
+ let sample = stable_sample(|| sample_backend(layout));
+ BackendObservation::from_sample(sample)
+}
+
+/// Capture a valid immutable runtime input bundle.
+pub fn capture_backend(layout: &ProjectLayout) -> Result {
+ observe_backend(layout).into_captured_backend()
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+enum InputContent {
+ Bytes(Vec),
+ Unavailable(String),
+}
+
+impl InputContent {
+ fn stable_bytes(&self) -> Vec {
+ let mut bytes = Vec::new();
+ match self {
+ Self::Bytes(value) => {
+ bytes.extend_from_slice(b"bytes");
+ push_field(&mut bytes, value);
+ }
+ Self::Unavailable(reason) => {
+ bytes.extend_from_slice(b"unavailable");
+ push_field(&mut bytes, reason.as_bytes());
+ }
+ }
+ bytes
+ }
+
+ fn bytes(&self) -> Option<&[u8]> {
+ match self {
+ Self::Bytes(bytes) => Some(bytes),
+ Self::Unavailable(_) => None,
+ }
+ }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct SampleInput {
+ display_name: String,
+ requested_path: PathBuf,
+ canonical_path: Option,
+ content: InputContent,
+}
+
+impl SampleInput {
+ fn unavailable(
+ display_name: impl Into,
+ requested_path: PathBuf,
+ reason: impl Into,
+ ) -> Self {
+ Self {
+ display_name: display_name.into(),
+ requested_path,
+ canonical_path: None,
+ content: InputContent::Unavailable(reason.into()),
+ }
+ }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct BackendSample {
+ source: SampleInput,
+ assets: BTreeMap,
+ diagnostics: BackendDiagnostics,
+}
+
+impl BackendSample {
+ fn new(layout: &ProjectLayout, source_path: PathBuf) -> Self {
+ Self {
+ source: SampleInput::unavailable(
+ layout.backend_entry.relative().as_str(),
+ source_path,
+ "source has not been read",
+ ),
+ assets: BTreeMap::new(),
+ diagnostics: BackendDiagnostics::default(),
+ }
+ }
+
+ fn source_failure(mut self, code: BackendDiagnosticCode, message: impl Into) -> Self {
+ let message = message.into();
+ self.source.content = InputContent::Unavailable(message.clone());
+ self.diagnostics.push(
+ BackendDiagnostic::new(code, message).at_path(self.source.requested_path.clone()),
+ );
+ self
+ }
+}
+
+impl BackendObservation {
+ fn from_sample(sample: BackendSample) -> Self {
+ let valid = sample.diagnostics.is_empty();
+ let source_bytes = sample.source.content.bytes().unwrap_or_default();
+ let asset_bytes = sample
+ .assets
+ .iter()
+ .filter_map(|(spelling, input)| {
+ input
+ .content
+ .bytes()
+ .map(|bytes| (spelling.clone(), bytes.to_vec()))
+ })
+ .collect::>();
+
+ let captured_candidate = CapturedBackend::new(source_bytes, asset_bytes);
+ let fingerprint = if valid {
+ Fingerprint::new(captured_candidate.input_fingerprint().as_str())
+ } else {
+ invalid_observation_fingerprint(&sample)
+ };
+
+ let mut inputs = BTreeMap::new();
+ inputs.insert(
+ format!("source:{}", sample.source.display_name),
+ observed_input("source", &sample.source),
+ );
+ for (spelling, input) in &sample.assets {
+ inputs.insert(
+ format!("seed:{spelling}"),
+ observed_input(&format!("seed:{spelling}"), input),
+ );
+ }
+
+ Self {
+ fingerprint,
+ inputs,
+ captured: valid.then_some(captured_candidate),
+ diagnostics: sample.diagnostics,
+ }
+ }
+}
+
+fn observed_input(identity: &str, input: &SampleInput) -> ObservedInput {
+ let captured = CapturedBackend::new(
+ [],
+ BTreeMap::from([(identity.to_string(), input.content.stable_bytes())]),
+ );
+ ObservedInput {
+ display_name: input.display_name.clone(),
+ fingerprint: Fingerprint::new(captured.input_fingerprint().as_str()),
+ }
+}
+
+fn invalid_observation_fingerprint(sample: &BackendSample) -> Fingerprint {
+ let mut source = INVALID_OBSERVATION_PROTOCOL.to_vec();
+ push_field(&mut source, &sample.source.content.stable_bytes());
+ for diagnostic in sample.diagnostics.iter() {
+ push_field(&mut source, &diagnostic.stable_bytes());
+ }
+ let assets = sample
+ .assets
+ .iter()
+ .map(|(spelling, input)| (spelling.clone(), input.content.stable_bytes()))
+ .collect();
+ let synthetic = CapturedBackend::new(source, assets);
+ Fingerprint::new(synthetic.input_fingerprint().as_str())
+}
+
+fn stable_sample(mut sample: impl FnMut() -> BackendSample) -> BackendSample {
+ let mut previous = sample();
+ for _ in 1..MAX_STABILITY_SAMPLES {
+ let current = sample();
+ if current == previous {
+ return current;
+ }
+ previous = current;
+ }
+ previous.diagnostics.push(
+ BackendDiagnostic::new(
+ BackendDiagnosticCode::UnstableInputs,
+ format!(
+ "backend inputs did not remain unchanged across {MAX_STABILITY_SAMPLES} consecutive samples"
+ ),
+ )
+ .at_path(previous.source.requested_path.clone()),
+ );
+ previous
+}
+
+#[derive(Debug)]
+enum ConfinedReadError {
+ Io(io::Error),
+ WrongEntryKind,
+}
+
+/// A retained directory capability used to open every backend input.
+///
+/// Callers first canonicalize for the existing user-facing containment policy,
+/// then traverse that canonical relative path without following any component.
+/// This preserves in-root symlink spellings while preventing an ancestor
+/// symlink or reparse-point swap from redirecting reads outside the validated
+/// root.
+#[derive(Debug)]
+struct ConfinedDirectory {
+ directory: cap_std::fs::Dir,
+}
+
+impl ConfinedDirectory {
+ fn open_ambient_nofollow(path: &Path) -> io::Result {
+ let file = open_directory_path_nofollow(path)?;
+ let directory = cap_std::fs::Dir::from_std_file(file);
+ if !directory.dir_metadata()?.is_dir() {
+ return Err(io::Error::new(
+ io::ErrorKind::NotADirectory,
+ "confined root is not a real directory",
+ ));
+ }
+ Ok(Self { directory })
+ }
+
+ fn open_directory(&self, relative: &Path) -> io::Result {
+ let mut current = self.directory.try_clone()?;
+ for component in relative.components() {
+ let std::path::Component::Normal(segment) = component else {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "confined directory path is not normalized and relative",
+ ));
+ };
+ current = current.open_dir_nofollow(segment)?;
+ }
+ Ok(Self { directory: current })
+ }
+
+ fn read_regular_file(&self, relative: &Path) -> Result, ConfinedReadError> {
+ let file_name = relative.file_name().ok_or_else(|| {
+ ConfinedReadError::Io(io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "confined file path has no file name",
+ ))
+ })?;
+ let parent = self
+ .open_directory(relative.parent().unwrap_or_else(|| Path::new("")))
+ .map_err(ConfinedReadError::Io)?;
+ let initial_metadata = parent
+ .directory
+ .symlink_metadata(file_name)
+ .map_err(ConfinedReadError::Io)?;
+ if !initial_metadata.is_file() && !initial_metadata.file_type().is_symlink() {
+ return Err(ConfinedReadError::WrongEntryKind);
+ }
+ let mut options = cap_std::fs::OpenOptions::new();
+ options
+ .read(true)
+ .follow(FollowSymlinks::No)
+ // A special entry installed after the metadata probe must not turn
+ // capture into a blocking FIFO/device open. The returned handle is
+ // still the authority for the regular-file check below.
+ .nonblock(true);
+ let mut file = match parent.directory.open_with(file_name, &options) {
+ Ok(file) => file,
+ Err(error) => {
+ if parent
+ .directory
+ .symlink_metadata(file_name)
+ .is_ok_and(|metadata| !metadata.is_file() && !metadata.file_type().is_symlink())
+ {
+ return Err(ConfinedReadError::WrongEntryKind);
+ }
+ return Err(ConfinedReadError::Io(error));
+ }
+ };
+ let metadata = file.metadata().map_err(ConfinedReadError::Io)?;
+ if !metadata.is_file() {
+ return Err(ConfinedReadError::WrongEntryKind);
+ }
+ let mut bytes = Vec::new();
+ file.read_to_end(&mut bytes)
+ .map_err(ConfinedReadError::Io)?;
+ Ok(bytes)
+ }
+}
+
+#[cfg(unix)]
+fn open_directory_path_nofollow(path: &Path) -> io::Result {
+ if !path.is_absolute() {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "confined root path is not absolute",
+ ));
+ }
+ let descriptor = rustix::fs::openat(
+ rustix::fs::CWD,
+ Path::new("/"),
+ rustix::fs::OFlags::RDONLY
+ | rustix::fs::OFlags::DIRECTORY
+ | rustix::fs::OFlags::NOFOLLOW
+ | rustix::fs::OFlags::CLOEXEC,
+ rustix::fs::Mode::empty(),
+ )?;
+ let mut current = cap_std::fs::Dir::from_std_file(fs::File::from(descriptor));
+ for component in path.components() {
+ match component {
+ std::path::Component::RootDir => {}
+ std::path::Component::Normal(segment) => {
+ current = current.open_dir_nofollow(segment)?;
+ }
+ _ => {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "confined root path is not canonical",
+ ));
+ }
+ }
+ }
+ Ok(current.into_std_file())
+}
+
+#[cfg(windows)]
+fn open_directory_path_nofollow(path: &Path) -> io::Result {
+ use std::os::windows::fs::{MetadataExt as _, OpenOptionsExt as _};
+ use windows_sys::Win32::Storage::FileSystem::{
+ FILE_ATTRIBUTE_REPARSE_POINT, FILE_FLAG_BACKUP_SEMANTICS, FILE_FLAG_OPEN_REPARSE_POINT,
+ FILE_SHARE_READ, FILE_SHARE_WRITE,
+ };
+
+ let mut components = path.components();
+ let Some(std::path::Component::Prefix(prefix)) = components.next() else {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "confined root path has no volume prefix",
+ ));
+ };
+ if !matches!(components.next(), Some(std::path::Component::RootDir)) {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "confined root path is not absolute",
+ ));
+ }
+ let mut volume_root = PathBuf::from(prefix.as_os_str());
+ volume_root.push(Path::new(r"\"));
+ let file = fs::OpenOptions::new()
+ .read(true)
+ // Denying delete sharing keeps each retained directory from being
+ // renamed while the next child is resolved through it.
+ .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE)
+ .custom_flags(FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT)
+ .open(&volume_root)?;
+ let metadata = file.metadata()?;
+ if !metadata.is_dir() || metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 {
+ return Err(io::Error::new(
+ io::ErrorKind::NotADirectory,
+ "confined root is not a real directory",
+ ));
+ }
+ let mut current = cap_std::fs::Dir::from_std_file(file);
+ for component in components {
+ let std::path::Component::Normal(segment) = component else {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidInput,
+ "confined root path is not canonical",
+ ));
+ };
+ current = current.open_dir_nofollow(segment)?;
+ }
+ Ok(current.into_std_file())
+}
+
+#[cfg(not(any(unix, windows)))]
+fn open_directory_path_nofollow(path: &Path) -> io::Result {
+ let metadata = fs::symlink_metadata(path)?;
+ if metadata.file_type().is_symlink() || !metadata.is_dir() {
+ return Err(io::Error::new(
+ io::ErrorKind::NotADirectory,
+ "confined root is not a real directory",
+ ));
+ }
+ cap_std::fs::Dir::open_ambient_dir(path, cap_std::ambient_authority())
+ .map(cap_std::fs::Dir::into_std_file)
+}
+
+fn relative_to<'a>(path: &'a Path, root: &Path) -> io::Result<&'a Path> {
+ path.strip_prefix(root).map_err(|_| {
+ io::Error::new(
+ io::ErrorKind::PermissionDenied,
+ "validated path is outside its confined root",
+ )
+ })
+}
+
+fn confined_failure_code(requested: &Path, allowed_root: &Path) -> BackendDiagnosticCode {
+ match fs::canonicalize(requested) {
+ Ok(current) if !current.starts_with(allowed_root) => BackendDiagnosticCode::PathEscape,
+ _ => BackendDiagnosticCode::Io,
+ }
+}
+
+fn sample_backend(layout: &ProjectLayout) -> BackendSample {
+ let source_requested = layout.root.join(layout.backend_entry.relative().as_path());
+ let mut sample = BackendSample::new(layout, source_requested.clone());
+
+ let canonical_root = match fs::canonicalize(&layout.root) {
+ Ok(path) => path,
+ Err(error) => {
+ return sample.source_failure(
+ BackendDiagnosticCode::Io,
+ format!("could not resolve project root: {error}"),
+ );
+ }
+ };
+ if !canonical_root.is_dir() {
+ return sample.source_failure(
+ BackendDiagnosticCode::WrongEntryKind,
+ "project root is not a directory",
+ );
+ }
+ let project_directory = match ConfinedDirectory::open_ambient_nofollow(&canonical_root) {
+ Ok(directory) => directory,
+ Err(error) => {
+ return sample.source_failure(
+ confined_failure_code(&layout.root, &canonical_root),
+ format!("could not securely open project root: {error}"),
+ );
+ }
+ };
+
+ let backend_root_requested = canonical_root.join(layout.backend_root.relative().as_path());
+ let canonical_backend_root = match fs::canonicalize(&backend_root_requested) {
+ Ok(path) => path,
+ Err(error) => {
+ return sample.source_failure(
+ BackendDiagnosticCode::Io,
+ format!("could not resolve configured backend root: {error}"),
+ );
+ }
+ };
+ if !canonical_backend_root.starts_with(&canonical_root) {
+ return sample.source_failure(
+ BackendDiagnosticCode::PathEscape,
+ "configured backend root resolves outside the project root",
+ );
+ }
+ if !canonical_backend_root.is_dir() {
+ return sample.source_failure(
+ BackendDiagnosticCode::WrongEntryKind,
+ "configured backend root is not a directory",
+ );
+ }
+ let backend_relative = match relative_to(&canonical_backend_root, &canonical_root) {
+ Ok(relative) => relative,
+ Err(error) => {
+ return sample.source_failure(
+ BackendDiagnosticCode::PathEscape,
+ format!("configured backend root escaped the project root: {error}"),
+ );
+ }
+ };
+ let backend_directory = match project_directory.open_directory(backend_relative) {
+ Ok(directory) => directory,
+ Err(error) => {
+ return sample.source_failure(
+ confined_failure_code(&backend_root_requested, &canonical_root),
+ format!("could not securely open configured backend root: {error}"),
+ );
+ }
+ };
+
+ let source_directory_requested = source_requested
+ .parent()
+ .unwrap_or(canonical_backend_root.as_path());
+ let canonical_source_directory = match fs::canonicalize(source_directory_requested) {
+ Ok(path) => path,
+ Err(error) => {
+ return sample.source_failure(
+ BackendDiagnosticCode::Io,
+ format!("could not resolve backend source directory: {error}"),
+ );
+ }
+ };
+ if !canonical_source_directory.starts_with(&canonical_backend_root) {
+ return sample.source_failure(
+ BackendDiagnosticCode::PathEscape,
+ "backend source directory resolves outside the configured backend root",
+ );
+ }
+ let source_directory_relative =
+ match relative_to(&canonical_source_directory, &canonical_backend_root) {
+ Ok(relative) => relative,
+ Err(error) => {
+ return sample.source_failure(
+ BackendDiagnosticCode::PathEscape,
+ format!(
+ "backend source directory escaped the configured backend root: {error}"
+ ),
+ );
+ }
+ };
+ let source_directory = match backend_directory.open_directory(source_directory_relative) {
+ Ok(directory) => directory,
+ Err(error) => {
+ return sample.source_failure(
+ confined_failure_code(source_directory_requested, &canonical_backend_root),
+ format!("could not securely open backend source directory: {error}"),
+ );
+ }
+ };
+
+ let canonical_source = match fs::canonicalize(&source_requested) {
+ Ok(path) => path,
+ Err(error) => {
+ return sample.source_failure(
+ BackendDiagnosticCode::Io,
+ format!("could not resolve backend entry: {error}"),
+ );
+ }
+ };
+ if !canonical_source.starts_with(&canonical_backend_root) {
+ return sample.source_failure(
+ BackendDiagnosticCode::PathEscape,
+ "backend entry resolves outside the configured backend root",
+ );
+ }
+ let source_relative = match relative_to(&canonical_source, &canonical_backend_root) {
+ Ok(relative) => relative,
+ Err(error) => {
+ return sample.source_failure(
+ BackendDiagnosticCode::PathEscape,
+ format!("backend entry escaped the configured backend root: {error}"),
+ );
+ }
+ };
+ let source = match backend_directory.read_regular_file(source_relative) {
+ Ok(source) => source,
+ Err(ConfinedReadError::WrongEntryKind) => {
+ return sample.source_failure(
+ BackendDiagnosticCode::WrongEntryKind,
+ "configured backend entry is not a regular file",
+ );
+ }
+ Err(ConfinedReadError::Io(error)) => {
+ let code = confined_failure_code(&source_requested, &canonical_backend_root);
+ let message = if code == BackendDiagnosticCode::PathEscape {
+ "backend entry changed to resolve outside the configured backend root".to_string()
+ } else {
+ format!("could not securely read backend entry: {error}")
+ };
+ return sample.source_failure(code, message);
+ }
+ };
+ sample.source = SampleInput {
+ display_name: layout.backend_entry.relative().as_str().to_string(),
+ requested_path: source_requested.clone(),
+ canonical_path: Some(canonical_source),
+ content: InputContent::Bytes(source.clone()),
+ };
+
+ let source_text = match std::str::from_utf8(&source) {
+ Ok(source) => source,
+ Err(error) => {
+ sample.diagnostics.push(
+ BackendDiagnostic::new(
+ BackendDiagnosticCode::InvalidUtf8,
+ format!("backend entry is not UTF-8: {error}"),
+ )
+ .at_path(source_requested),
+ );
+ return sample;
+ }
+ };
+ let contract = match spock_lang::compile(source_text) {
+ Ok(contract) => contract,
+ Err(diagnostics) => {
+ for diagnostic in diagnostics {
+ sample.diagnostics.push(BackendDiagnostic {
+ code: BackendDiagnosticCode::Language,
+ message: diagnostic.message,
+ path: Some(source_requested.clone()),
+ span: Some(diagnostic.span.start..diagnostic.span.end),
+ language_code: Some(diagnostic.code),
+ });
+ }
+ return sample;
+ }
+ };
+
+ let asset_spellings = contract
+ .seed
+ .iter()
+ .flat_map(|row| row.fields.values())
+ .filter_map(|value| match value {
+ SeedValue::File { path } => Some(path.clone()),
+ _ => None,
+ })
+ .collect::>();
+
+ for spelling in asset_spellings {
+ let display_name = format!("seed asset `{spelling}`");
+ let requested = source_directory_requested.join(Path::new(&spelling));
+ let canonical = match fs::canonicalize(&requested) {
+ Ok(path) => path,
+ Err(error) => {
+ let message = format!("could not resolve seed asset `{spelling}`: {error}");
+ sample.assets.insert(
+ spelling,
+ SampleInput::unavailable(display_name, requested.clone(), &message),
+ );
+ sample.diagnostics.push(
+ BackendDiagnostic::new(BackendDiagnosticCode::Io, message).at_path(requested),
+ );
+ continue;
+ }
+ };
+ if !canonical.starts_with(&canonical_source_directory)
+ || !canonical.starts_with(&canonical_backend_root)
+ || !canonical.starts_with(&canonical_root)
+ {
+ let message =
+ format!("seed asset `{spelling}` resolves outside the backend source directory");
+ let mut input =
+ SampleInput::unavailable(display_name, requested.clone(), message.clone());
+ input.canonical_path = Some(canonical);
+ sample.assets.insert(spelling, input);
+ sample.diagnostics.push(
+ BackendDiagnostic::new(BackendDiagnosticCode::PathEscape, message)
+ .at_path(requested),
+ );
+ continue;
+ }
+ let asset_relative = match relative_to(&canonical, &canonical_source_directory) {
+ Ok(relative) => relative,
+ Err(error) => {
+ let message =
+ format!("seed asset `{spelling}` escaped its source directory: {error}");
+ let mut input =
+ SampleInput::unavailable(display_name, requested.clone(), message.clone());
+ input.canonical_path = Some(canonical);
+ sample.assets.insert(spelling, input);
+ sample.diagnostics.push(
+ BackendDiagnostic::new(BackendDiagnosticCode::PathEscape, message)
+ .at_path(requested),
+ );
+ continue;
+ }
+ };
+ match source_directory.read_regular_file(asset_relative) {
+ Ok(bytes) => {
+ sample.assets.insert(
+ spelling,
+ SampleInput {
+ display_name,
+ requested_path: requested,
+ canonical_path: Some(canonical),
+ content: InputContent::Bytes(bytes),
+ },
+ );
+ }
+ Err(ConfinedReadError::WrongEntryKind) => {
+ let message = format!("seed asset `{spelling}` is not a regular file");
+ let mut input =
+ SampleInput::unavailable(display_name, requested.clone(), message.clone());
+ input.canonical_path = Some(canonical);
+ sample.assets.insert(spelling, input);
+ sample.diagnostics.push(
+ BackendDiagnostic::new(BackendDiagnosticCode::WrongEntryKind, message)
+ .at_path(requested),
+ );
+ }
+ Err(ConfinedReadError::Io(error)) => {
+ let code = confined_failure_code(&requested, &canonical_source_directory);
+ let message = if code == BackendDiagnosticCode::PathEscape {
+ format!("seed asset `{spelling}` changed to resolve outside the backend source directory")
+ } else {
+ format!("could not securely read seed asset `{spelling}`: {error}")
+ };
+ let mut input =
+ SampleInput::unavailable(display_name, requested.clone(), message.clone());
+ input.canonical_path = Some(canonical);
+ sample.assets.insert(spelling, input);
+ sample
+ .diagnostics
+ .push(BackendDiagnostic::new(code, message).at_path(requested));
+ }
+ }
+ }
+
+ sample
+}
+
+fn push_field(output: &mut Vec, bytes: &[u8]) {
+ output.extend_from_slice(&(bytes.len() as u64).to_be_bytes());
+ output.extend_from_slice(bytes);
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use spock_project::{load_project_from, ProjectManifest, MANIFEST_FILE};
+ use tempfile::tempdir;
+
+ const STORAGE_SOURCE: &str = "auth table user { key id: uuid = auto\n \
+ username: text unique\n avatar: storage_object? }\n\
+ seed { user { username: \"u\", avatar: file(\"./seed/pic.png\") } }\n";
+
+ fn project(source: &[u8]) -> (tempfile::TempDir, ProjectLayout) {
+ let temp = tempdir().expect("temp project");
+ fs::create_dir(temp.path().join("backend")).expect("backend directory");
+ fs::write(temp.path().join("backend/app.spock"), source).expect("backend source");
+ let manifest = ProjectManifest::new("demo", "backend", "app.spock", None)
+ .expect("manifest")
+ .to_toml_string();
+ fs::write(temp.path().join(MANIFEST_FILE), manifest).expect("project manifest");
+ let layout = load_project_from(temp.path()).expect("project layout");
+ (temp, layout)
+ }
+
+ #[test]
+ fn empty_backend_captures_without_constructing_a_runtime_generation() {
+ let (_temp, layout) = project(b"// intentionally empty\n");
+
+ let observation = observe_backend(&layout);
+
+ assert!(observation.is_valid(), "{}", observation.diagnostics());
+ let captured = observation.captured_backend().expect("captured backend");
+ assert_eq!(captured.source(), b"// intentionally empty\n");
+ assert_eq!(
+ observation.fingerprint().as_str(),
+ captured.input_fingerprint().as_str()
+ );
+ }
+
+ #[test]
+ fn seed_assets_are_captured_and_participate_in_change_detection() {
+ let (temp, layout) = project(STORAGE_SOURCE.as_bytes());
+ fs::create_dir(temp.path().join("backend/seed")).expect("seed directory");
+ let asset = temp.path().join("backend/seed/pic.png");
+ fs::write(&asset, b"first").expect("first asset");
+ let first = observe_backend(&layout);
+
+ fs::write(&asset, b"second").expect("second asset");
+ let second = observe_backend(&layout);
+
+ assert!(first.is_valid(), "{}", first.diagnostics());
+ assert!(second.is_valid(), "{}", second.diagnostics());
+ assert_eq!(
+ first
+ .captured_backend()
+ .expect("first capture")
+ .seed_asset("./seed/pic.png"),
+ Some(b"first".as_slice())
+ );
+ assert_ne!(first.fingerprint(), second.fingerprint());
+ assert_eq!(
+ second.changed_inputs_since(&first),
+ vec!["seed asset `./seed/pic.png`"]
+ );
+ }
+
+ #[test]
+ fn stable_invalid_source_has_diagnostics_and_a_recoverable_identity() {
+ let (temp, layout) = project(b"table broken {");
+ let invalid = observe_backend(&layout);
+
+ assert!(!invalid.is_valid());
+ assert!(invalid
+ .diagnostics()
+ .iter()
+ .any(|diagnostic| diagnostic.code == BackendDiagnosticCode::Language));
+
+ fs::write(
+ temp.path().join("backend/app.spock"),
+ b"table fixed { key id: uuid = auto }",
+ )
+ .expect("fixed source");
+ let fixed = observe_backend(&layout);
+ assert!(fixed.is_valid(), "{}", fixed.diagnostics());
+ assert_ne!(invalid.fingerprint(), fixed.fingerprint());
+ assert_eq!(
+ fixed.changed_inputs_since(&invalid),
+ vec!["backend/app.spock"]
+ );
+ }
+
+ #[test]
+ fn missing_seed_asset_is_invalid_and_recovers_when_the_file_appears() {
+ let (temp, layout) = project(STORAGE_SOURCE.as_bytes());
+ fs::create_dir(temp.path().join("backend/seed")).expect("seed directory");
+ let missing = observe_backend(&layout);
+ assert!(!missing.is_valid());
+
+ fs::write(temp.path().join("backend/seed/pic.png"), b"payload").expect("seed asset");
+ let recovered = observe_backend(&layout);
+
+ assert!(recovered.is_valid(), "{}", recovered.diagnostics());
+ assert_ne!(missing.fingerprint(), recovered.fingerprint());
+ assert_eq!(
+ recovered.changed_inputs_since(&missing),
+ vec!["seed asset `./seed/pic.png`"]
+ );
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn in_root_source_and_seed_symlinks_remain_supported() {
+ use std::os::unix::fs::symlink;
+
+ let (temp, layout) = project(STORAGE_SOURCE.as_bytes());
+ let backend = temp.path().join("backend");
+ let source = backend.join("app.spock");
+ let real_source = backend.join("real.spock");
+ fs::write(&real_source, STORAGE_SOURCE).expect("real backend source");
+ fs::remove_file(&source).expect("remove source fixture");
+ symlink("real.spock", &source).expect("in-root source symlink");
+
+ fs::create_dir(backend.join("seed")).expect("seed directory");
+ fs::write(backend.join("seed/real.png"), b"inside").expect("real seed asset");
+ symlink("real.png", backend.join("seed/pic.png")).expect("in-root seed symlink");
+
+ let observation = observe_backend(&layout);
+
+ assert!(observation.is_valid(), "{}", observation.diagnostics());
+ let captured = observation.captured_backend().expect("captured backend");
+ assert_eq!(captured.source(), STORAGE_SOURCE.as_bytes());
+ assert_eq!(
+ captured.seed_asset("./seed/pic.png"),
+ Some(b"inside".as_slice())
+ );
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn confined_reader_rejects_a_post_validation_symlink_swap() {
+ use std::os::unix::fs::symlink;
+
+ let root = tempdir().expect("confined root");
+ let outside = tempdir().expect("outside root");
+ let input = root.path().join("input.bin");
+ fs::write(&input, b"inside").expect("safe input");
+ fs::write(outside.path().join("outside.bin"), b"outside").expect("outside input");
+
+ let canonical_root = fs::canonicalize(root.path()).expect("canonical root");
+ let canonical_input = fs::canonicalize(&input).expect("validated input");
+ let reader = ConfinedDirectory::open_ambient_nofollow(&canonical_root)
+ .expect("retained confined root");
+
+ fs::remove_file(&input).expect("remove validated input");
+ symlink(outside.path().join("outside.bin"), &input).expect("escaping replacement");
+ let relative = relative_to(&canonical_input, &canonical_root).expect("relative input");
+
+ assert!(matches!(
+ reader.read_regular_file(relative),
+ Err(ConfinedReadError::Io(_))
+ ));
+ assert_eq!(
+ confined_failure_code(&input, &canonical_root),
+ BackendDiagnosticCode::PathEscape
+ );
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn confined_root_rejects_a_held_ancestor_redirect() {
+ use std::os::unix::fs::symlink;
+
+ let parent = tempdir().expect("root parent");
+ let outside = tempdir().expect("redirect target");
+ let ancestor = parent.path().join("ancestor");
+ let moved_ancestor = parent.path().join("moved-ancestor");
+ let root = ancestor.join("project");
+ fs::create_dir_all(&root).expect("original root");
+ fs::create_dir(outside.path().join("project")).expect("redirected project root");
+ let canonical_root = fs::canonicalize(&root).expect("canonical original root");
+
+ fs::rename(&ancestor, &moved_ancestor).expect("move original ancestor");
+ symlink(outside.path(), &ancestor).expect("held ancestor redirect");
+ assert_eq!(
+ fs::canonicalize(&canonical_root).expect("redirected canonical spelling"),
+ fs::canonicalize(outside.path().join("project")).expect("canonical redirect target")
+ );
+
+ ConfinedDirectory::open_ambient_nofollow(&canonical_root)
+ .expect_err("component-wise traversal must reject an ancestor redirect");
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn source_replaced_by_a_socket_is_rejected_as_non_regular_without_blocking() {
+ use std::os::unix::net::UnixListener;
+
+ let (temp, layout) = project(b"// initially regular\n");
+ let source = temp.path().join("backend/app.spock");
+ fs::remove_file(&source).expect("remove source fixture");
+ let _socket = UnixListener::bind(&source).expect("source socket");
+
+ let observation = observe_backend(&layout);
+
+ assert!(!observation.is_valid());
+ assert!(observation
+ .diagnostics()
+ .iter()
+ .any(|diagnostic| diagnostic.code == BackendDiagnosticCode::WrongEntryKind));
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn seed_asset_symlink_cannot_escape_the_source_directory() {
+ use std::os::unix::fs::symlink;
+
+ let (temp, layout) = project(STORAGE_SOURCE.as_bytes());
+ let outside = tempdir().expect("outside directory");
+ fs::write(outside.path().join("pic.png"), b"outside").expect("outside asset");
+ fs::create_dir(temp.path().join("backend/seed")).expect("seed directory");
+ symlink(
+ outside.path().join("pic.png"),
+ temp.path().join("backend/seed/pic.png"),
+ )
+ .expect("escaping symlink");
+
+ let observation = observe_backend(&layout);
+
+ assert!(!observation.is_valid());
+ assert!(observation
+ .diagnostics()
+ .iter()
+ .any(|diagnostic| diagnostic.code == BackendDiagnosticCode::PathEscape));
+ }
+
+ #[test]
+ fn changing_samples_are_not_published_as_a_coherent_capture() {
+ let (_temp, layout) = project(b"");
+ let source_path = layout.root.join(layout.backend_entry.relative().as_path());
+ let samples = [b"a", b"b", b"c", b"d"].map(|bytes| BackendSample {
+ source: SampleInput {
+ display_name: "backend/app.spock".into(),
+ requested_path: source_path.clone(),
+ canonical_path: Some(source_path.clone()),
+ content: InputContent::Bytes(bytes.to_vec()),
+ },
+ assets: BTreeMap::new(),
+ diagnostics: BackendDiagnostics::default(),
+ });
+ let mut samples = samples.into_iter();
+
+ let sample = stable_sample(|| samples.next().expect("bounded sample"));
+
+ assert!(sample
+ .diagnostics
+ .iter()
+ .any(|diagnostic| diagnostic.code == BackendDiagnosticCode::UnstableInputs));
+ }
+}
diff --git a/crates/spock-host/src/client.rs b/crates/spock-host/src/client.rs
new file mode 100644
index 0000000..dce6367
--- /dev/null
+++ b/crates/spock-host/src/client.rs
@@ -0,0 +1,426 @@
+use thiserror::Error;
+use uhura_host::{
+ build_candidate, CandidateDiagnostics, CandidateSummary, ClientCandidate as UhuraCandidate,
+ Host as UhuraHost, ProjectSourceSnapshot, PublicationReport, RouteRequest, RouteResponse,
+ WebAssets,
+};
+
+use crate::{Fingerprint, ObservedRevision};
+
+/// Content identity of the exact Uhura snapshot consumed by a client build.
+///
+/// Uhura remains responsible for enumerating and capturing its semantic
+/// inputs. The framework only converts that subsystem-owned identity into its
+/// status vocabulary.
+#[must_use]
+pub fn client_source_fingerprint(snapshot: &ProjectSourceSnapshot) -> Fingerprint {
+ Fingerprint::new(snapshot.fingerprint().stable_id())
+}
+
+/// One complete off-path Uhura build, bound to the framework observation that
+/// requested it.
+///
+/// `source_revision` is intentionally independent from `observed_revision`:
+/// backend-only observations advance the framework clock without creating a
+/// hole in Uhura's consecutive publication clock.
+pub struct PreparedClient {
+ observed_revision: ObservedRevision,
+ source_revision: u64,
+ source_fingerprint: Fingerprint,
+ summary: CandidateSummary,
+ candidate: UhuraCandidate,
+}
+
+impl PreparedClient {
+ fn build(
+ snapshot: &ProjectSourceSnapshot,
+ observed_revision: ObservedRevision,
+ source_revision: u64,
+ ) -> Self {
+ let source_fingerprint = client_source_fingerprint(snapshot);
+ let candidate = build_candidate(snapshot, source_revision);
+ let summary = candidate.summary();
+ Self {
+ observed_revision,
+ source_revision,
+ source_fingerprint,
+ summary,
+ candidate,
+ }
+ }
+
+ #[must_use]
+ pub const fn observed_revision(&self) -> ObservedRevision {
+ self.observed_revision
+ }
+
+ #[must_use]
+ pub const fn source_revision(&self) -> u64 {
+ self.source_revision
+ }
+
+ #[must_use]
+ pub fn source_fingerprint(&self) -> &Fingerprint {
+ &self.source_fingerprint
+ }
+
+ #[must_use]
+ pub const fn summary(&self) -> CandidateSummary {
+ self.summary
+ }
+
+ #[must_use]
+ pub fn diagnostics(&self) -> CandidateDiagnostics<'_> {
+ self.candidate.diagnostics()
+ }
+}
+
+/// The last Uhura Play generation that successfully replaced served client
+/// artifacts.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ActiveClientBinding {
+ pub observed_revision: ObservedRevision,
+ pub source_revision: u64,
+ pub source_fingerprint: Fingerprint,
+ pub play_generation: u64,
+}
+
+/// Result of publishing one Editor/Play attempt into the listenerless Uhura
+/// host.
+///
+/// An invalid attempt still advances Editor diagnostics and the Uhura source
+/// revision. `active` continues to name the last successful Play generation,
+/// if one exists.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ClientPublication {
+ pub observed_revision: ObservedRevision,
+ pub source_fingerprint: Fingerprint,
+ pub report: PublicationReport,
+ pub active: Option,
+}
+
+#[derive(Debug, Error, Eq, PartialEq)]
+pub enum ClientHostError {
+ #[error(
+ "client candidate from observed revision {candidate} is stale; newest observed revision is {newest}"
+ )]
+ StaleCandidate {
+ candidate: ObservedRevision,
+ newest: ObservedRevision,
+ },
+ #[error(
+ "client candidate repeats or precedes published observed revision {published}; received {received}"
+ )]
+ ObservationOrder {
+ published: ObservedRevision,
+ received: ObservedRevision,
+ },
+ #[error(
+ "client candidate has Uhura source revision {received}; expected the next consecutive revision {expected}"
+ )]
+ PublicationOrder { expected: u64, received: u64 },
+ #[error("Uhura host publication failed: {0}")]
+ Uhura(String),
+}
+
+/// Framework-owned publication state around the reusable listenerless Uhura
+/// host.
+///
+/// This type does not observe the filesystem or decide whether a candidate is
+/// the newest project observation. The future `dev` coordinator supplies that
+/// eligibility fact at publication time, while this boundary enforces it and
+/// translates between the two revision domains.
+pub struct ClientHost {
+ host: UhuraHost,
+ latest: ClientPublication,
+}
+
+impl ClientHost {
+ /// Build and publish Uhura revision 1 before a public listener is bound.
+ pub fn activate(
+ web: WebAssets,
+ snapshot: &ProjectSourceSnapshot,
+ observed_revision: ObservedRevision,
+ ) -> Result<(Self, ClientPublication), ClientHostError> {
+ let prepared = PreparedClient::build(snapshot, observed_revision, 1);
+ let source_fingerprint = prepared.source_fingerprint.clone();
+ let (host, report) =
+ UhuraHost::new(web, prepared.candidate).map_err(ClientHostError::Uhura)?;
+ let latest = publication(observed_revision, source_fingerprint, report, None);
+ Ok((
+ Self {
+ host,
+ latest: latest.clone(),
+ },
+ latest,
+ ))
+ }
+
+ /// Build the next candidate without mutating the served publication.
+ #[must_use]
+ pub fn prepare(
+ &self,
+ snapshot: &ProjectSourceSnapshot,
+ observed_revision: ObservedRevision,
+ ) -> PreparedClient {
+ PreparedClient::build(snapshot, observed_revision, self.host.source_revision() + 1)
+ }
+
+ /// Publish only a candidate belonging to the newest framework observation.
+ ///
+ /// The caller passes the current observation after any off-path build has
+ /// completed. This second check makes an older result permanently
+ /// ineligible even when it finishes after newer work.
+ pub fn publish(
+ &mut self,
+ prepared: PreparedClient,
+ newest_observed_revision: ObservedRevision,
+ ) -> Result {
+ if prepared.observed_revision != newest_observed_revision {
+ return Err(ClientHostError::StaleCandidate {
+ candidate: prepared.observed_revision,
+ newest: newest_observed_revision,
+ });
+ }
+ if prepared.observed_revision <= self.latest.observed_revision {
+ return Err(ClientHostError::ObservationOrder {
+ published: self.latest.observed_revision,
+ received: prepared.observed_revision,
+ });
+ }
+
+ let expected = self.host.source_revision() + 1;
+ if prepared.source_revision != expected {
+ return Err(ClientHostError::PublicationOrder {
+ expected,
+ received: prepared.source_revision,
+ });
+ }
+
+ let report = self
+ .host
+ .publish(prepared.candidate)
+ .map_err(ClientHostError::Uhura)?;
+ let latest = publication(
+ prepared.observed_revision,
+ prepared.source_fingerprint,
+ report,
+ self.latest.active.clone(),
+ );
+ self.latest = latest.clone();
+ Ok(latest)
+ }
+
+ #[must_use]
+ pub fn latest_publication(&self) -> &ClientPublication {
+ &self.latest
+ }
+
+ #[must_use]
+ pub fn active_client(&self) -> Option<&ActiveClientBinding> {
+ self.latest.active.as_ref()
+ }
+
+ /// Delegate one transport-neutral request to the subsystem host. The
+ /// combined Axum adapter can translate the returned bytes or event stream
+ /// without giving Uhura its own listener.
+ #[must_use]
+ pub fn route(&self, request: RouteRequest<'_>) -> RouteResponse {
+ self.host.route(request)
+ }
+}
+
+fn publication(
+ observed_revision: ObservedRevision,
+ source_fingerprint: Fingerprint,
+ report: PublicationReport,
+ previous_active: Option,
+) -> ClientPublication {
+ let active = if report.play_ok {
+ Some(ActiveClientBinding {
+ observed_revision,
+ source_revision: report.source_revision,
+ source_fingerprint: source_fingerprint.clone(),
+ play_generation: report.play_generation,
+ })
+ } else {
+ previous_active
+ };
+ ClientPublication {
+ observed_revision,
+ source_fingerprint,
+ report,
+ active,
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use std::fs;
+ use std::path::{Path, PathBuf};
+ use std::time::{SystemTime, UNIX_EPOCH};
+
+ use uhura_host::{capture_project_snapshot, RequestMethod, RouteBody};
+
+ use super::*;
+ use crate::{GenerationCoordinator, HostMode, Observation};
+
+ struct TempDirectory(PathBuf);
+
+ impl TempDirectory {
+ fn new(label: &str) -> Self {
+ let unique = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .expect("clock after epoch")
+ .as_nanos();
+ let path = std::env::temp_dir().join(format!(
+ "spock-host-{label}-{}-{unique}",
+ std::process::id()
+ ));
+ fs::create_dir_all(&path).expect("create temporary directory");
+ Self(path)
+ }
+ }
+
+ impl AsRef for TempDirectory {
+ fn as_ref(&self) -> &Path {
+ &self.0
+ }
+ }
+
+ impl Drop for TempDirectory {
+ fn drop(&mut self) {
+ let _ = fs::remove_dir_all(&self.0);
+ }
+ }
+
+ fn web_assets() -> (TempDirectory, WebAssets) {
+ let root = TempDirectory::new("web");
+ fs::create_dir_all(root.as_ref().join("assets")).unwrap();
+ fs::write(
+ root.as_ref().join("index.html"),
+ r#""#,
+ )
+ .unwrap();
+ fs::write(root.as_ref().join("assets/app.js"), "export {};\n").unwrap();
+ let assets = WebAssets::from_frontend_directory(root.as_ref()).unwrap();
+ (root, assets)
+ }
+
+ fn canonical_snapshot() -> ProjectSourceSnapshot {
+ capture_project_snapshot(
+ &Path::new(env!("CARGO_MANIFEST_DIR")).join("../../uhura/examples/instagram-uhura"),
+ )
+ }
+
+ fn coordinator() -> GenerationCoordinator {
+ GenerationCoordinator::activated(
+ HostMode::Dev,
+ Fingerprint::new("backend-a"),
+ Fingerprint::new("topology-a"),
+ Some(Fingerprint::new("client-a")),
+ "world-a",
+ )
+ }
+
+ fn advance_backend_only(coordinator: &mut GenerationCoordinator, name: &str) {
+ coordinator.observe(Observation {
+ topology: Fingerprint::new("topology-a"),
+ backend: Fingerprint::new(name),
+ client: Some(Fingerprint::new("client-a")),
+ changed_backend_inputs: vec!["backend/app.spock".to_owned()],
+ backend_diagnostics: Vec::new(),
+ });
+ }
+
+ #[test]
+ fn client_publication_clock_does_not_inherit_project_revision_gaps() {
+ let (_web_root, web) = web_assets();
+ let snapshot = canonical_snapshot();
+ let mut coordinator = coordinator();
+ let (mut host, initial) =
+ ClientHost::activate(web, &snapshot, coordinator.observed_revision()).unwrap();
+ assert_eq!(initial.report.source_revision, 1);
+ assert!(initial.active.is_some());
+
+ advance_backend_only(&mut coordinator, "backend-b");
+ advance_backend_only(&mut coordinator, "backend-c");
+ let observed_revision = coordinator.observed_revision();
+ assert_eq!(observed_revision.get(), 3);
+
+ let candidate = host.prepare(&snapshot, observed_revision);
+ assert_eq!(candidate.observed_revision(), observed_revision);
+ assert_eq!(candidate.source_revision(), 2);
+ let published = host.publish(candidate, observed_revision).unwrap();
+ assert_eq!(published.observed_revision, observed_revision);
+ assert_eq!(published.report.source_revision, 2);
+ assert_eq!(
+ published.active.unwrap().observed_revision,
+ observed_revision
+ );
+ }
+
+ #[test]
+ fn stale_result_is_rejected_before_it_can_advance_uhura_state() {
+ let (_web_root, web) = web_assets();
+ let snapshot = canonical_snapshot();
+ let mut coordinator = coordinator();
+ let (mut host, _) =
+ ClientHost::activate(web, &snapshot, coordinator.observed_revision()).unwrap();
+
+ advance_backend_only(&mut coordinator, "backend-b");
+ let stale_revision = coordinator.observed_revision();
+ let stale = host.prepare(&snapshot, stale_revision);
+ advance_backend_only(&mut coordinator, "backend-c");
+ let newest_revision = coordinator.observed_revision();
+ let newest = host.prepare(&snapshot, newest_revision);
+
+ assert_eq!(
+ host.publish(stale, newest_revision),
+ Err(ClientHostError::StaleCandidate {
+ candidate: stale_revision,
+ newest: newest_revision,
+ })
+ );
+ assert_eq!(host.latest_publication().report.source_revision, 1);
+
+ let publication = host.publish(newest, newest_revision).unwrap();
+ assert_eq!(publication.report.source_revision, 2);
+ }
+
+ #[test]
+ fn invalid_attempt_updates_editor_but_retains_last_good_play_binding() {
+ let (_web_root, web) = web_assets();
+ let valid = canonical_snapshot();
+ let mut coordinator = coordinator();
+ let initial_revision = coordinator.observed_revision();
+ let (mut host, initial) = ClientHost::activate(web, &valid, initial_revision).unwrap();
+ let active = initial.active.expect("valid example has Play artifacts");
+
+ let invalid_root = TempDirectory::new("invalid-client");
+ let invalid = capture_project_snapshot(invalid_root.as_ref());
+ coordinator.observe(Observation {
+ topology: Fingerprint::new("topology-a"),
+ backend: Fingerprint::new("backend-a"),
+ client: Some(client_source_fingerprint(&invalid)),
+ changed_backend_inputs: Vec::new(),
+ backend_diagnostics: Vec::new(),
+ });
+ let invalid_revision = coordinator.observed_revision();
+ let candidate = host.prepare(&invalid, invalid_revision);
+ let publication = host.publish(candidate, invalid_revision).unwrap();
+
+ assert!(!publication.report.editor_current);
+ assert!(!publication.report.play_ok);
+ assert!(publication.report.has_good_play);
+ assert_eq!(publication.active.as_ref(), Some(&active));
+ assert_eq!(host.active_client(), Some(&active));
+
+ let response = host.route(RouteRequest {
+ method: RequestMethod::Get,
+ url: "/api/play/ir.json",
+ });
+ assert_eq!(response.status, 200);
+ assert!(matches!(response.body, RouteBody::Bytes(_)));
+ }
+}
diff --git a/crates/spock-host/src/events.rs b/crates/spock-host/src/events.rs
new file mode 100644
index 0000000..fcf1dec
--- /dev/null
+++ b/crates/spock-host/src/events.rs
@@ -0,0 +1,308 @@
+use std::collections::BTreeMap;
+use std::sync::mpsc::{self, Receiver, RecvTimeoutError, SyncSender, TryRecvError, TrySendError};
+use std::sync::{Arc, Mutex, Weak};
+use std::time::Duration;
+
+use serde::Serialize;
+
+pub const PROJECT_EVENT_PROTOCOL: &str = "spock-project-event/1";
+pub const PROJECT_STATUS_PATH: &str = "/~project/status";
+pub const MAX_EVENT_STREAMS_PER_SESSION: usize = 4;
+
+/// One invalidation for the authoritative project-status snapshot.
+///
+/// Events deliberately carry no duplicated status fields. A browser that
+/// reconnects, misses an event, or sees an unfamiliar ID always converges by
+/// fetching `status_url`.
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+pub struct ProjectEvent {
+ pub protocol: &'static str,
+ pub event_id: u64,
+ pub status_url: &'static str,
+}
+
+impl ProjectEvent {
+ fn new(event_id: u64) -> Self {
+ Self {
+ protocol: PROJECT_EVENT_PROTOCOL,
+ event_id,
+ status_url: PROJECT_STATUS_PATH,
+ }
+ }
+
+ fn sse_frame(&self) -> String {
+ let data = serde_json::to_string(self).expect("project event always serializes");
+ format!("id: {}\nevent: invalidate\ndata: {data}\n\n", self.event_id)
+ }
+}
+
+/// Stable, host-session event hub shared across client publications.
+#[derive(Default)]
+struct HubState {
+ current_id: u64,
+ next_client_id: u64,
+ clients: BTreeMap>,
+}
+
+pub struct ProjectEventHub {
+ state: Arc>,
+ admission: Arc,
+}
+
+impl Default for ProjectEventHub {
+ fn default() -> Self {
+ Self::with_admission(Arc::new(EventAdmission::new(MAX_EVENT_STREAMS_PER_SESSION)))
+ }
+}
+
+pub(crate) struct EventAdmission {
+ active: Mutex,
+ limit: usize,
+}
+
+impl EventAdmission {
+ pub(crate) fn new(limit: usize) -> Self {
+ Self {
+ active: Mutex::new(0),
+ limit,
+ }
+ }
+
+ pub(crate) fn try_acquire(self: &Arc) -> Option {
+ let mut active = self.active.lock().expect("event admission lock");
+ if *active >= self.limit {
+ return None;
+ }
+ *active += 1;
+ Some(EventStreamPermit {
+ admission: Arc::clone(self),
+ })
+ }
+
+ #[cfg(test)]
+ fn active(&self) -> usize {
+ *self.active.lock().expect("event admission lock")
+ }
+}
+
+pub(crate) struct EventStreamPermit {
+ admission: Arc,
+}
+
+impl Drop for EventStreamPermit {
+ fn drop(&mut self) {
+ let mut active = self.admission.active.lock().expect("event admission lock");
+ *active = active
+ .checked_sub(1)
+ .expect("event admission count underflow");
+ }
+}
+
+impl ProjectEventHub {
+ pub(crate) fn with_admission(admission: Arc) -> Self {
+ Self {
+ state: Arc::new(Mutex::new(HubState::default())),
+ admission,
+ }
+ }
+
+ #[must_use]
+ pub fn current_id(&self) -> u64 {
+ self.state
+ .lock()
+ .expect("project event hub lock")
+ .current_id
+ }
+
+ /// Register a subscriber and immediately send a snapshot invalidation.
+ ///
+ /// Registration and snapshot creation share the client lock with
+ /// publication, so an event may be duplicated at the boundary but cannot
+ /// be lost.
+ pub fn subscribe(&self) -> Option {
+ let admission_permit = self.admission.try_acquire()?;
+ let (sender, receiver) = mpsc::sync_channel(1);
+ let client_id = {
+ let mut state = self.state.lock().expect("project event hub lock");
+ let _ = sender.try_send(ProjectEvent::new(state.current_id).sse_frame());
+ let client_id = state.next_client_id;
+ state.next_client_id += 1;
+ state.clients.insert(client_id, sender);
+ client_id
+ };
+ Some(ProjectEventStream {
+ receiver,
+ client_id,
+ state: Arc::downgrade(&self.state),
+ _admission_permit: admission_permit,
+ })
+ }
+
+ /// Advance the session event ID after status and artifacts are visible.
+ pub fn publish(&self) -> ProjectEvent {
+ // Allocate and broadcast under one lock so concurrent callers cannot
+ // deliver a later event ID before an earlier one.
+ let mut state = self.state.lock().expect("project event hub lock");
+ state.current_id += 1;
+ let event_id = state.current_id;
+ let event = ProjectEvent::new(event_id);
+ let frame = event.sse_frame();
+ state
+ .clients
+ .retain(|_, sender| match sender.try_send(frame.clone()) {
+ Ok(()) | Err(TrySendError::Full(_)) => true,
+ Err(TrySendError::Disconnected(_)) => false,
+ });
+ event
+ }
+
+ #[cfg(test)]
+ fn subscriber_count(&self) -> usize {
+ self.state
+ .lock()
+ .expect("project event hub lock")
+ .clients
+ .len()
+ }
+}
+
+pub struct ProjectEventStream {
+ receiver: Receiver,
+ client_id: u64,
+ state: Weak>,
+ _admission_permit: EventStreamPermit,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum ProjectEventStreamPoll {
+ Frame(String),
+ Timeout,
+ Closed,
+}
+
+impl ProjectEventStream {
+ /// Poll once without occupying an executor thread.
+ pub fn try_next_frame(&self) -> ProjectEventStreamPoll {
+ match self.receiver.try_recv() {
+ Ok(frame) => ProjectEventStreamPoll::Frame(frame),
+ Err(TryRecvError::Empty) => ProjectEventStreamPoll::Timeout,
+ Err(TryRecvError::Disconnected) => ProjectEventStreamPoll::Closed,
+ }
+ }
+
+ pub fn next_frame_timeout(&self, timeout: Duration) -> ProjectEventStreamPoll {
+ match self.receiver.recv_timeout(timeout) {
+ Ok(frame) => ProjectEventStreamPoll::Frame(frame),
+ Err(RecvTimeoutError::Timeout) => ProjectEventStreamPoll::Timeout,
+ Err(RecvTimeoutError::Disconnected) => ProjectEventStreamPoll::Closed,
+ }
+ }
+}
+
+impl Drop for ProjectEventStream {
+ fn drop(&mut self) {
+ if let Some(state) = self.state.upgrade() {
+ state
+ .lock()
+ .expect("project event hub lock")
+ .clients
+ .remove(&self.client_id);
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn next(stream: &ProjectEventStream) -> String {
+ match stream.next_frame_timeout(Duration::from_millis(10)) {
+ ProjectEventStreamPoll::Frame(frame) => frame,
+ other => panic!("expected frame, got {other:?}"),
+ }
+ }
+
+ fn subscribe(hub: &ProjectEventHub) -> ProjectEventStream {
+ hub.subscribe().expect("event stream admission")
+ }
+
+ #[test]
+ fn a_new_subscriber_immediately_invalidates_to_the_current_snapshot() {
+ let hub = ProjectEventHub::default();
+ hub.publish();
+ hub.publish();
+
+ let frame = next(&subscribe(&hub));
+ assert!(frame.starts_with("id: 2\nevent: invalidate\n"), "{frame}");
+ assert!(frame.contains(PROJECT_EVENT_PROTOCOL), "{frame}");
+ assert!(frame.contains(PROJECT_STATUS_PATH), "{frame}");
+ }
+
+ #[test]
+ fn publications_are_monotonic_and_reach_every_live_subscriber() {
+ let hub = ProjectEventHub::default();
+ let first = subscribe(&hub);
+ let second = subscribe(&hub);
+ let _ = next(&first);
+ let _ = next(&second);
+
+ assert_eq!(hub.publish().event_id, 1);
+ for stream in [&first, &second] {
+ assert!(next(stream).starts_with("id: 1\n"));
+ }
+ assert_eq!(hub.publish().event_id, 2);
+ for stream in [&first, &second] {
+ assert!(next(stream).starts_with("id: 2\n"));
+ }
+ }
+
+ #[test]
+ fn a_dropped_subscriber_does_not_block_later_publication() {
+ let hub = ProjectEventHub::default();
+ drop(subscribe(&hub));
+ assert_eq!(hub.subscriber_count(), 0);
+ assert_eq!(hub.publish().event_id, 1);
+ assert_eq!(hub.current_id(), 1);
+ assert_eq!(hub.subscriber_count(), 0);
+ }
+
+ #[test]
+ fn a_stalled_subscriber_has_one_bounded_invalidation() {
+ let hub = ProjectEventHub::default();
+ let stream = subscribe(&hub);
+ for _ in 0..250 {
+ hub.publish();
+ }
+
+ // The connection may see an older invalidation, but that event tells
+ // it to fetch the authoritative snapshot, now at event ID 250. No
+ // per-revision queue was accumulated.
+ let frame = next(&stream);
+ assert!(frame.starts_with("id: 0\n"));
+ assert_eq!(hub.current_id(), 250);
+ assert_eq!(
+ stream.next_frame_timeout(Duration::from_millis(1)),
+ ProjectEventStreamPoll::Timeout
+ );
+ }
+
+ #[test]
+ fn session_admission_is_bounded_and_reusable_after_drop() {
+ let admission = Arc::new(EventAdmission::new(2));
+ let hub = ProjectEventHub::with_admission(Arc::clone(&admission));
+ let first = subscribe(&hub);
+ let second = subscribe(&hub);
+ assert_eq!(admission.active(), 2);
+ assert!(hub.subscribe().is_none());
+
+ drop(first);
+ assert_eq!(admission.active(), 1);
+ let replacement = subscribe(&hub);
+ assert_eq!(admission.active(), 2);
+
+ drop(second);
+ drop(replacement);
+ assert_eq!(admission.active(), 0);
+ assert_eq!(hub.subscriber_count(), 0);
+ }
+}
diff --git a/crates/spock-host/src/generation.rs b/crates/spock-host/src/generation.rs
new file mode 100644
index 0000000..dbcc7a2
--- /dev/null
+++ b/crates/spock-host/src/generation.rs
@@ -0,0 +1,762 @@
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+use thiserror::Error;
+
+pub const STATUS_PROTOCOL: &str = "spock-project-status/1";
+
+macro_rules! numeric_id {
+ ($name:ident) => {
+ #[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
+ #[serde(transparent)]
+ pub struct $name(u64);
+
+ impl $name {
+ #[must_use]
+ pub const fn get(self) -> u64 {
+ self.0
+ }
+ }
+
+ impl fmt::Display for $name {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.0.fmt(formatter)
+ }
+ }
+ };
+}
+
+numeric_id!(ObservedRevision);
+numeric_id!(BackendGenerationId);
+numeric_id!(ClientGenerationId);
+numeric_id!(ProjectGenerationId);
+
+#[derive(Clone, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(transparent)]
+pub struct Fingerprint(String);
+
+impl Fingerprint {
+ #[must_use]
+ pub fn new(value: impl Into) -> Self {
+ Self(value.into())
+ }
+
+ #[must_use]
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+impl fmt::Display for Fingerprint {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.0.fmt(formatter)
+ }
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HostMode {
+ Start,
+ Dev,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum BackendFreshness {
+ Active,
+ RestartRequired,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClientFreshness {
+ Absent,
+ Building,
+ Active,
+ ColdInvalid,
+ RejectedLastGood,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum EditorFreshness {
+ Current,
+ Stale,
+ ColdInvalid,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClientAttemptState {
+ Building,
+ Published,
+ Rejected,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct ClientAttempt {
+ pub observed_revision: ObservedRevision,
+ pub state: ClientAttemptState,
+ pub diagnostics: Vec,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Observation {
+ pub topology: Fingerprint,
+ pub backend: Fingerprint,
+ pub client: Option,
+ pub changed_backend_inputs: Vec,
+ pub backend_diagnostics: Vec,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum ObservationDisposition {
+ NoChange,
+ Changed {
+ revision: ObservedRevision,
+ backend: BackendFreshness,
+ client_changed: bool,
+ },
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct HealthStatus {
+ pub ready: bool,
+ pub degraded: bool,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct BackendStatus {
+ pub generation_id: BackendGenerationId,
+ pub world_id: String,
+ pub freshness: BackendFreshness,
+ pub active_source_fingerprint: Fingerprint,
+ pub observed_source_fingerprint: Fingerprint,
+ pub active_topology_fingerprint: Fingerprint,
+ pub observed_topology_fingerprint: Fingerprint,
+ pub changed_inputs: Vec,
+ pub diagnostics: Vec,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct ActiveClientStatus {
+ pub generation_id: ClientGenerationId,
+ pub observed_revision: ObservedRevision,
+ /// Consecutive publication revision owned by the Uhura host.
+ pub source_revision: u64,
+ /// Content identity of the exact Uhura source snapshot that produced this
+ /// publication. This is not a digest of generated browser artifacts.
+ pub source_fingerprint: Fingerprint,
+ pub backend_generation_id: BackendGenerationId,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct ClientStatus {
+ pub freshness: ClientFreshness,
+ pub active: Option,
+ pub latest_attempt: Option,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct ActiveProjectStatus {
+ pub generation_id: ProjectGenerationId,
+ pub backend_generation_id: BackendGenerationId,
+ pub client_generation_id: Option,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct ObservedStatus {
+ pub revision: ObservedRevision,
+ pub topology_fingerprint: Fingerprint,
+ pub backend_fingerprint: Fingerprint,
+ pub client_fingerprint: Option,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct ProjectStatus {
+ pub protocol: String,
+ pub mode: HostMode,
+ pub observed: ObservedStatus,
+ pub active_project: ActiveProjectStatus,
+ pub backend: BackendStatus,
+ pub client: ClientStatus,
+ pub editor: EditorFreshness,
+ pub health: HealthStatus,
+}
+
+#[derive(Debug, Error, Eq, PartialEq)]
+pub enum CandidateError {
+ #[error(
+ "client candidate revision {candidate} is stale; newest observed revision is {observed}"
+ )]
+ Stale {
+ candidate: ObservedRevision,
+ observed: ObservedRevision,
+ },
+ #[error("client candidate revision {0} was not started")]
+ NotStarted(ObservedRevision),
+}
+
+#[derive(Clone, Debug)]
+struct ActiveClient {
+ generation_id: ClientGenerationId,
+ observed_revision: ObservedRevision,
+ source_revision: u64,
+ source_fingerprint: Fingerprint,
+ backend_generation_id: BackendGenerationId,
+}
+
+/// Pure session state for fixed and watched project generations.
+///
+/// There is intentionally no method that replaces the active backend. A
+/// process restart constructs another coordinator and another backend world.
+#[derive(Clone, Debug)]
+pub struct GenerationCoordinator {
+ mode: HostMode,
+ observed_revision: ObservedRevision,
+ active_backend_id: BackendGenerationId,
+ active_world_id: String,
+ active_backend: Fingerprint,
+ active_topology: Fingerprint,
+ observed_backend: Fingerprint,
+ observed_topology: Fingerprint,
+ observed_client: Option,
+ backend_freshness: BackendFreshness,
+ changed_backend_inputs: Vec,
+ observed_backend_diagnostics: Vec,
+ client_configured: bool,
+ client_freshness: ClientFreshness,
+ editor_freshness: EditorFreshness,
+ latest_attempt: Option,
+ active_client: Option,
+ project_generation_id: ProjectGenerationId,
+ next_client_generation_id: u64,
+}
+
+impl GenerationCoordinator {
+ #[must_use]
+ pub fn activated(
+ mode: HostMode,
+ backend_fingerprint: Fingerprint,
+ topology_fingerprint: Fingerprint,
+ client_fingerprint: Option,
+ world_id: impl Into,
+ ) -> Self {
+ let client_configured = client_fingerprint.is_some();
+ Self {
+ mode,
+ observed_revision: ObservedRevision(1),
+ active_backend_id: BackendGenerationId(1),
+ active_world_id: world_id.into(),
+ active_backend: backend_fingerprint.clone(),
+ active_topology: topology_fingerprint.clone(),
+ observed_backend: backend_fingerprint,
+ observed_topology: topology_fingerprint,
+ observed_client: client_fingerprint,
+ backend_freshness: BackendFreshness::Active,
+ changed_backend_inputs: Vec::new(),
+ observed_backend_diagnostics: Vec::new(),
+ client_configured,
+ client_freshness: if client_configured {
+ ClientFreshness::Building
+ } else {
+ ClientFreshness::Absent
+ },
+ editor_freshness: if client_configured {
+ EditorFreshness::ColdInvalid
+ } else {
+ EditorFreshness::Current
+ },
+ latest_attempt: None,
+ active_client: None,
+ project_generation_id: ProjectGenerationId(1),
+ next_client_generation_id: 1,
+ }
+ }
+
+ #[must_use]
+ pub const fn observed_revision(&self) -> ObservedRevision {
+ self.observed_revision
+ }
+
+ #[must_use]
+ pub const fn active_backend_generation(&self) -> BackendGenerationId {
+ self.active_backend_id
+ }
+
+ /// Record one coherently captured filesystem state.
+ ///
+ /// TODO(RFD-0023): replace restart-required with off-path backend candidate
+ /// construction and an explicit activation policy after development-world
+ /// semantics are accepted. Never reopen or mutate the active world here.
+ pub fn observe(&mut self, observation: Observation) -> ObservationDisposition {
+ if self.observed_topology == observation.topology
+ && self.observed_backend == observation.backend
+ && self.observed_client == observation.client
+ {
+ return ObservationDisposition::NoChange;
+ }
+
+ let previous_client = self.observed_client.clone();
+ self.observed_revision = ObservedRevision(self.observed_revision.0 + 1);
+ self.observed_topology = observation.topology;
+ self.observed_backend = observation.backend;
+ self.observed_client = observation.client;
+ self.observed_backend_diagnostics = observation.backend_diagnostics;
+
+ // A client build is eligible only for the exact project observation
+ // that started it. Terminalize a superseded attempt in the same state
+ // transition that advances the observation so status can never remain
+ // `building` after that candidate becomes permanently ineligible.
+ let superseded_attempt = self.latest_attempt.as_ref().and_then(|attempt| {
+ (attempt.state == ClientAttemptState::Building).then_some(attempt.observed_revision)
+ });
+ if let Some(revision) = superseded_attempt {
+ self.finish_client_rejection(
+ revision,
+ vec![format!(
+ "client build for observed revision {revision} was superseded by newer project observation {}",
+ self.observed_revision
+ )],
+ );
+ }
+
+ let backend_matches = self.observed_topology == self.active_topology
+ && self.observed_backend == self.active_backend;
+ self.backend_freshness = if backend_matches {
+ self.changed_backend_inputs.clear();
+ BackendFreshness::Active
+ } else {
+ self.changed_backend_inputs = observation.changed_backend_inputs;
+ BackendFreshness::RestartRequired
+ };
+
+ ObservationDisposition::Changed {
+ revision: self.observed_revision,
+ backend: self.backend_freshness,
+ client_changed: previous_client != self.observed_client,
+ }
+ }
+
+ pub fn begin_client_attempt(
+ &mut self,
+ revision: ObservedRevision,
+ ) -> Result<(), CandidateError> {
+ self.require_newest(revision)?;
+ self.latest_attempt = Some(ClientAttempt {
+ observed_revision: revision,
+ state: ClientAttemptState::Building,
+ diagnostics: Vec::new(),
+ });
+ self.client_freshness = ClientFreshness::Building;
+ Ok(())
+ }
+
+ pub fn publish_client(
+ &mut self,
+ observed_revision: ObservedRevision,
+ source_revision: u64,
+ source_fingerprint: Fingerprint,
+ diagnostics: Vec,
+ ) -> Result {
+ self.require_started_newest(observed_revision)?;
+ let generation_id = ClientGenerationId(self.next_client_generation_id);
+ self.next_client_generation_id += 1;
+ self.active_client = Some(ActiveClient {
+ generation_id,
+ observed_revision,
+ source_revision,
+ source_fingerprint,
+ backend_generation_id: self.active_backend_id,
+ });
+ self.latest_attempt = Some(ClientAttempt {
+ observed_revision,
+ state: ClientAttemptState::Published,
+ diagnostics,
+ });
+ self.client_freshness = ClientFreshness::Active;
+ self.editor_freshness = EditorFreshness::Current;
+ self.project_generation_id = ProjectGenerationId(self.project_generation_id.0 + 1);
+ Ok(generation_id)
+ }
+
+ pub fn reject_client(
+ &mut self,
+ revision: ObservedRevision,
+ diagnostics: Vec,
+ ) -> Result<(), CandidateError> {
+ self.require_started_newest(revision)?;
+ self.finish_client_rejection(revision, diagnostics);
+ Ok(())
+ }
+
+ fn finish_client_rejection(&mut self, revision: ObservedRevision, diagnostics: Vec) {
+ self.latest_attempt = Some(ClientAttempt {
+ observed_revision: revision,
+ state: ClientAttemptState::Rejected,
+ diagnostics,
+ });
+ let has_active_client = self.active_client.is_some();
+ self.client_freshness = if has_active_client {
+ ClientFreshness::RejectedLastGood
+ } else {
+ ClientFreshness::ColdInvalid
+ };
+ self.editor_freshness = if has_active_client {
+ EditorFreshness::Stale
+ } else {
+ EditorFreshness::ColdInvalid
+ };
+ }
+
+ #[must_use]
+ pub fn status(&self) -> ProjectStatus {
+ let active_client = self
+ .active_client
+ .as_ref()
+ .map(|client| ActiveClientStatus {
+ generation_id: client.generation_id,
+ observed_revision: client.observed_revision,
+ source_revision: client.source_revision,
+ source_fingerprint: client.source_fingerprint.clone(),
+ backend_generation_id: client.backend_generation_id,
+ });
+ ProjectStatus {
+ protocol: STATUS_PROTOCOL.to_owned(),
+ mode: self.mode,
+ observed: ObservedStatus {
+ revision: self.observed_revision,
+ topology_fingerprint: self.observed_topology.clone(),
+ backend_fingerprint: self.observed_backend.clone(),
+ client_fingerprint: self.observed_client.clone(),
+ },
+ active_project: ActiveProjectStatus {
+ generation_id: self.project_generation_id,
+ backend_generation_id: self.active_backend_id,
+ client_generation_id: active_client.as_ref().map(|client| client.generation_id),
+ },
+ backend: BackendStatus {
+ generation_id: self.active_backend_id,
+ world_id: self.active_world_id.clone(),
+ freshness: self.backend_freshness,
+ active_source_fingerprint: self.active_backend.clone(),
+ observed_source_fingerprint: self.observed_backend.clone(),
+ active_topology_fingerprint: self.active_topology.clone(),
+ observed_topology_fingerprint: self.observed_topology.clone(),
+ changed_inputs: self.changed_backend_inputs.clone(),
+ diagnostics: self.observed_backend_diagnostics.clone(),
+ },
+ client: ClientStatus {
+ freshness: if self.client_configured {
+ self.client_freshness
+ } else {
+ ClientFreshness::Absent
+ },
+ active: active_client,
+ latest_attempt: self.latest_attempt.clone(),
+ },
+ editor: self.editor_freshness,
+ health: HealthStatus {
+ ready: true,
+ degraded: self.backend_freshness == BackendFreshness::RestartRequired
+ || matches!(
+ self.client_freshness,
+ ClientFreshness::ColdInvalid | ClientFreshness::RejectedLastGood
+ ),
+ },
+ }
+ }
+
+ fn require_newest(&self, revision: ObservedRevision) -> Result<(), CandidateError> {
+ if revision == self.observed_revision {
+ Ok(())
+ } else {
+ Err(CandidateError::Stale {
+ candidate: revision,
+ observed: self.observed_revision,
+ })
+ }
+ }
+
+ fn require_started_newest(&self, revision: ObservedRevision) -> Result<(), CandidateError> {
+ self.require_newest(revision)?;
+ match &self.latest_attempt {
+ Some(attempt)
+ if attempt.observed_revision == revision
+ && attempt.state == ClientAttemptState::Building =>
+ {
+ Ok(())
+ }
+ _ => Err(CandidateError::NotStarted(revision)),
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn fingerprint(value: &str) -> Fingerprint {
+ Fingerprint::new(value)
+ }
+
+ fn coordinator() -> GenerationCoordinator {
+ GenerationCoordinator::activated(
+ HostMode::Dev,
+ fingerprint("backend-a"),
+ fingerprint("topology-a"),
+ Some(fingerprint("client-a")),
+ "world-a",
+ )
+ }
+
+ fn observation(backend: &str, topology: &str, client: &str) -> Observation {
+ Observation {
+ topology: fingerprint(topology),
+ backend: fingerprint(backend),
+ client: Some(fingerprint(client)),
+ changed_backend_inputs: vec!["backend/app.spock".to_owned()],
+ backend_diagnostics: Vec::new(),
+ }
+ }
+
+ #[test]
+ fn identical_observation_is_a_no_op() {
+ let mut coordinator = coordinator();
+ assert_eq!(
+ coordinator.observe(observation("backend-a", "topology-a", "client-a")),
+ ObservationDisposition::NoChange
+ );
+ assert_eq!(coordinator.observed_revision(), ObservedRevision(1));
+ }
+
+ #[test]
+ fn backend_change_requires_restart_without_replacing_any_active_identity() {
+ let mut coordinator = coordinator();
+ let backend_id = coordinator.active_backend_generation();
+ let project_id = coordinator.status().active_project.generation_id;
+
+ assert_eq!(
+ coordinator.observe(observation("backend-b", "topology-a", "client-a")),
+ ObservationDisposition::Changed {
+ revision: ObservedRevision(2),
+ backend: BackendFreshness::RestartRequired,
+ client_changed: false,
+ }
+ );
+
+ let status = coordinator.status();
+ assert_eq!(status.backend.generation_id, backend_id);
+ assert_eq!(status.active_project.generation_id, project_id);
+ assert_eq!(
+ status.backend.active_source_fingerprint,
+ fingerprint("backend-a")
+ );
+ assert_eq!(
+ status.backend.observed_source_fingerprint,
+ fingerprint("backend-b")
+ );
+ assert!(status.health.ready);
+ assert!(status.health.degraded);
+ }
+
+ #[test]
+ fn topology_and_backend_must_both_revert_before_restart_required_clears() {
+ let mut coordinator = coordinator();
+ coordinator.observe(observation("backend-b", "topology-b", "client-a"));
+ coordinator.observe(observation("backend-a", "topology-b", "client-a"));
+ assert_eq!(
+ coordinator.status().backend.freshness,
+ BackendFreshness::RestartRequired
+ );
+
+ coordinator.observe(observation("backend-a", "topology-a", "client-a"));
+ let status = coordinator.status();
+ assert_eq!(status.backend.freshness, BackendFreshness::Active);
+ assert!(status.backend.changed_inputs.is_empty());
+ assert_eq!(status.backend.generation_id, BackendGenerationId(1));
+ }
+
+ #[test]
+ fn client_publication_is_bound_to_the_active_backend() {
+ let mut coordinator = coordinator();
+ coordinator
+ .begin_client_attempt(ObservedRevision(1))
+ .unwrap();
+ let client_id = coordinator
+ .publish_client(ObservedRevision(1), 1, fingerprint("source-a"), Vec::new())
+ .unwrap();
+ let status = coordinator.status();
+ assert_eq!(status.client.freshness, ClientFreshness::Active);
+ assert_eq!(
+ status.client.active.as_ref().unwrap().generation_id,
+ client_id
+ );
+ assert_eq!(
+ status.client.active.as_ref().unwrap().backend_generation_id,
+ BackendGenerationId(1)
+ );
+ assert_eq!(
+ status.client.active.as_ref().unwrap().source_fingerprint,
+ fingerprint("source-a")
+ );
+ assert_eq!(status.active_project.client_generation_id, Some(client_id));
+ let value = serde_json::to_value(&status).unwrap();
+ assert_eq!(value["client"]["active"]["source_fingerprint"], "source-a");
+ assert!(value["client"]["active"]
+ .get("artifact_fingerprint")
+ .is_none());
+ }
+
+ #[test]
+ fn initial_client_rejection_is_cold_without_claiming_a_last_good_generation() {
+ let mut coordinator = coordinator();
+ coordinator
+ .begin_client_attempt(ObservedRevision(1))
+ .unwrap();
+ coordinator
+ .reject_client(ObservedRevision(1), vec!["UH0001".to_owned()])
+ .unwrap();
+
+ let status = coordinator.status();
+ assert_eq!(status.client.freshness, ClientFreshness::ColdInvalid);
+ assert!(status.client.active.is_none());
+ assert_eq!(
+ status.client.latest_attempt,
+ Some(ClientAttempt {
+ observed_revision: ObservedRevision(1),
+ state: ClientAttemptState::Rejected,
+ diagnostics: vec!["UH0001".to_owned()],
+ })
+ );
+ assert_eq!(status.editor, EditorFreshness::ColdInvalid);
+ assert!(status.health.ready);
+ assert!(status.health.degraded);
+
+ let value = serde_json::to_value(status).unwrap();
+ assert_eq!(value["client"]["freshness"], "cold_invalid");
+ assert!(value["client"]["active"].is_null());
+ }
+
+ #[test]
+ fn invalid_client_retains_last_good_and_keeps_attempt_identity_separate() {
+ let mut coordinator = coordinator();
+ coordinator
+ .begin_client_attempt(ObservedRevision(1))
+ .unwrap();
+ let good = coordinator
+ .publish_client(ObservedRevision(1), 1, fingerprint("source-a"), Vec::new())
+ .unwrap();
+
+ coordinator.observe(observation("backend-a", "topology-a", "client-b"));
+ coordinator
+ .begin_client_attempt(ObservedRevision(2))
+ .unwrap();
+ coordinator
+ .reject_client(ObservedRevision(2), vec!["UH0001".to_owned()])
+ .unwrap();
+
+ let status = coordinator.status();
+ assert_eq!(status.client.freshness, ClientFreshness::RejectedLastGood);
+ assert_eq!(status.client.active.unwrap().generation_id, good);
+ assert_eq!(
+ status.client.latest_attempt,
+ Some(ClientAttempt {
+ observed_revision: ObservedRevision(2),
+ state: ClientAttemptState::Rejected,
+ diagnostics: vec!["UH0001".to_owned()],
+ })
+ );
+ assert_eq!(status.editor, EditorFreshness::Stale);
+ }
+
+ #[test]
+ fn a_newer_observation_permanently_makes_an_older_candidate_ineligible() {
+ let mut coordinator = coordinator();
+ coordinator
+ .begin_client_attempt(ObservedRevision(1))
+ .unwrap();
+ coordinator.observe(observation("backend-a", "topology-a", "client-b"));
+ assert_eq!(
+ coordinator.publish_client(
+ ObservedRevision(1),
+ 1,
+ fingerprint("source-old"),
+ Vec::new(),
+ ),
+ Err(CandidateError::Stale {
+ candidate: ObservedRevision(1),
+ observed: ObservedRevision(2),
+ })
+ );
+ let status = coordinator.status();
+ assert_eq!(status.client.freshness, ClientFreshness::ColdInvalid);
+ assert!(status.client.active.is_none());
+ let attempt = status.client.latest_attempt.expect("terminal attempt");
+ assert_eq!(attempt.observed_revision, ObservedRevision(1));
+ assert_eq!(attempt.state, ClientAttemptState::Rejected);
+ assert!(attempt
+ .diagnostics
+ .iter()
+ .any(|diagnostic| diagnostic.contains("superseded by newer project observation 2")));
+ }
+
+ #[test]
+ fn client_can_publish_while_backend_restart_is_required() {
+ let mut coordinator = coordinator();
+ coordinator.observe(observation("backend-b", "topology-a", "client-b"));
+ coordinator
+ .begin_client_attempt(ObservedRevision(2))
+ .unwrap();
+ coordinator
+ .publish_client(ObservedRevision(2), 2, fingerprint("source-b"), Vec::new())
+ .unwrap();
+
+ let status = coordinator.status();
+ assert_eq!(status.backend.freshness, BackendFreshness::RestartRequired);
+ assert_eq!(status.client.freshness, ClientFreshness::Active);
+ assert_eq!(
+ status.client.active.unwrap().backend_generation_id,
+ BackendGenerationId(1)
+ );
+ }
+
+ #[test]
+ fn status_protocol_and_attempted_generation_are_serialized() {
+ let mut coordinator = coordinator();
+ coordinator
+ .begin_client_attempt(ObservedRevision(1))
+ .unwrap();
+ let value = serde_json::to_value(coordinator.status()).unwrap();
+ assert_eq!(value["protocol"], STATUS_PROTOCOL);
+ assert_eq!(value["client"]["freshness"], "building");
+ assert_eq!(value["client"]["latest_attempt"]["state"], "building");
+ assert_eq!(value["backend"]["generation_id"], 1);
+ }
+
+ #[test]
+ fn successful_client_publication_preserves_warnings() {
+ let mut coordinator = coordinator();
+ coordinator
+ .begin_client_attempt(ObservedRevision(1))
+ .unwrap();
+ coordinator
+ .publish_client(
+ ObservedRevision(1),
+ 1,
+ fingerprint("source-a"),
+ vec!["UH1000: warning".to_owned()],
+ )
+ .unwrap();
+
+ assert_eq!(
+ coordinator
+ .status()
+ .client
+ .latest_attempt
+ .expect("published attempt")
+ .diagnostics,
+ vec!["UH1000: warning"]
+ );
+ }
+}
diff --git a/crates/spock-host/src/http.rs b/crates/spock-host/src/http.rs
new file mode 100644
index 0000000..631bbcb
--- /dev/null
+++ b/crates/spock-host/src/http.rs
@@ -0,0 +1,798 @@
+use std::convert::Infallible;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, RwLock};
+use std::time::Duration;
+
+use axum::body::{Body, Bytes};
+use axum::extract::Request;
+use axum::http::header::{CACHE_CONTROL, CONTENT_TYPE, RETRY_AFTER};
+use axum::http::{HeaderName, HeaderValue, StatusCode};
+use axum::response::{IntoResponse, Redirect, Response};
+use axum::routing::get;
+use axum::{Json, Router};
+use serde::Serialize;
+use serde_json::json;
+use spock_runtime::error::ApiError;
+use spock_runtime::generation::BackendGeneration;
+use tokio::sync::mpsc;
+use tokio::sync::mpsc::error::TrySendError;
+use tokio_stream::wrappers::ReceiverStream;
+use uhura_host::{EventStreamPoll, RequestMethod, RouteBody, RouteRequest, RouteResponse};
+
+use crate::events::{EventAdmission, EventStreamPermit, MAX_EVENT_STREAMS_PER_SESSION};
+use crate::{
+ classify_route, BackendGenerationId, ClientHost, GenerationCoordinator, HostMode,
+ ProjectEventHub, ProjectEventStreamPoll, ProjectGenerationId, ProjectStatus, RouteOwner,
+};
+
+pub const HOST_ENVIRONMENT_PROTOCOL: &str = "spock-host-environment/1";
+const STREAM_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+/// One active backend, optional client publication service, and stable
+/// host-session status/event state.
+///
+/// The backend generation is immutable. Development observation can mutate
+/// only the coordinator and client publication behind their narrow locks.
+pub struct FrameworkSession {
+ backend: Arc,
+ publication: Arc>,
+ events: Arc,
+ stream_admission: Arc,
+ stream_shutdown: Arc,
+}
+
+pub(crate) struct PublicationState {
+ pub coordinator: GenerationCoordinator,
+ pub client: Option,
+}
+
+impl FrameworkSession {
+ #[must_use]
+ pub(crate) fn new(
+ backend: BackendGeneration,
+ client: Option,
+ coordinator: GenerationCoordinator,
+ ) -> Self {
+ let stream_admission = Arc::new(EventAdmission::new(MAX_EVENT_STREAMS_PER_SESSION));
+ Self {
+ backend: Arc::new(backend),
+ publication: Arc::new(RwLock::new(PublicationState {
+ coordinator,
+ client,
+ })),
+ events: Arc::new(ProjectEventHub::with_admission(Arc::clone(
+ &stream_admission,
+ ))),
+ stream_admission,
+ stream_shutdown: Arc::new(AtomicBool::new(false)),
+ }
+ }
+
+ #[must_use]
+ pub fn backend(&self) -> Arc {
+ Arc::clone(&self.backend)
+ }
+
+ #[must_use]
+ pub(crate) fn publication(&self) -> Arc> {
+ Arc::clone(&self.publication)
+ }
+
+ #[must_use]
+ pub(crate) fn events(&self) -> Arc {
+ Arc::clone(&self.events)
+ }
+
+ pub(crate) fn shutdown_streams(&self) {
+ self.stream_shutdown.store(true, Ordering::Release);
+ }
+
+ #[must_use]
+ pub fn status(&self) -> ProjectStatus {
+ self.publication
+ .read()
+ .expect("project publication lock")
+ .coordinator
+ .status()
+ }
+
+ /// Build the one-origin router without binding a listener.
+ pub fn router(&self) -> Result {
+ let authority = self.backend.authority_router()?;
+ let graphql_available =
+ !self.backend.contract().tables.is_empty() || !self.backend.contract().fns.is_empty();
+
+ let status_state = self.publication();
+ let environment_state = self.publication();
+ let health_state = self.publication();
+ let project_events = self.events();
+ let publication = self.publication();
+ let client_configured = publication
+ .read()
+ .expect("project publication lock")
+ .client
+ .is_some();
+ let event_shutdown = Arc::clone(&self.stream_shutdown);
+ let client_shutdown = Arc::clone(&self.stream_shutdown);
+ let client_stream_admission = Arc::clone(&self.stream_admission);
+
+ let framework = Router::new()
+ .route(
+ "/~project/status",
+ get(move || async move {
+ (
+ [(CACHE_CONTROL, HeaderValue::from_static("no-store"))],
+ Json(
+ status_state
+ .read()
+ .expect("project publication lock")
+ .coordinator
+ .status(),
+ ),
+ )
+ }),
+ )
+ .route(
+ "/~project/environment",
+ get(move || async move {
+ let status = environment_state
+ .read()
+ .expect("project publication lock")
+ .coordinator
+ .status();
+ (
+ [(CACHE_CONTROL, HeaderValue::from_static("no-store"))],
+ Json(HostEnvironment::from_status(&status, graphql_available)),
+ )
+ }),
+ )
+ .route(
+ "/~project/events",
+ get(move || {
+ let stream = project_events.subscribe();
+ let shutdown = Arc::clone(&event_shutdown);
+ async move {
+ match stream {
+ Some(stream) => project_event_response(stream, shutdown),
+ None => event_capacity_error(),
+ }
+ }
+ })
+ .head(|| async { event_method_error() }),
+ )
+ .route(
+ "/~health",
+ get(move || async move {
+ let status = health_state
+ .read()
+ .expect("project publication lock")
+ .coordinator
+ .status();
+ let code = if status.health.ready {
+ StatusCode::OK
+ } else {
+ StatusCode::SERVICE_UNAVAILABLE
+ };
+ (
+ code,
+ [(CACHE_CONTROL, HeaderValue::from_static("no-store"))],
+ Json(json!({
+ "ok": status.health.ready,
+ "ready": status.health.ready,
+ "degraded": status.health.degraded,
+ })),
+ )
+ }),
+ )
+ .fallback(move |request: Request| {
+ let publication = Arc::clone(&publication);
+ let shutdown = Arc::clone(&client_shutdown);
+ let stream_admission = Arc::clone(&client_stream_admission);
+ async move {
+ combined_fallback(
+ request,
+ publication,
+ client_configured,
+ shutdown,
+ stream_admission,
+ )
+ .await
+ }
+ });
+
+ Ok(authority.merge(framework))
+ }
+}
+
+#[derive(Serialize)]
+struct HostEnvironment {
+ protocol: &'static str,
+ mode: HostMode,
+ project_generation_id: ProjectGenerationId,
+ backend_generation_id: BackendGenerationId,
+ authority: AuthorityEnvironment,
+}
+
+#[derive(Serialize)]
+struct AuthorityEnvironment {
+ graphql_path: Option<&'static str>,
+ rpc_path: &'static str,
+ storage_path: &'static str,
+}
+
+impl HostEnvironment {
+ fn from_status(status: &ProjectStatus, graphql_available: bool) -> Self {
+ Self {
+ protocol: HOST_ENVIRONMENT_PROTOCOL,
+ mode: status.mode,
+ project_generation_id: status.active_project.generation_id,
+ backend_generation_id: status.active_project.backend_generation_id,
+ authority: AuthorityEnvironment {
+ graphql_path: graphql_available.then_some("/graphql/v1"),
+ rpc_path: "/rest/v1/rpc",
+ storage_path: "/storage/v1",
+ },
+ }
+ }
+}
+
+async fn combined_fallback(
+ request: Request,
+ publication: Arc>,
+ client_configured: bool,
+ stream_shutdown: Arc,
+ stream_admission: Arc,
+) -> Response {
+ let path = request.uri().path().to_string();
+ match classify_route(&path, client_configured) {
+ RouteOwner::Client => {
+ route_client(request, &publication, stream_shutdown, stream_admission)
+ }
+ RouteOwner::Framework if path == "/" && !client_configured => {
+ if matches!(
+ *request.method(),
+ axum::http::Method::GET | axum::http::Method::HEAD
+ ) {
+ Redirect::temporary("/~studio").into_response()
+ } else {
+ let mut response = (
+ StatusCode::METHOD_NOT_ALLOWED,
+ Json(json!({
+ "error": {
+ "code": "bad_request",
+ "kind": "bad_request",
+ "table": null,
+ "fields": [],
+ "message": "the backend-only project root accepts GET and HEAD",
+ }
+ })),
+ )
+ .into_response();
+ response
+ .headers_mut()
+ .insert("allow", HeaderValue::from_static("GET, HEAD"));
+ response
+ }
+ }
+ RouteOwner::Framework
+ | RouteOwner::Authority
+ | RouteOwner::ProtocolNotFound
+ | RouteOwner::NotFound => protocol_not_found(&path),
+ }
+}
+
+fn protocol_not_found(path: &str) -> Response {
+ ApiError::not_found(format!("no such path: {path}")).into_response()
+}
+
+fn route_client(
+ request: Request,
+ publication: &RwLock,
+ stream_shutdown: Arc,
+ stream_admission: Arc,
+) -> Response {
+ let method = match *request.method() {
+ axum::http::Method::GET => RequestMethod::Get,
+ axum::http::Method::HEAD => RequestMethod::Head,
+ _ => RequestMethod::Other,
+ };
+ let url = request
+ .uri()
+ .path_and_query()
+ .map_or_else(|| request.uri().path(), |value| value.as_str());
+ let publication = publication.read().expect("project publication lock");
+ let Some(client) = &publication.client else {
+ return protocol_not_found(request.uri().path());
+ };
+ let response = client.route(RouteRequest { method, url });
+ drop(publication);
+ uhura_response(response, stream_shutdown, stream_admission)
+}
+
+fn uhura_response(
+ response: RouteResponse,
+ stream_shutdown: Arc,
+ stream_admission: Arc,
+) -> Response {
+ let status = StatusCode::from_u16(response.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
+ let mut builder = Response::builder().status(status);
+ for (name, value) in response.headers {
+ let Ok(name) = HeaderName::from_bytes(name.as_bytes()) else {
+ return internal_transport_error("Uhura returned an invalid response header name");
+ };
+ let Ok(value) = HeaderValue::from_str(&value) else {
+ return internal_transport_error("Uhura returned an invalid response header value");
+ };
+ builder = builder.header(name, value);
+ }
+
+ let body = match response.body {
+ RouteBody::Bytes(bytes) => Body::from(bytes.into_inner()),
+ RouteBody::Events(stream) => {
+ let Some(admission_permit) = stream_admission.try_acquire() else {
+ return event_capacity_error();
+ };
+ let (sender, receiver) = mpsc::channel::>(1);
+ tokio::spawn(async move {
+ let _admission_permit: EventStreamPermit = admission_permit;
+ loop {
+ if sender.is_closed() || stream_shutdown.load(Ordering::Acquire) {
+ break;
+ }
+ match stream.try_next_frame() {
+ EventStreamPoll::Frame(frame) => {
+ match sender.try_send(Ok(Bytes::from(frame))) {
+ Ok(()) | Err(TrySendError::Full(_)) => {}
+ Err(TrySendError::Closed(_)) => break,
+ }
+ }
+ EventStreamPoll::Timeout => {
+ tokio::time::sleep(STREAM_POLL_INTERVAL).await;
+ }
+ EventStreamPoll::Closed => break,
+ }
+ }
+ });
+ Body::from_stream(ReceiverStream::new(receiver))
+ }
+ };
+ builder
+ .body(body)
+ .unwrap_or_else(|_| internal_transport_error("could not build the Uhura response"))
+}
+
+fn project_event_response(
+ stream: crate::ProjectEventStream,
+ stream_shutdown: Arc,
+) -> Response {
+ let (sender, receiver) = mpsc::channel::>(1);
+ tokio::spawn(async move {
+ loop {
+ if sender.is_closed() || stream_shutdown.load(Ordering::Acquire) {
+ break;
+ }
+ match stream.try_next_frame() {
+ ProjectEventStreamPoll::Frame(frame) => {
+ match sender.try_send(Ok(Bytes::from(frame))) {
+ Ok(()) | Err(TrySendError::Full(_)) => {}
+ Err(TrySendError::Closed(_)) => break,
+ }
+ }
+ ProjectEventStreamPoll::Timeout => {
+ tokio::time::sleep(STREAM_POLL_INTERVAL).await;
+ }
+ ProjectEventStreamPoll::Closed => break,
+ }
+ }
+ });
+
+ Response::builder()
+ .status(StatusCode::OK)
+ .header(CONTENT_TYPE, "text/event-stream; charset=utf-8")
+ .header(CACHE_CONTROL, "no-store")
+ .body(Body::from_stream(ReceiverStream::new(receiver)))
+ .unwrap_or_else(|_| internal_transport_error("could not build the project event response"))
+}
+
+fn event_method_error() -> Response {
+ let mut response = (
+ StatusCode::METHOD_NOT_ALLOWED,
+ Json(json!({
+ "error": {
+ "code": "bad_request",
+ "kind": "bad_request",
+ "table": null,
+ "fields": [],
+ "message": "/~project/events requires GET",
+ }
+ })),
+ )
+ .into_response();
+ response
+ .headers_mut()
+ .insert("allow", HeaderValue::from_static("GET"));
+ response
+}
+
+fn event_capacity_error() -> Response {
+ let mut response = (
+ StatusCode::SERVICE_UNAVAILABLE,
+ Json(json!({
+ "error": {
+ "code": "unavailable",
+ "kind": "unavailable",
+ "table": null,
+ "fields": [],
+ "message": "too many active framework event streams; retry shortly",
+ }
+ })),
+ )
+ .into_response();
+ response
+ .headers_mut()
+ .insert(RETRY_AFTER, HeaderValue::from_static("1"));
+ response
+ .headers_mut()
+ .insert(CACHE_CONTROL, HeaderValue::from_static("no-store"));
+ response
+}
+
+fn internal_transport_error(message: &'static str) -> Response {
+ (
+ StatusCode::INTERNAL_SERVER_ERROR,
+ Json(json!({
+ "error": {
+ "code": "internal",
+ "kind": "internal",
+ "table": null,
+ "fields": [],
+ "message": message,
+ }
+ })),
+ )
+ .into_response()
+}
+
+#[cfg(test)]
+mod tests {
+ use std::collections::BTreeMap;
+ use std::fs;
+
+ use axum::body::to_bytes;
+ use axum::http::Request;
+ use spock_project::minimal_uhura_client_template;
+ use spock_runtime::generation::CapturedBackend;
+ use tempfile::tempdir;
+ use tower::ServiceExt;
+ use uhura_host::{capture_project_snapshot, WebAssets};
+
+ use super::*;
+ use crate::{client_source_fingerprint, ClientHost, Fingerprint, GenerationCoordinator};
+
+ fn backend_only() -> FrameworkSession {
+ session_with_source("")
+ }
+
+ fn session_with_source(source: &str) -> FrameworkSession {
+ let backend =
+ BackendGeneration::from_captured(CapturedBackend::new(source, BTreeMap::new()), None)
+ .expect("backend generation");
+ let coordinator = GenerationCoordinator::activated(
+ HostMode::Start,
+ Fingerprint::new("backend"),
+ Fingerprint::new("topology"),
+ None,
+ "world-1",
+ );
+ FrameworkSession::new(backend, None, coordinator)
+ }
+
+ fn client_session() -> FrameworkSession {
+ let project = tempdir().expect("temporary client project");
+ for file in minimal_uhura_client_template().files() {
+ let path = project.path().join(file.path().as_path());
+ fs::create_dir_all(path.parent().expect("client file parent")).unwrap();
+ fs::write(path, file.contents()).unwrap();
+ }
+ let snapshot = capture_project_snapshot(project.path());
+
+ let web_root = tempdir().expect("temporary web assets");
+ fs::create_dir_all(web_root.path().join("assets")).unwrap();
+ fs::write(
+ web_root.path().join("index.html"),
+ r#""#,
+ )
+ .unwrap();
+ fs::write(web_root.path().join("assets/app.js"), "export {};\n").unwrap();
+ let web = WebAssets::from_frontend_directory(web_root.path()).unwrap();
+
+ let backend =
+ BackendGeneration::from_captured(CapturedBackend::new("", BTreeMap::new()), None)
+ .expect("backend generation");
+ let source_fingerprint = client_source_fingerprint(&snapshot);
+ let mut coordinator = GenerationCoordinator::activated(
+ HostMode::Start,
+ Fingerprint::new("backend"),
+ Fingerprint::new("topology"),
+ Some(source_fingerprint.clone()),
+ "world-1",
+ );
+ let revision = coordinator.observed_revision();
+ coordinator.begin_client_attempt(revision).unwrap();
+ let (client, publication) = ClientHost::activate(web, &snapshot, revision).unwrap();
+ assert!(publication.report.editor_current);
+ assert!(publication.report.play_ok);
+ coordinator
+ .publish_client(
+ revision,
+ publication.report.source_revision,
+ source_fingerprint,
+ Vec::new(),
+ )
+ .unwrap();
+ FrameworkSession::new(backend, Some(client), coordinator)
+ }
+
+ async fn response_json(response: Response) -> serde_json::Value {
+ let bytes = to_bytes(response.into_body(), usize::MAX)
+ .await
+ .expect("body bytes");
+ serde_json::from_slice(&bytes).expect("JSON body")
+ }
+
+ #[tokio::test]
+ async fn backend_only_root_redirects_and_unknown_protocol_paths_are_json() {
+ let router = backend_only().router().expect("router");
+ let root = router
+ .clone()
+ .oneshot(Request::get("/").body(Body::empty()).unwrap())
+ .await
+ .unwrap();
+ assert_eq!(root.status(), StatusCode::TEMPORARY_REDIRECT);
+ assert_eq!(root.headers()["location"], "/~studio");
+
+ let unknown = router
+ .clone()
+ .oneshot(
+ Request::get("/api/not-a-client-route")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(unknown.status(), StatusCode::NOT_FOUND);
+ assert_eq!(response_json(unknown).await["error"]["code"], "not_found");
+
+ let post_root = router
+ .clone()
+ .oneshot(Request::post("/").body(Body::empty()).unwrap())
+ .await
+ .unwrap();
+ assert_eq!(post_root.status(), StatusCode::METHOD_NOT_ALLOWED);
+ assert_eq!(post_root.headers()["allow"], "GET, HEAD");
+
+ let event_head = router
+ .oneshot(
+ Request::head("/~project/events")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(event_head.status(), StatusCode::METHOD_NOT_ALLOWED);
+ assert_eq!(event_head.headers()["allow"], "GET");
+ }
+
+ #[tokio::test]
+ async fn encoded_client_protocol_spelling_cannot_fall_through_to_spa_html() {
+ let session = backend_only();
+ let response = combined_fallback(
+ Request::get("/api%2Feditor/state")
+ .body(Body::empty())
+ .unwrap(),
+ session.publication(),
+ true,
+ Arc::new(AtomicBool::new(false)),
+ Arc::new(EventAdmission::new(MAX_EVENT_STREAMS_PER_SESSION)),
+ )
+ .await;
+
+ assert_eq!(response.status(), StatusCode::NOT_FOUND);
+ assert_eq!(response.headers()[CONTENT_TYPE], "application/json");
+ let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+ assert!(!bytes
+ .windows(b"(&bytes).unwrap()["error"]["code"],
+ "not_found"
+ );
+ }
+
+ #[tokio::test]
+ async fn fixed_status_environment_health_and_empty_contract_share_one_router() {
+ let router = backend_only().router().expect("router");
+ for path in [
+ "/~project/status",
+ "/~project/environment",
+ "/~health",
+ "/~contract",
+ ] {
+ let response = router
+ .clone()
+ .oneshot(Request::get(path).body(Body::empty()).unwrap())
+ .await
+ .unwrap();
+ assert_eq!(response.status(), StatusCode::OK, "{path}");
+ if path != "/~contract" {
+ assert_eq!(response.headers()[CACHE_CONTROL], "no-store", "{path}");
+ }
+ }
+
+ let environment = router
+ .clone()
+ .oneshot(
+ Request::get("/~project/environment")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ let environment = response_json(environment).await;
+ assert_eq!(environment["protocol"], HOST_ENVIRONMENT_PROTOCOL);
+ assert_eq!(environment["mode"], "start");
+ assert!(environment["authority"]["graphql_path"].is_null());
+
+ let graphql = router
+ .oneshot(Request::get("/graphql/v1").body(Body::empty()).unwrap())
+ .await
+ .unwrap();
+ assert_eq!(graphql.status(), StatusCode::NOT_FOUND);
+ assert_eq!(response_json(graphql).await["error"]["kind"], "not_found");
+ }
+
+ #[tokio::test]
+ async fn a_non_empty_contract_advertises_graphql() {
+ let router = session_with_source("table note { key id: uuid = auto }\n")
+ .router()
+ .expect("router");
+ let environment = router
+ .oneshot(
+ Request::get("/~project/environment")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ response_json(environment).await["authority"]["graphql_path"],
+ "/graphql/v1"
+ );
+ }
+
+ #[tokio::test]
+ async fn combined_host_grants_no_cross_origin_access() {
+ let router = backend_only().router().expect("router");
+ for path in ["/~project/status", "/~contract"] {
+ let response = router
+ .clone()
+ .oneshot(
+ Request::get(path)
+ .header("origin", "https://arbitrary.example")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(response.status(), StatusCode::OK, "{path}");
+ assert!(
+ !response
+ .headers()
+ .contains_key("access-control-allow-origin"),
+ "{path} must remain same-origin"
+ );
+ }
+
+ let preflight = router
+ .oneshot(
+ Request::builder()
+ .method("OPTIONS")
+ .uri("/rest/v1/rpc/example")
+ .header("origin", "https://arbitrary.example")
+ .header("access-control-request-method", "POST")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert!(!preflight
+ .headers()
+ .contains_key("access-control-allow-origin"));
+ }
+
+ #[tokio::test]
+ async fn project_and_uhura_event_routes_share_one_reusable_session_budget() {
+ let router = client_session().router().expect("router");
+ let mut streams = Vec::new();
+ for path in [
+ "/~project/events",
+ "/api/editor/events",
+ "/~project/events",
+ "/api/play/events",
+ ] {
+ let response = router
+ .clone()
+ .oneshot(Request::get(path).body(Body::empty()).unwrap())
+ .await
+ .unwrap();
+ assert_eq!(response.status(), StatusCode::OK, "GET {path}");
+ streams.push(response);
+ }
+
+ for path in ["/~project/events", "/api/editor/events"] {
+ let saturated = router
+ .clone()
+ .oneshot(Request::get(path).body(Body::empty()).unwrap())
+ .await
+ .unwrap();
+ assert_eq!(
+ saturated.status(),
+ StatusCode::SERVICE_UNAVAILABLE,
+ "GET {path}"
+ );
+ assert_eq!(saturated.headers()[RETRY_AFTER], "1");
+ assert_eq!(
+ response_json(saturated).await["error"]["code"],
+ "unavailable"
+ );
+ }
+
+ drop(streams.pop().expect("one admitted stream"));
+ let replacement = tokio::time::timeout(Duration::from_secs(1), async {
+ loop {
+ let response = router
+ .clone()
+ .oneshot(
+ Request::get("/api/editor/events")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ if response.status() == StatusCode::OK {
+ break response;
+ }
+ assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+ tokio::time::sleep(STREAM_POLL_INTERVAL).await;
+ }
+ })
+ .await
+ .expect("dropped event response should release admission");
+ streams.push(replacement);
+ assert_eq!(streams.len(), MAX_EVENT_STREAMS_PER_SESSION);
+
+ drop(streams.remove(0));
+ let replacement = tokio::time::timeout(Duration::from_secs(1), async {
+ loop {
+ let response = router
+ .clone()
+ .oneshot(
+ Request::get("/api/play/events")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ if response.status() == StatusCode::OK {
+ break response;
+ }
+ assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+ tokio::time::sleep(STREAM_POLL_INTERVAL).await;
+ }
+ })
+ .await
+ .expect("dropped project event response should release admission");
+ streams.push(replacement);
+ assert_eq!(streams.len(), MAX_EVENT_STREAMS_PER_SESSION);
+ }
+}
diff --git a/crates/spock-host/src/lib.rs b/crates/spock-host/src/lib.rs
new file mode 100644
index 0000000..c191d2c
--- /dev/null
+++ b/crates/spock-host/src/lib.rs
@@ -0,0 +1,49 @@
+//! Coordination and hosting for one Spock framework project.
+//!
+//! The pure generation state machine lives independently from filesystem and
+//! HTTP adapters so its activation laws can be exhaustively tested. Listener,
+//! observer, and subsystem adapters are layered on this crate.
+
+mod assets;
+mod backend_capture;
+mod client;
+mod events;
+mod generation;
+mod http;
+mod named_state;
+mod project;
+mod routing;
+mod server;
+
+pub use assets::{
+ load_uhura_assets, AssetError, UhuraAssetRoots, SPOCK_UHURA_WASM_DIST, SPOCK_UHURA_WEB_DIST,
+};
+pub use backend_capture::{
+ capture_backend, observe_backend, BackendDiagnostic, BackendDiagnosticCode, BackendDiagnostics,
+ BackendObservation,
+};
+pub use client::{
+ client_source_fingerprint, ActiveClientBinding, ClientHost, ClientHostError, ClientPublication,
+ PreparedClient,
+};
+pub use events::{
+ ProjectEvent, ProjectEventHub, ProjectEventStream, ProjectEventStreamPoll,
+ PROJECT_EVENT_PROTOCOL, PROJECT_STATUS_PATH,
+};
+pub use generation::{
+ BackendFreshness, BackendGenerationId, CandidateError, ClientAttempt, ClientAttemptState,
+ ClientFreshness, ClientGenerationId, EditorFreshness, Fingerprint, GenerationCoordinator,
+ HealthStatus, HostMode, Observation, ObservationDisposition, ObservedRevision,
+ ProjectGenerationId, ProjectStatus,
+};
+pub use http::{FrameworkSession, HOST_ENVIRONMENT_PROTOCOL};
+pub use named_state::{named_state_lock_path, NamedStateLock, NamedStateLockError};
+pub use project::{
+ check_project, topology_fingerprint, BackendCheckSummary, ClientCheckSummary, HostError,
+ ProjectCheckDiagnostic, ProjectCheckFailure, ProjectCheckReport, ProjectComponent,
+ ProjectDiagnosticPosition, ProjectDiagnosticSpan,
+};
+pub use routing::{classify_route, RouteOwner};
+pub use server::{
+ serve_project, HostNotice, HostNoticeSink, ServeError, ServeOptions, ServeOutcome,
+};
diff --git a/crates/spock-host/src/named_state.rs b/crates/spock-host/src/named_state.rs
new file mode 100644
index 0000000..ed9a85d
--- /dev/null
+++ b/crates/spock-host/src/named_state.rs
@@ -0,0 +1,711 @@
+//! Process ownership for an explicitly named database world.
+//!
+//! The lock file is only the stable object on which the operating system holds
+//! an advisory lock. Its contents and existence carry no ownership meaning:
+//! there is no PID record to inspect and no stale sentinel to delete.
+
+use std::ffi::{OsStr, OsString};
+use std::fs::{File, OpenOptions, TryLockError};
+use std::path::{Component, Path, PathBuf};
+
+use sha2::{Digest, Sha256};
+use thiserror::Error;
+#[cfg(any(windows, target_os = "macos"))]
+use unicode_normalization::UnicodeNormalization;
+
+const LOCK_DIRECTORY: &str = ".spock-named-state-locks";
+const LOCK_SUFFIX: &str = ".lock";
+
+/// Derive the advisory-lock path for one named `--db` value.
+///
+/// The database is first reduced to a normalized absolute filesystem identity.
+/// Its lock then lives in a reserved sibling directory under a SHA-256 name.
+/// Database, WAL, SHM, and historical `*.spock.lock` paths therefore cannot
+/// accidentally be the advisory object itself.
+#[must_use]
+pub fn named_state_lock_path(database_path: &Path) -> PathBuf {
+ let identity = resolved_database_entry(database_path).unwrap_or_else(|_| {
+ lexically_absolute(database_path).unwrap_or_else(|_| database_path.into())
+ });
+ lock_path_for_identity(&identity)
+}
+
+/// Failures before a host owns its named database world.
+#[derive(Debug, Error)]
+pub enum NamedStateLockError {
+ #[error("could not resolve named database identity {}: {source}", path.display())]
+ ResolveDatabase {
+ path: PathBuf,
+ #[source]
+ source: std::io::Error,
+ },
+ #[error(
+ "named database {} is inside reserved lock namespace `{LOCK_DIRECTORY}`",
+ path.display()
+ )]
+ ReservedDatabasePath { path: PathBuf },
+ #[error(
+ "named database {} has {links} hard links; use a database path with one directory entry",
+ path.display()
+ )]
+ HardLinkedDatabase { path: PathBuf, links: u64 },
+ #[error("could not create named-state lock directory {}: {source}", path.display())]
+ CreateParent {
+ path: PathBuf,
+ #[source]
+ source: std::io::Error,
+ },
+ #[error("could not open named-state lock {}: {source}", path.display())]
+ Open {
+ path: PathBuf,
+ #[source]
+ source: std::io::Error,
+ },
+ #[error(
+ "named database {} is already owned by another process (lock {})",
+ database_path.display(),
+ lock_path.display()
+ )]
+ Contended {
+ database_path: PathBuf,
+ lock_path: PathBuf,
+ },
+ #[error("could not acquire named-state lock {}: {source}", path.display())]
+ Acquire {
+ path: PathBuf,
+ #[source]
+ source: std::io::Error,
+ },
+}
+
+/// Exclusive process-lifetime ownership of one named database world.
+///
+/// Acquire this before creating, deleting, or opening the database, its WAL or
+/// SHM files, or any related mutable framework state. Keep the value in the
+/// host owner for at least as long as those resources are live.
+#[derive(Debug)]
+pub struct NamedStateLock {
+ database_path: PathBuf,
+ resolved_database_path: PathBuf,
+ lock_path: PathBuf,
+ file: File,
+}
+
+impl NamedStateLock {
+ /// Acquire an exclusive lock without waiting.
+ ///
+ /// This creates missing parent directories for the lock but deliberately
+ /// does not touch the database path. A competing owner produces
+ /// [`NamedStateLockError::Contended`] immediately.
+ pub fn acquire(database_path: impl AsRef) -> Result {
+ let database_path = database_path.as_ref().to_path_buf();
+ let resolved_database_path = resolved_database_entry(&database_path).map_err(|source| {
+ NamedStateLockError::ResolveDatabase {
+ path: database_path.clone(),
+ source,
+ }
+ })?;
+ if database_uses_lock_namespace(&resolved_database_path) {
+ return Err(NamedStateLockError::ReservedDatabasePath {
+ path: database_path,
+ });
+ }
+ let link_count =
+ existing_regular_file_link_count(&resolved_database_path).map_err(|source| {
+ NamedStateLockError::ResolveDatabase {
+ path: database_path.clone(),
+ source,
+ }
+ })?;
+ if let Some(links) = link_count.filter(|links| *links > 1) {
+ return Err(NamedStateLockError::HardLinkedDatabase {
+ path: database_path,
+ links,
+ });
+ }
+ let lock_path = lock_path_for_identity(&resolved_database_path);
+
+ if let Some(parent) = lock_path
+ .parent()
+ .filter(|parent| !parent.as_os_str().is_empty())
+ {
+ std::fs::create_dir_all(parent).map_err(|source| {
+ NamedStateLockError::CreateParent {
+ path: parent.to_path_buf(),
+ source,
+ }
+ })?;
+ }
+
+ let file = OpenOptions::new()
+ .read(true)
+ .write(true)
+ .create(true)
+ .truncate(false)
+ .open(&lock_path)
+ .map_err(|source| NamedStateLockError::Open {
+ path: lock_path.clone(),
+ source,
+ })?;
+
+ match file.try_lock() {
+ Ok(()) => Ok(Self {
+ database_path,
+ resolved_database_path,
+ lock_path,
+ file,
+ }),
+ Err(TryLockError::WouldBlock) => Err(NamedStateLockError::Contended {
+ database_path,
+ lock_path,
+ }),
+ Err(TryLockError::Error(source)) => Err(NamedStateLockError::Acquire {
+ path: lock_path,
+ source,
+ }),
+ }
+ }
+
+ #[must_use]
+ pub fn database_path(&self) -> &Path {
+ &self.database_path
+ }
+
+ /// The stable directory-entry path protected by this lock.
+ ///
+ /// Destructive database bootstrap must use this path rather than the
+ /// caller's spelling. Its parent has been resolved without following the
+ /// final database component, so a final-component symlink cannot change
+ /// the lock identity when bootstrap replaces it.
+ #[must_use]
+ pub fn resolved_database_path(&self) -> &Path {
+ &self.resolved_database_path
+ }
+
+ #[must_use]
+ pub fn lock_path(&self) -> &Path {
+ &self.lock_path
+ }
+}
+
+fn resolved_database_entry(database_path: &Path) -> std::io::Result {
+ let absolute = lexically_absolute(database_path)?;
+ let file_name = absolute.file_name().ok_or_else(|| {
+ std::io::Error::new(
+ std::io::ErrorKind::InvalidInput,
+ "database path must name a directory entry",
+ )
+ })?;
+ let parent = absolute.parent().ok_or_else(|| {
+ std::io::Error::new(
+ std::io::ErrorKind::InvalidInput,
+ "database path must have a parent directory",
+ )
+ })?;
+ resolve_directory(parent).map(|resolved_parent| resolved_parent.join(file_name))
+}
+
+fn resolve_directory(directory: &Path) -> std::io::Result {
+ let mut cursor = directory.to_path_buf();
+ let mut missing = Vec::::new();
+
+ loop {
+ match std::fs::symlink_metadata(&cursor) {
+ Ok(_) => {
+ let mut resolved = std::fs::canonicalize(&cursor)?;
+ for component in missing.iter().rev() {
+ resolved.push(component);
+ }
+ return Ok(resolved);
+ }
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+ let name = cursor.file_name().ok_or_else(|| {
+ std::io::Error::new(
+ std::io::ErrorKind::NotFound,
+ "database path has no existing ancestor",
+ )
+ })?;
+ missing.push(name.to_os_string());
+ cursor = cursor
+ .parent()
+ .ok_or_else(|| {
+ std::io::Error::new(
+ std::io::ErrorKind::NotFound,
+ "database path has no existing ancestor",
+ )
+ })?
+ .to_path_buf();
+ }
+ Err(error) => return Err(error),
+ }
+ }
+}
+
+fn existing_regular_file_link_count(path: &Path) -> std::io::Result