@keboola/agent-precheck

A portable pre-push enforcement CLI for the Keboola UI platform. Runs the same formatting and lint gates everywhere — keboola/ui, other Keboola repos, AI-agent-generated apps — so a single command verifies that a working tree is push-ready.

Why this exists

PR template checklists and "remember to run lint" agent instructions are descriptive but unverified. Agents (and humans) push PRs that fail CI on oxfmt or oxlint despite ticking every box. This package replaces the checklist with a single command that mechanically applies fixes and reports a hard pass/fail.

The CLI is platform-distributed — published to npm so any consumer of @keboola/design or @keboola/api-client can run the same gate without copying scripts around.

Install

Already vendored as a workspace in keboola/ui. Outside this monorepo:

yarn add -D @keboola/agent-precheck

Or run ad-hoc without installing:

npx @keboola/agent-precheck

Usage

# Default: fix mode on files changed vs origin/main + working tree
yarn precheck

# CI mode: no fixes, exit non-zero on any issue
yarn precheck --check

# Only files currently staged
yarn precheck --staged

# Every tracked file (slow; for first-run cleanups)
yarn precheck --all

# Suppress per-tool stdout
yarn precheck --quiet

# Skip the workspace-wide checks individually
yarn precheck --no-deps-check
yarn precheck --no-knip

What it runs (in order, fail-fast)

1. oxfmt — apply formatting.
2. oxlint --fix — apply lint auto-fix.
3. oxfmt --check — verify formatting is clean.
4. oxlint — verify lint is clean.
5. syncpack lint — verify dependency versions are consistent (only when at least one package.json is in the changed-file set; only if syncpack is installed).
6. knip — verify no unused exports / deps / files (only if knip is installed).

Any auto-fixed file is re-git added so git push ships the fixes.

Always-ignored paths

The following directories are filtered from the discovered file set regardless of .gitignore state — universal JS-project artifacts that no project meaningfully lints:

node_modules/   dist/   build/   out/   .next/
.turbo/         .yarn/  coverage/       storybook-static/

The match is both leading-prefix (node_modules/foo) and any internal segment (packages/foo/node_modules/bar) so monorepo workspace node_modules are also skipped. Belt-and-suspenders against the common "fresh git init + npm install without .gitignore" footgun where git ls-files --others --exclude-standard would otherwise return every file under node_modules/**.

How binaries are resolved

1. Walk up node_modules/.bin/ from cwd (handles monorepo + worktree cases).
2. For oxfmt and oxlint: fall back to npx --yes --package <name> if not found locally. Slower on first run; cached afterward.
3. For syncpack and knip: skip gracefully (with a one-line (skipped: not installed) note) if not found locally. No npx fallback — auto-installing heavier deps in repos that deliberately opt out is a footgun. Use --no-deps-check / --no-knip to suppress the "skipped" line.

This means the CLI works in:

• This monorepo (all four binaries live in root node_modules).
• Other repos that yarn add -D whichever subset they use.
• Bare working trees with only Node and network access (oxfmt/oxlint via npx fallback; syncpack/knip skipped with a (skipped: not installed) note, suppressible via --quiet or --no-deps-check / --no-knip).

Out of scope (for now)

• brand-audit integration — added when the audit CLI is stable.
• Pre-push git hook installation — the CLI is the contract; whoever wires it into a hook gets the gate.
• CI integration to run --check early in the workflow — separate follow-up.

Failure mode

Exit code 1 with an explicit message:

❌ agent-precheck failed: format issues remain, lint issues remain.
   Fix the issues above and re-run. Do not push around them.

Reference

• Linear UT-3992 — initial release issue.
• Platform epic: https://linear.app/keboola/issue/UT-3919