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.
Files changed (46) hide show
  1. package/README.md +126 -69
  2. package/dist/bin.js +48 -493
  3. package/dist/capabilities.d.ts +3 -3
  4. package/dist/capability-contract.js +4 -0
  5. package/dist/cli-arguments.d.ts +8 -0
  6. package/dist/cli-arguments.js +32 -0
  7. package/dist/cli-commands.d.ts +3 -0
  8. package/dist/cli-commands.js +114 -0
  9. package/dist/cli-delivery.d.ts +3 -0
  10. package/dist/cli-delivery.js +172 -0
  11. package/dist/cli-output.js +231 -205
  12. package/dist/delivery-evidence.d.ts +62 -0
  13. package/dist/delivery-evidence.js +186 -0
  14. package/dist/delivery.d.ts +3 -40
  15. package/dist/delivery.js +4 -181
  16. package/dist/dependencies.d.ts +1 -0
  17. package/dist/dependencies.js +2 -0
  18. package/dist/mobile-delivery.d.ts +21 -44
  19. package/dist/mobile-delivery.js +127 -80
  20. package/dist/provider-auth.js +3 -3
  21. package/dist/scaffold/documentation.js +1 -0
  22. package/dist/scaffold/stream.d.ts +2 -0
  23. package/dist/scaffold/stream.js +114 -0
  24. package/dist/service-readers.js +1 -1
  25. package/dist/services-command.js +8 -6
  26. package/dist/ship.d.ts +15 -15
  27. package/dist/stack-registry.d.ts +4 -2
  28. package/dist/stack-registry.js +16 -0
  29. package/dist/transaction-lock.d.ts +15 -0
  30. package/dist/transaction-lock.js +227 -0
  31. package/dist/transaction.js +2 -208
  32. package/dist/vercel-project.d.ts +101 -0
  33. package/dist/vercel-project.js +305 -0
  34. package/dist/vercel.d.ts +3 -36
  35. package/dist/vercel.js +3 -300
  36. package/dist/version.d.ts +1 -1
  37. package/dist/version.js +1 -1
  38. package/docs/software-factory.md +528 -0
  39. package/docs/stack-standard.md +196 -121
  40. package/docs/verification.md +444 -0
  41. package/package.json +3 -6
  42. package/docs/cli-design.md +0 -67
  43. package/docs/delivery-workflow.md +0 -98
  44. package/docs/plugin-ui.md +0 -102
  45. package/docs/provider-configuration.md +0 -116
  46. package/docs/void-verification.md +0 -185
package/README.md CHANGED
@@ -4,86 +4,155 @@
4
4
  [![npm](https://img.shields.io/npm/v/anhedral)](https://www.npmjs.com/package/anhedral)
5
5
  [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
6
6
 
7
- Anhedral scaffolds source code, guides authentication, then provisions, configures, and deploys the supported stack wherever provider APIs allow.
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
- You own the code, provider accounts, infrastructure, data, and billing. The CLI provides the foundation and delivery tools; application features remain development work. Anhedral offers feature development and ongoing maintenance for businesses that want that work delivered for them.
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
- ## Get started
11
+ ## Start locally
12
12
 
13
- Supported Cloudflare workspaces use Void 0.27.0 and require Node.js 24.21.0+ and pnpm 10.34.5. Explicit OpenNext, Queues and Basin selections use Wrangler. Other workspace profiles require Node.js 22.13+ on 22.x or Node.js 24+. Initialize on Linux, macOS, or WSL.
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
- # Preview the stack without creating project files or cloud resources
18
+ # Inspect the default selection; no writes or network requests.
21
19
  anhedral init my-app --dry-run --json
22
20
 
23
- # Generate a project and start development
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
- You can also run the CLI with `pnpm dlx anhedral@latest`. Initialization downloads the upstream shadcn starter and installs dependencies; it does not create cloud resources or deploy your app.
30
-
31
- ## Choose your stack
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
- The default is **Vinext, React, TypeScript, Tailwind, shadcn/ui, and Lucide on Cloudflare Workers**, organized as a pnpm/Turborepo monorepo.
110
+ ```sh
111
+ # Web with database-backed identity; Better Auth adds D1.
112
+ anhedral init my-app --better-auth
34
113
 
35
- | Application | Option |
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
- Add capabilities when needed: D1 or Neon for data, Better Auth or Clerk for identity, R2 for files, and selected AI, billing, email, analytics, or background services.
117
+ # Vercel web with a Cloudflare API and private files.
118
+ anhedral init my-app --next --r2
45
119
 
46
- ```sh
47
- anhedral init my-app --d1 --better-auth
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
- Optional `--neon-realtime` adds Neon live SQL foundations with separate server/client exports in `packages/neon-realtime`; it selects Neon and needs a server runtime. `--realtime` remains Cloudflare Durable Object WebSocket rooms. Neon Realtime is beta: enable the intended branch, allowed origins and secret manually, then implement authenticated, scoped query sealing and subscriptions. Initialization does not provision or verify Realtime. See the [stack standard](docs/stack-standard.md#neon-realtime).
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 add resend stripe --cwd my-app --dry-run --json
62
- anhedral add resend stripe --cwd my-app
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
- See the [stack standard](docs/stack-standard.md) for supported combinations and architecture guidance.
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
- ## Authenticate and ship
135
+ ## Build and deliver
68
136
 
69
- Implement your app, configure its selected services, review migrations, and commit the source before delivery. The generated README explains the remaining setup. Run these commands from your project directory.
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 email with the intended member. Private Workers hosting requires Cloudflare Zero Trust and the necessary Access permissions. Authentication does not establish every provisioning permission or complete service setup.
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
- 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.
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
- 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.
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 stack selection, feature development, setup, and verification. Its optional inspector displays local stack, setup, and recorded delivery evidence. It does not monitor live health or perform provisioning when opened. The CLI also works independently.
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
- ## Commands and documentation
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
- Use `anhedral --help` or `anhedral help <command>` for options and examples. `--cwd` selects a project; `--json` provides structured output.
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 usage](docs/cli-design.md)
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
- ## Development and contributions
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
- The root test command reuses a verified inspector runtime or installs its frozen dependencies and builds it when missing/stale. Preparing that runtime requires Node 22.13+ on 22.x or Node 24+; older CLI test lanes consume the verified CI runtime artifact. For inspector-specific checks, run `pnpm --dir plugins/codex/inspector install --frozen-lockfile` and `pnpm plugin:check`. Development builds require matching CLI and plugin versions; they do not update installed releases automatically.
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
- Run CLI commands from the repository root. `pnpm plugin:build`, `pnpm plugin:check` and `pnpm plugin:preview` delegate to the inspector application. The inspector owns its own dependencies and lockfile. Its build copies the bundled server and dashboard into `plugins/codex/distribution/runtime`; release packaging includes only the distribution directory. Shared project and provider logic stays in `src` so the CLI and plugin use the same implementation.
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).