loft-cli 0.6.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. loft_cli-0.6.3/PKG-INFO +19 -0
  2. loft_cli-0.6.3/README.md +268 -0
  3. loft_cli-0.6.3/loft_cli/__init__.py +3 -0
  4. loft_cli-0.6.3/loft_cli/_builtins.py +269 -0
  5. loft_cli-0.6.3/loft_cli/addons/__init__.py +12 -0
  6. loft_cli-0.6.3/loft_cli/addons/goss/__init__.py +1 -0
  7. loft_cli-0.6.3/loft_cli/addons/goss/generator.py +202 -0
  8. loft_cli-0.6.3/loft_cli/addons/goss/renderer.py +207 -0
  9. loft_cli-0.6.3/loft_cli/addons/goss/shipper.py +174 -0
  10. loft_cli-0.6.3/loft_cli/agent_installer.py +65 -0
  11. loft_cli-0.6.3/loft_cli/checks/__init__.py +0 -0
  12. loft_cli-0.6.3/loft_cli/checks/compose.py +147 -0
  13. loft_cli-0.6.3/loft_cli/checks/container.py +24 -0
  14. loft_cli-0.6.3/loft_cli/checks/http.py +30 -0
  15. loft_cli-0.6.3/loft_cli/checks/nginx.py +21 -0
  16. loft_cli-0.6.3/loft_cli/checks/ports.py +24 -0
  17. loft_cli-0.6.3/loft_cli/checks/postgres.py +21 -0
  18. loft_cli-0.6.3/loft_cli/checks/ssh.py +66 -0
  19. loft_cli-0.6.3/loft_cli/checks/wireguard.py +21 -0
  20. loft_cli-0.6.3/loft_cli/cli.py +1161 -0
  21. loft_cli-0.6.3/loft_cli/compiler/__init__.py +0 -0
  22. loft_cli-0.6.3/loft_cli/compiler/normalizer.py +420 -0
  23. loft_cli-0.6.3/loft_cli/compiler/parser.py +42 -0
  24. loft_cli-0.6.3/loft_cli/compiler/planner.py +2543 -0
  25. loft_cli-0.6.3/loft_cli/local/__init__.py +0 -0
  26. loft_cli-0.6.3/loft_cli/local/ddl/__init__.py +0 -0
  27. loft_cli-0.6.3/loft_cli/local/ddl/bootstrap_tables.py +75 -0
  28. loft_cli-0.6.3/loft_cli/local/ddl/versionize_system.py +374 -0
  29. loft_cli-0.6.3/loft_cli/local/inventory.py +449 -0
  30. loft_cli-0.6.3/loft_cli/local/inventory_db.py +255 -0
  31. loft_cli-0.6.3/loft_cli/local/keys.py +45 -0
  32. loft_cli-0.6.3/loft_cli/local/remove.py +135 -0
  33. loft_cli-0.6.3/loft_cli/local/ssh_config.py +118 -0
  34. loft_cli-0.6.3/loft_cli/local/tunnel.py +228 -0
  35. loft_cli-0.6.3/loft_cli/local/wireguard_store.py +138 -0
  36. loft_cli-0.6.3/loft_cli/logs/__init__.py +0 -0
  37. loft_cli-0.6.3/loft_cli/logs/reader.py +55 -0
  38. loft_cli-0.6.3/loft_cli/logs/writer.py +58 -0
  39. loft_cli-0.6.3/loft_cli/runtime/__init__.py +0 -0
  40. loft_cli-0.6.3/loft_cli/runtime/agent_transport.py +115 -0
  41. loft_cli-0.6.3/loft_cli/runtime/executor.py +798 -0
  42. loft_cli-0.6.3/loft_cli/runtime/fabric_transport.py +68 -0
  43. loft_cli-0.6.3/loft_cli/runtime/secret_rotation.py +99 -0
  44. loft_cli-0.6.3/loft_cli/runtime/ssh.py +147 -0
  45. loft_cli-0.6.3/loft_cli/runtime/steps/__init__.py +0 -0
  46. loft_cli-0.6.3/loft_cli/runtime/steps/backup.py +72 -0
  47. loft_cli-0.6.3/loft_cli/runtime/steps/bootstrap.py +227 -0
  48. loft_cli-0.6.3/loft_cli/runtime/steps/compose.py +43 -0
  49. loft_cli-0.6.3/loft_cli/runtime/steps/container.py +40 -0
  50. loft_cli-0.6.3/loft_cli/runtime/steps/docker.py +15 -0
  51. loft_cli-0.6.3/loft_cli/runtime/steps/file_template.py +25 -0
  52. loft_cli-0.6.3/loft_cli/runtime/steps/nginx.py +126 -0
  53. loft_cli-0.6.3/loft_cli/runtime/steps/postgres.py +101 -0
  54. loft_cli-0.6.3/loft_cli/runtime/steps/postgres_ensure.py +141 -0
  55. loft_cli-0.6.3/loft_cli/runtime/steps/systemd.py +131 -0
  56. loft_cli-0.6.3/loft_cli/runtime/steps/wireguard.py +76 -0
  57. loft_cli-0.6.3/loft_cli/runtime/transport.py +43 -0
  58. loft_cli-0.6.3/loft_cli/updater.py +208 -0
  59. loft_cli-0.6.3/loft_cli.egg-info/PKG-INFO +19 -0
  60. loft_cli-0.6.3/loft_cli.egg-info/SOURCES.txt +64 -0
  61. loft_cli-0.6.3/loft_cli.egg-info/dependency_links.txt +1 -0
  62. loft_cli-0.6.3/loft_cli.egg-info/entry_points.txt +5 -0
  63. loft_cli-0.6.3/loft_cli.egg-info/requires.txt +15 -0
  64. loft_cli-0.6.3/loft_cli.egg-info/top_level.txt +1 -0
  65. loft_cli-0.6.3/pyproject.toml +39 -0
  66. loft_cli-0.6.3/setup.cfg +4 -0
@@ -0,0 +1,19 @@
1
+ Metadata-Version: 2.4
2
+ Name: loft-cli
3
+ Version: 0.6.3
4
+ Summary: Securely bootstrap Linux servers with auditable plans, generated ops docs, and encrypted local inventory
5
+ Requires-Python: >=3.11
6
+ Requires-Dist: loft-cli-core>=0.5.0
7
+ Requires-Dist: typer[all]>=0.9.0
8
+ Requires-Dist: fabric>=3.2
9
+ Requires-Dist: rich>=13.0
10
+ Requires-Dist: requests>=2.31
11
+ Requires-Dist: pynacl>=1.5
12
+ Provides-Extra: dev
13
+ Requires-Dist: pytest>=7.0; extra == "dev"
14
+ Requires-Dist: pytest-mock>=3.12; extra == "dev"
15
+ Requires-Dist: pyfakefs>=5.3; extra == "dev"
16
+ Requires-Dist: ruff>=0.4; extra == "dev"
17
+ Requires-Dist: black>=24.0; extra == "dev"
18
+ Requires-Dist: build>=1.0; extra == "dev"
19
+ Requires-Dist: pyinstaller>=6.0; extra == "dev"
@@ -0,0 +1,268 @@
1
+ # loft-cli (client)
2
+
3
+ > CLI tool that safely bootstraps Linux servers from YAML specs — compiling specs into reviewable plans, generating ops docs, and executing via the server-side agent.
4
+
5
+ `loft-cli` is the client package. It provides the `loft-cli` CLI command, the three-phase compiler pipeline, transport abstraction for remote execution, local state management, and self-update capabilities.
6
+
7
+ ---
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ pip install loft-cli
13
+ ```
14
+
15
+ Or as part of the monorepo development setup:
16
+
17
+ ```bash
18
+ pip install -e packages/core -e packages/client
19
+ ```
20
+
21
+ ---
22
+
23
+ ## Dependencies
24
+
25
+ - `loft-cli-core>=0.5.0` -- shared models, specs, registries
26
+ - `typer[all]>=0.9.0` -- CLI framework with shell completion
27
+ - `fabric>=3.2` -- SSH transport (paramiko under the hood)
28
+ - `rich>=13.0` -- terminal formatting and progress
29
+ - `requests>=2.31` -- GitHub API calls (self-update, agent-update)
30
+ - `pynacl>=1.5` -- Curve25519 key derivation (WireGuard)
31
+
32
+ ### Dev dependencies
33
+
34
+ `pytest`, `pytest-mock`, `pyfakefs`, `ruff`, `black`, `build`, `pyinstaller`
35
+
36
+ ---
37
+
38
+ ## Module Structure
39
+
40
+ ```
41
+ loft-cli/
42
+ __init__.py Re-exports __version__ from loft-cli-core
43
+ _builtins.py Registers built-in spec kinds via entry_points
44
+ agent_installer.py Agent detection and installation on target servers
45
+ cli.py Typer CLI entry point — all user-facing commands
46
+ updater.py Self-update (client) and agent-update from GitHub Releases
47
+ compiler/
48
+ __init__.py
49
+ normalizer.py Phase 2: resolve paths, keys, secrets into NormalizedContext
50
+ parser.py Phase 1: YAML loading + spec hydration (delegates to core loader)
51
+ planner.py Phase 3: generate Plan (list of Steps) from spec + context
52
+ runtime/
53
+ __init__.py
54
+ agent_transport.py AgentTransport — upload plan, invoke agent, retrieve result
55
+ executor.py Executor — iterates Steps, dispatches via handler registry
56
+ fabric_transport.py FabricTransport — direct SSH execution (legacy, deprecated)
57
+ ssh.py SSH session management helpers
58
+ transport.py Transport protocol — connect(), upload(), exec(), download()
59
+ steps/
60
+ __init__.py
61
+ bootstrap.py Step builders for bootstrap kind (user, SSH, firewall, etc.)
62
+ compose.py Step builders for compose_project kind
63
+ container.py Step builders for Docker container service
64
+ docker.py Step builders for Docker installation service
65
+ file_template.py Step builders for file_template kind
66
+ nginx.py Step builders for Nginx service
67
+ postgres.py Step builders for PostgreSQL service
68
+ wireguard.py Step builders for WireGuard VPN
69
+ systemd.py Step builders for systemd_unit and systemd_timer kinds
70
+ backup.py Step builders for backup_job kind (script generator)
71
+ postgres_ensure.py Step builders for postgres_ensure kind (SQL generators)
72
+ local/
73
+ __init__.py
74
+ ddl/ SQLite DDL scripts for inventory schema
75
+ inventory.py High-level inventory operations
76
+ inventory_db.py Low-level SQLite inventory access (with versionize historization)
77
+ keys.py SSH key generation (ed25519)
78
+ remove.py Host removal orchestration (tunnel + WG state + SSH config + inventory)
79
+ ssh_config.py ~/.ssh/conf.d/ fragment management (with tunnel_comment support)
80
+ tunnel.py WireGuard tunnel management — up, down, status via wg-quick
81
+ wireguard_store.py WireGuard key material storage (~/.wg/loft-cli/)
82
+ checks/
83
+ __init__.py
84
+ compose.py Docker Compose health check
85
+ container.py Docker container health check
86
+ http.py HTTP endpoint check
87
+ nginx.py Nginx service check
88
+ ports.py Port reachability check
89
+ postgres.py PostgreSQL connection check
90
+ ssh.py SSH connectivity check
91
+ wireguard.py WireGuard interface check
92
+ logs/
93
+ __init__.py
94
+ reader.py Read past run logs
95
+ writer.py Write JSON run logs to ~/.loft-cli/runs/
96
+ addons/
97
+ __init__.py
98
+ goss/ Built-in addon: Goss server-state verification
99
+ ```
100
+
101
+ ---
102
+
103
+ ## Compiler Pipeline
104
+
105
+ The compiler transforms YAML specs into executable Plans in three phases:
106
+
107
+ ```
108
+ YAML file
109
+ └─ Parse (parser.py) Load YAML, resolve ${} tokens, hydrate Pydantic model
110
+ └─ Normalize (normalizer.py) Resolve paths, read keys, derive WireGuard pubkeys
111
+ └─ Plan (planner.py) Generate ordered list of Steps with dependencies
112
+ ```
113
+
114
+ Each phase dispatches by `kind` through the registry system. The output is a `Plan` object — an immutable data structure that drives docs, diff, and apply.
115
+
116
+ ---
117
+
118
+ ## Transport Protocol
119
+
120
+ The `Transport` protocol (`transport.py`) decouples the executor from any specific SSH library:
121
+
122
+ ```python
123
+ class Transport(Protocol):
124
+ def connect(self) -> None: ...
125
+ def upload(self, local_path: str, remote_path: str) -> None: ...
126
+ def exec(self, command: str) -> ExecResult: ...
127
+ def download(self, remote_path: str, local_path: str) -> None: ...
128
+ def close(self) -> None: ...
129
+ ```
130
+
131
+ Two implementations:
132
+
133
+ | Transport | Description | Status |
134
+ |---|---|---|
135
+ | `AgentTransport` | Uploads plan + agent binary, invokes `loft-cli-agent apply`, retrieves result | **Primary** (default) |
136
+ | `FabricTransport` | Executes each step via individual SSH commands | **Legacy** (deprecated) |
137
+
138
+ Mode selection: `--mode auto` (default) tries agent first, falls back to client. `--mode agent` forces agent. `--mode client` forces Fabric.
139
+
140
+ ---
141
+
142
+ ## CLI Commands
143
+
144
+ | Command | Description |
145
+ |---|---|
146
+ | `validate <spec>` | Parse and validate a spec file |
147
+ | `plan <spec>` | Show the execution plan |
148
+ | `docs <spec>` | Generate Markdown ops guide |
149
+ | `diff <spec>` | Show what would change on the server |
150
+ | `apply <spec>` | Execute the plan (supports `--dry-run`, `--mode`) |
151
+ | `doctor <spec>` | Detect drift between desired and actual state |
152
+ | `reconcile <spec>` | Re-apply only drifted resources |
153
+ | `tunnel up <host>` | Bring up a WireGuard tunnel for a host |
154
+ | `tunnel down <host>` | Tear down a WireGuard tunnel for a host |
155
+ | `tunnel status` | List all hosts with WireGuard tunnel status |
156
+ | `remove <host>` | Remove all local state for a decommissioned host |
157
+ | `version` | Print client version (add `--host` for agent version) |
158
+ | `update` | Self-update client from GitHub Releases |
159
+ | `agent-update <host>` | Update agent binary on a remote host |
160
+ | `inspect run <id>` | Inspect a past execution run |
161
+ | `inventory list` | List all servers in local inventory |
162
+ | `inventory show <id>` | Show server details |
163
+ | `rotate-secret <spec>` | Rotate a secret (password_env) and re-apply |
164
+
165
+ ---
166
+
167
+ ## Self-Update and Agent Update
168
+
169
+ `updater.py` handles binary updates:
170
+
171
+ - **`loft-cli update`** — downloads the latest client binary from GitHub Releases (matches platform suffix), replaces the running binary
172
+ - **`loft-cli agent-update <host>`** — downloads the latest agent binary, uploads it to the remote server, replaces the running agent
173
+
174
+ The updater looks for assets matching patterns like `loft-cli-linux-amd64` (client) and `agent-linux-amd64` (agent) in the latest GitHub Release.
175
+
176
+ ---
177
+
178
+ ## WireGuard Tunnel Lifecycle (v0.6.3)
179
+
180
+ When `wireguard.enabled: true`, the bootstrap planner inserts a **tunnel safety gate** between `allow_ssh_on_wireguard` and `delete_open_ssh_rule`:
181
+
182
+ 1. `allow_ssh_on_wireguard` — adds UFW rule allowing SSH on WireGuard interface
183
+ 2. `verify_ssh_over_wireguard_tunnel` — **GATE**: brings up the local WireGuard tunnel, verifies SSH through the VPN IP, tears down the tunnel
184
+ 3. `delete_open_ssh_rule` — removes the open-to-all SSH rule (only if gate passed)
185
+
186
+ If the gate fails, the open SSH rule is **not** deleted — the server remains accessible via its public IP.
187
+
188
+ ### SSH Config Integration
189
+
190
+ When WireGuard is enabled, the SSH config fragment uses the server's **VPN IP** as `HostName` instead of the public address. A comment is added noting the tunnel dependency:
191
+
192
+ ```
193
+ # loft-cli managed: myhost
194
+ # Requires: loft-cli tunnel up myhost
195
+ Host myhost
196
+ HostName 10.10.0.1
197
+ User deploy
198
+ Port 2222
199
+ ```
200
+
201
+ ### Tunnel Management (`tunnel.py`)
202
+
203
+ `loft-cli tunnel` subcommands manage client-side WireGuard tunnels via `wg-quick`:
204
+
205
+ - **`tunnel up <host>`** — creates a temporary config from `~/.wg/loft-cli/{host}/client.conf`, invokes `sudo wg-quick up`
206
+ - **`tunnel down <host>`** — recreates the temporary config and invokes `sudo wg-quick down`; falls back to `sudo ip link del` if the config is missing or `wg-quick` fails
207
+ - **`tunnel status`** — scans `~/.wg/loft-cli/*/metadata.json`, cross-references with `wg show interfaces`
208
+
209
+ Interface names use `wg-{host}` (truncated to 15 chars — Linux interface name limit).
210
+
211
+ #### Client-Side Prerequisites
212
+
213
+ WireGuard tunnel commands (`tunnel up`, `tunnel down`, and the tunnel safety gate during `apply`) require:
214
+
215
+ 1. **`wireguard-tools`** installed on the local machine (provides `wg` and `wg-quick`)
216
+ 2. **Passwordless `sudo`** for `wg`, `wg-quick`, and `ip` — these commands manage network interfaces and require root privileges. Without passwordless sudo, `wg-quick` will hang waiting for a password prompt and time out after 30 seconds.
217
+
218
+ To grant passwordless sudo for WireGuard commands only:
219
+
220
+ ```bash
221
+ # /etc/sudoers.d/wireguard-loft-cli
222
+ %sudo ALL=(ALL) NOPASSWD: /usr/bin/wg, /usr/bin/wg-quick, /usr/sbin/ip
223
+ ```
224
+
225
+ ```bash
226
+ sudo visudo -f /etc/sudoers.d/wireguard-loft-cli
227
+ ```
228
+
229
+ ### Host Removal (`remove.py`)
230
+
231
+ `loft-cli remove <host>` tears down all local state in four steps:
232
+
233
+ 1. Tear down active WireGuard tunnel (if running)
234
+ 2. Remove WireGuard local state (`~/.wg/loft-cli/{host}/`)
235
+ 3. Remove SSH conf.d entry (`~/.ssh/conf.d/loft-cli/{host}.conf`)
236
+ 4. Mark inventory record as decommissioned
237
+
238
+ ---
239
+
240
+ ## Built-in Addon Registration
241
+
242
+ `_builtins.py` registers all built-in spec kinds (bootstrap, service, file_template, compose_project, stack, http_check, systemd_unit, systemd_timer, backup_job, postgres_ensure) via the `loft_cli.addons` entry_points group. This happens automatically when the package is imported — no explicit registration calls needed from user code.
243
+
244
+ ---
245
+
246
+ ## Import Boundary
247
+
248
+ `loft-cli` (client) may import from:
249
+ - `loft_cli_core` (shared models, specs, registries)
250
+ - Standard library
251
+ - Third-party dependencies (fabric, requests, pynacl, etc.)
252
+
253
+ `loft-cli` must **never** import from `loft_cli_agent`. The client and agent are independent consumers of core.
254
+
255
+ ---
256
+
257
+ ## Binary Build
258
+
259
+ The client binary is built with PyInstaller:
260
+
261
+ ```bash
262
+ make build-binary
263
+ # or: python scripts/build_binary.py
264
+ ```
265
+
266
+ The client binary includes Fabric, paramiko, sqlcipher3, and all core + client code. It requires `libsqlcipher-dev` (Linux) or `brew install sqlcipher` (macOS) on the build host.
267
+
268
+ Output: `dist/loft-cli`
@@ -0,0 +1,3 @@
1
+ from loft_cli_core import __version__
2
+
3
+ __all__ = ["__version__"]
@@ -0,0 +1,269 @@
1
+ """Register the built-in core spec kinds: bootstrap and service.
2
+
3
+ All imports are lazy (inside function bodies) to avoid circular import
4
+ issues between the compiler, specs, runtime, and registry modules.
5
+ This module is called exactly once by load_addons() at CLI startup.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+
11
+ def _register_builtins() -> None:
12
+ """Register bootstrap and service kinds across all registries."""
13
+ _register_resolvers()
14
+ _register_specs()
15
+ _register_normalizers()
16
+ _register_validators()
17
+ _register_planners()
18
+ _register_step_handlers()
19
+ _register_hooks()
20
+
21
+
22
+ def _register_specs() -> None:
23
+ from loft_cli_core.registry.specs import register_spec_kind
24
+ from loft_cli_core.specs.backup_job_schema import BackupJobSpec
25
+ from loft_cli_core.specs.bootstrap_schema import BootstrapSpec
26
+ from loft_cli_core.specs.compose_project_schema import ComposeProjectSpec
27
+ from loft_cli_core.specs.file_template_schema import FileTemplateSpec
28
+ from loft_cli_core.specs.http_check_schema import HttpCheckSpec
29
+ from loft_cli_core.specs.postgres_ensure_schema import PostgresEnsureSpec
30
+ from loft_cli_core.specs.service_schema import ServiceSpec
31
+ from loft_cli_core.specs.stack_schema import StackSpec
32
+ from loft_cli_core.specs.systemd_timer_schema import SystemdTimerSpec
33
+ from loft_cli_core.specs.systemd_unit_schema import SystemdUnitSpec
34
+
35
+ register_spec_kind("bootstrap", BootstrapSpec)
36
+ register_spec_kind("service", ServiceSpec)
37
+ register_spec_kind("file_template", FileTemplateSpec)
38
+ register_spec_kind("compose_project", ComposeProjectSpec)
39
+ register_spec_kind("stack", StackSpec)
40
+ register_spec_kind("http_check", HttpCheckSpec)
41
+ register_spec_kind("backup_job", BackupJobSpec)
42
+ register_spec_kind("systemd_unit", SystemdUnitSpec)
43
+ register_spec_kind("systemd_timer", SystemdTimerSpec)
44
+ register_spec_kind("postgres_ensure", PostgresEnsureSpec)
45
+
46
+
47
+ def _register_normalizers() -> None:
48
+ from loft_cli.compiler.normalizer import (
49
+ _normalize_backup_job,
50
+ _normalize_bootstrap,
51
+ _normalize_compose_project,
52
+ _normalize_file_template,
53
+ _normalize_http_check,
54
+ _normalize_postgres_ensure,
55
+ _normalize_service,
56
+ _normalize_stack,
57
+ _normalize_systemd_timer,
58
+ _normalize_systemd_unit,
59
+ )
60
+ from loft_cli_core.registry.normalizers import register_normalizer
61
+
62
+ register_normalizer("bootstrap", _normalize_bootstrap)
63
+ register_normalizer("service", _normalize_service)
64
+ register_normalizer("file_template", _normalize_file_template)
65
+ register_normalizer("compose_project", _normalize_compose_project)
66
+ register_normalizer("stack", _normalize_stack)
67
+ register_normalizer("http_check", _normalize_http_check)
68
+ register_normalizer("backup_job", _normalize_backup_job)
69
+ register_normalizer("postgres_ensure", _normalize_postgres_ensure)
70
+ register_normalizer("systemd_unit", _normalize_systemd_unit)
71
+ register_normalizer("systemd_timer", _normalize_systemd_timer)
72
+
73
+
74
+ def _register_validators() -> None:
75
+ from loft_cli_core.registry.validators import register_validator
76
+ from loft_cli_core.specs.validators import (
77
+ validate_backup_job,
78
+ validate_bootstrap,
79
+ validate_compose_project,
80
+ validate_file_template,
81
+ validate_http_check,
82
+ validate_postgres_ensure,
83
+ validate_service,
84
+ validate_stack,
85
+ validate_systemd_timer,
86
+ validate_systemd_unit,
87
+ )
88
+
89
+ register_validator("bootstrap", validate_bootstrap)
90
+ register_validator("service", validate_service)
91
+ register_validator("file_template", validate_file_template)
92
+ register_validator("compose_project", validate_compose_project)
93
+ register_validator("stack", validate_stack)
94
+ register_validator("http_check", validate_http_check)
95
+ register_validator("backup_job", validate_backup_job)
96
+ register_validator("postgres_ensure", validate_postgres_ensure)
97
+ register_validator("systemd_unit", validate_systemd_unit)
98
+ register_validator("systemd_timer", validate_systemd_timer)
99
+
100
+
101
+ def _register_planners() -> None:
102
+ from loft_cli.compiler.planner import (
103
+ _plan_backup_job,
104
+ _plan_bootstrap,
105
+ _plan_compose_project,
106
+ _plan_file_template,
107
+ _plan_http_check,
108
+ _plan_postgres_ensure,
109
+ _plan_service,
110
+ _plan_stack,
111
+ _plan_systemd_timer,
112
+ _plan_systemd_unit,
113
+ )
114
+ from loft_cli_core.registry.planners import register_planner
115
+
116
+ register_planner("bootstrap", _plan_bootstrap)
117
+ register_planner("service", _plan_service)
118
+ register_planner("file_template", _plan_file_template)
119
+ register_planner("compose_project", _plan_compose_project)
120
+ register_planner("stack", _plan_stack)
121
+ register_planner("http_check", _plan_http_check)
122
+ register_planner("backup_job", _plan_backup_job)
123
+ register_planner("postgres_ensure", _plan_postgres_ensure)
124
+ register_planner("systemd_unit", _plan_systemd_unit)
125
+ register_planner("systemd_timer", _plan_systemd_timer)
126
+
127
+
128
+ def _register_step_handlers() -> None:
129
+ from loft_cli_core.plan.models import StepKind
130
+ from loft_cli_core.registry.executors import register_step_handler
131
+
132
+ # Wrap Executor instance methods: handler(executor, step) -> StepResult.
133
+ # The executor's private _execute_* methods are left entirely unchanged.
134
+ register_step_handler(StepKind.GATE, lambda ex, step: ex._execute_gate(step))
135
+ register_step_handler(StepKind.SSH_COMMAND, lambda ex, step: ex._execute_ssh_command(step))
136
+ register_step_handler(StepKind.SSH_UPLOAD, lambda ex, step: ex._execute_ssh_upload(step))
137
+ register_step_handler(
138
+ StepKind.LOCAL_FILE_WRITE, lambda ex, step: ex._execute_local_file_write(step)
139
+ )
140
+ register_step_handler(
141
+ StepKind.LOCAL_DB_WRITE, lambda ex, step: ex._execute_local_db_write(step)
142
+ )
143
+ register_step_handler(StepKind.LOCAL_COMMAND, lambda ex, step: ex._execute_local_command(step))
144
+ register_step_handler(StepKind.VERIFY, lambda ex, step: ex._execute_verify(step))
145
+ register_step_handler(
146
+ StepKind.COMPOSE_HEALTH_CHECK,
147
+ lambda ex, step: ex._execute_compose_health_check(step),
148
+ )
149
+
150
+
151
+ def _register_hooks() -> None:
152
+ from loft_cli.local.inventory import (
153
+ record_backup_job_apply,
154
+ record_bootstrap,
155
+ record_compose_project_apply,
156
+ record_file_template_apply,
157
+ record_http_check_apply,
158
+ record_postgres_ensure_apply,
159
+ record_service_apply,
160
+ record_stack_apply,
161
+ record_systemd_timer_apply,
162
+ record_systemd_unit_apply,
163
+ )
164
+ from loft_cli_core.registry.hooks import KindHooks, register_kind_hooks
165
+
166
+ register_kind_hooks(
167
+ "bootstrap",
168
+ KindHooks(
169
+ needs_key_generation=True,
170
+ ssh_port_fallback=True,
171
+ on_inventory_record=record_bootstrap,
172
+ ),
173
+ )
174
+ register_kind_hooks(
175
+ "service",
176
+ KindHooks(
177
+ needs_key_generation=False,
178
+ ssh_port_fallback=False,
179
+ on_inventory_record=record_service_apply,
180
+ ),
181
+ )
182
+ register_kind_hooks(
183
+ "file_template",
184
+ KindHooks(
185
+ needs_key_generation=False,
186
+ ssh_port_fallback=False,
187
+ on_inventory_record=record_file_template_apply,
188
+ ),
189
+ )
190
+ register_kind_hooks(
191
+ "compose_project",
192
+ KindHooks(
193
+ needs_key_generation=False,
194
+ ssh_port_fallback=False,
195
+ on_inventory_record=record_compose_project_apply,
196
+ ),
197
+ )
198
+ register_kind_hooks(
199
+ "stack",
200
+ KindHooks(
201
+ needs_key_generation=False,
202
+ ssh_port_fallback=False,
203
+ on_inventory_record=record_stack_apply,
204
+ ),
205
+ )
206
+ register_kind_hooks(
207
+ "http_check",
208
+ KindHooks(
209
+ needs_key_generation=False,
210
+ ssh_port_fallback=False,
211
+ on_inventory_record=record_http_check_apply,
212
+ ),
213
+ )
214
+ register_kind_hooks(
215
+ "backup_job",
216
+ KindHooks(
217
+ needs_key_generation=False,
218
+ ssh_port_fallback=False,
219
+ on_inventory_record=record_backup_job_apply,
220
+ ),
221
+ )
222
+ register_kind_hooks(
223
+ "postgres_ensure",
224
+ KindHooks(
225
+ needs_key_generation=False,
226
+ ssh_port_fallback=False,
227
+ on_inventory_record=record_postgres_ensure_apply,
228
+ ),
229
+ )
230
+ register_kind_hooks(
231
+ "systemd_unit",
232
+ KindHooks(
233
+ needs_key_generation=False,
234
+ ssh_port_fallback=False,
235
+ on_inventory_record=record_systemd_unit_apply,
236
+ ),
237
+ )
238
+ register_kind_hooks(
239
+ "systemd_timer",
240
+ KindHooks(
241
+ needs_key_generation=False,
242
+ ssh_port_fallback=False,
243
+ on_inventory_record=record_systemd_timer_apply,
244
+ ),
245
+ )
246
+
247
+
248
+ def _register_resolvers() -> None:
249
+ """Register the built-in value resolvers: 'env' and 'file'."""
250
+ import os
251
+ from pathlib import Path
252
+
253
+ from loft_cli_core.registry.resolvers import register_resolver
254
+
255
+ def _resolve_env(key: str) -> str | None:
256
+ return os.environ.get(key)
257
+
258
+ def _resolve_file(key: str) -> str | None:
259
+ path = Path(key).expanduser()
260
+ if not path.is_absolute():
261
+ path = Path.cwd() / path
262
+ if not path.exists():
263
+ return None
264
+ content = path.read_text(encoding="utf-8")
265
+ # Strip a single trailing newline — common in key files, config files, etc.
266
+ return content.rstrip("\n")
267
+
268
+ register_resolver("env", _resolve_env)
269
+ register_resolver("file", _resolve_file)
@@ -0,0 +1,12 @@
1
+ """loft-cli built-in addons.
2
+
3
+ This package contains optional built-in components that ship with loft-cli
4
+ but are architecturally separate from the core compiler/runtime pipeline.
5
+ Each addon is a self-contained subpackage.
6
+
7
+ Current built-in addons:
8
+ goss/ -- Goss server-state verification (post-bootstrap)
9
+
10
+ External addons are distributed as separate Python packages and discovered
11
+ at runtime via the 'loft_cli.addons' entry_points group.
12
+ """
@@ -0,0 +1 @@
1
+ """Goss integration: generate, ship, run, and render server-spec test results."""