Contributor guide: run the Spock-backed Instagram demo

[softmarshmallow]

This is the living contributor guide for running the canonical full-stack Instagram example. Spock owns data, policy, identity seams, RPC, and media storage; Uhura owns the Editor and interactive Play experience. The combined framework host serves both through one spock process on one origin.

Important

Spock is pre-1.0. If this guide is stale or a command fails, please leave a comment with the command and output so the guide can be corrected.

What runs

The project is uhura/examples/instagram. One framework process serves, by default:

• Uhura Editor at http://127.0.0.1:4000/
• Uhura Play at http://127.0.0.1:4000/play
• Spock Studio at http://127.0.0.1:4000/~studio
• health and reload state at http://127.0.0.1:4000/~health and http://127.0.0.1:4000/~project/status
• GraphQL, REST/RPC, and storage on the same origin

There are two supported contributor paths below. Use the published CLI to verify the released product. Use the local source build to test the current checkout without waiting for an npm release; after the initial build, Cargo reuses its incremental cache.

Prerequisites and checkout

Both paths require Git, Node.js 24, and Corepack. The local source commands target macOS, Linux, or WSL and also require rustup; the checkout pins Rust 1.92 and the WebAssembly target.

For a fresh checkout:

git clone --recurse-submodules https://github.com/gridaco/spock.git
cd spock

For an existing checkout:

git pull --ff-only
git submodule update --init --recursive

The Instagram provider is application-owned generated output and is intentionally not committed. Build it after cloning and after changing its TypeScript source:

corepack pnpm@10.11.0 -C uhura/web install --frozen-lockfile
corepack pnpm@10.11.0 -C uhura/web build:provider

Path A: run the published CLI

Install the current framework release and run the normal spock command:

npm install --global spock@0.5.0
spock --version
spock check uhura/examples/instagram
spock start uhura/examples/instagram

Use spock dev uhura/examples/instagram instead when testing watched client development with the released CLI.

To avoid a global installation, the equivalent pinned smoke command is:

npx --yes spock@0.5.0 start uhura/examples/instagram

This path uses the Editor/Play and WebAssembly sidecar shipped in the npm package. It does not require Rust, a local Spock build, or a manual Uhura WebAssembly build.

Path B: run the current checkout

Use this path when changing Spock or Uhura itself. Build the source-owned Studio, Editor/Play, provider, and WebAssembly assets once:

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 check
bash uhura/scripts/build-wasm.sh

If build-wasm.sh reports a missing or mismatched wasm-bindgen-cli, run the lockfile-exact install command it prints and then run the script again.

Check and start the project with the CLI compiled from this checkout:

cargo run --locked -p spock-cli -- check uhura/examples/instagram

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 -- start uhura/examples/instagram

For the incremental client-development loop, replace start with dev:

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 uhura/examples/instagram

The two SPOCK_UHURA_* overrides are a required pair for a source host. They prevent a local binary from silently mixing incompatible Editor/Play and WebAssembly generations.

Reload and data behavior

• spock start checks once and serves one fixed generation. It has no watcher.
• spock dev publishes valid Uhura client saves live.
• An invalid client save keeps the last good Play generation while Editor shows diagnostics.
• An initially invalid client is reported as cold_invalid until it becomes valid.
• A .spock source, seed input, or topology-affecting spock.toml save is detected and reported as restart_required. It never migrates, reseeds, reopens, or replaces the active database in place.
• Stopping and starting the command reconstructs backend state from seed. Restarting the Play shell only resets its UI session; it does not roll back Spock data.

This asymmetric policy is deliberate while the development-state model remains unresolved. Inspect /~project/status for the current generation and reload state.

Provider TypeScript is not compiled by spock dev. After changing client/providers/spock.ts, rerun build:provider, or keep this watcher in another terminal:

corepack pnpm@10.11.0 -C uhura/web dev:provider

Things to try in Play

• switch between Mobile and Desktop frames
• switch the active seeded actor
• open profiles, Followers, and Following
• view posts, multi-frame Stories, Search/Explore, and playable Reels
• like, save, follow, and comment
• choose an image in Create and publish a new post through Spock storage

Everything shown in Play, including counts and media, comes from the running Spock authority. Actor switching is a prototype impersonation seam, not production authentication.

Troubleshooting

• Missing project or Uhura files: run git submodule update --init --recursive.
• Missing client/providers/dist/spock.js: rerun corepack pnpm@10.11.0 -C uhura/web build:provider.
• Published command behaves differently: run spock --version; use the pinned npx --yes spock@0.5.0 ... form to distinguish an installation/PATH problem.
• Source host reports missing assets: complete every source-build command above and set both SPOCK_UHURA_* overrides.
• A backend edit does not reload: this is expected; stop and rerun the command, which reconstructs the database from seed.
• Port 4000 is busy: add --port 4001 to spock start or spock dev, then use that single port for Editor, Play, Studio, and APIs. Same-origin discovery handles the selected port; do not rewrite the fallback in client/uhura.toml.
• application-owned provider adapter code remains unchecked: this is the current expected warning, not a failed check.
• Health is ready but degraded: inspect /~project/status; an invalid client or a backend change awaiting restart intentionally produces this state.
• Alpine/musl: the npm package currently targets GNU-libc Linux; use a supported platform or the Cargo workflow.
• Press Ctrl-C once to stop the combined framework process.

The repository README remains the canonical command and reload reference; this issue stays open as the contributor-oriented walkthrough.