nullforge 0.1.0__py3-none-any.whl

nullforge/smithy/versions.py

@@ -0,0 +1,282 @@
+"""Versions utilities for NullForge."""
+
+import io
+
+from pyinfra.context import host as _ctx_host
+from pyinfra.facts.files import File, FileContents
+from pyinfra.facts.server import Command
+from pyinfra.operations import files
+
+from nullforge.smithy.arch import arch_id
+from nullforge.smithy.http import CURL_ARGS, pin_host_args
+
+
+DEFAULT_VERSIONS = {
+    "wgcf": "2.2.31",
+    "usque": "4.2.1",
+    "doggo": "1.1.7",
+    "nvim": "v0.12.4",
+    "tmux": "3.7b",
+    "curl": "8.21.0",
+    "eza": "v0.23.5",
+    "cloudflared": "2026.7.2",
+    "blocky": "v0.33.0",
+    "direnv": "v2.37.1",
+    "telemt": "3.4.23",
+    "nerd_fonts": "v3.4.0",
+}
+"""Version pins (override per-host via inventory if needed)."""
+
+RELEASE_ASSET_HOST = "release-assets.githubusercontent.com"
+"""Host GitHub redirects `_release_url()` downloads to, and so the one serving the bytes."""
+
+VERSION_COMMANDS: dict[str, str | None] = {
+    "wgcf": None,  # wgcf has no version output; tracked via marker file
+    "usque": "{bin} version",
+    "doggo": "{bin} --version",
+    "nvim": "{bin} --version",
+    "tmux": "{bin} -V",
+    "curl": "{bin} --version",
+    "eza": "{bin} --version",
+    "cloudflared": "{bin} --version",
+    "blocky": "{bin} version",
+    "direnv": "{bin} version",
+    "telemt": "{bin} --version",
+}
+"""How each pinned tool reports its installed version (None = tracked via marker file)."""
+
+VERSION_MARKER_DIR = "/var/lib/nullforge/versions"
+"""Marker files recording installed versions of tools that cannot report their own."""
+
+STATIC_URLS = {
+    "starship_install": "https://starship.rs/install.sh",
+    "docker_install": "https://get.docker.com",
+    "xray_install": "https://github.com/XTLS/Xray-install/raw/main/install-release.sh",
+    "nezha_agent_install": "https://raw.githubusercontent.com/nezhahq/scripts/main/agent/install.sh",
+    "atuin_install": "https://setup.atuin.sh",
+    "zoxide_install": "https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh",
+}
+"""Static endpoints."""
+
+ZSH_PLUGINS: dict[str, str] = {
+    "zsh-autosuggestions": "https://github.com/zsh-users/zsh-autosuggestions",
+    "zsh-syntax-highlighting": "https://github.com/zsh-users/zsh-syntax-highlighting",
+    "ohmyzsh-full-autoupdate": "https://github.com/Pilaton/OhMyZsh-full-autoupdate",
+}
+"""Oh-my-zsh plugins to install (name → git URL)."""
+
+GPG_KEYS = {
+    "haproxy": "https://haproxy.debian.net/haproxy-archive-keyring.gpg",
+    "gvisor": "https://gvisor.dev/archive.key",
+}
+"""GPG keys."""
+
+KEYRING_DIR = "/etc/apt/keyrings"
+"""Keyring directory."""
+
+
+class Versions:
+    def __init__(self, overrides: dict[str, str] | None = None) -> None:
+        if overrides is None:
+            try:
+                overrides = _ctx_host.data.get("versions", {}) or {}
+            except AttributeError:
+                overrides = {}
+        self.versions: dict[str, str] = {**DEFAULT_VERSIONS, **overrides}
+
+    def _arch_select(self, x86_64: str, arm64: str) -> str:
+        arch = arch_id()
+        match arch:
+            case "x86_64":
+                return x86_64
+            case "arm64":
+                return arm64
+            case _:
+                raise ValueError(f"Unsupported architecture: {arch}")
+
+    @staticmethod
+    def _release_url(repo: str, tag: str, asset: str) -> str:
+        """Build a GitHub release asset URL."""
+
+        if tag == "latest":
+            return f"https://github.com/{repo}/releases/latest/download/{asset}"
+        return f"https://github.com/{repo}/releases/download/{tag}/{asset}"
+
+    @staticmethod
+    def release_curl_args() -> dict[str, str]:
+        return {**CURL_ARGS, **pin_host_args(RELEASE_ASSET_HOST)}
+
+    def cloudflared_url(self) -> str:
+        arch = self._arch_select("amd64", "arm64")
+        return self._release_url(
+            "cloudflare/cloudflared",
+            self.versions["cloudflared"],
+            f"cloudflared-linux-{arch}",
+        )
+
+    def blocky_tar(self) -> str:
+        # asset embeds version, so `latest` version will 404
+        version = self.versions["blocky"]
+        arch = self._arch_select("x86_64", "arm64")
+        return self._release_url(
+            "0xERR0R/blocky",
+            version,
+            f"blocky_{version}_Linux_{arch}.tar.gz",
+        )
+
+    def eza_tar(self) -> str:
+        version = self.versions["eza"]
+        arch = self._arch_select("x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu")
+        return self._release_url(
+            "eza-community/eza",
+            version,
+            f"eza_{arch}.tar.gz",
+        )
+
+    def direnv_url(self) -> str:
+        arch = self._arch_select("amd64", "arm64")
+        return self._release_url(
+            "direnv/direnv",
+            self.versions["direnv"],
+            f"direnv.linux-{arch}",
+        )
+
+    def wgcf_url(self) -> str:
+        # asset embeds version, so `latest` version will 404
+        version = self.versions["wgcf"]
+        arch = self._arch_select("amd64", "arm64")
+        tag = "latest" if version == "latest" else f"v{version}"
+        return self._release_url(
+            "ViRb3/wgcf",
+            tag,
+            f"wgcf_{version}_linux_{arch}",
+        )
+
+    def usque_zip(self) -> str:
+        # asset embeds version, so `latest` version will 404
+        version = self.versions["usque"]
+        arch = self._arch_select("amd64", "arm64")
+        tag = "latest" if version == "latest" else f"v{version}"
+        return self._release_url(
+            "Diniboy1123/usque",
+            tag,
+            f"usque_{version}_linux_{arch}.zip",
+        )
+
+    def doggo_tar(self) -> str:
+        # asset embeds version, so `latest` version will 404
+        version = self.versions["doggo"]
+        arch = self._arch_select("x86_64", "arm64")
+        tag = "latest" if version == "latest" else f"v{version}"
+        return self._release_url(
+            "mr-karan/doggo",
+            tag,
+            f"doggo_{version}_Linux_{arch}.tar.gz",
+        )
+
+    def nvim_appimage(self) -> str:
+        arch = self._arch_select("x86_64", "arm64")
+        ext = "appimage" if arch == "x86_64" else "tar.gz"
+        return self._release_url(
+            "neovim/neovim",
+            self.versions["nvim"],
+            f"nvim-linux-{arch}.{ext}",
+        )
+
+    def tmux_tar(self) -> str:
+        # asset embeds version, so `latest` version will 404
+        version = self.versions["tmux"]
+        return self._release_url(
+            "tmux/tmux",
+            version,
+            f"tmux-{version}.tar.gz",
+        )
+
+    def curl_tar(self) -> str:
+        # asset embeds version, so `latest` version will 404
+        version = self.versions["curl"]
+        arch = self._arch_select("x86_64-musl", "aarch64-musl")
+        return self._release_url(
+            "stunnel/static-curl",
+            version,
+            f"curl-linux-{arch}-{version}.tar.xz",
+        )
+
+    def nerd_font_tar(self, family: str) -> str:
+        """Release archive for a single Nerd Font family, named as its base asset name.
+
+        Assets are arch-independent, so there is nothing to select on here.
+        """
+
+        return self._release_url(
+            "ryanoasis/nerd-fonts",
+            self.versions["nerd_fonts"],
+            f"{family}.tar.xz",
+        )
+
+    def telemt_tar(self) -> str:
+        version = self.versions["telemt"]
+        arch = self._arch_select("x86_64", "aarch64")
+        tag = "latest" if version == "latest" else version
+        return self._release_url(
+            "telemt/telemt",
+            tag,
+            f"telemt-{arch}-linux-gnu.tar.gz",
+        )
+
+
+def get_versions() -> Versions:
+    cache_key = "_nullforge_versions"
+    try:
+        if hasattr(_ctx_host.data, cache_key):
+            return getattr(_ctx_host.data, cache_key)
+        v = Versions()
+        setattr(_ctx_host.data, cache_key, v)
+        return v
+    except AttributeError:
+        return Versions()
+
+
+def _marker_path(tool: str) -> str:
+    return f"{VERSION_MARKER_DIR}/{tool}"
+
+
+def _recorded_version(tool: str) -> str | None:
+    """Check version via marker file."""
+
+    lines = _ctx_host.get_fact(FileContents, path=_marker_path(tool))
+    return lines[0].strip() if lines else None
+
+
+def is_pinned_version_installed(tool: str, binary_path: str) -> bool:
+    """Check that binary exists and matches pinned version."""
+
+    if not _ctx_host.get_fact(File, binary_path):
+        return False
+
+    pinned = get_versions().versions[tool]
+    if pinned == "latest":
+        return True
+
+    command = VERSION_COMMANDS[tool]
+    if command is None:
+        return _recorded_version(tool) == pinned
+
+    output = _ctx_host.get_fact(Command, f"{command.format(bin=binary_path)} 2>&1 || true")
+    if not output:
+        return False
+
+    return pinned.removeprefix("v") in output
+
+
+def record_installed_version(tool: str) -> None:
+    """Persist pinned version for tools without version output."""
+
+    files.put(
+        name=f"Record installed {tool} version",
+        src=io.StringIO(f"{get_versions().versions[tool]}\n"),
+        dest=_marker_path(tool),
+        mode="0644",
+        create_remote_dir=True,
+        _sudo=True,
+    )

nullforge/templates/__init__.py

@@ -0,0 +1,32 @@
+"""NullForge templates package."""
+
+from pathlib import Path
+from typing import Any
+
+from pyinfra.api.util import get_template
+
+
+BLOCK_TRIM_ENV: dict[str, Any] = {"trim_blocks": True, "lstrip_blocks": True}
+"""Jinja options for line-oriented templates."""
+
+
+def get_template_path(template_name: str) -> str:
+    """Get the full path to a template file."""
+
+    templates_dir = Path(__file__).parent
+    template_path = templates_dir / template_name
+
+    if not template_path.exists():
+        raise FileNotFoundError(f"Template not found: {template_name}")
+
+    return str(template_path)
+
+
+def render_template(
+    template_name: str,
+    jinja_env_kwargs: dict[str, Any] | None = None,
+    **data: Any,
+) -> str:
+    """Render a template on the control node, for operations that take content instead of a source file."""
+
+    return get_template(get_template_path(template_name), jinja_env_kwargs).render(data)

nullforge/templates/cloudflared/tunnel.yml.j2

@@ -0,0 +1,6 @@
+token: {{ TOKEN }}
+protocol: {{ PROTOCOL }}
+ha-connections: {{ HA_CONNECTIONS }}
+{% if POST_QUANTUM %}
+post-quantum: true
+{% endif %}

nullforge/templates/dns/blocky.yaml.j2

@@ -0,0 +1,11 @@
+upstreams:
+  groups:
+    default:
+{% for upstream in UPSTREAMS %}
+      - {{ upstream }}
+{% endfor %}
+ports:
+  dns: "{{ LISTEN_ENDPOINT }}"
+
+log:
+  level: warn

nullforge/templates/dns/dns.yaml.j2

@@ -0,0 +1,6 @@
+proxy-dns: true
+proxy-dns-port: {{ PORT }}
+proxy-dns-upstream:
+{% for upstream in UPSTREAMS -%}
+  - {{ upstream }}
+{% endfor -%}

nullforge/templates/dns/resolv.conf.j2

@@ -0,0 +1 @@
+nameserver {{ LISTEN_ADDRESS }}

nullforge/templates/dns/resolved.conf.j2

@@ -0,0 +1,13 @@
+[Resolve]
+{% if DOT -%}
+DNS={{ DNS_SERVERS | join(' ') }}
+DNSOverTLS=yes
+{% elif DOH -%}
+DNS=127.0.0.1:5053
+DNSOverTLS=no
+{% endif -%}
+DNSSEC=yes
+LLMNR=no
+Cache=yes
+CacheFromLocalhost=yes
+ReadEtcHosts=yes

nullforge/templates/etc/default/zramswap.j2

@@ -0,0 +1,13 @@
+# Algorithm to use.
+ALGO={{ algo }}
+
+# Specifies the amount of RAM to use as zram swap.
+# If both PERCENT and SIZE are specified, SIZE takes precedence.
+{% if size.endswith('%') %}
+PERCENT={{ size.rstrip('%') }}
+{% else %}
+SIZE={{ size }}
+{% endif %}
+
+# Priority for the zram swap devices.
+PRIORITY=100

nullforge/templates/nvim/nvim_patch.lua.j2

@@ -0,0 +1,5 @@
+vim.api.nvim_create_autocmd("VimLeave", {
+  callback = function()
+    vim.api.nvim_command('set guicursor= | call chansend(v:stderr, "\x1b[ q")')
+  end
+})

nullforge/templates/profiles/direnv.toml

@@ -0,0 +1,2 @@
+[global]
+load_dotenv = true

nullforge/templates/profiles/starship.toml

@@ -0,0 +1,186 @@
+add_newline = true
+
+[aws]
+symbol = "  "
+
+[buf]
+symbol = " "
+
+[bun]
+symbol = " "
+
+[c]
+symbol = " "
+
+[cmake]
+symbol = " "
+
+[conda]
+symbol = " "
+
+[crystal]
+symbol = " "
+
+[dart]
+symbol = " "
+
+[deno]
+symbol = " "
+
+[directory]
+read_only = " 󰌾"
+
+[docker_context]
+symbol = " "
+
+[elixir]
+symbol = " "
+
+[elm]
+symbol = " "
+
+[fennel]
+symbol = " "
+
+[fossil_branch]
+symbol = " "
+
+[gcloud]
+symbol = "  "
+
+[git_branch]
+symbol = " "
+
+[git_commit]
+tag_symbol = '  '
+
+[golang]
+symbol = " "
+
+[guix_shell]
+symbol = " "
+
+[haskell]
+symbol = " "
+
+[haxe]
+symbol = " "
+
+[hg_branch]
+symbol = " "
+
+[hostname]
+ssh_symbol = " "
+
+[java]
+symbol = " "
+
+[julia]
+symbol = " "
+
+[kotlin]
+symbol = " "
+
+[lua]
+symbol = " "
+
+[memory_usage]
+symbol = "󰍛 "
+
+[meson]
+symbol = "󰔷 "
+
+[nim]
+symbol = "󰆥 "
+
+[nix_shell]
+symbol = " "
+
+[nodejs]
+symbol = " "
+
+[ocaml]
+symbol = " "
+
+[os.symbols]
+Alpaquita = " "
+Alpine = " "
+AlmaLinux = " "
+Amazon = " "
+Android = " "
+Arch = " "
+Artix = " "
+CachyOS = " "
+CentOS = " "
+Debian = " "
+DragonFly = " "
+Emscripten = " "
+EndeavourOS = " "
+Fedora = " "
+FreeBSD = " "
+Garuda = "󰛓 "
+Gentoo = " "
+HardenedBSD = "󰞌 "
+Illumos = "󰈸 "
+Kali = " "
+Linux = " "
+Mabox = " "
+Macos = " "
+Manjaro = " "
+Mariner = " "
+MidnightBSD = " "
+Mint = " "
+NetBSD = " "
+NixOS = " "
+Nobara = " "
+OpenBSD = "󰈺 "
+openSUSE = " "
+OracleLinux = "󰌷 "
+Pop = " "
+Raspbian = " "
+Redhat = " "
+RedHatEnterprise = " "
+RockyLinux = " "
+Redox = "󰀘 "
+Solus = "󰠳 "
+SUSE = " "
+Ubuntu = " "
+Unknown = " "
+Void = " "
+Windows = "󰍲 "
+
+[package]
+symbol = "󰏗 "
+
+[perl]
+symbol = " "
+
+[php]
+symbol = " "
+
+[pijul_channel]
+symbol = " "
+
+[python]
+symbol = " "
+
+[rlang]
+symbol = "󰟔 "
+
+[ruby]
+symbol = " "
+
+[rust]
+symbol = "󱘗 "
+
+[scala]
+symbol = " "
+
+[swift]
+symbol = " "
+
+[zig]
+symbol = " "
+
+[gradle]
+symbol = " "

nullforge/templates/profiles/tmux.conf

@@ -0,0 +1,32 @@
+# Support for colors
+set-option -sa terminal-overrides ",xterm*:Tc"
+
+# Toggle mouse on\off
+set-option -g mouse on # Mouse support
+bind-key m \
+    if-shell -F "#{?mouse,1,0}" \
+    "set-option -g mouse off; display-message 'Mouse: OFF'" \
+    "set-option -g mouse on; display-message 'Mouse: ON'"
+
+# Start windows and panes at 1, not 0
+set -g base-index 1
+set -g pane-base-index 1
+set-window-option -g pane-base-index 1
+set-option -g renumber-windows on
+
+# Open pane in same directory
+bind '\' split-window -v -c "#{pane_current_path}"
+bind '%' split-window -h -c "#{pane_current_path}"
+
+# Additions to the status bar
+set -g status-right '#{prefix_highlight} | %a %Y-%m-%d %H:%M'
+
+# Plugins
+set -g @plugin 'tmux-plugins/tpm'
+set -g @plugin 'tmux-plugins/tmux-yank'
+set -g @plugin 'tmux-plugins/tmux-sensible'
+set -g @plugin 'tmux-plugins/tmux-prefix-highlight'
+set -g @plugin 'tmux-plugins/tmux-sessionist'
+set -g @plugin 'tmux-plugins/tmux-resurrect'
+set -g @plugin 'hoshiya4522/tokyo-night-tmux'
+run '~/.tmux/plugins/tpm/tpm'

nullforge/templates/profiles/zshrc.j2

@@ -0,0 +1,46 @@
+export ZSH="{{ home }}/.oh-my-zsh"
+ZSH_THEME=""
+
+case ":$PATH:" in
+  *:/usr/local/bin:*) ;;
+  *) export PATH="/usr/local/sbin:/usr/local/bin:$PATH" ;;
+esac
+
+plugins=(
+    git
+    docker
+    zsh-autosuggestions
+    zsh-syntax-highlighting
+    ohmyzsh-full-autoupdate
+)
+
+zstyle ':omz:update' mode auto
+
+source $ZSH/oh-my-zsh.sh
+
+[ -f "$HOME/.atuin/bin/env" ] && . "$HOME/.atuin/bin/env"
+
+command -v atuin    >/dev/null 2>&1 && eval "$(atuin init zsh)"
+command -v starship >/dev/null 2>&1 && eval "$(starship init zsh)"
+command -v direnv   >/dev/null 2>&1 && eval "$(direnv hook zsh)"
+if command -v zoxide >/dev/null 2>&1; then
+    eval "$(zoxide init zsh)"
+    alias cd='z'
+fi
+
+# Aliases
+alias tailf='tail -f'
+command -v btop  >/dev/null 2>&1 && alias top='btop'
+command -v eza   >/dev/null 2>&1 && alias ls='eza'
+command -v nvim  >/dev/null 2>&1 && alias vim='nvim'
+command -v duf   >/dev/null 2>&1 && alias df='duf'
+command -v doggo >/dev/null 2>&1 && alias dig='doggo'
+# `bat` named `batcat` on Debian/Ubuntu
+# `bat` on RHEL/Fedora
+if command -v batcat >/dev/null 2>&1; then
+    alias cat='batcat --style=plain --paging=never'
+elif command -v bat >/dev/null 2>&1; then
+    alias cat='bat --style=plain --paging=never'
+fi
+
+# Edits between the markers are overwritten on deploy - put host-specific config below the end marker