anhedral 0.11.0 → 0.11.2
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 +50 -170
- package/assets/patches/LICENSE.braces +21 -0
- package/assets/patches/LICENSE.node-forge +50 -0
- package/assets/patches/audit-deps.mjs +167 -0
- package/assets/patches/braces@3.0.3.patch +127 -0
- package/assets/patches/node-forge@1.4.0.patch +41 -0
- package/dist/auth-schema.js +3 -3
- package/dist/bin.js +15 -11
- package/dist/capabilities.d.ts +4 -4
- package/dist/capabilities.js +6 -2
- package/dist/capability-contract.js +22 -5
- package/dist/catalog-model.d.ts +24 -0
- package/dist/catalog-model.js +1 -0
- package/dist/catalog-registration.d.ts +16 -0
- package/dist/catalog-registration.js +22 -0
- package/dist/catalog-snapshot.d.ts +5 -0
- package/dist/catalog-snapshot.js +97 -0
- package/dist/cli-arguments.js +1 -1
- package/dist/cli-output.js +27 -2
- package/dist/cloudflare.d.ts +7 -1
- package/dist/cloudflare.js +36 -6
- package/dist/command-schema.js +49 -5
- package/dist/delivery.d.ts +10 -3
- package/dist/delivery.js +154 -37
- package/dist/dependencies.d.ts +24 -0
- package/dist/dependencies.js +48 -0
- package/dist/dependency-patches.d.ts +7 -0
- package/dist/dependency-patches.js +125 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +2 -0
- package/dist/inspector-model.d.ts +9 -1
- package/dist/integration-service-readers.d.ts +13 -0
- package/dist/integration-service-readers.js +173 -0
- package/dist/lifecycle.d.ts +0 -1
- package/dist/lifecycle.js +0 -1
- package/dist/neon-service-data.d.ts +8 -0
- package/dist/neon-service-data.js +117 -0
- package/dist/pnpm-policy.d.ts +2 -2
- package/dist/pnpm-policy.js +19 -45
- package/dist/project-catalog.d.ts +41 -0
- package/dist/project-catalog.js +288 -0
- package/dist/project-config.d.ts +14 -0
- package/dist/project-config.js +89 -0
- package/dist/project-inspector.js +73 -17
- package/dist/project-lifecycle.d.ts +25 -0
- package/dist/project-lifecycle.js +57 -0
- package/dist/project-state.d.ts +5 -1
- package/dist/project-state.js +122 -16
- package/dist/provider-auth.js +2 -3
- package/dist/provider-readiness.js +27 -10
- package/dist/providers/adapters.js +4 -1
- package/dist/providers/api.d.ts +1 -0
- package/dist/providers/api.js +1 -0
- package/dist/providers/config.js +6 -8
- package/dist/providers/provision.js +1 -1
- package/dist/providers/recovery.d.ts +1 -1
- package/dist/providers/runtime.d.ts +1 -1
- package/dist/providers/runtime.js +46 -23
- package/dist/providers/state.d.ts +1 -2
- package/dist/providers/state.js +14 -54
- package/dist/provision.d.ts +9 -0
- package/dist/provision.js +30 -1
- package/dist/r2-service-data.d.ts +2 -0
- package/dist/r2-service-data.js +136 -0
- package/dist/readiness.js +9 -13
- package/dist/registry/add.js +64 -21
- package/dist/registry/commands.js +7 -9
- package/dist/registry/options.d.ts +1 -1
- package/dist/registry/options.js +4 -4
- package/dist/registry/receipt.d.ts +1 -0
- package/dist/registry/receipt.js +19 -4
- package/dist/registry/resolve.js +5 -1
- package/dist/registry/usage.js +1 -5
- package/dist/render.d.ts +2 -0
- package/dist/render.js +6 -0
- package/dist/runtime-policy.d.ts +4 -0
- package/dist/runtime-policy.js +21 -0
- package/dist/scaffold/bootstrap.js +2 -2
- package/dist/scaffold/compose.js +9 -3
- package/dist/scaffold/database.js +107 -25
- package/dist/scaffold/documentation.js +18 -13
- package/dist/scaffold/lint.d.ts +4 -0
- package/dist/scaffold/lint.js +56 -0
- package/dist/scaffold/neon-realtime.d.ts +2 -0
- package/dist/scaffold/neon-realtime.js +97 -0
- package/dist/scaffold/stack-documentation.js +1 -1
- package/dist/scaffold/void.d.ts +4 -0
- package/dist/scaffold/void.js +256 -0
- package/dist/scaffold/web.js +7 -1
- package/dist/scaffold/workspace.js +120 -29
- package/dist/service-deletion.d.ts +29 -0
- package/dist/service-deletion.js +195 -0
- package/dist/service-descriptor.d.ts +10 -0
- package/dist/service-descriptor.js +78 -0
- package/dist/service-model.d.ts +49 -0
- package/dist/service-model.js +8 -0
- package/dist/service-operations.d.ts +29 -0
- package/dist/service-operations.js +78 -0
- package/dist/service-readers.d.ts +8 -0
- package/dist/service-readers.js +247 -0
- package/dist/services-command.d.ts +39 -0
- package/dist/services-command.js +100 -0
- package/dist/ship.d.ts +36 -8
- package/dist/ship.js +39 -13
- package/dist/stack-registry.d.ts +4 -2
- package/dist/stack-registry.js +41 -11
- package/dist/standard.js +23 -4
- package/dist/transaction.d.ts +2 -0
- package/dist/transaction.js +10 -0
- package/dist/util.js +17 -2
- package/dist/vercel.d.ts +2 -0
- package/dist/vercel.js +69 -13
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/vinext.d.ts +1 -0
- package/dist/vinext.js +13 -1
- package/dist/void-execution.d.ts +10 -0
- package/dist/void-execution.js +94 -0
- package/dist/void-migrations.d.ts +6 -0
- package/dist/void-migrations.js +110 -0
- package/dist/void-state.d.ts +16 -0
- package/dist/void-state.js +65 -0
- package/dist/void.d.ts +3 -0
- package/dist/void.js +5 -0
- package/docs/cli-design.md +2 -2
- package/docs/plugin-ui.md +51 -10
- package/docs/provider-configuration.md +10 -11
- package/docs/software-factory.md +192 -0
- package/docs/stack-standard.md +142 -0
- package/docs/void-verification.md +185 -0
- package/package.json +23 -21
- package/assets/anhedral-mark.svg +0 -4
- package/assets/anhedral-stack-technical.svg +0 -322
- package/assets/anhedral-stack.svg +0 -322
- package/assets/anhedral.svg +0 -4
- package/assets/favicon.ico +0 -0
- package/assets/security/LICENSES.txt +0 -63
- package/assets/security/audit-deps.mjs +0 -300
- package/assets/security/braces-regression.mjs +0 -102
- package/assets/security/braces@3.0.3.patch +0 -285
- package/assets/security/decode-uri-component@0.2.2.patch +0 -149
- package/assets/security/decoder-regression.mjs +0 -37
- package/assets/security/forge-regression.mjs +0 -46
- package/assets/security/manifest.json +0 -53
- package/assets/security/node-forge@1.4.0.patch +0 -26
- package/dist/security-backports.d.ts +0 -3
- package/dist/security-backports.js +0 -26
- package/docs/application-stack-standard.md +0 -75
- package/docs/delivery-workflow.md +0 -97
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# Software factory
|
|
2
|
+
|
|
3
|
+
Use this workflow to turn a product brief into an application that works, runs in the owner's accounts and can be maintained. The [stack standard](stack-standard.md) defines the architecture. This guide defines the work and the evidence needed to move it forward.
|
|
4
|
+
|
|
5
|
+
A developer or coding agent owns product implementation. The CLI supplies repeatable scaffolding, selected provider setup, delivery operations and recorded evidence. The owner supplies product decisions, account access and any required spending or release authorization. Source, repositories, infrastructure, data and billing stay owner-controlled.
|
|
6
|
+
|
|
7
|
+
## 1. Define a small, testable product
|
|
8
|
+
|
|
9
|
+
Write the intended users, core flows, data, access boundaries and observable acceptance criteria in the application's `docs/architecture.md`. Include the selected components, actual connections, environment assumptions, cost limits and tradeoffs. Preserve suitable existing code and use the same project for later changes.
|
|
10
|
+
|
|
11
|
+
For a booking app, “a member can create a booking, see it after reload, and cannot read another member's booking” is an acceptance criterion. “Use auth and a database” is a stack choice. Plan both, then implement a vertical slice that exercises the real UI, server and persistence together.
|
|
12
|
+
|
|
13
|
+
Choose only the necessary catalog components. Decide whether the app is public or private, whether several clients share an API, and who owns production operations. Resolve decisions that materially affect architecture, access or cost before creating resources.
|
|
14
|
+
|
|
15
|
+
**Ready to generate:** the core flow, stack selection, owner and acceptance criteria are clear.
|
|
16
|
+
|
|
17
|
+
## 2. Generate and inspect the foundation
|
|
18
|
+
|
|
19
|
+
Use Node.js `24.21.0+` and pnpm `10.34.5` for the default stack. Match the installed CLI version to the plugin's bundled registry `cliVersion` when using Codex. Pin that version for repeatable automation. For unpublished checkout work, run `pnpm build` and use `node dist/bin.js`; building does not update installed releases.
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
anhedral init my-app --vinext --hono --d1 --better-auth --r2 --dry-run --json
|
|
23
|
+
anhedral init my-app --vinext --hono --d1 --better-auth --r2
|
|
24
|
+
cd my-app
|
|
25
|
+
pnpm dev
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Use an unused directory. `init --dry-run` performs no writes or network requests. Actual initialization downloads the upstream bootstrap, generates source and normally installs dependencies and initializes Git; it does not create cloud resources or deploy. `--skip-install` skips the final install, but the upstream bootstrap still needs network access.
|
|
29
|
+
|
|
30
|
+
Review the generated README, `AGENTS.md`, `docs/stack.md`, root `anhedral.json` and lockfile. The setup section records remaining requirements. Keep secrets in the selected runtime's private files, following its templates.
|
|
31
|
+
|
|
32
|
+
For later capabilities, preview before applying:
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
anhedral add resend --dry-run --json
|
|
36
|
+
anhedral add resend --diff
|
|
37
|
+
anhedral add resend
|
|
38
|
+
anhedral doctor --json
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Additions use the bundled catalog and preserve edited source. Resolve conflicts deliberately. A selection plan marked `filesChecked: false` has not previewed files that require a new upstream web bootstrap. Add does not perform runtime relocation or switch the Cloudflare engine.
|
|
42
|
+
|
|
43
|
+
**Ready to implement:** the workspace starts, the selected packages have clear consumers, and remaining setup is understood.
|
|
44
|
+
|
|
45
|
+
## 3. Implement the product and integrations
|
|
46
|
+
|
|
47
|
+
Build the acceptance flows with real persistence, validation and server-side authorization. Include loading, empty and failure states. Exercise denied access and cross-user/tenant isolation, not just the successful path. Keep shared contracts in packages and privileged code on servers.
|
|
48
|
+
|
|
49
|
+
Generate SQL with `pnpm db:generate`, review it, then apply it to the intended development database with `pnpm db:migrate`. Migration tasks are separate from build/startup. Production migrations need a reviewed apply plan and data compatibility assessment. The stack standard explains D1 ownership and separate Neon migration credentials.
|
|
50
|
+
|
|
51
|
+
Configure the selected integrations in the `providers` section of `anhedral.json`. Supply management keys through the process environment; runtime secrets stay private. Use existing scoped resources where appropriate. The [provider configuration reference](provider-configuration.md) lists supported automation, exact fields, credentials and owner prerequisites.
|
|
52
|
+
|
|
53
|
+
Domain verification, OAuth consent, billing enrollment, store signing and product-specific webhook/purchase behavior may require separate work. Neon Realtime additionally needs manual branch activation/origins and authenticated scoped sealing/subscription flows. Installed SDKs and obtained credentials do not establish that these features work.
|
|
54
|
+
|
|
55
|
+
**Ready to validate:** each core flow uses its intended implementation and remaining external dependencies are explicit.
|
|
56
|
+
|
|
57
|
+
## 4. Check the actual application
|
|
58
|
+
|
|
59
|
+
From the generated project root:
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
pnpm check
|
|
63
|
+
anhedral doctor --json
|
|
64
|
+
anhedral inspect --json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`pnpm check` runs lint, types, Fallow analysis, dependency audit, tests and builds; the explicit OpenNext profile also builds its Worker output. Add meaningful product tests as you implement features. `doctor` checks local readiness and provenance. `inspect` reads local selection, setup and recorded delivery evidence offline; neither certifies live product behavior.
|
|
68
|
+
|
|
69
|
+
Exercise the actual runtime as well as compilation: Vinext/Vite workerd preview, OpenNext Worker preview, or native Next.js as selected. For mobile, desktop and extensions, check relevant device/packaged behavior and permissions. Verify retry, webhook duplication, private files, AI limits and recovery for the services you selected.
|
|
70
|
+
|
|
71
|
+
Record commands, results and gaps in the application's `docs/verification.md`. Distinguish local, preview and live results. A smoke check or HTTP 200 establishes availability of that route, not completion of the product.
|
|
72
|
+
|
|
73
|
+
**Ready to deliver:** checks pass and core flows have credible runtime evidence.
|
|
74
|
+
|
|
75
|
+
## 5. Establish source, access and delivery authority
|
|
76
|
+
|
|
77
|
+
Verify the owner's Git identity and repository destination. Review source and secret ignores, then commit the application and configuration in its own repository. Generation does not create a source commit for you. Never commit private runtime files or `.anhedral/`.
|
|
78
|
+
|
|
79
|
+
```sh
|
|
80
|
+
anhedral auth --status --json
|
|
81
|
+
anhedral auth
|
|
82
|
+
anhedral doctor --providers --json
|
|
83
|
+
anhedral repository --create --json
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`auth` can guide Cloudflare, Vercel and Expo login; API integrations use supplied environment credentials. `--status`, JSON and noninteractive modes never open login prompts. Authentication is separate from selecting a resource/account and proving every write permission.
|
|
87
|
+
|
|
88
|
+
`repository --create` creates a private GitHub repository under the selected account when necessary, pushes the intended source and verifies the exact remote identity/commit. Use explicit owner/name/visibility flags for a different authorized destination. Reuse matching origins; preserve existing remotes and visibility. Connecting Git to a host can trigger deployments, so check release authorization and policy first.
|
|
89
|
+
|
|
90
|
+
Connect the intended hosting account and audience, then review and commit the resulting configuration:
|
|
91
|
+
|
|
92
|
+
| Target | Example |
|
|
93
|
+
| ------------------------------ | ------------------------------------------------------------------------------------- |
|
|
94
|
+
| Private Cloudflare app | `anhedral connect --audience private --allow-email owner@example.com` |
|
|
95
|
+
| Intended public Cloudflare app | `anhedral connect --audience public` |
|
|
96
|
+
| Private Vercel app | `anhedral connect --scope customer-team --audience private --use commercial --create` |
|
|
97
|
+
|
|
98
|
+
Replace all example account/member values. Select `--account` for Cloudflare when needed, and `--provider cloudflare` or `--provider vercel` to disambiguate mixed projects. Private Cloudflare hosting requires Zero Trust and scoped Access permissions. Whole-Worker Access does not protect WebSockets; private realtime needs a separately reviewed identity/hostname design. Vercel private hosting requires verified all-deployment protection. Hosting access is separate from product identity and authorization.
|
|
99
|
+
|
|
100
|
+
Vercel Hobby is personal/non-commercial; use `--use personal` only for eligible personal use. Commercial apps need an eligible existing plan. Do not activate paid plans, broaden audience or weaken protection to clear a blocker.
|
|
101
|
+
|
|
102
|
+
**Ready to ship:** source is committed, account/audience are selected, and permissions and release authority cover the intended operations.
|
|
103
|
+
|
|
104
|
+
## 6. Deliver one reviewed change
|
|
105
|
+
|
|
106
|
+
Choose one path for each change: CLI delivery, or connected Vercel Git delivery. Configure branch protection and required CI explicitly; a connected host does not automatically wait for GitHub Actions.
|
|
107
|
+
|
|
108
|
+
### CLI delivery
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
anhedral ship --dry-run --json
|
|
112
|
+
anhedral ship --json
|
|
113
|
+
anhedral status --refresh --json
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
The dry run previews setup and delivery without provider operations. Actual `ship` coordinates supported integration setup, private runtime configuration, checks and hosting delivery. In mixed projects it handles Cloudflare services before the Vercel web app; provider flags select one target explicitly.
|
|
117
|
+
|
|
118
|
+
For supported Cloudflare selections, Void owns provisioning and deployment. `provision` reports the plan and defers writes to Void. Explicit OpenNext, Queues/DLQ and Basin use Wrangler; standalone `provision` reconciles Cloudflare resources only. The integration adapters and their limits are documented in the provider reference.
|
|
119
|
+
|
|
120
|
+
**Treat `configuration-required` as a checkpoint.** Wrangler can stop before deployment when resolved resource IDs change tracked bindings. Void can activate a target before recording new resource identities in `void.lock.json`; Anhedral retains activation receipts and then requires review and a commit. Inspect those results, commit the expected changes, and ship the clean configuration again. Do not assume a nonzero result means nothing happened. Anhedral never commits source automatically. Multiple Workers are not an atomic release.
|
|
121
|
+
|
|
122
|
+
Void apps use `env.example` and one private app-root `.env`. Production secrets travel through noninteractive stdin; public build variables must be present when building client bundles. Follow generated templates and the provider reference rather than adding unsupported environment files. Generate/review shared SQL first; exactly one server owns deployment migrations.
|
|
123
|
+
|
|
124
|
+
Anhedral independently checks active provider versions, traffic, account and audience against retained receipts. A process exit code or deployment log alone is insufficient. See [Void verification](void-verification.md) for the pinned receipt contract and outstanding live acceptance gates.
|
|
125
|
+
|
|
126
|
+
### Connected Vercel Git delivery
|
|
127
|
+
|
|
128
|
+
After committing source and establishing the verified repository, add `--git` to the Vercel `connect` command. Then:
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
pnpm check
|
|
132
|
+
anhedral repository --json
|
|
133
|
+
# Wait for the connected production deployment of this exact commit.
|
|
134
|
+
anhedral adopt --json
|
|
135
|
+
anhedral status --refresh --json
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`repository` pushes source; the host's Git integration deploys it. `adopt` verifies the active production source/repository and records the release without another push or deployment. Do not also run `ship` for that same change.
|
|
139
|
+
|
|
140
|
+
### Native delivery
|
|
141
|
+
|
|
142
|
+
For Expo, set explicit owner/slug in static `apps/mobile/app.json`, configure the selected EAS profile and run:
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
anhedral ship --platform android --profile preview --json
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Use `--platform ios` for iOS. Project creation/linking requires review and a commit before a build continues. A queued result returns the EAS build-page link; repeat the command to inspect that build rather than submitting another. A completed artifact must match the selected project/source. Store submission is separate. Simulator builds are not TestFlight artifacts; signed iOS builds require owner credentials. Electron/extension packaging and store distribution use their actual platform workflows.
|
|
149
|
+
|
|
150
|
+
**Ready for live acceptance:** the actual URL or artifact, exact source and provider identity are confirmed.
|
|
151
|
+
|
|
152
|
+
## 7. Verify and hand over
|
|
153
|
+
|
|
154
|
+
Open the actual deployed URL or install the confirmed artifact. Exercise the original acceptance criteria with real intended users and integrations. For private hosting, check anonymous rejection at primary and deployment URLs, allowed-user sign-in and denied users. Verify product authorization and cross-tenant access separately. Provider-authenticated automation does not prove visitor login.
|
|
155
|
+
|
|
156
|
+
Implement a meaningful root `test:live` script and run:
|
|
157
|
+
|
|
158
|
+
```sh
|
|
159
|
+
anhedral verify --json
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`verify` supplies the actual `ANHEDRAL_APP_URL` and checks source/provider provenance. Use the test to exercise the product's meaningful live assertions; a placeholder success script proves nothing. If access or an integration is blocked, retain the completed work and identify the exact unverified flow.
|
|
163
|
+
|
|
164
|
+
Keep the application's verification record current:
|
|
165
|
+
|
|
166
|
+
| Record | Include |
|
|
167
|
+
| ------------------ | -------------------------------------------------------------------------------- |
|
|
168
|
+
| Source | Repository, branch, exact commit, CLI/plugin versions |
|
|
169
|
+
| Hosting | Owner account/project, audience, active release, actual URL/artifact |
|
|
170
|
+
| Product evidence | Commands and observed results for each core flow; local/preview/live distinction |
|
|
171
|
+
| Integration status | Configured and exercised services, pending owner setup and acceptance gaps |
|
|
172
|
+
| Operations | Alert owner, usage limits, recovery procedure and next actions |
|
|
173
|
+
|
|
174
|
+
Do not include credentials. Successful delivery includes maintainable source, reproducible verification and a clear operating handoff. A later production change can make earlier acceptance evidence stale.
|
|
175
|
+
|
|
176
|
+
## 8. Maintain and recover
|
|
177
|
+
|
|
178
|
+
| Need | Command and boundary |
|
|
179
|
+
| --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
180
|
+
| Refresh deployments | `status --refresh --json` checks current provider evidence |
|
|
181
|
+
| Open a management overview | `manage --json`; `--local` explicitly uses historical local evidence |
|
|
182
|
+
| Inspect services on demand | `services list --json`, then supported status/metrics/data commands; reads can expose private data |
|
|
183
|
+
| Recover after cloning | `recover --json` reconstructs independently verified current hosting state, not missing history or credentials |
|
|
184
|
+
| Inspect interrupted integrations | `integrations status --json`; recover only the verified pending operation/resource |
|
|
185
|
+
| Release an interrupted local lock | `recover --lock` only removes a proven dead same-host delivery lock; inspect receipts first |
|
|
186
|
+
| Restore recorded code | `rollback --release <id> --data-compatible` after schema/resource compatibility review |
|
|
187
|
+
|
|
188
|
+
Rollback does not restore data, reverse SQL or cross incompatible Durable Object migration boundaries. Void rollback only restores covered code/triggers; review retained evidence. Restore matching clean source before verifying the result. Back up data and test restoration independently.
|
|
189
|
+
|
|
190
|
+
Keep alerts, dependency updates, quotas, retry/concurrency limits and shutdown controls owned and exercised. Ignored local receipts are not a durable historical backup. Live/foreign/uncertain locks are preserved; a leftover `.anhedral/ship.guard` needs manual ownership inspection. Lock recovery cannot be combined with provider/refresh flags and never replays provider writes.
|
|
191
|
+
|
|
192
|
+
Use `anhedral help <command>` for exact options. See [provider configuration](provider-configuration.md) for integration setup/retries and [CLI behavior](https://github.com/anhedral/anhedral-cli/blob/main/docs/cli-design.md) for machine output and previews. The optional [Codex inspector](plugin-ui.md) uses the same project logic; it does not replace runtime or product acceptance.
|
|
@@ -0,0 +1,142 @@
|
|
|
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
|
+
## Select the applications
|
|
8
|
+
|
|
9
|
+
| Need | Selection | Architecture |
|
|
10
|
+
| ------------------------------ | ----------------------------- | ---------------------------------------------------------- |
|
|
11
|
+
| Web on Workers | Default, or `--vinext` | Vinext routing and rendering, React UI, Cloudflare runtime |
|
|
12
|
+
| Native Next.js on Vercel | `--next` | Next.js server code and Vercel hosting |
|
|
13
|
+
| Next.js on Workers | `--next --hosting=cloudflare` | OpenNext adapter and Wrangler delivery |
|
|
14
|
+
| API shared by multiple clients | `--hono` | Hono Worker with OpenAPI contracts |
|
|
15
|
+
| iOS and Android | `--expo` | Expo, React Native Reusables and NativeWind |
|
|
16
|
+
| Desktop | `--electron` | Electron and React; platform packaging and signing |
|
|
17
|
+
| Browser extension | `--wxt` | WXT and React popup/Chrome side panel |
|
|
18
|
+
|
|
19
|
+
For example, `--vinext --hono --expo --neon` selects web, an API, mobile and PostgreSQL. `--expo` alone selects mobile. Explicit product flags replace the default selection; required dependencies are resolved automatically. Vinext and Next.js are alternatives. Native Next.js defaults to Vercel; Vinext uses Workers.
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
## Select data, identity and services
|
|
24
|
+
|
|
25
|
+
| Need | Selection | Rule |
|
|
26
|
+
| ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------ |
|
|
27
|
+
| SQL on Workers | `--d1` | Drizzle with D1 bindings; one deployment migration owner |
|
|
28
|
+
| PostgreSQL | `--neon` | Drizzle with Neon serverless HTTP; separate transactional migration connection |
|
|
29
|
+
| Application identity | `--better-auth` or `--clerk` | Choose one; implement product/resource authorization on the server |
|
|
30
|
+
| Private files | `--r2` | Authorize operations through server bindings |
|
|
31
|
+
| Cache and configuration | `--kv` | Eventually consistent; do not use as transactional authority |
|
|
32
|
+
| WebSocket rooms | `--realtime` | Cloudflare Durable Objects; define identity and reconnect behavior |
|
|
33
|
+
| Live SQL results | `--neon-realtime` | Neon sealed-query server/client factories; see below |
|
|
34
|
+
| Background work | `--queues`, `--cron`, `--workflows` | Define idempotency, retry limits, concurrency and failure recovery |
|
|
35
|
+
| Inference | `--workers-ai`, `--openai`, `--ai-sdk` | Server-side calls with explicit model, cost and usage limits |
|
|
36
|
+
| Transactional email | `--resend` | Verified sending domain, templates and delivery handling |
|
|
37
|
+
| Billing | `--stripe`, `--revenuecat` | Application-specific products, entitlements and verified webhooks/purchases |
|
|
38
|
+
| Errors and analytics | `--sentry`, `--posthog`, `--basin` | Initialize SDKs/events and define privacy and operating ownership |
|
|
39
|
+
| Device-local data and shared styling | `--local-data`, `--styling` | Select for supported client requirements |
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
The bundled registry is authoritative for exact dependencies, destinations and compatibility:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
anhedral registry list --json
|
|
47
|
+
anhedral registry view better-auth --json
|
|
48
|
+
anhedral init my-app --vinext --hono --d1 --better-auth --r2 --dry-run --json
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The resolver rejects conflicting databases/frameworks/identity providers and capabilities without a compatible server. 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.
|
|
52
|
+
|
|
53
|
+
## Organize the source
|
|
54
|
+
|
|
55
|
+
| Location | Owns |
|
|
56
|
+
| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
|
|
57
|
+
| `apps/web`, `apps/api`, other selected `apps/*` | Deployable applications and services, runtime entry points and configuration |
|
|
58
|
+
| `packages/ui` | Shared web UI components |
|
|
59
|
+
| `packages/db` | Server-only database factory, schemas and migrations |
|
|
60
|
+
| `packages/auth`, other selected `packages/*` | Reusable integration code with explicit inputs |
|
|
61
|
+
| `packages/typescript-config`, `packages/eslint-config` | Shared tooling conventions |
|
|
62
|
+
| `anhedral.json` | Committed Anhedral configuration and provenance |
|
|
63
|
+
| `docs/stack.md` | Generated selection, destinations and setup requirements |
|
|
64
|
+
| `.anhedral/` | Ignored local delivery journals and private state |
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
### One Anhedral configuration
|
|
71
|
+
|
|
72
|
+
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.
|
|
73
|
+
|
|
74
|
+
| Section | Purpose |
|
|
75
|
+
| ------------ | --------------------------------------------------------------------- |
|
|
76
|
+
| `identity` | Stable application identity and local catalog registration |
|
|
77
|
+
| `setup` | Products, hosting, environment requirements and owner setup |
|
|
78
|
+
| `standard` | Scaffold conventions and version provenance |
|
|
79
|
+
| `registry` | Recipe versions, generated-file fingerprints and workspace references |
|
|
80
|
+
| `providers` | Nonsecret integration settings and resource selections |
|
|
81
|
+
| `cloudflare` | Delivery engine, account, audience and targets |
|
|
82
|
+
| `vercel` | Repository, team, project and audience |
|
|
83
|
+
|
|
84
|
+
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.
|
|
85
|
+
|
|
86
|
+
## Data and migrations
|
|
87
|
+
|
|
88
|
+
All database-backed selections use the server-only `@workspace/db` package:
|
|
89
|
+
|
|
90
|
+
| Path | Responsibility |
|
|
91
|
+
| ------------------------------- | ----------------------------------------------------- |
|
|
92
|
+
| `packages/db/src/index.ts` | Factory receiving a D1 binding or connection string |
|
|
93
|
+
| `packages/db/src/schema.ts` | Shared Drizzle schema, including selected auth tables |
|
|
94
|
+
| `packages/db/src/migrate.ts` | Explicit migration entry point |
|
|
95
|
+
| `packages/db/drizzle/` | SQL, snapshots and migration journal |
|
|
96
|
+
| `packages/db/drizzle.config.ts` | Configuration with paths relative to itself |
|
|
97
|
+
|
|
98
|
+
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.
|
|
99
|
+
|
|
100
|
+
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.
|
|
101
|
+
|
|
102
|
+
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.
|
|
103
|
+
|
|
104
|
+
## Neon Realtime
|
|
105
|
+
|
|
106
|
+
`--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.
|
|
107
|
+
|
|
108
|
+
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.
|
|
109
|
+
|
|
110
|
+
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.
|
|
111
|
+
|
|
112
|
+
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.
|
|
113
|
+
|
|
114
|
+
## Runtime and delivery configuration
|
|
115
|
+
|
|
116
|
+
| Profile | Engine and configuration | Project runtime floor |
|
|
117
|
+
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
|
|
118
|
+
| 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+` |
|
|
119
|
+
| Explicit OpenNext, Queues/DLQ or Basin | Wrangler; app-local `wrangler.jsonc` | Node.js `22.13+` on 22.x, or `24+` |
|
|
120
|
+
| Native Next.js/Vercel and other non-Void profiles | Native framework/platform tools | Node.js `22.13+` on 22.x, or `24+` |
|
|
121
|
+
|
|
122
|
+
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.
|
|
123
|
+
|
|
124
|
+
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.
|
|
125
|
+
|
|
126
|
+
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](provider-configuration.md) describes credential transport and each integration's prerequisites.
|
|
127
|
+
|
|
128
|
+
## Source ownership and dependency policy
|
|
129
|
+
|
|
130
|
+
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.
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
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.
|
|
135
|
+
|
|
136
|
+
Validate the resolved dependency graph for each application selection. A clean CLI dependency graph does not establish a clean generated application graph.
|
|
137
|
+
|
|
138
|
+
## Product requirements
|
|
139
|
+
|
|
140
|
+
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.
|
|
141
|
+
|
|
142
|
+
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](void-verification.md) and the application's own verification record, rather than in this architecture standard.
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
# Void delivery verification
|
|
2
|
+
|
|
3
|
+
This records the implementation's evidence and remaining acceptance work. It is not a release certificate. Update the live results when an operation completes; retain sanitized target/version identifiers and actual acceptance results rather than diagnostic output.
|
|
4
|
+
|
|
5
|
+
## Version contract
|
|
6
|
+
|
|
7
|
+
- Anhedral development checkout: `anhedral@0.11.1`.
|
|
8
|
+
- Direct Cloudflare delivery: exact `void@0.27.0`.
|
|
9
|
+
- Void runtime requirement: Node `>=24.21.0` (checked before execution).
|
|
10
|
+
- Workspace package manager: `pnpm@10.34.5`.
|
|
11
|
+
- The published Void package distribution and its bundled documentation were inspected. Installed executable version and app dependency pin must agree.
|
|
12
|
+
|
|
13
|
+
Current Cloudflare configuration requires an explicit `deliveryEngine` in the `cloudflare` section of `anhedral.json`. Supported Void profiles select `void`; explicit OpenNext, Queues/DLQ and Basin profiles select `wrangler`. Missing or unsupported markers are rejected. No existing-project migration workflow is provided.
|
|
14
|
+
|
|
15
|
+
## Historical local evidence: initial Void integration
|
|
16
|
+
|
|
17
|
+
These results describe the earlier integration snapshot. They do not certify the current uncommitted candidate; subsequent local reviews are recorded in the repository’s `docs/verification.md` and `docs/codebase-review.md`.
|
|
18
|
+
|
|
19
|
+
The initial Void/coherence local CLI suite passed **608 of 608 tests**, with zero failures. The inspector suite passed **60 of 60 tests**. Build, typecheck, formatting, source hygiene, static security policy, packed CLI smoke and package allowlist checks passed. The corrected OSV audit passed for **85 unique locked and direct-catalog package versions**; the inspector dependency audit also reported no known vulnerabilities. This does not audit every generated application’s transitive dependency graph.
|
|
20
|
+
|
|
21
|
+
The normal generated combined workspace installed **395 packages** without extra harness dependency pins. Actual fresh builds passed for **Vinext 1.1.0 with Void 0.27.0** and **Hono**. Workerd returned HTTP 200 for rendered HTML, its client asset, API health and OpenAPI. A separate services profile covered D1/R2/KV/AI plus cron build/preview gates; the compiled scheduled handler was preserved and invoked successfully. Readiness responses contained an actual Worker version UUID.
|
|
22
|
+
|
|
23
|
+
Wrangler applied the generated local D1 migration `0000_better_auth` (10 commands). The shared Better Auth/D1 runtime passed signup, login, cookie/session lookup, incorrect-password HTTP 401, logout and session revocation through `tests/test-void-local-auth.mjs`. These are actual local runtime checks rather than mocked provider tests. They do not prove Cloudflare provisioning, production secrets, visitor Access policy enforcement or remote rollback.
|
|
24
|
+
|
|
25
|
+
The earlier generated dependency audit passed with a local `braces` backport and `fflate@0.7.5`; its raw advisory report still contained one high finding. The bundled backport system has since been removed at the owner’s request. A subsequent owner-approved change adds one narrowly scoped standard pnpm patch for `braces@3.0.3`, while retaining the upstream pnpm audit report and all advisory findings. The owner subsequently approved a verification gate for the one exact patched advisory, described below. The earlier backport audit gate remains removed; its result does not establish a passing audit for newly generated applications.
|
|
26
|
+
|
|
27
|
+
Additional regression coverage includes non-object JSONL records, canonical configuration/lock merging, and resolved bindings with authored placeholders. The final integrated count above includes this regression coverage.
|
|
28
|
+
|
|
29
|
+
The automated checks cover the pinned JSONL receipt format, rejection of stale/foreign/incomplete/ambiguous receipts, independent provider version confirmation, source cleanliness, explicit current engine validation, private policy reconciliation, and the lock-review checkpoint. Mocked Cloudflare responses establish control flow; they do not establish provider/runtime compatibility.
|
|
30
|
+
|
|
31
|
+
## Deployment evidence contract
|
|
32
|
+
|
|
33
|
+
Void 0.27.0 writes a new `~/.void/logs/deploy-*.jsonl` per invocation. Anhedral requires exactly one new matching log with:
|
|
34
|
+
|
|
35
|
+
1. A `deploy_start` record identifying the exact target working directory and a timestamp after invocation began.
|
|
36
|
+
2. One `cloudflare_deploy_end` record with `ok: true`, the expected Worker name and a complete version ID.
|
|
37
|
+
3. A final `deploy_end` record with `ok: true`.
|
|
38
|
+
|
|
39
|
+
This contract was inspected in the published distribution, rather than inferred from console prose. The recorded version must independently own 100% of current Cloudflare traffic. Application source and configuration are checked before and after deployment. Void's direct Cloudflare log does not contain a Git commit annotation; Anhedral correlates the checked invocation and its receipt with the clean source commit. Missing or ambiguous logs stop acceptance even when provider changes may have occurred.
|
|
40
|
+
|
|
41
|
+
Application URLs require provider evidence: enabled Workers subdomain plus account subdomain, or a matching custom-domain assignment. Private Access policies are checked before and after activation. Selected resource identities and private R2 exposure are independently inspected after Void resolves resources.
|
|
42
|
+
|
|
43
|
+
Void lock changes are expected on initial provisioning. If only the allowed target `void.lock.json` files change, activated version receipts are retained with release state `configuration-required`. Review and commit those files, then ship the clean configuration. Such a checkpoint cannot pass `verify` or serve as a complete rollback release. Arbitrary source changes still fail delivery. Database migrations remain applied during code rollback.
|
|
44
|
+
|
|
45
|
+
## Reproduce local checks
|
|
46
|
+
|
|
47
|
+
From the CLI repository:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
pnpm build
|
|
51
|
+
pnpm typecheck
|
|
52
|
+
node --test tests/test-void-state.test.mjs tests/test-void-execution.test.mjs tests/test-void-migrations.test.mjs tests/test-delivery.test.mjs tests/test-delivery-lock.test.mjs tests/test-ship.test.mjs
|
|
53
|
+
pnpm test:unit
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Use the repository's installed Node/pnpm versions. Avoid concurrent builds because the build script replaces shared `dist/` output.
|
|
57
|
+
|
|
58
|
+
## Live acceptance
|
|
59
|
+
|
|
60
|
+
Customer Cloudflare authentication succeeded using workspace-scoped Wrangler state. No credential contents belong in this document. A reproducible authentication pattern is:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
XDG_CONFIG_HOME="$PWD/.anhedral/cloudflare-auth" pnpm exec wrangler login
|
|
64
|
+
XDG_CONFIG_HOME="$PWD/.anhedral/cloudflare-auth" pnpm exec wrangler whoami --json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The actual Void authentication bridge also succeeded against the customer account with `accountConfirmed: true`. Credentials were supplied through the child-process environment, and no credential was persisted by the bridge. This is read-only authentication evidence, not deployment evidence.
|
|
68
|
+
|
|
69
|
+
The source-coherence review removed obsolete release helpers, diagram assets, stale plugin wrappers and duplicate dependencies; fixed bounded inspection of resolved Void locks; and brought CI runtimes and delivery documentation in line with the implementation. Browser UI acceptance was attempted but could not launch Chromium because the host denied its macOS Mach-port registration. The browser suite remains unverified in this environment. Hosted CI on commit `06bce77173cd8a122a35c3e04a7e210e4fd9d78c` subsequently passed the dashboard browser suite, both plugin checks, four CLI test lanes, eight macOS/Windows portability jobs and CodeQL. That evidence applies to that commit; subsequent changes require their own checks.
|
|
70
|
+
|
|
71
|
+
The executable read-only live preflight was also run using the workspace-scoped login. It exited with status 1 and structured `providerMutations: false`, `ready: false` before any cloud writes. Reproduce against the intended customer account and an existing generated fixture:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
XDG_CONFIG_HOME="$PWD/.anhedral/cloudflare-auth" \
|
|
75
|
+
WRANGLER_LOG_PATH=/tmp/anhedral-void-live-preflight.log \
|
|
76
|
+
node tests/test-live-void.mjs --account <customer-account-id> --fixture /absolute/generated-workspace
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The preflight can prepare an isolated local fixture with `--prepare-only /absolute/new-unused-path`; this scaffolds and builds locally and does not perform remote acceptance or publication.
|
|
80
|
+
|
|
81
|
+
Authentication alone does not prove provisioning, runtime builds, private access or deployment. Authenticated read-only preflight succeeded for the Workers account subdomain. The same login received HTTP 403 from Access organizations (provider code `10000`) and Access applications (provider code `9999`). No deployment or other provider mutation was performed. Private live acceptance is blocked until the authorized account has usable Access organization/application/policy permissions. Public deployment is not a substitute for the requested private acceptance. Separately, the Cloudflare dashboard explicitly shows that Zero Trust onboarding must be completed for this account. The dashboard observation and API permission errors are distinct evidence; the 403 responses alone do not establish their cause. In particular, do not infer that the complete Vinext plus Hono/shared database/auth combination works from local unit tests.
|
|
82
|
+
|
|
83
|
+
The acceptance workspace must exercise:
|
|
84
|
+
|
|
85
|
+
- Fresh-checkout installation and build using pinned versions.
|
|
86
|
+
- Vinext and Hono Workers with reusable shared packages.
|
|
87
|
+
- Existing D1/private R2 identity reuse, one migration owner, serialized resource creation and committed lock reuse across a new checkout.
|
|
88
|
+
- Environment validation, production secret stdin upload and public build variables.
|
|
89
|
+
- Private Access protection before activation, anonymous rejection, allowed user login and denied user behavior.
|
|
90
|
+
- Actual routing, assets, authentication and streaming responses.
|
|
91
|
+
- Initial lock review checkpoint followed by a clean provider-confirmed release and meaningful `test:live`.
|
|
92
|
+
- Failed build/deployment recovery and rollback without claiming migration reversal.
|
|
93
|
+
|
|
94
|
+
Watch the interaction between private Access's pre-created empty Worker and Void's existing-Worker checks, and between the first target's lock changes and later targets' secret upload guards. Validate both rather than weakening privacy or source checks.
|
|
95
|
+
|
|
96
|
+
For an authorized disposable application, use the built CLI's `connect`, `ship --dry-run`, `ship`, `status --refresh`, `verify`, and reviewed `rollback` commands. Preserve resource ownership and inspect partial operations before retrying. This document does not authorize additional provider resources or expenses.
|
|
97
|
+
|
|
98
|
+
## Handoff
|
|
99
|
+
|
|
100
|
+
Keep the customer-owned account, committed application manifest, `anhedral.cloudflare.json`, `void.config.ts`, `env.ts`, reviewed SQL and each app's `void.lock.json`. Keep secrets out of source. Local `.anhedral/` history and Void diagnostic logs are separate operational evidence; a fresh checkout cannot reconstruct historical source-to-version mappings from current provider versions. `recover` reports a current snapshot and does not fabricate historical verification.
|
|
101
|
+
|
|
102
|
+
## Generated dependency review (2026-10-15)
|
|
103
|
+
|
|
104
|
+
Hosted generated-profile checks on `d117f402faa6d899f972152f242b18026a45053b` failed. They are distinct from the passing CLI/plugin checks. Root-cause analysis found several independent paths to `braces`, including:
|
|
105
|
+
|
|
106
|
+
| Consumer | Dependency path | Required structural remediation |
|
|
107
|
+
| --- | --- | --- |
|
|
108
|
+
| Every inherited starter | Shared ESLint config → Next ESLint plugin → fast-glob → micromatch → braces | Declare framework lint tooling only in the web application; retain generic shared lint coverage |
|
|
109
|
+
| Vinext | vite-plugin-commonjs → vite-plugin-dynamic-import → fast-glob → micromatch → braces | Upstream consumer migration with CommonJS, development and SSR/RSC behavior verified |
|
|
110
|
+
| WXT styling | Tailwind CSS 3 → chokidar → braces | Supported Tailwind/toolchain migration, including generated styles and builds |
|
|
111
|
+
| Expo | React Native Metro config → Metro tooling → glob matching dependencies → braces | Compatible Metro/Expo dependency migration |
|
|
112
|
+
|
|
113
|
+
The current [CVE-2026-93687 advisory](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm) affects `braces <=3.0.3` and lists no patched version. npm’s latest is still `3.0.3`. [Proposed fix #72](https://github.com/micromatch/braces/pull/72) is closed without merging. The maintainer disputes the advisory’s security interpretation in [issue #70](https://github.com/micromatch/braces/issues/70); the advisory remains active. The separate [CVE-2024-4068](https://github.com/advisories/GHSA-grv7-fg5c-xmjg) was fixed by `3.0.3`, which does not resolve the newer advisory.
|
|
114
|
+
|
|
115
|
+
The failure is recursive AST processing of deeply nested glob patterns. Remote exploitability depends on whether an application passes attacker-controlled patterns to those operations; the presence of a development dependency alone does not establish an exploitable deployed endpoint. No complete reachability review has been performed for every generated profile.
|
|
116
|
+
|
|
117
|
+
An unqualified `fast-glob` → `tinyglobby` package alias is incompatible: consumers use different exports and directory expansion defaults. Removing the global starter dependency is an Anhedral composition fix, not proof that every supported framework is free of `braces`. Do not clear the audit gate or claim production acceptance until the resolved graphs and relevant runtime checks pass. The same generated CI also reports a separate `node-forge` advisory in Expo/WXT tooling, which is outside the `braces` remediation.
|
|
118
|
+
|
|
119
|
+
The shared-lint ownership change was checked against the actual upstream template manifest: a newly resolved pnpm graph contained 169 packages and none of `@next/eslint-plugin-next`, `fast-glob`, `micromatch` or `braces`; its standard pnpm audit reported no known vulnerabilities. This is evidence for the shared lint foundation only, not the entire generated application matrix. App-local web linting explicitly selects JavaScript/TypeScript/JSX/TSX files rather than relying on ESLint’s default JavaScript selection.
|
|
120
|
+
|
|
121
|
+
Validation of the scoped composition change passed 613 CLI unit tests with the real lint probe enabled, 60 inspector tests, builds, lint, static security policy, OSV checks for 86 root/catalog versions, and the package allowlist. The five lint tests include actual Next Image/Link and React Hooks diagnostics, full recommended/Core Web Vitals rule configuration, TypeScript/JSX parsing and adding web after an API-only scaffold. A helper now exercises installed rules in generated web CI profiles. A fresh local upstream shadcn initialization was attempted but its `ui.shadcn.com` request was refused by the network proxy; no fresh full generated-app matrix success is claimed.
|
|
122
|
+
|
|
123
|
+
## Temporary braces patch verification
|
|
124
|
+
|
|
125
|
+
The depth-only mitigation is based on official `braces@3.0.3`, tarball integrity `sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==`. Both the unmodified baseline and patched package passed all 764 tests from the published release source (`74b2db2938fad48a2ea54a9c8bf27a37a62c350d`). The bounded verifier passed 360 differential compile/expand/stringify comparisons, depth 100/101 and mixed/literal boundaries, deep direct ASTs, child cycles and expansion-parent cycles. Expansion width/range behavior and stringify parent handling remain unchanged.
|
|
126
|
+
|
|
127
|
+
This establishes the tested library mitigation, not a complete application exposure analysis or an upstream fixed release. The upstream registry report remains unmodified. The owner-approved gate accepts only the exact patched braces advisory after verifying installed bytes and regressions. Separate Expo/WXT findings and the remaining private Cloudflare acceptance gaps remain independent.
|
|
128
|
+
|
|
129
|
+
A real pnpm fixture resolved `braces@3.0.3` with micromatch, fast-glob and chokidar consumers, merged the exact patch, resolved the new lock and installed with `--frozen-lockfile --ignore-scripts`. The installed bytes passed the depth verifier and normal filesystem glob/watch checks. Changing the patch after resolution made a frozen install fail; restoring its bytes restored successful installation. The untouched pnpm audit JSON still reported `GHSA-vfj7-8cjw-p6xm` for `3.0.3` and was retained locally as test evidence. Both the patch and MIT notice are recorded in generated source fingerprints; customer artifacts and YAML patch entries are preserved or rejected on conflict.
|
|
130
|
+
|
|
131
|
+
Release-exception assessment: the evidence supports the tested depth mitigation for the exact patched version. It does not support a blanket advisory waiver, other versions, unrelated findings or a claim that every generated installation has been exercised. Any later exception must be constrained to the advisory/version and independently verified installed bytes, reviewed for the intended release, and retired with the patch. The owner subsequently approved and restored the exact verified exception below; other findings remain blocking.
|
|
132
|
+
|
|
133
|
+
The generated exact-path Git attributes preserve LF bytes with `core.autocrlf=true`; a real index/checkout round trip verifies the patch and license remain identical. The patch’s SHA-256 is `69bd65a37da4569ba0be8a044aa732ad7c2ebd5494d6076f966eb6df8a12756e`.
|
|
134
|
+
|
|
135
|
+
Final local validation of the mitigation passed 628 CLI tests without skips, 60 inspector tests, build/typecheck/lint, static secret/security scans, OSV checks for 87 root/catalog versions, package allowlist and packed CLI smoke. The packed installation test invokes the installed patch helper and compares generated patch/license bytes with the shipped assets. These results establish the tested mitigation, not completion of all generated-profile or live acceptance requirements.
|
|
136
|
+
|
|
137
|
+
## Restored verified advisory handling
|
|
138
|
+
|
|
139
|
+
The owner approved restoring the earlier verification-aware behavior for one package/advisory. `pnpm audit:deps` now invokes the bundled gate, preserving raw pnpm JSON in `.anhedral-audit-report.json` and printing the known upstream finding. Only `GHSA-vfj7-8cjw-p6xm` for `braces@3.0.3` can pass through this exception. Verification requires the pinned patch checksum, every discovered installed copy matching the reviewed full-package hash, and bounded depth/cycle regression checks. Unpatched/tampered copies, unknown versions, malformed or incomplete reports, command failures, and unrelated high/critical findings fail.
|
|
140
|
+
|
|
141
|
+
This restores the working patch-plus-verification behavior without the removed multi-package backport framework. It does not claim an upstream fixed release or waive the independent Expo/WXT findings or private Cloudflare acceptance work.
|
|
142
|
+
|
|
143
|
+
Validation of the restored gate passed 634 CLI tests without skips and 60 inspector tests, build/typecheck/lint, static security policy, package allowlist and packed CLI smoke. The real frozen pnpm fixture covered an npm dependency alias, accepted the exact verified mitigation, preserved the upstream audit JSON, rejected both patch-file and installed-package tampering, and passed again after restoration. The packed CLI writes the audit gate from its distributed asset.
|
|
144
|
+
|
|
145
|
+
## Hosted release follow-through (2026-10-16)
|
|
146
|
+
|
|
147
|
+
Hosted CI on `83e83e476fba8a052fb3c73aaa0e3b59659231bc` passed the Linux braces installation gate, all four CLI Node-version checks, portable macOS/Windows checks, inspector checks, plain Vercel, Next.js/Cloudflare (including Better Auth), desktop on Linux/macOS, Worker services and Vercel services. Other generated profiles exposed Void entrypoint discovery and duplicated database configuration, corrected in the subsequent source changes. These results are profile-specific, not a successful full matrix or live deployment.
|
|
148
|
+
|
|
149
|
+
The same hosted run independently confirmed that extension and combined-client profiles fail on `GHSA-86w9-cpqp-85rv` in `node-forge`. The [current advisory](https://github.com/advisories/GHSA-86w9-cpqp-85rv) covers versions through 1.4.0 and has no patched release; [upstream PR 1152](https://github.com/digitalbazaar/forge/pull/1152) remains unmerged. Current Expo CLI and extension-runner dependency paths still require this package. A framework version upgrade alone does not establish remediation.
|
|
150
|
+
|
|
151
|
+
The prior Node-main patch was evaluated separately against the official 1.4.0 release source (`fa385f92440879601240020f158bed68e444e83a`): baseline and patched versions each passed 828 tests with four upstream pending cases; the malformed-signature regression failed before and passed after patching. The aggregate harness neutralized an upstream `describe.only` so the complete suite actually ran. At that checkpoint the source-only patch did not update the package's prebuilt browser bundles and was not accepted. The completed bundle remediation and verification below supersede that earlier candidate.
|
|
152
|
+
|
|
153
|
+
Fresh pnpm resolution confirmed that Void's `^1.63.1` Cloudflare Vite dependency could select 1.64.0, whose Wrangler peer requirement exceeds Anhedral's validated pin. The Void recipe now pins that transitive edge to 1.63.1, sharing the existing version source, preserving customer override entries and leaving unrelated recipes untouched. The exact 1.63.1/4.149.0 pair passed fresh resolution and an actual Vinext/Void Vite build. Generated Worker acceptance reads the emitted Vite Worker configuration and verifies its actual entry artifact, instead of expecting the legacy Wrangler output path.
|
|
154
|
+
|
|
155
|
+
## Completed node-forge remediation
|
|
156
|
+
|
|
157
|
+
The final exact-version mitigation covers `lib/rsa.js`, `dist/forge.min.js` and `dist/forge.all.min.js` from official `node-forge@1.4.0`, rather than accepting an unpatched distribution path. The patch is 1,177,827 bytes because unified diffs include complete minified lines; the actual guard changes are limited to nested DigestAlgorithm cardinality and strict DER NULL contents. The minified predicates implement the same source guard, and their trivial one-line source maps remain valid. The upstream BSD attribution is retained.
|
|
158
|
+
|
|
159
|
+
Patch SHA-256: `2cbbff9183d2896f13da8c8655b8f598b0f24c9b7477e8230f9a313f806c239f`. Reviewed full installed-tree SHA-256: `2e3a4c3aa2e8f3235d9dd9b3f21698c7aa88983ba9623f1502029386316380e4`. The official tarball integrity is `sha512-LarFH0+6VfriEhqMMcLX2F7SwSXeWwnEAJEsYm5QKWchiVYVvJyV9v7UDvUv+w5HO23ZpQTXDv/GxdDdMyOuoQ==`.
|
|
160
|
+
|
|
161
|
+
For each of the three published entrypoints, forced pure-JavaScript RSA verification preserved 11 valid cases and rejected all 30 malformed cases across six digest algorithms. The official unpatched package accepted 23 malformed cases, so the regression distinguishes the fix. The complete official Node suite passed 828 tests with four upstream pending cases against the final source patch. Exact Node 24.21/pnpm 10.34.5 frozen installation with direct and aliased dependencies passed and reproduced the reviewed bytes and all-entrypoint behavior.
|
|
162
|
+
|
|
163
|
+
The audit gate extends its fixed policy to the one additional exact advisory/version only after patch checksum, every installed package tree and bounded runtime probes pass. It retains the raw upstream advisory and rejects unrelated high/critical findings. It is a verified local mitigation, not an official upstream fixed release. The removed open-ended multi-package manifest/backport framework remains absent.
|
|
164
|
+
|
|
165
|
+
CI now prepares a reviewable Linux release candidate on Node 24.21 after its checks, verifying artifact integrity, scanning for secrets and executing the exact packed CLI. It uploads the candidate with one-day retention; this step cannot publish and does not change required reviews or main-commit release checks.
|
|
166
|
+
|
|
167
|
+
Consolidated local validation passed 649 CLI tests without skips, 60 inspector tests, build/typecheck/lint, static security policy, package allowlist and packed CLI smoke. Both real frozen-install fixtures passed, including original braces glob/watch behavior and node-forge source/browser-bundle tamper rejection. The packed CLI carries and stages both exact patches and upstream notices. The combined candidate still requires the full hosted matrix and the repository’s existing code-owner review before publication.
|
|
168
|
+
|
|
169
|
+
Installed-graph verification recognizes explicitly optional peer dependencies as well as ordinary optional dependencies. A missing peer is skippable only when the parent declares the peer and marks it optional, with no competing required dependency declaration; present dangling links, outside paths and missing required packages still fail. Missing required-package diagnostics include an escaped project-relative path. All 650 CLI tests passed after this change.
|
|
170
|
+
|
|
171
|
+
## Incremental dependency installation repair
|
|
172
|
+
|
|
173
|
+
The remaining existing-project acceptance case exposed a real pnpm 10.34.5 installation defect. In an API/Neon project, `tslib@2.8.1` was initially skipped through optional `@emnapi/runtime`. Adding WXT introduced required `async-mutex -> tslib`, and the newly resolved lock recorded it as required, but the incremental frozen installation retained the old skipped state and omitted the package. The original verifier correctly rejected this missing required dependency. Optional-peer support is independently valid and does not hide this defect.
|
|
174
|
+
|
|
175
|
+
Removing only generated root `node_modules` and running an ordinary frozen installation completed in 5.6 seconds on the original failing graph. The reviewed lock remained exactly `b412f3758702f52968e564a99fcac618ea6be89697a05e301e4bad4807a04906`; the dependency was installed, its skipped state cleared, and both the original collector and full verified audit gate passed. Workspace links and the separate content-addressed package store were retained.
|
|
176
|
+
|
|
177
|
+
Actual additions now rematerialize that generated cache before frozen installation and check that the lock bytes remain unchanged. Linked or non-directory cache paths are rejected before cleanup. Source, reviewed patches and lock ownership remain intact. The alternate `--fix-lockfile` command was rejected because it rewrote the reviewed lock despite `--frozen-lockfile`; `--force` is not used.
|
|
178
|
+
|
|
179
|
+
The final cache-regression run passed all 652 CLI tests without skips, 60 inspector tests, lint and static security policy. Focused cases cover stale generated cache removal with package-store preservation, linked-cache refusal and frozen-lock byte drift.
|
|
180
|
+
|
|
181
|
+
## Simplified dependency patch policy (2026-10-16)
|
|
182
|
+
|
|
183
|
+
This supersedes the installed-tree and runtime audit-gate design described in the historical checkpoints above. `src/dependency-patches.ts` installs both exact-version patches and notices while preserving customer policy and source files. Generated audits retain the raw pnpm report and accept only the two reviewed advisory/version pairs, with the effective pnpm patch mapping and bundled patch checksum. Frozen pnpm installation applies the patches and checks lockfile consistency. The audit no longer traverses installed dependencies, hashes package trees, or executes package code.
|
|
184
|
+
|
|
185
|
+
Runtime coverage lives in this repository: the braces fixture checks depth/cycle guards and normal glob/watch consumers; the forge fixture checks valid and malformed signatures through Node and both browser bundles. Both fixtures check frozen installation and changed-patch rejection. Audit-policy tests use deterministic reports to cover unknown advisories, other versions, critical findings, malformed reports, command errors, missing/wrong mappings, and changed patch bytes. Live advisory-service availability is independent of these regression tests; generated `pnpm audit:deps` still queries the actual service.
|