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.
- package/README.md +50 -170
- package/assets/patches/LICENSE.braces +21 -0
- package/assets/patches/LICENSE.node-forge +50 -0
- package/assets/patches/audit-deps.mjs +167 -0
- package/assets/patches/braces@3.0.3.patch +127 -0
- package/assets/patches/node-forge@1.4.0.patch +41 -0
- package/dist/auth-schema.js +3 -3
- package/dist/bin.js +15 -11
- package/dist/capabilities.d.ts +4 -4
- package/dist/capabilities.js +6 -2
- package/dist/capability-contract.js +22 -5
- package/dist/catalog-model.d.ts +24 -0
- package/dist/catalog-model.js +1 -0
- package/dist/catalog-registration.d.ts +16 -0
- package/dist/catalog-registration.js +22 -0
- package/dist/catalog-snapshot.d.ts +5 -0
- package/dist/catalog-snapshot.js +97 -0
- package/dist/cli-arguments.js +1 -1
- package/dist/cli-output.js +27 -2
- package/dist/cloudflare.d.ts +7 -1
- package/dist/cloudflare.js +36 -6
- package/dist/command-schema.js +49 -5
- package/dist/delivery.d.ts +10 -3
- package/dist/delivery.js +154 -37
- package/dist/dependencies.d.ts +24 -0
- package/dist/dependencies.js +48 -0
- package/dist/dependency-patches.d.ts +7 -0
- package/dist/dependency-patches.js +125 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +2 -0
- package/dist/inspector-model.d.ts +9 -1
- package/dist/integration-service-readers.d.ts +13 -0
- package/dist/integration-service-readers.js +173 -0
- package/dist/lifecycle.d.ts +0 -1
- package/dist/lifecycle.js +0 -1
- package/dist/neon-service-data.d.ts +8 -0
- package/dist/neon-service-data.js +117 -0
- package/dist/pnpm-policy.d.ts +2 -2
- package/dist/pnpm-policy.js +19 -45
- package/dist/project-catalog.d.ts +41 -0
- package/dist/project-catalog.js +288 -0
- package/dist/project-config.d.ts +14 -0
- package/dist/project-config.js +89 -0
- package/dist/project-inspector.js +73 -17
- package/dist/project-lifecycle.d.ts +25 -0
- package/dist/project-lifecycle.js +57 -0
- package/dist/project-state.d.ts +5 -1
- package/dist/project-state.js +122 -16
- package/dist/provider-auth.js +2 -3
- package/dist/provider-readiness.js +27 -10
- package/dist/providers/adapters.js +4 -1
- package/dist/providers/api.d.ts +1 -0
- package/dist/providers/api.js +1 -0
- package/dist/providers/config.js +6 -8
- package/dist/providers/provision.js +1 -1
- package/dist/providers/recovery.d.ts +1 -1
- package/dist/providers/runtime.d.ts +1 -1
- package/dist/providers/runtime.js +46 -23
- package/dist/providers/state.d.ts +1 -2
- package/dist/providers/state.js +14 -54
- package/dist/provision.d.ts +9 -0
- package/dist/provision.js +30 -1
- package/dist/r2-service-data.d.ts +2 -0
- package/dist/r2-service-data.js +136 -0
- package/dist/readiness.js +9 -13
- package/dist/registry/add.js +64 -21
- package/dist/registry/commands.js +7 -9
- package/dist/registry/options.d.ts +1 -1
- package/dist/registry/options.js +4 -4
- package/dist/registry/receipt.d.ts +1 -0
- package/dist/registry/receipt.js +19 -4
- package/dist/registry/resolve.js +5 -1
- package/dist/registry/usage.js +1 -5
- package/dist/render.d.ts +2 -0
- package/dist/render.js +6 -0
- package/dist/runtime-policy.d.ts +4 -0
- package/dist/runtime-policy.js +21 -0
- package/dist/scaffold/bootstrap.js +2 -2
- package/dist/scaffold/compose.js +9 -3
- package/dist/scaffold/database.js +107 -25
- package/dist/scaffold/documentation.js +18 -13
- package/dist/scaffold/lint.d.ts +4 -0
- package/dist/scaffold/lint.js +56 -0
- package/dist/scaffold/neon-realtime.d.ts +2 -0
- package/dist/scaffold/neon-realtime.js +97 -0
- package/dist/scaffold/stack-documentation.js +1 -1
- package/dist/scaffold/void.d.ts +4 -0
- package/dist/scaffold/void.js +256 -0
- package/dist/scaffold/web.js +7 -1
- package/dist/scaffold/workspace.js +120 -29
- package/dist/service-deletion.d.ts +29 -0
- package/dist/service-deletion.js +195 -0
- package/dist/service-descriptor.d.ts +10 -0
- package/dist/service-descriptor.js +78 -0
- package/dist/service-model.d.ts +49 -0
- package/dist/service-model.js +8 -0
- package/dist/service-operations.d.ts +29 -0
- package/dist/service-operations.js +78 -0
- package/dist/service-readers.d.ts +8 -0
- package/dist/service-readers.js +247 -0
- package/dist/services-command.d.ts +39 -0
- package/dist/services-command.js +100 -0
- package/dist/ship.d.ts +36 -8
- package/dist/ship.js +39 -13
- package/dist/stack-registry.d.ts +4 -2
- package/dist/stack-registry.js +41 -11
- package/dist/standard.js +23 -4
- package/dist/transaction.d.ts +2 -0
- package/dist/transaction.js +10 -0
- package/dist/util.js +17 -2
- package/dist/vercel.d.ts +2 -0
- package/dist/vercel.js +69 -13
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/vinext.d.ts +1 -0
- package/dist/vinext.js +13 -1
- package/dist/void-execution.d.ts +10 -0
- package/dist/void-execution.js +94 -0
- package/dist/void-migrations.d.ts +6 -0
- package/dist/void-migrations.js +110 -0
- package/dist/void-state.d.ts +16 -0
- package/dist/void-state.js +65 -0
- package/dist/void.d.ts +3 -0
- package/dist/void.js +5 -0
- package/docs/cli-design.md +2 -2
- package/docs/plugin-ui.md +51 -10
- package/docs/provider-configuration.md +10 -11
- package/docs/software-factory.md +192 -0
- package/docs/stack-standard.md +142 -0
- package/docs/void-verification.md +185 -0
- package/package.json +23 -21
- package/assets/anhedral-mark.svg +0 -4
- package/assets/anhedral-stack-technical.svg +0 -322
- package/assets/anhedral-stack.svg +0 -322
- package/assets/anhedral.svg +0 -4
- package/assets/favicon.ico +0 -0
- package/assets/security/LICENSES.txt +0 -63
- package/assets/security/audit-deps.mjs +0 -300
- package/assets/security/braces-regression.mjs +0 -102
- package/assets/security/braces@3.0.3.patch +0 -285
- package/assets/security/decode-uri-component@0.2.2.patch +0 -149
- package/assets/security/decoder-regression.mjs +0 -37
- package/assets/security/forge-regression.mjs +0 -46
- package/assets/security/manifest.json +0 -53
- package/assets/security/node-forge@1.4.0.patch +0 -26
- package/dist/security-backports.d.ts +0 -3
- package/dist/security-backports.js +0 -26
- package/docs/application-stack-standard.md +0 -75
- package/docs/delivery-workflow.md +0 -97
package/README.md
CHANGED
|
@@ -4,216 +4,96 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/anhedral)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
|
|
7
|
-
Anhedral
|
|
7
|
+
Anhedral creates TypeScript application workspaces and helps deliver them to your own cloud accounts. Start with a web app, add the interfaces and services your product needs, and keep the source code, infrastructure, data and billing under your control.
|
|
8
8
|
|
|
9
|
-
|
|
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
|
-
|
|
11
|
+
## Start locally
|
|
17
12
|
|
|
18
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
46
|
-
|
|
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
|
-
|
|
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
|
-
|
|
29
|
+
## Choose what to generate
|
|
85
30
|
|
|
86
|
-
|
|
31
|
+
An explicit selection chooses the requested applications; include the web option when you want web alongside another interface.
|
|
87
32
|
|
|
88
|
-
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
Use additions after initialization:
|
|
43
|
+
Inspect available services and preview additions:
|
|
93
44
|
|
|
94
45
|
```sh
|
|
95
|
-
anhedral
|
|
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
|
-
|
|
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
|
-

|
|
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
|
-
|
|
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
|
-
|
|
159
|
-
anhedral
|
|
160
|
-
anhedral
|
|
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
|
-
|
|
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
|
-
|
|
176
|
-
|
|
177
|
-
|
|
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
|
-
|
|
73
|
+
Select **Try now**, or start with:
|
|
194
74
|
|
|
195
|
-
|
|
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
|
|
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
|
-
##
|
|
79
|
+
## Read next
|
|
200
80
|
|
|
201
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+
}
|