@davidvornholt/standards

CLI for bootstrapping, synchronizing, and validating repositories that consume davidvornholt/standards.

bunx @davidvornholt/standards init
standards sync
standards check
standards doctor
standards structure
standards dependabot --check
standards dependabot --write
standards dev-env
standards github --check
standards github --apply
standards poller --config <path>
standards poller --print-units --config <path>

dependabot --write regenerates the composed .github/dependabot.yml from the canonical .github/dependabot.base.yml and the optional repo-owned .github/dependabot.local.yml; init and sync do the same automatically. dependabot --check verifies the generated file still matches its sources, and doctor/check include the same verification. The overlay is deliberately lean and additive only: new update blocks for repo-specific ecosystems, top-level private registry definitions, and ignore or registries entries appended by repeating a canonical block's normalized target. Matching blocks cannot add labels, groups, cooldowns, pull-request limits, or other policy.

dev-env decrypts the SOPS-encrypted secrets/dev.yaml — keyed by workspace group and a one-segment kebab-case workspace name (apps.<name>, packages.<name>), each mapping portable environment variable names to string values — and transactionally writes every declared workspace's .env.local with owner-only permissions and a do-not-edit header. Its Bun-specific dotenv codec exactly round-trips every value it accepts without adding helper environment variables; a value the codec cannot encode exactly is gathered as a validation problem instead of being changed silently. Validation gathers all document, containment, destination-type, workspace, and gitignore problems before writing anything. Generation then stages every output in its destination directory and rolls the whole set back if staging or commit fails, preserving prior contents, modes, and absent files; symlink destinations, duplicate resolved destinations, changed parent-directory identities, and symlinked workspace paths are rejected without following the link. Cleanup trouble after a completed commit is reported loudly as a warning rather than falsely reporting generation failure. Parent identities are checked immediately before each path operation; an unavoidable swap in the syscall-sized interval after a check remains outside the non-hostile maintainer threat model. The canonical justfile exposes the command as just dev-env-generate, and just dev-refresh chains a just secrets edit dev session into regeneration.

check also rejects the raw token formed by biome- + ignore anywhere in lock-listed canonical files. The intentionally blunt policy keeps synced sources compatible with consumer Biome configurations without invoking Biome or maintaining language-aware comment parsing.

github --check compares the live GitHub repository (including the canonical squash-only repository settings, rulesets, and declared labels) against the merged declaration in .github/settings.json + .github/settings.local.json; github --apply converges that declared state. The canonical declaration enables squash while disabling merge commits and rebases, and its default-branch ruleset independently allows only squash. Undeclared live labels remain untouched, while undeclared repository-owned rulesets are removed. check runs the same comparison whenever .github/settings.json is present, and fails closed: declared state the token cannot see fails the gate with a message naming the token fix instead of passing unverified. The canonical workflow sets STANDARDS_SKIP_GITHUB_CHECK=true only in its unprivileged quality step because its isolated github-settings job runs the live comparison with the settings-read token; this is a workflow-internal integration seam, not a general way to disable the local gate. The CLI prints an explicit diagnostic whenever that exact value skips either check's live phase or github --check; github --apply is never skipped. --apply re-diffs the PATCH response, so a setting GitHub accepts with HTTP 200 but silently ignores (plan-unavailable features) is a reported failure, not a false success. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see rulesetEnforcement below); both commands then skip rulesets and plan-gated repository settings, converge the rest, and print an unprotected-branch notice on every run.

structure enforces the canonical monorepo structure contract: workspace scripts (check-types, lint, lint:fix, test), root gate scripts, filtered Turbo convenience aliases, internal 0.0.0/workspace:* versioning, package exports, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit *.a11y.ts suite must provide a test:a11y script and direct @axe-core/playwright and @playwright/test dependencies. check includes structure, so these rules gate every consumer PR.

poller runs one tick of the fix poller: host-level automation that turns maintainer-approved GitHub issues into verified draft PRs and maintainer-approved draft PRs into completed review-fix cycles, using headless Codex runs. All workflow state lives in GitHub labels, comments, and draft PRs (the labels are canonical declared settings — see github --apply), so ticks are stateless, re-runnable, and safe to schedule from any host. A tick claims work by label (fix-in-progress / review-in-progress), releases claims stale for longer than staleClaimHours, and fails loudly — a red tick means jobs stalled, never silence. Trust is verified per event, not per configuration: the approval labels (approved-for-fix, approved-for-review) only count when the applying user holds the admin or maintain role, bind to the exact approved issue revision or PR head, and are revalidated before publication; only admin/maintain comments are treated as answers to agent questions. The poller removes its direct GitHub token variables before launching Codex, but the approved run shares the host service identity and can read its other ambient credentials and logged-in tool state; that accepted visibility must not be treated as credential isolation. The run works in a throwaway git worktree, hands results back through a structured outcome file, and the poller verifies effects (commits exist, no protected paths touched) before pushing, opening the draft PR, or posting the review — the required CI checks on the resulting PR remain the quality gate. Host mutation is declarative-only: --print-units emits a correctly escaped systemd service and timer for the polling host's infrastructure repository to adapt and deploy. That repository owns the service identity, writable HOME, PATH, GitHub token environment, lingering, and deployment. The service's tick budget (TimeoutStartSec) is derived from maxJobsPerTick × runTimeoutMinutes plus overhead, so re-render and redeploy the units after changing either value.

structure --profile source validates the standards source repository itself, which is deliberately not a consumer. The profile pins its intentional exceptions so they cannot drift silently: exact, ordered root gate scripts that run this CLI from the local checkout (structure --profile source, dependabot --check or dependabot --write, github --check, and the Turbo gate) instead of a recursive standards check, and a non-private published bin-only CLI workspace that carries a stable release SemVer and exactly maps the standards bin to src/cli.ts without exports. Every other consumer rule still applies.

Configuration

• .github/dependabot.local.yml (optional) — repo-owned Dependabot extension composed with the canonical .github/dependabot.base.yml into the generated .github/dependabot.yml. May define updates and top-level registries; a block matching a canonical normalized target may only add ignore and/or registries entries. Other matching-block policy is rejected deliberately. A missing or comments-only file means no additions. CLI 0.10.1 requires the selected content ref to contain the canonical base and rejects older refs before mutation.
• sync-standards.local.json (optional) — consumer-owned sync policy at the repo root, validated by doctor/check and every init/sync even when an explicit ref or local source makes its "ref" irrelevant. All fields optional; a missing file means the defaults. "ref" is a non-empty single-line string that pins a tag, branch, or full commit sha to sync from instead of main (an explicit --ref overrides it; a local-path --from source is used as-is and ignores only the validated pin). "autoSync": false is read by the standards-sync workflow, not the CLI, and skips the weekly scheduled run; deliberate syncs then run locally because the secret-bearing workflow is schedule-only. Version 0.7.0 removes the legacy STANDARDS_AUTO_SYNC and STANDARDS_SYNC_REF variable behavior; consumers must upgrade the package and lockfile before adopting a policy file.
• .github/settings.local.json "rulesetEnforcement": "unavailable-on-plan" (optional) — declares that the repository's GitHub plan cannot enforce rulesets (private repositories on GitHub Free, both personal accounts and organizations). github --check and --apply then skip rulesets instead of comparing them, because a comparison cannot be trusted there: personal accounts answer ruleset reads with HTTP 403, and free-plan organizations report declared rulesets as active while silently not enforcing them. Plan-gated repository settings that only function alongside branch protection (allow_auto_merge) are skipped for the same reason — GitHub accepts a PATCH for them with HTTP 200 and silently keeps the old value. The remaining repository merge settings are still checked and converged, and both commands print an unprotected-branch notice on every run. The only accepted value is "unavailable-on-plan" (enforcement is the default; omit the key on paid plans), and combining the opt-out with additional local rulesets is rejected. After upgrading the plan, remove the declaration and run bun standards github --apply to restore enforcement.
• Poller config file (required for poller, passed via --config) — host-level JSON, deliberately not repository state. Required: "repos" (unique owner/repo strings — one poller watches any number of repositories), "model" and "reasoningEffort" (passed to codex exec; the model choice is deliberate and has no default). Optional: "maxJobsPerTick" (default 1 — the concurrency and rate-limit guard; subscription-authenticated Codex runs share the interactive rate window), "staleClaimHours" (default 6; must exceed runTimeoutMinutes so a sweep can never release the claim of a job that is still running), "runTimeoutMinutes" (default 240 — the timeout catches wedged agents, not honest multi-hour review runs), "cacheDir" (default ~/.cache/standards-poller; holds bare mirrors and job worktrees; relative paths resolve against the config file), "extraCodexArgs" (extra codex exec arguments, e.g. enabling the collaboration feature for subagent fan-out). Unknown keys are rejected. The poller needs git, codex (authenticated — its rotating auth state must live in a writable location), and a GitHub token per the bullet below; the token needs issues, pull-requests, and contents write on the watched repos, and nothing else.
• GH_TOKEN / GITHUB_TOKEN (optional) — GitHub API token for the github command and the GitHub portion of check. When neither is set, the token from the local gh CLI is used; with no token at all, reads still work on public repositories. --apply needs an admin token. GitHub's REST API reveals repo merge settings only to write-capable viewers — check retries REST-hidden keys over GraphQL, which serves them to read-only tokens — ruleset bypass_actors requires repository Administration read, and private-repository labels require Issues read (or Pull requests read); a token that still cannot see declared state fails the check rather than passing unverified. In CI, the canonical workflow decrypts ci.github_settings_read_token from the SOPS-encrypted secrets/ci.yaml: a repository-scoped fine-grained PAT with read-only "Administration" and "Issues" access.

See the standards repository README for the ownership model and adoption workflow.