feat: expose Uhura as a reusable framework host

[softmarshmallow]

Summary

• extract a reusable, listener-free uhura-host library from the standalone CLI
• expose coherent Editor/Play snapshots, bounded event streams, candidate diagnostics, asset discovery, and clean host lifecycle ownership
• keep uhura-cli as the independent contributor/subsystem entrypoint over the same host boundary
• let the Instagram provider consume the Spock framework's typed same-origin environment while retaining its standalone fallback

Boundary preserved

This is operational composition, not a language merger. Uhura owns client experience behavior and non-authoritative UI-session state; Spock remains the authority for durable facts, policy, and mutations. The reusable host does not bind a mandatory listener or absorb Spock semantics.

Companion framework integration: gridaco/spock#15. It consumes this branch through the existing submodule boundary.

Review hardening

• bound ordinary request work and isolate long-lived SSE on a separate bounded lane
• enforce one host-wide Editor + Play event-stream cap with explicit 503 / Retry-After overload behavior
• release stream admission promptly after disconnect through a transport-flushing keepalive
• parse only real HTML start-tag asset attributes and decode web/Wasm paths exactly once
• centralize HEAD finalization while preserving GET metadata and exact Content-Length for byte responses
• retain stable file identity across supported platforms

Verification

• cargo fmt --all -- --check
• cargo clippy --locked --workspace --all-targets -- -D warnings
• cargo test --locked --workspace --all-targets
• pnpm -C web check (typecheck, lint, production builds, browser/provider tests)
• canonical Instagram Uhura fmt --check, check --deny-warnings, and trace
• packaged native-host smoke without Node
• live transport probes for large GET/HEAD metadata, chunked SSE, exact stream saturation, and admission reuse

CodeRabbit's four actionable threads are addressed and resolved; its incremental review reported no new actionable comments.

[coderabbitai]

Walkthrough

The PR introduces uhura-host as a shared runtime for Editor and Play state, routing, SSE, and immutable assets; adapts the CLI to use it; and adds integrated authority discovery, fallback, timeout, and cancellation handling to the Spock provider.

Changes

Unified host runtime

Layer / File(s)	Summary
Public source capture and fingerprinting crates/uhura-host/src/source.rs, Cargo.toml, crates/uhura-host/Cargo.toml	Project snapshots and fingerprints gain public capture, stable identity, subtree APIs, and same-file workspace wiring.
Candidate construction and coherent publication crates/uhura-host/src/lib.rs	The host builds Editor and Play candidates, enforces revision ordering, publishes combined state, and generates boot and fixture artifacts.
SSE, immutable assets, and HTTP routing crates/uhura-host/src/lib.rs	The host adds event streams, validated web snapshots, Editor/Play routes, static asset serving, and related tests.
CLI integration with Host crates/uhura-cli/Cargo.toml, crates/uhura-cli/src/cmd/{dev.rs,mod.rs,trace.rs}	The CLI delegates development serving and trace helpers to uhura-host, including bounded request admission and stable observation.

Integrated authority discovery

Layer / File(s)	Summary
Authority discovery and endpoint resolution examples/instagram-uhura/providers/spock.ts	Spock discovers framework authority endpoints, validates metadata, caches resolution, applies configured fallback, and resolves endpoint-relative URLs.
Discovery and lifecycle tests examples/instagram-uhura/providers/spock.test.ts	Tests cover valid, invalid, delayed, capability-missing, and aborted framework environment discovery.
Split-checkout usage documentation examples/instagram-uhura/README.md	The example documents integrated environment discovery, precedence, timeout, capability absence, fallback, and standalone commands.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• gridaco/uhura#5: Reworks the CLI dev-server dependency around editor state generation.
• gridaco/uhura#8: Adds a related Play inspection route in the CLI HTTP routing layer.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.42% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: extracting Uhura into a reusable framework host.
Description check	✅ Passed	The description is directly related to the refactor and integration changes in this PR.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/spock-framework

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/uhura-cli/src/cmd/dev.rs`:
- Around line 99-103: Replace the unbounded std::thread::spawn loop in the
incoming_requests handling with a bounded executor that limits concurrent
request work. Add an explicit cap for long-lived SSE sessions so persistent
responses cannot consume all worker capacity, while preserving the existing
respond(request, &host) behavior for accepted requests.

In `@crates/uhura-host/src/lib.rs`:
- Around line 868-953: The index_asset_references scanner must parse actual HTML
start-tag attributes rather than matching src= or href= in arbitrary text such
as comments or inline JavaScript. Track HTML tag boundaries and only extract
these attribute names within start tags, while preserving existing asset
validation; add regression tests covering inline content and comments containing
src/href assignments.
- Around line 1149-1156: Decode each incoming web or Wasm URL path exactly once
and validate its decoded path segments before lookup. Apply this to the
application and Wasm route handling around serve_file_map and the corresponding
handlers near the other affected locations, while preserving the existing
PlayAsset behavior and error mapping.
- Around line 1115-1139: Update the request handling around api_route,
event_method_error, and all byte-producing responses so every HEAD response has
its body removed, including 404, 503, and the early 405 SSE response. Centralize
this finalization step for all responses while preserving the status, headers,
and other metadata that the corresponding GET response would return.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a296305e-4473-4b79-826c-bb3ff8fa3d28

📥 Commits

Reviewing files that changed from the base of the PR and between c1d2a9e and 8f20987.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (11)

• Cargo.toml
• crates/uhura-cli/Cargo.toml
• crates/uhura-cli/src/cmd/dev.rs
• crates/uhura-cli/src/cmd/mod.rs
• crates/uhura-cli/src/cmd/trace.rs
• crates/uhura-host/Cargo.toml
• crates/uhura-host/src/lib.rs
• crates/uhura-host/src/source.rs
• examples/instagram-uhura/README.md
• examples/instagram-uhura/providers/spock.test.ts
• examples/instagram-uhura/providers/spock.ts

💤 Files with no reviewable changes (1)

• crates/uhura-cli/src/cmd/mod.rs