keywharf 1.0.1__tar.gz

keywharf-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keywharf
+
+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.

keywharf-1.0.1/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: keywharf
+Version: 1.0.1
+Summary: Manage local SSH config alongside a remote key repository.
+Author: keywharf
+License: MIT
+Keywords: ssh,automation,cli,configuration
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# keywharf
+
+`keywharf` is a Python 3.11+ CLI for selecting remote SSH host definitions into a local desired state, then materializing only manager-owned SSH artifacts.
+
+It manages only:
+
+- one explicit local state file
+- one managed SSH config fragment
+- one managed key directory
+
+It does not take over the user's whole `~/.ssh/config`. Only `install-include` may minimally append one `Include` block to the main SSH config.
+
+## Recommended Workflow
+
+```bash
+keywharf --data-root ~/keywharf init
+keywharf --data-root ~/keywharf pull
+keywharf --data-root ~/keywharf remote host list
+keywharf --data-root ~/keywharf remote host show demo
+keywharf --data-root ~/keywharf remote host add demo --hostname demo.example.com --user fox --identity-file keys/id_demo
+keywharf --data-root ~/keywharf select demo --endpoint public --auth home
+keywharf --data-root ~/keywharf validate
+keywharf --data-root ~/keywharf render
+keywharf --data-root ~/keywharf apply
+keywharf --data-root ~/keywharf install-include
+```
+
+If the manager config lives outside the default workspace root, use `--config <path>` instead of `--data-root`.
+
+## Ownership Boundary
+
+`keywharf` manages:
+
+- `state_path`
+- `managed_config_path`
+- `managed_keys_dir`
+
+`keywharf` does not manage:
+
+- unrelated `Host` entries in the main SSH config
+- `Match` blocks
+- other `Include` lines
+- user comments and ordering in the main SSH config
+
+## Workspace Discovery
+
+Workspace resolution is explicit and predictable:
+
+1. `--data-root`
+2. `KEYWHARF_DATA_ROOT`
+3. current directory, if it already contains both the `KEYWHARF_DATA_ROOT` marker and `config.json`
+4. nearest ancestor workspace marker
+5. `~/keywharf`
+6. fail with the checked candidate paths listed
+
+`keywharf init` creates the marker, `config.json`, `state/state.json`, directory skeleton, and small workspace text files from package resources.
+
+## Formal Config And Templates
+
+Manager config is a formal runtime config:
+
+- defaults come from `pkg://keywharf/config_defaults/manager.json`
+- file or mapping input is override only
+- defaults and overrides are deep-merged before Pydantic v2 validation
+- runtime path resolution is separate from raw config loading
+
+Resource roles are intentionally split:
+
+- `config_defaults/*.json`: formal defaults for manager config
+- `templates/*.json`: structured starter data such as the empty state file
+- `templates/*.j2`: human-facing text templates such as workspace `README.md`, workspace `.gitignore`, and the include block text
+
+## Remote Host CRUD
+
+`remote host` edits only the local checkout copy of the remote repository config:
+
+- `remote host list`
+- `remote host show`
+- `remote host add`
+- `remote host update`
+- `remote host remove`
+
+These commands do not commit, push, or mutate git metadata. They perform structured JSON reads/writes, preserve array order, and revalidate the resulting host set before writing.
+
+This round only adds Host-level CRUD. `ExtraConfig` is preserved and rendered, but it is not exposed as a CLI editor yet.
+
+## `--sudo`
+
+Mutating commands support `--sudo`:
+
+- `init`
+- `pull`
+- `select`
+- `deselect`
+- `apply`
+- `install-include`
+- `remote host add`
+- `remote host update`
+- `remote host remove`
+
+Privilege handling is centralized:
+
+- normal writable paths run without sudo
+- unwritable paths fail fast with concrete path-based reasons
+- `--sudo` re-execs the full command through `sudo`
+
+## Installation
+
+```bash
+python3.11 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+pytest
+```
+
+Runtime requirements:
+
+- Python 3.11+
+- system `git`
+
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md)
+- [`docs/configuration.md`](docs/configuration.md)
+- [`docs/cli.md`](docs/cli.md)
+- [`docs/development.md`](docs/development.md)
+- [`CHANGELOG.md`](CHANGELOG.md)

keywharf-1.0.1/README.md

@@ -0,0 +1,127 @@
+# keywharf
+
+`keywharf` is a Python 3.11+ CLI for selecting remote SSH host definitions into a local desired state, then materializing only manager-owned SSH artifacts.
+
+It manages only:
+
+- one explicit local state file
+- one managed SSH config fragment
+- one managed key directory
+
+It does not take over the user's whole `~/.ssh/config`. Only `install-include` may minimally append one `Include` block to the main SSH config.
+
+## Recommended Workflow
+
+```bash
+keywharf --data-root ~/keywharf init
+keywharf --data-root ~/keywharf pull
+keywharf --data-root ~/keywharf remote host list
+keywharf --data-root ~/keywharf remote host show demo
+keywharf --data-root ~/keywharf remote host add demo --hostname demo.example.com --user fox --identity-file keys/id_demo
+keywharf --data-root ~/keywharf select demo --endpoint public --auth home
+keywharf --data-root ~/keywharf validate
+keywharf --data-root ~/keywharf render
+keywharf --data-root ~/keywharf apply
+keywharf --data-root ~/keywharf install-include
+```
+
+If the manager config lives outside the default workspace root, use `--config <path>` instead of `--data-root`.
+
+## Ownership Boundary
+
+`keywharf` manages:
+
+- `state_path`
+- `managed_config_path`
+- `managed_keys_dir`
+
+`keywharf` does not manage:
+
+- unrelated `Host` entries in the main SSH config
+- `Match` blocks
+- other `Include` lines
+- user comments and ordering in the main SSH config
+
+## Workspace Discovery
+
+Workspace resolution is explicit and predictable:
+
+1. `--data-root`
+2. `KEYWHARF_DATA_ROOT`
+3. current directory, if it already contains both the `KEYWHARF_DATA_ROOT` marker and `config.json`
+4. nearest ancestor workspace marker
+5. `~/keywharf`
+6. fail with the checked candidate paths listed
+
+`keywharf init` creates the marker, `config.json`, `state/state.json`, directory skeleton, and small workspace text files from package resources.
+
+## Formal Config And Templates
+
+Manager config is a formal runtime config:
+
+- defaults come from `pkg://keywharf/config_defaults/manager.json`
+- file or mapping input is override only
+- defaults and overrides are deep-merged before Pydantic v2 validation
+- runtime path resolution is separate from raw config loading
+
+Resource roles are intentionally split:
+
+- `config_defaults/*.json`: formal defaults for manager config
+- `templates/*.json`: structured starter data such as the empty state file
+- `templates/*.j2`: human-facing text templates such as workspace `README.md`, workspace `.gitignore`, and the include block text
+
+## Remote Host CRUD
+
+`remote host` edits only the local checkout copy of the remote repository config:
+
+- `remote host list`
+- `remote host show`
+- `remote host add`
+- `remote host update`
+- `remote host remove`
+
+These commands do not commit, push, or mutate git metadata. They perform structured JSON reads/writes, preserve array order, and revalidate the resulting host set before writing.
+
+This round only adds Host-level CRUD. `ExtraConfig` is preserved and rendered, but it is not exposed as a CLI editor yet.
+
+## `--sudo`
+
+Mutating commands support `--sudo`:
+
+- `init`
+- `pull`
+- `select`
+- `deselect`
+- `apply`
+- `install-include`
+- `remote host add`
+- `remote host update`
+- `remote host remove`
+
+Privilege handling is centralized:
+
+- normal writable paths run without sudo
+- unwritable paths fail fast with concrete path-based reasons
+- `--sudo` re-execs the full command through `sudo`
+
+## Installation
+
+```bash
+python3.11 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+pytest
+```
+
+Runtime requirements:
+
+- Python 3.11+
+- system `git`
+
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md)
+- [`docs/configuration.md`](docs/configuration.md)
+- [`docs/cli.md`](docs/cli.md)
+- [`docs/development.md`](docs/development.md)
+- [`CHANGELOG.md`](CHANGELOG.md)

keywharf-1.0.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keywharf"
+dynamic = ["version"]
+description = "Manage local SSH config alongside a remote key repository."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "keywharf" }]
+license = { text = "MIT" }
+keywords = ["ssh", "automation", "cli", "configuration"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "jinja2>=3.1,<4",
+    "pydantic>=2.7,<3",
+    "rich>=13",
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "ruff>=0.5",
+    "mypy>=1.8",
+]
+
+[project.scripts]
+keywharf = "keywharf.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+license-files = ["LICENSE"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["keywharf*"]
+
+[tool.setuptools.package-data]
+keywharf = ["config_defaults/**/*.json", "templates/**/*.json", "templates/**/*.j2"]
+
+[tool.setuptools.dynamic]
+version = {attr = "keywharf.version.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

keywharf-1.0.1/setup.cfg

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

keywharf-1.0.1/src/keywharf/__init__.py

@@ -0,0 +1,3 @@
+"""keywharf package."""
+
+__all__: list[str] = []

keywharf-1.0.1/src/keywharf/__main__.py

@@ -0,0 +1,11 @@
+"""Run the keywharf CLI."""
+
+from keywharf.cli import main as cli_main
+
+
+def main() -> None:
+    cli_main()
+
+
+if __name__ == "__main__":
+    main()

keywharf-1.0.1/src/keywharf/cli.py

@@ -0,0 +1,75 @@
+"""CLI entrypoint."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from keywharf.commands import register
+from keywharf.commands.context import build_cli_state
+from keywharf.domain.errors import KeywharfError
+from keywharf.version import __version__
+
+
+app = typer.Typer(
+    name="keywharf",
+    help="Select remote SSH hosts into local desired state, then render/apply keywharf owned SSH config fragments.",
+    invoke_without_command=True,
+)
+
+
+@app.callback()
+def callback(
+    ctx: typer.Context,
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to the keywharf config.json file (defaults to resolved data root/config.json).",
+        dir_okay=False,
+        exists=False,
+        readable=True,
+    ),
+    data_root: Path | None = typer.Option(
+        None,
+        "--data-root",
+        help="Explicit keywharf workspace root.",
+        file_okay=False,
+        dir_okay=True,
+        exists=False,
+        readable=True,
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show version and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+    ctx.obj = build_cli_state(
+        config,
+        data_root.expanduser().resolve() if data_root is not None else None,
+    )
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+register(app)
+
+
+def main() -> None:
+    try:
+        app()
+    except KeywharfError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+
+
+if __name__ == "__main__":
+    main()

keywharf-1.0.1/src/keywharf/commands/__init__.py

@@ -0,0 +1,15 @@
+"""Typer command registration."""
+
+from __future__ import annotations
+
+import typer
+
+from keywharf.commands import apply, deselect, init, install_include, local, pull, render, select, validate
+from keywharf.commands.remote.group import app as remote_app
+
+
+def register(app: typer.Typer) -> None:
+    for module in [init, pull, validate, render, apply, install_include, select, deselect]:
+        module.register(app)
+    app.add_typer(local.app, name="local")
+    app.add_typer(remote_app, name="remote")

keywharf-1.0.1/src/keywharf/commands/_invocation.py

@@ -0,0 +1,154 @@
+"""Canonical CLI invocation helpers for retry hints and sudo re-exec."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+import shlex
+import sys
+from typing import Any, Mapping
+
+import click
+from click.core import ParameterSource
+
+
+_AUTO_EXCLUDED_PARAMETER_NAMES = {"install_completion", "show_completion"}
+_DEFAULT_PARAMETER_SOURCES = {None, ParameterSource.DEFAULT, ParameterSource.DEFAULT_MAP}
+
+
+@dataclass(slots=True)
+class CommandInvocation:
+    """Stable, canonical argv for the current command."""
+
+    argv: list[str]
+
+    def display(self) -> str:
+        return shlex.join(["keywharf", *self.argv])
+
+    def with_sudo_flag(self) -> "CommandInvocation":
+        if "--sudo" in self.argv:
+            return CommandInvocation([*self.argv])
+        return CommandInvocation([*self.argv, "--sudo"])
+
+    def sudo_exec_args(self) -> list[str]:
+        cli_path = Path(sys.executable).resolve().with_name("keywharf")
+        sudo_argv = self.with_sudo_flag().argv
+        if cli_path.exists() and os.access(cli_path, os.X_OK):
+            return ["sudo", str(cli_path), *sudo_argv]
+        return ["sudo", sys.executable, "-m", "keywharf", *sudo_argv]
+
+
+def build_command_invocation(
+    ctx: click.Context,
+    *,
+    overrides: Mapping[str, Any] | None = None,
+    exclude: tuple[str, ...] = ("sudo",),
+) -> CommandInvocation:
+    """Build one canonical argv for the current Click/Typer command context."""
+
+    override_map = dict(overrides or {})
+    excluded_names = set(exclude) | _AUTO_EXCLUDED_PARAMETER_NAMES
+    argv: list[str] = []
+    context_chain = _context_chain(ctx)
+
+    root_ctx = context_chain[0]
+    argv.extend(
+        _serialize_context_params(root_ctx, excluded_names=excluded_names, overrides=override_map)
+    )
+
+    for command_ctx in context_chain[1:]:
+        command_name = command_ctx.info_name or command_ctx.command.name
+        if command_name:
+            argv.append(command_name)
+        argv.extend(
+            _serialize_context_params(
+                command_ctx,
+                excluded_names=excluded_names,
+                overrides=override_map,
+            )
+        )
+
+    return CommandInvocation(argv)
+
+
+def _context_chain(ctx: click.Context) -> list[click.Context]:
+    chain: list[click.Context] = []
+    current: click.Context | None = ctx
+    while current is not None:
+        chain.append(current)
+        current = current.parent
+    chain.reverse()
+    return chain
+
+
+def _serialize_context_params(
+    ctx: click.Context,
+    *,
+    excluded_names: set[str],
+    overrides: Mapping[str, Any],
+) -> list[str]:
+    argv: list[str] = []
+    for parameter in ctx.command.params:
+        if not parameter.expose_value:
+            continue
+        name = parameter.name
+        if name is None or name in excluded_names:
+            continue
+        value = overrides[name] if name in overrides else ctx.params.get(name)
+        if isinstance(parameter, click.Argument):
+            argv.extend(_serialize_argument(value))
+            continue
+        if name not in overrides and ctx.get_parameter_source(name) in _DEFAULT_PARAMETER_SOURCES:
+            continue
+        argv.extend(_serialize_option(parameter, value))
+    return argv
+
+
+def _serialize_argument(value: Any) -> list[str]:
+    return [_serialize_scalar(item) for item in _iter_values(value)]
+
+
+def _serialize_option(parameter: click.Option, value: Any) -> list[str]:
+    if value is None:
+        return []
+
+    if parameter.is_bool_flag:
+        if value:
+            return [parameter.opts[0]]
+        if parameter.secondary_opts:
+            return [parameter.secondary_opts[0]]
+        return []
+
+    if parameter.multiple:
+        argv: list[str] = []
+        for item in _iter_values(value):
+            argv.append(parameter.opts[0])
+            argv.extend(_serialize_composite_value(item))
+        return argv
+
+    return [parameter.opts[0], *_serialize_composite_value(value)]
+
+
+def _serialize_composite_value(value: Any) -> list[str]:
+    return [_serialize_scalar(item) for item in _iter_values(value)]
+
+
+def _iter_values(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, tuple):
+        return list(value)
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def _serialize_scalar(value: Any) -> str:
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, Enum):
+        return str(value.value)
+    return str(value)
+