craftz

One way to build, check, deploy and release a repository, as a package each one depends on.

Every repository makes the same choices, like its toolchain, versions, workflows, branch protection and deploys. Made in each one separately, they drift. craftz holds them as rules, checks a repository against the version it installs, and fixes what it can. Moving every repository to a new choice is then a version bump, not a copy into each one.

What it does

Command	Does
`craftz check`	checks the repository against every rule, as part of its `verify`
`craftz fix`	writes every fix that can be automated
`craftz settings`	checks and writes what lives outside the files, on GitHub and Cloudflare
`craftz deploy`	deploys a site the way its Worker config says
`craftz pr`, `craftz gone`	open a pull request that merges itself once CI passes, and delete the branches that merged
`craftz rules [id]`	prints the rules, or one rule, from the installed version
`craftz()`	a Vite plugin that sets `fmt`, `lint` and a site's config, and never overrides the repository's

An agent reads the rules with craftz rules, from the version the repository installed, so it never works from a fetched page or an older copy.

It's opinionated, and built for one setup: Vite+, pnpm, Node 26, GitHub and Cloudflare Workers. A repository on that setup gets the same build, checks, pull requests, releases and deploys as every other one.

Install

pnpm add -D @amitkaps/craftz

It needs Node 26 or newer, the Node it's built and tested on.

Use

pnpm exec craftz check                 # what's out of line
pnpm exec craftz fix                   # fix what can be fixed
pnpm exec craftz rules scripts-verify  # what one rule asks, and why

Read the docs for its design, the rules, its usage, the plan and the lessons.

Folders

docs/
The writing that spans the code, in reading order.
reference/
The files every repository is compared with, laid out as a repository has them. Each rule's check in src/rules.ts reads them, and its fix copies from them, so there's one copy of each. The rules say why each one is there.
src/
The code that checks every repository against the rules. rules.ts holds each rule's check and fix together, and stated.ts reads where the doc states each one. survey.ts reads each repository and runs the rules, and drift.ts prints what it found.
tests/
The tests, one file for each part of the source.

Docs

AGENTS.md
craftz — one way to build, check, deploy and release.
CLAUDE.md
@AGENTS.md

Code

.gitignore
What git leaves out. That is installed packages, what a build writes, the OS's own files and secrets, which never belong in the repository.
cloudflare.config.ts
What Cloudflare runs for craftz's site: its name, compatibility date, domain and how it serves the files. The site is the docs, the folder prose build writes, so it's static, and craftz deploy uploads it.
pnpm-workspace.yaml
pnpm 12 reads project settings from here. It's a settings file, not a workspace, and its settings are the rules', from craftz.
vite.config.ts
One Vite+ config packs the package and checks it. vp pack writes ESM with its types, and runs publint, which fails the build on a package npm would serve badly.

No prose yet

.github/ · .vscode/

Other files

LICENSE · package.json · pnpm-lock.yaml · tsconfig.json