@getjack/jack 0.1.17 → 0.1.20

package/src/lib/zip-packager.ts

@@ -6,6 +6,8 @@ import { join, relative } from "node:path";
 import archiver from "archiver";
 import { type AssetManifest, computeAssetHash } from "./asset-hash.ts";
 import type { BuildOutput, WranglerConfig } from "./build-helper.ts";
+import { debug } from "./debug.ts";
+import { formatSize } from "./format.ts";
 import { scanProjectFiles } from "./storage/file-filter.ts";
 
 export interface ZipPackageResult {
@@ -46,17 +48,23 @@ export interface ManifestData {
 	};
 }
 
+export interface ZipProgressCallback {
+	(current: number, total: number): void;
+}
+
 /**
  * Creates a ZIP archive from source directory
  * @param outputPath - Absolute path for output ZIP file
  * @param sourceDir - Absolute path to directory to archive
  * @param files - Optional list of specific files to include (relative to sourceDir)
+ * @param onProgress - Optional callback for file-count progress updates
  * @returns Promise that resolves when ZIP is created
  */
 async function createZipArchive(
 	outputPath: string,
 	sourceDir: string,
 	files?: string[],
+	onProgress?: ZipProgressCallback,
 ): Promise<void> {
 	return new Promise((resolve, reject) => {
 		const output = createWriteStream(outputPath);
@@ -68,13 +76,16 @@ async function createZipArchive(
 		archive.pipe(output);
 
 		if (files) {
-			// Add specific files
-			for (const file of files) {
+			// Add specific files with progress tracking
+			const total = files.length;
+			for (let i = 0; i < files.length; i++) {
+				const file = files[i];
 				const filePath = join(sourceDir, file);
 				archive.file(filePath, { name: file });
+				onProgress?.(i + 1, total);
 			}
 		} else {
-			// Add entire directory
+			// Add entire directory (no per-file progress available)
 			archive.directory(sourceDir, false);
 		}
 
@@ -82,6 +93,42 @@ async function createZipArchive(
 	});
 }
 
+/**
+ * Creates source.zip from project files without building.
+ * Used for prebuilt deployments that skip the full package flow.
+ * @param projectPath - Absolute path to project directory
+ * @returns Path to the created source.zip (caller responsible for cleanup)
+ */
+export async function createSourceZip(projectPath: string): Promise<string> {
+	const packageDir = join(tmpdir(), `jack-source-${Date.now()}`);
+	await mkdir(packageDir, { recursive: true });
+
+	const sourceZipPath = join(packageDir, "source.zip");
+	const projectFiles = await scanProjectFiles(projectPath);
+
+	// Debug output for source file statistics
+	const totalSize = projectFiles.reduce((sum, f) => sum + f.size, 0);
+	const largest =
+		projectFiles.length > 0
+			? projectFiles.reduce((max, f) => (f.size > max.size ? f : max), projectFiles[0])
+			: null;
+
+	debug(`Source: ${projectFiles.length} files, ${formatSize(totalSize)} uncompressed`);
+	if (largest) {
+		debug(`Largest: ${largest.path} (${formatSize(largest.size)})`);
+	}
+
+	const sourceFiles = projectFiles.map((f) => f.path);
+	await createZipArchive(sourceZipPath, projectPath, sourceFiles);
+
+	// Debug output for compression statistics
+	const zipStats = await stat(sourceZipPath);
+	const ratio = totalSize > 0 ? ((1 - zipStats.size / totalSize) * 100).toFixed(0) : 0;
+	debug(`Compressed: ${formatSize(zipStats.size)} (${ratio}% reduction)`);
+
+	return sourceZipPath;
+}
+
 /**
  * Recursively collects all file paths in a directory
  */
@@ -181,18 +228,38 @@ function extractBindingsFromConfig(config?: WranglerConfig): ManifestData["bindi
 	return Object.keys(bindings).length > 0 ? bindings : undefined;
 }
 
+export interface PackageOptions {
+	projectPath: string;
+	buildOutput: BuildOutput;
+	config?: WranglerConfig;
+	onProgress?: ZipProgressCallback;
+}
+
 /**
  * Packages a built project for deployment to jack cloud
- * @param projectPath - Absolute path to project directory
- * @param buildOutput - Build output from buildProject()
- * @param config - Optional wrangler config to extract binding intent
+ * @param options - Package options including paths, build output, config, and optional progress callback
  * @returns Package result with ZIP paths and cleanup function
  */
+export async function packageForDeploy(options: PackageOptions): Promise<ZipPackageResult>;
+/**
+ * @deprecated Use options object instead
+ */
 export async function packageForDeploy(
 	projectPath: string,
 	buildOutput: BuildOutput,
 	config?: WranglerConfig,
+): Promise<ZipPackageResult>;
+export async function packageForDeploy(
+	optionsOrPath: PackageOptions | string,
+	buildOutputArg?: BuildOutput,
+	configArg?: WranglerConfig,
 ): Promise<ZipPackageResult> {
+	// Support both old and new signatures
+	const options: PackageOptions =
+		typeof optionsOrPath === "string"
+			? { projectPath: optionsOrPath, buildOutput: buildOutputArg!, config: configArg }
+			: optionsOrPath;
+	const { projectPath, buildOutput, config, onProgress } = options;
 	// Create temp directory for package artifacts
 	const packageId = `jack-package-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 	const packageDir = join(tmpdir(), packageId);
@@ -209,7 +276,7 @@ export async function packageForDeploy(
 	// 2. Create source.zip from project files (filtered)
 	const projectFiles = await scanProjectFiles(projectPath);
 	const sourceFiles = projectFiles.map((f) => f.path);
-	await createZipArchive(sourceZipPath, projectPath, sourceFiles);
+	await createZipArchive(sourceZipPath, projectPath, sourceFiles, onProgress);
 
 	// 3. Create manifest.json
 	const manifest: ManifestData = {

package/src/lib/zip-utils.ts

@@ -0,0 +1,38 @@
+/**
+ * Zip utility functions for extracting zip archives
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { unzipSync } from "fflate";
+
+/**
+ * Extract a zip buffer to a target directory.
+ * Creates directories as needed and writes files preserving relative paths.
+ *
+ * @param zipBuffer - The zip file contents as a Buffer
+ * @param targetDir - The directory to extract files to
+ * @returns The number of files extracted
+ */
+export async function extractZipToDirectory(zipBuffer: Buffer, targetDir: string): Promise<number> {
+	const unzipped = unzipSync(new Uint8Array(zipBuffer));
+	let fileCount = 0;
+
+	for (const [path, content] of Object.entries(unzipped)) {
+		// Skip directories (they end with /)
+		if (path.endsWith("/")) continue;
+
+		// Security: prevent path traversal by removing any .. segments
+		const normalizedPath = path.replace(/\.\./g, "");
+		const fullPath = join(targetDir, normalizedPath);
+
+		// Ensure directory exists
+		await mkdir(dirname(fullPath), { recursive: true });
+
+		// Write file
+		await writeFile(fullPath, content);
+		fileCount++;
+	}
+
+	return fileCount;
+}

package/src/templates/index.ts

@@ -10,7 +10,7 @@ import type { Template } from "./types";
 // Resolve templates directory relative to this file (src/templates -> templates)
 const TEMPLATES_DIR = join(dirname(dirname(import.meta.dir)), "templates");
 
-export const BUILTIN_TEMPLATES = ["hello", "miniapp", "api", "nextjs"];
+export const BUILTIN_TEMPLATES = ["hello", "miniapp", "api", "nextjs", "saas"];
 
 /**
  * Resolved template with origin tracking for lineage

package/src/templates/types.ts

@@ -11,6 +11,7 @@ export type HookAction =
 			message: string;
 			validate?: "json" | "accountAssociation";
 			required?: boolean;
+			secret?: boolean; // Mask input (for sensitive values like API keys)
 			successMessage?: string;
 			writeJson?: {
 				path: string;
@@ -31,9 +32,24 @@ export type HookAction =
 			key: string;
 			message?: string;
 			setupUrl?: string;
+			onMissing?: "fail" | "prompt" | "generate";
+			promptMessage?: string;
+			generateCommand?: string;
+	  }
+	| {
+			action: "stripe-setup";
+			message?: string;
+			plans: Array<{
+				name: string;
+				priceKey: string; // Secret key to store price ID (e.g., "STRIPE_PRO_PRICE_ID")
+				amount: number; // in cents
+				interval: "month" | "year";
+				description?: string;
+			}>;
 	  };
 
 export interface TemplateHooks {
+	preCreate?: HookAction[];
 	preDeploy?: HookAction[];
 	postDeploy?: HookAction[];
 }

package/templates/CLAUDE.md

@@ -205,6 +205,109 @@ These variables are substituted at runtime (different from template placeholders
 }
 ```
 
+### Proposed Hook Extensions
+
+These extensions are planned to support more complex setup wizards (like SaaS templates with Stripe):
+
+#### 1. `require` + `onMissing: "prompt"`
+
+Currently `require` fails if a secret is missing. This extension allows prompting the user instead:
+
+```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 (no change)
+- If secret missing + interactive → prompt user, save to `.secrets.json`
+- If secret missing + non-interactive → fail with setup instructions
+
+#### 2. `shell` + `captureAs`
+
+Run a command and save its output as a secret or variable:
+
+```json
+{
+  "action": "shell",
+  "command": "stripe listen --print-secret",
+  "captureAs": "secret:STRIPE_WEBHOOK_SECRET",
+  "message": "Starting Stripe webhook listener..."
+}
+```
+
+**Use cases:**
+- Capture Stripe CLI webhook signing secret
+- Capture generated API keys or tokens
+- Capture any CLI output needed for configuration
+
+**`captureAs` syntax:**
+- `secret:KEY_NAME` → saves to `.secrets.json`
+- `var:NAME` → saves to hook variables for later hooks
+
+#### 3. `prompt` + `saveAs`
+
+Currently `prompt` only writes to JSON files via `writeJson`. This extension allows saving input as a secret:
+
+```json
+{
+  "action": "prompt",
+  "message": "Enter your Stripe Webhook Secret (whsec_...):",
+  "saveAs": "secret:STRIPE_WEBHOOK_SECRET",
+  "validate": "startsWith:whsec_",
+  "successMessage": "Webhook secret saved"
+}
+```
+
+**Difference from `require+onMissing`:**
+- `require+onMissing` checks first, prompts only if missing
+- `prompt+saveAs` always prompts (for update flows or explicit input)
+
+### Design Principles for Hook Extensions
+
+When extending the hook system:
+
+1. **Extend existing actions** - prefer `require+onMissing` over a new `requireOrPrompt` action
+2. **Reusable primitives** - `captureAs` works on any action that produces output
+3. **Consistent syntax** - `secret:KEY` pattern for writing to `.secrets.json`
+4. **Non-interactive fallback** - every interactive feature must degrade gracefully in CI/MCP
+
+### Example: Complex Setup Wizard
+
+A SaaS template with Stripe might use these extensions:
+
+```json
+{
+  "hooks": {
+    "preDeploy": [
+      {"action": "require", "source": "secret", "key": "BETTER_AUTH_SECRET", "onMissing": "prompt", "promptMessage": "Enter a random secret (32+ chars):"},
+      {"action": "require", "source": "secret", "key": "STRIPE_SECRET_KEY", "onMissing": "prompt", "promptMessage": "Enter Stripe Secret Key:", "setupUrl": "https://dashboard.stripe.com/apikeys"}
+    ],
+    "postDeploy": [
+      {"action": "box", "title": "Stripe Webhook Setup", "lines": ["1. Go to Stripe Dashboard → Webhooks", "2. Add endpoint: {{url}}/api/auth/stripe/webhook", "3. Select events: checkout.session.completed, customer.subscription.*"]},
+      {"action": "url", "url": "https://dashboard.stripe.com/webhooks/create?endpoint_url={{url}}/api/auth/stripe/webhook", "label": "Create webhook"},
+      {"action": "prompt", "message": "Paste webhook signing secret (whsec_...):", "saveAs": "secret:STRIPE_WEBHOOK_SECRET", "validate": "startsWith:whsec_"},
+      {"action": "message", "text": "Re-deploying with webhook secret..."},
+      {"action": "shell", "command": "jack ship --quiet"}
+    ]
+  }
+}
+```
+
+This creates a guided wizard that:
+1. Ensures auth secret exists (prompts if missing)
+2. Ensures Stripe key exists (prompts if missing, with setup link)
+3. Deploys the app
+4. Guides user through webhook setup with direct link
+5. Captures webhook secret
+6. Re-deploys with complete configuration
+
 ## 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"
+			}
+		]
+	}
+}