anhedral 0.1.0 → 0.1.3

package/README.md

@@ -9,40 +9,42 @@ Opinionated init CLI for product teams shipping with Next.js, Expo, Fastify, Dri
 
 ## Usage
 
-Run the CLI directly without installing it globally:
+Run the latest published CLI directly without installing it globally:
 
 ```sh
-pnpm dlx anhedral init next
-pnpm dlx anhedral init next-fullstack
-pnpm dlx anhedral init expo-fullstack
-pnpm dlx anhedral init backend
+pnpm dlx anhedral@latest init
+pnpm dlx anhedral@latest init --next
+pnpm dlx anhedral@latest init --extension
+pnpm dlx anhedral@latest init --next --extension
 ```
 
 ```sh
-npx anhedral init next
-npx anhedral init next-fullstack
-npx anhedral init expo-fullstack
-npx anhedral init backend
+npx anhedral@latest init
+npx anhedral@latest init --next
+npx anhedral@latest init --extension
+npx anhedral@latest init --next --extension
 ```
 
 Global install also works:
 
 ```sh
-pnpm add -g anhedral
-anhedral init next
+pnpm add -g anhedral@latest
+anhedral init
 ```
 
 ```sh
-npm install -g anhedral
-anhedral init next
+npm install -g anhedral@latest
+anhedral init
 ```
 
 ## Stacks
 
-- `next`: Next.js App Router for the fastest web-only SaaS path.
-- `next-fullstack`: Next.js frontend plus Fastify backend for clearer service boundaries.
-- `expo-fullstack`: Expo app plus Fastify backend for mobile-first or multi-client products.
-- `backend`: Fastify-only API foundation for headless products and integrations.
+- `init`: Expo app plus Fastify backend. This is the default.
+- `init --next`: Next.js frontend plus Fastify backend.
+- `init --extension`: default Expo fullstack plus a WXT Chrome extension.
+- `init --next --extension`: Next.js fullstack plus a WXT Chrome extension.
+
+Every scaffold is a pnpm workspace with `apps/*` and `packages/*`. 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 and generated outputs.
 
@@ -58,8 +60,68 @@ pnpm test:all
 
 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:
+
 ```sh
-pnpm build
-pnpm test:all
-npm publish
+git push origin main
+```
+
+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:
+
+```sh
+pnpm release:check
+npm publish --provenance=false --ignore-scripts
+```
+
+## Maintenance
+
+This repo is now maintained in two lanes:
+
+- `stable`: the default user-facing toolchain, pinned to known-good upstream CLI versions in `src/toolchain.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: detect drift on `latest`, verify it, then promote the pinned `stable` versions only after the e2e matrix passes.
+
+### Recommended automation
+
+- Renovate is configured in `renovate.json` to keep this repo's own dependencies 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 toolchain pins in `src/toolchain.ts` are annotated so Renovate can open PRs when upstream 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:
+
+```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
+```
+
+When a toolchain pin PR passes and the generated outputs look good, update the `verifiedAt` date in `src/toolchain.ts` and release normally.
+
+### Release policy
+
+- 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.

package/dist/branding.d.ts

@@ -1,3 +1,5 @@
 export declare const ANHEDRAL_LOGO_FILE_NAME = "anhedral.svg";
 export declare const ANHEDRAL_LOGO_PUBLIC_PATH = "/anhedral.svg";
+export declare const ANHEDRAL_FAVICON_FILE_NAME = "favicon.ico";
 export declare function writeAnhedralLogo(root: string): void;
+export declare function writeAnhedralWebBranding(root: string): void;

package/dist/branding.js

@@ -1,9 +1,17 @@
-import { readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { writeFile } from './util.js';
 export const ANHEDRAL_LOGO_FILE_NAME = 'anhedral.svg';
 export const ANHEDRAL_LOGO_PUBLIC_PATH = `/${ANHEDRAL_LOGO_FILE_NAME}`;
+export const ANHEDRAL_FAVICON_FILE_NAME = 'favicon.ico';
 const ANHEDRAL_LOGO_SVG = readFileSync(new URL('../anhedral.svg', import.meta.url), 'utf8');
+const ANHEDRAL_FAVICON = readFileSync(new URL(`../${ANHEDRAL_FAVICON_FILE_NAME}`, import.meta.url));
 export function writeAnhedralLogo(root) {
     writeFile(path.join(root, 'public', ANHEDRAL_LOGO_FILE_NAME), ANHEDRAL_LOGO_SVG);
 }
+export function writeAnhedralWebBranding(root) {
+    writeAnhedralLogo(root);
+    const faviconPath = path.join(root, 'app', ANHEDRAL_FAVICON_FILE_NAME);
+    mkdirSync(path.dirname(faviconPath), { recursive: true });
+    writeFileSync(faviconPath, ANHEDRAL_FAVICON);
+}

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+import type { FrontendMode, InitOptions } from './scaffold.js';
+export declare const DEFAULT_FRONTEND_MODE: FrontendMode;
+export declare const USAGE = "\nanhedral init [--next] [--extension] [--toolchain <latest|stable>]\n\nCommands:\n  anhedral init\n    Expo, Fastify, Drizzle ORM, Neon Postgres, Clerk Auth, RevenueCat + Stripe, Cloudflare R2, shared packages\n\n  anhedral init --next\n    Next.js App Router, shadcn/ui, Tailwind CSS, TypeScript, Fastify, Drizzle ORM, Neon Postgres, Clerk Auth, Stripe, Cloudflare R2, shared packages\n\n  anhedral init --extension\n    Expo + Fastify plus a WXT Chrome extension\n\n  anhedral init --next --extension\n    Next.js + Fastify plus a WXT Chrome extension\n";
+export type ParsedFlags = {
+    next: boolean;
+    extension: boolean;
+    toolchain?: string;
+};
+export declare function parseCli(args: string[]): ParsedFlags;
+export declare function deriveProjectName(cwd: string): string;
+export declare function deriveDisplayName(cwd: string): string;
+export declare function buildOptions(flags: ParsedFlags): InitOptions;

package/dist/cli.js

@@ -0,0 +1,86 @@
+import path from 'node:path';
+import { env } from 'node:process';
+import { TOOLCHAIN_CHANNELS, resolveToolchainChannel } from './toolchain.js';
+export const DEFAULT_FRONTEND_MODE = 'expo';
+export const USAGE = `
+anhedral init [--next] [--extension] [--toolchain <latest|stable>]
+
+Commands:
+  anhedral init
+    Expo, Fastify, Drizzle ORM, Neon Postgres, Clerk Auth, RevenueCat + Stripe, Cloudflare R2, shared packages
+
+  anhedral init --next
+    Next.js App Router, shadcn/ui, Tailwind CSS, TypeScript, Fastify, Drizzle ORM, Neon Postgres, Clerk Auth, Stripe, Cloudflare R2, shared packages
+
+  anhedral init --extension
+    Expo + Fastify plus a WXT Chrome extension
+
+  anhedral init --next --extension
+    Next.js + Fastify plus a WXT Chrome extension
+`;
+export function parseCli(args) {
+    const flags = {
+        next: false,
+        extension: false,
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (!token.startsWith('--')) {
+            throw new Error(`Unexpected argument: ${token}. Use flags: --next, --extension, --toolchain`);
+        }
+        if (token === '--next') {
+            flags.next = true;
+            continue;
+        }
+        if (token === '--extension') {
+            flags.extension = true;
+            continue;
+        }
+        if (token === '--toolchain') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('Missing value for --toolchain');
+            }
+            flags.toolchain = value;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown flag: ${token}`);
+    }
+    return flags;
+}
+export function deriveProjectName(cwd) {
+    const base = path.basename(cwd);
+    const sanitized = base
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return sanitized || 'anhedral-app';
+}
+export function deriveDisplayName(cwd) {
+    const base = path.basename(cwd).trim();
+    return base || 'Anhedral App';
+}
+export function buildOptions(flags) {
+    const cwd = process.cwd();
+    const projectName = deriveProjectName(cwd);
+    const displayName = deriveDisplayName(cwd);
+    if (flags.toolchain != null && !TOOLCHAIN_CHANNELS.includes(flags.toolchain)) {
+        throw new Error(`--toolchain must be one of: ${TOOLCHAIN_CHANNELS.join(', ')}`);
+    }
+    return {
+        frontend: flags.next ? 'next' : DEFAULT_FRONTEND_MODE,
+        extension: flags.extension,
+        projectName,
+        displayName,
+        auth: 'clerk',
+        payments: flags.next ? 'stripe' : 'revenuecat',
+        db: 'neon',
+        orm: 'drizzle',
+        storage: 'r2',
+        api: 'fastify',
+        monorepo: true,
+        toolchainChannel: resolveToolchainChannel(flags.toolchain ?? env.ANHEDRAL_TOOLCHAIN),
+    };
+}

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import type { InitMode } from './scaffold.js';
+import type { InitOptions } from './scaffold.js';
 import { type ToolchainSpec } from './toolchain.js';
 export type ScaffoldCommand = {
     cmd: string;
@@ -7,6 +7,5 @@ export type ScaffoldCommand = {
 };
 export declare function getDefaultWebInitCommand(toolchain: ToolchainSpec, projectName: string): ScaffoldCommand;
 export declare function getDefaultWebDependencyCommands(): ScaffoldCommand[];
-export declare function getHeadlessInstallCommands(): ScaffoldCommand[];
 export declare function getBackendInstallCommands(): ScaffoldCommand[];
-export declare function getSkillCommands(mode: InitMode): string[];
+export declare function getSkillCommands(options: Pick<InitOptions, 'frontend' | 'extension'>): string[];

package/dist/commands.js

@@ -1,6 +1,4 @@
 import { toolPackageRef } from './toolchain.js';
-const TYPESCRIPT_VERSION = '5.9.3';
-const NODE_TYPES_VERSION = '25.5.0';
 export function getDefaultWebInitCommand(toolchain, projectName) {
     return {
         cmd: [
@@ -21,7 +19,7 @@ export function getDefaultWebInitCommand(toolchain, projectName) {
 export function getDefaultWebDependencyCommands() {
     return [
         {
-            cmd: 'pnpm add @clerk/nextjs @clerk/ui drizzle-orm @neondatabase/serverless stripe @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner',
+            cmd: 'pnpm add @clerk/nextjs drizzle-orm @neondatabase/serverless stripe @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner',
             skippable: true,
         },
         {
@@ -30,18 +28,6 @@ export function getDefaultWebDependencyCommands() {
         },
     ];
 }
-export function getHeadlessInstallCommands() {
-    return [
-        {
-            cmd: 'pnpm add fastify @fastify/cors better-auth drizzle-orm @neondatabase/serverless @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner dotenv',
-            skippable: true,
-        },
-        {
-            cmd: `pnpm add -D typescript@${TYPESCRIPT_VERSION} tsx @types/node@${NODE_TYPES_VERSION} drizzle-kit`,
-            skippable: true,
-        },
-    ];
-}
 export function getBackendInstallCommands() {
     return [
         {
@@ -52,23 +38,13 @@ export function getBackendInstallCommands() {
         },
     ];
 }
-export function getSkillCommands(mode) {
-    switch (mode) {
-        case 'next':
-        case 'next-fullstack':
-            return [
-                'pnpm dlx skills add https://github.com/clerk/skills --skill clerk-custom-ui',
-                'pnpm dlx skills add https://github.com/stripe/ai --skill stripe-best-practices',
-            ];
-        case 'expo-fullstack':
-            return [
-                'pnpm dlx skills add https://github.com/clerk/skills --skill clerk-custom-ui',
-                'pnpm dlx skills add https://github.com/revenuecat/revenuecat-skill --skill revenuecat',
-                'pnpm dlx skills add https://github.com/stripe/ai --skill stripe-best-practices',
-            ];
-        case 'backend':
-            return [
-                'pnpm dlx skills add https://github.com/better-auth/skills --skill better-auth-best-practices',
-            ];
+export function getSkillCommands(options) {
+    const commands = [
+        'pnpm dlx skills add https://github.com/clerk/skills --skill clerk-custom-ui',
+        'pnpm dlx skills add https://github.com/stripe/ai --skill stripe-best-practices',
+    ];
+    if (options.frontend === 'expo') {
+        commands.splice(1, 0, 'pnpm dlx skills add https://github.com/revenuecat/revenuecat-skill --skill revenuecat');
     }
+    return commands;
 }

package/dist/index.js

@@ -1,137 +1,7 @@
 #!/usr/bin/env tsx
-import path from 'node:path';
-import { argv, env, exit } from 'node:process';
-import { STACK_IDS, scaffoldProject } from './scaffold.js';
-import { TOOLCHAIN_CHANNELS, resolveToolchainChannel } from './toolchain.js';
-const USAGE = `
-anhedral init <next|next-fullstack|expo-fullstack|backend> [--toolchain <latest|stable>]
-
-Commands:
-  anhedral init next
-    Next.js App Router, shadcn/ui, Tailwind CSS, TypeScript, Drizzle ORM, Neon Postgres, Clerk Auth, Stripe, Cloudflare R2
-
-  anhedral init next-fullstack
-    Next.js App Router, shadcn/ui, Tailwind CSS, TypeScript, Fastify, Drizzle ORM, Neon Postgres, Clerk Auth, Stripe, Cloudflare R2
-
-  anhedral init expo-fullstack
-    Expo, NativeWind/Tailwind CSS, TypeScript, Fastify, Drizzle ORM, Neon Postgres, Clerk Auth, RevenueCat + Stripe, Cloudflare R2
-
-  anhedral init backend
-    Fastify, TypeScript, Drizzle ORM, Neon Postgres, Clerk Auth or Better Auth, Stripe-ready integrations, Cloudflare R2
-`;
-function parseCli(args) {
-    const flags = {};
-    for (let index = 0; index < args.length; index += 1) {
-        const token = args[index];
-        if (!token.startsWith('--')) {
-            if (flags.stack != null) {
-                throw new Error(`Unknown flag: ${token}`);
-            }
-            flags.stack = token;
-            continue;
-        }
-        if (token === '--toolchain') {
-            const value = args[index + 1];
-            if (!value || value.startsWith('--')) {
-                throw new Error('Missing value for --toolchain');
-            }
-            flags.toolchain = value;
-            index += 1;
-            continue;
-        }
-        throw new Error(`Unknown flag: ${token}`);
-    }
-    if (!flags.stack) {
-        throw new Error(`Missing stack. Choose one of: ${STACK_IDS.join(', ')}`);
-    }
-    return flags;
-}
-function resolveMode(flags) {
-    if (!STACK_IDS.includes(flags.stack)) {
-        throw new Error(`Unknown stack: ${flags.stack}. Choose one of: ${STACK_IDS.join(', ')}`);
-    }
-    return flags.stack;
-}
-function deriveProjectName(cwd) {
-    const base = path.basename(cwd);
-    const sanitized = base
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9_-]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-    return sanitized || 'anhedral-app';
-}
-function deriveDisplayName(cwd) {
-    const base = path.basename(cwd).trim();
-    return base || 'Anhedral App';
-}
-function buildOptions(flags) {
-    const cwd = process.cwd();
-    const mode = resolveMode(flags);
-    const projectName = deriveProjectName(cwd);
-    const displayName = deriveDisplayName(cwd);
-    if (flags.toolchain != null && !TOOLCHAIN_CHANNELS.includes(flags.toolchain)) {
-        throw new Error(`--toolchain must be one of: ${TOOLCHAIN_CHANNELS.join(', ')}`);
-    }
-    switch (mode) {
-        case 'next':
-            return {
-                mode,
-                projectName,
-                displayName,
-                auth: 'clerk',
-                payments: 'stripe',
-                db: 'neon',
-                orm: 'drizzle',
-                storage: 'r2',
-                api: null,
-                monorepo: false,
-                toolchainChannel: resolveToolchainChannel(flags.toolchain ?? env.ANHEDRAL_TOOLCHAIN),
-            };
-        case 'next-fullstack':
-            return {
-                mode,
-                projectName,
-                displayName,
-                auth: 'clerk',
-                payments: 'stripe',
-                db: 'neon',
-                orm: 'drizzle',
-                storage: 'r2',
-                api: 'fastify',
-                monorepo: true,
-                toolchainChannel: resolveToolchainChannel(flags.toolchain ?? env.ANHEDRAL_TOOLCHAIN),
-            };
-        case 'expo-fullstack':
-            return {
-                mode,
-                projectName,
-                displayName,
-                auth: 'clerk',
-                payments: 'revenuecat',
-                db: 'neon',
-                orm: 'drizzle',
-                storage: 'r2',
-                api: 'fastify',
-                monorepo: true,
-                toolchainChannel: resolveToolchainChannel(flags.toolchain ?? env.ANHEDRAL_TOOLCHAIN),
-            };
-        case 'backend':
-            return {
-                mode,
-                projectName,
-                displayName,
-                auth: 'betterauth',
-                payments: 'none',
-                db: 'neon',
-                orm: 'drizzle',
-                storage: 'r2',
-                api: 'fastify',
-                monorepo: false,
-                toolchainChannel: resolveToolchainChannel(flags.toolchain ?? env.ANHEDRAL_TOOLCHAIN),
-            };
-    }
-}
+import { argv, exit } from 'node:process';
+import { buildOptions, parseCli, USAGE } from './cli.js';
+import { scaffoldProject } from './scaffold.js';
 async function main() {
     const args = argv.slice(2);
     const command = args[0];
@@ -144,8 +14,12 @@ async function main() {
         console.log(USAGE);
         exit(1);
     }
+    const rawArgs = args.slice(1);
+    if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+        console.log(USAGE);
+        exit(0);
+    }
     try {
-        const rawArgs = args.slice(1);
         const options = buildOptions(parseCli(rawArgs));
         await scaffoldProject(options);
     }

package/dist/print.d.ts

@@ -0,0 +1,8 @@
+export declare const anhedralPrint: {
+    banner(message: string): void;
+    section(message: string): void;
+    step(message: string): void;
+    done(message: string): void;
+    info(message: string): void;
+    fail(message: string): void;
+};

package/dist/print.js

@@ -0,0 +1,33 @@
+import { stdout } from 'node:process';
+const USE_COLOR = Boolean(stdout.isTTY) && process.env.NO_COLOR == null;
+function paint(code, message) {
+    if (!USE_COLOR)
+        return message;
+    return `\x1b[${code}m${message}\x1b[0m`;
+}
+const dim = (value) => paint('2', value);
+const bold = (value) => paint('1', value);
+const cyan = (value) => paint('36', value);
+const green = (value) => paint('32', value);
+const red = (value) => paint('31', value);
+const magenta = (value) => paint('35', value);
+export const anhedralPrint = {
+    banner(message) {
+        console.log(`${bold(magenta('>'))} ${bold(message)}\n`);
+    },
+    section(message) {
+        console.log(`\n${cyan('==')} ${bold(message)}`);
+    },
+    step(message) {
+        console.log(`  ${cyan('>')} ${message}`);
+    },
+    done(message) {
+        console.log(`  ${green('ok')} ${message}`);
+    },
+    info(message) {
+        console.log(`  ${dim(message)}`);
+    },
+    fail(message) {
+        console.log(`  ${red('x')} ${message}`);
+    },
+};

package/dist/scaffold.d.ts

@@ -1,10 +1,10 @@
 import { type ToolchainChannel } from './toolchain.js';
-export declare const STACK_IDS: readonly ["next", "next-fullstack", "expo-fullstack", "backend"];
-export type InitMode = (typeof STACK_IDS)[number];
+export type FrontendMode = 'expo' | 'next';
 export type AuthMode = 'clerk' | 'betterauth';
 export type PaymentsMode = 'none' | 'stripe' | 'revenuecat';
 export interface InitOptions {
-    mode: InitMode;
+    frontend: FrontendMode;
+    extension: boolean;
     projectName: string;
     displayName: string;
     auth: AuthMode;