anhedral 0.1.10 → 0.4.0

package/README.md

@@ -1,220 +1,277 @@
 # Anhedral
 
 [![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)
 
-One command to start a production-shaped Expo, Fastify, and Chrome extension application.
+Anhedral generates a complete, production-oriented TypeScript stack whose source code stays understandable and customizable.
 
-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.
+> **Three-second version:** Start with the full TypeScript stack. Keep every escape hatch.
 
-![Anhedral init CLI](docs/anhedral-cli-init.png)
+Anhedral is not a new programming language and generated applications do not run inside a proprietary application framework. It assembles well-documented tools, connects their difficult integration boundaries, and leaves developers with ordinary Next.js, Expo Router, Fastify, Drizzle, Electron, and WXT projects.
 
-## Quick Start
+Anhedral is open source under the [Apache License 2.0](LICENSE). You may use,
+modify, and distribute it subject to that license, including its notice and
+redistribution requirements. Generated applications remain ordinary project
+source that their developers can customize and license for their products.
+
+## Recommended: use the coding-agent skill
+
+Install the Anhedral skill for Codex, Claude Code, or another compatible coding
+agent:
 
 ```sh
-pnpm dlx anhedral@latest init
+pnpm dlx skills add https://github.com/anhedral/anhedral-init --skill anhedral-init
 ```
 
-Or with npm:
+Choose the agent and global or project scope when prompted. Then ask the agent:
 
-```sh
-npx anhedral@latest init
+```text
+Use $anhedral-init to create and provision my application.
 ```
 
-Use `--skip-install` when you want deterministic file generation before installing dependencies:
+The skill begins by asking for the project name and whether you already own a
+custom domain. It selects the CLI command with you, detects Computer Use and
+subagent support, generates the project, and walks through the selected cloud
+providers. It pauses for sign-in, MFA, payments, secret generation, and final
+release submissions. Paste secrets directly into the instructed uncommitted
+`.env` file or protected provider field—never into chat.
+
+## Create an application directly
+
+Create the complete stack:
 
 ```sh
-pnpm dlx anhedral@latest init --skip-install
-pnpm install
+pnpm dlx anhedral@latest new my-product
+cd my-product
 ```
 
-## What It Generates
+The generated `README.md` contains the exact next steps for the selected stack.
+For the complete stack, copy the package-local environment examples, configure
+the selected managed providers—including a Neon `DATABASE_URL`—and create the
+reviewed initial migration before running `pnpm dev`. Anhedral intentionally
+does not generate a local Postgres substitute or pretend that production
+provider credentials already exist.
+
+With no module flags, `new` includes every supported application surface and backend capability. Generate a focused stack by naming only what the product needs:
 
-```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
+pnpm dlx anhedral@latest new my-product --web --api --db --auth
+pnpm dlx anhedral@latest new my-api --api --db
+pnpm dlx anhedral@latest new my-clients --web --mobile
 ```
 
-The generated app is intentionally one repository. Deploy the same Git repo as two Vercel projects:
+`init` generates the same workspace in the current empty directory:
 
-- `Frontend`: Expo web export, built with `pnpm build:web`, output to `dist`
-- `Backend`: Fastify API, built with `pnpm build`, entrypoint at `src/index.ts`
+```sh
+mkdir my-product && cd my-product
+pnpm dlx anhedral@latest init --web --api --db --auth
+```
 
-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.
+Interactive terminals prompt for surfaces and capabilities. CI and coding agents should pass explicit module flags.
+
+## What gets generated
+
+```text
+my-product/
+├── apps/
+│   ├── web/                    # Next.js App Router + source-owned shadcn/ui
+│   ├── mobile/                 # Expo Router + React Native Reusables
+│   ├── api/                    # Fastify routes, backend modules, auth, providers
+│   ├── desktop/                # Electron + React
+│   ├── extension/              # WXT browser extension
+│   ├── assets-private-proxy/   # Cloudflare Worker for private asset delivery
+│   └── desktop-updater-worker/ # private R2 Electron update delivery
+├── packages/
+│   ├── contracts/              # shared Zod network contracts
+│   ├── api-client/             # typed client used by every frontend
+│   ├── db/                     # Drizzle schema and reviewed migrations
+│   └── realtime/               # Ably client when billing is selected
+├── docs/
+│   ├── DEVELOPMENT.md          # task-oriented feature recipes
+│   └── STACK.md                # tool map and official documentation
+├── README.md                   # first run and where-to-write-code map
+├── PRODUCTION.md               # selection-specific release runbook
+├── SKILL.md                    # repository guidance for coding agents
+├── ANHEDRAL.md                 # generator and ownership notes
+└── anhedral.json               # modules, versions, provenance, ownership
+```
 
-## Stack
+Whole directories are omitted when their module is not selected. Generated documentation is selection-aware.
 
-Anhedral supports one carefully maintained stack:
+## Developer experience
 
-- Expo + React Native Reusables frontend
-- Fastify backend
-- WXT Chrome extension
-- Neon + Drizzle
-- Cloudflare R2/CDN
-- Clerk auth
-- RevenueCat + Stripe
-- Vercel deployment
-- pnpm workspaces + Turborepo
+Developers use each tool normally:
 
-The goal is stability. The generated project avoids framework sprawl, duplicate schemas, and separate frontend/backend/extension repositories.
+```tsx
+// apps/web/app/projects/page.tsx
+import { ProjectList } from '@/components/projects/project-list';
 
-## Why This Stack
+export default function ProjectsPage() {
+  return <ProjectList />;
+}
+```
 
-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.
+```ts
+// packages/contracts/src/app.ts
+import { z } from 'zod';
 
-The stack is intentionally narrow:
+export const ProjectSchema = z.object({ id: z.string(), name: z.string() });
+export const ProjectListSchema = z.array(ProjectSchema);
+```
 
-| 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. |
+```ts
+// packages/db/src/app-schema.ts
+import { pgTable, text } from 'drizzle-orm/pg-core';
 
-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.
+export const projects = pgTable('projects', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+});
+```
 
-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.
+```ts
+// apps/api/src/routes/app.ts
+import type { FastifyPluginAsync } from 'fastify';
+import { db } from '@shared/db';
+import { projects } from '@shared/db/schema';
 
-## Local Development
+export const appRoutes: FastifyPluginAsync = async (app) => {
+  app.get('/projects', async () => db.select().from(projects));
+};
+```
 
-From the generated project root:
+The convention is a conventional vertical flow, not an Anhedral DSL:
 
-```sh
-pnpm install
-pnpm dev
+```text
+contracts -> database/service -> Fastify route -> typed API client -> frontend
 ```
 
-Run one surface at a time:
-
-```sh
-pnpm dev:frontend
-pnpm dev:backend
-pnpm dev:extension
+- Write web product code under `apps/web` using Next.js conventions.
+- Write mobile product code under `apps/mobile` using Expo Router conventions.
+- Register product routes in `apps/api/src/routes/app.ts` and add server-only feature modules under `apps/api/src` using Fastify conventions.
+- Write product tables in `packages/db/src/app-schema.ts` and queries under `packages/db` using Drizzle conventions.
+- Share only network contracts and client-safe packages with frontends.
+- Import the underlying framework directly whenever its API is the right tool.
+
+## The stack
+
+| Concern | Default | Why Anhedral includes it |
+| --- | --- | --- |
+| Web | Next.js + Vercel | App Router, React server rendering, routing, deployment |
+| Native | Expo Router | One TypeScript application for iOS and Android |
+| API | Fastify | Typed validation, structured logging, plugin boundaries |
+| Database | Neon + Drizzle | Managed Postgres with TypeScript schema and SQL-like queries |
+| Authentication | Clerk | Connected frontend and backend identity/session flows |
+| UI | shadcn/ui + React Native Reusables | Accessible source code the application owns |
+| Storage | private Cloudflare R2 | Signed uploads and controlled asset delivery |
+| Billing/realtime | RevenueCat + Ably | Durable entitlements and client invalidation |
+| Desktop | Electron | Predictable cross-platform TypeScript desktop runtime |
+| Desktop updates | electron-updater + private R2 + Worker | Signed automatic updates through a product-owned custom domain |
+| Extension | WXT | Browser-extension entrypoints, builds, and packaging |
+| Workspace | pnpm + Turborepo | Strict dependencies and dependency-aware tasks |
+
+Anhedral does **not** generate or require local Postgres. Database-enabled projects use a managed Neon connection through `DATABASE_URL`; teams should use isolated Neon branches or projects for development, preview, and production.
+
+## Commands
+
+```text
+anhedral new <directory> [modules...]    Generate a new readable workspace
+anhedral init [modules...]               Generate in the current empty directory
+anhedral add <module...>                 Add connected stack capabilities
+anhedral ui add <component...>           Add source-owned UI components
+anhedral upgrade                         Transactionally upgrade a supported project
+anhedral doctor                          Check ownership and generator drift
 ```
 
-Verify before deployment:
+Useful examples:
 
 ```sh
-pnpm verify
-pnpm verify:frontend
-pnpm verify:backend
-pnpm verify:extension
+anhedral add storage --dry-run
+anhedral add desktop extension
+anhedral add electron-updater
+anhedral ui add button dialog
+anhedral ui add data-table --target web --dry-run
+anhedral upgrade --dry-run
+anhedral doctor --json
 ```
 
-Database workflow:
+`--dry-run` builds the complete plan without changing the project. `--json` emits machine-readable output. `--verbose` streams child-tool diagnostics.
+
+Application lifecycle commands remain visible in the generated root `package.json`:
 
 ```sh
+pnpm dev
+pnpm dev:all
+pnpm dev:web
+pnpm dev:api
+pnpm typecheck
+pnpm verify
+pnpm build
 pnpm db:generate
 pnpm db:migrate
 ```
 
-## Provider Setup
+`pnpm dev` starts the primary product loop: the first selected client plus the
+API when present, or the API by itself for backend-only projects. In the full
+stack that means web plus API. `pnpm dev:all` appears only when the project has
+additional surfaces and intentionally starts all of them. Only commands
+relevant to selected modules are generated.
 
-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.
+## Extensibility and ownership
 
-The generated `README.md` and `PRODUCTION.md` explain where every key belongs:
+Anhedral owns initial assembly and safe structural additions. It does not own product architecture after generation.
 
-- 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`
+- `README.md`, `PRODUCTION.md`, application features, pages, routes, services, and domain code are developer-owned.
+- Root workspace configuration is mergeable.
+- Integration substrate is recorded in `anhedral.json`; `anhedral add` refuses to overwrite modified managed files.
+- UI components are copied into the application so developers can edit them normally.
+- Provider integrations use ordinary SDKs and configuration files with no hidden control plane.
 
-## Deployment
-
-### Vercel
-
-Import the same GitHub repository twice:
-
-| Project | Root Directory | Build Command | Output |
-| --- | --- | --- | --- |
-| Frontend | `Frontend` | `pnpm build:web` | `dist` |
-| Backend | `Backend` | `pnpm build` | Fastify entrypoint |
-
-Enable Vercel access to source files outside each project root so workspace packages under `packages/*` resolve during builds.
-
-### EAS
-
-Use `Frontend` as the Expo project root:
+Before a structural change:
 
 ```sh
-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
+anhedral doctor
+anhedral add <module> --dry-run
 ```
 
-### Chrome Extension
-
-```sh
-pnpm extension:zip
-```
-
-Upload `Extension/.output/*-chrome.zip` to the Chrome Web Store Developer Dashboard.
-
-## Dependency Policy
+When `doctor` reports that a project was generated by a supported older release, run `anhedral upgrade --dry-run`, inspect the plan, and then run `anhedral upgrade`. Version 0.4 supports transactional upgrades from 0.3 projects while preserving user-owned extension seams. If a 0.3 project changed a file that was generator-managed, the upgrade stops instead of overwriting it. Preserve the change in source control, restore that managed file to its recorded 0.3 content, run the upgrade, and then move the product behavior into the new user-owned `app.ts`, `app-schema.ts`, page, component, or `app-window.ts` seam.
 
-`pnpm dlx anhedral@latest init` gives users the latest published Anhedral CLI, but generated projects use the dependency manifest verified for that release.
+## Documentation contract
 
-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.
+Every generated project teaches both humans and coding agents how to work in it:
 
-This keeps generated apps reproducible while still allowing Anhedral itself to move forward quickly through verified releases.
+- `README.md` answers how to run the app and where frontend/backend code goes.
+- `docs/DEVELOPMENT.md` provides end-to-end feature and common-task recipes.
+- `docs/STACK.md` maps generated files to each tool's official documentation.
+- `SKILL.md` gives coding agents concise repository-specific workflow and safety rules.
+- `PRODUCTION.md` covers only the accounts, environment, infrastructure, DNS, stores, and release steps selected for that project.
 
-## Development
+The generator's exact output contract is documented in [docs/output-tree-contract.md](docs/output-tree-contract.md). Contributor architecture remains available in the [source repository](https://github.com/anhedral/anhedral-init/tree/main/docs/architecture).
 
-Work on the CLI locally:
+The complete lifecycle, runtime, cloud, command, and coding-agent topology is in
+the [Anhedral master stack map](docs/master-stack-map.md).
 
-```sh
-pnpm install
-pnpm build
-pnpm test:all
-```
+## Module dependency rules
 
-Refresh the checked-in demo output:
+Anhedral resolves integrations as a deterministic graph:
 
-```sh
-pnpm demo:refresh
+```text
+auth                 -> api + db
+billing              -> auth
+storage              -> auth
+native-subscriptions -> mobile + billing
+electron-updater     -> desktop
 ```
 
-Validate upstream scaffold drift:
+Adding a capability brings the infrastructure it actually requires. Unselected providers do not leave dead source files or environment placeholders behind.
 
-```sh
-pnpm test:e2e:latest
-```
-
-## Release
-
-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.
+## Verification
 
-Manual fallback:
+The generator and representative public stacks are checked with:
 
 ```sh
-pnpm release:check
-npm publish --provenance=false --ignore-scripts
+pnpm typecheck
+pnpm test:all
 ```
 
-## License
-
-MIT
+Generated workspaces include their own package-level tests, full-stack `verify` command, CI workflow, production environment validation, migration drift gate, and deployment configuration.

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are made on the current development branch and released as a new npm version. Consumers should use the latest version published under the `latest` dist-tag.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use GitHub's private vulnerability reporting or security-advisory flow for this repository. If repository access is unavailable, contact the package maintainers through the owner information on the [anhedral npm package](https://www.npmjs.com/package/anhedral).
+
+Include the affected version, reproduction steps, impact, and any suggested mitigation. Please avoid accessing data that is not yours and allow maintainers time to investigate before public disclosure.
+
+## Supply-chain policy
+
+- Release artifacts are built and tested in a read-only job.
+- The exact tarball uploaded by CI is the artifact submitted to npm.
+- npm integrity is checked before and after publication.
+- npm publication uses Trusted Publishing: GitHub exchanges an OIDC identity for a short-lived credential only in the publish step of the protected `npm` environment. No npm write token is stored in GitHub.
+- A Git tag and GitHub release are created only after npm confirms the expected artifact integrity.
+- GitHub Actions are pinned to reviewed commit SHAs, and the release Node.js/npm packer is pinned to an exact version.
+- CI queries OSV for every exact package version in `pnpm-lock.yaml` and every dependency version shipped by the generator; it fails closed if the service remains unavailable after bounded retries or reports a finding.
+- Local policy scans every tracked or non-ignored working-tree text file and built `dist/` file for high-confidence credential formats. Release jobs repeat the scan against the exact gzip tarball before it crosses the publish boundary. Placeholder examples use explicit non-secret values rather than allowlisting token-shaped strings.
+- Release declarations must be valid Semantic Versioning and have a matching `CHANGELOG.md` section. Local deterministic checks validate workflow policy and confirm every Renovate custom manager still extracts a maintained pin.
+
+Generated projects pin their stable dependency manifest, explicitly allow only required dependency build scripts, and record the selected toolchain channel in `anhedral.json`. The `latest` channel is for upstream-drift testing and is not the reproducible default.
+
+Incremental generation rejects path traversal, symbolic-link targets, unowned collisions, modified managed files, and managed-file permission drift. Transaction journals are validated before recovery, fsynced before filesystem moves, and advanced only around durable rename barriers where the host filesystem supports directory synchronization.
+
+UI component installation is an explicit networked supply-chain operation. Anhedral pins the shadcn installer version, routes Expo only to the official HTTPS React Native Reusables registry, validates component names and target paths, and runs provider mutation inside transaction staging. Provider-generated files and dependency manifests must pass ownership checks before commit. Users should review `--dry-run` output and the resulting source diff; registry content is upstream-maintained and is not part of Anhedral's immutable bundled-template catalog.
+
+## Secret response
+
+If a secret-shaped finding is real, do not merely remove it from the latest commit. Revoke or rotate the credential first, identify every log, artifact, cache, fork, and package version that may contain it, and coordinate history or artifact cleanup with the security responder. Treat false positives by changing the example to an unmistakable placeholder; do not add broad path exclusions.
+
+Anhedral is licensed under the Apache License 2.0. Security research must still
+comply with applicable law and the systems owner's authorization; the software
+license does not authorize testing infrastructure or accounts you do not own.