anhedral 0.1.6 → 0.1.8

package/README.md

@@ -1,74 +1,117 @@
-# anhedral
+# Anhedral
 
-Opinionated init CLI for product teams shipping one stable stack: Expo + React Native Reusables, Fastify, WXT, Drizzle, Neon, Clerk, RevenueCat + Stripe, Cloudflare R2/CDN, and Vercel.
+[![npm version](https://img.shields.io/npm/v/anhedral.svg)](https://www.npmjs.com/package/anhedral)
+[![license](https://img.shields.io/npm/l/anhedral.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/anhedral.svg)](https://www.npmjs.com/package/anhedral)
 
-## Requirements
+One command to start a production-shaped Expo, Fastify, and Chrome extension application.
 
-- Node.js 20+
-- `pnpm` available on your machine
+Anhedral is an opinionated init CLI for teams that want one stable full-stack architecture instead of a menu of half-finished choices. It generates a single pnpm monorepo with an Expo app for web/iOS/Android, a Fastify API, a WXT Chrome extension, shared packages, and deployment-ready structure for Vercel, EAS, and the Chrome Web Store.
 
-## Usage
+![Anhedral init CLI](docs/anhedral-cli-init.png)
 
-Run the latest published CLI directly without installing it globally:
+## Quick Start
 
 ```sh
 pnpm dlx anhedral@latest init
 ```
 
+Or with npm:
+
 ```sh
 npx anhedral@latest init
 ```
 
-Use `--skip-install` when you want deterministic file generation without running dependency installation during init:
+Use `--skip-install` when you want deterministic file generation before installing dependencies:
 
 ```sh
 pnpm dlx anhedral@latest init --skip-install
 pnpm install
 ```
 
-Global install also works:
+## What It Generates
 
-```sh
-pnpm add -g anhedral@latest
-anhedral init
+```txt
+.
+├─ Frontend/        Expo + React Native Reusables app
+├─ Backend/         Fastify API
+├─ Extension/       WXT Chrome extension
+├─ packages/
+│  ├─ api-client/   shared typed API client
+│  ├─ config/       shared config helpers
+│  ├─ contracts/    shared Zod request/response contracts
+│  ├─ db/           Drizzle schema, Neon client, migrations
+│  └─ types/        shared TypeScript types
+├─ PRODUCTION.md    deployment checklist
+├─ turbo.json       workspace task graph
+└─ package.json     root scripts
 ```
 
-```sh
-npm install -g anhedral@latest
-anhedral init
-```
+The generated app is intentionally one repository. Deploy the same Git repo as two Vercel projects:
+
+- `Frontend`: Expo web export, built with `pnpm build:web`, output to `dist`
+- `Backend`: Fastify API, built with `pnpm build`, entrypoint at `src/index.ts`
+
+The same `Frontend` source is used for native iOS and Android builds through EAS. The `Extension` source builds a WXT Chrome extension ZIP for the Chrome Web Store.
 
 ## Stack
 
-`init` generates the only supported stack:
+Anhedral supports one carefully maintained stack:
 
 - Expo + React Native Reusables frontend
 - Fastify backend
-- WXT extension
+- WXT Chrome extension
 - Neon + Drizzle
 - Cloudflare R2/CDN
 - Clerk auth
 - RevenueCat + Stripe
-- Vercel deploy
+- Vercel deployment
+- pnpm workspaces + Turborepo
+
+The goal is stability. The generated project avoids framework sprawl, duplicate schemas, and separate frontend/backend/extension repositories.
+
+## Why This Stack
+
+Anhedral is built around one idea: a startup should be able to launch every major client from one repository without committing to infrastructure that becomes expensive, fragmented, or hard to change later.
 
-The scaffold is a pnpm workspace with top-level `Frontend`, `Backend`, `Extension`, and `packages/*` folders. Shared code such as the Drizzle schema lives under `packages/db` so apps do not need separate database schemas.
+The stack is intentionally narrow:
 
-Each scaffold writes a `stack.json` file with the selected architecture, generated outputs, and the verified dependency manifest used for that run.
+| Choice | Why Anhedral uses it |
+| --- | --- |
+| Expo | One React Native codebase targets web browsers, iOS, and Android. Compared with separate web and native apps, Expo keeps product iteration faster and avoids rebuilding shared screens, auth flows, and client logic three times. |
+| React Native Reusables | It brings shadcn-style primitives to React Native and Expo without locking the app into a heavy design system. Compared with bespoke component scaffolds, it gives teams accessible primitives they can replace or extend as the product becomes specific. |
+| Fastify | Fastify is small, fast, TypeScript-friendly, and works well as a central API layer on Vercel. Compared with pushing logic into many frontend routes, serverless functions, or client SDK calls, a Fastify backend centralizes auth, billing, storage, database access, webhooks, and internal APIs in one place. |
+| TypeScript | The whole stack shares types, contracts, and API clients. Compared with untyped template code, this catches frontend/backend drift before deploy and makes the generated app safer to evolve. |
+| Zod contracts | Request and response schemas live in shared packages. Compared with duplicating interfaces across clients, Zod lets the backend validate inputs while the frontend parses responses from the same source of truth. |
+| Neon + Drizzle | Neon gives serverless Postgres that can start free and scale with usage; Drizzle keeps schema and queries close to TypeScript. Compared with proprietary document databases or opaque ORMs, this keeps the data layer portable, SQL-native, and easy to inspect. |
+| Cloudflare R2/CDN | R2 provides S3-compatible object storage without S3-style egress fees. Compared with storing files in the database or coupling uploads to one app client, signed storage routes give every client the same upload/download primitive. |
+| Clerk | Clerk handles modern auth across web, native, and extension clients. Compared with hand-rolled auth, it removes a high-risk surface area while still letting the backend own authorization decisions. |
+| RevenueCat + Stripe | RevenueCat coordinates native subscriptions and Stripe web billing behind one entitlement model. Compared with separate payment implementations per platform, the backend can ask one question: what is this user allowed to access? |
+| WXT | WXT gives the Chrome extension a modern TypeScript/Vite workflow and supports the Side Panel API. Compared with hand-maintained manifest scaffolds, it reduces extension build and packaging mistakes. |
+| Vercel | Vercel deploys the Expo web app and Fastify API from the same Git repository with separate project roots. Compared with manually wiring CI/CD early, teams get preview deployments and production deploys from normal commits. |
 
-## Vercel Deployment
+Every part of the stack can be started on free tiers and scales automatically as traffic grows. That matters because the first production architecture should not force a team to choose between moving quickly and being able to handle success.
 
-The generated workspace is one Git repository with two Vercel projects:
+The bigger advantage is architectural: Anhedral creates all target clients plus one backend that can serve internal and external requests. Product logic, auth decisions, subscription entitlements, storage access, database writes, and webhooks have a central home. That helps startups avoid the common failure mode where every client invents its own rules, and the team later cannot respond quickly when the product needs to shift.
 
-- `Frontend`: Expo web build. Build command: `pnpm build:web`. Output directory: `dist`.
-- `Backend`: Fastify API. Build command: `pnpm build`. Vercel detects `src/index.ts` as the Fastify entrypoint.
+## Local Development
 
-The `Frontend` source is also the EAS source for iOS and Android builds; Vercel only deploys its web export.
+From the generated project root:
 
-Import the same repository twice in Vercel and set each project Root Directory to the app path above. Enable source access outside the app root so `packages/*` workspace dependencies are available during builds.
+```sh
+pnpm install
+pnpm dev
+```
 
-Vercel deployments are Git-driven. After both projects are connected, pushes and pull requests deploy the Expo web app and Fastify API automatically from GitHub commits.
+Run one surface at a time:
 
-Generated projects also include `PRODUCTION.md` with the provider checklist and these root verification scripts:
+```sh
+pnpm dev:frontend
+pnpm dev:backend
+pnpm dev:extension
+```
+
+Verify before deployment:
 
 ```sh
 pnpm verify
@@ -77,98 +120,71 @@ pnpm verify:backend
 pnpm verify:extension
 ```
 
-## Generated Provider Setup
+Database workflow:
+
+```sh
+pnpm db:generate
+pnpm db:migrate
+```
+
+## Provider Setup
+
+Generated projects include placeholder env values so the repository can be inspected before accounts are provisioned. Real auth, billing, uploads, native builds, and extension sign-in require provider keys.
 
-New projects ship with placeholder env values so the repository can be inspected before accounts are provisioned. A production UI requires real keys from each provider. The generated `README.md` and `PRODUCTION.md` now include setup links and exact env placement for:
+The generated `README.md` and `PRODUCTION.md` explain where every key belongs:
 
-- Neon database: `DATABASE_URL`
-- Clerk auth: `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`, `VITE_CLERK_PUBLISHABLE_KEY`
+- Neon: `DATABASE_URL`
+- Clerk: `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`, `VITE_CLERK_PUBLISHABLE_KEY`
 - RevenueCat + Stripe: `EXPO_PUBLIC_RC_*`, `RC_SECRET_API_KEY`, `RC_WEBHOOK_SECRET`
 - Cloudflare R2/CDN: `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET`
-- Vercel: two projects from the same Git repo, rooted at `Frontend` and `Backend`
+- Vercel: two projects from the same Git repository, rooted at `Frontend` and `Backend`
 - EAS: native iOS and Android builds from `Frontend`
 - Chrome Web Store: WXT ZIP upload from `Extension/.output`
 
-## Native App Deployment
-
-Use `Frontend` as the Expo project root for iOS and Android. Vercel only deploys the web export from this app; native builds go through EAS.
-
-```sh
-cd Frontend
-pnpm dlx eas-cli@latest login
-pnpm dlx eas-cli@latest init
-```
+## Deployment
 
-The scaffold generates `Frontend/eas.json` with `development`, `preview`, and `production` profiles.
+### Vercel
 
-Build commands:
+Import the same GitHub repository twice:
 
-```sh
-# Android
-pnpm dlx eas-cli@latest build --platform android --profile production
+| Project | Root Directory | Build Command | Output |
+| --- | --- | --- | --- |
+| Frontend | `Frontend` | `pnpm build:web` | `dist` |
+| Backend | `Backend` | `pnpm build` | Fastify entrypoint |
 
-# iOS
-pnpm dlx eas-cli@latest build --platform ios --profile production
+Enable Vercel access to source files outside each project root so workspace packages under `packages/*` resolve during builds.
 
-# Both platforms
-pnpm dlx eas-cli@latest build --platform all --profile production
-```
+### EAS
 
-Submit latest successful builds to the stores:
+Use `Frontend` as the Expo project root:
 
 ```sh
-# Google Play
-pnpm dlx eas-cli@latest submit --platform android --latest --profile production
-
-# App Store Connect / TestFlight
-pnpm dlx eas-cli@latest submit --platform ios --latest --profile production
-
-# Both platforms
+cd Frontend
+pnpm dlx eas-cli@latest login
+pnpm dlx eas-cli@latest init
+pnpm dlx eas-cli@latest build --platform all --profile production
 pnpm dlx eas-cli@latest submit --platform all --latest --profile production
 ```
 
-One-step build and submit:
-
-```sh
-pnpm dlx eas-cli@latest build --platform android --profile production --auto-submit
-pnpm dlx eas-cli@latest build --platform ios --profile production --auto-submit
-pnpm dlx eas-cli@latest build --platform all --profile production --auto-submit
-```
-
-Useful release checks:
+### Chrome Extension
 
 ```sh
-pnpm dlx eas-cli@latest build:list
-pnpm dlx eas-cli@latest build:version:get --platform all --profile production
-pnpm dlx eas-cli@latest credentials
+pnpm extension:zip
 ```
 
-## Extension Release
+Upload `Extension/.output/*-chrome.zip` to the Chrome Web Store Developer Dashboard.
 
-The WXT extension is built from `Extension`. It is not deployed by Vercel.
-
-```sh
-cd Extension
-pnpm build
-pnpm zip
-```
+## Dependency Policy
 
-The Chrome ZIP is generated under `.output/`. Upload that ZIP in the Chrome Web Store Developer Dashboard:
+`pnpm dlx anhedral@latest init` gives users the latest published Anhedral CLI, but generated projects use the dependency manifest verified for that release.
 
-1. Open the Chrome Web Store Developer Dashboard.
-2. Create the item the first time, or open the existing extension item.
-3. Upload the generated Chrome ZIP.
-4. Complete or update the store listing, screenshots, privacy practices, permissions justification, and distribution settings.
-5. Submit the item for review.
+Runtime dependency versions live in `src/dependencies.ts`. Generated projects also receive a `stack.json` file recording the exact stack and dependency manifest used for that init run.
 
-For automated store submissions later, WXT supports:
+This keeps generated apps reproducible while still allowing Anhedral itself to move forward quickly through verified releases.
 
-```sh
-pnpm wxt submit init
-pnpm wxt submit
-```
+## Development
 
-## Local Development
+Work on the CLI locally:
 
 ```sh
 pnpm install
@@ -176,80 +192,29 @@ pnpm build
 pnpm test:all
 ```
 
-## Publishing
-
-This package is published once to the npm registry. `pnpm`, `npm`, `yarn`, and `bun` users all install that same published package.
-
-Official releases are automatic on merges to `main`. GitHub Actions bumps the patch version, runs the release checks once, creates a release commit and tag, and publishes that version to npm.
-
-Recommended release flow:
+Refresh the checked-in demo output:
 
 ```sh
-git push origin main
+pnpm demo:refresh
 ```
 
-Release publishing is handled by:
-
-- `.github/workflows/release-on-main.yml`: runs on pushes to `main`, bumps `package.json`, verifies the repo, pushes a `v*.*.*` tag, and publishes to npm.
-- `.github/workflows/release.yml`: manual retry workflow for publishing the current checked-out package version.
-
-The repository is private, so npm provenance publishing is not supported. GitHub Actions publishes with `--provenance=false` and skips npm lifecycle scripts because `pnpm release:check` has already run. Configure an npm automation token as `NPM_TOKEN` in the `npm` GitHub environment or repository secrets.
-
-Manual local publish is still available as an emergency fallback:
+Validate upstream scaffold drift:
 
 ```sh
-pnpm release:check
-npm publish --provenance=false --ignore-scripts
+pnpm test:e2e:latest
 ```
 
-## Maintenance
-
-This repo is maintained in two lanes:
-
-- `stable`: the default user-facing toolchain, pinned to known-good upstream CLI and package versions in `src/dependencies.ts`.
-- `latest`: an early-warning lane that tracks upstream scaffold tools without pinning, so breakage is detected before it reaches the default path.
-
-The practical rule is simple: users get the latest verified Anhedral release, not uncontrolled registry drift at init time. Detect drift on `latest`, verify it, then promote the pinned dependency manifest only after the e2e matrix passes.
-
-### Dependency policy
-
-- Runtime dependency versions for generated projects live in `src/dependencies.ts`.
-- Generated package manifests and install commands must read from that manifest.
-- Avoid raw `@latest` and caret ranges in generated output unless a package manager or platform command explicitly requires it.
-- `pnpm dlx anhedral@latest init` means the newest published Anhedral CLI. The generated project should still be reproducible for that exact Anhedral version.
-- `stack.json` records the dependency manifest so support and debugging can identify exactly what was generated.
-
-### Recommended automation
+## Release
 
-- Renovate is configured in `renovate.json` to keep this repo's own dependencies and generated dependency manifest current.
-- GitHub Actions CI runs on pushes and pull requests in `.github/workflows/ci.yml`.
-- Weekly toolchain drift checks run in `.github/workflows/toolchain-drift.yml` for both `stable` and `latest`.
-- Automatic releases publish through `.github/workflows/release-on-main.yml`; `.github/workflows/release.yml` is for manual retry only.
-- Stable dependency pins in `src/dependencies.ts` are annotated so Renovate can open PRs when upstream packages and scaffold CLIs publish updates.
-- `prepublishOnly` stays strict for manual local publishing. GitHub Actions skips npm lifecycle scripts during publish after running `pnpm release:check`.
+Official releases are automatic on merges to `main`. The release workflow bumps the patch version, runs the release checks, creates a release commit and tag, and publishes to npm.
 
-### Upgrade workflow
-
-Use this sequence when Renovate opens a dependency or toolchain PR:
-
-```sh
-pnpm install --frozen-lockfile
-pnpm test
-pnpm test:e2e
-npm pack --dry-run
-```
-
-If you want to validate upstream scaffold drift manually, use the explicit latest-lane script:
+Manual fallback:
 
 ```sh
-pnpm test:e2e:latest
+pnpm release:check
+npm publish --provenance=false --ignore-scripts
 ```
 
-When a dependency pin PR passes and the generated outputs look good, update the `VERIFIED_AT` date in `src/dependencies.ts` and release normally.
-
-### Release policy
+## License
 
-- Publish `patch` releases for scaffold fixes, dependency bumps, and safer defaults.
-- Publish `minor` releases for new stacks, new flags, or new generated capabilities.
-- Publish `major` releases for breaking CLI changes or incompatible generated-project structure changes.
-- Never publish from a dirty worktree.
+MIT

package/dist/dependencies.d.ts

@@ -13,6 +13,7 @@ export declare const TOOLCHAIN_DEPENDENCIES: {
 export declare const ROOT_DEPENDENCIES: DependencyGroup;
 export declare const SHARED_DB_DEPENDENCIES: DependencyGroup;
 export declare const SHARED_PACKAGE_DEPENDENCIES: DependencyGroup;
+export declare const CONTRACTS_DEPENDENCIES: DependencyGroup;
 export declare const API_CLIENT_DEPENDENCIES: DependencyGroup;
 export declare const BACKEND_DEPENDENCIES: DependencyGroup;
 export declare const EXTENSION_DEPENDENCIES: DependencyGroup;
@@ -27,6 +28,7 @@ export declare function dependencyManifest(): {
         readonly wxt: "0.20.25";
     };
     root: DependencyGroup;
+    contracts: DependencyGroup;
     sharedDb: DependencyGroup;
     sharedPackages: DependencyGroup;
     backend: DependencyGroup;

package/dist/dependencies.js

@@ -40,15 +40,25 @@ export const SHARED_PACKAGE_DEPENDENCIES = {
         typescript: '5.9.3',
     },
 };
+export const CONTRACTS_DEPENDENCIES = {
+    dependencies: {
+        // renovate: datasource=npm depName=zod
+        zod: '4.2.1',
+    },
+    ...SHARED_PACKAGE_DEPENDENCIES,
+};
 export const API_CLIENT_DEPENDENCIES = {
     dependencies: {
         '@anhedral/config': 'workspace:*',
+        '@anhedral/contracts': 'workspace:*',
         '@anhedral/types': 'workspace:*',
+        zod: CONTRACTS_DEPENDENCIES.dependencies.zod,
     },
     ...SHARED_PACKAGE_DEPENDENCIES,
 };
 export const BACKEND_DEPENDENCIES = {
     dependencies: {
+        '@anhedral/contracts': 'workspace:*',
         '@anhedral/db': 'workspace:*',
         // renovate: datasource=npm depName=fastify
         fastify: '5.6.2',
@@ -81,6 +91,7 @@ export const BACKEND_DEPENDENCIES = {
         // renovate: datasource=npm depName=@aws-sdk/s3-request-presigner
         '@aws-sdk/s3-request-presigner': '3.1047.0',
         dotenv: SHARED_DB_DEPENDENCIES.dependencies.dotenv,
+        zod: CONTRACTS_DEPENDENCIES.dependencies.zod,
     },
     devDependencies: {
         typescript: SHARED_DB_DEPENDENCIES.devDependencies.typescript,
@@ -164,6 +175,7 @@ export function dependencyManifest() {
         packageManager: PACKAGE_MANAGER,
         toolchain: TOOLCHAIN_DEPENDENCIES,
         root: ROOT_DEPENDENCIES,
+        contracts: CONTRACTS_DEPENDENCIES,
         sharedDb: SHARED_DB_DEPENDENCIES,
         sharedPackages: SHARED_PACKAGE_DEPENDENCIES,
         backend: BACKEND_DEPENDENCIES,