diff --git a/README.md b/README.md index 6a9703a..f4e7e7c 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,9 @@ commands; ordinary server-first apps do not need a frontend framework, handwritten UI JavaScript, selector targeting, or raw runtime primitives. req: pitch/001 req: canonical_authoring/001 Status: the repository currently has a strong v0 example/API path, a compile-tested -SaaS tutorial skeleton, an advanced Kanban milestone sketch, and a full techdemo. -The polished v1 product story is still being filled out through docs, recipes, -diagnostics, and stability guidance. See `docs/v1-readiness.md` for the current -close-gap audit. +SaaS tutorial app, an advanced Kanban milestone sketch, and a full techdemo. +The v1 story now has tutorial, recipe, diagnostics, and stability docs; see +`docs/v1-readiness.md` for the remaining close-gap audit. ## The normal path @@ -120,7 +119,7 @@ See `docs/versioning.md`. - `examples/v0`: canonical beginner path covering counter, typed todo CRUD, form wizard, auth action, page swaps, SSE notifications, and keyed list updates. Start here. -- `examples/saas`: compile-tested v1 tutorial skeleton covering auth/session, +- `examples/saas`: compile-tested v1 tutorial app covering auth/session, CSRF-safe mutation, local persistence, generated swaps, page/push shape, plain CSS, and one explicit island without provider-heavy platform scope. Read the walkthrough in `docs/tutorial-saas.md`; the SQLx persistence recipe in diff --git a/docs/v1-readiness.md b/docs/v1-readiness.md index 7d413e0..3dd4762 100644 --- a/docs/v1-readiness.md +++ b/docs/v1-readiness.md @@ -8,11 +8,11 @@ or v1 tag. req: examples/001 req: public_api/001 ### Canonical tutorial app -Status: partially satisfied; not enough for GOAL_DONE. +Status: satisfied pending final closure verification. Evidence: -- `examples/saas` is a compile-tested tutorial skeleton with typed domain values, +- `examples/saas` is a compile-tested tutorial app with typed domain values, `#[hemx::form("new_project")]`, auth/session-shaped `AppContext`, CSRF-safe mutation, local persistence adapter, generated keyed row/form/summary/page/live effects, SSE/polling shape, plain CSS, one explicit metrics island, and tests. @@ -21,14 +21,16 @@ Evidence: - `docs/recipes/sqlx-persistence.md` shows how to replace `LocalProjectStore` with an app-owned SQLx adapter without moving SQLx into core. +Release decision: + +- The supported v1 production boundary is the compile-tested local persistence + adapter plus provider-explicit recipes. SQLx/auth/observability/deploy/PWA stay + app integrations rather than required workspace dependencies, so the tutorial + remains runnable in CI without credentials or external services. + Remaining before GOAL_DONE: -- Turn `examples/saas` from a skeleton into the canonical v1 close artifact: either - add one checked production adapter path/profile, or make an explicit release - decision that local persistence plus provider recipes is the supported v1 - production boundary. -- If the release must prove a real DB provider in CI, add a feature-gated or - companion SQLx-backed test instead of only a recipe. +- Run the final closure audit and full gates on a clean tree. ### Beginner API stability @@ -58,8 +60,8 @@ Evidence: - `README.md`, `docs/versioning.md`, and `docs/diagnostics.md` identify raw effects, ids, render/target construction, manual registries, runtime hooks, SSE internals, and island internals as advanced. -- Public examples label `v0` as beginner, `examples/saas` as the tutorial - skeleton, `kanban` as advanced/north-star, and `techdemo` as advanced. +- Public examples label `v0` as beginner, `examples/saas` as the tutorial app, + `kanban` as advanced/north-star, and `techdemo` as advanced. Remaining before GOAL_DONE: @@ -120,9 +122,8 @@ Evidence: Remaining before GOAL_DONE: -- Confirm whether SQLx/auth/observability/deploy/PWA recipes are sufficient as - recipe-only production guidance or whether one provider path must be exercised - by the tutorial crate before v1. +- Run the final recipe scan and confirm links from the tutorial and README remain + complete. ### Public examples @@ -131,7 +132,7 @@ Status: satisfied pending final scan. Evidence: - `examples/v0/README.md` is the beginner entry. -- `examples/saas/README.md` identifies the production-shaped tutorial skeleton. +- `examples/saas/README.md` identifies the production-shaped tutorial app. - `examples/kanban/README.md` identifies Kanban as advanced/north-star. - `examples/techdemo/README.md` identifies Techdemo as advanced. - Contract tests guard against browser JavaScript and low-level resource plumbing @@ -175,11 +176,6 @@ Remaining before GOAL_DONE: ## Recommended next waypoint -Make the production-shaped SaaS path closure decision concrete. The smallest -implementation path is a bounded, checked provider slice for `examples/saas` -(such as a feature-gated SQLx adapter test) if v1 must prove a real provider in -CI; the smallest docs path is an explicit release decision that the local adapter -plus provider recipes is the v1 production boundary. - -After that, run the closure audit with the full gates from the active goal, -including `cargo run -p hemx-xtask -- test` and the full diagnostics scan. +Run the closure audit with the full gates from the active goal, including +`cargo run -p hemx-xtask -- test`, the full diagnostics scan, forbidden +normal-path scans, and a final critic review before any GOAL_DONE claim. diff --git a/examples/saas/README.md b/examples/saas/README.md index 698b04f..c148461 100644 --- a/examples/saas/README.md +++ b/examples/saas/README.md @@ -1,8 +1,8 @@ -# hemx SaaS tutorial skeleton +# hemx SaaS tutorial app -This is the compile-tested skeleton for the v1 production-shaped tutorial app. It is intentionally provider-light: auth/session, CSRF, persistence, deploy, metrics, and islands are explicit app boundaries, not hemx core services. Read the walkthrough in `../../docs/tutorial-saas.md`. req: examples/001 req: auth/001 +This is the compile-tested v1 production-shaped tutorial app. It intentionally uses an equivalent local persistence adapter and provider recipes as the supported v1 production boundary: auth/session, CSRF, SQLx persistence, deploy, metrics, flags, offline behavior, and islands are explicit app integrations, not hemx core services. Read the walkthrough in `../../docs/tutorial-saas.md`. req: examples/001 req: auth/001 -What it proves today: +What it proves: - typed form/newtype inputs for project creation - auth/session context passed through normal Rust state @@ -14,12 +14,13 @@ What it proves today: For provider-explicit boundaries, see `../../docs/recipes/sqlx-persistence.md`, `../../docs/recipes/auth-session-csrf.md`, `../../docs/recipes/observability-flags.md`, `../../docs/recipes/deploy-versioning.md`, and `../../docs/recipes/pwa-offline.md`. -What it deliberately does not claim yet: +What it deliberately keeps out of the tutorial crate: -- a checked-in SQLx migration crate or database pool -- production cookie/session middleware -- a deploy target, flags, analytics, billing, or offline sync -- browser automation for the metrics island +- a vendored SQL/auth/metrics/flags/deploy provider dependency +- provider credentials, external services, migrations, or browser automation +- billing, account administration, or other SaaS platform scope + +Those production concerns belong in app adapters and recipes so the tutorial remains runnable in CI without external side effects. Run: diff --git a/examples/saas/src/lib.rs b/examples/saas/src/lib.rs index 76fb134..0a87638 100644 --- a/examples/saas/src/lib.rs +++ b/examples/saas/src/lib.rs @@ -320,7 +320,7 @@ mod tests { } #[test] - fn home_page_documents_the_production_skeleton_boundaries() { + fn home_page_documents_the_production_app_boundaries() { // req: examples/001 req: auth/001 req: auth/004 req: interop/003 let ctx = AppContext::demo(); let html = home_page(&ctx);