loft-cli-core 0.6.3__py3-none-any.whl

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 (41) hide show
  1. loft_cli_core/__init__.py +1 -0
  2. loft_cli_core/agent_models.py +34 -0
  3. loft_cli_core/agent_paths.py +27 -0
  4. loft_cli_core/plan/__init__.py +0 -0
  5. loft_cli_core/plan/models.py +80 -0
  6. loft_cli_core/plan/render_diff.py +112 -0
  7. loft_cli_core/plan/render_markdown.py +189 -0
  8. loft_cli_core/plan/render_text.py +86 -0
  9. loft_cli_core/policy.py +218 -0
  10. loft_cli_core/registry/__init__.py +108 -0
  11. loft_cli_core/registry/executors.py +31 -0
  12. loft_cli_core/registry/hooks.py +46 -0
  13. loft_cli_core/registry/local_paths.py +147 -0
  14. loft_cli_core/registry/normalizers.py +21 -0
  15. loft_cli_core/registry/planners.py +21 -0
  16. loft_cli_core/registry/resolvers.py +65 -0
  17. loft_cli_core/registry/specs.py +20 -0
  18. loft_cli_core/registry/validators.py +21 -0
  19. loft_cli_core/specs/__init__.py +0 -0
  20. loft_cli_core/specs/backup_job_schema.py +95 -0
  21. loft_cli_core/specs/bootstrap_schema.py +124 -0
  22. loft_cli_core/specs/compose_project_schema.py +93 -0
  23. loft_cli_core/specs/file_template_schema.py +64 -0
  24. loft_cli_core/specs/http_check_schema.py +64 -0
  25. loft_cli_core/specs/loader.py +250 -0
  26. loft_cli_core/specs/postgres_ensure_schema.py +104 -0
  27. loft_cli_core/specs/service_schema.py +114 -0
  28. loft_cli_core/specs/stack_schema.py +74 -0
  29. loft_cli_core/specs/systemd_timer_schema.py +76 -0
  30. loft_cli_core/specs/systemd_unit_schema.py +86 -0
  31. loft_cli_core/specs/validators.py +755 -0
  32. loft_cli_core/state.py +31 -0
  33. loft_cli_core/utils/__init__.py +0 -0
  34. loft_cli_core/utils/files.py +41 -0
  35. loft_cli_core/utils/hashing.py +10 -0
  36. loft_cli_core/utils/os_detect.py +36 -0
  37. loft_cli_core/utils/templates.py +87 -0
  38. loft_cli_core-0.6.3.dist-info/METADATA +10 -0
  39. loft_cli_core-0.6.3.dist-info/RECORD +41 -0
  40. loft_cli_core-0.6.3.dist-info/WHEEL +5 -0
  41. loft_cli_core-0.6.3.dist-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ """Validator registry: maps kind strings to validator callables.
2
+
3
+ A validator callable has the signature:
4
+ (spec: AnySpec) -> list[ValidationIssue]
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Callable
10
+
11
+ _VALIDATOR_REGISTRY: dict[str, Callable] = {}
12
+
13
+
14
+ def register_validator(kind: str, fn: Callable) -> None:
15
+ """Register a validator function for a spec kind."""
16
+ _VALIDATOR_REGISTRY[kind] = fn
17
+
18
+
19
+ def get_validator(kind: str) -> Callable | None:
20
+ """Return the validator for a kind, or None if not registered."""
21
+ return _VALIDATOR_REGISTRY.get(kind)
File without changes
@@ -0,0 +1,95 @@
1
+ """Pydantic v2 models for kind: backup_job YAML specs.
2
+
3
+ Define host-local backup operations with retention semantics.
4
+ The planner generates a backup shell script and a systemd timer
5
+ to run it on schedule.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Literal
11
+
12
+ from pydantic import BaseModel, ConfigDict, Field
13
+
14
+ from loft_cli_core.specs.bootstrap_schema import (
15
+ CheckBlock,
16
+ HostBlock,
17
+ InventoryBlock,
18
+ MetaBlock,
19
+ )
20
+
21
+
22
+ class BackupSource(BaseModel):
23
+ """Source definition for backup operations."""
24
+
25
+ model_config = ConfigDict(extra="forbid")
26
+
27
+ type: Literal["postgres_dump", "directory"]
28
+ # postgres_dump fields
29
+ database: str | None = None
30
+ host: str = "localhost"
31
+ port: int = 5432
32
+ user: str = "postgres"
33
+ docker_exec: str | None = None # container name for docker exec
34
+ # directory fields
35
+ path: str | None = None
36
+
37
+
38
+ class BackupDestination(BaseModel):
39
+ """Destination for backup files."""
40
+
41
+ model_config = ConfigDict(extra="forbid")
42
+
43
+ path: str # local directory for backups
44
+
45
+
46
+ class BackupRetention(BaseModel):
47
+ """Retention policy for backups."""
48
+
49
+ model_config = ConfigDict(extra="forbid")
50
+
51
+ count: int = 7 # keep N most recent backups
52
+
53
+
54
+ class BackupJobConfig(BaseModel):
55
+ """Configuration for a backup job."""
56
+
57
+ model_config = ConfigDict(extra="forbid")
58
+
59
+ name: str # job name (used for script/timer naming)
60
+ source: BackupSource
61
+ destination: BackupDestination
62
+ retention: BackupRetention = Field(default_factory=BackupRetention)
63
+ schedule: str = "*-*-* 02:00:00" # systemd OnCalendar expression
64
+
65
+
66
+ class BackupJobLoginBlock(BaseModel):
67
+ """Login defaults matching post-bootstrap convention (admin@2222)."""
68
+
69
+ model_config = ConfigDict(extra="forbid")
70
+
71
+ user: str = "admin"
72
+ private_key: str = "~/.ssh/id_ed25519"
73
+ password: str | None = None
74
+ port: int = 2222
75
+
76
+
77
+ class BackupJobLocalBlock(BaseModel):
78
+ model_config = ConfigDict(extra="forbid")
79
+
80
+ state_dir: str = ""
81
+ inventory: InventoryBlock = Field(default_factory=InventoryBlock)
82
+
83
+
84
+ class BackupJobSpec(BaseModel):
85
+ """Spec for defining backup operations with retention and scheduling."""
86
+
87
+ model_config = ConfigDict(extra="forbid")
88
+
89
+ kind: Literal["backup_job"]
90
+ meta: MetaBlock
91
+ host: HostBlock
92
+ login: BackupJobLoginBlock = Field(default_factory=BackupJobLoginBlock)
93
+ backup: BackupJobConfig
94
+ local: BackupJobLocalBlock = Field(default_factory=BackupJobLocalBlock)
95
+ checks: list[CheckBlock] = Field(default_factory=list)
@@ -0,0 +1,124 @@
1
+ """Pydantic v2 models for kind: bootstrap YAML specs (RFC section 7)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Literal
6
+
7
+ from pydantic import BaseModel, ConfigDict, Field
8
+
9
+
10
+ class MetaBlock(BaseModel):
11
+ model_config = ConfigDict(extra="forbid")
12
+
13
+ name: str
14
+ description: str = ""
15
+
16
+
17
+ class HostBlock(BaseModel):
18
+ model_config = ConfigDict(extra="forbid")
19
+
20
+ name: str
21
+ address: str
22
+ os_family: str = "debian"
23
+
24
+
25
+ class LoginBlock(BaseModel):
26
+ model_config = ConfigDict(extra="forbid")
27
+
28
+ user: str = "root"
29
+ private_key: str = "~/.ssh/id_ed25519"
30
+ password: str | None = None
31
+ port: int = 22
32
+
33
+
34
+ class AdminUserBlock(BaseModel):
35
+ model_config = ConfigDict(extra="forbid")
36
+
37
+ name: str = "admin"
38
+ groups: list[str] = Field(default_factory=lambda: ["sudo"])
39
+ pubkeys: list[str] = Field(default_factory=list)
40
+
41
+
42
+ class SSHBlock(BaseModel):
43
+ model_config = ConfigDict(extra="forbid")
44
+
45
+ port: int = 2222
46
+ disable_root_login: bool = True
47
+ disable_password_auth: bool = False
48
+
49
+
50
+ class FirewallBlock(BaseModel):
51
+ model_config = ConfigDict(extra="forbid")
52
+
53
+ provider: str = "ufw"
54
+ ssh_only: bool = True
55
+ registered_peers_only: bool = False
56
+ # When wireguard.enabled=true and registered_peers_only=true:
57
+ # SSH is restricted to the declared peer IP only (in on wg0 from {peer_ip} to any port {ssh_port})
58
+ # When wireguard.enabled=true and registered_peers_only=false (default):
59
+ # SSH is restricted to the WireGuard interface only (in on wg0 to any port {ssh_port})
60
+ # Has no effect when wireguard.enabled=false.
61
+
62
+
63
+ class WireGuardBlock(BaseModel):
64
+ model_config = ConfigDict(extra="forbid")
65
+
66
+ enabled: bool = False
67
+ interface: str = "wg0"
68
+ address: str = "" # server VPN interface CIDR, e.g. 10.10.0.1/24
69
+ private_key_file: str = "" # path to server's Curve25519 private key file
70
+ endpoint: str = "" # server's public endpoint, e.g. 192.168.56.10:51820
71
+ peer_address: str = "" # client/peer VPN IP CIDR, e.g. 10.10.0.2/32
72
+ persistent_keepalive: int = 25
73
+
74
+
75
+ class SSHConfigBlock(BaseModel):
76
+ model_config = ConfigDict(extra="forbid")
77
+
78
+ enabled: bool = True
79
+ host_alias: str = ""
80
+ config_path: str = "~/.ssh/config"
81
+ preserve_legacy_entry: bool = False # keep any pre-existing Host entry in main config
82
+
83
+
84
+ class InventoryBlock(BaseModel):
85
+ model_config = ConfigDict(extra="forbid")
86
+
87
+ enabled: bool = True
88
+ db_path: str = "~/.loft-cli/inventory.db"
89
+
90
+
91
+ class LocalBlock(BaseModel):
92
+ model_config = ConfigDict(extra="forbid")
93
+
94
+ state_dir: str = ""
95
+ ssh_config: SSHConfigBlock = Field(default_factory=SSHConfigBlock)
96
+ inventory: InventoryBlock = Field(default_factory=InventoryBlock)
97
+
98
+
99
+ class CheckBlock(BaseModel):
100
+ model_config = ConfigDict(extra="forbid")
101
+
102
+ type: str
103
+ port: int | None = None
104
+ user: str | None = None
105
+ interface: str | None = None
106
+ host: str | None = None
107
+ name: str | None = None # container name for container_running checks
108
+ url: str | None = None # URL for http checks
109
+ expect_status: int | None = None # expected HTTP status code
110
+
111
+
112
+ class BootstrapSpec(BaseModel):
113
+ model_config = ConfigDict(extra="forbid")
114
+
115
+ kind: Literal["bootstrap"]
116
+ meta: MetaBlock
117
+ host: HostBlock
118
+ login: LoginBlock = Field(default_factory=LoginBlock)
119
+ admin_user: AdminUserBlock = Field(default_factory=AdminUserBlock)
120
+ ssh: SSHBlock = Field(default_factory=SSHBlock)
121
+ firewall: FirewallBlock = Field(default_factory=FirewallBlock)
122
+ wireguard: WireGuardBlock = Field(default_factory=WireGuardBlock)
123
+ local: LocalBlock = Field(default_factory=LocalBlock)
124
+ checks: list[CheckBlock] = Field(default_factory=list)
@@ -0,0 +1,93 @@
1
+ """Pydantic v2 models for kind: compose_project YAML specs.
2
+
3
+ Manages Docker Compose projects: upload compose file and templates,
4
+ pull images, start the stack, and verify container health.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Literal
10
+
11
+ from pydantic import BaseModel, ConfigDict, Field
12
+
13
+ from loft_cli_core.specs.bootstrap_schema import (
14
+ CheckBlock,
15
+ HostBlock,
16
+ InventoryBlock,
17
+ MetaBlock,
18
+ )
19
+
20
+
21
+ class ComposeTemplateBlock(BaseModel):
22
+ """A file to render from a Jinja2 template and upload into the project directory."""
23
+
24
+ model_config = ConfigDict(extra="forbid")
25
+
26
+ src: str # local Jinja2 template path (spec-relative)
27
+ dest: str # filename relative to project directory
28
+
29
+
30
+ class ManagedDirectoryBlock(BaseModel):
31
+ """An additional directory to create under (or outside) the project root."""
32
+
33
+ model_config = ConfigDict(extra="forbid")
34
+
35
+ path: str # relative to project directory (or absolute)
36
+ mode: str = "0755"
37
+ owner: str = "root"
38
+ group: str = "root"
39
+
40
+
41
+ class ComposeHealthCheckBlock(BaseModel):
42
+ model_config = ConfigDict(extra="forbid")
43
+
44
+ enabled: bool = True
45
+ timeout: int = 120 # total seconds to wait for all containers healthy
46
+ interval: int = 5 # seconds between polls
47
+
48
+
49
+ class ComposeProjectLoginBlock(BaseModel):
50
+ """Login defaults matching post-bootstrap convention (admin@2222)."""
51
+
52
+ model_config = ConfigDict(extra="forbid")
53
+
54
+ user: str = "admin"
55
+ private_key: str = "~/.ssh/id_ed25519"
56
+ password: str | None = None
57
+ port: int = 2222
58
+
59
+
60
+ class ComposeProjectLocalBlock(BaseModel):
61
+ model_config = ConfigDict(extra="forbid")
62
+
63
+ state_dir: str = ""
64
+ inventory: InventoryBlock = Field(default_factory=InventoryBlock)
65
+
66
+
67
+ class ComposeProjectBlock(BaseModel):
68
+ """The core project configuration."""
69
+
70
+ model_config = ConfigDict(extra="forbid")
71
+
72
+ name: str # docker compose project name
73
+ directory: str # remote base directory (absolute)
74
+ compose_file: str = "docker-compose.yml" # compose filename (in project dir or spec-relative)
75
+ templates: list[ComposeTemplateBlock] = Field(default_factory=list)
76
+ variables: dict[str, str] = Field(default_factory=dict)
77
+ directories: list[ManagedDirectoryBlock] = Field(default_factory=list)
78
+ pull_before_up: bool = True
79
+ healthcheck: ComposeHealthCheckBlock = Field(default_factory=ComposeHealthCheckBlock)
80
+
81
+
82
+ class ComposeProjectSpec(BaseModel):
83
+ """Spec for deploying a Docker Compose project on a remote host."""
84
+
85
+ model_config = ConfigDict(extra="forbid")
86
+
87
+ kind: Literal["compose_project"]
88
+ meta: MetaBlock
89
+ host: HostBlock
90
+ login: ComposeProjectLoginBlock = Field(default_factory=ComposeProjectLoginBlock)
91
+ project: ComposeProjectBlock
92
+ local: ComposeProjectLocalBlock = Field(default_factory=ComposeProjectLocalBlock)
93
+ checks: list[CheckBlock] = Field(default_factory=list)
@@ -0,0 +1,64 @@
1
+ """Pydantic v2 models for kind: file_template YAML specs.
2
+
3
+ Renders managed configuration files from Jinja2 templates and variables.
4
+ Templates are rendered at plan time — the full rendered content appears in
5
+ step.file_content, making plans fully reviewable and deterministic.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Literal
11
+
12
+ from pydantic import BaseModel, ConfigDict, Field
13
+
14
+ from loft_cli_core.specs.bootstrap_schema import (
15
+ CheckBlock,
16
+ HostBlock,
17
+ InventoryBlock,
18
+ MetaBlock,
19
+ )
20
+
21
+
22
+ class TemplateFileBlock(BaseModel):
23
+ """A single managed file rendered from a Jinja2 template."""
24
+
25
+ model_config = ConfigDict(extra="forbid")
26
+
27
+ src: str # local template path (spec-relative)
28
+ dest: str # remote absolute destination path
29
+ mode: str = "0644" # file permissions (octal string)
30
+ owner: str = "root"
31
+ group: str = "root"
32
+
33
+
34
+ class FileTemplateLoginBlock(BaseModel):
35
+ """Login defaults matching post-bootstrap convention (admin@2222)."""
36
+
37
+ model_config = ConfigDict(extra="forbid")
38
+
39
+ user: str = "admin"
40
+ private_key: str = "~/.ssh/id_ed25519"
41
+ password: str | None = None
42
+ port: int = 2222
43
+
44
+
45
+ class FileTemplateLocalBlock(BaseModel):
46
+ model_config = ConfigDict(extra="forbid")
47
+
48
+ state_dir: str = ""
49
+ inventory: InventoryBlock = Field(default_factory=InventoryBlock)
50
+
51
+
52
+ class FileTemplateSpec(BaseModel):
53
+ """Spec for rendering and uploading managed configuration files."""
54
+
55
+ model_config = ConfigDict(extra="forbid")
56
+
57
+ kind: Literal["file_template"]
58
+ meta: MetaBlock
59
+ host: HostBlock
60
+ login: FileTemplateLoginBlock = Field(default_factory=FileTemplateLoginBlock)
61
+ templates: list[TemplateFileBlock] # at least 1 required
62
+ variables: dict[str, str] = Field(default_factory=dict)
63
+ local: FileTemplateLocalBlock = Field(default_factory=FileTemplateLocalBlock)
64
+ checks: list[CheckBlock] = Field(default_factory=list)
@@ -0,0 +1,64 @@
1
+ """Pydantic v2 models for kind: http_check YAML specs.
2
+
3
+ GET-only HTTP readiness probe with configurable retry, backoff, and timeout.
4
+ Usable as a dependency gate in stacks — "proceed only when this URL returns
5
+ the expected status code". No request bodies, no mutations, no response
6
+ templating.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from typing import Literal
12
+
13
+ from pydantic import BaseModel, ConfigDict, Field
14
+
15
+ from loft_cli_core.specs.bootstrap_schema import (
16
+ CheckBlock,
17
+ HostBlock,
18
+ InventoryBlock,
19
+ MetaBlock,
20
+ )
21
+
22
+
23
+ class HttpCheckConfig(BaseModel):
24
+ """Configuration for a GET-only HTTP readiness probe."""
25
+
26
+ model_config = ConfigDict(extra="forbid")
27
+
28
+ url: str # GET target URL
29
+ expected_status: int = 200
30
+ retries: int = 5 # number of attempts
31
+ interval: int = 3 # seconds between retries
32
+ timeout: int = 10 # per-request timeout in seconds
33
+
34
+
35
+ class HttpCheckLoginBlock(BaseModel):
36
+ """Login defaults matching post-bootstrap convention (admin@2222)."""
37
+
38
+ model_config = ConfigDict(extra="forbid")
39
+
40
+ user: str = "admin"
41
+ private_key: str = "~/.ssh/id_ed25519"
42
+ password: str | None = None
43
+ port: int = 2222
44
+
45
+
46
+ class HttpCheckLocalBlock(BaseModel):
47
+ model_config = ConfigDict(extra="forbid")
48
+
49
+ state_dir: str = ""
50
+ inventory: InventoryBlock = Field(default_factory=InventoryBlock)
51
+
52
+
53
+ class HttpCheckSpec(BaseModel):
54
+ """Spec for GET-only HTTP readiness checks, usable as stack dependency gates."""
55
+
56
+ model_config = ConfigDict(extra="forbid")
57
+
58
+ kind: Literal["http_check"]
59
+ meta: MetaBlock
60
+ host: HostBlock
61
+ login: HttpCheckLoginBlock = Field(default_factory=HttpCheckLoginBlock)
62
+ check: HttpCheckConfig
63
+ local: HttpCheckLocalBlock = Field(default_factory=HttpCheckLocalBlock)
64
+ checks: list[CheckBlock] = Field(default_factory=list)