@getjack/jack 0.1.19 → 0.1.22

package/templates/CLAUDE.md

@@ -119,16 +119,18 @@ Templates can define hooks in `.jack.json` that run at specific lifecycle points
 | `url` | `url` | Prints label + URL |
 | `clipboard` | `text` | Prints text |
 | `pause` | _(none)_ | Skipped |
-| `require` | `source`, `key` | Validates, prints setup if provided |
+| `require` | `source`, `key` | Validates, prints setup if provided. Supports `onMissing: "prompt" \| "generate"` |
 | `shell` | `command` | Runs with stdin ignored |
-| `prompt` | `message` | Skipped (supports `validate: "json" | "accountAssociation"`) |
+| `prompt` | `message` | Skipped. Supports `secret: true` for masked input, `validate`, `writeJson`, `deployAfter` |
 | `writeJson` | `path`, `set` | Runs (safe in CI) |
+| `stripe-setup` | `plans` | Creates Stripe products/prices, saves price IDs to secrets |
 
 ### Hook Lifecycle
 
 ```json
 {
   "hooks": {
+    "preCreate": [...],   // During project creation (secret collection, auto-generation)
     "preDeploy": [...],   // Before wrangler deploy (validation)
     "postDeploy": [...]   // After successful deploy (notifications, testing)
   }
@@ -145,9 +147,10 @@ Templates can define hooks in `.jack.json` that run at specific lifecycle points
 | `clipboard` | Copy text to clipboard | `{"action": "clipboard", "text": "{{url}}", "message": "Copied!"}` |
 | `shell` | Execute shell command | `{"action": "shell", "command": "curl {{url}}/health"}` |
 | `pause` | Wait for Enter key | `{"action": "pause", "message": "Press Enter..."}` |
-| `require` | Verify secret or env | `{"action": "require", "source": "secret", "key": "API_KEY"}` |
-| `prompt` | Prompt for input and update JSON file | `{"action": "prompt", "message": "Paste JSON", "validate": "json", "successMessage": "Saved", "writeJson": {"path": "public/data.json", "set": {"data": {"from": "input"}}}}` |
+| `require` | Verify secret/env, optionally prompt or generate | `{"action": "require", "source": "secret", "key": "API_KEY", "onMissing": "prompt"}` |
+| `prompt` | Prompt for input, optionally masked | `{"action": "prompt", "message": "Secret:", "secret": true, "writeJson": {...}}` |
 | `writeJson` | Update JSON file with template vars | `{"action": "writeJson", "path": "public/data.json", "set": {"siteUrl": "{{url}}"}}` |
+| `stripe-setup` | Create Stripe products/prices | `{"action": "stripe-setup", "plans": [{"name": "Pro", "priceKey": "STRIPE_PRO_PRICE_ID", "amount": 1900, "interval": "month"}]}` |
 
 ### Non-Interactive Mode
 
@@ -169,7 +172,7 @@ These variables are substituted at runtime (different from template placeholders
 |----------|-------|--------------|
 | `{{url}}` | Full deployed URL | postDeploy |
 | `{{domain}}` | Domain without protocol | postDeploy |
-| `{{name}}` | Project name | preDeploy, postDeploy |
+| `{{name}}` | Project name | preCreate, preDeploy, postDeploy |
 
 ### Example: API Template Hooks
 
@@ -205,6 +208,170 @@ These variables are substituted at runtime (different from template placeholders
 }
 ```
 
+### Advanced Hook Features
+
+These features support complex setup wizards (like the SaaS template with Stripe):
+
+#### 1. `require` + `onMissing: "prompt" | "generate"`
+
+The `require` action supports automatic secret collection when a secret is missing:
+
+```json
+{
+  "action": "require",
+  "source": "secret",
+  "key": "STRIPE_SECRET_KEY",
+  "onMissing": "prompt",
+  "promptMessage": "Enter your Stripe Secret Key (sk_test_...):",
+  "setupUrl": "https://dashboard.stripe.com/apikeys"
+}
+```
+
+**Behavior:**
+- If secret exists → continue (shows "Using saved KEY")
+- If secret missing + interactive → prompt user, save to `.secrets.json`
+- If secret missing + non-interactive → fail with setup instructions
+
+**Auto-generate secrets with `onMissing: "generate"`:**
+
+```json
+{
+  "action": "require",
+  "source": "secret",
+  "key": "BETTER_AUTH_SECRET",
+  "message": "Generating authentication secret...",
+  "onMissing": "generate",
+  "generateCommand": "openssl rand -base64 32"
+}
+```
+
+This runs the command, captures stdout, and saves it as the secret automatically.
+
+#### 2. `stripe-setup` Action
+
+Automatically creates Stripe products and prices, saving the price IDs as secrets:
+
+```json
+{
+  "action": "stripe-setup",
+  "message": "Setting up Stripe subscription plans...",
+  "plans": [
+    {
+      "name": "Pro",
+      "priceKey": "STRIPE_PRO_PRICE_ID",
+      "amount": 1900,
+      "interval": "month",
+      "description": "Pro monthly subscription"
+    },
+    {
+      "name": "Enterprise",
+      "priceKey": "STRIPE_ENTERPRISE_PRICE_ID",
+      "amount": 9900,
+      "interval": "month"
+    }
+  ]
+}
+```
+
+**Behavior:**
+- Requires `STRIPE_SECRET_KEY` to be set first
+- Checks for existing prices by lookup key (`jack_pro_month`)
+- Creates product + price if not found
+- Saves price IDs to secrets
+
+#### 3. `prompt` with `secret` Flag
+
+Mask sensitive input (like API keys):
+
+```json
+{
+  "action": "prompt",
+  "message": "Paste your webhook signing secret (whsec_...):",
+  "secret": true,
+  "writeJson": {
+    "path": ".secrets.json",
+    "set": { "STRIPE_WEBHOOK_SECRET": { "from": "input" } }
+  }
+}
+```
+
+#### 4. `prompt` with `deployAfter`
+
+Automatically redeploy after user provides input:
+
+```json
+{
+  "action": "prompt",
+  "message": "Paste webhook signing secret:",
+  "secret": true,
+  "deployAfter": true,
+  "deployMessage": "Deploying with webhook support...",
+  "writeJson": {
+    "path": ".secrets.json",
+    "set": { "STRIPE_WEBHOOK_SECRET": { "from": "input" } }
+  }
+}
+```
+
+### Design Principles
+
+When extending the hook system:
+
+1. **Extend existing actions** - prefer `require+onMissing` over a new `requireOrPrompt` action
+2. **Non-interactive fallback** - every interactive feature must degrade gracefully in CI/MCP
+3. **Secrets via `.secrets.json`** - use `writeJson` with `.secrets.json` for secret storage
+
+### Example: SaaS Template Setup Wizard
+
+The `saas` template uses `preCreate` hooks for a complete setup wizard:
+
+```json
+{
+  "hooks": {
+    "preCreate": [
+      {
+        "action": "require",
+        "source": "secret",
+        "key": "STRIPE_SECRET_KEY",
+        "message": "Stripe API key required for payments",
+        "setupUrl": "https://dashboard.stripe.com/apikeys",
+        "onMissing": "prompt",
+        "promptMessage": "Enter your Stripe Secret Key (sk_test_... or sk_live_...):"
+      },
+      {
+        "action": "require",
+        "source": "secret",
+        "key": "BETTER_AUTH_SECRET",
+        "message": "Generating authentication secret...",
+        "onMissing": "generate",
+        "generateCommand": "openssl rand -base64 32"
+      },
+      {
+        "action": "stripe-setup",
+        "message": "Setting up Stripe subscription plans...",
+        "plans": [
+          {"name": "Pro", "priceKey": "STRIPE_PRO_PRICE_ID", "amount": 1900, "interval": "month"},
+          {"name": "Enterprise", "priceKey": "STRIPE_ENTERPRISE_PRICE_ID", "amount": 9900, "interval": "month"}
+        ]
+      }
+    ],
+    "postDeploy": [
+      {"action": "box", "title": "Your SaaS is live!", "lines": ["{{url}}"]},
+      {"action": "clipboard", "text": "{{url}}/api/auth/stripe/webhook", "message": "Webhook URL copied"},
+      {"action": "prompt", "message": "Paste your webhook signing secret (whsec_...):", "secret": true, "deployAfter": true, "writeJson": {"path": ".secrets.json", "set": {"STRIPE_WEBHOOK_SECRET": {"from": "input"}}}}
+    ]
+  }
+}
+```
+
+This creates a guided wizard that:
+1. Prompts for Stripe key (with setup URL)
+2. Auto-generates auth secret
+3. Creates Stripe products/prices automatically
+4. Deploys the app
+5. Guides through webhook setup
+6. Re-deploys with webhook secret
+
 ## Farcaster Miniapp Embeds
 
 When a cast includes a URL, Farcaster scrapes it for `fc:miniapp` meta tags to render a rich embed.

package/templates/miniapp/.jack.json

@@ -38,9 +38,7 @@
 			{
 				"action": "box",
 				"title": "Deployed: {{name}}",
-				"lines": [
-					"{{url}}"
-				]
+				"lines": ["{{url}}"]
 			},
 			{
 				"action": "writeJson",

package/templates/saas/.jack.json

@@ -0,0 +1,154 @@
+{
+	"name": "saas",
+	"description": "SaaS starter (Auth + Payments + React)",
+	"secrets": ["STRIPE_SECRET_KEY", "BETTER_AUTH_SECRET", "STRIPE_PRO_PRICE_ID", "STRIPE_ENTERPRISE_PRICE_ID"],
+	"capabilities": ["db"],
+	"requires": ["DB"],
+	"intent": {
+		"keywords": ["saas", "subscription", "auth", "payment", "stripe", "membership"],
+		"examples": ["subscription app", "paid membership site", "saas product"]
+	},
+	"agentContext": {
+		"summary": "A SaaS starter with Better Auth authentication, Stripe payments, React + Vite frontend, and Hono API on Cloudflare Workers with D1 SQLite database.",
+		"full_text": "## Project Structure\n\n- `src/index.ts` - Hono API entry point with auth and payment routes\n- `src/auth.ts` - Better Auth configuration with Stripe plugin\n- `src/client/App.tsx` - React application entry point\n- `src/client/lib/auth-client.ts` - Better Auth client\n- `src/client/hooks/` - useAuth, useSubscription hooks\n- `src/client/pages/` - Page components (HomePage, DashboardPage, etc.)\n- `src/client/components/ui/` - shadcn/ui components\n- `schema.sql` - D1 database schema (user, session, account, subscription)\n- `wrangler.jsonc` - Cloudflare Workers configuration\n\n## Authentication\n\nUses Better Auth with email/password. Auth routes are handled at `/api/auth/*`.\n\n### Client-side\n```tsx\nimport { authClient } from './lib/auth-client';\n\n// Sign up\nawait authClient.signUp.email({ email, password, name });\n\n// Sign in\nawait authClient.signIn.email({ email, password });\n\n// Get session\nconst { data: session } = await authClient.getSession();\n```\n\n## Payments (Stripe)\n\nUses Better Auth Stripe plugin for subscription management.\n\n### Upgrade Flow\n```tsx\nimport { authClient } from './lib/auth-client';\n\nasync function handleUpgrade(plan: 'pro' | 'enterprise') {\n  const { data, error } = await authClient.subscription.upgrade({\n    plan,\n    successUrl: '/dashboard?upgraded=true',\n    cancelUrl: '/pricing',\n  });\n\n  if (data?.url) {\n    window.location.href = data.url;  // Redirect to Stripe Checkout\n  }\n}\n```\n\n### Check Subscription\n```tsx\nconst { data: subscriptions } = await authClient.subscription.list();\nconst activeSubscription = subscriptions?.find(s =>\n  s.status === 'active' || s.status === 'trialing'\n);\nconst plan = activeSubscription?.plan || 'free';\n```\n\n## Webhook Setup\n\nStripe webhooks are handled at `/api/auth/stripe/webhook`. Required events:\n- `checkout.session.completed`\n- `customer.subscription.created`\n- `customer.subscription.updated`\n- `customer.subscription.deleted`\n\n## Database Schema\n\nUses Better Auth's default schema (singular table names, camelCase columns):\n- `user` - User accounts\n- `session` - Active sessions\n- `account` - OAuth/password credentials\n- `verification` - Email verification tokens\n- `subscription` - Stripe subscriptions\n\n## Environment Variables\n\n- `BETTER_AUTH_SECRET` - Random secret for auth tokens (generate with: openssl rand -base64 32)\n- `STRIPE_SECRET_KEY` - Stripe API secret key\n- `STRIPE_WEBHOOK_SECRET` - Stripe webhook signing secret (whsec_...)\n- `STRIPE_PRO_PRICE_ID` - Stripe price ID for Pro plan\n- `STRIPE_ENTERPRISE_PRICE_ID` - Stripe price ID for Enterprise plan\n\n## Resources\n\n- [Better Auth Docs](https://www.betterauth.com/docs)\n- [Better Auth Stripe Plugin](https://www.betterauth.com/docs/plugins/stripe)\n- [Stripe Subscriptions](https://docs.stripe.com/billing/subscriptions)\n- [Hono Documentation](https://hono.dev)\n- [Cloudflare D1 Docs](https://developers.cloudflare.com/d1)"
+	},
+	"hooks": {
+		"preCreate": [
+			{
+				"action": "require",
+				"source": "secret",
+				"key": "STRIPE_SECRET_KEY",
+				"message": "Stripe API key required for payments",
+				"setupUrl": "https://dashboard.stripe.com/apikeys",
+				"onMissing": "prompt",
+				"promptMessage": "Enter your Stripe Secret Key (sk_test_... or sk_live_...):"
+			},
+			{
+				"action": "require",
+				"source": "secret",
+				"key": "BETTER_AUTH_SECRET",
+				"message": "Generating authentication secret...",
+				"onMissing": "generate",
+				"generateCommand": "openssl rand -base64 32"
+			},
+			{
+				"action": "stripe-setup",
+				"message": "Setting up Stripe subscription plans...",
+				"plans": [
+					{
+						"name": "Pro",
+						"priceKey": "STRIPE_PRO_PRICE_ID",
+						"amount": 1900,
+						"interval": "month",
+						"description": "Pro monthly subscription"
+					},
+					{
+						"name": "Enterprise",
+						"priceKey": "STRIPE_ENTERPRISE_PRICE_ID",
+						"amount": 9900,
+						"interval": "month",
+						"description": "Enterprise monthly subscription"
+					}
+				]
+			}
+		],
+		"preDeploy": [
+			{
+				"action": "require",
+				"source": "secret",
+				"key": "STRIPE_SECRET_KEY"
+			}
+		],
+		"postDeploy": [
+			{
+				"action": "box",
+				"title": "Your SaaS is live!",
+				"lines": ["{{url}}"]
+			},
+			{
+				"action": "clipboard",
+				"text": "{{url}}/api/auth/stripe/webhook",
+				"message": "Webhook URL copied to clipboard"
+			},
+			{
+				"action": "message",
+				"text": ""
+			},
+			{
+				"action": "message",
+				"text": "━━━ Stripe Webhook Setup ━━━"
+			},
+			{
+				"action": "message",
+				"text": ""
+			},
+			{
+				"action": "message",
+				"text": "1. Create webhook endpoint in Stripe"
+			},
+			{
+				"action": "message",
+				"text": "2. Set endpoint URL to: {{url}}/api/auth/stripe/webhook"
+			},
+			{
+				"action": "message",
+				"text": "3. Select these events:"
+			},
+			{
+				"action": "message",
+				"text": "   • checkout.session.completed"
+			},
+			{
+				"action": "message",
+				"text": "   • customer.subscription.created"
+			},
+			{
+				"action": "message",
+				"text": "   • customer.subscription.updated"
+			},
+			{
+				"action": "message",
+				"text": "   • customer.subscription.deleted"
+			},
+			{
+				"action": "message",
+				"text": ""
+			},
+			{
+				"action": "url",
+				"url": "https://dashboard.stripe.com/webhooks",
+				"label": "Open Stripe webhooks",
+				"prompt": true
+			},
+			{
+				"action": "prompt",
+				"message": "Paste your webhook signing secret (whsec_...):",
+				"required": false,
+				"secret": true,
+				"successMessage": "Webhook secret saved!",
+				"deployAfter": true,
+				"deployMessage": "Deploying with webhook support...",
+				"writeJson": {
+					"path": ".secrets.json",
+					"set": { "STRIPE_WEBHOOK_SECRET": { "from": "input" } }
+				}
+			},
+			{
+				"action": "message",
+				"text": ""
+			},
+			{
+				"action": "message",
+				"text": "━━━ Next Steps ━━━"
+			},
+			{
+				"action": "message",
+				"text": "• Test card: 4242 4242 4242 4242 (any future date, any CVC)"
+			},
+			{
+				"action": "message",
+				"text": "• Customize theme: https://ui.shadcn.com/create"
+			}
+		]
+	}
+}