kuzybackup 0.1.5__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.
- kuzybackup/__init__.py +3 -0
- kuzybackup/__main__.py +3 -0
- kuzybackup/agents.py +435 -0
- kuzybackup/backend.py +217 -0
- kuzybackup/cli.py +310 -0
- kuzybackup/config.py +287 -0
- kuzybackup/generation.py +186 -0
- kuzybackup/lifecycle.py +705 -0
- kuzybackup/needlecast.py +107 -0
- kuzybackup/privilege.py +150 -0
- kuzybackup/py.typed +0 -0
- kuzybackup/report.py +229 -0
- kuzybackup/run.py +912 -0
- kuzybackup/verify.py +508 -0
- kuzybackup-0.1.5.data/data/share/kuzybackup/backends/dropbox +12 -0
- kuzybackup-0.1.5.data/data/share/kuzybackup/backends/gdrive +12 -0
- kuzybackup-0.1.5.data/data/share/kuzybackup/backends/local-dir +107 -0
- kuzybackup-0.1.5.data/data/share/kuzybackup/backends/mega +137 -0
- kuzybackup-0.1.5.data/data/share/kuzybackup/backends/rclone +111 -0
- kuzybackup-0.1.5.data/data/share/kuzybackup/backends/s3 +122 -0
- kuzybackup-0.1.5.dist-info/METADATA +199 -0
- kuzybackup-0.1.5.dist-info/RECORD +26 -0
- kuzybackup-0.1.5.dist-info/WHEEL +5 -0
- kuzybackup-0.1.5.dist-info/entry_points.txt +2 -0
- kuzybackup-0.1.5.dist-info/licenses/LICENSE +661 -0
- kuzybackup-0.1.5.dist-info/top_level.txt +1 -0
kuzybackup/__init__.py
ADDED
kuzybackup/__main__.py
ADDED
kuzybackup/agents.py
ADDED
|
@@ -0,0 +1,435 @@
|
|
|
1
|
+
"""Discover the agent sessions to back up.
|
|
2
|
+
|
|
3
|
+
Two sources are supported:
|
|
4
|
+
|
|
5
|
+
* ``static``: agents listed in the configuration file. This is the portable
|
|
6
|
+
default for anyone not running kuzywrap.
|
|
7
|
+
* ``kuzywrap``: targets configured under ``~/.config/kuzywrap/<runtime>/targets``.
|
|
8
|
+
The session bindings are read the same way kuzywrap stores them.
|
|
9
|
+
|
|
10
|
+
With ``system_targets``, the kuzywrap source also reads the targets of separate
|
|
11
|
+
system users under ``/etc/kuzywrap``, their bindings under ``/var/lib/kuzywrap``
|
|
12
|
+
and the sessions in each user's own home. That needs root, so it is opt-in.
|
|
13
|
+
|
|
14
|
+
Several kuzywrap targets can share one session (aliases). They are captured
|
|
15
|
+
once, and every alias is listed in the report.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import json
|
|
21
|
+
import os
|
|
22
|
+
import pwd
|
|
23
|
+
from dataclasses import dataclass, field
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
from typing import Any
|
|
26
|
+
|
|
27
|
+
from .config import Config, ConfigError
|
|
28
|
+
|
|
29
|
+
KUZYWRAP_RUNTIMES = ("claude", "codex", "codewhale", "antigravity", "opencode")
|
|
30
|
+
# OpenCode keeps every session of a user in one SQLite database. Several targets
|
|
31
|
+
# can share it, each pinned to its own session (and that session's children).
|
|
32
|
+
OPENCODE_DATA_DIR = Path(".local/share/opencode")
|
|
33
|
+
OPENCODE_DB = "opencode.db"
|
|
34
|
+
# kuzywrap-opencode's app-server persists the session it is pinned to here and
|
|
35
|
+
# loads it first at every start; the target file's session_id is only the pin
|
|
36
|
+
# it starts from when nothing was persisted yet. `chat --new`, `pin` and `fork`
|
|
37
|
+
# move the persisted pin and leave the target file as it was.
|
|
38
|
+
OPENCODE_SYNC_DIR = Path("kuzywrap/opencode/sync-state")
|
|
39
|
+
SYSTEM_CONFIG_ROOT = Path("/etc/kuzywrap")
|
|
40
|
+
SYSTEM_STATE_ROOT = Path("/var/lib/kuzywrap")
|
|
41
|
+
SYSTEM_USER_KIND = "system-user"
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class DiscoveryError(ConfigError):
|
|
45
|
+
"""System targets cannot be read, so the list of agents would be partial."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass
|
|
49
|
+
class AgentSession:
|
|
50
|
+
"""One session to capture, possibly shared by several target names."""
|
|
51
|
+
|
|
52
|
+
name: str
|
|
53
|
+
runtime: str
|
|
54
|
+
root: Path | None
|
|
55
|
+
session_id: str | None
|
|
56
|
+
aliases: list[str] = field(default_factory=list)
|
|
57
|
+
skip_reason: str | None = None
|
|
58
|
+
excluded_reason: str | None = None
|
|
59
|
+
system_user: str | None = None
|
|
60
|
+
# OpenCode only, per target name: where the pin is persisted and the target
|
|
61
|
+
# file's session, so the binding can be read again once the agent is stopped.
|
|
62
|
+
pin_sources: dict[str, tuple[Path, str | None]] = field(default_factory=dict)
|
|
63
|
+
|
|
64
|
+
@property
|
|
65
|
+
def label(self) -> str:
|
|
66
|
+
return f"{self.runtime}/{self.name}"
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class BindingError(ValueError):
|
|
70
|
+
"""The session a target is bound to cannot be read reliably."""
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _read_json(path: Path) -> dict[str, Any] | None:
|
|
74
|
+
try:
|
|
75
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
76
|
+
except (OSError, UnicodeError, json.JSONDecodeError):
|
|
77
|
+
# One unreadable file marks its target, never the whole discovery.
|
|
78
|
+
return None
|
|
79
|
+
return data if isinstance(data, dict) else None
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def claude_transcript_exists(root: Path, session_id: str) -> bool:
|
|
83
|
+
projects = root / "projects"
|
|
84
|
+
return projects.is_dir() and any(projects.glob(f"*/{session_id}.jsonl"))
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _home_of(user: str) -> Path | None:
|
|
88
|
+
try:
|
|
89
|
+
return Path(pwd.getpwnam(user).pw_dir)
|
|
90
|
+
except KeyError:
|
|
91
|
+
return None
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _system_user(config: dict[str, Any]) -> str | None:
|
|
95
|
+
if config.get("kind") != SYSTEM_USER_KIND:
|
|
96
|
+
return None
|
|
97
|
+
user = config.get("system_user")
|
|
98
|
+
return user if isinstance(user, str) and user else None
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _target_home(config: dict[str, Any]) -> Path | None:
|
|
102
|
+
"""The home of a target; None when its system user does not exist."""
|
|
103
|
+
declared = config.get("home")
|
|
104
|
+
if declared:
|
|
105
|
+
return Path(str(declared)).expanduser()
|
|
106
|
+
user = _system_user(config)
|
|
107
|
+
return _home_of(user) if user else Path.home()
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def user_state_home() -> Path:
|
|
111
|
+
"""Where kuzywrap keeps a current-user target's state (as kuzywrap reads it)."""
|
|
112
|
+
xdg = os.environ.get("XDG_STATE_HOME")
|
|
113
|
+
return Path(xdg) if xdg else Path.home() / ".local/state"
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _opencode_pin_path(
|
|
117
|
+
name: str,
|
|
118
|
+
system_user: str | None,
|
|
119
|
+
state_root: Path | None = None,
|
|
120
|
+
state_home: Path | None = None,
|
|
121
|
+
) -> Path:
|
|
122
|
+
if system_user:
|
|
123
|
+
base = (state_root or SYSTEM_STATE_ROOT) / "opencode/sync-state"
|
|
124
|
+
else:
|
|
125
|
+
base = (state_home or user_state_home()) / OPENCODE_SYNC_DIR
|
|
126
|
+
return base / f"session-{name}.json"
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def opencode_pin(path: Path, configured: str | None) -> str | None:
|
|
130
|
+
"""The session kuzywrap-opencode is pinned to, or will pin at its next start.
|
|
131
|
+
|
|
132
|
+
A persisted pin wins, as in the app-server. With none, the app-server pins
|
|
133
|
+
the target file's session when it starts, so that one is the binding. A pin
|
|
134
|
+
file that exists but cannot be read is an error, never a reason to fall back
|
|
135
|
+
to the target file: that session may be an old one.
|
|
136
|
+
"""
|
|
137
|
+
try:
|
|
138
|
+
raw = path.read_text(encoding="utf-8")
|
|
139
|
+
except FileNotFoundError:
|
|
140
|
+
return configured
|
|
141
|
+
except OSError as exc:
|
|
142
|
+
raise BindingError(f"cannot read the persisted OpenCode pin: {exc}") from exc
|
|
143
|
+
except UnicodeError as exc:
|
|
144
|
+
raise BindingError("the persisted OpenCode pin is not UTF-8") from exc
|
|
145
|
+
try:
|
|
146
|
+
data = json.loads(raw)
|
|
147
|
+
except json.JSONDecodeError as exc:
|
|
148
|
+
raise BindingError("the persisted OpenCode pin is not JSON") from exc
|
|
149
|
+
session = data.get("session_id") if isinstance(data, dict) else None
|
|
150
|
+
if not isinstance(session, str) or not session:
|
|
151
|
+
raise BindingError("the persisted OpenCode pin names no session")
|
|
152
|
+
return session
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def current_binding(agent: AgentSession) -> dict[str, str | None]:
|
|
156
|
+
"""Read again, for every name of an OpenCode agent, the session it is bound to.
|
|
157
|
+
|
|
158
|
+
Called once the agent is stopped: its app-server can no longer move the pin,
|
|
159
|
+
so this is the binding the capture must match.
|
|
160
|
+
"""
|
|
161
|
+
return {
|
|
162
|
+
name: opencode_pin(path, configured)
|
|
163
|
+
for name, (path, configured) in sorted(agent.pin_sources.items())
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def _codex_binding_path(
|
|
168
|
+
name: str, system_user: str | None, state_root: Path | None = None
|
|
169
|
+
) -> Path:
|
|
170
|
+
if system_user:
|
|
171
|
+
base = state_root or SYSTEM_STATE_ROOT
|
|
172
|
+
return base / "codex/sessions" / f"{system_user}.json"
|
|
173
|
+
return Path.home() / ".local/share/kuzywrap/codex/sessions" / f"{name}.json"
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def session_source_exists(
|
|
177
|
+
runtime: str,
|
|
178
|
+
root: Path,
|
|
179
|
+
session_id: str,
|
|
180
|
+
name: str,
|
|
181
|
+
*,
|
|
182
|
+
system_user: str | None = None,
|
|
183
|
+
state_root: Path | None = None,
|
|
184
|
+
) -> bool:
|
|
185
|
+
"""Whether the canonical session data is present on disk."""
|
|
186
|
+
if runtime == "claude":
|
|
187
|
+
return claude_transcript_exists(root, session_id)
|
|
188
|
+
if runtime == "codex":
|
|
189
|
+
binding = _codex_binding_path(name, system_user, state_root)
|
|
190
|
+
return binding.is_file() and (root / "state_5.sqlite").is_file()
|
|
191
|
+
if runtime == "codewhale":
|
|
192
|
+
return (root / "sessions" / f"{session_id}.json").is_file()
|
|
193
|
+
if runtime == "opencode":
|
|
194
|
+
# Whether the session row exists is Needlecast's to check: kuzybackup
|
|
195
|
+
# does not open the database of running agents.
|
|
196
|
+
return (root / OPENCODE_DB).is_file()
|
|
197
|
+
return root.exists()
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def _kuzywrap_binding(
|
|
201
|
+
runtime: str,
|
|
202
|
+
name: str,
|
|
203
|
+
config: dict[str, Any],
|
|
204
|
+
state_root: Path | None = None,
|
|
205
|
+
state_home: Path | None = None,
|
|
206
|
+
) -> tuple[Path | None, str | None]:
|
|
207
|
+
home = _target_home(config)
|
|
208
|
+
if runtime == "claude":
|
|
209
|
+
session = config.get("canonical_session_id")
|
|
210
|
+
root = home / ".claude" if home else None
|
|
211
|
+
return root, session if isinstance(session, str) else None
|
|
212
|
+
if runtime == "codex":
|
|
213
|
+
binding = _read_json(
|
|
214
|
+
_codex_binding_path(name, _system_user(config), state_root)
|
|
215
|
+
)
|
|
216
|
+
thread = binding.get("thread_id") if binding else None
|
|
217
|
+
root = home / ".codex" if home else None
|
|
218
|
+
return root, thread if isinstance(thread, str) else None
|
|
219
|
+
if runtime == "codewhale":
|
|
220
|
+
session = config.get("session_id")
|
|
221
|
+
app_home = config.get("app_home")
|
|
222
|
+
root = Path(str(app_home)).expanduser() / ".codewhale" if app_home else None
|
|
223
|
+
return root, session if isinstance(session, str) else None
|
|
224
|
+
if runtime == "antigravity":
|
|
225
|
+
session = config.get("session_id")
|
|
226
|
+
root = home / ".gemini/antigravity-cli" if home else None
|
|
227
|
+
return root, session if isinstance(session, str) else None
|
|
228
|
+
if runtime == "opencode":
|
|
229
|
+
path, configured = _opencode_pin_source(name, config, state_root, state_home)
|
|
230
|
+
root = home / OPENCODE_DATA_DIR if home else None
|
|
231
|
+
return root, opencode_pin(path, configured)
|
|
232
|
+
return None, None
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _opencode_pin_source(
|
|
236
|
+
name: str,
|
|
237
|
+
config: dict[str, Any],
|
|
238
|
+
state_root: Path | None,
|
|
239
|
+
state_home: Path | None,
|
|
240
|
+
) -> tuple[Path, str | None]:
|
|
241
|
+
path = _opencode_pin_path(name, _system_user(config), state_root, state_home)
|
|
242
|
+
configured = config.get("session_id")
|
|
243
|
+
return path, configured if isinstance(configured, str) and configured else None
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def _agent_from_target(
|
|
247
|
+
runtime: str,
|
|
248
|
+
name: str,
|
|
249
|
+
data: dict[str, Any],
|
|
250
|
+
state_root: Path | None = None,
|
|
251
|
+
state_home: Path | None = None,
|
|
252
|
+
) -> AgentSession:
|
|
253
|
+
system_user = _system_user(data)
|
|
254
|
+
try:
|
|
255
|
+
root, session_id = _kuzywrap_binding(
|
|
256
|
+
runtime, name, data, state_root, state_home
|
|
257
|
+
)
|
|
258
|
+
except BindingError as exc:
|
|
259
|
+
return AgentSession(
|
|
260
|
+
name=name,
|
|
261
|
+
runtime=runtime,
|
|
262
|
+
root=None,
|
|
263
|
+
session_id=None,
|
|
264
|
+
system_user=system_user,
|
|
265
|
+
skip_reason=str(exc),
|
|
266
|
+
)
|
|
267
|
+
agent = AgentSession(
|
|
268
|
+
name=name,
|
|
269
|
+
runtime=runtime,
|
|
270
|
+
root=root,
|
|
271
|
+
session_id=session_id,
|
|
272
|
+
system_user=system_user,
|
|
273
|
+
)
|
|
274
|
+
if runtime == "opencode":
|
|
275
|
+
agent.pin_sources[name] = _opencode_pin_source(
|
|
276
|
+
name, data, state_root, state_home
|
|
277
|
+
)
|
|
278
|
+
if root is None or session_id is None:
|
|
279
|
+
agent.skip_reason = "target has no canonical local session binding"
|
|
280
|
+
elif not session_source_exists(
|
|
281
|
+
runtime, root, session_id, name, system_user=system_user, state_root=state_root
|
|
282
|
+
):
|
|
283
|
+
agent.skip_reason = "canonical session source is absent locally"
|
|
284
|
+
return agent
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
def _unreadable_target(path: Path, runtime: str) -> AgentSession:
|
|
288
|
+
return AgentSession(
|
|
289
|
+
name=path.stem,
|
|
290
|
+
runtime=runtime,
|
|
291
|
+
root=None,
|
|
292
|
+
session_id=None,
|
|
293
|
+
skip_reason="target configuration is unreadable",
|
|
294
|
+
)
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def discover_kuzywrap(
|
|
298
|
+
config_root: Path | None = None, state_home: Path | None = None
|
|
299
|
+
) -> list[AgentSession]:
|
|
300
|
+
base = (config_root or Path.home() / ".config/kuzywrap").expanduser()
|
|
301
|
+
found: list[AgentSession] = []
|
|
302
|
+
for runtime in KUZYWRAP_RUNTIMES:
|
|
303
|
+
target_dir = base / runtime / "targets"
|
|
304
|
+
if not target_dir.is_dir():
|
|
305
|
+
continue
|
|
306
|
+
for path in sorted(target_dir.glob("*.json")):
|
|
307
|
+
data = _read_json(path)
|
|
308
|
+
if data is None:
|
|
309
|
+
found.append(_unreadable_target(path, runtime))
|
|
310
|
+
continue
|
|
311
|
+
found.append(
|
|
312
|
+
_agent_from_target(
|
|
313
|
+
runtime,
|
|
314
|
+
str(data.get("target") or path.stem),
|
|
315
|
+
data,
|
|
316
|
+
state_home=state_home,
|
|
317
|
+
)
|
|
318
|
+
)
|
|
319
|
+
return found
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
def _require_readable(directory: Path) -> None:
|
|
323
|
+
"""A directory we cannot list would silently shorten the list of agents."""
|
|
324
|
+
if directory.exists() and not os.access(directory, os.R_OK | os.X_OK):
|
|
325
|
+
raise DiscoveryError(
|
|
326
|
+
f"cannot read {directory}: [discovery].system_targets needs root"
|
|
327
|
+
)
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
def _implicit_codex_targets(state_root: Path, known: set[str]) -> list[dict[str, Any]]:
|
|
331
|
+
"""Codex serves a system user as a target even with no file under /etc."""
|
|
332
|
+
sessions = state_root / "codex/sessions"
|
|
333
|
+
_require_readable(sessions)
|
|
334
|
+
if not sessions.is_dir():
|
|
335
|
+
return []
|
|
336
|
+
return [
|
|
337
|
+
{"target": path.stem, "kind": SYSTEM_USER_KIND, "system_user": path.stem}
|
|
338
|
+
for path in sorted(sessions.glob("*.json"))
|
|
339
|
+
if path.stem not in known and _home_of(path.stem) is not None
|
|
340
|
+
]
|
|
341
|
+
|
|
342
|
+
|
|
343
|
+
def discover_system_targets(
|
|
344
|
+
config_root: Path = SYSTEM_CONFIG_ROOT, state_root: Path = SYSTEM_STATE_ROOT
|
|
345
|
+
) -> list[AgentSession]:
|
|
346
|
+
"""Targets of separate system users, for a host where agents do not share one."""
|
|
347
|
+
found: list[AgentSession] = []
|
|
348
|
+
for runtime in KUZYWRAP_RUNTIMES:
|
|
349
|
+
target_dir = config_root / runtime / "targets"
|
|
350
|
+
_require_readable(target_dir)
|
|
351
|
+
records: list[dict[str, Any]] = []
|
|
352
|
+
if target_dir.is_dir():
|
|
353
|
+
for path in sorted(target_dir.glob("*.json")):
|
|
354
|
+
data = _read_json(path)
|
|
355
|
+
if data is None:
|
|
356
|
+
found.append(_unreadable_target(path, runtime))
|
|
357
|
+
else:
|
|
358
|
+
records.append({"target": path.stem, **data})
|
|
359
|
+
if runtime == "codex":
|
|
360
|
+
known = {str(r.get("system_user") or r["target"]) for r in records}
|
|
361
|
+
records += _implicit_codex_targets(state_root, known)
|
|
362
|
+
for data in records:
|
|
363
|
+
found.append(
|
|
364
|
+
_agent_from_target(runtime, str(data["target"]), data, state_root)
|
|
365
|
+
)
|
|
366
|
+
return found
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
def discover_static(config: Config) -> list[AgentSession]:
|
|
370
|
+
agents: list[AgentSession] = []
|
|
371
|
+
for item in config.agents:
|
|
372
|
+
root = item.root.expanduser()
|
|
373
|
+
agent = AgentSession(
|
|
374
|
+
name=item.name,
|
|
375
|
+
runtime=item.runtime,
|
|
376
|
+
root=root,
|
|
377
|
+
session_id=item.session_id,
|
|
378
|
+
system_user=item.system_user,
|
|
379
|
+
)
|
|
380
|
+
if not session_source_exists(
|
|
381
|
+
item.runtime, root, item.session_id, item.name, system_user=item.system_user
|
|
382
|
+
):
|
|
383
|
+
agent.skip_reason = "session source is absent locally"
|
|
384
|
+
agents.append(agent)
|
|
385
|
+
return agents
|
|
386
|
+
|
|
387
|
+
|
|
388
|
+
def group_aliases(agents: list[AgentSession]) -> list[AgentSession]:
|
|
389
|
+
"""Merge targets that point at the same session into one capture."""
|
|
390
|
+
groups: dict[tuple[str, str, str], list[AgentSession]] = {}
|
|
391
|
+
singles: list[AgentSession] = []
|
|
392
|
+
for agent in agents:
|
|
393
|
+
if agent.root is None or agent.session_id is None or agent.skip_reason:
|
|
394
|
+
singles.append(agent)
|
|
395
|
+
continue
|
|
396
|
+
key = (agent.runtime, str(agent.root.resolve()), agent.session_id)
|
|
397
|
+
groups.setdefault(key, []).append(agent)
|
|
398
|
+
merged: list[AgentSession] = []
|
|
399
|
+
for members in groups.values():
|
|
400
|
+
# A shared session is excluded only when every alias is excluded.
|
|
401
|
+
included = sorted(m.name for m in members if not m.excluded_reason)
|
|
402
|
+
names = included + sorted(m.name for m in members if m.excluded_reason)
|
|
403
|
+
primary = members[0]
|
|
404
|
+
pins: dict[str, tuple[Path, str | None]] = {}
|
|
405
|
+
for member in members:
|
|
406
|
+
pins.update(member.pin_sources)
|
|
407
|
+
merged.append(
|
|
408
|
+
AgentSession(
|
|
409
|
+
name=names[0],
|
|
410
|
+
runtime=primary.runtime,
|
|
411
|
+
root=primary.root,
|
|
412
|
+
session_id=primary.session_id,
|
|
413
|
+
aliases=names[1:],
|
|
414
|
+
excluded_reason=None if included else primary.excluded_reason,
|
|
415
|
+
system_user=primary.system_user,
|
|
416
|
+
pin_sources=pins,
|
|
417
|
+
)
|
|
418
|
+
)
|
|
419
|
+
return sorted(merged + singles, key=lambda a: (a.runtime, a.name))
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
def discover(config: Config) -> list[AgentSession]:
|
|
423
|
+
if config.discovery == "kuzywrap":
|
|
424
|
+
agents = discover_kuzywrap()
|
|
425
|
+
if config.system_targets:
|
|
426
|
+
agents += discover_system_targets()
|
|
427
|
+
else:
|
|
428
|
+
agents = discover_static(config)
|
|
429
|
+
for agent in agents:
|
|
430
|
+
names = {agent.name, f"{agent.runtime}/{agent.name}"}
|
|
431
|
+
if config.include and not names & set(config.include):
|
|
432
|
+
agent.excluded_reason = "not in [discovery].include"
|
|
433
|
+
elif names & set(config.exclude):
|
|
434
|
+
agent.excluded_reason = "listed in [discovery].exclude"
|
|
435
|
+
return group_aliases(agents)
|
kuzybackup/backend.py
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
"""Client for backend scripts.
|
|
2
|
+
|
|
3
|
+
A backend is an executable in a backends directory. kuzybackup calls it as
|
|
4
|
+
``<backend> <command> [args...]`` and reads one JSON object from stdout. The
|
|
5
|
+
protocol is documented in ``docs/BACKENDS.md``.
|
|
6
|
+
|
|
7
|
+
Credentials never pass through kuzybackup: the configuration only names a
|
|
8
|
+
file, and the backend reads it through ``KUZYBACKUP_CREDENTIALS_FILE``.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import json
|
|
14
|
+
import os
|
|
15
|
+
import pwd
|
|
16
|
+
import subprocess
|
|
17
|
+
from dataclasses import dataclass, field
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
from typing import Any
|
|
20
|
+
|
|
21
|
+
PROTOCOL_VERSION = 1
|
|
22
|
+
EXIT_NOT_IMPLEMENTED = 2
|
|
23
|
+
COMMANDS = ("put", "list", "get", "delete")
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class BackendError(RuntimeError):
|
|
27
|
+
"""The backend failed or answered outside the protocol."""
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class NotImplementedByBackend(BackendError):
|
|
31
|
+
"""The backend explicitly declined a command (exit status 2)."""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass(frozen=True)
|
|
35
|
+
class Capabilities:
|
|
36
|
+
name: str
|
|
37
|
+
tested: bool
|
|
38
|
+
list_is_remote: bool
|
|
39
|
+
supports: dict[str, bool]
|
|
40
|
+
note: str | None = None
|
|
41
|
+
|
|
42
|
+
def can(self, command: str) -> bool:
|
|
43
|
+
return bool(self.supports.get(command, False))
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass(frozen=True)
|
|
47
|
+
class RemoteEntry:
|
|
48
|
+
name: str
|
|
49
|
+
type: str
|
|
50
|
+
size: int | None = None
|
|
51
|
+
sha256: str | None = None
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass
|
|
55
|
+
class Backend:
|
|
56
|
+
"""A backend script plus the environment it runs with."""
|
|
57
|
+
|
|
58
|
+
executable: Path
|
|
59
|
+
credentials_file: Path | None = None
|
|
60
|
+
options: dict[str, str] = field(default_factory=dict)
|
|
61
|
+
timeout_seconds: float = 3600.0
|
|
62
|
+
run_as: str | None = None
|
|
63
|
+
|
|
64
|
+
@classmethod
|
|
65
|
+
def locate(
|
|
66
|
+
cls,
|
|
67
|
+
name: str,
|
|
68
|
+
search_dirs: list[Path],
|
|
69
|
+
*,
|
|
70
|
+
credentials_file: Path | None = None,
|
|
71
|
+
options: dict[str, str] | None = None,
|
|
72
|
+
timeout_seconds: float = 3600.0,
|
|
73
|
+
run_as: str | None = None,
|
|
74
|
+
) -> Backend:
|
|
75
|
+
if "/" in name or name.startswith("."):
|
|
76
|
+
raise BackendError(f"invalid backend name: {name!r}")
|
|
77
|
+
for directory in search_dirs:
|
|
78
|
+
candidate = directory.expanduser() / name
|
|
79
|
+
if candidate.is_file() and os.access(candidate, os.X_OK):
|
|
80
|
+
return cls(
|
|
81
|
+
executable=candidate,
|
|
82
|
+
credentials_file=credentials_file,
|
|
83
|
+
options=dict(options or {}),
|
|
84
|
+
timeout_seconds=timeout_seconds,
|
|
85
|
+
run_as=run_as,
|
|
86
|
+
)
|
|
87
|
+
searched = ", ".join(str(d) for d in search_dirs)
|
|
88
|
+
raise BackendError(f"backend {name!r} not found in: {searched}")
|
|
89
|
+
|
|
90
|
+
def _environment(self) -> dict[str, str]:
|
|
91
|
+
env = dict(os.environ)
|
|
92
|
+
# Never leak a credentials path from the caller's environment into a
|
|
93
|
+
# backend that was configured without one.
|
|
94
|
+
env.pop("KUZYBACKUP_CREDENTIALS_FILE", None)
|
|
95
|
+
if self.credentials_file is not None:
|
|
96
|
+
env["KUZYBACKUP_CREDENTIALS_FILE"] = str(self.credentials_file.expanduser())
|
|
97
|
+
for key, value in self.options.items():
|
|
98
|
+
env[f"KUZYBACKUP_OPT_{key.upper()}"] = value
|
|
99
|
+
env["KUZYBACKUP_PROTOCOL"] = str(PROTOCOL_VERSION)
|
|
100
|
+
return env
|
|
101
|
+
|
|
102
|
+
def _identity(self) -> dict[str, Any]:
|
|
103
|
+
"""How to run the script as run_as: root switches, anyone else must be it."""
|
|
104
|
+
if self.run_as is None:
|
|
105
|
+
return {"env": self._environment()}
|
|
106
|
+
try:
|
|
107
|
+
account = pwd.getpwnam(self.run_as)
|
|
108
|
+
except KeyError as exc:
|
|
109
|
+
raise BackendError(f"backend user {self.run_as!r} does not exist") from exc
|
|
110
|
+
if os.geteuid() != 0:
|
|
111
|
+
if os.geteuid() != account.pw_uid:
|
|
112
|
+
raise BackendError(f"the backend must run as {self.run_as}")
|
|
113
|
+
return {"env": self._environment()}
|
|
114
|
+
# Nothing from root's own environment reaches the script.
|
|
115
|
+
inherited = self._environment()
|
|
116
|
+
env = {k: v for k, v in inherited.items() if k.startswith("KUZYBACKUP_")}
|
|
117
|
+
env.update(
|
|
118
|
+
PATH=inherited.get("PATH", "/usr/bin:/bin"),
|
|
119
|
+
LANG=inherited.get("LANG", "C.UTF-8"),
|
|
120
|
+
HOME=account.pw_dir,
|
|
121
|
+
USER=self.run_as,
|
|
122
|
+
LOGNAME=self.run_as,
|
|
123
|
+
)
|
|
124
|
+
return {
|
|
125
|
+
"env": env,
|
|
126
|
+
"user": account.pw_uid,
|
|
127
|
+
"group": account.pw_gid,
|
|
128
|
+
"extra_groups": [],
|
|
129
|
+
"cwd": account.pw_dir,
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
def _call(self, *args: str) -> dict[str, Any]:
|
|
133
|
+
identity = self._identity()
|
|
134
|
+
try:
|
|
135
|
+
result = subprocess.run(
|
|
136
|
+
[str(self.executable), *args],
|
|
137
|
+
capture_output=True,
|
|
138
|
+
text=True,
|
|
139
|
+
timeout=self.timeout_seconds,
|
|
140
|
+
check=False,
|
|
141
|
+
**identity,
|
|
142
|
+
)
|
|
143
|
+
except subprocess.TimeoutExpired as exc:
|
|
144
|
+
raise BackendError(
|
|
145
|
+
f"backend {self.executable.name} {args[0]} timed out"
|
|
146
|
+
) from exc
|
|
147
|
+
if result.returncode == EXIT_NOT_IMPLEMENTED:
|
|
148
|
+
raise NotImplementedByBackend(
|
|
149
|
+
f"backend {self.executable.name} does not implement {args[0]}"
|
|
150
|
+
)
|
|
151
|
+
try:
|
|
152
|
+
data = json.loads(result.stdout) if result.stdout.strip() else {}
|
|
153
|
+
except json.JSONDecodeError as exc:
|
|
154
|
+
raise BackendError(
|
|
155
|
+
f"backend {self.executable.name} {args[0]} returned invalid JSON"
|
|
156
|
+
) from exc
|
|
157
|
+
if not isinstance(data, dict):
|
|
158
|
+
raise BackendError(
|
|
159
|
+
f"backend {self.executable.name} {args[0]} did not return an object"
|
|
160
|
+
)
|
|
161
|
+
if result.returncode != 0 or data.get("status") != "ok":
|
|
162
|
+
detail = data.get("error")
|
|
163
|
+
if not isinstance(detail, str) or not detail:
|
|
164
|
+
lines = result.stderr.strip().splitlines()
|
|
165
|
+
detail = lines[-1] if lines else f"exit status {result.returncode}"
|
|
166
|
+
raise BackendError(
|
|
167
|
+
f"backend {self.executable.name} {args[0]} failed: {detail}"
|
|
168
|
+
)
|
|
169
|
+
return data
|
|
170
|
+
|
|
171
|
+
def capabilities(self) -> Capabilities:
|
|
172
|
+
data = self._call("capabilities")
|
|
173
|
+
if data.get("protocol") != PROTOCOL_VERSION:
|
|
174
|
+
raise BackendError(
|
|
175
|
+
f"backend {self.executable.name} speaks protocol "
|
|
176
|
+
f"{data.get('protocol')!r}, expected {PROTOCOL_VERSION}"
|
|
177
|
+
)
|
|
178
|
+
supports = data.get("supports")
|
|
179
|
+
if not isinstance(supports, dict):
|
|
180
|
+
raise BackendError("capabilities.supports must be an object")
|
|
181
|
+
return Capabilities(
|
|
182
|
+
name=str(data.get("name") or self.executable.name),
|
|
183
|
+
tested=data.get("tested") is True,
|
|
184
|
+
list_is_remote=data.get("list_is_remote") is True,
|
|
185
|
+
supports={k: supports.get(k) is True for k in COMMANDS},
|
|
186
|
+
note=str(data["note"]) if data.get("note") else None,
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
def put(self, local_path: Path, remote_path: str) -> None:
|
|
190
|
+
self._call("put", str(local_path), remote_path)
|
|
191
|
+
|
|
192
|
+
def get(self, remote_path: str, local_path: Path) -> None:
|
|
193
|
+
self._call("get", remote_path, str(local_path))
|
|
194
|
+
|
|
195
|
+
def delete(self, remote_path: str) -> None:
|
|
196
|
+
self._call("delete", remote_path)
|
|
197
|
+
|
|
198
|
+
def list(self, remote_dir: str) -> list[RemoteEntry]:
|
|
199
|
+
data = self._call("list", remote_dir)
|
|
200
|
+
entries = data.get("entries")
|
|
201
|
+
if not isinstance(entries, list):
|
|
202
|
+
raise BackendError("list.entries must be an array")
|
|
203
|
+
parsed: list[RemoteEntry] = []
|
|
204
|
+
for item in entries:
|
|
205
|
+
if not isinstance(item, dict) or not isinstance(item.get("name"), str):
|
|
206
|
+
raise BackendError("list entry without a name")
|
|
207
|
+
size = item.get("size")
|
|
208
|
+
sha = item.get("sha256")
|
|
209
|
+
parsed.append(
|
|
210
|
+
RemoteEntry(
|
|
211
|
+
name=item["name"],
|
|
212
|
+
type=str(item.get("type") or "file"),
|
|
213
|
+
size=size if isinstance(size, int) else None,
|
|
214
|
+
sha256=sha if isinstance(sha, str) else None,
|
|
215
|
+
)
|
|
216
|
+
)
|
|
217
|
+
return parsed
|