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.

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:

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.