@getjack/jack 0.1.24 → 0.1.26

package/templates/AI-BINDINGS.md

@@ -0,0 +1,181 @@
+# AI and Vectorize Bindings in Jack Cloud
+
+## Quick Reference for Coding Agents
+
+**DO NOT add `[ai]` or `[[vectorize]]` bindings directly for jack cloud projects.**
+
+Jack cloud uses metered proxies for AI and Vectorize calls. Use the patterns below:
+
+### AI Pattern
+
+```typescript
+import { createJackAI } from "./jack-ai";
+
+function getAI(env: Env) {
+  if (env.__AI_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+    return createJackAI(env);
+  }
+  if (env.AI) {
+    return env.AI;
+  }
+  throw new Error("No AI binding available");
+}
+
+// Usage:
+const ai = getAI(env);
+const result = await ai.run("@cf/meta/llama-3.2-1b-instruct", { messages });
+```
+
+### Vectorize Pattern
+
+```typescript
+import { createJackVectorize } from "./jack-vectorize";
+
+const INDEX_NAME = "my-vectors";
+
+function getVectorize(env: Env) {
+  if (env.__VECTORIZE_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+    return createJackVectorize(env, INDEX_NAME);
+  }
+  if (env.VECTORS) {
+    return env.VECTORS;
+  }
+  throw new Error("No Vectorize binding available");
+}
+
+// Usage:
+const vectors = getVectorize(env);
+const results = await vectors.query(embedding, { topK: 10 });
+await vectors.insert([{ id: "doc1", values: embedding, metadata: {} }]);
+```
+
+## Why This Pattern?
+
+Jack cloud is multi-tenant. All users share Cloudflare's AI quota (10k neurons/day). Without metering:
+- One user could exhaust the daily quota for everyone
+- No visibility into per-project usage
+- No ability to bill for AI usage
+
+The proxy:
+1. Checks per-project quota
+2. Logs usage to Analytics Engine
+3. Forwards to real AI binding
+4. Returns response unchanged
+
+## Environment Bindings
+
+### Jack Cloud (Managed Deploy)
+
+Control plane injects these bindings:
+- `__AI_PROXY` - Service binding to jack-binding-proxy for AI
+- `__VECTORIZE_PROXY` - Service binding to jack-binding-proxy for Vectorize
+- `__JACK_PROJECT_ID` - Project ID for metering
+- `__JACK_ORG_ID` - Organization ID for billing
+
+`env.AI` and `env.VECTORS` are **NOT available** in jack cloud. Direct calls will fail.
+
+### Local Development
+
+wrangler.jsonc provides:
+- `AI` - Direct Cloudflare AI binding for local testing
+- `VECTORS` - Direct Vectorize binding for local testing
+
+The helper functions automatically use the right binding based on environment.
+
+## Template Pattern
+
+### AI Templates
+
+1. **src/jack-ai.ts** - Client wrapper (copy from ai-chat or semantic-search template)
+
+2. **Env interface** with optional bindings:
+```typescript
+interface Env {
+  AI?: Ai;                    // Local dev
+  __AI_PROXY?: Fetcher;       // Jack cloud
+  __JACK_PROJECT_ID?: string; // Jack cloud
+  __JACK_ORG_ID?: string;     // Jack cloud
+}
+```
+
+3. **getAI() helper** that handles both environments
+
+4. **wrangler.jsonc** with AI binding for local dev only:
+```jsonc
+{
+  "ai": { "binding": "AI" }
+}
+```
+
+### Vectorize Templates
+
+1. **src/jack-vectorize.ts** - Client wrapper (copy from semantic-search template)
+
+2. **Env interface** with optional bindings:
+```typescript
+interface Env {
+  VECTORS?: VectorizeIndex;      // Local dev
+  __VECTORIZE_PROXY?: Fetcher;   // Jack cloud
+  __JACK_PROJECT_ID?: string;    // Jack cloud
+  __JACK_ORG_ID?: string;        // Jack cloud
+}
+```
+
+3. **getVectorize() helper** that handles both environments
+
+4. **wrangler.jsonc** with Vectorize binding for local dev only:
+```jsonc
+{
+  "vectorize": [{
+    "binding": "VECTORS",
+    "index_name": "my-vectors",
+    "preset": "cloudflare"
+  }]
+}
+```
+
+## Error Handling
+
+Quota exceeded returns 429:
+
+### AI Quota
+```typescript
+try {
+  const result = await ai.run(model, inputs);
+} catch (error) {
+  if (error.code === "AI_QUOTA_EXCEEDED") {
+    // Daily limit (1000 requests) reached, resets at midnight UTC
+    console.log(`Retry in ${error.resetIn} seconds`);
+  }
+}
+```
+
+### Vectorize Quota
+```typescript
+try {
+  const results = await vectors.query(embedding, { topK: 10 });
+} catch (error) {
+  if (error.code === "VECTORIZE_QUERY_QUOTA_EXCEEDED") {
+    // Query limit (33,000/day) reached
+    console.log(`Retry in ${error.resetIn} seconds`);
+  }
+  if (error.code === "VECTORIZE_MUTATION_QUOTA_EXCEEDED") {
+    // Mutation limit (10,000/day) reached
+    console.log(`Retry in ${error.resetIn} seconds`);
+  }
+}
+```
+
+## BYOC Mode
+
+For Bring Your Own Cloud deployments:
+- User configures their own Cloudflare account
+- Direct AI binding is used (no proxy)
+- No metering (it's their account)
+- Standard Cloudflare docs apply
+
+## See Also
+
+- `/docs/internal/specs/binding-proxy-worker.md` - Full architecture spec
+- `apps/binding-proxy-worker/` - Proxy implementation
+- `apps/control-plane/src/deployment-service.ts` - Binding injection logic

package/templates/CLAUDE.md

@@ -6,6 +6,36 @@
 2. **Templates are for user code, not jack's tools** - wrangler is jack's responsibility (installed globally), not the template's
 3. **Ship a lockfile** - `bun.lock` provides 70% faster installs on cold cache
 
+## AI Bindings (IMPORTANT)
+
+**For jack cloud projects, DO NOT use direct AI bindings.**
+
+See [AI-BINDINGS.md](./AI-BINDINGS.md) for the full pattern.
+
+Quick summary:
+- Jack cloud uses a metered proxy (`__AI_PROXY`) instead of direct `env.AI`
+- Templates must include `src/jack-ai.ts` wrapper
+- Use `getAI(env)` helper instead of `env.AI` directly
+- wrangler.jsonc still declares `ai: { binding: "AI" }` for local dev only
+
+```typescript
+// WRONG for jack cloud:
+const result = await env.AI.run(model, inputs);
+
+// CORRECT (works for both local dev and jack cloud):
+import { createJackAI } from "./jack-ai";
+
+function getAI(env: Env) {
+  if (env.__AI_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+    return createJackAI(env);
+  }
+  return env.AI;
+}
+
+const ai = getAI(env);
+const result = await ai.run(model, inputs);
+```
+
 ## Dependency Rules
 
 ### DO include in templates:

package/templates/ai-chat/.jack.json

@@ -4,7 +4,7 @@
 	"secrets": [],
 	"capabilities": ["ai"],
 	"intent": {
-		"keywords": ["ai", "chat", "llm", "mistral", "completion", "chatbot"],
+		"keywords": ["ai", "chat", "llm", "llama", "completion", "chatbot"],
 		"examples": ["AI chatbot", "chat interface", "LLM chat app"]
 	},
 	"hooks": {
@@ -16,12 +16,11 @@
 			},
 			{
 				"action": "box",
-				"title": "AI Chat: {{name}}",
+				"title": "{{name}}",
 				"lines": [
 					"{{url}}",
 					"",
-					"Open in browser to start chatting!",
-					"Rate limit: 10 requests/minute"
+					"jack open  to view in browser"
 				]
 			}
 		]

package/templates/ai-chat/src/index.ts

@@ -1,13 +1,46 @@
+import { createJackAI } from "./jack-ai";
+
 interface Env {
-	AI: Ai;
+	// Direct AI binding (for local dev with wrangler)
+	AI?: Ai;
+	// Jack proxy bindings (injected in jack cloud)
+	__AI_PROXY?: Fetcher;
+	__JACK_PROJECT_ID?: string;
+	__JACK_ORG_ID?: string;
+	// Assets binding
 	ASSETS: Fetcher;
 }
 
+function getAI(env: Env) {
+	// Prefer jack cloud proxy if available (for metering)
+	if (env.__AI_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+		return createJackAI(env as Required<Pick<Env, "__AI_PROXY" | "__JACK_PROJECT_ID" | "__JACK_ORG_ID">>);
+	}
+	// Fallback to direct binding for local dev
+	if (env.AI) {
+		return env.AI;
+	}
+	throw new Error("No AI binding available");
+}
+
 interface ChatMessage {
 	role: "user" | "assistant" | "system";
 	content: string;
 }
 
+// System prompt - customize this to change the AI's personality
+const SYSTEM_PROMPT = `You are a helpful AI assistant built with jack (getjack.sh).
+
+jack helps developers ship ideas fast - from "what if" to a live URL in seconds. You're running on Cloudflare's edge network, close to users worldwide.
+
+Be concise, friendly, and helpful. If asked about jack:
+- jack new creates projects from templates
+- jack ship deploys to production
+- jack open opens your app in browser
+- Docs: https://docs.getjack.sh
+
+Focus on being useful. Keep responses short unless detail is needed.`;
+
 // Rate limiting: 10 requests per minute per IP
 const RATE_LIMIT = 10;
 const RATE_WINDOW_MS = 60_000;
@@ -65,7 +98,7 @@ export default {
 
 			try {
 				const body = (await request.json()) as { messages?: ChatMessage[] };
-				const messages = body.messages;
+				let messages = body.messages;
 
 				if (!messages || !Array.isArray(messages)) {
 					return Response.json(
@@ -74,9 +107,16 @@ export default {
 					);
 				}
 
-				// Stream response using SSE
-				const stream = await env.AI.run(
-					"@cf/mistral/mistral-7b-instruct-v0.1",
+				// Prepend system prompt if not already present
+				if (messages.length === 0 || messages[0].role !== "system") {
+					messages = [{ role: "system", content: SYSTEM_PROMPT }, ...messages];
+				}
+
+				// Stream response using Llama 3.2 1B - cheapest model with good quality
+				// See: https://developers.cloudflare.com/workers-ai/models/
+				const ai = getAI(env);
+				const stream = await ai.run(
+					"@cf/meta/llama-3.2-1b-instruct",
 					{
 						messages,
 						stream: true,

package/templates/ai-chat/src/jack-ai.ts

@@ -0,0 +1,96 @@
+/**
+ * Jack AI Client - Drop-in replacement for Cloudflare AI binding.
+ *
+ * This wrapper provides the same interface as env.AI but routes calls
+ * through jack's binding proxy for metering and quota enforcement.
+ *
+ * Usage in templates:
+ * ```typescript
+ * import { createJackAI } from "./jack-ai";
+ *
+ * interface Env {
+ *   __AI_PROXY: Fetcher;        // Service binding to binding-proxy worker
+ *   __JACK_PROJECT_ID: string;  // Injected by control plane
+ *   __JACK_ORG_ID: string;      // Injected by control plane
+ * }
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const AI = createJackAI(env);
+ *     const result = await AI.run("@cf/meta/llama-3.2-1b-instruct", { messages });
+ *     // Works exactly like env.AI.run()
+ *   }
+ * };
+ * ```
+ *
+ * The wrapper is transparent - it accepts the same parameters as env.AI.run()
+ * and returns the same response types, including streaming.
+ */
+
+interface JackAIEnv {
+	__AI_PROXY: Fetcher;
+	__JACK_PROJECT_ID: string;
+	__JACK_ORG_ID: string;
+}
+
+/**
+ * Creates a Jack AI client that mirrors the Cloudflare AI binding interface.
+ *
+ * @param env - Worker environment with jack proxy bindings
+ * @returns AI-compatible object with run() method
+ */
+export function createJackAI(env: JackAIEnv): {
+	run: <T = unknown>(
+		model: string,
+		inputs: unknown,
+		options?: unknown,
+	) => Promise<T | ReadableStream>;
+} {
+	return {
+		async run<T = unknown>(
+			model: string,
+			inputs: unknown,
+			options?: unknown,
+		): Promise<T | ReadableStream> {
+			const response = await env.__AI_PROXY.fetch("http://internal/ai/run", {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-Jack-Project-ID": env.__JACK_PROJECT_ID,
+					"X-Jack-Org-ID": env.__JACK_ORG_ID,
+				},
+				body: JSON.stringify({ model, inputs, options }),
+			});
+
+			// Handle quota exceeded
+			if (response.status === 429) {
+				const error = await response.json();
+				const quotaError = new Error((error as { message?: string }).message || "AI quota exceeded");
+				(quotaError as Error & { code: string }).code = "AI_QUOTA_EXCEEDED";
+				(quotaError as Error & { resetIn?: number }).resetIn = (error as { resetIn?: number }).resetIn;
+				throw quotaError;
+			}
+
+			// Handle other errors
+			if (!response.ok) {
+				const error = await response.json();
+				throw new Error((error as { error?: string }).error || "AI request failed");
+			}
+
+			// Handle streaming response
+			const contentType = response.headers.get("Content-Type");
+			if (contentType?.includes("text/event-stream")) {
+				return response.body as ReadableStream;
+			}
+
+			// Handle JSON response
+			return response.json() as Promise<T>;
+		},
+	};
+}
+
+/**
+ * Type-safe wrapper that infers return types based on model.
+ * For advanced users who want full type safety.
+ */
+export type JackAI = ReturnType<typeof createJackAI>;

package/templates/semantic-search/.jack.json

@@ -7,18 +7,17 @@
 		"keywords": ["rag", "semantic", "search", "embeddings", "vectorize", "vector", "similarity"],
 		"examples": ["RAG app", "document search", "semantic search", "knowledge base"]
 	},
+	"agentContext": "Local development requires 'wrangler dev --remote' for AI and Vectorize bindings.",
 	"hooks": {
 		"postDeploy": [
 			{ "action": "clipboard", "text": "{{url}}", "message": "URL copied" },
 			{
 				"action": "box",
-				"title": "Semantic Search: {{name}}",
+				"title": "{{name}}",
 				"lines": [
 					"{{url}}",
 					"",
-					"Open in browser to index documents and search!",
-					"",
-					"Note: Local dev requires 'wrangler dev --remote'"
+					"jack open  to view in browser"
 				]
 			}
 		]

package/templates/semantic-search/src/index.ts

@@ -1,10 +1,64 @@
+import { createJackAI, type JackAI } from "./jack-ai";
+import { createJackVectorize, type JackVectorize } from "./jack-vectorize";
+
 interface Env {
-	AI: Ai;
-	VECTORS: VectorizeIndex;
+	// Direct bindings (for local dev with wrangler)
+	AI?: Ai;
+	VECTORS?: VectorizeIndex;
+	// Jack proxy bindings (injected in jack cloud)
+	__AI_PROXY?: Fetcher;
+	__VECTORIZE_PROXY?: Fetcher;
+	__JACK_PROJECT_ID?: string;
+	__JACK_ORG_ID?: string;
+	// Other bindings
 	DB: D1Database;
 	ASSETS: Fetcher;
 }
 
+// Index name must match wrangler.jsonc vectorize config
+const VECTORIZE_INDEX_NAME = "jack-template-vectors";
+
+// Minimal AI interface for embedding generation
+type AIClient = {
+	run: (model: string, inputs: { text: string }) => Promise<{ data: number[][] } | unknown>;
+};
+
+function getAI(env: Env): AIClient {
+	// Prefer jack cloud proxy if available (for metering)
+	if (env.__AI_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+		return createJackAI(env as Required<Pick<Env, "__AI_PROXY" | "__JACK_PROJECT_ID" | "__JACK_ORG_ID">>) as AIClient;
+	}
+	// Fallback to direct binding for local dev
+	if (env.AI) {
+		return env.AI as unknown as AIClient;
+	}
+	throw new Error("No AI binding available");
+}
+
+// Minimal Vectorize interface
+type VectorizeClient = {
+	insert: (vectors: { id: string; values: number[]; metadata?: Record<string, unknown> }[]) => Promise<unknown>;
+	query: (
+		vector: number[],
+		options?: { topK?: number; returnMetadata?: "none" | "indexed" | "all" },
+	) => Promise<{ matches: { id: string; score: number; metadata?: Record<string, unknown> }[] }>;
+};
+
+function getVectorize(env: Env): VectorizeClient {
+	// Prefer jack cloud proxy if available (for metering)
+	if (env.__VECTORIZE_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+		return createJackVectorize(
+			env as Required<Pick<Env, "__VECTORIZE_PROXY" | "__JACK_PROJECT_ID" | "__JACK_ORG_ID">>,
+			VECTORIZE_INDEX_NAME,
+		) as VectorizeClient;
+	}
+	// Fallback to direct binding for local dev
+	if (env.VECTORS) {
+		return env.VECTORS as unknown as VectorizeClient;
+	}
+	throw new Error("No Vectorize binding available");
+}
+
 // Rate limiting: 10 requests per minute per IP
 const RATE_LIMIT = 10;
 const RATE_WINDOW_MS = 60_000;
@@ -29,17 +83,17 @@ function checkRateLimit(ip: string): boolean {
 
 /**
  * Extract embedding vector from AI response
- * Handles union type from @cf/baai/bge-base-en-v1.5
+ * Handles response from @cf/baai/bge-base-en-v1.5
  */
-function getEmbeddingVector(response: Awaited<ReturnType<Ai["run"]>>): number[] | null {
+function getEmbeddingVector(response: unknown): number[] | null {
 	if (
 		response &&
 		typeof response === "object" &&
 		"data" in response &&
-		Array.isArray(response.data) &&
-		response.data.length > 0
+		Array.isArray((response as { data: unknown }).data) &&
+		(response as { data: unknown[] }).data.length > 0
 	) {
-		return response.data[0] as number[];
+		return (response as { data: number[][] }).data[0];
 	}
 	return null;
 }
@@ -72,8 +126,9 @@ export default {
 					return Response.json({ error: "Missing id or content" }, { status: 400 });
 				}
 
-				// Generate embedding using free Cloudflare AI
-				const embedding = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
+				// Generate embedding using Cloudflare AI
+				const ai = getAI(env);
+				const embedding = await ai.run("@cf/baai/bge-base-en-v1.5", {
 					text: content,
 				});
 
@@ -83,7 +138,8 @@ export default {
 				}
 
 				// Store in Vectorize
-				await env.VECTORS.insert([
+				const vectors = getVectorize(env);
+				await vectors.insert([
 					{
 						id,
 						values: embeddingVector,
@@ -117,7 +173,8 @@ export default {
 				}
 
 				// Generate query embedding
-				const embedding = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
+				const ai = getAI(env);
+				const embedding = await ai.run("@cf/baai/bge-base-en-v1.5", {
 					text: query,
 				});
 
@@ -127,7 +184,8 @@ export default {
 				}
 
 				// Search Vectorize
-				const results = await env.VECTORS.query(embeddingVector, {
+				const vectors = getVectorize(env);
+				const results = await vectors.query(embeddingVector, {
 					topK: limit,
 					returnMetadata: "all",
 				});

package/templates/semantic-search/src/jack-ai.ts

@@ -0,0 +1,96 @@
+/**
+ * Jack AI Client - Drop-in replacement for Cloudflare AI binding.
+ *
+ * This wrapper provides the same interface as env.AI but routes calls
+ * through jack's binding proxy for metering and quota enforcement.
+ *
+ * Usage in templates:
+ * ```typescript
+ * import { createJackAI } from "./jack-ai";
+ *
+ * interface Env {
+ *   __AI_PROXY: Fetcher;        // Service binding to binding-proxy worker
+ *   __JACK_PROJECT_ID: string;  // Injected by control plane
+ *   __JACK_ORG_ID: string;      // Injected by control plane
+ * }
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const AI = createJackAI(env);
+ *     const result = await AI.run("@cf/meta/llama-3.2-1b-instruct", { messages });
+ *     // Works exactly like env.AI.run()
+ *   }
+ * };
+ * ```
+ *
+ * The wrapper is transparent - it accepts the same parameters as env.AI.run()
+ * and returns the same response types, including streaming.
+ */
+
+interface JackAIEnv {
+	__AI_PROXY: Fetcher;
+	__JACK_PROJECT_ID: string;
+	__JACK_ORG_ID: string;
+}
+
+/**
+ * Creates a Jack AI client that mirrors the Cloudflare AI binding interface.
+ *
+ * @param env - Worker environment with jack proxy bindings
+ * @returns AI-compatible object with run() method
+ */
+export function createJackAI(env: JackAIEnv): {
+	run: <T = unknown>(
+		model: string,
+		inputs: unknown,
+		options?: unknown,
+	) => Promise<T | ReadableStream>;
+} {
+	return {
+		async run<T = unknown>(
+			model: string,
+			inputs: unknown,
+			options?: unknown,
+		): Promise<T | ReadableStream> {
+			const response = await env.__AI_PROXY.fetch("http://internal/ai/run", {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-Jack-Project-ID": env.__JACK_PROJECT_ID,
+					"X-Jack-Org-ID": env.__JACK_ORG_ID,
+				},
+				body: JSON.stringify({ model, inputs, options }),
+			});
+
+			// Handle quota exceeded
+			if (response.status === 429) {
+				const error = await response.json();
+				const quotaError = new Error((error as { message?: string }).message || "AI quota exceeded");
+				(quotaError as Error & { code: string }).code = "AI_QUOTA_EXCEEDED";
+				(quotaError as Error & { resetIn?: number }).resetIn = (error as { resetIn?: number }).resetIn;
+				throw quotaError;
+			}
+
+			// Handle other errors
+			if (!response.ok) {
+				const error = await response.json();
+				throw new Error((error as { error?: string }).error || "AI request failed");
+			}
+
+			// Handle streaming response
+			const contentType = response.headers.get("Content-Type");
+			if (contentType?.includes("text/event-stream")) {
+				return response.body as ReadableStream;
+			}
+
+			// Handle JSON response
+			return response.json() as Promise<T>;
+		},
+	};
+}
+
+/**
+ * Type-safe wrapper that infers return types based on model.
+ * For advanced users who want full type safety.
+ */
+export type JackAI = ReturnType<typeof createJackAI>;