anhedral 0.11.1 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +126 -69
- package/dist/bin.js +48 -493
- package/dist/capabilities.d.ts +3 -3
- package/dist/capability-contract.js +4 -0
- package/dist/cli-arguments.d.ts +8 -0
- package/dist/cli-arguments.js +32 -0
- package/dist/cli-commands.d.ts +3 -0
- package/dist/cli-commands.js +114 -0
- package/dist/cli-delivery.d.ts +3 -0
- package/dist/cli-delivery.js +172 -0
- package/dist/cli-output.js +231 -205
- package/dist/delivery-evidence.d.ts +62 -0
- package/dist/delivery-evidence.js +186 -0
- package/dist/delivery.d.ts +3 -40
- package/dist/delivery.js +4 -181
- package/dist/dependencies.d.ts +1 -0
- package/dist/dependencies.js +2 -0
- package/dist/mobile-delivery.d.ts +21 -44
- package/dist/mobile-delivery.js +127 -80
- package/dist/provider-auth.js +3 -3
- package/dist/scaffold/documentation.js +1 -0
- package/dist/scaffold/stream.d.ts +2 -0
- package/dist/scaffold/stream.js +114 -0
- package/dist/service-readers.js +1 -1
- package/dist/services-command.js +8 -6
- package/dist/ship.d.ts +15 -15
- package/dist/stack-registry.d.ts +4 -2
- package/dist/stack-registry.js +16 -0
- package/dist/transaction-lock.d.ts +15 -0
- package/dist/transaction-lock.js +227 -0
- package/dist/transaction.js +2 -208
- package/dist/vercel-project.d.ts +101 -0
- package/dist/vercel-project.js +305 -0
- package/dist/vercel.d.ts +3 -36
- package/dist/vercel.js +3 -300
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/software-factory.md +528 -0
- package/docs/stack-standard.md +196 -121
- package/docs/verification.md +444 -0
- package/package.json +3 -6
- package/docs/cli-design.md +0 -67
- package/docs/delivery-workflow.md +0 -98
- package/docs/plugin-ui.md +0 -102
- package/docs/provider-configuration.md +0 -116
- package/docs/void-verification.md +0 -185
package/README.md
CHANGED
|
@@ -4,86 +4,155 @@
|
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
##
|
|
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.
|
|
28
|
+
|
|
29
|
+
## Defaults
|
|
30
|
+
|
|
31
|
+
Plain `anhedral init my-app` creates a Vinext web application. It includes no database, application identity provider, billing, email or analytics service.
|
|
32
|
+
|
|
33
|
+
| Area | Default |
|
|
34
|
+
| ------------- | ----------------------------------------------------------------------------------------------- |
|
|
35
|
+
| Application | Vinext and React on Cloudflare Workers |
|
|
36
|
+
| UI | TypeScript, Tailwind, shadcn/ui conventions and Lucide |
|
|
37
|
+
| Workspace | pnpm workspaces and Turborepo, even for one application |
|
|
38
|
+
| Tooling | Shared TypeScript and ESLint configuration packages; root checks and dependency audit |
|
|
39
|
+
| Delivery | Void for supported Cloudflare selections |
|
|
40
|
+
| Source | Deployable code in `apps/*`, reusable code in `packages/*` |
|
|
41
|
+
| Configuration | One root `anhedral.json` and `pnpm-lock.yaml`; secrets and local delivery history stay separate |
|
|
42
|
+
|
|
43
|
+
The registry has four foundation entries: `workspace`, `typescript`, `eslint` and `ui`. The first three accompany every project; the shared UI foundation accompanies web applications.
|
|
44
|
+
|
|
45
|
+
## Choose the applications
|
|
46
|
+
|
|
47
|
+
Combine these flags after `anhedral init my-app`. Vinext and Next.js are alternatives; web, API, mobile, desktop and extension applications can otherwise coexist.
|
|
48
|
+
|
|
49
|
+
| Selection | Generates |
|
|
50
|
+
| ----------------------------- | ----------------------------------------------------------------------------------- |
|
|
51
|
+
| Default, or `--vinext` | Vinext web application on Cloudflare Workers |
|
|
52
|
+
| `--next` | Native Next.js web application on Vercel |
|
|
53
|
+
| `--next --hosting=cloudflare` | Next.js on Workers through OpenNext |
|
|
54
|
+
| `--hono` | Shared Hono API Worker with OpenAPI/Zod contracts |
|
|
55
|
+
| `--expo` | Expo/React Native, Expo Router, NativeWind and React Native Reusables configuration |
|
|
56
|
+
| `--electron` | Electron/React desktop application, Vite and packaging configuration |
|
|
57
|
+
| `--wxt` | WXT/React Chrome side-panel extension |
|
|
58
|
+
|
|
59
|
+
Explicit application flags replace the default application selection. `--expo` generates mobile alone; `--vinext --expo` selects both. If you select only add-ons, such as `--neon`, the resolver includes a default web application. Use web server routes for a web-only backend, or select Hono for an API shared by several clients.
|
|
60
|
+
|
|
61
|
+
## Choose data and identity
|
|
62
|
+
|
|
63
|
+
| Selection | Generates | Selection rule |
|
|
64
|
+
| --------------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
65
|
+
| `--d1` | Shared Drizzle/SQLite database package and migrations | Cloudflare runtime; alternative to Neon |
|
|
66
|
+
| `--neon` | Shared Drizzle/PostgreSQL package using Neon HTTP | Server required; separate direct migration connection |
|
|
67
|
+
| `--better-auth` | Auth factory, database schema and server auth routes | Adds D1 when no database is selected; can use Neon |
|
|
68
|
+
| `--clerk` | Managed web identity integration and/or backend authentication helper | Alternative to Better Auth; server required |
|
|
69
|
+
| `--local-data` | Device-local persistence interface | Implement platform adapters and synchronization |
|
|
70
|
+
|
|
71
|
+
Database code lives in `packages/db`, including schemas and explicit migration tooling. Browser and device clients call server endpoints. Hosting audience protection and application resource authorization are separate from selecting an identity provider.
|
|
72
|
+
|
|
73
|
+
## Choose services and integrations
|
|
74
|
+
|
|
75
|
+
These are optional foundations. The generated scope column distinguishes bindings and Workers from SDK factories and integration guidance.
|
|
76
|
+
|
|
77
|
+
| Selection | Purpose | Generated scope |
|
|
78
|
+
| ----------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
79
|
+
| `--r2` | Private files | R2 Worker binding and authorization guidance |
|
|
80
|
+
| `--kv` | Cache/configuration | Eventually consistent Worker binding |
|
|
81
|
+
| `--realtime` | WebSocket rooms | Separate Durable Object Worker; implement room authorization |
|
|
82
|
+
| `--neon-realtime` | Live PostgreSQL query results | Server/client factories and Drizzle adapter; adds Neon; manual branch activation |
|
|
83
|
+
| `--stream` | One-to-many live video | Cloudflare Stream WHIP/WHEP; server management factory; manual activation and product UI |
|
|
84
|
+
| `--queues` | Background jobs | Producer, consumer and dead-letter configuration; implement processing/idempotency |
|
|
85
|
+
| `--cron` | Scheduled work | Separate Worker with an hourly starter schedule |
|
|
86
|
+
| `--workflows` | Durable multi-step work | Separate Worker with a starter validation step |
|
|
87
|
+
| `--workers-ai` | Cloudflare inference | Worker AI binding; implement model calls |
|
|
88
|
+
| `--openai` | Direct OpenAI integration | Server SDK factory in `packages/ai` |
|
|
89
|
+
| `--ai-sdk` | AI streaming/provider abstraction | AI SDK exports with an OpenAI provider; alternative to `--openai` |
|
|
90
|
+
| `--resend` | Transactional email | Server SDK factory in `packages/email` |
|
|
91
|
+
| `--stripe` | Payments/subscriptions | Server SDK factory in `packages/billing` |
|
|
92
|
+
| `--revenuecat` | Cross-store entitlements | Integration guidance; explicitly requires `--stripe`; install platform SDKs |
|
|
93
|
+
| `--sentry` | Error/crash monitoring | Integration boundary and redaction fields; initialize platform SDKs |
|
|
94
|
+
| `--posthog` | Product analytics | Server analytics factory |
|
|
95
|
+
| `--basin` | Cloudflare analytical events | Private stream binding and event helper |
|
|
96
|
+
| `--styling` | Shared design tokens | Light/dark tokens and Tailwind preset; automatically included with Expo/WXT |
|
|
97
|
+
|
|
98
|
+
Live video (`--stream`), room messaging (`--realtime`) and live SQL (`--neon-realtime`) can coexist. See [live video setup and limits](docs/stack-standard.md#live-video-with-cloudflare-stream). PostHog and Basin can coexist with separate packages. Workers AI can accompany either AI SDK choice. Provider setup supports selected resources for Neon, Clerk, Resend, Stripe, RevenueCat, Sentry, PostHog and OpenAI; credentials, permissions and remaining owner steps are described in the [provider reference](docs/software-factory.md#provider-configuration).
|
|
99
|
+
|
|
100
|
+
### Composition rules
|
|
101
|
+
|
|
102
|
+
- Choose one web framework, one database and one identity provider. `--openai` and `--ai-sdk` are alternatives.
|
|
103
|
+
- Database/auth, Stream and Neon Realtime selections need a compatible server. For mobile with PostgreSQL, use `--expo --hono --neon`.
|
|
104
|
+
- Native Next.js/Vercel plus Worker-bound capabilities such as D1 or R2 automatically adds Hono on Cloudflare.
|
|
105
|
+
- Explicit OpenNext, Queues or Basin uses Wrangler for the Cloudflare workspace. Other supported Cloudflare selections use Void. `add` rejects changes that switch an existing engine or relocate runtime source.
|
|
106
|
+
- Neon Realtime requires Neon and manual Realtime configuration. RevenueCat requires an explicit Stripe selection.
|
|
107
|
+
|
|
108
|
+
Examples:
|
|
32
109
|
|
|
33
|
-
|
|
110
|
+
```sh
|
|
111
|
+
# Web with database-backed identity; Better Auth adds D1.
|
|
112
|
+
anhedral init my-app --better-auth
|
|
34
113
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
| Web on Cloudflare Workers | Default |
|
|
38
|
-
| Native Next.js on Vercel | `--next` |
|
|
39
|
-
| Mobile with Expo | `--expo` |
|
|
40
|
-
| Desktop with Electron | `--electron` |
|
|
41
|
-
| Browser extension with WXT | `--wxt` |
|
|
42
|
-
| Shared API with Hono | `--hono` |
|
|
114
|
+
# Web, shared API, mobile and PostgreSQL.
|
|
115
|
+
anhedral init my-app --vinext --hono --expo --neon
|
|
43
116
|
|
|
44
|
-
|
|
117
|
+
# Vercel web with a Cloudflare API and private files.
|
|
118
|
+
anhedral init my-app --next --r2
|
|
45
119
|
|
|
46
|
-
|
|
47
|
-
anhedral init my-app --
|
|
48
|
-
anhedral init mobile-app --expo
|
|
49
|
-
anhedral init product --next --hono --d1 --r2
|
|
50
|
-
anhedral registry list
|
|
51
|
-
anhedral registry view resend --json
|
|
120
|
+
# Live broadcasts with independent room messaging and SQL subscriptions.
|
|
121
|
+
anhedral init my-app --stream --neon-realtime --realtime
|
|
52
122
|
```
|
|
53
123
|
|
|
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:
|
|
124
|
+
Inspect the full catalog and preview later additions:
|
|
59
125
|
|
|
60
126
|
```sh
|
|
61
|
-
anhedral
|
|
62
|
-
anhedral
|
|
127
|
+
anhedral registry list
|
|
128
|
+
anhedral registry view resend --json
|
|
129
|
+
anhedral add resend --cwd my-app --dry-run --json
|
|
130
|
+
anhedral add resend --cwd my-app
|
|
63
131
|
```
|
|
64
132
|
|
|
65
|
-
|
|
133
|
+
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
134
|
|
|
67
|
-
##
|
|
135
|
+
## Build and deliver
|
|
68
136
|
|
|
69
|
-
Implement
|
|
137
|
+
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
138
|
|
|
71
139
|
```sh
|
|
72
|
-
anhedral auth
|
|
73
140
|
anhedral auth --status --json
|
|
141
|
+
anhedral doctor --providers --json
|
|
142
|
+
# Select the intended account and audience, then commit source/configuration.
|
|
74
143
|
anhedral connect --audience private --allow-email owner@example.com
|
|
144
|
+
git add .
|
|
145
|
+
git commit -m "Implement application and delivery configuration"
|
|
75
146
|
anhedral ship --dry-run --json
|
|
76
147
|
anhedral ship --json
|
|
77
148
|
anhedral verify --json
|
|
78
149
|
```
|
|
79
150
|
|
|
80
|
-
Replace the example
|
|
151
|
+
Replace the example member with the intended user. Private Cloudflare hosting requires Zero Trust and scoped Access permissions; native Vercel uses its own connect options in the factory. Implement a meaningful `test:live` script before `verify`. 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.
|
|
81
152
|
|
|
82
|
-
|
|
153
|
+
Cloudflare and Vercel have automated delivery and provider evidence checks. Mixed delivery runs Cloudflare before Vercel and can partially succeed. Expo shipping returns verified EAS build artifacts; store submission is separate. Electron and extension projects include local build/package tooling, with signing and distribution handled through their platform workflows.
|
|
83
154
|
|
|
84
|
-
|
|
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.
|
|
155
|
+
Use the [stack standard](docs/stack-standard.md) for destinations, compatibility, migration ownership, environment files and the remaining implementation requirements for every option. Exact dependency versions live in the [source catalog](https://github.com/anhedral/anhedral-cli/blob/main/src/dependencies.ts).
|
|
87
156
|
|
|
88
157
|
## Use with Codex
|
|
89
158
|
|
|
@@ -96,40 +165,28 @@ Select **Try now**, or start with:
|
|
|
96
165
|
|
|
97
166
|
> Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.
|
|
98
167
|
|
|
99
|
-
The plugin guides
|
|
168
|
+
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.
|
|
169
|
+
|
|
170
|
+
## Read next
|
|
100
171
|
|
|
101
|
-
|
|
172
|
+
| Document | Use it to answer |
|
|
173
|
+
| -------------------------------------------- | ------------------------------------------------------------------------ |
|
|
174
|
+
| [Stack standard](docs/stack-standard.md) | What should the application contain, and how should it fit together? |
|
|
175
|
+
| [Software factory](docs/software-factory.md) | How do I turn a brief into a tested, delivered and maintainable product? |
|
|
102
176
|
|
|
103
|
-
|
|
177
|
+
The [verification record](docs/verification.md) keeps dated code reviews, provider evidence and remaining acceptance gaps together. Provider setup, CLI behavior, dashboard development and the release process are sections of the software factory.
|
|
104
178
|
|
|
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)
|
|
179
|
+
Use `anhedral --help` and `anhedral help <command>` for command options. `--cwd` selects the project; `--json` produces structured output. Use its [provider configuration](docs/software-factory.md#provider-configuration), [CLI behavior](docs/software-factory.md#cli-behavior), [Codex dashboard](docs/software-factory.md#project-dashboard) and [release process](docs/software-factory.md#maintain-and-release-the-cli) sections for details.
|
|
110
180
|
|
|
111
|
-
##
|
|
181
|
+
## Work on the CLI
|
|
112
182
|
|
|
113
183
|
```sh
|
|
114
184
|
pnpm install --frozen-lockfile
|
|
185
|
+
pnpm build
|
|
186
|
+
node dist/bin.js init ../my-test-app --dry-run --json
|
|
115
187
|
pnpm test:all
|
|
116
|
-
pnpm test:integration
|
|
117
188
|
```
|
|
118
189
|
|
|
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 |
|
|
190
|
+
`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
191
|
|
|
135
|
-
|
|
192
|
+
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).
|