@bonnard/cli 0.1.3 → 0.1.5

package/dist/docs/topics/workflow.validate.md

@@ -0,0 +1,152 @@
+# workflow.validate
+
+> Check models for errors before deploying.
+
+## Overview
+
+The `bon validate` command checks your YAML models for syntax errors, schema violations, and optionally tests data source connections. Run this before deploying to catch issues early.
+
+## Usage
+
+```bash
+# Basic validation
+bon validate
+
+# Also test data source connections
+bon validate --test-connection
+```
+
+## What Gets Validated
+
+### YAML Syntax
+
+- Valid YAML format
+- Proper indentation
+- Correct quoting
+
+### Schema Compliance
+
+- Required fields present (name, type, sql)
+- Valid field values (known measure types, relationship types)
+- Consistent naming conventions
+
+### Reference Integrity
+
+- Referenced cubes exist
+- Referenced members exist
+- Join relationships are valid
+
+### Connection Testing (--test-connection)
+
+- Data source credentials work
+- Database is accessible
+- Tables/schemas exist
+
+## Example Output
+
+### Success
+
+```
+✓ Validating YAML syntax...
+✓ Checking models/orders.yaml
+✓ Checking models/users.yaml
+✓ Checking views/orders_overview.yaml
+
+All models valid.
+```
+
+### Errors
+
+```
+✗ Validating YAML syntax...
+
+models/orders.yaml:15:5
+  error: Unknown measure type "counts"
+
+  Did you mean "count"?
+
+  14:   measures:
+  15:     - name: order_count
+  16:       type: counts  <-- here
+  17:       sql: id
+
+1 error found.
+```
+
+### Connection Warnings
+
+```
+✓ Validating YAML syntax...
+✓ All models valid.
+
+⚠ Testing connections...
+  ⚠ datasource "analytics": Connection timed out
+    (This won't block deploy, but queries may fail)
+```
+
+## Common Errors
+
+### Missing Required Field
+
+```yaml
+# Error: "sql" is required
+measures:
+  - name: count
+    type: count
+    # Missing: sql: id
+```
+
+### Invalid Type
+
+```yaml
+# Error: Unknown dimension type "text"
+dimensions:
+  - name: status
+    type: text    # Should be: string
+    sql: status
+```
+
+### Reference Not Found
+
+```yaml
+# Error: Cube "user" not found (did you mean "users"?)
+joins:
+  - name: user
+    relationship: many_to_one
+    sql: "{CUBE}.user_id = {user.id}"
+```
+
+### YAML Syntax
+
+```yaml
+# Error: Bad indentation
+measures:
+- name: count  # Should be indented
+  type: count
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--test-connection` | Also test datasource connections |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All validations passed |
+| 1 | Validation errors found |
+
+## Best Practices
+
+1. **Run before every deploy** — `bon validate && bon deploy`
+2. **Add to CI/CD** — validate on pull requests
+3. **Fix errors first** — don't deploy with validation errors
+4. **Test connections periodically** — catch credential issues early
+
+## See Also
+
+- workflow
+- workflow.deploy
+- syntax

package/dist/templates/claude/rules/bonnard.md

@@ -0,0 +1,15 @@
+# Bonnard Analytics
+
+This project uses Bonnard for semantic layer analytics.
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `bon validate` | Validate models and views |
+| `bon deploy` | Deploy to Cube |
+| `bon query <ds> <sql>` | Run SQL query |
+| `bon datasource list` | List data sources |
+
+For detailed CLI help: `/bonnard-cli`
+For query patterns: `/bonnard-queries`

package/dist/templates/claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bon *)"
+    ]
+  }
+}

package/dist/templates/claude/skills/bonnard-cli/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: bonnard-cli
+description: Bonnard CLI reference. Use when user needs help with bon commands, data sources, or deployments.
+allowed-tools: Bash(bon *)
+---
+
+# Bonnard CLI
+
+## Commands
+
+### Project Setup
+```bash
+bon init              # Initialize new project
+bon login             # Authenticate with Bonnard
+bon logout            # Clear credentials
+```
+
+### Data Sources
+```bash
+bon datasource add              # Add new data source (interactive)
+bon datasource list             # List all data sources
+bon datasource test <name>      # Test connection
+bon datasource remove <name>    # Remove data source
+```
+
+### Development
+```bash
+bon validate          # Validate models and views
+bon deploy            # Deploy to Bonnard Cube
+```
+
+### Data Exploration (Local)
+```bash
+bon preview <datasource> "<sql>"              # Preview data with raw SQL
+bon preview <datasource> "<sql>" --format json  # JSON output
+bon preview <datasource> "<sql>" --limit 100    # Limit rows
+```
+
+### Semantic Layer Queries (Deployed)
+```bash
+# JSON format (default)
+bon cube query '{"measures": ["orders.count"]}'
+bon cube query '{"measures": ["orders.total_revenue"], "dimensions": ["orders.status"]}'
+
+# SQL format
+bon cube query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+bon cube query --sql "SELECT city, SUM(amount) FROM orders GROUP BY 1" --limit 10
+```
+
+### Documentation
+```bash
+bon docs                          # Show all topics
+bon docs <topic>                  # View topic (e.g., cubes.measures)
+bon docs <topic> --recursive      # Topic + all children
+bon docs --search "<query>"       # Search all docs
+bon docs <topic> --format json    # Structured output
+```
+
+**Key topics:** `cubes`, `cubes.measures`, `cubes.dimensions`, `cubes.joins`, `views`, `pre-aggregations`, `syntax`

package/dist/templates/claude/skills/bonnard-queries/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: bonnard-queries
+description: How to write Cube queries and work with models. Use when user asks about metrics, dimensions, or data modeling.
+---
+
+# Bonnard Query Patterns
+
+## Model Structure (YAML)
+
+```yaml
+cubes:
+  - name: orders
+    sql: SELECT * FROM public.orders
+
+    measures:
+      - name: count
+        type: count
+        description: Total number of orders
+
+      - name: total_amount
+        type: sum
+        sql: amount
+        description: Sum of order amounts in dollars
+
+    dimensions:
+      - name: status
+        type: string
+        sql: status
+        description: Order status (pending, completed, cancelled)
+
+      - name: created_at
+        type: time
+        sql: created_at
+        description: When the order was placed
+```
+
+## View Structure (YAML)
+
+```yaml
+views:
+  - name: orders_overview
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_amount
+          - status
+```
+
+## Workflow
+
+1. Define models in `models/*.yaml`
+2. Define views in `views/*.yaml`
+3. Run `bon validate` to check syntax
+4. Run `bon deploy` to publish
+
+## Learn More
+
+Use `bon docs` for comprehensive documentation:
+
+```bash
+bon docs cubes.measures.types    # All 12 measure types
+bon docs cubes.dimensions.types  # All 6 dimension types
+bon docs cubes.joins             # Relationship types
+bon docs cubes.segments          # Predefined filters
+bon docs views.cubes             # View composition
+bon docs --search "rolling"      # Search for concepts
+```

package/dist/templates/cursor/rules/bonnard-cli.mdc

@@ -0,0 +1,47 @@
+---
+description: "Bonnard CLI reference. Use when user needs help with bon commands, data sources, or deployments."
+alwaysApply: false
+---
+
+# Bonnard CLI
+
+## Commands
+
+### Project Setup
+```bash
+bon init              # Initialize new project
+bon login             # Authenticate with Bonnard
+bon logout            # Clear credentials
+```
+
+### Data Sources
+```bash
+bon datasource add              # Add new data source (interactive)
+bon datasource list             # List all data sources
+bon datasource test <name>      # Test connection
+bon datasource remove <name>    # Remove data source
+```
+
+### Development
+```bash
+bon validate          # Validate models and views
+bon deploy            # Deploy to Bonnard Cube
+```
+
+### Data Exploration (Local)
+```bash
+bon preview <datasource> "<sql>"              # Preview data with raw SQL
+bon preview <datasource> "<sql>" --format json  # JSON output
+bon preview <datasource> "<sql>" --limit 100    # Limit rows
+```
+
+### Semantic Layer Queries (Deployed)
+```bash
+# JSON format (default)
+bon cube query '{"measures": ["orders.count"]}'
+bon cube query '{"measures": ["orders.total_revenue"], "dimensions": ["orders.status"]}'
+
+# SQL format
+bon cube query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+bon cube query --sql "SELECT city, SUM(amount) FROM orders GROUP BY 1" --limit 10
+```

package/dist/templates/cursor/rules/bonnard-queries.mdc

@@ -0,0 +1,49 @@
+---
+description: "How to write Cube queries and work with models. Use when user asks about metrics, dimensions, or data modeling."
+alwaysApply: false
+---
+
+# Bonnard Query Patterns
+
+## Model Structure (YAML)
+
+```yaml
+cubes:
+  - name: orders
+    sql: SELECT * FROM public.orders
+
+    measures:
+      - name: count
+        type: count
+      - name: total_amount
+        type: sum
+        sql: amount
+
+    dimensions:
+      - name: status
+        type: string
+        sql: status
+      - name: created_at
+        type: time
+        sql: created_at
+```
+
+## View Structure (YAML)
+
+```yaml
+views:
+  - name: orders_overview
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_amount
+          - status
+```
+
+## Workflow
+
+1. Define models in `models/*.yaml`
+2. Define views in `views/*.yaml`
+3. Run `bon validate` to check syntax
+4. Run `bon deploy` to publish

package/dist/templates/cursor/rules/bonnard.mdc

@@ -0,0 +1,20 @@
+---
+description: "Bonnard analytics project context"
+alwaysApply: true
+---
+
+# Bonnard Analytics
+
+This project uses Bonnard for semantic layer analytics.
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `bon validate` | Validate models and views |
+| `bon deploy` | Deploy to Cube |
+| `bon query <ds> <sql>` | Run SQL query |
+| `bon datasource list` | List data sources |
+
+For detailed CLI help, ask about "bonnard cli commands".
+For query patterns, ask about "bonnard queries".

package/dist/templates/shared/bonnard.md

@@ -0,0 +1,81 @@
+# Bonnard Semantic Layer
+
+Bonnard is a semantic layer platform that sits between your data warehouse and end users (analysts, dashboards, AI agents). It provides consistent metrics and dimensions via a type-safe API.
+
+## How It Works
+
+```
+Data Warehouse (Snowflake, Postgres, BigQuery, Databricks)
+        ↓
+   Cube Models (measures, dimensions, joins)
+        ↓
+      Views (curated subsets for specific use cases)
+        ↓
+   Bonnard API (deployed Cube instance)
+        ↓
+   Consumers (MCP tools, dashboards, analysts)
+```
+
+## Key Concepts
+
+**Cubes** — Define metrics (measures) and attributes (dimensions) on top of database tables. Each cube typically maps to one table or a base SQL query.
+
+**Views** — Compose cubes into focused interfaces for specific use cases. Views expose only the relevant measures/dimensions, hiding complexity.
+
+**Datasources** — Warehouse connections stored locally in `.bon/datasources.yaml`. Referenced by cubes via the `data_source` property.
+
+## Project Structure
+
+```
+my-project/
+├── bon.yaml              # Project config
+├── models/               # Cube definitions
+│   ├── orders.yaml
+│   └── customers.yaml
+├── views/                # View definitions
+│   └── sales_overview.yaml
+└── .bon/                 # Local state (gitignored)
+    └── datasources.yaml  # Warehouse connections
+```
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `bon init` | Initialize new project |
+| `bon datasource add` | Add warehouse connection |
+| `bon datasource add --from-dbt` | Import from dbt profiles |
+| `bon datasource test <name>` | Test connection |
+| `bon validate` | Validate YAML syntax |
+| `bon validate --test-connection` | Validate + test connections |
+| `bon deploy` | Deploy to Bonnard (requires login) |
+| `bon docs` | Browse Cube documentation |
+
+## Learning Cube Syntax
+
+Use `bon docs` to explore Cube data modeling concepts:
+
+```bash
+bon docs                        # Show all topics
+bon docs cubes                  # Learn about cubes
+bon docs cubes.measures         # Learn about measures
+bon docs cubes.measures.types   # See all 12 measure types
+bon docs cubes.joins            # Learn about relationships
+bon docs views                  # Learn about views
+bon docs --search "primary key" # Search for a concept
+bon docs cubes.measures -r      # Topic + all children
+bon docs cubes --format json    # Structured output
+```
+
+Topics follow dot notation (e.g., `cubes.dimensions.time`). Use `--recursive` to see a topic and all its children.
+
+## Workflow
+
+1. **Setup datasource** — `bon datasource add --from-dbt` or manual
+2. **Create cubes** — Define measures/dimensions in `models/*.yaml`
+3. **Create views** — Compose cubes in `views/*.yaml`
+4. **Validate** — `bon validate --test-connection`
+5. **Deploy** — `bon login` then `bon deploy`
+
+For CLI details: `/bonnard-cli`
+For YAML patterns: `/bonnard-queries`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"
@@ -8,6 +8,11 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin && cp -r src/templates dist/ && cp -r src/docs dist/",
+    "dev": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin --watch",
+    "test": "vitest run"
+  },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
     "@toon-format/toon": "^2.1.0",
@@ -15,7 +20,12 @@
     "open": "^11.0.0",
     "@cubejs-backend/schema-compiler": "^1.6.7",
     "@cubejs-backend/shared": "^1.6.7",
-    "picocolors": "^1.0.0"
+    "picocolors": "^1.0.0",
+    "yaml": "^2.8.0"
+  },
+  "optionalDependencies": {
+    "snowflake-sdk": "^2.3.3",
+    "pg": "^8.18.0"
   },
   "devDependencies": {
     "tsdown": "^0.20.1",
@@ -23,10 +33,5 @@
   },
   "engines": {
     "node": ">=20.0.0"
-  },
-  "scripts": {
-    "build": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin",
-    "dev": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin --watch",
-    "test": "vitest run"
   }
-}
+}