anhedral 0.1.5 → 0.1.7

package/README.md

@@ -1,74 +1,92 @@
-# 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
+│  ├─ 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
-
-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.
-
-Each scaffold writes a `stack.json` file with the selected architecture, generated outputs, and the verified dependency manifest used for that run.
+- Vercel deployment
+- pnpm workspaces + Turborepo
 
-## Vercel Deployment
+The goal is stability. The generated project avoids framework sprawl, duplicate schemas, and separate frontend/backend/extension repositories.
 
-The generated workspace is one Git repository with two Vercel projects:
+## Local Development
 
-- `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.
+From the generated project root:
 
-The `Frontend` source is also the EAS source for iOS and Android builds; Vercel only deploys its web export.
+```sh
+pnpm install
+pnpm dev
+```
 
-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.
+Run one surface at a time:
 
-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.
+```sh
+pnpm dev:frontend
+pnpm dev:backend
+pnpm dev:extension
+```
 
-Generated projects also include `PRODUCTION.md` with the provider checklist and these root verification scripts:
+Verify before deployment:
 
 ```sh
 pnpm verify
@@ -77,86 +95,71 @@ pnpm verify:backend
 pnpm verify:extension
 ```
 
-## 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.
+Database workflow:
 
 ```sh
-cd Frontend
-pnpm dlx eas-cli@latest login
-pnpm dlx eas-cli@latest init
+pnpm db:generate
+pnpm db:migrate
 ```
 
-The scaffold generates `Frontend/eas.json` with `development`, `preview`, and `production` profiles.
+## Provider Setup
 
-Build commands:
+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.
 
-```sh
-# Android
-pnpm dlx eas-cli@latest build --platform android --profile production
+The generated `README.md` and `PRODUCTION.md` explain where every key belongs:
 
-# iOS
-pnpm dlx eas-cli@latest build --platform ios --profile production
+- 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 repository, rooted at `Frontend` and `Backend`
+- EAS: native iOS and Android builds from `Frontend`
+- Chrome Web Store: WXT ZIP upload from `Extension/.output`
 
-# Both platforms
-pnpm dlx eas-cli@latest build --platform all --profile production
-```
+## Deployment
 
-Submit latest successful builds to the stores:
+### Vercel
 
-```sh
-# Google Play
-pnpm dlx eas-cli@latest submit --platform android --latest --profile production
+Import the same GitHub repository twice:
 
-# App Store Connect / TestFlight
-pnpm dlx eas-cli@latest submit --platform ios --latest --profile production
+| Project | Root Directory | Build Command | Output |
+| --- | --- | --- | --- |
+| Frontend | `Frontend` | `pnpm build:web` | `dist` |
+| Backend | `Backend` | `pnpm build` | Fastify entrypoint |
 
-# Both platforms
-pnpm dlx eas-cli@latest submit --platform all --latest --profile production
-```
+Enable Vercel access to source files outside each project root so workspace packages under `packages/*` resolve during builds.
 
-One-step build and submit:
+### EAS
+
+Use `Frontend` as the Expo project root:
 
 ```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
+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
 ```
 
-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.
+## Dependency Policy
 
-```sh
-cd Extension
-pnpm build
-pnpm zip
-```
+`pnpm dlx anhedral@latest init` gives users the latest published Anhedral CLI, but generated projects use the dependency manifest verified for that release.
 
-The Chrome ZIP is generated under `.output/`. Upload that ZIP in the Chrome Web Store Developer Dashboard:
+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.
 
-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.
+This keeps generated apps reproducible while still allowing Anhedral itself to move forward quickly through verified releases.
 
-For automated store submissions later, WXT supports:
-
-```sh
-pnpm wxt submit init
-pnpm wxt submit
-```
+## Development
 
-## Local Development
+Work on the CLI locally:
 
 ```sh
 pnpm install
@@ -164,80 +167,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
+## Release
 
-This repo is maintained in two lanes:
+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.
 
-- `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
-
-- 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`.
-
-### Upgrade workflow
-
-Use this sequence when Renovate opens a dependency or toolchain PR:
+Manual fallback:
 
 ```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:
-
-```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