anhedral 0.1.10 → 0.3.0

package/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: anhedral-init
+description: Create, extend, explain, or diagnose complete Anhedral-generated TypeScript stacks. Use for new/init/add/ui/doctor; ordinary Next.js, Expo, Fastify, Drizzle/Neon, Clerk, R2, Electron, or WXT development inside a generated workspace; interpreting anhedral.json ownership; reproducing the scaffold manually; or verifying generated applications.
+---
+
+# Anhedral Init
+
+Anhedral is a stack generator, not an application runtime or programming language. Generated projects use ordinary framework source and expose the complete integration code. Do not invent Anhedral-specific models, routes, queries, components, or client hooks when the selected framework already has a documented convention.
+
+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.
+
+## Choose the construction path
+
+- Use the manual path whenever the user asks to avoid the Anhedral CLI, the CLI is unavailable, or the task requires explaining/reproducing the scaffold itself.
+- Before creating or changing files manually, read [references/manual-scaffolding.md](references/manual-scaffolding.md) completely and follow its ordered procedure. Treat it as the canonical manual checklist, including its source-file matrix and feature gates.
+- Use the CLI path only when the user permits it. Do not silently substitute `anhedral init`, `anhedral add`, imported generator code, or a generated demo for the manual path.
+- For an exact-version scaffold inside the Anhedral source repository, render from the current `src/templates/*.ts`, `src/scaffold.ts`, and `src/dependencies.ts`; do not copy stale demo output. Outside that repository, implement the behavior and file contract in the manual reference and pin a mutually compatible toolchain.
+
+The manual path must leave a complete working workspace, not merely a directory tree or list of commands. Write the source, configuration, tests, environment examples, CI, deployment configuration, and database migration gate selected by the module plan. Install and verify when the environment permits it.
+
+## Select modules
+
+Choose app surfaces from `web`, `mobile`, `api`, `desktop`, and `extension`.
+
+Choose backend features from `db`, `auth`, `billing`, `storage`, and `native-subscriptions`.
+
+Apply these dependency rules automatically:
+
+```text
+auth                 -> api + db
+billing              -> auth
+storage              -> auth
+native-subscriptions -> mobile + billing
+```
+
+With no module flags, generate the full stack.
+
+## Initialize
+
+```sh
+pnpm dlx anhedral@latest new my-product
+cd my-product
+```
+
+Prefer explicit modules when the user requests a smaller stack:
+
+```sh
+pnpm dlx anhedral@latest new my-product --web --api --db --auth
+pnpm dlx anhedral@latest new my-product --web --mobile --ui button,dialog --native-styling nativewind
+pnpm dlx anhedral@latest new my-api --api --skip-install
+```
+
+Use the stable toolchain for normal generation. The `latest` value is retained only as a metadata compatibility channel for maintainer investigations:
+
+```sh
+pnpm dlx anhedral@latest new my-product --toolchain stable
+pnpm dlx anhedral@latest new my-product --toolchain latest
+```
+
+Both channels generate the same exact verified dependencies and integrity-checked bundled templates; `latest` only records investigation intent in `anhedral.json`. Upstream refreshes happen outside user projects and are shipped only after review and checksum verification. Neither channel invokes mutable upstream framework generators inside a user project.
+
+Do not run any command in this section during the manual path.
+
+## Develop inside a generated project
+
+Read these files before changing product code:
+
+1. `README.md` for the selected modules, first run, and source-location map.
+2. `docs/DEVELOPMENT.md` for end-to-end feature recipes.
+3. `docs/STACK.md` for responsibility boundaries and official tool documentation.
+4. `PRODUCTION.md` only for provisioning, deployment, DNS, stores, or release work.
+
+Use the native source conventions:
+
+- Next.js code belongs in `apps/web/app`, `apps/web/components`, and `apps/web/lib`.
+- Expo Router code belongs in `apps/mobile/app` and `apps/mobile/components`.
+- Fastify routes and server-only services belong in `apps/api/src/routes` and `apps/api/src/services`.
+- Shared Zod network schemas belong in `packages/contracts/src`.
+- Client-safe HTTP methods belong in `packages/api-client/src`.
+- Drizzle schema and queries belong in `packages/db`; 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.
+
+## Add modules safely
+
+Run `add` only from a project containing `anhedral.json` schema v5:
+
+```sh
+pnpm dlx anhedral@latest add desktop extension
+pnpm dlx anhedral@latest add storage --dry-run
+```
+
+Use `--dry-run` before a consequential add. Use `--json` when another program needs the plan; JSON failures include a stable `code` and a human-readable `error`. Use `--verbose` for interactive child-command diagnostics. Do not bypass ownership conflicts: Anhedral intentionally refuses modified managed files, user-owned files, symlinks, and unowned collisions.
+
+Require the manifest generator version to match the running CLI. Regenerate projects created by another version; do not add compatibility branches.
+
+Do not rewrite a generated project's README or custom workflows while adding modules. Preserve custom package fields and mergeable root configuration.
+
+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
+
+Use the unified UI wrapper for source-owned components:
+
+```sh
+pnpm dlx anhedral@latest ui add button dialog
+pnpm dlx anhedral@latest ui add select --target mobile
+pnpm dlx anhedral@latest ui add data-table --target web --dry-run
+```
+
+Anhedral routes web, desktop, and extension targets to shadcn/ui. It routes Expo mobile to React Native Reusables using the manifest's NativeWind or Uniwind selection. Omit `--target` to add the provider-specific implementation to every selected UI client. Provider writes occur in transaction staging and must pass the same ownership checks as module additions.
+
+## Diagnose
+
+Dry-runs never perform transaction recovery. If a recovery journal is pending, rerun the original command without `--dry-run` before requesting a new preview.
+
+Check recorded files and hashes with:
+
+```sh
+pnpm dlx anhedral@latest doctor
+pnpm dlx anhedral@latest doctor --json
+```
+
+Explain that warnings can represent mergeable or user-owned drift, while modified or missing managed files make the project unhealthy.
+
+## Configure the generated project
+
+Copy environment examples, fill only selected provider values, install, and verify:
+
+```sh
+cp apps/api/.env.example apps/api/.env
+cp packages/db/.env.example packages/db/.env
+pnpm install
+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.
+
+Common selected keys are:
+
+- Neon: `DATABASE_URL`
+- Clerk server: `CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`
+- Clerk clients: `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`, `VITE_CLERK_PUBLISHABLE_KEY`
+- RevenueCat: `RC_WEBHOOK_SECRET`, `RC_SECRET_API_KEY`, `RC_ENTITLEMENT_ID`, `EXPO_PUBLIC_RC_*`
+- Ably billing synchronization: server-only `ABLY_API_KEY`; clients obtain scoped tokens from the API
+- R2: `BASE_URL`, `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_PREFIX=storage`, `R2_PROXY_READ_URL_TTL_SECONDS=600`; keep `CLOUDFLARE_API_TOKEN` operations/CI-only
+- Internal billing/storage jobs: high-entropy server-only `CRON_SECRET`
+
+Never commit real `.env` files. Keep `ANHEDRAL_DEMO=false` in production.
+
+Run only scripts present for installed modules. Typical commands include `dev:web`, `dev:mobile`, `dev:api`, `dev:desktop`, `dev:extension`, corresponding `verify:*` scripts, and database scripts for `db` projects.
+
+## Understand deployment
+
+Treat the root `vercel.json` as the only Vercel Services configuration. It uses the current `services` schema, declares `apps/api` and `apps/web` as independent service roots, and routes `/api/(.*)` before the web catch-all. Vercel preserves the original path, so Fastify mounts its routes under `/api` locally and in deployment. Select the Services framework preset before deploying.
+
+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.
+
+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 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.
+
+## Verify outcomes
+
+After generation or repair, run the strongest practical checks:
+
+```sh
+pnpm typecheck
+pnpm verify
+pnpm build
+```
+
+Use `pnpm --filter ./apps/api test` when the API exists. If verification fails, report the exact package and command rather than replacing generated ownership records manually.
+
+For exact representative trees, consult `docs/output-tree-contract.md` in the Anhedral repository. During manual construction, also compare the finished workspace with the file matrix in [references/manual-scaffolding.md](references/manual-scaffolding.md); every selected conditional file must exist and every unselected provider integration must be absent.

package/bin/anhedral.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import '../dist/index.js';
+import '../dist/bin.js';

package/dist/architecture/contributions.d.ts

@@ -0,0 +1,28 @@
+import { type ModuleId } from './modules.js';
+export type EnvironmentContribution = {
+    readonly owner: ModuleId;
+    readonly name: string;
+    readonly defaultValue: string;
+};
+export type CronContribution = {
+    readonly owner: ModuleId;
+    readonly id: string;
+    readonly path: string;
+    readonly schedule: string;
+};
+export type ModuleCompositionContribution = {
+    readonly module: ModuleId;
+    readonly environment: readonly Omit<EnvironmentContribution, 'owner'>[];
+    readonly crons: readonly Omit<CronContribution, 'owner'>[];
+};
+export type CompositionModel = {
+    readonly modules: readonly ModuleId[];
+    readonly environment: readonly EnvironmentContribution[];
+    readonly crons: readonly CronContribution[];
+};
+export type CompositionErrorCode = 'DUPLICATE_ENVIRONMENT_CONTRIBUTION' | 'DUPLICATE_CRON_CONTRIBUTION';
+export declare class CompositionError extends Error {
+    readonly code: CompositionErrorCode;
+    constructor(code: CompositionErrorCode, message: string);
+}
+export declare function collectModuleContributions(requestedModules: readonly ModuleId[], overrides?: Readonly<Partial<Record<ModuleId, ModuleCompositionContribution>>>): CompositionModel;

package/dist/architecture/contributions.js

@@ -0,0 +1,118 @@
+import { resolveModules } from './modules.js';
+export class CompositionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CompositionError';
+    }
+}
+const EMPTY = Object.freeze([]);
+const MODULE_CONTRIBUTIONS = Object.freeze({
+    web: Object.freeze({ module: 'web', environment: EMPTY, crons: EMPTY }),
+    mobile: Object.freeze({ module: 'mobile', environment: EMPTY, crons: EMPTY }),
+    api: Object.freeze({
+        module: 'api',
+        environment: Object.freeze([
+            { name: 'ANHEDRAL_DEMO', defaultValue: 'false' },
+            { name: 'PORT', defaultValue: '8787' },
+            { name: 'TRUST_PROXY_HOPS', defaultValue: '0' },
+            { name: 'CORS_ORIGINS', defaultValue: '' },
+        ]),
+        crons: EMPTY,
+    }),
+    desktop: Object.freeze({ module: 'desktop', environment: EMPTY, crons: EMPTY }),
+    extension: Object.freeze({ module: 'extension', environment: EMPTY, crons: EMPTY }),
+    db: Object.freeze({
+        module: 'db',
+        environment: Object.freeze([{ name: 'DATABASE_URL', defaultValue: 'YOUR_NEON_POSTGRES_URL' }]),
+        crons: EMPTY,
+    }),
+    auth: Object.freeze({
+        module: 'auth',
+        environment: Object.freeze([
+            { name: 'CLERK_PUBLISHABLE_KEY', defaultValue: 'pk_test_***' },
+            { name: 'CLERK_SECRET_KEY', defaultValue: 'sk_test_***' },
+        ]),
+        crons: EMPTY,
+    }),
+    billing: Object.freeze({
+        module: 'billing',
+        environment: Object.freeze([
+            { name: 'RC_WEBHOOK_SECRET', defaultValue: '' },
+            { name: 'RC_SECRET_API_KEY', defaultValue: '' },
+            { name: 'RC_ENTITLEMENT_ID', defaultValue: 'pro' },
+            { name: 'ABLY_API_KEY', defaultValue: '' },
+            { name: 'CRON_SECRET', defaultValue: '' },
+        ]),
+        crons: Object.freeze([
+            { id: 'realtime-outbox', path: '/api/internal/realtime/flush', schedule: '*/5 * * * *' },
+        ]),
+    }),
+    storage: Object.freeze({
+        module: 'storage',
+        environment: Object.freeze([
+            { name: 'BASE_URL', defaultValue: 'http://localhost:8787' },
+            { name: 'R2_ACCOUNT_ID', defaultValue: '' },
+            { name: 'R2_ACCESS_KEY_ID', defaultValue: '' },
+            { name: 'R2_SECRET_ACCESS_KEY', defaultValue: '' },
+            { name: 'R2_BUCKET_NAME', defaultValue: '' },
+            { name: 'R2_PREFIX', defaultValue: 'storage' },
+            { name: 'R2_PROXY_READ_URL_TTL_SECONDS', defaultValue: '600' },
+            { name: 'CLOUDFLARE_API_TOKEN', defaultValue: '' },
+            { name: 'CRON_SECRET', defaultValue: '' },
+        ]),
+        crons: Object.freeze([
+            { id: 'storage-cleanup', path: '/api/internal/storage/cleanup', schedule: '0 3 * * *' },
+        ]),
+    }),
+    'native-subscriptions': Object.freeze({
+        module: 'native-subscriptions',
+        environment: EMPTY,
+        crons: EMPTY,
+    }),
+});
+function collectEnvironmentFromRegistry(modules, registry) {
+    const byName = new Map();
+    for (const module of modules) {
+        for (const contribution of registry[module].environment) {
+            const candidate = Object.freeze({ owner: module, ...contribution });
+            const previous = byName.get(candidate.name);
+            if (previous && previous.defaultValue !== candidate.defaultValue) {
+                throw new CompositionError('DUPLICATE_ENVIRONMENT_CONTRIBUTION', `Environment variable ${candidate.name} has incompatible defaults from ${previous.owner} and ${module}.`);
+            }
+            if (!previous)
+                byName.set(candidate.name, candidate);
+        }
+    }
+    return Object.freeze([...byName.values()]);
+}
+function collectCronsFromRegistry(modules, registry) {
+    const byId = new Map();
+    for (const module of modules) {
+        for (const contribution of registry[module].crons) {
+            const candidate = Object.freeze({ owner: module, ...contribution });
+            const previous = byId.get(candidate.id);
+            if (previous && (previous.path !== candidate.path || previous.schedule !== candidate.schedule)) {
+                throw new CompositionError('DUPLICATE_CRON_CONTRIBUTION', `Cron ${candidate.id} has incompatible definitions from ${previous.owner} and ${module}.`);
+            }
+            if (!previous)
+                byId.set(candidate.id, candidate);
+        }
+    }
+    return Object.freeze([...byId.values()]);
+}
+export function collectModuleContributions(requestedModules, overrides = {}) {
+    const modules = resolveModules(requestedModules).resolvedModules;
+    const contributions = Object.freeze({ ...MODULE_CONTRIBUTIONS, ...overrides });
+    for (const module of modules) {
+        if (contributions[module].module !== module) {
+            throw new Error(`Composition contribution key ${module} must declare the same module ID.`);
+        }
+    }
+    return Object.freeze({
+        modules,
+        environment: collectEnvironmentFromRegistry(modules, contributions),
+        crons: collectCronsFromRegistry(modules, contributions),
+    });
+}

package/dist/architecture/index.d.ts

@@ -0,0 +1,12 @@
+export { DEFAULT_MODULE_DEFINITIONS, DEFAULT_MODULE_REGISTRY, MODULE_IDS, ModuleRegistryError, ModuleResolutionError, createModuleRegistry, isModuleId, resolveModules, } from './modules.js';
+export type { DependencyEdge, ModuleDefinition, ModuleId, ModuleKind, ModuleRegistry, ModuleRegistryErrorCode, ModuleResolution, ModuleResolutionErrorCode, } from './modules.js';
+export { FILE_OWNERSHIP_CLASSES, PlanBuildError, buildGenerationPlan, hashContent, isFileOwnershipClass, isSha256, normalizePlanPath, writePolicyForOwnership, } from './plan.js';
+export type { BuildGenerationPlanInput, FileOwner, FileOwnershipClass, FileWritePolicy, GenerationOperation, GenerationPlan, ModulePlanContribution, PlanBuildErrorCode, PlanFileInput, PlannedFile, } from './plan.js';
+export { MANIFEST_SCHEMA_VERSION, ManifestValidationError, createManifest, readManifest, serializeManifest, } from './manifest.js';
+export { TEMPLATE_IDS, isTemplateId, templateIdsForModules, } from './templates.js';
+export type { TemplateId, TemplateProvenance, TemplateProvenanceMap, } from './templates.js';
+export { CompositionError, collectModuleContributions, } from './contributions.js';
+export type { CompositionErrorCode, CompositionModel, CronContribution, EnvironmentContribution, ModuleCompositionContribution, } from './contributions.js';
+export type { CreateManifestInput, ManifestFileRecord, ManifestToolchain, ManifestValidationErrorCode, ProjectManifest, } from './manifest.js';
+export { NATIVE_STYLING_LIBRARIES, UI_PROVIDERS, UI_TARGETS, buildUiInstallCommands, isNativeStylingLibrary, isUiProvider, isUiTarget, mergeUiInstalls, normalizeUiComponentName, parseUiComponentList, providerForTarget, registrySourceFor, resolveUiInstalls, uiInstallKey, } from '../ui.js';
+export type { NativeStylingLibrary, UiComponentInstall, UiInstallCommand, UiProvider, UiTarget, } from '../ui.js';

package/dist/architecture/index.js

@@ -0,0 +1,6 @@
+export { DEFAULT_MODULE_DEFINITIONS, DEFAULT_MODULE_REGISTRY, MODULE_IDS, ModuleRegistryError, ModuleResolutionError, createModuleRegistry, isModuleId, resolveModules, } from './modules.js';
+export { FILE_OWNERSHIP_CLASSES, PlanBuildError, buildGenerationPlan, hashContent, isFileOwnershipClass, isSha256, normalizePlanPath, writePolicyForOwnership, } from './plan.js';
+export { MANIFEST_SCHEMA_VERSION, ManifestValidationError, createManifest, readManifest, serializeManifest, } from './manifest.js';
+export { TEMPLATE_IDS, isTemplateId, templateIdsForModules, } from './templates.js';
+export { CompositionError, collectModuleContributions, } from './contributions.js';
+export { NATIVE_STYLING_LIBRARIES, UI_PROVIDERS, UI_TARGETS, buildUiInstallCommands, isNativeStylingLibrary, isUiProvider, isUiTarget, mergeUiInstalls, normalizeUiComponentName, parseUiComponentList, providerForTarget, registrySourceFor, resolveUiInstalls, uiInstallKey, } from '../ui.js';

package/dist/architecture/manifest.d.ts

@@ -0,0 +1,53 @@
+import { type ModuleId, type ModuleRegistry } from './modules.js';
+import { type FileOwner, type FileOwnershipClass, type GenerationPlan } from './plan.js';
+import { type TemplateProvenanceMap } from './templates.js';
+import { type NativeStylingLibrary, type UiComponentInstall } from '../ui.js';
+export declare const MANIFEST_SCHEMA_VERSION: 5;
+export type ManifestToolchain = 'stable' | 'latest';
+export type ManifestFileRecord = {
+    readonly owner: FileOwner;
+    readonly ownership: FileOwnershipClass;
+    readonly hash: string;
+    /** Normalized Unix permission bits (0o000-0o777), or null on platforms without portable modes. */
+    readonly mode: number | null;
+};
+export type ProjectManifest = {
+    readonly schemaVersion: typeof MANIFEST_SCHEMA_VERSION;
+    readonly generatorVersion: string;
+    readonly project: {
+        readonly name: string;
+        readonly displayName: string;
+    };
+    /** The complete, canonically ordered module dependency closure. */
+    readonly modules: readonly ModuleId[];
+    readonly toolchain: ManifestToolchain;
+    /** Immutable template catalog entries used to seed the generated workspace. */
+    readonly templates: TemplateProvenanceMap;
+    readonly ui: {
+        readonly nativeStyling: NativeStylingLibrary;
+        readonly components: readonly UiComponentInstall[];
+    };
+    readonly files: Readonly<Record<string, ManifestFileRecord>>;
+};
+export type CreateManifestInput = {
+    readonly generatorVersion: string;
+    readonly project: {
+        readonly name: string;
+        readonly displayName: string;
+    };
+    readonly plan: GenerationPlan;
+    readonly toolchain: ManifestToolchain;
+    readonly templates: TemplateProvenanceMap;
+    readonly nativeStyling?: NativeStylingLibrary;
+    readonly components?: readonly UiComponentInstall[];
+    readonly registry?: ModuleRegistry;
+};
+export type ManifestValidationErrorCode = 'INVALID_JSON' | 'INVALID_MANIFEST' | 'INVALID_SCHEMA_VERSION' | 'FUTURE_SCHEMA_VERSION' | 'UNKNOWN_MODULE' | 'DUPLICATE_MODULE' | 'INVALID_MODULE_CLOSURE' | 'INVALID_FILE_RECORD';
+export declare class ManifestValidationError extends Error {
+    readonly code: ManifestValidationErrorCode;
+    readonly path: string;
+    constructor(code: ManifestValidationErrorCode, message: string, path: string);
+}
+export declare function readManifest(input: string | unknown, registry?: ModuleRegistry): ProjectManifest;
+export declare function createManifest(input: CreateManifestInput): ProjectManifest;
+export declare function serializeManifest(manifest: ProjectManifest): string;