create-authhero 0.16.0 → 0.18.0

package/README.md

@@ -18,9 +18,10 @@ The CLI will guide you through:
 
 1. **Project name** - Name of your project directory
 2. **Setup type** - Choose between Local, Cloudflare Simple, or Cloudflare Multi-Tenant
-3. **Admin credentials** - Email and password for the initial admin user
-4. **Install dependencies** - Optionally install packages with your preferred package manager
-5. **Start server** - Optionally run migrations, seed the database, and start the dev server
+3. **GitHub CI** - (Cloudflare only) Optionally include GitHub Actions workflows with semantic versioning
+4. **Admin credentials** - Email and password for the initial admin user
+5. **Install dependencies** - Optionally install packages with your preferred package manager
+6. **Start server** - Optionally run migrations, seed the database, and start the dev server
 
 ## Setup Types
 
@@ -68,27 +69,38 @@ npm run dev
 ```
 my-auth-project/
 ├── src/
-│   ├── index.ts     # Worker entry point
-│   ├── app.ts       # AuthHero configuration
-│   └── types.ts     # TypeScript types
-├── wrangler.toml    # Cloudflare configuration
-├── seed.sql         # Database seeding (generated)
+│   ├── index.ts          # Worker entry point
+│   ├── app.ts            # AuthHero configuration
+│   └── types.ts          # TypeScript types
+├── wrangler.toml         # Base Cloudflare config (safe for git)
+├── wrangler.local.toml   # Your private IDs (gitignored)
+├── .dev.vars             # Local secrets (gitignored)
+├── .dev.vars.example     # Template for .dev.vars
+├── seed.sql              # Database seeding (generated)
 ├── package.json
 └── tsconfig.json
 ```
 
-**Quick Start:**
+**Quick Start (Local Development):**
 
 ```sh
 cd my-auth-project
 npm install
-wrangler d1 create authhero-db
-# Update wrangler.toml with database_id
-npm run db:migrate
-npm run seed
+npm run migrate
+ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=yourpassword npm run seed
 npm run dev
 ```
 
+**Remote Development (Your Cloudflare Account):**
+
+```sh
+# Create a D1 database
+npx wrangler d1 create authhero-db
+# Copy the database_id to wrangler.local.toml
+npm run db:migrate:remote
+npm run dev:remote
+```
+
 ### 3. Cloudflare Multi-Tenant (Production)
 
 **Best for:** SaaS platforms, agencies, enterprise deployments
@@ -103,13 +115,15 @@ npm run dev
 ```
 my-auth-project/
 ├── src/
-│   ├── index.ts           # Worker entry point
-│   ├── app.ts             # AuthHero configuration
-│   ├── types.ts           # TypeScript types
+│   ├── index.ts            # Worker entry point
+│   ├── app.ts              # AuthHero configuration
+│   ├── types.ts            # TypeScript types
 │   └── database-factory.ts # Multi-tenant DB factory
-├── wrangler.toml          # Cloudflare configuration
-├── .dev.vars.example      # Environment variables template
-├── seed.sql               # Database seeding (generated)
+├── wrangler.toml           # Base Cloudflare config (safe for git)
+├── wrangler.local.toml     # Your private IDs (gitignored)
+├── .dev.vars               # Local secrets (gitignored)
+├── .dev.vars.example       # Environment variables template
+├── seed.sql                # Database seeding (generated)
 ├── package.json
 └── tsconfig.json
 ```
@@ -138,20 +152,51 @@ my-auth-project/
    └─────────────┘         └─────────────┘         └─────────────┘
 ```
 
-**Quick Start:**
+**Quick Start (Local Development):**
 
 ```sh
 cd my-auth-project
 npm install
-wrangler d1 create authhero-main-db
-# Update wrangler.toml with database_id
-cp .dev.vars.example .dev.vars
-# Add your Cloudflare credentials to .dev.vars
-npm run db:migrate
-npm run seed
+npm run migrate
+ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=yourpassword npm run seed
 npm run dev
 ```
 
+**Remote Development (Your Cloudflare Account):**
+
+```sh
+# Create a D1 database
+npx wrangler d1 create authhero-db
+# Copy the database_id to wrangler.local.toml
+# Optionally add CLOUDFLARE_ACCOUNT_ID to .dev.vars
+npm run db:migrate:remote
+npm run dev:remote
+```
+
+## Security & Privacy
+
+Cloudflare projects are designed to be **open-source friendly**:
+
+| File                  | Purpose                            | In Git? |
+| --------------------- | ---------------------------------- | ------- |
+| `wrangler.toml`       | Base config (safe for public repo) | ✅ Yes  |
+| `wrangler.local.toml` | Your private IDs (database_id)     | ❌ No   |
+| `.dev.vars`           | Local secrets (API tokens, etc.)   | ❌ No   |
+| `.dev.vars.example`   | Template for .dev.vars             | ✅ Yes  |
+
+The CLI automatically creates `wrangler.local.toml` and `.dev.vars` from the templates when you create a project. Simply update them with your Cloudflare IDs.
+
+### GitHub Actions / CI Deployment
+
+For automated deployments, set these GitHub Secrets:
+
+| Secret                  | Description                                              |
+| ----------------------- | -------------------------------------------------------- |
+| `CLOUDFLARE_API_TOKEN`  | API token with Workers permissions                       |
+| `CLOUDFLARE_ACCOUNT_ID` | Your Cloudflare account ID (optional, for some features) |
+
+The wrangler GitHub Action will automatically use these secrets. No need to store IDs in your repo!
+
 ## Example
 
 ```sh
@@ -175,6 +220,40 @@ You'll be prompted to:
 | Complexity   | Low          | Medium            | High                    |
 | Best For     | Development  | Simple Production | Enterprise/SaaS         |
 
+## GitHub CI with Semantic Versioning
+
+For Cloudflare setups, you can optionally include GitHub Actions workflows that provide:
+
+- **Unit Tests**: Runs on all pushes to any branch
+- **Deploy to Dev**: Automatically deploys to dev environment on push to `main`, with semantic-release for version management
+- **Deploy to Production**: Deploys to production when a GitHub release is published
+
+### CI/CD Flow
+
+```
+All PRs/Pushes → Unit Tests (type-check + tests)
+Push to main  → Semantic Release + Deploy to Dev
+GitHub Release → Deploy to Production
+```
+
+### Required GitHub Secrets
+
+| Secret                      | Description                              |
+| --------------------------- | ---------------------------------------- |
+| `CLOUDFLARE_API_TOKEN`      | API token for dev deployments            |
+| `CLOUDFLARE_ACCOUNT_ID`     | Account ID (optional, for some features) |
+| `PROD_CLOUDFLARE_API_TOKEN` | API token for production deployments     |
+
+> **Note:** You do NOT need to store `database_id` or `zone_id` in your repo or secrets. Wrangler resolves these automatically when deploying with the correct API token.
+
+### Commit Message Conventions
+
+Use conventional commits for automatic versioning:
+
+- `fix:` → Patch release (1.0.0 → 1.0.1)
+- `feat:` → Minor release (1.0.0 → 1.1.0)
+- `BREAKING CHANGE:` → Major release (1.0.0 → 2.0.0)
+
 ## Documentation
 
 For more information, visit [https://authhero.net/docs](https://authhero.net/docs)

package/dist/cloudflare-multitenant/README.md

@@ -4,6 +4,7 @@ A production-grade multi-tenant AuthHero authentication server using Cloudflare
 
 - Multi-tenant support with tenant isolation at the data level
 - Multiple tenants in a single D1 database
+- Static assets (widget, CSS, JS) served via Cloudflare Workers Assets
 - Easy setup similar to single-tenant
 
 ## Architecture
@@ -18,6 +19,11 @@ A production-grade multi-tenant AuthHero authentication server using Cloudflare
                     │  │   - Tenant isolation via API    │   │
                     │  └─────────────────────────────────┘   │
                     │              │                          │
+                    │  ┌───────────┴────────────────────┐     │
+                    │  │      Static Assets             │     │
+                    │  │  /u/widget/* /u/css/* /u/js/*  │     │
+                    │  └────────────────────────────────┘     │
+                    │              │                          │
                     └──────────────┼──────────────────────────┘
                                    │
                                    ▼
@@ -28,15 +34,53 @@ A production-grade multi-tenant AuthHero authentication server using Cloudflare
                           └─────────────┘
 ```
 
+## Static Assets
+
+The authentication widget, CSS, and client-side JavaScript are served as static assets via Cloudflare Workers Assets.
+
+### How It Works
+
+1. **Source**: Assets are bundled with the `authhero` package in `node_modules/authhero/dist/assets`
+2. **Build Step**: The `copy-assets.js` script copies these files to `./dist/assets` before dev/deploy
+3. **Serving**: Wrangler serves files from `./dist/assets` (configured in `wrangler.toml`)
+4. **Automatic**: The copy happens automatically when you run `npm run dev` or `npm run deploy`
+
+> **Note**: Wrangler's Assets feature does not support serving files directly from `node_modules`, which is why the copy step is necessary.
+
+Assets are served at:
+
+- `/u/widget/*` - AuthHero login widget (Stencil web component)
+- `/u/css/*` - Tailwind CSS for universal login pages
+- `/u/js/*` - Client-side JavaScript bundle
+
+## Security & Privacy
+
+This project is designed to be **open-source friendly**. Sensitive Cloudflare IDs are kept out of version control:
+
+| File                  | Purpose                            | In Git? |
+| --------------------- | ---------------------------------- | ------- |
+| `wrangler.toml`       | Base config (safe for public repo) | ✅ Yes  |
+| `wrangler.local.toml` | Your private IDs (database_id)     | ❌ No   |
+| `.dev.vars`           | Local secrets (API tokens, etc.)   | ❌ No   |
+| `.dev.vars.example`   | Template for .dev.vars             | ✅ Yes  |
+
+**For GitHub Actions / CI:**
+
+- Set `CLOUDFLARE_API_TOKEN` as a GitHub Secret
+- Set `CLOUDFLARE_ACCOUNT_ID` as a GitHub Secret (if needed)
+- The wrangler action will use these automatically
+
 ## Getting Started
 
+### Local Development (Quick Start)
+
 1. Install dependencies:
 
    ```bash
    npm install
    ```
 
-2. Run local database migrations:
+2. Run database migrations (uses local SQLite-backed D1):
 
    ```bash
    npm run migrate
@@ -55,29 +99,46 @@ A production-grade multi-tenant AuthHero authentication server using Cloudflare
 
 The server will be available at `https://localhost:3000`.
 
-## Production Deployment
+### Remote Development (Your Cloudflare Account)
 
 1. Create a D1 database:
 
    ```bash
-   wrangler d1 create authhero-db
+   npx wrangler d1 create authhero-db
    ```
 
-2. Update `wrangler.toml` with your database ID.
+2. Copy the `database_id` from the output and update `wrangler.local.toml`:
+
+   ```toml
+   [[d1_databases]]
+   binding = "AUTH_DB"
+   database_name = "authhero-db"
+   database_id = "paste-your-database-id-here"
+   migrations_dir = "node_modules/@authhero/drizzle/drizzle"
+   ```
 
-3. Run migrations on production:
+3. Run remote migrations:
 
    ```bash
    npm run db:migrate:remote
    ```
 
-4. Seed the production database:
+4. Seed the remote database:
 
    ```bash
    ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=yourpassword npm run seed:remote
    ```
 
-5. Deploy:
+5. Start with remote D1:
+   ```bash
+   npm run dev:remote
+   ```
+
+## Production Deployment
+
+1. Ensure `wrangler.local.toml` has your production `database_id`.
+
+2. Deploy:
    ```bash
    npm run deploy
    ```
@@ -154,6 +215,83 @@ curl https://your-worker.workers.dev/management/tenants \
 
 For more information, visit [https://authhero.net/docs](https://authhero.net/docs).
 
+## CI/CD with GitHub Actions
+
+If you selected GitHub CI during setup, your project includes automated workflows for continuous integration and deployment.
+
+### Workflow Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           GitHub Actions                                 │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐    │
+│  │  Any Push    │     │   Push to main   │     │ GitHub Release   │    │
+│  │              │     │                  │     │   (released)     │    │
+│  └──────┬───────┘     └────────┬─────────┘     └────────┬─────────┘    │
+│         │                      │                        │               │
+│         ▼                      ▼                        ▼               │
+│  ┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐    │
+│  │  Unit Tests  │     │ Semantic Release │     │    Deploy to     │    │
+│  │  Type Check  │     │  + Deploy Dev    │     │   Production     │    │
+│  └──────────────┘     └──────────────────┘     └──────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Workflows
+
+1. **Unit Tests** (`.github/workflows/unit-tests.yml`)
+   - **Trigger**: All pushes to any branch
+   - **Actions**: Runs type checking and tests
+
+2. **Deploy to Dev** (`.github/workflows/deploy-dev.yml`)
+   - **Trigger**: Push to `main` branch
+   - **Actions**:
+     - Runs semantic-release to create version tags
+     - Deploys to Cloudflare Workers (dev environment)
+
+3. **Deploy to Production** (`.github/workflows/release.yml`)
+   - **Trigger**: GitHub Release (when "released")
+   - **Actions**: Deploys to Cloudflare Workers (production environment)
+
+### Required Secrets
+
+Configure these secrets in your GitHub repository settings:
+
+| Secret                      | Description                                     |
+| --------------------------- | ----------------------------------------------- |
+| `CLOUDFLARE_API_TOKEN`      | Cloudflare API token for dev deployments        |
+| `PROD_CLOUDFLARE_API_TOKEN` | Cloudflare API token for production deployments |
+
+### Semantic Versioning
+
+Commits to `main` are analyzed to determine version bumps:
+
+- `fix:` - Patch release (1.0.0 → 1.0.1)
+- `feat:` - Minor release (1.0.0 → 1.1.0)
+- `BREAKING CHANGE:` - Major release (1.0.0 → 2.0.0)
+
+### Production Deployment
+
+To deploy to production:
+
+1. Go to GitHub → Releases → "Draft a new release"
+2. Create a new tag (e.g., `v1.0.0`)
+3. Click "Publish release"
+4. The `release.yml` workflow will deploy to production
+
+### Wrangler Configuration
+
+For production deployments, add an environment to `wrangler.toml`:
+
+```toml
+[env.production]
+name = "your-worker-production"
+# Add production-specific settings here
+```
+
 ## Optional Features
 
 ### Analytics Engine (Centralized Logging)

package/dist/cloudflare-multitenant/copy-assets.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+/**
+ * Copy AuthHero assets to dist directory
+ *
+ * This script copies static assets from the authhero package to the dist directory
+ * so they can be served by Wrangler's Assets feature. Wrangler does not support
+ * serving files directly from node_modules.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const sourceDir = path.join(
+  __dirname,
+  "node_modules",
+  "authhero",
+  "dist",
+  "assets",
+);
+const targetDir = path.join(__dirname, "dist", "assets");
+
+/**
+ * Recursively copy directory contents
+ */
+function copyDirectory(src, dest) {
+  // Create destination directory if it doesn't exist
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  // Read source directory
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+try {
+  console.log("📦 Copying AuthHero assets...");
+
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`❌ Source directory not found: ${sourceDir}`);
+    console.error("Make sure the authhero package is installed.");
+    process.exit(1);
+  }
+
+  copyDirectory(sourceDir, targetDir);
+
+  console.log(`✅ Assets copied to ${targetDir}`);
+} catch (error) {
+  console.error("❌ Error copying assets:", error.message);
+  process.exit(1);
+}

package/dist/cloudflare-multitenant/wrangler.toml

@@ -1,23 +1,57 @@
+# ════════════════════════════════════════════════════════════════════════════
+# AuthHero Multi-Tenant Cloudflare Worker Configuration
+# ════════════════════════════════════════════════════════════════════════════
+# This file is safe for version control. Sensitive IDs should go in:
+# - wrangler.local.toml (local development - gitignored)
+# - GitHub Secrets / Cloudflare Dashboard (production)
+#
+# For local development with your own Cloudflare resources:
+#   cp wrangler.toml wrangler.local.toml
+#   # Add your database_id to wrangler.local.toml
+#   npm run dev  # Uses wrangler.local.toml automatically
+# ════════════════════════════════════════════════════════════════════════════
+
 name = "authhero-multitenant"
 main = "src/index.ts"
 compatibility_date = "2024-11-20"
 
-# D1 Database binding
-# Run: wrangler d1 create authhero-db
-# Then uncomment and update the database_id below:
-# [[d1_databases]]
-# binding = "AUTH_DB"
-# database_name = "authhero-db"
-# database_id = "<YOUR_DATABASE_ID>"
-# migrations_dir = "node_modules/@authhero/drizzle/drizzle"
+# ════════════════════════════════════════════════════════════════════════════
+# Static Assets (CSS, JS, Widget)
+# ════════════════════════════════════════════════════════════════════════════
+# Serve static assets from the authhero package.
+# This includes the widget, CSS, and client-side JavaScript.
+# Assets are copied from node_modules/authhero/dist/assets to dist/assets
+# during the build process (see copy-assets.js).
+# Assets are served at their path: /u/widget/*, /u/css/*, /u/js/*
+[assets]
+directory = "./dist/assets"
 
-# For local development, you can use a local D1 database:
+# ════════════════════════════════════════════════════════════════════════════
+# D1 Database binding
+# ════════════════════════════════════════════════════════════════════════════
+# This configuration uses a local D1 database by default.
+# For remote development/production, copy to wrangler.local.toml and update.
+#
+# Setup:
+# 1. Create database: npx wrangler d1 create authhero-db
+# 2. Copy to local config: cp wrangler.toml wrangler.local.toml
+# 3. Update database_id in wrangler.local.toml with the ID from step 1
+#
 [[d1_databases]]
 binding = "AUTH_DB"
 database_name = "authhero-db"
-database_id = "local"
+database_id = "local"  # Use "local" for local dev, or your actual ID in wrangler.local.toml
 migrations_dir = "node_modules/@authhero/drizzle/drizzle"
 
+# ════════════════════════════════════════════════════════════════════════════
+# OPTIONAL: Custom Domain
+# ════════════════════════════════════════════════════════════════════════════
+# To route your worker to a custom domain, use zone_name (not zone_id):
+#
+# [[routes]]
+# pattern = "auth.yourdomain.com/*"
+# zone_name = "yourdomain.com"
+
 # ════════════════════════════════════════════════════════════════════════════
 # OPTIONAL: Analytics Engine for centralized logging
 # ════════════════════════════════════════════════════════════════════════════