feat: improve scripts and write tests

This commit is contained in:
alexm committed 2026-10-11 07:22:13 -04:00
1 parent bc3091647e
commit cf4bd07a8e
32 files changed
+3817 -723

No files matched your search

+364 -207
View File
@@ -1,57 +1,88 @@
#!/usr/bin/env python3
"""
Scaffold a new NixOS host and add it to flake.nix.
Scaffold a new NixOS host and register it in flake.nix.
Creates hosts/<name>/{default.nix,hardware.nix} and adds a
`<name> = nixpkgs.lib.nixosSystem { ... };` entry to nixosConfigurations,
cloning an existing host's entry when possible so local customizations carry over.
Everything is computed and validated in memory before the first byte is
written, and the write phase is rolled back if any step fails, so a failed
run never leaves a half-registered host behind.
Exit codes: 0 ok, 1 error, 2 usage, 130 interrupted.
"""
from __future__ import annotations
import argparse
import os
import re
import shutil
import subprocess
import sys
import tempfile
from dataclasses import dataclass, field
from pathlib import Path
from textwrap import dedent
sys.path.insert(0, str(Path(__file__).resolve().parent))
import nixflake # noqa: E402 (needs the sys.path tweak above)
from nixflake import FlakeError, HostEntry # noqa: E402
# --------------------------------------------------------------------------
# Output helpers
# --------------------------------------------------------------------------
_COLOR = sys.stderr.isatty() and "NO_COLOR" not in os.environ
def _supports_color() -> bool:
return sys.stderr.isatty()
_C = {
"green": "\033[32m" if _supports_color() else "",
"yellow": "\033[33m" if _supports_color() else "",
"red": "\033[31m" if _supports_color() else "",
"bold": "\033[1m" if _supports_color() else "",
"reset": "\033[0m" if _supports_color() else "",
}
def _c(code: str) -> str:
return f"\033[{code}m" if _COLOR else ""
def log(msg: str) -> None:
print(f"{_C['green']}[+]{_C['reset']} {msg}", file=sys.stderr)
print(f"{_c('32')}[+]{_c('0')} {msg}", file=sys.stderr)
def warn(msg: str) -> None:
print(f"{_C['yellow']}[!]{_C['reset']} {msg}", file=sys.stderr)
print(f"{_c('33')}[!]{_c('0')} {msg}", file=sys.stderr)
def die(msg: str, code: int = 1) -> None:
print(f"{_C['red']}[-]{_C['reset']} {msg}", file=sys.stderr)
sys.exit(code)
class RegisterError(Exception):
"""A user-facing failure; message is printed without a traceback."""
# --------------------------------------------------------------------------
# Hostname validation
# --------------------------------------------------------------------------
# RFC 1123 hostname: 1-63 chars, [a-z0-9-], no leading/trailing dash.
HOST_RE = re.compile(r"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$")
# RFC 1123 label, restricted further so it is also a legal bare Nix attribute
# name: lowercase, starts with a letter, no trailing dash, at most 63 chars.
HOST_RE = re.compile(r"^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$")
def valid_hostname(name: str) -> bool:
return bool(HOST_RE.match(name))
def validate_hostname(name: str) -> None:
if not HOST_RE.fullmatch(name):
raise RegisterError(
f"invalid hostname {name!r}: use lowercase letters, digits and hyphens, "
"start with a letter, end with a letter or digit, max 63 characters"
)
if name in nixflake.NIX_KEYWORDS:
raise RegisterError(f"invalid hostname {name!r}: reserved word in Nix")
# --------------------------------------------------------------------------
# Templates
#
# These contain Nix code, which is full of braces, so they must NOT go
# through str.format() or f-strings. Placeholders are @UPPER_CASE@ tokens
# replaced by render(), which fails loudly on any leftover token.
# --------------------------------------------------------------------------
DEFAULT_NIX_TEMPLATE = dedent("""\
{{ pkgs, ... }}: {{
{ pkgs, ... }:
{
imports = [
./hardware.nix
../../modules/core.nix
@@ -59,7 +90,7 @@ DEFAULT_NIX_TEMPLATE = dedent("""\
../../modules/security.nix
];
networking.hostName = "{name}";
networking.hostName = "@NAME@";
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
@@ -74,11 +105,11 @@ DEFAULT_NIX_TEMPLATE = dedent("""\
zlib
];
users.users.alex = {{
users.users.alex = {
isNormalUser = true;
shell = pkgs.zsh;
extraGroups = [ "wheel" "networkmanager" ];
}};
};
programs._1password.enable = true;
programs._1password-gui = {
@@ -87,244 +118,370 @@ DEFAULT_NIX_TEMPLATE = dedent("""\
};
system.stateVersion = "26.05";
}}
}
""")
HARDWARE_PLACEHOLDER_MARKER = "PLACEHOLDER hardware.nix" # capture-hardware.sh greps for this
PLACEHOLDER_HARDWARE = dedent("""\
# PLACEHOLDER hardware.nix for host "{name}".
# PLACEHOLDER hardware.nix for host "@NAME@".
#
# Replace this file with the output of `nixos-generate-config --show-hardware-config`
# run on the target machine. The justfile has a helper for this:
#
# just capture-hardware {name}
# just capture-hardware @NAME@
#
# Until then, this file intentionally does nothing useful and the host
# will not build.
{{ lib, ... }}: {{
# nixpkgs hostPlatform — change if not x86_64-linux.
{ lib, ... }:
{
# nixpkgs hostPlatform; change if not x86_64-linux.
nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
# Intentionally empty. See note above.
}}
}
""")
# Used only when there is no existing host to clone. @I@ is the base indent.
DEFAULT_FLAKE_ENTRY = dedent("""\
@I@@NAME@ = nixpkgs.lib.nixosSystem {
@I@ inherit system;
@I@ specialArgs = { inherit inputs; };
@I@ modules = [
@I@ ./hosts/@NAME@
@I@ home-manager.nixosModules.home-manager
@I@ {
@I@ home-manager = {
@I@ useGlobalPkgs = true;
@I@ useUserPackages = true;
@I@ users.alex = import ./home/alex;
@I@ extraSpecialArgs = { inherit inputs; };
@I@ sharedModules = [ inputs.plasma-manager.homeModules.plasma-manager ];
@I@ };
@I@ }
@I@ ];
@I@};
""")
_TOKEN_RE = re.compile(r"@[A-Z][A-Z_]*@")
def render(template: str, **values: str) -> str:
"""Substitute ``@KEY@`` tokens. Unlike str.format this is brace-safe."""
out = template
for key, value in values.items():
out = out.replace(f"@{key.upper()}@", value)
leftover = _TOKEN_RE.search(out)
if leftover:
raise RuntimeError(f"BUG: unreplaced template token {leftover.group(0)}")
return out
def add_to_flake(flake_path: Path, name: str, *, template_host: str | None = None) -> None:
# --------------------------------------------------------------------------
# flake.nix editing (pure functions: text in, text out)
# --------------------------------------------------------------------------
@dataclass
class FlakeEdit:
new_src: str
template_used: str | None
stale_template_lines: list[str] = field(default_factory=list)
def plan_flake_edit(src: str, name: str, template: str | None) -> FlakeEdit:
"""Return ``src`` with a new host entry for ``name`` inserted.
If ``template`` names an existing host, its entry is cloned (renamed,
with ``./hosts/<template>`` rewritten). Otherwise a default entry is used.
"""
Insert a new `<name> = nixpkgs.lib.nixosSystem { ... };` entry inside
the `nixosConfigurations = { ... };` block of flake.nix.
masked = nixflake.mask_non_code(src)
block = nixflake.locate_configurations(src, masked)
hosts = nixflake.find_hosts(src)
by_name = {h.name: h for h in hosts}
Strategy: locate the literal `nixosConfigurations = {` (allowing inline
or next-line `{`), find the matching closing `}` by brace counting,
then insert the new entry just before it. If `template_host` is set,
clone that host's block; otherwise emit a sensible default.
"""
src = flake_path.read_text()
if name in by_name:
raise RegisterError(f"host `{name}` is already defined in flake.nix")
m = re.search(r"nixosConfigurations\s*=\s*\{", src)
if not m:
die(f"could not find `nixosConfigurations = {{` in {flake_path}")
eol = "\r\n" if "\r\n" in src else "\n"
stale: list[str] = []
tmpl: HostEntry | None = None
open_pos = m.end() - 1 # index of the '{'
# Brace-match to find the closing '}' of this attrset.
depth = 0
close_pos = None
in_string = False
i = open_pos
while i < len(src):
c = src[i]
# Cheap string skipping. flake.nix shouldn't have weird escapes inside
# nixosConfigurations, but be polite about double-quoted strings.
if c == '"' and (i == 0 or src[i - 1] != "\\"):
in_string = not in_string
elif not in_string:
if c == "{":
depth += 1
elif c == "}":
depth -= 1
if depth == 0:
close_pos = i
break
i += 1
if template is not None:
tmpl = by_name.get(template)
if tmpl is None:
known = ", ".join(by_name) or "<none>"
raise RegisterError(f"template host `{template}` not found in flake.nix (known: {known})")
if close_pos is None:
die("could not find the closing `}` of nixosConfigurations")
block = src[open_pos + 1 : close_pos]
# Already present? Bail.
if re.search(rf"(^|\W){re.escape(name)}\s*=\s*nixpkgs\.lib\.nixosSystem", block):
die(f"host `{name}` already exists in {flake_path}")
# If we can clone an existing entry, do it (preserves user customizations).
new_entry: str
cloned = False
if template_host:
# Find `<template_host> = nixpkgs.lib.nixosSystem { ... };` inside block.
tmpl_re = re.compile(
rf"(^[ \t]*){re.escape(template_host)}\s*=\s*nixpkgs\.lib\.nixosSystem\s*\{{",
re.MULTILINE,
if tmpl is not None:
text = src[tmpl.start : tmpl.end]
text = re.sub(
rf"^([ \t]*){re.escape(tmpl.name)}(?![\w'-])",
lambda m: m.group(1) + name,
text,
count=1,
)
tm = tmpl_re.search(block)
if tm:
tmpl_indent = tm.group(1)
tmpl_start = tm.start()
# Brace-match the template entry to find its terminating `};`.
d = 0
j = tm.end() - 1 # index of opening '{'
in_str = False
entry_end = None
while j < len(block):
cc = block[j]
if cc == '"' and (j == 0 or block[j - 1] != "\\"):
in_str = not in_str
elif not in_str:
if cc == "{":
d += 1
elif cc == "}":
d -= 1
if d == 0:
# Expect a trailing ';' after the closing '}'.
semi = block.find(";", j)
if semi != -1 and block[j + 1 : semi].strip() == "":
entry_end = semi + 1
else:
entry_end = j + 1
break
j += 1
if entry_end is None:
die(f"could not parse template host `{template_host}` in flake.nix")
# Rewrite ./hosts/<template> but not ./hosts/<template>-other.
text = re.sub(
rf"(\./hosts/){re.escape(tmpl.name)}(?![\w'-])",
lambda m: m.group(1) + name,
text,
)
stale_re = re.compile(rf"(?<![\w'-]){re.escape(tmpl.name)}(?![\w'-])")
stale = [ln.strip() for ln in text.splitlines() if stale_re.search(ln)]
else:
close_indent = nixflake.line_indent(src, block.close_pos)
indent = hosts[0].indent if hosts else close_indent + " "
text = render(DEFAULT_FLAKE_ENTRY, name=name, i=indent).rstrip("\n")
if eol != "\n":
text = text.replace("\n", eol)
entry_text = block[tmpl_start:entry_end]
# Rename the binding and rewrite ./hosts/<template_host> paths.
new_entry_body = re.sub(
rf"^([ \t]*){re.escape(template_host)}(\s*=\s*nixpkgs\.lib\.nixosSystem)",
rf"\1{name}\2",
entry_text,
count=1,
flags=re.MULTILINE,
)
new_entry_body = new_entry_body.replace(
f"./hosts/{template_host}", f"./hosts/{name}"
)
new_entry = "\n" + new_entry_body
cloned = True
# Insert just before the line holding the closing brace, so we never
# produce `};};` on one line. If other code shares that line (e.g. a
# one-line attrset), split the line instead.
line_start = src.rfind("\n", 0, block.close_pos) + 1
before_brace = src[line_start : block.close_pos]
if before_brace.strip() == "":
head, tail = src[:line_start], src[line_start:]
sep = "" if (head.endswith(eol * 2) or head.endswith("{" + eol)) else eol
new_src = f"{head}{sep}{text}{eol}{tail}"
else:
close_indent = nixflake.line_indent(src, block.close_pos)
head = src[: block.close_pos].rstrip(" \t")
lead = eol if head.endswith("{") else eol * 2
new_src = f"{head}{lead}{text}{eol}{close_indent}{src[block.close_pos:]}"
if not cloned:
# Best-effort default block. Indent two extra spaces if we can guess
# the indentation by looking at existing content; otherwise 6 spaces.
indent_match = re.search(r"^([ \t]+)\S", block, re.MULTILINE)
indent = indent_match.group(1) if indent_match else " "
new_entry = (
f"\n{indent}{name} = nixpkgs.lib.nixosSystem {{\n"
f"{indent} inherit system;\n"
f"{indent} specialArgs = {{ inherit inputs; }};\n"
f"{indent} modules = [\n"
f"{indent} ./hosts/{name}\n"
f"{indent} home-manager.nixosModules.home-manager\n"
f"{indent} {{\n"
f"{indent} home-manager = {{\n"
f"{indent} useGlobalPkgs = true;\n"
f"{indent} useUserPackages = true;\n"
f"{indent} users.alex = import ./home/alex;\n"
f"{indent} extraSpecialArgs = {{ inherit inputs; }};\n"
f"{indent} sharedModules = [ inputs.plasma-manager.homeModules.plasma-manager ];\n"
f"{indent} }};\n"
f"{indent} }}\n"
f"{indent} ];\n"
f"{indent}}};\n"
return FlakeEdit(new_src, tmpl.name if tmpl else None, stale)
def verify_edit(old_src: str, new_src: str, name: str) -> None:
"""Sanity-check the edited flake before it is allowed to touch disk."""
if not nixflake.braces_balanced(new_src):
raise RegisterError("internal check failed: edited flake.nix has unbalanced braces")
before = [h.name for h in nixflake.find_hosts(old_src)]
after = [h.name for h in nixflake.find_hosts(new_src)]
if after != [*before, name]:
raise RegisterError(
f"internal check failed: expected hosts {[*before, name]}, found {after}"
)
# Insert new_entry just before the line containing the closing brace,
# so we never produce `};};` on a single line.
line_start = src.rfind("\n", 0, close_pos)
if line_start == -1:
line_start = 0
if not new_entry.endswith("\n"):
new_entry += "\n"
new_src = src[: line_start + 1] + new_entry + src[line_start + 1 :]
# Write atomically.
tmp = flake_path.with_suffix(flake_path.suffix + ".tmp")
tmp.write_text(new_src)
tmp.replace(flake_path)
def nix_parse_check(src: str) -> None:
"""If nix-instantiate is available, make sure ``src`` still parses.
Skipped silently when Nix isn't installed (e.g. running on macOS without Nix).
"""
exe = shutil.which("nix-instantiate")
if exe is None:
return
with tempfile.TemporaryDirectory() as td:
probe = Path(td) / "flake.nix"
probe.write_text(src, encoding="utf-8", newline="")
try:
proc = subprocess.run(
[exe, "--parse", str(probe)],
capture_output=True,
text=True,
timeout=60,
check=False,
)
except subprocess.TimeoutExpired:
warn("nix-instantiate --parse timed out; skipping syntax check")
return
if proc.returncode != 0:
detail = (proc.stderr or proc.stdout).strip()
raise RegisterError(f"edited flake.nix would not parse; nothing was written:\n{detail}")
def host_in_flake(flake_path: Path, name: str) -> bool:
"""Cheap textual check, does flake.nix already define this host?"""
src = flake_path.read_text()
return bool(
re.search(rf"(^|\W){re.escape(name)}\s*=\s*nixpkgs\.lib\.nixosSystem", src)
)
# --------------------------------------------------------------------------
# Filesystem
# --------------------------------------------------------------------------
def find_template_host(flake_path: Path) -> str | None:
"""Return the name of the first existing nixosConfigurations entry, if any."""
src = flake_path.read_text()
m = re.search(r"nixosConfigurations\s*=\s*\{", src)
if not m:
return None
tail = src[m.end():]
m2 = re.search(r"^[ \t]*([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*nixpkgs\.lib\.nixosSystem",
tail, re.MULTILINE)
return m2.group(1) if m2 else None
def read_text_exact(path: Path) -> str:
"""Read a UTF-8 file without newline translation."""
try:
return path.read_bytes().decode("utf-8")
except UnicodeDecodeError as e:
raise RegisterError(f"{path} is not valid UTF-8: {e}") from e
def atomic_replace(path: Path, data: str) -> None:
"""Replace ``path`` with ``data`` atomically, keeping its mode.
def main() -> int:
Writes through symlinks (the target is replaced, the link is kept).
"""
real = path.resolve()
fd, tmp_name = tempfile.mkstemp(dir=real.parent, prefix=f".{real.name}.", suffix=".tmp")
try:
with os.fdopen(fd, "w", encoding="utf-8", newline="") as f:
f.write(data)
f.flush()
os.fsync(f.fileno())
shutil.copymode(real, tmp_name)
os.replace(tmp_name, real)
except BaseException:
try:
os.unlink(tmp_name)
except FileNotFoundError:
pass
raise
def create_new_file(path: Path, data: str) -> None:
"""Create ``path`` with ``data``; fails if it already exists."""
with path.open("x", encoding="utf-8", newline="") as f:
f.write(data)
f.flush()
os.fsync(f.fileno())
def missing_template_imports(repo: Path, default_nix: str) -> list[str]:
"""Repo-relative files that the generated default.nix imports but which don't exist."""
wanted = re.findall(r"\.\./\.\./([\w./-]+)", default_nix)
return [w for w in wanted if not (repo / w).exists()]
# --------------------------------------------------------------------------
# main
# --------------------------------------------------------------------------
def parse_args(argv: list[str] | None) -> argparse.Namespace:
p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
p.add_argument("name", help="hostname for the new host (lowercase, RFC 1123)")
p.add_argument("name", help="hostname for the new host (lowercase, starts with a letter)")
p.add_argument("--repo-root", default=".", help="path to the repo root (default: cwd)")
p.add_argument("--dry-run", action="store_true", help="describe actions without writing")
args = p.parse_args()
p.add_argument(
"--template",
metavar="HOST",
help="existing host whose flake.nix entry to clone (default: the first host)",
)
p.add_argument(
"--no-template",
action="store_true",
help="don't clone an existing host; emit the built-in default entry",
)
p.add_argument("--dry-run", action="store_true", help="validate and describe, but write nothing")
args = p.parse_args(argv)
if args.template and args.no_template:
p.error("--template and --no-template are mutually exclusive")
return args
if not valid_hostname(args.name):
die(f"invalid hostname: {args.name!r} (must match {HOST_RE.pattern})")
def run(args: argparse.Namespace) -> int:
validate_hostname(args.name)
name: str = args.name
repo = Path(args.repo_root).resolve()
flake = repo / "flake.nix"
hosts_dir = repo / "hosts" / args.name
hosts_dir = repo / "hosts" / name
if not flake.is_file():
die(f"flake.nix not found at {flake}")
raise RegisterError(f"flake.nix not found at {flake}")
# An existing but EMPTY directory is debris from an earlier failed run.
reuse_empty_dir = False
if hosts_dir.exists():
die(f"hosts/{args.name} already exists")
if host_in_flake(flake, args.name):
die(f"host `{args.name}` already defined in {flake} — refusing to touch anything")
if hosts_dir.is_dir() and not any(hosts_dir.iterdir()):
reuse_empty_dir = True
warn(f"hosts/{name} exists but is empty (leftover from a failed run); reusing it")
else:
raise RegisterError(f"hosts/{name} already exists and is not empty; refusing to touch it")
# ---- Phase 1: compute and validate everything in memory. ----
old_src = read_text_exact(flake)
try:
existing = nixflake.find_hosts(old_src)
if args.no_template:
template = None
elif args.template:
template = args.template
else:
template = existing[0].name if existing else None
edit = plan_flake_edit(old_src, name, template)
verify_edit(old_src, edit.new_src, name)
except FlakeError as e:
raise RegisterError(f"cannot edit {flake}: {e}") from e
nix_parse_check(edit.new_src)
default_nix = render(DEFAULT_NIX_TEMPLATE, name=name)
hardware_nix = render(PLACEHOLDER_HARDWARE, name=name)
template_host = find_template_host(flake)
log(f"repo: {repo}")
log(f"new host: {args.name}")
log(f"template host: {template_host or '<none, using default block>'}")
log(f"new host: {name}")
log(f"template host: {edit.template_used or '<none, using built-in default entry>'}")
if existing and not edit.template_used:
warn("flake.nix has hosts but none were cloned; double-check the new entry matches your conventions")
for rel in missing_template_imports(repo, default_nix):
warn(f"generated default.nix imports ../../{rel}, which does not exist in this repo")
if edit.stale_template_lines:
warn(f"cloned entry still mentions `{edit.template_used}` on these lines; review them:")
for ln in edit.stale_template_lines:
print(f" {ln}", file=sys.stderr)
if args.dry_run:
warn("dry-run: nothing written")
return 0
# Scaffold filesystem.
hosts_dir.mkdir(parents=True)
(hosts_dir / "default.nix").write_text(DEFAULT_NIX_TEMPLATE.format(name=args.name))
(hosts_dir / "hardware.nix").write_text(PLACEHOLDER_HARDWARE.format(name=args.name))
log(f"created hosts/{args.name}/default.nix")
log(f"created hosts/{args.name}/hardware.nix (placeholder)")
# ---- Phase 2: write, rolling back on any failure. ----
created_files: list[Path] = []
created_dir = False
try:
if not reuse_empty_dir:
hosts_dir.mkdir(parents=True)
created_dir = True
for fname, body in (("default.nix", default_nix), ("hardware.nix", hardware_nix)):
target = hosts_dir / fname
create_new_file(target, body)
created_files.append(target)
log(f"created hosts/{name}/default.nix")
log(f"created hosts/{name}/hardware.nix (placeholder)")
# Edit flake.nix.
add_to_flake(flake, args.name, template_host=template_host)
log(f"added `{args.name}` entry to flake.nix")
atomic_replace(flake, edit.new_src) # last: the only step that mutates an existing file
log(f"added `{name}` entry to flake.nix")
except BaseException:
for f in reversed(created_files):
f.unlink(missing_ok=True)
if created_dir:
try:
hosts_dir.rmdir()
except OSError:
pass
warn("failed; rolled back all changes")
raise
print()
log(f"{_C['bold']}Next steps:{_C['reset']}")
print(f" 1. On the new machine (booted from installer or already running):")
print(f" just capture-hardware {args.name}")
print(f" This overwrites hosts/{args.name}/hardware.nix with the real config.")
print(f" 2. Review hosts/{args.name}/default.nix — tweak modules, users, etc.")
print(f" 3. git add hosts/{args.name} flake.nix && git commit")
print(f" 4. Build: just rebuild (when running ON the new host)")
print(
dedent(f"""
Next steps:
1. On the new machine (booted from the installer or already running NixOS):
just capture-hardware {name}
This replaces hosts/{name}/hardware.nix with the real config.
2. Review hosts/{name}/default.nix (modules, users, etc.).
3. Flakes only see git-tracked files, so before building:
git add hosts/{name} flake.nix && git commit
4. Build, when running ON the new host:
just rebuild
"""),
file=sys.stderr,
)
return 0
def main(argv: list[str] | None = None) -> int:
args = parse_args(argv)
try:
return run(args)
except RegisterError as e:
print(f"{_c('31')}[-]{_c('0')} {e}", file=sys.stderr)
return 1
except OSError as e:
print(f"{_c('31')}[-]{_c('0')} {e}", file=sys.stderr)
return 1
except KeyboardInterrupt:
print("\ninterrupted", file=sys.stderr)
return 130
if __name__ == "__main__":
sys.exit(main())