@etus/bhono-app 0.1.1

package/templates/base/.claude/skills/wrangler/resources/system-enviroments-variables.md

@@ -0,0 +1,120 @@
+---
+title: System environment variables · Cloudflare Workers docs
+description: Local environment variables that can change Wrangler's behavior.
+lastUpdated: 2025-11-28T09:56:31.000Z
+chatbotDeprioritize: false
+source_url:
+  html: https://developers.cloudflare.com/workers/wrangler/system-environment-variables/
+  md: https://developers.cloudflare.com/workers/wrangler/system-environment-variables/index.md
+---
+
+System environment variables are local environment variables that can change Wrangler's behavior. There are three ways to set system environment variables:
+
+1. Create an `.env` file in your project directory. Set the values of your environment variables in your [`.env`](https://developers.cloudflare.com/workers/wrangler/system-environment-variables/#example-env-file) file. This is the recommended way to set these variables, as it persists the values between Wrangler sessions.
+
+2. Inline the values in your Wrangler command. For example, `WRANGLER_LOG="debug" npx wrangler deploy` will set the value of `WRANGLER_LOG` to `"debug"` for this execution of the command.
+
+3. Set the values in your shell environment. For example, if you are using Z shell, adding `export CLOUDFLARE_API_TOKEN=...` to your `~/.zshrc` file will set this token as part of your shell configuration.
+
+Note
+
+To set different system environment variables for each environment, create files named `.env.<environment-name>`. When you use `wrangler <command> --env <environment-name>`, the corresponding environment-specific file will be loaded instead of the `.env` file, so the two files are not merged.
+
+Note
+
+During local development, the values in `.env` files are also loaded into the `env` object in your Worker, so you can access them in your Worker code.
+
+For example, if you set `API_HOST="localhost:3000"` in your `.env` file, you can access it in your Worker like this:
+
+```js
+const apiHost = env.API_HOST;
+```
+
+See the [Environment variables and secrets](https://developers.cloudflare.com/workers/development-testing/environment-variables/) page for more information on how to use `.env` files in local development.
+
+## Supported environment variables
+
+Wrangler supports the following environment variables:
+
+- `CLOUDFLARE_ACCOUNT_ID` string optional
+
+  - The [account ID](https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/) for the Workers related account.
+
+- `CLOUDFLARE_API_TOKEN` string optional
+
+  - The [API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) for your Cloudflare account, can be used for authentication for situations like CI/CD, and other automation.
+
+- `CLOUDFLARE_API_KEY` string optional
+
+  - The API key for your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_EMAIL=`.
+
+- `CLOUDFLARE_EMAIL` string optional
+
+  - The email address associated with your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_API_KEY=`.
+
+- `CLOUDFLARE_ENV` string optional
+
+  - The [environment](https://developers.cloudflare.com/workers/wrangler/environments/) to use for Wrangler commands. This allows you to select an environment without using the `--env` flag. For example, `CLOUDFLARE_ENV=production wrangler deploy` will deploy to the `production` environment. The `--env` command line argument takes precedence over this environment variable.
+
+- `WRANGLER_SEND_METRICS` string optional
+
+  - Options for this are `true` and `false`. Defaults to `true`. Controls whether Wrangler can send anonymous usage data to Cloudflare for this project. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md).
+
+- `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>`string optional
+
+  - The [local connection string](https://developers.cloudflare.com/hyperdrive/configuration/local-development/) for your database to use in local development with [Hyperdrive](https://developers.cloudflare.com/hyperdrive/). For example, if the binding for your Hyperdrive is named `PROD_DB`, this would be `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_PROD_DB="postgres://user:password@127.0.0.1:5432/testdb"`. Each Hyperdrive is uniquely distinguished by the binding name.
+
+- `CLOUDFLARE_API_BASE_URL` string optional
+
+  - The default value is `"https://api.cloudflare.com/client/v4"`.
+
+- `WRANGLER_LOG` string optional
+
+  - Options for Logging levels are `"none"`, `"error"`, `"warn"`, `"info"`, `"log"` and `"debug"`. Levels are case-insensitive and default to `"log"`. If an invalid level is specified, Wrangler will fallback to the default. Logs can include requests to Cloudflare's API, any usage data being collected, and more verbose error logs.
+
+- `WRANGLER_LOG_PATH` string optional
+
+  - A file or directory path where Wrangler will write debug logs. If the path ends in `.log`, Wrangler will consider this the path to a file where all logs will be written. Otherwise, Wrangler will treat the path as a directory where it will write one or more log files using a timestamp for the filenames.
+
+- `FORCE_COLOR` string optional
+
+  - By setting this to `0`, you can disable Wrangler's colorised output, which makes it easier to read with some terminal setups. For example, `FORCE_COLOR=0`.
+
+* `WRANGLER_HTTPS_KEY_PATH` string optional
+
+  - Path to a custom HTTPS certificate key when running `wrangler dev`, to be used with `WRANGLER_HTTPS_CERT_PATH`.
+
+* `WRANGLER_HTTPS_CERT_PATH` string optional
+
+  - Path to a custom HTTPS certificate when running `wrangler dev`, to be used with `WRANGLER_HTTPS_KEY_PATH`.
+
+- `DOCKER_HOST` string optional
+  - Used for local development of [Containers](https://developers.cloudflare.com/containers/local-dev). Wrangler will attempt to automatically find the correct socket to use to communicate with your container engine. If that does not work (usually surfacing as an `internal error` when attempting to connect to your Container), you can try setting the socket path using this environment variable.
+
+* `WRANGLER_R2_SQL_AUTH_TOKEN` string optional
+  - API token used for executing queries with [R2 SQL](https://developers.cloudflare.com/r2-sql).
+
+## Example `.env` file
+
+The following is an example `.env` file:
+
+```bash
+CLOUDFLARE_ACCOUNT_ID=<YOUR_ACCOUNT_ID_VALUE>
+CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN_VALUE>
+CLOUDFLARE_EMAIL=<YOUR_EMAIL>
+WRANGLER_SEND_METRICS=true
+CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
+WRANGLER_LOG=debug
+WRANGLER_LOG_PATH=../Desktop/my-logs/my-log-file.log
+WRANGLER_R2_SQL_AUTH_TOKEN=<YOUR_R2_API_TOKEN_VALUE>
+```
+
+## Deprecated global variables
+
+The following variables are deprecated. Use the new variables listed above to prevent any issues or unwanted messaging.
+
+- `CF_ACCOUNT_ID`
+- `CF_API_TOKEN`
+- `CF_API_KEY`
+- `CF_EMAIL`
+- `CF_API_BASE_URL`

package/templates/base/.dev.vars.example

@@ -0,0 +1,15 @@
+# JWT Configuration
+JWT_SECRET=your-jwt-secret-key-min-32-chars-here
+JWT_EXPIRY_MINUTES=15
+
+# Google OAuth
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
+
+# Refresh Token
+REFRESH_TOKEN_EXPIRY_DAYS=30
+
+# SendGrid
+SENDGRID_API_KEY=your-sendgrid-api-key
+SENDGRID_FROM_EMAIL=noreply@example.com

package/templates/base/.env.example

@@ -0,0 +1,29 @@
+# Server
+PORT=3000
+NODE_ENV=development
+
+# Database
+DATABASE_URL=db.sqlite
+
+# JWT Secret (min 32 characters)
+JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars
+JWT_EXPIRY_MINUTES=15
+
+# Google OAuth
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
+
+# Refresh Token
+REFRESH_TOKEN_EXPIRY_DAYS=30
+
+# SendGrid (for invitations)
+SENDGRID_API_KEY=your-sendgrid-api-key
+SENDGRID_FROM_EMAIL=noreply@yourdomain.com
+
+# App URL
+APP_URL=http://localhost:3000
+
+# Optional
+CORS_ORIGINS=*
+LOG_LEVEL=info

package/templates/base/.github/workflows/test.yml

@@ -0,0 +1,127 @@
+name: Test Suite
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+env:
+  CI: true
+  NODE_VERSION: '20'
+
+jobs:
+  # Unit and Integration Tests (Vitest) with Coverage
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run backend tests with coverage
+        run: npm run test:coverage
+
+      - name: Run frontend tests with coverage
+        run: npm run test:coverage:client
+
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v4
+        if: always()
+        with:
+          files: ./coverage/server/lcov.info,./coverage/client/lcov.info
+          flags: unittests
+          fail_ci_if_error: false
+
+  # E2E Tests (Playwright)
+  e2e-tests:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install chromium --with-deps
+
+      - name: Run E2E tests
+        run: npm run test:e2e -- --project=chromium-unauth
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 7
+
+  # Type checking
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run type check
+        run: npx tsc --noEmit
+
+  # Linting
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint

package/templates/base/.nycrc.json

@@ -0,0 +1,16 @@
+{
+  "check-coverage": true,
+  "lines": 90,
+  "statements": 90,
+  "branches": 84,
+  "functions": 85,
+  "include": ["src/client/**/*.{ts,tsx}"],
+  "exclude": [
+    "**/*.test.*",
+    "**/__tests__/**",
+    "**/routeTree.gen.ts",
+    "**/main.tsx"
+  ],
+  "report-dir": ".test-output/coverage/e2e",
+  "temp-dir": ".test-output/coverage/e2e/.nyc_output"
+}

package/templates/base/CLAUDE.md

@@ -0,0 +1,218 @@
+# Hono Boilerplate
+
+Production-ready multi-tenant SaaS boilerplate with Hono.js backend and React frontend, deployed on Cloudflare Workers.
+
+## Tech Stack
+
+- **Runtime**: Cloudflare Workers (D1 database, KV sessions, R2 storage)
+- **Backend**: Hono.js 4.6 + Drizzle ORM + Zod validation
+- **Frontend**: React 19 + TanStack Router + Tailwind CSS 4.0
+- **Testing**: Vitest (unit/integration) + Playwright (E2E)
+- **Auth**: Google OAuth 2.0 with session-based cookies
+
+## Project Structure
+
+```
+├── config/                     # All configuration files
+│   ├── vite.config.ts          # Vite build config
+│   ├── vitest.config.ts        # Backend unit tests
+│   ├── vitest.frontend.config.ts
+│   ├── vitest.browser.config.ts
+│   ├── eslint.config.js
+│   └── wrangler.json           # Cloudflare Workers config
+│
+├── src/
+│   ├── server/                 # Backend (Hono.js)
+│   │   ├── routes/             # API endpoints (OpenAPI)
+│   │   │   ├── auth/           # OAuth login, logout, me, refresh
+│   │   │   ├── users/          # User CRUD
+│   │   │   ├── accounts/       # Multi-tenant workspaces
+│   │   │   ├── invitations/    # Team invite system
+│   │   │   ├── audits/         # Audit log queries
+│   │   │   ├── storage/        # R2 file operations
+│   │   │   └── health/         # Health check
+│   │   ├── services/           # Business logic layer
+│   │   ├── middleware/         # Auth, CORS, logging, rate-limit
+│   │   ├── db/schema/          # Drizzle table definitions
+│   │   ├── lib/                # Utilities (oauth, session, tokens)
+│   │   └── auth/               # Roles, permissions, guards
+│   │
+│   ├── client/                 # Frontend (React)
+│   │   ├── routes/             # TanStack file-based routing
+│   │   │   └── _authenticated/ # Protected pages
+│   │   ├── components/ui/      # Reusable UI components
+│   │   └── hooks/              # React hooks (use-auth)
+│   │
+│   └── shared/                 # Shared between client/server
+│       ├── schemas/            # Zod validation schemas
+│       └── types/              # TypeScript types
+│
+├── tests/                      # All tests (centralized)
+│   ├── unit/                   # Unit tests
+│   │   ├── server/             # Backend unit tests
+│   │   └── client/             # Frontend unit tests
+│   ├── integration/            # Integration tests
+│   ├── e2e/                    # Playwright E2E tests
+│   │   ├── journeys/           # User journey tests
+│   │   ├── crud/               # CRUD operation tests
+│   │   ├── api/                # API tests
+│   │   ├── a11y/               # Accessibility tests
+│   │   ├── visual/             # Visual regression
+│   │   └── mobile/             # Responsive tests
+│   ├── fixtures/               # Test fixtures
+│   ├── mocks/                  # Test mocks
+│   └── helpers/                # Test utilities
+│
+├── packages/                   # Monorepo packages
+│   └── bhono-app/        # Project scaffolding CLI
+│
+├── docs/                       # Documentation
+├── scripts/                    # Build/utility scripts
+└── migrations/                 # D1 SQL migrations
+```
+
+## Development
+
+### Commands
+
+```bash
+pnpm dev                    # Start dev server (Vite + Wrangler)
+pnpm build                  # Build for production
+pnpm deploy                 # Deploy to Cloudflare Workers
+
+# Database
+pnpm db:migrate:local       # Apply migrations locally
+pnpm db:migrate:remote      # Apply migrations to production
+pnpm db:seed                # Seed test data
+
+# Testing
+pnpm test                   # Backend unit tests (watch)
+pnpm test:run               # Backend tests (single run)
+pnpm test:client            # Frontend unit tests
+pnpm test:integration       # Integration tests
+pnpm test:e2e               # Playwright E2E tests
+pnpm test:e2e:ui            # Playwright interactive UI
+pnpm test:coverage          # Coverage report
+
+# Code quality
+pnpm lint                   # ESLint
+pnpm cf-typegen             # Generate Cloudflare types
+```
+
+### Workflow
+
+1. Make changes
+2. Run `pnpm test` for affected unit tests
+3. Run `pnpm lint` to check code style
+4. Run `pnpm test:e2e` for E2E validation
+5. Verify build with `pnpm build`
+
+### Path Aliases
+
+Defined in `tsconfig.json`:
+- `@/*` → `src/client/*`
+- `@shared/*` → `src/shared/*`
+- `@server/*` → `src/server/*`
+
+## Architecture
+
+### Multi-Tenancy
+
+Users belong to multiple Accounts (workspaces). Each user-account relationship has a Role: `ADMIN`, `EDITOR`, `VIEWER`. Permissions checked via guards in `src/server/auth/guards.ts`.
+
+### Authentication Flow
+
+1. `/auth/login` → Redirects to Google OAuth
+2. `/auth/callback` → Handles OAuth response, creates session in KV
+3. Session cookie (`__Host-sid`) sent with all requests
+4. `sessionAuth` middleware validates session on protected routes
+
+### Request Context
+
+Every request gets a `transactionId` for tracing across logs. See `src/server/middleware/request-context.ts`.
+
+### Audit Logging
+
+All state changes logged to `audit_logs` table. See `src/server/lib/audit.ts`.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/server/index.ts` | Hono app entry, middleware stack |
+| `src/server/routes/index.ts` | API router with OpenAPI/Swagger |
+| `src/server/db/schema/` | Database schema definitions |
+| `src/client/routes/__root.tsx` | React app root layout |
+| `src/client/routes/_authenticated.tsx` | Protected routes wrapper |
+| `config/wrangler.json` | Cloudflare Workers configuration |
+| `playwright.config.ts` | E2E test configuration |
+
+## API Documentation
+
+- **OpenAPI JSON**: `/api/doc`
+- **Swagger UI**: `/api/swagger`
+
+## Testing Strategy
+
+### Coverage Thresholds
+
+| Layer | Statements | Branches | Functions |
+|-------|------------|----------|-----------|
+| Server Unit | 90% | 84% | 85% |
+| Client Unit | 65% | 70% | 58% |
+| Integration | 90%+ | 85%+ | 90%+ |
+
+### E2E Test Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `@smoke` | Basic health checks |
+| `@critical` | Must-pass paths |
+| `@crud` | Create/Read/Update/Delete |
+| `@a11y` | Accessibility compliance |
+| `@visual` | Visual regression |
+| `@mobile` | Mobile responsive |
+
+### Test Authentication
+
+E2E tests use `/auth/test-login` endpoint (dev only) or OAuth session capture for production testing.
+
+## Environment Variables
+
+Required in `.env` (see `.env.example`):
+
+- `JWT_SECRET` - Session signing key (min 32 chars)
+- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` - OAuth credentials
+- `SENDGRID_API_KEY` - Email service for invitations
+- `APP_URL` - Application base URL
+
+## Cloudflare Bindings
+
+Defined in `config/wrangler.json`:
+
+- `DB` - D1 database
+- `SESSIONS` - KV namespace for sessions
+- `R2_BUCKET` - R2 storage for files
+
+## Common Patterns
+
+### Adding a New API Route
+
+1. Create route folder in `src/server/routes/{resource}/`
+2. Define schemas in `schemas.ts` (Zod + OpenAPI)
+3. Implement handlers in `handlers.ts`
+4. Register routes in `routes.ts`
+5. Export from `index.ts`
+6. Mount in `src/server/routes/index.ts`
+
+### Adding a Protected Page
+
+1. Create file in `src/client/routes/_authenticated/{page}.tsx`
+2. Use `createFileRoute` from TanStack Router
+3. Access auth via `useAuth()` hook
+
+### Database Changes
+
+1. Modify schema in `src/server/db/schema/`
+2. Run `pnpm drizzle-kit generate` to create migration
+3. Apply with `pnpm db:migrate:local`