droch-shuil 0.2.0__tar.gz

droch_shuil-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oberon Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

droch_shuil-0.2.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: droch-shuil
+Version: 0.2.0
+Summary: Declarative Linux host configuration on top of pyinfra
+License-Expression: MIT
+Project-URL: Documentation, https://oberon-systems.github.io/droch-shuil/
+Project-URL: Source, https://github.com/oberon-systems/droch-shuil
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.5
+Requires-Dist: platformdirs>=4.11
+Requires-Dist: pydantic>=2.13
+Requires-Dist: pydantic-settings>=2.15
+Requires-Dist: pyinfra<4,>=3.10
+Requires-Dist: pyrage>=1.4
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: questionary>=2.1
+Dynamic: license-file
+
+# suil
+
+*suil* is the Irish and Scottish Gaelic word for eye or vision, and
+*drochshuil* is the evil eye, the eye of the Fomorian king in the old myths.
+The package is named after it.
+
+suil provisions Linux hosts from declarative data, on top of
+[pyinfra](https://pyinfra.com). A workspace holds the site data and declares
+its modules in `modules.yaml`; suil resolves them into the configuration of
+each node, collects facts, applies only what differs and checks that the node
+converged.
+
+## Install
+
+```bash
+pip install droch-shuil
+```
+
+The package is published as `droch-shuil` and imported as `suil`. It installs
+the same command under two names, `suil` and `droch-shuil`.
+
+## Development
+
+```bash
+make install
+make test
+make lint
+make docs
+```
+
+`make install` creates `.venv`, installs the tooling from `requirements.txt`
+and the pre-commit hooks. Commits go through commitizen: `cz commit`.
+
+## Releases
+
+A `vX.Y.Z` tag that matches the version in `pyproject.toml` builds the sdist
+and the wheel and publishes them to [PyPI](https://pypi.org/project/droch-shuil/).
+The documentation is rebuilt and published to GitHub Pages on every push to
+`main` that changes `docs/`, `README.md` or `mkdocs.yml`.
+
+## License
+
+[MIT](LICENSE)

droch_shuil-0.2.0/README.md

@@ -0,0 +1,43 @@
+# suil
+
+*suil* is the Irish and Scottish Gaelic word for eye or vision, and
+*drochshuil* is the evil eye, the eye of the Fomorian king in the old myths.
+The package is named after it.
+
+suil provisions Linux hosts from declarative data, on top of
+[pyinfra](https://pyinfra.com). A workspace holds the site data and declares
+its modules in `modules.yaml`; suil resolves them into the configuration of
+each node, collects facts, applies only what differs and checks that the node
+converged.
+
+## Install
+
+```bash
+pip install droch-shuil
+```
+
+The package is published as `droch-shuil` and imported as `suil`. It installs
+the same command under two names, `suil` and `droch-shuil`.
+
+## Development
+
+```bash
+make install
+make test
+make lint
+make docs
+```
+
+`make install` creates `.venv`, installs the tooling from `requirements.txt`
+and the pre-commit hooks. Commits go through commitizen: `cz commit`.
+
+## Releases
+
+A `vX.Y.Z` tag that matches the version in `pyproject.toml` builds the sdist
+and the wheel and publishes them to [PyPI](https://pypi.org/project/droch-shuil/).
+The documentation is rebuilt and published to GitHub Pages on every push to
+`main` that changes `docs/`, `README.md` or `mkdocs.yml`.
+
+## License
+
+[MIT](LICENSE)

droch_shuil-0.2.0/droch_shuil.egg-info/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: droch-shuil
+Version: 0.2.0
+Summary: Declarative Linux host configuration on top of pyinfra
+License-Expression: MIT
+Project-URL: Documentation, https://oberon-systems.github.io/droch-shuil/
+Project-URL: Source, https://github.com/oberon-systems/droch-shuil
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.5
+Requires-Dist: platformdirs>=4.11
+Requires-Dist: pydantic>=2.13
+Requires-Dist: pydantic-settings>=2.15
+Requires-Dist: pyinfra<4,>=3.10
+Requires-Dist: pyrage>=1.4
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: questionary>=2.1
+Dynamic: license-file
+
+# suil
+
+*suil* is the Irish and Scottish Gaelic word for eye or vision, and
+*drochshuil* is the evil eye, the eye of the Fomorian king in the old myths.
+The package is named after it.
+
+suil provisions Linux hosts from declarative data, on top of
+[pyinfra](https://pyinfra.com). A workspace holds the site data and declares
+its modules in `modules.yaml`; suil resolves them into the configuration of
+each node, collects facts, applies only what differs and checks that the node
+converged.
+
+## Install
+
+```bash
+pip install droch-shuil
+```
+
+The package is published as `droch-shuil` and imported as `suil`. It installs
+the same command under two names, `suil` and `droch-shuil`.
+
+## Development
+
+```bash
+make install
+make test
+make lint
+make docs
+```
+
+`make install` creates `.venv`, installs the tooling from `requirements.txt`
+and the pre-commit hooks. Commits go through commitizen: `cz commit`.
+
+## Releases
+
+A `vX.Y.Z` tag that matches the version in `pyproject.toml` builds the sdist
+and the wheel and publishes them to [PyPI](https://pypi.org/project/droch-shuil/).
+The documentation is rebuilt and published to GitHub Pages on every push to
+`main` that changes `docs/`, `README.md` or `mkdocs.yml`.
+
+## License
+
+[MIT](LICENSE)

droch_shuil-0.2.0/droch_shuil.egg-info/SOURCES.txt

@@ -0,0 +1,102 @@
+LICENSE
+README.md
+pyproject.toml
+droch_shuil.egg-info/PKG-INFO
+droch_shuil.egg-info/SOURCES.txt
+droch_shuil.egg-info/dependency_links.txt
+droch_shuil.egg-info/entry_points.txt
+droch_shuil.egg-info/requires.txt
+droch_shuil.egg-info/top_level.txt
+suil/__init__.py
+suil/__main__.py
+suil/cli.py
+suil/config.py
+suil/deployment.py
+suil/directory.py
+suil/errors.py
+suil/log.py
+suil/testing.py
+suil/tui.py
+suil/workspace.py
+suil/sdk/__init__.py
+suil/sdk/errors.py
+suil/sdk/facter.py
+suil/sdk/module.py
+suil/sdk/protocols.py
+suil/sdk/libs/__init__.py
+suil/sdk/libs/config/__init__.py
+suil/sdk/libs/config/expand_lookups.py
+suil/sdk/libs/config/strip_secrets.py
+suil/sdk/libs/host/__init__.py
+suil/sdk/libs/host/put_content.py
+suil/sdk/libs/host/run_command.py
+suil/sdk/libs/host/sudo_password.py
+suil/sdk/libs/inventory/__init__.py
+suil/sdk/libs/inventory/lookup.py
+suil/sdk/libs/manifest/__init__.py
+suil/sdk/libs/manifest/check_manifest.py
+suil/sdk/libs/manifest/get_checkout.py
+suil/sdk/libs/manifest/get_latest_tag.py
+suil/sdk/libs/manifest/get_revision.py
+suil/sdk/libs/manifest/get_roots.py
+suil/sdk/libs/manifest/install_repo.py
+suil/sdk/libs/manifest/read_manifest.py
+suil/sdk/libs/manifest/run_git.py
+suil/sdk/libs/manifest/set_versions.py
+suil/sdk/libs/merge/__init__.py
+suil/sdk/libs/merge/deep.py
+suil/sdk/libs/module/__init__.py
+suil/sdk/libs/module/check_facter.py
+suil/sdk/libs/module/collect_facts.py
+suil/sdk/libs/module/collect_files.py
+suil/sdk/libs/module/diff_configs.py
+suil/sdk/libs/module/diff_names.py
+suil/sdk/libs/module/diff_touches.py
+suil/sdk/libs/module/file_digest.py
+suil/sdk/libs/module/file_needs_write.py
+suil/sdk/libs/module/get_config.py
+suil/sdk/libs/module/get_defaults.py
+suil/sdk/libs/module/get_facts.py
+suil/sdk/libs/module/get_files.py
+suil/sdk/libs/module/get_names.py
+suil/sdk/libs/module/get_order.py
+suil/sdk/libs/module/get_public.py
+suil/sdk/libs/module/get_requires.py
+suil/sdk/libs/module/get_signature.py
+suil/sdk/libs/module/load_class.py
+suil/sdk/libs/module/load_code.py
+suil/sdk/libs/module/run_check.py
+suil/sdk/libs/module/run_code.py
+suil/sdk/libs/module/run_drift.py
+suil/sdk/libs/module/validate_file.py
+suil/sdk/libs/node/__init__.py
+suil/sdk/libs/node/collect.py
+suil/sdk/libs/node/get_role.py
+suil/sdk/libs/node/probe_os.py
+suil/sdk/libs/pyinfra/__init__.py
+suil/sdk/libs/pyinfra/make_inventory.py
+suil/sdk/libs/pyinfra/run_state.py
+suil/sdk/libs/role/__init__.py
+suil/sdk/libs/role/collect.py
+suil/sdk/libs/role/get_nodes.py
+suil/sdk/libs/run/__init__.py
+suil/sdk/libs/run/build_directory.py
+suil/sdk/libs/string/__init__.py
+suil/sdk/libs/string/decrypt.py
+suil/sdk/libs/string/encrypt.py
+suil/sdk/libs/yaml/__init__.py
+suil/sdk/libs/yaml/load.py
+suil/sdk/libs/yaml/load_data.py
+suil/sdk/models/__init__.py
+suil/sdk/models/config.py
+suil/sdk/models/context.py
+suil/sdk/models/encrypted.py
+suil/sdk/models/lookup.py
+suil/sdk/models/manifest.py
+suil/sdk/models/repo.py
+suil/sdk/models/root.py
+suil/sdk/models/secret.py
+suil/sdk/models/tagged.py
+tests/test_modules_import_sdk.py
+tests/test_modules_read_facts.py
+tests/test_workspace.py

droch_shuil-0.2.0/droch_shuil.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

droch_shuil-0.2.0/droch_shuil.egg-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+droch-shuil = suil.cli:cli
+suil = suil.cli:cli
+
+[pytest11]
+suil = suil.testing

droch_shuil-0.2.0/droch_shuil.egg-info/requires.txt

@@ -0,0 +1,8 @@
+click>=8.5
+platformdirs>=4.11
+pydantic>=2.13
+pydantic-settings>=2.15
+pyinfra<4,>=3.10
+pyrage>=1.4
+PyYAML>=6.0
+questionary>=2.1

droch_shuil-0.2.0/droch_shuil.egg-info/top_level.txt

@@ -0,0 +1 @@
+suil

droch_shuil-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "droch-shuil"
+version = "0.2.0"
+description = "Declarative Linux host configuration on top of pyinfra"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "click>=8.5",
+    "platformdirs>=4.11",
+    "pydantic>=2.13",
+    "pydantic-settings>=2.15",
+    "pyinfra>=3.10,<4",
+    "pyrage>=1.4",
+    "PyYAML>=6.0",
+    "questionary>=2.1",
+]
+
+[project.urls]
+Documentation = "https://oberon-systems.github.io/droch-shuil/"
+Source = "https://github.com/oberon-systems/droch-shuil"
+
+# PyPI refuses `suil` as too close to an existing name; the commands keep it.
+[project.scripts]
+suil = "suil.cli:cli"
+droch-shuil = "suil.cli:cli"
+
+# A module's tests get the fixtures without a conftest of their own, wherever
+# they live. Registered at install time, so `pip install -e .` again.
+[project.entry-points.pytest11]
+suil = "suil.testing"
+
+[tool.setuptools.packages.find]
+include = ["suil*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

droch_shuil-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

droch_shuil-0.2.0/suil/__init__.py

@@ -0,0 +1 @@
+"""Suil: declarative Linux host configuration on top of pyinfra."""

droch_shuil-0.2.0/suil/__main__.py

@@ -0,0 +1,4 @@
+from suil.cli import cli
+
+if __name__ == '__main__':
+    cli()

droch_shuil-0.2.0/suil/cli.py

@@ -0,0 +1,186 @@
+import logging
+
+import click
+import yaml
+
+from suil.config import Config
+from suil.deployment import Deployment
+from suil.directory import Directory, counted
+from suil.errors import errors_handler
+from suil.log import OK, log_setup
+from suil.sdk.libs.manifest import check_manifest, get_latest_tag, install_repo, read_manifest, set_versions
+from suil.sdk.libs.module import get_order, get_requires
+from suil.sdk.libs.string import decrypt, encrypt
+from suil.tui import tui
+from suil.workspace import Workspace
+
+log = logging.getLogger(__name__)
+
+
+def _selection(function):
+    function = click.option('--role', help='Role to act on.')(function)
+    function = click.option('--node', help='Node to act on.')(function)
+
+    return function
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def main(ctx):
+    """Suil: an infrastructure manager."""
+    workspace = Workspace()
+    settings = Config()
+    log_setup(settings.log_color)
+
+    if ctx.invoked_subcommand is None:
+        tui(workspace, settings)
+        return
+
+    ctx.obj = (workspace, settings)
+
+
+@main.command()
+@_selection
+@click.option('--force', is_flag=True, help='Run the modules even when nothing changed.')
+@click.option('--confirm', is_flag=True, help='Apply; without it the run is only shown.')
+@click.option('--dry-run', is_flag=True, help='Show what would change and stop.')
+@click.pass_obj
+def apply(obj, role, node, force, confirm, dry_run):
+    """Apply the modules of the selected role or node."""
+    workspace, settings = obj
+    directory = Directory(workspace, role=role, node=node)
+    directory.show()
+
+    if not confirm:
+        log.warning('not applied: give --confirm')
+        return
+
+    Deployment(settings, directory, force=force, dry_run=dry_run).run()
+
+
+@main.command()
+@_selection
+@click.pass_obj
+def config(obj, role, node):
+    """Print the run without applying anything."""
+    workspace, settings = obj
+    directory = Directory(workspace, role=role, node=node)
+    deployment = Deployment(settings, directory)
+    directory.show()
+
+    for item in directory.nodes:
+        log.info(f'--- {item.name}')
+        print(yaml.safe_dump(deployment.configs(item)[1], default_flow_style=False, sort_keys=False))
+
+
+@main.command()
+@_selection
+@click.pass_obj
+def facts(obj, role, node):
+    """Collect facts, change nothing."""
+    workspace, settings = obj
+    directory = Directory(workspace, role=role, node=node)
+    deployment = Deployment(settings, directory)
+
+    for item in directory.nodes:
+        _, host, probe = deployment.connect(item)
+        item = directory.probe(item.name, probe['family'], probe['release'])
+        deployment.facts(host, item, *deployment.configs(item))
+
+
+@main.command()
+@click.pass_obj
+def nodes(obj):
+    """List the nodes and the role each declares."""
+    workspace, _ = obj
+
+    for name, role in sorted(Directory(workspace).inventory.items()):
+        log.info(f'{name}  ({role or "no role"})')
+
+
+@main.command()
+@click.pass_obj
+def modules(obj):
+    """List the modules and the requires graph."""
+    workspace, _ = obj
+    roots = _roots(workspace)
+
+    for name, root in sorted(roots.items()):
+        requires = get_requires(root)
+        kind = 'meta' if not (root.path / 'code' / 'main.py').is_file() else 'module'
+        log.info(f'{name}  [{kind}]' + (f'  {root.repo} {root.version}' if root.version else ''))
+
+        if requires:
+            log.info('  requires: ' + ', '.join(requires))
+            log.info('  order:    ' + ' -> '.join(get_order([name], roots)))
+
+
+@main.command()
+@click.pass_obj
+def install(obj):
+    """Clone the Git repositories of modules.yaml into the cache."""
+    workspace, _ = obj
+
+    for repo in read_manifest(workspace.manifest).repos:
+        if not repo.local:
+            installed = install_repo(repo, workspace.cache_dir)
+            log.log(OK, f"{repo.repo} {repo.version}: {'installed' if installed else 'in the cache'}")
+
+
+@main.command()
+@click.pass_obj
+def autoupdate(obj):
+    """Move every version in modules.yaml to the newest tag of its repository."""
+    workspace, _ = obj
+    versions = {}
+
+    for repo in read_manifest(workspace.manifest).repos:
+        if repo.local:
+            continue
+
+        if not (latest := get_latest_tag(repo.repo)):
+            log.warning(f'{repo.repo}: no tags, {repo.version} kept')
+        elif latest != repo.version:
+            log.info(f'{repo.repo}: {repo.version} -> {latest}')
+            versions[repo.repo] = latest
+
+    if versions:
+        workspace.manifest.write_text(set_versions(workspace.manifest.read_text(), versions))
+        log.warning('modules.yaml updated: run suil install')
+    else:
+        log.log(OK, 'modules.yaml is up to date')
+
+
+@main.command()
+@click.pass_obj
+def validate(obj):
+    """Check modules.yaml and every module it declares, without connecting."""
+    workspace, _ = obj
+    log.log(OK, f"modules.yaml: {counted(len(_roots(workspace)), 'module')} valid")
+
+
+@main.command('encrypt')
+@click.argument('value')
+@click.pass_obj
+def encrypt_command(obj, value):
+    """Encrypt a string to SUIL_AGE_RECIPIENT."""
+    _, settings = obj
+    print(f'!ENC[{encrypt(value, settings.age_recipient)}]')
+
+
+@main.command('decrypt')
+@click.argument('value')
+@click.pass_obj
+def decrypt_command(obj, value):
+    """Decrypt a string with SUIL_AGE_KEY."""
+    _, settings = obj
+    print(decrypt(value, settings.age_key))
+
+
+def _roots(workspace):
+    return check_manifest(workspace.manifest, workspace.modules_dir, workspace.cache_dir)
+
+
+@errors_handler
+def cli():
+    main()

droch_shuil-0.2.0/suil/config.py

@@ -0,0 +1,16 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Config(BaseSettings):
+
+    model_config = SettingsConfigDict(env_prefix='SUIL_', env_file='.env')
+
+    # age keys, X25519. The private half decrypts, the public half encrypts.
+    age_key:       str | None = None
+    age_recipient: str | None = None
+
+    # Sudo on the targets. Set it and pyinfra never prompts, mid-run or at all.
+    sudo_password: str | None = None
+
+    # Terminal output
+    log_color: bool = True