anhedral 0.16.0 → 0.18.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 +42 -20
- package/assets/contracts/LICENSE +201 -0
- package/assets/contracts/LICENSE.environment +201 -0
- package/assets/contracts/LICENSE.operations +201 -0
- package/assets/contracts/deployment-provenance.json +15 -0
- package/assets/contracts/environment-provenance.json +11 -0
- package/assets/contracts/operations-provenance.json +11 -0
- package/assets/launch/application.server.ts.txt +13 -0
- package/assets/launch/auth-client.ts.txt +4 -0
- package/assets/launch/home.tsx.txt +20 -0
- package/assets/launch/minimal-application.server.ts.txt +5 -0
- package/assets/launch/minimal-server.ts.txt +7 -0
- package/assets/launch/request-context.ts.txt +3 -0
- package/assets/launch/root.tsx.txt +27 -0
- package/assets/launch/router.tsx.txt +21 -0
- package/assets/launch/server.ts.txt +13 -0
- package/assets/launch/sign-in.tsx.txt +53 -0
- package/assets/launch/styles.css.txt +19 -0
- package/assets/security/credential-patterns.d.mts +3 -0
- package/assets/security/credential-patterns.mjs +59 -0
- package/assets/stack/api-index.ts.txt +6 -1
- package/assets/stack/event-retention.sql.txt +10 -0
- package/assets/stack/stripe.ts.txt +30 -13
- package/assets/ui/UPSTREAM.json +1 -18
- package/dist/bin.js +55 -36
- package/dist/capabilities.d.ts +1 -1
- package/dist/capability-catalog.d.ts +44 -11
- package/dist/capability-catalog.js +96 -11
- package/dist/capability-command.d.ts +2 -2
- package/dist/capability-command.js +178 -27
- package/dist/capability-editor.js +6 -5
- package/dist/capability-recipes.js +54 -6
- package/dist/cli-arguments.d.ts +2 -0
- package/dist/cli-arguments.js +101 -50
- package/dist/cli-commands.d.ts +1 -1
- package/dist/cli-commands.js +30 -6
- package/dist/cli-errors.d.ts +18 -0
- package/dist/cli-errors.js +63 -0
- package/dist/cli-output.d.ts +22 -0
- package/dist/cli-output.js +42 -7
- package/dist/command-runner.d.ts +1 -0
- package/dist/command-runner.js +88 -0
- package/dist/command-schema.d.ts +16 -0
- package/dist/command-schema.js +390 -21
- package/dist/completion.d.ts +2 -0
- package/dist/completion.js +201 -0
- package/dist/composition.d.ts +35 -0
- package/dist/composition.js +28 -0
- package/dist/contracts/cli-transport.d.ts +217 -0
- package/dist/contracts/cli-transport.js +167 -0
- package/dist/contracts/deployment.d.ts +282 -0
- package/dist/contracts/deployment.js +234 -0
- package/dist/contracts/environment-file.d.ts +7 -0
- package/dist/contracts/environment-file.js +112 -0
- package/dist/contracts/environment-transport.d.ts +79 -0
- package/dist/contracts/environment-transport.js +110 -0
- package/dist/contracts/runtime-logs-transport.d.ts +127 -0
- package/dist/contracts/runtime-logs-transport.js +50 -0
- package/dist/contracts/source-bundle.d.ts +11 -0
- package/dist/contracts/source-bundle.js +197 -0
- package/dist/contracts/source-profile.d.ts +4 -0
- package/dist/contracts/source-profile.js +5 -0
- package/dist/contracts/staging-transport.d.ts +79 -0
- package/dist/contracts/staging-transport.js +43 -0
- package/dist/dependencies.d.ts +10 -4
- package/dist/dependencies.js +17 -54
- package/dist/index.d.ts +6 -0
- package/dist/index.js +4 -0
- package/dist/launch.d.ts +21 -0
- package/dist/launch.js +250 -0
- package/dist/platform-command.d.ts +9 -0
- package/dist/platform-command.js +584 -0
- package/dist/platform-environment.d.ts +18 -0
- package/dist/platform-environment.js +257 -0
- package/dist/platform-operations.d.ts +26 -0
- package/dist/platform-operations.js +155 -0
- package/dist/platform-source.d.ts +8 -0
- package/dist/platform-source.js +111 -0
- package/dist/platform-state.d.ts +13 -0
- package/dist/platform-state.js +207 -0
- package/dist/platforms/tanstack.d.ts +8 -0
- package/dist/platforms/tanstack.js +155 -0
- package/dist/registry/options.js +34 -31
- package/dist/registry/resolve.js +2 -0
- package/dist/registry/usage.d.ts +4 -1
- package/dist/registry/usage.js +58 -4
- package/dist/scaffold/documentation.js +17 -48
- package/dist/scaffold/styling.d.ts +1 -1
- package/dist/scaffold/workspace.js +11 -7
- package/dist/stack-registry.d.ts +2 -4
- package/dist/stack-registry.js +1 -11
- package/dist/standard.js +21 -6
- package/dist/transaction.js +28 -3
- package/dist/ui-command.d.ts +4 -2
- package/dist/ui-command.js +79 -38
- package/dist/ui-project.d.ts +2 -0
- package/dist/ui-project.js +38 -8
- package/dist/util.js +40 -61
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/capabilities.md +22 -88
- package/docs/software-factory.md +189 -16
- package/docs/stack-standard.md +6 -18
- package/docs/ui.md +9 -22
- package/docs/verification.md +6 -1067
- package/package.json +33 -22
- package/assets/ui/native/_controls.tsx +0 -521
- package/assets/ui/native/_core.tsx +0 -118
- package/assets/ui/native/_data.tsx +0 -200
- package/assets/ui/native/_display.tsx +0 -453
- package/assets/ui/native/_feedback.tsx +0 -242
- package/assets/ui/native/_legacy-dialog.tsx +0 -38
- package/assets/ui/native/_motion.tsx +0 -520
- package/assets/ui/native/_overlay.tsx +0 -402
- package/assets/ui/native/_selection.tsx +0 -366
- package/assets/ui/native/accordion.tsx +0 -1
- package/assets/ui/native/alert-dialog.tsx +0 -11
- package/assets/ui/native/alert.tsx +0 -1
- package/assets/ui/native/aspect-ratio.tsx +0 -1
- package/assets/ui/native/attachment.tsx +0 -8
- package/assets/ui/native/avatar.tsx +0 -8
- package/assets/ui/native/badge.tsx +0 -1
- package/assets/ui/native/breadcrumb.tsx +0 -9
- package/assets/ui/native/bubble.tsx +0 -1
- package/assets/ui/native/button-group.tsx +0 -1
- package/assets/ui/native/button.tsx +0 -86
- package/assets/ui/native/calendar.tsx +0 -170
- package/assets/ui/native/card.tsx +0 -44
- package/assets/ui/native/carousel.tsx +0 -1
- package/assets/ui/native/chart.tsx +0 -193
- package/assets/ui/native/checkbox.tsx +0 -1
- package/assets/ui/native/code-block.tsx +0 -137
- package/assets/ui/native/collapsible.tsx +0 -1
- package/assets/ui/native/combobox.tsx +0 -1
- package/assets/ui/native/command.tsx +0 -11
- package/assets/ui/native/context-menu.tsx +0 -16
- package/assets/ui/native/data-table.tsx +0 -1
- package/assets/ui/native/date-picker.tsx +0 -43
- package/assets/ui/native/dialog.tsx +0 -15
- package/assets/ui/native/direction.tsx +0 -1
- package/assets/ui/native/drawer.tsx +0 -10
- package/assets/ui/native/dropdown-menu.tsx +0 -16
- package/assets/ui/native/empty.tsx +0 -8
- package/assets/ui/native/field.tsx +0 -13
- package/assets/ui/native/hover-card.tsx +0 -1
- package/assets/ui/native/input-group.tsx +0 -8
- package/assets/ui/native/input-otp.tsx +0 -1
- package/assets/ui/native/input.tsx +0 -28
- package/assets/ui/native/item.tsx +0 -12
- package/assets/ui/native/kbd.tsx +0 -1
- package/assets/ui/native/label.tsx +0 -4
- package/assets/ui/native/layout.tsx +0 -26
- package/assets/ui/native/marker.tsx +0 -1
- package/assets/ui/native/menubar.tsx +0 -17
- package/assets/ui/native/message-scroller.tsx +0 -6
- package/assets/ui/native/message.tsx +0 -10
- package/assets/ui/native/native-select.tsx +0 -1
- package/assets/ui/native/navigation-menu.tsx +0 -10
- package/assets/ui/native/pagination.tsx +0 -9
- package/assets/ui/native/popover.tsx +0 -1
- package/assets/ui/native/progress.tsx +0 -1
- package/assets/ui/native/questionnaire.tsx +0 -130
- package/assets/ui/native/radio-group.tsx +0 -1
- package/assets/ui/native/registry.json +0 -1103
- package/assets/ui/native/resizable.tsx +0 -1
- package/assets/ui/native/scroll-area.tsx +0 -1
- package/assets/ui/native/select.tsx +0 -11
- package/assets/ui/native/separator.tsx +0 -1
- package/assets/ui/native/sheet.tsx +0 -10
- package/assets/ui/native/sidebar.tsx +0 -22
- package/assets/ui/native/skeleton.tsx +0 -1
- package/assets/ui/native/slider.tsx +0 -1
- package/assets/ui/native/spinner.tsx +0 -1
- package/assets/ui/native/switch.tsx +0 -1
- package/assets/ui/native/table.tsx +0 -10
- package/assets/ui/native/tabs.tsx +0 -1
- package/assets/ui/native/text.tsx +0 -20
- package/assets/ui/native/textarea.tsx +0 -1
- package/assets/ui/native/theme-switcher.tsx +0 -22
- package/assets/ui/native/toast.tsx +0 -11
- package/assets/ui/native/toggle-group.tsx +0 -1
- package/assets/ui/native/toggle.tsx +0 -1
- package/assets/ui/native/tooltip.tsx +0 -1
- package/assets/ui/native/trace.tsx +0 -20
- package/assets/ui/native/typography.tsx +0 -15
- package/assets/ui/theme-storage.ts +0 -25
- package/assets/ui/theme.tsx +0 -66
- package/dist/platforms/mobile.d.ts +0 -2
- package/dist/platforms/mobile.js +0 -137
- package/dist/scaffold/expo-runtime.d.ts +0 -3
- package/dist/scaffold/expo-runtime.js +0 -42
- package/dist/scaffold/native-ui.d.ts +0 -2
- package/dist/scaffold/native-ui.js +0 -74
- package/docs/anhedral-stack.md +0 -7
- package/docs/native-ui.md +0 -102
package/docs/capabilities.md
CHANGED
|
@@ -1,110 +1,44 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Anhedral Stack additions
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
There is one current **Anhedral Stack**. `anhedral init` creates its web foundation with TanStack Start SSR/server functions and source-owned shadcn Anhedral UI. Add the remaining services only when needed.
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
anhedral init my-app
|
|
7
7
|
cd my-app
|
|
8
|
-
anhedral
|
|
9
|
-
anhedral add
|
|
10
|
-
anhedral add
|
|
11
|
-
anhedral add database-auth
|
|
8
|
+
anhedral add backend --dry-run --json
|
|
9
|
+
anhedral add backend
|
|
10
|
+
anhedral add r2 stripe
|
|
12
11
|
anhedral stack status --json
|
|
13
12
|
```
|
|
14
13
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
## Capabilities
|
|
18
|
-
|
|
19
|
-
| Name | Adds | Required source capabilities |
|
|
14
|
+
| Selection | Source added | Requires |
|
|
20
15
|
| --- | --- | --- |
|
|
21
|
-
| `
|
|
22
|
-
| `
|
|
23
|
-
| `
|
|
24
|
-
| `stripe` | Stripe SDK, Checkout subscription starter, signed webhook receipts, canonical access checks | `database-auth` |
|
|
25
|
-
| `realtime` | Authenticated D1-backed events and resumable SSE | `database-auth` |
|
|
26
|
-
| `rtc` | Cloudflare Realtime SFU session/track adapter with ownership checks | `database-auth` |
|
|
27
|
-
| `ai` | Workers AI binding, authenticated text-generation route and atomic daily quota | `database-auth` |
|
|
28
|
-
| `expo` | Expo app and Better Auth/SecureStore client | `database-auth` |
|
|
29
|
-
| `native-ui` | NativeWind 4, shared theme CSS, RNR Button/Text starter, portal/root adapter, UI catalog metadata | `expo` |
|
|
30
|
-
| `revenuecat` | Native subscription SDK/UI, scoped webhooks and server-side entitlement reconciliation | `expo`, `stripe` |
|
|
31
|
-
| `wxt` | WXT React extension, scoped API host permission and editable popup | `database-auth` |
|
|
32
|
-
| `side-panel` | Chromium Side Panel entrypoint and background registration | `wxt` |
|
|
33
|
-
| `gpui` | Rust/GPUI desktop application and native build scripts | `database-auth` |
|
|
34
|
-
|
|
35
|
-
The progression is Next.js → Hono → database/auth, followed by independently selected branches. These are Anhedral's source-builder rules, not intrinsic restrictions of those technologies. `anhedral ui` still requires only the target Next.js or Expo application; it has no backend prerequisite. See [UI commands](ui.md).
|
|
36
|
-
|
|
37
|
-
```sh
|
|
38
|
-
anhedral add expo native-ui --dry-run --json
|
|
39
|
-
anhedral add side-panel --with-dependencies --dry-run --json
|
|
40
|
-
anhedral add r2 stripe
|
|
41
|
-
anhedral add realtime rtc ai
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
Missing prerequisites stop the command before writes. Explicitly list the parents in the same command, or choose `--with-dependencies` to include them in dependency order. There is no `add all` shortcut that silently chooses every optional branch.
|
|
45
|
-
|
|
46
|
-
## Protecting existing applications
|
|
47
|
-
|
|
48
|
-
Additions require an Anhedral workspace with a Next.js foundation. They do not reinitialize it. All selected recipes are planned in memory before any installation. A late collision rejects the entire plan. JSON/JSONC changes preserve unrelated keys and comments; existing bindings and dependency pins that conflict require reconciliation. New source files never replace existing files.
|
|
49
|
-
|
|
50
|
-
CLI-owned composition adapters are fingerprinted in `anhedral.json`. Their edits are protected too: if an adapter was customized, a later addition stops rather than replacing it. Add business routes in `apps/api/src/index.ts`, custom binding/variable types in `custom-environment.ts`, auth methods in `auth-features.ts`/`auth.ts`, and native product UI in `apps/mobile/App.tsx`. Keep additional application behavior outside composition adapters.
|
|
51
|
-
|
|
52
|
-
Source writes use the existing journaled transaction/recovery implementation. Dependency resolution/install follows source commit; if installation fails, the CLI reports a post-commit error and retains the source for review and retry. Reviewed dependency patches are configured before the frozen install. `--skip-install` leaves dependency resolution/patch staging to a subsequent normal CLI installation or explicit consumer setup. `--dry-run` makes no writes or network requests, including transaction metadata.
|
|
53
|
-
|
|
54
|
-
Repeated additions leave source unchanged; the normal command still resolves and installs dependencies so it can recover from an earlier install failure. Use `--skip-install` for a source-only no-op. There is no removal command, provider deletion or implicit D1/R2 data deletion. An inconsistent parent/child declaration is rejected. Earlier full-stack generators and arbitrary custom layouts are not automatically adopted or overlaid; inspect their source and reconcile conflicts explicitly.
|
|
55
|
-
|
|
56
|
-
## Source state and activation
|
|
57
|
-
|
|
58
|
-
`stack list` shows the complete catalog. `stack status` reports `locked`, `available`, `installed` or `incomplete` source state. `stack doctor` exits unsuccessfully when declared source is missing. Neither command inspects live providers or proves deployment/activation. An installed capability can still need credentials, migrations, resource IDs and runtime verification.
|
|
59
|
-
|
|
60
|
-
The intended operational sequence remains source selection → resource provisioning → bindings/secrets/migrations → runtime validation/deployment → verified active service. Client binaries run on their target platforms, independently of Cloudflare server deployments.
|
|
61
|
-
|
|
62
|
-
## Configuration and local validation
|
|
63
|
-
|
|
64
|
-
Run dependency installation, inspect the generated files, then run `pnpm check`. The normal `add` path resolves lockfiles, stages any applicable reviewed patches and performs a frozen install. The consumer's `audit:deps` retains raw findings and accepts only the existing reviewed exact patches. Source-only generation does not apply a patch to a dependency that has not been resolved yet.
|
|
65
|
-
|
|
66
|
-
For API development, use the web service binding in production and `API_INTERNAL_URL=http://127.0.0.1:8787` in `apps/web/.env.local` locally. Copy selected API values from `apps/api/.dev.vars.example` to `.dev.vars`; never put server secrets in client public variables. Set a sufficiently long auth secret and the actual `PUBLIC_APP_URL` before enabling identity-dependent features.
|
|
67
|
-
|
|
68
|
-
D1's initial resource ID is deliberately a placeholder. Configure the actual D1 identity and private R2 bucket yourself. Keep R2 public access disabled. Generate and review additional SQL, then deliberately apply it to an isolated local database:
|
|
69
|
-
|
|
70
|
-
```sh
|
|
71
|
-
pnpm db:generate
|
|
72
|
-
pnpm db:migrate --local
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
Builds and startup never migrate. Remote migration requires explicit `--remote` and deliberate resource selection. No configured database is migrated by this repository's tests.
|
|
76
|
-
|
|
77
|
-
Better Auth starts with email/password disabled, and no OAuth, passkeys, MFA or organization plugins silently activated. Enable chosen methods explicitly after configuring their credentials, email/policies, schemas and client flows. The included sign-in UI is an email/password example, not automatic method activation. Regenerate/review migrations when adding auth plugins.
|
|
78
|
-
|
|
79
|
-
## Payments
|
|
80
|
-
|
|
81
|
-
The included routes form a subscription starter, rather than a complete commerce product. Choose the allowed Stripe price and RevenueCat entitlement. `BILLING_PROVIDER` selects `stripe`, `revenuecat` or `either` for the shared server access guard. The default billing environment is `sandbox`; a deliberate `BILLING_ENVIRONMENT=live` selection must match the provider key and webhook environment. The CLI sets neither live credentials nor live mode.
|
|
82
|
-
|
|
83
|
-
Checkout derives identity from the authenticated session, uses a server-selected price and requires an idempotency key. Stripe verifies the untouched body/signature through the web proxy. RevenueCat validates its configured authorization header, app scope and environment. D1 receipts deduplicate delivery. Webhook order, redirects and SDK callbacks never grant access.
|
|
84
|
-
|
|
85
|
-
The server re-reads canonical provider state, checks identity/product/environment/expiry, and fails closed on unavailable or unconfigured providers. Reuse `requireSession` and `requireEntitlement` on paid application routes. `/api/billing/access` demonstrates that guard. SDK account changes are serialized; native sign-out disconnects purchases before clearing the app session. One-time fulfillment, credits, tax, marketplace/Connect, pricing and store-policy decisions remain application work.
|
|
16
|
+
| `backend` | Hono API, Drizzle/D1, Better Auth and web sign-in starter | Anhedral Stack web foundation |
|
|
17
|
+
| `r2` | Private storage binding and authenticated owner-scoped file routes | `backend` |
|
|
18
|
+
| `stripe` | Subscription Checkout, signed webhooks and canonical entitlement checks | `backend` |
|
|
86
19
|
|
|
87
|
-
|
|
20
|
+
`backend` is one public selection; its provenance records the concrete Hono and database/auth capabilities. Use `--with-dependencies` to include missing prerequisites in the same planned source transaction. `stack list` describes this stack's additions. `status`/`doctor` check source completeness, not live service activation.
|
|
88
21
|
|
|
89
|
-
##
|
|
22
|
+
## Source protection
|
|
90
23
|
|
|
91
|
-
|
|
24
|
+
Additions never reinitialize an application. They plan all selected changes before writing, reject collisions and preserve unrelated JSON/JSONC settings. Composition adapters are fingerprinted in `anhedral.json`; modified adapters require reconciliation instead of silent replacement. Add product routes in `apps/api/src/index.ts`, custom types in `custom-environment.ts`, and auth method configuration in `auth-features.ts`/`auth.ts`.
|
|
92
25
|
|
|
93
|
-
|
|
26
|
+
Journaled transactions preserve recovery evidence and refuse ambiguous recreated files. Dependency installation follows source commit; a post-commit install failure keeps source for repair/retry. Reviewed dependency patches precede the frozen install. `--skip-install` writes source only. `--dry-run` performs no writes or network requests. Repeating an addition preserves source; normal installation may still retry dependencies.
|
|
94
27
|
|
|
95
|
-
|
|
28
|
+
There is no implicit capability removal or resource/data deletion. Existing applications retain their source and identity. Legacy generators and broader recipe implementations are retained for compatibility and recovery, not exposed as current stack options.
|
|
96
29
|
|
|
97
|
-
##
|
|
30
|
+
## Local setup and validation
|
|
98
31
|
|
|
99
|
-
|
|
32
|
+
Minimal `pnpm dev` runs the web Worker. After backend is added, Vite also runs its auxiliary Hono Worker in the same process using isolated local D1 and optional R2. Copy `apps/api/.dev.vars.example` to `.dev.vars`; configure `PUBLIC_APP_URL` and a private `BETTER_AUTH_SECRET`. Never put server secrets in web/public variables.
|
|
100
33
|
|
|
101
|
-
|
|
34
|
+
Review initial SQL, then deliberately run `pnpm db:migrate --local`. For later schema additions, run `pnpm db:generate`, inspect the SQL and apply it explicitly. Remote migration requires deliberate `--remote` selection. Builds, startup and ordinary checks never migrate a configured database.
|
|
102
35
|
|
|
103
|
-
|
|
36
|
+
Better Auth methods start disabled. Configure credentials, email/policy, schema and client flows before enabling chosen methods. The sign-in page is an example, not automatic activation. R2 remains private and file routes enforce authenticated ownership.
|
|
104
37
|
|
|
105
|
-
|
|
38
|
+
Stripe adds source/schema, not a live payment service. Generate and review its billing migration before webhook tests. Configure test credentials, allowed prices and signed webhooks deliberately. Server-side canonical provider state controls entitlements; redirects, client claims and webhook ordering do not grant access. Live mode and real charges require separate activation.
|
|
106
39
|
|
|
40
|
+
## Source and hosting contracts
|
|
107
41
|
|
|
108
|
-
|
|
42
|
+
`anhedral.json` records nonsecret generator/capability versions and identity. Source provenance never grants hosting authority. The public deployment manifest uses runtime profile `anhedral-stack` for the web foundation and selected backend/R2/Stripe composition. Artifact identity, resource provisioning, secrets, migrations, runtime checks and production approval remain server-owned. See [the workflow](software-factory.md#platform-cli-access-and-source-upload).
|
|
109
43
|
|
|
110
|
-
|
|
44
|
+
Run `pnpm check` and `pnpm audit:deps` in generated applications. Framework/runtime, provider and browser acceptance are distinct; source installation alone establishes none of them.
|
package/docs/software-factory.md
CHANGED
|
@@ -1,26 +1,199 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Anhedral Stack workflow
|
|
2
2
|
|
|
3
|
-
Anhedral
|
|
3
|
+
The Anhedral Stack has one current web foundation and progressive backend/storage/payment additions. There is no public stack selection or independent stack-registry repository.
|
|
4
4
|
|
|
5
|
-
1.
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
5
|
+
1. Preview an empty destination with `anhedral init my-app --dry-run --json`, then
|
|
6
|
+
run `anhedral init my-app` and `pnpm dev` inside it.
|
|
7
|
+
2. Read the generated README, AGENTS, `anhedral.json`, environment examples and
|
|
8
|
+
Wrangler configuration. Use their recorded tool versions.
|
|
9
|
+
3. Preview and add [capabilities](capabilities.md) as needed. Configure selected
|
|
10
|
+
providers/auth methods, apply reviewed migrations and validate actual runtime
|
|
11
|
+
behavior before deployment. Source installation is not provider activation.
|
|
12
|
+
4. Extend [source-owned UI](ui.md), implement features and run consumer checks.
|
|
11
13
|
|
|
12
|
-
|
|
14
|
+
## Evidence-driven maintenance
|
|
13
15
|
|
|
14
|
-
|
|
16
|
+
Inspect current Git state and preserve unrelated work. Verify runtime entrypoints,
|
|
17
|
+
exports, generated consumers and operational safeguards before removing source;
|
|
18
|
+
static findings and passing tests alone do not prove a path is unused.
|
|
15
19
|
|
|
16
|
-
|
|
20
|
+
Update the existing owning guide with behavior changes. Keep exact versions and
|
|
21
|
+
defaults in manifests/source, not duplicated narratives. Store dated development,
|
|
22
|
+
audit and verification notes in
|
|
23
|
+
[docs/agent-notes](https://github.com/anhedral/anhedral-cli/tree/main/docs/agent-notes),
|
|
24
|
+
with revision, checks, failures and remaining gaps. Keep raw reports in ignored
|
|
25
|
+
`.artifacts/`. Historical notes are not current instructions.
|
|
17
26
|
|
|
18
|
-
|
|
27
|
+
Canonical docs live in `docs/`; `pnpm build` refreshes bundled plugin references.
|
|
28
|
+
Current generated app guidance lives in `src/launch.ts`; retained compatibility generators have their own source guidance. Preserve shipped
|
|
29
|
+
reference paths, source-generation safety, dependency patch gates, UI provenance,
|
|
30
|
+
licenses and exact-artifact packaging. A build does not publish npm or update an
|
|
31
|
+
installed plugin. See [Contributing](https://github.com/anhedral/anhedral-cli/blob/main/.github/CONTRIBUTING.md)
|
|
32
|
+
for staging, release identity and validation tiers.
|
|
19
33
|
|
|
20
|
-
|
|
34
|
+
This repository also works as a Git submodule. Its own `pnpm-workspace.yaml`,
|
|
35
|
+
lockfile and safe `.npmrc` keep installs independent of a parent workspace;
|
|
36
|
+
the parent must exclude the CLI from its package graph. Run install/build/tests
|
|
37
|
+
inside this checkout with its pinned package manager. Commit public changes here
|
|
38
|
+
separately, then update the parent's Git pointer only after that commit is reviewed
|
|
39
|
+
and available in this repository. Never copy parent configuration, credentials or
|
|
40
|
+
implementation into this checkout. Public CI checks out only this repository,
|
|
41
|
+
without recursive submodules; publishing rejects calls from another repository.
|
|
42
|
+
These checks do not make a submodule a security sandbox: review tracked files,
|
|
43
|
+
package contents, inherited environment and publication authority independently.
|
|
21
44
|
|
|
22
|
-
|
|
45
|
+
The reviewed public module inventory in `scripts/public-package-policy.json` and
|
|
46
|
+
`pnpm check:boundaries` constrain compilation and package preparation; an unexpected
|
|
47
|
+
dist module or private import requires explicit review. Portable contracts are
|
|
48
|
+
synced only from a reviewed, licensed Platform projection with exact provenance,
|
|
49
|
+
never as a build side effect. Local credential scanning additionally retains the
|
|
50
|
+
CLI's stricter source-upload policy. Plugin packaging accepts its explicit reviewed
|
|
51
|
+
MCP-inclusive file set, refuses linked distribution roots and verifies the bounded
|
|
52
|
+
publisher archive format before npm publication. Oversized unscanned text is an
|
|
53
|
+
explicit review failure, not a clean secret scan.
|
|
23
54
|
|
|
24
|
-
|
|
55
|
+
## Runtime verification
|
|
25
56
|
|
|
26
|
-
|
|
57
|
+
Routine CI compiles the CLI once and runs fast source/security checks and selected
|
|
58
|
+
contract tests. Generated applications are not installed or built in that path.
|
|
59
|
+
Dispatch [CI](https://github.com/anhedral/anhedral-cli/blob/main/.github/workflows/ci.yml) with `runtime_proof` enabled for the
|
|
60
|
+
Anhedral Stack proof and one-day measurements. Broader compatibility and generated
|
|
61
|
+
application matrices remain in [Full validation](https://github.com/anhedral/anhedral-cli/blob/main/.github/workflows/validation.yml).
|
|
62
|
+
|
|
63
|
+
`node scripts/tanstack-runtime-smoke.mjs` installs a disposable Anhedral Stack
|
|
64
|
+
application and exercises local workerd, SSR/server functions, progressive backend,
|
|
65
|
+
private storage and the generated Stripe build/migration path. It uses isolated
|
|
66
|
+
local data, never a configured database or live payment provider. Retained
|
|
67
|
+
Next/OpenNext proof commands cover compatibility code only; they are not another
|
|
68
|
+
public stack. Preserve source/tool/lock identities and distinguish prepared,
|
|
69
|
+
passed and failed evidence. Tests are not provider deployment acceptance.
|
|
70
|
+
|
|
71
|
+
## Platform CLI access and source upload
|
|
72
|
+
|
|
73
|
+
`login --start` prints browser approval instructions; `login --resume` redeems the
|
|
74
|
+
saved approval. Interactive `login` polls after showing the URL and confirmation
|
|
75
|
+
code. Tokens and device secrets use macOS Keychain or Linux Secret Service;
|
|
76
|
+
`--credential-file <path>` explicitly selects an owner-only file. Credential
|
|
77
|
+
storage is currently unsupported on Windows. Credentials are
|
|
78
|
+
bound to the explicit `--api-url` origin (HTTPS, with literal loopback for fixtures).
|
|
79
|
+
Do not use repository configuration to select the credential destination. `logout`
|
|
80
|
+
revokes server access before removing the saved credential; `whoami` checks live
|
|
81
|
+
identity. Add `whoami --context --human` (or `--context --json`) to inspect the
|
|
82
|
+
selected origin, credential-store kind and saved local team/project link. Identity
|
|
83
|
+
is checked live; the saved project link is explicitly not proof of current project
|
|
84
|
+
access. A link for a different origin or principal fails closed. Normal `whoami`
|
|
85
|
+
JSON is unchanged and context inspection never creates a project or starts login.
|
|
86
|
+
Explicit `--api-url` and `--credential-file` select the origin/store; saved state
|
|
87
|
+
cannot override either. API access must be separately enabled by Platform operators.
|
|
88
|
+
|
|
89
|
+
`link --project <uuid> --team <uuid>` checks current build authority and saves an
|
|
90
|
+
origin/principal-bound link under ignored `.anhedral/platform/`. `unlink` removes
|
|
91
|
+
that local link. `source upload --dry-run` inspects packaging; `source upload`
|
|
92
|
+
resumes the same immutable source request after interruption, including lost
|
|
93
|
+
responses. `source status` reads its server receipt. Changed source requires an
|
|
94
|
+
explicit `source upload --new`; an expired request also requires a new request.
|
|
95
|
+
The client honors nested `.gitignore`, excludes generated output and secret paths,
|
|
96
|
+
rejects symlinks and recognized credential material, and hashes every bounded
|
|
97
|
+
chunk plus the complete archive and canonical source inventory. The generated
|
|
98
|
+
`apps/web/src/routeTree.gen.ts` is excluded because the router regenerates it during
|
|
99
|
+
checks/builds; authored routes, router configuration and server source remain
|
|
100
|
+
included. Credential scanning is deliberately conservative; inspect source before uploading.
|
|
101
|
+
|
|
102
|
+
Public upload limits and message shapes live in `src/contracts`; protocol code is
|
|
103
|
+
in `src/platform-command.ts`. The server independently authenticates the caller,
|
|
104
|
+
checks current tenant/project authority and revocation, validates source, and
|
|
105
|
+
enforces admission. Client checks and supplied IDs cannot grant access. Upload
|
|
106
|
+
does not deploy, activate providers, migrate a database or replace identities.
|
|
107
|
+
Run `tests/test-platform.test.mjs` after building for isolated client fixtures.
|
|
108
|
+
|
|
109
|
+
`deploy plan --manifest <file>` plans from the saved sealed upload, independently
|
|
110
|
+
of subsequent local edits. The manifest follows Platform's `deploymentManifestSchema`
|
|
111
|
+
in `src/contracts/deployment.ts`; it must match the archive's recorded composition,
|
|
112
|
+
capabilities, CLI version and existing standalone identity. Runtime-profile admission is server-owned. Staged server sources include Hono/D1
|
|
113
|
+
and web candidates; source support does not establish a deployed cohort or provider readiness. Plans bind source/lockfile/migrations,
|
|
114
|
+
routing state, principal epoch and project authority. Artifact provenance and
|
|
115
|
+
runtime configuration remain explicitly unverified; null receipts are not approval.
|
|
116
|
+
Anhedral Stack source composition version 2 records framework foundation
|
|
117
|
+
`tanstack-start`; the public runtime profile is `anhedral-stack`. Its five compositions are
|
|
118
|
+
web-only, backend (`hono` plus `database-auth`), backend/R2, backend/Stripe and
|
|
119
|
+
backend/R2/Stripe. Backend manifests preserve `better-auth-d1-v1`; web-only uses
|
|
120
|
+
`none`. Broader retained capability/protocol values are compatibility implementation,
|
|
121
|
+
not current public selections or hosted support.
|
|
122
|
+
Continue selecting an explicit manifest; the CLI never infers an admitted artifact
|
|
123
|
+
from locally generated source. Native candidate receipts name an immutable registry
|
|
124
|
+
image with `scope: candidate-workspace`; legacy isolated-build receipts remain valid.
|
|
125
|
+
Both describe build admission, not production approval.
|
|
126
|
+
|
|
127
|
+
`deploy prepare` reserves an immutable candidate. `deploy status` reads
|
|
128
|
+
`awaiting-runtime`, `building`, `built`, `ready` or `failed`. A built candidate grants no
|
|
129
|
+
preview or publishing capability. A `ready` receipt reports Platform-admitted hosted
|
|
130
|
+
readiness; it does not approve production publication. Runtime admission and build
|
|
131
|
+
enforcement remain server-owned. These commands never provision, migrate, activate a preview or
|
|
132
|
+
deploy. Lost responses resume the same saved request. Changed manifest inputs or
|
|
133
|
+
routing require `deploy plan --manifest <file> --new`. Plan/source expiry and
|
|
134
|
+
revocation fail closed. State under `.anhedral/platform/deployment.json` contains
|
|
135
|
+
no credentials and cannot select a network origin or change the signed-in identity.
|
|
136
|
+
|
|
137
|
+
`env list` returns names, types, environments and versions. `env import --environment
|
|
138
|
+
staging|production --file <path>` reads a private dotenv file; `--stdin` accepts a
|
|
139
|
+
pipe. `env set <NAME>` reads one literal value from a file or pipe. Values are
|
|
140
|
+
never arguments, output or retry-state contents. Non-public names default to
|
|
141
|
+
secrets; `--type config` is explicit readable configuration. Public-prefixed
|
|
142
|
+
secrets, reserved names, duplicate names and oversized input fail before upload.
|
|
143
|
+
Files require owner-only permissions and a regular non-symlink final file;
|
|
144
|
+
ancestor checks reject observed symlinks but are not an atomic directory lock.
|
|
145
|
+
Use `--dry-run` without authentication for names/types only. Actual imports bind
|
|
146
|
+
API origin, principal, team, project and environment, require `--replace` for
|
|
147
|
+
existing variables, and resume one request after a lost response. Use `--new` for
|
|
148
|
+
a different import. Receipts are checked against names, types and expected versions.
|
|
149
|
+
Production changes remain subject to Platform approval and deployment policy.
|
|
150
|
+
|
|
151
|
+
`staging status` reads persistent staging history. `staging deploy --candidate
|
|
152
|
+
<uuid>` selects a ready candidate, freezes the current staging configuration and
|
|
153
|
+
retains one generation-bound request across retries. `--new` starts another
|
|
154
|
+
deployment after reviewing the current state. Saved receipts must match their
|
|
155
|
+
project, candidate, request and generation before replay. CLI runtime admission remains a
|
|
156
|
+
separate server gate; a built source upload alone is not a ready candidate.
|
|
157
|
+
`logs` reads bounded, redacted runtime events, defaulting to staging. Select
|
|
158
|
+
production explicitly with `--environment production`; filter by deployment,
|
|
159
|
+
level, source or range, and pass `--cursor` for the next page. Coverage, dropped
|
|
160
|
+
events and seven-day retention are part of the response.
|
|
161
|
+
|
|
162
|
+
The plugin includes source skills plus one remote MCP connection at
|
|
163
|
+
`https://platform.anhedral.com/api/mcp`. OAuth consent grants scoped project
|
|
164
|
+
access; CLI credentials are separate. Secret imports initiated through ChatGPT
|
|
165
|
+
open a secure browser form rather than accepting values as tool arguments.
|
|
166
|
+
The plugin packages no executable server, credential or authorization header. Its root `mcp.json` uses the [official remote OAuth declaration](https://developers.openai.com/plugins/build/plugins#bundled-mcp-servers-and-lifecycle-hooks), DCR and read-only default scopes; write access requires additional consent.
|
|
167
|
+
Server features remain unavailable until their operator-controlled gates are enabled.
|
|
168
|
+
|
|
169
|
+
The CLI and plugin share one release version. Build prepares the
|
|
170
|
+
marketplace pointer to that version's immutable `plugin-v<version>` tag; it does
|
|
171
|
+
not create the tag or publish either artifact. During review that pointer may be
|
|
172
|
+
unavailable. Install an already published version until the coordinated release
|
|
173
|
+
has completed and its tag and artifact integrities have been verified.
|
|
174
|
+
|
|
175
|
+
## CLI presentation compatibility
|
|
176
|
+
|
|
177
|
+
The command schema owns options, nested help and offline shell completion. Root
|
|
178
|
+
help is an index; leaf help includes examples. Keep executable and exported parser
|
|
179
|
+
contracts covered by `test-cli-discovery`, `test-cli-experience`, `test-cli-output`,
|
|
180
|
+
`test-completion` and `test-platform-ux`. The CI gate runs these alongside existing
|
|
181
|
+
contracts; the executable suite accepts `ANHEDRAL_CLI_BIN` to validate an installed
|
|
182
|
+
exact candidate without contacting Platform.
|
|
183
|
+
|
|
184
|
+
Results belong on stdout; errors and permitted diagnostics belong on stderr.
|
|
185
|
+
Platform retains implicit compact JSON for compatibility, with opt-in `--human`.
|
|
186
|
+
Other families retain human defaults and explicit `--json`. Quiet suppresses
|
|
187
|
+
ordinary results unless JSON was explicitly requested. Explicit JSON, quiet,
|
|
188
|
+
headless input/output, CI and `--non-interactive` cannot initiate interactive
|
|
189
|
+
approval polling; `login --resume` explicitly redeems an existing approval.
|
|
190
|
+
|
|
191
|
+
Numeric failure status remains 1. Existing error fields/code families remain;
|
|
192
|
+
usage errors classify invalid origins and selectors before credential/network
|
|
193
|
+
access, including environment, staging and log selectors. Credential-store helpers
|
|
194
|
+
have bounded execution. Logout revokes server access first; a failed local deletion
|
|
195
|
+
reports cleanup still pending instead of successful logout. Categories and retryability are additive diagnostics, not authorization
|
|
196
|
+
to repeat a mutation. In particular, post-commit failures retain source, expose
|
|
197
|
+
committed paths and require repairing only the failed follow-up. Upload/deployment
|
|
198
|
+
retries keep the existing immutable request identity. None of these presentation
|
|
199
|
+
changes alters server admission or activates hosted execution.
|
package/docs/stack-standard.md
CHANGED
|
@@ -1,23 +1,11 @@
|
|
|
1
|
-
# Stack
|
|
1
|
+
# Anhedral Stack
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Anhedral Stack** is the single current stack. The CLI generates its editable source; Platform independently owns managed builds, resource admission, deployment and operations. There is no public multi-stack registry or framework selector.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The web foundation uses TanStack Start SSR/server functions and source-owned shadcn Anhedral UI. `anhedral init` creates only that foundation. `add backend` composes Hono, Drizzle/D1 and Better Auth together. Add private R2 or Stripe subscriptions later when needed. See [additions](capabilities.md).
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
When selected, Hono owns privileged business/auth/data/storage operations. Web server functions call its scoped service binding; application source is never imported across application boundaries. Keep resources private, enforce identity/ownership/limits and configure secrets per environment.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Auth methods and payment providers require explicit activation. Apply reviewed migrations separately from builds/startup. Source-owned UI preserves semantic tokens, consumer edits and upstream licensing; see [UI ownership](ui.md).
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
## Anhedral UI
|
|
14
|
-
|
|
15
|
-
Anhedral UI is thin orchestration over official shadcn web and React Native Reusables native source. Its maintained surface is a versioned component catalog, CLI routing, setup metadata and a small reviewed native extension registry. Native resolution prefers an Anhedral extension, then RNR, then reports unavailable. The extension registry is initially empty. Do not revive the exhaustive native shadcn fork or require every component to reach parity before shipping a useful feature.
|
|
16
|
-
|
|
17
|
-
New web applications include a bounded Button/Input/Label starter and MIT attribution. Additional components are installed by the pinned shadcn CLI. Native currently supports the RNR NativeWind 4 registry only, in an already configured Expo application. Keep matching React/React Native/Expo dependencies and test the consuming app. The UI layer has no dependency on Hono, D1 or Better Auth.
|
|
18
|
-
|
|
19
|
-
Components belong to the consumer's source tree. Retain upstream licenses, use semantic theme tokens, review diffs and preserve local edits. No runtime UI package or automatic overwrite/update is introduced. Catalog availability means an upstream source exists; it does not assert API parity, accessibility or device acceptance. See [UI commands](ui.md).
|
|
20
|
-
|
|
21
|
-
## Operations and compatibility
|
|
22
|
-
|
|
23
|
-
Init writes editable source and can install dependencies and initialize Git. It never provisions providers, creates credentials, deploys or registers a managed project. Consumers own application security and operations; Platform is a separate managed product. Existing applications, native port work and Platform runtime artifacts retain their explicit reviewed pins until separately adopted. A CLI build or release does not update them.
|
|
11
|
+
Recorded source provenance is not a hosting receipt. Runtime profile `anhedral-stack` identifies the current deployment contract; exact artifact/runtime policy, current authority and production approval still apply. Retained historical wire values and programmatic generators exist only for compatibility, not additional public stacks. Existing applications and runtime pins are not silently migrated.
|
package/docs/ui.md
CHANGED
|
@@ -1,33 +1,20 @@
|
|
|
1
1
|
# Anhedral UI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Anhedral UI is the source-owned web UI layer of the **Anhedral Stack**, using official shadcn and semantic theme tokens. It is a catalog/installer convention, not another runtime component library.
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
anhedral ui list --json
|
|
7
|
-
anhedral ui
|
|
8
|
-
anhedral ui
|
|
9
|
-
anhedral ui
|
|
10
|
-
anhedral ui diff button --native
|
|
11
|
-
anhedral ui doctor --all
|
|
12
|
-
anhedral ui add card --all --dry-run --json
|
|
7
|
+
anhedral ui add card --web
|
|
8
|
+
anhedral ui diff card --web
|
|
9
|
+
anhedral ui doctor --web
|
|
13
10
|
```
|
|
14
11
|
|
|
15
|
-
|
|
12
|
+
Init already creates web UI configuration and reviewed Button, Input and Label source. `list` reads the packaged web catalog offline. `init`, `add`, `diff` and `doctor` select an Anhedral Stack web application through the working directory or `--cwd`; `--web` is optional. Current public commands do not select mobile/native targets or arbitrary framework applications.
|
|
16
13
|
|
|
17
|
-
|
|
14
|
+
`--dry-run --json` previews configuration/installation without network or writes. Selected destinations, metadata and attribution paths are preflighted before installation. CLI-owned writes refuse symlinked metadata destinations. Bounded consumer manifest/configuration links remain supported where their targets are regular files. Ambiguous or invalid targets stop before installation.
|
|
18
15
|
|
|
19
|
-
|
|
16
|
+
The pinned official shadcn CLI resolves registry dependencies and copies source. `add` never requests overwrite; review diffs and reconcile customizations explicitly. `diff` delegates to the upstream preview. Installer failure can leave partial upstream changes, so inspect Git before retrying.
|
|
20
17
|
|
|
21
|
-
`
|
|
18
|
+
`assets/ui/catalog.json` owns the web inventory and pinned installer. `.anhedral-ui.json` records catalog/platform ownership, not automatic updates or runtime certification. Preserve applicable MIT notices under `ANHEDRAL_UI_LICENSES/`, existing components, semantic tokens and source attribution.
|
|
22
19
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
## Ownership and provenance
|
|
26
|
-
|
|
27
|
-
`assets/ui/catalog.json` records the catalog revision, upstream sources, dependency metadata and pinned installer. Availability is not parity or runtime certification. RNR URLs are live upstream endpoints; the catalog's recorded source revision describes the inventory, not an immutable downloaded artifact. Review registry changes before installing into sensitive consumers.
|
|
28
|
-
|
|
29
|
-
`.anhedral-ui.json` records platform, catalog revision and source ownership; it does not automatically update components. `ANHEDRAL_UI_LICENSES/` retains the relevant MIT notice. No Anhedral runtime package is introduced. Theme through consumer CSS variables and existing tokens. Future native extensions require a focused product need, upstream provenance/license and native consumer evidence; broad parity is not a release prerequisite.
|
|
30
|
-
|
|
31
|
-
Validate web flows in a browser. Validate native interactions in Android/iOS development builds, including accessibility, overlays, keyboard and lifecycle. Typechecking or an Expo web export does not establish device acceptance. Legacy `docs/native-ui.md` describes the retained earlier port, not this new default UI layer.
|
|
32
|
-
|
|
33
|
-
For a generated Anhedral workspace, `anhedral add expo` creates the native application after its core source prerequisites, and `anhedral add native-ui` prepares its NativeWind/RNR integration without replacing product UI. The UI component commands remain independent of backend activation. See [stack additions](capabilities.md).
|
|
20
|
+
Validate browser behavior, keyboard focus and interactions. Typechecking or source completeness alone is not browser acceptance. Backend services are independent additions; UI installation does not require authentication, a database or storage. See [stack additions](capabilities.md).
|