@getjack/jack 0.1.32 → 0.1.33

package/src/lib/project-operations.ts

@@ -102,6 +102,7 @@ export interface DeployOptions {
 	managed?: boolean; // Force managed deploy mode
 	byo?: boolean; // Force BYO deploy mode
 	dryRun?: boolean; // Stop before actual deployment
+	message?: string; // Deploy message describing what changed
 }
 
 export interface DeployResult {
@@ -109,6 +110,9 @@ export interface DeployResult {
 	projectName: string;
 	deployOutput?: string;
 	deployMode: DeployMode; // The deploy mode used
+	deploymentId?: string;
+	deployStatus?: string;
+	errorMessage?: string | null;
 }
 
 export interface ProjectStatus {
@@ -126,6 +130,12 @@ export interface ProjectStatus {
 	missing: boolean;
 	backupFiles: number | null;
 	backupLastSync: string | null;
+	// Deploy tracking (managed projects only)
+	lastDeployAt: string | null;
+	deployCount: number;
+	lastDeployStatus: string | null;
+	lastDeploySource: string | null;
+	lastDeployMessage: string | null;
 }
 
 export interface StaleProject {
@@ -361,6 +371,7 @@ async function runParallelSetup(
 	options: {
 		template?: string;
 		usePrebuilt?: boolean;
+		forkedFrom?: string;
 		onRemoteReady?: (result: ManagedCreateResult) => void;
 	},
 ): Promise<{
@@ -391,6 +402,7 @@ async function runParallelSetup(
 	const remotePromise = createManagedProjectRemote(projectName, undefined, {
 		template: options.template || "hello",
 		usePrebuilt: options.usePrebuilt ?? true,
+		forkedFrom: options.forkedFrom,
 	}).then((result) => {
 		const duration = ((Date.now() - remoteStart) / 1000).toFixed(1);
 		debug(`Remote project created in ${duration}s (status: ${result.status})`);
@@ -793,11 +805,25 @@ export async function createProject(
 		}
 	}
 
-	// Check if jack init was run (throws if not)
+	// Auto-initialize on first run (replaces "Run: jack init" error)
 	const { isInitialized } = await import("../commands/init.ts");
 	const initialized = await isInitialized();
 	if (!initialized) {
-		throw new JackError(JackErrorCode.VALIDATION_ERROR, "jack is not set up yet", "Run: jack init");
+		const { writeConfig, readConfig } = await import("./config.ts");
+		const existingConfig = await readConfig();
+		await writeConfig({
+			version: 1,
+			initialized: true,
+			initializedAt: existingConfig?.initializedAt || new Date().toISOString(),
+			...existingConfig,
+		});
+
+		// Best-effort MCP config install (non-blocking)
+		try {
+			const { installMcpConfigsToAllApps, saveMcpConfig } = await import("./mcp-config.ts");
+			await installMcpConfigsToAllApps();
+			await saveMcpConfig();
+		} catch {}
 	}
 
 	// Auth gate - check/prompt for authentication before any work
@@ -1199,9 +1225,11 @@ export async function createProject(
 			reporter.start("Setting up project...");
 
 			try {
+				const forkedFrom = templateOrigin.type !== "builtin" ? templateOrigin.name : undefined;
 				const result = await runParallelSetup(targetDir, projectName, {
 					template: resolvedTemplate || "hello",
 					usePrebuilt: templateOrigin.type === "builtin", // Only builtin templates have prebuilt bundles
+					forkedFrom,
 					onRemoteReady: (remote) => {
 						// Show URL immediately when prebuilt succeeds
 						reporter.stop();
@@ -1355,22 +1383,8 @@ export async function createProject(
 					reporter.success(`Deployed: ${workerUrl}`);
 				}
 
-				// Upload source snapshot for forking (prebuilt path needs this too)
-				try {
-					const { createSourceZip } = await import("./zip-packager.ts");
-					const { uploadSourceSnapshot } = await import("./control-plane.ts");
-					const { rm } = await import("node:fs/promises");
-
-					const sourceZipPath = await createSourceZip(targetDir);
-					await uploadSourceSnapshot(remoteResult.projectId, sourceZipPath);
-					await rm(sourceZipPath, { force: true });
-					debug("Source snapshot uploaded for prebuilt project");
-				} catch (err) {
-					debug(
-						"Source snapshot upload failed (prebuilt):",
-						err instanceof Error ? err.message : String(err),
-					);
-				}
+				// source.zip is now stored in deployment artifacts by the control plane
+				// during prebuilt deploy — no client-side upload needed
 			} else {
 				// Prebuilt not available - fall back to fresh build
 				if (remoteResult.prebuiltFailed) {
@@ -1688,11 +1702,10 @@ export async function deployProject(options: DeployOptions = {}): Promise<Deploy
 		deployMode = link?.deploy_mode ?? "byo";
 	}
 
-	// Ensure agent integration is set up (JACK.md, MCP config)
+	// Ensure agent integration is set up (MCP config)
 	// This is idempotent and runs silently
 	try {
 		await ensureAgentIntegration(projectPath, {
-			projectName,
 			silent: true,
 		});
 	} catch (err) {
@@ -1723,6 +1736,7 @@ export async function deployProject(options: DeployOptions = {}): Promise<Deploy
 
 	let workerUrl: string | null = null;
 	let deployOutput: string | undefined;
+	let managedDeployResult: { deploymentId: string; status: string; errorMessage: string | null } | undefined;
 
 	// Deploy based on mode
 	if (deployMode === "managed") {
@@ -1781,7 +1795,7 @@ export async function deployProject(options: DeployOptions = {}): Promise<Deploy
 		}
 
 		// deployToManagedProject now handles both template and code deploy
-		await deployToManagedProject(managedProjectId as string, projectPath, reporter);
+		managedDeployResult = await deployToManagedProject(managedProjectId as string, projectPath, reporter, options.message);
 
 		// Construct URL with username if available
 		workerUrl = link?.owner_username
@@ -1936,6 +1950,9 @@ export async function deployProject(options: DeployOptions = {}): Promise<Deploy
 		projectName,
 		deployOutput: workerUrl ? undefined : deployOutput,
 		deployMode,
+		deploymentId: managedDeployResult?.deploymentId,
+		deployStatus: managedDeployResult?.status,
+		errorMessage: managedDeployResult?.errorMessage,
 	};
 }
 
@@ -2025,11 +2042,35 @@ export async function getProjectStatus(
 		}
 	}
 
+	// Fetch real deployment data for managed projects
+	let lastDeployAt: string | null = null;
+	let deployCount = 0;
+	let lastDeployStatus: string | null = null;
+	let lastDeploySource: string | null = null;
+	let lastDeployMessage: string | null = null;
+
+	if (link?.deploy_mode === "managed") {
+		try {
+			const { fetchDeployments } = await import("./control-plane.ts");
+			const result = await fetchDeployments(link.project_id);
+			deployCount = result.total;
+			const latest = result.deployments[0];
+			if (latest) {
+				lastDeployAt = latest.created_at;
+				lastDeployStatus = latest.status;
+				lastDeploySource = latest.source;
+				lastDeployMessage = latest.message;
+			}
+		} catch {
+			// Silent fail — deploy tracking is supplementary
+		}
+	}
+
 	return {
 		name: projectName,
 		localPath,
 		workerUrl,
-		lastDeployed: link?.linked_at ?? null,
+		lastDeployed: lastDeployAt ?? link?.linked_at ?? null,
 		createdAt: link?.linked_at ?? null,
 		accountId: null, // No longer stored in registry
 		workerId: projectName,
@@ -2040,6 +2081,11 @@ export async function getProjectStatus(
 		missing: false,
 		backupFiles,
 		backupLastSync,
+		lastDeployAt,
+		deployCount,
+		lastDeployStatus,
+		lastDeploySource,
+		lastDeployMessage,
 	};
 }
 

package/src/lib/telemetry.ts

@@ -47,6 +47,8 @@ export const Events = {
 	// Token management events
 	TOKEN_CREATED: "token_created",
 	TOKEN_REVOKED: "token_revoked",
+	// Hook events
+	HOOK_SESSION_CONTEXT: "hook_session_context",
 } as const;
 
 type EventName = (typeof Events)[keyof typeof Events];

package/src/mcp/README.md

@@ -25,7 +25,7 @@ src/mcp/
 ### `tools/index.ts`
 - Centralized tool registration and dispatch
 - Implements 4 core tools:
-  - `create_project` - Create new Cloudflare Workers project
+  - `create_project` - Create new project (supports forking via template)
   - `deploy_project` - Deploy existing project
   - `get_project_status` - Get project status info
   - `list_projects` - List all projects with filters

package/src/mcp/resources/index.ts

@@ -74,30 +74,15 @@ export function registerResources(
 
 		if (uri === "agents://context") {
 			const projectPath = options.projectPath ?? process.cwd();
-			const jackPath = join(projectPath, "JACK.md");
 			const agentsPath = join(projectPath, "AGENTS.md");
 			const claudePath = join(projectPath, "CLAUDE.md");
 
 			const contents: string[] = [];
 
-			// Try to read JACK.md first (jack-specific context)
-			if (existsSync(jackPath)) {
-				try {
-					const jackContent = await Bun.file(jackPath).text();
-					contents.push("# JACK.md\n\n");
-					contents.push(jackContent);
-				} catch {
-					// Ignore read errors
-				}
-			}
-
 			// Try to read AGENTS.md
 			if (existsSync(agentsPath)) {
 				try {
 					const agentsContent = await Bun.file(agentsPath).text();
-					if (contents.length > 0) {
-						contents.push("\n\n---\n\n");
-					}
 					contents.push("# AGENTS.md\n\n");
 					contents.push(agentsContent);
 				} catch {
@@ -143,7 +128,7 @@ If connected, prefer \`mcp__jack__*\` tools over CLI:
 
 Full docs: https://docs.getjack.org/llms-full.txt
 
-Check for JACK.md in the project root for project-specific instructions.
+Check AGENTS.md in the project root for project-specific instructions.
 `;
 				return {
 					contents: [

package/src/mcp/server.ts

@@ -43,8 +43,31 @@ export async function createMcpServer(options: McpServerOptions = {}) {
 	return { server, debug };
 }
 
+/**
+ * Install runtime guards that prevent accidental stdout writes from corrupting
+ * the MCP JSON-RPC stdio transport. This catches console.log() and
+ * process.stdout.write() but NOT Bun.spawn({ stdout: "inherit" }) which writes
+ * directly to fd 1 — that case is handled by the `interactive` flag in hooks.
+ */
+function installStdoutGuards() {
+	// Redirect console.log to stderr so accidental calls don't corrupt the stream.
+	// We don't wrap process.stdout.write because the MCP SDK writes JSON-RPC
+	// messages through it — intercepting those risks breaking the protocol if
+	// messages are chunked or newlines are written separately.
+	console.log = (...args: unknown[]) => {
+		console.error(
+			"[jack-mcp] WARNING: console.log intercepted (would corrupt MCP protocol):",
+			...args,
+		);
+	};
+}
+
 export async function startMcpServer(options: McpServerOptions = {}) {
 	const { server, debug } = await createMcpServer(options);
+
+	// Install stdout guards BEFORE connecting transport to prevent corruption
+	installStdoutGuards();
+
 	const transport = new StdioServerTransport();
 
 	debug("Starting MCP server on stdio transport");

package/src/mcp/tools/index.ts

@@ -7,6 +7,10 @@ import { JackError, JackErrorCode } from "../../lib/errors.ts";
 import { getDeployMode, getProjectId } from "../../lib/project-link.ts";
 import { createProject, deployProject, getProjectStatus } from "../../lib/project-operations.ts";
 import { listAllProjects } from "../../lib/project-resolver.ts";
+import { createCronSchedule } from "../../lib/services/cron-create.ts";
+import { deleteCronSchedule } from "../../lib/services/cron-delete.ts";
+import { listCronSchedules } from "../../lib/services/cron-list.ts";
+import { testCronExpression } from "../../lib/services/cron-test.ts";
 import { createDatabase } from "../../lib/services/db-create.ts";
 import {
 	DestructiveOperationError,
@@ -15,10 +19,6 @@ import {
 	wrapResultsForMcp,
 } from "../../lib/services/db-execute.ts";
 import { listDatabases } from "../../lib/services/db-list.ts";
-import { createCronSchedule } from "../../lib/services/cron-create.ts";
-import { deleteCronSchedule } from "../../lib/services/cron-delete.ts";
-import { listCronSchedules } from "../../lib/services/cron-list.ts";
-import { testCronExpression } from "../../lib/services/cron-test.ts";
 import {
 	assignDomain,
 	connectDomain,
@@ -41,7 +41,12 @@ 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')"),
+	template: z
+		.string()
+		.optional()
+		.describe(
+			"Template to use (e.g., 'miniapp', 'api'). Also supports forking: use 'username/slug' for published projects or 'my-project' to fork your own.",
+		),
 });
 
 const DeployProjectSchema = z.object({
@@ -49,6 +54,12 @@ const DeployProjectSchema = z.object({
 		.string()
 		.optional()
 		.describe("Path to project directory (defaults to current directory)"),
+	message: z
+		.string()
+		.optional()
+		.describe(
+			"Deploy message describing what changed and why (e.g., 'Add user auth', 'Fix CORS bug')",
+		),
 });
 
 const GetProjectStatusSchema = z.object({
@@ -200,6 +211,19 @@ const TailLogsSchema = z.object({
 		.describe("How long to listen before returning (default: 2000ms, max: 10000ms)"),
 });
 
+const RollbackProjectSchema = z.object({
+	deployment_id: z
+		.string()
+		.optional()
+		.describe(
+			"Specific deployment ID to roll back to (defaults to previous successful deployment)",
+		),
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+});
+
 const ListDomainsSchema = z.object({});
 
 const ConnectDomainSchema = z.object({
@@ -220,7 +244,9 @@ const DisconnectDomainSchema = z.object({
 });
 
 const CreateCronSchema = z.object({
-	expression: z.string().describe("Cron expression (e.g., '0 * * * *' for hourly, '*/15 * * * *' for every 15 min)"),
+	expression: z
+		.string()
+		.describe("Cron expression (e.g., '0 * * * *' for hourly, '*/15 * * * *' for every 15 min)"),
 	project_path: z
 		.string()
 		.optional()
@@ -264,7 +290,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 				{
 					name: "create_project",
 					description:
-						"Create a new Cloudflare Workers project from a template. Automatically installs dependencies, deploys to Cloudflare, and registers the project.",
+						"Create a new project from a template. Automatically installs dependencies, deploys, and registers the project. Also supports forking: pass a 'username/slug' template to fork a published project, or a project slug to fork your own.",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -274,7 +300,8 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 							},
 							template: {
 								type: "string",
-								description: "Template to use (e.g., 'miniapp', 'api')",
+								description:
+									"Template to use (e.g., 'miniapp', 'api'). Also supports forking: use 'username/slug' for published projects or 'my-project' to fork your own.",
 							},
 						},
 					},
@@ -282,7 +309,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 				{
 					name: "deploy_project",
 					description:
-						"Deploy an existing project to Cloudflare Workers. Builds the project if needed and pushes to production.",
+						"Deploy an existing project. Builds if needed and pushes to production. Always provide a 'message' describing what changed and why (e.g., 'Add user auth', 'Fix CORS bug').",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -290,13 +317,18 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 								type: "string",
 								description: "Path to project directory (defaults to current directory)",
 							},
+							message: {
+								type: "string",
+								description:
+									"Deploy message describing what changed and why (e.g., 'Add user auth', 'Fix CORS bug')",
+							},
 						},
 					},
 				},
 				{
 					name: "get_project_status",
 					description:
-						"Get detailed status information for a specific project, including deployment status, local path, and backup status.",
+						"Get live deployment state: URL, last deploy time, deploy count, status (live/failed), and deploy source. Call this first to understand what's currently deployed before making changes.",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -347,7 +379,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 				{
 					name: "tail_logs",
 					description:
-						"Collect a short sample of live log events (JSON) from a managed (jack cloud) project. Useful for agentic debugging.",
+						"Collect live log events from production. Use after deploying to verify changes work, or to debug errors. Returns JSON log entries with timestamps and messages.",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -370,6 +402,27 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 						},
 					},
 				},
+				{
+					name: "rollback_project",
+					description:
+						"Roll back a managed (jack cloud) project to a previous deployment. " +
+						"Defaults to the previous successful deployment if no deployment_id is specified. " +
+						"Only rolls back code — database state and secrets are unchanged.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							deployment_id: {
+								type: "string",
+								description:
+									"Specific deployment ID to roll back to (defaults to previous successful deployment)",
+							},
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+						},
+					},
+				},
 				{
 					name: "create_database",
 					description:
@@ -654,13 +707,14 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 				{
 					name: "create_cron",
 					description:
-						"Create a cron schedule for a managed (Jack Cloud) project. Minimum interval is 15 minutes. The worker must have a scheduled() handler or POST /__scheduled route.",
+						"Create a cron schedule for a managed (Jack Cloud) project. Minimum interval is 15 minutes. The worker must handle POST /__scheduled requests — Cloudflare's native scheduled() export does not work with Jack Cloud crons.",
 					inputSchema: {
 						type: "object",
 						properties: {
 							expression: {
 								type: "string",
-								description: "Cron expression (e.g., '0 * * * *' for hourly, '*/15 * * * *' for every 15 min)",
+								description:
+									"Cron expression (e.g., '0 * * * *' for hourly, '*/15 * * * *' for every 15 min)",
 							},
 							project_path: {
 								type: "string",
@@ -719,7 +773,8 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 							trigger_production: {
 								type: "boolean",
 								default: false,
-								description: "Whether to trigger the cron handler on production (requires managed project)",
+								description:
+									"Whether to trigger the cron handler on production (requires managed project)",
 							},
 						},
 						required: ["expression"],
@@ -777,12 +832,13 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 
 					const wrappedDeployProject = withTelemetry(
 						"deploy_project",
-						async (projectPath?: string) => {
+						async (projectPath?: string, message?: string) => {
 							const result = await deployProject({
 								projectPath,
 								interactive: false,
 								includeSecrets: false,
 								includeSync: false,
+								message,
 							});
 
 							// Track business event
@@ -795,7 +851,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 						{ platform: "mcp" },
 					);
 
-					const result = await wrappedDeployProject(args.project_path);
+					const result = await wrappedDeployProject(args.project_path, args.message);
 
 					return {
 						content: [
@@ -1046,6 +1102,60 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 					};
 				}
 
+				case "rollback_project": {
+					const args = RollbackProjectSchema.parse(request.params.arguments ?? {});
+					const projectPath = args.project_path ?? process.cwd();
+
+					const deployMode = await getDeployMode(projectPath);
+					if (deployMode !== "managed") {
+						throw new JackError(
+							JackErrorCode.VALIDATION_ERROR,
+							"Rollback is only available for managed (jack cloud) projects",
+							"For BYOC projects, use wrangler to manage deployments.",
+						);
+					}
+
+					const projectId = await getProjectId(projectPath);
+					if (!projectId) {
+						throw new JackError(
+							JackErrorCode.PROJECT_NOT_FOUND,
+							"Project not found",
+							"Run this from a linked jack cloud project directory (has .jack/project.json).",
+						);
+					}
+
+					// Import rollbackDeployment from control-plane
+					const { rollbackDeployment } = await import("../../lib/control-plane.ts");
+
+					const wrappedRollback = withTelemetry(
+						"rollback_project",
+						async (id: string, deploymentId?: string) => rollbackDeployment(id, deploymentId),
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedRollback(projectId, args.deployment_id);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(
+									formatSuccessResponse(
+										{
+											...result.deployment,
+											message:
+												"Code rolled back successfully. Database state and secrets are unchanged.",
+										},
+										startTime,
+									),
+									null,
+									2,
+								),
+							},
+						],
+					};
+				}
+
 				case "create_database": {
 					const args = CreateDatabaseSchema.parse(request.params.arguments ?? {});
 					const projectPath = args.project_path ?? process.cwd();
@@ -1268,7 +1378,13 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 						content: [
 							{
 								type: "text",
-								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+								text: JSON.stringify(
+									formatSuccessResponse(result, startTime, [
+										"Vectorize indexes have eventual consistency. Newly inserted vectors typically take 2-3 minutes to become queryable.",
+									]),
+									null,
+									2,
+								),
 							},
 						],
 					};

package/src/mcp/types.ts

@@ -5,6 +5,7 @@
 export interface McpToolResponse<T = unknown> {
 	success: boolean;
 	data?: T;
+	notes?: string[]; // Situational context for AI agents (e.g. eventual consistency caveats)
 	error?: {
 		code: string; // Machine-readable: 'AUTH_FAILED', 'PROJECT_NOT_FOUND'
 		message: string; // Human-readable description

package/src/mcp/utils.ts

@@ -5,10 +5,11 @@ import { McpErrorCode, type McpToolResponse } from "./types.ts";
 /**
  * Format a successful MCP tool response
  */
-export function formatSuccessResponse<T>(data: T, startTime: number): McpToolResponse<T> {
+export function formatSuccessResponse<T>(data: T, startTime: number, notes?: string[]): McpToolResponse<T> {
 	return {
 		success: true,
 		data,
+		...(notes?.length && { notes }),
 		meta: {
 			duration_ms: Date.now() - startTime,
 			jack_version: packageJson.version,