@getjack/jack 0.1.16 → 0.1.19

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/mcp/tools/index.ts

@@ -5,6 +5,12 @@ import { JackError, JackErrorCode } from "../../lib/errors.ts";
 import { createProject, deployProject, getProjectStatus } from "../../lib/project-operations.ts";
 import { listAllProjects } from "../../lib/project-resolver.ts";
 import { createDatabase } from "../../lib/services/db-create.ts";
+import {
+	DestructiveOperationError,
+	WriteNotAllowedError,
+	executeSql,
+	wrapResultsForMcp,
+} from "../../lib/services/db-execute.ts";
 import { listDatabases } from "../../lib/services/db-list.ts";
 import { Events, track, withTelemetry } from "../../lib/telemetry.ts";
 import type { DebugLogger, McpServerOptions } from "../types.ts";
@@ -53,6 +59,25 @@ const ListDatabasesSchema = z.object({
 		.describe("Path to project directory (defaults to current directory)"),
 });
 
+const ExecuteSqlSchema = z.object({
+	sql: z.string().describe("SQL query to execute"),
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+	allow_write: z
+		.boolean()
+		.optional()
+		.default(false)
+		.describe(
+			"Allow write operations (INSERT, UPDATE, DELETE). Required for any data modification. Destructive operations (DROP, TRUNCATE) are blocked and must be run via CLI.",
+		),
+	database_name: z
+		.string()
+		.optional()
+		.describe("Database name (auto-detect from wrangler.jsonc if not provided)"),
+});
+
 export function registerTools(server: McpServer, _options: McpServerOptions, debug: DebugLogger) {
 	// Register tool list handler
 	server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -155,6 +180,38 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 						},
 					},
 				},
+				{
+					name: "execute_sql",
+					description:
+						"Execute SQL against the project's D1 database. Read-only by default for safety. " +
+						"Set allow_write=true for INSERT, UPDATE, DELETE operations. " +
+						"Destructive operations (DROP, TRUNCATE, ALTER) are blocked and must be run via CLI with confirmation. " +
+						"Results are wrapped with anti-injection headers to prevent prompt injection from database content.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							sql: {
+								type: "string",
+								description: "SQL query to execute",
+							},
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+							allow_write: {
+								type: "boolean",
+								default: false,
+								description:
+									"Allow write operations (INSERT, UPDATE, DELETE). Required for any data modification.",
+							},
+							database_name: {
+								type: "string",
+								description: "Database name (auto-detect from wrangler.jsonc if not provided)",
+							},
+						},
+						required: ["sql"],
+					},
+				},
 			],
 		};
 	});
@@ -389,6 +446,110 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 					};
 				}
 
+				case "execute_sql": {
+					const args = ExecuteSqlSchema.parse(request.params.arguments ?? {});
+					const projectPath = args.project_path ?? process.cwd();
+
+					const wrappedExecuteSql = withTelemetry(
+						"execute_sql",
+						async (projectDir: string, sql: string, allowWrite: boolean, databaseName?: string) => {
+							try {
+								const result = await executeSql({
+									projectDir,
+									sql,
+									databaseName,
+									allowWrite,
+									interactive: false, // MCP is non-interactive
+									wrapResults: true,
+								});
+
+								// Track business event
+								track(Events.SQL_EXECUTED, {
+									risk_level: result.risk,
+									statement_count: result.statements.length,
+									platform: "mcp",
+								});
+
+								// Wrap results with anti-injection header for MCP
+								const wrappedContent = wrapResultsForMcp(result.results ?? [], sql, result.meta);
+
+								return {
+									success: result.success,
+									risk_level: result.risk,
+									results_wrapped: wrappedContent,
+									meta: result.meta,
+									warning: result.warning,
+								};
+							} catch (err) {
+								if (err instanceof WriteNotAllowedError) {
+									return {
+										success: false,
+										error: err.message,
+										suggestion: "Set allow_write=true to allow data modification",
+										risk_level: err.risk,
+									};
+								}
+								if (err instanceof DestructiveOperationError) {
+									return {
+										success: false,
+										error: err.message,
+										suggestion:
+											"Destructive operations (DROP, TRUNCATE, ALTER, DELETE without WHERE) " +
+											"must be run via CLI with explicit confirmation: " +
+											`jack services db execute "${sql.slice(0, 50)}..." --write`,
+										risk_level: "destructive",
+									};
+								}
+								throw err;
+							}
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedExecuteSql(
+						projectPath,
+						args.sql,
+						args.allow_write ?? false,
+						args.database_name,
+					);
+
+					// Check if the result indicates an error (e.g., WriteNotAllowedError, DestructiveOperationError)
+					// These are returned as objects with success: false instead of thrown
+					const resultObj = result as Record<string, unknown>;
+					if (resultObj?.success === false) {
+						return {
+							content: [
+								{
+									type: "text",
+									text: JSON.stringify(
+										{
+											success: false,
+											error: resultObj.error,
+											suggestion: resultObj.suggestion,
+											risk_level: resultObj.risk_level,
+											meta: {
+												duration_ms: Date.now() - startTime,
+											},
+										},
+										null,
+										2,
+									),
+								},
+							],
+							isError: true,
+						};
+					}
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
 				default:
 					throw new Error(`Unknown tool: ${toolName}`);
 			}

package/src/templates/index.ts

@@ -73,6 +73,7 @@ async function loadTemplate(name: string): Promise<Template> {
 		description: string;
 		secrets: string[];
 		optionalSecrets?: Template["optionalSecrets"];
+		envVars?: Template["envVars"];
 		capabilities?: Template["capabilities"];
 		requires?: Template["requires"];
 		hooks?: Template["hooks"];
@@ -90,6 +91,7 @@ async function loadTemplate(name: string): Promise<Template> {
 		description: metadata.description,
 		secrets: metadata.secrets,
 		optionalSecrets: metadata.optionalSecrets,
+		envVars: metadata.envVars,
 		capabilities: metadata.capabilities,
 		requires: metadata.requires,
 		hooks: metadata.hooks,
@@ -165,6 +167,7 @@ async function fetchPublishedTemplate(username: string, slug: string): Promise<T
 		description: (metadata.description as string) || `Fork of ${username}/${slug}`,
 		secrets: (metadata.secrets as string[]) || [],
 		optionalSecrets: metadata.optionalSecrets as Template["optionalSecrets"],
+		envVars: metadata.envVars as Template["envVars"],
 		capabilities: metadata.capabilities as Template["capabilities"],
 		requires: metadata.requires as Template["requires"],
 		hooks: metadata.hooks as Template["hooks"],
@@ -200,6 +203,7 @@ async function fetchUserTemplate(slug: string): Promise<Template | null> {
 		description: (metadata.description as string) || `Your project: ${slug}`,
 		secrets: (metadata.secrets as string[]) || [],
 		optionalSecrets: metadata.optionalSecrets as Template["optionalSecrets"],
+		envVars: metadata.envVars as Template["envVars"],
 		capabilities: metadata.capabilities as Template["capabilities"],
 		requires: metadata.requires as Template["requires"],
 		hooks: metadata.hooks as Template["hooks"],

package/src/templates/types.ts

@@ -16,6 +16,8 @@ export type HookAction =
 				path: string;
 				set: Record<string, string | { from: "input" }>;
 			};
+			deployAfter?: boolean; // Redeploy after successful input (only if user provided input)
+			deployMessage?: string; // Message to show during deploy (default: "Deploying...")
 	  }
 	| {
 			action: "writeJson";
@@ -53,6 +55,15 @@ export interface OptionalSecret {
 	setupUrl?: string;
 }
 
+export interface EnvVar {
+	name: string;
+	description: string;
+	required?: boolean;
+	defaultValue?: string;
+	example?: string;
+	setupUrl?: string;
+}
+
 export interface IntentMetadata {
 	keywords: string[];
 	examples?: string[]; // For future telemetry/docs
@@ -62,6 +73,7 @@ export interface Template {
 	files: Record<string, string>; // path -> content
 	secrets?: string[]; // required secret keys (e.g., ["NEYNAR_API_KEY"])
 	optionalSecrets?: OptionalSecret[]; // optional secret configurations
+	envVars?: EnvVar[]; // environment variables (non-secret config)
 	capabilities?: Capability[]; // infrastructure requirements (deprecated, use requires)
 	requires?: ServiceTypeKey[]; // service requirements (DB, KV, CRON, QUEUE, STORAGE)
 	description?: string; // for help text

package/templates/api/AGENTS.md

@@ -0,0 +1,33 @@
+# Agent Context
+
+## Infrastructure
+
+This project uses **jack** for deployment. When Jack MCP is connected, prefer `mcp__jack__*` tools over CLI commands - they're cloud-aware and faster.
+
+**Do NOT use wrangler directly.** Jack manages config and may use cloud-hosted resources where wrangler won't work.
+
+Common operations:
+- **Deploy**: `jack ship` or Jack MCP
+- **Database**: `jack services db create` or Jack MCP
+- **Status**: `jack status` or Jack MCP
+
+## SQL Execution
+
+Jack supports secure SQL execution against D1 databases:
+
+**Via MCP** (preferred for agents):
+- `execute_sql({ sql: "SELECT * FROM users" })` - read queries work by default
+- `execute_sql({ sql: "INSERT...", allow_write: true })` - writes require allow_write
+- Destructive ops (DROP, TRUNCATE, ALTER) are blocked via MCP - use CLI
+
+**Via CLI**:
+- `jack services db execute "SELECT * FROM users"` - read queries
+- `jack services db execute "INSERT..." --write` - write queries
+- `jack services db execute "DROP TABLE..." --write` - prompts for typed confirmation
+- `jack services db execute --file schema.sql --write` - run SQL from file
+
+**Security notes**:
+- Read-only by default to prevent accidental data modification
+- Write operations require explicit `--write` flag or `allow_write: true`
+- Destructive operations (DROP, TRUNCATE, ALTER, DELETE without WHERE) require CLI confirmation
+- MCP results are wrapped with anti-injection headers to prevent prompt injection

package/templates/hello/AGENTS.md

@@ -0,0 +1,33 @@
+# Agent Context
+
+## Infrastructure
+
+This project uses **jack** for deployment. When Jack MCP is connected, prefer `mcp__jack__*` tools over CLI commands - they're cloud-aware and faster.
+
+**Do NOT use wrangler directly.** Jack manages config and may use cloud-hosted resources where wrangler won't work.
+
+Common operations:
+- **Deploy**: `jack ship` or Jack MCP
+- **Database**: `jack services db create` or Jack MCP
+- **Status**: `jack status` or Jack MCP
+
+## SQL Execution
+
+Jack supports secure SQL execution against D1 databases:
+
+**Via MCP** (preferred for agents):
+- `execute_sql({ sql: "SELECT * FROM users" })` - read queries work by default
+- `execute_sql({ sql: "INSERT...", allow_write: true })` - writes require allow_write
+- Destructive ops (DROP, TRUNCATE, ALTER) are blocked via MCP - use CLI
+
+**Via CLI**:
+- `jack services db execute "SELECT * FROM users"` - read queries
+- `jack services db execute "INSERT..." --write` - write queries
+- `jack services db execute "DROP TABLE..." --write` - prompts for typed confirmation
+- `jack services db execute --file schema.sql --write` - run SQL from file
+
+**Security notes**:
+- Read-only by default to prevent accidental data modification
+- Write operations require explicit `--write` flag or `allow_write: true`
+- Destructive operations (DROP, TRUNCATE, ALTER, DELETE without WHERE) require CLI confirmation
+- MCP results are wrapped with anti-injection headers to prevent prompt injection

package/templates/miniapp/.jack.json

@@ -39,10 +39,7 @@
 				"action": "box",
 				"title": "Deployed: {{name}}",
 				"lines": [
-					"URL: {{url}}",
-					"Manifest: {{url}}/.well-known/farcaster.json",
-					"",
-					"Next: Sign the manifest and paste accountAssociation when prompted"
+					"{{url}}"
 				]
 			},
 			{
@@ -72,7 +69,9 @@
 					"set": {
 						"accountAssociation": { "from": "input" }
 					}
-				}
+				},
+				"deployAfter": true,
+				"deployMessage": "Deploying manifest..."
 			},
 			{
 				"action": "url",

package/templates/miniapp/AGENTS.md

@@ -0,0 +1,33 @@
+# Agent Context
+
+## Infrastructure
+
+This project uses **jack** for deployment. When Jack MCP is connected, prefer `mcp__jack__*` tools over CLI commands - they're cloud-aware and faster.
+
+**Do NOT use wrangler directly.** Jack manages config and may use cloud-hosted resources where wrangler won't work.
+
+Common operations:
+- **Deploy**: `jack ship` or Jack MCP
+- **Database**: `jack services db create` or Jack MCP
+- **Status**: `jack status` or Jack MCP
+
+## SQL Execution
+
+Jack supports secure SQL execution against D1 databases:
+
+**Via MCP** (preferred for agents):
+- `execute_sql({ sql: "SELECT * FROM users" })` - read queries work by default
+- `execute_sql({ sql: "INSERT...", allow_write: true })` - writes require allow_write
+- Destructive ops (DROP, TRUNCATE, ALTER) are blocked via MCP - use CLI
+
+**Via CLI**:
+- `jack services db execute "SELECT * FROM users"` - read queries
+- `jack services db execute "INSERT..." --write` - write queries
+- `jack services db execute "DROP TABLE..." --write` - prompts for typed confirmation
+- `jack services db execute --file schema.sql --write` - run SQL from file
+
+**Security notes**:
+- Read-only by default to prevent accidental data modification
+- Write operations require explicit `--write` flag or `allow_write: true`
+- Destructive operations (DROP, TRUNCATE, ALTER, DELETE without WHERE) require CLI confirmation
+- MCP results are wrapped with anti-injection headers to prevent prompt injection

package/templates/nextjs/AGENTS.md

@@ -0,0 +1,33 @@
+# Agent Context
+
+## Infrastructure
+
+This project uses **jack** for deployment. When Jack MCP is connected, prefer `mcp__jack__*` tools over CLI commands - they're cloud-aware and faster.
+
+**Do NOT use wrangler directly.** Jack manages config and may use cloud-hosted resources where wrangler won't work.
+
+Common operations:
+- **Deploy**: `jack ship` or Jack MCP
+- **Database**: `jack services db create` or Jack MCP
+- **Status**: `jack status` or Jack MCP
+
+## SQL Execution
+
+Jack supports secure SQL execution against D1 databases:
+
+**Via MCP** (preferred for agents):
+- `execute_sql({ sql: "SELECT * FROM users" })` - read queries work by default
+- `execute_sql({ sql: "INSERT...", allow_write: true })` - writes require allow_write
+- Destructive ops (DROP, TRUNCATE, ALTER) are blocked via MCP - use CLI
+
+**Via CLI**:
+- `jack services db execute "SELECT * FROM users"` - read queries
+- `jack services db execute "INSERT..." --write` - write queries
+- `jack services db execute "DROP TABLE..." --write` - prompts for typed confirmation
+- `jack services db execute --file schema.sql --write` - run SQL from file
+
+**Security notes**:
+- Read-only by default to prevent accidental data modification
+- Write operations require explicit `--write` flag or `allow_write: true`
+- Destructive operations (DROP, TRUNCATE, ALTER, DELETE without WHERE) require CLI confirmation
+- MCP results are wrapped with anti-injection headers to prevent prompt injection