@getjack/jack 0.1.28 → 0.1.30

package/src/lib/clone-core.ts

@@ -0,0 +1,252 @@
+/**
+ * Clone Core - reusable clone logic for CLI and other callers
+ *
+ * This module extracts the core clone functionality from the clone command
+ * so it can be reused by other commands (e.g., `jack cd` for auto-cloning).
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { downloadProjectSource, fetchProjectTags } from "./control-plane.ts";
+import { formatSize } from "./format.ts";
+import { registerPath } from "./paths-index.ts";
+import { linkProject, updateProjectLink } from "./project-link.ts";
+import { resolveProject } from "./project-resolver.ts";
+import { cloneFromCloud, getRemoteManifest } from "./storage/index.ts";
+import { extractZipToDirectory } from "./zip-utils.ts";
+
+/**
+ * Options for the clone operation
+ */
+export interface CloneOptions {
+	/**
+	 * When true, don't show spinners or progress output.
+	 * Useful for programmatic calls or when called from other commands.
+	 */
+	silent?: boolean;
+
+	/**
+	 * When true, skip interactive prompts for collision handling.
+	 * If target directory exists, throws an error instead of prompting.
+	 */
+	skipPrompts?: boolean;
+}
+
+/**
+ * Result of a clone operation
+ */
+export interface CloneResult {
+	/** The final absolute path where the project was cloned */
+	path: string;
+	/** Number of files restored */
+	fileCount: number;
+	/** Whether this was a managed (Jack Cloud) or BYO project */
+	mode: "managed" | "byo";
+	/** Project ID if managed */
+	projectId?: string;
+	/** Number of tags restored (if any) */
+	tagsRestored?: number;
+}
+
+/**
+ * Error thrown when clone cannot proceed due to existing directory
+ */
+export class CloneCollisionError extends Error {
+	constructor(
+		public readonly targetDir: string,
+		public readonly displayName: string,
+	) {
+		super(`Directory ${displayName} already exists`);
+		this.name = "CloneCollisionError";
+	}
+}
+
+/**
+ * Error thrown when project is not found
+ */
+export class ProjectNotFoundError extends Error {
+	constructor(
+		public readonly projectName: string,
+		public readonly isByo: boolean,
+	) {
+		super(
+			isByo
+				? `Project not found: ${projectName}. For BYO projects, run 'jack sync' first to backup your project.`
+				: `Project not found: ${projectName}`,
+		);
+		this.name = "ProjectNotFoundError";
+	}
+}
+
+/**
+ * Reporter interface for clone progress (optional)
+ */
+export interface CloneReporter {
+	onLookup?: (projectName: string) => void;
+	onLookupComplete?: (found: boolean, isManaged: boolean) => void;
+	onDownloadStart?: (source: "cloud" | "r2", details?: string) => void;
+	onDownloadComplete?: (fileCount: number, displayPath: string) => void;
+	onDownloadError?: (error: string) => void;
+	onTagsRestored?: (count: number) => void;
+}
+
+/**
+ * Clone a project from Jack Cloud or User R2 storage.
+ *
+ * This is the core clone logic that can be called from:
+ * - `jack clone` command (full UX with prompts)
+ * - `jack cd` command (silent, auto-clone mode)
+ * - MCP tools (programmatic access)
+ *
+ * @param projectName - The project name/slug to clone
+ * @param targetDir - The target directory (can be relative, will be resolved to absolute)
+ * @param options - Clone options (silent, skipPrompts)
+ * @param reporter - Optional reporter for progress callbacks
+ * @returns CloneResult with the final path and details
+ * @throws CloneCollisionError if target exists and skipPrompts is true
+ * @throws ProjectNotFoundError if project not found
+ * @throws Error for other failures (download, extract, etc.)
+ */
+export async function cloneProject(
+	projectName: string,
+	targetDir: string,
+	options: CloneOptions = {},
+	reporter?: CloneReporter,
+): Promise<CloneResult> {
+	const { silent = false, skipPrompts = false } = options;
+	const absoluteTargetDir = resolve(targetDir);
+	const displayName = targetDir.startsWith("/") ? targetDir : targetDir.replace(/^\.\//, "");
+
+	// Check if target directory exists
+	if (existsSync(absoluteTargetDir)) {
+		if (skipPrompts) {
+			throw new CloneCollisionError(absoluteTargetDir, displayName);
+		}
+		// If not skipping prompts, caller is responsible for handling collision
+		// (the clone.ts command handles this with interactive prompts)
+		throw new CloneCollisionError(absoluteTargetDir, displayName);
+	}
+
+	// Look up project
+	reporter?.onLookup?.(projectName);
+
+	let project: Awaited<ReturnType<typeof resolveProject>> = null;
+	try {
+		project = await resolveProject(projectName);
+	} catch {
+		// Not found on control-plane, will fall back to User R2
+	}
+
+	reporter?.onLookupComplete?.(
+		!!project,
+		!!(project?.sources.controlPlane && project?.remote?.projectId),
+	);
+
+	// Managed mode: download from control-plane
+	if (project?.sources.controlPlane && project.remote?.projectId) {
+		reporter?.onDownloadStart?.("cloud");
+
+		try {
+			const sourceZip = await downloadProjectSource(projectName);
+			const fileCount = await extractZipToDirectory(sourceZip, absoluteTargetDir);
+
+			reporter?.onDownloadComplete?.(fileCount, `./${displayName}/`);
+
+			// Link to control-plane
+			await linkProject(absoluteTargetDir, project.remote.projectId, "managed");
+			await registerPath(project.remote.projectId, absoluteTargetDir);
+
+			// Fetch and restore tags from control plane
+			let tagsRestored = 0;
+			try {
+				const remoteTags = await fetchProjectTags(project.remote.projectId);
+				if (remoteTags.length > 0) {
+					await updateProjectLink(absoluteTargetDir, { tags: remoteTags });
+					tagsRestored = remoteTags.length;
+					reporter?.onTagsRestored?.(tagsRestored);
+				}
+			} catch {
+				// Silent fail - tag restoration is non-critical
+			}
+
+			return {
+				path: absoluteTargetDir,
+				fileCount,
+				mode: "managed",
+				projectId: project.remote.projectId,
+				tagsRestored: tagsRestored > 0 ? tagsRestored : undefined,
+			};
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Could not download project source";
+			reporter?.onDownloadError?.(message);
+			throw new Error(message);
+		}
+	}
+
+	// BYO mode: use existing User R2 flow
+	const manifest = await getRemoteManifest(projectName);
+
+	if (!manifest) {
+		throw new ProjectNotFoundError(projectName, true);
+	}
+
+	// Show file count and size in reporter
+	const totalSize = manifest.files.reduce((sum, f) => sum + f.size, 0);
+	reporter?.onDownloadStart?.("r2", `${manifest.files.length} file(s) (${formatSize(totalSize)})`);
+
+	// Download files
+	const result = await cloneFromCloud(projectName, absoluteTargetDir);
+
+	if (!result.success) {
+		const errorMsg = result.error || "Could not download project files";
+		reporter?.onDownloadError?.(errorMsg);
+		throw new Error(errorMsg);
+	}
+
+	reporter?.onDownloadComplete?.(result.filesDownloaded, `./${displayName}/`);
+
+	return {
+		path: absoluteTargetDir,
+		fileCount: result.filesDownloaded,
+		mode: "byo",
+	};
+}
+
+/**
+ * Check if a project exists (either on Jack Cloud or User R2).
+ * Useful for pre-flight checks before cloning.
+ *
+ * @param projectName - The project name/slug to check
+ * @returns Object with exists flag and source info
+ */
+export async function checkProjectExists(
+	projectName: string,
+): Promise<{ exists: boolean; isManaged: boolean; projectId?: string }> {
+	// Check Jack Cloud first
+	try {
+		const project = await resolveProject(projectName);
+		if (project?.sources.controlPlane && project.remote?.projectId) {
+			return {
+				exists: true,
+				isManaged: true,
+				projectId: project.remote.projectId,
+			};
+		}
+	} catch {
+		// Not found on control-plane
+	}
+
+	// Check User R2
+	const manifest = await getRemoteManifest(projectName);
+	if (manifest) {
+		return {
+			exists: true,
+			isManaged: false,
+		};
+	}
+
+	return {
+		exists: false,
+		isManaged: false,
+	};
+}

package/src/lib/config.ts

@@ -44,6 +44,28 @@ const DEFAULT_CONFIG_DIR = join(homedir(), ".config", "jack");
 export const CONFIG_DIR = process.env.JACK_CONFIG_DIR ?? DEFAULT_CONFIG_DIR;
 export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 
+/**
+ * Default Jack home directory for projects
+ */
+export const DEFAULT_JACK_HOME = join(homedir(), ".jack", "projects");
+
+/**
+ * Get the Jack home directory for projects.
+ * Supports environment variable override via JACK_HOME.
+ * @returns The resolved Jack home path (~ expanded to home directory)
+ */
+export function getJackHome(): string {
+	const envHome = process.env.JACK_HOME;
+	if (envHome) {
+		// Expand ~ to home directory if present
+		if (envHome.startsWith("~")) {
+			return join(homedir(), envHome.slice(1));
+		}
+		return envHome;
+	}
+	return DEFAULT_JACK_HOME;
+}
+
 /**
  * Ensure config directory exists
  */

package/src/lib/control-plane.ts

@@ -112,7 +112,11 @@ export async function createManagedProject(
 		requestBody.use_prebuilt = options.usePrebuilt;
 	}
 
-	debug("Creating managed project", { name, template: options?.template, usePrebuilt: options?.usePrebuilt });
+	debug("Creating managed project", {
+		name,
+		template: options?.template,
+		usePrebuilt: options?.usePrebuilt,
+	});
 	const start = Date.now();
 
 	const response = await authFetch(`${getControlApiUrl()}/v1/projects`, {
@@ -234,9 +238,7 @@ export interface ManagedProject {
 export async function getManagedDatabaseInfo(projectId: string): Promise<DatabaseInfoResponse> {
 	const { authFetch } = await import("./auth/index.ts");
 
-	const response = await authFetch(
-		`${getControlApiUrl()}/v1/projects/${projectId}/database/info`,
-	);
+	const response = await authFetch(`${getControlApiUrl()}/v1/projects/${projectId}/database/info`);
 
 	if (response.status === 404) {
 		throw new Error("No database found for this project");
@@ -365,6 +367,28 @@ export async function listManagedProjects(): Promise<ManagedProject[]> {
 	return data.projects;
 }
 
+/**
+ * Find a managed project by ID.
+ */
+export async function findProjectById(projectId: string): Promise<ManagedProject | null> {
+	const { authFetch } = await import("./auth/index.ts");
+
+	const response = await authFetch(
+		`${getControlApiUrl()}/v1/projects/${encodeURIComponent(projectId)}`,
+	);
+
+	if (response.status === 404) {
+		return null;
+	}
+
+	if (!response.ok) {
+		return null; // Silent fail - just can't look up the name
+	}
+
+	const data = (await response.json()) as { project: ManagedProject };
+	return data.project;
+}
+
 /**
  * Find a managed project by slug.
  */
@@ -729,8 +753,10 @@ export async function publishProject(projectId: string): Promise<PublishProjectR
 export async function downloadProjectSource(slug: string): Promise<Buffer> {
 	const { authFetch } = await import("./auth/index.ts");
 
+	// Use /me/projects endpoint to download your own project's source
+	// (works for both published and unpublished projects you own)
 	const response = await authFetch(
-		`${getControlApiUrl()}/v1/projects/by-slug/${encodeURIComponent(slug)}/source`,
+		`${getControlApiUrl()}/v1/me/projects/${encodeURIComponent(slug)}/source`,
 	);
 
 	if (!response.ok) {

package/src/lib/fuzzy.ts

@@ -0,0 +1,93 @@
+/**
+ * Simple fuzzy matching for project filtering
+ *
+ * Scoring priority:
+ * 1. Exact prefix match (highest)
+ * 2. Substring match (medium)
+ * 3. Character-by-character fuzzy (lower)
+ *
+ * Returns 0 for no match.
+ */
+
+const SCORE_EXACT_PREFIX = 1000;
+const SCORE_SUBSTRING = 500;
+const SCORE_FUZZY_BASE = 100;
+
+/**
+ * Calculate fuzzy match score between query and target.
+ * Higher score = better match. 0 = no match.
+ */
+export function fuzzyMatch(query: string, target: string): number {
+	if (!query || !target) return 0;
+
+	const q = query.toLowerCase();
+	const t = target.toLowerCase();
+
+	// Exact prefix match (highest priority)
+	if (t.startsWith(q)) {
+		// Bonus for exact match
+		if (t === q) return SCORE_EXACT_PREFIX + 100;
+		return SCORE_EXACT_PREFIX;
+	}
+
+	// Substring match (medium priority)
+	if (t.includes(q)) {
+		return SCORE_SUBSTRING;
+	}
+
+	// Character-by-character fuzzy match
+	// All query characters must appear in order in target
+	let targetIdx = 0;
+	let matchedChars = 0;
+	let consecutiveBonus = 0;
+	let lastMatchIdx = -2;
+
+	for (let i = 0; i < q.length; i++) {
+		const char = q[i];
+		let found = false;
+
+		while (targetIdx < t.length) {
+			if (t[targetIdx] === char) {
+				matchedChars++;
+				// Bonus for consecutive matches
+				if (targetIdx === lastMatchIdx + 1) {
+					consecutiveBonus += 10;
+				}
+				lastMatchIdx = targetIdx;
+				targetIdx++;
+				found = true;
+				break;
+			}
+			targetIdx++;
+		}
+
+		if (!found) {
+			return 0; // Query char not found, no match
+		}
+	}
+
+	// Base score plus bonuses
+	// More matched chars and consecutive matches = higher score
+	const lengthRatio = matchedChars / t.length;
+	return Math.floor(SCORE_FUZZY_BASE * lengthRatio + consecutiveBonus);
+}
+
+/**
+ * Filter and sort items by fuzzy match score.
+ * Returns only items with score > 0, sorted by score descending.
+ */
+export function fuzzyFilter<T>(query: string, items: T[], getText: (item: T) => string): T[] {
+	if (!query) return items;
+
+	const scored = items
+		.map((item) => ({
+			item,
+			score: fuzzyMatch(query, getText(item)),
+		}))
+		.filter(({ score }) => score > 0);
+
+	// Sort by score descending
+	scored.sort((a, b) => b.score - a.score);
+
+	return scored.map(({ item }) => item);
+}

package/src/lib/managed-deploy.ts

@@ -15,7 +15,7 @@ import { formatSize } from "./format.ts";
 import { createFileCountProgress, createUploadProgress } from "./progress.ts";
 import type { OperationReporter } from "./project-operations.ts";
 import { getProjectTags } from "./tags.ts";
-import { Events, track } from "./telemetry.ts";
+import { Events, track, trackActivationIfFirst } from "./telemetry.ts";
 import { packageForDeploy } from "./zip-packager.ts";
 
 export interface ManagedCreateResult {
@@ -169,8 +169,11 @@ export async function deployCodeToManagedProject(
 		// Track success
 		track(Events.MANAGED_DEPLOY_COMPLETED, {
 			duration_ms: Date.now() - startTime,
+			project_id: projectId,
 		});
 
+		await trackActivationIfFirst("managed");
+
 		// Fire-and-forget tag sync (non-blocking)
 		getProjectTags(projectPath)
 			.then((tags) => {

package/src/lib/managed-down.ts

@@ -3,12 +3,15 @@
  * Mirrors BYO down.ts flow but uses control plane APIs.
  */
 
+import { mkdirSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { getJackHome } from "./config.ts";
 import {
 	deleteManagedProject,
 	exportManagedDatabase,
 	fetchProjectResources,
+	getManagedDatabaseInfo,
 } from "./control-plane.ts";
 import { promptSelect } from "./hooks.ts";
 import { error, info, item, output, success, warn } from "./output.ts";
@@ -20,6 +23,7 @@ export interface ManagedDownFlags {
 export interface ManagedProjectInfo {
 	projectId: string;
 	runjackUrl: string | null;
+	localPath: string | null;
 }
 
 export async function managedDown(
@@ -54,12 +58,21 @@ export async function managedDown(
 	// Interactive mode - fetch actual resources
 	let hasDatabase = false;
 	let databaseName: string | null = null;
+	let databaseNumTables = 0;
 	try {
 		const resources = await fetchProjectResources(projectId);
 		const d1Resource = resources.find((r) => r.resource_type === "d1");
 		if (d1Resource) {
 			hasDatabase = true;
 			databaseName = d1Resource.resource_name;
+			// Fetch table count to determine if export is needed
+			try {
+				const dbInfo = await getManagedDatabaseInfo(projectId);
+				databaseNumTables = dbInfo.numTables;
+			} catch {
+				// If we can't get info, assume it has data to be safe
+				databaseNumTables = 1;
+			}
 		}
 	} catch {
 		// If fetch fails, assume no database (safer than showing wrong info)
@@ -89,11 +102,13 @@ export async function managedDown(
 		return false;
 	}
 
-	// Auto-export database if it exists (no prompt)
+	// Auto-export database if it has tables (skip empty databases)
 	let exportPath: string | null = null;
-	if (hasDatabase) {
-		exportPath = join(process.cwd(), `${projectName}-backup.sql`);
-		output.start(`Exporting database to ${exportPath}...`);
+	if (hasDatabase && databaseNumTables > 0) {
+		const backupDir = project.localPath ?? join(getJackHome(), projectName);
+		mkdirSync(backupDir, { recursive: true });
+		exportPath = join(backupDir, `${projectName}-backup.sql`);
+		output.start("Exporting database...");
 
 		try {
 			const exportResult = await exportManagedDatabase(projectId);
@@ -132,7 +147,7 @@ export async function managedDown(
 		console.error("");
 		success(`Undeployed '${projectName}'`);
 		if (exportPath) {
-			info(`Backup saved to ./${projectName}-backup.sql`);
+			info(`Backup saved to ${exportPath}`);
 		}
 		console.error("");
 		return true;

package/src/lib/output.ts

@@ -1,7 +1,18 @@
 import yoctoSpinner from "yocto-spinner";
+import type { OperationReporter } from "./project-operations.ts";
 
 const isColorEnabled = !process.env.NO_COLOR && process.stderr.isTTY !== false;
 
+/**
+ * Quiet mode detection for AI agents and CI environments.
+ * Reduces token usage by simplifying output (no spinners, no decorative boxes).
+ */
+export const isQuietMode =
+	!process.stderr.isTTY ||
+	process.env.CI === "true" ||
+	process.env.CI === "1" ||
+	process.env.JACK_QUIET === "1";
+
 /**
  * ANSI color codes for terminal output
  */
@@ -22,12 +33,19 @@ let currentSpinner: ReturnType<typeof yoctoSpinner> | null = null;
  */
 export const output = {
 	start(text: string) {
+		if (isQuietMode) {
+			console.error(text);
+			return;
+		}
 		if (currentSpinner) {
 			currentSpinner.stop();
 		}
 		currentSpinner = yoctoSpinner({ text }).start();
 	},
 	stop() {
+		if (isQuietMode) {
+			return;
+		}
 		if (currentSpinner) {
 			currentSpinner.stop();
 			currentSpinner = null;
@@ -46,6 +64,26 @@ export const output = {
  * Create a spinner for long-running operations
  */
 export function spinner(text: string) {
+	if (isQuietMode) {
+		console.error(text);
+		let currentText = text;
+		return {
+			success(message: string) {
+				success(message);
+			},
+			error(message: string) {
+				error(message);
+			},
+			stop() {},
+			get text() {
+				return currentText;
+			},
+			set text(value: string | undefined) {
+				currentText = value ?? "";
+			},
+		};
+	}
+
 	const spin = yoctoSpinner({ text }).start();
 
 	return {
@@ -121,7 +159,15 @@ export function getRandomPurple(): string {
  * Print a boxed message for important info (cyberpunk style)
  */
 export function box(title: string, lines: string[]): void {
-	const maxLen = Math.max(title.length, ...lines.map((l) => l.length));
+	if (isQuietMode) {
+		return; // Skip decorative boxes in quiet mode
+	}
+	// Respect terminal width (leave room for box borders + indent)
+	const termWidth = process.stderr.columns || process.stdout.columns || 80;
+	const maxBoxWidth = Math.max(30, termWidth - 6); // 2 indent + 2 borders + 2 padding
+
+	const contentMaxLen = Math.max(title.length, ...lines.map((l) => l.length));
+	const maxLen = Math.min(contentMaxLen, maxBoxWidth - 4);
 	const innerWidth = maxLen + 4;
 
 	const purple = isColorEnabled ? getRandomPurple() : "";
@@ -132,10 +178,15 @@ export function box(title: string, lines: string[]): void {
 	const fill = "▓".repeat(innerWidth);
 	const gradient = "░".repeat(innerWidth);
 
+	// Truncate text if too long for box
+	const truncate = (text: string) => (text.length > maxLen ? text.slice(0, maxLen - 1) + "…" : text);
+
 	// Pad plain text first, then apply colors (ANSI codes break padEnd calculation)
-	const pad = (text: string) => `  ${text.padEnd(maxLen)}  `;
-	const padTitle = (text: string) =>
-		`  ${bold}${text}${reset}${purple}${" ".repeat(maxLen - text.length)}  `;
+	const pad = (text: string) => `  ${truncate(text).padEnd(maxLen)}  `;
+	const padTitle = (text: string) => {
+		const t = truncate(text);
+		return `  ${bold}${t}${reset}${purple}${" ".repeat(maxLen - t.length)}  `;
+	};
 
 	console.error("");
 	console.error(`  ${purple}╔${bar}╗${reset}`);
@@ -154,7 +205,15 @@ export function box(title: string, lines: string[]): void {
  * Print a celebration box (for final success after setup)
  */
 export function celebrate(title: string, lines: string[]): void {
-	const maxLen = Math.max(title.length, ...lines.map((l) => l.length));
+	if (isQuietMode) {
+		return; // Skip decorative boxes in quiet mode
+	}
+	// Respect terminal width (leave room for box borders + indent)
+	const termWidth = process.stderr.columns || process.stdout.columns || 80;
+	const maxBoxWidth = Math.max(30, termWidth - 6); // 2 indent + 2 borders + 2 padding
+
+	const contentMaxLen = Math.max(title.length, ...lines.map((l) => l.length));
+	const maxLen = Math.min(contentMaxLen, maxBoxWidth - 4);
 	const innerWidth = maxLen + 4;
 
 	const purple = isColorEnabled ? getRandomPurple() : "";
@@ -166,12 +225,16 @@ export function celebrate(title: string, lines: string[]): void {
 	const gradient = "░".repeat(innerWidth);
 	const space = " ".repeat(innerWidth);
 
+	// Truncate text if too long for box
+	const truncate = (text: string) => (text.length > maxLen ? text.slice(0, maxLen - 1) + "…" : text);
+
 	// Center text based on visual length, then apply colors
 	const center = (text: string, applyBold = false) => {
-		const left = Math.floor((innerWidth - text.length) / 2);
-		const right = innerWidth - text.length - left;
-		const centered = " ".repeat(left) + text + " ".repeat(right);
-		return applyBold ? centered.replace(text, bold + text + reset + purple) : centered;
+		const t = truncate(text);
+		const left = Math.floor((innerWidth - t.length) / 2);
+		const right = innerWidth - t.length - left;
+		const centered = " ".repeat(left) + t + " ".repeat(right);
+		return applyBold ? centered.replace(t, bold + t + reset + purple) : centered;
 	};
 
 	console.error("");
@@ -188,3 +251,21 @@ export function celebrate(title: string, lines: string[]): void {
 	console.error(`  ${purple}╚${bar}╝${reset}`);
 	console.error("");
 }
+
+/**
+ * Create a standard reporter object for project operations.
+ * Respects quiet mode for reduced output in CI/agent environments.
+ */
+export function createReporter(): OperationReporter {
+	return {
+		start: output.start,
+		stop: output.stop,
+		spinner,
+		info,
+		warn,
+		error,
+		success,
+		box,
+		celebrate,
+	};
+}