@bonnard/cli 0.2.6 → 0.2.7

package/dist/bin/bon.mjs

@@ -2698,11 +2698,11 @@ async function showOverview(client) {
 	console.log(pc.dim("  bon metabase explore collections"));
 	console.log(pc.dim("  bon metabase explore cards"));
 	console.log(pc.dim("  bon metabase explore dashboards"));
-	console.log(pc.dim("  bon metabase explore card <id>"));
-	console.log(pc.dim("  bon metabase explore dashboard <id>"));
-	console.log(pc.dim("  bon metabase explore database <id>"));
-	console.log(pc.dim("  bon metabase explore table <id>"));
-	console.log(pc.dim("  bon metabase explore collection <id>"));
+	console.log(pc.dim("  bon metabase explore card <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore dashboard <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore database <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore table <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore collection <id-or-name>"));
 }
 async function showDatabases(client) {
 	const databases = await client.getDatabases();
@@ -2778,7 +2778,7 @@ async function showCards(client) {
 		console.log();
 	}
 	if (models.length === 0 && metrics.length === 0 && questions.length === 0) console.log(pc.dim("  No cards found."));
-	console.log(pc.dim("View details: bon metabase explore card <id>"));
+	console.log(pc.dim("View details: bon metabase explore card <id-or-name>"));
 }
 async function showCardDetail(client, id) {
 	const card = await client.getCard(id);
@@ -2835,7 +2835,7 @@ async function showDashboards(client) {
 	console.log(`  ${pc.dim(padColumn("ID", 6))}${pc.dim("NAME")}`);
 	for (const d of active) console.log(`  ${padColumn(String(d.id), 6)}${d.name}`);
 	console.log();
-	console.log(pc.dim("View details: bon metabase explore dashboard <id>"));
+	console.log(pc.dim("View details: bon metabase explore dashboard <id-or-name>"));
 }
 async function showDashboardDetail(client, id) {
 	const [dashboard, allCards] = await Promise.all([client.getDashboard(id), client.getCards()]);
@@ -2895,7 +2895,7 @@ async function showDatabaseDetail(client, id) {
 		}
 		console.log();
 	}
-	console.log(pc.dim("View table fields: bon metabase explore table <id>"));
+	console.log(pc.dim("View table fields: bon metabase explore table <id-or-name>"));
 }
 function classifyFieldType(field) {
 	const bt = field.base_type || "";
@@ -3008,8 +3008,105 @@ async function showCollectionDetail(client, id) {
 		console.log();
 	}
 	if (cardItems.length === 0 && dashboardItems.length === 0) console.log(pc.dim("  No items in this collection."));
-	console.log(pc.dim("View card SQL: bon metabase explore card <id>"));
-	console.log(pc.dim("View dashboard: bon metabase explore dashboard <id>"));
+	console.log(pc.dim("View card SQL: bon metabase explore card <id-or-name>"));
+	console.log(pc.dim("View dashboard: bon metabase explore dashboard <id-or-name>"));
+}
+function isNumericId(value) {
+	return /^\d+$/.test(value);
+}
+function showDisambiguation(resource, matches) {
+	console.error(pc.yellow(`Multiple ${resource}s match that name:\n`));
+	for (const m of matches) console.log(`  ${padColumn(String(m.id), 8)}${m.label}`);
+	console.log();
+	console.log(pc.dim(`Use the numeric ID to be specific: bon metabase explore ${resource} <id>`));
+	process.exit(1);
+}
+async function resolveCardId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const cards = await client.getCards();
+	const needle = input.toLowerCase();
+	const matches = cards.filter((c) => c.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No card found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("card", matches.map((c) => ({
+		id: c.id,
+		label: c.name
+	})));
+}
+async function resolveDashboardId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const dashboards = await client.getDashboards();
+	const needle = input.toLowerCase();
+	const matches = dashboards.filter((d) => d.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No dashboard found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("dashboard", matches.map((d) => ({
+		id: d.id,
+		label: d.name
+	})));
+}
+async function resolveDatabaseId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const databases = await client.getDatabases();
+	const needle = input.toLowerCase();
+	const matches = databases.filter((d) => d.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No database found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("database", matches.map((d) => ({
+		id: d.id,
+		label: `${d.name} (${d.engine})`
+	})));
+}
+async function resolveTableId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const databases = await client.getDatabases();
+	const needle = input.toLowerCase();
+	const matches = [];
+	for (const db of databases) {
+		const meta = await client.getDatabaseMetadata(db.id);
+		for (const t of meta.tables) {
+			if (t.visibility_type === "hidden" || t.visibility_type === "retired") continue;
+			if (t.name.toLowerCase().includes(needle)) matches.push({
+				id: t.id,
+				name: t.name,
+				schema: t.schema,
+				dbName: db.name
+			});
+		}
+	}
+	if (matches.length === 0) {
+		console.error(pc.red(`No table found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("table", matches.map((m) => ({
+		id: m.id,
+		label: `${m.dbName} / ${m.schema}.${m.name}`
+	})));
+}
+async function resolveCollectionId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const collections = await client.getCollections();
+	const needle = input.toLowerCase();
+	const matches = collections.filter((c) => typeof c.id === "number" && c.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No collection found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("collection", matches.map((c) => ({
+		id: c.id,
+		label: c.name
+	})));
 }
 const RESOURCES = [
 	"databases",
@@ -3047,71 +3144,41 @@ async function metabaseExploreCommand(resource, id) {
 			case "dashboards":
 				await showDashboards(client);
 				break;
-			case "card": {
+			case "card":
 				if (!id) {
-					console.error(pc.red("Card ID required: bon metabase explore card <id>"));
+					console.error(pc.red("Usage: bon metabase explore card <id-or-name>"));
 					process.exit(1);
 				}
-				const cardId = parseInt(id, 10);
-				if (isNaN(cardId)) {
-					console.error(pc.red(`Invalid card ID: ${id}`));
-					process.exit(1);
-				}
-				await showCardDetail(client, cardId);
+				await showCardDetail(client, await resolveCardId(client, id));
 				break;
-			}
-			case "dashboard": {
+			case "dashboard":
 				if (!id) {
-					console.error(pc.red("Dashboard ID required: bon metabase explore dashboard <id>"));
+					console.error(pc.red("Usage: bon metabase explore dashboard <id-or-name>"));
 					process.exit(1);
 				}
-				const dashId = parseInt(id, 10);
-				if (isNaN(dashId)) {
-					console.error(pc.red(`Invalid dashboard ID: ${id}`));
-					process.exit(1);
-				}
-				await showDashboardDetail(client, dashId);
+				await showDashboardDetail(client, await resolveDashboardId(client, id));
 				break;
-			}
-			case "database": {
+			case "database":
 				if (!id) {
-					console.error(pc.red("Database ID required: bon metabase explore database <id>"));
-					process.exit(1);
-				}
-				const dbId = parseInt(id, 10);
-				if (isNaN(dbId)) {
-					console.error(pc.red(`Invalid database ID: ${id}`));
+					console.error(pc.red("Usage: bon metabase explore database <id-or-name>"));
 					process.exit(1);
 				}
-				await showDatabaseDetail(client, dbId);
+				await showDatabaseDetail(client, await resolveDatabaseId(client, id));
 				break;
-			}
-			case "table": {
+			case "table":
 				if (!id) {
-					console.error(pc.red("Table ID required: bon metabase explore table <id>"));
+					console.error(pc.red("Usage: bon metabase explore table <id-or-name>"));
 					process.exit(1);
 				}
-				const tableId = parseInt(id, 10);
-				if (isNaN(tableId)) {
-					console.error(pc.red(`Invalid table ID: ${id}`));
-					process.exit(1);
-				}
-				await showTableDetail(client, tableId);
+				await showTableDetail(client, await resolveTableId(client, id));
 				break;
-			}
-			case "collection": {
+			case "collection":
 				if (!id) {
-					console.error(pc.red("Collection ID required: bon metabase explore collection <id>"));
+					console.error(pc.red("Usage: bon metabase explore collection <id-or-name>"));
 					process.exit(1);
 				}
-				const colId = parseInt(id, 10);
-				if (isNaN(colId)) {
-					console.error(pc.red(`Invalid collection ID: ${id}`));
-					process.exit(1);
-				}
-				await showCollectionDetail(client, colId);
+				await showCollectionDetail(client, await resolveCollectionId(client, id));
 				break;
-			}
 		}
 	} catch (err) {
 		if (err instanceof MetabaseApiError) {
@@ -3454,10 +3521,10 @@ function buildReport(data) {
 	report += `5. **Collection Structure** → Map collections to views (one view per business domain)\n`;
 	report += `6. **Table Inventory** → Use field classification (dims/measures/time) to build each cube\n\n`;
 	report += `Drill deeper with:\n`;
-	report += `- \`bon metabase explore table <id>\` — field types and classification\n`;
-	report += `- \`bon metabase explore card <id>\` — SQL and columns\n`;
-	report += `- \`bon metabase explore collection <id>\` — cards in a collection\n`;
-	report += `- \`bon metabase explore database <id>\` — schemas and tables\n\n`;
+	report += `- \`bon metabase explore table <id-or-name>\` — field types and classification\n`;
+	report += `- \`bon metabase explore card <id-or-name>\` — SQL and columns\n`;
+	report += `- \`bon metabase explore collection <id-or-name>\` — cards in a collection\n`;
+	report += `- \`bon metabase explore database <id-or-name>\` — schemas and tables\n\n`;
 	report += `## Summary\n\n`;
 	report += `| Metric | Count |\n|--------|-------|\n`;
 	report += `| Databases | ${databases.length} |\n`;
@@ -3497,7 +3564,7 @@ function buildReport(data) {
 	report += "```\n\n";
 	report += `## Top ${topCards.length} Cards by Activity\n\n`;
 	report += `Ranked by view count, weighted by recency. Cards not used in the last ${INACTIVE_MONTHS} months are penalized 90%.\n`;
-	report += `Use \`bon metabase explore card <id>\` to view SQL and column details for any card.\n\n`;
+	report += `Use \`bon metabase explore card <id-or-name>\` to view SQL and column details for any card.\n\n`;
 	report += `| Rank | ID | Views | Last Used | Active | Pattern | Type | Display | Collection | Name |\n`;
 	report += `|------|----|-------|-----------|--------|---------|------|---------|------------|------|\n`;
 	for (let i = 0; i < topCards.length; i++) {
@@ -3555,8 +3622,18 @@ function buildReport(data) {
 		const sortedRefs = Array.from(globalTableRefs.entries()).sort((a, b) => b[1] - a[1]).slice(0, 20);
 		report += `## Most Referenced Tables (from SQL)\n\n`;
 		report += `Tables most frequently referenced in FROM/JOIN clauses across all cards.\n\n`;
-		report += `| Table | References |\n|-------|------------|\n`;
-		for (const [table, count] of sortedRefs) report += `| ${table} | ${count} |\n`;
+		const tableIdByRef = /* @__PURE__ */ new Map();
+		for (const db of databases) for (const t of db.tables) {
+			const qualified = `${t.schema}.${t.name}`.toLowerCase();
+			const unqualified = t.name.toLowerCase();
+			if (!tableIdByRef.has(qualified)) tableIdByRef.set(qualified, t.id);
+			if (!tableIdByRef.has(unqualified)) tableIdByRef.set(unqualified, t.id);
+		}
+		report += `| ID | Table | References |\n|------|-------|------------|\n`;
+		for (const [table, count] of sortedRefs) {
+			const tid = tableIdByRef.get(table);
+			report += `| ${tid ?? "—"} | ${table} | ${count} |\n`;
+		}
 		report += `\n`;
 	}
 	const fieldIdLookup = /* @__PURE__ */ new Map();
@@ -3656,9 +3733,9 @@ function buildReport(data) {
 			report += `### ${db.name} / ${schema} (${referenced.length} referenced`;
 			if (unreferenced > 0) report += `, ${unreferenced} unreferenced`;
 			report += `)\n\n`;
-			report += `| Table | Fields | Dims | Measures | Time | Refs |\n`;
-			report += `|-------|--------|------|----------|------|------|\n`;
-			for (const s of referenced) report += `| ${s.name} | ${s.fieldCount} | ${s.dimensions} | ${s.measures} | ${s.timeDimensions} | ${s.refCount} |\n`;
+			report += `| ID | Table | Fields | Dims | Measures | Time | Refs |\n`;
+			report += `|------|-------|--------|------|----------|------|------|\n`;
+			for (const s of referenced) report += `| ${s.id} | ${s.name} | ${s.fieldCount} | ${s.dimensions} | ${s.measures} | ${s.timeDimensions} | ${s.refCount} |\n`;
 			if (unreferenced > 0) skippedTables += unreferenced;
 			report += `\n`;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"