@getjack/jack 0.1.19 → 0.1.22

package/templates/saas/AGENTS.md

@@ -0,0 +1,333 @@
+# Agent Context
+
+## Infrastructure
+
+This project uses **jack** for deployment. When Jack MCP is connected, prefer `mcp__jack__*` tools over CLI commands - they're cloud-aware and faster.
+
+**Do NOT use wrangler directly.** Jack manages config and may use cloud-hosted resources where wrangler won't work.
+
+Common operations:
+- **Deploy**: `jack ship` or Jack MCP
+- **Database**: `jack services db create` or Jack MCP
+- **Status**: `jack status` or Jack MCP
+
+## Project Structure
+
+```
+src/
+├── index.ts              # Hono API entry point
+├── auth.ts               # Better Auth configuration
+├── client/               # React frontend
+│   ├── App.tsx           # Application entry
+│   ├── main.tsx          # React entry point
+│   ├── index.css         # Tailwind + theme CSS
+│   ├── lib/
+│   │   ├── auth-client.ts  # Better Auth client
+│   │   └── utils.ts        # Utility functions (cn)
+│   ├── hooks/
+│   │   ├── useAuth.ts      # Auth hook
+│   │   └── useSubscription.ts  # Subscription hook
+│   ├── pages/            # Page components
+│   │   ├── HomePage.tsx    # Public landing page
+│   │   ├── LoginPage.tsx   # Login form
+│   │   ├── SignupPage.tsx  # Signup form
+│   │   ├── DashboardPage.tsx # Protected dashboard
+│   │   └── PricingPage.tsx   # Pricing page
+│   └── components/       # Reusable components
+│       └── ui/           # shadcn/ui components
+└── db/
+    └── schema.sql        # D1 database schema
+```
+
+## Authentication (Better Auth)
+
+This template uses Better Auth with email/password authentication.
+
+### Server-side Setup (src/auth.ts)
+
+```typescript
+import { betterAuth } from "better-auth";
+import { stripe } from "@better-auth/stripe";
+import { Kysely } from "kysely";
+import { D1Dialect } from "kysely-d1";
+
+export function createAuth(env: Env) {
+  // Use Kysely with D1 dialect - Better Auth uses Kysely internally for D1
+  const db = new Kysely<any>({
+    dialect: new D1Dialect({ database: env.DB }),
+  });
+
+  return betterAuth({
+    database: { db, type: "sqlite" },
+    emailAndPassword: { enabled: true },
+    secret: env.BETTER_AUTH_SECRET,
+    plugins: [stripe({ /* config */ })],
+  });
+}
+```
+
+### Client-side Usage
+
+```tsx
+import { authClient } from './lib/auth-client';
+
+// Sign up new user
+await authClient.signUp.email({
+  email: 'user@example.com',
+  password: 'password123',
+  name: 'John Doe'
+});
+
+// Sign in existing user
+await authClient.signIn.email({
+  email: 'user@example.com',
+  password: 'password123'
+});
+
+// Get current session
+const { data: session } = await authClient.getSession();
+if (session) {
+  console.log('Logged in as:', session.user.email);
+}
+
+// Sign out
+await authClient.signOut();
+```
+
+## Payments (Stripe)
+
+Uses Better Auth's Stripe plugin for subscription management. Webhooks are handled automatically at `/api/auth/stripe/webhook`.
+
+### Subscription Tiers
+
+- **Free**: No payment required, basic features
+- **Pro**: Monthly subscription, full features
+- **Enterprise**: Monthly subscription, premium support
+
+### Upgrading a User
+
+```tsx
+import { authClient } from './lib/auth-client';
+
+async function handleUpgrade(plan: 'pro' | 'enterprise') {
+  const { data, error } = await authClient.subscription.upgrade({
+    plan,
+    successUrl: '/dashboard?upgraded=true',
+    cancelUrl: '/pricing',
+  });
+
+  if (data?.url) {
+    // Redirect to Stripe Checkout
+    window.location.href = data.url;
+  }
+}
+```
+
+### Checking Subscription Status
+
+```tsx
+import { authClient } from './lib/auth-client';
+
+async function getCurrentPlan() {
+  const { data: subscriptions } = await authClient.subscription.list();
+
+  const activeSubscription = subscriptions?.find(
+    s => s.status === 'active' || s.status === 'trialing'
+  );
+
+  return activeSubscription?.plan || 'free';
+}
+```
+
+## Adding New Pages
+
+1. Create component in `src/client/pages/NewPage.tsx`
+2. Add route in `src/client/App.tsx`
+3. For protected pages, check session before rendering
+
+### Protected Page Pattern
+
+```tsx
+import { authClient } from '../lib/auth-client';
+import { useEffect, useState } from 'react';
+
+export function ProtectedPage() {
+  const [session, setSession] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    authClient.getSession().then(({ data }) => {
+      setSession(data);
+      setLoading(false);
+    });
+  }, []);
+
+  if (loading) return <div>Loading...</div>;
+  if (!session) {
+    window.location.href = '/login';
+    return null;
+  }
+
+  return <div>Protected content for {session.user.email}</div>;
+}
+```
+
+## Adding API Routes
+
+API routes are defined in `src/index.ts` using Hono.
+
+```typescript
+import { Hono } from "hono";
+
+const app = new Hono<{ Bindings: Env }>();
+
+// Public route
+app.get("/api/health", (c) => c.json({ status: "ok" }));
+
+// Protected route (check auth)
+app.get("/api/me", async (c) => {
+  const auth = createAuth(c.env);
+  const session = await auth.api.getSession({ headers: c.req.raw.headers });
+
+  if (!session) {
+    return c.json({ error: "Unauthorized" }, 401);
+  }
+
+  return c.json({ user: session.user });
+});
+```
+
+## Database Schema
+
+The D1 database uses Better Auth's default schema (singular table names, camelCase columns):
+
+- `user` - User accounts with email, name, stripeCustomerId
+- `session` - Active user sessions
+- `account` - OAuth provider accounts (includes password for email/password auth)
+- `verification` - Email verification tokens
+- `subscription` - Stripe subscription records
+
+To modify the schema, edit `schema.sql` and run migrations with jack.
+
+## Stripe Setup (Required Order)
+
+### 1. Initial Deploy & Webhook Setup
+
+The webhook secret requires the deployment URL, so follow this order:
+
+```bash
+# 1. Deploy first (without webhook secret - subscriptions won't work yet)
+jack ship
+
+# 2. Get your deployment URL
+jack status  # e.g., https://your-app.runjack.xyz
+
+# 3. Create webhook in Stripe Dashboard:
+#    - Go to: Developers → Webhooks → Add endpoint
+#    - URL: https://your-app.runjack.xyz/api/auth/stripe/webhook
+#    - Events: customer.subscription.created, customer.subscription.updated,
+#              customer.subscription.deleted, checkout.session.completed
+#    - Copy the signing secret (whsec_...)
+
+# 4. Set the webhook secret
+jack secrets set STRIPE_WEBHOOK_SECRET whsec_your_secret_here
+
+# 5. Redeploy to enable Stripe plugin
+jack ship
+```
+
+**Important:** The Stripe plugin is DISABLED if `STRIPE_WEBHOOK_SECRET` is missing. This prevents silent sync failures.
+
+### 2. Customer Portal Setup
+
+For subscription upgrades/downgrades to work:
+
+1. Go to [Stripe Dashboard → Settings → Billing → Customer Portal](https://dashboard.stripe.com/settings/billing/portal)
+2. Enable **"Customers can switch plans"**
+3. Add your products/prices to the allowed list
+4. Enable **"Customers can cancel subscriptions"** if you want in-portal cancellation
+
+Without this, users will see: *"This subscription cannot be updated because the subscription update feature in the portal configuration is disabled."*
+
+## Environment Variables
+
+Required secrets (set via `jack secrets set KEY value`):
+
+| Secret | Description | Where to get it |
+|--------|-------------|-----------------|
+| `BETTER_AUTH_SECRET` | Random secret for auth tokens | `openssl rand -base64 32` |
+| `STRIPE_SECRET_KEY` | Stripe API secret key | [Stripe Dashboard](https://dashboard.stripe.com/apikeys) |
+| `STRIPE_WEBHOOK_SECRET` | Webhook signing secret (whsec_...) | Created after adding webhook |
+| `STRIPE_PRO_PRICE_ID` | Price ID for Pro plan | [Stripe Products](https://dashboard.stripe.com/products) |
+| `STRIPE_ENTERPRISE_PRICE_ID` | Price ID for Enterprise plan | [Stripe Products](https://dashboard.stripe.com/products) |
+
+## SQL Execution
+
+Jack supports secure SQL execution against D1 databases:
+
+**Via MCP** (preferred for agents):
+- `execute_sql({ sql: "SELECT * FROM user" })` - read queries work by default
+- `execute_sql({ sql: "INSERT...", allow_write: true })` - writes require allow_write
+- Destructive ops (DROP, TRUNCATE, ALTER) are blocked via MCP - use CLI
+
+**Via CLI**:
+- `jack services db execute "SELECT * FROM user"` - read queries
+- `jack services db execute "INSERT..." --write` - write queries
+- `jack services db execute --file schema.sql --write` - run SQL from file
+
+## Customizing Theme
+
+The template uses shadcn/ui CSS variables for theming. To customize:
+
+1. Visit [ui.shadcn.com/create](https://ui.shadcn.com/create)
+2. Design your theme with the visual editor
+3. Copy the generated CSS variables
+4. Replace the `:root` and `.dark` blocks in `src/client/index.css`
+
+The default theme uses neutral colors. The CSS variables control all component colors:
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 0 0% 3.9%;
+  --primary: 0 0% 9%;
+  --primary-foreground: 0 0% 98%;
+  /* ... etc */
+}
+```
+
+## External API Integration Principles
+
+### 1. Don't trust cached data for real-time state
+
+Libraries that sync external data via webhooks (like Better Auth's Stripe plugin) provide **eventual consistency**, not real-time truth. Webhooks may be delayed, fail silently, or not be configured yet.
+
+**Rule**: For user-facing state that must be accurate (subscription status, payment state, cancellation), query the source API directly rather than relying on locally cached data.
+
+### 2. Defensive coding for external data
+
+External APIs return unpredictable shapes. Fields you expect may be null, undefined, or have different types in edge cases.
+
+**Rule**: Always add null checks before transforming external data, especially timestamps, nested objects, and optional fields.
+
+### 3. Return actionable error details
+
+Generic "500 Internal Server Error" messages waste debugging time. During development, include the actual error.
+
+**Rule**: In catch blocks, return `details: err.message` so you can see what actually failed. Strip these in production if needed.
+
+### 4. Test the unhappy paths
+
+The happy path (user signs up, subscribes, uses app) usually works. The bugs hide in: cancellation flows, expired states, partial failures, re-subscription after cancel.
+
+**Rule**: Manually test state transitions, not just initial states.
+
+## Resources
+
+- [Better Auth Docs](https://www.betterauth.com/docs)
+- [Better Auth Stripe Plugin](https://www.betterauth.com/docs/plugins/stripe)
+- [Stripe Billing Docs](https://docs.stripe.com/billing)
+- [Stripe Webhooks](https://docs.stripe.com/billing/subscriptions/webhooks)
+- [shadcn/ui Theme Creator](https://ui.shadcn.com/create)
+- [Hono Documentation](https://hono.dev)
+- [Cloudflare D1 Docs](https://developers.cloudflare.com/d1)