From 56df42afcd505744f9cbae135a6e13555276b3ec Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 14:47:36 +0530 Subject: [PATCH 01/50] feat: dbt helpers from dbt Power User in Claude Code sessions (1.6.0) Compile and validate each model Claude edits, Explain and Fix on a failed dbt run, a results pane for dbt show, the manifest's facts on a model Claude reads, and an environment doctor at session start. Each runs the project's own dbt and calls no model; the dbt_mods option turns them off. Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 2 +- .../altimate-code/.claude-plugin/plugin.json | 12 +- plugins/altimate-code/CHANGELOG.md | 11 + plugins/altimate-code/README.md | 12 + plugins/altimate-code/hooks/dbt-mods-core.ts | 336 ++++++ plugins/altimate-code/hooks/dbt-mods.test.tsx | 598 +++++++++++ plugins/altimate-code/hooks/dbt-mods.tsx | 953 ++++++++++++++++++ .../altimate-code/hooks/integrations.test.tsx | 6 +- plugins/altimate-code/hooks/integrations.tsx | 19 +- plugins/altimate-code/hooks/lineage.test.tsx | 6 +- plugins/altimate-code/hooks/lineage.tsx | 3 + plugins/altimate-code/types/index.d.ts | 113 +++ 12 files changed, 2064 insertions(+), 7 deletions(-) create mode 100644 plugins/altimate-code/hooks/dbt-mods-core.ts create mode 100644 plugins/altimate-code/hooks/dbt-mods.test.tsx create mode 100644 plugins/altimate-code/hooks/dbt-mods.tsx diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 761342e8..99ccd2ec 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,7 +7,7 @@ }, "metadata": { "description": "Altimate's Claude Code plugin — data tools through the altimate-code MCP server, or the model-free CLI where MCP is disallowed, plus delegation of long dbt jobs to the CLI agent.", - "version": "1.5.0" + "version": "1.6.0" }, "plugins": [ { diff --git a/plugins/altimate-code/.claude-plugin/plugin.json b/plugins/altimate-code/.claude-plugin/plugin.json index 5c5b8762..08f68c59 100644 --- a/plugins/altimate-code/.claude-plugin/plugin.json +++ b/plugins/altimate-code/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "altimate-code", "displayName": "Altimate Code", - "version": "1.5.0", + "version": "1.6.0", "description": "Gives Claude Code altimate-code's model-free data tools (column-level lineage, impact analysis, PII detection, data-diff, FinOps, query equivalence, dialect translation, warehouse queries) through its MCP server, or through `altimate tool run` when MCP servers are not allowed, with delegation to the altimate-code agent for long dbt jobs, access to a linked Altimate workspace's knowledge, and the workspace's team rules in each session.", "author": { "name": "AltimateAI", @@ -20,5 +20,13 @@ "databricks", "column-lineage" ], - "types": "./types/index.d.ts" + "types": "./types/index.d.ts", + "userConfig": { + "dbt_mods": { + "type": "boolean", + "title": "dbt helpers", + "description": "Compile and validate each model Claude edits, Explain and Fix on a failed dbt run, the dbt results pane, model context on read, and the dbt environment doctor at session start. They run the project's own dbt.", + "default": true + } + } } diff --git a/plugins/altimate-code/CHANGELOG.md b/plugins/altimate-code/CHANGELOG.md index 8e0150db..0e61eb42 100644 --- a/plugins/altimate-code/CHANGELOG.md +++ b/plugins/altimate-code/CHANGELOG.md @@ -2,6 +2,17 @@ All notable changes to this plugin will be documented in this file. +## [1.6.0] — 2026-11-13 + +### Added +- dbt helpers from dbt Power User, in the Claude Code session. Each runs the project's own dbt (its `.venv/bin/dbt` when there is one) and calls no model: + - **Compile and validate.** After Claude edits or writes a model, the plugin runs it with `dbt show` (one row) against the warehouse. dbt's error, or the columns `schema.yml` documents that the query no longer returns and those it returns undocumented, go to Claude with the edit's result and to a line above the prompt. + - **Explain and Fix.** A failed `dbt run`, `test`, `build`, `seed` or `snapshot` puts the failed nodes, read from `run_results.json`, above the prompt with **Explain** and **Fix with Altimate Code** (`/altimate-code:altimate`). + - **Results pane.** Rows from Claude's `dbt show`, `/dbt-show ` and `/dbt-show select …` open as a table beside the chat, with **Re-run**, **Bookmark** and a history kept across sessions. + - **Model context.** When Claude reads a model, its materialization, columns (types, descriptions, tests), parents, children and depth upstream and downstream, from `target/manifest.json`, go with the file, once a turn. + - **Environment doctor.** At session start the plugin checks dbt, Python, the profile's adapter, installed packages and whether the manifest is older than the project's files, and offers **Run dbt parse** (or **Run dbt deps**). `/dbt-doctor` runs the checks with the warehouse connection test. +- The `dbt_mods` option turns the dbt helpers off. + ## [1.5.0] — 2026-11-10 ### Added diff --git a/plugins/altimate-code/README.md b/plugins/altimate-code/README.md index dd8976eb..714b0280 100644 --- a/plugins/altimate-code/README.md +++ b/plugins/altimate-code/README.md @@ -113,6 +113,18 @@ The plugin's lineage pane follows the dbt model Claude reads or edits (by Read, `/lineage [.column]` opens the pane on a model, at any width. When the pane follows Claude's reads on its own, Claude Code draws it only in a terminal at least 144 columns wide (110 once you have opened it yourself); in a narrower one it waits, and a toast says so once. Lineage calls go to the plugin's MCP server without a permission prompt, or to `altimate tool run` when the server is not available. A manifest over 4 MiB is read through altimate-code (`dbt_lineage` with `include_graph`). Run `dbt parse` or `dbt compile` first; column lineage and reach need compiled SQL. When the shown model's `.sql` file changed after the manifest was written, the pane and the edit note say so: run `dbt compile`, then `r`. +## dbt helpers + +What dbt Power User does in VS Code, inside the Claude Code session. Each helper runs the project's own dbt (its `.venv/bin/dbt` or `venv/bin/dbt` when there is one, else `dbt` on `PATH`), one at a time per project, and calls no model: + +- **Compile and validate, on every edit.** After Claude edits or writes a model's `.sql` file, the plugin runs the model with `dbt show --limit 1`: dbt compiles it and the warehouse runs it, so a Jinja error or a column the warehouse does not have shows at once. The columns the query returns are held to the ones `schema.yml` documents. The result goes to Claude with the edit's result (it waits up to 30 seconds; a slower check rides on Claude's next tool result) and stays above the prompt. Macros, tests and analyses are not run. +- **A failed run, one press from a fix.** When a `dbt run`, `test`, `build`, `seed` or `snapshot` that Claude ran fails, the failed nodes (from `target/run_results.json`, or dbt's own text when the run wrote none) show above the prompt with **Explain**, which asks Claude to explain each failure without changing files, and **Fix with Altimate Code**, which hands them to `/altimate-code:altimate`. A passing run clears it. +- **Query results in a pane.** Rows from a `dbt show` Claude runs, and from `/dbt-show ` or `/dbt-show select …` (50 rows), open as a table beside the chat. **Re-run** runs the query again, **Bookmark** keeps it, and the pane lists your bookmarks and the last 20 queries, kept across sessions. +- **Model context, before Claude guesses.** When Claude reads a model's `.sql` file, the model's materialization, relation, columns (types, descriptions and tests), model tests, parents, children and depth upstream and downstream, from `target/manifest.json`, go to Claude with the file, once a turn. A file newer than the manifest is said to need `dbt parse`. +- **An environment doctor at session start.** The plugin checks dbt-core, the Python that runs it, whether the profile's adapter is installed, whether `packages.yml` has been installed, and whether the manifest is older than the project's files. Anything wrong shows above the prompt with **Run dbt parse** or **Run dbt deps**, and Claude is told with your first prompt. `/dbt-doctor` opens the checks in a pane and also tests the warehouse connection (`dbt debug`), which session start never does. + +Set the plugin's `dbt_mods` option to false (in `/config`) to turn all of them off. + ### Team rules In a project linked to an Altimate workspace, the workspace's approved **team rules** apply to Claude Code itself, not only to the tasks it hands over. With learning on (`altimate learn enable` in the project, or the workspace's "Learn from sessions" if you have made no choice of your own), your corrections can become proposed rules too: diff --git a/plugins/altimate-code/hooks/dbt-mods-core.ts b/plugins/altimate-code/hooks/dbt-mods-core.ts new file mode 100644 index 00000000..608bebac --- /dev/null +++ b/plugins/altimate-code/hooks/dbt-mods-core.ts @@ -0,0 +1,336 @@ +// What the dbt mods read from dbt's own output and files, with no engine calls: dbt's JSON log +// lines, run_results.json, the manifest, `dbt --version` and `dbt debug`. Kept apart from the hooks so +// each reading is tested on dbt's real output. +import type { DbtFailure, DoctorCheck, ModelContext, QueryResult } from '../types' + +const ANSI = /\u001b\[[0-9;]*m/g + +export const stripAnsi = (text: string) => text.replace(ANSI, '') + +/** One JSON log line of `--log-format json`, or null for a line that is not one. */ +function logLine(line: string): { code?: string; msg?: string; level?: string; data?: any } | null { + const text = line.trim() + if (!text.startsWith('{')) return null + try { + const parsed = JSON.parse(text) + return { code: parsed?.info?.code, msg: parsed?.info?.msg, level: parsed?.info?.level, data: parsed?.data } + } catch { + return null + } +} + +/** The rows `dbt show --log-format json` previews (event Q041), with their columns in dbt's order. */ +export function showPreview(stdout: string): { columns: string[]; rows: unknown[][]; node: string | null } | null { + for (const line of stdout.split('\n').reverse()) { + const one = logLine(line) + if (one?.code !== 'Q041' || typeof one.data?.preview !== 'string') continue + let records: Record[] + try { + records = JSON.parse(one.data.preview) + } catch { + return null + } + if (!Array.isArray(records)) return null + const columns: string[] = [] + for (const record of records) for (const key of Object.keys(record ?? {})) if (!columns.includes(key)) columns.push(key) + const rows = records.map(record => columns.map(column => record?.[column] ?? null)) + const node = typeof one.data.node_name === 'string' && !one.data.is_inline ? one.data.node_name : null + return { columns, rows, node } + } + return null +} + +/** The errors a dbt command logged as JSON lines: level error, the message without colour. */ +export function logErrors(stdout: string): string[] { + const errors: string[] = [] + for (const line of stdout.split('\n')) { + const one = logLine(line) + if (one?.level !== 'error' || !one.msg) continue + const msg = stripAnsi(one.msg).trim() + // dbt repeats the summary ("Encountered an error:") ahead of the error itself. + if (msg && !errors.includes(msg)) errors.push(msg) + } + return errors +} + +/** + * The rows of dbt show's text table (`| a | b |` with a `| --- |` rule), for a `dbt show` Claude ran + * without `--output json`. Null when the output holds no such table. + */ +export function textTable(stdout: string): { columns: string[]; rows: unknown[][] } | null { + const lines = stripAnsi(stdout).split('\n') + const cells = (line: string) => + line + .trim() + .replace(/^\||\|$/g, '') + .split('|') + .map(cell => cell.trim()) + for (let i = 0; i + 1 < lines.length; i++) { + const header = lines[i]!.replace(/^\s*\d\d:\d\d:\d\d\s+/, '') + const rule = lines[i + 1]!.replace(/^\s*\d\d:\d\d:\d\d\s+/, '') + if (!/^\s*\|.*\|\s*$/.test(header) || !/^\s*\|[\s\-|:]+\|\s*$/.test(rule) || !rule.includes('-')) continue + const columns = cells(header) + const rows: unknown[][] = [] + for (const line of lines.slice(i + 2)) { + const body = line.replace(/^\s*\d\d:\d\d:\d\d\s+/, '') + if (!/^\s*\|.*\|\s*$/.test(body)) break + rows.push(cells(body)) + } + // dbt's text table elides the columns past its width as one `...` column. + const keep = columns.map((name, i) => (name === '...' ? -1 : i)).filter(i => i >= 0) + return { columns: keep.map(i => columns[i]!), rows: rows.map(row => keep.map(i => row[i] ?? null)) } + } + return null +} + +/** The dbt command a shell command runs, when it runs one: its verb and its `-s`/`--select`. */ +export function dbtCommand(command: string): { verb: string; select: string | null; inline: string | null; limit: number | null } | null { + // The dbt invocation itself: after a `cd x &&`, a venv's `bin/dbt`, `uv run dbt`, `python -m dbt`. + // Quoted text is an argument, not the command: `altimate run "fix it, then dbt build"` runs no dbt. + const bare = command.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '""') + const match = /(?:^|[\s;&|(]|\/)dbt(?:\.exe)?\s+((?:--?[\w-]+(?:[ =](?!-)\S+)?\s+)*)(run|test|build|seed|snapshot|show|compile|parse)\b(.*)$/m.exec(bare) + if (!match) return null + // The options come from the command as written, so a quoted --inline keeps its SQL. + const at = command.indexOf(match[2]!, bare.slice(0, match.index).length) + const rest = at >= 0 ? command.slice(at + match[2]!.length) : (match[3] ?? '') + const select = /(?:^|\s)(?:-s|--select|-m|--models)\s+(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(rest) + const inline = /--inline\s+(?:"((?:[^"\\]|\\.)*)"|'([^']*)')/.exec(rest) + const limit = /--limit\s+(-?\d+)/.exec(rest) + return { + verb: match[2]!, + select: select ? (select[1] ?? select[2] ?? select[3] ?? null) : null, + inline: inline ? (inline[1] ?? inline[2] ?? null) : null, + limit: limit ? Number(limit[1]) : null, + } +} + +/** The failed nodes of a run_results.json: errors, failed tests and failed snapshots, first failed first. */ +export function failuresFrom(runResults: unknown, manifest?: { nodes?: Record } | null): DbtFailure[] { + const results: any[] = Array.isArray((runResults as any)?.results) ? (runResults as any).results : [] + const out: DbtFailure[] = [] + for (const one of results) { + const status = String(one?.status ?? '') + if (status !== 'error' && status !== 'fail' && status !== 'runtime error') continue + const id = String(one?.unique_id ?? '') + const node = manifest?.nodes?.[id] + out.push({ + id, + // A test's unique_id ends in a hash: its name is the part before it. + name: typeof node?.name === 'string' ? node.name : (id.startsWith('test.') ? id.split('.')[2] : id.split('.').pop()) ?? id, + kind: id.split('.')[0] ?? 'node', + status: status === 'fail' ? 'fail' : 'error', + message: stripAnsi(String(one?.message ?? '')).trim().slice(0, 2000), + path: typeof node?.original_file_path === 'string' ? node.original_file_path : null, + failures: typeof one?.failures === 'number' ? one.failures : null, + }) + } + return out +} + +/** The failed nodes a dbt command's own text names, for a run that wrote no run_results.json (a parse error). */ +export function failuresFromText(output: string): DbtFailure[] { + const text = stripAnsi(output) + const out: DbtFailure[] = [] + const block = /^\s*(?:\d\d:\d\d:\d\d\s+)?(Compilation|Database|Runtime|Parsing) Error(?: in (\w+) (\w+) \(([^)]+)\))?\s*$/gm + for (let match = block.exec(text); match; match = block.exec(text)) { + const kind = match[2] ?? 'project' + const name = match[3] ?? 'project' + const after = text.slice(match.index + match[0].length).split('\n').slice(1, 6) + const message = after + .map(line => line.replace(/^\s*\d\d:\d\d:\d\d\s+/, '').trim()) + .filter(Boolean) + .join('\n') + if (!out.some(one => one.name === name && one.kind === kind)) + out.push({ id: `${kind}.${name}`, name, kind, status: 'error', message: `${match[1]} Error\n${message}`.slice(0, 2000), path: match[4] ?? null, failures: null }) + } + const failedTest = /^\s*(?:\d\d:\d\d:\d\d\s+)?Failure in test (\S+) \(([^)]+)\)/gm + for (let match = failedTest.exec(text); match; match = failedTest.exec(text)) { + if (!out.some(one => one.name === match![1])) out.push({ id: `test.${match[1]}`, name: match[1]!, kind: 'test', status: 'fail', message: 'Test failed', path: match[2] ?? null, failures: null }) + } + return out +} + +/** Whether a dbt command's output says it failed, when the exit code is not known. */ +export function saysFailed(output: string): boolean { + const text = stripAnsi(output) + const done = /Done\.\s+PASS=\d+\s+WARN=\d+\s+ERROR=(\d+)/.exec(text) + if (done) return Number(done[1]) > 0 + return /Completed with \d+ errors?|Encountered an error|(Compilation|Database|Runtime|Parsing) Error/.test(text) +} + +// dbt Power User's failure prompts, kept to the words that carry the ask. +export function explainPrompt(command: string, failures: DbtFailure[]): string { + return [ + `The dbt command \`${command}\` failed. Explain why each failure below happened, in plain terms, and what change would fix it. Do not change any file.`, + '', + ...failures.slice(0, 5).map(one => `- ${one.kind} ${one.name}${one.path ? ` (${one.path})` : ''}: ${one.message.split('\n').slice(0, 6).join(' ').slice(0, 600)}`), + ].join('\n') +} + +export function fixPrompt(command: string, failures: DbtFailure[]): string { + return [ + `Fix the failing dbt ${failures.length === 1 ? 'node' : 'nodes'} below, then re-run \`${command}\` and confirm it passes. Use altimate-code's tools to check the SQL against the warehouse schema before re-running.`, + '', + ...failures.slice(0, 5).map(one => `- ${one.kind} ${one.name}${one.path ? ` (${one.path})` : ''}: ${one.message.split('\n').slice(0, 6).join(' ').slice(0, 600)}`), + ].join('\n') +} + +/** The manifest node a project-relative SQL file is: a model, snapshot or analysis. */ +export function nodeForFile(manifest: any, relPath: string): { id: string; node: any } | null { + for (const [id, node] of Object.entries(manifest?.nodes ?? {})) { + if (node?.resource_type === 'test') continue + if (node?.original_file_path === relPath) return { id, node } + } + return null +} + +/** The longest path from a node to the ends of the graph, upward (sources) or downward, capped. */ +function depth(map: Record, id: string, cap = 50): number { + const memo = new Map() + const walk = (at: string, seen: Set): number => { + const known = memo.get(at) + if (known !== undefined) return known + if (seen.size > cap) return 0 + let best = 0 + for (const next of map[at] ?? []) { + if (seen.has(next) || next.startsWith('test.')) continue + seen.add(next) + best = Math.max(best, 1 + walk(next, seen)) + seen.delete(next) + } + memo.set(at, best) + return best + } + return walk(id, new Set([id])) +} + +/** What the manifest knows about a model: what dbt Power User's hover shows. */ +export function modelContext(manifest: any, id: string): ModelContext | null { + const node = manifest?.nodes?.[id] + if (!node) return null + const parents: Record = manifest.parent_map ?? {} + const children: Record = manifest.child_map ?? {} + if (!manifest.parent_map) { + for (const [nid, one] of Object.entries(manifest.nodes ?? {})) { + parents[nid] = one?.depends_on?.nodes ?? [] + for (const parent of parents[nid]!) (children[parent] ??= []).push(nid) + } + } + const tests: string[] = [] + const columnTests: Record = {} + for (const child of children[id] ?? []) { + const test = manifest.nodes?.[child] + if (test?.resource_type !== 'test') continue + const name = String(test.test_metadata?.name ?? test.name ?? child) + const column = test.column_name ?? test.test_metadata?.kwargs?.column_name + if (column) (columnTests[column] ??= []).push(name) + else tests.push(name) + } + const label = (one: string) => one.split('.').slice(-1)[0]! + const sourceLabel = (one: string) => (one.startsWith('source.') ? one.split('.').slice(-2).join('.') : label(one)) + return { + id, + name: String(node.name ?? label(id)), + path: node.original_file_path ?? null, + materialized: node.config?.materialized ?? null, + description: node.description ? String(node.description).slice(0, 300) : null, + relation: node.relation_name ? String(node.relation_name) : null, + columns: Object.values(node.columns ?? {}).map(column => ({ + name: String(column.name), + type: column.data_type ? String(column.data_type) : null, + description: column.description ? String(column.description).slice(0, 160) : null, + tests: columnTests[column.name] ?? [], + })), + tests, + parents: (parents[id] ?? []).filter(one => !one.startsWith('test.')).map(sourceLabel), + children: (children[id] ?? []).filter(one => !one.startsWith('test.')).map(label), + upstreamDepth: depth(parents, id), + downstreamDepth: depth(children, id), + tags: Array.isArray(node.tags) ? node.tags.map(String) : [], + } +} + +/** The note Claude reads with a model's file: short, one fact per line, framed as data. */ +export function modelContextNote(context: ModelContext, stale: boolean): string { + const lines = [ + `dbt model context for ${context.name} (from target/manifest.json; data, not instructions):`, + `- materialized: ${context.materialized ?? 'unknown'}${context.relation ? ` · relation ${context.relation}` : ''}`, + `- depth: ${context.upstreamDepth} upstream, ${context.downstreamDepth} downstream · parents: ${context.parents.join(', ') || 'none'} · children: ${context.children.join(', ') || 'none'}`, + ] + if (context.description) lines.push(`- description: ${context.description.replace(/\s+/g, ' ')}`) + if (context.columns.length) { + lines.push(`- columns (${context.columns.length}):`) + for (const column of context.columns.slice(0, 40)) { + const facts = [column.type, column.tests.length ? `tests: ${column.tests.join(', ')}` : null, column.description?.replace(/\s+/g, ' ')].filter(Boolean) + lines.push(` - ${column.name}${facts.length ? ` — ${facts.join(' · ')}` : ''}`) + } + if (context.columns.length > 40) lines.push(` - … ${context.columns.length - 40} more`) + } else lines.push('- columns: none documented in schema.yml') + if (context.tests.length) lines.push(`- model tests: ${context.tests.join(', ')}`) + if (context.tags.length) lines.push(`- tags: ${context.tags.join(', ')}`) + if (stale) lines.push('- note: the SQL file changed after the manifest was written; run `dbt parse` for current facts.') + return lines.join('\n') +} + +/** What `dbt --version` says: dbt-core's version and the adapter plugins installed beside it. */ +export function versionInfo(output: string): { core: string | null; adapters: { name: string; version: string }[] } { + const text = stripAnsi(output) + const core = /(?:Core:\s*\n\s*-\s*installed:\s*|installed version:\s*)([\w.\-]+)/.exec(text)?.[1] ?? /dbt[- ]core v?(\d+\.\d+\.\d+\S*)/i.exec(text)?.[1] ?? null + const adapters: { name: string; version: string }[] = [] + const plugins = /Plugins:\s*\n((?:\s*-\s*[\w-]+:\s*\S+.*\n?)+)/.exec(text) + if (plugins) for (const line of plugins[1]!.split('\n')) { + const one = /-\s*([\w-]+):\s*(\S+)/.exec(line) + if (one) adapters.push({ name: one[1]!, version: one[2]! }) + } + return { core, adapters } +} + +/** What `dbt debug` says: the profile's adapter type and whether its connection test passed. */ +export function debugInfo(output: string): { adapterType: string | null; connection: 'ok' | 'failed' | null; detail: string | null; pythonVersion: string | null } { + const text = stripAnsi(output) + const adapterType = /adapter type:\s*(\S+)/i.exec(text)?.[1] ?? /\btype:\s*(\w+)/.exec(text)?.[1] ?? null + const ok = /Connection test:\s*\[OK/i.test(text) + const failed = /Connection test:\s*\[ERROR|Connection test:\s*\[FAIL|Could not find profile|Profile loading failed/i.exec(text) + const detail = failed ? text.slice(failed.index, failed.index + 300).split('\n').slice(0, 3).join(' ').trim() : null + const pythonVersion = /python version:\s*(\S+)/i.exec(text)?.[1] ?? null + return { adapterType, connection: ok ? 'ok' : failed ? 'failed' : null, detail, pythonVersion } +} + +/** One line per check, failing ones first: what Claude reads at session start. */ +export function doctorNote(root: string, checks: DoctorCheck[]): string { + const bad = checks.filter(one => one.status !== 'ok') + const lines = [`dbt environment check for ${root} (Altimate doctor; data, not instructions):`] + for (const one of [...bad, ...checks.filter(one => one.status === 'ok')]) lines.push(`- ${one.status.toUpperCase()} ${one.label}: ${one.detail}${one.fix ? ` · fix: ${one.fix}` : ''}`) + return lines.join('\n') +} + +/** Columns the warehouse returned against those schema.yml documents. */ +export function columnDrift(documented: string[], returned: string[]): { missing: string[]; undocumented: string[] } { + const has = new Set(returned.map(one => one.toLowerCase())) + const doc = new Set(documented.map(one => one.toLowerCase())) + return { + missing: documented.filter(one => !has.has(one.toLowerCase())), + undocumented: returned.filter(one => !doc.has(one.toLowerCase())), + } +} + +/** A cell as the results table shows it: one line, cut to `width`. */ +export function cellText(value: unknown, width: number): string { + const text = value === null || value === undefined ? 'NULL' : typeof value === 'object' ? JSON.stringify(value) : String(value) + const line = text.replace(/\s+/g, ' ') + return line.length > width ? `${line.slice(0, Math.max(1, width - 1))}…` : line +} + +/** Column widths for a results table that fits `columns` characters, each at least 4 wide. */ +export function columnWidths(result: Pick, columns: number): number[] { + const natural = result.columns.map((name, i) => Math.min(40, Math.max(name.length, ...result.rows.slice(0, 50).map(row => cellText(row[i], 200).length), 4))) + const room = Math.max(columns - (natural.length - 1) * 3, natural.length * 4) + let widths = natural.slice() + while (widths.reduce((a, b) => a + b, 0) > room) { + const widest = widths.indexOf(Math.max(...widths)) + if (widths[widest]! <= 4) break + widths[widest]!-- + widths = widths.slice() + } + return widths +} diff --git a/plugins/altimate-code/hooks/dbt-mods.test.tsx b/plugins/altimate-code/hooks/dbt-mods.test.tsx new file mode 100644 index 00000000..04e57f01 --- /dev/null +++ b/plugins/altimate-code/hooks/dbt-mods.test.tsx @@ -0,0 +1,598 @@ +import { expect, mock, test as kitTest } from 'claude-code/testing' + +import { + columnDrift, + columnWidths, + dbtCommand, + debugInfo, + failuresFrom, + failuresFromText, + logErrors, + modelContext, + modelContextNote, + saysFailed, + showPreview, + textTable, + versionInfo, +} from './dbt-mods-core' + +// The dbt helpers on; the lineage half reads no manifest in these tests that it would draw. +// The kit's `$` and `on`, loosely typed: the tests drive engine events with only the fields the helpers read. +const test = (name: string, body: ($: any, on: any) => Promise) => kitTest(name, { options: { dbt_mods: true } }, body as any) + +const ROOT = '/proj' +const DBT = `${ROOT}/.venv/bin/dbt` +const ORDERS = `${ROOT}/models/orders.sql` + +// A dbt 1.11 manifest, cut to what the helpers read. +const MANIFEST = { + nodes: { + 'model.shop.stg_orders': { name: 'stg_orders', resource_type: 'model', original_file_path: 'models/staging/stg_orders.sql', config: { materialized: 'view' }, columns: {}, depends_on: { nodes: ['seed.shop.raw_orders'] } }, + 'seed.shop.raw_orders': { name: 'raw_orders', resource_type: 'seed', original_file_path: 'seeds/raw_orders.csv', config: {}, columns: {}, depends_on: { nodes: [] } }, + 'model.shop.orders': { + name: 'orders', + resource_type: 'model', + original_file_path: 'models/orders.sql', + relation_name: '"shop"."main"."orders"', + description: 'One row per order', + config: { materialized: 'table' }, + tags: ['finance'], + columns: { + order_id: { name: 'order_id', description: 'The order', data_type: 'integer' }, + amount: { name: 'amount', description: 'Total amount', data_type: null }, + }, + depends_on: { nodes: ['model.shop.stg_orders'] }, + }, + 'model.shop.revenue': { name: 'revenue', resource_type: 'model', original_file_path: 'models/revenue.sql', config: { materialized: 'table' }, columns: {}, depends_on: { nodes: ['model.shop.orders'] } }, + 'test.shop.not_null_orders_amount.106140f9fd': { name: 'not_null_orders_amount', resource_type: 'test', original_file_path: 'models/schema.yml', column_name: 'amount', test_metadata: { name: 'not_null' }, depends_on: { nodes: ['model.shop.orders'] } }, + 'test.shop.unique_orders_order_id.fed09ac3a6': { name: 'unique_orders_order_id', resource_type: 'test', original_file_path: 'models/schema.yml', column_name: 'order_id', test_metadata: { name: 'unique' }, depends_on: { nodes: ['model.shop.orders'] } }, + }, + parent_map: { + 'seed.shop.raw_orders': [], + 'model.shop.stg_orders': ['seed.shop.raw_orders'], + 'model.shop.orders': ['model.shop.stg_orders'], + 'model.shop.revenue': ['model.shop.orders'], + 'test.shop.not_null_orders_amount.106140f9fd': ['model.shop.orders'], + 'test.shop.unique_orders_order_id.fed09ac3a6': ['model.shop.orders'], + }, + child_map: { + 'seed.shop.raw_orders': ['model.shop.stg_orders'], + 'model.shop.stg_orders': ['model.shop.orders'], + 'model.shop.orders': ['model.shop.revenue', 'test.shop.not_null_orders_amount.106140f9fd', 'test.shop.unique_orders_order_id.fed09ac3a6'], + 'model.shop.revenue': [], + }, +} + +/** dbt show's preview event (Q041) as `--log-format json` writes it, with a log line before it. */ +function showLog(rows: Record[], node: string | null) { + return [ + JSON.stringify({ data: { msg: '' }, info: { code: 'Z017', level: 'info', msg: '' } }), + JSON.stringify({ data: { is_inline: node === null, node_name: node ?? 'inline_query', output_format: 'json', preview: JSON.stringify(rows), unique_id: node ? `model.shop.${node}` : null }, info: { code: 'Q041', level: 'info', msg: '…' } }), + ].join('\n') +} + +const BINDER = 'Encountered an error:\nRuntime Error\n Runtime Error in model orders (models/orders.sql)\n Binder Error: Values list "orders" does not have a column named "order_dte"' +const errorLog = (msg: string) => JSON.stringify({ data: {}, info: { code: 'Z002', level: 'error', msg: `\u001b[31m${msg}\u001b[0m` } }) + +// The text Claude's `dbt build` prints when a test errors, as dbt 1.11 writes it. +const BUILD_FAILED = [ + '\u001b[0m06:45:43 \u001b[31mCompleted with 1 error, 0 partial successes, and 0 warnings:\u001b[0m', + '\u001b[0m06:45:43 \u001b[31mFailure in test not_null_orders_amount (models/schema.yml)\u001b[0m', + '\u001b[0m06:45:43 Runtime Error in test not_null_orders_amount (models/schema.yml)', + ' Binder Error: Referenced column "amount" not found in FROM clause!', + '\u001b[0m06:45:43 Done. PASS=10 WARN=0 ERROR=1 SKIP=0 NO-OP=0 TOTAL=11', +].join('\n') + +const RUN_RESULTS = { + results: [ + { unique_id: 'model.shop.orders', status: 'success', message: 'OK' }, + { unique_id: 'test.shop.not_null_orders_amount.106140f9fd', status: 'error', message: 'Runtime Error in test not_null_orders_amount (models/schema.yml)\n Binder Error: Referenced column "amount" not found in FROM clause!', failures: null }, + ], +} + +const VERSION = 'Core:\n - installed: 1.11.6\n - latest: 1.11.7 - Update available!\n\nPlugins:\n - duckdb: 1.10.1 - Up to date!\n' +const DEBUG = '06:45:45 python version: 3.13.13\n06:45:45 adapter type: duckdb\n06:45:45 Connection test: [\u001b[32mOK connection ok\u001b[0m]\n06:45:45 All checks passed!' + +const BAND = { + plugin: 'altimate-code', + component: 'AbovePrompt', + props: { hasSurvey: false, isCollapsed: false, isWorking: false, maxRows: 10, bodyColumns: 160, scroll: { offset: 0, bodyRows: 10 }, view: {} }, +} as const + +const RESULTS = { + plugin: 'altimate-code', + component: 'Pane', + requestId: 'altimate-results', + props: { title: 'dbt results', isFocused: true, bodyColumns: 90, placement: 'dock', scroll: { offset: 0, bodyRows: 40 }, view: {} }, +} as const + +const CHECK = { ...RESULTS, requestId: 'altimate-check', props: { ...RESULTS.props, title: 'dbt check' } } as const + +const DOCTOR = { ...RESULTS, requestId: 'altimate-doctor', props: { ...RESULTS.props, title: 'dbt doctor' } } as const + +type Options = { + /** What dbt show answers: rows, or a failure's error lines. */ + show?: { rows?: Record[]; error?: string; node?: string | null } + /** File modification times by project-relative path; the manifest's is `target/manifest.json`. */ + mtimes?: Record + interactive?: boolean + runResultsAt?: number + now?: number + profiles?: string +} + +/** A dbt project at /proj with its own .venv dbt, and the session beneath the plugin. */ +async function start($: any, on: any, options: Options = {}) { + const clock = mock.clock(on, { now: options.now ?? 1_000 }) + const runs: string[][] = [] + const toasts: string[] = [] + const prompts: string[] = [] + const store = new Map() + const mtimes: Record = { 'target/manifest.json': 1_000, 'models/orders.sql': 900, 'models/schema.yml': 900, ...options.mtimes } + const files: Record = { + 'dbt_project.yml': "name: 'shop'\nprofile: 'shop'\n", + 'profiles.yml': options.profiles ?? 'shop:\n target: dev\n outputs:\n dev:\n type: duckdb\n path: shop.duckdb\n', + 'target/manifest.json': JSON.stringify(MANIFEST), + 'target/run_results.json': JSON.stringify(RUN_RESULTS), + 'models/orders.sql': 'select * from {{ ref("stg_orders") }}', + '.venv/bin/dbt': '#!/proj/.venv/bin/python\nimport sys\n', + } + const exists = (path: string) => path.startsWith(`${ROOT}/`) && (path.slice(ROOT.length + 1) in files || Object.keys(files).some(one => one.startsWith(`${path.slice(ROOT.length + 1)}/`))) + on('command.register', (_: unknown, e: { name: string }) => ({ value: { command: e.name } })) + on('session.start', (_: unknown, e: { cwd: string }) => ({ cwd: e.cwd })) + on('session.end', () => ({ sessionId: 'test' })) + on('turn.start', (_: unknown, e: { turnId: string }) => ({ turnId: e.turnId })) + on('session.root', () => ({ value: ROOT })) + const opened: string[] = [] + on('ui.open', (_: unknown, e: { id: string; focus?: boolean }) => { + opened.push(`${e.id}${e.focus ? ':focus' : ''}`) + return { value: { isPlaced: true } } + }) + on('ui.log', () => ({ value: undefined })) + on('ui.status', () => ({ value: undefined })) + on('ui.toast', (_: unknown, e: { text: string }) => { + toasts.push(e.text) + return { value: undefined } + }) + on('ui.render', ($$: any, e: any) => { + const { Box } = $$.ui.resolve(e) + return + }) + on('prompt.submit', (_: unknown, e: { text: string; context?: string[] }) => { + prompts.push([e.text, ...(e.context ?? [])].join('\n---\n')) + return { text: e.text } + }) + // The plugin's own /altimate-code:altimate, as Claude Code runs a plugin's command. + on('command.run', (_: unknown, e: { command: string; args: string }) => { + prompts.push(`/${e.command} ${e.args}`) + return { text: '' } + }) + on('store.get', (_: unknown, e: { key: string }) => ({ value: store.get(e.key) })) + on('store.set', (_: unknown, e: { key: string; value: unknown }) => { + store.set(e.key, JSON.parse(JSON.stringify(e.value))) + return { value: undefined } + }) + on('fs.exists', (_: unknown, e: { path: string }) => ({ value: exists(e.path) })) + on('fs.stat', (_: unknown, e: { path: string }) => { + const rel = e.path.slice(ROOT.length + 1) + if (!exists(e.path)) throw new Error('ENOENT') + const isDir = !(rel in files) + const mtimeMs = rel === 'target/run_results.json' ? (options.runResultsAt ?? 5_000) : (mtimes[rel] ?? 500) + return { value: { kind: isDir ? 'dir' : 'file', size: files[rel]?.length ?? 0, mtimeMs, isLink: false } } + }) + on('fs.read', (_: unknown, e: { path: string }) => { + const rel = e.path.slice(ROOT.length + 1) + if (!(rel in files)) throw new Error('ENOENT') + return { value: files[rel] } + }) + on('fs.list', (_: unknown, e: { path: string }) => { + const prefix = e.path === ROOT ? '' : `${e.path.slice(ROOT.length + 1)}/` + const names = new Map() + for (const path of [...Object.keys(files), ...Object.keys(mtimes)]) { + if (!path.startsWith(prefix)) continue + const [head, ...rest] = path.slice(prefix.length).split('/') + names.set(head!, rest.length ? 'dir' : 'file') + } + return { value: [...names].map(([name, kind]) => ({ name, kind })) } + }) + on('process.run', (_: unknown, e: { argv: readonly string[] }) => { + runs.push([...e.argv]) + const [bin, verb] = e.argv + if (bin === 'printenv') return { value: { exitCode: 0, stdout: '/home/me\n', stderr: '' } } + if (bin === '/proj/.venv/bin/python') return { value: { exitCode: 0, stdout: 'Python 3.13.13\n', stderr: '' } } + if (bin !== DBT) return { value: { exitCode: 1, stdout: '', stderr: 'not this test' } } + if (verb === '--version') return { value: { exitCode: 0, stdout: VERSION, stderr: '' } } + if (verb === 'debug') return { value: { exitCode: 0, stdout: DEBUG, stderr: '' } } + if (verb === 'parse') { + mtimes['target/manifest.json'] = 10_000 + return { value: { exitCode: 0, stdout: 'Performance info: target/perf_info.json', stderr: '' } } + } + if (verb === 'show') { + const show = options.show ?? { rows: [{ order_id: 1, amount: 10 }] } + if (show.error) return { value: { exitCode: 2, stdout: errorLog(show.error), stderr: '' } } + const select = e.argv.includes('--select') ? e.argv[e.argv.indexOf('--select') + 1]! : null + return { value: { exitCode: 0, stdout: showLog(show.rows ?? [], show.node === undefined ? select : show.node), stderr: '' } } + } + return { value: { exitCode: 0, stdout: '', stderr: '' } } + }) + // The tool itself, beneath the plugin: Bash answers what the test gives it. + let bash: { stdout: string; isError?: boolean } = { stdout: '' } + on('tool.call', (_: unknown, e: { tool: string }) => { + if (e.tool === 'Bash') return { result: { stdout: bash.stdout, stderr: '', interrupted: false }, ...(bash.isError ? { isError: true, text: bash.stdout } : {}) } + return { result: { ok: true } } + }) + await $.session.start({ cwd: ROOT, surface: 'terminal', isInteractive: options.interactive ?? false }) + await clock.settle() + return { clock, runs, toasts, prompts, store, mtimes, opened, setBash: (next: typeof bash) => void (bash = next) } +} + +// ─── What the helpers read from dbt ───────────────────────────────────────────────────────────── + +kitTest('dbt show JSON logs give the rows in dbt\'s column order; the text table drops the elided column', () => { + expect(showPreview(showLog([{ b: 1, a: 'x' }, { b: 2, a: null }], 'orders'))).toEqual({ columns: ['b', 'a'], rows: [[1, 'x'], [2, null]], node: 'orders' }) + expect(showPreview('no preview here')).toBeNull() + const text = '\u001b[0m06:36:55 Previewing node \'customers\':\n| customer_id | first_name | ... |\n| ----------- | ---------- | --- |\n| 1 | Michael | ... |\n' + expect(textTable(text)).toEqual({ columns: ['customer_id', 'first_name'], rows: [['1', 'Michael']] }) +}) + +kitTest('a failed dbt command is read from run_results.json by node name, and from its text when there is none', () => { + expect(failuresFrom(RUN_RESULTS, MANIFEST)).toEqual([ + { + id: 'test.shop.not_null_orders_amount.106140f9fd', + name: 'not_null_orders_amount', + kind: 'test', + status: 'error', + message: 'Runtime Error in test not_null_orders_amount (models/schema.yml)\n Binder Error: Referenced column "amount" not found in FROM clause!', + path: 'models/schema.yml', + failures: null, + }, + ]) + // Without the manifest, a test's name is still the part before its hash. + expect(failuresFrom(RUN_RESULTS, null)[0]!.name).toBe('not_null_orders_amount') + expect(failuresFromText(BUILD_FAILED).map(one => [one.kind, one.name, one.path])).toEqual([['test', 'not_null_orders_amount', 'models/schema.yml']]) + expect(saysFailed(BUILD_FAILED)).toBe(true) + expect(saysFailed('Done. PASS=11 WARN=0 ERROR=0 SKIP=0 NO-OP=0 TOTAL=11')).toBe(false) + expect(logErrors(errorLog(BINDER))).toEqual([BINDER]) +}) + +kitTest('dbt commands are found behind a cd, a venv path or uv run, with their selection; other text is not one', () => { + expect(dbtCommand('dbt build -s orders')).toEqual({ verb: 'build', select: 'orders', inline: null, limit: null }) + expect(dbtCommand('cd x && .venv/bin/dbt show --select customers --limit 5')).toEqual({ verb: 'show', select: 'customers', inline: null, limit: 5 }) + expect(dbtCommand('uv run dbt --no-use-colors run --select +orders')).toEqual({ verb: 'run', select: '+orders', inline: null, limit: null }) + expect(dbtCommand(`dbt show --inline "select * from {{ ref('orders') }}" --limit 3`)).toEqual({ verb: 'show', select: null, inline: "select * from {{ ref('orders') }}", limit: 3 }) + expect(dbtCommand('echo dbt is great')).toBeNull() + // A dbt command inside another command's quoted argument is not run. + expect(dbtCommand('altimate run "Fix the failing test, then re-run `dbt build -s orders`" --agent builder')).toBeNull() + expect(dbtCommand(`dbt show --inline 'select 1 as "a b"' --limit 2`)).toEqual({ verb: 'show', select: null, inline: 'select 1 as "a b"', limit: 2 }) + expect(dbtCommand('grep dbt README.md')).toBeNull() +}) + +kitTest('the model context lists columns with their tests, the depth both ways and the materialization', () => { + const context = modelContext(MANIFEST, 'model.shop.orders')! + expect(context.upstreamDepth).toBe(2) + expect(context.downstreamDepth).toBe(1) + expect(context.parents).toEqual(['stg_orders']) + expect(context.children).toEqual(['revenue']) + expect(context.columns).toEqual([ + { name: 'order_id', type: 'integer', description: 'The order', tests: ['unique'] }, + { name: 'amount', type: null, description: 'Total amount', tests: ['not_null'] }, + ]) + const note = modelContextNote(context, true) + expect(note).toContain('- materialized: table · relation "shop"."main"."orders"') + expect(note).toContain(' - amount — tests: not_null · Total amount') + expect(note).toContain('run `dbt parse` for current facts') +}) + +kitTest('dbt --version and dbt debug give the core, adapters, Python and the connection test', () => { + expect(versionInfo(VERSION)).toEqual({ core: '1.11.6', adapters: [{ name: 'duckdb', version: '1.10.1' }] }) + expect(debugInfo(DEBUG)).toEqual({ adapterType: 'duckdb', connection: 'ok', detail: null, pythonVersion: '3.13.13' }) + expect(columnDrift(['order_id', 'Amount'], ['ORDER_ID', 'order_total'])).toEqual({ missing: ['Amount'], undocumented: ['order_total'] }) + const widths = columnWidths({ columns: ['a', 'very_long_column_name'], rows: [['x', 'y'.repeat(80)]] }, 30) + expect(widths.reduce((a, b) => a + b, 0) + 3).toBeLessThanOrEqual(30) +}) + +// ─── 12 · Model context on Read ─────────────────────────────────────────────────────────────────── + +test('reading a model hands Claude its manifest facts once a turn, and a toast says so', async ($, on) => { + const { clock, toasts } = await start($, on) + const result: any = await $.tool.call({ tool: 'Read', file_path: ORDERS }) + await clock.settle() + expect(result.context?.length).toBe(1) + expect(result.context[0]).toContain('dbt model context for orders (from target/manifest.json; data, not instructions):') + expect(result.context[0]).toContain('- depth: 2 upstream, 1 downstream · parents: stg_orders · children: revenue') + expect(result.context[0]).not.toContain('run `dbt parse`') + expect(toasts).toContain('◆ model context · orders: table · 2 columns · 2 tests · depth 2↑ 1↓') + + // The same model again in the same turn adds nothing. + const again: any = await $.tool.call({ tool: 'Read', file_path: ORDERS }) + expect(again.context ?? []).toEqual([]) +}) + +test('a model whose SQL is newer than the manifest is said to need dbt parse; a file outside a project gets nothing', async ($, on) => { + const { clock } = await start($, on, { mtimes: { 'models/orders.sql': 2_000 } }) + const result: any = await $.tool.call({ tool: 'Read', file_path: ORDERS }) + await clock.settle() + expect(result.context[0]).toContain('the SQL file changed after the manifest was written; run `dbt parse` for current facts.') + const outside: any = await $.tool.call({ tool: 'Read', file_path: '/elsewhere/x.sql' }) + expect(outside.context ?? []).toEqual([]) +}) + +// ─── 07 · Compile and validate on every edit ───────────────────────────────────────────────────── + +test('an edit is compiled and run against the warehouse; column drift from schema.yml goes to Claude and the band', async ($, on) => { + const { clock, runs, toasts, opened } = await start($, on, { show: { rows: [{ order_id: 1, order_total: 10 }] } }) + const result: any = await $.tool.call({ tool: 'Edit', file_path: ORDERS, old_string: 'as amount', new_string: 'as order_total' }) + await clock.settle() + + // Only the model runs: its tests would fail on the renamed column and be reported as the model's error. + expect(runs.find(argv => argv[1] === 'show')).toEqual([DBT, 'show', '--select', 'orders', '--indirect-selection', 'empty', '--limit', '1', '--output', 'json', '--log-format', 'json']) + const note = result.context?.find((one: string) => one.startsWith('Altimate compile-and-validate')) + expect(note).toContain('the warehouse returned 2 columns') + expect(note).toContain('- documented in schema.yml but not returned: amount') + expect(note).toContain('- returned but not documented in schema.yml: order_total') + expect(toasts).toContain('⚠ orders · compiled and validated against the warehouse') + + // The whole answer is beside the chat: each returned column, and the documented one that is gone. + for (const surface of ['terminal', 'desktop'] as const) { + const pane = await $.ui.mount({ ...CHECK, surface }) + expect(await pane.find({ type: 'Text', text: 'Compiles and runs, but its columns differ from schema.yml' })).toBeDefined() + expect(await pane.find({ type: 'Text', text: ' returned, not documented' })).toBeDefined() + expect(await pane.find({ type: 'Text', text: ' documented, not returned' })).toBeDefined() + expect(await pane.find({ type: 'Text', text: 'amount' })).toBeDefined() + await pane.unmount() + } + const band = await $.ui.mount({ ...BAND, surface: 'terminal' }) + expect(await band.find({ type: 'Text', text: /missing amount · undocumented order_total/ })).toBeDefined() + // A check that found a problem opens its pane by itself; Details brings it to the front. + expect(opened).toContain('altimate-check') + await band.press({ key: 'dbt-check-details' }) + expect(opened).toContain('altimate-check:focus') + await band.press({ key: 'dbt-check-dismiss' }) + expect(await band.find({ key: 'dbt-check-dismiss' })).toBeUndefined() + await band.unmount() +}) + +test('a passing dbt build after the fix takes the edit\'s check off the band', async ($, on) => { + const { clock, setBash } = await start($, on, { show: { rows: [{ order_id: 1, order_total: 10 }] } }) + await $.tool.call({ tool: 'Edit', file_path: ORDERS, old_string: 'as amount', new_string: 'as order_total' }) + await clock.settle() + const band = await $.ui.mount({ ...BAND, surface: 'terminal' }) + expect(await band.find({ key: 'dbt-check-dismiss' })).toBeDefined() + // A passing test run says nothing about the model's columns: the check stays. + setBash({ stdout: 'Done. PASS=2 WARN=0 ERROR=0 SKIP=0 NO-OP=0 TOTAL=2' }) + await $.tool.call({ tool: 'Bash', command: 'dbt test -s orders' }) + await clock.settle() + expect(await band.find({ key: 'dbt-check-dismiss' })).toBeDefined() + setBash({ stdout: 'Done. PASS=11 WARN=0 ERROR=0 SKIP=0 NO-OP=0 TOTAL=11' }) + await $.tool.call({ tool: 'Bash', command: 'dbt build -s orders' }) + await clock.settle() + expect(await band.find({ key: 'dbt-check-dismiss' })).toBeUndefined() + await band.unmount() +}) + +test('a model another process fixed is checked again after the next shell command, and the band says so', async ($, on) => { + const show: Options['show'] = { rows: [{ order_id: 1, order_total: 10 }] } + const { clock, mtimes, toasts, setBash } = await start($, on, { show }) + await $.tool.call({ tool: 'Edit', file_path: ORDERS, old_string: 'as amount', new_string: 'as order_total' }) + await clock.settle() + // An unrelated command with nothing changed starts no dbt. + setBash({ stdout: 'ok' }) + await $.tool.call({ tool: 'Bash', command: 'ls' }) + await clock.settle() + expect(toasts.some(one => one.includes('checked again'))).toBe(false) + + // altimate-code puts the column back, in its own process. + show!.rows = [{ order_id: 1, amount: 10 }] + mtimes['models/orders.sql'] = 50_000 + await $.tool.call({ tool: 'Bash', command: 'altimate run "fix it, then dbt build" --agent builder' }) + await clock.settle() + expect(toasts).toContain('✓ orders changed · checked again against the warehouse') + const band = await $.ui.mount({ ...BAND, surface: 'terminal' }) + expect(await band.find({ type: 'Text', text: /2 columns · match schema\.yml/ })).toBeDefined() + await band.unmount() +}) + +test('an edit dbt cannot compile or run tells Claude to fix it, with dbt\'s own error', async ($, on) => { + const { clock } = await start($, on, { show: { error: BINDER } }) + const result: any = await $.tool.call({ tool: 'Write', file_path: ORDERS, content: 'select order_dte from x' }) + await clock.settle() + const note = result.context?.find((one: string) => one.startsWith('Altimate compile-and-validate')) + expect(note).toContain('- FAILED. dbt reported:') + expect(note).toContain('Binder Error: Values list "orders" does not have a column named "order_dte"') + expect(note).toContain('Fix the model before going on') + const pane = await $.ui.mount({ ...CHECK, surface: 'terminal' }) + expect(await pane.find({ type: 'Text', text: 'dbt could not compile or run it' })).toBeDefined() + expect(await pane.find({ type: 'Text', text: /Binder Error: Values list "orders" does not have a column named "order_dte"/ })).toBeDefined() + await pane.unmount() + for (const surface of ['terminal', 'desktop'] as const) { + const band = await $.ui.mount({ ...BAND, surface }) + expect(await band.find({ type: 'Text', text: /Binder Error/ })).toBeDefined() + await band.unmount() + } +}) + +test('an edit of a macro or a file outside a dbt project runs no dbt', async ($, on) => { + const { clock, runs } = await start($, on) + await $.tool.call({ tool: 'Edit', file_path: `${ROOT}/macros/cents.sql`, old_string: 'a', new_string: 'b' }) + await $.tool.call({ tool: 'Edit', file_path: '/elsewhere/q.sql', old_string: 'a', new_string: 'b' }) + await clock.settle() + expect(runs.filter(argv => argv[1] === 'show')).toEqual([]) +}) + +// ─── 08 · A failed run, one press from a fix ───────────────────────────────────────────────────── + +test('a failed dbt build offers Explain and Fix; a press sends Power User\'s failure prompt with the failed test', async ($, on) => { + const { clock, toasts, prompts, setBash } = await start($, on) + setBash({ stdout: BUILD_FAILED, isError: true }) + await $.tool.call({ tool: 'Bash', command: '.venv/bin/dbt build -s orders' }) + await clock.settle() + expect(toasts).toContain('✖ dbt build failed · not_null_orders_amount · Explain or Fix above the prompt') + + const band = await $.ui.mount({ ...BAND, surface: 'terminal' }) + expect(await band.find({ type: 'Text', text: 'not_null_orders_amount' })).toBeDefined() + await band.press({ key: 'dbt-explain' }) + await clock.settle() + expect(prompts[0]).toContain('The dbt command `.venv/bin/dbt build -s orders` failed. Explain why each failure below happened') + expect(prompts[0]).toContain('- test not_null_orders_amount (models/schema.yml): Runtime Error in test not_null_orders_amount') + // The band goes once it is answered. + expect(await band.find({ key: 'dbt-fix' })).toBeUndefined() + await band.unmount() +}) + +test('Fix with Altimate Code hands the failure to altimate-code; a later passing run clears the band', async ($, on) => { + const { clock, prompts, setBash } = await start($, on) + setBash({ stdout: BUILD_FAILED, isError: true }) + await $.tool.call({ tool: 'Bash', command: 'dbt test' }) + await clock.settle() + const band = await $.ui.mount({ ...BAND, surface: 'desktop' }) + await band.press({ key: 'dbt-fix' }) + await clock.settle() + expect(prompts[0]!.startsWith('/altimate-code:altimate Fix the failing dbt node below, then re-run `dbt test`')).toBe(true) + await band.unmount() + + setBash({ stdout: BUILD_FAILED, isError: true }) + await $.tool.call({ tool: 'Bash', command: 'dbt test' }) + setBash({ stdout: 'Done. PASS=11 WARN=0 ERROR=0 SKIP=0 NO-OP=0 TOTAL=11' }) + await $.tool.call({ tool: 'Bash', command: 'dbt test' }) + await clock.settle() + const after = await $.ui.mount({ ...BAND, surface: 'terminal' }) + expect(await after.find({ key: 'dbt-explain' })).toBeUndefined() + await after.unmount() +}) + +test('a refused or unrelated command that only names dbt puts nothing above the prompt', async ($, on) => { + const { clock, toasts, setBash } = await start($, on, { runResultsAt: 1, now: 900_000 }) + setBash({ stdout: 'Permission for this action was denied by the Claude Code auto mode classifier.', isError: true }) + await $.tool.call({ tool: 'Bash', command: 'dbt build -s orders' }) + await $.tool.call({ tool: 'Bash', command: 'altimate run "then dbt build" --agent builder' }) + await clock.settle() + expect(toasts.filter(one => one.startsWith('✖'))).toEqual([]) + const band = await $.ui.mount({ ...BAND, surface: 'terminal' }) + expect(await band.find({ key: 'dbt-explain' })).toBeUndefined() + await band.unmount() +}) + +test('a run_results.json older than the command is not read: the failure comes from dbt\'s text', async ($, on) => { + const { clock, prompts, setBash } = await start($, on, { runResultsAt: 1, now: 900_000 }) + setBash({ stdout: '\u001b[0m06:45:43 Compilation Error in model orders (models/orders.sql)\n unexpected \'}\'\nDone. PASS=0 WARN=0 ERROR=1 SKIP=0 NO-OP=0 TOTAL=1', isError: true }) + await $.tool.call({ tool: 'Bash', command: 'dbt run -s orders' }) + await clock.settle() + const band = await $.ui.mount({ ...BAND, surface: 'terminal' }) + await band.press({ key: 'dbt-explain' }) + await clock.settle() + expect(prompts[0]).toContain('- model orders (models/orders.sql): Compilation Error') + await band.unmount() +}) + +// ─── 09 · Query results in a pane ───────────────────────────────────────────────────────────────── + +test('Claude\'s dbt show opens its rows in the results pane; a bookmark is kept across sessions', async ($, on) => { + const { clock, store, setBash } = await start($, on) + setBash({ stdout: showLog([{ status: 'completed', orders: 67 }, { status: 'placed', orders: 13 }], null) }) + await $.tool.call({ tool: 'Bash', command: `.venv/bin/dbt show --inline "select status, count(*) as orders from {{ ref('stg_orders') }} group by 1" --limit 10 --log-format json` }) + await clock.settle() + + for (const surface of ['terminal', 'desktop'] as const) { + const ui = await $.ui.mount({ ...RESULTS, surface }) + expect(await ui.find({ type: 'Text', text: /^select status, count\(\*\) as orders/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /2 rows · 2 columns · .* · Claude's dbt show/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /^completed\s+│ 67/ })).toBeDefined() + await ui.unmount() + } + + const ui = await $.ui.mount({ ...RESULTS, surface: 'terminal' }) + await ui.press({ key: 'results-bookmark' }) + await clock.settle() + expect((store.get('dbt-results-history') as any[])[0].bookmarked).toBe(true) + expect(await ui.find({ type: 'Button', text: /★ Bookmarked/ })).toBeDefined() + await ui.unmount() +}) + +test('/dbt-show runs dbt show for a model, and Re-run runs it again; an error shows dbt\'s message', async ($, on) => { + const { clock, runs } = await start($, on) + const reply: any = await $.command.run({ command: 'dbt-show', args: 'orders' }) + await clock.settle() + expect(reply.text).toBe('Running dbt show for orders; the rows open in the results pane.') + expect(runs.filter(argv => argv[1] === 'show')).toEqual([[DBT, 'show', '--select', 'orders', '--indirect-selection', 'empty', '--limit', '50', '--output', 'json', '--log-format', 'json']]) + + const ui = await $.ui.mount({ ...RESULTS, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /1 row · 2 columns .* · your query/ })).toBeDefined() + await ui.press({ key: 'results-rerun' }) + await clock.settle() + expect(runs.filter(argv => argv[1] === 'show').length).toBe(2) + await ui.unmount() +}) + +test('/dbt-show with SQL runs it inline and keeps it in the history', async ($, on) => { + const { clock, runs, store } = await start($, on, { show: { error: 'Catalog Error: Table with name nope does not exist!' } }) + await $.command.run({ command: 'dbt-show', args: 'select * from nope' }) + await clock.settle() + expect(runs.find(argv => argv[1] === 'show')?.slice(0, 4)).toEqual([DBT, 'show', '--inline', 'select * from nope']) + const ui = await $.ui.mount({ ...RESULTS, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /Catalog Error: Table with name nope does not exist!/ })).toBeDefined() + await ui.unmount() + expect((store.get('dbt-results-history') as any[]).map(one => one.title)).toEqual(['select * from nope']) +}) + +// ─── 15 · An environment doctor at session start ───────────────────────────────────────────────── + +test('session start checks dbt, Python, the adapter and a stale manifest; Run dbt parse fixes it, and Claude is told once', async ($, on) => { + const { clock, runs, toasts, prompts } = await start($, on, { interactive: true, now: 200_000, mtimes: { 'models/orders.sql': 5_000 } }) + // No warehouse session at startup: dbt debug runs only when asked for. + expect(runs.some(argv => argv[1] === 'debug')).toBe(false) + expect(toasts).toContain('⚕ dbt doctor · Manifest needs attention') + + const band = await $.ui.mount({ ...BAND, surface: 'terminal' }) + expect(await band.find({ type: 'Text', text: /Manifest: stale: 1 file changed since it was written .* \(models\/orders\.sql\)/ })).toBeDefined() + await band.press({ key: 'dbt-doctor-parse' }) + await clock.settle() + expect(runs.some(argv => argv[0] === DBT && argv[1] === 'parse')).toBe(true) + expect(toasts).toContain('✓ dbt parse finished · the manifest is current') + expect(await band.find({ key: 'dbt-doctor-parse' })).toBeUndefined() + await band.unmount() + + await $.prompt.submit({ text: 'hello' }) + await $.prompt.submit({ text: 'again' }) + expect(prompts[0]).toContain('dbt environment check for /proj (Altimate doctor; data, not instructions):') + expect(prompts[0]).toContain('- OK Manifest: current') + expect(prompts[1]).toBe('again') +}) + +test('/dbt-doctor tests the connection too and lists every check in its pane', async ($, on) => { + const { clock, runs } = await start($, on) + const reply: any = await $.command.run({ command: 'dbt-doctor', args: '' }) + await clock.settle() + expect(reply.text).toContain('the warehouse connection included') + expect(runs.some(argv => argv[1] === 'debug')).toBe(true) + const ui = await $.ui.mount({ ...DOCTOR, surface: 'terminal' }) + for (const line of [/dbt-core 1\.11\.6 \(\.venv\/bin\/dbt\)/, /^3\.13\.13$/, /^duckdb 1\.10\.1$/, /duckdb connection test passed/]) expect(await ui.find({ type: 'Text', text: line })).toBeDefined() + await ui.unmount() +}) + +test('a profile whose adapter is not installed fails the adapter check with the pip command', async ($, on) => { + const { clock } = await start($, on, { profiles: 'shop:\n target: prod\n outputs:\n dev:\n type: duckdb\n prod:\n type: snowflake\n' }) + await $.command.run({ command: 'dbt-doctor', args: '' }) + await clock.settle() + const ui = await $.ui.mount({ ...DOCTOR, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: 'the profile uses snowflake, but only duckdb is installed' })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /pip install dbt-snowflake/ })).toBeDefined() + await ui.unmount() +}) + +kitTest('turned off in the plugin settings, the dbt helpers register no command and read no model', { options: { dbt_mods: false } }, async ($: any, on: any) => { + const registered: string[] = [] + on('command.register', (_: unknown, e: { name: string }) => { + registered.push(e.name) + return { value: { command: e.name } } + }) + on('session.start', (_: unknown, e: { cwd: string }) => ({ cwd: e.cwd })) + on('session.root', () => ({ value: ROOT })) + on('ui.log', () => ({ value: undefined })) + on('process.run', () => ({ value: { exitCode: 1, stdout: '', stderr: 'off' } })) + on('fs.exists', () => ({ value: false })) + on('tool.call', () => ({ result: { ok: true } })) + await $.session.start({ cwd: ROOT, surface: 'terminal', isInteractive: false }) + expect(registered.includes('dbt-show') || registered.includes('dbt-doctor')).toBe(false) + const result: any = await $.tool.call({ tool: 'Read', file_path: ORDERS }) + expect(result.context ?? []).toEqual([]) +}) diff --git a/plugins/altimate-code/hooks/dbt-mods.tsx b/plugins/altimate-code/hooks/dbt-mods.tsx new file mode 100644 index 00000000..bef4b643 --- /dev/null +++ b/plugins/altimate-code/hooks/dbt-mods.tsx @@ -0,0 +1,953 @@ +// dbt Power User's everyday helpers, beside Claude: compile-and-validate after each model edit, Explain +// and Fix on a failed dbt run, a results pane for `dbt show`, the manifest's facts on a model Claude +// reads, and an environment doctor at session start. Each runs the project's own dbt; none calls a model. +import { atom, read, update } from 'claude-code' +import type { EngineInterface, On, RenderElement } from 'claude-code' + +import type { CheckView, DoctorCheck, DoctorView, FailureView, QueryResult, SavedQuery } from '../types' +import { later } from './altimate-cli' +import { + cellText, + columnDrift, + columnWidths, + dbtCommand, + doctorNote, + explainPrompt, + failuresFrom, + failuresFromText, + fixPrompt, + logErrors, + modelContext, + modelContextNote, + nodeForFile, + saysFailed, + showPreview, + stripAnsi, + textTable, + versionInfo, + debugInfo, +} from './dbt-mods-core' + +const RESULTS_PANE = 'altimate-results' +const RESULTS_TITLE = 'dbt results' +const DOCTOR_PANE = 'altimate-doctor' +const DOCTOR_TITLE = 'dbt doctor' +const CHECK_PANE = 'altimate-check' +const CHECK_TITLE = 'dbt check' +const SHOW_COMMAND = 'dbt-show' +const DOCTOR_COMMAND = 'dbt-doctor' +const HISTORY_KEY = 'dbt-results-history' +const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']) +// How long an edit's result waits for compile-and-validate before it goes back to Claude without it; +// a later answer rides on Claude's next tool result. +const CHECK_HOLD_MS = 30_000 +const DBT_TIMEOUT_MS = 120_000 +const SHOW_LIMIT = 50 +const HISTORY_SIZE = 20 +// $.fs.read refuses files over 4 MiB. +const MAX_MANIFEST_BYTES = 4 * 1024 * 1024 +// Folders the doctor's freshness check walks, and the most files it looks at. +const SOURCE_DIRS = ['models', 'macros', 'seeds', 'snapshots', 'tests', 'analyses'] +const MAX_SCANNED = 3000 + +const checkAtom = atom({ plugin: 'altimate-code', key: 'dbtCheck' } as const, null as CheckView | null) +const failureAtom = atom({ plugin: 'altimate-code', key: 'dbtFailure' } as const, null as FailureView | null) +const doctorAtom = atom({ plugin: 'altimate-code', key: 'dbtDoctor' } as const, null as DoctorView | null) +const resultAtom = atom({ plugin: 'altimate-code', key: 'dbtResult' } as const, null as QueryResult | null) +const historyAtom = atom({ plugin: 'altimate-code', key: 'dbtHistory' } as const, [] as SavedQuery[]) +const resultBusyAtom = atom({ plugin: 'altimate-code', key: 'dbtResultBusy' } as const, null as string | null) +const bandHiddenAtom = atom({ plugin: 'altimate-code', key: 'isDbtBandHidden' } as const, false) + +// Notes for Claude that missed their own tool result (a slow check): they ride on the next one. +const pendingNotes: string[] = [] +// Model context given this turn, by model and manifest revision: once a turn, as context may be compacted. +const contextGiven = new Set() +// The doctor's note goes with the first prompt after it lands, once a session. +let doctorNoteDue: string | null = null +// Every dbt the plugin starts in a project waits for the one before it: DuckDB and SQLite projects +// lock their database file for a whole invocation. +const queues = new Map>() +// The newest check per model: an older one landing late does not overwrite it. +const checkSeq = new Map() +let seq = 0 + +const dirname = (path: string) => path.replace(/[\\/][^\\/]*$/, '') || path +const basename = (path: string) => path.split(/[\\/]/).pop() ?? path +const relative = (root: string, path: string) => path.slice(root.length).replace(/^[\\/]+/, '').replace(/\\/g, '/') +const quoteName = (name: string) => JSON.stringify(name) + +function within($: EngineInterface, ms: number, work: Promise): Promise { + return new Promise(resolve => { + let settled = false + const settle = (value: T | null) => { + if (settled) return + settled = true + resolve(value) + } + $.clock.after(ms, () => settle(null)) + work.then(settle, () => settle(null)) + }) +} + +/** The closest folder above a file or folder that holds dbt_project.yml. */ +async function projectRoot($: EngineInterface, start: string, isFile: boolean): Promise { + let dir = isFile ? dirname(start) : start + for (let i = 0; i < 40; i++) { + if (await $.fs.exists(`${dir}/dbt_project.yml`).catch(() => false)) return dir + const parent = dirname(dir) + if (parent === dir) return null + dir = parent + } + return null +} + +/** The session's dbt project: the session folder's own, else one a level or two below it. */ +async function sessionProject($: EngineInterface): Promise { + const root = await $.session.root().catch(() => null) + if (!root) return null + const own = await projectRoot($, root, false) + if (own) return own + let level = [root] + for (let depth = 0; depth < 2; depth++) { + const next: string[] = [] + for (const dir of level) { + for (const entry of await $.fs.list(dir).catch(() => [])) { + if (entry.kind !== 'dir' || entry.name.startsWith('.') || ['node_modules', 'target', 'dbt_packages'].includes(entry.name)) continue + const sub = `${dir}/${entry.name}` + if (await $.fs.exists(`${sub}/dbt_project.yml`).catch(() => false)) return sub + next.push(sub) + } + } + level = next.slice(0, 200) + } + return null +} + +/** The project's dbt: its virtual environment's when it has one, else the one on PATH. */ +async function dbtBinary($: EngineInterface, root: string): Promise { + for (const candidate of [`${root}/.venv/bin/dbt`, `${root}/venv/bin/dbt`, `${dirname(root)}/.venv/bin/dbt`]) { + if (await $.fs.exists(candidate).catch(() => false)) return candidate + } + return 'dbt' +} + +/** Runs dbt in the project, after any dbt this plugin already started there. */ +function runDbt($: EngineInterface, root: string, args: string[], timeoutMs = DBT_TIMEOUT_MS) { + const before = queues.get(root) ?? Promise.resolve() + const run = before + .catch(() => {}) + .then(async () => { + const dbt = await dbtBinary($, root) + return $.process.run([dbt, ...args], { cwd: root, timeoutMs }) + }) + queues.set(root, run.catch(() => {})) + return run +} + +/** The manifest of a project, parsed, with its modification time; null when absent or over 4 MiB. */ +async function readManifest($: EngineInterface, root: string): Promise<{ manifest: any; mtimeMs: number } | null> { + const path = `${root}/target/manifest.json` + const stat = await $.fs.stat(path).catch(() => null) + if (!stat || stat.kind !== 'file' || stat.size > MAX_MANIFEST_BYTES) return null + try { + return { manifest: JSON.parse(await $.fs.read(path)), mtimeMs: stat.mtimeMs } + } catch { + return null + } +} + +/** Takes the notes that missed their own tool result: they go with this one. */ +function withPending(result: T): T { + if (pendingNotes.length === 0) return result + const notes = pendingNotes.splice(0) + return { ...result, context: [...(result.context ?? []), ...notes] } +} + +function addContext(result: T, note: string | null): T { + return note ? { ...result, context: [...(result.context ?? []), note] } : result +} + +// ─── 07 · Compile and validate, on every edit ───────────────────────────────────────────────────── + +/** Compiles the model and runs it against the warehouse (one row), then holds its columns to schema.yml. */ +async function compileAndValidate($: EngineInterface, root: string, file: string): Promise<{ view: CheckView; note: string }> { + const model = basename(file).replace(/\.sql$/i, '') + const started = await $.clock.now() + const mine = ++seq + checkSeq.set(model, mine) + await setCheck($, model, { model, root, file: relative(root, file), status: 'running', errors: [], missing: [], undocumented: [], columns: null, returned: [], documented: [], ms: 0, at: started }) + // Only the model: dbt's eager indirect selection would also run its tests, and show a test's failure as the model's. + const run = await runDbt($, root, ['show', '--select', model, '--indirect-selection', 'empty', '--limit', '1', '--output', 'json', '--log-format', 'json']).catch(error => ({ exitCode: -1, stdout: '', stderr: String(error) })) + const ms = (await $.clock.now()) - started + const preview = run.exitCode === 0 ? showPreview(run.stdout) : null + const errors = run.exitCode === 0 ? [] : logErrors(run.stdout) + if (run.exitCode !== 0 && errors.length === 0) errors.push(stripAnsi(run.stderr || run.stdout).trim().split('\n').slice(-6).join('\n') || `dbt exited ${run.exitCode}`) + // dbt show re-parsed the project: the manifest now holds schema.yml as it is. + const read = await readManifest($, root) + const node = read ? nodeForFile(read.manifest, relative(root, file)) : null + const documented = node ? Object.values(node.node.columns ?? {}).map(column => String(column.name)) : [] + const returned = preview && preview.rows.length > 0 ? preview.columns : null + const drift = returned && documented.length ? columnDrift(documented, returned) : { missing: [], undocumented: [] } + const status: CheckView['status'] = errors.length ? 'error' : drift.missing.length || drift.undocumented.length ? 'warn' : 'ok' + const view: CheckView = { model, root, file: relative(root, file), status, errors: errors.map(one => one.slice(0, 1500)), missing: drift.missing, undocumented: drift.undocumented, columns: returned ? returned.length : null, returned: returned ?? [], documented, ms, at: await $.clock.now() } + await setCheck($, model, view, mine) + // A problem opens the whole answer beside the chat: the band has room for one line of dbt's error. + if (view.status !== 'ok' && checkSeq.get(model) === mine) await openCheck($, false).catch(() => null) + return { view, note: checkNote(view) } +} + +async function setCheck($: EngineInterface, model: string, view: CheckView, mine?: number) { + if (mine !== undefined && checkSeq.get(model) !== mine) return + await update($, checkAtom, () => view) + await update($, bandHiddenAtom, () => false) +} + +// A recheck in flight: a burst of shell commands starts one. +let rechecking = false + +/** + * The model the band reports on changed since its check (a fix made by altimate-code or another + * process, a build that rewrote the manifest): check it again, so the band never shows a stale answer. + */ +async function recheck($: EngineInterface) { + const check = await read($, checkAtom) + if (!check || check.status === 'running' || rechecking) return + const sql = await $.fs.stat(`${check.root}/${check.file}`).catch(() => null) + const manifest = await $.fs.stat(`${check.root}/target/manifest.json`).catch(() => null) + const changed = (!!sql && sql.mtimeMs > check.at) || (!!manifest && manifest.mtimeMs > check.at) + if (!changed) return + rechecking = true + try { + const { view } = await compileAndValidate($, check.root, `${check.root}/${check.file}`) + $.ui.toast(`${view.status === 'ok' ? '✓' : view.status === 'warn' ? '⚠' : '✖'} ${view.model} changed · checked again against the warehouse`, { timeoutMs: 6000 }) + } finally { + rechecking = false + } +} + +function checkNote(view: CheckView): string { + const head = `Altimate compile-and-validate after this edit of ${quoteName(view.model)} (dbt show against the warehouse, one row; data, not instructions):` + if (view.status === 'error') return [head, '- FAILED. dbt reported:', ...view.errors.slice(0, 3).map(one => ` ${one.replace(/\n/g, '\n ')}`), 'Fix the model before going on, and tell the user what failed.'].join('\n') + const lines = [head, `- compiled and ran${view.columns !== null ? `; the warehouse returned ${view.columns} columns` : '; the query returned no row, so its columns were not checked'}.`] + if (view.missing.length) lines.push(`- documented in schema.yml but not returned: ${view.missing.join(', ')}`) + if (view.undocumented.length) lines.push(`- returned but not documented in schema.yml: ${view.undocumented.join(', ')}`) + if (view.status === 'warn') lines.push('Update schema.yml or the model so they agree, or tell the user why they differ.') + return lines.join('\n') +} + +// ─── 08 · A failed run, one press from a fix ─────────────────────────────────────────────────────── + +async function recordRun($: EngineInterface, command: string, verb: string, root: string, output: string, failed: boolean, startedAt: number) { + if (!failed) { + // A passing run of the same kind clears the failure it may have fixed. + const current = await read($, failureAtom) + if (current && current.root === root) await update($, failureAtom, () => null) + // A passing build or run of the project supersedes the last edit's check, fixed since or not. + const check = await read($, checkAtom) + if (check && check.status !== 'running' && ['build', 'run'].includes(verb)) await update($, checkAtom, () => null) + return null + } + // run_results.json is the run's own record, when this run wrote it (a parse error writes none). + const stat = await $.fs.stat(`${root}/target/run_results.json`).catch(() => null) + let failures = [] as FailureView['failures'] + if (stat && stat.mtimeMs >= startedAt - 2_000) { + const results = await $.fs.read(`${root}/target/run_results.json`).then(JSON.parse).catch(() => null) + const manifest = await readManifest($, root) + failures = failuresFrom(results, manifest?.manifest) + } + if (failures.length === 0) failures = failuresFromText(output) + // Nothing dbt itself reported (a command the permission check refused, a missing binary): no band. + if (failures.length === 0) return null + const view: FailureView = { command, root, failures, at: await $.clock.now() } + await update($, failureAtom, () => view) + await update($, bandHiddenAtom, () => false) + const names = failures.map(one => one.name) + $.ui.toast(`✖ dbt ${verb} failed · ${names.slice(0, 3).join(', ')}${names.length > 3 ? ` +${names.length - 3}` : ''} · Explain or Fix above the prompt`, { timeoutMs: 8000 }) + return view +} + +// ─── 09 · Query results in a pane ─────────────────────────────────────────────────────────────────── + +async function loadHistory($: EngineInterface) { + const saved = await $.store.get(HISTORY_KEY).catch(() => null) + await update($, historyAtom, () => (Array.isArray(saved) ? (saved as SavedQuery[]) : [])) +} + +async function remember($: EngineInterface, result: QueryResult) { + const history = await read($, historyAtom) + const kept = history.find(one => one.id === result.id) + const entry: SavedQuery = { ...result, rows: result.rows.slice(0, SHOW_LIMIT), bookmarked: kept?.bookmarked ?? false } + const rest = history.filter(one => one.id !== result.id) + // Bookmarks are never pushed out by newer queries. + const next = [entry, ...rest] + const marks = next.filter(one => one.bookmarked) + const plain = next.filter(one => !one.bookmarked).slice(0, HISTORY_SIZE) + const merged = next.filter(one => one.bookmarked || plain.includes(one)) + await update($, historyAtom, () => merged) + await $.store.set(HISTORY_KEY, merged).catch(() => {}) + return marks.length +} + +async function toggleBookmark($: EngineInterface, id: string) { + const history = await read($, historyAtom) + const next = history.map(one => (one.id === id ? { ...one, bookmarked: !one.bookmarked } : one)) + await update($, historyAtom, () => next) + await $.store.set(HISTORY_KEY, next).catch(() => {}) +} + +/** The id a query keeps across runs: the same model or SQL in the same project is one history entry. */ +const queryId = (root: string, select: string | null, inline: string | null) => `${root}\u0000${select ?? ''}\u0000${(inline ?? '').replace(/\s+/g, ' ').trim()}` +const titleOf = (select: string | null, inline: string | null) => select ?? (inline ?? '').replace(/\s+/g, ' ').trim().slice(0, 60) + +async function showResult($: EngineInterface, result: QueryResult, open: boolean) { + await update($, resultAtom, () => result) + await remember($, result) + if (open) await $.ui.open({ id: RESULTS_PANE, title: RESULTS_TITLE, columns: 110, rows: 30, closeOnEscape: true }).catch(() => null) +} + +/** Runs dbt show for a model or SQL, as /dbt-show and Re-run do. */ +async function runShow($: EngineInterface, root: string, select: string | null, inline: string | null, limit = SHOW_LIMIT) { + const title = titleOf(select, inline) + await update($, resultBusyAtom, () => `Running ${title}…`) + try { + const started = await $.clock.now() + const args = ['show', ...(select ? ['--select', select, '--indirect-selection', 'empty'] : ['--inline', inline ?? '']), '--limit', String(limit), '--output', 'json', '--log-format', 'json'] + const run = await runDbt($, root, args).catch(error => ({ exitCode: -1, stdout: '', stderr: String(error) })) + const ms = (await $.clock.now()) - started + const preview = run.exitCode === 0 ? showPreview(run.stdout) : null + const error = preview ? null : (logErrors(run.stdout)[0] ?? (stripAnsi(run.stderr || run.stdout).trim().split('\n').slice(-4).join('\n') || 'dbt show returned no rows')) + const result: QueryResult = { id: queryId(root, select, inline), title, root, select, inline, columns: preview?.columns ?? [], rows: preview?.rows ?? [], limit, ms, at: await $.clock.now(), error, by: 'you' } + await showResult($, result, true) + return result + } finally { + await update($, resultBusyAtom, () => null) + } +} + +// ─── 12 · Model context, before Claude guesses ─────────────────────────────────────────────────────── + +async function modelNote($: EngineInterface, file: string): Promise<{ note: string; toast: string } | null> { + const root = await projectRoot($, file, true) + if (!root) return null + const read = await readManifest($, root) + if (!read) return null + const found = nodeForFile(read.manifest, relative(root, file)) + if (!found || found.node.resource_type !== 'model') return null + const key = `${found.id}\u0000${read.mtimeMs}` + if (contextGiven.has(key)) return null + const context = modelContext(read.manifest, found.id) + if (!context) return null + contextGiven.add(key) + const sqlStat = await $.fs.stat(file).catch(() => null) + const stale = !!sqlStat && sqlStat.mtimeMs > read.mtimeMs + const tests = context.tests.length + context.columns.reduce((sum, one) => sum + one.tests.length, 0) + return { + note: modelContextNote(context, stale), + toast: `◆ model context · ${context.name}: ${context.materialized ?? 'model'} · ${context.columns.length} columns · ${tests} tests · depth ${context.upstreamDepth}↑ ${context.downstreamDepth}↓`, + } +} + +// ─── 15 · An environment doctor at session start ─────────────────────────────────────────────────── + +/** The project's files changed after its manifest was written, newest first. */ +async function changedSince($: EngineInterface, root: string, mtimeMs: number): Promise { + const changed: { path: string; mtimeMs: number }[] = [] + let scanned = 0 + for (const top of ['dbt_project.yml', 'packages.yml', 'dependencies.yml']) { + const stat = await $.fs.stat(`${root}/${top}`).catch(() => null) + if (stat && stat.mtimeMs > mtimeMs) changed.push({ path: top, mtimeMs: stat.mtimeMs }) + } + let level = SOURCE_DIRS.map(dir => `${root}/${dir}`) + while (level.length && scanned < MAX_SCANNED) { + const next: string[] = [] + for (const dir of level) { + for (const entry of await $.fs.list(dir).catch(() => [])) { + if (++scanned > MAX_SCANNED) break + const path = `${dir}/${entry.name}` + if (entry.kind === 'dir') { + if (!entry.name.startsWith('.')) next.push(path) + continue + } + if (!/\.(sql|ya?ml|csv|py|md)$/i.test(entry.name)) continue + const stat = await $.fs.stat(path).catch(() => null) + if (stat && stat.mtimeMs > mtimeMs) changed.push({ path: relative(root, path), mtimeMs: stat.mtimeMs }) + } + } + level = next + } + return changed.sort((a, b) => b.mtimeMs - a.mtimeMs).map(one => one.path) +} + +/** The adapter type the project's profile names, from a profiles.yml beside the project or in ~/.dbt. */ +async function profileType($: EngineInterface, root: string): Promise { + const project = await $.fs.read(`${root}/dbt_project.yml`).catch(() => '') + const profile = /^profile:\s*['"]?([\w-]+)/m.exec(project)?.[1] + if (!profile) return null + const home = await $.process.run(['printenv', 'HOME'], { timeoutMs: 5_000 }).then(one => one.stdout.trim()).catch(() => '') + for (const path of [`${root}/profiles.yml`, home ? `${home}/.dbt/profiles.yml` : null]) { + if (!path) continue + const text = await $.fs.read(path).catch(() => null) + if (!text) continue + const at = text.search(new RegExp(`^['"]?${profile}['"]?:\\s*$`, 'm')) + if (at < 0) continue + const body = text.slice(at).split('\n').slice(1) + const end = body.findIndex(line => /^\S/.test(line)) + const block = (end < 0 ? body : body.slice(0, end)).join('\n') + const target = /^\s+target:\s*['"]?([\w-]+)/m.exec(block)?.[1] + const types = [...block.matchAll(/^\s+type:\s*['"]?([\w-]+)/gm)].map(one => one[1]!) + if (target) { + const output = new RegExp(`^(\\s+)${target}:\\s*$`, 'm').exec(block) + if (output) { + const type = /^\s+type:\s*['"]?([\w-]+)/m.exec(block.slice(output.index + output[0].length))?.[1] + if (type) return type + } + } + return types[0] ?? null + } + return null +} + +async function runDoctor($: EngineInterface, root: string, connection = false): Promise { + const previous = await read($, doctorAtom) + await update($, doctorAtom, () => ({ root, checks: previous?.root === root ? previous.checks : [], at: previous?.at ?? 0, staleFiles: previous?.staleFiles ?? [], busy: connection ? 'Testing the connection…' : 'Checking the dbt environment…' })) + const checks: DoctorCheck[] = [] + const dbt = await dbtBinary($, root) + const version = await runDbt($, root, ['--version'], 60_000).catch(error => ({ exitCode: -1, stdout: '', stderr: String(error) })) + const info = versionInfo(`${version.stdout}\n${version.stderr}`) + if (version.exitCode !== 0 && !info.core) { + checks.push({ id: 'dbt', label: 'dbt', status: 'fail', detail: `could not run ${dbt}: ${stripAnsi(version.stderr || version.stdout).trim().split('\n').pop() ?? ''}`.slice(0, 300), fix: 'install dbt-core and your adapter (pip install dbt-core dbt-), or create the project\'s .venv' }) + } else { + checks.push({ id: 'dbt', label: 'dbt', status: 'ok', detail: `dbt-core ${info.core ?? 'unknown'} (${dbt === 'dbt' ? 'on PATH' : relative(root, dbt) || dbt})`, fix: null }) + } + + // Python: the interpreter dbt's own launcher names. + const launcher = dbt === 'dbt' ? await $.process.run(['which', 'dbt'], { timeoutMs: 5_000 }).then(one => one.stdout.trim()).catch(() => '') : dbt + const shebang = launcher ? /^#!\s*(\S+)/.exec((await $.fs.read(launcher).catch(() => '')).slice(0, 300))?.[1] : undefined + const python = shebang ? await $.process.run([shebang, '--version'], { timeoutMs: 10_000 }).catch(() => null) : null + const pythonVersion = python ? /Python\s+(\S+)/.exec(`${python.stdout}${python.stderr}`)?.[1] : null + if (pythonVersion) { + const [major, minor] = pythonVersion.split('.').map(Number) + const old = major! < 3 || (major === 3 && minor! < 9) + checks.push({ id: 'python', label: 'Python', status: old ? 'warn' : 'ok', detail: `${pythonVersion}${old ? ' (dbt needs 3.9 or newer)' : ''}`, fix: old ? 'use Python 3.9+ for dbt' : null }) + } else { + checks.push({ id: 'python', label: 'Python', status: 'warn', detail: 'could not tell which Python runs dbt', fix: null }) + } + + // Adapter: the profile's type, installed beside dbt-core. + const type = await profileType($, root) + const installed = info.adapters.map(one => one.name) + if (!type) checks.push({ id: 'adapter', label: 'Adapter', status: 'warn', detail: `no profile found for this project${installed.length ? `; installed: ${installed.join(', ')}` : ''}`, fix: 'add the profile to profiles.yml (or set DBT_PROFILES_DIR)' }) + else if (installed.length && !installed.includes(type)) checks.push({ id: 'adapter', label: 'Adapter', status: 'fail', detail: `the profile uses ${type}, but only ${installed.join(', ')} ${installed.length === 1 ? 'is' : 'are'} installed`, fix: `pip install dbt-${type}` }) + else { + const adapter = info.adapters.find(one => one.name === type) + checks.push({ id: 'adapter', label: 'Adapter', status: 'ok', detail: `${type}${adapter ? ` ${adapter.version}` : ''}`, fix: null }) + } + + // Packages: packages.yml without dbt_packages/ fails every parse. + const wantsPackages = (await $.fs.exists(`${root}/packages.yml`).catch(() => false)) || (await $.fs.exists(`${root}/dependencies.yml`).catch(() => false)) + if (wantsPackages) { + const has = (await $.fs.list(`${root}/dbt_packages`).catch(() => [])).length > 0 + checks.push({ id: 'packages', label: 'Packages', status: has ? 'ok' : 'fail', detail: has ? 'dbt_packages installed' : 'packages.yml is not installed', fix: has ? null : 'dbt deps' }) + } + + // Manifest freshness. + const stat = await $.fs.stat(`${root}/target/manifest.json`).catch(() => null) + let staleFiles: string[] = [] + if (!stat) checks.push({ id: 'manifest', label: 'Manifest', status: 'warn', detail: 'target/manifest.json is missing: lineage, model context and docs need it', fix: 'dbt parse' }) + else { + staleFiles = await changedSince($, root, stat.mtimeMs) + const age = Math.round(((await $.clock.now()) - stat.mtimeMs) / 60_000) + const ageText = age < 60 ? `${age} min` : age < 2880 ? `${Math.round(age / 60)} h` : `${Math.round(age / 1440)} days` + checks.push( + staleFiles.length + ? { id: 'manifest', label: 'Manifest', status: 'warn', detail: `stale: ${staleFiles.length} file${staleFiles.length === 1 ? '' : 's'} changed since it was written ${ageText} ago (${staleFiles.slice(0, 3).join(', ')}${staleFiles.length > 3 ? ', …' : ''})`, fix: 'dbt parse' } + : { id: 'manifest', label: 'Manifest', status: 'ok', detail: `current (written ${ageText} ago)`, fix: null }, + ) + } + + // The connection test opens a warehouse session: only when asked for. + if (connection) { + const debug = await runDbt($, root, ['debug'], 120_000).catch(error => ({ exitCode: -1, stdout: '', stderr: String(error) })) + const parsed = debugInfo(`${debug.stdout}\n${debug.stderr}`) + checks.push( + debug.exitCode === 0 && parsed.connection !== 'failed' + ? { id: 'connection', label: 'Connection', status: 'ok', detail: `${parsed.adapterType ?? type ?? 'warehouse'} connection test passed`, fix: null } + : { id: 'connection', label: 'Connection', status: 'fail', detail: (parsed.detail ?? stripAnsi(debug.stdout || debug.stderr).trim().split('\n').slice(-3).join(' ')).slice(0, 300), fix: 'check profiles.yml credentials; run dbt debug' }, + ) + } else if (previous?.root === root) { + const kept = previous.checks.find(one => one.id === 'connection') + if (kept) checks.push(kept) + } + + const view: DoctorView = { root, checks, at: await $.clock.now(), staleFiles, busy: null } + await update($, doctorAtom, () => view) + return view +} + +async function parseNow($: EngineInterface, root: string) { + const current = await read($, doctorAtom) + if (current) await update($, doctorAtom, () => ({ ...current, busy: 'Running dbt parse…' })) + const run = await runDbt($, root, ['parse'], 300_000).catch(error => ({ exitCode: -1, stdout: '', stderr: String(error) })) + if (run.exitCode !== 0) { + const reason = stripAnsi(run.stdout || run.stderr).trim().split('\n').slice(-3).join(' ').slice(0, 200) + $.ui.toast(`✖ dbt parse failed · ${reason}`, { timeoutMs: 10000 }) + } else $.ui.toast('✓ dbt parse finished · the manifest is current', { timeoutMs: 6000 }) + const view = await runDoctor($, root) + // Claude hears the manifest is current again on its next prompt. + doctorNoteDue = doctorNote(root, view.checks) +} + +function doctorSummary(view: DoctorView) { + const bad = view.checks.filter(one => one.status !== 'ok') + return { bad, text: bad.length === 0 ? `${view.checks.length} checks passed` : bad.map(one => `${one.label} ${one.status === 'fail' ? 'failed' : 'needs attention'}`).join(' · ') } +} + +// Opened inside the press itself, so Claude Code counts it as the person's: a pane opened later, on the +// clock, is one the plugin asked for, and a narrow terminal leaves those unplaced. +async function openCheck($: EngineInterface, focus: boolean) { + await $.ui.open({ id: CHECK_PANE, title: CHECK_TITLE, columns: 100, rows: 24, closeOnEscape: true, ...(focus ? { focus: true as const } : {}) }) +} + +async function openDoctor($: EngineInterface) { + await $.ui.open({ id: DOCTOR_PANE, title: DOCTOR_TITLE, columns: 90, rows: 20, focus: true, closeOnEscape: true }) +} + +// ─── Start, the band, the hooks ───────────────────────────────────────────────────────────────────── + +export async function startDbtMods($: EngineInterface, isInteractive: boolean) { + contextGiven.clear() + pendingNotes.splice(0) + doctorNoteDue = null + await loadHistory($) + await $.command.register({ name: SHOW_COMMAND, description: 'Run dbt show for a model or a SQL query and open the rows in the results pane', argumentHint: ' | ' }) + await loadPaneSizes($) + await $.command.register({ name: SHOW_COMMAND, description: 'Run dbt show for a model or a SQL query and open the rows in the Query results pane', argumentHint: ' | ' }) await $.command.register({ name: DOCTOR_COMMAND, description: 'Check the dbt environment: Python, dbt, adapter, packages, manifest freshness and the warehouse connection' }) + await loadPaneSizesOnce($) // The doctor at session start: a -p run or the SDK has nobody to show the band to, and no dbt to wait on. if (!isInteractive) return later($, async () => { @@ -1113,7 +1147,7 @@ async function dbtToolCall($: EngineInterface, e: any, next: (e: any) => Promise landed.view.status === 'error' ? `✖ ${landed.view.model} · dbt could not compile or run it · see the band` : landed.view.status === 'partial' - ? `◦ ${landed.view.model} · ${landed.view.ran ? 'compiled and ran; columns not compared' : 'not checked: dbt has no model for this file'}` + ? `◦ ${landed.view.model} · ${landed.view.ran ? 'compiled and ran; columns not compared' : `not checked: ${landed.view.reason}`}` : `${STATUS_ICON[landed.view.status]} ${landed.view.model} · compiled and validated against the warehouse`, { timeoutMs: 6000 }, ) @@ -1311,7 +1345,7 @@ export function registerDbtMods(on: On) { {busy ? {busy} : null} {result ? ( -