138 lines
12 KiB
Markdown
138 lines
12 KiB
Markdown
# WRNexusJS quality, migration, and usability roadmap
|
|
|
|
This page is the authoritative implementation tracker for the repository-wide 0.8 audit. A
|
|
point is complete only when its acceptance criteria are executable in CI. Security and release
|
|
correctness take priority over new surface area.
|
|
|
|
## Release blockers
|
|
|
|
| Status | Area | Work | Acceptance criteria |
|
|
| -------- | ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
| Complete | Dependencies | Remove high-severity `brace-expansion` and `fast-uri` advisories | Root `bun audit` and editor `npm audit` report no high/critical findings |
|
|
| Complete | Component showcase | Use the current `payload` output contract in generated examples and tests | Showcase generation and tests pass without a diff |
|
|
| Complete | Formatting | Normalize the package-kit audit and migration changes | `bun run format:check` passes |
|
|
| Complete | Examples | Resolve every runtime warning, including unregistered `theme-toggle` | Example tests fail on unexpected framework warnings |
|
|
| Complete | Application updates | Modernize all `.wrn` files during the 0.8 CLI update | Migration is backed up, idempotent, reports unresolved work, and has focused tests |
|
|
|
|
## Repository delivery and configuration
|
|
|
|
| Status | Work | Acceptance criteria |
|
|
| -------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
|
|
| Complete | Add Linux and Windows CI for install, typecheck, lint, format, packages, examples, services, editor, audits, and staging | Required checks run on every pull request |
|
|
| Complete | Split generators from validators | Every `check:*` and `validate:*` command is read-only; `generate:*` owns writes |
|
|
| Complete | Add root `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, and code of conduct | Release validation requires each document |
|
|
| Complete | Normalize all staged package manifests from one schema | Description, license, repository, exports, files, engines, side effects, and scripts are validated |
|
|
| Complete | Replace `latest` dependency ranges with controlled versions | Frozen-lockfile installs are reproducible |
|
|
| Complete | Test staged tarballs outside workspace aliases | Bun consumer, CLI binary, browser imports, assets, and declarations work from packed artifacts |
|
|
| Complete | Correct publishing documentation and package counts | Generated documentation matches the package inventory |
|
|
|
|
## Framework and package work
|
|
|
|
Delivered compiler/editor foundation:
|
|
|
|
- `@wrnexus/syntax` owns the typed canonical formatter API and publishable formatter subpath.
|
|
- The compiler, CLI updater, and VS Code extension consume the same implementation.
|
|
- The tracked editor compiler bundle has a read-only freshness gate.
|
|
- Formatter tests cover structured declarations, markup, comments, parsing, and idempotence.
|
|
- Compiler diagnostics are structured for CLI/editor/toolbar consumers, the dev
|
|
pipeline exposes incremental hit/miss/error/timing metrics, and
|
|
`wrnexus doctor --fix` applies conservative idempotent project repairs.
|
|
|
|
Delivered observability/operations foundation:
|
|
|
|
- Strict W3C `traceparent` propagation and correlated request/span identifiers.
|
|
- One request tracer shared with downstream framework spans and safe exporter failure isolation.
|
|
- OTLP/HTTP JSON trace and metric exporters with service resource attributes.
|
|
- Redacting structured JSON logs with correlated child loggers.
|
|
- Separate liveness and dependency readiness handlers backed by `HealthRegistry`.
|
|
- Production runtime `/healthz` and `/readyz` integration with configuration validation.
|
|
|
|
Delivered public API foundation:
|
|
|
|
- Every package root and declared subpath is resolved through the TypeScript
|
|
checker into a reviewed `0.8` export baseline.
|
|
- CI and production validation reject accidental export removals/renames.
|
|
- Intentional API evolution uses a separate generator command and the policy in
|
|
`docs/PUBLIC-API-POLICY.md`.
|
|
- Browser payload budgets cover reactive, navigation, and realtime runtimes.
|
|
- SSR/store hydration compatibility tests enforce bounded safe JSON, secret
|
|
redaction, script-breakout protection, and escaped CSP nonce attributes.
|
|
|
|
| Packages | Planned outcomes |
|
|
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `core`, `reactive`, `router`, `ssr`, `csr`, `store`, `realtime` | Stable public API policy; conditional exports; hydration/serialization compatibility; cancellation and disconnect tests; typed routes; one realtime contract; runtime-size budgets |
|
|
| `syntax`, `compiler`, `typecheck`, `dev-server`, `dev-toolbar`, editor | Shared formatter/compiler artifact; incremental cache metrics; structured diagnostics; fuzz and snapshot tests; code actions; rename/references; `doctor --fix` |
|
|
| `auth`, `authz`, `captcha`, `jwt`, `oauth`, `encryption`, `security` | WebAuthn/OIDC conformance; JWKS rotation; replay/rate-limit tests; built-app header checks; threat models; stable audit events and support matrix |
|
|
| `db`, `cache`, `queue`, `pubsub`, `observability`, `tracking` | Live database/Redis matrices; cancellation and pool lifecycle; migration locks/dry-run/rollback; distributed invalidation; DLQ/idempotency; OpenTelemetry; health primitives |
|
|
| `validation`, `i18n`, `image`, `uploader`, `ui`, `styles`, `helpers` | JSON Schema/OpenAPI; localized validation; locale extraction/pseudo-locales/RTL; image build optimization; resumable uploads; accessibility and visual regression; typed theme tokens; strict helper ownership |
|
|
| `ai` | Provider capabilities; structured output; tools; cancellation/retries; usage cost; redaction; deterministic test provider; circuit breakers |
|
|
| `mobile`, `native` | Generated Expo/Capacitor E2E builds; typed permissions; deep links; push; offline and secure storage; platform fallbacks |
|
|
| `cli`, `plugin`, `test`, `benchmark` | JSON/non-interactive commands; stable error codes; clean scaffold-to-production test; plugin compatibility; consumer test kit; tarball and benchmark budgets |
|
|
|
|
Queue/pub-sub reliability delivered in 0.8: bounded queue capacity,
|
|
idempotency keys, priorities, delayed/repeated jobs, exponential retries,
|
|
inspectable/retryable dead letters, AbortSignal cancellation, graceful/forced
|
|
shutdown, durable-store leases, bounded Redis offline writes, reconnect backoff,
|
|
subscription replay, awaited in-memory delivery, and idempotent pub/sub close.
|
|
|
|
Database deployment safety delivered in 0.8: idempotent close that drains active
|
|
queries/transactions, registry-wide all-settled pool shutdown, portable
|
|
cross-process migration locks with stale-lock recovery, dry-run planning,
|
|
between-migration cancellation, and lock-protected rollback.
|
|
|
|
Cache coherence delivered in 0.8: bounded tag-aware memory caching,
|
|
stampede-safe request deduplication, invalidation-safe in-flight loaders, and a
|
|
namespaced pub/sub bridge for cross-instance tag, key, and full-cache
|
|
invalidation with explicit failure and unsubscribe lifecycle.
|
|
|
|
AI reliability delivered in 0.8: explicit provider capability discovery,
|
|
validated structured output and tool execution, normalized token/cost usage,
|
|
abort-aware bounded retries, provider fallback and circuit breakers, metadata-only
|
|
attempt telemetry, and a deterministic offline provider for tests and examples.
|
|
|
|
Mobile portability delivered in 0.8: tested Capacitor and Expo generators, portable
|
|
WRN-to-Expo compilation, typed capability permissions, normalized deep-link and push
|
|
contracts, pluggable secure-storage and offline stores, and explicit SSR/browser/native
|
|
fallback behavior.
|
|
|
|
Security protocol hardening delivered in 0.8: bounded HTTPS RS256 JWKS caching
|
|
with immediate `kid` rotation refresh, strict OIDC discovery and ID-token claim
|
|
validation, stable authentication audit-event vocabulary, built production
|
|
response header assertions, and a framework/application responsibility matrix
|
|
in `docs/SECURITY-SUPPORT-MATRIX.md`.
|
|
|
|
Validation/localization interoperability delivered in 0.8: JSON Schema 2020-12
|
|
and OpenAPI request-body generation, shared localized validation descriptors,
|
|
static translation-key extraction, reference-locale missing/extra audits, and
|
|
placeholder-safe LTR/RTL pseudo-locales.
|
|
|
|
Asset and upload delivery delivered in 0.8: bounded deterministic AVIF/WebP/etc.
|
|
image build variants through optional Sharp or a custom processor, plus
|
|
checksum-verified resumable uploads with out-of-order/idempotent chunks,
|
|
expiry/cancel/prune, pluggable durable session state, and single final assembly.
|
|
|
|
## CLI update contract
|
|
|
|
The `0.8.0-02-current-wrn-source` migration applies one consistent upgrade point to every WRN
|
|
page, layout, component, and store beneath `app/`:
|
|
|
|
1. Create a complete pre-update backup under `.wrnexus/update-backups/`.
|
|
2. Convert legacy events, `$emit`, `event.detail`, function runtimes, dynamic attributes, and
|
|
inline prop declarations to the current syntax.
|
|
3. Convert string layouts to imported layout symbols.
|
|
4. Add deterministic imports for uniquely resolved application and UI components.
|
|
5. Normalize line endings, trailing whitespace, final newlines, and safe structural formatting.
|
|
6. Preserve ambiguous source and list it in
|
|
`.wrnexus/migrations/0.8.0-source-modernization.json` for manual review.
|
|
7. Run the application formatter, health checks, tests, and production build before committing
|
|
the new framework version marker.
|
|
|
|
The migration must remain idempotent: running it twice produces byte-identical application
|
|
source on the second run.
|
|
|
|
## Definition of done
|
|
|
|
A roadmap item may move to **Complete** only with tests, documentation, no high/critical audit
|
|
findings, no unexpected warnings, clean formatting, a clean generated-file check, and a staged
|
|
package consumer test where publishing behavior changes.
|