@getjack/jack 0.1.22 → 0.1.23

package/src/lib/agent-integration.ts

@@ -0,0 +1,217 @@
+/**
+ * Agent integration module
+ *
+ * Ensures AI agents have proper context for jack projects.
+ * Called during both project creation and first BYO deploy.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Template } from "../templates/types.ts";
+import { installMcpConfigsToAllApps, isAppInstalled } from "./mcp-config.ts";
+
+export interface EnsureAgentResult {
+	mcpInstalled: string[];
+	jackMdCreated: boolean;
+	referencesAdded: string[];
+}
+
+export interface EnsureAgentOptions {
+	template?: Template;
+	silent?: boolean;
+	projectName?: string;
+}
+
+/**
+ * Generate JACK.md content
+ * Uses template agentContext if available, otherwise generic jack instructions
+ */
+export function generateJackMd(projectName?: string, template?: Template): string {
+	const header = projectName ? `# ${projectName}\n\n` : "# Jack\n\n";
+
+	const templateSummary = template?.agentContext?.summary;
+	const templateFullText = template?.agentContext?.full_text;
+
+	const summarySection = templateSummary ? `> ${templateSummary}\n\n` : "";
+
+	const templateSection = templateFullText ? `${templateFullText}\n\n` : "";
+
+	return `${header}${summarySection}This project is deployed and managed via jack.
+
+## Quick Commands
+
+| Command | What it does |
+|---------|--------------|
+| \`jack ship\` | Deploy to production |
+| \`jack logs\` | Stream live logs |
+| \`jack services\` | Manage databases, KV, and other bindings |
+| \`jack secrets\` | Manage environment secrets |
+
+## Important
+
+- **Never run \`wrangler\` commands directly** - jack handles all infrastructure
+- Use \`jack services db\` to create and query databases
+- Secrets sync automatically across deploys
+
+## Services & Bindings
+
+Jack manages your project's services. To add a database:
+
+\`\`\`bash
+jack services db create
+\`\`\`
+
+To query it:
+
+\`\`\`bash
+jack services db query "SELECT * FROM users"
+\`\`\`
+
+More bindings (KV, R2, queues) coming soon.
+
+${templateSection}## For AI Agents
+
+### MCP Tools
+
+If jack MCP is connected, prefer these tools over CLI commands:
+
+| Tool | Use for |
+|------|---------|
+| \`mcp__jack__deploy_project\` | Deploy changes |
+| \`mcp__jack__create_database\` | Create a new database |
+| \`mcp__jack__execute_sql\` | Query the database |
+| \`mcp__jack__list_projects\` | List all projects |
+| \`mcp__jack__get_project_status\` | Check deployment status |
+
+### Documentation
+
+Full jack documentation: https://docs.getjack.org/llms-full.txt
+`;
+}
+
+/**
+ * Create JACK.md if it doesn't exist
+ */
+async function ensureJackMd(
+	projectPath: string,
+	projectName?: string,
+	template?: Template,
+): Promise<boolean> {
+	const jackMdPath = join(projectPath, "JACK.md");
+
+	if (existsSync(jackMdPath)) {
+		return false;
+	}
+
+	const content = generateJackMd(projectName, template);
+	await Bun.write(jackMdPath, content);
+	return true;
+}
+
+/**
+ * Append JACK.md reference to existing agent files (CLAUDE.md, AGENTS.md)
+ */
+async function appendJackMdReferences(projectPath: string): Promise<string[]> {
+	const filesToCheck = ["CLAUDE.md", "AGENTS.md"];
+	const referencesAdded: string[] = [];
+	const jackMdPath = join(projectPath, "JACK.md");
+
+	// Only add references if JACK.md exists
+	if (!existsSync(jackMdPath)) {
+		return referencesAdded;
+	}
+
+	const referenceBlock = `<!-- Added by jack -->
+> **Jack project** - See [JACK.md](./JACK.md) for deployment, services, and bindings.
+
+`;
+
+	for (const filename of filesToCheck) {
+		const filePath = join(projectPath, filename);
+
+		if (!existsSync(filePath)) {
+			continue;
+		}
+
+		try {
+			const content = await Bun.file(filePath).text();
+
+			// Skip if reference already exists
+			if (content.includes("JACK.md") || content.includes("<!-- Added by jack -->")) {
+				continue;
+			}
+
+			// Find position after first heading, or prepend if no heading
+			const headingMatch = content.match(/^#[^\n]*\n/m);
+			let newContent: string;
+
+			if (headingMatch && headingMatch.index !== undefined) {
+				const insertPos = headingMatch.index + headingMatch[0].length;
+				newContent =
+					content.slice(0, insertPos) + "\n" + referenceBlock + content.slice(insertPos);
+			} else {
+				newContent = referenceBlock + content;
+			}
+
+			await Bun.write(filePath, newContent);
+			referencesAdded.push(filename);
+		} catch {
+			// Ignore errors reading/writing individual files
+		}
+	}
+
+	return referencesAdded;
+}
+
+/**
+ * Ensure MCP is configured for detected AI apps
+ * Returns list of apps that were configured
+ */
+async function ensureMcpConfigured(): Promise<string[]> {
+	// Only attempt if at least one supported app is installed
+	const hasClaudeCode = isAppInstalled("claude-code");
+	const hasClaudeDesktop = isAppInstalled("claude-desktop");
+
+	if (!hasClaudeCode && !hasClaudeDesktop) {
+		return [];
+	}
+
+	try {
+		return await installMcpConfigsToAllApps();
+	} catch {
+		// Don't fail if MCP install fails
+		return [];
+	}
+}
+
+/**
+ * Ensure agent integration is set up for a project
+ *
+ * This function:
+ * 1. Creates JACK.md if not exists (with template context if available)
+ * 2. Appends JACK.md reference to existing CLAUDE.md/AGENTS.md
+ * 3. Installs MCP config to detected AI apps
+ *
+ * Safe to call multiple times - all operations are idempotent.
+ */
+export async function ensureAgentIntegration(
+	projectPath: string,
+	options: EnsureAgentOptions = {},
+): Promise<EnsureAgentResult> {
+	const { template, projectName } = options;
+
+	// 1. Create JACK.md if not exists
+	const jackMdCreated = await ensureJackMd(projectPath, projectName, template);
+
+	// 2. Append references to existing agent files
+	const referencesAdded = await appendJackMdReferences(projectPath);
+
+	// 3. Ensure MCP is configured
+	const mcpInstalled = await ensureMcpConfigured();
+
+	return {
+		mcpInstalled,
+		jackMdCreated,
+		referencesAdded,
+	};
+}

package/src/lib/auth/login-flow.ts

@@ -1,7 +1,8 @@
 /**
  * Shared login flow for CLI and programmatic use
  */
-import { isCancel, text } from "@clack/prompts";
+import { text } from "@clack/prompts";
+import { isCancel } from "../hooks.ts";
 import {
 	checkUsernameAvailable,
 	getCurrentUserProfile,

package/src/lib/binding-validator.ts

@@ -19,6 +19,7 @@ export const SUPPORTED_BINDINGS = [
 	"vars",
 	"r2_buckets",
 	"kv_namespaces",
+	"vectorize",
 ] as const;
 
 /**
@@ -30,7 +31,6 @@ export const UNSUPPORTED_BINDINGS = [
 	"queues",
 	"services",
 	"hyperdrive",
-	"vectorize",
 	"browser",
 	"mtls_certificates",
 ] as const;
@@ -43,7 +43,6 @@ const BINDING_DISPLAY_NAMES: Record<string, string> = {
 	queues: "Queues",
 	services: "Service Bindings",
 	hyperdrive: "Hyperdrive",
-	vectorize: "Vectorize",
 	browser: "Browser Rendering",
 	mtls_certificates: "mTLS Certificates",
 };
@@ -72,7 +71,7 @@ export function validateBindings(
 		if (value !== undefined && value !== null) {
 			const displayName = BINDING_DISPLAY_NAMES[binding] || binding;
 			errors.push(
-				`✗ ${displayName} not supported in managed deploy.\n  Managed deploy supports: D1, AI, Assets, R2, KV, vars.\n  Fix: Remove ${binding} from wrangler.jsonc, or use 'wrangler deploy' for full control.`,
+				`✗ ${displayName} not supported in managed deploy.\n  Managed deploy supports: D1, AI, Assets, R2, KV, Vectorize, vars.\n  Fix: Remove ${binding} from wrangler.jsonc, or use 'wrangler deploy' for full control.`,
 			);
 		}
 	}

package/src/lib/build-helper.ts

@@ -57,12 +57,18 @@ export interface WranglerConfig {
 		binding: string;
 		id?: string; // Optional - wrangler auto-provisions if missing
 	}>;
+	vectorize?: Array<{
+		binding: string;
+		index_name?: string;
+		preset?: "cloudflare" | "cloudflare-small" | "cloudflare-large";
+		dimensions?: number;
+		metric?: "cosine" | "euclidean" | "dot-product";
+	}>;
 	// Unsupported bindings (for validation)
 	durable_objects?: unknown;
 	queues?: unknown;
 	services?: unknown;
 	hyperdrive?: unknown;
-	vectorize?: unknown;
 	browser?: unknown;
 	mtls_certificates?: unknown;
 }

package/src/lib/hooks.ts

@@ -23,14 +23,13 @@ async function readMultilineJson(prompt: string): Promise<string> {
 
 	return new Promise((resolve) => {
 		rl.on("line", (line) => {
-			if (line.trim() === "" && lines.length > 0) {
+			// Empty line = submit (or skip if nothing entered)
+			if (line.trim() === "") {
 				rl.close();
 				resolve(lines.join("\n"));
 				return;
 			}
-			if (line.trim() !== "") {
-				lines.push(line);
-			}
+			lines.push(line);
 		});
 
 		rl.on("close", () => {
@@ -82,31 +81,112 @@ const noopOutput: HookOutput = {
  * - writeJson: { path, set, successMessage? } -> JSON update (runs in non-interactive)
  */
 
+// Re-export isCancel for consumers
+export { isCancel } from "@clack/core";
+
+// Unicode symbols (with ASCII fallbacks for non-unicode terminals)
+const isUnicodeSupported =
+	process.platform !== "win32" ||
+	Boolean(process.env.CI) ||
+	Boolean(process.env.WT_SESSION) ||
+	process.env.TERM_PROGRAM === "vscode" ||
+	process.env.TERM === "xterm-256color";
+
+const S_RADIO_ACTIVE = isUnicodeSupported ? "●" : ">";
+const S_RADIO_INACTIVE = isUnicodeSupported ? "○" : " ";
+
+export interface SelectOption<T = string> {
+	value: T;
+	label: string;
+	hint?: string;
+}
+
 /**
- * Prompt user with numbered options
- * Uses @clack/prompts selectKey for reliable input handling
- * Returns the selected option index (0-based) or -1 if cancelled
+ * Clean select prompt with bullet-point style (no vertical bars)
+ * Supports both:
+ * - Number keys (1, 2, 3...) for immediate selection
+ * - Arrow keys (up/down) + Enter for navigation-based selection
+ *
+ * @param message - The prompt message to display
+ * @param options - Array of options (strings or {value, label, hint?} objects)
+ * @returns The selected value, or symbol if cancelled
  */
-export async function promptSelect(options: string[]): Promise<number> {
-	const { selectKey, isCancel } = await import("@clack/prompts");
-
-	// Build options with number keys (1, 2, 3, ...)
-	const clackOptions = options.map((label, index) => ({
-		value: String(index + 1),
-		label,
-	}));
-
-	const result = await selectKey({
-		message: "",
-		options: clackOptions,
+export async function promptSelectValue<T>(
+	message: string,
+	options: Array<SelectOption<T> | string>,
+): Promise<T | symbol> {
+	const { SelectPrompt, isCancel } = await import("@clack/core");
+	const pc = await import("picocolors");
+
+	// Normalize options to {value, label} format
+	const normalizedOptions = options.map((opt, index) => {
+		if (typeof opt === "string") {
+			return { value: opt as T, label: opt, key: String(index + 1) };
+		}
+		return { ...opt, key: String(index + 1) };
+	});
+
+	const prompt = new SelectPrompt({
+		options: normalizedOptions,
+		initialValue: normalizedOptions[0]?.value,
+		render() {
+			const title = `${message}\n`;
+			const lines: string[] = [];
+
+			for (let i = 0; i < normalizedOptions.length; i++) {
+				const opt = normalizedOptions[i];
+				const isActive = this.cursor === i;
+				const num = `${i + 1}.`;
+
+				if (isActive) {
+					const hint = opt.hint ? pc.dim(` (${opt.hint})`) : "";
+					lines.push(`${pc.green(S_RADIO_ACTIVE)} ${num} ${opt.label}${hint}`);
+				} else {
+					lines.push(`${pc.dim(S_RADIO_INACTIVE)} ${pc.dim(num)} ${pc.dim(opt.label)}`);
+				}
+			}
+
+			return title + lines.join("\n");
+		},
 	});
 
+	// Add number key support for immediate selection
+	prompt.on("key", (char) => {
+		if (!char) return;
+		const num = Number.parseInt(char, 10);
+		if (num >= 1 && num <= normalizedOptions.length) {
+			prompt.value = normalizedOptions[num - 1]?.value;
+			prompt.emit("submit");
+		}
+	});
+
+	const result = await prompt.prompt();
+
+	if (isCancel(result)) {
+		return result;
+	}
+
+	return result as T;
+}
+
+/**
+ * Simple select prompt for string options (returns index)
+ * Supports both number keys (1, 2...) and arrow keys + Enter
+ * Returns the selected option index (0-based) or -1 if cancelled
+ */
+export async function promptSelect(options: string[], message?: string): Promise<number> {
+	const { isCancel } = await import("@clack/core");
+
+	const result = await promptSelectValue(
+		message ?? "",
+		options.map((label, index) => ({ value: index, label })),
+	);
+
 	if (isCancel(result)) {
 		return -1;
 	}
 
-	// Convert "1", "2", etc. back to 0-based index
-	return Number.parseInt(result as string, 10) - 1;
+	return result as number;
 }
 
 /**

package/src/lib/managed-down.ts

@@ -76,9 +76,12 @@ export async function managedDown(
 	}
 	console.error("");
 
-	// Confirm undeploy
+	// Single confirmation with clear description
 	console.error("");
-	info("Undeploy this project?");
+	const confirmMsg = hasDatabase
+		? "Undeploy this project? All resources will be deleted."
+		: "Undeploy this project?";
+	info(confirmMsg);
 	const action = await promptSelect(["Yes", "No"]);
 
 	if (action !== 0) {
@@ -86,77 +89,51 @@ export async function managedDown(
 		return false;
 	}
 
-	// Ask about database export (only if database exists)
+	// Auto-export database if it exists (no prompt)
+	let exportPath: string | null = null;
 	if (hasDatabase) {
-		console.error("");
-		info("Database will be deleted with the project");
+		exportPath = join(process.cwd(), `${projectName}-backup.sql`);
+		output.start(`Exporting database to ${exportPath}...`);
 
-		console.error("");
-		info("Export database before deleting?");
-		const exportAction = await promptSelect(["Yes", "No"]);
-
-		if (exportAction === 0) {
-			const exportPath = join(process.cwd(), `${projectName}-backup.sql`);
-			output.start(`Exporting database to ${exportPath}...`);
-
-			try {
-				const exportResult = await exportManagedDatabase(projectId);
-
-				// Download the SQL file
-				const response = await fetch(exportResult.download_url);
-				if (!response.ok) {
-					throw new Error(`Failed to download export: ${response.statusText}`);
-				}
-
-				const sqlContent = await response.text();
-				await writeFile(exportPath, sqlContent, "utf-8");
-
-				output.stop();
-				success(`Database exported to ${exportPath}`);
-			} catch (err) {
-				output.stop();
-				error(`Failed to export database: ${err instanceof Error ? err.message : String(err)}`);
-
-				// If export times out, abort
-				if (err instanceof Error && err.message.includes("timed out")) {
-					error("Export timeout - deletion aborted");
-					return false;
-				}
-
-				console.error("");
-				info("Continue without exporting?");
-				const continueAction = await promptSelect(["Yes", "No"]);
-
-				if (continueAction !== 0) {
-					info("Cancelled");
-					return false;
-				}
+		try {
+			const exportResult = await exportManagedDatabase(projectId);
+
+			// Download the SQL file
+			const response = await fetch(exportResult.download_url);
+			if (!response.ok) {
+				throw new Error(`Failed to download export: ${response.statusText}`);
 			}
+
+			const sqlContent = await response.text();
+			await writeFile(exportPath, sqlContent, "utf-8");
+
+			output.stop();
+		} catch (err) {
+			output.stop();
+			warn(`Could not export database: ${err instanceof Error ? err.message : String(err)}`);
+			exportPath = null;
 		}
 	}
 
 	// Execute deletion
-	console.error("");
-	info("Executing cleanup...");
-	console.error("");
-
 	output.start("Undeploying from jack cloud...");
 	try {
 		const result = await deleteManagedProject(projectId);
 		output.stop();
-		success(`'${projectName}' undeployed`);
 
-		// Report resource results
+		// Report any resource deletion failures
 		for (const resource of result.resources) {
-			if (resource.success) {
-				success(`Deleted ${resource.resource}`);
-			} else {
+			if (!resource.success) {
 				warn(`Failed to delete ${resource.resource}: ${resource.error}`);
 			}
 		}
 
+		// Final success message
 		console.error("");
-		success(`Project '${projectName}' undeployed`);
+		success(`Undeployed '${projectName}'`);
+		if (exportPath) {
+			info(`Backup saved to ./${projectName}-backup.sql`);
+		}
 		console.error("");
 		return true;
 	} catch (err) {

package/src/lib/project-detection.ts

@@ -34,6 +34,7 @@ interface PackageJson {
 	name?: string;
 	dependencies?: Record<string, string>;
 	devDependencies?: Record<string, string>;
+	workspaces?: string[] | { packages: string[] };
 }
 
 const CONFIG_EXTENSIONS = [".ts", ".js", ".mjs"];
@@ -212,6 +213,16 @@ export function detectProjectType(projectPath: string): DetectionResult {
 	const detectedDeps: string[] = [];
 	const configFiles: string[] = [];
 
+	// Check for monorepo - user is in wrong directory
+	if (pkg?.workspaces) {
+		const workspaces = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces.packages;
+		const hint = workspaces.length > 0 ? workspaces[0]?.replace("/*", "/your-app") : "apps/your-app";
+		return {
+			type: "unknown",
+			error: `This is a monorepo root, not a deployable project.\n\ncd into a package first:\n  cd ${hint}\n  jack ship`,
+		};
+	}
+
 	// Check for unsupported/coming-soon frameworks first (before reading package.json)
 	// This provides better error messages for frameworks we recognize but don't auto-deploy yet
 	const unsupported = detectUnsupportedFramework(projectPath, pkg);
@@ -363,6 +374,11 @@ function shouldExclude(relativePath: string): boolean {
 	return false;
 }
 
+// Derive skip directories from DEFAULT_EXCLUDES patterns (e.g., "node_modules/**" -> "node_modules")
+const SKIP_DIRECTORIES = new Set(
+	DEFAULT_EXCLUDES.filter((p) => p.endsWith("/**")).map((p) => p.slice(0, -3)),
+);
+
 export async function validateProject(projectPath: string): Promise<ValidationResult> {
 	if (!existsSync(join(projectPath, "package.json"))) {
 		return {
@@ -374,37 +390,41 @@ export async function validateProject(projectPath: string): Promise<ValidationRe
 	let fileCount = 0;
 	let totalSizeBytes = 0;
 
-	try {
-		const entries = await readdir(projectPath, {
-			recursive: true,
-			withFileTypes: true,
-		});
+	// Walk directory tree manually to skip excluded dirs early (don't descend into node_modules)
+	async function walkDir(dirPath: string): Promise<void> {
+		const entries = await readdir(dirPath, { withFileTypes: true });
 
 		for (const entry of entries) {
-			if (!entry.isFile()) {
+			// Skip excluded directories entirely (don't descend)
+			if (entry.isDirectory() && SKIP_DIRECTORIES.has(entry.name)) {
 				continue;
 			}
 
-			const parentDir = entry.parentPath ?? projectPath;
-			const absolutePath = join(parentDir, entry.name);
+			const absolutePath = join(dirPath, entry.name);
 			const relativePath = relative(projectPath, absolutePath);
 
-			if (shouldExclude(relativePath)) {
-				continue;
-			}
+			if (entry.isDirectory()) {
+				// Recursively walk subdirectories
+				await walkDir(absolutePath);
+			} else if (entry.isFile()) {
+				// Check glob-based exclusions for files
+				if (shouldExclude(relativePath)) {
+					continue;
+				}
 
-			fileCount++;
-			if (fileCount > MAX_FILES) {
-				return {
-					valid: false,
-					error: `Project has more than ${MAX_FILES} files (excluding node_modules, .git, etc.)`,
-					fileCount,
-				};
-			}
+				fileCount++;
+				if (fileCount > MAX_FILES) {
+					throw new Error(`Project has more than ${MAX_FILES} files (excluding node_modules, .git, etc.)`);
+				}
 
-			const stats = await stat(absolutePath);
-			totalSizeBytes += stats.size;
+				const stats = await stat(absolutePath);
+				totalSizeBytes += stats.size;
+			}
 		}
+	}
+
+	try {
+		await walkDir(projectPath);
 
 		const totalSizeKb = Math.round(totalSizeBytes / 1024);
 
@@ -423,6 +443,13 @@ export async function validateProject(projectPath: string): Promise<ValidationRe
 			totalSizeKb,
 		};
 	} catch (err) {
+		if (err instanceof Error && err.message.includes("more than")) {
+			return {
+				valid: false,
+				error: err.message,
+				fileCount,
+			};
+		}
 		return {
 			valid: false,
 			error: `Failed to scan project: ${err instanceof Error ? err.message : String(err)}`,