@getjack/jack 0.1.0 → 0.1.1

package/src/mcp/tools/index.ts

@@ -0,0 +1,261 @@
+import type { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+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 { Events, track, withTelemetry } from "../../lib/telemetry.ts";
+import type { McpServerOptions } from "../types.ts";
+import { formatErrorResponse, formatSuccessResponse } from "../utils.ts";
+
+// Tool schemas
+const CreateProjectSchema = z.object({
+	name: z.string().optional().describe("Project name (auto-generated if not provided)"),
+	template: z.string().optional().describe("Template to use (e.g., 'miniapp', 'api')"),
+});
+
+const DeployProjectSchema = z.object({
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+});
+
+const GetProjectStatusSchema = z.object({
+	name: z.string().optional().describe("Project name (auto-detected if not provided)"),
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+});
+
+const ListProjectsSchema = z.object({
+	filter: z
+		.enum(["all", "local", "deployed", "cloud"])
+		.optional()
+		.describe("Filter projects by status (defaults to 'all')"),
+});
+
+export function registerTools(server: McpServer, _options: McpServerOptions) {
+	// Register tool list handler
+	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		return {
+			tools: [
+				{
+					name: "create_project",
+					description:
+						"Create a new Cloudflare Workers project from a template. Automatically installs dependencies, deploys to Cloudflare, and registers the project.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							name: {
+								type: "string",
+								description: "Project name (auto-generated if not provided)",
+							},
+							template: {
+								type: "string",
+								description: "Template to use (e.g., 'miniapp', 'api')",
+							},
+						},
+					},
+				},
+				{
+					name: "deploy_project",
+					description:
+						"Deploy an existing project to Cloudflare Workers. Builds the project if needed and pushes to production.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+						},
+					},
+				},
+				{
+					name: "get_project_status",
+					description:
+						"Get detailed status information for a specific project, including deployment status, local path, and cloud backup status.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							name: {
+								type: "string",
+								description: "Project name (auto-detected if not provided)",
+							},
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+						},
+					},
+				},
+				{
+					name: "list_projects",
+					description:
+						"List all known projects with their status information. Can filter by local, deployed, or cloud-backed projects.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							filter: {
+								type: "string",
+								enum: ["all", "local", "deployed", "cloud"],
+								description: "Filter projects by status (defaults to 'all')",
+							},
+						},
+					},
+				},
+			],
+		};
+	});
+
+	// Register single tools/call handler that dispatches to individual tool implementations
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const startTime = Date.now();
+
+		try {
+			switch (request.params.name) {
+				case "create_project": {
+					const args = CreateProjectSchema.parse(request.params.arguments ?? {});
+
+					const wrappedCreateProject = withTelemetry(
+						"create_project",
+						async (name?: string, template?: string) => {
+							const result = await createProject(name, {
+								template,
+								interactive: false,
+							});
+
+							// Track business event
+							track(Events.PROJECT_CREATED, {
+								template: template ?? "default",
+								platform: "mcp",
+							});
+
+							return result;
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedCreateProject(args.name, args.template);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
+				case "deploy_project": {
+					const args = DeployProjectSchema.parse(request.params.arguments ?? {});
+
+					const wrappedDeployProject = withTelemetry(
+						"deploy_project",
+						async (projectPath?: string) => {
+							const result = await deployProject({
+								projectPath,
+								interactive: false,
+								includeSecrets: false,
+								includeSync: false,
+							});
+
+							// Track business event
+							track(Events.DEPLOY_STARTED, {
+								platform: "mcp",
+							});
+
+							return result;
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedDeployProject(args.project_path);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
+				case "get_project_status": {
+					const args = GetProjectStatusSchema.parse(request.params.arguments ?? {});
+
+					const wrappedGetProjectStatus = withTelemetry(
+						"get_project_status",
+						async (name?: string, projectPath?: string) => {
+							return await getProjectStatus(name, projectPath);
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedGetProjectStatus(args.name, args.project_path);
+
+					if (result === null) {
+						throw new JackError(
+							JackErrorCode.PROJECT_NOT_FOUND,
+							"Project not found",
+							"Use list_projects to see available projects",
+						);
+					}
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
+				case "list_projects": {
+					const args = ListProjectsSchema.parse(request.params.arguments ?? {});
+
+					const wrappedListProjects = withTelemetry(
+						"list_projects",
+						async (filter?: "all" | "local" | "deployed" | "cloud") => {
+							return await listAllProjects(filter);
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedListProjects(args.filter);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
+				default:
+					throw new Error(`Unknown tool: ${request.params.name}`);
+			}
+		} catch (error) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(formatErrorResponse(error, startTime), null, 2),
+					},
+				],
+				isError: true,
+			};
+		}
+	});
+}

package/src/mcp/types.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP tool response format
+ * Provides structured, machine-readable responses for AI agents
+ */
+export interface McpToolResponse<T = unknown> {
+	success: boolean;
+	data?: T;
+	error?: {
+		code: string; // Machine-readable: 'AUTH_FAILED', 'PROJECT_NOT_FOUND'
+		message: string; // Human-readable description
+		suggestion?: string; // What to do next
+	};
+	meta?: {
+		duration_ms: number;
+		jack_version: string;
+	};
+}
+
+/**
+ * Error codes for MCP tool responses
+ */
+export { JackErrorCode as McpErrorCode } from "../lib/errors.ts";
+
+/**
+ * MCP server configuration options
+ */
+export interface McpServerOptions {
+	projectPath?: string;
+}

package/src/mcp/utils.ts

@@ -0,0 +1,147 @@
+import packageJson from "../../package.json" with { type: "json" };
+import { isJackError } from "../lib/errors.ts";
+import { McpErrorCode, type McpToolResponse } from "./types.ts";
+
+/**
+ * Format a successful MCP tool response
+ */
+export function formatSuccessResponse<T>(data: T, startTime: number): McpToolResponse<T> {
+	return {
+		success: true,
+		data,
+		meta: {
+			duration_ms: Date.now() - startTime,
+			jack_version: packageJson.version,
+		},
+	};
+}
+
+/**
+ * Format an error MCP tool response
+ */
+export function formatErrorResponse(error: unknown, startTime: number): McpToolResponse {
+	const message = error instanceof Error ? error.message : String(error);
+	const code = classifyMcpError(error);
+	const suggestion = isJackError(error)
+		? error.suggestion ?? getSuggestionForError(code)
+		: getSuggestionForError(code);
+
+	return {
+		success: false,
+		error: {
+			code,
+			message,
+			suggestion,
+		},
+		meta: {
+			duration_ms: Date.now() - startTime,
+			jack_version: packageJson.version,
+		},
+	};
+}
+
+/**
+ * Classify an error into an MCP error code
+ */
+export function classifyMcpError(error: unknown): McpErrorCode {
+	if (isJackError(error)) {
+		return error.code as McpErrorCode;
+	}
+
+	if (!(error instanceof Error)) {
+		return McpErrorCode.INTERNAL_ERROR;
+	}
+
+	const message = error.message.toLowerCase();
+
+	// Authentication errors
+	if (
+		message.includes("not authenticated") ||
+		message.includes("authentication failed") ||
+		message.includes("invalid token")
+	) {
+		return McpErrorCode.AUTH_FAILED;
+	}
+
+	// Wrangler-specific auth
+	if (
+		message.includes("wrangler") &&
+		(message.includes("auth") || message.includes("login") || message.includes("expired"))
+	) {
+		return McpErrorCode.WRANGLER_AUTH_EXPIRED;
+	}
+
+	// Project not found
+	if (
+		message.includes("project not found") ||
+		message.includes("no project") ||
+		message.includes("directory not found")
+	) {
+		return McpErrorCode.PROJECT_NOT_FOUND;
+	}
+
+	// Template not found
+	if (message.includes("template not found") || message.includes("invalid template")) {
+		return McpErrorCode.TEMPLATE_NOT_FOUND;
+	}
+
+	// Build failures
+	if (
+		message.includes("build failed") ||
+		message.includes("compilation error") ||
+		message.includes("syntax error")
+	) {
+		return McpErrorCode.BUILD_FAILED;
+	}
+
+	// Deploy failures
+	if (
+		message.includes("deploy failed") ||
+		message.includes("deployment failed") ||
+		message.includes("publish failed")
+	) {
+		return McpErrorCode.DEPLOY_FAILED;
+	}
+
+	// Validation errors
+	if (
+		message.includes("validation") ||
+		message.includes("invalid") ||
+		message.includes("required")
+	) {
+		return McpErrorCode.VALIDATION_ERROR;
+	}
+
+	return McpErrorCode.INTERNAL_ERROR;
+}
+
+/**
+ * Get a helpful suggestion for an error code
+ */
+export function getSuggestionForError(code: McpErrorCode): string {
+	switch (code) {
+		case McpErrorCode.AUTH_FAILED:
+			return "Check your authentication credentials and try again.";
+
+		case McpErrorCode.WRANGLER_AUTH_EXPIRED:
+			return "Run 'wrangler login' to re-authenticate with Cloudflare.";
+
+		case McpErrorCode.PROJECT_NOT_FOUND:
+			return "Ensure you're in a valid jack project directory or specify the project path.";
+
+		case McpErrorCode.TEMPLATE_NOT_FOUND:
+			return "Use a valid template name. Run 'jack new --help' to see available templates.";
+
+		case McpErrorCode.BUILD_FAILED:
+			return "Check your code for syntax errors and ensure all dependencies are installed.";
+
+		case McpErrorCode.DEPLOY_FAILED:
+			return "Verify your Cloudflare configuration and check the deployment logs for details.";
+
+		case McpErrorCode.VALIDATION_ERROR:
+			return "Review the error message and ensure all required fields are provided correctly.";
+
+		default:
+			return "An unexpected error occurred. Check the error message for details.";
+	}
+}

package/src/templates/index.ts

@@ -60,6 +60,7 @@ async function loadTemplate(name: string): Promise<Template> {
 		description: string;
 		secrets: string[];
 		capabilities?: Template["capabilities"];
+		requires?: Template["requires"];
 		hooks?: Template["hooks"];
 	} = { name, description: "", secrets: [] };
 	if (existsSync(metadataPath)) {
@@ -73,6 +74,7 @@ async function loadTemplate(name: string): Promise<Template> {
 		description: metadata.description,
 		secrets: metadata.secrets,
 		capabilities: metadata.capabilities,
+		requires: metadata.requires,
 		hooks: metadata.hooks,
 		files,
 	};

package/src/templates/types.ts

@@ -2,13 +2,17 @@
 export type HookAction =
 	| { action: "message"; text: string }
 	| { action: "box"; title: string; lines: string[] } // boxed info panel
-	| { action: "link"; url: string; label?: string; prompt?: boolean } // show link, optionally ask to open
-	| { action: "open"; url: string } // auto-open (use sparingly)
-	| { action: "checkSecret"; secret: string; message?: string; setupUrl?: string }
-	| { action: "checkEnv"; env: string; message?: string }
-	| { action: "copy"; text: string; message?: string }
-	| { action: "wait"; message?: string } // press enter to continue
-	| { action: "run"; command: string; cwd?: "project"; message?: string }; // run shell command
+	| { action: "url"; url: string; label?: string; open?: boolean; prompt?: boolean }
+	| { action: "clipboard"; text: string; message?: string }
+	| { action: "shell"; command: string; cwd?: "project"; message?: string }
+	| { action: "pause"; message?: string } // press enter to continue
+	| {
+			action: "require";
+			source: "secret" | "env";
+			key: string;
+			message?: string;
+			setupUrl?: string;
+	  };
 
 export interface TemplateHooks {
 	preDeploy?: HookAction[];
@@ -18,6 +22,9 @@ export interface TemplateHooks {
 // Supported infrastructure capabilities
 export type Capability = "db" | "kv" | "r2" | "queue" | "ai";
 
+// Service type key from services library
+import type { ServiceTypeKey } from "../lib/services/index.ts";
+
 export interface AgentContext {
 	summary: string;
 	full_text: string;
@@ -26,7 +33,8 @@ export interface AgentContext {
 export interface Template {
 	files: Record<string, string>; // path -> content
 	secrets?: string[]; // required secret keys (e.g., ["NEYNAR_API_KEY"])
-	capabilities?: Capability[]; // infrastructure requirements
+	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;

package/templates/CLAUDE.md

@@ -85,11 +85,112 @@ Before shipping a new template:
 - [ ] All scripts work without global tools except wrangler
 - [ ] `.gitignore` includes `.env`, `.dev.vars`, `.secrets.json`
 
+## Placeholder System
+
+All templates use **`jack-template`** as the universal placeholder. When a user runs `jack new my-app`, every occurrence of `jack-template` is replaced with `my-app`.
+
+```
+# In template files:
+name = "jack-template"           → name = "my-app"
+"database_name": "jack-template-db"  → "database_name": "my-app-db"
+```
+
+**Rules:**
+- Use `jack-template` for project name in all files (wrangler.toml, package.json, etc.)
+- Use `jack-template-db` for database names (replaced with `my-app-db`)
+- The `-db` variant is replaced first to avoid partial matches
+- No other placeholder syntax needed—just these two strings
+
+**Why universal placeholder?**
+- Templates are self-contained (no jack core changes needed)
+- GitHub templates work automatically
+- Simple string replacement, no complex parsing
+
+## Hook System
+
+Templates can define hooks in `.jack.json` that run at specific lifecycle points.
+
+### Hook Lifecycle
+
+```json
+{
+  "hooks": {
+    "preDeploy": [...],   // Before wrangler deploy (validation)
+    "postDeploy": [...]   // After successful deploy (notifications, testing)
+  }
+}
+```
+
+### Available Actions
+
+| Action | Purpose | Example |
+|--------|---------|---------|
+| `message` | Print info message | `{"action": "message", "text": "Setting up..."}` |
+| `box` | Display boxed message | `{"action": "box", "title": "Done", "lines": ["URL: {{url}}"]}` |
+| `url` | Show URL (optional prompt/open) | `{"action": "url", "url": "{{url}}", "label": "Open site", "prompt": true}` |
+| `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"}` |
+
+### Non-Interactive Mode
+
+Hooks run in a non-interactive mode for MCP/silent execution. In this mode:
+
+- `url` prints `Label: URL` (no prompt, no auto-open)
+- `clipboard` prints the text (no clipboard access)
+- `pause` is skipped
+- `require` still validates; if `setupUrl` exists it prints `Setup: ...`
+- `shell` runs with stdin ignored to avoid hangs
+
+### Hook Variables
+
+These variables are substituted at runtime (different from template placeholders):
+
+| Variable | Value | Available in |
+|----------|-------|--------------|
+| `{{url}}` | Full deployed URL | postDeploy |
+| `{{domain}}` | Domain without protocol | postDeploy |
+| `{{name}}` | Project name | preDeploy, postDeploy |
+
+### Example: API Template Hooks
+
+```json
+{
+  "hooks": {
+    "postDeploy": [
+      {"action": "clipboard", "text": "{{url}}", "message": "URL copied"},
+      {"action": "shell", "command": "curl -s {{url}}/health"},
+      {"action": "box", "title": "{{name}}", "lines": ["{{url}}", "", "API is live!"]}
+    ]
+  }
+}
+```
+
+### Example: Miniapp Template Hooks
+
+```json
+{
+  "hooks": {
+    "preDeploy": [
+      {"action": "require", "source": "secret", "key": "NEYNAR_API_KEY", "setupUrl": "https://neynar.com"}
+    ],
+    "postDeploy": [
+      {"action": "clipboard", "text": "{{url}}"},
+      {"action": "box", "title": "Deployed: {{name}}", "lines": ["URL: {{url}}"]},
+      {"action": "url", "url": "https://farcaster.xyz/.../manifest?domain={{domain}}", "label": "Generate manifest"},
+      {"action": "url", "url": "https://farcaster.xyz/.../preview?url={{url}}", "label": "Preview"}
+    ]
+  }
+}
+```
+
 ## Adding New Templates
 
 1. Create directory: `templates/my-template/`
 2. Add `.jack.json` with metadata and hooks
-3. Add all template files
-4. Generate lockfile: `cd templates/my-template && bun install`
-5. Test: `jack new test-project -t my-template`
-6. Verify install time with `./test-lockfile-timing.sh`
+3. Use `jack-template` placeholder in all files
+4. Add all template files
+5. Generate lockfile: `cd templates/my-template && bun install`
+6. Test: `jack new test-project -t my-template`
+7. Verify install time with `./test-lockfile-timing.sh`

package/templates/api/.jack.json

@@ -1,5 +1,24 @@
 {
 	"name": "api",
 	"description": "Hono API with routing",
-	"secrets": []
+	"secrets": [],
+	"hooks": {
+		"postDeploy": [
+			{
+				"action": "clipboard",
+				"text": "{{url}}",
+				"message": "Deploy URL copied to clipboard"
+			},
+			{
+				"action": "shell",
+				"command": "curl -s {{url}}/health | head -c 200",
+				"message": "Testing API..."
+			},
+			{
+				"action": "box",
+				"title": "Deployed: {{name}}",
+				"lines": ["URL: {{url}}", "", "API is live!"]
+			}
+		]
+	}
 }

package/templates/api/src/index.ts

@@ -6,7 +6,7 @@ const app = new Hono();
 app.use("/*", cors());
 
 app.get("/", (c) => {
-	return c.json({ message: "Hello from {{name}}!" });
+	return c.json({ message: "Hello from jack-template!" });
 });
 
 app.get("/health", (c) => {

package/templates/miniapp/.jack.json

@@ -3,6 +3,7 @@
 	"description": "Farcaster Miniapp (React + Vite)",
 	"secrets": ["NEYNAR_API_KEY"],
 	"capabilities": ["db"],
+	"requires": ["DB"],
 	"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)"
@@ -10,15 +11,16 @@
 	"hooks": {
 		"preDeploy": [
 			{
-				"action": "checkSecret",
-				"secret": "NEYNAR_API_KEY",
+				"action": "require",
+				"source": "secret",
+				"key": "NEYNAR_API_KEY",
 				"message": "NEYNAR_API_KEY is required for Farcaster miniapps",
 				"setupUrl": "https://neynar.com"
 			}
 		],
 		"postDeploy": [
 			{
-				"action": "copy",
+				"action": "clipboard",
 				"text": "{{url}}",
 				"message": "Deploy URL copied to clipboard"
 			},
@@ -28,12 +30,12 @@
 				"lines": ["URL: {{url}}", "", "Next: Generate a manifest, then preview your miniapp"]
 			},
 			{
-				"action": "link",
+				"action": "url",
 				"url": "https://farcaster.xyz/~/developers/mini-apps/manifest?domain={{domain}}",
 				"label": "Generate manifest"
 			},
 			{
-				"action": "link",
+				"action": "url",
 				"url": "https://farcaster.xyz/~/developers/mini-apps/preview?url={{url}}",
 				"label": "Preview in Farcaster"
 			}