Skip to content
Open
34 changes: 33 additions & 1 deletion plugins/altimate-code/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,5 +20,37 @@
"databricks",
"column-lineage"
],
"types": "./types/index.d.ts"
"types": "./types/index.d.ts",
"userConfig": {
"maxScanBytes": {
"type": "number",
"title": "Largest BigQuery scan without asking",
"description": "A dbt run, build or show that BigQuery estimates would scan more bytes than this is held until you allow it with /allow-scan. 0 never holds one. Other warehouses are never held.",
"default": 10737418240
},
"healthBlocksPush": {
"type": "boolean",
"title": "Project health blocks git push",
"description": "When on, git push is refused while the project health check finds new issues in the models you changed. Off, the issues are only shown.",
"default": false
},
"healthConfigPath": {
"type": "string",
"title": "Project health check config",
"description": "Path to a DataPilot health check config file, relative to the dbt project. Empty uses the default checks.",
"default": ""
},
"commentsPollSeconds": {
"type": "number",
"title": "Team comments refresh (seconds)",
"description": "How often the team's comments on shared docs are fetched again.",
"default": 900
},
"commentsInContext": {
"type": "boolean",
"title": "Team comments in Claude's context",
"description": "When on, the open comments on a model Claude reads or edits are added to its context. Off keeps them out of Claude's context.",
"default": true
}
}
}
130 changes: 130 additions & 0 deletions plugins/altimate-code/hooks/altimate-cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,133 @@ export function later($: EngineInterface, work: () => Promise<unknown>) {
})
})
}

// The plugin's own MCP server, by its key in .mcp.json.
const SERVER_KEY = 'altimate-code'
const TOOL_TIMEOUT_MS = 60_000

/** Resolves with the work's value, or null once `ms` pass or it fails. */
export function within<T>($: EngineInterface, ms: number, work: Promise<T>): Promise<T | null> {
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))
})
}

let serverName: string | null = null
let connectFailedAt = -Infinity
const CONNECT_RETRY_MS = 60_000

/** The plugin's MCP server as $.mcp.call names it, or null when it is not connected (CLI mode); a failure is retried after a minute. */
async function mcpServer($: EngineInterface): Promise<string | null> {
if (serverName) return serverName
const now = await $.clock.now()
if (now - connectFailedAt < CONNECT_RETRY_MS) return null
const connected = await $.mcp.connect(SERVER_KEY).catch(() => null)
serverName = connected?.isConnected ? connected.server : null
if (!serverName) connectFailedAt = now
return serverName
}

export function textOf(content: unknown): string {
if (typeof content === 'string') return content
const blocks = Array.isArray(content) ? content : Array.isArray((content as any)?.content) ? (content as any).content : []
return blocks
.filter((block: any) => block?.type === 'text' && typeof block.text === 'string')
.map((block: any) => block.text)
.join('\n')
}

/**
* The file a `<persisted-output>` preview says holds the whole answer: null when the text is no such
* preview, undefined when it is one but names no file.
*/
export function persistedPath(text: string): string | null | undefined {
if (!/^\s*(?:<|&lt;)persisted-output(?:>|&gt;)/.test(text)) return null
return /Full output saved to: ([^\n]+?)\s*$/m.exec(text)?.[1]
}

/** A file:// URI as a filesystem path; a Windows drive path keeps no leading slash. */
function fileUriPath(uri: string): string {
const path = decodeURIComponent(new URL(uri).pathname)
return /^\/[A-Za-z]:/.test(path) ? path.slice(1) : path
}

export type RunToolOptions = {
/** Straight to the CLI, whose --json carries the whole metadata. */
cliOnly?: boolean
/** A deadline on the engine's clock: nothing starts once it has passed, and the CLI is stopped at it. */
until?: number
/**
* The tool needs write permission (it starts the dbt adapter, or changes something): the call goes
* through the CLI with `--allow-write`, since the plugin's MCP server runs read-only.
*/
write?: boolean
}

/**
* Runs one altimate-code data tool: through the plugin's MCP server when it is connected (no
* permission prompt, structured content when the build sends it), else `altimate tool run --json`.
* `cliOnly` goes straight to the CLI, whose --json carries the whole metadata; a structured result
* the server left out for size is fetched that way too.
*/
export async function runTool($: EngineInterface, name: string, args: Record<string, unknown>, options: RunToolOptions = {}) {
const { until, write = false } = options
const cliOnly = options.cliOnly === true || write
// With a deadline, nothing starts once it has passed, and the CLI is stopped at it.
const left = async () => {
const ms = until === undefined ? TOOL_TIMEOUT_MS : until - (await $.clock.now())
if (ms <= 0) throw new Error('out of time')
return ms
}
const server = cliOnly ? null : await mcpServer($)
if (server) {
const ms = await left()
try {
// The engine's MCP call has no timeout of its own: one that never answers is given up on, so a
// shared trace does not hold every later edit of that column, and the CLI is tried instead.
const result = await within($, ms, $.mcp.call(server, name, args))
if (!result) throw new Error('altimate-code did not answer over MCP')
let text = textOf(result.content)
// A long result comes back as a preview plus a link to the full text.
const link = result.content.find((block: any) => block?.type === 'resource_link' && String(block.uri).startsWith('file://')) as
| { uri: string }
| undefined
// Claude Code (2.1.319) swaps an answer of about 49 KB or more for a preview that names the file it
// saved the whole answer to, with no link block: the answer is that file.
const saved = link ? null : persistedPath(text)
if (!link && saved === undefined) throw new Error('a cut-off preview with no file named')
// An unreadable link or file leaves only the preview: fetch the whole answer through the CLI instead.
const full = link ? await $.fs.read(fileUriPath(link.uri)).catch(() => null) : saved ? await $.fs.read(saved).catch(() => null) : text
if (full === null) throw new Error('the full result could not be read')
text = full
// Claude Code hands a tool's structured content over as one JSON text block in place of the
// text; the structured content carries the text report as `report`.
const structured = (result.structuredContent ?? (text.trim().startsWith('{') ? parseJson(text) : null)) as any
if (structured?.truncated !== true) {
return { metadata: structured, text: typeof structured?.report === 'string' ? structured.report : text, ok: !result.isError }
}
} catch {
// Fall through to the CLI: the server may have gone away mid-session, so the next call reconnects.
serverName = null
}
}
const argv = ['tool', 'run', name, '--args', JSON.stringify(args), '--json', ...(write ? ['--allow-write'] : [])]
const result = await runAltimate($, argv, await left())
if ((result as { isStdoutTruncated?: boolean }).isStdoutTruncated) {
return { metadata: null as any, text: `${name}'s answer was larger than the 4 MiB a plugin can read`, ok: false }
}
const data = parseJson<{ status?: string; output?: string; metadata?: unknown }>(result.stdout)
// Anything but the CLI's answer object (an altimate-code that exits before a pipe drains cuts it off) is a
// failure to report and ask again, not "no such model".
if (result.exitCode === 0 && (!data || typeof data !== 'object' || typeof data.status !== 'string')) {
return { metadata: null as any, text: 'the answer could not be read', ok: false }
}
return { metadata: (data?.metadata ?? null) as any, text: data?.output ?? '', ok: result.exitCode === 0 && data?.status !== 'error' }
}
132 changes: 132 additions & 0 deletions plugins/altimate-code/hooks/dbt-command.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
import { expect, test } from 'claude-code/testing'

import { parseDbtCommand } from './dbt-command'

/** The fields a caller decides on, without the offsets. */
const shape = (line: string) => parseDbtCommand(line).map(({ start, end, subcommandEnd, ...rest }) => rest)

const base = { select: [], target: null, targetPath: null, hasDefer: false, hasState: false }

test('a plain dbt command: subcommand, selections, target and target path', () => {
expect(shape('dbt build -s stg_orders --select +fct_orders -t prod --target-path tgt')).toEqual([
{ ...base, binary: 'dbt', subcommand: 'build', select: ['stg_orders', '+fct_orders'], target: 'prod', targetPath: 'tgt' },
])
expect(shape('dbt run --models a b --target=dev')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run', select: ['a', 'b'], target: 'dev' }])
})

test('commands joined with &&, ; and pipes each give their dbt invocation, in order', () => {
expect(shape('cd jaffle && dbt deps && dbt run -s a; dbt test | tee log.txt')).toEqual([
{ ...base, binary: 'dbt', subcommand: 'deps' },
{ ...base, binary: 'dbt', subcommand: 'run', select: ['a'] },
{ ...base, binary: 'dbt', subcommand: 'test' },
])
})

test('uv run dbt, poetry run dbt and a path to dbt are dbt launchers', () => {
expect(shape('uv run dbt build -s a')).toEqual([{ ...base, binary: 'uv run dbt', subcommand: 'build', select: ['a'] }])
expect(shape('poetry run dbt test')).toEqual([{ ...base, binary: 'poetry run dbt', subcommand: 'test' }])
expect(shape('.venv/bin/dbt compile')).toEqual([{ ...base, binary: '.venv/bin/dbt', subcommand: 'compile' }])
})

test('VAR=x in front of dbt is kept in the invocation; DBT_DEFER and DBT_STATE count as defer and state', () => {
const line = 'DBT_PROFILES_DIR=. dbt run -s a'
const [one] = parseDbtCommand(line)
expect(one).toEqual({ ...base, binary: 'dbt', subcommand: 'run', select: ['a'], start: 0, end: line.length, subcommandEnd: line.indexOf(' -s') })
expect(shape('DBT_DEFER=1 DBT_STATE=prod dbt run')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run', hasDefer: true, hasState: true }])
})

test('--defer and --state are seen; the offsets cut the invocation out of the line', () => {
const line = 'echo hi && dbt build --defer --state prod-artifacts -s a > out.log'
const [one] = parseDbtCommand(line)
expect(one).toMatchObject({ subcommand: 'build', hasDefer: true, hasState: true })
expect(line.slice(one!.start, one!.end)).toBe('dbt build --defer --state prod-artifacts -s a')
expect(line.slice(one!.start, one!.subcommandEnd)).toBe('dbt build')
})

test('a line without dbt, or one that cannot be read, gives no invocation', () => {
expect(parseDbtCommand('ls -la && git status')).toEqual([])
expect(parseDbtCommand('echo "dbt run')).toEqual([])
expect(parseDbtCommand('dbt run $(echo')).toEqual([])
expect(parseDbtCommand('')).toEqual([])
expect(parseDbtCommand('grep dbt run.log')).toEqual([])
})

test('a bare dbt has no subcommand; quoted selections are unquoted', () => {
expect(shape('dbt')).toEqual([{ ...base, binary: 'dbt', subcommand: null }])
expect(shape(`dbt ls -s "tag:nightly" --select 'path:models/staging'`)).toEqual([
{ ...base, binary: 'dbt', subcommand: 'ls', select: ['tag:nightly', 'path:models/staging'] },
])
})

test('a heredoc, or an operator or redirection with nothing after it, makes the line unreadable', () => {
expect(parseDbtCommand('cat > run.sh <<EOF\ndbt run -s a\nEOF')).toEqual([])
expect(parseDbtCommand("cat <<'EOF' > x.sh\ndbt build\nEOF\nbash x.sh")).toEqual([])
expect(parseDbtCommand('cat <<-EOF\n\tdbt run\n\tEOF')).toEqual([])
for (const line of ['dbt run >', 'dbt run &&', 'dbt run |', '&& dbt run', '; dbt run', 'dbt run )', 'dbt run (', '(dbt run', 'dbt run ; ;'])
expect(parseDbtCommand(line)).toEqual([])
// A here-string is no heredoc; a subshell, a function and a trailing ; or & are fine.
expect(shape('dbt run <<< y')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run' }])
expect(shape('(cd a && dbt run); f() { dbt test; }; dbt ls &')).toEqual([
{ ...base, binary: 'dbt', subcommand: 'run' },
{ ...base, binary: 'dbt', subcommand: 'test' },
{ ...base, binary: 'dbt', subcommand: 'ls' },
])
})

test('parentheses inside a quoted string in a substitution are text', () => {
expect(shape('dbt run $(printf "(") -t dev')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run', target: 'dev' }])
expect(shape('dbt run "$(printf ")")" -t dev')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run', target: 'dev' }])
})

test('short options joined to their value, and global options that take one before the subcommand', () => {
expect(shape('dbt run -tprod -sorders -musers')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run', select: ['orders', 'users'], target: 'prod' }])
expect(shape(`dbt --warn-error-options '{"include":"all"}' -r timing.txt run -s a`)).toEqual([
{ ...base, binary: 'dbt', subcommand: 'run', select: ['a'] },
])
expect(shape('dbt build --indirect-selection cautious -s a')).toEqual([{ ...base, binary: 'dbt', subcommand: 'build', select: ['a'] }])
})

test('env options that take a value; DBT_TARGET and DBT_TARGET_PATH in front of dbt, which the flags override', () => {
expect(shape('env -i -u FOO dbt run')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run' }])
expect(shape('DBT_TARGET=prod DBT_TARGET_PATH=tgt dbt run')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run', target: 'prod', targetPath: 'tgt' }])
expect(shape('DBT_TARGET=prod dbt run -t dev')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run', target: 'dev' }])
})

test('subshells after a keyword, case patterns, process substitution, arrays and arithmetic are read', () => {
const run = { ...base, binary: 'dbt', subcommand: 'run' }
expect(shape('time (dbt build)')).toEqual([{ ...base, binary: 'dbt', subcommand: 'build' }])
for (const line of [
'if (cd proj && dbt run); then echo ok; fi',
'! (dbt run)',
'{ (dbt run); }',
'dbt run 2> >(tee err.log)',
'for ((i=0;i<3;i++)); do dbt run; done',
'f() ( dbt run )',
'case $t in\n a|b) dbt run;;\nesac',
])
expect(shape(line)).toEqual([run])
expect(shape('case $t in prod) dbt run -t prod;; *) dbt run;; esac')).toEqual([{ ...run, target: 'prod' }, run])
expect(shape('case $t in (prod) dbt run -t prod;; esac')).toEqual([{ ...run, target: 'prod' }])
expect(shape('models=(orders users); for m in "${models[@]}"; do dbt run -s $m; done')).toEqual([{ ...run, select: ['$m'] }])
const line = 'diff <(dbt ls -s a) <(dbt ls -s b)'
const found = parseDbtCommand(line)
expect(found.map(({ start, end }) => line.slice(start, end))).toEqual(['dbt ls -s a', 'dbt ls -s b'])
})

test('a function definition takes one name: `dbt run ()` is unreadable and a function named dbt is no invocation', () => {
expect(parseDbtCommand('dbt run ()')).toEqual([])
expect(parseDbtCommand('case x in a) dbt run')).toEqual([])
expect(shape('dbt() { echo hi; }; dbt test')).toEqual([{ ...base, binary: 'dbt', subcommand: 'test' }])
expect(shape('function f() { dbt run; }')).toEqual([{ ...base, binary: 'dbt', subcommand: 'run' }])
})

test('a case pattern named dbt is no invocation', () => {
const run = { ...base, binary: 'dbt', subcommand: 'run' }
for (const line of ['case $t in a) x;; dbt) dbt run;; esac', 'case $t in a|dbt) dbt run;; esac', 'case $t in (dbt) dbt run;; esac'])
expect(shape(line)).toEqual([run])
})

test("quotes in a heredoc inside a substitution are text, so Claude's commit form stays readable", () => {
const line = `dbt run -s a && git commit -m "$(cat <<'EOF'\nfix "foo it's\nEOF\n)"`
expect(shape(line)).toEqual([{ ...base, binary: 'dbt', subcommand: 'run', select: ['a'] }])
})
Loading
Loading