anhedral 0.10.1 → 0.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -124
- 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 +284 -163
- package/dist/capabilities.d.ts +4 -4
- package/dist/capabilities.js +6 -2
- package/dist/capability-contract.d.ts +47 -0
- package/dist/capability-contract.js +153 -0
- 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.d.ts +16 -0
- package/dist/cli-arguments.js +115 -0
- package/dist/cli-output.d.ts +8 -0
- package/dist/cli-output.js +236 -0
- package/dist/cloudflare.d.ts +14 -3
- package/dist/cloudflare.js +196 -36
- package/dist/command-schema.d.ts +21 -0
- package/dist/command-schema.js +418 -0
- package/dist/delivery.d.ts +12 -5
- package/dist/delivery.js +173 -39
- 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 +26 -1
- package/dist/index.js +17 -1
- package/dist/inspector-model.d.ts +123 -0
- package/dist/inspector-model.js +1 -0
- package/dist/integration-service-readers.d.ts +13 -0
- package/dist/integration-service-readers.js +173 -0
- package/dist/lifecycle-model.d.ts +15 -0
- package/dist/lifecycle-model.js +20 -0
- package/dist/lifecycle.d.ts +11 -0
- package/dist/lifecycle.js +91 -0
- package/dist/mobile-delivery.d.ts +100 -0
- package/dist/mobile-delivery.js +319 -0
- package/dist/neon-service-data.d.ts +8 -0
- package/dist/neon-service-data.js +117 -0
- package/dist/platforms/mobile.js +8 -5
- 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.d.ts +4 -0
- package/dist/project-inspector.js +702 -0
- package/dist/project-lifecycle.d.ts +25 -0
- package/dist/project-lifecycle.js +57 -0
- package/dist/project-state.d.ts +22 -1
- package/dist/project-state.js +361 -27
- package/dist/provider-auth.d.ts +41 -0
- package/dist/provider-auth.js +209 -0
- package/dist/provider-readiness.js +27 -10
- package/dist/providers/adapters.d.ts +17 -0
- package/dist/providers/adapters.js +272 -0
- package/dist/providers/api.d.ts +29 -0
- package/dist/providers/api.js +253 -0
- package/dist/providers/config.d.ts +15 -0
- package/dist/providers/config.js +182 -0
- package/dist/providers/definitions.d.ts +318 -0
- package/dist/providers/definitions.js +127 -0
- package/dist/providers/provision.d.ts +24 -0
- package/dist/providers/provision.js +76 -0
- package/dist/providers/receipts.d.ts +20 -0
- package/dist/providers/receipts.js +66 -0
- package/dist/providers/recovery-verification.d.ts +7 -0
- package/dist/providers/recovery-verification.js +112 -0
- package/dist/providers/recovery.d.ts +30 -0
- package/dist/providers/recovery.js +34 -0
- package/dist/providers/runtime.d.ts +10 -0
- package/dist/providers/runtime.js +254 -0
- package/dist/providers/schema.d.ts +28 -0
- package/dist/providers/schema.js +49 -0
- package/dist/providers/state.d.ts +55 -0
- package/dist/providers/state.js +289 -0
- package/dist/provision.d.ts +10 -1
- package/dist/provision.js +91 -4
- 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.d.ts +6 -0
- package/dist/registry/add.js +93 -22
- package/dist/registry/commands.d.ts +3 -2
- package/dist/registry/commands.js +52 -15
- package/dist/registry/options.d.ts +1 -1
- package/dist/registry/options.js +5 -4
- package/dist/registry/preview.d.ts +11 -0
- package/dist/registry/preview.js +91 -0
- 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.d.ts +10 -0
- package/dist/registry/usage.js +18 -37
- 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/auth.js +3 -19
- 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 +127 -25
- 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 +348 -0
- package/dist/ship.js +237 -0
- package/dist/stack-registry.d.ts +4 -2
- package/dist/stack-registry.js +48 -12
- package/dist/standard.d.ts +2 -1
- package/dist/standard.js +33 -14
- package/dist/transaction.d.ts +2 -0
- package/dist/transaction.js +10 -0
- package/dist/util.js +17 -2
- package/dist/vercel.d.ts +5 -3
- package/dist/vercel.js +96 -14
- 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 +67 -0
- package/docs/delivery-workflow.md +32 -17
- package/docs/plugin-ui.md +102 -0
- package/docs/provider-configuration.md +116 -0
- package/docs/stack-standard.md +175 -0
- package/docs/void-verification.md +185 -0
- package/package.json +29 -23
- package/assets/anhedral-cli-init-technical.svg +0 -322
- package/assets/anhedral-cli-init.svg +0 -322
- package/assets/anhedral-mark.svg +0 -4
- 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/managed-hosting.d.ts +0 -49
- package/dist/managed-hosting.js +0 -373
- package/dist/security-backports.d.ts +0 -3
- package/dist/security-backports.js +0 -26
- package/docs/application-stack-standard.md +0 -104
- package/docs/managed-hosting-architecture.md +0 -87
- package/docs/sponsorships.md +0 -25
package/README.md
CHANGED
|
@@ -1,180 +1,135 @@
|
|
|
1
|
-
# Anhedral
|
|
1
|
+
# Anhedral
|
|
2
2
|
|
|
3
|
-
[](https://github.com/anhedral/anhedral-cli/actions/workflows/ci.yml)
|
|
4
4
|
[](https://www.npmjs.com/package/anhedral)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
2. **Choose the architecture** — Explain the stack decisions; default web apps use Vinext on Cloudflare Workers.
|
|
9
|
-
3. **Set up ownership** — Choose customer-account or managed hosting; set up only the accounts that profile requires.
|
|
10
|
-
4. **Build the app** — Implement the requested features, data, authentication and integrations.
|
|
11
|
-
5. **Check and ship** — Run checks, deploy, open the real URL and verify the live user flows.
|
|
12
|
-
6. **Maintain it** — Keep architecture, deployment history and verification visible; update or roll back as needed.
|
|
7
|
+
Anhedral scaffolds source code, guides authentication, then provisions, configures, and deploys the supported stack wherever provider APIs allow.
|
|
13
8
|
|
|
14
|
-
You own the code, infrastructure, data and billing.
|
|
9
|
+
You own the code, provider accounts, infrastructure, data, and billing. The CLI provides the foundation and delivery tools; application features remain development work. Anhedral offers feature development and ongoing maintenance for businesses that want that work delivered for them.
|
|
15
10
|
|
|
16
|
-
|
|
11
|
+
## Get started
|
|
17
12
|
|
|
18
|
-
|
|
13
|
+
Supported Cloudflare workspaces use Void 0.27.0 and require Node.js 24.21.0+ and pnpm 10.34.5. Explicit OpenNext, Queues and Basin selections use Wrangler. Other workspace profiles require Node.js 22.13+ on 22.x or Node.js 24+. Initialize on Linux, macOS, or WSL.
|
|
19
14
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
Starter prompt:
|
|
23
|
-
|
|
24
|
-
> Create a new app with [@Anhedral](plugin://anhedral@anhedral). Start by asking me what it should do.
|
|
25
|
-
|
|
26
|
-
Codex asks about the app, explains the stack, implements the product, configures selected services, and delivers into your authorized accounts. The CLI commands below are also available independently.
|
|
27
|
-
|
|
28
|
-
Use Node.js 22.13+ on the 22.x line or Node.js 24+, with pnpm 10.34.5, for generated workspaces. Generate on Linux, macOS, or WSL.
|
|
15
|
+
Void owns Cloudflare provisioning, secret uploads and deployment. Anhedral retains stack composition, shared packages, customer ownership and independent release/product verification. Explicit OpenNext, Queues and Basin profiles use Anhedral’s Wrangler delivery path. Initialization creates source without deploying it.
|
|
29
16
|
|
|
30
17
|
```sh
|
|
31
|
-
|
|
32
|
-
|
|
18
|
+
npm install --global anhedral
|
|
19
|
+
|
|
20
|
+
# Preview the stack without creating project files or cloud resources
|
|
21
|
+
anhedral init my-app --dry-run --json
|
|
33
22
|
|
|
34
|
-
# Generate
|
|
35
|
-
|
|
23
|
+
# Generate a project and start development
|
|
24
|
+
anhedral init my-app
|
|
36
25
|
cd my-app
|
|
37
26
|
pnpm dev
|
|
38
27
|
```
|
|
39
28
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
**If Anhedral is useful to you, [star the repository](https://github.com/anhedral/anhedral-init) to help other developers discover it.**
|
|
43
|
-
|
|
44
|
-
## Sponsors
|
|
45
|
-
|
|
46
|
-
### Help keep Anhedral Init free and open source
|
|
47
|
-
|
|
48
|
-
Anhedral Init is free and open source. Sponsorship helps fund ongoing development, maintenance, and documentation so more developers can build and deliver applications they own.
|
|
49
|
-
|
|
50
|
-
**[♡ Become a sponsor](docs/sponsorships.md)**
|
|
29
|
+
You can also run the CLI with `pnpm dlx anhedral@latest`. Initialization downloads the upstream shadcn starter and installs dependencies; it does not create cloud resources or deploy your app.
|
|
51
30
|
|
|
52
31
|
## Choose your stack
|
|
53
32
|
|
|
54
|
-
The
|
|
33
|
+
The default is **Vinext, React, TypeScript, Tailwind, shadcn/ui, and Lucide on Cloudflare Workers**, organized as a pnpm/Turborepo monorepo.
|
|
55
34
|
|
|
56
|
-
|
|
35
|
+
| Application | Option |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| Web on Cloudflare Workers | Default |
|
|
38
|
+
| Native Next.js on Vercel | `--next` |
|
|
39
|
+
| Mobile with Expo | `--expo` |
|
|
40
|
+
| Desktop with Electron | `--electron` |
|
|
41
|
+
| Browser extension with WXT | `--wxt` |
|
|
42
|
+
| Shared API with Hono | `--hono` |
|
|
57
43
|
|
|
58
|
-
|
|
44
|
+
Add capabilities when needed: D1 or Neon for data, Better Auth or Clerk for identity, R2 for files, and selected AI, billing, email, analytics, or background services.
|
|
59
45
|
|
|
60
46
|
```sh
|
|
61
|
-
anhedral
|
|
62
|
-
anhedral
|
|
63
|
-
anhedral
|
|
47
|
+
anhedral init my-app --d1 --better-auth
|
|
48
|
+
anhedral init mobile-app --expo
|
|
49
|
+
anhedral init product --next --hono --d1 --r2
|
|
50
|
+
anhedral registry list
|
|
64
51
|
anhedral registry view resend --json
|
|
65
52
|
```
|
|
66
53
|
|
|
67
|
-
|
|
54
|
+
Optional `--neon-realtime` adds Neon live SQL foundations with separate server/client exports in `packages/neon-realtime`; it selects Neon and needs a server runtime. `--realtime` remains Cloudflare Durable Object WebSocket rooms. Neon Realtime is beta: enable the intended branch, allowed origins and secret manually, then implement authenticated, scoped query sealing and subscriptions. Initialization does not provision or verify Realtime. See the [stack standard](docs/stack-standard.md#neon-realtime).
|
|
55
|
+
|
|
56
|
+
The project keeps Anhedral metadata in one committed root `anhedral.json`, with named sections for identity, stack selection, registry provenance, integrations and selected hosting. Credentials and delivery history remain in ignored runtime files and `.anhedral/`.
|
|
68
57
|
|
|
69
|
-
|
|
58
|
+
The bundled registry contains recipes maintained and tested by Anhedral. Generated source belongs to your project and stays editable. External registries are unsupported. Preview additions before applying them:
|
|
70
59
|
|
|
71
60
|
```sh
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
pnpm dlx anhedral@latest new product --next --expo --hono --neon --clerk --r2
|
|
75
|
-
pnpm dlx anhedral@latest init --wxt
|
|
61
|
+
anhedral add resend stripe --cwd my-app --dry-run --json
|
|
62
|
+
anhedral add resend stripe --cwd my-app
|
|
76
63
|
```
|
|
77
64
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-

|
|
81
|
-
|
|
82
|
-
Applications: `vinext`, `next`, `expo`, `electron`, `wxt`, `hono`.
|
|
83
|
-
|
|
84
|
-
Optional capabilities: `neon`, `d1`, `local-data`, `clerk`, `better-auth`, `r2`, `kv`, `realtime`, `queues`, `cron`, `workflows`, `openai`, `ai-sdk`, `workers-ai`, `resend`, `stripe`, `revenuecat`, `sentry`, `basin`, `posthog`, `styling`.
|
|
85
|
-
|
|
86
|
-
Hono provides an OpenAPI Worker when a shared API is selected. Web-only endpoints belong in Next.js route handlers. Selecting Cloudflare bindings with native Vercel hosting adds a Hono API. Workers services live under `apps/*`, reusable code under `packages/*`. Mobile-only, desktop-only, extension-only and API-only selections remove the unused Next.js starter after the shadcn bootstrap.
|
|
87
|
-
|
|
88
|
-
The stack standard prefers direct Neon serverless HTTP + Drizzle; Hyperdrive is optional for measured connection/latency needs or standard PostgreSQL drivers. D1 + Drizzle is the Worker-native SQLite option. Neon recipes use direct HTTP through the serverless driver on Workers and native Next.js. Interactive transactions require a reviewed WebSocket or PostgreSQL adapter. Use Neon’s non-pooled endpoint with Hyperdrive and disable correctness-sensitive query caching. Authentication is optional; Better Auth is preferred when identity is needed, and Clerk is a deliberate alternative. They are mutually exclusive. Better Auth requires an explicit database selection. Stripe is the web billing choice; RevenueCat is an optional addition for cross-store entitlements. Private files use R2 Worker bindings; clients never receive R2 credentials.
|
|
89
|
-
|
|
90
|
-
`--next` selects native Next.js on Vercel; `--next --hosting=cloudflare` explicitly selects OpenNext on Workers. There is one framework path, including simple websites, with no separate static generator. For Vercel, Hobby is currently free for personal non-commercial use within limits, while commercial use needs an eligible existing plan. Other frameworks, specialized compute and source/CI platforms require deliberate project adaptations.
|
|
91
|
-
|
|
92
|
-
`--dry-run --json` prints a plan without writes or network calls. `--skip-install` skips the final workspace installation; the official shadcn bootstrap still needs network access and can install dependencies. Generation resolves and retains a workspace lockfile. Commit it with the source.
|
|
65
|
+
See the [stack standard](docs/stack-standard.md) for supported combinations and architecture guidance.
|
|
93
66
|
|
|
94
|
-
|
|
67
|
+
## Authenticate and ship
|
|
95
68
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
## Control costs and runaway work
|
|
99
|
-
|
|
100
|
-
Anhedral's stack must make unexpected spending and runaway work difficult to trigger, easy to detect, and possible to stop. Choosing Vercel, Cloudflare, or another provider does not establish those protections. Treat the following as delivery requirements for each selected service; **the initializer does not automatically configure or verify all of them**.
|
|
101
|
-
|
|
102
|
-
| Common mistake | Basic instruction |
|
|
103
|
-
| --- | --- |
|
|
104
|
-
| Assuming a free tier or budget alert caps spending | Check what each service charges for. Set available spending limits and alerts, allow for enforcement delays, and identify costs without a hard cap. |
|
|
105
|
-
| Creating infinite loops in jobs, queues, schedules or alarms | Define a stopping condition, deadline and maximum amount of work. Keep job processing separate from enqueueing, and prevent overlapping scheduled runs. |
|
|
106
|
-
| Retrying forever or processing the same job twice | Limit retries and concurrency, add backoff, and make repeated processing safe. Move failed jobs to a dead-letter queue for investigation before replay. |
|
|
107
|
-
| Scanning an entire database or writing repeatedly on every request | Use indexed lookups, bounded pagination and batches. Measure storage operations per user action and remove unnecessary work. |
|
|
108
|
-
| Letting public traffic trigger unlimited paid operations | Authorize expensive actions. Set user, tenant and total usage quotas for email, AI, uploads and background jobs; rate-limit public entry points. |
|
|
109
|
-
| Assuming caching or DDoS protection eliminates traffic costs | Check request, bandwidth and image-processing charges. Optimize media, restrict transformations and protect direct access to origins. |
|
|
110
|
-
| Collecting unlimited logs, analytics or session recordings | Collect only necessary events, sample high-volume data, and limit retention and ingestion. Keep test traffic separate. |
|
|
111
|
-
| Testing with unrestricted production credentials | Separate environments and credentials. Mock paid services in routine tests and bound live test traffic. Review generated code and test failure paths before release. |
|
|
112
|
-
| Discovering runaway usage only when the bill arrives | Monitor usage spikes and retries, assign an alert owner, and test an emergency stop for both web requests and background work. |
|
|
113
|
-
| Assuming code rollback restores data | Keep backups and test restoration. Document how to stop work, recover data and resume safely. |
|
|
114
|
-
|
|
115
|
-
Before delivery, record the budget and limits in the app's `docs/architecture.md`, and the tested controls, alert owner and recovery steps in `docs/verification.md`. Verify behavior under traffic spikes, duplicate jobs and service failures. Resolve exposure beyond the customer's authorized budget before enabling the workload.
|
|
116
|
-
|
|
117
|
-
## Build and deliver
|
|
118
|
-
|
|
119
|
-
Default Vinext/Workers apps have `anhedral.project.json`; explicit Next.js/Vercel apps have `anhedral.web.json`. Customer-account delivery is supported: configure the customer's account, implement the app and verify its actual deployment.
|
|
69
|
+
Implement your app, configure its selected services, review migrations, and commit the source before delivery. The generated README explains the remaining setup. Run these commands from your project directory.
|
|
120
70
|
|
|
121
71
|
```sh
|
|
122
|
-
|
|
123
|
-
anhedral
|
|
124
|
-
anhedral connect
|
|
125
|
-
anhedral
|
|
126
|
-
anhedral
|
|
127
|
-
|
|
128
|
-
anhedral ship my-app --dry-run --json
|
|
129
|
-
anhedral ship my-app --json
|
|
130
|
-
anhedral verify my-app --json
|
|
131
|
-
anhedral manage my-app --json
|
|
72
|
+
anhedral auth
|
|
73
|
+
anhedral auth --status --json
|
|
74
|
+
anhedral connect --audience private --allow-email owner@example.com
|
|
75
|
+
anhedral ship --dry-run --json
|
|
76
|
+
anhedral ship --json
|
|
77
|
+
anhedral verify --json
|
|
132
78
|
```
|
|
133
79
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
For explicit Next.js/Vercel, connect the intended customer scope and private audience with `--git`, run checks before an authorized source push, then `adopt --json` and `verify --json` after the actual production deployment. Use `ship` only when selecting CLI delivery rather than deploying the same Git change twice.
|
|
137
|
-
|
|
138
|
-
Account discovery selects the sole accessible account; use `--account <id>` for multiple accounts. D1, private R2, KV and Queues are reconciled idempotently. Selected external providers use their actual tools. Private hosting requires Cloudflare Zero Trust and scoped Access permissions; protection covers the whole Worker before product deployment. Whole-Worker Access currently excludes WebSockets, which need a deliberate alternative access workflow.
|
|
80
|
+
Replace the example email with the intended member. Private Workers hosting requires Cloudflare Zero Trust and the necessary Access permissions. Authentication does not establish every provisioning permission or complete service setup.
|
|
139
81
|
|
|
140
|
-
|
|
82
|
+
For Wrangler profiles, changed resource IDs stop `ship` before deployment for review and a commit. Void can activate a target before recording new resource identities in `void.lock.json`; it then returns `configuration-required` with the activation receipts retained. Review and commit those locks, then ship the clean configuration. It never commits source automatically. Shipping runs project checks and records delivery results. `verify` exercises your application's live acceptance test; a successful scaffold or deployment alone does not prove its features work.
|
|
141
83
|
|
|
142
|
-
|
|
84
|
+
Provider eligibility, subscriptions, usage limits, and charges remain your responsibility. Some setup requires owner action. Expo delivery returns EAS build links; it does not submit apps to stores.
|
|
143
85
|
|
|
144
|
-
|
|
86
|
+
See [delivery and recovery](docs/delivery-workflow.md) and [provider configuration](docs/provider-configuration.md) for account selection, deployment, migration, rollback, and integration requirements.
|
|
145
87
|
|
|
146
|
-
|
|
88
|
+
## Use with Codex
|
|
147
89
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
## Use with ChatGPT and Codex
|
|
153
|
-
|
|
154
|
-
The workflow follows the [Anhedral Application Stack & Delivery Standard](docs/application-stack-standard.md).
|
|
90
|
+
```sh
|
|
91
|
+
codex plugin marketplace add anhedral/anhedral-cli
|
|
92
|
+
codex plugin add anhedral@anhedral
|
|
93
|
+
```
|
|
155
94
|
|
|
156
|
-
|
|
95
|
+
Select **Try now**, or start with:
|
|
157
96
|
|
|
158
|
-
|
|
97
|
+
> Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.
|
|
159
98
|
|
|
160
|
-
The plugin guides
|
|
99
|
+
The plugin guides stack selection, feature development, setup, and verification. Its optional inspector displays local stack, setup, and recorded delivery evidence. It does not monitor live health or perform provisioning when opened. The CLI also works independently.
|
|
161
100
|
|
|
162
|
-
|
|
101
|
+
## Commands and documentation
|
|
163
102
|
|
|
164
|
-
|
|
103
|
+
Use `anhedral --help` or `anhedral help <command>` for options and examples. `--cwd` selects a project; `--json` provides structured output.
|
|
165
104
|
|
|
166
|
-
|
|
105
|
+
- [CLI usage](docs/cli-design.md)
|
|
106
|
+
- [Stack standard](docs/stack-standard.md)
|
|
107
|
+
- [Delivery and recovery](docs/delivery-workflow.md)
|
|
108
|
+
- [Provider configuration](docs/provider-configuration.md)
|
|
109
|
+
- [Plugin development](docs/plugin-ui.md)
|
|
167
110
|
|
|
168
|
-
## Development
|
|
111
|
+
## Development and contributions
|
|
169
112
|
|
|
170
113
|
```sh
|
|
171
114
|
pnpm install --frozen-lockfile
|
|
172
115
|
pnpm test:all
|
|
173
|
-
pnpm test:integration
|
|
116
|
+
pnpm test:integration
|
|
174
117
|
```
|
|
175
118
|
|
|
176
|
-
|
|
119
|
+
The root test command reuses a verified inspector runtime or installs its frozen dependencies and builds it when missing/stale. Preparing that runtime requires Node 22.13+ on 22.x or Node 24+; older CLI test lanes consume the verified CI runtime artifact. For inspector-specific checks, run `pnpm --dir plugins/codex/inspector install --frozen-lockfile` and `pnpm plugin:check`. Development builds require matching CLI and plugin versions; they do not update installed releases automatically.
|
|
177
120
|
|
|
178
|
-
|
|
121
|
+
Focused fixes, tests, and documentation contributions are welcome. See [contributing](https://github.com/anhedral/anhedral-cli/blob/main/.github/CONTRIBUTING.md), [code of conduct](https://github.com/anhedral/anhedral-cli/blob/main/.github/CODE_OF_CONDUCT.md), and [security reporting](https://github.com/anhedral/anhedral-cli/blob/main/.github/SECURITY.md). Report reproducible problems in [issues](https://github.com/anhedral/anhedral-cli/issues) and vulnerabilities through [private reporting](https://github.com/anhedral/anhedral-cli/security/advisories/new).
|
|
122
|
+
|
|
123
|
+
Anhedral is open source under the [Apache License 2.0](LICENSE). Generated applications are source code that developers can customize and license for their products, preserving applicable upstream notices.
|
|
124
|
+
|
|
125
|
+
## Repository layout
|
|
126
|
+
|
|
127
|
+
| Path | Purpose |
|
|
128
|
+
| --- | --- |
|
|
129
|
+
| `src` | CLI and application scaffolding |
|
|
130
|
+
| `plugins/codex/inspector` | Optional project inspector and MCP runtime sources |
|
|
131
|
+
| `plugins/codex/distribution` | Plugin manifest, assets, skill and bundled runtime |
|
|
132
|
+
| `scripts`, `tests` | Build, release and verification tooling |
|
|
133
|
+
| `docs` | Canonical architecture, delivery and development documentation |
|
|
179
134
|
|
|
180
|
-
|
|
135
|
+
Run CLI commands from the repository root. `pnpm plugin:build`, `pnpm plugin:check` and `pnpm plugin:preview` delegate to the inspector application. The inspector owns its own dependencies and lockfile. Its build copies the bundled server and dashboard into `plugins/codex/distribution/runtime`; release packaging includes only the distribution directory. Shared project and provider logic stays in `src` so the CLI and plugin use the same implementation.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2014-present, Jon Schlinkert.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
+
THE SOFTWARE.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
You may use the Forge project under the terms of either the BSD License or the
|
|
2
|
+
GNU General Public License (GPL) Version 2.
|
|
3
|
+
|
|
4
|
+
The BSD License is recommended for most projects. It is simple and easy to
|
|
5
|
+
understand and it places almost no restrictions on what you can do with the
|
|
6
|
+
Forge project.
|
|
7
|
+
|
|
8
|
+
If the GPL suits your project better you are also free to use Forge under
|
|
9
|
+
that license.
|
|
10
|
+
|
|
11
|
+
You don't have to do anything special to choose one license or the other and
|
|
12
|
+
you don't have to notify anyone which license you are using. You are free to
|
|
13
|
+
use this project in commercial projects as long as the copyright header is
|
|
14
|
+
left intact.
|
|
15
|
+
|
|
16
|
+
If you are a commercial entity and use this set of libraries in your
|
|
17
|
+
commercial software then reasonable payment to Digital Bazaar, if you can
|
|
18
|
+
afford it, is not required but is expected and would be appreciated. If this
|
|
19
|
+
library saves you time, then it's saving you money. The cost of developing
|
|
20
|
+
the Forge software was on the order of several hundred hours and tens of
|
|
21
|
+
thousands of dollars. We are attempting to strike a balance between helping
|
|
22
|
+
the development community while not being taken advantage of by lucrative
|
|
23
|
+
commercial entities for our efforts.
|
|
24
|
+
|
|
25
|
+
-------------------------------------------------------------------------------
|
|
26
|
+
New BSD License (3-clause)
|
|
27
|
+
Copyright (c) 2010, Digital Bazaar, Inc.
|
|
28
|
+
All rights reserved.
|
|
29
|
+
|
|
30
|
+
Redistribution and use in source and binary forms, with or without
|
|
31
|
+
modification, are permitted provided that the following conditions are met:
|
|
32
|
+
* Redistributions of source code must retain the above copyright
|
|
33
|
+
notice, this list of conditions and the following disclaimer.
|
|
34
|
+
* Redistributions in binary form must reproduce the above copyright
|
|
35
|
+
notice, this list of conditions and the following disclaimer in the
|
|
36
|
+
documentation and/or other materials provided with the distribution.
|
|
37
|
+
* Neither the name of Digital Bazaar, Inc. nor the
|
|
38
|
+
names of its contributors may be used to endorse or promote products
|
|
39
|
+
derived from this software without specific prior written permission.
|
|
40
|
+
|
|
41
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
42
|
+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
43
|
+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
44
|
+
DISCLAIMED. IN NO EVENT SHALL DIGITAL BAZAAR BE LIABLE FOR ANY
|
|
45
|
+
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
46
|
+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
47
|
+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
48
|
+
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
49
|
+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
50
|
+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { lstatSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { spawnSync } from 'node:child_process';
|
|
5
|
+
import { fileURLToPath } from 'node:url';
|
|
6
|
+
|
|
7
|
+
// Exact local mitigations; pnpm's frozen install applies and checks the patches.
|
|
8
|
+
// Runtime regression probes belong in the CLI repository's test:patch suite.
|
|
9
|
+
const patches = [
|
|
10
|
+
{
|
|
11
|
+
name: 'braces',
|
|
12
|
+
version: '3.0.3',
|
|
13
|
+
advisory: 'GHSA-vfj7-8cjw-p6xm',
|
|
14
|
+
sha256: '69bd65a37da4569ba0be8a044aa732ad7c2ebd5494d6076f966eb6df8a12756e',
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
name: 'node-forge',
|
|
18
|
+
version: '1.4.0',
|
|
19
|
+
advisory: 'GHSA-86w9-cpqp-85rv',
|
|
20
|
+
sha256: '2cbbff9183d2896f13da8c8655b8f598b0f24c9b7477e8230f9a313f806c239f',
|
|
21
|
+
},
|
|
22
|
+
];
|
|
23
|
+
const severities = ['info', 'low', 'moderate', 'high', 'critical'];
|
|
24
|
+
const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
|
|
25
|
+
const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
|
|
26
|
+
const fail = (message) => {
|
|
27
|
+
throw new Error(message);
|
|
28
|
+
};
|
|
29
|
+
const readRegular = (file, maximum = 2 * 1024 * 1024) => {
|
|
30
|
+
const stat = lstatSync(file);
|
|
31
|
+
if (!stat.isFile() || stat.isSymbolicLink() || stat.size > maximum)
|
|
32
|
+
fail('Expected a bounded regular file.');
|
|
33
|
+
return readFileSync(file);
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
/** Accept only exact advisory/version pairs whose reviewed patches are configured. */
|
|
37
|
+
export function verifyAuditReport(report, { status, patchedCoordinates = [] } = {}) {
|
|
38
|
+
if (
|
|
39
|
+
!object(report) ||
|
|
40
|
+
report.error ||
|
|
41
|
+
!object(report.advisories) ||
|
|
42
|
+
!object(report.metadata?.vulnerabilities)
|
|
43
|
+
)
|
|
44
|
+
fail('Incomplete pnpm audit report; no advisory exception was applied.');
|
|
45
|
+
const findings = Object.values(report.advisories);
|
|
46
|
+
const counts = Object.fromEntries(severities.map((severity) => [severity, 0]));
|
|
47
|
+
for (const finding of findings) {
|
|
48
|
+
if (
|
|
49
|
+
!object(finding) ||
|
|
50
|
+
!severities.includes(finding.severity) ||
|
|
51
|
+
typeof finding.module_name !== 'string' ||
|
|
52
|
+
!/^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$/.test(finding.github_advisory_id ?? '') ||
|
|
53
|
+
!Array.isArray(finding.findings) ||
|
|
54
|
+
!finding.findings.length ||
|
|
55
|
+
finding.findings.some(
|
|
56
|
+
(item) =>
|
|
57
|
+
!object(item) ||
|
|
58
|
+
typeof item.version !== 'string' ||
|
|
59
|
+
!item.version ||
|
|
60
|
+
!Array.isArray(item.paths) ||
|
|
61
|
+
!item.paths.length ||
|
|
62
|
+
item.paths.some((entry) => typeof entry !== 'string' || !entry),
|
|
63
|
+
)
|
|
64
|
+
)
|
|
65
|
+
fail('Incomplete advisory details; no advisory exception was applied.');
|
|
66
|
+
if (new Set(finding.findings.map((item) => item.version)).size !== finding.findings.length)
|
|
67
|
+
fail('Duplicate affected versions in advisory details.');
|
|
68
|
+
counts[finding.severity] += finding.findings.length;
|
|
69
|
+
}
|
|
70
|
+
for (const severity of severities) {
|
|
71
|
+
const count = report.metadata.vulnerabilities[severity];
|
|
72
|
+
if (!Number.isSafeInteger(count) || count < 0 || count !== counts[severity])
|
|
73
|
+
fail('Audit severity counts do not match its advisory details.');
|
|
74
|
+
}
|
|
75
|
+
if (status !== (findings.some((finding) => finding.severity !== 'info') ? 1 : 0))
|
|
76
|
+
fail('Unexpected pnpm audit exit status; inspect the raw report.');
|
|
77
|
+
const high = findings.filter((finding) => ['high', 'critical'].includes(finding.severity));
|
|
78
|
+
for (const finding of high) {
|
|
79
|
+
const patch = patches.find(
|
|
80
|
+
({ name, version, advisory }) =>
|
|
81
|
+
finding.module_name === name &&
|
|
82
|
+
finding.github_advisory_id === advisory &&
|
|
83
|
+
finding.findings.every((item) => item.version === version),
|
|
84
|
+
);
|
|
85
|
+
if (finding.severity !== 'high' || !patch)
|
|
86
|
+
fail(
|
|
87
|
+
`Unaccepted high/critical advisory: ${finding.github_advisory_id} (${finding.module_name}).`,
|
|
88
|
+
);
|
|
89
|
+
}
|
|
90
|
+
for (const finding of high) {
|
|
91
|
+
const coordinate = `${finding.module_name}@${finding.findings[0].version}`;
|
|
92
|
+
if (!patchedCoordinates.includes(coordinate))
|
|
93
|
+
fail(`The ${finding.module_name} advisory requires its reviewed configured patch.`);
|
|
94
|
+
}
|
|
95
|
+
return {
|
|
96
|
+
exceptionApplied: high.length > 0,
|
|
97
|
+
acceptedAdvisories: high.map((finding) => finding.github_advisory_id),
|
|
98
|
+
vulnerabilities: counts,
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export function runAuditGate(root = process.cwd()) {
|
|
103
|
+
root = realpathSync(root);
|
|
104
|
+
const executable = process.env.npm_execpath;
|
|
105
|
+
if (!executable) fail('Run this gate with pnpm run audit:deps.');
|
|
106
|
+
const run = (args) => {
|
|
107
|
+
const result = spawnSync(process.execPath, [executable, ...args], {
|
|
108
|
+
cwd: root,
|
|
109
|
+
env: process.env,
|
|
110
|
+
encoding: 'utf8',
|
|
111
|
+
timeout: 120000,
|
|
112
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
113
|
+
});
|
|
114
|
+
if (result.error || result.signal || !Number.isInteger(result.status))
|
|
115
|
+
fail('pnpm audit command did not complete.');
|
|
116
|
+
return result;
|
|
117
|
+
};
|
|
118
|
+
const audit = run(['audit', '--json', '--audit-level', 'low']);
|
|
119
|
+
const reportFile = path.join(root, '.anhedral-audit-report.json');
|
|
120
|
+
const existingReport = lstatSync(reportFile, { throwIfNoEntry: false });
|
|
121
|
+
if (existingReport && (!existingReport.isFile() || existingReport.isSymbolicLink()))
|
|
122
|
+
fail('The raw audit report target must be a regular file.');
|
|
123
|
+
writeFileSync(reportFile, audit.stdout, { mode: 0o600 });
|
|
124
|
+
let report;
|
|
125
|
+
try {
|
|
126
|
+
report = JSON.parse(audit.stdout);
|
|
127
|
+
} catch {
|
|
128
|
+
fail('pnpm returned invalid audit JSON; inspect .anhedral-audit-report.json.');
|
|
129
|
+
}
|
|
130
|
+
// Validate the entire report before considering any exception.
|
|
131
|
+
const candidate = verifyAuditReport(report, {
|
|
132
|
+
status: audit.status,
|
|
133
|
+
patchedCoordinates: patches.map(({ name, version }) => `${name}@${version}`),
|
|
134
|
+
});
|
|
135
|
+
if (!candidate.exceptionApplied) return candidate;
|
|
136
|
+
const config = run(['config', 'get', 'patchedDependencies', '--json']);
|
|
137
|
+
if (config.status !== 0) fail('pnpm could not read the configured dependency patches.');
|
|
138
|
+
const configured = JSON.parse(config.stdout);
|
|
139
|
+
const patchedCoordinates = [];
|
|
140
|
+
for (const patch of patches) {
|
|
141
|
+
if (!candidate.acceptedAdvisories.includes(patch.advisory)) continue;
|
|
142
|
+
const coordinate = `${patch.name}@${patch.version}`;
|
|
143
|
+
const relative = `patches/${coordinate}.patch`;
|
|
144
|
+
if (
|
|
145
|
+
!object(configured) ||
|
|
146
|
+
typeof configured[coordinate] !== 'string' ||
|
|
147
|
+
path.resolve(root, configured[coordinate]) !== path.join(root, relative) ||
|
|
148
|
+
hash(readRegular(path.join(root, relative))) !== patch.sha256
|
|
149
|
+
)
|
|
150
|
+
fail(`The reviewed ${patch.name} patch is missing or changed or is not configured.`);
|
|
151
|
+
patchedCoordinates.push(coordinate);
|
|
152
|
+
}
|
|
153
|
+
const result = verifyAuditReport(report, { status: audit.status, patchedCoordinates });
|
|
154
|
+
console.log(
|
|
155
|
+
`Accepted only ${result.acceptedAdvisories.join('; ')} for configured local patches. Raw audit remains in .anhedral-audit-report.json.`,
|
|
156
|
+
);
|
|
157
|
+
return result;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
161
|
+
try {
|
|
162
|
+
runAuditGate();
|
|
163
|
+
} catch (error) {
|
|
164
|
+
console.error(error.message);
|
|
165
|
+
process.exitCode = 1;
|
|
166
|
+
}
|
|
167
|
+
}
|