feat: add application productivity foundations

2026-08-23 11:13:03 +05:30
parent 46195462c3
commit 64ab20cc95
42 changed files with 1533 additions and 40 deletions
@@ -0,0 +1,43 @@
+# Application productivity kit
+
+WrNexus applications should declare infrastructure once and keep only domain decisions locally.
+
+## Included foundations
+
+1. HTTP routes: `defineApiRoute`, `authorized`, `requireUser`, `requirePermission`, `requireParam`, `requireJson`, and `json`.
+2. CRUD resources: `defineResource` generates owned list/create/get/update/delete handlers.
+3. Seed data: `addSeedData`, `upsertSeedData`, `seedIfMissing`, `defineSeed`, `removeSeedData`, and `runSeedQuery`.
+4. Transactional delivery: `withOutbox`, `drainOutbox`, and `installOutboxSchema`.
+5. Job state transitions: `defineJobStateMachine`.
+6. SQLite/PostgreSQL/MySQL queue tables: configured storage plus `databaseQueueStore`.
+7. Queue operations: success/failed hooks, dashboard handler and queue CLI.
+8. Queue testing: `testQueue` with deterministic `runNext`/`runAll`.
+9. Workflows and compensation: durable workflows and `defineSaga`.
+10. Mail: `defineMail`, `defineMailTemplate`, sandbox allowlists and `queuedMail`.
+11. Encrypted settings: `defineSecretResource`.
+12. Ledgers: `defineLedger` with atomic debit and audit entries.
+13. Forms: `useForm` for values, errors, dirty/submitting state, validation and submission.
+14. Typed HTTP calls: `createApiClient`; generated OpenAPI/SDK clients remain available through `wrnexus api generate`.
+15. Full-stack testing: `createTestApp`, database rollback/factories, and queue test controls.
+16. Package migrations: queue/auth/authz packages contribute migrations through the plugin lifecycle.
+17. Auth/OAuth: auth and authz plugins own routes, middleware, roles and provider lifecycle.
+18. Code generation: `wrnexus generate resource <name>`.
+19. Incremental features: `wrnexus add queue|mail|seed|testing|resource`.
+20. Starter presets: `wrnexus create app --preset=saas|email` and `--features=...`.
+
+## Recommended new-project flow
+
+```sh
+wrnexus create acme --preset=saas
+cd acme && bun install
+wrnexus generate resource projects
+wrnexus add mail
+wrnexus db migrate
+wrnexus db seed
+wrnexus dev
+```
+
+Use generated resources for ordinary owned CRUD. Use the outbox for business operations that
+change data and enqueue work together. Use sagas only when a workflow crosses systems that cannot
+share a transaction. Application code should retain product-specific policy; framework code owns
+storage, validation, lifecycle, retries, diagnostics and scaffolding.