create-authhero 0.16.0 → 0.18.0

package/dist/cloudflare-simple/README.md

@@ -7,90 +7,117 @@ A single-tenant AuthHero authentication server using Cloudflare Workers and D1.
 - [Cloudflare Account](https://dash.cloudflare.com/sign-up)
 - [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/)
 
+## 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. Create a D1 database (if not using local mode):
+2. Run database migrations (uses local SQLite-backed D1):
 
    ```bash
-   wrangler d1 create authhero-db
+   npm run migrate
    ```
 
-   Update `wrangler.toml` with your database ID from the output above.
-
-3. Run database migrations:
-
-   **For local development:**
+3. Seed the database with an admin user:
 
    ```bash
-   npm run migrate
+   ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=yourpassword npm run seed
    ```
 
-   **For production:**
+4. Start the development server:
 
    ```bash
-   npm run db:migrate:remote
+   npm run dev
    ```
 
-4. Seed the database with an admin user:
+The server will be available at `https://localhost:3000`.
 
-   **For local development:**
+### Remote Development (Your Cloudflare Account)
+
+1. Create a D1 database:
 
    ```bash
-   ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=yourpassword npm run seed:local
+   npx wrangler d1 create authhero-db
    ```
 
-   **For production:**
+2. Copy the `database_id` from the output and update `wrangler.local.toml`:
 
-   ```bash
-   ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=yourpassword npm run seed:remote
+   ```toml
+   [[d1_databases]]
+   binding = "AUTH_DB"
+   database_name = "authhero-db"
+   database_id = "paste-your-database-id-here"
+   migrations_dir = "node_modules/@authhero/drizzle/drizzle"
    ```
 
-5. Start the development server:
-
-   **For local mode (local D1 database):**
+3. Run remote migrations:
 
    ```bash
-   npm run dev:local
+   npm run db:migrate:remote
    ```
 
-   **For remote mode (production D1 database):**
+4. Seed the remote database:
+
+   ```bash
+   ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=yourpassword npm run seed:remote
+   ```
 
+5. Start with remote D1:
    ```bash
    npm run dev:remote
    ```
 
 ## Available Scripts
 
-- `npm run dev:local` - Start development server with local D1 database
-- `npm run dev:remote` - Start development server with remote D1 database
+- `npm run dev` - Start development server with local D1 database
+- `npm run dev:remote` - Start with remote D1 database
 - `npm run deploy` - Deploy to Cloudflare Workers
 - `npm run migrate` - Run migrations on local database
 - `npm run db:migrate:local` - Run migrations on local database (alias)
 - `npm run db:migrate:remote` - Run migrations on remote database
-- `npm run seed:local` - Seed local database with admin user
+- `npm run seed` - Seed local database with admin user
 - `npm run seed:remote` - Seed remote database with admin user
+- `npm run setup` - Create wrangler.local.toml and .dev.vars from templates
 
 ## Deployment
 
-1. Deploy to Cloudflare:
+1. Ensure `wrangler.local.toml` has your production `database_id`.
+
+2. Deploy to Cloudflare:
 
    ```bash
    npm run deploy
    ```
 
-2. Run production migrations:
+3. Run production migrations:
 
    ```bash
    npm run db:migrate:remote
    ```
 
-3. Seed the production database:
+4. Seed the production database:
    ```bash
    ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=yourpassword npm run seed:remote
    ```
@@ -103,12 +130,34 @@ A single-tenant AuthHero authentication server using Cloudflare Workers and D1.
 │   ├── app.ts            # AuthHero app configuration
 │   ├── seed.ts           # Database seeding worker
 │   └── types.ts          # TypeScript type definitions
+├── dist/
+│   └── assets/           # Copied static assets (CSS, JS, Widget)
+├── copy-assets.js        # Build script to copy assets from authhero package
 ├── drizzle.config.ts     # Drizzle configuration (reference only)
 ├── seed-helper.js        # Helper script for automated seeding
 ├── wrangler.toml         # Cloudflare Worker configuration
 └── package.json
 ```
 
+## 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
+
 ## Database Migrations
 
 Database migrations are pre-generated and shipped with the `@authhero/drizzle` package. The schema is managed by AuthHero to ensure compatibility with future updates.
@@ -136,6 +185,83 @@ routes = [
 
 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-simple/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-simple/wrangler.toml

@@ -1,23 +1,57 @@
+# ════════════════════════════════════════════════════════════════════════════
+# AuthHero 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-server"
 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
 # ════════════════════════════════════════════════════════════════════════════