anhedral 0.11.0 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/README.md +50 -170
  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 +15 -11
  9. package/dist/capabilities.d.ts +4 -4
  10. package/dist/capabilities.js +6 -2
  11. package/dist/capability-contract.js +22 -5
  12. package/dist/catalog-model.d.ts +24 -0
  13. package/dist/catalog-model.js +1 -0
  14. package/dist/catalog-registration.d.ts +16 -0
  15. package/dist/catalog-registration.js +22 -0
  16. package/dist/catalog-snapshot.d.ts +5 -0
  17. package/dist/catalog-snapshot.js +97 -0
  18. package/dist/cli-arguments.js +1 -1
  19. package/dist/cli-output.js +27 -2
  20. package/dist/cloudflare.d.ts +7 -1
  21. package/dist/cloudflare.js +36 -6
  22. package/dist/command-schema.js +49 -5
  23. package/dist/delivery.d.ts +10 -3
  24. package/dist/delivery.js +154 -37
  25. package/dist/dependencies.d.ts +24 -0
  26. package/dist/dependencies.js +48 -0
  27. package/dist/dependency-patches.d.ts +7 -0
  28. package/dist/dependency-patches.js +125 -0
  29. package/dist/index.d.ts +3 -0
  30. package/dist/index.js +2 -0
  31. package/dist/inspector-model.d.ts +9 -1
  32. package/dist/integration-service-readers.d.ts +13 -0
  33. package/dist/integration-service-readers.js +173 -0
  34. package/dist/lifecycle.d.ts +0 -1
  35. package/dist/lifecycle.js +0 -1
  36. package/dist/neon-service-data.d.ts +8 -0
  37. package/dist/neon-service-data.js +117 -0
  38. package/dist/pnpm-policy.d.ts +2 -2
  39. package/dist/pnpm-policy.js +19 -45
  40. package/dist/project-catalog.d.ts +41 -0
  41. package/dist/project-catalog.js +288 -0
  42. package/dist/project-config.d.ts +14 -0
  43. package/dist/project-config.js +89 -0
  44. package/dist/project-inspector.js +73 -17
  45. package/dist/project-lifecycle.d.ts +25 -0
  46. package/dist/project-lifecycle.js +57 -0
  47. package/dist/project-state.d.ts +5 -1
  48. package/dist/project-state.js +122 -16
  49. package/dist/provider-auth.js +2 -3
  50. package/dist/provider-readiness.js +27 -10
  51. package/dist/providers/adapters.js +4 -1
  52. package/dist/providers/api.d.ts +1 -0
  53. package/dist/providers/api.js +1 -0
  54. package/dist/providers/config.js +6 -8
  55. package/dist/providers/provision.js +1 -1
  56. package/dist/providers/recovery.d.ts +1 -1
  57. package/dist/providers/runtime.d.ts +1 -1
  58. package/dist/providers/runtime.js +46 -23
  59. package/dist/providers/state.d.ts +1 -2
  60. package/dist/providers/state.js +14 -54
  61. package/dist/provision.d.ts +9 -0
  62. package/dist/provision.js +30 -1
  63. package/dist/r2-service-data.d.ts +2 -0
  64. package/dist/r2-service-data.js +136 -0
  65. package/dist/readiness.js +9 -13
  66. package/dist/registry/add.js +64 -21
  67. package/dist/registry/commands.js +7 -9
  68. package/dist/registry/options.d.ts +1 -1
  69. package/dist/registry/options.js +4 -4
  70. package/dist/registry/receipt.d.ts +1 -0
  71. package/dist/registry/receipt.js +19 -4
  72. package/dist/registry/resolve.js +5 -1
  73. package/dist/registry/usage.js +1 -5
  74. package/dist/render.d.ts +2 -0
  75. package/dist/render.js +6 -0
  76. package/dist/runtime-policy.d.ts +4 -0
  77. package/dist/runtime-policy.js +21 -0
  78. package/dist/scaffold/bootstrap.js +2 -2
  79. package/dist/scaffold/compose.js +9 -3
  80. package/dist/scaffold/database.js +107 -25
  81. package/dist/scaffold/documentation.js +18 -13
  82. package/dist/scaffold/lint.d.ts +4 -0
  83. package/dist/scaffold/lint.js +56 -0
  84. package/dist/scaffold/neon-realtime.d.ts +2 -0
  85. package/dist/scaffold/neon-realtime.js +97 -0
  86. package/dist/scaffold/stack-documentation.js +1 -1
  87. package/dist/scaffold/void.d.ts +4 -0
  88. package/dist/scaffold/void.js +256 -0
  89. package/dist/scaffold/web.js +7 -1
  90. package/dist/scaffold/workspace.js +120 -29
  91. package/dist/service-deletion.d.ts +29 -0
  92. package/dist/service-deletion.js +195 -0
  93. package/dist/service-descriptor.d.ts +10 -0
  94. package/dist/service-descriptor.js +78 -0
  95. package/dist/service-model.d.ts +49 -0
  96. package/dist/service-model.js +8 -0
  97. package/dist/service-operations.d.ts +29 -0
  98. package/dist/service-operations.js +78 -0
  99. package/dist/service-readers.d.ts +8 -0
  100. package/dist/service-readers.js +247 -0
  101. package/dist/services-command.d.ts +39 -0
  102. package/dist/services-command.js +100 -0
  103. package/dist/ship.d.ts +36 -8
  104. package/dist/ship.js +39 -13
  105. package/dist/stack-registry.d.ts +4 -2
  106. package/dist/stack-registry.js +41 -11
  107. package/dist/standard.js +23 -4
  108. package/dist/transaction.d.ts +2 -0
  109. package/dist/transaction.js +10 -0
  110. package/dist/util.js +17 -2
  111. package/dist/vercel.d.ts +2 -0
  112. package/dist/vercel.js +69 -13
  113. package/dist/version.d.ts +1 -1
  114. package/dist/version.js +1 -1
  115. package/dist/vinext.d.ts +1 -0
  116. package/dist/vinext.js +13 -1
  117. package/dist/void-execution.d.ts +10 -0
  118. package/dist/void-execution.js +94 -0
  119. package/dist/void-migrations.d.ts +6 -0
  120. package/dist/void-migrations.js +110 -0
  121. package/dist/void-state.d.ts +16 -0
  122. package/dist/void-state.js +65 -0
  123. package/dist/void.d.ts +3 -0
  124. package/dist/void.js +5 -0
  125. package/docs/cli-design.md +2 -2
  126. package/docs/plugin-ui.md +51 -10
  127. package/docs/provider-configuration.md +10 -11
  128. package/docs/software-factory.md +192 -0
  129. package/docs/stack-standard.md +142 -0
  130. package/docs/void-verification.md +185 -0
  131. package/package.json +23 -21
  132. package/assets/anhedral-mark.svg +0 -4
  133. package/assets/anhedral-stack-technical.svg +0 -322
  134. package/assets/anhedral-stack.svg +0 -322
  135. package/assets/anhedral.svg +0 -4
  136. package/assets/favicon.ico +0 -0
  137. package/assets/security/LICENSES.txt +0 -63
  138. package/assets/security/audit-deps.mjs +0 -300
  139. package/assets/security/braces-regression.mjs +0 -102
  140. package/assets/security/braces@3.0.3.patch +0 -285
  141. package/assets/security/decode-uri-component@0.2.2.patch +0 -149
  142. package/assets/security/decoder-regression.mjs +0 -37
  143. package/assets/security/forge-regression.mjs +0 -46
  144. package/assets/security/manifest.json +0 -53
  145. package/assets/security/node-forge@1.4.0.patch +0 -26
  146. package/dist/security-backports.d.ts +0 -3
  147. package/dist/security-backports.js +0 -26
  148. package/docs/application-stack-standard.md +0 -75
  149. package/docs/delivery-workflow.md +0 -97
package/README.md CHANGED
@@ -4,216 +4,96 @@
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 automatically wherever provider APIs allow. Application features, design, custom integrations and business workflows remain development work; Anhedral offers development and ongoing maintenance services for businesses that want that work delivered for them.
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
- 1. **Describe the app** — Anhedral clarifies its purpose, users and essential features.
10
- 2. **Choose the architecture** — Explain the stack decisions; default web apps use Vinext on Cloudflare Workers.
11
- 3. **Set up ownership** — Use your own source repository and provider accounts; configure only the selected services.
12
- 4. **Build the app** — Implement the requested features, data, authentication and integrations.
13
- 5. **Check and ship** — Run checks, deploy, open the real URL and verify the live user flows.
14
- 6. **Maintain it** — Keep architecture, deployment history and verification visible; update or roll back as needed.
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.
15
10
 
16
- You own the code, infrastructure, data and billing.
11
+ ## Start locally
17
12
 
18
- 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.
19
-
20
- ## Try it
21
-
22
- Use `anhedral help <command>` for focused options and examples. Human output shows concise outcomes and next steps; `--json` preserves the complete result for scripts. `--cwd` / `-c` selects a project, and `--quiet` / `-q` suppresses human output while retaining errors and JSON. [CLI behavior and design](docs/cli-design.md) explains the comparison with shadcn, GitHub CLI and uv, and the source preview contract.
23
-
24
- Use the CLI independently, or install the optional Codex plugin:
13
+ Use **Node.js 24.21.0 or newer** and **pnpm 10.34.5**. Initialize on Linux, macOS or WSL.
25
14
 
26
15
  ```sh
27
- codex plugin marketplace add anhedral/anhedral-cli
28
- codex plugin add anhedral@anhedral
29
- ```
30
-
31
- Select **Try now** in Codex. The plugin uses the CLI version pinned by its bundled registry. A local rebuild does not update an installed plugin; development versions require their matching local CLI and plugin.
32
-
33
- Starter prompt:
16
+ npm install --global anhedral
34
17
 
35
- > Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.
36
-
37
- 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.
38
-
39
- 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.
40
-
41
- ```sh
42
- # Inspect a plan first: no project files or cloud resources are created
43
- pnpm dlx anhedral@latest init my-app --dry-run --json
18
+ # Inspect the default selection; no writes or network requests.
19
+ anhedral init my-app --dry-run --json
44
20
 
45
- # Generate the default Vinext/Workers workspace
46
- pnpm dlx anhedral@latest init my-app
21
+ # Generate source, install dependencies and start development.
22
+ anhedral init my-app
47
23
  cd my-app
48
24
  pnpm dev
49
25
  ```
50
26
 
51
- 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.
52
-
53
- **If Anhedral is useful to you, [star the repository](https://github.com/anhedral/anhedral-cli) to help other developers discover it.**
54
-
55
- ## Initialize, authenticate and deliver
56
-
57
- Install the CLI with `npm install --global anhedral`, or run these commands through `pnpm dlx anhedral@latest`.
58
-
59
- ```sh
60
- anhedral init my-app --hono --d1 --better-auth --r2
61
- anhedral auth my-app
62
- anhedral auth my-app --status --json
63
- anhedral ship my-app --dry-run --json
64
- anhedral ship my-app --json
65
- ```
66
-
67
- `init` accepts a destination directory or initializes the current directory. Authentication requirements derive from the selected stack; Cloudflare requirements are deduplicated. Interactive authentication can open the supported Cloudflare, Vercel and Expo login flows. API-backed checks use credentials supplied through the environment; they do not read or print application secret files. Missing access and insufficient permissions remain explicit. A verified session or API endpoint does not establish every provisioning permission, the intended account connection or configured application secrets. Use the supported `connect` workflow to select hosting account, project and audience before delivery.
68
-
69
- `init` writes a nonsecret `anhedral.providers.json` for the selected integrations. Complete its account/resource choices before shipping. Adapters provision and configure Neon, Clerk, Resend, Stripe webhooks, RevenueCat apps, Sentry, PostHog and OpenAI project/service-account resources. Management access, provider eligibility and owner prerequisites remain explicit. See [provider configuration](docs/provider-configuration.md) for supported operations, credentials, runtime configuration, recovery and verification limits.
70
-
71
- Cloudflare `ship` runs checks before reconciling D1, R2, KV, Queue and private Basin stream resources. If provisioning changes tracked binding IDs, it stops before deployment: review and commit the configuration, then repeat `ship`. It never commits source automatically. Runtime credentials accompany the checked code deployment; Vercel receives the selected web runtime's production variables. In mixed projects default `ship` runs Cloudflare services before the Vercel web target; use `--provider cloudflare` or `--provider vercel` for an explicit target. Partial delivery is reported without an automatic cross-provider rollback. The operation journal records diagnostics; retries recheck prerequisites and use resource receipts rather than skipping recorded phases. Pending provider setup stops deployment. Authentication alone does not establish completed setup.
72
-
73
- For an Expo project with an explicit owner/slug in `app.json` and the required signing configuration:
74
-
75
- ```sh
76
- anhedral ship my-app --platform android --profile preview --json
77
- anhedral ship my-app --platform ios --profile simulator --json
78
- ```
79
-
80
- EAS project creation/linking stops for review and a source commit. Queued builds return their build-page link; repeat the same command to inspect the existing build without submitting another. Completed builds return their ID, artifact type and download URL after checking project and source identity. Android preview produces an APK; production normally produces an AAB. The simulator profile produces an iOS Simulator artifact, not a TestFlight upload. Production iOS builds require Apple signing credentials. No store submission is performed. Build success does not verify the app's feature behavior.
81
-
82
- Private provisioning receipts and credentials stay in ignored `.anhedral/` state. Inspect them with `anhedral integrations status my-app --json`; its output is redacted and read-only. `integrations recover` verifies an explicitly selected pending resource and writes only its local completion receipt. Legacy entries without descriptors, changed configuration, and missing one-time credentials remain blocked. See [provider configuration](docs/provider-configuration.md) before attempting recovery or moving machines.
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.
83
28
 
84
- For Better Auth, configure the primary server's ignored private runtime file with a generated secret of at least 32 characters and its HTTPS public origin; POSIX file permissions must be `0600`. Older Wrangler configs must remove same-named plain auth variables before secrets can be deployed. Review and apply the generated database migrations; resource provisioning does not establish application authorization or completed features.
29
+ ## Choose what to generate
85
30
 
86
- ## Choose your stack
31
+ An explicit selection chooses the requested applications; include the web option when you want web alongside another interface.
87
32
 
88
- The bundled stack registry drives composition of every supported stack part. Run `anhedral inspect --json` for read-only stack/setup/delivery evidence. Run `anhedral registry capabilities --json` for the implemented scope, local evidence, and owner prerequisites. Live provider acceptance remains separate; Electron/WXT distribution and plugin live readers are not automated, and Expo delivery returns EAS artifacts without store submission. Run `anhedral registry list` or `anhedral registry view better-auth --json` to inspect items, destinations, dependencies and selection constraints. `init --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
+ | Project | Command |
34
+ | ---------------------------------- | -------------------------------------------------- |
35
+ | Default web app | `anhedral init my-app` |
36
+ | Web with D1 and Better Auth | `anhedral init my-app --vinext --d1 --better-auth` |
37
+ | Web and shared API with PostgreSQL | `anhedral init my-app --vinext --hono --neon` |
38
+ | Native Next.js on Vercel | `anhedral init my-app --next` |
39
+ | Expo mobile app | `anhedral init my-app --expo` |
40
+ | Electron desktop app | `anhedral init my-app --electron` |
41
+ | WXT browser extension | `anhedral init my-app --wxt` |
89
42
 
90
- 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.
91
-
92
- Use additions after initialization:
43
+ Inspect available services and preview additions:
93
44
 
94
45
  ```sh
95
- anhedral add resend stripe --cwd my-app --dry-run --json
96
- anhedral add resend stripe --cwd my-app --diff
97
- anhedral add resend stripe --cwd my-app
98
- anhedral registry list --json
99
- anhedral registry capabilities --json
46
+ anhedral registry list
100
47
  anhedral registry view resend --json
48
+ anhedral add resend --cwd my-app --dry-run --json
49
+ anhedral add resend --cwd my-app
101
50
  ```
102
51
 
103
- 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.
104
-
105
- 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.
106
-
107
- ```sh
108
- pnpm dlx anhedral@latest init my-app
109
- pnpm dlx anhedral@latest init mobile-app --expo
110
- pnpm dlx anhedral@latest init product --next --expo --hono --neon --clerk --r2
111
- pnpm dlx anhedral@latest init --wxt
112
- ```
113
-
114
- To use a local checkout, run `pnpm build`, then `node dist/bin.js init <directory>`.
115
-
116
- ![Anhedral stack](assets/anhedral-stack.svg)
117
-
118
- Applications: `vinext`, `next`, `expo`, `electron`, `wxt`, `hono`.
119
-
120
- 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`.
121
-
122
- 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.
123
-
124
- 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.
125
-
126
- `--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.
127
-
128
- `--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.
129
-
130
- 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.
131
-
132
- 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.
133
-
134
- ## Control costs and runaway work
135
-
136
- 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**.
137
-
138
- | Common mistake | Basic instruction |
139
- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
140
- | 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. |
141
- | 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. |
142
- | 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. |
143
- | 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. |
144
- | 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. |
145
- | 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. |
146
- | Collecting unlimited logs, analytics or session recordings | Collect only necessary events, sample high-volume data, and limit retention and ingestion. Keep test traffic separate. |
147
- | 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. |
148
- | 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. |
149
- | Assuming code rollback restores data | Keep backups and test restoration. Document how to stop work, recover data and resume safely. |
150
-
151
- 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.
52
+ Generated entry points live in `apps/*`, shared code in `packages/*`, and Anhedral configuration in one root `anhedral.json`. Read the [source-only full-stack example](https://github.com/anhedral/anhedral-cli/tree/main/examples/full-stack) to see a larger project without creating services.
152
53
 
153
54
  ## Build and deliver
154
55
 
155
- 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.
56
+ Implement the product, configure selected integrations and review database migrations. Then use the [software factory](docs/software-factory.md) to check provider access, connect the intended account and audience, commit source, ship and verify real user flows.
156
57
 
157
58
  ```sh
158
- # Customer-account profile: review source/ignored secrets and commit the app first.
159
- anhedral repository my-app --create --json # Private GitHub repo when using this source workflow
160
- anhedral connect my-app --audience private --allow-email owner@example.com
161
- anhedral provision my-app --dry-run --json
162
- anhedral provision my-app --json
163
- # Apply reviewed migrations, configure secrets and implement the actual product.
164
- anhedral ship my-app --dry-run --json
165
- anhedral ship my-app --json
166
- anhedral verify my-app --json
167
- anhedral manage my-app --json
59
+ anhedral auth --status --json
60
+ anhedral doctor --providers --json
61
+ anhedral ship --dry-run --json
168
62
  ```
169
63
 
64
+ These commands help inspect readiness; actual shipping can create resources, apply reviewed deployment migrations and publish code. Provider permissions, account eligibility and usage charges still apply. A generated starter or successful deployment does not establish a working product.
170
65
 
171
- 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.
172
-
173
- Account discovery selects the sole accessible account; use `--account <id>` for multiple accounts. D1, private R2, KV and Queues are reconciled idempotently. Selected API integrations use the bounded adapters documented in [provider configuration](docs/provider-configuration.md). 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.
66
+ ## Use with Codex
174
67
 
175
- 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.
176
-
177
- 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.
178
-
179
- ## Inspect setup and compatibility
180
-
181
- The CLI supports `init`, `auth`, `new`, `add`, `registry`, `doctor`, `repository`, `register`, `connect`, `provision`, `ship`, `adopt`, `recover`, `status`, `manage`, `verify`, `rollback`, `integrations`, `--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.
182
-
183
- 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.
184
-
185
- 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.
186
-
187
- ## Use with ChatGPT and Codex
188
-
189
- The workflow follows the [Anhedral Application Stack & Delivery Standard](docs/application-stack-standard.md).
190
-
191
- Install the plugin with `codex plugin marketplace add anhedral/anhedral-cli`, then `codex plugin add anhedral@anhedral`. The marketplace pins an immutable plugin source tag containing the same self-contained runtime as the release ZIP. Released plugin ZIPs match the CLI version. The headless-first plugin includes an optional MCP-backed project inspector with Overview, Stack, Setup and Delivery sections; see [plugin UI development](docs/plugin-ui.md) for preview, packaging and host integration. A public ChatGPT listing requires separate submission.
68
+ ```sh
69
+ codex plugin marketplace add anhedral/anhedral-cli
70
+ codex plugin add anhedral@anhedral
71
+ ```
192
72
 
193
- Ask: **“Build a team request dashboard with Anhedral. Include sign-in, persistent requests, ownership, status updates, and filters. Implement and verify the complete app.”**
73
+ Select **Try now**, or start with:
194
74
 
195
- 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.
75
+ > Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.
196
76
 
197
- The plugin guides development toward an application with editable source in your accounts. Initialization generates a starter; delivery also requires feature implementation, provider access and live verification. A successful scaffold or build is not evidence of a working product.
77
+ The plugin guides implementation using the same stack and workflow. Its optional inspector shows project structure, setup, recorded delivery evidence and explicit service controls. Opening it does not deploy the app. The CLI works independently.
198
78
 
199
- ## Contributing and security
79
+ ## Read next
200
80
 
201
- 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-cli/blob/main/.github/CONTRIBUTING.md), the [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). Use [issues](https://github.com/anhedral/anhedral-cli/issues) for reproducible CLI problems and [private reporting](https://github.com/anhedral/anhedral-cli/security/advisories/new) for vulnerabilities.
81
+ | Document | Use it to answer |
82
+ | -------------------------------------------- | ------------------------------------------------------------------------ |
83
+ | [Stack standard](docs/stack-standard.md) | What should the application contain, and how should it fit together? |
84
+ | [Software factory](docs/software-factory.md) | How do I turn a brief into a tested, delivered and maintainable product? |
202
85
 
203
- ## Development
86
+ Use `anhedral --help` and `anhedral help <command>` for command options. `--cwd` selects the project; `--json` produces structured output. Detailed references cover [provider configuration](docs/provider-configuration.md), [CLI behavior](docs/cli-design.md) and the [Codex inspector](docs/plugin-ui.md).
204
87
 
205
- Match the CLI, plugin and registry versions when developing or reviewing changes. Unpublished changes require the locally built CLI and matching plugin rather than the public npm release. Local tests and packaged-artifact checks do not establish live provider acceptance or native plugin installation.
88
+ ## Work on the CLI
206
89
 
207
90
  ```sh
208
91
  pnpm install --frozen-lockfile
92
+ pnpm build
93
+ node dist/bin.js init ../my-test-app --dry-run --json
209
94
  pnpm test:all
210
- pnpm test:integration # Generate and validate fresh application workspaces
211
95
  ```
212
96
 
213
- The project inspector lives in `plugin-app/` with its own dependency lockfile and Node 22.13+/24 toolchain. Run `pnpm --dir plugin-app install --frozen-lockfile`, then `pnpm plugin:check`.
214
-
215
- Implementation lives in `src/`, plugin instructions in `plugins/anhedral/`, and validation in `scripts/` and `tests/`. `dist/` and `.artifacts/release/` are generated and ignored.
216
-
217
- 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.
97
+ `pnpm test:integration` installs and checks generated projects. Inspector development uses `pnpm plugin:build`, `pnpm plugin:check` and `pnpm plugin:preview`; its dependencies and lockfile live in `plugins/codex/inspector`. Building the checkout does not update an installed CLI or plugin. See the [contribution guide](https://github.com/anhedral/anhedral-cli/blob/main/.github/CONTRIBUTING.md) for the development and review process.
218
98
 
219
- 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.
99
+ Anhedral is open source under the [Apache License 2.0](LICENSE). Generated applications are source code that developers can customize and license for their products, preserving upstream notices. Report bugs in [issues](https://github.com/anhedral/anhedral-cli/issues) and vulnerabilities through [private security reporting](https://github.com/anhedral/anhedral-cli/security/advisories/new).
@@ -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
+ }