dbt-tools-ts

Imported from yu-iskw/dbt-tools-ts (AGENTS.md). Install upstream with npx skills add yu-iskw/dbt-tools-ts. Copyright stays with the author.

Agent instructions (dbt-tools-ts)

Agent documentation split

• This file (AGENTS.md) is canonical for humans and all agent tools: stack, package layout, quality gates, commands, and policy detail.
• CLAUDE.md is a Claude Code entry digest that points back here and adds Claude-specific coordination notes.
• If anything disagrees, this file wins; update this file first, then adjust shorter mirrors such as CLAUDE.md or .cursor/rules/*.mdc.

Tech stack

• Package manager: pnpm workspace.
• Node.js: use .node-version for local development and CI. Published packages require Node.js 20+.
• Language: TypeScript. Unit tests use Vitest from the repository root (per-package vitest.config.ts projects; coverage and global thresholds only in root vitest.config.ts).
• Repository boundary: this repo owns @dbt-tools/core, @dbt-tools/cli, @dbt-tools/mcp, and @dbt-tools/web. dbt-artifacts-parser is an external npm dependency and upstream parser package, not a workspace package here.

Packages

Product positioning is ADR-0008. Core/web/CLI scalability boundaries are ADR-0003, ADR-0004, ADR-0006, and ADR-0010.

Frontend application

• @dbt-tools/web is an artifact-driven investigation UI; it must remain useful without a chat surface or LLM dependency.
• Web app code lives in packages/web/src; Playwright specs live in packages/web/e2e.
• Use @dbt-tools/core/browser in workers and code that must avoid Node built-ins. Use the full @dbt-tools/core entry for Vite/Node-only code such as artifact-source middleware and server-side CLI wiring.
• Path alias @web maps to packages/web/src; keep package and root Vitest/Vite aliases in sync when it changes.

Design tokens and styling

• Token source of truth: packages/web/src/styles/tokens.css.
• TypeScript mirror: packages/web/src/constants/theme-colors.generated.ts is generated by pnpm tokens:sync; never edit it manually.
• New CSS should use semantic var(--*) tokens for colors, spacing, typography, and radii. See .cursor/rules/design-tokens.mdc.
• Run pnpm lint:stylelint after substantive CSS changes; pnpm lint:report is ESLint-only.

Unit test and coverage configuration

• Global thresholds: coverage-thresholds.mjs — lines 60%, branches 50%, functions 60%, statements 60%.
• Workspace mins: packages/*/coverage.policy.ts — per-package floors merged at root.
• Shared aliases / pool: vitest.shared.ts.
• Coverage provider and reporters: root vitest.config.ts only (Vitest projects do not support coverage in package configs).
• Agent harness: pnpm coverage:report runs vitest.coverage.ts and writes coverage-report.json.

Quality gates

Unless the user explicitly narrows scope, run the relevant gates from the repository root before claiming completion:

Root eslint.config.mjs layers eslint-plugin-security (code patterns) on top of Trunk security scanners (Trivy/OSV). See pnpm lint:security for dependency/CVE scope. Dynamic filesystem paths must go through packages/core/src/io/safe-fs.ts (resolveSafePath first); packaged fixture reads use packages/test-fixtures/dbt-artifacts-parser/test-utils.ts. pnpm lint:trunk-all expects zero eslint/security/* findings—use Map / typed-map.ts helpers instead of dynamic object indexing elsewhere.

1. pnpm test for Vitest.
2. pnpm lint:report and pnpm knip.
3. pnpm coverage:report.
4. Full pnpm lint or scoped Trunk when touching Markdown, YAML, .trunk/, GitHub workflow files, or substantive CSS.
5. pnpm build when the change spans package exports, shared TypeScript, worker protocol, package manifests, or publish-shaped behavior.
6. pnpm test:e2e when changing packages/web/e2e/ or material web journeys.
7. pnpm verify:plugins when changing plugins/**, .agents/plugins/**, .cursor-plugin/**, or .claude/skills/dbt-tools-cli-plugin-skill/**.

For documentation-only and agent-resource edits, the default repo policy still expects pnpm lint:report, pnpm knip, and pnpm coverage:report; a user may explicitly narrow verification for migration or review work. Cursor mirror: .cursor/rules/coverage-and-lint-reports.mdc.

Commands

pnpm install   # respects root .npmrc ignore-scripts=true; pnpm-workspace minimumReleaseAge
pnpm build
pnpm test
pnpm lint:report
pnpm coverage:report
pnpm knip
pnpm verify:plugins
pnpm dev:web
pnpm test:e2e
pnpm --filter @dbt-tools/web build

Pack and npx smoke for the web package is documented in .claude/skills/dbt-tools-web-pack-npx-smoke/SKILL.md.

Agent resources

• CLI plugin authoring: .claude/skills/dbt-tools-cli-plugin-skill/SKILL.md.
• Agent plugins (primitive skills): plugins/dbt-tools-cli/README.md, plugins/dbt-tools-mcp/README.md.
• E2E authoring: .claude/skills/dbt-tools-web-e2e/SKILL.md.
• E2E fix loop: .claude/skills/dbt-tools-web-e2e-fix/SKILL.md.
• UI-scope verification: .claude/skills/ui-feature-verify/SKILL.md.
• Workspace package version bump (release semver sync): .claude/skills/bump-workspace-versions/SKILL.md.
• Full verification prompt: .claude/agents/verifier.md.

Documentation boundaries

• Parser schema generation, parser package publishing, and parser-only development guidance belong in the external dbt-artifacts-parser repository. Keep only the context needed to explain that @dbt-tools/* depends on the published parser package.
• ADRs should describe durable decisions and invariants, not volatile file inventories or generated tables. Operational details belong in this file, package READMEs, code, and tests.
• Do not edit GitHub workflow files unless the task explicitly owns CI.

Secrets and suppressions

Do not commit API keys, tokens, or passwords into docs, prompts, rules, or tracked config. Reference environment variable names only. Fix lint/static-analysis findings at the root cause; inline suppressions are a last resort and must be narrow and justified.

Learned User Preferences

• Prefer simple, minimal scope in plans and implementations; avoid over-engineering when the user asks to keep work simple.
• Do not create git commits or open/update pull requests unless the user explicitly asks.
• On follow-up code or security reviews, describe only remaining issues—do not rehash fixes already applied.
• For large design questions, use structured problem-solving (intent, alternatives, scored recommendation) before implementation when the user invokes that workflow.
• CLI and MCP surfaces should use warehouse-specific filter and sort shapes, not flat option bags that mix conditions across warehouses.
• Prefer dbt-tools-mcp for long, multi-step agent work over large artifacts; prefer dbt-tools-cli for one-shot shell/CI or manifest-only readiness before run_results.json exists.
• For docs/site/, prefer task-oriented workflows and recipes (jobs users complete) over mirroring package READMEs; keep full CLI/MCP flag reference in packages/*/README.md with deliberate links from the site.
• When growing the published docs, add a Workflows hub and shallow per-surface tours before package-first reference dumps; expand guide/agents/ for plugins/skills rather than folding agent docs into MCP pages.
• GitHub Pages (docs/site/) is for end users of CLI/MCP/Web/plugins—do not link to ADRs there; keep ADRs in docs/adr/ for contributors and agents.
• End-user docs use “coding agent” and “agent skills” wording; avoid generic “AI agent” phrasing on the published site.

Learned Workspace Facts

• docs/adr/ is the only canonical ADR corpus; agents should read ADRs there directly rather than relying on the published site alone.
• docs/architecture/ holds non-ADR explanatory history; do not create new ADRs outside docs/adr/.
• docs/site/ is the VitePress end-user docs (@dbt-tools/site, base /dbt-tools-ts/): sidebar Start Here, Foundations (guide/foundations/new-to-dbt, expanded concepts/dbt-artifacts), Concepts (local/remote artifacts, discovery parity, operational intelligence), per-surface CLI / Web / MCP / Agents guides with nested Workflows, and Reference (configuration env tables, CLI cheatsheet, MCP tools, deep links); documents CLI, MCP, Web, and agent plugins—not @dbt-tools/core. Build with pnpm site:build / pnpm site:dev; deploy via .github/workflows/pages.yml; separate from docs/adr/.
• Do not ship demo artifact bundles (demo-artifacts.zip) or hand-crafted fixture JSON from this repo; users without a project should generate real artifacts via public sample repos—default jaffle_shop_duckdb (local DuckDB), optional jaffle-shop when a warehouse profile exists—documented at docs/site/guide/try-with-sample-project.md (redirect from /guide/demo-artifacts).
• Remote artifacts do not use DBT_TOOLS_REMOTE_SOURCE (removed); use --dbt-target / DBT_TOOLS_DBT_TARGET with s3:// or gs:// URIs, granular DBT_TOOLS_* remote env vars, and the web Load artifacts UI for server-mediated buckets—see docs/site/concepts/local-and-remote-artifacts.md.
• Keep @dbt-tools/mcp package README isolated: do not add cross-links to CLI or web package docs from the MCP README.
• Execution search APIs (CLI/MCP) should align with per-adapter response schemas in packages/core rather than mixing warehouse metrics in one shared options type.
• VitePress in this monorepo needs vite.esbuild, vite.build, and optimizeDeps.esbuildOptions all set to esnext in docs/site/.vitepress/config.ts or pnpm site:dev fails on legacy browser downlevel targets.
• First-party plugins (plugins/dbt-tools-cli, plugins/dbt-tools-mcp) ship eight primitive skills with identical folder/YAML names (bind-target through summarize-run); compose workflows from handles like dbt-tools-cli:bind-target, not monolithic workflow skills. Plugin SKILL.md files hold the stable contract; references/implementation.md maps to current CLI subcommands or MCP tools when surfaces change.
• Bundled plugins/dbt-tools-mcp/mcp.json is spawn-only (npx -y @dbt-tools/mcp); per-session artifact roots use dbt_tools_set_target, not DBT_TOOLS_* env in the plugin bundle.
• @dbt-tools/mcp loads manifest.json and run_results.json together; there is no manifest-only MCP session—use CLI check-session for manifest-only readiness.
• MCP ArtifactWorkspace keeps up to three parsed artifact roots in memory by default (DBT_TOOLS_MAX_CACHED_TARGETS, --max-cached-targets; 0 disables). Tools: dbt_tools_unset_target, dbt_tools_clear_cached_targets; optional idle eviction via DBT_TOOLS_CACHE_TTL_MS / --cache-ttl-ms. Background poll and dbt_tools_refresh only touch the active target.
• Local CodeQL analysis: run dev/codeql.sh from the repo root (see .claude/skills/codeql-fix/SKILL.md).