night-market-build-and-env

night-market-build-and-env

Recreate a working claude-night-market development environment from a bare machine, verify it in under an hour, and avoid the traps that have broken it before. Everything below was verified against the repo on 2026-07-02 (v1.9.15).

One rule dominates: every Python tool runs through uv run. uv is Astral's Python package and environment manager. On first uv run it creates .venv/ and syncs it from uv.lock. Never install repo dependencies with bare pip.

Toolchain setup

Install in this order. "via uv" means the tool resolves from uv.lock automatically. There is no manual install step for those rows.

#	Tool	Required?	Install hint	Verify command
1	uv	REQUIRED	official installer at astral.sh/uv	uv --version
2	Python 3.12	REQUIRED	uv python install 3.12	python3 --version
3	make + bash	REQUIRED	GNU make 3.82+ (Xcode CLT ships 3.81, which ignores .SHELLFLAGS; brew install make, run gmake)	make --version
4	ruff >=0.14.13	via uv	none (dev dependency in uv.lock)	uv run ruff --version
5	bandit	via uv	none (pre-commit env is pinned separately, see traps)	uv run bandit --version
6	mypy >=1.13	via uv	none	uv run mypy --version
7	pre-commit >=4	via uv	uv run pre-commit install	uv run pre-commit --version
8	Python 3.9	optional	uv python install 3.9	uv venv --python 3.9 /tmp/py39-check
9	node + npm	optional	needed for conjure Gemini delegation	node --version
10	Rust + cargo	optional	rustup (only for make skrills-build)	cargo --version
11	skrills binary	optional	make skrills-build or make skrills-install	make skrills-verify
12	mdbook	optional	cargo install mdbook; builds book/	mdbook --version
13	gh CLI	optional	cli.github.com (releases and Discussions)	gh --version

Notes on the optional rows:

• Python 3.9 is ONLY for local hook-compatibility testing. Hooks are scripts Claude Code runs on tool events under the host system Python (macOS ships 3.9.6), outside any virtual environment. CI enforces this in .github/workflows/python39-compat.yml.
• The conjure plugin delegates to Gemini. The root package.json pins @google/gemini-cli at ^0.25.1. Run npm install at the repo root only if you use conjure delegation.
• skrills is a Rust CLI that validates and analyzes skill files. Every Makefile target that uses it (make validate-skills, make analyze-skills) has a Python fallback, so you can skip Rust entirely.
• gh is needed for releases and for GitHub Discussions. Discussions have no gh discussion subcommand. They are reachable only through gh api graphql.

Version numbers observed on the reference machine (2026-07-02): uv 0.8.22, Python 3.12.3, ruff 0.14.13, mypy 1.19.1, bandit 1.9.2, pre-commit 4.5.1. Newer versions of uv are fine. The ruff version must match uv.lock (see traps).

First-hour verification sequence

Run these in order after installing rows 1-3 above. Each step lists the output shape that means success.

Step 1: clone and check uv.

git clone git@github.com:athola/claude-night-market.git
cd claude-night-market
uv --version

Expected: a single line like uv 0.8.22. Any 0.8+ version works. CI pins astral-sh/setup-uv@v8.2.0.

Step 2: validate all plugin structures (also proves the venv syncs).

make validate-all

Expected: one block per plugin (26 directories) shaped like:

>>> Validating plugins/abstract:
Plugin Validation Report: abstract
...
OK Plugin validation passed

Blue "Recommendations" lines are advisory and fine. A red failure line or (validation failed) is not.

Step 3: run one fast plugin test suite.

make -C plugins/leyline test

Expected: verbose pytest output ending with a coverage table and a summary like 710 passed, 6 warnings in 9.96s (counts and timing drift, but zero failures is the invariant). This proves uv run, pytest, and per-plugin coverage thresholds all work.

Step 4: install the git hooks.

uv run pre-commit install

Expected: pre-commit installed at .git/hooks/pre-commit. From now on commits run the full hook chain (file validation, bandit, ruff, mypy, changed-plugin tests, structure validation). Never bypass it with --no-verify; CONSTITUTION.md forbids that.

If any step fails, load night-market-debugging-playbook.

Python version tiers

This is the number-one onboarding misconception. The README says "Python 3.9+ for hooks", and newcomers read that as "the repo runs on 3.9". It does not. There are three tiers:

Tier	Version	Enforced by	Why
Root tooling (pytest, ruff, mypy)	3.12	root pyproject.toml requires-python = ">=3.12", ruff target-version = "py312", mypy python_version = "3.12"	dev toolchain runs inside the uv venv
Plugin packages	varies, 3.9 to 3.12	each plugins/<name>/pyproject.toml	plugins are independent deployables (ADR-0001)
Hook import chains	3.9	.github/workflows/python39-compat.yml	hooks run under the HOST system Python (macOS 3.9.6), outside any venv

Per-plugin requires-python as of 2026-07-02 (22 of 26 plugin dirs have a pyproject.toml):

• 3.12: abstract, conjure (also <3.14), imbue, leyline, minister, sanctum, scry
• 3.10: attune, conserve, hookify, memory-palace, parseltongue, pensive, scribe, spec-kit
• 3.9: archetypes, egregore, gauntlet, herald, oracle, phantom, tome

Why the hook tier exists: Claude Code executes hook scripts with whatever interpreter the host provides, not the repo venv. A hook file AND everything it transitively imports must therefore stay 3.9-compatible, even inside a plugin whose package requires 3.12. CI enforces this with two gates in python39-compat.yml: gate 1 runs ruff check --select UP007 --target-version py39 on hook files (bare X | Y union annotations), gate 2 builds a real 3.9 venv with uv venv --python 3.9 and runs hook tests with --override-ini="addopts=".

Consequences you must respect in hook-reachable code:

• Use timezone.utc, never datetime.UTC (a 3.11+ alias). The root ruff config extend-ignores UP017 specifically so autofix does not reintroduce the alias. This break recurred three times before the ignore plus an AST guard test held the line.
• Guard third-party imports (yaml, anthropic) in hook entrypoints. The system interpreter has none of the repo's dependencies, and an unguarded import makes every git commit emit ModuleNotFoundError.

Known traps

Trap	Symptom	Fix or guard
setup-uv@v8 bare tag	CI fails: the bare v8 tag does not exist upstream	pin exact tag astral-sh/setup-uv@v8.2.0 (commit f81d89a5). Guard: scripts/check_pinned_versions.py
bandit 1.9+ under system 3.9	pre-commit bandit hook env fails to install	.pre-commit-config.yaml pins rev: 1.8.6, the last release supporting 3.9 (commit 25bf5a9d). The project-venv bandit (1.9.x via uv run) is a different install and is fine
stale .uv-tools binary shadows ruff	bare ruff reports an old version (0.7.3 observed) and disagrees with CI	root Makefile sets UV_TOOL_DIR ?= $(abspath .)/.uv-tools and prepends .uv-tools/ruff/bin to PATH. Always lint via make lint or uv run ruff, never bare ruff. Guard: scripts/check_ruff_version.py compares uv.lock to PyPI
root pytest silently skips plugins	uv run pytest at the root collects only tests/, never plugin tests	root pyproject.toml sets norecursedirs = ["plugins/*", ...] on purpose (root conftest.py documents ImportPathMismatchError). Run make -C plugins/<name> test or make <name>-test
imbue coverage artifacts	every pytest run in plugins/imbue writes htmlcov/, coverage.xml	imbue's pytest addopts force --cov=scripts with term, html, and xml reports. Artifacts are gitignored. Expect them and never commit them
make skrills-build fails	Error: skrills repo not found at $HOME/skrills	SKRILLS_REPO defaults to $(HOME)/skrills. Set SKRILLS_REPO=/path/to/skrills or skip: make validate-skills falls back to a Python checker when no skrills binary exists
plugins run from a cache dir	plugin hook cannot find a file by relative path	installed plugins execute from the Claude Code cache dir, not the repo. Hooks must never use paths relative to the current working directory

When NOT to use

• Daily test, lint, release, and publish commands: use night-market-operations. This skill only bootstraps the machine.
• A previously working environment started failing: use night-market-debugging-playbook first to triage the symptom.
• Configuration axes, env vars, and their defaults beyond setup (VOW_SHADOW_MODE, quality gates): use night-market-config-catalog.
• Plugin, skill, and hook mechanics (how the pieces work rather than how to install the tools): use claude-code-plugin-reference.

Exit Criteria

• uv --version prints a version at the repo root.
• uv run ruff --version prints the uv.lock version (0.14.13 as of 2026-07-02), not the .uv-tools version.
• make validate-all prints Plugin validation passed for every plugin and no (validation failed) lines.
• make -C plugins/leyline test ends with N passed and zero failures, plus a coverage table.
• uv run pre-commit install created .git/hooks/pre-commit.
• The reader can state why hook code is 3.9-constrained while root tooling requires 3.12 (hooks run under the host system Python).

Provenance and maintenance

Compiled 2026-07-02 against repo v1.9.15 (branch discussions-fix-1.9.14). Observed tool versions and test counts in this file are snapshots and will drift. Re-verify with:

• Root Python floor: rg -n "requires-python" pyproject.toml
• Per-plugin floors: rg -n "requires-python" plugins/*/pyproject.toml
• Locked ruff version: rg -n -A1 'name = "ruff"$' uv.lock
• setup-uv pin: rg -n "setup-uv" .github/workflows/*.yml
• bandit pin: rg -n -B2 "id: bandit" .pre-commit-config.yaml
• Makefile defaults: rg -n "UV_TOOL_DIR|SKRILLS_REPO \?=" Makefile
• Root pytest exclusion: rg -n "norecursedirs" pyproject.toml
• imbue coverage addopts: rg -n -A8 "addopts" plugins/imbue/pyproject.toml
• gemini-cli pin: rg -n "gemini-cli" package.json
• Leyline test count drift: make -C plugins/leyline test