/night-market-build-and-env

name: night-market-build-and-env
description: "Rebuild the dev environment: uv, Python tiers, pins, traps. Use when onboarding or toolchain breaks. Do not use for daily commands; use night-market-operations."

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 | distro package (build-essential, Xcode CLT) | `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 sta