loft-cli-core 0.6.3__tar.gz → 0.11.0__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 (57) hide show
  1. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/PKG-INFO +1 -1
  2. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/plan/models.py +4 -0
  3. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/__init__.py +18 -0
  4. loft_cli_core-0.11.0/loft_cli_core/registry/catalog.py +95 -0
  5. loft_cli_core-0.11.0/loft_cli_core/registry/conditions.py +114 -0
  6. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/local_paths.py +51 -1
  7. loft_cli_core-0.11.0/loft_cli_core/specs/backup_job_schema.py +137 -0
  8. loft_cli_core-0.11.0/loft_cli_core/specs/blueprint_schema.py +84 -0
  9. loft_cli_core-0.11.0/loft_cli_core/specs/bootstrap_schema.py +244 -0
  10. loft_cli_core-0.11.0/loft_cli_core/specs/compose_project_schema.py +229 -0
  11. loft_cli_core-0.11.0/loft_cli_core/specs/file_template_schema.py +80 -0
  12. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/specs/http_check_schema.py +25 -11
  13. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/specs/loader.py +112 -2
  14. loft_cli_core-0.11.0/loft_cli_core/specs/package_schema.py +81 -0
  15. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/specs/postgres_ensure_schema.py +44 -19
  16. loft_cli_core-0.11.0/loft_cli_core/specs/service_schema.py +172 -0
  17. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/specs/stack_schema.py +27 -10
  18. loft_cli_core-0.11.0/loft_cli_core/specs/systemd_timer_schema.py +101 -0
  19. loft_cli_core-0.11.0/loft_cli_core/specs/systemd_unit_schema.py +135 -0
  20. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/specs/validators.py +299 -5
  21. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core.egg-info/PKG-INFO +1 -1
  22. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core.egg-info/SOURCES.txt +4 -0
  23. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/pyproject.toml +1 -1
  24. loft_cli_core-0.6.3/loft_cli_core/specs/backup_job_schema.py +0 -95
  25. loft_cli_core-0.6.3/loft_cli_core/specs/bootstrap_schema.py +0 -124
  26. loft_cli_core-0.6.3/loft_cli_core/specs/compose_project_schema.py +0 -93
  27. loft_cli_core-0.6.3/loft_cli_core/specs/file_template_schema.py +0 -64
  28. loft_cli_core-0.6.3/loft_cli_core/specs/service_schema.py +0 -114
  29. loft_cli_core-0.6.3/loft_cli_core/specs/systemd_timer_schema.py +0 -76
  30. loft_cli_core-0.6.3/loft_cli_core/specs/systemd_unit_schema.py +0 -86
  31. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/README.md +0 -0
  32. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/__init__.py +0 -0
  33. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/agent_models.py +0 -0
  34. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/agent_paths.py +0 -0
  35. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/plan/__init__.py +0 -0
  36. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/plan/render_diff.py +0 -0
  37. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/plan/render_markdown.py +0 -0
  38. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/plan/render_text.py +0 -0
  39. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/policy.py +0 -0
  40. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/executors.py +0 -0
  41. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/hooks.py +0 -0
  42. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/normalizers.py +0 -0
  43. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/planners.py +0 -0
  44. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/resolvers.py +0 -0
  45. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/specs.py +0 -0
  46. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/registry/validators.py +0 -0
  47. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/specs/__init__.py +0 -0
  48. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/state.py +0 -0
  49. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/utils/__init__.py +0 -0
  50. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/utils/files.py +0 -0
  51. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/utils/hashing.py +0 -0
  52. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/utils/os_detect.py +0 -0
  53. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core/utils/templates.py +0 -0
  54. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core.egg-info/dependency_links.txt +0 -0
  55. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core.egg-info/requires.txt +0 -0
  56. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/loft_cli_core.egg-info/top_level.txt +0 -0
  57. {loft_cli_core-0.6.3 → loft_cli_core-0.11.0}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: loft-cli-core
3
- Version: 0.6.3
3
+ Version: 0.11.0
4
4
  Summary: Shared models, specs, and registry infrastructure for loft-cli
5
5
  Requires-Python: >=3.11
6
6
  Requires-Dist: pydantic>=2.5
@@ -35,6 +35,10 @@ class StepKind:
35
35
  GATE = "gate" # must pass before subsequent steps that depend on it execute
36
36
  COMPOSE_HEALTH_CHECK = "compose_health_check" # poll docker compose ps for container health
37
37
 
38
+ # compose_project v0.3 extensions
39
+ COMPOSE_HTTP_READY = "compose_http_ready" # HTTP-level readiness poll after container health
40
+ POST_DEPLOY_HTTP = "post_deploy_http" # HTTP request post-deploy action
41
+
38
42
  # Agent-side step kinds (v0.4) — execute locally on the managed server
39
43
  AGENT_COMMAND = "agent_command"
40
44
  AGENT_FILE_WRITE = "agent_file_write"
@@ -25,6 +25,15 @@ load_addons() is idempotent — subsequent calls are no-ops.
25
25
 
26
26
  from __future__ import annotations
27
27
 
28
+ from loft_cli_core.registry.catalog import (
29
+ CatalogEntry,
30
+ OutputTemplate,
31
+ StepTemplate,
32
+ get_catalog_entry,
33
+ list_catalog_entries,
34
+ register_catalog_entry,
35
+ )
36
+ from loft_cli_core.registry.conditions import evaluate_condition
28
37
  from loft_cli_core.registry.executors import get_step_handler, register_step_handler
29
38
  from loft_cli_core.registry.hooks import KindHooks, get_kind_hooks, register_kind_hooks
30
39
  from loft_cli_core.registry.local_paths import (
@@ -67,6 +76,15 @@ __all__ = [
67
76
  "register_local_paths",
68
77
  "get_local_paths",
69
78
  "LocalPathsConfig",
79
+ # Catalog registry (8th registry)
80
+ "register_catalog_entry",
81
+ "get_catalog_entry",
82
+ "list_catalog_entries",
83
+ "CatalogEntry",
84
+ "StepTemplate",
85
+ "OutputTemplate",
86
+ # Condition DSL
87
+ "evaluate_condition",
70
88
  # Addon loader
71
89
  "load_addons",
72
90
  ]
@@ -0,0 +1,95 @@
1
+ """Catalog registry — the 8th registry in the loft-cli registry series.
2
+
3
+ Maps kind strings to ``CatalogEntry`` objects that describe each kind's
4
+ fields, step templates, and observable outputs. This registry makes
5
+ loft-cli self-describing: ``loft-cli catalog list/show/export`` all draw
6
+ from this registry.
7
+
8
+ Extending the catalog from an external addon
9
+ ---------------------------------------------
10
+ External addons register catalog entries the same way they register spec
11
+ kinds, planners, etc.:
12
+
13
+ # In loft_cli_pro/register.py:
14
+ from loft_cli_core.registry import register_catalog_entry, CatalogEntry, OutputTemplate
15
+
16
+ def register():
17
+ register_catalog_entry("pro_deploy", CatalogEntry(
18
+ kind="pro_deploy",
19
+ description="Browser-triggered deployment via loft-cli-pro.",
20
+ outputs=[
21
+ OutputTemplate(
22
+ name="deploy_url",
23
+ description="Public URL of the deployed application.",
24
+ example="https://myapp.example.com",
25
+ ),
26
+ ],
27
+ ))
28
+
29
+ ``list_catalog_entries()`` returns built-in entries first (in registration
30
+ order) followed by addon-registered entries — this is the natural result of
31
+ ``load_addons()`` loading built-ins before external addons.
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+ from pydantic import BaseModel, ConfigDict
37
+
38
+
39
+ class OutputTemplate(BaseModel):
40
+ """Declares what a kind produces after apply."""
41
+
42
+ model_config = ConfigDict(extra="forbid")
43
+
44
+ name: str
45
+ description: str
46
+ example: str = ""
47
+
48
+
49
+ class StepTemplate(BaseModel):
50
+ """A named step blueprint that can be conditionally included in a plan."""
51
+
52
+ model_config = ConfigDict(extra="forbid")
53
+
54
+ id: str
55
+ description: str
56
+ condition: dict | None = None # evaluated by Condition DSL (see conditions.py)
57
+
58
+
59
+ class CatalogEntry(BaseModel):
60
+ """Full self-description of a registered kind."""
61
+
62
+ model_config = ConfigDict(extra="forbid")
63
+
64
+ kind: str
65
+ description: str
66
+ fields: list[dict] = []
67
+ step_templates: list[StepTemplate] = []
68
+ outputs: list[OutputTemplate] = []
69
+
70
+
71
+ # ---------------------------------------------------------------------------
72
+ # Internal registry store
73
+ # ---------------------------------------------------------------------------
74
+
75
+ _CATALOG_REGISTRY: dict[str, CatalogEntry] = {}
76
+
77
+
78
+ # ---------------------------------------------------------------------------
79
+ # Public API
80
+ # ---------------------------------------------------------------------------
81
+
82
+
83
+ def register_catalog_entry(kind: str, entry: CatalogEntry) -> None:
84
+ """Register a catalog entry for *kind*, replacing any previous entry."""
85
+ _CATALOG_REGISTRY[kind] = entry
86
+
87
+
88
+ def get_catalog_entry(kind: str) -> CatalogEntry | None:
89
+ """Return the ``CatalogEntry`` for *kind*, or ``None`` if not registered."""
90
+ return _CATALOG_REGISTRY.get(kind)
91
+
92
+
93
+ def list_catalog_entries() -> list[CatalogEntry]:
94
+ """Return all registered catalog entries in registration order."""
95
+ return list(_CATALOG_REGISTRY.values())
@@ -0,0 +1,114 @@
1
+ """Condition DSL evaluator for StepTemplate conditions.
2
+
3
+ Conditions allow a kind to declare "include this step only when field X is
4
+ set" without duplicating planner logic. They make catalog entries
5
+ self-describing in terms of when their steps are active.
6
+
7
+ Supported condition types
8
+ -------------------------
9
+
10
+ **Field presence** — true when the value at the path is not None/empty::
11
+
12
+ {"field_present": "wireguard.enabled"}
13
+
14
+ **Field equality** — true when the value at the path equals *value*::
15
+
16
+ {"field_equals": {"path": "host.os_family", "value": "debian"}}
17
+
18
+ **Boolean combinations**::
19
+
20
+ {"all": [<condition>, ...]} # all sub-conditions must be true
21
+ {"any": [<condition>, ...]} # at least one sub-condition must be true
22
+ {"not": <condition>} # inverts the sub-condition
23
+
24
+ Path resolution
25
+ ---------------
26
+ Dot-separated paths are resolved against the context ``dict`` using nested
27
+ key traversal. A missing intermediate key returns ``False`` (never an error).
28
+
29
+ Example usage inside a StepTemplate::
30
+
31
+ StepTemplate(
32
+ id="wireguard_setup",
33
+ description="Generate WireGuard keypair and write server config",
34
+ condition={"field_present": "wireguard.enabled"},
35
+ )
36
+ """
37
+
38
+ from __future__ import annotations
39
+
40
+
41
+ def _resolve_path(path: str, context: dict) -> object:
42
+ """Traverse *context* using dot-separated *path*.
43
+
44
+ Returns the value at the path, or ``None`` if any intermediate key is
45
+ missing or the context is not a dict at some level.
46
+ """
47
+ parts = path.split(".")
48
+ current: object = context
49
+ for part in parts:
50
+ if not isinstance(current, dict):
51
+ return None
52
+ current = current.get(part)
53
+ return current
54
+
55
+
56
+ def evaluate_condition(condition: dict, context: dict) -> bool:
57
+ """Evaluate a condition dict against *context*.
58
+
59
+ Parameters
60
+ ----------
61
+ condition:
62
+ A condition dict as described in the module docstring.
63
+ context:
64
+ A plain ``dict`` representation of the spec (e.g. from
65
+ ``spec.model_dump()``).
66
+
67
+ Returns
68
+ -------
69
+ ``True`` if the condition is satisfied, ``False`` otherwise. Missing
70
+ paths always return ``False`` rather than raising an exception.
71
+ """
72
+ if not isinstance(condition, dict):
73
+ return False
74
+
75
+ # ── field_present ──────────────────────────────────────────────────
76
+ if "field_present" in condition:
77
+ path: str = condition["field_present"]
78
+ value = _resolve_path(path, context)
79
+ if value is None:
80
+ return False
81
+ # Also treat empty string, empty list, and False as "not present"
82
+ return not (value == "" or value == [] or value is False)
83
+
84
+ # ── field_equals ───────────────────────────────────────────────────
85
+ if "field_equals" in condition:
86
+ spec = condition["field_equals"]
87
+ path = spec.get("path", "")
88
+ expected = spec.get("value")
89
+ value = _resolve_path(path, context)
90
+ return value == expected
91
+
92
+ # ── all ────────────────────────────────────────────────────────────
93
+ if "all" in condition:
94
+ sub_conditions = condition["all"]
95
+ if not isinstance(sub_conditions, list):
96
+ return False
97
+ return all(evaluate_condition(c, context) for c in sub_conditions)
98
+
99
+ # ── any ────────────────────────────────────────────────────────────
100
+ if "any" in condition:
101
+ sub_conditions = condition["any"]
102
+ if not isinstance(sub_conditions, list):
103
+ return False
104
+ return any(evaluate_condition(c, context) for c in sub_conditions)
105
+
106
+ # ── not ────────────────────────────────────────────────────────────
107
+ if "not" in condition:
108
+ sub_condition = condition["not"]
109
+ if not isinstance(sub_condition, dict):
110
+ return False
111
+ return not evaluate_condition(sub_condition, context)
112
+
113
+ # Unknown condition type — default to False rather than raising
114
+ return False
@@ -63,7 +63,7 @@ def _default_state_dir() -> Path | None:
63
63
  """Read LOFT_CLI_STATE_DIR from environment, or return None."""
64
64
  val = os.environ.get("LOFT_CLI_STATE_DIR")
65
65
  if val:
66
- return Path(val)
66
+ return Path(val).expanduser()
67
67
  return None
68
68
 
69
69
 
@@ -105,6 +105,7 @@ class LocalPathsConfig:
105
105
  wg_state_base: Path = field(default_factory=lambda: _UNSET)
106
106
  inventory_db_path: Path = field(default_factory=lambda: _UNSET)
107
107
  log_dir: Path = field(default_factory=lambda: _UNSET)
108
+ keys_base: Path = field(default_factory=lambda: _UNSET)
108
109
 
109
110
  def __post_init__(self) -> None:
110
111
  """Fill unset paths from state_dir or built-in defaults."""
@@ -130,6 +131,12 @@ class LocalPathsConfig:
130
131
  if self.state_dir
131
132
  else Path("~/.loft-cli/runs").expanduser()
132
133
  )
134
+ if self.keys_base is _UNSET:
135
+ self.keys_base = (
136
+ (self.state_dir / "keys")
137
+ if self.state_dir
138
+ else Path("~/.loft-cli/keys").expanduser()
139
+ )
133
140
 
134
141
 
135
142
  # Module-level singleton -- replaced wholesale on each call to register_local_paths().
@@ -145,3 +152,46 @@ def register_local_paths(config: LocalPathsConfig) -> None:
145
152
  def get_local_paths() -> LocalPathsConfig:
146
153
  """Return the currently active local paths config."""
147
154
  return _config
155
+
156
+
157
+ def provider_ssh_conf_d_base(provider: str, config: LocalPathsConfig | None = None) -> Path:
158
+ """Return the SSH conf.d base directory namespaced under a provider.
159
+
160
+ When ``provider`` is non-empty, fragments are stored in a subdirectory
161
+ named after the provider so that keys from different cloud providers do
162
+ not collide:
163
+
164
+ {ssh_conf_d_base}/{provider}/ (e.g. ~/.ssh/conf.d/loft-cli/hetzner/)
165
+
166
+ When ``provider`` is empty the base directory itself is returned
167
+ (backward-compatible behaviour).
168
+ """
169
+ base = (config or _config).ssh_conf_d_base
170
+ if provider:
171
+ return base / provider
172
+ return base
173
+
174
+
175
+ def ssh_key_dir(provider: str, host_name: str, config: LocalPathsConfig | None = None) -> Path:
176
+ """Return the SSH key directory for a given provider and host.
177
+
178
+ Keys are stored under:
179
+ {keys_base}/{provider}/{host_name}/ (e.g. ~/.loft-cli/keys/hetzner/my-server/)
180
+ """
181
+ base = (config or _config).keys_base
182
+ return base / provider / host_name
183
+
184
+
185
+ def provider_wg_state_base(provider: str, config: LocalPathsConfig | None = None) -> Path:
186
+ """Return the WireGuard state base directory namespaced under a provider.
187
+
188
+ When ``provider`` is non-empty, WG key material is stored under:
189
+
190
+ {wg_state_base}/{provider}/ (e.g. ~/.wg/loft-cli/hetzner/)
191
+
192
+ When ``provider`` is empty the base directory itself is returned.
193
+ """
194
+ base = (config or _config).wg_state_base
195
+ if provider:
196
+ return base / provider
197
+ return base
@@ -0,0 +1,137 @@
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"] = Field(
28
+ description="Backup source type: 'postgres_dump' for PostgreSQL databases, 'directory' for filesystem paths."
29
+ )
30
+ # postgres_dump fields
31
+ database: str | None = Field(
32
+ default=None,
33
+ description="PostgreSQL database name to dump. Required when type is 'postgres_dump'.",
34
+ )
35
+ host: str = Field(
36
+ default="localhost",
37
+ description="PostgreSQL server hostname. Used when type is 'postgres_dump'.",
38
+ )
39
+ port: int = Field(
40
+ default=5432, description="PostgreSQL port number. Used when type is 'postgres_dump'."
41
+ )
42
+ user: str = Field(
43
+ default="postgres",
44
+ description="PostgreSQL user for pg_dump. Used when type is 'postgres_dump'.",
45
+ )
46
+ docker_exec: str | None = Field(
47
+ default=None, description="Docker container name to run pg_dump inside via 'docker exec'."
48
+ )
49
+ # directory fields
50
+ path: str | None = Field(
51
+ default=None, description="Filesystem path to back up. Required when type is 'directory'."
52
+ )
53
+
54
+
55
+ class BackupDestination(BaseModel):
56
+ """Destination for backup files."""
57
+
58
+ model_config = ConfigDict(extra="forbid")
59
+
60
+ path: str = Field(description="Local directory on the server where backup files are stored.")
61
+
62
+
63
+ class BackupRetention(BaseModel):
64
+ """Retention policy for backups."""
65
+
66
+ model_config = ConfigDict(extra="forbid")
67
+
68
+ count: int = Field(
69
+ default=7,
70
+ description="Number of most recent backup files to keep. Older files are deleted automatically.",
71
+ )
72
+
73
+
74
+ class BackupJobConfig(BaseModel):
75
+ """Configuration for a backup job."""
76
+
77
+ model_config = ConfigDict(extra="forbid")
78
+
79
+ name: str = Field(
80
+ description="Job name used for script and systemd timer naming, e.g. 'postgres-daily'."
81
+ )
82
+ source: BackupSource = Field(
83
+ description="Source to back up: a PostgreSQL database or a filesystem directory."
84
+ )
85
+ destination: BackupDestination = Field(
86
+ description="Destination directory where backup files are stored on the server."
87
+ )
88
+ retention: BackupRetention = Field(
89
+ default_factory=BackupRetention,
90
+ description="Retention policy controlling how many old backups to keep.",
91
+ )
92
+ schedule: str = Field(
93
+ default="*-*-* 02:00:00",
94
+ description="Systemd OnCalendar expression for backup scheduling, e.g. '*-*-* 02:00:00' for 2am daily.",
95
+ )
96
+
97
+
98
+ class BackupJobLoginBlock(BaseModel):
99
+ """Login defaults matching post-bootstrap convention (admin@2222)."""
100
+
101
+ model_config = ConfigDict(extra="forbid")
102
+
103
+ user: str = Field(default="admin", description="SSH username for connecting to the server.")
104
+ private_key: str = Field(
105
+ default="~/.ssh/id_ed25519", description="Path to the SSH private key for this connection."
106
+ )
107
+ password: str | None = Field(
108
+ default=None, description="SSH password. Use only when key auth is not available."
109
+ )
110
+ port: int = Field(
111
+ default=2222, description="SSH port on the server (post-bootstrap default is 2222)."
112
+ )
113
+
114
+
115
+ class BackupJobLocalBlock(BaseModel):
116
+ model_config = ConfigDict(extra="forbid")
117
+
118
+ state_dir: str = Field(
119
+ default="", description="Override the local state directory. Defaults to ~/.loft-cli/."
120
+ )
121
+ inventory: InventoryBlock = Field(
122
+ default_factory=InventoryBlock, description="Controls local inventory database recording."
123
+ )
124
+
125
+
126
+ class BackupJobSpec(BaseModel):
127
+ """Spec for defining backup operations with retention and scheduling."""
128
+
129
+ model_config = ConfigDict(extra="forbid")
130
+
131
+ kind: Literal["backup_job"]
132
+ meta: MetaBlock
133
+ host: HostBlock
134
+ login: BackupJobLoginBlock = Field(default_factory=BackupJobLoginBlock)
135
+ backup: BackupJobConfig
136
+ local: BackupJobLocalBlock = Field(default_factory=BackupJobLocalBlock)
137
+ checks: list[CheckBlock] = Field(default_factory=list)
@@ -0,0 +1,84 @@
1
+ """Pydantic v2 models for kind: blueprint YAML specs.
2
+
3
+ A blueprint is a reusable, parameterised composition of existing spec kinds.
4
+ It declares ``inputs`` (with optional defaults), optional ``includes`` (references
5
+ to other blueprint files), and inline ``resources`` (same shape as StackResourceBlock).
6
+
7
+ Design principles
8
+ -----------------
9
+ - Blueprints are expanded into primitive steps during planning — no blueprint
10
+ wrappers appear in the final plan.
11
+ - Input tokens (``${name}``) in resource configs are substituted before delegation
12
+ to per-kind planners.
13
+ - Include files are merged into the parent ``resources`` list in order at load time.
14
+ - Circular includes are detected at validation time.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from typing import Annotated, Literal
20
+
21
+ from pydantic import BaseModel, ConfigDict, Field
22
+
23
+ from loft_cli_core.specs.bootstrap_schema import HostBlock, MetaBlock
24
+ from loft_cli_core.specs.stack_schema import StackLocalBlock, StackLoginBlock
25
+
26
+
27
+ class BlueprintInputSpec(BaseModel):
28
+ """Declaration of a single input parameter accepted by a blueprint.
29
+
30
+ Inputs are referenced as ``${name}`` tokens inside resource configs.
31
+ """
32
+
33
+ model_config = ConfigDict(extra="forbid")
34
+
35
+ name: str # input name (used as ${name} in resources)
36
+ required: bool = True # when True, a value must be supplied at plan time
37
+ default: str | None = None # only meaningful when required=False
38
+ description: str = "" # human-readable hint
39
+
40
+
41
+ class BlueprintIncludeBlock(BaseModel):
42
+ """A reference to another blueprint or resource file to be merged in.
43
+
44
+ The included file's resources are appended to the parent's resources list
45
+ in the order the include appears. ``with_`` bindings override the included
46
+ file's input defaults.
47
+ """
48
+
49
+ model_config = ConfigDict(extra="forbid", populate_by_name=True)
50
+
51
+ include: str # local or repo-relative path (e.g. ./fragment.yaml, blueprints/caddy.yaml)
52
+ with_: Annotated[dict[str, str], Field(default_factory=dict, alias="with")] = Field(
53
+ default_factory=dict
54
+ )
55
+
56
+
57
+ class BlueprintResourceBlock(BaseModel):
58
+ """An inline resource within a blueprint.
59
+
60
+ Same shape as ``StackResourceBlock`` in stack_schema.py so that the same
61
+ topological sort and planner delegation logic can be reused.
62
+ """
63
+
64
+ model_config = ConfigDict(extra="forbid")
65
+
66
+ name: str # unique within the blueprint (e.g. "caddy")
67
+ kind: str # the spec kind: "compose_project", "backup_job", etc.
68
+ config: dict = Field(default_factory=dict) # kind-specific config block
69
+ depends_on: list[str] = Field(default_factory=list) # other resource names in this blueprint
70
+
71
+
72
+ class BlueprintSpec(BaseModel):
73
+ """Spec for a reusable, parameterised composition of infrastructure resources."""
74
+
75
+ model_config = ConfigDict(extra="forbid")
76
+
77
+ kind: Literal["blueprint"]
78
+ meta: MetaBlock
79
+ host: HostBlock
80
+ login: StackLoginBlock = Field(default_factory=StackLoginBlock)
81
+ local: StackLocalBlock = Field(default_factory=StackLocalBlock)
82
+ inputs: list[BlueprintInputSpec] = Field(default_factory=list)
83
+ includes: list[BlueprintIncludeBlock] = Field(default_factory=list)
84
+ resources: list[BlueprintResourceBlock] = Field(default_factory=list)