anhedral 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -6,6 +6,65 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## Unreleased
 
+## 0.4.2 - 2026-07-23
+
+### Added
+
+- Add idempotent `pnpm first-run` setup plus a secret-safe `pnpm ready` gate with
+  human and JSON output, required/optional variable awareness, and truthful exit
+  status.
+- Generate a working items feature across Drizzle, Zod contracts, Fastify
+  routes, the shared API client, and idiomatic Next.js, Expo, Electron, and WXT
+  interfaces for every selected client.
+- Add explicit `--all`, automatic Git initialization for `new`, dependency-resolution previews, confirmation, exact generated lifecycle scripts, UI-provider command previews, and actionable `doctor` recommendations.
+- Add a published DX north star that defines measurable discovery, creation,
+  configuration, development, extension, diagnosis, upgrade, and shipping
+  journeys.
+
+### Changed
+
+- Default interactive creation to a focused web app with optional capabilities while preserving the complete-stack default for noninteractive compatibility.
+- Replace deprecated Turborepo development commands, make cache outputs package-specific, and let typechecks depend on upstream typechecks instead of builds.
+- Track bundled UI primitives in the project manifest and make generated onboarding, deployment, provider, and source-location guidance selection-aware.
+- Include status, generator version, project root, resolved modules, and next
+  steps in machine-readable plans; make human lifecycle output concise unless a
+  dry-run or verbose path listing is requested.
+
+### Fixed
+
+- Allow Next.js client API factories to render safely during production prerendering while preserving HTTPS enforcement for non-loopback production endpoints.
+- Make generated lifecycle commands reproducible even though Anhedral is intentionally not installed in application dependencies.
+- Forward arguments through generated pnpm lifecycle scripts without inserting a literal `--` that the Anhedral or provider CLI would reject.
+- Treat generated Clerk placeholder keys as unconfigured on every client instead
+  of mounting providers with knowingly invalid values.
+- Keep Electron starter features synchronized with Clerk sign-in changes instead
+  of treating an opened account dialog as an authenticated session.
+- Put reviewed database migration generation, Git staging, verification, and
+  application in one consistent onboarding order.
+- Detect required environment variables that were deleted from an existing
+  package-local configuration file.
+
+### Security
+
+- Scope generated starter-item reads and writes to the authenticated Clerk user
+  whenever authentication is selected.
+- Reject local home-directory paths and email addresses in source and packed
+  release artifacts while continuing to allow documentation placeholders and
+  public GitHub noreply contributor identities.
+
+## 0.4.1 - 2026-07-22
+
+### Added
+
+- Add the public launch artwork, reusable stack-map renderer, and expanded brand asset library to the repository and published package.
+
+### Changed
+
+- Present Anhedral as a cross-platform, modular product stack that lets teams build once, ship everywhere, and scale without repeating framework setup.
+- Automatically create patch versions for ordinary changes merged to `main`, while preserving explicitly declared minor and major releases.
+- Keep project upgrades compatible across automatic patch releases and retain the supported 0.3-to-0.4 ownership migration.
+- Publish from the exact generated release commit and attach npm provenance now that the source repository is public.
+
 ## 0.4.0 - 2026-07-22
 
 ### Added

package/CONTRIBUTING.md

@@ -1,5 +1,9 @@
 # Contributing
 
+Changes should follow the repository's
+[engineering principles](docs/engineering-principles.md): explicit behavior,
+one source of truth, narrow namespaces, visible failures, and focused tests.
+
 ## Local setup
 
 Anhedral requires Node.js 20.19+ or 22.12+ and pnpm 10.34.5.

package/README.md

@@ -1,14 +1,23 @@
 # Anhedral
 
 [![npm version](https://img.shields.io/npm/v/anhedral.svg)](https://www.npmjs.com/package/anhedral)
-[![node](https://img.shields.io/node/v/anhedral.svg)](https://www.npmjs.com/package/anhedral)
+[![Node.js ^20.19.0 or >=22.12.0](https://img.shields.io/badge/Node.js-%5E20.19.0%20%7C%7C%20%3E%3D22.12.0-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 
 Anhedral generates a complete, production-oriented TypeScript stack whose source code stays understandable and customizable.
 
-> **Three-second version:** Start with the full TypeScript stack. Keep every escape hatch.
+> **Build once. Ship everywhere. Scale is built in.** Pick the platforms,
+> frameworks, and features your product needs; Anhedral assembles them into a
+> production-ready TypeScript workspace for web, iOS, Android, desktop, APIs,
+> and browser extensions. Start free, skip months of repetitive setup and
+> integration work, and focus on what makes your app unique.
+
+![Anhedral Init Stack architecture diagram](assets/anhedral-cli-init.svg)
 
 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.
 
+The measurable product and developer-experience contract is documented in the
+[Anhedral DX north star](docs/NORTHSTAR.md).
+
 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
@@ -38,21 +47,33 @@ release submissions. Paste secrets directly into the instructed uncommitted
 
 ## Create an application directly
 
-Create the complete stack:
+In an interactive terminal, start Anhedral and choose the surfaces and
+capabilities you need:
 
 ```sh
 pnpm dlx anhedral@latest new my-product
 cd my-product
 ```
 
+The suggested selection is a focused web app, and Anhedral shows the complete
+resolved stack before it writes anything. To explicitly create every supported
+surface and capability, use:
+
+```sh
+pnpm dlx anhedral@latest new my-product --all
+```
+
 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.
+Run `pnpm first-run` to create missing local environment files without
+overwriting anything, then use `pnpm ready` for a secret-safe readiness check.
+For the complete stack, 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:
+In noninteractive environments, no module flags retain the complete-stack
+default for compatibility. Prefer `--all` when that is your intent, or name
+only what the product needs:
 
 ```sh
 pnpm dlx anhedral@latest new my-product --web --api --db --auth
@@ -100,47 +121,40 @@ Whole directories are omitted when their module is not selected. Generated docum
 
 ## Developer experience
 
-Developers use each tool normally:
+Database-backed client stacks include a working `items` feature on day one. It
+connects the Drizzle table, Zod request/response contracts, Fastify list/create
+routes, typed client calls, and an idiomatic UI for every selected surface. Use
+it to verify the stack, then rename or replace these ordinary user-owned files
+with the product idea:
 
-```tsx
-// apps/web/app/projects/page.tsx
-import { ProjectList } from '@/components/projects/project-list';
-
-export default function ProjectsPage() {
-  return <ProjectList />;
-}
+```text
+packages/db/src/app-schema.ts
+packages/contracts/src/app.ts
+apps/api/src/routes/app.ts
+packages/api-client/src/app.ts
+apps/web/components/item-list.tsx
+apps/mobile/components/item-list.tsx
+apps/desktop/src/renderer/components/item-list.tsx
+apps/extension/src/components/item-list.tsx
 ```
 
+Only paths for selected clients are generated. Shared contracts and API calls
+stay consistent while presentation follows Next.js, React Native, Electron, or
+browser-extension conventions.
+
 ```ts
 // packages/contracts/src/app.ts
 import { z } from 'zod';
 
-export const ProjectSchema = z.object({ id: z.string(), name: z.string() });
-export const ProjectListSchema = z.array(ProjectSchema);
-```
-
-```ts
-// packages/db/src/app-schema.ts
-import { pgTable, text } from 'drizzle-orm/pg-core';
-
-export const projects = pgTable('projects', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
+export const ItemSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  createdAt: z.string().datetime(),
 });
+export const ItemListSchema = z.array(ItemSchema);
 ```
 
-```ts
-// apps/api/src/routes/app.ts
-import type { FastifyPluginAsync } from 'fastify';
-import { db } from '@shared/db';
-import { projects } from '@shared/db/schema';
-
-export const appRoutes: FastifyPluginAsync = async (app) => {
-  app.get('/projects', async () => db.select().from(projects));
-};
-```
-
-The convention is a conventional vertical flow, not an Anhedral DSL:
+The flow is a normal TypeScript architecture, not an Anhedral DSL:
 
 ```text
 contracts -> database/service -> Fastify route -> typed API client -> frontend
@@ -164,7 +178,7 @@ contracts -> database/service -> Fastify route -> typed API client -> frontend
 | 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 |
+| Billing/realtime | RevenueCat + Stripe + Ably | Unified billing entitlements and realtime 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 |
@@ -177,29 +191,32 @@ Anhedral does **not** generate or require local Postgres. Database-enabled proje
 ```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
+anhedral new <directory> --all           Explicitly select the complete stack
+pnpm anhedral:add <module...>             Add connected stack capabilities
+pnpm anhedral:ui <component...>           Add source-owned UI components
+pnpm anhedral:upgrade                     Transactionally upgrade a supported project
+pnpm anhedral:doctor                      Check ownership and generator drift
 ```
 
 Useful examples:
 
 ```sh
-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
+pnpm anhedral:add storage --dry-run
+pnpm anhedral:add desktop extension
+pnpm anhedral:add electron-updater
+pnpm anhedral:ui button dialog
+pnpm anhedral:ui data-table --target web --dry-run
+pnpm anhedral:upgrade --dry-run
+pnpm anhedral:doctor --json
 ```
 
-`--dry-run` builds the complete plan without changing the project. `--json` emits machine-readable output. `--verbose` streams child-tool diagnostics.
+`--dry-run` builds the structural plan without changing the project. For `ui add`, it also shows the exact provider command; registry-generated file paths are resolved only when the plan is applied. `--json` emits machine-readable output. `--verbose` streams child-tool diagnostics.
 
 Application lifecycle commands remain visible in the generated root `package.json`:
 
 ```sh
+pnpm first-run
+pnpm ready
 pnpm dev
 pnpm dev:all
 pnpm dev:web
@@ -223,18 +240,18 @@ Anhedral owns initial assembly and safe structural additions. It does not own pr
 
 - `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.
+- Integration substrate is recorded in `anhedral.json`; `pnpm 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.
 
 Before a structural change:
 
 ```sh
-anhedral doctor
-anhedral add <module> --dry-run
+pnpm anhedral:doctor
+pnpm anhedral:add <module> --dry-run
 ```
 
-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.
+When `doctor` reports that a project was generated by a supported older release, run `pnpm anhedral:upgrade --dry-run`, inspect the plan, and then run `pnpm 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.
 
 ## Documentation contract
 
@@ -250,6 +267,8 @@ The generator's exact output contract is documented in [docs/output-tree-contrac
 
 The complete lifecycle, runtime, cloud, command, and coding-agent topology is in
 the [Anhedral master stack map](docs/master-stack-map.md).
+The repository's implementation policy is the
+[Zen of Anhedral](docs/engineering-principles.md).
 
 ## Module dependency rules
 

package/SKILL.md

@@ -11,7 +11,70 @@ For every new project or provisioning request, begin by asking for the project
 name and whether the user already owns a custom domain for it. Do not run init
 or create provider resources until those answers establish canonical names.
 
-Use Node.js 20.19+ or 22.12+ and pnpm. `new` creates a destination directory; `init` works in an empty current directory where `.git`, `.gitignore`, and `.DS_Store` are allowed.
+`new` creates a destination directory; `init` works in an empty current
+directory where `.git`, `.gitignore`, and `.DS_Store` are allowed.
+
+## Bootstrap a blank workstation
+
+Do not assume Node.js, npm, pnpm, Git, a browser, provider CLIs, or native build
+tools are installed. After collecting the project name and domain status, audit
+the workstation before generation:
+
+```sh
+node --version
+npm --version
+pnpm --version
+git --version
+```
+
+For a new installation, recommend the current Node.js 24 LTS release. The
+generator itself accepts `^20.19.0 || >=22.12.0`, but mobile projects require
+`^22.13.0 || ^24.3.0 || >=25`; Node.js 24 LTS is the single supported choice
+that covers every Anhedral module without using an end-of-life line.
+
+If Node.js is absent, use Computer Use to open `https://nodejs.org/en/download`,
+select the current Node.js 24 LTS installer for the user's operating system and
+architecture, and stop for the user at the installer, administrator-password,
+or operating-system approval boundary. npm is bundled with Node.js and may be
+used to install pnpm, but npm is not the package manager for a generated
+workspace. Installing the public Anhedral package does not require an npm
+account or `npm login`.
+
+Install the exact pnpm release recorded by this generator's
+`package.json#packageManager` (currently `pnpm@10.34.5`):
+
+```sh
+npm install --global pnpm@10.34.5
+```
+
+Ask before a global or administrator-level installation. Verify the four
+commands above again after installation. Install Git with the operating-system
+package manager or official installer when it is missing; stop for UAC,
+administrator credentials, Xcode Command Line Tools approval, or a license
+prompt. Configure the user's real Git name and email only after asking what
+identity they want commits to use.
+
+A modern browser is required for OAuth device flows and provider dashboards.
+No global Vercel, Neon, Wrangler, EAS, shadcn, or Anhedral installation is
+required: generated scripts invoke reviewed CLI versions through `pnpm dlx`.
+GitHub CLI is recommended for repository creation. Clerk CLI and Ably CLI are
+optional supplemental control planes; use them only after the corresponding
+module is selected, record the resolved version, and do not run `clerk init`
+inside an Anhedral project because the integration source already exists.
+
+Native tools are conditional:
+
+- EAS cloud builds do not require local Xcode or Android Studio.
+- Local iOS builds and manual App Store uploads require macOS and Xcode.
+- Local Android builds/emulators require Android Studio and a compatible JDK.
+- Signed Electron releases must be built on each target OS; macOS notarization
+  needs Xcode tooling and Apple credentials, while Windows distribution needs
+  an organization-owned code-signing certificate and Windows runner.
+- Extension development requires a Chromium browser; store publication does
+  not require another build CLI beyond the generated WXT scripts.
+
+Anhedral intentionally requires neither Docker nor local Postgres. Database
+modules use managed Neon.
 
 ## Choose the construction path
 
@@ -38,7 +101,10 @@ native-subscriptions -> mobile + billing
 electron-updater     -> desktop
 ```
 
-With no module flags, generate the full stack.
+With no module flags in an interactive terminal, Anhedral prompts and suggests
+a focused web app. In a noninteractive environment, no flags retain the full
+stack for compatibility. Use `--all` when the complete stack is intentional,
+or pass explicit modules for reproducible automation.
 
 ## Master stack map
 
@@ -78,10 +144,12 @@ domain, provider-order, and verification gates.
 The lead agent must:
 
 1. Ask for project name and existing/custom-domain status first.
-2. Discover whether Computer Use/browser control and subagents are available.
-3. Resolve modules and show the user canonical project/resource names.
-4. Run the explicit CLI command, then read the generated `PRODUCTION.md`.
-5. Provision only selected providers, pausing for sign-in, MFA, secret
+2. Audit and bootstrap the workstation, then discover whether Computer
+   Use/browser control and subagents are available.
+3. Resolve modules, required accounts, and canonical project/resource names.
+4. Run the explicit CLI command, then read the generated `PRODUCTION.md`,
+   `anhedral.json`, root scripts, and package-local environment examples.
+5. Provision only selected providers in dependency order, pausing for sign-in, MFA, secret
    generation, purchases, and final submissions exactly as the reference says.
 6. Keep secrets out of chat and tool output; have the user paste them directly
    into uncommitted environment files and protected provider fields.
@@ -92,8 +160,15 @@ The lead agent must:
 ```sh
 pnpm dlx anhedral@latest new my-product
 cd my-product
+pnpm first-run
+pnpm ready
 ```
 
+`first-run` creates only missing package-local environment files and never
+overwrites existing configuration. `ready` reports missing filenames and
+required variable names without printing values; resolve every blocker before
+starting affected services.
+
 Prefer explicit modules when the user requests a smaller stack:
 
 ```sh
@@ -131,7 +206,7 @@ Use the native source conventions:
 - Product client-safe HTTP methods belong in `packages/api-client/src/app.ts`.
 - Product Drizzle tables belong in `packages/db/src/app-schema.ts`; generate and review SQL migrations.
 
-Implement an end-to-end feature as `contracts -> database/service -> route -> API client -> frontend`. Frontends may import contracts and client-safe packages, never API services, database connections, or server environments. This stack uses managed Neon and intentionally has no local Postgres service.
+Implement an end-to-end feature as `contracts -> database/service -> route -> API client -> frontend`. The generated `items` feature demonstrates that same path on every selected client—Next.js, Expo, Electron, and WXT—using one contract and API client with platform-native UI. Frontends may import contracts and client-safe packages, never API services, database connections, or server environments. This stack uses managed Neon and intentionally has no local Postgres service.
 
 ## Add modules safely
 
@@ -152,6 +227,13 @@ Require the manifest generator version to match the running CLI. Regenerate proj
 
 Do not rewrite a generated project's README or custom workflows while adding modules. Preserve custom package fields and mergeable root configuration.
 
+`README.md` and `PRODUCTION.md` are user-owned and are not regenerated by
+`anhedral add`. After adding modules, do not assume those two files describe the
+new provider set. Reconcile them against `anhedral.json`, the managed project
+`SKILL.md`, root `package.json` scripts, and every package-local `.env.example`;
+then update the user-owned documentation explicitly with the developer's
+approval.
+
 For manual projects without a trustworthy schema-v5 `anhedral.json`, add modules with the manual reference instead. Never fabricate manifest ownership records, template provenance, UI installation records, or hashes. A manually authored workspace is valid as an application workspace but is not CLI-managed until it has been regenerated by a matching Anhedral version.
 
 ## Add UI components
@@ -181,16 +263,20 @@ Explain that warnings can represent mergeable or user-owned drift, while modifie
 
 ## Configure the generated project
 
-Copy environment examples, fill only selected provider values, install, and verify:
+Create only missing local environment files, fill selected provider values, and
+verify readiness:
 
 ```sh
-cp apps/api/.env.example apps/api/.env
-cp packages/db/.env.example packages/db/.env
 pnpm install
+pnpm first-run
+pnpm ready
 pnpm verify
 ```
 
-Copy only examples that exist for the selected surfaces. Client packages use package-local runtime files (for example, copy `apps/web/.env.example` to `apps/web/.env.local` and `apps/desktop/.env.example` to `apps/desktop/.env`); the root `.env.example` is an inventory, not a runtime environment file.
+`first-run` copies only examples that exist for selected surfaces and never
+overwrites an existing file. Client packages use package-local runtime files
+(for example, `apps/web/.env.local` and `apps/desktop/.env`); the root
+`.env.example` is an inventory, not a runtime environment file.
 
 Common selected keys are:
 
@@ -218,6 +304,15 @@ Treat the root `vercel.json` as the only Vercel Services configuration. It uses
 
 For billing, keep Neon authoritative: RevenueCat reconciliation writes the subscription revision and realtime outbox atomically, Ably carries only per-user invalidations, and every client refetches the entitlement. Schedule the authenticated outbox flush every five minutes and verify purchase, webhook, reconnect, and foreground recovery paths.
 
+The generated billing substrate does not implement Stripe Checkout, Stripe
+webhooks, or a web purchase screen. RevenueCat's Test Store can exercise the
+entitlement flow without Apple, Google, or Stripe accounts. Native purchases
+require `native-subscriptions` plus Apple/Google store setup. If the user wants
+web subscriptions through RevenueCat Billing or a manual Stripe integration,
+treat that as an explicit product feature with additional account, checkout,
+webhook, tax, and customer-portal work; do not claim the generated billing
+module already completed it.
+
 Use `apps/mobile` for EAS, `pnpm desktop:build` for a current-host Electron artifact, matching platform-specific desktop scripts in CI, and `pnpm extension:zip` for the WXT archive.
 
 For `electron-updater`, provision the generated private R2 bucket and
@@ -227,7 +322,7 @@ platform and publish artifacts before mutable channel metadata.
 
 For storage, generate `apps/assets-private-proxy` plus `cloudflare/r2-cors.template.json` and keep the R2 bucket private. The Worker must be named `assets-private-proxy`, bind the normalized `<project>-assets` bucket as `ASSETS`, disable `workers.dev`, and own `assets.<domain>` as a Worker Custom Domain. Presigned uploads continue on the R2 S3 API hostname. Root every key below `R2_PREFIX=storage`; expose only `storage/confirmed/` through the Worker and reject staging plus `generation-inputs`. Authenticated private reads must verify upload ownership and return a presigned GET URL bounded by `R2_PROXY_READ_URL_TTL_SECONDS`.
 
-When explaining domains, distinguish DNS delegation from registrar transfer. A GoDaddy registration can use Cloudflare authoritative nameservers immediately; transferring registration/billing to Cloudflare Registrar is optional and subject to eligibility locks. Keep Vercel app/API A or CNAME records DNS-only in Cloudflare, while Worker Custom Domains stay Cloudflare-managed and proxied.
+When explaining domains, distinguish DNS delegation from registrar transfer. A domain can use Cloudflare authoritative nameservers while remaining with its current registrar; transferring registration/billing to Cloudflare Registrar is optional and subject to eligibility locks. Keep Vercel app/API A or CNAME records DNS-only in Cloudflare, while Worker Custom Domains stay Cloudflare-managed and proxied.
 
 ## Verify outcomes