@bonnard/cli 0.1.13 → 0.2.1

package/dist/bin/bon.mjs

@@ -1519,7 +1519,6 @@ async function addDemo(options) {
 	console.log(pc.dim("  fact_sales, dim_product, dim_store, dim_customer"));
 	console.log();
 	console.log(pc.dim(`Test connection: bon datasource test ${name}`));
-	console.log(pc.dim(`Explore tables:  bon preview ${name} "SELECT table_name FROM information_schema.tables WHERE table_schema = 'contoso'"`));
 }
 /**
 * Main datasource add command
@@ -1626,464 +1625,11 @@ async function datasourceListCommand(options = {}) {
 	if (showRemote) await listRemoteDatasources();
 }
 
-//#endregion
-//#region src/lib/connection/snowflake.ts
-/**
-* Snowflake connection testing and querying
-*/
-const require$4 = createRequire(import.meta.url);
-function loadSnowflake() {
-	try {
-		const snowflake = require$4("snowflake-sdk");
-		snowflake.configure({ logLevel: "ERROR" });
-		return snowflake;
-	} catch {
-		return null;
-	}
-}
-async function testSnowflakeConnection(config, credentials) {
-	const snowflake = loadSnowflake();
-	if (!snowflake) return {
-		success: false,
-		message: "Snowflake driver not installed",
-		error: "Run: pnpm add snowflake-sdk"
-	};
-	const startTime = Date.now();
-	return new Promise((resolve) => {
-		const connection = snowflake.createConnection({
-			account: config.account,
-			username: credentials.username,
-			password: credentials.password,
-			database: config.database,
-			warehouse: config.warehouse,
-			schema: config.schema,
-			role: config.role
-		});
-		connection.connect((err) => {
-			if (err) {
-				resolve({
-					success: false,
-					message: "Connection failed",
-					error: err.message
-				});
-				return;
-			}
-			connection.execute({
-				sqlText: "SELECT 1",
-				complete: (queryErr) => {
-					const latencyMs = Date.now() - startTime;
-					connection.destroy(() => {});
-					if (queryErr) resolve({
-						success: false,
-						message: "Query failed",
-						error: queryErr.message,
-						latencyMs
-					});
-					else resolve({
-						success: true,
-						message: "Connection successful",
-						latencyMs
-					});
-				}
-			});
-		});
-	});
-}
-async function querySnowflake(config, credentials, sql, options = {}) {
-	const snowflake = loadSnowflake();
-	if (!snowflake) return {
-		columns: [],
-		rows: [],
-		rowCount: 0,
-		truncated: false,
-		error: "Snowflake driver not installed. Run: pnpm add snowflake-sdk"
-	};
-	const limit = options.limit ?? 1e3;
-	return new Promise((resolve) => {
-		const connection = snowflake.createConnection({
-			account: config.account,
-			username: credentials.username,
-			password: credentials.password,
-			database: options.database || config.database,
-			warehouse: config.warehouse,
-			schema: options.schema || config.schema,
-			role: config.role
-		});
-		connection.connect((err) => {
-			if (err) {
-				resolve({
-					columns: [],
-					rows: [],
-					rowCount: 0,
-					truncated: false,
-					error: err.message
-				});
-				return;
-			}
-			connection.execute({
-				sqlText: sql,
-				complete: (queryErr, _stmt, rows) => {
-					connection.destroy(() => {});
-					if (queryErr) {
-						resolve({
-							columns: [],
-							rows: [],
-							rowCount: 0,
-							truncated: false,
-							error: queryErr.message
-						});
-						return;
-					}
-					const allRows = rows || [];
-					const truncated = allRows.length > limit;
-					const resultRows = truncated ? allRows.slice(0, limit) : allRows;
-					resolve({
-						columns: resultRows.length > 0 ? Object.keys(resultRows[0]) : [],
-						rows: resultRows,
-						rowCount: resultRows.length,
-						truncated
-					});
-				}
-			});
-		});
-	});
-}
-
-//#endregion
-//#region src/lib/connection/postgres.ts
-/**
-* Postgres connection testing and querying
-*/
-const require$3 = createRequire(import.meta.url);
-function loadPg() {
-	try {
-		return require$3("pg");
-	} catch {
-		return null;
-	}
-}
-function createClient(config, credentials, pg) {
-	return new pg.Client({
-		host: config.host,
-		port: config.port ? parseInt(config.port, 10) : 5432,
-		database: config.database,
-		user: credentials.username,
-		password: credentials.password,
-		ssl: config.sslmode === "require" ? { rejectUnauthorized: false } : void 0
-	});
-}
-async function testPostgresConnection(config, credentials) {
-	const pg = loadPg();
-	if (!pg) return {
-		success: false,
-		message: "Postgres driver not installed",
-		error: "Run: pnpm add pg"
-	};
-	const startTime = Date.now();
-	const client = createClient(config, credentials, pg);
-	try {
-		await client.connect();
-		await client.query("SELECT 1");
-		const latencyMs = Date.now() - startTime;
-		await client.end();
-		return {
-			success: true,
-			message: "Connection successful",
-			latencyMs
-		};
-	} catch (err) {
-		try {
-			await client.end();
-		} catch {}
-		return {
-			success: false,
-			message: "Connection failed",
-			error: err.message
-		};
-	}
-}
-async function queryPostgres(config, credentials, sql, options = {}) {
-	const pg = loadPg();
-	if (!pg) return {
-		columns: [],
-		rows: [],
-		rowCount: 0,
-		truncated: false,
-		error: "Postgres driver not installed. Run: pnpm add pg"
-	};
-	const limit = options.limit ?? 1e3;
-	const client = createClient(config, credentials, pg);
-	try {
-		await client.connect();
-		const schema = options.schema || config.schema;
-		if (schema) {
-			if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schema)) throw new Error("Invalid schema name");
-			await client.query(`SET search_path TO "${schema}"`);
-		}
-		const result = await client.query(sql);
-		await client.end();
-		const columns = result.fields?.map((f) => f.name) || [];
-		const allRows = result.rows || [];
-		const truncated = allRows.length > limit;
-		const rows = truncated ? allRows.slice(0, limit) : allRows;
-		return {
-			columns,
-			rows,
-			rowCount: rows.length,
-			truncated
-		};
-	} catch (err) {
-		try {
-			await client.end();
-		} catch {}
-		return {
-			columns: [],
-			rows: [],
-			rowCount: 0,
-			truncated: false,
-			error: err.message
-		};
-	}
-}
-
-//#endregion
-//#region src/lib/connection/bigquery.ts
-/**
-* BigQuery connection testing
-*/
-const require$2 = createRequire(import.meta.url);
-async function testBigQueryConnection(config, credentials) {
-	let BigQuery;
-	try {
-		BigQuery = require$2("@google-cloud/bigquery").BigQuery;
-	} catch {
-		return {
-			success: false,
-			message: "BigQuery driver not installed",
-			error: "Run: pnpm add @google-cloud/bigquery"
-		};
-	}
-	const startTime = Date.now();
-	try {
-		const options = { projectId: config.project_id };
-		if (config.location) options.location = config.location;
-		if (credentials.service_account_json) options.credentials = JSON.parse(credentials.service_account_json);
-		else if (credentials.keyfile_path) options.keyFilename = credentials.keyfile_path;
-		await new BigQuery(options).query("SELECT 1");
-		return {
-			success: true,
-			message: "Connection successful",
-			latencyMs: Date.now() - startTime
-		};
-	} catch (err) {
-		return {
-			success: false,
-			message: "Connection failed",
-			error: err.message
-		};
-	}
-}
-
-//#endregion
-//#region src/lib/connection/databricks.ts
-/**
-* Databricks connection testing
-*/
-const require$1 = createRequire(import.meta.url);
-async function testDatabricksConnection(config, credentials) {
-	let DBSQLClient;
-	try {
-		const module = require$1("@databricks/sql");
-		DBSQLClient = module.default || module;
-	} catch {
-		return {
-			success: false,
-			message: "Databricks driver not installed",
-			error: "Run: pnpm add @databricks/sql"
-		};
-	}
-	const startTime = Date.now();
-	const client = new DBSQLClient();
-	try {
-		const connection = await client.connect({
-			host: config.hostname,
-			path: config.http_path,
-			token: credentials.token
-		});
-		const session = await connection.openSession({
-			initialCatalog: config.catalog,
-			initialSchema: config.schema
-		});
-		const operation = await session.executeStatement("SELECT 1");
-		await operation.fetchAll();
-		await operation.close();
-		const latencyMs = Date.now() - startTime;
-		await session.close();
-		await connection.close();
-		return {
-			success: true,
-			message: "Connection successful",
-			latencyMs
-		};
-	} catch (err) {
-		try {
-			await client.close();
-		} catch {}
-		return {
-			success: false,
-			message: "Connection failed",
-			error: err.message
-		};
-	}
-}
-
-//#endregion
-//#region src/lib/connection/index.ts
-var connection_exports = /* @__PURE__ */ __exportAll({
-	executeQuery: () => executeQuery,
-	testConnection: () => testConnection
-});
-/**
-* Test connection to a datasource
-*/
-async function testConnection(datasource) {
-	const { type, config, credentials } = datasource;
-	switch (type) {
-		case "snowflake": return testSnowflakeConnection({
-			account: config.account,
-			database: config.database,
-			warehouse: config.warehouse,
-			schema: config.schema,
-			role: config.role
-		}, {
-			username: credentials.username,
-			password: credentials.password
-		});
-		case "postgres": return testPostgresConnection({
-			host: config.host,
-			port: config.port,
-			database: config.database,
-			schema: config.schema,
-			sslmode: config.sslmode
-		}, {
-			username: credentials.username,
-			password: credentials.password
-		});
-		case "bigquery": return testBigQueryConnection({
-			project_id: config.project_id,
-			dataset: config.dataset,
-			location: config.location
-		}, {
-			service_account_json: credentials.service_account_json,
-			keyfile_path: credentials.keyfile_path
-		});
-		case "databricks": return testDatabricksConnection({
-			hostname: config.hostname,
-			http_path: config.http_path,
-			catalog: config.catalog,
-			schema: config.schema
-		}, { token: credentials.token });
-		default: return {
-			success: false,
-			message: `Unsupported warehouse type: ${type}`
-		};
-	}
-}
-/**
-* Execute a query against a datasource
-*/
-async function executeQuery(datasource, sql, options = {}) {
-	const { type, config, credentials } = datasource;
-	switch (type) {
-		case "snowflake": return querySnowflake({
-			account: config.account,
-			database: config.database,
-			warehouse: config.warehouse,
-			schema: config.schema,
-			role: config.role
-		}, {
-			username: credentials.username,
-			password: credentials.password
-		}, sql, options);
-		case "postgres": return queryPostgres({
-			host: config.host,
-			port: config.port,
-			database: config.database,
-			schema: config.schema,
-			sslmode: config.sslmode
-		}, {
-			username: credentials.username,
-			password: credentials.password
-		}, sql, options);
-		case "bigquery": return {
-			columns: [],
-			rows: [],
-			rowCount: 0,
-			truncated: false,
-			error: "BigQuery local querying not yet implemented"
-		};
-		case "databricks": return {
-			columns: [],
-			rows: [],
-			rowCount: 0,
-			truncated: false,
-			error: "Databricks local querying not yet implemented"
-		};
-		default: return {
-			columns: [],
-			rows: [],
-			rowCount: 0,
-			truncated: false,
-			error: `Unsupported warehouse type: ${type}`
-		};
-	}
-}
-
 //#endregion
 //#region src/commands/datasource/test.ts
-async function datasourceTestCommand(name, options = {}) {
-	const localDs = getLocalDatasource(name);
-	if (options.remote || !localDs) {
-		await testRemote(name, !localDs);
-		return;
-	}
-	await testLocal(name, localDs);
-}
-/**
-* Test datasource locally using direct connection
-*/
-async function testLocal(name, ds) {
-	console.log(pc.dim(`Testing ${name} locally...`));
-	console.log();
-	const { resolved, missing } = resolveEnvVarsInCredentials(ds.credentials);
-	if (missing.length > 0) {
-		console.log(pc.red(`Missing environment variables: ${missing.join(", ")}`));
-		console.log(pc.dim("Set these env vars or update .bon/datasources.yaml with actual values."));
-		process.exit(1);
-	}
-	const result = await testConnection({
-		type: ds.type,
-		config: ds.config,
-		credentials: resolved
-	});
-	if (result.success) {
-		console.log(pc.green(`✓ ${result.message}`));
-		if (result.latencyMs) console.log(pc.dim(`  Latency: ${result.latencyMs}ms`));
-	} else {
-		console.log(pc.red(`✗ ${result.message}`));
-		if (result.error) console.log(pc.dim(`  ${result.error}`));
-		process.exit(1);
-	}
-}
-/**
-* Test datasource via remote API (requires login)
-*/
-async function testRemote(name, notFoundLocally) {
+async function datasourceTestCommand(name) {
 	if (!loadCredentials()) {
-		if (notFoundLocally) {
-			console.log(pc.red(`Datasource "${name}" not found locally.`));
-			console.log(pc.dim("Run `bon datasource add` to create it, or `bon login` to test remote datasources."));
-		} else console.log(pc.red("Not logged in. Run `bon login` to test remote datasources."));
+		console.log(pc.red("Not logged in. Run `bon login` to test datasources."));
 		process.exit(1);
 	}
 	console.log(pc.dim(`Testing ${name} via remote API...`));
@@ -2228,58 +1774,16 @@ async function pushDatasource(name, options = {}) {
 	}
 }
 
-//#endregion
-//#region src/commands/preview.ts
-async function previewCommand(datasourceName, sql, options) {
-	const limit = options.limit ? parseInt(options.limit, 10) : 1e3;
-	const format = options.format ?? "toon";
-	const ds = getLocalDatasource(datasourceName);
-	if (!ds) {
-		console.error(pc.red(`Datasource "${datasourceName}" not found in .bon/datasources.yaml`));
-		console.log(pc.dim("Run `bon datasource add` to create it."));
-		process.exit(1);
-	}
-	const { resolved, missing } = resolveEnvVarsInCredentials(ds.credentials);
-	if (missing.length > 0) {
-		console.error(pc.red(`Missing environment variables: ${missing.join(", ")}`));
-		console.log(pc.dim("Set these env vars or update .bon/datasources.yaml with actual values."));
-		process.exit(1);
-	}
-	const result = await executeQuery({
-		type: ds.type,
-		config: ds.config,
-		credentials: resolved
-	}, sql, {
-		limit,
-		schema: options.schema,
-		database: options.database
-	});
-	if (result.error) {
-		console.error(pc.red(result.error));
-		process.exit(1);
-	}
-	if (result.rowCount === 0) {
-		console.log("No rows returned.");
-		return;
-	}
-	if (format === "json") console.log(JSON.stringify(result, null, 2));
-	else {
-		const toon = encode({ results: result.rows });
-		console.log(toon);
-	}
-	if (result.truncated) console.log(pc.dim(`(truncated to ${result.rowCount} rows)`));
-}
-
 //#endregion
 //#region src/commands/validate.ts
-async function validateCommand(options = {}) {
+async function validateCommand() {
 	const cwd = process.cwd();
 	const paths = getProjectPaths(cwd);
 	if (!fs.existsSync(paths.config)) {
 		console.log(pc.red("No bon.yaml found. Are you in a Bonnard project?"));
 		process.exit(1);
 	}
-	const { validate } = await import("./validate-DiN3DaTl.mjs");
+	const { validate } = await import("./validate-DEh1XQnH.mjs");
 	const result = await validate(cwd);
 	if (result.cubes.length === 0 && result.views.length === 0 && result.valid) {
 		console.log(pc.yellow(`No cube or view files found in ${BONNARD_DIR}/cubes/ or ${BONNARD_DIR}/views/.`));
@@ -2307,61 +1811,12 @@ async function validateCommand(options = {}) {
 		}
 		for (const [parent, items] of byParent) console.log(pc.dim(`  ${parent}: ${items.join(", ")}`));
 	}
-	if (options.testConnection) {
-		console.log();
-		await testReferencedConnections(cwd);
-	}
-}
-/**
-* Test connections for datasources referenced by cubes and views
-* Lenient: warns but doesn't fail validation
-*/
-async function testReferencedConnections(cwd) {
-	const { extractDatasourcesFromCubes } = await import("./cubes-De1_2_YJ.mjs");
-	const { loadLocalDatasources, resolveEnvVarsInCredentials } = await Promise.resolve().then(() => local_exports);
-	const { testConnection } = await Promise.resolve().then(() => connection_exports);
-	const references = extractDatasourcesFromCubes(cwd);
-	if (references.length === 0) {
-		console.log(pc.dim("No datasource references found in cubes."));
-		return;
-	}
-	console.log(pc.bold("Testing connections..."));
-	console.log();
-	const localDatasources = loadLocalDatasources(cwd);
-	let warnings = 0;
-	for (const ref of references) {
-		const ds = localDatasources.find((d) => d.name === ref.name);
-		if (!ds) {
-			console.log(pc.yellow(`⚠ ${ref.name}: not found in .bon/datasources.yaml`));
-			console.log(pc.dim(`    Used by: ${ref.cubes.join(", ")}`));
-			warnings++;
-			continue;
-		}
-		const { resolved, missing } = resolveEnvVarsInCredentials(ds.credentials);
-		if (missing.length > 0) {
-			console.log(pc.yellow(`⚠ ${ref.name}: missing env vars: ${missing.join(", ")}`));
-			console.log(pc.dim(`    Used by: ${ref.cubes.join(", ")}`));
-			warnings++;
-			continue;
-		}
-		const result = await testConnection({
-			type: ds.type,
-			config: ds.config,
-			credentials: resolved
-		});
-		if (result.success) {
-			const latency = result.latencyMs ? pc.dim(` (${result.latencyMs}ms)`) : "";
-			console.log(pc.green(`✓ ${ref.name}${latency}`));
-		} else {
-			console.log(pc.yellow(`⚠ ${ref.name}: ${result.error || result.message}`));
-			console.log(pc.dim(`    Used by: ${ref.cubes.join(", ")}`));
-			warnings++;
-		}
-	}
-	if (warnings > 0) {
+	if (result.cubesMissingDataSource.length > 0) {
 		console.log();
-		console.log(pc.yellow(`${warnings} connection warning(s)`));
-		console.log(pc.dim("Connection issues won't block file validation, but will fail at deploy."));
+		console.log(pc.yellow(`⚠ ${result.cubesMissingDataSource.length} cube(s) missing data_source`));
+		console.log(pc.dim("  Without an explicit data_source, cubes use the default warehouse."));
+		console.log(pc.dim("  This can cause issues when multiple warehouses are configured."));
+		console.log(pc.dim(`  ${result.cubesMissingDataSource.join(", ")}`));
 	}
 }
 
@@ -2383,6 +1838,9 @@ function collectFiles(dir, rootDir) {
 	walk(dir);
 	return files;
 }
+function capitalize$1(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
 async function deployCommand(options = {}) {
 	const cwd = process.cwd();
 	const paths = getProjectPaths(cwd);
@@ -2391,7 +1849,7 @@ async function deployCommand(options = {}) {
 		process.exit(1);
 	}
 	console.log(pc.dim("Validating cubes and views..."));
-	const { validate } = await import("./validate-DiN3DaTl.mjs");
+	const { validate } = await import("./validate-DEh1XQnH.mjs");
 	const result = await validate(cwd);
 	if (!result.valid) {
 		console.log(pc.red("Validation failed:\n"));
@@ -2412,10 +1870,40 @@ async function deployCommand(options = {}) {
 	console.log(pc.dim(`Deploying ${fileCount} file(s)...`));
 	console.log();
 	try {
-		const response = await post("/api/deploy", { files });
+		const response = await post("/api/deploy", {
+			files,
+			...options.message && { message: options.message }
+		});
 		console.log(pc.green("Deploy successful!"));
 		console.log(`Deployment ID: ${pc.cyan(response.deployment.id)}`);
-		console.log(`API: ${pc.cyan(response.deployment.cubeApiUrl)}`);
+		console.log();
+		if (response.deployment.isFirstDeploy) console.log(pc.dim(`  First deployment — ${response.deployment.fileCount} files uploaded`));
+		else if (response.deployment.changes && response.deployment.changes.details.length > 0) {
+			const { changes } = response.deployment;
+			console.log(pc.dim("Changes from previous deploy:"));
+			console.log();
+			for (const c of changes.details) {
+				const prefix = c.changeType === "added" ? pc.green("+") : c.changeType === "removed" ? pc.red("-") : pc.yellow("~");
+				const label = `${capitalize$1(c.changeType)} ${c.objectType}: ${c.objectName}`;
+				const breakingTag = c.breaking ? pc.red(" BREAKING") : "";
+				const summaryTag = c.summary ? pc.dim(` — ${c.summary}`) : "";
+				console.log(`  ${prefix} ${label}${summaryTag}${breakingTag}`);
+			}
+			if (changes.breaking > 0) {
+				console.log();
+				console.log(pc.red(`${changes.breaking} breaking change${changes.breaking > 1 ? "s" : ""} detected`));
+			}
+			console.log();
+			console.log(pc.bold("Annotate these changes with reasoning:"));
+			console.log();
+			const annotationTemplate = { annotations: changes.details.map((c) => ({
+				objectName: c.objectName,
+				annotation: `Why ${c.objectName} was ${c.changeType}`
+			})) };
+			console.log(`  bon annotate ${response.deployment.id} --data '${JSON.stringify(annotationTemplate)}'`);
+			console.log();
+			console.log(pc.dim("Replace each annotation value with the reasoning behind the change."));
+		} else console.log(pc.dim("  No changes detected from previous deployment."));
 		console.log();
 		console.log(pc.bold("Connect AI agents via MCP:"));
 		console.log(`  MCP URL: ${pc.cyan("https://mcp.bonnard.dev/mcp")}`);
@@ -2430,51 +1918,29 @@ async function deployCommand(options = {}) {
 * Returns true if any connection failed (strict mode)
 */
 async function testAndSyncDatasources(cwd, options = {}) {
-	const { extractDatasourcesFromCubes } = await import("./cubes-De1_2_YJ.mjs");
-	const { loadLocalDatasources, resolveEnvVarsInCredentials } = await Promise.resolve().then(() => local_exports);
-	const { testConnection } = await Promise.resolve().then(() => connection_exports);
+	const { extractDatasourcesFromCubes } = await import("./cubes-Bf0IPYd7.mjs");
+	const { loadLocalDatasources } = await Promise.resolve().then(() => local_exports);
 	const { pushDatasource } = await Promise.resolve().then(() => push_exports);
 	const references = extractDatasourcesFromCubes(cwd);
 	if (references.length === 0) return false;
 	console.log();
-	console.log(pc.dim("Testing datasource connections..."));
+	console.log(pc.dim("Checking datasources..."));
 	const localDatasources = loadLocalDatasources(cwd);
 	let failed = false;
-	const validatedDatasources = [];
+	const foundDatasources = [];
 	for (const ref of references) {
-		const ds = localDatasources.find((d) => d.name === ref.name);
-		if (!ds) {
+		if (!localDatasources.find((d) => d.name === ref.name)) {
 			console.log(pc.red(`✗ ${ref.name}: not found in .bon/datasources.yaml`));
 			console.log(pc.dim(`    Used by: ${ref.cubes.join(", ")}`));
 			console.log(pc.dim(`    Run: bon datasource add --from-dbt`));
 			failed = true;
 			continue;
 		}
-		const { resolved, missing } = resolveEnvVarsInCredentials(ds.credentials);
-		if (missing.length > 0) {
-			console.log(pc.red(`✗ ${ref.name}: missing env vars: ${missing.join(", ")}`));
-			console.log(pc.dim(`    Used by: ${ref.cubes.join(", ")}`));
-			failed = true;
-			continue;
-		}
-		const result = await testConnection({
-			type: ds.type,
-			config: ds.config,
-			credentials: resolved
-		});
-		if (result.success) {
-			const latency = result.latencyMs ? pc.dim(` (${result.latencyMs}ms)`) : "";
-			console.log(pc.green(`✓ ${ref.name}${latency}`));
-			validatedDatasources.push(ref.name);
-		} else {
-			console.log(pc.red(`✗ ${ref.name}: ${result.error || result.message}`));
-			console.log(pc.dim(`    Used by: ${ref.cubes.join(", ")}`));
-			failed = true;
-		}
+		foundDatasources.push(ref.name);
 	}
-	console.log();
 	if (failed) {
-		console.log(pc.red("Connection tests failed. Fix datasource issues before deploying."));
+		console.log();
+		console.log(pc.red("Missing datasources. Fix issues before deploying."));
 		return true;
 	}
 	console.log(pc.dim("Checking remote datasources..."));
@@ -2486,22 +1952,17 @@ async function testAndSyncDatasources(cwd, options = {}) {
 		return true;
 	}
 	const remoteNames = new Set(remoteDatasources.map((ds) => ds.name));
-	const missingRemote = validatedDatasources.filter((name) => !remoteNames.has(name));
-	if (missingRemote.length === 0) {
-		console.log(pc.green("✓ All datasources exist on remote"));
+	const missingRemote = foundDatasources.filter((name) => !remoteNames.has(name));
+	if (missingRemote.length > 0) {
 		console.log();
-		return false;
-	}
-	console.log();
-	console.log(pc.yellow(`⚠ Missing remote datasource${missingRemote.length > 1 ? "s" : ""}: ${missingRemote.join(", ")}`));
-	console.log();
-	if (options.ci) {
-		console.log(pc.red("Deploy aborted (--ci mode)."));
-		console.log(pc.dim(`Run: bon datasource push <name>`));
-		return true;
-	}
-	if (options.pushDatasources) {
-		for (const name of missingRemote) {
+		console.log(pc.yellow(`⚠ Missing remote datasource${missingRemote.length > 1 ? "s" : ""}: ${missingRemote.join(", ")}`));
+		console.log();
+		if (options.ci) {
+			console.log(pc.red("Deploy aborted (--ci mode)."));
+			console.log(pc.dim(`Run: bon datasource push <name>`));
+			return true;
+		}
+		if (options.pushDatasources) for (const name of missingRemote) {
 			console.log(pc.dim(`Pushing "${name}"...`));
 			if (await pushDatasource(name, { silent: true })) console.log(pc.green(`✓ Pushed "${name}"`));
 			else {
@@ -2509,27 +1970,249 @@ async function testAndSyncDatasources(cwd, options = {}) {
 				return true;
 			}
 		}
-		console.log();
-		return false;
+		else {
+			if (!await confirm({
+				message: `Push ${missingRemote.length > 1 ? "these datasources" : `"${missingRemote[0]}"`} to Bonnard? (credentials will be encrypted)`,
+				default: true
+			})) {
+				console.log(pc.dim("Deploy aborted."));
+				return true;
+			}
+			console.log();
+			for (const name of missingRemote) {
+				console.log(pc.dim(`Pushing "${name}"...`));
+				if (await pushDatasource(name, { silent: true })) console.log(pc.green(`✓ Pushed "${name}"`));
+				else {
+					console.log(pc.red(`✗ Failed to push "${name}"`));
+					return true;
+				}
+			}
+		}
+	}
+	console.log();
+	console.log(pc.dim("Testing datasource connections..."));
+	for (const name of foundDatasources) try {
+		const result = await post("/api/datasources/test", { name });
+		if (result.success) {
+			const latency = result.details?.latencyMs ? pc.dim(` (${result.details.latencyMs}ms)`) : "";
+			console.log(pc.green(`✓ ${name}${latency}`));
+		} else {
+			console.log(pc.red(`✗ ${name}: ${result.message}`));
+			failed = true;
+		}
+	} catch (err) {
+		console.log(pc.red(`✗ ${name}: ${err.message}`));
+		failed = true;
 	}
-	if (!await confirm({
-		message: `Push ${missingRemote.length > 1 ? "these datasources" : `"${missingRemote[0]}"`} to Bonnard? (credentials will be encrypted)`,
-		default: true
-	})) {
-		console.log(pc.dim("Deploy aborted."));
+	console.log();
+	if (failed) {
+		console.log(pc.red("Connection tests failed. Fix datasource issues before deploying."));
 		return true;
 	}
+	console.log(pc.green("✓ All datasources connected"));
 	console.log();
-	for (const name of missingRemote) {
-		console.log(pc.dim(`Pushing "${name}"...`));
-		if (await pushDatasource(name, { silent: true })) console.log(pc.green(`✓ Pushed "${name}"`));
-		else {
-			console.log(pc.red(`✗ Failed to push "${name}"`));
-			return true;
+	return false;
+}
+
+//#endregion
+//#region src/commands/deployments.ts
+function relativeTime(dateStr) {
+	const now = Date.now();
+	const then = new Date(dateStr).getTime();
+	const seconds = Math.floor((now - then) / 1e3);
+	if (seconds < 60) return "just now";
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes} min ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours} hour${hours > 1 ? "s" : ""} ago`;
+	const days = Math.floor(hours / 24);
+	return `${days} day${days > 1 ? "s" : ""} ago`;
+}
+function truncate(str, max) {
+	if (str.length <= max) return str;
+	return str.slice(0, max - 1) + "…";
+}
+function statusColor(status) {
+	switch (status) {
+		case "success": return pc.green(status);
+		case "failed": return pc.red(status);
+		case "processing": return pc.yellow(status);
+		default: return pc.dim(status);
+	}
+}
+async function deploymentsCommand(options = {}) {
+	const limit = options.all ? 100 : 10;
+	let response;
+	try {
+		response = await get(`/api/deploy/history?limit=${limit}`);
+	} catch (err) {
+		console.log(pc.red(`Failed to fetch deployments: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+	const { deployments } = response;
+	if (options.format === "json") {
+		console.log(JSON.stringify(deployments, null, 2));
+		return;
+	}
+	console.log();
+	console.log(pc.bold("Deployments for Bonnard"));
+	console.log();
+	if (deployments.length === 0) {
+		console.log(pc.dim("  No deployments found."));
+		console.log();
+		return;
+	}
+	const colId = 10;
+	const colStatus = 12;
+	const colFiles = 7;
+	const colMessage = 32;
+	console.log(pc.dim("  " + "ID".padEnd(colId) + "Status".padEnd(colStatus) + "Files".padEnd(colFiles) + "Message".padEnd(colMessage) + "Deployed"));
+	for (const d of deployments) {
+		const id = d.id.slice(0, 8);
+		const status = statusColor(d.status);
+		const statusPad = " ".repeat(Math.max(0, colStatus - d.status.length));
+		const files = String(d.fileCount);
+		const message = d.message ? truncate(d.message, 30) : "—";
+		const time = relativeTime(d.createdAt);
+		console.log("  " + id.padEnd(colId) + status + statusPad + files.padEnd(colFiles) + message.padEnd(colMessage) + pc.dim(time));
+	}
+	console.log();
+	console.log(pc.dim(`Showing ${deployments.length} deployment${deployments.length !== 1 ? "s" : ""}.`));
+	console.log();
+}
+
+//#endregion
+//#region src/commands/annotate.ts
+function readStdin() {
+	return new Promise((resolve) => {
+		if (process.stdin.isTTY) {
+			resolve(null);
+			return;
 		}
+		let data = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => data += chunk);
+		process.stdin.on("end", () => resolve(data.trim() || null));
+		setTimeout(() => resolve(data.trim() || null), 100);
+	});
+}
+function parseAnnotations(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error("Invalid JSON. Expected: {\"annotations\": [{\"objectName\": \"...\", \"annotation\": \"...\"}]}");
+	}
+	const obj = parsed;
+	if (!obj.annotations || !Array.isArray(obj.annotations) || obj.annotations.length === 0) throw new Error("JSON must contain a non-empty \"annotations\" array");
+	for (const entry of obj.annotations) {
+		const e = entry;
+		if (!e.objectName || typeof e.objectName !== "string") throw new Error("Each annotation must have a string \"objectName\"");
+		if (!e.annotation || typeof e.annotation !== "string") throw new Error(`Missing \"annotation\" text for \"${e.objectName}\"`);
+		if (e.annotation.length > 1e3) throw new Error(`Annotation for \"${e.objectName}\" exceeds 1000 chars`);
+	}
+	return { annotations: obj.annotations };
+}
+async function annotateCommand(id, options = {}) {
+	const raw = options.data || await readStdin();
+	if (!raw) {
+		try {
+			const { changes } = await get(`/api/deploy/changes/${id}`);
+			if (changes.length === 0) {
+				console.log(pc.dim("No changes recorded for this deployment."));
+				return;
+			}
+			console.log();
+			console.log(pc.bold(`Changes in deployment ${id.slice(0, 8)}`));
+			console.log();
+			for (const c of changes) {
+				const prefix = c.changeType === "added" ? pc.green("+") : c.changeType === "removed" ? pc.red("-") : pc.yellow("~");
+				const label = `${c.changeType} ${c.objectType}: ${c.objectName}`;
+				const breakingTag = c.breaking ? pc.red(" BREAKING") : "";
+				console.log(`  ${prefix} ${label}${breakingTag}`);
+				if (c.annotation) console.log(pc.dim(`      "${c.annotation}"`));
+			}
+			console.log();
+			console.log(pc.dim("To annotate, provide JSON via --data or stdin:"));
+			console.log(pc.dim(`  bon annotate ${id.slice(0, 8)} --data '{"annotations":[{"objectName":"...","annotation":"..."}]}'`));
+			console.log();
+		} catch (err) {
+			console.log(pc.red(`Failed to fetch changes: ${err instanceof Error ? err.message : err}`));
+			process.exit(1);
+		}
+		return;
+	}
+	let payload;
+	try {
+		payload = parseAnnotations(raw);
+	} catch (err) {
+		console.log(pc.red(err instanceof Error ? err.message : String(err)));
+		process.exit(1);
+	}
+	try {
+		const response = await post(`/api/deploy/annotate/${id}`, payload);
+		console.log(pc.green(`Annotated ${response.updated}/${response.total} changes.`));
+	} catch (err) {
+		console.log(pc.red(`Failed to submit annotations: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/diff.ts
+async function diffCommand(id, options = {}) {
+	let response;
+	try {
+		response = await get(`/api/deploy/changes/${id}`);
+	} catch (err) {
+		console.log(pc.red(`Failed to fetch changes: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+	let { changes } = response;
+	if (options.breaking) changes = changes.filter((c) => c.breaking);
+	if (options.format === "json") {
+		console.log(JSON.stringify(changes, null, 2));
+		return;
 	}
 	console.log();
-	return false;
+	console.log(pc.bold(`Changes in deployment ${id.slice(0, 8)}`));
+	console.log();
+	if (changes.length === 0) {
+		console.log(pc.dim("  No changes recorded."));
+		console.log();
+		return;
+	}
+	for (const c of changes) {
+		const prefix = c.changeType === "added" ? pc.green("+") : c.changeType === "removed" ? pc.red("-") : pc.yellow("~");
+		const label = `${capitalize(c.changeType)} ${c.objectType}: ${c.objectName}`;
+		const breakingTag = c.breaking ? pc.red(" BREAKING") : "";
+		console.log(`  ${prefix} ${label}${breakingTag}`);
+		const details = [];
+		if (c.summary) details.push(c.summary);
+		if (details.length > 0) console.log(pc.dim(`      ${details.join(" | ")}`));
+		if (c.changeType === "modified" && c.previousDefinition && c.newDefinition) for (const key of Object.keys(c.newDefinition)) {
+			const oldVal = c.previousDefinition[key];
+			const newVal = c.newDefinition[key];
+			if (oldVal !== newVal && oldVal !== void 0 && newVal !== void 0) console.log(pc.dim(`      ${key}: ${JSON.stringify(oldVal)} -> ${JSON.stringify(newVal)}`));
+		}
+		if (c.annotation) console.log(`      ${pc.cyan("\"" + c.annotation + "\"")}`);
+		console.log();
+	}
+	const added = changes.filter((c) => c.changeType === "added").length;
+	const modified = changes.filter((c) => c.changeType === "modified").length;
+	const removed = changes.filter((c) => c.changeType === "removed").length;
+	const breaking = changes.filter((c) => c.breaking).length;
+	const parts = [
+		`${added} added`,
+		`${modified} modified`,
+		`${removed} removed`
+	];
+	if (breaking > 0) parts.push(pc.red(`${breaking} breaking`));
+	console.log(pc.dim(`Summary: ${parts.join(", ")}`));
+	console.log();
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
 }
 
 //#endregion
@@ -2852,12 +2535,14 @@ program.command("whoami").description("Show current login status").option("--ver
 const datasource = program.command("datasource").description("Manage warehouse data source connections");
 datasource.command("add").description("Add a data source to .bon/datasources.yaml. Use --name and --type together for non-interactive mode").option("--demo", "Add a read-only demo datasource (Contoso retail dataset) for testing").option("--from-dbt [profile]", "Import from dbt profiles.yml (optionally specify profile/target)").option("--target <target>", "Target name when using --from-dbt").option("--all", "Import all connections from dbt profiles").option("--default-targets", "Import only default targets from dbt profiles (non-interactive)").option("--name <name>", "Datasource name (required for non-interactive mode)").option("--type <type>", "Warehouse type: snowflake, postgres, bigquery, databricks (required for non-interactive mode)").option("--account <account>", "Snowflake account identifier").option("--database <database>", "Database name").option("--schema <schema>", "Schema name").option("--warehouse <warehouse>", "Warehouse name (Snowflake)").option("--role <role>", "Role (Snowflake)").option("--host <host>", "Host (Postgres)").option("--port <port>", "Port (Postgres, default: 5432)").option("--project-id <projectId>", "GCP Project ID (BigQuery)").option("--dataset <dataset>", "Dataset name (BigQuery)").option("--location <location>", "Location (BigQuery)").option("--hostname <hostname>", "Server hostname (Databricks)").option("--http-path <httpPath>", "HTTP path (Databricks)").option("--catalog <catalog>", "Catalog name (Databricks)").option("--user <user>", "Username").option("--password <password>", "Password (use --password-env for env var reference)").option("--token <token>", "Access token (use --token-env for env var reference)").option("--service-account-json <json>", "Service account JSON (BigQuery)").option("--keyfile <path>", "Path to service account key file (BigQuery)").option("--password-env <varName>", "Env var name for password, stores as {{ env_var('NAME') }}").option("--token-env <varName>", "Env var name for token, stores as {{ env_var('NAME') }}").option("--force", "Overwrite existing datasource without prompting").action(datasourceAddCommand);
 datasource.command("list").description("List data sources (shows both local and remote by default)").option("--local", "Show only local data sources from .bon/datasources.yaml").option("--remote", "Show only remote data sources from Bonnard server (requires login)").action(datasourceListCommand);
-datasource.command("test").description("Test data source connectivity by connecting directly to the warehouse").argument("<name>", "Data source name from .bon/datasources.yaml").option("--remote", "Test via Bonnard API instead of direct connection (requires login)").action(datasourceTestCommand);
+datasource.command("test").description("Test data source connectivity via Bonnard API (requires login)").argument("<name>", "Data source name from .bon/datasources.yaml").action(datasourceTestCommand);
 datasource.command("remove").description("Remove a data source from .bon/datasources.yaml (local by default)").argument("<name>", "Data source name").option("--remote", "Remove from Bonnard server instead of local (requires login)").action(datasourceRemoveCommand);
 datasource.command("push").description("Push a local data source to Bonnard server (requires login)").argument("<name>", "Data source name from .bon/datasources.yaml").option("--force", "Overwrite if already exists on remote").action(datasourcePushCommand);
-program.command("preview").description("Preview data from a local warehouse using raw SQL (for development/exploration)").argument("<datasource>", "Data source name from .bon/datasources.yaml").argument("<sql>", "SQL query to execute").option("--schema <schema>", "Override schema").option("--database <database>", "Override database").option("--limit <limit>", "Max rows to return", "1000").option("--format <format>", "Output format: toon or json", "toon").action(previewCommand);
-program.command("validate").description("Validate YAML syntax in bonnard/cubes/ and bonnard/views/").option("--test-connection", "Also test datasource connections (warns on failure, doesn't block)").action(validateCommand);
-program.command("deploy").description("Deploy cubes and views to Bonnard. Requires login, validates, tests connections (fails on error)").option("--ci", "Non-interactive mode (fail if missing datasources)").option("--push-datasources", "Auto-push missing datasources without prompting").action(deployCommand);
+program.command("validate").description("Validate YAML syntax in bonnard/cubes/ and bonnard/views/").action(validateCommand);
+program.command("deploy").description("Deploy cubes and views to Bonnard. Requires login, validates, syncs datasources").option("--ci", "Non-interactive mode (fail if missing datasources)").option("--push-datasources", "Auto-push missing datasources without prompting").requiredOption("-m, --message <text>", "Deploy message describing your changes").action(deployCommand);
+program.command("deployments").description("List deployment history").option("--all", "Show all deployments (default: last 10)").option("--format <format>", "Output format: table or json", "table").action(deploymentsCommand);
+program.command("diff").description("Show changes in a deployment").argument("<id>", "Deployment ID").option("--format <format>", "Output format: table or json", "table").option("--breaking", "Show only breaking changes").action(diffCommand);
+program.command("annotate").description("Annotate deployment changes with reasoning").argument("<id>", "Deployment ID").option("--data <json>", "Annotations JSON").action(annotateCommand);
 program.command("mcp").description("MCP connection info and setup instructions").action(mcpCommand).command("test").description("Test MCP server connectivity").action(mcpTestCommand);
 program.command("query").description("Execute a query against the deployed semantic layer").argument("<query>", "JSON query or SQL (with --sql flag)").option("--sql", "Use SQL API instead of JSON format").option("--limit <limit>", "Max rows to return").option("--format <format>", "Output format: toon or json", "toon").action(cubeQueryCommand);
 program.command("docs").description("Browse documentation for building cubes and views").argument("[topic]", "Topic to display (e.g., cubes, cubes.measures)").option("-r, --recursive", "Show topic and all child topics").option("-s, --search <query>", "Search topics for a keyword").option("-f, --format <format>", "Output format: markdown or json", "markdown").action(docsCommand).command("schema").description("Show JSON schema for a type (cube, view, measure, etc.)").argument("<type>", "Schema type to display").action(docsSchemaCommand);