@getjack/jack 0.1.32 → 0.1.33

package/src/lib/agent-integration.ts

@@ -1,165 +1,18 @@
 /**
  * Agent integration module
  *
- * Ensures AI agents have proper context for jack projects.
+ * Ensures AI agents have MCP configured 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;
 }
 
 /**
@@ -186,31 +39,16 @@ async function ensureMcpConfigured(): Promise<string[]> {
 /**
  * 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
- *
+ * Installs MCP config to detected AI apps.
  * Safe to call multiple times - all operations are idempotent.
  */
 export async function ensureAgentIntegration(
-	projectPath: string,
-	options: EnsureAgentOptions = {},
+	_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/claude-hooks-installer.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+const HOOK_COMMAND = "jack mcp context 2>/dev/null || true";
+
+/**
+ * Install a Claude Code SessionStart hook to the project's .claude/settings.json.
+ * Only fires when Claude Code is opened in this project directory.
+ * Non-destructive: preserves existing hooks and deduplicates.
+ */
+export async function installClaudeCodeHooks(projectPath: string): Promise<boolean> {
+	try {
+		const claudeDir = join(projectPath, ".claude");
+		const settingsPath = join(claudeDir, "settings.json");
+
+		// Ensure .claude directory exists
+		if (!existsSync(claudeDir)) {
+			await mkdir(claudeDir, { recursive: true });
+		}
+
+		let settings: Record<string, unknown> = {};
+		if (existsSync(settingsPath)) {
+			try {
+				settings = await Bun.file(settingsPath).json();
+			} catch {
+				settings = {};
+			}
+		}
+
+		const hooks = (settings.hooks as Record<string, unknown[]>) ?? {};
+		const sessionStart = (hooks.SessionStart as Array<Record<string, unknown>>) ?? [];
+
+		// Check if jack hook is already installed
+		for (const entry of sessionStart) {
+			const entryHooks = entry.hooks as Array<Record<string, string>> | undefined;
+			if (entryHooks?.some((h) => h.command?.includes("jack mcp context"))) {
+				return true;
+			}
+		}
+
+		sessionStart.push({
+			matcher: "",
+			hooks: [{ type: "command", command: HOOK_COMMAND }],
+		});
+
+		hooks.SessionStart = sessionStart;
+		settings.hooks = hooks;
+
+		await Bun.write(settingsPath, JSON.stringify(settings, null, 2));
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/lib/control-plane.ts

@@ -3,7 +3,6 @@
  */
 
 import { debug } from "./debug.ts";
-import { formatSize } from "./format.ts";
 
 const DEFAULT_CONTROL_API_URL = "https://control.getjack.org";
 
@@ -16,12 +15,14 @@ export interface CreateProjectRequest {
 	slug?: string;
 	template?: string;
 	use_prebuilt?: boolean;
+	forked_from?: string;
 }
 
 export interface CreateManagedProjectOptions {
 	slug?: string;
 	template?: string;
 	usePrebuilt?: boolean;
+	forkedFrom?: string;
 }
 
 export interface CreateProjectResponse {
@@ -111,6 +112,9 @@ export async function createManagedProject(
 	if (options?.usePrebuilt !== undefined) {
 		requestBody.use_prebuilt = options.usePrebuilt;
 	}
+	if (options?.forkedFrom) {
+		requestBody.forked_from = options.forkedFrom;
+	}
 
 	debug("Creating managed project", {
 		name,
@@ -451,6 +455,79 @@ export async function fetchProjectResources(projectId: string): Promise<ProjectR
 	return data.resources;
 }
 
+export interface DeploymentInfo {
+	id: string;
+	status: "queued" | "building" | "live" | "failed";
+	source: string;
+	error_message: string | null;
+	message: string | null;
+	created_at: string;
+	updated_at: string;
+}
+
+export interface DeploymentListResult {
+	deployments: DeploymentInfo[];
+	total: number;
+}
+
+/**
+ * Fetch recent deployments for a managed project.
+ * Returns deployments (up to 10) and total count.
+ */
+export async function fetchDeployments(projectId: string): Promise<DeploymentListResult> {
+	const { authFetch } = await import("./auth/index.ts");
+
+	const response = await authFetch(`${getControlApiUrl()}/v1/projects/${projectId}/deployments`);
+
+	if (!response.ok) {
+		return { deployments: [], total: 0 }; // Silent fail — deployment history is supplementary
+	}
+
+	const data = (await response.json()) as { deployments: DeploymentInfo[]; total: number };
+	return { deployments: data.deployments, total: data.total };
+}
+
+export interface RollbackResponse {
+	deployment: {
+		id: string;
+		status: string;
+		source: string;
+		created_at: string;
+		updated_at: string;
+	};
+}
+
+/**
+ * Rollback a managed project to a previous deployment.
+ * If no deploymentId given, rolls back to the previous successful deployment.
+ */
+export async function rollbackDeployment(
+	projectId: string,
+	deploymentId?: string,
+): Promise<RollbackResponse> {
+	const { authFetch } = await import("./auth/index.ts");
+
+	const body: Record<string, string> = {};
+	if (deploymentId) {
+		body.deployment_id = deploymentId;
+	}
+
+	const response = await authFetch(`${getControlApiUrl()}/v1/projects/${projectId}/rollback`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+	});
+
+	if (!response.ok) {
+		const err = (await response.json().catch(() => ({ message: "Unknown error" }))) as {
+			message?: string;
+		};
+		throw new Error(err.message || `Rollback failed: ${response.status}`);
+	}
+
+	return response.json() as Promise<RollbackResponse>;
+}
+
 /**
  * Create a resource for a managed project.
  * Uses POST /v1/projects/:id/resources/:type endpoint.
@@ -715,45 +792,6 @@ export async function getCurrentUserProfile(): Promise<UserProfile | null> {
 	}
 }
 
-export interface SourceSnapshotResponse {
-	success: boolean;
-	source_key: string;
-}
-
-/**
- * Upload a source snapshot for a project.
- * Used to enable project forking.
- */
-export async function uploadSourceSnapshot(
-	projectId: string,
-	sourceZipPath: string,
-): Promise<SourceSnapshotResponse> {
-	const { authFetch } = await import("./auth/index.ts");
-
-	const formData = new FormData();
-	const sourceFile = Bun.file(sourceZipPath);
-	formData.append("source", sourceFile);
-
-	const url = `${getControlApiUrl()}/v1/projects/${projectId}/source`;
-	debug(`Source snapshot: ${formatSize(sourceFile.size)}`);
-
-	const start = Date.now();
-	const response = await authFetch(url, {
-		method: "POST",
-		body: formData,
-	});
-	debug(`Source snapshot: ${response.status} (${((Date.now() - start) / 1000).toFixed(1)}s)`);
-
-	if (!response.ok) {
-		const error = (await response.json().catch(() => ({ message: "Upload failed" }))) as {
-			message?: string;
-		};
-		throw new Error(error.message || `Source upload failed: ${response.status}`);
-	}
-
-	return response.json() as Promise<SourceSnapshotResponse>;
-}
-
 /**
  * Publish a project to make it forkable by others.
  */

package/src/lib/debug.ts

@@ -1,6 +1,7 @@
 // Debug utilities for timing and verbose logging
 
-let debugEnabled = false;
+let debugEnabled =
+	process.env.JACK_DEBUG === "1" || process.env.JACK_DEBUG === "true";
 const timers: Map<string, number> = new Map();
 const startTime = Date.now();
 

package/src/lib/deploy-upload.ts

@@ -18,6 +18,7 @@ export interface DeployUploadOptions {
 	secretsPath?: string;
 	assetsZipPath?: string;
 	assetManifest?: AssetManifest;
+	message?: string;
 }
 
 export interface DeployUploadResult {
@@ -25,6 +26,7 @@ export interface DeployUploadResult {
 	project_id: string;
 	status: "queued" | "building" | "live" | "failed";
 	source: string;
+	error_message: string | null;
 	created_at: string;
 }
 
@@ -91,6 +93,10 @@ export async function uploadDeployment(options: DeployUploadOptions): Promise<De
 		totalSize += manifestJson.length;
 	}
 
+	if (options.message) {
+		formData.append("message", options.message);
+	}
+
 	const prepareMs = Date.now() - prepareStart;
 	debug(`Payload ready: ${formatSize(totalSize)} (${prepareMs}ms)`);
 

package/src/lib/hooks.ts

@@ -702,7 +702,9 @@ const actionHandlers: {
 		const proc = Bun.spawn(["sh", "-c", command], {
 			cwd,
 			stdin: interactive ? "inherit" : "ignore",
-			stdout: "inherit",
+			// In non-interactive mode (MCP), stdout must NOT inherit because it would
+			// write into the JSON-RPC stdio transport and corrupt the protocol.
+			stdout: interactive ? "inherit" : "pipe",
 			stderr: "inherit",
 		});
 		await proc.exited;

package/src/lib/managed-deploy.ts

@@ -7,7 +7,7 @@
 import { stat } from "node:fs/promises";
 import { validateBindings } from "./binding-validator.ts";
 import { buildProject, parseWranglerConfig } from "./build-helper.ts";
-import { createManagedProject, syncProjectTags, uploadSourceSnapshot } from "./control-plane.ts";
+import { createManagedProject, syncProjectTags } from "./control-plane.ts";
 import { debug } from "./debug.ts";
 import { uploadDeployment } from "./deploy-upload.ts";
 import { JackError, JackErrorCode } from "./errors.ts";
@@ -31,6 +31,7 @@ export interface ManagedCreateResult {
 export interface ManagedCreateOptions {
 	template?: string;
 	usePrebuilt?: boolean;
+	forkedFrom?: string;
 }
 
 /**
@@ -50,6 +51,7 @@ export async function createManagedProjectRemote(
 		const result = await createManagedProject(projectName, {
 			template: options?.template,
 			usePrebuilt: options?.usePrebuilt ?? true,
+			forkedFrom: options?.forkedFrom,
 		});
 
 		const runjackUrl = result.url || `https://${result.project.slug}.runjack.xyz`;
@@ -79,6 +81,7 @@ export interface ManagedCodeDeployOptions {
 	projectId: string;
 	projectPath: string;
 	reporter?: OperationReporter;
+	message?: string;
 }
 
 /**
@@ -88,7 +91,7 @@ export interface ManagedCodeDeployOptions {
  */
 export async function deployCodeToManagedProject(
 	options: ManagedCodeDeployOptions,
-): Promise<{ deploymentId: string; status: string }> {
+): Promise<{ deploymentId: string; status: string; errorMessage: string | null }> {
 	const { projectId, projectPath, reporter } = options;
 
 	// Track deploy start
@@ -161,6 +164,7 @@ export async function deployCodeToManagedProject(
 			secretsPath: pkg.secretsPath ?? undefined,
 			assetsZipPath: pkg.assetsZipPath ?? undefined,
 			assetManifest: pkg.assetManifest ?? undefined,
+			message: options.message,
 		});
 
 		uploadProgress.complete();
@@ -183,16 +187,13 @@ export async function deployCodeToManagedProject(
 			})
 			.catch(() => {});
 
-		// Upload source snapshot for forking (non-fatal, but must await before cleanup)
-		try {
-			await uploadSourceSnapshot(projectId, pkg.sourceZipPath);
-		} catch (err) {
-			debug("Source snapshot upload failed:", err instanceof Error ? err.message : String(err));
-		}
+		// Source snapshot for forking is now derived from deployment artifacts on the control plane.
+		// No separate upload needed — clone/fork reads from the latest live deployment's source.zip.
 
 		return {
 			deploymentId: result.id,
 			status: result.status,
+			errorMessage: result.error_message,
 		};
 	} catch (error) {
 		reporter?.stop();
@@ -218,10 +219,12 @@ export async function deployToManagedProject(
 	projectId: string,
 	projectPath: string,
 	reporter?: OperationReporter,
-): Promise<{ deploymentId: string; status: string }> {
+	message?: string,
+): Promise<{ deploymentId: string; status: string; errorMessage: string | null }> {
 	return deployCodeToManagedProject({
 		projectId,
 		projectPath,
 		reporter,
+		message,
 	});
 }

package/src/lib/project-link.ts

@@ -116,6 +116,12 @@ export async function linkProject(
 
 	// Auto-add .jack/ to .gitignore
 	await ensureGitignored(projectDir);
+
+	// Install Claude Code SessionStart hook to project-level .claude/settings.json
+	// Non-blocking, fire-and-forget — never delays project linking
+	import("./claude-hooks-installer.ts")
+		.then(({ installClaudeCodeHooks }) => installClaudeCodeHooks(projectDir))
+		.catch(() => {});
 }
 
 /**