@getjack/jack 0.1.2 → 0.1.3

package/src/mcp/tools/index.ts

@@ -2,14 +2,10 @@ import type { Server as McpServer } from "@modelcontextprotocol/sdk/server/index
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { JackError, JackErrorCode } from "../../lib/errors.ts";
-import {
-	createProject,
-	deployProject,
-	getProjectStatus,
-	listAllProjects,
-} from "../../lib/project-operations.ts";
+import { createProject, deployProject, getProjectStatus } from "../../lib/project-operations.ts";
+import { listAllProjects } from "../../lib/project-resolver.ts";
 import { Events, track, withTelemetry } from "../../lib/telemetry.ts";
-import type { McpServerOptions } from "../types.ts";
+import type { DebugLogger, McpServerOptions } from "../types.ts";
 import { formatErrorResponse, formatSuccessResponse } from "../utils.ts";
 
 // Tool schemas
@@ -40,9 +36,10 @@ const ListProjectsSchema = z.object({
 		.describe("Filter projects by status (defaults to 'all')"),
 });
 
-export function registerTools(server: McpServer, _options: McpServerOptions) {
+export function registerTools(server: McpServer, _options: McpServerOptions, debug: DebugLogger) {
 	// Register tool list handler
 	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		debug("tools/list requested");
 		return {
 			tools: [
 				{
@@ -80,7 +77,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions) {
 				{
 					name: "get_project_status",
 					description:
-						"Get detailed status information for a specific project, including deployment status, local path, and cloud backup status.",
+						"Get detailed status information for a specific project, including deployment status, local path, and backup status.",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -98,7 +95,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions) {
 				{
 					name: "list_projects",
 					description:
-						"List all known projects with their status information. Can filter by local, deployed, or cloud-backed projects.",
+						"List all known projects with their status information. Can filter by local, deployed, or backup projects.",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -117,9 +114,12 @@ export function registerTools(server: McpServer, _options: McpServerOptions) {
 	// Register single tools/call handler that dispatches to individual tool implementations
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const startTime = Date.now();
+		const toolName = request.params.name;
+
+		debug("tools/call requested", { tool: toolName, args: request.params.arguments });
 
 		try {
-			switch (request.params.name) {
+			switch (toolName) {
 				case "create_project": {
 					const args = CreateProjectSchema.parse(request.params.arguments ?? {});
 
@@ -226,7 +226,23 @@ export function registerTools(server: McpServer, _options: McpServerOptions) {
 					const wrappedListProjects = withTelemetry(
 						"list_projects",
 						async (filter?: "all" | "local" | "deployed" | "cloud") => {
-							return await listAllProjects(filter);
+							const allProjects = await listAllProjects();
+
+							// Apply filter if specified
+							if (!filter || filter === "all") {
+								return allProjects;
+							}
+
+							switch (filter) {
+								case "local":
+									return allProjects.filter((p) => p.sources.filesystem);
+								case "deployed":
+									return allProjects.filter((p) => p.status === "live");
+								case "cloud":
+									return allProjects.filter((p) => p.sources.controlPlane);
+								default:
+									return allProjects;
+							}
 						},
 						{ platform: "mcp" },
 					);
@@ -244,9 +260,15 @@ export function registerTools(server: McpServer, _options: McpServerOptions) {
 				}
 
 				default:
-					throw new Error(`Unknown tool: ${request.params.name}`);
+					throw new Error(`Unknown tool: ${toolName}`);
 			}
 		} catch (error) {
+			const duration = Date.now() - startTime;
+			debug("tools/call failed", {
+				tool: toolName,
+				duration_ms: duration,
+				error: error instanceof Error ? error.message : String(error),
+			});
 			return {
 				content: [
 					{

package/src/mcp/types.ts

@@ -26,4 +26,10 @@ export { JackErrorCode as McpErrorCode } from "../lib/errors.ts";
  */
 export interface McpServerOptions {
 	projectPath?: string;
+	debug?: boolean;
 }
+
+/**
+ * Debug logger function type
+ */
+export type DebugLogger = (message: string, data?: unknown) => void;

package/src/mcp/utils.ts

@@ -23,7 +23,7 @@ export function formatErrorResponse(error: unknown, startTime: number): McpToolR
 	const message = error instanceof Error ? error.message : String(error);
 	const code = classifyMcpError(error);
 	const suggestion = isJackError(error)
-		? error.suggestion ?? getSuggestionForError(code)
+		? (error.suggestion ?? getSuggestionForError(code))
 		: getSuggestionForError(code);
 
 	return {

package/src/templates/index.ts

@@ -1,12 +1,22 @@
 import { existsSync } from "node:fs";
 import { readFile, readdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { parseJsonc } from "../lib/jsonc.ts";
+import type { TemplateOrigin } from "../lib/registry.ts";
 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");
 
-const BUILTIN_TEMPLATES = ["miniapp", "api"];
+export const BUILTIN_TEMPLATES = ["hello", "miniapp", "api"];
+
+/**
+ * Resolved template with origin tracking for lineage
+ */
+export interface ResolvedTemplate {
+	template: Template;
+	origin: TemplateOrigin;
+}
 
 /**
  * Read all files in a directory recursively
@@ -59,12 +69,15 @@ async function loadTemplate(name: string): Promise<Template> {
 		name: string;
 		description: string;
 		secrets: string[];
+		optionalSecrets?: Template["optionalSecrets"];
 		capabilities?: Template["capabilities"];
 		requires?: Template["requires"];
 		hooks?: Template["hooks"];
+		agentContext?: Template["agentContext"];
+		intent?: Template["intent"];
 	} = { name, description: "", secrets: [] };
 	if (existsSync(metadataPath)) {
-		metadata = JSON.parse(await readFile(metadataPath, "utf-8"));
+		metadata = parseJsonc(await readFile(metadataPath, "utf-8"));
 	}
 
 	// Read all template files
@@ -73,9 +86,12 @@ async function loadTemplate(name: string): Promise<Template> {
 	return {
 		description: metadata.description,
 		secrets: metadata.secrets,
+		optionalSecrets: metadata.optionalSecrets,
 		capabilities: metadata.capabilities,
 		requires: metadata.requires,
 		hooks: metadata.hooks,
+		agentContext: metadata.agentContext,
+		intent: metadata.intent,
 		files,
 	};
 }
@@ -84,9 +100,9 @@ async function loadTemplate(name: string): Promise<Template> {
  * Resolve template by name or GitHub URL
  */
 export async function resolveTemplate(template?: string): Promise<Template> {
-	// No template → miniapp (omakase default)
+	// No template → hello (omakase default)
 	if (!template) {
-		return loadTemplate("miniapp");
+		return loadTemplate("hello");
 	}
 
 	// Built-in template
@@ -104,6 +120,28 @@ export async function resolveTemplate(template?: string): Promise<Template> {
 	throw new Error(`Unknown template: ${template}\n\nAvailable: ${BUILTIN_TEMPLATES.join(", ")}`);
 }
 
+/**
+ * Resolve template with origin tracking for lineage
+ * Used during project creation to record which template was used
+ */
+export async function resolveTemplateWithOrigin(
+	templateOption?: string,
+): Promise<ResolvedTemplate> {
+	const templateName = templateOption || "hello";
+
+	// Determine origin type
+	const isGitHub = templateName.includes("/");
+	const origin: TemplateOrigin = {
+		type: isGitHub ? "github" : "builtin",
+		name: templateName,
+	};
+
+	// Resolve the template
+	const template = await resolveTemplate(templateOption);
+
+	return { template, origin };
+}
+
 /**
  * Replace template placeholders with project name
  * All templates use "jack-template" as universal placeholder

package/src/templates/types.ts

@@ -30,12 +30,25 @@ export interface AgentContext {
 	full_text: string;
 }
 
+export interface OptionalSecret {
+	name: string;
+	description: string;
+	setupUrl?: string;
+}
+
+export interface IntentMetadata {
+	keywords: string[];
+	examples?: string[]; // For future telemetry/docs
+}
+
 export interface Template {
 	files: Record<string, string>; // path -> content
 	secrets?: string[]; // required secret keys (e.g., ["NEYNAR_API_KEY"])
+	optionalSecrets?: OptionalSecret[]; // optional secret configurations
 	capabilities?: Capability[]; // infrastructure requirements (deprecated, use requires)
 	requires?: ServiceTypeKey[]; // service requirements (DB, KV, CRON, QUEUE, STORAGE)
 	description?: string; // for help text
 	hooks?: TemplateHooks;
 	agentContext?: AgentContext;
+	intent?: IntentMetadata;
 }

package/templates/CLAUDE.md

@@ -185,6 +185,172 @@ These variables are substituted at runtime (different from template placeholders
 }
 ```
 
+## Farcaster Miniapp Embeds
+
+When a cast includes a URL, Farcaster scrapes it for `fc:miniapp` meta tags to render a rich embed.
+
+### fc:miniapp Meta Format
+
+```html
+<meta name="fc:miniapp" content='{"version":"1","imageUrl":"...","button":{...}}' />
+```
+
+```typescript
+{
+  version: "1",
+  imageUrl: "https://absolute-url/image.png",  // MUST be absolute https
+  button: {
+    title: "Open App",  // Max 32 chars
+    action: {
+      type: "launch_miniapp",
+      name: "app-name",           // REQUIRED - app name shown in UI
+      url: "https://absolute-url" // MUST be absolute https
+    }
+  }
+}
+```
+
+**Critical requirements:**
+- All URLs must be absolute `https://` - no relative paths, no localhost
+- `button.action.name` is **required** - omitting it breaks the embed
+- Image must be 600×400 to 3000×2000 (3:2 ratio), <10MB, PNG/JPG/GIF/WebP
+
+### Wrangler Assets + Dynamic Routes
+
+To serve both static assets AND dynamic routes (like `/share` with meta tags):
+
+```jsonc
+// wrangler.jsonc (miniapp template)
+"assets": {
+  "directory": "dist/client",  // Cloudflare Vite plugin outputs client assets here
+  "binding": "ASSETS",
+  "not_found_handling": "single-page-application",
+  "run_worker_first": true  // CRITICAL - without this, assets bypass the worker!
+}
+```
+
+**Why `run_worker_first: true`?**
+Without it, Cloudflare serves static files directly from the assets directory, completely bypassing your worker. This means:
+- `/api/*` routes won't work if there's a matching file
+- Dynamic routes like `/share` that need to inject meta tags won't work
+- The worker only runs for truly non-existent paths
+
+### External Fetch Timeout Pattern
+
+When fetching external resources (like profile pictures for OG images), always use a timeout:
+
+```typescript
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), 3000);
+
+try {
+  const response = await fetch(url, { signal: controller.signal });
+  clearTimeout(timeoutId);
+
+  if (response.ok) {
+    const buffer = await response.arrayBuffer();
+    // Also limit size to prevent memory issues
+    if (buffer.byteLength < 500_000) {
+      // process...
+    }
+  }
+} catch {
+  // Handle timeout/network errors gracefully
+}
+```
+
+Without timeout, a slow or hanging external URL can cause your OG image generation to fail silently.
+
+## URL Detection in Cloudflare Workers
+
+When generating URLs for external services (like Farcaster embed URLs), you need reliable production URL detection. This is non-trivial because:
+
+1. `new URL(request.url).origin` may not work correctly in all cases
+2. Local development returns `localhost` which is invalid for embeds
+3. Custom domains require explicit configuration
+
+### The Pattern
+
+```typescript
+function getBaseUrl(
+  env: Env,
+  c: { req: { header: (name: string) => string | undefined; url: string } },
+): string | null {
+  // 1. Prefer explicit APP_URL (most reliable for custom domains)
+  if (env.APP_URL?.trim()) {
+    const url = env.APP_URL.replace(/\/$/, "");
+    if (url.startsWith("https://")) return url;
+  }
+
+  // 2. Use Host header (always set by Cloudflare in production)
+  const host = c.req.header("host");
+  if (host) {
+    // Reject localhost - return null to signal "can't generate valid URLs"
+    if (host.startsWith("localhost") || host.startsWith("127.0.0.1")) {
+      return null;
+    }
+
+    // Get protocol from cf-visitor (Cloudflare-specific) or x-forwarded-proto
+    let proto = "https";
+    const cfVisitor = c.req.header("cf-visitor");
+    if (cfVisitor) {
+      try {
+        const parsed = JSON.parse(cfVisitor);
+        if (parsed.scheme) proto = parsed.scheme;
+      } catch {}
+    } else {
+      proto = c.req.header("x-forwarded-proto") || "https";
+    }
+
+    // Workers.dev is always https
+    if (host.endsWith(".workers.dev")) proto = "https";
+
+    return `${proto}://${host}`;
+  }
+
+  // 3. Fallback to URL origin (rarely needed)
+  try {
+    const url = new URL(c.req.url);
+    if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
+      return null;
+    }
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+```
+
+### Key Headers in Cloudflare Workers
+
+| Header | Value | Notes |
+|--------|-------|-------|
+| `host` | `my-app.workers.dev` | Always set in production |
+| `cf-visitor` | `{"scheme":"https"}` | Cloudflare-specific, most reliable for protocol |
+| `x-forwarded-proto` | `https` | Standard header, less reliable |
+
+### Handling Local Development
+
+When `getBaseUrl()` returns `null`, show a helpful error instead of generating broken URLs:
+
+```typescript
+const baseUrl = getBaseUrl(env, c);
+if (!baseUrl) {
+  return c.html(`
+    <h2>Share embeds require production deployment</h2>
+    <p>Deploy with <code>jack ship</code> to enable sharing.</p>
+  `);
+}
+```
+
+### Why Not Just Use `new URL(request.url)`?
+
+- In some edge cases, `request.url` may not have the expected origin
+- Local development always returns localhost
+- Doesn't help distinguish production from development
+
+The Host header approach is reliable because Cloudflare always sets it to the actual domain being accessed.
+
 ## Adding New Templates
 
 1. Create directory: `templates/my-template/`

package/templates/api/.jack.json

@@ -2,6 +2,10 @@
 	"name": "api",
 	"description": "Hono API with routing",
 	"secrets": [],
+	"intent": {
+		"keywords": ["api", "endpoint", "webhook", "worker"],
+		"examples": ["stripe webhook API", "REST API endpoint"]
+	},
 	"hooks": {
 		"postDeploy": [
 			{

package/templates/api/bun.lock

@@ -1,5 +1,6 @@
 {
   "lockfileVersion": 1,
+  "configVersion": 0,
   "workspaces": {
     "": {
       "name": "jack-template",

package/templates/api/wrangler.jsonc

@@ -0,0 +1,5 @@
+{
+	"name": "jack-template",
+	"main": "src/index.ts",
+	"compatibility_date": "2024-12-01"
+}

package/templates/hello/.jack.json

@@ -0,0 +1,28 @@
+{
+	"name": "hello",
+	"description": "Minimal Worker (fetch)",
+	"secrets": [],
+	"intent": {
+		"keywords": ["hello", "starter", "worker"],
+		"examples": ["hello world worker"]
+	},
+	"hooks": {
+		"postDeploy": [
+			{
+				"action": "clipboard",
+				"text": "{{url}}",
+				"message": "Deploy URL copied to clipboard"
+			},
+			{
+				"action": "shell",
+				"command": "curl -s {{url}} | head -c 200",
+				"message": "Testing worker..."
+			},
+			{
+				"action": "box",
+				"title": "Deployed: {{name}}",
+				"lines": ["URL: {{url}}", "", "Worker is live!"]
+			}
+		]
+	}
+}

package/templates/hello/package.json

@@ -0,0 +1,10 @@
+{
+	"name": "jack-template",
+	"version": "0.0.1",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"dev": "wrangler dev",
+		"deploy": "wrangler deploy"
+	}
+}

package/templates/hello/src/index.ts

@@ -0,0 +1,11 @@
+export default {
+	async fetch() {
+		return new Response(
+			JSON.stringify({
+				message: "Hello from jack!",
+				timestamp: new Date().toISOString(),
+			}),
+			{ headers: { "Content-Type": "application/json" } },
+		);
+	},
+};

package/templates/hello/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"skipLibCheck": true,
+		"types": ["@cloudflare/workers-types"]
+	},
+	"include": ["src/**/*"]
+}

package/templates/hello/wrangler.jsonc

@@ -0,0 +1,5 @@
+{
+	"name": "jack-template",
+	"main": "src/index.ts",
+	"compatibility_date": "2024-12-01"
+}

package/templates/miniapp/.jack.json

@@ -2,11 +2,22 @@
 	"name": "miniapp",
 	"description": "Farcaster Miniapp (React + Vite)",
 	"secrets": ["NEYNAR_API_KEY"],
-	"capabilities": ["db"],
-	"requires": ["DB"],
+	"optionalSecrets": [
+		{
+			"name": "OPENAI_API_KEY",
+			"description": "For better AI (optional, falls back to free Workers AI)",
+			"setupUrl": "https://platform.openai.com/api-keys"
+		}
+	],
+	"capabilities": ["db", "ai"],
+	"requires": ["DB", "AI"],
+	"intent": {
+		"keywords": ["mini app", "miniapp", "frontend", "ui", "dashboard"],
+		"examples": ["simple dashboard", "farcaster miniapp"]
+	},
 	"agentContext": {
-		"summary": "A Farcaster miniapp using React + Vite frontend, Hono API on Cloudflare Workers, with D1 SQLite database.",
-		"full_text": "## Project Structure\n\n- `src/App.tsx` - React application entry point\n- `src/worker.ts` - Hono API routes for backend\n- `src/components/` - React components\n- `schema.sql` - D1 database schema\n- `wrangler.jsonc` - Cloudflare Workers configuration\n\n## Conventions\n\n- API routes are defined with Hono in `src/worker.ts`\n- Frontend uses Vite for bundling and is served as static assets\n- Database uses D1 prepared statements for queries\n- Secrets are managed via jack and pushed to Cloudflare\n- Wrangler is installed globally by jack, not in project dependencies\n\n## Resources\n\n- [Farcaster Miniapp Docs](https://miniapps.farcaster.xyz)\n- [Hono Documentation](https://hono.dev)\n- [Cloudflare D1 Docs](https://developers.cloudflare.com/d1)"
+		"summary": "A Farcaster miniapp using React + Vite frontend, Hono API on Cloudflare Workers, with D1 SQLite database and AI capabilities.",
+		"full_text": "## Project Structure\n\n- `src/App.tsx` - React application entry point\n- `src/worker.ts` - Hono API routes for backend\n- `src/hooks/useAI.ts` - AI generation hook\n- `src/components/` - React components\n- `schema.sql` - D1 database schema\n- `wrangler.jsonc` - Cloudflare Workers configuration\n\n## Conventions\n\n- API routes are defined with Hono in `src/worker.ts`\n- Frontend uses Vite for bundling and is served as static assets\n- Database uses D1 prepared statements for queries\n- Secrets are managed via jack and pushed to Cloudflare\n- Wrangler is installed globally by jack, not in project dependencies\n\n## AI Feature\n\nThe template includes a `useAI()` hook for AI text generation.\n\n### Usage\n```tsx\nconst { generate, isLoading, error } = useAI();\nconst result = await generate('Your prompt here');\n// result.result = AI response text\n// result.provider = 'openai' | 'workers-ai'\n```\n\n### Providers\n- **Workers AI** (default): Free, uses Llama 3.1 8B. No API key needed.\n- **OpenAI** (optional): Better quality with gpt-4o-mini. Requires OPENAI_API_KEY.\n\n### Costs\n- **Workers AI**: Free (included in Cloudflare Workers)\n- **OpenAI gpt-4o-mini**: ~$0.0001 per request (~$0.15/1M input + $0.60/1M output tokens)\n- Typical usage (10 requests/day): ~$0.03/month\n\n### Rate Limiting\n- 10 requests per minute per IP address\n- Returns 429 with Retry-After header when exceeded\n- Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining\n\n## Resources\n\n- [Farcaster Miniapp Docs](https://miniapps.farcaster.xyz)\n- [Hono Documentation](https://hono.dev)\n- [Cloudflare D1 Docs](https://developers.cloudflare.com/d1)\n- [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/)"
 	},
 	"hooks": {
 		"preDeploy": [