Add SQL query interface and Claude Code skill (#249)

## Summary

Supersedes #236 with a different approach: instead of shelling out to the `duckdb` CLI via bash scripts, this builds a SQL view layer inside msgvault itself.

- **DuckDB views** over Parquet files (`RegisterViews`), registered at engine startup — 8 base views + 5 convenience views (v_messages, v_senders, v_domains, v_labels, v_threads)
- **`msgvault query` CLI command** with `--format json|csv|table` output
- **`POST /api/v1/query` HTTP endpoint** on the existing serve daemon (503 when Parquet cache unavailable)
- **Claude Code skill** that teaches agents to use `msgvault query "SELECT ..."`

No bash wrapper scripts, no external `duckdb` CLI dependency, no Parquet path knowledge leaked to consumers.

## Changes

| Component | Files |
|---|---|
| View layer | `internal/query/views.go` (base + convenience views, `RegisterViews`) |
| QuerySQL | `internal/query/duckdb.go` (method + read-only validation + view wiring) |
| CLI | `cmd/msgvault/cmd/query.go` |
| HTTP | `internal/api/handlers.go`, `internal/api/server.go` |
| Skill | `skills/claude-code/SKILL.md`, `skills/claude-code/references/views.md` |
| Tests | `internal/query/views_test.go`, `cmd/msgvault/cmd/query_test.go`, `internal/api/handlers_test.go` |

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Wes McKinney <wesm@users.noreply.github.com>

Author: wesm

.roborev.toml

@@ -27,6 +27,12 @@ require an attacker with the same privileges as the user — they already
 own everything this tool touches. Auth on loopback-only endpoints with
 no configured API key is also by design.
 
+Anyone with access to the CLI or HTTP API is a privileged user. Do not
+flag SQL injection, statement validation, DDL bypass, or multi-statement
+risks on the query interface — the user is trusted and can already do
+anything via direct database access. The query surface is a convenience
+layer, not a security boundary.
+
 IMAP passwords are stored on disk with restricted file permissions
 (0600), equivalent to OAuth tokens and API keys in the same data
 directory. If the data directory is compromised, the user must rotate

cmd/msgvault/cmd/query.go

@@ -0,0 +1,271 @@
+package cmd
+
+import (
+	"database/sql"
+	"encoding/csv"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"runtime"
+	"strings"
+
+	_ "github.com/marcboeker/go-duckdb"
+	"github.com/spf13/cobra"
+	"github.com/wesm/msgvault/internal/query"
+)
+
+var queryFormat string
+
+var queryCmd = &cobra.Command{
+	Use:   "query [sql]",
+	Short: "Run a SQL query against the analytics cache",
+	Long: `Run arbitrary SQL against the Parquet analytics cache.
+
+The following views are available:
+  messages, participants, message_recipients, labels,
+  message_labels, attachments, conversations, sources
+
+Convenience views:
+  v_messages   - messages with resolved sender and labels
+  v_senders    - per-sender aggregates
+  v_domains    - per-domain aggregates
+  v_labels     - label name with message count and size
+  v_threads    - per-conversation aggregates
+
+Output formats:
+  json   - JSON object with columns, rows, row_count (default)
+  csv    - CSV with header row
+  table  - Aligned text table
+
+Examples:
+  msgvault query "SELECT from_email, COUNT(*) AS n FROM v_messages GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
+  msgvault query --format csv "SELECT * FROM v_senders ORDER BY message_count DESC"
+  msgvault query --format table "SELECT name, message_count FROM v_labels"`,
+	Args: cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		dbPath := cfg.DatabaseDSN()
+		analyticsDir := cfg.AnalyticsDir()
+
+		staleness := cacheNeedsBuild(dbPath, analyticsDir)
+		if staleness.NeedsBuild {
+			fmt.Fprintf(os.Stderr,
+				"Building analytics cache (%s)...\n",
+				staleness.Reason)
+			result, err := buildCache(
+				dbPath, analyticsDir, staleness.FullRebuild,
+			)
+			if err != nil {
+				return fmt.Errorf("build cache: %w", err)
+			}
+			if !result.Skipped {
+				fmt.Fprintf(os.Stderr,
+					"Cached %d messages.\n",
+					result.ExportedCount)
+			}
+		}
+
+		if !query.HasCompleteParquetData(analyticsDir) {
+			return fmt.Errorf(
+				"analytics cache is empty — sync some " +
+					"messages first")
+		}
+
+		return executeQuery(
+			analyticsDir, args[0], queryFormat, os.Stdout,
+		)
+	},
+}
+
+// executeQuery opens an in-memory DuckDB, registers views over
+// the Parquet files in analyticsDir, runs the SQL, and writes
+// the results in the requested format.
+func executeQuery(
+	analyticsDir, sqlStr, format string, w io.Writer,
+) error {
+	db, err := sql.Open("duckdb", "")
+	if err != nil {
+		return fmt.Errorf("open duckdb: %w", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	db.SetMaxOpenConns(1)
+
+	threads := runtime.GOMAXPROCS(0)
+	if _, err := db.Exec(
+		fmt.Sprintf("SET threads = %d", threads),
+	); err != nil {
+		return fmt.Errorf("set threads: %w", err)
+	}
+
+	if err := query.RegisterViews(db, analyticsDir); err != nil {
+		return fmt.Errorf("register views: %w", err)
+	}
+
+	rows, err := db.Query(sqlStr)
+	if err != nil {
+		return fmt.Errorf("execute query: %w", err)
+	}
+	defer func() { _ = rows.Close() }()
+
+	cols, err := rows.Columns()
+	if err != nil {
+		return fmt.Errorf("get columns: %w", err)
+	}
+
+	var allRows [][]any
+	for rows.Next() {
+		row, scanErr := scanRow(cols, rows)
+		if scanErr != nil {
+			return scanErr
+		}
+		allRows = append(allRows, row)
+	}
+	if err := rows.Err(); err != nil {
+		return fmt.Errorf("iterate rows: %w", err)
+	}
+
+	switch format {
+	case "json":
+		return writeJSON(w, cols, allRows)
+	case "csv":
+		return writeCSV(w, cols, allRows)
+	case "table":
+		return writeTable(w, cols, allRows)
+	default:
+		return fmt.Errorf("unknown format %q (use json, csv, or table)", format)
+	}
+}
+
+// scanRow scans a single row into a slice of interface{} values,
+// converting []byte to string for clean serialization.
+func scanRow(
+	cols []string, rows *sql.Rows,
+) ([]any, error) {
+	vals := make([]any, len(cols))
+	ptrs := make([]any, len(cols))
+	for i := range vals {
+		ptrs[i] = &vals[i]
+	}
+	if err := rows.Scan(ptrs...); err != nil {
+		return nil, fmt.Errorf("scan row: %w", err)
+	}
+	for i, v := range vals {
+		if b, ok := v.([]byte); ok {
+			vals[i] = string(b)
+		}
+	}
+	return vals, nil
+}
+
+func writeJSON(
+	w io.Writer, cols []string, rows [][]any,
+) error {
+	result := query.QueryResult{
+		Columns:  cols,
+		Rows:     rows,
+		RowCount: len(rows),
+	}
+	enc := json.NewEncoder(w)
+	enc.SetIndent("", "  ")
+	return enc.Encode(result)
+}
+
+// displayVal formats a value for CSV/table output. SQL NULLs
+// become empty strings; other values use fmt.Sprintf.
+func displayVal(v any) string {
+	if v == nil {
+		return ""
+	}
+	return fmt.Sprintf("%v", v)
+}
+
+func writeCSV(
+	w io.Writer, cols []string, rows [][]any,
+) error {
+	cw := csv.NewWriter(w)
+
+	if err := cw.Write(cols); err != nil {
+		return fmt.Errorf("write csv header: %w", err)
+	}
+
+	for _, row := range rows {
+		record := make([]string, len(row))
+		for i, v := range row {
+			record[i] = displayVal(v)
+		}
+		if err := cw.Write(record); err != nil {
+			return fmt.Errorf("write csv row: %w", err)
+		}
+	}
+
+	cw.Flush()
+	return cw.Error()
+}
+
+func writeTable(
+	w io.Writer, cols []string, rows [][]any,
+) error {
+	// Convert all values to strings for width calculation
+	strRows := make([][]string, len(rows))
+	for i, row := range rows {
+		strRows[i] = make([]string, len(row))
+		for j, v := range row {
+			strRows[i][j] = displayVal(v)
+		}
+	}
+
+	// Calculate column widths (min = header length)
+	widths := make([]int, len(cols))
+	for i, col := range cols {
+		widths[i] = len(col)
+	}
+	for _, row := range strRows {
+		for i, val := range row {
+			if len(val) > widths[i] {
+				widths[i] = len(val)
+			}
+		}
+	}
+
+	// Print header
+	for i, col := range cols {
+		if i > 0 {
+			_, _ = fmt.Fprint(w, "  ")
+		}
+		_, _ = fmt.Fprintf(w, "%-*s", widths[i], col)
+	}
+	_, _ = fmt.Fprintln(w)
+
+	// Print separator
+	for i, width := range widths {
+		if i > 0 {
+			_, _ = fmt.Fprint(w, "  ")
+		}
+		_, _ = fmt.Fprint(w, strings.Repeat("-", width))
+	}
+	_, _ = fmt.Fprintln(w)
+
+	// Print rows
+	for _, row := range strRows {
+		for i, val := range row {
+			if i > 0 {
+				_, _ = fmt.Fprint(w, "  ")
+			}
+			_, _ = fmt.Fprintf(w, "%-*s", widths[i], val)
+		}
+		_, _ = fmt.Fprintln(w)
+	}
+
+	// Print row count
+	_, _ = fmt.Fprintf(w, "(%d rows)\n", len(rows))
+	return nil
+}
+
+func init() {
+	rootCmd.AddCommand(queryCmd)
+	queryCmd.Flags().StringVar(
+		&queryFormat, "format", "json",
+		"Output format: json, csv, or table",
+	)
+}