@bonnard/cli 0.1.10 → 0.1.12

package/dist/bin/bon.mjs

@@ -1488,10 +1488,45 @@ async function addManual(options) {
 	console.log(pc.dim(`Test connection: bon datasource test ${name}`));
 }
 /**
+* Add the Contoso demo datasource (read-only retail dataset)
+*/
+async function addDemo(options) {
+	const name = "contoso_demo";
+	if (datasourceExists(name) && !options.force) {
+		console.log(pc.yellow(`Datasource "${name}" already exists. Use --force to overwrite.`));
+		return;
+	}
+	if (isDatasourcesTrackedByGit()) console.log(pc.yellow("Warning: .bon/datasources.yaml is tracked by git. Add it to .gitignore!"));
+	addLocalDatasource({
+		name,
+		type: "postgres",
+		source: "demo",
+		config: {
+			host: "aws-1-eu-west-1.pooler.supabase.com",
+			port: "5432",
+			database: "postgres",
+			schema: "contoso"
+		},
+		credentials: {
+			username: "demo_reader.yvbfzqogtdsqqkpyztlu",
+			password: "contoso-demo-2025!"
+		}
+	});
+	console.log();
+	console.log(pc.green(`✓ Demo datasource "${name}" saved to .bon/datasources.yaml`));
+	console.log();
+	console.log(pc.dim("Contoso is a read-only retail dataset with tables like:"));
+	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
 */
 async function datasourceAddCommand(options = {}) {
-	if (options.fromDbt !== void 0) await importFromDbt(options);
+	if (options.demo) await addDemo(options);
+	else if (options.fromDbt !== void 0) await importFromDbt(options);
 	else await addManual(options);
 }
 
@@ -2806,7 +2841,7 @@ program.command("login").description("Authenticate with Bonnard via your browser
 program.command("logout").description("Remove stored credentials").action(logoutCommand);
 program.command("whoami").description("Show current login status").option("--verify", "Verify session is still valid with the server").action(whoamiCommand);
 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("--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("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("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);

package/dist/templates/claude/skills/bonnard-get-started/SKILL.md

@@ -12,16 +12,22 @@ confirming progress before moving on.
 
 ## Phase 1: Connect a Data Source
 
-Check if the user has dbt:
+Ask the user if they have a warehouse to connect, or want to try a demo dataset first:
 
 ```bash
-# Import from dbt (if they use it)
+# Option A: Import from dbt (if they use it)
 bon datasource add --from-dbt
 
-# Or add manually (interactive)
+# Option B: Add manually (interactive)
 bon datasource add
+
+# Option C: Use demo data (no warehouse needed)
+bon datasource add --demo
 ```
 
+The demo option adds a read-only Contoso retail dataset with tables like
+`fact_sales`, `dim_product`, `dim_store`, and `dim_customer`.
+
 Then verify the connection works:
 
 ```bash
@@ -35,65 +41,81 @@ If the test fails, common issues:
 
 ## Phase 2: Explore the Data
 
-Use `bon preview` to understand what tables and columns are available:
+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.
 
 ```bash
-# List tables (Postgres)
+# 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'"
 
-# List tables (Snowflake)
+# Snowflake:
 bon preview <datasource> "SHOW TABLES"
 
-# Sample a table
-bon preview <datasource> "SELECT * FROM orders" --limit 10
+# 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
 ```
 
-This helps you understand the schema before writing cubes.
+Note the table names, column names, and data types — you'll use these in Phase 3.
 
 ## Phase 3: Create Your First Cube
 
-Create a file in `bonnard/cubes/` for the most important table. A cube
-typically maps directly to a database table — define measures for the metrics
-you want to track and dimensions for the attributes you want to filter and
-group by.
+Based on what you found in Phase 2, create a file in `bonnard/cubes/` for
+the most important table. A cube maps directly to a database table — define
+measures for the metrics you want to track and dimensions for the attributes
+you want to filter and group by. **Use the actual table and column names from
+Phase 2, not placeholder names.**
 
-Example — `bonnard/cubes/orders.yaml`:
+Example using demo data — `bonnard/cubes/sales.yaml`:
 
 ```yaml
 cubes:
-  - name: orders
-    sql_table: public.orders
+  - name: sales
+    sql_table: contoso.fact_sales
+    data_source: contoso_demo
 
     measures:
       - name: count
         type: count
-        description: Total number of orders
+        description: Total number of sales transactions
 
       - name: total_revenue
         type: sum
-        sql: amount
-        description: Sum of order amounts
+        sql: sales_amount
+        description: Sum of sales revenue
+
+      - name: total_cost
+        type: sum
+        sql: total_cost
+        description: Sum of product costs
 
     dimensions:
-      - name: id
+      - name: sales_key
         type: number
-        sql: id
+        sql: sales_key
         primary_key: true
 
-      - name: status
-        type: string
-        sql: status
-        description: Order status (pending, completed, cancelled)
-
-      - name: created_at
+      - name: date
         type: time
-        sql: created_at
-        description: When the order was placed
+        sql: date_key
+        description: Sale date
+
+      - name: sales_quantity
+        type: number
+        sql: sales_quantity
+        description: Number of units sold
 ```
 
 Key rules:
 - Every cube needs a `primary_key` dimension
 - Every measure and dimension should have a `description`
+- Set `data_source` to match the datasource name from Phase 1
+- Use `sql_table` with the full `schema.table` path
 - Use `sql_table` for simple table references, `sql` for complex queries
 
 Use `bon docs cubes` for the full reference, `bon docs cubes.measures.types`
@@ -102,21 +124,22 @@ for all 12 measure types, `bon docs cubes.dimensions.types` for dimension types.
 ## Phase 4: Create a View
 
 Views expose a curated subset of measures and dimensions for consumers.
-Create a file in `bonnard/views/`:
+Create a file in `bonnard/views/` that references the cube from Phase 3.
 
-Example — `bonnard/views/orders_overview.yaml`:
+Example using demo data — `bonnard/views/sales_overview.yaml`:
 
 ```yaml
 views:
-  - name: orders_overview
-    description: High-level order metrics and attributes
+  - name: sales_overview
+    description: High-level sales metrics and attributes
     cubes:
-      - join_path: orders
+      - join_path: sales
         includes:
           - count
           - total_revenue
-          - status
-          - created_at
+          - total_cost
+          - date
+          - sales_quantity
 ```
 
 Use `bon docs views` for the full reference.
@@ -154,17 +177,17 @@ credentials (encrypted) to Bonnard.
 
 ## Phase 7: Test with a Query
 
-Verify the deployment works:
+Verify the deployment works using the cube name from Phase 3:
 
 ```bash
 # Simple count
-bon query '{"measures": ["orders.count"]}'
+bon query '{"measures": ["sales.count"]}'
 
-# Group by a dimension
-bon query '{"measures": ["orders.count"], "dimensions": ["orders.status"]}'
+# With a dimension
+bon query '{"measures": ["sales.total_revenue"], "dimensions": ["sales.date"]}'
 
 # SQL format
-bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+bon query --sql "SELECT MEASURE(total_revenue) FROM sales"
 ```
 
 ## Phase 8: Connect AI Agents (Optional)

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

@@ -11,16 +11,22 @@ confirming progress before moving on.
 
 ## Phase 1: Connect a Data Source
 
-Check if the user has dbt:
+Ask the user if they have a warehouse to connect, or want to try a demo dataset first:
 
 ```bash
-# Import from dbt (if they use it)
+# Option A: Import from dbt (if they use it)
 bon datasource add --from-dbt
 
-# Or add manually (interactive)
+# Option B: Add manually (interactive)
 bon datasource add
+
+# Option C: Use demo data (no warehouse needed)
+bon datasource add --demo
 ```
 
+The demo option adds a read-only Contoso retail dataset with tables like
+`fact_sales`, `dim_product`, `dim_store`, and `dim_customer`.
+
 Then verify the connection works:
 
 ```bash
@@ -34,65 +40,81 @@ If the test fails, common issues:
 
 ## Phase 2: Explore the Data
 
-Use `bon preview` to understand what tables and columns are available:
+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.
 
 ```bash
-# List tables (Postgres)
+# 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'"
 
-# List tables (Snowflake)
+# Snowflake:
 bon preview <datasource> "SHOW TABLES"
 
-# Sample a table
-bon preview <datasource> "SELECT * FROM orders" --limit 10
+# 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
 ```
 
-This helps you understand the schema before writing cubes.
+Note the table names, column names, and data types — you'll use these in Phase 3.
 
 ## Phase 3: Create Your First Cube
 
-Create a file in `bonnard/cubes/` for the most important table. A cube
-typically maps directly to a database table — define measures for the metrics
-you want to track and dimensions for the attributes you want to filter and
-group by.
+Based on what you found in Phase 2, create a file in `bonnard/cubes/` for
+the most important table. A cube maps directly to a database table — define
+measures for the metrics you want to track and dimensions for the attributes
+you want to filter and group by. **Use the actual table and column names from
+Phase 2, not placeholder names.**
 
-Example — `bonnard/cubes/orders.yaml`:
+Example using demo data — `bonnard/cubes/sales.yaml`:
 
 ```yaml
 cubes:
-  - name: orders
-    sql_table: public.orders
+  - name: sales
+    sql_table: contoso.fact_sales
+    data_source: contoso_demo
 
     measures:
       - name: count
         type: count
-        description: Total number of orders
+        description: Total number of sales transactions
 
       - name: total_revenue
         type: sum
-        sql: amount
-        description: Sum of order amounts
+        sql: sales_amount
+        description: Sum of sales revenue
+
+      - name: total_cost
+        type: sum
+        sql: total_cost
+        description: Sum of product costs
 
     dimensions:
-      - name: id
+      - name: sales_key
         type: number
-        sql: id
+        sql: sales_key
         primary_key: true
 
-      - name: status
-        type: string
-        sql: status
-        description: Order status (pending, completed, cancelled)
-
-      - name: created_at
+      - name: date
         type: time
-        sql: created_at
-        description: When the order was placed
+        sql: date_key
+        description: Sale date
+
+      - name: sales_quantity
+        type: number
+        sql: sales_quantity
+        description: Number of units sold
 ```
 
 Key rules:
 - Every cube needs a `primary_key` dimension
 - Every measure and dimension should have a `description`
+- Set `data_source` to match the datasource name from Phase 1
+- Use `sql_table` with the full `schema.table` path
 - Use `sql_table` for simple table references, `sql` for complex queries
 
 Use `bon docs cubes` for the full reference, `bon docs cubes.measures.types`
@@ -101,21 +123,22 @@ for all 12 measure types, `bon docs cubes.dimensions.types` for dimension types.
 ## Phase 4: Create a View
 
 Views expose a curated subset of measures and dimensions for consumers.
-Create a file in `bonnard/views/`:
+Create a file in `bonnard/views/` that references the cube from Phase 3.
 
-Example — `bonnard/views/orders_overview.yaml`:
+Example using demo data — `bonnard/views/sales_overview.yaml`:
 
 ```yaml
 views:
-  - name: orders_overview
-    description: High-level order metrics and attributes
+  - name: sales_overview
+    description: High-level sales metrics and attributes
     cubes:
-      - join_path: orders
+      - join_path: sales
         includes:
           - count
           - total_revenue
-          - status
-          - created_at
+          - total_cost
+          - date
+          - sales_quantity
 ```
 
 Use `bon docs views` for the full reference.
@@ -153,17 +176,17 @@ credentials (encrypted) to Bonnard.
 
 ## Phase 7: Test with a Query
 
-Verify the deployment works:
+Verify the deployment works using the cube name from Phase 3:
 
 ```bash
 # Simple count
-bon query '{"measures": ["orders.count"]}'
+bon query '{"measures": ["sales.count"]}'
 
-# Group by a dimension
-bon query '{"measures": ["orders.count"], "dimensions": ["orders.status"]}'
+# With a dimension
+bon query '{"measures": ["sales.total_revenue"], "dimensions": ["sales.date"]}'
 
 # SQL format
-bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+bon query --sql "SELECT MEASURE(total_revenue) FROM sales"
 ```
 
 ## Phase 8: Connect AI Agents (Optional)

package/dist/templates/shared/bonnard.md

@@ -39,12 +39,29 @@ my-project/
     └── datasources.yaml  # Warehouse connections
 ```
 
+## Demo Data
+
+No warehouse? Use the built-in demo dataset to try Bonnard:
+
+```bash
+bon datasource add --demo
+```
+
+This adds a read-only **Contoso** retail database (Postgres) with tables:
+- `fact_sales` — transactions with sales_amount, unit_price, sales_quantity, date_key
+- `dim_product` — product_name, brand_name, manufacturer, unit_cost, unit_price
+- `dim_store` — store_name, store_type, employee_count, selling_area_size
+- `dim_customer` — first_name, last_name, gender, yearly_income, education, occupation
+
+All tables are in the `contoso` schema. The datasource is named `contoso_demo`.
+
 ## Quick Reference
 
 | Command | Purpose |
 |---------|---------|
 | `bon init` | Initialize new project |
 | `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 validate` | Validate YAML syntax |

package/dist/templates/shared/datasources.yaml

@@ -0,0 +1,16 @@
+# Bonnard datasources configuration
+# This file contains credentials - add to .gitignore
+# Env vars like {{ env_var('PASSWORD') }} are resolved at deploy time
+
+datasources:
+  - name: contoso_demo
+    type: postgres
+    source: demo
+    config:
+      host: aws-1-eu-west-1.pooler.supabase.com
+      port: "5432"
+      database: postgres
+      schema: contoso
+    credentials:
+      username: demo_reader.yvbfzqogtdsqqkpyztlu
+      password: contoso-demo-2025!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"
@@ -9,7 +9,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin && cp -r src/templates dist/ && mkdir -p dist/docs/topics dist/docs/schemas && cp ../content/index.md dist/docs/_index.md && cp ../content/modeling/*.md dist/docs/topics/ && cp ../content/dashboards/*.md dist/docs/topics/",
+    "build": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin && cp -r src/templates dist/ && mkdir -p dist/docs/topics dist/docs/schemas && cp ../content/index.md dist/docs/_index.md && cp ../content/modeling/*.md dist/docs/topics/",
     "dev": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin --watch",
     "test": "vitest run"
   },