kumiko check

There are two kumiko check commands. In an app you run the one from @cosmicdrift/kumiko-cli. The framework repository has its own, larger pass, described further down.

In an app

bunx @cosmicdrift/kumiko-cli check
bunx @cosmicdrift/kumiko-cli check --explain

The command reads kumiko.json in the repository root and derives its steps from it:

Step	Runs when	What it does
`boot`	`kind: "app"` and `kumiko/schema.ts` exists	`validateBoot` over the composed features
`guards`	`kind` is not `tooling`	AST guards over `sourceRoots`
`ui`	`uiRoots` is not empty	UI guards over `uiRoots`
`checks`	`kind` is not `tooling`	repository checks over `sourceRoots` and `testGlobs`, including the upgrade-state guard

--explain prints the resolved step list and runs nothing.

`uiRoots` is required for apps

An app (kind: "app") must list its UI directories in uiRoots. Without the field the command stops before the first step:

kind "app" must declare uiRoots in kumiko.json: list the UI directories (e.g. ["src/app", "src/features/*/web"]) or set uiRoots: [] for an app without UI.

kumiko new app writes this kumiko.json:

{
  "kind": "app",
  "sourceRoots": ["src", "bin"],
  "testGlobs": ["src/**/*.{test,integration}.{ts,tsx}"],
  "uiRoots": ["src/features/*/web"],
  "excludes": ["**/node_modules/**", "**/dist/**"]
}

Older apps add the field by hand. uiRoots: [] declares an app without UI and skips the UI guards on purpose. Without kumiko.json the command derives a manifest without uiRoots, so an app stops with the same error plus Add a kumiko.json.

In the framework repository

bun kumiko check

Runs the same quality gates CI runs, in parallel where possible. The typical wall-clock is 60-120 seconds on a warm cache.

What it runs

Step	Tool
Lint	Biome
Types	`tsc --noEmit` (every package)
Guards	the repository’s configured quality guards
Tests	`bun test` (unit + integration)

The four steps run in parallel; tee’d logs land under /tmp/kumiko-check-*.

Parallel-lock

Concurrent invocations of kumiko check don’t compete, the second call detects the running one via lockfile and tails its output. Lead crashes release the lock atomically.

This makes it safe to call kumiko check from a pre-push hook and from a foreground terminal at the same time.

Scoping

Set KUMIKO_CLI_SCOPE to one of framework, enterprise, platform, studio, publicstatus to limit the check to a single repo:

KUMIKO_CLI_SCOPE=framework kumiko check

This is what the pre-push hook does, it scopes to the repo the push is coming from instead of running all five Kumiko repos.

When to use

Before opening a PR
After resolving merge conflicts (catches lint regressions instantly)
When CI fails and you want to reproduce locally

When NOT to use

Pre-commit. Use kumiko check:fast, it runs the same scope but only against changed files.