@cosmicdrift/kumiko-guards

AST guards and repo checks for a single Kumiko repo that need more than one file: direct entity writes, tenant escalation, undeclared escape hatches, openToAll without a reason, missing access-denied tests and the repo checks. Single-file checks (direct fs/fetch, date API, test titles, raw HTML, ...) live in the Biome preset @cosmicdrift/kumiko-framework/biome-rules as builtins and GritQL plugins. Every finding must clear the repo's own security baseline; there is no per-guard skip flag.

bun node_modules/@cosmicdrift/kumiko-guards/src/run-guards.ts [--explain|--write-security-baseline]

The baseline lives at .kumiko-security-baseline.json in the consumer repo's root. --explain prints the resolved repo and per-guard scan scope without running any guard; --write-security-baseline freezes current findings into the baseline file.

Dependency checks

Three subcommands check the dependencies of the repo cwd sits in. They call the npm registry or bun audit, so they are not part of the default run and not part of checks; each takes --report (print only, exit 0; for outdated it adds transitive and major-lag sections and a deprecated direct dependency still exits 1). outdated lists every package the registry did not answer as UNKNOWN with the reason and fails when no direct dependency got an answer.

bunx kumiko-guards licenses   # licence allow/gray/deny classification of installed packages
bunx kumiko-guards security   # bun audit: critical/high block, moderate warns
bunx kumiko-guards outdated   # installed direct dependencies the registry marks deprecated

Installed packages (licenses, outdated) are read from node_modules of the repo root, its workspace members and every ancestor directory, the resolution Bun itself uses, so a hoisted parent workspace and .wt/ worktrees work. If nothing is found the command fails ("nothing scanned"). security audits the repo root's bun.lock, or the nearest ancestor's (announced) when the repo has none, and fails if there is no lockfile at all.

Exceptions need a reason, a reviewer and an expiry date. The package ships defaults (dependency-license-exceptions.json, dependency-security-exceptions.json); a file of the same name in the repo root (and, for licenses, in an ancestor whose node_modules was scanned) is merged on top. A security exception that expires within 14 days blocks.

Raw-SQL markers

guard-raw-sql blocks .unsafe() / asRawClient() outside db/queries/*, db/query.ts and testing code. A // kumiko-lint-ignore raw-sql <reason> marker on the call's line or the line above only suppresses while its (file, reason) pair is frozen in .kumiko-raw-sql-baseline.json at the repo root. A new or reworded marker without a baseline entry fails the check, so every exception shows up as a baseline diff in review. Without a baseline file the guard only warns, so consumers do not break on bump. Prefer a typed db/query helper; freeze a deliberate exception with:

bunx kumiko-guards checks --write-baseline --guard=guard-raw-sql

Rewording the reason is a new entry: re-run the command and review the diff. A removed marker leaves a stale entry that does not fail; the same command drops it.

kumiko-pre-push

A POSIX-sh pre-push hook, wired by copying the package's hooks/pre-push shim to .husky/pre-push. The shim execs the nearest executable node_modules/.bin/kumiko-pre-push from the repo root upwards (so worktrees without their own node_modules resolve via the parent install, up to and including $HOME, skipping ancestors owned by another user or writable by group/others) and fails closed with a bun install hint when none exists. Inside the cosmicdriftgamestudio parent workspace it runs a scoped bun check for the pushing repo only; in a standalone clone it runs the repo's own package.json test script. From a .wt/<name> worktree under the parent workspace it runs a tracked scripts/check-wt.sh if present, otherwise the worktree's own package.json scripts typecheck, lint, test, and test:dom (whichever are declared), directly in the worktree — the parent's bun check would otherwise check the main checkout instead — followed by kumiko-guards guards, ui (only with non-empty uiRoots in kumiko.json, as in kumiko check), checks, comment-lang and public-exports-changelog. The repo that ships this package runs its checked-out packages/guards/src/cli.ts for these. There is no bypass switch. A check-wt.sh that wraps this hook (via exec or as a child process) is recognised, so the hook does not call it again and skips the pre-flight steps (pre-push-extra.sh, upgrade-state guard, gitleaks) the outer run already did. Recognition needs the recorded owner PID (KUMIKO_CHECK_WT_OWNER) to be this process or an ancestor running scripts/check-wt.sh, and a random KUMIKO_CHECK_WT_NONCE that matches the 0600 file kumiko-prepush-<pid> in the git common dir. Setting the variables by hand (KUMIKO_CHECK_WT_OWNER=$$ git push) therefore skips nothing; the files of finished runs are swept by the next push.

Extension point: a tracked, executable scripts/pre-push-extra.sh runs before the main check in every branch (worktree, parent-scoped, and standalone), with KUMIKO_PUSH_REPO_ROOT and KUMIKO_PUSH_PARENT_DIR available inline (never exported, so nothing else inherits them). An untracked or non-executable scripts/pre-push-extra.sh is never run — this is fail-closed so a stray or unreviewed file can't hijack push. A non-zero exit from pre-push-extra.sh aborts the push before the main check runs.