diff --git a/README.md b/README.md index e7e3194..64f8765 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,8 @@ handwritten UI JavaScript, selector targeting, or raw runtime primitives. req: p 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. +diagnostics, and stability guidance. See `docs/v1-readiness.md` for the current +close-gap audit. ## The normal path diff --git a/docs/v1-readiness.md b/docs/v1-readiness.md new file mode 100644 index 0000000..cb716ca --- /dev/null +++ b/docs/v1-readiness.md @@ -0,0 +1,187 @@ +# v1 readiness audit + +This audit tracks the current hemx v1 northstar against the active Close when. +It is a checkpoint, not the release announcement: update it before any GOAL_DONE +or v1 tag. req: examples/001 req: public_api/001 + +## Close-when status + +### Canonical tutorial app + +Status: partially satisfied; not enough for GOAL_DONE. + +Evidence: + +- `examples/saas` is a compile-tested tutorial skeleton 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. +- `docs/tutorial-saas.md` walks through the app from template to production + provider handoff. +- `docs/recipes/sqlx-persistence.md` shows how to replace `LocalProjectStore` + with an app-owned SQLx adapter without moving SQLx into core. + +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. + +### Beginner API stability + +Status: mostly satisfied; final release audit still required. + +Evidence: + +- Normal path is documented around `app`, `component`, `handler`, `form`, + `page`, generated helpers, tuple `IntoEffect`, and `Result` + mapping. +- `docs/versioning.md` defines stable beginner API vs wire/runtime ABI vs + advanced escape hatches. +- `examples/v0` and `examples/saas` exercise the normal path without manual + registries or raw ids in app authoring. + +Remaining before GOAL_DONE: + +- Run a final API surface audit before v1 and either accept current names or make + the last naming changes before declaring stability. + +### Advanced APIs isolated + +Status: satisfied for docs/examples; final scan required. + +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. + +Remaining before GOAL_DONE: + +- Re-run the forbidden-normal-path scan over README, docs, and public examples; + review any hits in explicit island/runtime/deploy sections as intentional. + +### Docs explain the model in one sitting + +Status: mostly satisfied. + +Evidence: + +- `README.md` explains render → slot/key → effect → runtime, forms/errors, + pages/push, CSS/islands, production boundaries, escape hatches, and + deploy/version compatibility. +- `docs/tutorial-saas.md` provides the product walkthrough. +- Recipes cover SQLx, auth/session + CSRF, observability/flags/killswitches, and + deploy/versioning. +- `docs/diagnostics.md` and `docs/versioning.md` cover failure and release + policy. + +Remaining before GOAL_DONE: + +- Add a small docs index or check the root README is enough as the single entry + point for all tutorial/recipe/versioning pages. + +### Diagnostics + +Status: documented and substantially tested; coverage audit still required. + +Evidence: + +- `docs/diagnostics.md` names common mistakes and desired fixes in author + language. +- Existing gates cover build diagnostics, derive compile-fail diagnostics, + runtime root/fingerprint behavior, and example contract checks. + +Remaining before GOAL_DONE: + +- Run the full diagnostics gate and confirm each required mistake class has + either an actual test or an explicitly accepted compiler diagnostic: missing + handler/form/slot/key/param, invalid form field type, unknown hemx attribute, + unsafe HTML boundary, wrong component/slot target, missing root/fingerprint, + and bad result error type. + +### Production recipes + +Status: mostly satisfied; optional PWA/offline remains unresolved. + +Evidence: + +- SQLx: `docs/recipes/sqlx-persistence.md` +- auth/session + CSRF: `docs/recipes/auth-session-csrf.md` +- observability/metrics + feature flags/killswitches: + `docs/recipes/observability-flags.md` +- deploy/versioning: `docs/recipes/deploy-versioning.md` + +Remaining before GOAL_DONE: + +- Add a bounded optional PWA/offline recipe, or explicitly scope it out of v1 if + optional adapters are not required for the release. +- Confirm whether SQLx/auth/observability/deploy recipes are sufficient as + recipe-only production guidance or whether one provider path must be exercised + by the tutorial crate before v1. + +### Public examples + +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/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 + in canonical examples. + +Remaining before GOAL_DONE: + +- Re-run example contract tests and forbidden-pattern scans on a clean tree. + +### Runtime remains tiny and selectorless + +Status: satisfied in core; final runtime gate required. + +Evidence: + +- `README.md`, `docs/versioning.md`, `docs/recipes/deploy-versioning.md`, and + `docs/recipes/observability-flags.md` keep runtime scope to checked effect + application and reject VDOM/hydration/client-store/selector-retargeting growth. +- `examples/saas/templates/metrics.js` uses selectors only inside an explicit + leaf island, not for normal hemx targeting. + +Remaining before GOAL_DONE: + +- Run `cargo test -p hemx-js` and audit runtime diff before closure. + +### Versioning explicit + +Status: satisfied pending final release check. + +Evidence: + +- `docs/versioning.md` defines semver tiers, wire/runtime ABI policy, advanced + escape-hatch policy, upgrade-note template, and release checklist. +- `docs/recipes/deploy-versioning.md` documents release units, asset caching, + rolling deploy behavior, fingerprint mismatch behavior, and rollback checks. + +Remaining before GOAL_DONE: + +- Run final verification and confirm upgrade/versioning docs still match the + current generated ABI/runtime behavior. + +## 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, either add the optional PWA/offline recipe or explicitly scope it out +of v1, then run the closure audit with the full gates from the active goal, +including `cargo run -p hemx-xtask -- test` and the full diagnostics scan.