fnhook-fixture-valid · Claude Code mod

README

Reproducible Dotfiles (AMD64)

A highly resilient, declarative dotfiles setup using Chezmoi, Mise, and Python, optimized for Linux-based devcontainers.

Quick Start

Local Development

mise install                                       # Install all tools
mise run lint                                      # Run lint checks (read-only ≡ CI; `mise run fmt` auto-fixes)
uv run --project python pytest tests/ -x -q      # Run all 190 tests

Docker Build

docker buildx bake dev-load                        # Build devcontainer locally

Bootstrap (Container)

curl -fsSL https://raw.githubusercontent.com/sortakool/dotfiles/main/install.sh | bash

Architecture

Stage 0: install.sh bootstraps mise.
Stage 1: mise installs git, chezmoi, and uv.
Stage 2: chezmoi init clones the repo and applies templated configs.
Stage 3: Python lifecycle hooks (uv run) handle complex orchestration and tool installations.

Features

Strictly AMD64: Forced x86_64 architecture for container consistency.
Declarative Config: Pydantic DotfilesConfig centralizes 16 env vars; hk.pkl for git hooks with shared hk-common.pkl checks.
Zero-Bash: Logic is encapsulated in a typed, linted Python library (dotfiles_setup).
Zero Lint Suppressions: No noqa, type: ignore, or pylint: disable — enforced by no_lint_skip hk step.
Environment Auditor: Built-in health checks for identity, toolchains, and SSH connectivity.
CI/CD: GitHub Actions — lint → contract-preflight → a changes path-gate → base-prep → p2996-prep → build → smoke-test (smoke + Dive); promote retags on main; benchmark + Trivy run async in image-analysis.yml. Docs-only changes skip the build chain.

Tool Management

All tools are declared in mise.toml and installed via mise install. Python dependencies are managed via uv with python/pyproject.toml.

Local Testing

uv run --project python pytest tests/ -x -q      # All tests
uv run --project python dotfiles-setup verify run # Contract verification
mise run pin-actions                                # Verify GHA SHA-pinning
mise run lint-docs                                  # Validate agent documentation

Source 1 files

hooks/register.ts 17 lines

1import type { Register } from "claude-code";
2
3// Every module registering classic.PreToolUse must permit these, consulted —
4// asserted by `assert_escape_hatch_permitted`. This fixture denies nothing, and
5// carries the set anyway: the invariant is deliberately exception-free.
6const ESCAPE_HATCH_TOOLS = new Set(["AskUserQuestion", "SendUserMessage"]);
7
8export const register: Register = (on) => {
9  on("classic.PreToolUse", { tool: "Read" }, async (_$, e, next) => {
10    const result = await next(e);
11    if (ESCAPE_HATCH_TOOLS.has(e.tool)) {
12      return result;
13    }
14    return { ...result, additionalContext: ["fixture-valid"] };
15  });
16};
17