dbt-list-runs

Instructions

Implementation Reference

• src/tools/dbt-runs.ts:8-27 (handler)

  Main handler function for dbt-list-runs. Calls listRunHistory(), computes pass/error counts and success rate per run.

  export async function dbtListRuns(args: z.infer<typeof dbtListRunsSchema>): Promise<unknown> {
    const runs = listRunHistory(args.limit);
    return {
      count: runs.length,
      runs: runs.map((r) => {
        const total = r.results.length;
        const errored = r.results.filter((x) => x.status === "error" || x.status === "fail").length;
        const passed = r.results.filter((x) => x.status === "pass" || x.status === "success").length;
        return {
          invocationId: r.invocationId,
          generatedAt: r.generatedAt,
          filePath: r.filePath,
          totalNodes: total,
          passed,
          errored,
          successRate: total === 0 ? null : Math.round(((total - errored) / total) * 1000) / 10,
        };
      }),
    };
  }

• src/tools/dbt-runs.ts:4-6 (schema)

  Zod schema for dbt-list-runs: accepts optional limit (1-200, default 20).

  export const dbtListRunsSchema = z.object({
    limit: z.coerce.number().int().min(1).max(200).default(20),
  });

• src/index.ts:86-86 (registration)

  Tool registration in index.ts using tool() with name 'dbt-list-runs', description, schema and handler.

  tool("dbt-list-runs", "List recent dbt invocations from run_results.json files in target/ and DBT_RUN_HISTORY_DIR", dbtListRunsSchema.shape, wrapToolHandler(dbtListRuns));

• src/index.ts:30-35 (registration)

  Import of dbtListRunsSchema and dbtListRuns from src/tools/dbt-runs.js

  import {
    dbtListRunsSchema, dbtListRuns,
    dbtGetRunResultsSchema, dbtGetRunResults,
    dbtFailedTestsSchema, dbtFailedTests,
    dbtSlowModelsSchema, dbtSlowModels,
  } from "./tools/dbt-runs.js";

• src/clients/dbt-artifacts.ts:195-235 (helper)

  Helper function listRunHistory() that reads run_results.json files from DBT_RUN_HISTORY_DIR and target/, deduplicates by invocation_id, sorts by generatedAt desc, and applies limit.

  export function listRunHistory(limit = 20): ArchivedRun[] {
    const out: ArchivedRun[] = [];
    const dirs: string[] = [];
    if (config.dbt.runHistoryDir && existsSync(config.dbt.runHistoryDir)) {
      dirs.push(config.dbt.runHistoryDir);
    }
    if (config.dbt.targetDir && existsSync(config.dbt.targetDir)) {
      dirs.push(config.dbt.targetDir);
    }
    const seenInvocationIds = new Set<string>();
    for (const dir of dirs) {
      let entries: string[];
      try {
        entries = readdirSync(dir);
      } catch {
        continue;
      }
      for (const entry of entries) {
        if (!entry.endsWith(".json")) continue;
        if (!entry.includes("run_results")) continue;
        const filePath = join(dir, entry);
        try {
          const data = readArtifact<DbtRunResultsFile>(filePath);
          const invocationId = data.metadata?.invocation_id;
          if (invocationId && seenInvocationIds.has(invocationId)) continue;
          if (invocationId) seenInvocationIds.add(invocationId);
          out.push({
            filePath,
            fileName: basename(entry),
            generatedAt: data.metadata?.generated_at ?? "",
            invocationId,
            results: data.results ?? [],
          });
        } catch {
          // skip unreadable
        }
      }
    }
    out.sort((a, b) => (b.generatedAt > a.generatedAt ? 1 : -1));
    return out.slice(0, limit);
  }