buildx-cli 1.0.8 → 1.0.10

package/src/commands/functions.ts

@@ -0,0 +1,703 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import fs from "fs-extra";
+import path from "path";
+import { configManager } from "../config/index";
+import { apiService } from "../services/api";
+import { loadEnvConfig } from "../utils/env";
+import { matchByFilters, parseFilters, readJsonIfExists, sanitizeFileName, sha256, toAbsolutePath } from "../utils/sync";
+
+type FunctionManifestEntry = {
+	name: string;
+	file: string;
+	remoteChecksum?: string;
+	localChecksum: string;
+	metadata: {
+		group_path?: string;
+		compatible?: ("api" | "flow")[];
+		collection_id?: string;
+		allow_anonymous?: boolean;
+		allow_method?: string[];
+		input_schema?: string;
+		output_schema?: string;
+		output_format?: {
+			format: "json" | "csv" | "xml" | "xlsx" | "text";
+			as_attachment?: boolean;
+			filename?: string;
+			content_type?: string;
+		};
+	};
+};
+
+type FunctionManifest = {
+	version: 1;
+	projectId: string;
+	generatedAt: string;
+	context: {
+		file: string;
+		checksum?: string;
+		version?: number;
+	};
+	functions: FunctionManifestEntry[];
+};
+
+type FunctionCodeValidationResult = {
+	valid: boolean;
+	reason?: string;
+};
+
+type FunctionCodeLintResult = {
+	valid: boolean;
+	reason?: string;
+};
+
+const ASYNC_ARROW_FUNCTION_REGEX = /^\s*async\s*\(\s*[A-Za-z_$][\w$]*(?:\s*:[^,]+)?\s*,\s*[A-Za-z_$][\w$]*(?:\s*:[^)]+)?\s*\)\s*=>\s*\{([\s\S]*)\}\s*;?\s*$/;
+const FUNCTION_DECLARATION_REGEX = /^\s*(?:async\s+)?function(?:\s+[A-Za-z_$][\w$]*)?\s*\(\s*[A-Za-z_$][\w$]*(?:\s*:[^,]+)?\s*,\s*[A-Za-z_$][\w$]*(?:\s*:[^)]+)?\s*\)\s*\{[\s\S]*\}\s*;?\s*$/;
+
+function applyFunctionPullOptions(command: Command): Command {
+	return command
+		.option("-p, --project-id <project-id>", "Project ID to sync functions from (uses default if not specified)")
+		.option("-t, --target-dir <path>", "Base target directory for function artifacts")
+		.option("--context-output <path>", "Output path for function context schema", "./buildx/generated/function-context.d.ts")
+		.option("--functions-dir <path>", "Directory to store function source files", "./buildx/functions")
+		.option("-u, --api-url <url>", "Custom API base URL")
+		.option("--filter <pattern...>", "Only include functions matching wildcard pattern(s)")
+		.option("--full-context", "Write full context schema from API (default writes compact schema)")
+		.option("--module-wrap", "Wrap function code into ESM module format (experimental)")
+		.option("--no-validate-code", "Skip runtime compatibility validation")
+		.option("--no-lint", "Skip basic syntax lint checks")
+		.option("--dry-run", "Preview sync result without writing local files")
+		.option("-f, --force", "Force overwrite existing local files");
+}
+
+function printDryRunFilePreview(filePath: string, content: string): void {
+	console.log(chalk.cyan(`\n--- DRY RUN: ${filePath} ---`));
+	console.log(content);
+	console.log(chalk.cyan(`--- END DRY RUN: ${filePath} ---\n`));
+}
+
+function ensureConfigured(): void {
+	if (!apiService.isConfigured()) {
+		console.error(chalk.red("❌ API not configured"));
+		console.log(chalk.yellow("Please configure your API endpoint and API key first:"));
+		console.log(chalk.cyan("  buildx config:setup"));
+		process.exit(1);
+	}
+
+	if (!configManager.isAuthenticated()) {
+		console.error(chalk.red("Error: Not authenticated"));
+		console.log(chalk.yellow("Run \"buildx auth:login\" to authenticate first"));
+		process.exit(1);
+	}
+}
+
+function resolveProjectId(projectId?: string): string {
+	if (projectId) return projectId;
+
+	const defaultProjectId = configManager.getDefaultProject();
+	if (defaultProjectId) {
+		console.log(chalk.blue("Using project ID:"), defaultProjectId);
+		return defaultProjectId;
+	}
+
+	const envConfig = loadEnvConfig();
+	if (envConfig.BUILDX_PROJECT_ID) {
+		console.log(chalk.blue("Using project ID from environment variable:"), envConfig.BUILDX_PROJECT_ID);
+		return envConfig.BUILDX_PROJECT_ID;
+	}
+
+	console.error(chalk.red("Error: No project ID specified"));
+	console.log(chalk.yellow("Use --project-id option, set a default project with 'buildx projects:set-default', or set BUILDX_PROJECT_ID environment variable"));
+	process.exit(1);
+}
+
+function toFunctionFilename(functionName: string): string {
+	return `${sanitizeFileName(functionName)}.ts`;
+}
+
+function getFunctionManifestPath(functionsDirPath: string): string {
+	return path.join(functionsDirPath, "functions.manifest.json");
+}
+
+function filterFunctions(functions: any[], filters: string[]): any[] {
+	if (!filters.length) return functions;
+	return functions.filter((fn) => matchByFilters(String(fn.name || ""), filters));
+}
+
+function ensureFlowDataType(schema: string): string {
+	if (/\btype\s+FlowData\b/.test(schema) || /\binterface\s+FlowData\b/.test(schema)) {
+		return schema;
+	}
+	const trimmed = schema.trimEnd();
+	return `${trimmed}\n\nexport type FlowData = Record<string, any>;\n`;
+}
+
+function buildCompactContextSchema(rawSchema: string): string {
+	const lines = [
+		"// Auto-generated by buildx-cli (compact mode).",
+		"// Use --full-context to keep the full remote schema.",
+		"",
+		"export type FlowData = Record<string, any>;",
+		"export type FlowContext = Record<string, any>;",
+		"",
+		"export interface CodeContext {",
+		"\tcontext: FlowContext;",
+		"\tdata: FlowData;",
+		"\t[key: string]: any;",
+		"}",
+		""
+	];
+
+	// Keep high-signal service aliases if they exist in upstream schema.
+	if (rawSchema.includes("type LODASH_TYPE")) {
+		lines.splice(3, 0, "type LODASH_TYPE = any;");
+	}
+	if (rawSchema.includes("type URL_SEARCH_PARAMS_TYPE")) {
+		lines.splice(3, 0, "type URL_SEARCH_PARAMS_TYPE = any;");
+	}
+
+	return lines.join("\n");
+}
+
+function toImportPathWithoutExtension(fromFilePath: string, toFilePath: string): string {
+	const relativePath = path.relative(path.dirname(fromFilePath), toFilePath);
+	const normalized = relativePath.split(path.sep).join("/");
+	const withoutExt = normalized.replace(/\.[^.]+$/, "");
+	if (withoutExt.startsWith(".")) return withoutExt;
+	return `./${withoutExt}`;
+}
+
+function wrapArrowFunctionSource(code: string, contextImportPath: string): string {
+	return [
+		`import type { FlowContext, FlowData } from "${contextImportPath}";`,
+		"",
+		`const handler = ${code.trim()};`,
+		"",
+		"export default handler;",
+		""
+	].join("\n");
+}
+
+function normalizeFunctionSource(code: string, contextImportPath: string): string {
+	const trimmed = code.trim();
+	if (!trimmed) {
+		return [
+			`import type { FlowContext, FlowData } from "${contextImportPath}";`,
+			"",
+			"const handler = async (data: FlowData, context: FlowContext) => {",
+			"\treturn { data, context };",
+			"};",
+			"",
+			"export default handler;",
+			""
+		].join("\n");
+	}
+
+	const hasModuleShape = /\bexport\s+default\b/.test(trimmed) || /\bmodule\.exports\b/.test(trimmed);
+	if (hasModuleShape) {
+		return `${trimmed}\n`;
+	}
+
+	const looksLikeArrowExpression = /^(async\s*)?\([\s\S]*\)\s*=>\s*[\s\S]+$/.test(trimmed);
+	if (looksLikeArrowExpression) {
+		return wrapArrowFunctionSource(trimmed, contextImportPath);
+	}
+
+	return `${trimmed}\n`;
+}
+
+function preserveFunctionSource(code: string): string {
+	const trimmed = code.trim();
+	return trimmed ? `${trimmed}\n` : "";
+}
+
+function compactFunctionMetadata(detail: any): FunctionManifestEntry["metadata"] {
+	const metadata: FunctionManifestEntry["metadata"] = {};
+	if (detail.group_path) metadata.group_path = detail.group_path;
+	if (Array.isArray(detail.compatible) && detail.compatible.length > 0) metadata.compatible = detail.compatible;
+	if (detail.collection_id) metadata.collection_id = detail.collection_id;
+	if (typeof detail.allow_anonymous === "boolean") metadata.allow_anonymous = detail.allow_anonymous;
+	if (Array.isArray(detail.allow_method) && detail.allow_method.length > 0) metadata.allow_method = detail.allow_method;
+	if (detail.input_schema && detail.input_schema !== "{}") metadata.input_schema = detail.input_schema;
+	if (detail.output_schema && detail.output_schema !== "{}") metadata.output_schema = detail.output_schema;
+	if (detail.output_format && typeof detail.output_format === "object") {
+		metadata.output_format = detail.output_format;
+	}
+	return metadata;
+}
+
+function validateFunctionRuntimeCode(code: string): FunctionCodeValidationResult {
+	const trimmed = String(code || "").trim();
+	if (!trimmed) {
+		return { valid: false, reason: "code is empty" };
+	}
+
+	if (FUNCTION_DECLARATION_REGEX.test(trimmed)) {
+		return { valid: true };
+	}
+
+	const arrowMatch = trimmed.match(ASYNC_ARROW_FUNCTION_REGEX);
+	if (arrowMatch) {
+		const body = (arrowMatch[1] || "").trim();
+		if (ASYNC_ARROW_FUNCTION_REGEX.test(body)) {
+			return { valid: false, reason: "nested async wrapper detected (double-wrapped function body)" };
+		}
+		return { valid: true };
+	}
+
+	// TODO(buildx-export-default): add optional export default runtime mode in datastore/runtime and accept ESM handler shape here.
+	return {
+		valid: false,
+		reason: "expected runtime wrapper function, e.g. async (data, context) => { ... }"
+	};
+}
+
+function stripTypeFromParam(param: string): string {
+	const withoutDefault = param.trim();
+	const colonIndex = withoutDefault.indexOf(":");
+	const left = colonIndex >= 0 ? withoutDefault.slice(0, colonIndex).trim() : withoutDefault;
+	return left.replace(/\?/g, "");
+}
+
+function toLintableRuntimeCode(code: string): string {
+	const trimmed = String(code || "").trim();
+	if (!trimmed) return trimmed;
+
+	const arrowSignature = trimmed.match(/^(\s*async\s*)\(([\s\S]*?)\)(\s*=>\s*\{[\s\S]*\}\s*;?\s*)$/);
+	if (arrowSignature) {
+		const params = arrowSignature[2]
+			.split(",")
+			.map((p) => stripTypeFromParam(p))
+			.join(", ");
+		return `${arrowSignature[1]}(${params})${arrowSignature[3]}`;
+	}
+
+	const fnSignature = trimmed.match(/^(\s*(?:async\s+)?function(?:\s+[A-Za-z_$][\w$]*)?\s*)\(([\s\S]*?)\)(\s*\{[\s\S]*\}\s*;?\s*)$/);
+	if (fnSignature) {
+		const params = fnSignature[2]
+			.split(",")
+			.map((p) => stripTypeFromParam(p))
+			.join(", ");
+		return `${fnSignature[1]}(${params})${fnSignature[3]}`;
+	}
+
+	return trimmed;
+}
+
+function lintFunctionRuntimeCode(code: string): FunctionCodeLintResult {
+	const trimmed = String(code || "").trim();
+	if (!trimmed) {
+		return { valid: false, reason: "code is empty" };
+	}
+
+	try {
+		const jsLikeCode = toLintableRuntimeCode(trimmed);
+		if (jsLikeCode.startsWith("async")) {
+			// Arrow function expression
+			void new Function(`return (${jsLikeCode});`)();
+		} else {
+			// Function declaration shape
+			void new Function(`${jsLikeCode}; return true;`)();
+		}
+		return { valid: true };
+	} catch (error) {
+		return {
+			valid: false,
+			reason: `syntax check failed (${error instanceof Error ? error.message : "unknown error"})`
+		};
+	}
+}
+
+async function runFunctionPull(options: any): Promise<void> {
+	ensureConfigured();
+	const projectId = resolveProjectId(options.projectId);
+	if (options.apiUrl) {
+		apiService.setBaseUrl(options.apiUrl);
+	}
+
+	const targetDirPath = options.targetDir ? toAbsolutePath(options.targetDir) : null;
+	const contextOutputPath = targetDirPath
+		? path.join(targetDirPath, "function-context.d.ts")
+		: toAbsolutePath(options.contextOutput);
+	const functionsDirPath = targetDirPath
+		? path.join(targetDirPath, "functions")
+		: toAbsolutePath(options.functionsDir);
+	const manifestPath = getFunctionManifestPath(functionsDirPath);
+	const previousManifest = await readJsonIfExists<FunctionManifest>(manifestPath);
+
+	const contextSpinner = ora("Fetching function context schema...").start();
+	const contextInfo = await apiService.getFunctionContextSchemaInfo(projectId);
+	const contextSchema = options.fullContext
+		? ensureFlowDataType(contextInfo.schema)
+		: buildCompactContextSchema(contextInfo.schema);
+	contextSpinner.succeed("Function context schema fetched");
+
+	await fs.ensureDir(path.dirname(contextOutputPath));
+	if ((await fs.pathExists(contextOutputPath)) && !options.force) {
+		const existingContext = await fs.readFile(contextOutputPath, "utf8");
+		if (sha256(existingContext) !== sha256(contextSchema)) {
+			throw new Error(`Context file has local edits: ${contextOutputPath}. Use --force to overwrite.`);
+		}
+	}
+	if (options.dryRun) {
+		console.log(chalk.cyan(`~ would write function context schema: ${contextOutputPath}`));
+		printDryRunFilePreview(contextOutputPath, contextSchema);
+	} else {
+		await fs.writeFile(contextOutputPath, contextSchema, "utf8");
+	}
+
+	await fs.ensureDir(functionsDirPath);
+	const listSpinner = ora("Fetching function list...").start();
+	const filters = parseFilters(options.filter);
+	const functions = filterFunctions(await apiService.listFunctions(projectId), filters);
+	listSpinner.succeed(`Fetched ${functions.length} functions`);
+
+	const entries: FunctionManifestEntry[] = [];
+	for (const fn of functions) {
+		const name = String(fn.name || "");
+		if (!name) continue;
+
+		const detail = await apiService.getFunction(projectId, name);
+		const filename = toFunctionFilename(name);
+		const filePath = path.join(functionsDirPath, filename);
+		const contextImportPath = toImportPathWithoutExtension(filePath, contextOutputPath);
+		const sourceCode = String(detail.code || "");
+		if (options.validateCode) {
+			const validation = validateFunctionRuntimeCode(sourceCode);
+			if (!validation.valid) {
+				console.log(chalk.yellow(`⚠ ${name}: runtime validation warning (${validation.reason})`));
+			}
+		}
+		if (options.lint) {
+			const lintResult = lintFunctionRuntimeCode(sourceCode);
+			if (!lintResult.valid) {
+				console.log(chalk.yellow(`⚠ ${name}: lint warning (${lintResult.reason})`));
+			}
+		}
+		const code = options.moduleWrap
+			? normalizeFunctionSource(sourceCode, contextImportPath)
+			: preserveFunctionSource(sourceCode);
+		const localChecksum = sha256(code);
+
+		if ((await fs.pathExists(filePath)) && !options.force) {
+			const previousEntry = previousManifest?.functions?.find((entry) => entry.name === name);
+			const existingCode = await fs.readFile(filePath, "utf8");
+			const existingChecksum = sha256(existingCode);
+			if (previousEntry && existingChecksum !== previousEntry.localChecksum) {
+				console.log(chalk.yellow(`⚠ Skipped ${name}: local file changed (use --force to overwrite)`));
+				continue;
+			}
+		}
+
+		if (options.dryRun) {
+			console.log(chalk.cyan(`~ would write function source: ${filePath}`));
+			printDryRunFilePreview(filePath, code);
+		} else {
+			await fs.writeFile(filePath, code, "utf8");
+		}
+		entries.push({
+			name,
+			file: filename,
+			remoteChecksum: detail.checksum,
+			localChecksum,
+			metadata: compactFunctionMetadata(detail)
+		});
+	}
+
+	const manifest: FunctionManifest = {
+		version: 1,
+		projectId,
+		generatedAt: new Date().toISOString(),
+		context: {
+			file: path.relative(path.dirname(manifestPath), contextOutputPath),
+			checksum: contextInfo.checksum,
+			version: contextInfo.version
+		},
+		functions: entries.sort((a, b) => a.name.localeCompare(b.name))
+	};
+
+	if (options.dryRun) {
+		console.log(chalk.cyan(`~ would write function manifest: ${manifestPath}`));
+		console.log(chalk.blue("Functions count:"), entries.length);
+		printDryRunFilePreview(manifestPath, JSON.stringify(manifest, null, 2));
+	} else {
+		await fs.writeJson(manifestPath, manifest, { spaces: 2 });
+		console.log(chalk.green("✓ Function context schema:"), contextOutputPath);
+		console.log(chalk.green("✓ Function sources:"), functionsDirPath);
+		console.log(chalk.green("✓ Function manifest:"), manifestPath);
+	}
+}
+
+export const functionSyncCommand = applyFunctionPullOptions(
+	new Command("function:sync")
+		.description("Deprecated alias of function:pull (kept for compatibility)")
+).action(async (options) => {
+	try {
+		console.log(chalk.yellow("function:sync is deprecated. Use function:pull."));
+		await runFunctionPull(options);
+	} catch (error) {
+		console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
+		process.exit(1);
+	}
+});
+
+export const functionPullCommand = applyFunctionPullOptions(
+	new Command("function:pull")
+		.description("Pull function context type + function source files into local project")
+).action(async (options) => {
+	try {
+		await runFunctionPull(options);
+	} catch (error) {
+		console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
+		process.exit(1);
+	}
+});
+
+export const functionPushCommand = new Command("function:push")
+	.description("Push local function source files back to project")
+	.option("-p, --project-id <project-id>", "Project ID to push functions to (uses default if not specified)")
+	.option("-t, --target-dir <path>", "Base target directory for function artifacts")
+	.option("--functions-dir <path>", "Directory containing function source files", "./buildx/functions")
+	.option("-n, --name <function-name>", "Push only one function by name")
+	.option("-u, --api-url <url>", "Custom API base URL")
+	.option("--filter <pattern...>", "Only push functions matching wildcard pattern(s)")
+	.option("--no-validate-code", "Skip runtime compatibility validation before push")
+	.option("--no-lint", "Skip basic syntax lint checks before push")
+	.option("--dry-run", "Show what would be pushed")
+	.option("-f, --force", "Force push even when remote drift is detected")
+	.action(async (options) => {
+		try {
+			ensureConfigured();
+			const projectId = resolveProjectId(options.projectId);
+			if (options.apiUrl) {
+				apiService.setBaseUrl(options.apiUrl);
+			}
+
+			const targetDirPath = options.targetDir ? toAbsolutePath(options.targetDir) : null;
+			const functionsDirPath = targetDirPath
+				? path.join(targetDirPath, "functions")
+				: toAbsolutePath(options.functionsDir);
+			const manifestPath = getFunctionManifestPath(functionsDirPath);
+			const manifest = await readJsonIfExists<FunctionManifest>(manifestPath);
+			if (!manifest) {
+				throw new Error(`Function manifest not found: ${manifestPath}. Run function:sync first.`);
+			}
+
+			const filters = parseFilters(options.filter);
+			const filteredFromManifest = filterFunctions(manifest.functions, filters);
+			const targets = options.name
+				? filteredFromManifest.filter((entry) => entry.name === options.name)
+				: filteredFromManifest;
+
+			if (targets.length === 0) {
+				throw new Error(options.name ? `Function "${options.name}" not found in manifest` : "No functions in manifest");
+			}
+
+			if (options.validateCode) {
+				const invalidEntries: string[] = [];
+				for (const entry of targets) {
+					const filePath = path.join(functionsDirPath, entry.file);
+					if (!(await fs.pathExists(filePath))) continue;
+					const code = await fs.readFile(filePath, "utf8");
+					const validation = validateFunctionRuntimeCode(code);
+					if (!validation.valid) {
+						invalidEntries.push(`${entry.name}: ${validation.reason}`);
+					}
+				}
+				if (invalidEntries.length > 0) {
+					throw new Error(
+						`Function code validation failed:\n- ${invalidEntries.join("\n- ")}\nUse --no-validate-code to bypass.`
+					);
+				}
+			}
+			if (options.lint) {
+				const lintErrors: string[] = [];
+				for (const entry of targets) {
+					const filePath = path.join(functionsDirPath, entry.file);
+					if (!(await fs.pathExists(filePath))) continue;
+					const code = await fs.readFile(filePath, "utf8");
+					const lintResult = lintFunctionRuntimeCode(code);
+					if (!lintResult.valid) {
+						lintErrors.push(`${entry.name}: ${lintResult.reason}`);
+					}
+				}
+				if (lintErrors.length > 0) {
+					throw new Error(
+						`Function lint failed:\n- ${lintErrors.join("\n- ")}\nUse --no-lint to bypass.`
+					);
+				}
+			}
+
+			let pushed = 0;
+			let skipped = 0;
+			const updatedEntries: FunctionManifestEntry[] = [];
+
+			for (const entry of manifest.functions) {
+				const target = targets.find((item) => item.name === entry.name);
+				if (!target) {
+					updatedEntries.push(entry);
+					continue;
+				}
+
+				const filePath = path.join(functionsDirPath, entry.file);
+				if (!(await fs.pathExists(filePath))) {
+					console.log(chalk.yellow(`⚠ Skipped ${entry.name}: source file missing (${filePath})`));
+					skipped++;
+					updatedEntries.push(entry);
+					continue;
+				}
+
+				const code = await fs.readFile(filePath, "utf8");
+				const localChecksum = sha256(code);
+
+				const remote = await apiService.getFunction(projectId, entry.name).catch(() => null);
+				const remoteChecksum = remote?.checksum;
+				const remoteDrifted = !!(entry.remoteChecksum && remoteChecksum && remoteChecksum !== entry.remoteChecksum);
+				if (remoteDrifted && !options.force) {
+					console.log(chalk.yellow(`⚠ Skipped ${entry.name}: remote changed since last sync (use --force to override)`));
+					skipped++;
+					updatedEntries.push(entry);
+					continue;
+				}
+
+				if (options.dryRun) {
+					console.log(chalk.cyan(`~ would push ${entry.name}`));
+					pushed++;
+					updatedEntries.push({
+						...entry,
+						localChecksum
+					});
+					continue;
+				}
+
+				const payload = {
+					...entry.metadata,
+					code
+				};
+				const saved = await apiService.upsertFunction(projectId, entry.name, payload);
+				const nextEntry: FunctionManifestEntry = {
+					...entry,
+					remoteChecksum: saved?.checksum || remoteChecksum,
+					localChecksum
+				};
+				updatedEntries.push(nextEntry);
+				console.log(chalk.green(`✓ pushed ${entry.name}`));
+				pushed++;
+			}
+
+			manifest.generatedAt = new Date().toISOString();
+			manifest.functions = updatedEntries.sort((a, b) => a.name.localeCompare(b.name));
+			await fs.writeJson(manifestPath, manifest, { spaces: 2 });
+
+			console.log(chalk.blue(`Done. pushed=${pushed}, skipped=${skipped}`));
+		} catch (error) {
+			console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
+			process.exit(1);
+		}
+	});
+
+export const functionListCommand = new Command("function:list")
+	.description("List remote functions in project")
+	.option("-p, --project-id <project-id>", "Project ID (uses default if not specified)")
+	.option("-u, --api-url <url>", "Custom API base URL")
+	.option("--filter <pattern...>", "Filter function names by wildcard pattern(s)")
+	.action(async (options) => {
+		try {
+			ensureConfigured();
+			const projectId = resolveProjectId(options.projectId);
+			if (options.apiUrl) {
+				apiService.setBaseUrl(options.apiUrl);
+			}
+			const filters = parseFilters(options.filter);
+			const functions = filterFunctions(await apiService.listFunctions(projectId), filters)
+				.sort((a, b) => String(a.name || "").localeCompare(String(b.name || "")));
+			for (const fn of functions) {
+				console.log(fn.name);
+			}
+			console.log(chalk.blue(`Total: ${functions.length}`));
+		} catch (error) {
+			console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
+			process.exit(1);
+		}
+	});
+
+export const functionDiffCommand = new Command("function:diff")
+	.description("Diff local function sources against remote project")
+	.option("-p, --project-id <project-id>", "Project ID (uses default if not specified)")
+	.option("-t, --target-dir <path>", "Base target directory for function artifacts")
+	.option("--functions-dir <path>", "Directory containing function source files", "./buildx/functions")
+	.option("-u, --api-url <url>", "Custom API base URL")
+	.option("-n, --name <function-name>", "Diff only one function by name")
+	.option("--filter <pattern...>", "Filter function names by wildcard pattern(s)")
+	.action(async (options) => {
+		try {
+			ensureConfigured();
+			const projectId = resolveProjectId(options.projectId);
+			if (options.apiUrl) {
+				apiService.setBaseUrl(options.apiUrl);
+			}
+
+			const targetDirPath = options.targetDir ? toAbsolutePath(options.targetDir) : null;
+			const functionsDirPath = targetDirPath
+				? path.join(targetDirPath, "functions")
+				: toAbsolutePath(options.functionsDir);
+			const manifestPath = getFunctionManifestPath(functionsDirPath);
+			const manifest = await readJsonIfExists<FunctionManifest>(manifestPath);
+			if (!manifest) {
+				throw new Error(`Function manifest not found: ${manifestPath}. Run function:sync first.`);
+			}
+
+			const filters = parseFilters(options.filter);
+			let targets = filterFunctions(manifest.functions, filters);
+			if (options.name) {
+				targets = targets.filter((entry) => entry.name === options.name);
+			}
+			if (!targets.length) {
+				throw new Error("No functions matched filters/name");
+			}
+
+			let same = 0;
+			let changed = 0;
+			let missingLocal = 0;
+			let missingRemote = 0;
+			let remoteDrift = 0;
+
+			for (const entry of targets) {
+				const filePath = path.join(functionsDirPath, entry.file);
+				if (!(await fs.pathExists(filePath))) {
+					console.log(chalk.yellow(`+ local-missing ${entry.name}`));
+					missingLocal++;
+					continue;
+				}
+				const localCode = await fs.readFile(filePath, "utf8");
+				const localChecksum = sha256(localCode);
+
+				const remote = await apiService.getFunction(projectId, entry.name).catch(() => null);
+				if (!remote) {
+					console.log(chalk.yellow(`- remote-missing ${entry.name}`));
+					missingRemote++;
+					continue;
+				}
+
+				if (entry.remoteChecksum && remote.checksum && entry.remoteChecksum !== remote.checksum) {
+					console.log(chalk.yellow(`! remote-drift ${entry.name}`));
+					remoteDrift++;
+				}
+
+				const remoteChecksum = remote.checksum || sha256(String(remote.code || ""));
+				if (localChecksum === remoteChecksum) {
+					console.log(chalk.gray(`= same ${entry.name}`));
+					same++;
+				} else {
+					console.log(chalk.cyan(`~ changed ${entry.name}`));
+					changed++;
+				}
+			}
+
+			console.log(chalk.blue(`Summary: changed=${changed}, same=${same}, local-missing=${missingLocal}, remote-missing=${missingRemote}, remote-drift=${remoteDrift}`));
+		} catch (error) {
+			console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
+			process.exit(1);
+		}
+	});