Files
notfiles/scripts/register-host.py
T

488 lines
17 KiB
Python
Executable File

#!/usr/bin/env python3
"""
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 _c(code: str) -> str:
return f"\033[{code}m" if _COLOR else ""
def log(msg: str) -> None:
print(f"{_c('32')}[+]{_c('0')} {msg}", file=sys.stderr)
def warn(msg: str) -> None:
print(f"{_c('33')}[!]{_c('0')} {msg}", file=sys.stderr)
class RegisterError(Exception):
"""A user-facing failure; message is printed without a traceback."""
# --------------------------------------------------------------------------
# Hostname validation
# --------------------------------------------------------------------------
# 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 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, ... }:
{
imports = [
./hardware.nix
../../modules/core.nix
../../modules/plasma.nix
../../modules/security.nix
];
networking.hostName = "@NAME@";
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
boot.kernelPackages = pkgs.linuxPackages_latest;
networking.networkmanager.enable = true;
programs.zsh.enable = true;
programs.nix-ld.enable = true;
programs.nix-ld.libraries = with pkgs; [
stdenv.cc.cc.lib
zlib
];
users.users.alex = {
isNormalUser = true;
shell = pkgs.zsh;
extraGroups = [ "wheel" "networkmanager" ];
};
programs._1password.enable = true;
programs._1password-gui = {
enable = true;
polkitPolicyOwners = [ "alex" ];
};
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@".
#
# 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@
#
# Until then, this file intentionally does nothing useful and the host
# will not build.
{ 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
# --------------------------------------------------------------------------
# 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.
"""
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}
if name in by_name:
raise RegisterError(f"host `{name}` is already defined in flake.nix")
eol = "\r\n" if "\r\n" in src else "\n"
stale: list[str] = []
tmpl: HostEntry | None = None
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 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,
)
# 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)
# 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:]}"
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}"
)
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}")
# --------------------------------------------------------------------------
# Filesystem
# --------------------------------------------------------------------------
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.
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, starts with a letter)")
p.add_argument("--repo-root", default=".", help="path to the repo root (default: cwd)")
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
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" / name
if not flake.is_file():
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():
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)
log(f"repo: {repo}")
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
# ---- 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)")
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(
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())