anhedral 0.12.0 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -172
- package/assets/patches/audit-deps.mjs +12 -2
- package/assets/ui/LICENSE.shadcn +21 -0
- package/assets/ui/UPSTREAM.json +33 -0
- package/assets/ui/native/button.tsx +85 -0
- package/assets/ui/native/card.tsx +33 -0
- package/assets/ui/native/dialog.tsx +75 -0
- package/assets/ui/native/input.tsx +27 -0
- package/assets/ui/native/label.tsx +4 -0
- package/assets/ui/native/layout.tsx +26 -0
- package/assets/ui/native/text.tsx +20 -0
- package/assets/ui/native/theme-switcher.tsx +22 -0
- package/assets/ui/theme-storage.ts +25 -0
- package/assets/ui/theme.tsx +66 -0
- package/assets/ui/web/button.tsx +59 -0
- package/assets/ui/web/input.tsx +21 -0
- package/assets/ui/web/label.tsx +19 -0
- package/dist/capabilities.d.ts +5 -5
- package/dist/capabilities.js +3 -21
- package/dist/capability-contract.d.ts +3 -3
- package/dist/capability-contract.js +11 -39
- package/dist/cli-delivery.d.ts +1 -1
- package/dist/cli-delivery.js +5 -65
- package/dist/cli-output.js +3 -3
- package/dist/command-schema.js +35 -80
- package/dist/command.js +9 -11
- package/dist/delivery-evidence.d.ts +1 -1
- package/dist/delivery-evidence.js +7 -36
- package/dist/delivery.d.ts +2 -8
- package/dist/delivery.js +23 -102
- package/dist/dependencies.d.ts +12 -58
- package/dist/dependencies.js +67 -189
- package/dist/index.d.ts +1 -3
- package/dist/index.js +1 -3
- package/dist/inspector-model.d.ts +2 -2
- package/dist/integration-service-readers.d.ts +1 -2
- package/dist/integration-service-readers.js +3 -84
- package/dist/lifecycle-model.d.ts +1 -1
- package/dist/lifecycle-model.js +1 -1
- package/dist/mobile-delivery.d.ts +1 -1
- package/dist/mobile-delivery.js +4 -0
- package/dist/platforms/mobile.d.ts +1 -1
- package/dist/platforms/mobile.js +64 -114
- package/dist/platforms/web.d.ts +3 -0
- package/dist/platforms/web.js +299 -0
- package/dist/project-config.d.ts +1 -1
- package/dist/project-config.js +0 -1
- package/dist/project-inspector.js +5 -36
- package/dist/project-state.d.ts +1 -3
- package/dist/project-state.js +6 -86
- package/dist/provider-auth.js +3 -32
- package/dist/provider-readiness.d.ts +1 -1
- package/dist/provider-readiness.js +5 -24
- package/dist/providers/adapters.js +9 -178
- package/dist/providers/api.d.ts +1 -1
- package/dist/providers/api.js +3 -3
- package/dist/providers/config.js +2 -48
- package/dist/providers/definitions.d.ts +1 -204
- package/dist/providers/definitions.js +0 -85
- package/dist/providers/provision.d.ts +1 -1
- package/dist/providers/receipts.js +1 -11
- package/dist/providers/recovery-verification.js +1 -61
- package/dist/providers/runtime.js +15 -35
- package/dist/providers/state.js +1 -7
- package/dist/provision.d.ts +5 -13
- package/dist/provision.js +4 -80
- package/dist/readiness.d.ts +1 -1
- package/dist/readiness.js +3 -6
- package/dist/registry/add.js +11 -38
- package/dist/registry/bootstrap.d.ts +3 -2
- package/dist/registry/bootstrap.js +4 -13
- package/dist/registry/commands.js +8 -10
- package/dist/registry/context.js +0 -1
- package/dist/registry/options.js +8 -26
- package/dist/registry/resolve.d.ts +3 -2
- package/dist/registry/resolve.js +26 -82
- package/dist/registry/types.d.ts +2 -7
- package/dist/registry/usage.js +2 -2
- package/dist/runtime-policy.d.ts +0 -2
- package/dist/runtime-policy.js +0 -13
- package/dist/scaffold/api.js +10 -2
- package/dist/scaffold/auth.d.ts +1 -2
- package/dist/scaffold/auth.js +57 -116
- package/dist/scaffold/backend.d.ts +2 -0
- package/dist/scaffold/backend.js +39 -0
- package/dist/scaffold/billing-config.d.ts +1 -0
- package/dist/scaffold/billing-config.js +73 -0
- package/dist/scaffold/billing-contracts.d.ts +2 -0
- package/dist/scaffold/billing-contracts.js +48 -0
- package/dist/scaffold/billing-providers.d.ts +1 -0
- package/dist/scaffold/billing-providers.js +249 -0
- package/dist/scaffold/billing-schema.d.ts +1 -0
- package/dist/scaffold/billing-schema.js +34 -0
- package/dist/scaffold/billing-security.d.ts +1 -0
- package/dist/scaffold/billing-security.js +46 -0
- package/dist/scaffold/billing-server.d.ts +1 -0
- package/dist/scaffold/billing-server.js +139 -0
- package/dist/scaffold/billing-store.d.ts +1 -0
- package/dist/scaffold/billing-store.js +72 -0
- package/dist/scaffold/billing.d.ts +2 -0
- package/dist/scaffold/billing.js +208 -0
- package/dist/scaffold/bootstrap.d.ts +2 -3
- package/dist/scaffold/bootstrap.js +37 -43
- package/dist/scaffold/compose.js +2 -12
- package/dist/scaffold/database.d.ts +1 -1
- package/dist/scaffold/database.js +20 -111
- package/dist/scaffold/documentation.d.ts +0 -1
- package/dist/scaffold/documentation.js +22 -82
- package/dist/scaffold/expo-auth.d.ts +3 -0
- package/dist/scaffold/expo-auth.js +203 -0
- package/dist/scaffold/expo-billing.d.ts +3 -0
- package/dist/scaffold/expo-billing.js +257 -0
- package/dist/scaffold/expo-runtime.d.ts +3 -0
- package/dist/scaffold/expo-runtime.js +43 -0
- package/dist/scaffold/integrations.d.ts +1 -2
- package/dist/scaffold/integrations.js +9 -5
- package/dist/scaffold/managed-email.d.ts +3 -0
- package/dist/scaffold/managed-email.js +47 -0
- package/dist/scaffold/native-ui.d.ts +2 -0
- package/dist/scaffold/native-ui.js +69 -0
- package/dist/scaffold/password-reset.d.ts +1 -0
- package/dist/scaffold/password-reset.js +99 -0
- package/dist/scaffold/private-files.d.ts +2 -0
- package/dist/scaffold/private-files.js +78 -0
- package/dist/scaffold/stack-documentation.d.ts +0 -1
- package/dist/scaffold/stack-documentation.js +3 -49
- package/dist/scaffold/styling.d.ts +1 -1
- package/dist/scaffold/styling.js +20 -28
- package/dist/scaffold/web-billing.d.ts +2 -0
- package/dist/scaffold/web-billing.js +48 -0
- package/dist/scaffold/workspace.js +53 -189
- package/dist/service-deletion.js +1 -1
- package/dist/service-descriptor.js +5 -12
- package/dist/service-model.d.ts +1 -1
- package/dist/service-operations.js +2 -32
- package/dist/service-readers.js +1 -32
- package/dist/services-command.d.ts +1 -1
- package/dist/services-command.js +3 -9
- package/dist/ship.d.ts +3 -316
- package/dist/ship.js +13 -143
- package/dist/stack-registry.d.ts +2 -43
- package/dist/stack-registry.js +80 -308
- package/dist/standard.js +7 -14
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/anhedral-stack.md +23 -0
- package/docs/assets/anhedral-stack-light.png +0 -0
- package/docs/assets/anhedral-stack.png +0 -0
- package/docs/software-factory.md +25 -499
- package/docs/stack-standard.md +48 -226
- package/docs/verification.md +433 -0
- package/package.json +22 -21
- package/dist/neon-service-data.d.ts +0 -8
- package/dist/neon-service-data.js +0 -117
- package/dist/platforms/desktop.d.ts +0 -2
- package/dist/platforms/desktop.js +0 -415
- package/dist/platforms/extension.d.ts +0 -2
- package/dist/platforms/extension.js +0 -328
- package/dist/scaffold/lint.d.ts +0 -4
- package/dist/scaffold/lint.js +0 -56
- package/dist/scaffold/neon-realtime.d.ts +0 -2
- package/dist/scaffold/neon-realtime.js +0 -97
- package/dist/scaffold/services.d.ts +0 -5
- package/dist/scaffold/services.js +0 -108
- package/dist/scaffold/stream.d.ts +0 -2
- package/dist/scaffold/stream.js +0 -114
- package/dist/scaffold/void.d.ts +0 -4
- package/dist/scaffold/void.js +0 -256
- package/dist/scaffold/web.d.ts +0 -2
- package/dist/scaffold/web.js +0 -128
- package/dist/vercel-project.d.ts +0 -101
- package/dist/vercel-project.js +0 -305
- package/dist/vercel.d.ts +0 -67
- package/dist/vercel.js +0 -581
- package/dist/vinext.d.ts +0 -2
- package/dist/vinext.js +0 -86
- package/dist/void-execution.d.ts +0 -10
- package/dist/void-execution.js +0 -94
- package/dist/void-migrations.d.ts +0 -6
- package/dist/void-migrations.js +0 -110
- package/dist/void-state.d.ts +0 -16
- package/dist/void-state.js +0 -65
- package/dist/void.d.ts +0 -3
- package/dist/void.js +0 -5
package/docs/software-factory.md
CHANGED
|
@@ -1,528 +1,54 @@
|
|
|
1
1
|
# Software factory
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Anhedral CLI supplies the starter foundation for applications built with Anhedral. Developers and Anhedral Agents extend its editable source; Anhedral Platform brings collaboration and delivery oversight together, and Anhedral Cloud hosts applications and their managed services. The workflow below describes the technical steps supporting that foundation.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Use one maintained architecture: Next.js web + Expo native + Hono + Drizzle/D1 + private R2, supporting Better Auth and shared styling. Stripe and RevenueCat are the only optional additions. The [stack standard](stack-standard.md) owns architectural boundaries.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Generate
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- [Application implementation and validation](#3-implement-the-product-and-integrations)
|
|
11
|
-
- [Source, access and delivery](#5-establish-source-access-and-delivery-authority)
|
|
12
|
-
- [Maintenance and recovery](#8-maintain-and-recover)
|
|
13
|
-
- [Provider configuration](#provider-configuration)
|
|
14
|
-
- [CLI behavior](#cli-behavior)
|
|
15
|
-
- [Project dashboard](#project-dashboard)
|
|
16
|
-
- [Maintain and release the CLI](#maintain-and-release-the-cli)
|
|
17
|
-
|
|
18
|
-
## 1. Define a small, testable product
|
|
19
|
-
|
|
20
|
-
Write the intended users, core flows, data, access boundaries and observable acceptance criteria in the application's `docs/architecture.md`. Include the selected components, actual connections, environment assumptions, cost limits and tradeoffs. Preserve suitable existing code and use the same project for later changes.
|
|
21
|
-
|
|
22
|
-
For a booking app, “a member can create a booking, see it after reload, and cannot read another member's booking” is an acceptance criterion. “Use auth and a database” is a stack choice. Plan both, then implement a vertical slice that exercises the real UI, server and persistence together.
|
|
23
|
-
|
|
24
|
-
Choose only the necessary catalog components. Decide whether the app is public or private, whether several clients share an API, and who owns production operations. Resolve decisions that materially affect architecture, access or cost before creating resources.
|
|
25
|
-
|
|
26
|
-
Use the complete [stack catalog](stack-standard.md#defaults-and-foundations) to choose applications, data/identity, services and SDK integrations. Plain initialization supplies the Vinext web foundation without a database or identity provider. Include the web flag when combining it with another interface; for example, `--vinext --hono --expo --neon` selects web, API, mobile and PostgreSQL. Better Auth defaults to D1, Neon Realtime adds Neon, and RevenueCat requires an explicit Stripe selection. Review the [composition rules](stack-standard.md#composition-and-compatibility) before choosing a delivery engine: OpenNext, Queues and Basin use Wrangler, and later additions do not switch an existing Void workspace to Wrangler.
|
|
27
|
-
|
|
28
|
-
Record what each recipe supplies and what the product still needs. Sentry, device-local data and RevenueCat require platform integration work; SDK factories need consumers; room messaging, live video, job processing and workflows need product behavior. Select `--stream` for one-to-many WHIP/WHEP broadcasts; Stream activation, live input ownership, creator/player UI and private playback verification remain explicit integration work. The catalog's generated-scope and setup columns describe these boundaries.
|
|
29
|
-
|
|
30
|
-
**Ready to generate:** the core flow, stack selection, owner and acceptance criteria are clear.
|
|
31
|
-
|
|
32
|
-
## 2. Generate and inspect the foundation
|
|
33
|
-
|
|
34
|
-
Use Node.js `24.21.0+` and pnpm `10.34.5` for the default stack. Match the installed CLI version to the plugin's bundled registry `cliVersion` when using Codex. Pin that version for repeatable automation. For unpublished checkout work, run `pnpm build` and use `node dist/bin.js`; building does not update installed releases.
|
|
35
|
-
|
|
36
|
-
```sh
|
|
37
|
-
anhedral init my-app --vinext --hono --d1 --better-auth --r2 --dry-run --json
|
|
38
|
-
anhedral init my-app --vinext --hono --d1 --better-auth --r2
|
|
39
|
-
cd my-app
|
|
40
|
-
pnpm dev
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Use an unused directory. `init --dry-run` performs no writes or network requests. Actual initialization downloads the upstream bootstrap, generates source and normally installs dependencies and initializes Git; it does not create cloud resources or deploy. `--skip-install` skips the final install, but the upstream bootstrap still needs network access.
|
|
44
|
-
|
|
45
|
-
Review the generated README, `AGENTS.md`, `docs/stack.md`, root `anhedral.json` and lockfile. The setup section records remaining requirements. Keep secrets in the selected runtime's private files, following its templates.
|
|
46
|
-
|
|
47
|
-
For later capabilities, preview before applying:
|
|
48
|
-
|
|
49
|
-
```sh
|
|
50
|
-
anhedral add resend --dry-run --json
|
|
51
|
-
anhedral add resend --diff
|
|
52
|
-
anhedral add resend
|
|
53
|
-
anhedral doctor --json
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Additions use the bundled catalog and preserve edited source. Resolve conflicts deliberately. A selection plan marked `filesChecked: false` has not previewed files that require a new upstream web bootstrap. Add does not perform runtime relocation or switch the Cloudflare engine.
|
|
57
|
-
|
|
58
|
-
**Ready to implement:** the workspace starts, the selected packages have clear consumers, and remaining setup is understood.
|
|
59
|
-
|
|
60
|
-
## 3. Implement the product and integrations
|
|
61
|
-
|
|
62
|
-
Build the acceptance flows with real persistence, validation and server-side authorization. Include loading, empty and failure states. Exercise denied access and cross-user/tenant isolation, not just the successful path. Keep shared contracts in packages and privileged code on servers.
|
|
63
|
-
|
|
64
|
-
Generate SQL with `pnpm db:generate`, review it, then apply it to the intended development database with `pnpm db:migrate`. Migration tasks are separate from build/startup. Production migrations need a reviewed apply plan and data compatibility assessment. The stack standard explains D1 ownership and separate Neon migration credentials.
|
|
65
|
-
|
|
66
|
-
Configure the selected integrations in the `providers` section of `anhedral.json`. Supply management keys through the process environment; runtime secrets stay private. Use existing scoped resources where appropriate. The [provider configuration reference](software-factory.md#provider-configuration) lists supported automation, exact fields, credentials and owner prerequisites.
|
|
67
|
-
|
|
68
|
-
Domain verification, OAuth consent, billing enrollment, store signing and product-specific webhook/purchase behavior may require separate work. Neon Realtime additionally needs manual branch activation/origins and authenticated scoped sealing/subscription flows. Installed SDKs and obtained credentials do not establish that these features work.
|
|
69
|
-
|
|
70
|
-
**Ready to validate:** each core flow uses its intended implementation and remaining external dependencies are explicit.
|
|
71
|
-
|
|
72
|
-
## 4. Check the actual application
|
|
73
|
-
|
|
74
|
-
From the generated project root:
|
|
75
|
-
|
|
76
|
-
```sh
|
|
77
|
-
pnpm check
|
|
78
|
-
anhedral doctor --json
|
|
79
|
-
anhedral inspect --json
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
`pnpm check` runs lint, types, Fallow analysis, dependency audit, tests and builds; the explicit OpenNext profile also builds its Worker output. Add meaningful product tests as you implement features. `doctor` checks local readiness and provenance. `inspect` reads local selection, setup and recorded delivery evidence offline; neither certifies live product behavior.
|
|
83
|
-
|
|
84
|
-
Exercise the actual runtime as well as compilation: Vinext/Vite workerd preview, OpenNext Worker preview, or native Next.js as selected. For mobile, desktop and extensions, check relevant device/packaged behavior and permissions. Verify retry, webhook duplication, private files, AI limits and recovery for the services you selected.
|
|
85
|
-
|
|
86
|
-
Record commands, results and gaps in the application's `docs/verification.md`. Distinguish local, preview and live results. A smoke check or HTTP 200 establishes availability of that route, not completion of the product.
|
|
87
|
-
|
|
88
|
-
**Ready to deliver:** checks pass and core flows have credible runtime evidence.
|
|
89
|
-
|
|
90
|
-
## 5. Establish source, access and delivery authority
|
|
91
|
-
|
|
92
|
-
Verify the owner's Git identity and repository destination. Review source and secret ignores, then commit the application and configuration in its own repository. Generation does not create a source commit for you. Never commit private runtime files or `.anhedral/`.
|
|
93
|
-
|
|
94
|
-
```sh
|
|
95
|
-
anhedral auth --status --json
|
|
96
|
-
anhedral auth
|
|
97
|
-
anhedral doctor --providers --json
|
|
98
|
-
anhedral repository --create --json
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
`auth` can guide Cloudflare, Vercel and Expo login; API integrations use supplied environment credentials. `--status`, JSON and noninteractive modes never open login prompts. Authentication is separate from selecting a resource/account and proving every write permission.
|
|
102
|
-
|
|
103
|
-
`repository --create` creates a private GitHub repository under the selected account when necessary, pushes the intended source and verifies the exact remote identity/commit. Use explicit owner/name/visibility flags for a different authorized destination. Reuse matching origins; preserve existing remotes and visibility. Connecting Git to a host can trigger deployments, so check release authorization and policy first.
|
|
104
|
-
|
|
105
|
-
Connect the intended hosting account and audience, then review and commit the resulting configuration:
|
|
106
|
-
|
|
107
|
-
| Target | Example |
|
|
108
|
-
| ------------------------------ | ------------------------------------------------------------------------------------- |
|
|
109
|
-
| Private Cloudflare app | `anhedral connect --audience private --allow-email owner@example.com` |
|
|
110
|
-
| Intended public Cloudflare app | `anhedral connect --audience public` |
|
|
111
|
-
| Private Vercel app | `anhedral connect --scope customer-team --audience private --use commercial --create` |
|
|
112
|
-
|
|
113
|
-
Replace all example account/member values. Select `--account` for Cloudflare when needed, and `--provider cloudflare` or `--provider vercel` to disambiguate mixed projects. Private Cloudflare hosting requires Zero Trust and scoped Access permissions. Whole-Worker Access does not protect WebSockets; private realtime needs a separately reviewed identity/hostname design. Vercel private hosting requires verified all-deployment protection. Hosting access is separate from product identity and authorization.
|
|
114
|
-
|
|
115
|
-
Vercel Hobby is personal/non-commercial; use `--use personal` only for eligible personal use. Commercial apps need an eligible existing plan. Do not activate paid plans, broaden audience or weaken protection to clear a blocker.
|
|
116
|
-
|
|
117
|
-
**Ready to ship:** source is committed, account/audience are selected, and permissions and release authority cover the intended operations.
|
|
118
|
-
|
|
119
|
-
## 6. Deliver one reviewed change
|
|
120
|
-
|
|
121
|
-
Choose one path for each change: CLI delivery, or connected Vercel Git delivery. Configure branch protection and required CI explicitly; a connected host does not automatically wait for GitHub Actions.
|
|
122
|
-
|
|
123
|
-
### CLI delivery
|
|
9
|
+
Use the pinned CLI version, supported Node runtime and generated pnpm version. Preview with `anhedral init my-app --dry-run --json`; generate with the same options. `--skip-install --no-git` writes source without network or a repository. Normal initialization may install dependencies and initialize Git, but never provisions cloud resources, migrates a remote database or deploys.
|
|
124
10
|
|
|
125
11
|
```sh
|
|
126
|
-
anhedral
|
|
127
|
-
anhedral
|
|
128
|
-
anhedral status --refresh --json
|
|
12
|
+
anhedral init my-app
|
|
13
|
+
anhedral init paid-app --stripe --revenuecat
|
|
129
14
|
```
|
|
130
15
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
For supported Cloudflare selections, Void owns provisioning and deployment. `provision` reports the plan and defers writes to Void. Explicit OpenNext, Queues/DLQ and Basin use Wrangler; standalone `provision` reconciles Cloudflare resources only. The integration adapters and their limits are documented in the provider reference.
|
|
134
|
-
|
|
135
|
-
**Treat `configuration-required` as a checkpoint.** Wrangler can stop before deployment when resolved resource IDs change tracked bindings. Void can activate a target before recording new resource identities in `void.lock.json`; Anhedral retains activation receipts and then requires review and a commit. Inspect those results, commit the expected changes, and ship the clean configuration again. Do not assume a nonzero result means nothing happened. Anhedral never commits source automatically. Multiple Workers are not an atomic release.
|
|
16
|
+
Review generated README, AGENTS, anhedral.json, environment templates, migration files and scripts. Secrets belong only in ignored private runtime files. Preserve useful existing applications rather than reinitializing them.
|
|
136
17
|
|
|
137
|
-
|
|
18
|
+
## Develop and validate
|
|
138
19
|
|
|
139
|
-
|
|
20
|
+
Run generated `pnpm dev` for Next.js web and Hono. Start Expo Metro separately for iOS/Android with the generated mobile command. Web uses the full App Router, including SSR and React Server Components; production builds run through Cloudflare OpenNext rather than static export. The OpenNext Worker forwards API requests through `ANHEDRAL_API`; native clients use the configured HTTPS origin. Keep web DOM shadcn components separate from the Anhedral native shadcn port, sharing contracts and design tokens.
|
|
140
21
|
|
|
141
|
-
|
|
22
|
+
Build complete vertical slices with persistent data, validation, owner authorization, error/loading states and meaningful tests. Verify session isolation and denied private-file access. Apply migrations explicitly to isolated local fixtures. Builds and tests must never migrate a configured remote database.
|
|
142
23
|
|
|
143
|
-
|
|
24
|
+
Run `pnpm check`, `anhedral doctor --json` and `anhedral inspect --json`. Local inspection reports declared configuration and recorded evidence, not live provider health. Compile/export success is not device or production acceptance.
|
|
144
25
|
|
|
145
|
-
|
|
146
|
-
pnpm check
|
|
147
|
-
anhedral repository --json
|
|
148
|
-
# Wait for the connected production deployment of this exact commit.
|
|
149
|
-
anhedral adopt --json
|
|
150
|
-
anhedral status --refresh --json
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
`repository` pushes source; the host's Git integration deploys it. `adopt` verifies the active production source/repository and records the release without another push or deployment. Do not also run `ship` for that same change.
|
|
154
|
-
|
|
155
|
-
### Native delivery
|
|
156
|
-
|
|
157
|
-
For Expo, set explicit owner/slug in static `apps/mobile/app.json`, configure the selected EAS profile and run:
|
|
26
|
+
## Add payments
|
|
158
27
|
|
|
159
28
|
```sh
|
|
160
|
-
anhedral
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
Use `--platform ios` for iOS. Project creation/linking requires review and a commit before a build continues. A queued result returns the EAS build-page link; repeat the command to inspect that build rather than submitting another. A completed artifact must match the selected project/source. Store submission is separate. Simulator builds are not TestFlight artifacts; signed iOS builds require owner credentials. Electron/extension packaging and store distribution use their actual platform workflows.
|
|
164
|
-
|
|
165
|
-
**Ready for live acceptance:** the actual URL or artifact, exact source and provider identity are confirmed.
|
|
166
|
-
|
|
167
|
-
## 7. Verify and hand over
|
|
168
|
-
|
|
169
|
-
Open the actual deployed URL or install the confirmed artifact. Exercise the original acceptance criteria with real intended users and integrations. For private hosting, check anonymous rejection at primary and deployment URLs, allowed-user sign-in and denied users. Verify product authorization and cross-tenant access separately. Provider-authenticated automation does not prove visitor login.
|
|
170
|
-
|
|
171
|
-
Implement a meaningful root `test:live` script and run:
|
|
172
|
-
|
|
173
|
-
```sh
|
|
174
|
-
anhedral verify --json
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
`verify` supplies the actual `ANHEDRAL_APP_URL` and checks source/provider provenance. Use the test to exercise the product's meaningful live assertions; a placeholder success script proves nothing. If access or an integration is blocked, retain the completed work and identify the exact unverified flow.
|
|
178
|
-
|
|
179
|
-
Keep the application's verification record current:
|
|
180
|
-
|
|
181
|
-
| Record | Include |
|
|
182
|
-
| ------------------ | -------------------------------------------------------------------------------- |
|
|
183
|
-
| Source | Repository, branch, exact commit, CLI/plugin versions |
|
|
184
|
-
| Hosting | Owner account/project, audience, active release, actual URL/artifact |
|
|
185
|
-
| Product evidence | Commands and observed results for each core flow; local/preview/live distinction |
|
|
186
|
-
| Integration status | Configured and exercised services, pending owner setup and acceptance gaps |
|
|
187
|
-
| Operations | Alert owner, usage limits, recovery procedure and next actions |
|
|
188
|
-
|
|
189
|
-
Do not include credentials. Successful delivery includes maintainable source, reproducible verification and a clear operating handoff. A later production change can make earlier acceptance evidence stale.
|
|
190
|
-
|
|
191
|
-
## 8. Maintain and recover
|
|
192
|
-
|
|
193
|
-
| Need | Command and boundary |
|
|
194
|
-
| --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
195
|
-
| Refresh deployments | `status --refresh --json` checks current provider evidence |
|
|
196
|
-
| Open a management overview | `manage --json`; `--local` explicitly uses historical local evidence |
|
|
197
|
-
| Inspect services on demand | `services list --json`, then supported status/metrics/data commands; reads can expose private data |
|
|
198
|
-
| Recover after cloning | `recover --json` reconstructs independently verified current hosting state, not missing history or credentials |
|
|
199
|
-
| Inspect interrupted integrations | `integrations status --json`; recover only the verified pending operation/resource |
|
|
200
|
-
| Release an interrupted local lock | `recover --lock` only removes a proven dead same-host delivery lock; inspect receipts first |
|
|
201
|
-
| Restore recorded code | `rollback --release <id> --data-compatible` after schema/resource compatibility review |
|
|
202
|
-
|
|
203
|
-
Rollback does not restore data, reverse SQL or cross incompatible Durable Object migration boundaries. Void rollback only restores covered code/triggers; review retained evidence. Restore matching clean source before verifying the result. Back up data and test restoration independently.
|
|
204
|
-
|
|
205
|
-
Keep alerts, dependency updates, quotas, retry/concurrency limits and shutdown controls owned and exercised. Ignored local receipts are not a durable historical backup. Live/foreign/uncertain locks are preserved; a leftover `.anhedral/ship.guard` needs manual ownership inspection. Lock recovery cannot be combined with provider/refresh flags and never replays provider writes.
|
|
206
|
-
|
|
207
|
-
Use `anhedral help <command>` for exact options. See [provider configuration](software-factory.md#provider-configuration) for integration setup/retries and [CLI behavior](https://github.com/anhedral/anhedral-cli/blob/main/docs/software-factory.md#cli-behavior) for machine output and previews. The optional [Codex inspector](software-factory.md#project-dashboard) uses the same project logic; it does not replace runtime or product acceptance.
|
|
208
|
-
|
|
209
|
-
## Provider configuration
|
|
210
|
-
|
|
211
|
-
Anhedral scaffolds source, guides authentication, and provisions and configures the selected stack before deployment. The application and accounts belong to the developer or client. Feature development, design, custom integrations, and ongoing maintenance are Anhedral's services.
|
|
212
|
-
|
|
213
|
-
### Setup
|
|
214
|
-
|
|
215
|
-
1. Run `anhedral init <directory> <stack-flags>`. Review the generated source and install dependencies.
|
|
216
|
-
2. Fill in the `providers` section of `anhedral.json`. It contains only selected integrations, nonsecret resource names, account identifiers, regions, and desired webhook settings. Empty account/domain fields require an explicit choice. Commit this file with the application source. To use an existing resource, set its ID instead of requesting a new project by name.
|
|
217
|
-
3. Supply management credentials through the process environment and run `anhedral auth <directory>`. `--status` performs checks without opening login. Cloudflare, Vercel, and Expo support interactive CLI login; API integrations show their required credentials. A successful read does not prove every write permission.
|
|
218
|
-
4. Connect the intended hosting account, project, plan, and audience using `anhedral connect`. Review and commit the connection manifest. Expo uses the explicit `owner` and `slug` in `apps/mobile/app.json`.
|
|
219
|
-
5. Inspect `anhedral registry capabilities --json` for implemented scope and evidence limits, then inspect `anhedral ship <directory> --dry-run`. It reports missing provider settings without login, network requests, writes, provisioning, or deployment. Run `ship` after reviewing the plan and authorizing the provider operations.
|
|
220
|
-
|
|
221
|
-
The manifest uses a typed, provider-specific configuration contract. It rejects unsupported providers, foreign fields, unknown enum choices, and duplicate webhook events before network operations. Empty fields are accepted for scaffolding but must be completed when required for provisioning. The exported `PROVIDER_CONFIGURATION_SCHEMA` matches these fields and enums; no generated `$schema` URL is currently installed in projects.
|
|
222
|
-
|
|
223
|
-
Authentication results label verified access as `session`, `management`, or `runtime`; unsuccessful checks use `none`. Clerk and OpenAI management credentials take precedence over runtime credentials. A runtime probe is never reported as management access. Vercel and Expo session probes require bounded, single-identity output from the pinned CLI; diagnostic paragraphs do not count as a session. These probes do not verify the selected project, all write permissions, account enrollment, or remaining owner prerequisites.
|
|
224
|
-
|
|
225
|
-
Management keys do not belong in this manifest or application source. Runtime credentials returned by providers are configured in ignored application environment files and private `.anhedral/` state. API errors and CLI results omit credential values. Never attach this private state to an issue or commit it.
|
|
226
|
-
|
|
227
|
-
### Adapters
|
|
228
|
-
|
|
229
|
-
| Provider | Management credential | Automated configuration | Owner prerequisites and remaining application work |
|
|
230
|
-
| ---------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
231
|
-
| Neon | `NEON_API_KEY` | Create or select an explicitly scoped organization/project; check outstanding operations; obtain the selected database/role's pooled connection URI; configure the server runtime environment; migration credentials are configured separately | An eligible account/region; reviewed schema and migrations; application data access |
|
|
232
|
-
| Clerk | `CLERK_PLATFORM_API_KEY` | Verify the selected workspace; create or select an application and environment; retrieve its matching publishable and secret keys | Platform API access; production domain/DNS/OAuth setup; application authorization. `CLERK_SECRET_KEY` alone verifies runtime access and cannot create an application |
|
|
233
|
-
| Resend | `RESEND_API_KEY` with management access | Create or select the explicit sending domain; request verification; report required DNS records; issue a domain-scoped sending key only after verification | Domain ownership and DNS publication/propagation; sending eligibility; templates and delivery behavior |
|
|
234
|
-
| Stripe | `STRIPE_SECRET_KEY` | Verify the explicit account and test/live key mode; configure a webhook with explicitly listed events when requested; securely retain its signing secret | Account activation for live payments; product/price decisions and webhook handlers. Provisioning does not invent a billing model or create financial commitments |
|
|
235
|
-
| RevenueCat | `RC_API_KEY` with v2 configuration access | Create or select a project; create/select iOS, Android, or connected Stripe apps; retrieve platform public SDK keys | Store credentials or Stripe account connection; products, offerings, entitlements, SDK installation, and purchase verification |
|
|
236
|
-
| Sentry | `SENTRY_AUTH_TOKEN` | Select organization/team/project; create a project if absent; verify the team/platform; select a single active client key or create one if absent; configure DSN | Appropriate organization/team permissions; platform SDK initialization, source maps, privacy filtering, and alerts |
|
|
237
|
-
| PostHog | `POSTHOG_PERSONAL_API_KEY` | Select US/EU region and organization; create/select a project; retrieve its ingestion key and matching ingestion host | Project permissions; product events, privacy/consent rules, and SDK initialization. Personal management keys never become ingestion keys |
|
|
238
|
-
| OpenAI | `OPENAI_ADMIN_KEY` | Create or select an active project; create a named service account; retain its one-time runtime key privately | Organization administration access, provider billing eligibility, limits, and application AI behavior. `OPENAI_API_KEY` alone cannot create projects |
|
|
239
|
-
|
|
240
|
-
The adapters implement a bounded scaffolding setup, not every administration endpoint a provider exposes. Account enrollment, required billing acceptance, DNS ownership, OAuth consent, store enrollment, and product-specific design remain explicit owner steps. Provisioning success does not certify those steps or finished product functionality.
|
|
241
|
-
|
|
242
|
-
#### Example manifest
|
|
243
|
-
|
|
244
|
-
For a selected Hono + Neon + PostHog stack, the `providers` section contains the following value. Keep the other `anhedral.json` sections intact:
|
|
245
|
-
|
|
246
|
-
```json
|
|
247
|
-
{
|
|
248
|
-
"schemaVersion": 1,
|
|
249
|
-
"providers": {
|
|
250
|
-
"neon": {
|
|
251
|
-
"name": "customer-app",
|
|
252
|
-
"organizationId": "org-example",
|
|
253
|
-
"region": "aws-us-east-1",
|
|
254
|
-
"database": "app",
|
|
255
|
-
"role": "app_owner"
|
|
256
|
-
},
|
|
257
|
-
"posthog": {
|
|
258
|
-
"name": "customer-app",
|
|
259
|
-
"organizationId": "00000000-0000-0000-0000-000000000000",
|
|
260
|
-
"region": "eu"
|
|
261
|
-
}
|
|
262
|
-
}
|
|
263
|
-
}
|
|
29
|
+
anhedral add stripe --cwd my-app --dry-run --json
|
|
30
|
+
anhedral add stripe --cwd my-app
|
|
31
|
+
anhedral add revenuecat --cwd my-app
|
|
264
32
|
```
|
|
265
33
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
### Delivery and retries
|
|
269
|
-
|
|
270
|
-
For new supported Cloudflare workspaces, Void owns resource provisioning and deployment; Anhedral does not run its resource creator in parallel. Explicit resource declarations remain in `anhedral.cloudflare.json`, and Void records resolved identities in `void.lock.json`. Explicit OpenNext, queue/DLQ and Basin selections use Wrangler. Wrangler provisioning reconciles D1, private R2 buckets, KV, Queues, and private JSON Basin streams. Basin HTTP ingestion stays disabled; the Worker binding is enabled. Sinks and transformations require application-specific design. Durable Objects, schedules, Workflows, and Workers AI bindings are configured through Worker deployment. Hyperdrive configurations added by a developer still require an explicit provider workflow.
|
|
34
|
+
Only these two additions are supported. Use the exact project generator version and preserve edited-source fingerprints; review conflicts instead of forcing replacement. Configure provider scope, plans, environment and credentials before acceptance. Test retries, duplicate/reordered webhooks, account switching, refunds/revocation and expiry. Native purchases require an actual device build and store sandbox configuration.
|
|
271
35
|
|
|
272
|
-
|
|
36
|
+
## Provision and deliver
|
|
273
37
|
|
|
274
|
-
|
|
38
|
+
Use the CLI help for exact flags. Authenticate the selected Cloudflare/provider accounts explicitly, inspect plans, and provision only authorized resources. Commit resolved tracked configuration before delivery. Keep management credentials out of application code and logs. Secret installation, provider activation, DNS ownership and any spending approvals remain explicit operator steps.
|
|
275
39
|
|
|
276
|
-
|
|
40
|
+
Cloudflare delivery checks clean-source provenance, account identity, selected audience and recorded releases. Retain those safeguards. A deployment exit code alone does not prove the intended application works. Migrations are explicit; no automatic remote database migration during checks/startup. Native builds and store distribution are separate workflows.
|
|
277
41
|
|
|
278
|
-
|
|
42
|
+
Verify the actual deployed web URL and target device against product acceptance criteria, including anonymous rejection and cross-account isolation. Record source SHA, exact artifact identity, commands, outcomes and remaining limitations. Rollback does not restore data or undo migrations; review data compatibility independently.
|
|
279
43
|
|
|
280
|
-
|
|
44
|
+
## Evidence-driven maintenance
|
|
281
45
|
|
|
282
|
-
|
|
46
|
+
Before deleting code, trace runtime entrypoints, published exports, generated consumers, plugin tools and maintained examples. Keep changes scoped to an explicit behavior. The 0.14 scope reduction deliberately removes unsupported alternatives; it does not authorize deleting customer source, remote resources, credentials or historical verification.
|
|
283
47
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
Keep secure backups of `.anhedral/` and runtime environment files when moving machines. A fresh clone does not carry one-time credentials or provisioning receipts. Configure explicitly selected existing resource IDs and recover runtime credentials through authorized provider tooling rather than treating it as the original provisioning session. The CLI does not automatically delete, rotate, or replace resources. `integrations status` reads the journal without writes. `integrations recover --provider <provider> --operation <exact hash> --resource <id>` verifies a supported existing resource against the unchanged recorded configuration, then writes only its local completion receipt. It never recreates or deletes a provider resource. Recovery is unavailable for pending entries without operation metadata, changed desired configuration, and one-time credential creation when the original credential is missing; inspect the provider and retain secure backups. RevenueCat application recovery requires the parent project ID recorded explicitly in the original configuration.
|
|
287
|
-
|
|
288
|
-
```sh
|
|
289
|
-
anhedral integrations status my-app --json
|
|
290
|
-
anhedral integrations recover my-app --provider neon --operation <exact-64-character-hash> --resource <verified-project-id> --json
|
|
291
|
-
```
|
|
292
|
-
|
|
293
|
-
Copy the operation hash from status and supply the intended resource ID yourself. Supported recovery checks cover known Neon projects, Clerk applications/workspace/environment, Resend domains, PostHog projects/organizations, active OpenAI projects, Sentry projects/teams/platform, and RevenueCat projects or explicitly scoped apps. They perform provider GET requests and then update only the local completion receipt. Status does not write journals or create directories. It shows missing descriptors and one-time-credential operations as blocked. Resend sending keys, Stripe webhook signing secrets, and OpenAI service-account keys cannot be recovered from a resource ID alone; securely retained credentials and explicit provider inspection are required. Never paste credentials into the command or conversation.
|
|
294
|
-
|
|
295
|
-
### Mobile delivery
|
|
296
|
-
|
|
297
|
-
Use `anhedral ship <directory> --platform ios|android --profile <profile>`. Set the intended Expo `owner` and `slug` in static `apps/mobile/app.json`. The pinned EAS CLI creates/links the project when needed, then stops for review and a source commit. Subsequent builds independently check the linked project identity. Inherited profiles require explicit resolution before automatic delivery.
|
|
298
|
-
|
|
299
|
-
Only public mobile keys are uploaded to the selected EAS environment; server credentials are excluded. Queued builds return a build-page link and `building` state. Repeat the same command to inspect the saved build ID without creating another build. Completed builds must match the selected project and source commit before returning the download link. Failed/cancelled builds require provider inspection before removing the pending record and requesting another build.
|
|
300
|
-
|
|
301
|
-
Android preview builds produce APKs; production builds produce AABs. iOS simulator artifacts need no device signing; signed iOS builds need the developer's Apple credentials and enrollment. Anhedral never runs `eas submit`. Store uploads and approvals belong to the owner.
|
|
302
|
-
|
|
303
|
-
### Verification scope
|
|
304
|
-
|
|
305
|
-
Local contract tests cover selected-stack planning, API request/response shapes, resource reuse, one-time credentials, account mismatch, pending operations, DNS gates, unknown outcomes, private file safety, runtime partitioning, and deployment handoff. These tests do not establish live account eligibility, quota, permissions, billing, DNS, signing, or production product behavior. Verify those in explicitly authorized accounts before release.
|
|
306
|
-
|
|
307
|
-
Provider contracts: [Neon API](https://api-docs.neon.tech/reference/createproject), [Clerk Platform schema](https://github.com/clerk/openapi-specs/blob/main/platform/beta.yml), [Resend API](https://resend.com/docs/api-reference/introduction), [Stripe API](https://docs.stripe.com/api), [RevenueCat API v2](https://www.revenuecat.com/docs/api-v2), [Sentry API](https://docs.sentry.io/api/), [PostHog API](https://posthog.com/docs/api), [OpenAI administration](https://developers.openai.com/api/reference/resources/admin/), [Cloudflare secrets](https://developers.cloudflare.com/workers/configuration/secrets/), [Vercel OpenAPI](https://openapi.vercel.sh), and [pinned EAS source](https://github.com/expo/eas-cli/tree/v21.0.1/packages/eas-cli/src/commands).
|
|
308
|
-
|
|
309
|
-
### Authorized staging acceptance
|
|
310
|
-
|
|
311
|
-
Use a dedicated, explicitly selected account/project for live verification. Before the first mutation, record its owner, region, resource names, permitted operations, spending limit, cleanup responsibility, and retention period in the application's verification notes. Never use production credentials for routine tests or treat access to an account as permission to incur unspecified costs.
|
|
312
|
-
|
|
313
|
-
For each selected provider, verify the following against the exact candidate CLI:
|
|
314
|
-
|
|
315
|
-
1. Missing, expired, and insufficient credentials produce an actionable state without leaking keys or starting creation.
|
|
316
|
-
2. The selected account, organization, environment and region match the manifest before provisioning.
|
|
317
|
-
3. First creation and repeated configuration use the intended resources, with no duplicate creation.
|
|
318
|
-
4. Pending DNS, provider operations or enrollment produce an explicit blocked state before deployment.
|
|
319
|
-
5. An interrupted or unknown creation outcome preserves evidence and stops automatic replay; recovery requires inspected provider state.
|
|
320
|
-
6. Runtime credentials reach only their intended server or public client target. Check runtime access through a bounded application flow, without publishing the credential value.
|
|
321
|
-
7. The actual deployed service or build matches the selected project and checked source commit. Test its promised user flow independently of build success.
|
|
322
|
-
8. Record provider/resource IDs, source revision, nonsecret verification results, unresolved owner steps, and cleanup results. Keep credential files and complete provider responses out of public logs and issues.
|
|
323
|
-
|
|
324
|
-
A completed local contract test, an accessible API endpoint, a created resource, a successful deployment, and a verified product flow are separate evidence levels. Release notes must name the level actually established; do not promote one to another.
|
|
325
|
-
|
|
326
|
-
## CLI behavior
|
|
327
|
-
|
|
328
|
-
Anhedral uses three primary commands: `init` scaffolds source, `auth` checks or guides provider authentication, and `ship` provisions/configures the supported stack and coordinates delivery. `add`, `registry`, and `doctor` support development. Hosting selection and advanced release operations remain available through focused command help.
|
|
329
|
-
|
|
330
|
-
The comparison below uses current upstream documentation and source inspected on October 12, 2026. These projects solve different problems; the useful comparison is how they make commands discoverable, changes reviewable, and failures understandable.
|
|
331
|
-
|
|
332
|
-
| Reference | Useful practice | Anhedral behavior |
|
|
333
|
-
| --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
334
|
-
| [shadcn CLI](https://ui.shadcn.com/docs/cli) and its [command source](https://github.com/shadcn-ui/ui/tree/main/packages/shadcn/src/commands) | Source ownership, command-specific help, working-directory selection, and previews before changing files | Bundled recipes scaffold owned source; focused help, `--cwd`, and `add --dry-run`, `--diff`, and `--view` support review |
|
|
335
|
-
| [shadcn monorepos](https://ui.shadcn.com/docs/monorepo) | Resolve application and shared-package destinations coherently | The registry resolves dependencies and workspace references into `apps/*` and `packages/*`; additions preserve edited source and record provenance |
|
|
336
|
-
| [GitHub CLI help](https://cli.github.com/manual/gh_help) | Discover commands through focused help topics | `anhedral help <command>` and `<command> --help` show the same options, examples, and relevant prerequisites |
|
|
337
|
-
| [uv command reference](https://docs.astral.sh/uv/reference/cli/) | Consistent output controls and discoverable options | `--quiet` suppresses human output; `--json` retains one machine-readable result; errors remain on stderr |
|
|
338
|
-
| [CLI Guidelines](https://clig.dev/) | Explain outcomes, suggest corrections, and show the next action | Human summaries describe selected parts, pending setup, release evidence, and next steps; command/flag typos receive bounded suggestions |
|
|
339
|
-
|
|
340
|
-
Shadcn's entry point uses Commander and registers separate commands; its initialization separates preflight checks, configuration, templates, registry work, and source updates. Anhedral separates its command metadata, argument handling, human output, registry resolution, staged transactions, and provider operations. The existing provider verification and mutation boundaries remain in the operation modules. See [shadcn's entry point](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/index.ts) and [initialization implementation](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/commands/init.ts).
|
|
341
|
-
|
|
342
|
-
### Command definitions
|
|
343
|
-
|
|
344
|
-
`src/command-schema.ts` declares command descriptions, option flags and aliases, required or optional values, and repeatable options. Command help and argument validation consume this same metadata; help text is never parsed to infer flag behavior. Singleton command options reject duplicates, required values reject missing input, and boolean options reject inline values without echoing those values. `--allow-email` remains repeatable; `add --diff` and `--view` accept an optional path. Command dispatch and domain-specific value validation remain in the operation handlers.
|
|
345
|
-
|
|
346
|
-
`src/bin.ts` handles global output flags, help/version, working-directory selection and error reporting. `src/cli-commands.ts` dispatches individual commands; `src/cli-delivery.ts` selects mobile, mixed-stack or provider-specific delivery. Their option collector in `src/cli-arguments.ts` uses the command schema's arity, aliases and repeatability rather than maintaining another flag parser. Initialization and source-preview additions retain their selection-specific parsers. Human output uses command-specific formatters in `src/cli-output.ts`, with explicit field allowlists and captured output contracts.
|
|
347
|
-
|
|
348
|
-
Provider lifecycle operations stay in `src/delivery.ts` and `src/vercel.ts`. Cloudflare planning, receipt parsing and evidence helpers live in `src/delivery-evidence.ts`; Vercel project state, provider queries and provenance checks live in `src/vercel-project.ts`. The original module exports remain available. Source transaction locking is isolated in `src/transaction-lock.ts`, while `src/transaction.ts` owns staging, journals, commit and recovery. Mobile delivery separates configuration, project linking, private environment transport, queue submission/resume, build validation and receipt recording; the orchestration retains the original whole-flow lock and mutation order.
|
|
349
|
-
|
|
350
|
-
### Daily use
|
|
351
|
-
|
|
352
|
-
```sh
|
|
353
|
-
anhedral init client-app --hono --neon --dry-run
|
|
354
|
-
anhedral init client-app --hono --neon
|
|
355
|
-
anhedral auth --cwd client-app
|
|
356
|
-
anhedral ship --cwd client-app --dry-run
|
|
357
|
-
|
|
358
|
-
anhedral add resend --cwd client-app --dry-run
|
|
359
|
-
anhedral add resend --cwd client-app --diff
|
|
360
|
-
anhedral add resend --cwd client-app --view packages/email/src/index.ts
|
|
361
|
-
anhedral add resend --cwd client-app
|
|
362
|
-
|
|
363
|
-
anhedral help ship
|
|
364
|
-
anhedral registry view neon
|
|
365
|
-
anhedral doctor --cwd client-app --json
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
Complete the selected provider settings and connect the intended hosting account before delivery, as described in [provider configuration](software-factory.md#provider-configuration). The commands above are examples, not authorization to deploy an application.
|
|
369
|
-
|
|
370
|
-
`--cwd` / `-c` selects the working directory and resolves relative directory arguments from it. `init [directory]` scaffolds a workspace; `add <items...>` adds bundled parts to the current project. Use `anhedral --cwd <directory> add <items...>` to select a project explicitly.
|
|
371
|
-
|
|
372
|
-
### Output contract
|
|
373
|
-
|
|
374
|
-
- Human output summarizes the operation and relevant next steps. Interactive scaffolding reports its current stage on stderr. Redirected output has no animated terminal effects or progress messages.
|
|
375
|
-
- `--json` emits a complete result on stdout. Failures emit a JSON error, code, and next action on stderr with a nonzero exit status. Login prompts and scaffolding tool output are suppressed in machine mode.
|
|
376
|
-
- Invalid `inspect` or `services` arguments use `INVALID_ARGUMENT`; inspection and service-operation failures use `INSPECTION_FAILED` and `SERVICE_FAILED`, respectively. `UNKNOWN_COMMAND` identifies an unrecognized command.
|
|
377
|
-
- `--quiet` / `-q` suppresses human results and progress, retaining errors. Combining it with `--json` retains the JSON result.
|
|
378
|
-
- `--verbose` exposes local scaffolding tool output in human mode. Machine and quiet modes keep tool output suppressed.
|
|
379
|
-
- Help and version checks do not require an existing project or a usable working directory. Unknown commands and flags fail before setup or provider operations; suggestions do not execute corrections.
|
|
380
|
-
|
|
381
|
-
### Source previews
|
|
382
|
-
|
|
383
|
-
`add --diff [path]` shows an applicable unified patch. `add --view [path]` shows generated source. Both imply a dry run and use the existing staged transaction; neither installs the preview. Without a path, they show the changed generated files. Conflict reporting still applies; previewing a conflict does not permit overwriting edited source.
|
|
384
|
-
|
|
385
|
-
Previews exclude private environment files and `.anhedral/` state. Public `env.example` (Void), `.env.example`, and `.dev.vars.example` templates can be inspected. Binary, nonregular, or files over 256 KiB are marked unavailable. The combined preview has a 1 MiB limit; select a file for larger additions. Diffs use a linear single-contextual-hunk implementation, including explicit handling of final newlines and new empty files.
|
|
386
|
-
|
|
387
|
-
A selection that needs a new upstream web bootstrap cannot produce source previews offline. The CLI explains this and directs the user to the selection-only `--dry-run` plan, which marks `filesChecked: false`. It does not fabricate files or run a networked generator during that preview.
|
|
388
|
-
|
|
389
|
-
### Deliberate boundaries
|
|
390
|
-
|
|
391
|
-
The public CLI accepts only bundled registry options. It does not accept external URLs, local third-party registries, or arbitrary remote content. It does not force overwrites, infer paid activation, or claim that scaffolding and authentication establish complete product behavior. Provider enrollment, permissions, DNS, billing eligibility, signing, and feature development remain explicit where required.
|
|
392
|
-
|
|
393
|
-
Contract and local-flow tests establish command behavior, source preservation, machine output, and provider request/response handling. Live account provisioning and deployment require separate authorized verification. Release remains a separate review decision.
|
|
394
|
-
|
|
395
|
-
### Read-only project inspection
|
|
396
|
-
|
|
397
|
-
`anhedral inspect [directory] --json` returns the shared versioned project-inspector contract used by the optional plugin UI. It reads bounded allowlisted local source and receipt files only, with independent errors for unavailable evidence. It does not contact providers, inspect credential values, migrate state or change files. It preserves per-target latest attempt and last successful release as separate facts. Authentication, permission and live provider health remain explicitly unknown. Read time does not make an old receipt fresh.
|
|
398
|
-
|
|
399
|
-
## Project dashboard
|
|
400
|
-
|
|
401
|
-
Anhedral is headless-first: describe the application to Codex, review the selected stack, develop its features, authenticate to your providers and ship through the CLI. The optional dashboard starts with the same local evidence available from `anhedral inspect --json`. Opening it or refreshing the project performs no provider calls. Explicit service controls request live status, analytics or data through the shared CLI adapters.
|
|
402
|
-
|
|
403
|
-
Building or packaging the plugin does not install or publish it. Actual Codex host rendering and composer behavior require separate verification; protocol tests do not establish those behaviors.
|
|
404
|
-
|
|
405
|
-
### Project lifecycle
|
|
406
|
-
|
|
407
|
-
The overview begins with **Init → Auth → Ship**, derived by the same inspector used by the CLI. Init reports supported Anhedral configuration and local structural readiness. Auth lists selected providers and recorded account references; these are not proof of a valid session, permission or billing eligibility. Ship summarizes per-target success receipts and flags incomplete operations, conflicts and deletion history. A recorded success does not establish current source or live health.
|
|
408
|
-
|
|
409
|
-
Review source, provider access and shipping plan prepare unsent Codex drafts. They do not run commands directly. The workflow is equally usable through the headless CLI. Services remain a secondary, project-scoped view. Registering an arbitrary directory does not adopt its stack or activate lifecycle actions; supported Anhedral configuration must exist. There is no separate Anhedral account or hosted control plane.
|
|
410
|
-
|
|
411
|
-
### Screens and evidence
|
|
412
|
-
|
|
413
|
-
| Screen | Information | Evidence boundary |
|
|
414
|
-
| -------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
415
|
-
| Overview | Project identity, stack selection, per-target latest attempt and last success | Recorded results; not live health or feature acceptance |
|
|
416
|
-
| Services | Application targets, configured bindings, provisioning receipts and selected integrations | Local inventory plus explicitly requested live readings; receipt matching uses resource kind and identifiers |
|
|
417
|
-
| Stack | Workspace package dependencies, declared bindings, environment names and cron expressions | Package dependencies do not prove network calls; declarations do not prove resource existence |
|
|
418
|
-
| Setup | Local prerequisites, selected providers, capability limits and setup guidance | Authentication, selected-account permission and billing remain not checked |
|
|
419
|
-
| Delivery | Separate Cloudflare, Vercel and mobile records; integration pending outcomes and latest operation | One provider's success does not establish another's; old running records do not prove a process is active |
|
|
420
|
-
|
|
421
|
-
Service controls expose only implemented readers; there is no schedule-execution reader. Environment names come from example files and reveal no values or proof of secret validity. Mobile download URLs may contain access tokens and are excluded; validated Expo build-page links may be displayed. Missing record timestamps and project identity are unavailable rather than invented.
|
|
422
|
-
|
|
423
|
-
Every section is bounded and validated independently. A corrupt provider journal must not hide another target's valid evidence. Read time is explicitly distinct from receipt time. Configured, recorded and unknown states must remain distinguishable. General secret files, provider credential vaults, runtime state, raw diagnostics and absolute source paths are excluded from the UI projection.
|
|
424
|
-
|
|
425
|
-
### Interactions
|
|
426
|
-
|
|
427
|
-
New project opens a new composer with this prompt, without sending: “Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.” Setup and delivery actions prepare unsent drafts for the current conversation. The user reviews and sends the request before Codex acts. Unsupported hosts offer copyable text. Project selection updates authorized model context; it does not execute commands.
|
|
428
|
-
|
|
429
|
-
Refresh reloads local files only. Rename and forget affect only local catalog metadata, never project source or provider resources. There is no project-creation or registration dialog. Successful `anhedral init` automatically registers its generated source in the local catalog. Existing sources can be registered through the local operator command. MCP tool inputs accept project IDs rather than arbitrary filesystem paths.
|
|
430
|
-
|
|
431
|
-
### Installation
|
|
432
|
-
|
|
433
|
-
Install with `codex plugin marketplace add anhedral/anhedral-cli`, then `codex plugin add anhedral@anhedral`. The marketplace references `plugin-v<version>` in the same repository. The release workflow creates this immutable tag from the verified ZIP, including its generated runtime; the development source directory alone is not an installable release. Plugin source tags retain the reviewed release commit as their parent. Existing tags cannot be replaced by the release workflow.
|
|
434
|
-
|
|
435
|
-
### Local development
|
|
436
|
-
|
|
437
|
-
The UI toolchain requires Node 22.13+ within Node 22, or Node 24+. The CLI retains its separately documented engines.
|
|
438
|
-
|
|
439
|
-
```sh
|
|
440
|
-
pnpm install --frozen-lockfile
|
|
441
|
-
pnpm --dir plugins/codex/inspector install --frozen-lockfile
|
|
442
|
-
pnpm build
|
|
443
|
-
pnpm plugin:check
|
|
444
|
-
pnpm --dir plugins/codex/inspector exec playwright install chromium
|
|
445
|
-
pnpm --dir plugins/codex/inspector test:browser
|
|
446
|
-
ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" node plugins/codex/inspector/dist/server.mjs register "$PWD" "Anhedral"
|
|
447
|
-
ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" pnpm plugin:preview
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
Open `http://127.0.0.1:4317/`. The preview binds only to loopback, validates Host/Origin, bounds requests and uses a restrictive content security policy. `anhedral inspect [directory] --json` provides the shared read-only projection directly. `anhedral registry capabilities --json` explains the supported automation and owner steps.
|
|
451
|
-
|
|
452
|
-
`src/project-inspector.ts` owns projection; `src/catalog-snapshot.ts` adds catalog identity. The browser only renders its validated schema. The MCP server exposes `open_projects`, `list_projects`, `get_project`, `get_project_services`, local metadata tools and model-only source/catalog context tools. They remain useful without UI rendering. Standard MCP Apps resources and bridge messages provide the optional panel, host themes and inline/fullscreen modes. Native host-specific draft support is a separate acceptance gate.
|
|
453
|
-
|
|
454
|
-
The plugin and standalone CLI share one private catalog. List views read bounded summaries; only a selected project loads detailed inspection. The server does not scan for other projects. CLI initialization registers new apps using the persistent `identity.id` in `anhedral.json`; recreating a directory creates a separate app rather than silently retargeting an old catalog entry. A remote server cannot inspect these local directories without a separately reviewed architecture; never publish the local catalog through a tunnel.
|
|
455
|
-
|
|
456
|
-
### Recovery and release review
|
|
457
|
-
|
|
458
|
-
Interrupted catalog writers can be inspected and recovered with the same private catalog directory:
|
|
459
|
-
|
|
460
|
-
```sh
|
|
461
|
-
ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" node plugins/codex/inspector/dist/server.mjs recover-catalog-lock
|
|
462
|
-
```
|
|
463
|
-
|
|
464
|
-
Only a proven dead same-host owner permits recovery. Live, foreign, malformed and uncertain owners remain blocked. Recovery changes catalog access only, not provider work or delivery state.
|
|
465
|
-
|
|
466
|
-
Build/package checks bind the runtime and self-contained browser HTML to source and CLI version. Exact ZIP protocol tests exercise resources, schemas and headless tools. Before publication, verify native host entrypoints, unsent drafts, theme/reload behavior, all supported sections, keyboard navigation and narrow screens against the exact rebuilt ZIP. Publication remains a separate reviewed action.
|
|
467
|
-
|
|
468
|
-
The design follows the official [optional UI guidance](https://developers.openai.com/plugins/concepts/plugins#optional-ui) and [MCP Apps foundation](https://developers.openai.com/plugins/build/chatgpt-ui#start-with-mcp-apps).
|
|
469
|
-
|
|
470
|
-
### Live service capabilities
|
|
471
|
-
|
|
472
|
-
Live readings require the selected provider account and resource permissions. Missing access, unavailable providers and absent resources are distinct from a successful reading. Analytics show their source, UTC window and sampling status; recorded deployment success does not imply current health.
|
|
473
|
-
|
|
474
|
-
| Service | Status | Analytics | Data | Confirmed deletion |
|
|
475
|
-
| ------------------------------------------------- | ------------------------------------- | ----------------------------------------- | -------------------------------------- | ----------------------------------- |
|
|
476
|
-
| Cloudflare Worker | Settings existence | Requests, errors and CPU quantiles | — | — |
|
|
477
|
-
| D1 | Resource identity and current storage | Daily query/row counts and latency | Bounded table pages | Project-created, unshared resources |
|
|
478
|
-
| KV | Resource identity | — | Paginated key metadata; no values | Project-created, unshared resources |
|
|
479
|
-
| R2 | Bucket identity | — | Paginated object metadata; no contents | — |
|
|
480
|
-
| Queues | Resource identity | — | — | — |
|
|
481
|
-
| Vercel | Project/deployment status | Daily Web Analytics | — | — |
|
|
482
|
-
| Neon | Project identity | — | Bounded public-table pages | — |
|
|
483
|
-
| PostHog | Project identity | Hourly events and distinct IDs per bucket | — | — |
|
|
484
|
-
| Clerk, Resend, Stripe, RevenueCat, Sentry, OpenAI | Selected integration identity | — | — | — |
|
|
485
|
-
|
|
486
|
-
Neon browsing requires `ANHEDRAL_NEON_READONLY_URL`, optionally suffixed with the uppercase project ID (hyphens replaced by underscores). The endpoint must belong to that project. Each read transaction verifies a restricted role and read-only mode. Sensitive columns are masked before fetching; arbitrary SQL is not accepted.
|
|
487
|
-
|
|
488
|
-
R2 metadata browsing requires bucket-scoped read-only S3 credentials in `ANHEDRAL_R2_ACCESS_KEY_ID` and `ANHEDRAL_R2_SECRET_ACCESS_KEY`, optionally suffixed with the uppercase account ID. The reader signs only the selected account/bucket request and never downloads object contents.
|
|
489
|
-
|
|
490
|
-
Data rows, table names and deletion confirmation tokens are returned through private app metadata rather than model-visible MCP results. CLI data output is explicit user-requested output. Data views mask sensitive fields and do not provide an unmask control. D1 and Neon project bounded columns and mask sensitive columns in SQL before fetching rows; empty tables retain their schema. Database pages use explicit ordering, but concurrent writes can still change offset-based pages. KV and R2 metadata pages use provider cursors.
|
|
491
|
-
|
|
492
|
-
D1 table browsing excludes the literal internal prefixes `sqlite_` and `_cf_`. Underscores elsewhere in application table names do not act as wildcard filters.
|
|
493
|
-
|
|
494
|
-
Deletion is intentionally limited to D1 and KV. Review shows the exact account, resource, affected applications and impact. The user must type the resource name. The server requires a short-lived, single-use token, revalidates source and provider identity, and rejects adopted resources or detected external Worker consumers. Provider reads cannot provide an atomic lock against another operator changing remote dependencies.
|
|
495
|
-
|
|
496
|
-
A deletion request is never automatically retried. Confirmed absence is required to report success. Pending or uncertain outcomes remain recorded across reloads and block automatic reprovisioning. Source bindings remain for explicit review before shipping; removing a service does not silently rewrite application code. This implementation does not delete whole applications or provider accounts.
|
|
497
|
-
|
|
498
|
-
The CLI shares these adapters: `anhedral services list --json` lists exact selectors; `anhedral help services` describes status, metrics, tables, data and the two-step deletion flow. No service operation provisions resources, changes billing or deploys code.
|
|
499
|
-
|
|
500
|
-
The catalog defaults to `~/.local/share/anhedral/projects`; `ANHEDRAL_PLUGIN_DATA` selects an alternate directory and `ANHEDRAL_DISABLE_CATALOG=1` disables initialization registration. A catalog failure leaves successfully generated source intact and reports a registration recovery action.
|
|
501
|
-
|
|
502
|
-
The inspector source lives in `plugins/codex/inspector`; the installable plugin source lives in `plugins/codex/distribution`. Packaging reads that directory and emits a self-contained ZIP. Immutable `plugin-v*` release tags retain the public `plugins/anhedral` installation path used by the marketplace; the publication script builds that tree from the verified ZIP. That release path is independent of the development checkout layout.
|
|
48
|
+
Preserve operational checks, secret protection, lock/recovery safeguards and independent provider evidence. For generator changes, check emitted source and packed package behavior. For provider changes, distinguish isolated contract fixtures from live acceptance. Passing static tests cannot establish production operation.
|
|
503
49
|
|
|
504
50
|
## Maintain and release the CLI
|
|
505
51
|
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
| Path | Responsibility |
|
|
509
|
-
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
510
|
-
| `src/bin.ts`, `src/command-schema.ts`, `src/cli-*.ts` | Entry point, command grammar, dispatch and output contracts |
|
|
511
|
-
| `src/stack-registry.ts`, `src/dependencies.ts`, `src/scaffold/`, `src/platforms/` | Stack selection, pinned dependencies and owned source recipes |
|
|
512
|
-
| `src/providers/`, `src/delivery*.ts`, `src/vercel*.ts`, `src/mobile-delivery.ts` | Provider setup, checked delivery, recovery and receipts |
|
|
513
|
-
| `src/project-inspector.ts`, `src/services*.ts`, `src/service-*.ts` | Shared local inspection and explicit service readers |
|
|
514
|
-
| `plugins/codex/inspector/` | Optional MCP server, dashboard source and its independent toolchain |
|
|
515
|
-
| `plugins/codex/distribution/` | Plugin manifest, skills, generated reference copies and built runtime |
|
|
516
|
-
| `tests/`, `scripts/`, `.github/workflows/` | Contract/runtime checks, immutable artifact tooling and CI/release |
|
|
517
|
-
| `examples/full-stack/` | Source-only example of a generated workspace; no provisioned services |
|
|
518
|
-
| `docs/` | Stack architecture, this development/delivery guide and dated verification evidence |
|
|
519
|
-
|
|
520
|
-
Keep application-facing guidance in the stack standard and this factory, with one README as the entry point. Put dated checks and remaining acceptance gaps in the verification record. Update existing sections instead of creating another report for each investigation. `pnpm build` regenerates plugin reference copies from these canonical documents and the registry; edit the canonical sources first.
|
|
521
|
-
|
|
522
|
-
Before release, review the entire diff, run `pnpm release:check` and `pnpm plugin:check`, and exercise affected generated profiles with `pnpm test:integration`. The full local release gate includes external advisory refresh, exact patch regressions, packed installation and package allowlisting. A restricted local environment can leave network, listener or browser checks blocked; record that boundary and require the corresponding hosted CI evidence. Do not disable required checks to make a release pass.
|
|
523
|
-
|
|
524
|
-
For a new version, update `package.json`, `src/version.ts` and the immutable marketplace `plugin-v<version>` reference in `.agents/plugins/marketplace.json`. Build regenerates plugin manifest and registry versions. Commit all source and generated references, open a focused PR and wait for its checks before merging. Keep the owner's local checkout on `main` and synchronize it with the merged source without discarding unrelated work.
|
|
525
|
-
|
|
526
|
-
Publication uses `.github/workflows/release-on-main.yml` (Release Reviewed Candidate). It is dispatched explicitly against the exact current main commit, after its main-branch CI succeeds. Main CI builds and uploads the `release-candidate` artifact. Download it and review `metadata.json`, including its CLI `integrity` and matching `plugin.integrity`; dispatch with those exact values as `release_sha`, `cli_integrity` and `plugin_integrity`. The release workflow rebuilds, compares both immutable artifacts, runs the OS/Node portability matrix, publishes through npm trusted publishing and then creates the GitHub release and immutable plugin source tag. Do not manually publish a different tarball or move an existing release tag.
|
|
52
|
+
Follow repository AGENTS and CONTRIBUTING instructions. Use short-lived codex branches from staging and reviewable PRs into staging. Main accepts release promotions; no direct development pushes. Preserve reviewed release artifacts, npm provenance, plugin source integrity and protected publishing. Saving code to GitHub is separate from publishing npm, deploying customer applications, or installing a plugin.
|
|
527
53
|
|
|
528
|
-
|
|
54
|
+
Run build, typecheck, formatting/source hygiene, static security, relevant unit/generated runtime tests and packed-consumer tests. The Codex plugin has its own build/check and independently packaged runtime. A local CLI build does not update an installed plugin. Keep package version, source generator version and plugin marketplace reference synchronized.
|