nullforge 0.1.0__tar.gz → 0.2.0__tar.gz

{nullforge-0.1.0 → nullforge-0.2.0}/.github/workflows/release-please.yaml

@@ -1,9 +1,9 @@
-name: 🤖 Release Please
+name: 🚀 Release
 
 on:
   push:
-    branches:
-      - main
+    branches: [main]
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -14,7 +14,7 @@ concurrency:
 
 jobs:
   release-please:
-    name: 🤖 Release Please
+    name: 🔖 Create release
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:
@@ -78,7 +78,7 @@ jobs:
           path: dist/
 
   attest-artifacts:
-    name: 🔐 Generate artifact attestations
+    name: 🔏 Attest provenance
     needs: [release-please, build]
     if: needs.release-please.outputs.release_created == 'true'
     runs-on: ubuntu-latest
@@ -123,7 +123,7 @@ jobs:
         run: uv publish --trusted-publishing always
 
   finalize-release:
-    name: 🚀 Attach assets and publish release
+    name: 🚀 Attach assets and publish
     needs: [release-please, build, attest-artifacts, publish-pypi]
     if: needs.release-please.outputs.release_created == 'true'
     runs-on: ubuntu-latest
@@ -173,7 +173,7 @@ jobs:
           gh api --method PATCH "repos/${GITHUB_REPOSITORY}/releases/${release_id}" -F draft=false
 
   release-pr:
-    name: 🤖 Open release PR
+    name: 🔁 Open next release PR
     needs: [release-please, finalize-release]
     if: |
       always()

nullforge-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

{nullforge-0.1.0 → nullforge-0.2.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.2.0](https://github.com/wlix13/NullForge/compare/v0.1.0...v0.2.0) (2026-07-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* **cli:** `nullforge cast -i <inventory>` replaces `pyinfra <inventory> nullforge/foundry/full_cast.py` invocation.
+
+### Features
+
+* **cli:** add nullforge CLI ([1f842e3](https://github.com/wlix13/NullForge/commit/1f842e38e1cecffa9ea390a1142d38854c1bde9b))
+
 ## 0.1.0 (2026-07-25)
 
 

nullforge-0.2.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: nullforge
+Version: 0.2.0
+Summary: Forge the server's baseline from null
+Author-email: wlix13 <github@wlix13.dev>
+Maintainer-email: wlix13 <github@wlix13.dev>
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.13
+Requires-Dist: click
+Requires-Dist: pydantic
+Requires-Dist: pyinfra
+Requires-Dist: rich-click
+Description-Content-Type: text/markdown
+
+# NullForge
+
+Forge the server's baseline from null — an infrastructure-as-code framework built on [pyinfra](https://pyinfra.com), themed around a blacksmith's forge: **inventories** define hosts, **molds** shape the configuration, **runes** are idempotent operation sets, the **foundry** casts them onto targets, and the **smithy** holds cross-distro helpers.
+
+> [!WARNING]
+> **NullForge is in active development.** Until the `v1.0.0` release, the CLI, mold schemas and deploy behaviour may change at any time — breaking changes can land in **any** release, including patch versions. Pin an exact version (e.g. `nullforge==0.1.0`) and check the [release notes](https://github.com/wlix13/NullForge/releases) before upgrading.
+
+## Install
+
+```bash
+# Latest release from PyPI — puts `nullforge` on PATH
+uv tool install nullforge
+```
+
+From a source checkout instead, when you want the Python API (`nullforge.molds`, `nullforge.smithy`, ...) or to hack on NullForge itself:
+
+```bash
+uv sync
+```
+
+Every command below then runs as `uv run nullforge ...`.
+
+## CLI
+
+```bash
+# Full cast (all enabled features from the inventory)
+nullforge cast -i nullforge/inventories/example.py
+
+# Cast specific runes, in order (built-in names or paths to custom rune files)
+nullforge cast -i nullforge/inventories/example.py -r warp -r dns
+nullforge cast -i nullforge/inventories/example.py -r ./my_rune.py
+
+# Fresh host without sudo: run the prepare rune as a separate first deploy
+nullforge cast -i nullforge/inventories/example.py -r base --with-prepare
+
+# Connection flags are proxied to pyinfra; unknown options pass through verbatim
+nullforge cast -i nullforge/inventories/example.py -r dns --ssh-user root --ssh-port 2222 --dry -v
+
+# List built-in runes
+nullforge runes
+
+# Shell completion (bash, zsh, fish, powershell) — print or install
+nullforge completion powershell --install
+```
+
+Custom rune files are plain pyinfra deploy modules and can use the full NullForge API, since they run in the same environment.
+
+Note for PowerShell users: quote `@local`-style host specs (`-i "@local"`) — unquoted `@name` is PowerShell splatting syntax and is swallowed by the shell.
+
+## Contributing
+
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the full setup, commit conventions and pull request flow.

nullforge-0.2.0/README.md

@@ -0,0 +1,52 @@
+# NullForge
+
+Forge the server's baseline from null — an infrastructure-as-code framework built on [pyinfra](https://pyinfra.com), themed around a blacksmith's forge: **inventories** define hosts, **molds** shape the configuration, **runes** are idempotent operation sets, the **foundry** casts them onto targets, and the **smithy** holds cross-distro helpers.
+
+> [!WARNING]
+> **NullForge is in active development.** Until the `v1.0.0` release, the CLI, mold schemas and deploy behaviour may change at any time — breaking changes can land in **any** release, including patch versions. Pin an exact version (e.g. `nullforge==0.1.0`) and check the [release notes](https://github.com/wlix13/NullForge/releases) before upgrading.
+
+## Install
+
+```bash
+# Latest release from PyPI — puts `nullforge` on PATH
+uv tool install nullforge
+```
+
+From a source checkout instead, when you want the Python API (`nullforge.molds`, `nullforge.smithy`, ...) or to hack on NullForge itself:
+
+```bash
+uv sync
+```
+
+Every command below then runs as `uv run nullforge ...`.
+
+## CLI
+
+```bash
+# Full cast (all enabled features from the inventory)
+nullforge cast -i nullforge/inventories/example.py
+
+# Cast specific runes, in order (built-in names or paths to custom rune files)
+nullforge cast -i nullforge/inventories/example.py -r warp -r dns
+nullforge cast -i nullforge/inventories/example.py -r ./my_rune.py
+
+# Fresh host without sudo: run the prepare rune as a separate first deploy
+nullforge cast -i nullforge/inventories/example.py -r base --with-prepare
+
+# Connection flags are proxied to pyinfra; unknown options pass through verbatim
+nullforge cast -i nullforge/inventories/example.py -r dns --ssh-user root --ssh-port 2222 --dry -v
+
+# List built-in runes
+nullforge runes
+
+# Shell completion (bash, zsh, fish, powershell) — print or install
+nullforge completion powershell --install
+```
+
+Custom rune files are plain pyinfra deploy modules and can use the full NullForge API, since they run in the same environment.
+
+Note for PowerShell users: quote `@local`-style host specs (`-i "@local"`) — unquoted `@name` is PowerShell splatting syntax and is swallowed by the shell.
+
+## Contributing
+
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the full setup, commit conventions and pull request flow.

nullforge-0.2.0/nullforge/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"  # x-release-please-version

nullforge-0.2.0/nullforge/cli/__main__.py

@@ -0,0 +1,42 @@
+"""NullForge CLI entry point."""
+
+from click.exceptions import Abort, ClickException, Exit
+from rich.console import Console
+
+from nullforge.cli.app import cli
+from nullforge.cli.components.foundry.errors import PyinfraExecutionFailed
+from nullforge.cli.core import Error
+
+
+_err = Console(stderr=True)
+
+
+def main() -> None:
+    try:
+        cli(standalone_mode=False, prog_name="nullforge")
+    except PyinfraExecutionFailed as e:
+        _err.print(f"[red bold]Error:[/red bold] {e}")
+        raise SystemExit(e.returncode)
+    except Error as e:
+        _err.print(f"[red bold]Error:[/red bold] {e}")
+        raise SystemExit(1)
+    except ClickException as e:
+        e.show()
+        raise SystemExit(e.exit_code)
+    except Exit as e:
+        raise SystemExit(e.exit_code)
+    except SystemExit:
+        raise
+    except Abort:
+        _err.print("\n[yellow]Aborted.[/yellow]")
+        raise SystemExit(130)
+    except KeyboardInterrupt:
+        _err.print("\n[yellow]Interrupted.[/yellow]")
+        raise SystemExit(130)
+    except Exception as e:
+        _err.print(f"[red bold]Unexpected error:[/red bold] {e}")
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

nullforge-0.2.0/nullforge/cli/app.py

@@ -0,0 +1,58 @@
+"""NullForge CLI application and root command group."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+import rich_click as click
+
+from nullforge import __version__
+from nullforge.cli.components.completion.component import CompletionComponent
+from nullforge.cli.components.completion.powershell import register_powershell_completion
+from nullforge.cli.components.foundry.component import FoundryComponent
+from nullforge.cli.components.runes.component import RunesComponent
+from nullforge.cli.core import BaseApplication
+from nullforge.cli.display import Display
+
+
+if TYPE_CHECKING:
+    from nullforge.cli.components.completion.controller import CompletionController
+    from nullforge.cli.components.foundry.controller import FoundryController
+    from nullforge.cli.components.runes.controller import RunesController
+
+click.rich_click.USE_RICH_MARKUP = True
+click.rich_click.SHOW_ARGUMENTS = True
+click.rich_click.GROUP_ARGUMENTS_OPTIONS = True
+click.rich_click.USE_MARKDOWN = False
+click.rich_click.STYLE_ERRORS_SUGGESTION = "dim italic"
+click.rich_click.MAX_WIDTH = 100
+
+register_powershell_completion()
+
+
+class NullForgeCli(BaseApplication["NullForgeCli"]):
+    """Main application — component registry and dependency injector."""
+
+    default_components = [FoundryComponent, RunesComponent, CompletionComponent]
+
+    foundry: FoundryController
+    runes: RunesController
+    completion: CompletionController
+
+    def __init__(self) -> None:
+        self.display = Display(self)
+        super().__init__()
+
+
+@click.group(name="nullforge")
+@click.version_option(__version__, "-V", "--version")
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """NullForge — forge the server's baseline from null."""
+
+    app = NullForgeCli()
+    app.cli_root = cast("click.Group", ctx.command)
+    ctx.obj = app
+
+
+NullForgeCli.register_cli(cli)

nullforge-0.2.0/nullforge/cli/components/completion/component.py

@@ -0,0 +1,38 @@
+"""Completion component and CLI commands."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import rich_click as click
+
+from nullforge.cli.core import BaseComponent
+from nullforge.cli.types import ShellType
+
+from .controller import CompletionController
+
+
+if TYPE_CHECKING:
+    from nullforge.cli.app import NullForgeCli
+
+
+class CompletionComponent(BaseComponent["NullForgeCli", CompletionController]):
+    name = "completion"
+    controller_class = CompletionController
+    expose_controller = True
+
+    @classmethod
+    def expose_cli(cls, base: click.Group) -> None:
+        @base.command()
+        @click.argument("shell", type=ShellType())
+        @click.option("--install", is_flag=True, help="Install the script into the shell profile.")
+        @click.pass_obj
+        def completion(app: NullForgeCli, shell: str, install: bool) -> None:
+            """Print or install shell completion (bash, zsh, fish, powershell)."""
+
+            if install:
+                script_path, profile_path = app.completion.install(shell)
+                app.display.completion_installed(script_path, profile_path)
+            else:
+                # Raw stdout on purpose: the rich console would wrap lines and corrupt the script.
+                click.echo(app.completion.script(shell))

nullforge-0.2.0/nullforge/cli/components/completion/controller.py

@@ -0,0 +1,99 @@
+"""Completion controller for script generation and installation."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING, Final
+
+from click.shell_completion import get_completion_class
+
+from nullforge.cli.core import BaseController
+from nullforge.cli.core.errors import Unreachable
+
+from .errors import ProfileNotFound, UnsupportedShell
+
+
+if TYPE_CHECKING:
+    from nullforge.cli.app import NullForgeCli  # noqa: F401
+
+COMPLETE_VAR: Final[str] = "_NULLFORGE_COMPLETE"
+PROG_NAME: Final[str] = "nullforge"
+
+MARKER_BEGIN: Final[str] = "# >>> nullforge completion >>>"
+MARKER_END: Final[str] = "# <<< nullforge completion <<<"
+
+SCRIPT_SUFFIXES: Final[dict[str, str]] = {
+    "bash": "bash",
+    "zsh": "zsh",
+    "fish": "fish",
+    "powershell": "ps1",
+}
+
+
+class CompletionController(BaseController["NullForgeCli"]):
+    def script(self, shell: str) -> str:
+        """Generate the completion script for shell."""
+
+        completion_cls = get_completion_class(shell)
+        if completion_cls is None:
+            raise UnsupportedShell(shell)
+        if self.app.cli_root is None:
+            raise Unreachable()
+        return completion_cls(self.app.cli_root, {}, PROG_NAME, COMPLETE_VAR).source()
+
+    def install(self, shell: str) -> tuple[Path, Path]:
+        """Write the completion script and wire it into the shell profile. Idempotent."""
+
+        script_path = self._script_path(shell)
+        script_path.parent.mkdir(parents=True, exist_ok=True)
+        script_path.write_text(self.script(shell), encoding="utf-8")
+        if shell == "fish":
+            return script_path, script_path  # fish autoloads from completions/, no profile edit
+
+        profile_path = self._profile_path(shell)
+        existing = profile_path.read_text(encoding="utf-8") if profile_path.exists() else ""
+        if MARKER_BEGIN not in existing:
+            profile_path.parent.mkdir(parents=True, exist_ok=True)
+            block = f"\n{MARKER_BEGIN}\n{self._source_line(shell, script_path)}\n{MARKER_END}\n"
+            with profile_path.open("a", encoding="utf-8") as handle:
+                handle.write(block)
+        return script_path, profile_path
+
+    def _script_path(self, shell: str) -> Path:
+        if shell == "fish":
+            return Path.home() / ".config" / "fish" / "completions" / "nullforge.fish"
+        return Path.home() / ".nullforge" / f"completion.{SCRIPT_SUFFIXES[shell]}"
+
+    def _source_line(self, shell: str, script_path: Path) -> str:
+        if shell == "powershell":
+            return f'. "{script_path}"'
+        return f'source "{script_path}"'
+
+    def _profile_path(self, shell: str) -> Path:
+        if shell == "bash":
+            return Path.home() / ".bashrc"
+        if shell == "zsh":
+            return Path.home() / ".zshrc"
+        if shell == "powershell":
+            return self._powershell_profile()
+        raise Unreachable()
+
+    def _powershell_profile(self) -> Path:
+        executable = shutil.which("pwsh") or shutil.which("powershell")
+        if executable is None:
+            raise ProfileNotFound("powershell")
+        try:
+            completed = subprocess.run(  # noqa: S603
+                [executable, "-NoProfile", "-Command", "$PROFILE"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError as exc:
+            raise ProfileNotFound("powershell") from exc
+        profile = completed.stdout.strip()
+        if completed.returncode != 0 or not profile:
+            raise ProfileNotFound("powershell")
+        return Path(profile)

nullforge-0.2.0/nullforge/cli/components/completion/errors.py

@@ -0,0 +1,13 @@
+"""Completion component errors."""
+
+from nullforge.cli.core.errors import Error
+
+
+class UnsupportedShell(Error):
+    def __init__(self, shell: str) -> None:
+        super().__init__(f"Unsupported shell [bold]{shell}[/bold].")
+
+
+class ProfileNotFound(Error):
+    def __init__(self, shell: str) -> None:
+        super().__init__(f"Could not resolve [bold]{shell}[/bold] profile path.")

nullforge-0.2.0/nullforge/cli/components/completion/powershell.py

@@ -0,0 +1,81 @@
+"""PowerShell shell-completion support."""
+
+import os
+import re
+from typing import Final
+
+from click.shell_completion import CompletionItem, ShellComplete, add_completion_class
+
+
+SOURCE_POWERSHELL: Final[str] = """\
+$%(complete_func)s = {
+    param($wordToComplete, $commandAst, $cursorPosition)
+    $env:%(complete_var)s = "powershell_complete"
+    $env:%(complete_var)s_WORDS = $commandAst.ToString()
+    $env:%(complete_var)s_INCOMPLETE = "$wordToComplete"
+    try {
+        & "%(prog_name)s" 2>$null | ForEach-Object {
+            $type, $value, $help = $_ -split "`t", 3
+            if ($type -eq "plain") {
+                $completionText = if ($value -match "\\s") { '"' + $value + '"' } else { $value }
+                $tooltip = if ($help) { $help } else { $value }
+                [System.Management.Automation.CompletionResult]::new(
+                    $completionText, $value, "ParameterValue", $tooltip)
+            }
+            elseif (($type -eq "file") -or ($type -eq "dir")) {
+                Get-ChildItem -Path "$wordToComplete*" -ErrorAction SilentlyContinue | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new(
+                        $_.FullName, $_.Name, "ProviderItem", $_.Name)
+                }
+            }
+        }
+    }
+    finally {
+        Remove-Item Env:%(complete_var)s, Env:%(complete_var)s_WORDS, Env:%(complete_var)s_INCOMPLETE `
+            -ErrorAction SilentlyContinue
+    }
+}
+Register-ArgumentCompleter -Native -CommandName "%(prog_name)s", "%(prog_name)s.exe" `
+    -ScriptBlock $%(complete_func)s
+"""
+
+TOKEN_PATTERN: Final[re.Pattern[str]] = re.compile(r'"[^"]*"?|\'[^\']*\'?|\S+')
+
+
+def split_powershell_line(line: str) -> list[str]:
+    """Split PowerShell command line into words, keeping backslashes literal."""
+
+    tokens: list[str] = []
+    for match in TOKEN_PATTERN.finditer(line):
+        token = match.group()
+        if len(token) >= 2 and token[0] == token[-1] and token[0] in {'"', "'"}:
+            token = token[1:-1]
+        elif token[:1] in {'"', "'"}:
+            token = token[1:]
+        tokens.append(token)
+    return tokens
+
+
+class PowerShellComplete(ShellComplete):
+    """Completion for Windows PowerShell 5+ and pwsh."""
+
+    name = "powershell"
+    source_template = SOURCE_POWERSHELL
+
+    def get_completion_args(self) -> tuple[list[str], str]:
+        line = os.environ.get(f"{self.complete_var}_WORDS", "")
+        incomplete = os.environ.get(f"{self.complete_var}_INCOMPLETE", "")
+        args = split_powershell_line(line)[1:]
+        if incomplete and args and args[-1] == incomplete:
+            args.pop()
+        return args, incomplete
+
+    def format_completion(self, item: CompletionItem) -> str:
+        return f"{item.type}\t{item.value}\t{' '.join((item.help or '').split())}"
+
+
+def register_powershell_completion() -> None:
+    """Register PowerShell completer with click."""
+
+    add_completion_class(PowerShellComplete)
+    add_completion_class(PowerShellComplete, "pwsh")

nullforge-0.2.0/nullforge/cli/components/foundry/component.py

@@ -0,0 +1,137 @@
+"""Foundry component and CLI commands."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import rich_click as click
+
+from nullforge.cli.core import BaseComponent
+from nullforge.cli.types import InventoryType, KeyValueType, RuneType
+
+from .controller import CastOptions, FoundryController
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from nullforge.cli.app import NullForgeCli
+
+
+class FoundryComponent(BaseComponent["NullForgeCli", FoundryController]):
+    name = "foundry"
+    controller_class = FoundryController
+    expose_controller = True
+
+    @classmethod
+    def expose_cli(cls, base: click.Group) -> None:
+        @base.command("cast", context_settings={"ignore_unknown_options": True})
+        @click.option(
+            "-i",
+            "--inventory",
+            required=True,
+            type=InventoryType(),
+            help="Inventory .py file or raw host spec (e.g. @local, host1,host2).",
+        )
+        @click.option(
+            "-r",
+            "--rune",
+            "runes",
+            multiple=True,
+            type=RuneType(),
+            help="Built-in rune name or path to a custom rune file; repeatable, runs in order. "
+            "Omit to run the full cast.",
+        )
+        @click.option(
+            "--with-prepare",
+            is_flag=True,
+            help="Run the prepare rune as a separate first deploy (for fresh hosts without sudo).",
+        )
+        @click.option(
+            "--dry",
+            is_flag=True,
+            help="Don't execute operations on the target hosts.",
+        )
+        @click.option(
+            "--diff",
+            is_flag=True,
+            help="Show file and template differences.",
+        )
+        @click.option(
+            "-y",
+            "--yes",
+            is_flag=True,
+            help="Execute operations without prompting.",
+        )
+        @click.option(
+            "--debug",
+            is_flag=True,
+            help="Print Pyinfra debug logs.",
+        )
+        @click.option(
+            "-v",
+            "verbosity",
+            count=True,
+            help="Print meta (-v), input (-vv) and output (-vvv).",
+        )
+        @click.option(
+            "--ssh-user",
+            help="SSH user to connect as.",
+        )
+        @click.option(
+            "--ssh-port",
+            type=int,
+            help="SSH port to connect to.",
+        )
+        @click.option(
+            "--ssh-key",
+            help="SSH private key file.",
+        )
+        @click.option(
+            "--ssh-key-password",
+            help="SSH private key password.",
+        )
+        @click.option(
+            "--ssh-password",
+            help="SSH password.",
+        )
+        @click.option(
+            "--sudo-user",
+            help="User to sudo as.",
+        )
+        @click.option(
+            "--parallel",
+            type=int,
+            help="Number of hosts to run in parallel.",
+        )
+        @click.option(
+            "--limit",
+            multiple=True,
+            help="Restrict target hosts by name or group.",
+        )
+        @click.option(
+            "--data",
+            multiple=True,
+            type=KeyValueType(),
+            help="Override target data (key=value).",
+        )
+        @click.argument(
+            "pyinfra_args",
+            nargs=-1,
+            type=click.UNPROCESSED,
+        )
+        @click.pass_obj
+        def cast(
+            app: NullForgeCli,
+            inventory: str,
+            runes: tuple[Path, ...],
+            with_prepare: bool,
+            pyinfra_args: tuple[str, ...],
+            **proxied: Any,
+        ) -> None:
+            """Cast runes onto the inventory via Pyinfra.
+
+            Unknown options are passed through to Pyinfra.
+            """
+
+            app.foundry.cast(inventory, runes, with_prepare, CastOptions(extra=pyinfra_args, **proxied))