anhedral 0.11.1 → 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 +38 -74
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/software-factory.md +192 -0
- package/docs/stack-standard.md +94 -127
- package/package.json +2 -2
- package/docs/delivery-workflow.md +0 -98
package/README.md
CHANGED
|
@@ -4,86 +4,64 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/anhedral)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
|
|
7
|
-
Anhedral
|
|
7
|
+
Anhedral creates TypeScript application workspaces and helps deliver them to your own cloud accounts. Start with a web app, add the interfaces and services your product needs, and keep the source code, infrastructure, data and billing under your control.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The default is **Vinext, React, Tailwind, shadcn/ui and Lucide on Cloudflare Workers**, with pnpm and Turborepo. The CLI generates the foundation and handles supported setup and delivery operations. You or your coding agent implement the product.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Start locally
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
Void owns Cloudflare provisioning, secret uploads and deployment. Anhedral retains stack composition, shared packages, customer ownership and independent release/product verification. Explicit OpenNext, Queues and Basin profiles use Anhedral’s Wrangler delivery path. Initialization creates source without deploying it.
|
|
13
|
+
Use **Node.js 24.21.0 or newer** and **pnpm 10.34.5**. Initialize on Linux, macOS or WSL.
|
|
16
14
|
|
|
17
15
|
```sh
|
|
18
16
|
npm install --global anhedral
|
|
19
17
|
|
|
20
|
-
#
|
|
18
|
+
# Inspect the default selection; no writes or network requests.
|
|
21
19
|
anhedral init my-app --dry-run --json
|
|
22
20
|
|
|
23
|
-
# Generate
|
|
21
|
+
# Generate source, install dependencies and start development.
|
|
24
22
|
anhedral init my-app
|
|
25
23
|
cd my-app
|
|
26
24
|
pnpm dev
|
|
27
25
|
```
|
|
28
26
|
|
|
29
|
-
|
|
27
|
+
Initialization downloads the pinned upstream starter and installs dependencies. It does not provision cloud services or deploy the app. Follow the generated README for local addresses and any setup required by your selection. You can also run the CLI with `pnpm dlx anhedral@latest`; pin a version for repeatable automation.
|
|
30
28
|
|
|
31
|
-
## Choose
|
|
29
|
+
## Choose what to generate
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
An explicit selection chooses the requested applications; include the web option when you want web alongside another interface.
|
|
34
32
|
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
|
|
|
33
|
+
| Project | Command |
|
|
34
|
+
| ---------------------------------- | -------------------------------------------------- |
|
|
35
|
+
| Default web app | `anhedral init my-app` |
|
|
36
|
+
| Web with D1 and Better Auth | `anhedral init my-app --vinext --d1 --better-auth` |
|
|
37
|
+
| Web and shared API with PostgreSQL | `anhedral init my-app --vinext --hono --neon` |
|
|
38
|
+
| Native Next.js on Vercel | `anhedral init my-app --next` |
|
|
39
|
+
| Expo mobile app | `anhedral init my-app --expo` |
|
|
40
|
+
| Electron desktop app | `anhedral init my-app --electron` |
|
|
41
|
+
| WXT browser extension | `anhedral init my-app --wxt` |
|
|
43
42
|
|
|
44
|
-
|
|
43
|
+
Inspect available services and preview additions:
|
|
45
44
|
|
|
46
45
|
```sh
|
|
47
|
-
anhedral init my-app --d1 --better-auth
|
|
48
|
-
anhedral init mobile-app --expo
|
|
49
|
-
anhedral init product --next --hono --d1 --r2
|
|
50
46
|
anhedral registry list
|
|
51
47
|
anhedral registry view resend --json
|
|
48
|
+
anhedral add resend --cwd my-app --dry-run --json
|
|
49
|
+
anhedral add resend --cwd my-app
|
|
52
50
|
```
|
|
53
51
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
The project keeps Anhedral metadata in one committed root `anhedral.json`, with named sections for identity, stack selection, registry provenance, integrations and selected hosting. Credentials and delivery history remain in ignored runtime files and `.anhedral/`.
|
|
57
|
-
|
|
58
|
-
The bundled registry contains recipes maintained and tested by Anhedral. Generated source belongs to your project and stays editable. External registries are unsupported. Preview additions before applying them:
|
|
59
|
-
|
|
60
|
-
```sh
|
|
61
|
-
anhedral add resend stripe --cwd my-app --dry-run --json
|
|
62
|
-
anhedral add resend stripe --cwd my-app
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
See the [stack standard](docs/stack-standard.md) for supported combinations and architecture guidance.
|
|
52
|
+
Generated entry points live in `apps/*`, shared code in `packages/*`, and Anhedral configuration in one root `anhedral.json`. Read the [source-only full-stack example](https://github.com/anhedral/anhedral-cli/tree/main/examples/full-stack) to see a larger project without creating services.
|
|
66
53
|
|
|
67
|
-
##
|
|
54
|
+
## Build and deliver
|
|
68
55
|
|
|
69
|
-
Implement
|
|
56
|
+
Implement the product, configure selected integrations and review database migrations. Then use the [software factory](docs/software-factory.md) to check provider access, connect the intended account and audience, commit source, ship and verify real user flows.
|
|
70
57
|
|
|
71
58
|
```sh
|
|
72
|
-
anhedral auth
|
|
73
59
|
anhedral auth --status --json
|
|
74
|
-
anhedral
|
|
60
|
+
anhedral doctor --providers --json
|
|
75
61
|
anhedral ship --dry-run --json
|
|
76
|
-
anhedral ship --json
|
|
77
|
-
anhedral verify --json
|
|
78
62
|
```
|
|
79
63
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
For Wrangler profiles, changed resource IDs stop `ship` before deployment for review and a commit. Void can activate a target before recording new resource identities in `void.lock.json`; it then returns `configuration-required` with the activation receipts retained. Review and commit those locks, then ship the clean configuration. It never commits source automatically. Shipping runs project checks and records delivery results. `verify` exercises your application's live acceptance test; a successful scaffold or deployment alone does not prove its features work.
|
|
83
|
-
|
|
84
|
-
Provider eligibility, subscriptions, usage limits, and charges remain your responsibility. Some setup requires owner action. Expo delivery returns EAS build links; it does not submit apps to stores.
|
|
85
|
-
|
|
86
|
-
See [delivery and recovery](docs/delivery-workflow.md) and [provider configuration](docs/provider-configuration.md) for account selection, deployment, migration, rollback, and integration requirements.
|
|
64
|
+
These commands help inspect readiness; actual shipping can create resources, apply reviewed deployment migrations and publish code. Provider permissions, account eligibility and usage charges still apply. A generated starter or successful deployment does not establish a working product.
|
|
87
65
|
|
|
88
66
|
## Use with Codex
|
|
89
67
|
|
|
@@ -96,40 +74,26 @@ Select **Try now**, or start with:
|
|
|
96
74
|
|
|
97
75
|
> Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.
|
|
98
76
|
|
|
99
|
-
The plugin guides
|
|
77
|
+
The plugin guides implementation using the same stack and workflow. Its optional inspector shows project structure, setup, recorded delivery evidence and explicit service controls. Opening it does not deploy the app. The CLI works independently.
|
|
100
78
|
|
|
101
|
-
##
|
|
79
|
+
## Read next
|
|
102
80
|
|
|
103
|
-
|
|
81
|
+
| Document | Use it to answer |
|
|
82
|
+
| -------------------------------------------- | ------------------------------------------------------------------------ |
|
|
83
|
+
| [Stack standard](docs/stack-standard.md) | What should the application contain, and how should it fit together? |
|
|
84
|
+
| [Software factory](docs/software-factory.md) | How do I turn a brief into a tested, delivered and maintainable product? |
|
|
104
85
|
|
|
105
|
-
- [CLI
|
|
106
|
-
- [Stack standard](docs/stack-standard.md)
|
|
107
|
-
- [Delivery and recovery](docs/delivery-workflow.md)
|
|
108
|
-
- [Provider configuration](docs/provider-configuration.md)
|
|
109
|
-
- [Plugin development](docs/plugin-ui.md)
|
|
86
|
+
Use `anhedral --help` and `anhedral help <command>` for command options. `--cwd` selects the project; `--json` produces structured output. Detailed references cover [provider configuration](docs/provider-configuration.md), [CLI behavior](docs/cli-design.md) and the [Codex inspector](docs/plugin-ui.md).
|
|
110
87
|
|
|
111
|
-
##
|
|
88
|
+
## Work on the CLI
|
|
112
89
|
|
|
113
90
|
```sh
|
|
114
91
|
pnpm install --frozen-lockfile
|
|
92
|
+
pnpm build
|
|
93
|
+
node dist/bin.js init ../my-test-app --dry-run --json
|
|
115
94
|
pnpm test:all
|
|
116
|
-
pnpm test:integration
|
|
117
95
|
```
|
|
118
96
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
Focused fixes, tests, and documentation contributions are welcome. See [contributing](https://github.com/anhedral/anhedral-cli/blob/main/.github/CONTRIBUTING.md), [code of conduct](https://github.com/anhedral/anhedral-cli/blob/main/.github/CODE_OF_CONDUCT.md), and [security reporting](https://github.com/anhedral/anhedral-cli/blob/main/.github/SECURITY.md). Report reproducible problems in [issues](https://github.com/anhedral/anhedral-cli/issues) and vulnerabilities through [private reporting](https://github.com/anhedral/anhedral-cli/security/advisories/new).
|
|
122
|
-
|
|
123
|
-
Anhedral is open source under the [Apache License 2.0](LICENSE). Generated applications are source code that developers can customize and license for their products, preserving applicable upstream notices.
|
|
124
|
-
|
|
125
|
-
## Repository layout
|
|
126
|
-
|
|
127
|
-
| Path | Purpose |
|
|
128
|
-
| --- | --- |
|
|
129
|
-
| `src` | CLI and application scaffolding |
|
|
130
|
-
| `plugins/codex/inspector` | Optional project inspector and MCP runtime sources |
|
|
131
|
-
| `plugins/codex/distribution` | Plugin manifest, assets, skill and bundled runtime |
|
|
132
|
-
| `scripts`, `tests` | Build, release and verification tooling |
|
|
133
|
-
| `docs` | Canonical architecture, delivery and development documentation |
|
|
97
|
+
`pnpm test:integration` installs and checks generated projects. Inspector development uses `pnpm plugin:build`, `pnpm plugin:check` and `pnpm plugin:preview`; its dependencies and lockfile live in `plugins/codex/inspector`. Building the checkout does not update an installed CLI or plugin. See the [contribution guide](https://github.com/anhedral/anhedral-cli/blob/main/.github/CONTRIBUTING.md) for the development and review process.
|
|
134
98
|
|
|
135
|
-
|
|
99
|
+
Anhedral is open source under the [Apache License 2.0](LICENSE). Generated applications are source code that developers can customize and license for their products, preserving upstream notices. Report bugs in [issues](https://github.com/anhedral/anhedral-cli/issues) and vulnerabilities through [private security reporting](https://github.com/anhedral/anhedral-cli/security/advisories/new).
|
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const GENERATOR_VERSION = "0.11.
|
|
1
|
+
export declare const GENERATOR_VERSION = "0.11.2";
|
package/dist/version.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export const GENERATOR_VERSION = '0.11.
|
|
1
|
+
export const GENERATOR_VERSION = '0.11.2';
|
|
@@ -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.
|
package/docs/stack-standard.md
CHANGED
|
@@ -1,175 +1,142 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Stack standard
|
|
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
|
-
|
|
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
6
|
|
|
7
|
-
|
|
8
|
-
| --- | --- | --- |
|
|
9
|
-
| Workspace | pnpm/Turborepo, TypeScript, ESLint, shared UI | Official pinned shadcn monorepo bootstrap, workspace configuration and checks |
|
|
10
|
-
| Web | Vinext; Next.js | React, Tailwind, shadcn/ui and Lucide; Vinext on Workers by default, native Next.js on Vercel or explicit OpenNext on Workers |
|
|
11
|
-
| API | Hono | OpenAPI Worker application with selected service bindings |
|
|
12
|
-
| Cloudflare delivery | Void; explicit Wrangler profiles | Void provisions and publishes; Anhedral composes, controls audience policy and independently verifies |
|
|
13
|
-
| Mobile | Expo | React Native Reusables and NativeWind; native builds require platform toolchains |
|
|
14
|
-
| Desktop | Electron | React application; packaging, signing and distribution require platform-specific setup |
|
|
15
|
-
| Browser extension | WXT | React popup and Chrome side panel; installation and store distribution are separate steps |
|
|
16
|
-
| Data | D1, Neon, local data | Drizzle schemas for D1/Neon; direct Neon serverless HTTP; device-local data foundations |
|
|
17
|
-
| Live Postgres queries | Neon Realtime (`--neon-realtime`) | Optional server/client factories and Drizzle adapter; branch setup and authorized query flows remain application work |
|
|
18
|
-
| Identity | Better Auth, Clerk | Server/client configuration and selected schema or provider middleware |
|
|
19
|
-
| Worker services | R2, KV, realtime, Queues, cron, Workflows | Private storage bindings, cache/config bindings, Durable Object WebSocket rooms and job/schedule foundations |
|
|
20
|
-
| AI | Workers AI, OpenAI, AI SDK | Server-side inference bindings or SDK factories |
|
|
21
|
-
| Email | Resend | Server-side transactional email client |
|
|
22
|
-
| Payments | Stripe, RevenueCat | Payment/entitlement integration foundations |
|
|
23
|
-
| Monitoring and analytics | Sentry, PostHog, Basin | Runtime SDK factories or analytical ingestion configuration |
|
|
24
|
-
| Shared styling | Styling | Tokens and presets for compatible native and extension clients |
|
|
7
|
+
## Select the applications
|
|
25
8
|
|
|
26
|
-
|
|
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 |
|
|
27
18
|
|
|
28
|
-
|
|
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.
|
|
29
20
|
|
|
30
|
-
|
|
31
|
-
| --- | --- |
|
|
32
|
-
| `packages/db/src/index.ts` | Database factory; the server supplies a connection string or D1 binding |
|
|
33
|
-
| `packages/db/src/schema.ts` | Shared Drizzle schema, including selected auth tables |
|
|
34
|
-
| `packages/db/src/migrate.ts` | Explicit migration entry point, separate from runtime exports |
|
|
35
|
-
| `packages/db/drizzle/` | Generated SQL, snapshots and migration journal |
|
|
36
|
-
| `packages/db/drizzle.config.ts` | Paths resolved relative to the configuration file, not the caller's working directory |
|
|
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.
|
|
37
22
|
|
|
38
|
-
|
|
23
|
+
## Select data, identity and services
|
|
39
24
|
|
|
40
|
-
|
|
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 |
|
|
41
40
|
|
|
42
|
-
|
|
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.
|
|
43
42
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
Inspect exact current requirements before generation:
|
|
43
|
+
The bundled registry is authoritative for exact dependencies, destinations and compatibility:
|
|
47
44
|
|
|
48
45
|
```sh
|
|
49
46
|
anhedral registry list --json
|
|
50
47
|
anhedral registry view better-auth --json
|
|
51
|
-
anhedral init my-app --hono --d1 --better-auth --r2 --dry-run --json
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
The default selects only Vinext on Cloudflare Workers, delivered through Void, plus the shared workspace and UI foundation. Add capabilities because the application needs them. The resolver adds required dependencies and rejects incompatible choices, including conflicting web frameworks, databases and identity providers. `--all` is unsupported. Native Next.js selects Vercel unless Cloudflare hosting is explicit. Some services require a Worker application; inspect the plan rather than assuming every selection can run on every client.
|
|
55
|
-
|
|
56
|
-
## Neon Realtime
|
|
57
|
-
|
|
58
|
-
Select `--neon-realtime` when the product needs live Postgres query results. It adds Neon when no database was selected and requires a server runtime; an explicit conflicting database is rejected. `--realtime` continues to mean Cloudflare Durable Object WebSocket rooms, which can be selected independently.
|
|
59
|
-
|
|
60
|
-
The recipe creates `packages/neon-realtime` with separate `@workspace/neon-realtime/server` and `/client` exports. The server factory receives private `NEON_REALTIME_SECRET` and `DATABASE_URL` and uses the Drizzle adapter; the client factory receives the public `NEON_REALTIME_URL`. Keep database credentials and sealing code out of browser/native bundles. Follow the generated package README for usage and framework-specific public environment mapping.
|
|
61
|
-
|
|
62
|
-
Manually enable Realtime on the intended Neon branch, allow the exact client origins and configure its secret and URL. The CLI does not automate Realtime provisioning. Authenticate each sealing request, derive user/tenant scope from verified identity and construct bounded, read-only queries on the server. No arbitrary SQL endpoint or complete subscription flow is generated. Clients subscribe with short-lived sealed queries; implement authorized renewal and test denied users and membership changes.
|
|
63
|
-
|
|
64
|
-
[Neon Realtime](https://neon.com/docs/realtime/overview) is beta and currently has no RLS support. Application authorization must be expressed in the scoped queries you seal. See [query authorization](https://neon.com/docs/realtime/guides/queries#authorization) and [branch setup](https://neon.com/docs/realtime/quickstart). Local recipe checks do not establish live subscription, renewal or cross-tenant acceptance.
|
|
65
|
-
|
|
66
|
-
## Source layout and composition
|
|
67
|
-
|
|
68
|
-
Use `apps/*` for applications and services, and `packages/*` for shared code. Generated `docs/stack.md` lists the resolved options, destinations, environment names and setup requirements. The `setup` section of `anhedral.json` records setup requirements; its `registry` section records recipe versions, generated-file fingerprints and workspace references.
|
|
69
|
-
|
|
70
|
-
The root `anhedral.json` is the single committed Anhedral configuration document. Its envelope has `schemaVersion: 1`; each named section retains its own domain schema version and validation. The CLI updates only the section it owns and preserves the other sections.
|
|
71
|
-
|
|
72
|
-
| Section | Purpose |
|
|
73
|
-
| --- | --- |
|
|
74
|
-
| `identity` | Stable local application ID used by the project catalog |
|
|
75
|
-
| `setup` | Selected products, hosting, environment requirements and owner setup |
|
|
76
|
-
| `standard` | Scaffold conventions and version provenance |
|
|
77
|
-
| `registry` | Recipe versions, generated-file fingerprints and workspace references |
|
|
78
|
-
| `providers` | Nonsecret integration settings and selected provider resources |
|
|
79
|
-
| `cloudflare` | Cloudflare delivery engine, account, audience and targets |
|
|
80
|
-
| `vercel` | Vercel repository, project, team and audience |
|
|
81
|
-
|
|
82
|
-
Only selected hosting sections are present. Keep credentials and delivery history in ignored runtime files and `.anhedral/`; they do not belong in `anhedral.json`. Per-app `anhedral.cloudflare.json`, `void.config.ts`, `void.lock.json` and native tool configuration remain with their owning applications.
|
|
83
|
-
|
|
84
|
-
The catalog in `src/stack-registry.ts` owns recipe identity and composition rules. Dependencies and the official shadcn bootstrap are pinned in `src/dependencies.ts`. Recipes under `src/scaffold/` compose the resolved selection inside a staging transaction. Workspace names must be unique, references must resolve, and dependency cycles fail before commit.
|
|
85
|
-
|
|
86
|
-
Incremental `add` uses only the bundled catalog maintained with the CLI. External registries and custom registry payloads are unsupported. Additions preserve edited and untracked source, refresh generated stack documentation and record provenance. Additions require current registry receipts and preserve the selected runtime layout.
|
|
87
|
-
|
|
88
|
-
```sh
|
|
89
|
-
anhedral --cwd my-app add resend stripe --dry-run --json
|
|
90
|
-
anhedral --cwd my-app add resend stripe
|
|
91
|
-
anhedral doctor my-app --json
|
|
48
|
+
anhedral init my-app --vinext --hono --d1 --better-auth --r2 --dry-run --json
|
|
92
49
|
```
|
|
93
50
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
## Provider access and delivery
|
|
97
|
-
|
|
98
|
-
### Default Cloudflare delivery: Void
|
|
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.
|
|
99
52
|
|
|
100
|
-
|
|
53
|
+
## Organize the source
|
|
101
54
|
|
|
102
|
-
|
|
|
103
|
-
|
|
|
104
|
-
|
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
|
|
|
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 |
|
|
109
65
|
|
|
110
|
-
|
|
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.
|
|
111
67
|
|
|
112
|
-
|
|
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.
|
|
113
69
|
|
|
114
|
-
|
|
70
|
+
### One Anhedral configuration
|
|
115
71
|
|
|
116
|
-
|
|
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.
|
|
117
73
|
|
|
118
|
-
|
|
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 |
|
|
119
83
|
|
|
120
|
-
|
|
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.
|
|
121
85
|
|
|
122
|
-
|
|
86
|
+
## Data and migrations
|
|
123
87
|
|
|
124
|
-
|
|
88
|
+
All database-backed selections use the server-only `@workspace/db` package:
|
|
125
89
|
|
|
126
|
-
|
|
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 |
|
|
127
97
|
|
|
128
|
-
|
|
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.
|
|
129
99
|
|
|
130
|
-
|
|
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.
|
|
131
101
|
|
|
132
|
-
|
|
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.
|
|
133
103
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
`ship` coordinates selected integration provisioning, private runtime configuration and supported hosting delivery. [Provider configuration](provider-configuration.md) documents the eight API adapters, required management credentials and owner prerequisites. Authentication checks alone do not establish every write permission. If resolved bindings change tracked configuration, review and commit them before repeating the command. Expo delivery verifies the selected account/project/source and returns a build-page link while queued or a download link when complete; store submission remains separate.
|
|
104
|
+
## Neon Realtime
|
|
137
105
|
|
|
138
|
-
|
|
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.
|
|
139
107
|
|
|
140
|
-
|
|
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.
|
|
141
109
|
|
|
142
|
-
-
|
|
143
|
-
- Select one database and one identity provider. Implement resource and tenant authorization in the application; hosting access protection does not replace product identity.
|
|
144
|
-
- Keep R2 private and authorize file operations. KV is eventually consistent and should not hold authoritative transactional state.
|
|
145
|
-
- Implement webhooks and jobs idempotently. Bound retries, concurrency and paid usage; verify recovery and data compatibility before rollback.
|
|
146
|
-
- Verify the actual runtime: Vinext/Vite on Workers, Next.js/OpenNext on Workers, or native Next.js on Vercel. Generated native clients need device, packaging and signing checks appropriate to their target.
|
|
147
|
-
- Run generated checks and exercise product flows. Initialization, installed SDKs and successful builds do not prove provider configuration or production acceptance.
|
|
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.
|
|
148
111
|
|
|
149
|
-
|
|
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.
|
|
150
113
|
|
|
151
|
-
##
|
|
114
|
+
## Runtime and delivery configuration
|
|
152
115
|
|
|
153
|
-
|
|
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+` |
|
|
154
121
|
|
|
155
|
-
|
|
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.
|
|
156
123
|
|
|
157
|
-
|
|
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.
|
|
158
125
|
|
|
159
|
-
|
|
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.
|
|
160
127
|
|
|
161
|
-
|
|
128
|
+
## Source ownership and dependency policy
|
|
162
129
|
|
|
163
|
-
|
|
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.
|
|
164
131
|
|
|
165
|
-
|
|
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.
|
|
166
133
|
|
|
167
|
-
|
|
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.
|
|
168
135
|
|
|
169
|
-
|
|
136
|
+
Validate the resolved dependency graph for each application selection. A clean CLI dependency graph does not establish a clean generated application graph.
|
|
170
137
|
|
|
171
|
-
|
|
138
|
+
## Product requirements
|
|
172
139
|
|
|
173
|
-
|
|
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.
|
|
174
141
|
|
|
175
|
-
|
|
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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "anhedral",
|
|
3
|
-
"version": "0.11.
|
|
3
|
+
"version": "0.11.2",
|
|
4
4
|
"description": "Build and deliver applications with Cloudflare-first Vinext, selected services, optional Next.js on Vercel, and verified release evidence.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
"LICENSE",
|
|
25
25
|
"README.md",
|
|
26
26
|
"docs/stack-standard.md",
|
|
27
|
-
"docs/
|
|
27
|
+
"docs/software-factory.md",
|
|
28
28
|
"docs/void-verification.md",
|
|
29
29
|
"docs/provider-configuration.md",
|
|
30
30
|
"docs/cli-design.md",
|
|
@@ -1,98 +0,0 @@
|
|
|
1
|
-
# Build and deliver an application
|
|
2
|
-
|
|
3
|
-
The CLI supplies the source foundation, provider access checks and supported delivery operations. Feature design, product implementation, custom integrations and ongoing maintenance are development work. Anhedral offers these services; scaffolding and successful deployment do not establish a finished product.
|
|
4
|
-
|
|
5
|
-
Codex implements the product; the CLI supplies scaffolding, selected resource reconciliation and source/provider evidence. Delivery uses your own Cloudflare or Vercel account. Start with users, flows, audience, budget and observable acceptance criteria; preserve suitable existing apps.
|
|
6
|
-
|
|
7
|
-
## Plan and implement
|
|
8
|
-
|
|
9
|
-
1. Choose only needed components from the [stack standard](https://github.com/anhedral/anhedral-cli/blob/main/docs/stack-standard.md). Record decisions, ownership, environment/cost assumptions and actual connections in the application's `docs/architecture.md`.
|
|
10
|
-
2. Match installed plugin, registry `cliVersion` and executable versions. Check Node/pnpm, Git identity, toolchains and customer provider access. For unpublished development use `pnpm build` and `node dist/bin.js`; never silently substitute `@latest`.
|
|
11
|
-
3. Inspect `init <unused-directory> <flags> --dry-run --json`, then generate with those choices. Review README, AGENTS, setup manifests and resolved lockfile. For initialized apps, preview `anhedral --cwd <directory> add <items...> --dry-run --json`; additions protect edited source and record registry provenance. Select only items from the bundled Anhedral catalog. If a web addition reports `filesChecked: false`, the preview covers selection and targets only; the actual transaction checks generated-file conflicts before committing. Additions require current registry receipts and preserve the selected runtime layout. `doctor --providers --json` checks access without configuring infrastructure or certifying production.
|
|
12
|
-
4. Implement screens, APIs, persistence, authorization and integration behavior. Replace placeholders with working flows. Configure real secrets, origins and reviewed migrations using provider tools; starters do not establish setup completion. Keep credentials out of source, logs and handoffs.
|
|
13
|
-
|
|
14
|
-
## Provider authentication
|
|
15
|
-
|
|
16
|
-
Run `anhedral auth <directory>` for the selected stack. `--status` checks existing access without opening login; `--provider <name>` limits the check to a required provider. JSON and `--non-interactive` never start login prompts. Missing credentials, insufficient permissions and unverified access return a nonzero exit status. Environment-supplied API credentials stay out of output and committed configuration. Authentication does not activate subscriptions, select hosting audience or configure integration resources.
|
|
17
|
-
|
|
18
|
-
## Source and release authority
|
|
19
|
-
|
|
20
|
-
Complete the selected integrations' nonsecret account/resource choices in the `providers` section of `anhedral.json`. See [provider configuration](provider-configuration.md) for supported adapters, management credentials, private runtime files, retry behavior, provider prerequisites and verification limits. `ship --dry-run` previews their missing settings without provider operations.
|
|
21
|
-
|
|
22
|
-
Use customer-owned accounts and a reviewed clean commit. Default to a private repository in the selected account; organizations require selection.
|
|
23
|
-
|
|
24
|
-
```sh
|
|
25
|
-
anhedral repository my-app --create --json
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
This verifies the app's Git root, owner, visibility, write access and exact remote commit. Reuse matching origins without `--create`; do not replace remotes, change visibility or force-push. Connected repository identity is retained and rechecked.
|
|
29
|
-
|
|
30
|
-
Choose one release path per change: checked `ship`, or checks followed by an authorized Git push, active production confirmation and `adopt`. Git integration can deploy independently of CLI checks; configure required CI/branch/deployment policy explicitly. Do not routinely deploy the same commit twice.
|
|
31
|
-
|
|
32
|
-
## Cloudflare delivery
|
|
33
|
-
|
|
34
|
-
Vinext/Workers is the default web recipe. Explicit Next.js on Workers uses `--next --hosting=cloudflare`. Select persistence, identity and AI from the standard. Cloudflare delivery reads the `cloudflare` section of `anhedral.json`. Default `ship` coordinates Cloudflare services before the Vercel web app in mixed projects. Use `--provider cloudflare` or `--provider vercel` to operate on one hosting target explicitly; standalone `provision` is Cloudflare-only. Supported Cloudflare selections use Void, while explicit OpenNext, queue/DLQ and Basin selections use Wrangler.
|
|
35
|
-
|
|
36
|
-
```sh
|
|
37
|
-
anhedral connect my-app --audience private --allow-email owner@example.com
|
|
38
|
-
anhedral provision my-app --dry-run --json
|
|
39
|
-
anhedral ship my-app --dry-run --json
|
|
40
|
-
anhedral ship my-app --json
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Connect verifies the sole accessible or explicitly selected `--account` and preserves audience/account choices. Public access requires authorization. Private hosting needs Zero Trust and scoped Access/Workers permissions; verify routes, domains and previews before and after deployment. Whole-Worker Access does not cover WebSockets: design and verify private realtime separately.
|
|
44
|
-
|
|
45
|
-
For Void projects, `provision` reports the resource plan and defers writes to Void deployment. It never runs Anhedral's resource creator in parallel. The migration owner prepares an ignored, byte-identical validation copy from `packages/db/drizzle`; Void validates its apply set against the shared SQL. Other consumers receive no migration copy. Generate and review SQL with the shared Drizzle configuration first; Void does not inspect shared-package schema drift automatically. Void deploys targets serially, records actual IDs in each app's `void.lock.json`, and applies reviewed deployment migrations. The first activation may require reviewing and committing new locks before shipping a clean release; successful target activation is recorded separately from source completion and product verification. Subsequent deployments reuse the committed identities. Wrangler provisioning reconciles D1, private R2, KV and Queues/dead-letter queues; it does not implement schemas or integrations. Full `ship` also configures the selected integration adapters and private Basin streams. Review database migrations and application-specific integrations separately; developer-added Hyperdrive, Basin sinks and transforms need an explicit provider workflow. Void apps use `anhedral.cloudflare.json`, `void.config.ts` and `env.ts`; copy `env.example` to the app's private `.env`. Do not add `.env.local`, `.env.production`, `.env.example` or `.dev.vars` alongside Void's local environment file. Secret commands use noninteractive stdin; public build variables stay in the build environment. Vite clients use `VITE_*`; the pinned Vinext plugin loads the app `.env` for local builds and maps `NEXT_PUBLIC_*` into client bundles. Supply the selected public values during production builds; server-secret uploads do not configure client bundles. The Neon starter uses direct serverless HTTP with a server-side DATABASE_URL. Reconcile partial operations before retrying. Shipping requires clean source, checks account/bindings, runs application checks and confirms active versions/traffic. Void's pinned structured JSONL receipt is correlated with the active Cloudflare version independently; diagnostic prose is never a success receipt. Missing/ambiguous receipts or provider drift stop acceptance. Multiple Workers are not an atomic release; web deploys last by default. Code rollback delegates to Void for Void projects and does not undo database migrations or incompatible Durable Object class changes.
|
|
46
|
-
|
|
47
|
-
See [Void verification and handoff](void-verification.md) for the pinned evidence contract, reproducible checks, live acceptance results and outstanding gates.
|
|
48
|
-
|
|
49
|
-
## Native Next.js/Vercel delivery
|
|
50
|
-
|
|
51
|
-
Select `--next`, authenticate the intended customer account and choose an eligible plan. Hobby is personal/non-commercial; commercial use requires an eligible existing plan.
|
|
52
|
-
|
|
53
|
-
```sh
|
|
54
|
-
anhedral connect my-app --scope customer-team --audience private --use personal --create --git
|
|
55
|
-
pnpm --dir my-app run check
|
|
56
|
-
anhedral repository my-app --json
|
|
57
|
-
# Wait for the connected production Git deployment.
|
|
58
|
-
anhedral adopt my-app --json
|
|
59
|
-
anhedral verify my-app --json
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
Connect checks project/framework/root, repository link and audience. New private projects establish independently verified all-deployment Vercel Authentication before code or Git deployment. Hosting membership is separate from product identity; do not add members, seats or paid upgrades automatically. Existing protection changes need authorization. Mixed apps provision/ship Cloudflare services first, then verify the web-to-service flow.
|
|
63
|
-
|
|
64
|
-
## Mobile build handoff
|
|
65
|
-
|
|
66
|
-
Use `ship --platform ios|android --profile <eas-profile>`. Set an explicit Expo owner and slug in static `app.json`; project creation/linking stops for review and a commit. Subsequent builds check the linked identity, configure only public mobile keys, and use the pinned EAS CLI. A queued build returns a build-page link; repeat the same command to inspect that build without submitting another. Completed artifacts must match the selected project and source commit before returning a download URL. It does not submit to a store. Simulator builds cannot be submitted to TestFlight. Signed iOS builds require Apple credentials; Android APK builds can be installed directly.
|
|
67
|
-
|
|
68
|
-
## Acceptance and operating limits
|
|
69
|
-
|
|
70
|
-
Run relevant lint/types/Fallow, dependency audits, meaningful tests and actual runtime builds. Exercise browser flows, installed extension permissions, packaged desktop behavior and signed/native device flows where selected. Deployment or HTTP 200 alone does not establish product completion.
|
|
71
|
-
|
|
72
|
-
Verify anonymous rejection at primary/deployment URLs, permitted-user login, denied-user and cross-tenant behavior. Verify selected private files, realtime reconnect/replay, duplicate jobs/webhooks, bounded AI, purchase/restore/refund, email/push and offline conflicts. Provider-authenticated requests do not prove visitor login or app authorization. Protected automation may use Vercel curl or authorized origin-scoped Trusted Sources; never weaken protection for testing.
|
|
73
|
-
|
|
74
|
-
Record service quotas, maximum retries/concurrency/AI work, alert ownership and shutdown controls within the authorized budget. Test spikes, duplicate execution, partial deployment and backup restoration. Review migrations and compatibility before rollback; code rollback does not restore data.
|
|
75
|
-
|
|
76
|
-
## Operations and handoff
|
|
77
|
-
|
|
78
|
-
| Command | Boundary |
|
|
79
|
-
| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
80
|
-
| `register` | Stable app identity; generated apps register automatically. |
|
|
81
|
-
| `status --refresh` | Independently refresh provider state. |
|
|
82
|
-
| `manage` / `manage --local` | Provider overview / explicitly historical local view. |
|
|
83
|
-
| `adopt` | Verify active Vercel Git source/repository and record its checked release; no push/deploy. |
|
|
84
|
-
| `recover` | Reconcile current provider state after cloning; no invented historical tests/releases. |
|
|
85
|
-
| `verify` | Run meaningful root `test:live` with actual URL/release and source/provider checks. |
|
|
86
|
-
| `rollback --release <id> --data-compatible` | Restore recorded code after compatibility review; no migration reversal/data restore. |
|
|
87
|
-
|
|
88
|
-
Open the actual app URL or installable artifact and exercise acceptance. Maintain the application's existing `docs/verification.md`: exact versions, source/release, repository, provider identity, audience, configured versus tested integrations, reproducible results and remaining actions. Refresh after changes; acceptance becomes stale when production changes. After rollback, restore matching clean source before verifying.
|
|
89
|
-
|
|
90
|
-
Committed manifests preserve identity. Ignored `.anhedral/` receipts are local history; back them up when needed. Before removing an interrupted shared lock, confirm no active process and inspect provider state. Maintain alerts, dependencies, costs and tested recovery. Recurring monitoring requires an authorized schedule. Release artifacts need exact contents, secret checks and integrity verification; never replace published version bytes.
|
|
91
|
-
|
|
92
|
-
## Evidence and maintenance
|
|
93
|
-
|
|
94
|
-
Before release, check the exact candidate's runtime, current dependency advisories, remote CI, installed-plugin and selected provider/native acceptance. Unresolved high-severity production audit failures block shipping. Keep dated results with release/test artifacts. Update this guide when commands, lifecycle or acceptance requirements change, and regenerate its bundled plugin copy.
|
|
95
|
-
|
|
96
|
-
### Interrupted local delivery locks
|
|
97
|
-
|
|
98
|
-
Use `anhedral recover --lock [directory]` only after an interrupted command. This releases a lock only when its recorded process is proven dead on the same host. It never replays provider operations or deletes delivery receipts. Inspect status and receipts before retrying. Live, foreign, malformed, and uncertain locks are preserved. A leftover `.anhedral/ship.guard` requires manual inspection; the CLI cannot safely infer its ownership. Do not combine local lock recovery with `--provider` or `--refresh`.
|