anhedral 0.12.0 → 0.13.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 +99 -39
- package/dist/capabilities.d.ts +3 -3
- package/dist/capability-contract.js +12 -1
- package/dist/command-schema.js +8 -2
- package/dist/command.js +9 -11
- package/dist/delivery.js +3 -1
- package/dist/dependencies.d.ts +6 -1
- package/dist/dependencies.js +13 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/platforms/mobile.d.ts +1 -1
- package/dist/platforms/mobile.js +44 -3
- package/dist/project-state.js +4 -1
- package/dist/provider-auth.js +6 -0
- package/dist/providers/adapters.js +9 -3
- package/dist/providers/runtime.js +11 -0
- package/dist/readiness.js +4 -2
- package/dist/registry/add.js +40 -7
- package/dist/registry/options.js +12 -0
- package/dist/registry/presets.d.ts +4 -0
- package/dist/registry/presets.js +41 -0
- package/dist/registry/resolve.d.ts +3 -1
- package/dist/registry/resolve.js +40 -14
- package/dist/registry/types.d.ts +1 -0
- package/dist/registry/usage.js +1 -1
- package/dist/runtime-policy.js +4 -1
- package/dist/scaffold/api.js +10 -2
- package/dist/scaffold/auth.d.ts +1 -1
- package/dist/scaffold/auth.js +22 -6
- package/dist/scaffold/backend.d.ts +6 -0
- package/dist/scaffold/backend.js +224 -0
- package/dist/scaffold/billing-config.d.ts +1 -0
- package/dist/scaffold/billing-config.js +73 -0
- package/dist/scaffold/billing-contracts.d.ts +2 -0
- package/dist/scaffold/billing-contracts.js +48 -0
- package/dist/scaffold/billing-providers.d.ts +1 -0
- package/dist/scaffold/billing-providers.js +249 -0
- package/dist/scaffold/billing-schema.d.ts +1 -0
- package/dist/scaffold/billing-schema.js +34 -0
- package/dist/scaffold/billing-security.d.ts +1 -0
- package/dist/scaffold/billing-security.js +46 -0
- package/dist/scaffold/billing-server.d.ts +1 -0
- package/dist/scaffold/billing-server.js +139 -0
- package/dist/scaffold/billing-store.d.ts +1 -0
- package/dist/scaffold/billing-store.js +72 -0
- package/dist/scaffold/billing.d.ts +2 -0
- package/dist/scaffold/billing.js +216 -0
- package/dist/scaffold/cloudflare-services.d.ts +8 -0
- package/dist/scaffold/cloudflare-services.js +198 -0
- package/dist/scaffold/compose.js +2 -0
- package/dist/scaffold/database.js +19 -2
- package/dist/scaffold/documentation.js +10 -6
- package/dist/scaffold/expo-auth.d.ts +3 -0
- package/dist/scaffold/expo-auth.js +192 -0
- package/dist/scaffold/expo-billing.d.ts +3 -0
- package/dist/scaffold/expo-billing.js +292 -0
- package/dist/scaffold/expo-runtime.d.ts +3 -0
- package/dist/scaffold/expo-runtime.js +134 -0
- package/dist/scaffold/integrations.d.ts +2 -1
- package/dist/scaffold/integrations.js +7 -2
- package/dist/scaffold/void.js +13 -5
- package/dist/scaffold/web.js +2 -0
- package/dist/scaffold/workspace.js +6 -1
- package/dist/ship.js +3 -1
- package/dist/stack-registry.d.ts +11 -2
- package/dist/stack-registry.js +136 -16
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/anhedral-stack.md +122 -0
- package/docs/software-factory.md +67 -8
- package/docs/stack-standard.md +126 -57
- package/docs/verification.md +113 -0
- package/package.json +7 -4
package/docs/stack-standard.md
CHANGED
|
@@ -2,39 +2,98 @@
|
|
|
2
2
|
|
|
3
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
4
|
|
|
5
|
-
The default
|
|
5
|
+
The default is a minimal Expo web/iOS/Android client in `apps/mobile`, with React
|
|
6
|
+
Native Reusables using shadcn conventions, NativeWind, shared styling, TypeScript,
|
|
7
|
+
pnpm and Turborepo. Cloudflare serves the static web export. Hono, auth, databases,
|
|
8
|
+
private storage and paid integrations are generated only when selected or required
|
|
9
|
+
by a selected capability. Initialization never provisions or activates services.
|
|
6
10
|
|
|
7
11
|
## Defaults and foundations
|
|
8
12
|
|
|
9
|
-
|
|
|
10
|
-
|
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
| Web
|
|
15
|
-
|
|
|
16
|
-
|
|
|
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 |
|
|
13
|
+
| Layer | Minimal default | Added when needed |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| Clients | Expo / React Native / Expo Router | WXT side panel, Electron, explicit web alternatives |
|
|
16
|
+
| Styling | NativeWind, shared tokens, shadcn conventions | Platform-specific components and effects |
|
|
17
|
+
| Workspace | pnpm, Turborepo, shared TypeScript/ESLint, one lockfile | Public contracts when Hono is selected |
|
|
18
|
+
| Web hosting | Cloudflare static asset Worker | Service binding to a separate Hono API Worker |
|
|
19
|
+
| Backend | None | Hono for server capabilities |
|
|
20
|
+
| Data / identity / files | None | Drizzle/D1, Better Auth, private R2 independently |
|
|
20
21
|
|
|
21
|
-
The registry
|
|
22
|
+
The registry has 33 products and five foundation entries: `workspace`, `typescript`,
|
|
23
|
+
`eslint`, `ui` and the conditional server-only `cloudflare-api` transport. The first three accompany every project; `ui` accompanies
|
|
24
|
+
explicit Next.js/Vinext apps. Expo and WXT resolve shared styling. Shared packages
|
|
25
|
+
are generated for selected responsibilities, not empty future architecture.
|
|
22
26
|
|
|
23
|
-
##
|
|
27
|
+
## Progressive selection and full-product preset
|
|
24
28
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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.
|
|
29
|
+
```sh
|
|
30
|
+
anhedral init my-app
|
|
31
|
+
anhedral init accounts --better-auth
|
|
32
|
+
anhedral init ai-tool --workers-ai
|
|
33
|
+
anhedral init complete --preset full-product --dry-run --json
|
|
34
|
+
anhedral add better-auth --cwd my-app --dry-run --json
|
|
35
|
+
anhedral add stripe revenuecat --cwd my-app --dry-run --json
|
|
36
|
+
```
|
|
36
37
|
|
|
37
|
-
|
|
38
|
+
Plain init and `--preset minimal` select only Expo. `--d1` adds Hono and D1 without
|
|
39
|
+
auth; `--better-auth` adds Hono and D1 unless Neon was selected. Billing adds Hono,
|
|
40
|
+
identity (Better Auth unless Clerk was selected) and a database; RevenueCat does
|
|
41
|
+
not require Stripe. `--workers-ai`, `--images` or `--r2` adds the server capability
|
|
42
|
+
without adding user accounts, billing or unrelated storage. Capabilities resolve
|
|
43
|
+
dependencies to a fixed point independently of flag order. The direct registry API
|
|
44
|
+
remains strict; it validates already-resolved selections rather than inventing them.
|
|
45
|
+
|
|
46
|
+
`--preset full-product` selects Expo, WXT, Hono, D1, Better Auth, R2, KV, Stripe,
|
|
47
|
+
RevenueCat, Workers AI, Analytics Engine, Basin/Pipelines, Durable Object rooms,
|
|
48
|
+
RealtimeKit, Images, Stream live video, on-demand video, Queues, Cron, Workflows,
|
|
49
|
+
Resend and Sentry. It is a compatible complete product foundation, not every
|
|
50
|
+
mutually exclusive vendor or a finished implementation. Explicit Next.js/Vinext,
|
|
51
|
+
Neon and Clerk replace the corresponding preset defaults. Electron, local-data,
|
|
52
|
+
OpenAI/AI SDK, PostHog and Neon Realtime remain separately selectable alternatives
|
|
53
|
+
or specialized additions. The preset does not activate paid services or configure
|
|
54
|
+
all provider accounts. Inspect `registry capabilities` for support and evidence.
|
|
55
|
+
|
|
56
|
+
## Applications and runtime ownership
|
|
57
|
+
|
|
58
|
+
| Selection | Generates |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| Default / `--expo` | Expo universal client and Cloudflare static gateway |
|
|
61
|
+
| `--next` | Next.js on Vercel, the usual explicit web alternative |
|
|
62
|
+
| `--vinext` | Vinext on Cloudflare |
|
|
63
|
+
| `--next --hosting=cloudflare` | Explicit OpenNext compatibility profile |
|
|
64
|
+
| `--hono` | Standalone Hono API, no implicit frontend |
|
|
65
|
+
| `--wxt` | Standalone WXT Chrome side panel; combine with Expo explicitly |
|
|
66
|
+
| `--electron` | Standalone Electron client |
|
|
67
|
+
|
|
68
|
+
Selecting only service capabilities retains Expo as the default client. Explicit
|
|
69
|
+
application selections replace that implicit choice. When server capabilities are
|
|
70
|
+
selected, new profiles use Hono for identity, authorization, persistence and
|
|
71
|
+
privileged integrations; web routes adapt/proxy calls. Existing web-owned backends
|
|
72
|
+
retain their owner, and `add` rejects a required relocation or edited-source
|
|
73
|
+
replacement rather than performing an implicit migration.
|
|
74
|
+
|
|
75
|
+
Hono creates `packages/contracts` for public Zod schemas and HTTP transport.
|
|
76
|
+
Browser clients use `/api/*` through the web gateway; native clients use public
|
|
77
|
+
`EXPO_PUBLIC_API_URL`. Next.js on Vercel uses server-only `API_URL`; a private
|
|
78
|
+
Cloudflare Access API also requires scoped server-only service credentials.
|
|
79
|
+
Clients never import auth/database server packages or another app's source.
|
|
80
|
+
|
|
81
|
+
Adding Hono to an existing minimal Expo app wires its gateway and API client without
|
|
82
|
+
regenerating product screens. Adding auth exposes `/sign-in` and `/account`; connect
|
|
83
|
+
those routes to the product navigation explicitly. Existing edited generated files
|
|
84
|
+
remain protected by transaction fingerprints. No addition removes capabilities.
|
|
85
|
+
|
|
86
|
+
Root `pnpm dev` runs the exported Expo gateway on 3000; Hono joins on 8787 when
|
|
87
|
+
selected. Native Metro uses `pnpm --dir apps/mobile start`. Re-export browser changes
|
|
88
|
+
with `pnpm --dir apps/mobile build:web`; this loop is not HMR. Keep SDK 57 pinned
|
|
89
|
+
unless upgrading deliberately. Static dynamic routes need `generateStaticParams`
|
|
90
|
+
or a supported explicit alternative; static export does not supply SSR.
|
|
91
|
+
|
|
92
|
+
New Expo, OpenNext, Queues, Basin, Images and Analytics Engine selections use
|
|
93
|
+
Wrangler. Preserve existing engines; incompatible additions to Void need a
|
|
94
|
+
reviewed migration. Expo + Better Auth generates browser/native transport and
|
|
95
|
+
screens, but device acceptance remains separate. Full-stack CLI capabilities do
|
|
96
|
+
not automatically upgrade the portal's legacy publisher.
|
|
38
97
|
|
|
39
98
|
## Select data and identity
|
|
40
99
|
|
|
@@ -61,53 +120,61 @@ D1 is the standard choice when Worker-local SQL fits. Choose Neon when the appli
|
|
|
61
120
|
| `--cron` | `apps/scheduled`; scheduled Worker with an hourly starter trigger | Product schedule, task implementation, overlap policy, idempotency and failure visibility |
|
|
62
121
|
| `--workflows` | `apps/workflows`; durable workflow and a retryable validation step | Authorized invocation, product steps, retry/resume/cancel behavior and recovery |
|
|
63
122
|
| `--workers-ai` | Selected server's `AI` Worker binding | Model calls, authorization, input handling, usage and spending limits |
|
|
123
|
+
| `--analytics-engine` | `EVENTS` dataset binding and `packages/analytics-engine/server` helper | Define privacy-safe events; verify ingestion and sampled queries; not a billing ledger |
|
|
124
|
+
| `--images` | `IMAGES` binding and private raw-byte transform helper | Activate Images, authorize source objects and enforce transform/cache limits |
|
|
125
|
+
| `--realtimekit` | Server-only meeting and participant-token factory | Activate app/presets, implement authorized routes and platform media SDK/UI |
|
|
126
|
+
| `--video` | Stream private direct-upload URL helper | Activate Stream, implement processing checks, retention and signed playback |
|
|
64
127
|
|
|
65
128
|
`--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
129
|
|
|
67
130
|
## Select SDKs and integrations
|
|
68
131
|
|
|
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`;
|
|
75
|
-
| `--revenuecat` | `packages/billing
|
|
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
|
|
132
|
+
| Selection | Destination and generated scope | Required implementation/setup |
|
|
133
|
+
| -------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
134
|
+
| `--openai` | `packages/ai`; direct server-side OpenAI SDK factory | Models, routes, failure handling and usage limits |
|
|
135
|
+
| `--ai-sdk` | `packages/ai`; AI SDK `generateText`/`streamText` exports and OpenAI provider | Streaming, tools, cancellation and provider configuration; generated credentials default to OpenAI |
|
|
136
|
+
| `--resend` | `packages/email`; server SDK factory | Verified sending domain, templates, delivery/bounce handling and webhook verification |
|
|
137
|
+
| `--stripe` | `packages/billing`; Hono Checkout/portal, verified webhooks, DB projection and entitlement guard | Configure plans/prices/origin/secrets, review/apply SQL, verify sandbox/live purchase lifecycle |
|
|
138
|
+
| `--revenuecat` | `packages/billing`; native purchase/restore/manage, verified webhooks and shared entitlement projection | Configure project/app IDs, platform keys/offerings/store products, migrate and verify real development-build purchases |
|
|
139
|
+
| `--sentry` | `packages/observability`; integration boundary and redaction fields | Install/init platform SDKs, configure private source-map uploads and verify alerts |
|
|
140
|
+
| `--posthog` | `packages/analytics`; server analytics factory | Event schema, consent, privacy filtering and event delivery |
|
|
141
|
+
| `--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 |
|
|
142
|
+
| `--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
143
|
|
|
81
144
|
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
145
|
|
|
83
146
|
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
147
|
|
|
148
|
+
Optional `--stripe` and `--revenuecat` now generate shared Hono billing, DB schema and validated contracts. Stripe supplies web Checkout/customer portal; RevenueCat supplies native purchase/restore/manage wiring. Each provider projects independently to the signed-in account; Hono unions verified grants and enforces access. Configuration, reviewed SQL migration and provider/store acceptance remain required. Neither provider is selected by plain init.
|
|
149
|
+
|
|
150
|
+
Existing billing-guidance/scaffold projects retain their recorded provenance. New billing implementation requires an explicitly reviewed migration; do not silently replace edited source or treat an old SDK factory as the new entitlement contract.
|
|
151
|
+
|
|
85
152
|
## Composition and compatibility
|
|
86
153
|
|
|
87
154
|
| Choice | Resolver behavior |
|
|
88
155
|
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
|
89
|
-
| No application flag | Adds
|
|
156
|
+
| No application flag | Adds Expo universal frontend; explicit Vercel hosting selects Next.js |
|
|
90
157
|
| `--next` without a hosting flag | Selects Vercel |
|
|
91
158
|
| Vinext with Vercel | Rejected; Vinext requires Cloudflare |
|
|
92
159
|
| Vinext and Next.js; D1 and Neon; Better Auth and Clerk; OpenAI and AI SDK | Each pair is mutually exclusive |
|
|
93
160
|
| Better Auth without a database | Adds D1; an explicit Neon selection uses PostgreSQL instead |
|
|
94
161
|
| Neon Realtime without a database | Adds Neon; an explicit D1 selection is rejected |
|
|
95
162
|
| Better Auth with Neon Realtime | Resolves to Neon regardless of flag order |
|
|
96
|
-
| RevenueCat without Stripe |
|
|
163
|
+
| RevenueCat without Stripe | Supported independent selection; billing remains optional |
|
|
97
164
|
| Expo or WXT | Includes the shared styling package |
|
|
98
|
-
| Database/auth or Neon Realtime without a server |
|
|
99
|
-
| Native Next.js/Vercel with Worker-bound capabilities such as D1, R2, KV or Workers AI | Adds Hono
|
|
100
|
-
| OpenNext, Queues or
|
|
165
|
+
| Database/auth or Neon Realtime without a server | Init includes Hono; existing additions require a compatible server |
|
|
166
|
+
| Native Next.js/Vercel with Worker-bound capabilities such as D1, R2, KV or Workers AI | Adds Hono on Cloudflare when required |
|
|
167
|
+
| New Expo workspaces, OpenNext, Queues, Basin, Images or Analytics Engine | Uses Wrangler for all Cloudflare targets in the workspace |
|
|
101
168
|
| Later addition that changes the engine or relocates existing runtime source | Rejected; `add` does not migrate delivery engines or runtime ownership |
|
|
102
169
|
|
|
103
|
-
|
|
170
|
+
Hono 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.
|
|
104
171
|
|
|
105
172
|
```sh
|
|
106
173
|
# Web with D1 and Better Auth (D1 is also the conditional auth default).
|
|
107
174
|
anhedral init my-app --better-auth
|
|
108
175
|
|
|
109
|
-
#
|
|
110
|
-
anhedral init my-app --
|
|
176
|
+
# Universal web/iOS/Android and API with PostgreSQL.
|
|
177
|
+
anhedral init my-app --expo --neon
|
|
111
178
|
|
|
112
179
|
# Vercel web with an automatically selected Hono backend for R2.
|
|
113
180
|
anhedral init my-app --next --r2
|
|
@@ -128,19 +195,21 @@ Append `--dry-run --json` to an initialization command to inspect its resolved p
|
|
|
128
195
|
|
|
129
196
|
## Organize the source
|
|
130
197
|
|
|
131
|
-
| Location
|
|
132
|
-
|
|
|
133
|
-
| `apps/
|
|
134
|
-
| `packages/ui`
|
|
135
|
-
| `packages/db`
|
|
136
|
-
| `packages/auth`, other selected `packages/*`
|
|
137
|
-
| `packages/typescript-config`, `packages/eslint-config`
|
|
138
|
-
| `anhedral.json`
|
|
139
|
-
| `docs/stack.md`
|
|
140
|
-
| `.anhedral/`
|
|
198
|
+
| Location | Owns |
|
|
199
|
+
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
200
|
+
| `apps/mobile`, `apps/api`, explicit `apps/web`, other selected `apps/*` | Deployable applications and services, runtime entry points and configuration |
|
|
201
|
+
| `packages/ui` | Shared web UI components |
|
|
202
|
+
| `packages/db` | Server-only database factory, schemas and migrations |
|
|
203
|
+
| `packages/auth`, other selected `packages/*` | Reusable integration code with explicit inputs |
|
|
204
|
+
| `packages/typescript-config`, `packages/eslint-config` | Shared tooling conventions |
|
|
205
|
+
| `anhedral.json` | Committed Anhedral configuration and provenance |
|
|
206
|
+
| `docs/stack.md` | Generated selection, destinations and setup requirements |
|
|
207
|
+
| `.anhedral/` | Ignored local delivery journals and private state |
|
|
141
208
|
|
|
142
209
|
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.
|
|
143
210
|
|
|
211
|
+
Validate browser/API routing through the Cloudflare gateway and Hono separately from iOS/Android exports. Static/native exports establish compilation, not device, auth or store acceptance.
|
|
212
|
+
|
|
144
213
|
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.
|
|
145
214
|
|
|
146
215
|
### One Anhedral configuration
|
|
@@ -179,7 +248,7 @@ Neon runtime queries use server-supplied `DATABASE_URL` through the HTTP adapter
|
|
|
179
248
|
|
|
180
249
|
## Live video with Cloudflare Stream
|
|
181
250
|
|
|
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
|
|
251
|
+
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 use the separately selected `--realtimekit` server helpers and platform client implementation.
|
|
183
252
|
|
|
184
253
|
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.
|
|
185
254
|
|
|
@@ -214,7 +283,7 @@ The pinned integration targets the [Neon Realtime beta](https://neon.com/docs/re
|
|
|
214
283
|
|
|
215
284
|
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.
|
|
216
285
|
|
|
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.
|
|
286
|
+
Existing projects keep their recorded backend ownership during readiness checks and additions. A pre-contracts Hono project needs an explicit contracts/proxy migration before adding web/auth UI wiring; unrelated additions preserve its API source. 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.
|
|
218
287
|
|
|
219
288
|
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.
|
|
220
289
|
|
package/docs/verification.md
CHANGED
|
@@ -2,6 +2,66 @@
|
|
|
2
2
|
|
|
3
3
|
Dated records below describe the source and environment exercised at that time. Earlier results are historical evidence, not acceptance of a later release. Current architecture and operating instructions live in the stack standard and software factory.
|
|
4
4
|
|
|
5
|
+
## Full Cloudflare default and optional shared billing — 2026-10-18
|
|
6
|
+
|
|
7
|
+
New plain initialization and new Expo selections include Expo web/iOS/Android, Hono, Better Auth, Drizzle/D1 and private R2. Explicit Neon replaces D1. WXT-only initialization adds an extension to that default; explicit primary applications preserve their compatibility selection. Existing saved selections and unrelated additions do not receive new profile defaults. Legacy billing SDK/guidance projects require their pinned CLI or an explicit reviewed migration; strict provenance was preserved.
|
|
8
|
+
|
|
9
|
+
Stripe and RevenueCat are independently optional. Generated shared contracts, Expo web/native billing adapters, authenticated Hono Checkout/portal/identity/entitlement routes and a server enforcement example are connected. The authenticated subject is the RevenueCat App User ID. Server-only Drizzle tables store account/customer ownership, fenced reconciliation snapshots and an idempotent webhook inbox. Stripe signatures use raw request bodies; RevenueCat requires configured Authorization and supports HMAC with timestamp checks. Canonical provider reads reconcile grants instead of trusting event order or client purchase state. A bounded scheduled retry drains pending events. Access caches expire within sixty seconds and never outlive provider expiry; stale access fails closed during outages. Provider environments and native public keys remain isolated from private credentials.
|
|
10
|
+
|
|
11
|
+
Checkout guards nonterminal subscriptions independently of entitlement state, including refunded or past-due subscriptions. Verified open same-plan sessions are reused across distinct intents; another pending plan returns a conflict. Root client error handling gives safe conflict guidance. SDK operations fence native identity changes; RevenueCat logout failure cannot prevent Better Auth session revocation. R2 remains a private binding: each product must implement file ownership checks before exposing file routes.
|
|
12
|
+
|
|
13
|
+
Local evidence:
|
|
14
|
+
|
|
15
|
+
- CLI build, lint and static security checks passed. The full unit suite passed with 743 passing, zero failures and two existing skips (745 total); the focused release-scanner regression also passed. The scanner correction exempts only adjacent empty assignments in example files; populated secrets and JavaScript multiline credentials remain detected.
|
|
16
|
+
- Retained `examples/billing-reference` was generated with `--stripe --revenuecat`; its final full `pnpm check` passed, including client/server/Worker types, Fallow, dependency audit, static web export and both Worker dry builds. Reviewed reference migration source is `0001_billing.sql`; no configured database was migrated. Final iOS/Android Hermes exports passed with the real optional RevenueCat native package and account-transition adapters.
|
|
17
|
+
- `pnpm test:billing` passed against the compiled generated Hono Worker, real Better Auth/Drizzle SQL and Stripe SDK, with synthetic vendor HTTP responses and in-memory SQLite. It covered authenticated account isolation, strict plans/body/origins, deterministic retries, open-session reuse, duplicate-sale guards, server enforcement, independent optional providers, Stripe/RevenueCat grant union, refund/revocation, cancellation versus expiry, trial/past-due behavior, native transfers, invalid/stale signatures, environment/app scope, duplicate/out-of-order events, concurrent lease fencing, stale-cache outage denial and durable scheduled recovery. SQLite fixtures do not certify Cloudflare D1 semantics; vendor fixtures do not certify provider/store acceptance.
|
|
18
|
+
- A final fresh `node tests/test-generated-apps.mjs universal-billing` passed initialization/install, generated SQL/check/build, local workerd/D1/R2 auth and the compiled billing proof, including open-session reuse and duplicate-sale guards. The hosted CI matrix now includes this reproducible profile.
|
|
19
|
+
- Real local workerd, service bindings, D1 and private R2 loaded successfully. Chrome verified signup, protected account/reload, sign-out and mobile viewport behavior. An initial concurrent-edit run observed Worker reload/session unavailability; the unchanged assertions passed after source writers stopped. No timeout or security assertions were relaxed.
|
|
20
|
+
- Main repository `pnpm check` and `pnpm build` passed. The five local Anhedral skills passed frontmatter/UI-metadata YAML and local-reference checks. CLI build refreshes bundled references; an installed plugin is not silently updated.
|
|
21
|
+
|
|
22
|
+
Billing provider products/prices, webhook ingress and credentials, RevenueCat project/store policy, signed native builds and real sandbox purchases still require owner configuration and acceptance. Native exports are not device tests. Nothing was provisioned, deployed or published; no financial provider writes, charges or remote migrations were performed. Earlier dated records remain historical evidence of their own source/environment.
|
|
23
|
+
|
|
24
|
+
## Universal Expo default — 2026-10-18
|
|
25
|
+
|
|
26
|
+
New plain initialization selects Expo web/iOS/Android in `apps/mobile`, Hono in `apps/api`, shared contracts/styling and Wrangler delivery on Cloudflare. SDK 57 exports static web assets behind a thin API-binding gateway. Explicit Vinext/Next.js selections and existing projects remain supported. Better Auth selects a database and generates browser/native session adapters, exact application-scheme trust, SecureStore integration and account screens. Billing entitlements and the portal publisher remain separate implementation work.
|
|
27
|
+
|
|
28
|
+
Local evidence:
|
|
29
|
+
|
|
30
|
+
- CLI build, lint, static security policy and the full unit suite passed: 740 passing, zero failures and two existing conditional skips (742 total). Coverage includes gateway forwarding/caching/failure behavior, API-first target order, public build-variable isolation, native cookie rotation and server/browser/native auth boundaries.
|
|
31
|
+
- Retained `examples/universal-reference` was generated from the local CLI with `--better-auth --no-git`. Its complete `pnpm check` passed, including lint, client/server/gateway types, Fallow, dependency audit, static web export and both Worker dry builds. Its lockfile and source are retained; generated outputs remain ignored.
|
|
32
|
+
- `pnpm test:reference --browser` passed against real local workerd, an API service binding and disposable D1. It exercised health/exported routes, signup/login, protected contracts, incorrect-password rejection, sign-out/revocation, forged identity-header rejection, native scheme/cookie transport and untrusted-scheme rejection. Headless installed Chrome verified account creation, the protected account screen, reload, sign-out and a 390px viewport without horizontal overflow. The helper creates local synthetic credentials/state, applies migrations only with `--local`, refuses existing configured private files and cleans its processes/files.
|
|
33
|
+
- A second fresh `node tests/test-generated-apps.mjs universal-auth` passed initialization, installation, full generated `pnpm check` and the real workerd/D1 gateway acceptance flow, proving the retained example does not depend on manual source repairs.
|
|
34
|
+
- Final iOS and Android Hermes exports passed with the platform-specific auth and development-client modules. This proves bundler compatibility, not an installed native build or device session persistence.
|
|
35
|
+
- Main repository `pnpm check` and `pnpm build` passed. Five local Anhedral skills passed YAML/frontmatter/UI-metadata and local-reference validation.
|
|
36
|
+
|
|
37
|
+
The browser preview currently needs a new static export for changes; it does not provide web HMR. Arbitrary unknown dynamic URLs require explicit routing/rendering design. Physical-device/simulator native acceptance, native compilation/signing, deployed Cloudflare behavior, store purchase sandboxes and complete billing synchronization remain unverified. No cloud provisioning, remote migration, deployment, package publication or installed-plugin update occurred. Earlier records below retain their original source/environment scope.
|
|
38
|
+
|
|
39
|
+
## Default Hono backend — 2026-10-18
|
|
40
|
+
|
|
41
|
+
New initialization includes Hono and framework-independent Zod/HTTP contracts. Web remains Vinext/Cloudflare by default; explicit native Next.js/Vercel calls the API through a server-only configured URL. Cloudflare web/API service bindings, cookie-preserving same-origin transport, selected database bindings/factories and Better Auth routes/session UI are generated together. Database and identity remain opt-in. New routes still need product authorization. Existing registry metadata remains compatible; readiness and additions do not apply new backend defaults to old selections.
|
|
42
|
+
|
|
43
|
+
Local validation:
|
|
44
|
+
|
|
45
|
+
- CLI build and lint (types, formatting, source hygiene and release policy) passed. The unit suite passed with 738 passing and two skipped tests, including shared-client response validation and Vercel server-credential transport checks. The composition matrix now validates 200 supported combinations.
|
|
46
|
+
- A fresh `node tests/test-generated-apps.mjs web-auth` completed initialization/install, generated `pnpm check` (including Fallow and dependency audit), build, real Vite/workerd web→API service binding, rendered auth screen, signup/login, protected session, invalid-password rejection, signout and revocation. Compiled Worker/Drizzle auth also passed against isolated in-memory SQLite; both generated Workers passed production-runtime local previews. Test data and credentials were synthetic/local; migrations were never applied to a configured production database.
|
|
47
|
+
- An isolated generated native Next.js/Vercel + Hono/Neon profile passed its full `pnpm check` and build after regeneration with the current scaffold. No live Neon database or protected Vercel-to-Cloudflare deployment was exercised. Its API URL and optional Access service credentials remain explicit deployment configuration.
|
|
48
|
+
- A copy of the original HEAD generator produced real old web-only, Hono-only and combined Hono/web/auth receipts. Current readiness accepted each; adding Resend preserved its API source and did not silently generate/migrate contracts. Pre-contracts Hono web/auth additions require an explicit migration.
|
|
49
|
+
- The five local skills in the main repository passed frontmatter/UI-metadata parsing and local-reference checks. Main repository `pnpm check` and `pnpm build` passed for the checked working state. Historical verification records remain intact.
|
|
50
|
+
|
|
51
|
+
The Expo/RevenueCat/Stripe sequence is a documented implementation roadmap, not generated native authentication, store purchases or verified billing behavior. No cloud provisioning, remote migrations, deployment, package publication or installed-plugin update occurred. Provider access/protection, native/device acceptance, store sandboxes and real billing remain separate verification work.
|
|
52
|
+
|
|
53
|
+
## Maintenance practices — 2026-10-18
|
|
54
|
+
|
|
55
|
+
Added the software factory's evidence-driven maintenance workflow and connected it to the CLI's root `AGENTS.md`, contribution/PR guidance, shipped Anhedral skill and generated application instructions. It covers removal evidence for published/generated consumers, operational flag dependencies, focused changes, causal flaky-test diagnosis and controlled instruction comparisons. Existing uncommitted CI work was preserved. These instruction changes have not been evaluated through comparative agent task replays; no model cost or quality improvement is claimed.
|
|
56
|
+
|
|
57
|
+
Local CLI build, generator and plugin package contracts (`node --test tests/test-standard.test.mjs tests/test-plugin.test.mjs`, two tests passed), source hygiene, changed TypeScript formatting and `git diff --check` passed. Build refreshed bundled canonical references. Skill YAML parsing passed using the repository's YAML library, and package contracts checked bundled Markdown reference targets. The skill-creator Python validator could not start because PyYAML is unavailable. No full release gate, provider acceptance, publication or installed-plugin update was performed for this local workflow change.
|
|
58
|
+
|
|
59
|
+
### CLI integration verification — 2026-10-18
|
|
60
|
+
|
|
61
|
+
Reviewed the pending maintenance guidance and documentation-only CI changes together with the Windows pnpm PATH fix. Ordinary contribution and PR-template Markdown now takes the documentation path; registry matrix preparation is skipped for that path. Source, shipped plugin instructions, unknown comparison history and manual runs retain full checks. Regression coverage includes source-to-document renames, whitespace failures, generated instructions preserving existing framework guidance, and earlier pnpm shims taking precedence over later native executables.
|
|
62
|
+
|
|
63
|
+
Local CLI and optional inspector builds passed with a 384 MB Node heap cap. All 16 targeted tests passed across CI scope, release-candidate policy, command execution, generated guidance, documentation contracts, plugin packaging/workflow and standard generation. Root lint (types, formatting, hygiene and release policy), static security policy, package allowlist (227 files, 607781 packed bytes) and `git diff --check` passed. The first plugin workflow check correctly rejected a stale runtime; rebuilding the inspector resolved it. Frozen inspector dependency installation changed no lockfiles. Build refreshed bundled references. Hosted CI, the full cross-platform/generated-app matrix, browser acceptance, current external advisory refresh, publication and installed-plugin updates were not performed in this focused pass.
|
|
64
|
+
|
|
5
65
|
## Release candidate 0.12.0 — 2026-10-16
|
|
6
66
|
|
|
7
67
|
This candidate combines the CLI/service refactor with optional Cloudflare Stream live video and consolidated documentation. Stream supplies a server-only management factory; billing activation, input ownership, broadcast/player UI, signed playback and live media acceptance remain explicit integration work. The README links into three maintained documents: the stack standard, software factory and this dated evidence record. Provider, CLI, dashboard, Void and codebase-review material is retained in those documents; packaging and plugin references use the same sources.
|
|
@@ -442,3 +502,56 @@ The listener and empty-cache failures are environment limitations, not proven ap
|
|
|
442
502
|
4. For an implemented product, verify protected business data, denied users, tenant isolation and any cross-app/native/extension identity flows. The scaffold's auth session smoke does not implement or certify those product behaviors.
|
|
443
503
|
|
|
444
504
|
No provider resources, publication, production deployment or source commit were performed during this review. Detailed local evidence and prior pass results are recorded in `docs/verification.md`.
|
|
505
|
+
|
|
506
|
+
|
|
507
|
+
## Progressive stack — local checkout, 2026-10-18
|
|
508
|
+
|
|
509
|
+
Plain initialization now selects Expo only. Capability dependencies resolve to a
|
|
510
|
+
fixed point; the compatible full-product preset includes Cloudflare AI, analytics,
|
|
511
|
+
media, realtime and jobs plus WXT, billing, email and monitoring. Existing edited
|
|
512
|
+
source and backend/delivery ownership remain protected. Legacy full-stack records
|
|
513
|
+
above describe earlier defaults and are retained as historical evidence.
|
|
514
|
+
|
|
515
|
+
Real generated `universal` (minimal) and `full-product` profiles passed dependency
|
|
516
|
+
installation and `pnpm check`, including lint, type checks, Fallow, dependency audit,
|
|
517
|
+
tests and builds. Full-product built Expo web, WXT, Hono and service Workers. These
|
|
518
|
+
were isolated temporary projects; no configured database was migrated or provider
|
|
519
|
+
resource deployed. The full-product check exposed unused helper dependencies and
|
|
520
|
+
duplicate transport code; shared server transport and lazy Hono adapters fixed the
|
|
521
|
+
actual findings without suppressing the generated checks.
|
|
522
|
+
|
|
523
|
+
Focused regressions exercise minimal selection, provider independence, preset
|
|
524
|
+
overrides, read-only previews, adding auth/billing without overwriting an edited
|
|
525
|
+
home screen, data added after service adapters, scoped media calls, private image
|
|
526
|
+
responses and redacted invalid provider JSON. The stack page's Mermaid diagram was
|
|
527
|
+
rendered locally. The six local plugin skills passed frontmatter/link validation.
|
|
528
|
+
|
|
529
|
+
Remaining acceptance: account/service activation and permissions, actual AI/event
|
|
530
|
+
receipt/image/video behavior, RealtimeKit calls, app room authorization, native
|
|
531
|
+
build/device/store flows and live payment reconciliation. No release, installation,
|
|
532
|
+
publication, production deployment or source commit was performed.
|
|
533
|
+
|
|
534
|
+
Final regression run: `pnpm test:unit` reported 750 tests, 748 passed, two skipped,
|
|
535
|
+
zero failures. `pnpm typecheck`, `pnpm format:check`, `pnpm check:hygiene`,
|
|
536
|
+
`pnpm check:security`, `pnpm check:release-policy`, CLI build and inspector/plugin
|
|
537
|
+
build passed. Additional growth coverage confirms direct billing additions retain
|
|
538
|
+
native RevenueCat key examples in the consuming app and preserve API-origin entries.
|
|
539
|
+
|
|
540
|
+
## 0.13.0 release preparation
|
|
541
|
+
|
|
542
|
+
The candidate changes plain init to a minimal Expo app, adds dependency-resolving
|
|
543
|
+
capabilities and a full-product preset, and packages six focused skills with shared
|
|
544
|
+
plugin-wide references. README and the concise stack page use the same progressive
|
|
545
|
+
diagram. Historical generated reference apps retain their original provenance.
|
|
546
|
+
|
|
547
|
+
Local `pnpm release:check` passed: lint/typecheck/format/hygiene/release policy,
|
|
548
|
+
static security policy, refreshed OSV audit, 748 passing tests (two skipped), exact
|
|
549
|
+
braces/node-forge patch regressions, packed CLI installation and package allowlist.
|
|
550
|
+
`pnpm plugin:check` passed, including 62 inspector tests. Release artifact creation,
|
|
551
|
+
hosted CI and publication are recorded separately after they actually complete.
|
|
552
|
+
|
|
553
|
+
### 2026-10-19 — release CI corrections and artifact reuse
|
|
554
|
+
|
|
555
|
+
- Hosted generated-profile checks exposed an unused web API-client stub in Clerk builds and Wrangler ready URLs without trailing slashes. Emit the web client/dependency only for its Better Auth consumer; normalize both Vite and Wrangler loopback URLs. Both Clerk profiles subsequently passed real local generation, check, build and Worker preview. Universal auth and billing reference previews passed with the corrected readiness parser.
|
|
556
|
+
- Provider-call assertions in billing fixtures now compare exact hostnames, addressing CodeQL substring findings without changing provider transport.
|
|
557
|
+
- Publication consumes the immutable candidate from successful trusted main CI for the exact reviewed SHA instead of reinstalling and rebuilding it. CLI/plugin integrity pins, secret scan, package smoke, cross-platform artifact checks, protected npm environment and OIDC publication remain required. Negative policy checks reject staging, PR-run or unpinned candidate selection.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "anhedral",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.13.0",
|
|
4
|
+
"description": "Start with a minimal Expo app and progressively add Hono, identity, data and Cloudflare services.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
7
7
|
".": {
|
|
@@ -25,7 +25,8 @@
|
|
|
25
25
|
"README.md",
|
|
26
26
|
"docs/stack-standard.md",
|
|
27
27
|
"docs/software-factory.md",
|
|
28
|
-
"docs/verification.md"
|
|
28
|
+
"docs/verification.md",
|
|
29
|
+
"docs/anhedral-stack.md"
|
|
29
30
|
],
|
|
30
31
|
"homepage": "https://github.com/anhedral/anhedral-cli#readme",
|
|
31
32
|
"repository": {
|
|
@@ -80,7 +81,9 @@
|
|
|
80
81
|
"plugin:build": "pnpm --dir plugins/codex/inspector build",
|
|
81
82
|
"plugin:check": "pnpm --dir plugins/codex/inspector check",
|
|
82
83
|
"plugin:preview": "pnpm --dir plugins/codex/inspector start",
|
|
83
|
-
"test:patch": "node tests/test-braces-install.mjs && node tests/test-forge-install.mjs"
|
|
84
|
+
"test:patch": "node tests/test-braces-install.mjs && node tests/test-forge-install.mjs",
|
|
85
|
+
"test:reference": "node tests/test-universal-reference.mjs",
|
|
86
|
+
"test:billing": "node tests/test-generated-billing.mjs examples/billing-reference"
|
|
84
87
|
},
|
|
85
88
|
"keywords": [
|
|
86
89
|
"cli",
|