anhedral 0.11.1 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +126 -69
- package/dist/bin.js +48 -493
- package/dist/capabilities.d.ts +3 -3
- package/dist/capability-contract.js +4 -0
- package/dist/cli-arguments.d.ts +8 -0
- package/dist/cli-arguments.js +32 -0
- package/dist/cli-commands.d.ts +3 -0
- package/dist/cli-commands.js +114 -0
- package/dist/cli-delivery.d.ts +3 -0
- package/dist/cli-delivery.js +172 -0
- package/dist/cli-output.js +231 -205
- package/dist/delivery-evidence.d.ts +62 -0
- package/dist/delivery-evidence.js +186 -0
- package/dist/delivery.d.ts +3 -40
- package/dist/delivery.js +4 -181
- package/dist/dependencies.d.ts +1 -0
- package/dist/dependencies.js +2 -0
- package/dist/mobile-delivery.d.ts +21 -44
- package/dist/mobile-delivery.js +127 -80
- package/dist/provider-auth.js +3 -3
- package/dist/scaffold/documentation.js +1 -0
- package/dist/scaffold/stream.d.ts +2 -0
- package/dist/scaffold/stream.js +114 -0
- package/dist/service-readers.js +1 -1
- package/dist/services-command.js +8 -6
- package/dist/ship.d.ts +15 -15
- package/dist/stack-registry.d.ts +4 -2
- package/dist/stack-registry.js +16 -0
- package/dist/transaction-lock.d.ts +15 -0
- package/dist/transaction-lock.js +227 -0
- package/dist/transaction.js +2 -208
- package/dist/vercel-project.d.ts +101 -0
- package/dist/vercel-project.js +305 -0
- package/dist/vercel.d.ts +3 -36
- package/dist/vercel.js +3 -300
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/software-factory.md +528 -0
- package/docs/stack-standard.md +196 -121
- package/docs/verification.md +444 -0
- package/package.json +3 -6
- package/docs/cli-design.md +0 -67
- package/docs/delivery-workflow.md +0 -98
- package/docs/plugin-ui.md +0 -102
- package/docs/provider-configuration.md +0 -116
- package/docs/void-verification.md +0 -185
package/docs/stack-standard.md
CHANGED
|
@@ -1,175 +1,250 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Stack standard
|
|
2
|
+
|
|
3
|
+
This is the architecture standard for applications generated by Anhedral. Use it to select components and decide where code belongs. Follow the [software factory](software-factory.md) to implement and deliver the product.
|
|
4
|
+
|
|
5
|
+
The default web foundation is Vinext, React, TypeScript, Tailwind, shadcn/ui and Lucide on Cloudflare Workers. Every project uses pnpm workspaces and Turborepo. Add components for a concrete product requirement; the default does not include a database, identity provider or every available service.
|
|
6
|
+
|
|
7
|
+
## Defaults and foundations
|
|
8
|
+
|
|
9
|
+
| Area | Default behavior |
|
|
10
|
+
| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| Application | Vinext web app; Cloudflare hosting |
|
|
12
|
+
| Workspace | pnpm workspaces, Turborepo and one root lockfile, including single-app projects |
|
|
13
|
+
| Shared tooling | `packages/typescript-config` and `packages/eslint-config` |
|
|
14
|
+
| Web UI | Shared `packages/ui`, shadcn/ui conventions, React, Tailwind and Lucide |
|
|
15
|
+
| Cloudflare delivery | Void for supported selections; explicit OpenNext, Queues and Basin use Wrangler |
|
|
16
|
+
| Runtime | Node.js `24.21.0+` for Void; pnpm `10.34.5` |
|
|
17
|
+
| Configuration | One root `anhedral.json`; application tooling stays beside its app |
|
|
18
|
+
| Data, identity and integrations | Opt-in; no database, authentication, billing, email or analytics service is selected by plain `init` |
|
|
19
|
+
| Generation | Source and dependency setup; no cloud provisioning, deployment or automatic source commit |
|
|
20
|
+
|
|
21
|
+
The registry contains 28 selectable products and four foundation entries: `workspace`, `typescript`, `eslint` and `ui`. The first three accompany every project; `ui` accompanies web applications. Product flags select recipes; the resolver supplies required foundation dependencies.
|
|
22
|
+
|
|
23
|
+
## Select the applications
|
|
24
|
+
|
|
25
|
+
| Need | Selection | Destination and generated architecture |
|
|
26
|
+
| ------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
27
|
+
| Web on Workers | Default, or `--vinext` | `apps/web`; Vinext, Vite and React on Cloudflare |
|
|
28
|
+
| Native Next.js on Vercel | `--next` | `apps/web`; native Next.js and Vercel configuration |
|
|
29
|
+
| Next.js on Workers | `--next --hosting=cloudflare` | `apps/web`; OpenNext adapter and Wrangler delivery |
|
|
30
|
+
| API shared by multiple clients | `--hono` | `apps/api`; Hono Worker with OpenAPI/Zod contracts and health route |
|
|
31
|
+
| iOS and Android | `--expo` | `apps/mobile`; Expo, React Native, Expo Router, NativeWind and React Native Reusables configuration |
|
|
32
|
+
| Desktop | `--electron` | `apps/desktop`; Electron, React, Vite, isolated preload and platform packaging configuration |
|
|
33
|
+
| Browser extension | `--wxt` | `apps/extension`; WXT/React Chrome side panel with user-triggered active-page access |
|
|
34
|
+
|
|
35
|
+
For example, `--vinext --hono --expo --neon` selects web, an API, mobile and PostgreSQL. Explicit application flags replace the default application selection: `--expo` alone selects mobile, and `--hono` alone selects the API. If only add-ons are requested, the resolver includes a default web app: `--neon` selects Neon and Vinext. Vinext and Next.js are alternatives. Native Next.js defaults to Vercel; Vinext uses Workers.
|
|
36
|
+
|
|
37
|
+
Use server routes inside the web app when it is the only consumer. Add Hono when mobile, desktop, extensions or independent clients need a shared API. Browser and device clients access server endpoints; they never import database factories or receive server credentials. Check actual Vinext behavior in its Worker runtime rather than assuming native Next.js parity.
|
|
38
|
+
|
|
39
|
+
## Select data and identity
|
|
40
|
+
|
|
41
|
+
| Selection | Destination and generated scope | Required implementation/setup |
|
|
42
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
|
|
43
|
+
| `--d1` | `packages/db`; Drizzle/D1 factory, schema and explicit migration tooling; `DB` Worker binding | Create/reconcile the database, define product tables and review SQL; one deployment migration owner |
|
|
44
|
+
| `--neon` | `packages/db`; Drizzle/Neon HTTP factory, schema and transactional migration tooling | Select project/role, configure runtime and separate direct migration connections, review SQL |
|
|
45
|
+
| `--better-auth` | `packages/auth` and database schema; auth routes on the selected server | Private secret, public auth origin, migrations, sign-up policy and resource authorization |
|
|
46
|
+
| `--clerk` | Web provider, sign-in/up pages and middleware when web is selected; `packages/auth` backend helper when Hono is selected | Configure keys, origins, protected routes and native client integration as needed |
|
|
47
|
+
| `--local-data` | `packages/local-data`; async read/write interface | Implement platform-specific SQLite/filesystem adapters, offline behavior and synchronization |
|
|
48
|
+
|
|
49
|
+
D1 is the standard choice when Worker-local SQL fits. Choose Neon when the application needs PostgreSQL semantics. Better Auth supplies application-controlled identity; Clerk supplies hosted identity. Hosting audience protection is a separate access layer from either choice.
|
|
50
|
+
|
|
51
|
+
## Select services
|
|
52
|
+
|
|
53
|
+
| Selection | Destination and generated scope | Required implementation/setup |
|
|
54
|
+
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| `--r2` | Selected server's private `FILES` binding and `private-files.md` | Authorized upload/download/delete endpoints and file ownership checks; no public bucket or generic file API is generated |
|
|
56
|
+
| `--kv` | Selected server's `CONFIG` binding | Keys, TTLs and propagation handling; never use KV as transactional authority |
|
|
57
|
+
| `--realtime` | `apps/realtime`; SQLite-backed Durable Object rooms and WebSocket message forwarding | Authenticate connections, authorize membership, isolate rooms and handle reconnects; public entry returns 501 until implemented |
|
|
58
|
+
| `--neon-realtime` | `packages/neon-realtime`; separate sealing server/subscription client factories and Drizzle adapter | Manually activate the selected branch, configure origins and implement authorized queries, renewal and cleanup |
|
|
59
|
+
| `--stream` | `packages/stream`; server-only Cloudflare Stream live input factory for WHIP/WHEP broadcasts | Activate Stream manually; implement creator/player UI, input ownership, media negotiation, playback privacy and teardown |
|
|
60
|
+
| `--queues` | `apps/jobs`; queue producer/consumer, retry limits and dead-letter configuration; producer binding on a selected server | Transactional idempotency, processing and dead-letter recovery; the starter retries messages instead of acknowledging unimplemented work |
|
|
61
|
+
| `--cron` | `apps/scheduled`; scheduled Worker with an hourly starter trigger | Product schedule, task implementation, overlap policy, idempotency and failure visibility |
|
|
62
|
+
| `--workflows` | `apps/workflows`; durable workflow and a retryable validation step | Authorized invocation, product steps, retry/resume/cancel behavior and recovery |
|
|
63
|
+
| `--workers-ai` | Selected server's `AI` Worker binding | Model calls, authorization, input handling, usage and spending limits |
|
|
64
|
+
|
|
65
|
+
`--realtime` and `--neon-realtime` are independent and can coexist. The former supplies room-based messaging infrastructure; the latter supplies live SQL query integration. Neither generates a complete collaboration or subscription feature.
|
|
66
|
+
|
|
67
|
+
## Select SDKs and integrations
|
|
68
|
+
|
|
69
|
+
| Selection | Destination and generated scope | Required implementation/setup |
|
|
70
|
+
| -------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
71
|
+
| `--openai` | `packages/ai`; direct server-side OpenAI SDK factory | Models, routes, failure handling and usage limits |
|
|
72
|
+
| `--ai-sdk` | `packages/ai`; AI SDK `generateText`/`streamText` exports and OpenAI provider | Streaming, tools, cancellation and provider configuration; generated credentials default to OpenAI |
|
|
73
|
+
| `--resend` | `packages/email`; server SDK factory | Verified sending domain, templates, delivery/bounce handling and webhook verification |
|
|
74
|
+
| `--stripe` | `packages/billing`; server SDK factory | Products/prices, purchase/cancellation flows, signed webhooks, entitlements and idempotency |
|
|
75
|
+
| `--revenuecat` | `packages/billing/revenuecat.md`; cross-store integration guidance | Install platform SDKs and configure store products, offerings, purchase/restore flows and entitlement reconciliation |
|
|
76
|
+
| `--sentry` | `packages/observability`; integration boundary and redaction fields | Install/init platform SDKs, configure private source-map uploads and verify alerts |
|
|
77
|
+
| `--posthog` | `packages/analytics`; server analytics factory | Event schema, consent, privacy filtering and event delivery |
|
|
78
|
+
| `--basin` | `packages/analytics`, or `packages/basin` alongside PostHog; event helper and private `ANALYTICS` stream binding | Event schema, ingestion verification and application-specific sink/transformation design |
|
|
79
|
+
| `--styling` | `packages/styling`; light/dark tokens and Tailwind v3 preset used by Expo/WXT | Platform typography/components and adoption by other interfaces; automatically selected with Expo and WXT |
|
|
80
|
+
|
|
81
|
+
OpenAI and AI SDK are alternative recipes for `packages/ai`; Workers AI can accompany either. PostHog and Basin can coexist: the Basin recipe changes its package destination to avoid a collision. Electron starts with its own renderer styling; shared tokens do not imply one component library across every platform.
|
|
82
|
+
|
|
83
|
+
The provider adapters can configure selected Neon projects/connections, Clerk applications/keys, Resend domains/sending keys, Stripe account/webhook setup, RevenueCat projects/apps/keys, Sentry projects/DSNs, PostHog projects and OpenAI projects/service accounts. This automation is separate from the generated application integration. See [provider configuration](software-factory.md#provider-configuration) for fields, credentials, permissions and remaining owner steps. Neon Realtime activation is manual.
|
|
84
|
+
|
|
85
|
+
## Composition and compatibility
|
|
86
|
+
|
|
87
|
+
| Choice | Resolver behavior |
|
|
88
|
+
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
|
89
|
+
| No application flag | Adds Vinext, or Next.js when Vercel hosting is selected |
|
|
90
|
+
| `--next` without a hosting flag | Selects Vercel |
|
|
91
|
+
| Vinext with Vercel | Rejected; Vinext requires Cloudflare |
|
|
92
|
+
| Vinext and Next.js; D1 and Neon; Better Auth and Clerk; OpenAI and AI SDK | Each pair is mutually exclusive |
|
|
93
|
+
| Better Auth without a database | Adds D1; an explicit Neon selection uses PostgreSQL instead |
|
|
94
|
+
| Neon Realtime without a database | Adds Neon; an explicit D1 selection is rejected |
|
|
95
|
+
| Better Auth with Neon Realtime | Resolves to Neon regardless of flag order |
|
|
96
|
+
| RevenueCat without Stripe | Rejected; select `--stripe` explicitly |
|
|
97
|
+
| Expo or WXT | Includes the shared styling package |
|
|
98
|
+
| Database/auth or Neon Realtime without a server | Rejected; select a compatible web app or Hono |
|
|
99
|
+
| Native Next.js/Vercel with Worker-bound capabilities such as D1, R2, KV or Workers AI | Adds Hono for the Cloudflare runtime |
|
|
100
|
+
| OpenNext, Queues or Basin | Uses Wrangler for all Cloudflare targets in the workspace |
|
|
101
|
+
| Later addition that changes the engine or relocates existing runtime source | Rejected; `add` does not migrate delivery engines or runtime ownership |
|
|
102
|
+
|
|
103
|
+
When Hono is selected, it owns the shared database/auth runtime and server resource bindings. Other interfaces consume its endpoints. Worker services such as realtime, cron and workflows have their own deployable applications.
|
|
2
104
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
| Layer | Supported options | Generated foundation |
|
|
8
|
-
| --- | --- | --- |
|
|
9
|
-
| Workspace | pnpm/Turborepo, TypeScript, ESLint, shared UI | Official pinned shadcn monorepo bootstrap, workspace configuration and checks |
|
|
10
|
-
| Web | Vinext; Next.js | React, Tailwind, shadcn/ui and Lucide; Vinext on Workers by default, native Next.js on Vercel or explicit OpenNext on Workers |
|
|
11
|
-
| API | Hono | OpenAPI Worker application with selected service bindings |
|
|
12
|
-
| Cloudflare delivery | Void; explicit Wrangler profiles | Void provisions and publishes; Anhedral composes, controls audience policy and independently verifies |
|
|
13
|
-
| Mobile | Expo | React Native Reusables and NativeWind; native builds require platform toolchains |
|
|
14
|
-
| Desktop | Electron | React application; packaging, signing and distribution require platform-specific setup |
|
|
15
|
-
| Browser extension | WXT | React popup and Chrome side panel; installation and store distribution are separate steps |
|
|
16
|
-
| Data | D1, Neon, local data | Drizzle schemas for D1/Neon; direct Neon serverless HTTP; device-local data foundations |
|
|
17
|
-
| Live Postgres queries | Neon Realtime (`--neon-realtime`) | Optional server/client factories and Drizzle adapter; branch setup and authorized query flows remain application work |
|
|
18
|
-
| Identity | Better Auth, Clerk | Server/client configuration and selected schema or provider middleware |
|
|
19
|
-
| Worker services | R2, KV, realtime, Queues, cron, Workflows | Private storage bindings, cache/config bindings, Durable Object WebSocket rooms and job/schedule foundations |
|
|
20
|
-
| AI | Workers AI, OpenAI, AI SDK | Server-side inference bindings or SDK factories |
|
|
21
|
-
| Email | Resend | Server-side transactional email client |
|
|
22
|
-
| Payments | Stripe, RevenueCat | Payment/entitlement integration foundations |
|
|
23
|
-
| Monitoring and analytics | Sentry, PostHog, Basin | Runtime SDK factories or analytical ingestion configuration |
|
|
24
|
-
| Shared styling | Styling | Tokens and presets for compatible native and extension clients |
|
|
25
|
-
|
|
26
|
-
Every generated project uses pnpm workspaces (`apps/*` and `packages/*`), one root `pnpm-lock.yaml`, and a registry-pinned Turborepo version. Root commands run the shared task graph; adding a second interface does not introduce a separate installer or lockfile. Application/service entry points live in `apps`, reusable implementation in `packages`. Extract shared code around actual consumers rather than moving every helper into a package.
|
|
27
|
-
|
|
28
|
-
Database-backed selections create the server-only `@workspace/db` package:
|
|
29
|
-
|
|
30
|
-
| Path | Responsibility |
|
|
31
|
-
| --- | --- |
|
|
32
|
-
| `packages/db/src/index.ts` | Database factory; the server supplies a connection string or D1 binding |
|
|
33
|
-
| `packages/db/src/schema.ts` | Shared Drizzle schema, including selected auth tables |
|
|
34
|
-
| `packages/db/src/migrate.ts` | Explicit migration entry point, separate from runtime exports |
|
|
35
|
-
| `packages/db/drizzle/` | Generated SQL, snapshots and migration journal |
|
|
36
|
-
| `packages/db/drizzle.config.ts` | Paths resolved relative to the configuration file, not the caller's working directory |
|
|
37
|
-
|
|
38
|
-
Only server consumers depend on `@workspace/db`; browser, mobile and extension interfaces use API contracts and endpoints. Reusable auth and other selected integrations remain independent packages. Each server is responsible for authentication, resource authorization and its environment. The database factory never loads environment files or migrates during application startup.
|
|
105
|
+
```sh
|
|
106
|
+
# Web with D1 and Better Auth (D1 is also the conditional auth default).
|
|
107
|
+
anhedral init my-app --better-auth
|
|
39
108
|
|
|
40
|
-
|
|
109
|
+
# Web, API and mobile with PostgreSQL.
|
|
110
|
+
anhedral init my-app --vinext --hono --expo --neon
|
|
41
111
|
|
|
42
|
-
|
|
112
|
+
# Vercel web with an automatically selected Hono backend for R2.
|
|
113
|
+
anhedral init my-app --next --r2
|
|
43
114
|
|
|
44
|
-
|
|
115
|
+
# Independent room messaging and live PostgreSQL queries.
|
|
116
|
+
anhedral init my-app --realtime --neon-realtime
|
|
117
|
+
```
|
|
45
118
|
|
|
46
|
-
|
|
119
|
+
The bundled registry is authoritative for exact dependencies, destinations and compatibility:
|
|
47
120
|
|
|
48
121
|
```sh
|
|
49
122
|
anhedral registry list --json
|
|
50
123
|
anhedral registry view better-auth --json
|
|
51
|
-
anhedral init my-app --hono --d1 --better-auth --r2 --dry-run --json
|
|
124
|
+
anhedral init my-app --vinext --hono --d1 --better-auth --r2 --dry-run --json
|
|
52
125
|
```
|
|
53
126
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
## Neon Realtime
|
|
57
|
-
|
|
58
|
-
Select `--neon-realtime` when the product needs live Postgres query results. It adds Neon when no database was selected and requires a server runtime; an explicit conflicting database is rejected. `--realtime` continues to mean Cloudflare Durable Object WebSocket rooms, which can be selected independently.
|
|
59
|
-
|
|
60
|
-
The recipe creates `packages/neon-realtime` with separate `@workspace/neon-realtime/server` and `/client` exports. The server factory receives private `NEON_REALTIME_SECRET` and `DATABASE_URL` and uses the Drizzle adapter; the client factory receives the public `NEON_REALTIME_URL`. Keep database credentials and sealing code out of browser/native bundles. Follow the generated package README for usage and framework-specific public environment mapping.
|
|
61
|
-
|
|
62
|
-
Manually enable Realtime on the intended Neon branch, allow the exact client origins and configure its secret and URL. The CLI does not automate Realtime provisioning. Authenticate each sealing request, derive user/tenant scope from verified identity and construct bounded, read-only queries on the server. No arbitrary SQL endpoint or complete subscription flow is generated. Clients subscribe with short-lived sealed queries; implement authorized renewal and test denied users and membership changes.
|
|
63
|
-
|
|
64
|
-
[Neon Realtime](https://neon.com/docs/realtime/overview) is beta and currently has no RLS support. Application authorization must be expressed in the scoped queries you seal. See [query authorization](https://neon.com/docs/realtime/guides/queries#authorization) and [branch setup](https://neon.com/docs/realtime/quickstart). Local recipe checks do not establish live subscription, renewal or cross-tenant acceptance.
|
|
65
|
-
|
|
66
|
-
## Source layout and composition
|
|
127
|
+
Append `--dry-run --json` to an initialization command to inspect its resolved products, destinations and setup requirements without writes or network requests. There is no `--all` or external registry support. Recipes create integration foundations; provider resources, credentials and finished features have their own setup and acceptance requirements.
|
|
67
128
|
|
|
68
|
-
|
|
129
|
+
## Organize the source
|
|
69
130
|
|
|
70
|
-
|
|
131
|
+
| Location | Owns |
|
|
132
|
+
| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
|
|
133
|
+
| `apps/web`, `apps/api`, other selected `apps/*` | Deployable applications and services, runtime entry points and configuration |
|
|
134
|
+
| `packages/ui` | Shared web UI components |
|
|
135
|
+
| `packages/db` | Server-only database factory, schemas and migrations |
|
|
136
|
+
| `packages/auth`, other selected `packages/*` | Reusable integration code with explicit inputs |
|
|
137
|
+
| `packages/typescript-config`, `packages/eslint-config` | Shared tooling conventions |
|
|
138
|
+
| `anhedral.json` | Committed Anhedral configuration and provenance |
|
|
139
|
+
| `docs/stack.md` | Generated selection, destinations and setup requirements |
|
|
140
|
+
| `.anhedral/` | Ignored local delivery journals and private state |
|
|
71
141
|
|
|
72
|
-
|
|
73
|
-
| --- | --- |
|
|
74
|
-
| `identity` | Stable local application ID used by the project catalog |
|
|
75
|
-
| `setup` | Selected products, hosting, environment requirements and owner setup |
|
|
76
|
-
| `standard` | Scaffold conventions and version provenance |
|
|
77
|
-
| `registry` | Recipe versions, generated-file fingerprints and workspace references |
|
|
78
|
-
| `providers` | Nonsecret integration settings and selected provider resources |
|
|
79
|
-
| `cloudflare` | Cloudflare delivery engine, account, audience and targets |
|
|
80
|
-
| `vercel` | Vercel repository, project, team and audience |
|
|
142
|
+
Use one root `pnpm-lock.yaml` and the root task graph. Keep framework-specific lint dependencies in the consuming app; shared lint configuration stays usable by non-web clients. Shared packages receive bindings, connections and configuration through factories. Extract code around actual consumers, and keep runtime/network relationships explicit.
|
|
81
143
|
|
|
82
|
-
|
|
144
|
+
See the [full-stack example](https://github.com/anhedral/anhedral-cli/tree/main/examples/full-stack) for a source-only composition. It demonstrates the structure; it is not a running production system.
|
|
83
145
|
|
|
84
|
-
|
|
146
|
+
### One Anhedral configuration
|
|
85
147
|
|
|
86
|
-
|
|
148
|
+
The root `anhedral.json` has an envelope with `schemaVersion: 1` and validated named sections. Each section retains its own domain schema. Only selected hosting sections are present.
|
|
87
149
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
150
|
+
| Section | Purpose |
|
|
151
|
+
| ------------ | --------------------------------------------------------------------- |
|
|
152
|
+
| `identity` | Stable application identity and local catalog registration |
|
|
153
|
+
| `setup` | Products, hosting, environment requirements and owner setup |
|
|
154
|
+
| `standard` | Scaffold conventions and version provenance |
|
|
155
|
+
| `registry` | Recipe versions, generated-file fingerprints and workspace references |
|
|
156
|
+
| `providers` | Nonsecret integration settings and resource selections |
|
|
157
|
+
| `cloudflare` | Delivery engine, account, audience and targets |
|
|
158
|
+
| `vercel` | Repository, team, project and audience |
|
|
93
159
|
|
|
94
|
-
|
|
160
|
+
Preserve unrelated sections when editing. Credentials and delivery history stay outside this document. Native tooling files remain with their applications: a single Anhedral document does not replace `package.json`, Vite configuration or per-app deployment configuration.
|
|
95
161
|
|
|
96
|
-
##
|
|
162
|
+
## Data and migrations
|
|
97
163
|
|
|
98
|
-
|
|
164
|
+
All database-backed selections use the server-only `@workspace/db` package:
|
|
99
165
|
|
|
100
|
-
|
|
166
|
+
| Path | Responsibility |
|
|
167
|
+
| ------------------------------- | ----------------------------------------------------- |
|
|
168
|
+
| `packages/db/src/index.ts` | Factory receiving a D1 binding or connection string |
|
|
169
|
+
| `packages/db/src/schema.ts` | Shared Drizzle schema, including selected auth tables |
|
|
170
|
+
| `packages/db/src/migrate.ts` | Explicit migration entry point |
|
|
171
|
+
| `packages/db/drizzle/` | SQL, snapshots and migration journal |
|
|
172
|
+
| `packages/db/drizzle.config.ts` | Configuration with paths relative to itself |
|
|
101
173
|
|
|
102
|
-
|
|
103
|
-
| --- | --- |
|
|
104
|
-
| Stack selection, registry composition and multi-interface architecture | Supported Cloudflare builds and deployment mechanics |
|
|
105
|
-
| Customer account selection, authored resource declarations and shared-package contracts | Resource provisioning and resolved resource identities |
|
|
106
|
-
| Schema generation, SQL review and designation of one migration owner | Applying the designated reviewed deployment migrations |
|
|
107
|
-
| Audience requirements, hosting-policy orchestration and application authorization | Supported readiness and operational deployment primitives |
|
|
108
|
-
| Source provenance, independent provider checks and end-to-end product acceptance | Worker publication, deployment diagnostics and supported code rollback |
|
|
174
|
+
The factory does not load environment files or migrate on startup. Review generated SQL from `pnpm db:generate` before running `pnpm db:migrate`. Both tasks are uncached and excluded from builds and checks. Exactly one server owns deployment migrations; other consumers share the database without becoming migration writers.
|
|
109
175
|
|
|
110
|
-
|
|
176
|
+
D1 manual migration defaults to local. `pnpm db:migrate -- --remote` explicitly targets the configured database in the migration owner's Worker configuration. Void deployment validates an ignored, byte-identical app-local copy against the authoritative shared SQL; the copy is not another migration source.
|
|
111
177
|
|
|
112
|
-
|
|
178
|
+
Neon runtime queries use server-supplied `DATABASE_URL` through the HTTP adapter. Interactive transactions require a reviewed WebSocket or PostgreSQL adapter. Migrations use a transactional WebSocket connection and direct `DATABASE_URL_UNPOOLED` from the environment or `packages/db/.env.local`/`.env`. Test migrations on the intended development branch before production. Runtime provisioning does not supply migration credentials automatically.
|
|
113
179
|
|
|
114
|
-
|
|
180
|
+
## Live video with Cloudflare Stream
|
|
115
181
|
|
|
116
|
-
|
|
182
|
+
Select `--stream` for one-to-many ultra-low latency live video: browser or supported encoder publishes with WHIP and viewers play with WHEP. [Stream Live WebRTC reached GA on October 15, 2026](https://developers.cloudflare.com/changelog/post/2026-10-15-stream-live-webrtc-ga/). It is the preferred broadcast service when a product needs live video. Add it only when needed; it can coexist with `--realtime` Durable Object messaging and `--neon-realtime` live SQL. Many-to-many calls require a separate Cloudflare Realtime design.
|
|
117
183
|
|
|
118
|
-
|
|
184
|
+
The recipe creates `packages/stream` with a server-only `@workspace/stream/server` export. `createStream({ accountId, apiToken })` exposes live input creation and retrieval. It requires a server, works with Vinext, native Next.js or Hono, and adds no Worker resource binding or SDK dependency. Follow the generated package README. Stream activation, live inputs and runtime credentials are configured explicitly; CLI provisioning and `ship` do not automate this integration.
|
|
119
185
|
|
|
120
|
-
|
|
186
|
+
Keep `STREAM_API_TOKEN` server-only and scope it to Stream Write in the customer account selected by `STREAM_ACCOUNT_ID`. Authorize creators, persist input ownership and enforce quotas before management calls. The returned `webRTC.url` is a publish credential: disclose it only to the authorized broadcaster, never to viewers, logs or static assets. Viewer responses contain only the approved WHEP endpoint or short-lived playback token. Choose `requireSignedURLs` explicitly when creating an input; implement and verify playback token issuance for private broadcasts. Hosting access protection does not protect Stream media endpoints.
|
|
121
187
|
|
|
122
|
-
|
|
188
|
+
Media goes directly between the browser and Stream. The application server owns identity, input ownership and endpoint/token issuance. Implement camera/microphone consent, HTTPS, ICE negotiation, user-facing errors, reconnect and session cleanup. Delete signaling sessions, close peer connections and stop capture tracks when a broadcast ends. No finished player, broadcaster or conferencing feature is generated.
|
|
123
189
|
|
|
124
|
-
|
|
190
|
+
As reviewed October 16, 2026, the [WebRTC documentation](https://developers.cloudflare.com/stream/webrtc-beta/) requires paired WHIP/WHEP and excludes recording, WHIP-to-HLS/DASH playback, RTMP/SRT-to-WHEP bridging, restreaming and live viewer counts. Usage is visible in Stream analytics/billing; broadcast and player-experience metrics remain unsupported. The URL retains `webrtc-beta` although the feature is GA. [Delivery billing](https://developers.cloudflare.com/stream/pricing/) began October 15 at standard Stream rates; budget viewer-minutes and check current account eligibility before activation. Verify creator/viewer access, private media denial, cross-tenant isolation, reconnect and teardown against the actual provider before claiming live acceptance.
|
|
125
191
|
|
|
126
|
-
|
|
192
|
+
```sh
|
|
193
|
+
anhedral init my-app --stream
|
|
194
|
+
anhedral add stream --dry-run --json
|
|
195
|
+
```
|
|
127
196
|
|
|
128
|
-
|
|
197
|
+
## Neon Realtime
|
|
129
198
|
|
|
130
|
-
|
|
199
|
+
`--neon-realtime` selects live PostgreSQL query foundations and adds Neon if no database was chosen. It requires a server and rejects an explicit conflicting database. It can coexist with `--realtime`, which means Durable Object WebSocket rooms.
|
|
131
200
|
|
|
132
|
-
|
|
201
|
+
The recipe creates `@workspace/neon-realtime/server` and `/client` exports in `packages/neon-realtime`. The server receives private `NEON_REALTIME_SECRET` and `DATABASE_URL`; the client receives public `NEON_REALTIME_URL`. Follow the generated package README for framework-specific public environment mapping.
|
|
133
202
|
|
|
134
|
-
|
|
203
|
+
Enable Realtime on the intended Neon branch and configure exact allowed origins, secret and endpoint manually. Authenticate sealing requests, derive user/tenant scope from verified identity, and construct bounded read-only queries on the server. Clients subscribe with short-lived sealed queries; implement authorized renewal, reconnect behavior and isolation tests. No arbitrary SQL endpoint or complete subscription feature is generated.
|
|
135
204
|
|
|
136
|
-
|
|
205
|
+
The pinned integration targets the [Neon Realtime beta](https://neon.com/docs/realtime/overview), whose reviewed authorization model has no RLS support. Scope the queries you seal and review the provider's current limits before production use. Recipe tests do not establish live subscription or cross-tenant acceptance.
|
|
137
206
|
|
|
138
|
-
|
|
207
|
+
## Runtime and delivery configuration
|
|
139
208
|
|
|
140
|
-
|
|
209
|
+
| Profile | Engine and configuration | Project runtime floor |
|
|
210
|
+
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
|
|
211
|
+
| Supported Cloudflare selections | Void `0.27.0`; app-local `anhedral.cloudflare.json`, `void.config.ts`, `env.ts`, `env.example`, committed `void.lock.json` | Node.js `24.21.0+` |
|
|
212
|
+
| Explicit OpenNext, Queues/DLQ or Basin | Wrangler; app-local `wrangler.jsonc` | Node.js `22.13+` on 22.x, or `24+` |
|
|
213
|
+
| Native Next.js/Vercel and other non-Void profiles | Native framework/platform tools | Node.js `22.13+` on 22.x, or `24+` |
|
|
141
214
|
|
|
142
|
-
|
|
143
|
-
- Select one database and one identity provider. Implement resource and tenant authorization in the application; hosting access protection does not replace product identity.
|
|
144
|
-
- Keep R2 private and authorize file operations. KV is eventually consistent and should not hold authoritative transactional state.
|
|
145
|
-
- Implement webhooks and jobs idempotently. Bound retries, concurrency and paid usage; verify recovery and data compatibility before rollback.
|
|
146
|
-
- Verify the actual runtime: Vinext/Vite on Workers, Next.js/OpenNext on Workers, or native Next.js on Vercel. Generated native clients need device, packaging and signing checks appropriate to their target.
|
|
147
|
-
- Run generated checks and exercise product flows. Initialization, installed SDKs and successful builds do not prove provider configuration or production acceptance.
|
|
215
|
+
Use pnpm `10.34.5`. The CLI's own supported Node range is broader than the generated toolchains' requirements. For a new development environment, Node.js `24.21.0+` satisfies these documented floors.
|
|
148
216
|
|
|
149
|
-
|
|
217
|
+
There is one Cloudflare engine per workspace. `add` refuses selections that would switch the engine or relocate existing runtime source. Anhedral owns composition, account/audience selection, shared packages and independent verification; Void owns its supported provisioning, deployment and code rollback mechanics. Native Void framework features are not implied by deploying Vinext through Void.
|
|
150
218
|
|
|
151
|
-
|
|
219
|
+
Void apps read one private app-root `.env`, copied from `env.example`. Avoid `.env.*` companions and `.dev.vars` in those apps. Wrangler and native Vercel use their generated runtime templates. Keep production secrets server-side; public `VITE_*`, `NEXT_PUBLIC_*` and `EXPO_PUBLIC_*` values are build inputs, not server secrets. Vinext maps `NEXT_PUBLIC_*` into client bundles. The [provider reference](software-factory.md#provider-configuration) describes credential transport and each integration's prerequisites.
|
|
152
220
|
|
|
153
|
-
|
|
221
|
+
### Delivery scope by target
|
|
154
222
|
|
|
155
|
-
|
|
223
|
+
| Target | Supported automation | Remaining delivery work |
|
|
224
|
+
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
225
|
+
| Cloudflare web/API/services | Selected resource setup, bindings/secrets, deployment, provider evidence, verification and recorded code rollback | Account/audience selection, product acceptance and data compatibility; rollback does not reverse SQL or restore data |
|
|
226
|
+
| Native Next.js/Vercel | Project connection, environment configuration, CLI delivery or adoption of connected Git deployments, provider evidence and recorded rollback | Eligible account plan, audience protection, repository/CI policy and product acceptance |
|
|
227
|
+
| Mixed Cloudflare/Vercel | Cloudflare first, then Vercel, with per-target receipts | Handle partial success; there is no atomic cross-provider release or rollback |
|
|
228
|
+
| Expo | Explicit platform/profile EAS build, project/source checks, queued-build resume and artifact receipt | Signing, device acceptance, store enrollment and submission; a simulator build is not a store artifact |
|
|
229
|
+
| Electron | Local build and packaging scripts | Platform signing, notarization, installers, updates and distribution |
|
|
230
|
+
| WXT | Local extension build and ZIP tooling | Installed-browser acceptance, store review and publication |
|
|
156
231
|
|
|
157
|
-
|
|
232
|
+
Hosting audience starts unconfigured and must be selected explicitly. Hosting protection, application authentication and resource authorization are separate decisions. Generated SDK factories and configured provider resources do not establish completed user flows.
|
|
158
233
|
|
|
159
|
-
|
|
234
|
+
The optional Codex inspector uses the same project and service domain logic as the CLI. Opening it reads local configuration and recorded evidence. Live status, analytics and bounded data reads require explicit service actions; supported deletion requires its separate confirmation flow. The inspector is development tooling, not a generated application dependency.
|
|
160
235
|
|
|
161
|
-
|
|
236
|
+
## Source ownership and dependency policy
|
|
162
237
|
|
|
163
|
-
|
|
238
|
+
Generated source belongs to the application and remains editable. Preview bundled additions with `add --dry-run`, `--diff` or `--view`; additions preserve edited/untracked source and record provenance. They require current registry receipts. When `filesChecked: false`, the selection plan is available but a new upstream web bootstrap cannot be previewed offline. Actual installation checks conflicts before committing files.
|
|
164
239
|
|
|
165
|
-
|
|
240
|
+
The catalog in `src/stack-registry.ts` defines composition, `src/dependencies.ts` pins dependencies, and `src/scaffold/` implements recipes. Generated plugin references come from these maintained sources and documents.
|
|
166
241
|
|
|
167
|
-
|
|
242
|
+
Commit the resolved lockfile and any generated `patches/*` plus `pnpm-workspace.yaml` patch mappings. Conditional reviewed patches apply only to `braces@3.0.3` and `node-forge@1.4.0`. `pnpm audit:deps` retains raw upstream findings in `.anhedral-audit-report.json` and blocks high/critical advisories except the exact reviewed advisory/version/patch combinations (`GHSA-vfj7-8cjw-p6xm` and `GHSA-86w9-cpqp-85rv`). Frozen pnpm installation applies patches; detailed runtime regressions belong to this repository's `pnpm test:patch`. These temporary mitigations must be reviewed each release and retired when a compatible verified fix replaces them. Compatible brace-expansion overrides do not create an exception for an affected 3.x consumer.
|
|
168
243
|
|
|
169
|
-
|
|
244
|
+
Validate the resolved dependency graph for each application selection. A clean CLI dependency graph does not establish a clean generated application graph.
|
|
170
245
|
|
|
171
|
-
|
|
246
|
+
## Product requirements
|
|
172
247
|
|
|
173
|
-
|
|
248
|
+
A completed application has server-side resource authorization, private file access, reviewed migrations, meaningful error/loading/empty states and tests for its actual user flows. Jobs and webhooks must tolerate duplicates; paid operations need limits and ownership. Verify the selected runtime and any native packaging, permissions and signing.
|
|
174
249
|
|
|
175
|
-
|
|
250
|
+
Use the [software factory](software-factory.md) for the implementation and acceptance process. Detailed delivery evidence and outstanding live acceptance gaps belong in the [Void verification reference](verification.md#void-delivery-verification) and the application's own verification record, rather than in this architecture standard.
|