@bonnard/cli 0.2.0 → 0.2.2

package/dist/templates/claude/skills/bonnard-metabase-migrate/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: bonnard-metabase-migrate
+description: Guide migration from an existing Metabase instance to a Bonnard semantic layer. Use when user says "migrate from metabase", "import metabase", "metabase to semantic layer", or has Metabase data they want to model.
+allowed-tools: Bash(bon *)
+---
+
+# Migrate from Metabase to Bonnard
+
+This skill guides you through analyzing an existing Metabase instance and
+building a semantic layer that replicates its most important metrics.
+Walk through each phase in order, confirming progress before moving on.
+
+## Phase 1: Connect to Metabase
+
+Set up a connection to the Metabase instance:
+
+```bash
+bon metabase connect
+```
+
+This prompts for the Metabase URL and API key. The API key should be created
+in Metabase under Admin > Settings > Authentication > API Keys.
+An admin-level key gives the richest analysis (permissions, schema access).
+
+## Phase 2: Analyze the Instance
+
+Generate an intelligence report that maps the entire Metabase instance:
+
+```bash
+bon metabase analyze
+```
+
+This writes a report to `.bon/metabase-analysis.md`. Read it carefully — it
+drives every decision in the remaining phases.
+
+### How to interpret each section
+
+| Report Section | What It Tells You | Action |
+|----------------|-------------------|--------|
+| **Most Referenced Tables** | Tables used most in SQL queries | Create cubes for these first — they are the core of the data model |
+| **Top Cards by Activity** | Most-viewed questions/models | `analytical` cards (GROUP BY + aggregation) map to measures; `lookup` cards indicate key filter dimensions; `display` cards can be skipped |
+| **Common Filter Variables** | Template vars (`{{var}}`) used across 3+ cards | These must be dimensions on relevant cubes |
+| **Foreign Key Relationships** | FK links between tables | Define `joins` between cubes using these relationships |
+| **Collection Structure** | How users organize content by business area | Map each top-level collection to a view (one view per business domain) |
+| **Dashboard Parameters** | Shared filters across dashboards | The most important shared dimensions — ensure they exist on relevant cubes |
+| **Table Inventory** | Field counts and classification per table | Field classification (dims/measures/time) guides each cube definition; tables with 0 refs can be deprioritized |
+| **Schema Access** | Which schemas non-admin groups can query | Focus on user-facing schemas — skip admin-only/staging schemas |
+
+## Phase 3: Connect the Data Warehouse
+
+Add a datasource pointing to the same database that Metabase queries:
+
+```bash
+# Interactive setup
+bon datasource add
+
+# Or import from dbt if available
+bon datasource add --from-dbt
+```
+
+Then verify the connection:
+
+```bash
+bon datasource test <name>
+```
+
+The database connection details can often be found in Metabase under
+Admin > Databases, or in the analysis report header.
+
+## Phase 4: Explore Key Tables
+
+Before writing cubes, drill into the most important tables and cards
+identified in Phase 2. Use the explore commands to understand field types
+and existing SQL patterns:
+
+```bash
+# View table fields with type classification
+bon metabase explore table <id>
+
+# View card SQL and columns
+bon metabase explore card <id>
+
+# View schemas and tables in a database
+bon metabase explore database <id>
+
+# View cards in a collection
+bon metabase explore collection <id>
+```
+
+### How explore output maps to cube definitions
+
+| Explore Field | Cube Mapping |
+|---------------|-------------|
+| Field class `pk` | Set `primary_key: true` on dimension |
+| Field class `fk` | Join candidate — note the target table |
+| Field class `time` | Dimension with `type: time` |
+| Field class `measure` | Measure candidate — check card SQL for aggregation type |
+| Field class `dim` | Dimension with `type: string` or `type: number` |
+
+### How card SQL maps to measures
+
+Look at the SQL in `analytical` cards to determine measure types:
+
+| Card SQL Pattern | Cube Measure |
+|-----------------|-------------|
+| `SUM(amount)` | `type: sum`, `sql: amount` |
+| `COUNT(*)` | `type: count` |
+| `COUNT(DISTINCT user_id)` | `type: count_distinct`, `sql: user_id` |
+| `AVG(price)` | `type: avg`, `sql: price` |
+| `MIN(date)` / `MAX(date)` | `type: min` / `type: max`, `sql: date` |
+
+Use `bon docs cubes.measures.types` for all 12 measure types.
+
+## Phase 5: Build Cubes
+
+Create cubes for the most-referenced tables (from Phase 2). Start with the
+highest-referenced table and work down. Create one file per cube in
+`bonnard/cubes/`.
+
+For each cube:
+1. Set `sql_table` to the full `schema.table` path
+2. Set `data_source` to the datasource name from Phase 3
+3. Add a `primary_key` dimension
+4. Add time dimensions for date/datetime columns
+5. Add measures based on card SQL patterns (Phase 4)
+6. Add dimensions for columns used as filters (template vars from Phase 2)
+7. Add `description` to every measure and dimension
+
+Example — `bonnard/cubes/orders.yaml`:
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+    data_source: my_warehouse
+    description: Order transactions
+
+    measures:
+      - name: count
+        type: count
+        description: Total number of orders
+
+      - name: total_revenue
+        type: sum
+        sql: amount
+        description: Sum of order amounts
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: created_at
+        type: time
+        sql: created_at
+        description: Order creation timestamp
+
+      - name: status
+        type: string
+        sql: status
+        description: Order status (pending, completed, cancelled)
+```
+
+### Adding joins
+
+Use FK relationships from the analysis report to define joins between cubes:
+
+```yaml
+    joins:
+      - name: customers
+        sql: "{CUBE}.customer_id = {customers.id}"
+        relationship: many_to_one
+```
+
+Use `bon docs cubes.joins` for the full reference.
+
+## Phase 6: Build Views
+
+Map Metabase collections to views. Each top-level collection (business domain)
+from the analysis report becomes a view that composes the relevant cubes.
+
+Create one file per view in `bonnard/views/`.
+
+Example — `bonnard/views/sales_analytics.yaml`:
+
+```yaml
+views:
+  - name: sales_analytics
+    description: Sales metrics and dimensions for the sales team
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+          - created_at
+          - status
+
+      - join_path: orders.customers
+        prefix: true
+        includes:
+          - name
+          - region
+```
+
+Use `bon docs views` for the full reference.
+
+## Phase 7: Validate and Deploy
+
+Validate the semantic layer:
+
+```bash
+bon validate
+```
+
+Fix any errors. Common issues:
+- Missing `primary_key` dimension
+- Unknown measure/dimension types
+- Undefined cube referenced in a view join path
+- Missing `data_source`
+
+Then deploy:
+
+```bash
+bon login
+bon deploy -m "Migrate semantic layer from Metabase"
+```
+
+## Phase 8: Verify
+
+Compare results from the semantic layer against Metabase card outputs.
+Pick 3-5 important `analytical` cards from the analysis report and run
+equivalent queries:
+
+```bash
+# Run a semantic layer query
+bon query '{"measures": ["orders.total_revenue"], "dimensions": ["orders.status"]}'
+
+# SQL format
+bon query --sql "SELECT status, MEASURE(total_revenue) FROM orders GROUP BY 1"
+```
+
+Compare the numbers with the corresponding Metabase card. If they don't match:
+- Check the SQL in the card (`bon metabase explore card <id>`) for filters or transformations
+- Ensure the measure type matches the aggregation (SUM vs COUNT vs AVG)
+- Check for WHERE clauses that should be segments or pre-filters
+
+## Next Steps
+
+After the core migration is working:
+
+- Add remaining tables as cubes (work down the reference count list)
+- Add calculated measures for complex card SQL (`bon docs cubes.measures.calculated`)
+- Add segments for common WHERE clauses (`bon docs cubes.segments`)
+- Set up MCP for AI agent access (`bon mcp`)
+- Review and iterate with `bon deployments` and `bon diff <id>`

package/dist/templates/cursor/rules/bonnard-get-started.mdc

@@ -40,25 +40,12 @@ If the test fails, common issues:
 
 ## Phase 2: Explore the Data
 
-Use `bon preview` to understand what tables and columns are available.
-**Always run this before creating cubes** — use the results to decide which
-tables to model and what columns to expose.
+Before creating cubes, understand what tables and columns are available in your warehouse.
 
-```bash
-# List tables — use the schema from the datasource config
-# For demo data (contoso schema):
-bon preview contoso_demo "SELECT table_name FROM information_schema.tables WHERE table_schema = 'contoso'"
-
-# For user's own data (typically public schema):
-bon preview <datasource> "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
-
-# Snowflake:
-bon preview <datasource> "SHOW TABLES"
-
-# Then sample the key tables to see columns and data:
-bon preview contoso_demo "SELECT * FROM contoso.fact_sales" --limit 10
-bon preview contoso_demo "SELECT * FROM contoso.dim_product" --limit 10
-```
+**Options for exploring your data:**
+- Use your database IDE or CLI (e.g., `psql`, Snowflake web UI, BigQuery console) to browse tables
+- Check your dbt docs or existing documentation for table schemas
+- For the demo dataset, the tables are: `contoso.fact_sales`, `contoso.dim_product`, `contoso.dim_store`, `contoso.dim_customer`
 
 Note the table names, column names, and data types — you'll use these in Phase 3.
 
@@ -160,12 +147,6 @@ Validate also warns about:
 - **Missing descriptions** — descriptions help AI agents and analysts discover metrics
 - **Missing `data_source`** — cubes without an explicit `data_source` use the default warehouse, which can cause issues when multiple warehouses are configured
 
-Optionally test the datasource connection too:
-
-```bash
-bon validate --test-connection
-```
-
 ## Phase 6: Deploy
 
 Log in (if not already) and deploy:

package/dist/templates/cursor/rules/bonnard-metabase-migrate.mdc

@@ -0,0 +1,255 @@
+---
+description: "Guide migration from an existing Metabase instance to a Bonnard semantic layer. Use when user says 'migrate from metabase', 'import metabase', 'metabase to semantic layer', or has Metabase data they want to model."
+alwaysApply: false
+---
+
+# Migrate from Metabase to Bonnard
+
+This skill guides you through analyzing an existing Metabase instance and
+building a semantic layer that replicates its most important metrics.
+Walk through each phase in order, confirming progress before moving on.
+
+## Phase 1: Connect to Metabase
+
+Set up a connection to the Metabase instance:
+
+```bash
+bon metabase connect
+```
+
+This prompts for the Metabase URL and API key. The API key should be created
+in Metabase under Admin > Settings > Authentication > API Keys.
+An admin-level key gives the richest analysis (permissions, schema access).
+
+## Phase 2: Analyze the Instance
+
+Generate an intelligence report that maps the entire Metabase instance:
+
+```bash
+bon metabase analyze
+```
+
+This writes a report to `.bon/metabase-analysis.md`. Read it carefully — it
+drives every decision in the remaining phases.
+
+### How to interpret each section
+
+| Report Section | What It Tells You | Action |
+|----------------|-------------------|--------|
+| **Most Referenced Tables** | Tables used most in SQL queries | Create cubes for these first — they are the core of the data model |
+| **Top Cards by Activity** | Most-viewed questions/models | `analytical` cards (GROUP BY + aggregation) map to measures; `lookup` cards indicate key filter dimensions; `display` cards can be skipped |
+| **Common Filter Variables** | Template vars (`{{var}}`) used across 3+ cards | These must be dimensions on relevant cubes |
+| **Foreign Key Relationships** | FK links between tables | Define `joins` between cubes using these relationships |
+| **Collection Structure** | How users organize content by business area | Map each top-level collection to a view (one view per business domain) |
+| **Dashboard Parameters** | Shared filters across dashboards | The most important shared dimensions — ensure they exist on relevant cubes |
+| **Table Inventory** | Field counts and classification per table | Field classification (dims/measures/time) guides each cube definition; tables with 0 refs can be deprioritized |
+| **Schema Access** | Which schemas non-admin groups can query | Focus on user-facing schemas — skip admin-only/staging schemas |
+
+## Phase 3: Connect the Data Warehouse
+
+Add a datasource pointing to the same database that Metabase queries:
+
+```bash
+# Interactive setup
+bon datasource add
+
+# Or import from dbt if available
+bon datasource add --from-dbt
+```
+
+Then verify the connection:
+
+```bash
+bon datasource test <name>
+```
+
+The database connection details can often be found in Metabase under
+Admin > Databases, or in the analysis report header.
+
+## Phase 4: Explore Key Tables
+
+Before writing cubes, drill into the most important tables and cards
+identified in Phase 2. Use the explore commands to understand field types
+and existing SQL patterns:
+
+```bash
+# View table fields with type classification
+bon metabase explore table <id>
+
+# View card SQL and columns
+bon metabase explore card <id>
+
+# View schemas and tables in a database
+bon metabase explore database <id>
+
+# View cards in a collection
+bon metabase explore collection <id>
+```
+
+### How explore output maps to cube definitions
+
+| Explore Field | Cube Mapping |
+|---------------|-------------|
+| Field class `pk` | Set `primary_key: true` on dimension |
+| Field class `fk` | Join candidate — note the target table |
+| Field class `time` | Dimension with `type: time` |
+| Field class `measure` | Measure candidate — check card SQL for aggregation type |
+| Field class `dim` | Dimension with `type: string` or `type: number` |
+
+### How card SQL maps to measures
+
+Look at the SQL in `analytical` cards to determine measure types:
+
+| Card SQL Pattern | Cube Measure |
+|-----------------|-------------|
+| `SUM(amount)` | `type: sum`, `sql: amount` |
+| `COUNT(*)` | `type: count` |
+| `COUNT(DISTINCT user_id)` | `type: count_distinct`, `sql: user_id` |
+| `AVG(price)` | `type: avg`, `sql: price` |
+| `MIN(date)` / `MAX(date)` | `type: min` / `type: max`, `sql: date` |
+
+Use `bon docs cubes.measures.types` for all 12 measure types.
+
+## Phase 5: Build Cubes
+
+Create cubes for the most-referenced tables (from Phase 2). Start with the
+highest-referenced table and work down. Create one file per cube in
+`bonnard/cubes/`.
+
+For each cube:
+1. Set `sql_table` to the full `schema.table` path
+2. Set `data_source` to the datasource name from Phase 3
+3. Add a `primary_key` dimension
+4. Add time dimensions for date/datetime columns
+5. Add measures based on card SQL patterns (Phase 4)
+6. Add dimensions for columns used as filters (template vars from Phase 2)
+7. Add `description` to every measure and dimension
+
+Example — `bonnard/cubes/orders.yaml`:
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+    data_source: my_warehouse
+    description: Order transactions
+
+    measures:
+      - name: count
+        type: count
+        description: Total number of orders
+
+      - name: total_revenue
+        type: sum
+        sql: amount
+        description: Sum of order amounts
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: created_at
+        type: time
+        sql: created_at
+        description: Order creation timestamp
+
+      - name: status
+        type: string
+        sql: status
+        description: Order status (pending, completed, cancelled)
+```
+
+### Adding joins
+
+Use FK relationships from the analysis report to define joins between cubes:
+
+```yaml
+    joins:
+      - name: customers
+        sql: "{CUBE}.customer_id = {customers.id}"
+        relationship: many_to_one
+```
+
+Use `bon docs cubes.joins` for the full reference.
+
+## Phase 6: Build Views
+
+Map Metabase collections to views. Each top-level collection (business domain)
+from the analysis report becomes a view that composes the relevant cubes.
+
+Create one file per view in `bonnard/views/`.
+
+Example — `bonnard/views/sales_analytics.yaml`:
+
+```yaml
+views:
+  - name: sales_analytics
+    description: Sales metrics and dimensions for the sales team
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+          - created_at
+          - status
+
+      - join_path: orders.customers
+        prefix: true
+        includes:
+          - name
+          - region
+```
+
+Use `bon docs views` for the full reference.
+
+## Phase 7: Validate and Deploy
+
+Validate the semantic layer:
+
+```bash
+bon validate
+```
+
+Fix any errors. Common issues:
+- Missing `primary_key` dimension
+- Unknown measure/dimension types
+- Undefined cube referenced in a view join path
+- Missing `data_source`
+
+Then deploy:
+
+```bash
+bon login
+bon deploy -m "Migrate semantic layer from Metabase"
+```
+
+## Phase 8: Verify
+
+Compare results from the semantic layer against Metabase card outputs.
+Pick 3-5 important `analytical` cards from the analysis report and run
+equivalent queries:
+
+```bash
+# Run a semantic layer query
+bon query '{"measures": ["orders.total_revenue"], "dimensions": ["orders.status"]}'
+
+# SQL format
+bon query --sql "SELECT status, MEASURE(total_revenue) FROM orders GROUP BY 1"
+```
+
+Compare the numbers with the corresponding Metabase card. If they don't match:
+- Check the SQL in the card (`bon metabase explore card <id>`) for filters or transformations
+- Ensure the measure type matches the aggregation (SUM vs COUNT vs AVG)
+- Check for WHERE clauses that should be segments or pre-filters
+
+## Next Steps
+
+After the core migration is working:
+
+- Add remaining tables as cubes (work down the reference count list)
+- Add calculated measures for complex card SQL (`bon docs cubes.measures.calculated`)
+- Add segments for common WHERE clauses (`bon docs cubes.segments`)
+- Set up MCP for AI agent access (`bon mcp`)
+- Review and iterate with `bon deployments` and `bon diff <id>`

package/dist/templates/shared/bonnard.md

@@ -63,18 +63,19 @@ All tables are in the `contoso` schema. The datasource is named `contoso_demo`.
 | `bon datasource add` | Add warehouse connection |
 | `bon datasource add --demo` | Add demo dataset (no warehouse needed) |
 | `bon datasource add --from-dbt` | Import from dbt profiles |
-| `bon datasource test <name>` | Test connection |
+| `bon datasource test <name>` | Test connection (requires login) |
 | `bon validate` | Validate YAML syntax, warn on missing descriptions and `data_source` |
-| `bon validate --test-connection` | Validate + test warehouse connections |
 | `bon deploy -m "message"` | Deploy to Bonnard (requires login, message required) |
 | `bon deploy --ci` | Non-interactive deploy (fails on missing datasources) |
 | `bon deployments` | List recent deployments (add `--all` for full history) |
 | `bon diff <deployment-id>` | Show changes in a deployment (`--breaking` for breaking only) |
 | `bon annotate <deployment-id>` | Add reasoning/context to deployment changes |
 | `bon query '{...}'` | Execute a semantic layer query (JSON or `--sql` format) |
-| `bon preview <ds> "SQL"` | Run raw SQL against a warehouse |
 | `bon mcp` | Show MCP setup instructions for AI agents |
 | `bon docs` | Browse documentation |
+| `bon metabase connect` | Connect to a Metabase instance (API key) |
+| `bon metabase analyze` | Generate analysis report for semantic layer planning |
+| `bon metabase explore` | Browse Metabase databases, collections, cards, dashboards |
 
 ## Learning YAML Syntax
 
@@ -99,11 +100,12 @@ Topics follow dot notation (e.g., `cubes.dimensions.time`). Use `--recursive` to
 1. **Setup datasource** — `bon datasource add --from-dbt` or manual
 2. **Create cubes** — Define measures/dimensions in `bonnard/cubes/*.yaml`
 3. **Create views** — Compose cubes in `bonnard/views/*.yaml`
-4. **Validate** — `bon validate --test-connection`
+4. **Validate** — `bon validate`
 5. **Deploy** — `bon login` then `bon deploy -m "description of changes"`
 6. **Review** — `bon deployments` to list, `bon diff <id>` to inspect changes
 
 For a guided walkthrough: `/bonnard-get-started`
+For projects migrating from Metabase: `/bonnard-metabase-migrate`
 
 ## Deployment & Change Tracking
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"
@@ -18,16 +18,12 @@
     "@toon-format/toon": "^2.1.0",
     "commander": "^12.0.0",
     "open": "^11.0.0",
-    "@cubejs-backend/schema-compiler": "^1.6.7",
-    "@cubejs-backend/shared": "^1.6.7",
     "picocolors": "^1.0.0",
-    "yaml": "^2.8.0"
-  },
-  "optionalDependencies": {
-    "snowflake-sdk": "^2.3.3",
-    "pg": "^8.18.0"
+    "yaml": "^2.8.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@types/node": "^20.0.0",
     "tsdown": "^0.20.1",
     "vitest": "^2.0.0"
   },