anhedral 0.10.1 → 0.11.1

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 (183) hide show
  1. package/README.md +79 -124
  2. package/assets/patches/LICENSE.braces +21 -0
  3. package/assets/patches/LICENSE.node-forge +50 -0
  4. package/assets/patches/audit-deps.mjs +167 -0
  5. package/assets/patches/braces@3.0.3.patch +127 -0
  6. package/assets/patches/node-forge@1.4.0.patch +41 -0
  7. package/dist/auth-schema.js +3 -3
  8. package/dist/bin.js +284 -163
  9. package/dist/capabilities.d.ts +4 -4
  10. package/dist/capabilities.js +6 -2
  11. package/dist/capability-contract.d.ts +47 -0
  12. package/dist/capability-contract.js +153 -0
  13. package/dist/catalog-model.d.ts +24 -0
  14. package/dist/catalog-model.js +1 -0
  15. package/dist/catalog-registration.d.ts +16 -0
  16. package/dist/catalog-registration.js +22 -0
  17. package/dist/catalog-snapshot.d.ts +5 -0
  18. package/dist/catalog-snapshot.js +97 -0
  19. package/dist/cli-arguments.d.ts +16 -0
  20. package/dist/cli-arguments.js +115 -0
  21. package/dist/cli-output.d.ts +8 -0
  22. package/dist/cli-output.js +236 -0
  23. package/dist/cloudflare.d.ts +14 -3
  24. package/dist/cloudflare.js +196 -36
  25. package/dist/command-schema.d.ts +21 -0
  26. package/dist/command-schema.js +418 -0
  27. package/dist/delivery.d.ts +12 -5
  28. package/dist/delivery.js +173 -39
  29. package/dist/dependencies.d.ts +24 -0
  30. package/dist/dependencies.js +48 -0
  31. package/dist/dependency-patches.d.ts +7 -0
  32. package/dist/dependency-patches.js +125 -0
  33. package/dist/index.d.ts +26 -1
  34. package/dist/index.js +17 -1
  35. package/dist/inspector-model.d.ts +123 -0
  36. package/dist/inspector-model.js +1 -0
  37. package/dist/integration-service-readers.d.ts +13 -0
  38. package/dist/integration-service-readers.js +173 -0
  39. package/dist/lifecycle-model.d.ts +15 -0
  40. package/dist/lifecycle-model.js +20 -0
  41. package/dist/lifecycle.d.ts +11 -0
  42. package/dist/lifecycle.js +91 -0
  43. package/dist/mobile-delivery.d.ts +100 -0
  44. package/dist/mobile-delivery.js +319 -0
  45. package/dist/neon-service-data.d.ts +8 -0
  46. package/dist/neon-service-data.js +117 -0
  47. package/dist/platforms/mobile.js +8 -5
  48. package/dist/pnpm-policy.d.ts +2 -2
  49. package/dist/pnpm-policy.js +19 -45
  50. package/dist/project-catalog.d.ts +41 -0
  51. package/dist/project-catalog.js +288 -0
  52. package/dist/project-config.d.ts +14 -0
  53. package/dist/project-config.js +89 -0
  54. package/dist/project-inspector.d.ts +4 -0
  55. package/dist/project-inspector.js +702 -0
  56. package/dist/project-lifecycle.d.ts +25 -0
  57. package/dist/project-lifecycle.js +57 -0
  58. package/dist/project-state.d.ts +22 -1
  59. package/dist/project-state.js +361 -27
  60. package/dist/provider-auth.d.ts +41 -0
  61. package/dist/provider-auth.js +209 -0
  62. package/dist/provider-readiness.js +27 -10
  63. package/dist/providers/adapters.d.ts +17 -0
  64. package/dist/providers/adapters.js +272 -0
  65. package/dist/providers/api.d.ts +29 -0
  66. package/dist/providers/api.js +253 -0
  67. package/dist/providers/config.d.ts +15 -0
  68. package/dist/providers/config.js +182 -0
  69. package/dist/providers/definitions.d.ts +318 -0
  70. package/dist/providers/definitions.js +127 -0
  71. package/dist/providers/provision.d.ts +24 -0
  72. package/dist/providers/provision.js +76 -0
  73. package/dist/providers/receipts.d.ts +20 -0
  74. package/dist/providers/receipts.js +66 -0
  75. package/dist/providers/recovery-verification.d.ts +7 -0
  76. package/dist/providers/recovery-verification.js +112 -0
  77. package/dist/providers/recovery.d.ts +30 -0
  78. package/dist/providers/recovery.js +34 -0
  79. package/dist/providers/runtime.d.ts +10 -0
  80. package/dist/providers/runtime.js +254 -0
  81. package/dist/providers/schema.d.ts +28 -0
  82. package/dist/providers/schema.js +49 -0
  83. package/dist/providers/state.d.ts +55 -0
  84. package/dist/providers/state.js +289 -0
  85. package/dist/provision.d.ts +10 -1
  86. package/dist/provision.js +91 -4
  87. package/dist/r2-service-data.d.ts +2 -0
  88. package/dist/r2-service-data.js +136 -0
  89. package/dist/readiness.js +9 -13
  90. package/dist/registry/add.d.ts +6 -0
  91. package/dist/registry/add.js +93 -22
  92. package/dist/registry/commands.d.ts +3 -2
  93. package/dist/registry/commands.js +52 -15
  94. package/dist/registry/options.d.ts +1 -1
  95. package/dist/registry/options.js +5 -4
  96. package/dist/registry/preview.d.ts +11 -0
  97. package/dist/registry/preview.js +91 -0
  98. package/dist/registry/receipt.d.ts +1 -0
  99. package/dist/registry/receipt.js +19 -4
  100. package/dist/registry/resolve.js +5 -1
  101. package/dist/registry/usage.d.ts +10 -0
  102. package/dist/registry/usage.js +18 -37
  103. package/dist/render.d.ts +2 -0
  104. package/dist/render.js +6 -0
  105. package/dist/runtime-policy.d.ts +4 -0
  106. package/dist/runtime-policy.js +21 -0
  107. package/dist/scaffold/auth.js +3 -19
  108. package/dist/scaffold/bootstrap.js +2 -2
  109. package/dist/scaffold/compose.js +9 -3
  110. package/dist/scaffold/database.js +107 -25
  111. package/dist/scaffold/documentation.js +18 -13
  112. package/dist/scaffold/lint.d.ts +4 -0
  113. package/dist/scaffold/lint.js +56 -0
  114. package/dist/scaffold/neon-realtime.d.ts +2 -0
  115. package/dist/scaffold/neon-realtime.js +97 -0
  116. package/dist/scaffold/stack-documentation.js +1 -1
  117. package/dist/scaffold/void.d.ts +4 -0
  118. package/dist/scaffold/void.js +256 -0
  119. package/dist/scaffold/web.js +7 -1
  120. package/dist/scaffold/workspace.js +127 -25
  121. package/dist/service-deletion.d.ts +29 -0
  122. package/dist/service-deletion.js +195 -0
  123. package/dist/service-descriptor.d.ts +10 -0
  124. package/dist/service-descriptor.js +78 -0
  125. package/dist/service-model.d.ts +49 -0
  126. package/dist/service-model.js +8 -0
  127. package/dist/service-operations.d.ts +29 -0
  128. package/dist/service-operations.js +78 -0
  129. package/dist/service-readers.d.ts +8 -0
  130. package/dist/service-readers.js +247 -0
  131. package/dist/services-command.d.ts +39 -0
  132. package/dist/services-command.js +100 -0
  133. package/dist/ship.d.ts +348 -0
  134. package/dist/ship.js +237 -0
  135. package/dist/stack-registry.d.ts +4 -2
  136. package/dist/stack-registry.js +48 -12
  137. package/dist/standard.d.ts +2 -1
  138. package/dist/standard.js +33 -14
  139. package/dist/transaction.d.ts +2 -0
  140. package/dist/transaction.js +10 -0
  141. package/dist/util.js +17 -2
  142. package/dist/vercel.d.ts +5 -3
  143. package/dist/vercel.js +96 -14
  144. package/dist/version.d.ts +1 -1
  145. package/dist/version.js +1 -1
  146. package/dist/vinext.d.ts +1 -0
  147. package/dist/vinext.js +13 -1
  148. package/dist/void-execution.d.ts +10 -0
  149. package/dist/void-execution.js +94 -0
  150. package/dist/void-migrations.d.ts +6 -0
  151. package/dist/void-migrations.js +110 -0
  152. package/dist/void-state.d.ts +16 -0
  153. package/dist/void-state.js +65 -0
  154. package/dist/void.d.ts +3 -0
  155. package/dist/void.js +5 -0
  156. package/docs/cli-design.md +67 -0
  157. package/docs/delivery-workflow.md +32 -17
  158. package/docs/plugin-ui.md +102 -0
  159. package/docs/provider-configuration.md +116 -0
  160. package/docs/stack-standard.md +175 -0
  161. package/docs/void-verification.md +185 -0
  162. package/package.json +29 -23
  163. package/assets/anhedral-cli-init-technical.svg +0 -322
  164. package/assets/anhedral-cli-init.svg +0 -322
  165. package/assets/anhedral-mark.svg +0 -4
  166. package/assets/anhedral.svg +0 -4
  167. package/assets/favicon.ico +0 -0
  168. package/assets/security/LICENSES.txt +0 -63
  169. package/assets/security/audit-deps.mjs +0 -300
  170. package/assets/security/braces-regression.mjs +0 -102
  171. package/assets/security/braces@3.0.3.patch +0 -285
  172. package/assets/security/decode-uri-component@0.2.2.patch +0 -149
  173. package/assets/security/decoder-regression.mjs +0 -37
  174. package/assets/security/forge-regression.mjs +0 -46
  175. package/assets/security/manifest.json +0 -53
  176. package/assets/security/node-forge@1.4.0.patch +0 -26
  177. package/dist/managed-hosting.d.ts +0 -49
  178. package/dist/managed-hosting.js +0 -373
  179. package/dist/security-backports.d.ts +0 -3
  180. package/dist/security-backports.js +0 -26
  181. package/docs/application-stack-standard.md +0 -104
  182. package/docs/managed-hosting-architecture.md +0 -87
  183. package/docs/sponsorships.md +0 -25
package/README.md CHANGED
@@ -1,180 +1,135 @@
1
- # Anhedral Init
1
+ # Anhedral
2
2
 
3
- [![CI](https://github.com/anhedral/anhedral-init/actions/workflows/ci.yml/badge.svg)](https://github.com/anhedral/anhedral-init/actions/workflows/ci.yml)
3
+ [![CI](https://github.com/anhedral/anhedral-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/anhedral/anhedral-cli/actions/workflows/ci.yml)
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
- 1. **Describe the app** — Anhedral clarifies its purpose, users and essential features.
8
- 2. **Choose the architecture** — Explain the stack decisions; default web apps use Vinext on Cloudflare Workers.
9
- 3. **Set up ownership** — Choose customer-account or managed hosting; set up only the accounts that profile requires.
10
- 4. **Build the app** — Implement the requested features, data, authentication and integrations.
11
- 5. **Check and ship** — Run checks, deploy, open the real URL and verify the live user flows.
12
- 6. **Maintain it** — Keep architecture, deployment history and verification visible; update or roll back as needed.
7
+ Anhedral scaffolds source code, guides authentication, then provisions, configures, and deploys the supported stack wherever provider APIs allow.
13
8
 
14
- You own the code, infrastructure, data and billing.
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.
15
10
 
16
- Anhedral initializes a Vinext, React, TypeScript, Tailwind, shadcn/ui and Lucide workspace for Cloudflare Workers. D1 + Drizzle, Better Auth and Workers AI are the defaults when persistence, identity or inference are needed. Native Next.js on Vercel and Neon/PostgreSQL remain deliberate options. Choose the application surfaces and provider starters your product needs; the generated source stays yours to edit.
11
+ ## Get started
17
12
 
18
- ## Try it
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.
19
14
 
20
- Install the plugin and select **Try now**. Use the CLI version pinned by its bundled registry. A local rewrite or ZIP does not update an installed plugin; unpublished development versions require their matching local CLI and skill.
21
-
22
- Starter prompt:
23
-
24
- > Create a new app with [@Anhedral](plugin://anhedral@anhedral). Start by asking me what it should do.
25
-
26
- Codex asks about the app, explains the stack, implements the product, configures selected services, and delivers into your authorized accounts. The CLI commands below are also available independently.
27
-
28
- Use Node.js 22.13+ on the 22.x line or Node.js 24+, with pnpm 10.34.5, for generated workspaces. Generate on Linux, macOS, or WSL.
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.
29
16
 
30
17
  ```sh
31
- # Inspect a plan first: no project files or cloud resources are created
32
- pnpm dlx anhedral@latest new my-app --dry-run --json
18
+ npm install --global anhedral
19
+
20
+ # Preview the stack without creating project files or cloud resources
21
+ anhedral init my-app --dry-run --json
33
22
 
34
- # Generate the default Vinext/Workers workspace
35
- pnpm dlx anhedral@latest new my-app
23
+ # Generate a project and start development
24
+ anhedral init my-app
36
25
  cd my-app
37
26
  pnpm dev
38
27
  ```
39
28
 
40
- The first command downloads the CLI through pnpm; the CLI's dry run performs no writes or network calls. Generation needs network access for the official shadcn bootstrap. The default selects Vinext on Cloudflare; add capabilities only when needed. Follow the generated README for provider setup, Worker builds, and preview deployment.
41
-
42
- **If Anhedral is useful to you, [star the repository](https://github.com/anhedral/anhedral-init) to help other developers discover it.**
43
-
44
- ## Sponsors
45
-
46
- ### Help keep Anhedral Init free and open source
47
-
48
- Anhedral Init is free and open source. Sponsorship helps fund ongoing development, maintenance, and documentation so more developers can build and deliver applications they own.
49
-
50
- **[♡ Become a sponsor](docs/sponsorships.md)**
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.
51
30
 
52
31
  ## Choose your stack
53
32
 
54
- The bundled stack registry drives composition of every supported stack part. Run `anhedral registry list` or `anhedral registry view better-auth --json` to inspect items, destinations, dependencies and selection constraints. `new --dry-run --json` includes the resolved dependency graph. Scaffolding installs recipes in dependency order into `apps/*` and `packages/*`, validates local workspace references and cycles, and writes `anhedral.registry.json` with recipe versions and the resulting workspace graph. The same catalog is bundled with the plugin at build time. Generated `docs/stack.md` lists the current resolved options, targets, environment names, required setup and verification; additions refresh it without rewriting the application README.
33
+ The default is **Vinext, React, TypeScript, Tailwind, shadcn/ui, and Lucide on Cloudflare Workers**, organized as a pnpm/Turborepo monorepo.
55
34
 
56
- Registry items are trusted recipes shipped in the CLI release: foundations, apps, services, shared packages and runtime integrations. They follow shadcn's source ownership and dependency composition practices; this catalog is an Anhedral schema, not a shadcn registry payload. Runtime-aware recipes coordinate bindings, manifests and auth routes across workspaces. Each registry entry owns its recipe, provider requirements, environment variables, bindings and composition rules. Resolved plans name the exact generated destinations, including runtime-dependent packages. Recipe versions follow the CLI release. The official shadcn bootstrap is pinned to 4.21.4; commit the generated source and lockfile to preserve the application artifact. Incremental `add` supports only the bundled catalog maintained and tested by Anhedral. External registries and customer-authored registry payloads are unsupported. Additions refuse to overwrite edited or untracked source; runtime relocation requires a deliberate migration.
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` |
57
43
 
58
- Use additions after initialization:
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.
59
45
 
60
46
  ```sh
61
- anhedral add my-app resend stripe --dry-run --json
62
- anhedral add my-app resend stripe
63
- anhedral registry list --json
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
64
51
  anhedral registry view resend --json
65
52
  ```
66
53
 
67
- Review the dry-run file list and conflicts, then run the same addition without `--dry-run`. A preview that needs a new web foundation reports `bootstrapRequired: true` and `filesChecked: false`; it describes the selection and targets without running the upstream generator or checking generated-file conflicts. The actual addition checks conflicts in an isolated transaction before committing files. `--skip-install` still resolves the lockfile; run `pnpm install --frozen-lockfile` afterward to prepare dependencies. Final installs run the bundled workspace's dependency preparation hooks, including WXT and Electron setup. Projects must have matching CLI versions and scaffold fingerprints; older projects and receipts containing external items need a deliberate migration. Existing provider identities stay intact, and no provider resources are created.
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/`.
68
57
 
69
- Application recipes start from the official **shadcn pnpm/Turborepo monorepo**. The default creates **Vinext + React + TypeScript + Tailwind + shadcn/ui + Lucide**, targeting **Cloudflare Workers**. Select additional apps and services only when needed.
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:
70
59
 
71
60
  ```sh
72
- pnpm dlx anhedral@latest new my-app
73
- pnpm dlx anhedral@latest new mobile-app --expo
74
- pnpm dlx anhedral@latest new product --next --expo --hono --neon --clerk --r2
75
- pnpm dlx anhedral@latest init --wxt
61
+ anhedral add resend stripe --cwd my-app --dry-run --json
62
+ anhedral add resend stripe --cwd my-app
76
63
  ```
77
64
 
78
- To use a local checkout, run `pnpm build`, then `node dist/bin.js new <directory>`.
79
-
80
- ![Anhedral CLI init stack](assets/anhedral-cli-init.svg)
81
-
82
- Applications: `vinext`, `next`, `expo`, `electron`, `wxt`, `hono`.
83
-
84
- Optional capabilities: `neon`, `d1`, `local-data`, `clerk`, `better-auth`, `r2`, `kv`, `realtime`, `queues`, `cron`, `workflows`, `openai`, `ai-sdk`, `workers-ai`, `resend`, `stripe`, `revenuecat`, `sentry`, `basin`, `posthog`, `styling`.
85
-
86
- Hono provides an OpenAPI Worker when a shared API is selected. Web-only endpoints belong in Next.js route handlers. Selecting Cloudflare bindings with native Vercel hosting adds a Hono API. Workers services live under `apps/*`, reusable code under `packages/*`. Mobile-only, desktop-only, extension-only and API-only selections remove the unused Next.js starter after the shadcn bootstrap.
87
-
88
- The stack standard prefers direct Neon serverless HTTP + Drizzle; Hyperdrive is optional for measured connection/latency needs or standard PostgreSQL drivers. D1 + Drizzle is the Worker-native SQLite option. Neon recipes use direct HTTP through the serverless driver on Workers and native Next.js. Interactive transactions require a reviewed WebSocket or PostgreSQL adapter. Use Neon’s non-pooled endpoint with Hyperdrive and disable correctness-sensitive query caching. Authentication is optional; Better Auth is preferred when identity is needed, and Clerk is a deliberate alternative. They are mutually exclusive. Better Auth requires an explicit database selection. Stripe is the web billing choice; RevenueCat is an optional addition for cross-store entitlements. Private files use R2 Worker bindings; clients never receive R2 credentials.
89
-
90
- `--next` selects native Next.js on Vercel; `--next --hosting=cloudflare` explicitly selects OpenNext on Workers. There is one framework path, including simple websites, with no separate static generator. For Vercel, Hobby is currently free for personal non-commercial use within limits, while commercial use needs an eligible existing plan. Other frameworks, specialized compute and source/CI platforms require deliberate project adaptations.
91
-
92
- `--dry-run --json` prints a plan without writes or network calls. `--skip-install` skips the final workspace installation; the official shadcn bootstrap still needs network access and can install dependencies. Generation resolves and retains a workspace lockfile. Commit it with the source.
65
+ See the [stack standard](docs/stack-standard.md) for supported combinations and architecture guidance.
93
66
 
94
- Generated projects include `dev`, `build`, `lint`, `typecheck`, `test`, `audit`, `audit:full`, and `check`, plus GitHub Actions PR checks. Fallow is part of the deterministic gate. Tests run in workspaces that define them; add meaningful product and integration tests as behavior is implemented.
67
+ ## Authenticate and ship
95
68
 
96
- Provider packages and services are **starters**, not finished product features. Generated READMEs identify the remaining setup: resource IDs, migrations, product authorization, webhooks, native adapters and runtime SDK initialization. Initialization does not create cloud resources, activate billing, or deploy. Respect existing account, budget, audience and release authorization. Request only missing approval for paid activation, material spending, architecture changes or release.
97
-
98
- ## Control costs and runaway work
99
-
100
- Anhedral's stack must make unexpected spending and runaway work difficult to trigger, easy to detect, and possible to stop. Choosing Vercel, Cloudflare, or another provider does not establish those protections. Treat the following as delivery requirements for each selected service; **the initializer does not automatically configure or verify all of them**.
101
-
102
- | Common mistake | Basic instruction |
103
- | --- | --- |
104
- | Assuming a free tier or budget alert caps spending | Check what each service charges for. Set available spending limits and alerts, allow for enforcement delays, and identify costs without a hard cap. |
105
- | Creating infinite loops in jobs, queues, schedules or alarms | Define a stopping condition, deadline and maximum amount of work. Keep job processing separate from enqueueing, and prevent overlapping scheduled runs. |
106
- | Retrying forever or processing the same job twice | Limit retries and concurrency, add backoff, and make repeated processing safe. Move failed jobs to a dead-letter queue for investigation before replay. |
107
- | Scanning an entire database or writing repeatedly on every request | Use indexed lookups, bounded pagination and batches. Measure storage operations per user action and remove unnecessary work. |
108
- | Letting public traffic trigger unlimited paid operations | Authorize expensive actions. Set user, tenant and total usage quotas for email, AI, uploads and background jobs; rate-limit public entry points. |
109
- | Assuming caching or DDoS protection eliminates traffic costs | Check request, bandwidth and image-processing charges. Optimize media, restrict transformations and protect direct access to origins. |
110
- | Collecting unlimited logs, analytics or session recordings | Collect only necessary events, sample high-volume data, and limit retention and ingestion. Keep test traffic separate. |
111
- | Testing with unrestricted production credentials | Separate environments and credentials. Mock paid services in routine tests and bound live test traffic. Review generated code and test failure paths before release. |
112
- | Discovering runaway usage only when the bill arrives | Monitor usage spikes and retries, assign an alert owner, and test an emergency stop for both web requests and background work. |
113
- | Assuming code rollback restores data | Keep backups and test restoration. Document how to stop work, recover data and resume safely. |
114
-
115
- Before delivery, record the budget and limits in the app's `docs/architecture.md`, and the tested controls, alert owner and recovery steps in `docs/verification.md`. Verify behavior under traffic spikes, duplicate jobs and service failures. Resolve exposure beyond the customer's authorized budget before enabling the workload.
116
-
117
- ## Build and deliver
118
-
119
- Default Vinext/Workers apps have `anhedral.project.json`; explicit Next.js/Vercel apps have `anhedral.web.json`. Customer-account delivery is supported: configure the customer's account, implement the app and verify its actual deployment.
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.
120
70
 
121
71
  ```sh
122
- # Customer-account profile: review source/ignored secrets and commit the app first.
123
- anhedral repository my-app --create --json # Private GitHub repo when using this source workflow
124
- anhedral connect my-app --audience private --allow-email owner@example.com
125
- anhedral provision my-app --dry-run --json
126
- anhedral provision my-app --json
127
- # Apply reviewed migrations, configure secrets and implement the actual product.
128
- anhedral ship my-app --dry-run --json
129
- anhedral ship my-app --json
130
- anhedral verify my-app --json
131
- anhedral manage my-app --json
72
+ anhedral auth
73
+ anhedral auth --status --json
74
+ anhedral connect --audience private --allow-email owner@example.com
75
+ anhedral ship --dry-run --json
76
+ anhedral ship --json
77
+ anhedral verify --json
132
78
  ```
133
79
 
134
- Anhedral-managed hosting is under implementation. Its intended profile uses Workers for Platforms, Anhedral sign-in, an app registry, durable source/build versions and private routing; customer Cloudflare/GitHub/Vercel accounts should not be prerequisites. GitHub connection/export is optional for this managed profile. The local foundation is not yet a deployed service, a verified managed URL or a promise of free hosting. The [managed-hosting contract](docs/managed-hosting-architecture.md) defines required accounts, paid activation, source/version storage and the planned agent CLI. Use the supported customer-account path when that is the agreed destination; do not silently substitute it for unavailable managed hosting.
135
-
136
- For explicit Next.js/Vercel, connect the intended customer scope and private audience with `--git`, run checks before an authorized source push, then `adopt --json` and `verify --json` after the actual production deployment. Use `ship` only when selecting CLI delivery rather than deploying the same Git change twice.
137
-
138
- Account discovery selects the sole accessible account; use `--account <id>` for multiple accounts. D1, private R2, KV and Queues are reconciled idempotently. Selected external providers use their actual tools. Private hosting requires Cloudflare Zero Trust and scoped Access permissions; protection covers the whole Worker before product deployment. Whole-Worker Access currently excludes WebSockets, which need a deliberate alternative access workflow.
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.
139
81
 
140
- Shipping requires a clean app source commit, runs checks, captures actual URLs and versions, and confirms 100% provider traffic. Failures preserve partial-operation evidence. `status --refresh` verifies current state. `rollback --release <id> --data-compatible` restores recorded code versions after schema/resource compatibility review; it does not restore data.
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.
141
83
 
142
- For a Git-triggered production release, run checks before pushing, then `adopt --json` after it becomes active instead of deploying the same commit again. Use `recover --json` after a fresh clone to reconcile current provider state; historical acceptance is not invented. `manage` produces a local overview from provider evidence. See the [delivery workflow](docs/delivery-workflow.md) for account setup, live verification and recovery.
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.
143
85
 
144
- ## Inspect setup and compatibility
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.
145
87
 
146
- The CLI supports `new`, `init`, `add`, `registry`, `doctor`, `repository`, `register`, `connect`, `provision`, `ship`, `adopt`, `recover`, `status`, `manage`, `verify`, `rollback`, `--help`, and `--version`. `anhedral doctor <directory> --json` checks registry provenance, generated targets, workspace dependencies and local setup requirements without writes. Add `--providers` for read-only tool/account readiness; production product behavior remains unverified. Use `anhedral --help` for options. Its JSON plan includes versioned setup requirements, and generated projects include `anhedral.setup.json`. Requirements do not imply that accounts or resources are configured. The CLI and plugin catalogs derive from `src/stack-registry.ts`; `pnpm build` refreshes the plugin's bundled registry and stack standard.
88
+ ## Use with Codex
147
89
 
148
- Requires Node.js 20.19+ in the 20 series or 22.12+ and pnpm 10.34.5. Pin the CLI version and commit the generated lockfile. The shadcn bootstrap version is pinned in `src/dependencies.ts`; review its upgrades and generated output before use.
149
-
150
- Initialize from Linux, macOS, or WSL. Native Windows initialization fails before writes because upstream shadcn currently resolves monorepo component paths outside the project; planning and `doctor` remain portable. Generated projects include reviewed security backports for affected tooling dependencies, with verified patch and installed-package hashes and regression checks. Unknown advisories and modified patches remain blocking.
151
-
152
- ## Use with ChatGPT and Codex
153
-
154
- The workflow follows the [Anhedral Application Stack & Delivery Standard](docs/application-stack-standard.md).
90
+ ```sh
91
+ codex plugin marketplace add anhedral/anhedral-cli
92
+ codex plugin add anhedral@anhedral
93
+ ```
155
94
 
156
- Install the plugin with `codex plugin marketplace add anhedral/anhedral-init`, then `codex plugin add anhedral@anhedral`. Releases include a self-contained skill plugin ZIP matching the CLI version. A public ChatGPT listing requires separate submission.
95
+ Select **Try now**, or start with:
157
96
 
158
- Ask: **“Build a team request dashboard with Anhedral. Include sign-in, persistent requests, ownership, status updates, and filters. Implement and verify the complete app.”**
97
+ > Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.
159
98
 
160
- The plugin guides Codex through requirement inference, stack selection, CLI planning and generation, implementation, and verification. It records decisions in the app's `docs/architecture.md` and evidence in `docs/verification.md`. The CLI maintains deployment records and reads provider status. Provider access uses the tools and CLIs available in the session.
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.
161
100
 
162
- Anhedral carries one request through to a shipped product with editable source in your accounts. Initialization generates a starter; delivery also requires implementation, provider access and live verification.
101
+ ## Commands and documentation
163
102
 
164
- ## Contributing and security
103
+ Use `anhedral --help` or `anhedral help <command>` for options and examples. `--cwd` selects a project; `--json` provides structured output.
165
104
 
166
- Anhedral is maintainer-led, with a small contribution surface. Focused bug fixes, tests, and documentation corrections are welcome; discuss larger changes before implementation. See [contributing](https://github.com/anhedral/anhedral-init/blob/main/.github/CONTRIBUTING.md), the [code of conduct](https://github.com/anhedral/anhedral-init/blob/main/.github/CODE_OF_CONDUCT.md), and [security reporting](https://github.com/anhedral/anhedral-init/blob/main/.github/SECURITY.md). Use [issues](https://github.com/anhedral/anhedral-init/issues) for reproducible CLI problems and [private reporting](https://github.com/anhedral/anhedral-init/security/advisories/new) for vulnerabilities.
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)
167
110
 
168
- ## Development
111
+ ## Development and contributions
169
112
 
170
113
  ```sh
171
114
  pnpm install --frozen-lockfile
172
115
  pnpm test:all
173
- pnpm test:integration # Generate and validate fresh application workspaces
116
+ pnpm test:integration
174
117
  ```
175
118
 
176
- Implementation lives in `src/`, plugin instructions in `plugins/anhedral/`, and validation in `scripts/` and `tests/`. `dist/` and `.artifacts/release/` are generated and ignored.
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.
177
120
 
178
- Anhedral is open source under the [Apache License 2.0](LICENSE). Generated applications remain ordinary project source that their developers can customize and license for their products. Preserve applicable license notices for upstream code and dependencies.
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 |
179
134
 
180
- Generated projects run a full dependency audit through `pnpm audit:deps`. Reviewed backports for `braces`, `node-forge`, and `decode-uri-component` retain upstream findings and require exact patch hashes, installed-package hashes, and regression checks before accepting remediation. Adopt upstream fixed releases when available; unverified findings remain blocking.
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.
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2014-present, Jon Schlinkert.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
@@ -0,0 +1,50 @@
1
+ You may use the Forge project under the terms of either the BSD License or the
2
+ GNU General Public License (GPL) Version 2.
3
+
4
+ The BSD License is recommended for most projects. It is simple and easy to
5
+ understand and it places almost no restrictions on what you can do with the
6
+ Forge project.
7
+
8
+ If the GPL suits your project better you are also free to use Forge under
9
+ that license.
10
+
11
+ You don't have to do anything special to choose one license or the other and
12
+ you don't have to notify anyone which license you are using. You are free to
13
+ use this project in commercial projects as long as the copyright header is
14
+ left intact.
15
+
16
+ If you are a commercial entity and use this set of libraries in your
17
+ commercial software then reasonable payment to Digital Bazaar, if you can
18
+ afford it, is not required but is expected and would be appreciated. If this
19
+ library saves you time, then it's saving you money. The cost of developing
20
+ the Forge software was on the order of several hundred hours and tens of
21
+ thousands of dollars. We are attempting to strike a balance between helping
22
+ the development community while not being taken advantage of by lucrative
23
+ commercial entities for our efforts.
24
+
25
+ -------------------------------------------------------------------------------
26
+ New BSD License (3-clause)
27
+ Copyright (c) 2010, Digital Bazaar, Inc.
28
+ All rights reserved.
29
+
30
+ Redistribution and use in source and binary forms, with or without
31
+ modification, are permitted provided that the following conditions are met:
32
+ * Redistributions of source code must retain the above copyright
33
+ notice, this list of conditions and the following disclaimer.
34
+ * Redistributions in binary form must reproduce the above copyright
35
+ notice, this list of conditions and the following disclaimer in the
36
+ documentation and/or other materials provided with the distribution.
37
+ * Neither the name of Digital Bazaar, Inc. nor the
38
+ names of its contributors may be used to endorse or promote products
39
+ derived from this software without specific prior written permission.
40
+
41
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
42
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
43
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44
+ DISCLAIMED. IN NO EVENT SHALL DIGITAL BAZAAR BE LIABLE FOR ANY
45
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
46
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
49
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
50
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,167 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { lstatSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
3
+ import path from 'node:path';
4
+ import { spawnSync } from 'node:child_process';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ // Exact local mitigations; pnpm's frozen install applies and checks the patches.
8
+ // Runtime regression probes belong in the CLI repository's test:patch suite.
9
+ const patches = [
10
+ {
11
+ name: 'braces',
12
+ version: '3.0.3',
13
+ advisory: 'GHSA-vfj7-8cjw-p6xm',
14
+ sha256: '69bd65a37da4569ba0be8a044aa732ad7c2ebd5494d6076f966eb6df8a12756e',
15
+ },
16
+ {
17
+ name: 'node-forge',
18
+ version: '1.4.0',
19
+ advisory: 'GHSA-86w9-cpqp-85rv',
20
+ sha256: '2cbbff9183d2896f13da8c8655b8f598b0f24c9b7477e8230f9a313f806c239f',
21
+ },
22
+ ];
23
+ const severities = ['info', 'low', 'moderate', 'high', 'critical'];
24
+ const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
25
+ const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
26
+ const fail = (message) => {
27
+ throw new Error(message);
28
+ };
29
+ const readRegular = (file, maximum = 2 * 1024 * 1024) => {
30
+ const stat = lstatSync(file);
31
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > maximum)
32
+ fail('Expected a bounded regular file.');
33
+ return readFileSync(file);
34
+ };
35
+
36
+ /** Accept only exact advisory/version pairs whose reviewed patches are configured. */
37
+ export function verifyAuditReport(report, { status, patchedCoordinates = [] } = {}) {
38
+ if (
39
+ !object(report) ||
40
+ report.error ||
41
+ !object(report.advisories) ||
42
+ !object(report.metadata?.vulnerabilities)
43
+ )
44
+ fail('Incomplete pnpm audit report; no advisory exception was applied.');
45
+ const findings = Object.values(report.advisories);
46
+ const counts = Object.fromEntries(severities.map((severity) => [severity, 0]));
47
+ for (const finding of findings) {
48
+ if (
49
+ !object(finding) ||
50
+ !severities.includes(finding.severity) ||
51
+ typeof finding.module_name !== 'string' ||
52
+ !/^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$/.test(finding.github_advisory_id ?? '') ||
53
+ !Array.isArray(finding.findings) ||
54
+ !finding.findings.length ||
55
+ finding.findings.some(
56
+ (item) =>
57
+ !object(item) ||
58
+ typeof item.version !== 'string' ||
59
+ !item.version ||
60
+ !Array.isArray(item.paths) ||
61
+ !item.paths.length ||
62
+ item.paths.some((entry) => typeof entry !== 'string' || !entry),
63
+ )
64
+ )
65
+ fail('Incomplete advisory details; no advisory exception was applied.');
66
+ if (new Set(finding.findings.map((item) => item.version)).size !== finding.findings.length)
67
+ fail('Duplicate affected versions in advisory details.');
68
+ counts[finding.severity] += finding.findings.length;
69
+ }
70
+ for (const severity of severities) {
71
+ const count = report.metadata.vulnerabilities[severity];
72
+ if (!Number.isSafeInteger(count) || count < 0 || count !== counts[severity])
73
+ fail('Audit severity counts do not match its advisory details.');
74
+ }
75
+ if (status !== (findings.some((finding) => finding.severity !== 'info') ? 1 : 0))
76
+ fail('Unexpected pnpm audit exit status; inspect the raw report.');
77
+ const high = findings.filter((finding) => ['high', 'critical'].includes(finding.severity));
78
+ for (const finding of high) {
79
+ const patch = patches.find(
80
+ ({ name, version, advisory }) =>
81
+ finding.module_name === name &&
82
+ finding.github_advisory_id === advisory &&
83
+ finding.findings.every((item) => item.version === version),
84
+ );
85
+ if (finding.severity !== 'high' || !patch)
86
+ fail(
87
+ `Unaccepted high/critical advisory: ${finding.github_advisory_id} (${finding.module_name}).`,
88
+ );
89
+ }
90
+ for (const finding of high) {
91
+ const coordinate = `${finding.module_name}@${finding.findings[0].version}`;
92
+ if (!patchedCoordinates.includes(coordinate))
93
+ fail(`The ${finding.module_name} advisory requires its reviewed configured patch.`);
94
+ }
95
+ return {
96
+ exceptionApplied: high.length > 0,
97
+ acceptedAdvisories: high.map((finding) => finding.github_advisory_id),
98
+ vulnerabilities: counts,
99
+ };
100
+ }
101
+
102
+ export function runAuditGate(root = process.cwd()) {
103
+ root = realpathSync(root);
104
+ const executable = process.env.npm_execpath;
105
+ if (!executable) fail('Run this gate with pnpm run audit:deps.');
106
+ const run = (args) => {
107
+ const result = spawnSync(process.execPath, [executable, ...args], {
108
+ cwd: root,
109
+ env: process.env,
110
+ encoding: 'utf8',
111
+ timeout: 120000,
112
+ maxBuffer: 64 * 1024 * 1024,
113
+ });
114
+ if (result.error || result.signal || !Number.isInteger(result.status))
115
+ fail('pnpm audit command did not complete.');
116
+ return result;
117
+ };
118
+ const audit = run(['audit', '--json', '--audit-level', 'low']);
119
+ const reportFile = path.join(root, '.anhedral-audit-report.json');
120
+ const existingReport = lstatSync(reportFile, { throwIfNoEntry: false });
121
+ if (existingReport && (!existingReport.isFile() || existingReport.isSymbolicLink()))
122
+ fail('The raw audit report target must be a regular file.');
123
+ writeFileSync(reportFile, audit.stdout, { mode: 0o600 });
124
+ let report;
125
+ try {
126
+ report = JSON.parse(audit.stdout);
127
+ } catch {
128
+ fail('pnpm returned invalid audit JSON; inspect .anhedral-audit-report.json.');
129
+ }
130
+ // Validate the entire report before considering any exception.
131
+ const candidate = verifyAuditReport(report, {
132
+ status: audit.status,
133
+ patchedCoordinates: patches.map(({ name, version }) => `${name}@${version}`),
134
+ });
135
+ if (!candidate.exceptionApplied) return candidate;
136
+ const config = run(['config', 'get', 'patchedDependencies', '--json']);
137
+ if (config.status !== 0) fail('pnpm could not read the configured dependency patches.');
138
+ const configured = JSON.parse(config.stdout);
139
+ const patchedCoordinates = [];
140
+ for (const patch of patches) {
141
+ if (!candidate.acceptedAdvisories.includes(patch.advisory)) continue;
142
+ const coordinate = `${patch.name}@${patch.version}`;
143
+ const relative = `patches/${coordinate}.patch`;
144
+ if (
145
+ !object(configured) ||
146
+ typeof configured[coordinate] !== 'string' ||
147
+ path.resolve(root, configured[coordinate]) !== path.join(root, relative) ||
148
+ hash(readRegular(path.join(root, relative))) !== patch.sha256
149
+ )
150
+ fail(`The reviewed ${patch.name} patch is missing or changed or is not configured.`);
151
+ patchedCoordinates.push(coordinate);
152
+ }
153
+ const result = verifyAuditReport(report, { status: audit.status, patchedCoordinates });
154
+ console.log(
155
+ `Accepted only ${result.acceptedAdvisories.join('; ')} for configured local patches. Raw audit remains in .anhedral-audit-report.json.`,
156
+ );
157
+ return result;
158
+ }
159
+
160
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
161
+ try {
162
+ runAuditGate();
163
+ } catch (error) {
164
+ console.error(error.message);
165
+ process.exitCode = 1;
166
+ }
167
+ }