devstuff 2.20.0__py3-none-any.whl → 2.22.0__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.
@@ -88,6 +88,12 @@ CONFIGURATORS: dict[str, Configurator] = {
88
88
  description="Prompt style, colour palette, and which sections appear",
89
89
  module="dev_setup.configure.starship.wizard",
90
90
  ),
91
+ "syncthing": Configurator(
92
+ key="syncthing",
93
+ label="Syncthing",
94
+ description="Pair with a server device and share a folder through the local API",
95
+ module="dev_setup.configure.syncthing.wizard",
96
+ ),
91
97
  }
92
98
 
93
99
 
@@ -0,0 +1 @@
1
+ """`devstuff configure syncthing` — pair with a server device via the local API."""
@@ -0,0 +1,144 @@
1
+ """Talking to syncthing's local REST API.
2
+
3
+ No new dependencies — stdlib `urllib` against the address and API key found in
4
+ `syncthing paths`' config.xml. The API key only ever travels in the `X-API-Key`
5
+ header; it must never appear in output, errors or a process command line.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import ipaddress
11
+ import json
12
+ import ssl
13
+ import time
14
+ import urllib.error
15
+ import urllib.request
16
+ import xml.etree.ElementTree as ET
17
+ from dataclasses import dataclass
18
+ from pathlib import Path
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class Endpoint:
23
+ base_url: str
24
+ api_key: str
25
+ verify_tls: bool
26
+
27
+ def __repr__(self) -> str: # never leak the key into logs or tracebacks
28
+ return f"Endpoint(base_url={self.base_url!r}, api_key=<redacted>, verify_tls={self.verify_tls!r})"
29
+
30
+
31
+ def discover(config_file: Path) -> Endpoint | str:
32
+ """The Endpoint config.xml describes, or a sentence saying why it is unusable."""
33
+ try:
34
+ root = ET.parse(config_file).getroot()
35
+ except OSError:
36
+ return f"no config file at {config_file} — has `syncthing` been run once?"
37
+ except ET.ParseError as exc:
38
+ return f"{config_file} does not parse as XML: {exc}"
39
+
40
+ gui = root.find("gui")
41
+ if gui is None:
42
+ return f"{config_file} has no <gui> element"
43
+ address = (gui.findtext("address") or "").strip()
44
+ api_key = (gui.findtext("apikey") or "").strip()
45
+ if not api_key:
46
+ return f"{config_file} has no <apikey> under <gui>"
47
+ if address.startswith("unix://"):
48
+ return (
49
+ f"the GUI listens on a unix socket ({address}); this wizard only speaks http(s) — "
50
+ "change the listen address in the Syncthing GUI"
51
+ )
52
+
53
+ if ":" not in address:
54
+ return f"could not parse the GUI address '{address}'"
55
+ host, _, port = address.rpartition(":")
56
+ host = host.strip("[]")
57
+
58
+ tls = gui.get("tls", "false").lower() == "true"
59
+ wildcard = {"0.0.0.0", "", "::"}
60
+ if host in wildcard:
61
+ host = "127.0.0.1" if host in ("0.0.0.0", "") else "::1"
62
+ try:
63
+ loopback = ipaddress.ip_address(host).is_loopback
64
+ except ValueError:
65
+ loopback = host.lower() in ("localhost", "localhost.localdomain")
66
+ if not loopback:
67
+ return (
68
+ f"the GUI is bound to {host}:{port}, which is not a loopback address — "
69
+ f"refusing to send the API key there; set the GUI listen address to "
70
+ f"127.0.0.1:{port} in the Syncthing GUI (Actions → Settings → GUI) and re-run"
71
+ )
72
+
73
+ scheme = "https" if tls else "http"
74
+ if ":" in host: # IPv6 literal needs brackets in a URL
75
+ host = f"[{host}]"
76
+ return Endpoint(base_url=f"{scheme}://{host}:{port}", api_key=api_key, verify_tls=not tls)
77
+
78
+
79
+ class ApiError(Exception):
80
+ """One error type for every API failure. Carries status and body, never the key."""
81
+
82
+
83
+ class Client:
84
+ def __init__(self, endpoint: Endpoint, timeout: float = 5.0):
85
+ self._endpoint = endpoint
86
+ self._timeout = timeout
87
+ handlers: list = [
88
+ # A corporate HTTP proxy must never see the local daemon's API key.
89
+ urllib.request.ProxyHandler({}),
90
+ ]
91
+ if not endpoint.verify_tls:
92
+ # tls="true" on a loopback GUI serves a self-signed cert; the key is
93
+ # sent only to 127.0.0.1/[::1], so skipping verification is safe here.
94
+ ctx = ssl.create_default_context()
95
+ ctx.check_hostname = False
96
+ ctx.verify_mode = ssl.CERT_NONE
97
+ handlers.append(urllib.request.HTTPSHandler(context=ctx))
98
+ self._opener = urllib.request.build_opener(*handlers)
99
+
100
+ def _request(self, method: str, path: str, data: object = None) -> object:
101
+ url = self._endpoint.base_url + path
102
+ body = json.dumps(data).encode() if data is not None else None
103
+ request = urllib.request.Request(url, data=body, method=method)
104
+ request.add_header("X-API-Key", self._endpoint.api_key)
105
+ if body is not None:
106
+ request.add_header("Content-Type", "application/json")
107
+ try:
108
+ with self._opener.open(request, timeout=self._timeout) as response:
109
+ raw = response.read()
110
+ except urllib.error.HTTPError as exc:
111
+ try:
112
+ detail = exc.read().decode(errors="replace").strip()
113
+ except Exception:
114
+ detail = ""
115
+ raise ApiError(f"{method} {path}: HTTP {exc.code} {exc.reason} {detail}".strip()) from exc
116
+ except (urllib.error.URLError, OSError) as exc:
117
+ reason = getattr(exc, "reason", exc)
118
+ raise ApiError(f"{method} {path}: {reason}") from exc
119
+ if not raw:
120
+ return {}
121
+ try:
122
+ return json.loads(raw)
123
+ except json.JSONDecodeError as exc:
124
+ raise ApiError(f"{method} {path}: response was not JSON") from exc
125
+
126
+ def get(self, path: str) -> object:
127
+ return self._request("GET", path)
128
+
129
+ def post(self, path: str, data: object) -> object:
130
+ return self._request("POST", path, data)
131
+
132
+
133
+ def wait_ready(endpoint: Endpoint, timeout: float = 30.0) -> dict | None:
134
+ """Poll `system/status` until the daemon answers, or give up."""
135
+ deadline = time.monotonic() + timeout
136
+ while time.monotonic() < deadline:
137
+ try:
138
+ status = Client(endpoint).get("/rest/system/status")
139
+ if isinstance(status, dict) and status.get("myID"):
140
+ return status
141
+ except ApiError:
142
+ pass
143
+ time.sleep(0.5)
144
+ return None
@@ -0,0 +1,77 @@
1
+ """Asking the machine — every probe goes through generic._probe/_run so `-v`
2
+ covers them and nothing here writes state."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import getpass
7
+ import os
8
+ from pathlib import Path
9
+
10
+ from dev_setup.generic import _probe
11
+
12
+
13
+ def config_file() -> Path:
14
+ """Where syncthing keeps config.xml — asked of the binary, then the defaults."""
15
+ try:
16
+ r = _probe(["syncthing", "paths"], text=True, timeout=10)
17
+ except OSError:
18
+ r = None
19
+ if r is not None and r.returncode == 0:
20
+ lines = r.stdout.splitlines()
21
+ for i, line in enumerate(lines):
22
+ if line.strip() == "Configuration file:" and i + 1 < len(lines):
23
+ found = lines[i + 1].strip()
24
+ if found:
25
+ return Path(found)
26
+
27
+ xdg = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state")
28
+ path = xdg / "syncthing" / "config.xml"
29
+ if path.exists():
30
+ return path
31
+ legacy = Path.home() / ".config" / "syncthing" / "config.xml"
32
+ if legacy.exists():
33
+ return legacy
34
+ return path
35
+
36
+
37
+ def has_systemd() -> bool:
38
+ return Path("/run/systemd/system").is_dir()
39
+
40
+
41
+ def user_session() -> bool:
42
+ try:
43
+ return _probe(["systemctl", "--user", "show-environment"], timeout=10).returncode == 0
44
+ except OSError:
45
+ return False
46
+
47
+
48
+ def service_active() -> bool:
49
+ try:
50
+ r = _probe(
51
+ ["systemctl", "--user", "is-active", "syncthing.service"],
52
+ text=True,
53
+ timeout=10,
54
+ )
55
+ except OSError:
56
+ return False
57
+ return r.returncode == 0 and r.stdout.strip() == "active"
58
+
59
+
60
+ def linger_enabled() -> bool | None:
61
+ """Whether sync survives logout — or None when the system cannot say."""
62
+ try:
63
+ r = _probe(
64
+ ["loginctl", "show-user", getpass.getuser(), "-p", "Linger"],
65
+ text=True,
66
+ timeout=10,
67
+ )
68
+ except OSError:
69
+ return None
70
+ if r.returncode != 0:
71
+ return None
72
+ value = r.stdout.strip().removeprefix("Linger=").lower()
73
+ if value in ("yes", "true", "1"):
74
+ return True
75
+ if value in ("no", "false", "0"):
76
+ return False
77
+ return None
@@ -0,0 +1,241 @@
1
+ """The pure decision layer for `devstuff configure syncthing`. No I/O.
2
+
3
+ Everything here operates on plain dicts of the shape `GET /rest/config`
4
+ returns, so the whole decision table is testable without a daemon.
5
+
6
+ Measured against syncthing v2.1.6 — each behaviour below is load-bearing:
7
+ - `POST /rest/config/devices` and `POST /rest/config/folders` upsert by id and
8
+ accept any id (slashes included); `PUT …/<id>` 404s on an id containing `/`.
9
+ - A folder's `devices` entry naming a device absent from `config.devices` is
10
+ *silently dropped* — the device must be written before the folder, and the
11
+ result re-read (`verify`).
12
+ - A folder `type` the daemon does not know is stored as `sendreceive` with a
13
+ 200 — the mode comes from a picker and is verified after the write.
14
+ - Overlapping or nested folder paths return 200 and sit `idle`. The overlap
15
+ check is ours.
16
+ - A relative or `~/` folder path is accepted and resolved against the daemon's
17
+ working directory — the wizard always sends an absolute, resolved path.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import re
23
+ from dataclasses import dataclass, field
24
+ from pathlib import Path
25
+
26
+ # The base32 alphabet syncthing device IDs use: no 0, 1, 8 or 9.
27
+ _ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
28
+
29
+ # A device ID is 52 base32 data chars in 4 chunks of 13, each chunk followed by
30
+ # its Luhn mod-32 check char — 56 chars total, printed as 8 groups of 7.
31
+ _ID_DATA_LEN = 56
32
+
33
+ DEFAULT_FOLDER_PATH = "~/SyncthingShared"
34
+ DEFAULT_SERVER_NAME = "Storage server"
35
+
36
+ # The two modes the wizard offers, in picker order.
37
+ FOLDER_MODES = {
38
+ "sendreceive": "Send & receive",
39
+ "receiveonly": "Receive only",
40
+ }
41
+
42
+
43
+ def _luhn32_check(data: str) -> str:
44
+ """One Luhn mod-32 check char over a 13-char group (syncthing's luhnBase32)."""
45
+ factor = 1
46
+ total = 0
47
+ for ch in data:
48
+ addend = factor * _ALPHABET.index(ch)
49
+ factor = 2 if factor == 1 else 1
50
+ addend = addend // 32 + addend % 32
51
+ total += addend
52
+ return _ALPHABET[(32 - total % 32) % 32]
53
+
54
+
55
+ def normalize_device_id(raw: str) -> str:
56
+ """Uppercase, strip whitespace and dashes, regroup into 8×7 with dashes."""
57
+ compact = re.sub(r"[\s-]+", "", raw).upper()
58
+ return "-".join(compact[i : i + 7] for i in range(0, len(compact), 7))
59
+
60
+
61
+ def device_id_problem(raw: str) -> str | None:
62
+ """A human-readable reason the ID cannot be right, or None if it is valid.
63
+
64
+ Local validation catches a typo before anything is written; syncthing itself
65
+ only answers 400 to a bad check digit or wrong length.
66
+ """
67
+ compact = re.sub(r"[\s-]+", "", raw).upper()
68
+ bad = sorted({c for c in compact if c not in _ALPHABET})
69
+ if bad:
70
+ shown = "".join(bad)
71
+ return f"contains invalid characters ({shown}) — a device ID uses A–Z and 2–7 only"
72
+ if len(compact) != _ID_DATA_LEN:
73
+ return f"is {len(compact)} characters — a device ID is 56 (8 groups of 7)"
74
+ for group in range(4):
75
+ data = compact[group * 14 : group * 14 + 13]
76
+ check = compact[group * 14 + 13]
77
+ if _luhn32_check(data) != check:
78
+ return "has a wrong check digit — re-copy it from 'Actions → Show ID'"
79
+ return None
80
+
81
+
82
+ def paths_overlap(a: Path, b: Path) -> bool:
83
+ """Equal, or one inside the other. `/a/sync` vs `/a/sync2` must be False."""
84
+ ra, rb = a.resolve(), b.resolve()
85
+ return ra == rb or ra in rb.parents or rb in ra.parents
86
+
87
+
88
+ def _resolve(path: str | Path) -> Path:
89
+ return Path(path).expanduser().resolve()
90
+
91
+
92
+ @dataclass(frozen=True)
93
+ class Request:
94
+ server_id: str
95
+ server_name: str
96
+ folder_id: str
97
+ folder_path: Path
98
+ mode: str
99
+
100
+
101
+ @dataclass(frozen=True)
102
+ class Refusal:
103
+ reason: str
104
+
105
+
106
+ @dataclass(frozen=True)
107
+ class Plan:
108
+ add_device: bool
109
+ folder_action: str # "create" | "share" | "none"
110
+ lines: list[str] = field(default_factory=list)
111
+
112
+
113
+ def _folder_devices(folder: dict) -> list[str]:
114
+ return [d.get("deviceID", "") for d in folder.get("devices", [])]
115
+
116
+
117
+ def plan(config: dict, local_id: str, req: Request) -> Plan | Refusal:
118
+ """What the run would change, over the dict `GET /rest/config` returned."""
119
+ if req.server_id == local_id:
120
+ return Refusal("that is this machine's own Device ID — put the server's ID here")
121
+
122
+ devices = config.get("devices", [])
123
+ folders = config.get("folders", [])
124
+ existing = next((f for f in folders if f.get("id") == req.folder_id), None)
125
+ wanted_path = _resolve(req.folder_path)
126
+
127
+ if existing is not None:
128
+ have_path = _resolve(existing.get("path", ""))
129
+ if have_path != wanted_path:
130
+ return Refusal(
131
+ f"folder '{req.folder_id}' already exists pointing at {have_path} — "
132
+ "edit it in the Syncthing GUI instead"
133
+ )
134
+ if existing.get("type") != req.mode:
135
+ return Refusal(
136
+ f"folder '{req.folder_id}' already exists as "
137
+ f"'{existing.get('type')}', not '{req.mode}' — edit it in the Syncthing GUI instead"
138
+ )
139
+ else:
140
+ for other in folders:
141
+ other_path = _resolve(other.get("path", ""))
142
+ if paths_overlap(wanted_path, other_path):
143
+ return Refusal(
144
+ f"{wanted_path} overlaps existing folder '{other.get('id')}' at "
145
+ f"{other_path} — syncthing accepts overlapping folders and then misbehaves"
146
+ )
147
+
148
+ add_device = not any(d.get("deviceID") == req.server_id for d in devices)
149
+ if existing is None:
150
+ folder_action = "create"
151
+ elif req.server_id not in _folder_devices(existing):
152
+ folder_action = "share"
153
+ else:
154
+ folder_action = "none"
155
+
156
+ lines: list[str] = []
157
+ if add_device:
158
+ lines.append(f"Add device '{req.server_name}' ({req.server_id})")
159
+ else:
160
+ lines.append(f"Device {req.server_id} already exists — its name and settings are left alone")
161
+ if folder_action == "create":
162
+ lines.append(
163
+ f"Create folder '{req.folder_id}' at {wanted_path} "
164
+ f"({FOLDER_MODES.get(req.mode, req.mode)}), shared with both devices"
165
+ )
166
+ elif folder_action == "share":
167
+ lines.append(f"Share existing folder '{req.folder_id}' with '{req.server_name}'")
168
+ else:
169
+ lines.append(f"Folder '{req.folder_id}' is already shared with '{req.server_name}'")
170
+ lines.append("On the server you must still approve this device and the folder — nothing syncs until then")
171
+ return Plan(add_device=add_device, folder_action=folder_action, lines=lines)
172
+
173
+
174
+ def build_device(defaults: dict, req: Request) -> dict:
175
+ """The `GET /rest/config/defaults/device` template filled in for the server."""
176
+ device = dict(defaults)
177
+ device["deviceID"] = req.server_id
178
+ device["name"] = req.server_name
179
+ device["addresses"] = ["dynamic"]
180
+ device["introducer"] = False
181
+ device["autoAcceptFolders"] = False
182
+ return device
183
+
184
+
185
+ def build_folder(template_or_existing: dict, local_id: str, req: Request, action: str) -> dict:
186
+ """The folder body to POST.
187
+
188
+ For "create" the argument is the `GET /rest/config/defaults/folder` template
189
+ (which already lists the local device); for "share" it is the existing
190
+ folder, with the server device appended.
191
+ """
192
+ folder = dict(template_or_existing)
193
+ if action == "create":
194
+ folder["id"] = req.folder_id
195
+ folder["label"] = req.folder_id
196
+ folder["path"] = str(_resolve(req.folder_path))
197
+ folder["type"] = req.mode
198
+ folder["paused"] = False
199
+ device_ids = _folder_devices(folder)
200
+ for device_id in (local_id, req.server_id):
201
+ if device_id not in device_ids:
202
+ folder.setdefault("devices", []).append({"deviceID": device_id})
203
+ device_ids.append(device_id)
204
+ return folder
205
+
206
+
207
+ def verify(config: dict, req: Request) -> list[str]:
208
+ """Problems found by re-reading `GET /rest/config` after the writes.
209
+
210
+ Each message names the silent behaviour it guards against, because a 200
211
+ from the API is not evidence the config changed the way it was asked to.
212
+ """
213
+ problems: list[str] = []
214
+ devices = config.get("devices", [])
215
+ if not any(d.get("deviceID") == req.server_id for d in devices):
216
+ problems.append(
217
+ f"device {req.server_id} is absent from the config — the API accepted the "
218
+ "write but did not store it"
219
+ )
220
+ folder = next((f for f in config.get("folders", []) if f.get("id") == req.folder_id), None)
221
+ if folder is None:
222
+ problems.append(f"folder '{req.folder_id}' is absent from the config after the write")
223
+ return problems
224
+ have_path = _resolve(folder.get("path", ""))
225
+ if have_path != _resolve(req.folder_path):
226
+ problems.append(
227
+ f"folder '{req.folder_id}' was stored with path {have_path}, "
228
+ f"not {_resolve(req.folder_path)}"
229
+ )
230
+ if folder.get("type") != req.mode:
231
+ problems.append(
232
+ f"folder '{req.folder_id}' was stored as type '{folder.get('type')}' — "
233
+ f"syncthing coerces an unknown type to sendreceive rather than rejecting it "
234
+ f"(asked for '{req.mode}')"
235
+ )
236
+ if req.server_id not in _folder_devices(folder):
237
+ problems.append(
238
+ f"folder '{req.folder_id}' does not list {req.server_id} — syncthing silently "
239
+ "drops a devices entry whose device is not in the config"
240
+ )
241
+ return problems
@@ -0,0 +1,277 @@
1
+ """`devstuff configure syncthing` — pair this machine with a storage server.
2
+
3
+ Syncthing is configured through its running REST API, not a file the wizard
4
+ writes, which is why `--output` is refused and the apply path takes an explicit
5
+ Client (the live test points it at a throwaway daemon rather than the real one).
6
+
7
+ Two orderings are load-bearing, both measured against syncthing v2.1.6: the
8
+ device must exist before the folder that lists it (an unknown device's entry is
9
+ silently dropped), and the result must be re-read — a 200 proves nothing (see
10
+ model.py's docstring).
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import getpass
16
+ import os
17
+ import socket
18
+ from pathlib import Path
19
+
20
+ import questionary
21
+ from rich.markup import escape
22
+ from rich.text import Text
23
+
24
+ from dev_setup import ui
25
+ from dev_setup.configure.syncthing import api, detect, model
26
+ from dev_setup.configure.syncthing.model import (
27
+ DEFAULT_FOLDER_PATH,
28
+ DEFAULT_SERVER_NAME,
29
+ FOLDER_MODES,
30
+ Request,
31
+ )
32
+ from dev_setup.generic import _run
33
+
34
+
35
+ def config_path() -> Path:
36
+ return detect.config_file()
37
+
38
+
39
+ def apply(client: api.Client, config: dict, local_id: str, req: Request, plan: model.Plan) -> None:
40
+ """POST the device (if needed) then the folder — order matters, see above.
41
+
42
+ Raises api.ApiError; a failure on the folder write can leave the device
43
+ already added, so what succeeded is attached to the exception as `.wrote`
44
+ for the caller to report.
45
+ """
46
+ req.folder_path.mkdir(parents=True, exist_ok=True)
47
+ wrote: list[str] = []
48
+ try:
49
+ if plan.add_device:
50
+ defaults = client.get("/rest/config/defaults/device")
51
+ client.post("/rest/config/devices", model.build_device(defaults, req))
52
+ wrote.append("the device entry")
53
+ if plan.folder_action == "create":
54
+ defaults = client.get("/rest/config/defaults/folder")
55
+ client.post("/rest/config/folders", model.build_folder(defaults, local_id, req, "create"))
56
+ elif plan.folder_action == "share":
57
+ existing = next(
58
+ f for f in config.get("folders", []) if f.get("id") == req.folder_id
59
+ )
60
+ client.post(
61
+ "/rest/config/folders", model.build_folder(existing, local_id, req, "share")
62
+ )
63
+ if plan.folder_action != "none":
64
+ wrote.append("the folder")
65
+ except api.ApiError as exc:
66
+ exc.wrote = wrote
67
+ raise
68
+
69
+
70
+ def _summary(endpoint: api.Endpoint, local_id: str, req: Request) -> None:
71
+ ui.console.print()
72
+ ui.heading("Done on this side")
73
+ for label, value in [
74
+ ("This machine", f"{socket.gethostname()}"),
75
+ ("Device ID", local_id),
76
+ ("Folder", f"{req.folder_id} → {req.folder_path}"),
77
+ ("Mode", FOLDER_MODES.get(req.mode, req.mode)),
78
+ ("Server", f"{req.server_name} ({req.server_id})"),
79
+ ("Web GUI", endpoint.base_url),
80
+ ]:
81
+ ui.console.print(Text(f" {label:<12} ") + Text(str(value)))
82
+ ui.console.print()
83
+ ui.console.print(Text(" On the server:", style="bold"))
84
+ for line in (
85
+ f" 1. Add this machine's Device ID {local_id} (Actions → Add Remote Device).",
86
+ f" 2. Share folder '{req.folder_id}' with it — it appears under 'Pending' once this side connects.",
87
+ ):
88
+ ui.console.print(Text(line))
89
+ ui.console.print()
90
+
91
+
92
+ def run(*, target: Path | None = None) -> Request | None:
93
+ if target is not None:
94
+ ui.error(
95
+ "--output is not meaningful here: syncthing is configured through its "
96
+ "running local API — there is no file to export."
97
+ )
98
+ return None
99
+ if os.geteuid() == 0:
100
+ ui.error("Run this as your normal user, not root — syncthing is a per-user service.")
101
+ return None
102
+
103
+ ui.section("Syncthing pairing")
104
+ ui.dim("Add the storage server as a device and share one folder with it,")
105
+ ui.dim("through syncthing's local API. Nothing is written until you confirm.")
106
+ ui.console.print()
107
+
108
+ if not detect.has_systemd() or not detect.user_session():
109
+ ui.error("There is no systemd user session here, so syncthing.service cannot run.")
110
+ ui.dim(" On a server without a login session, the syncthing@<user> system unit is the")
111
+ ui.dim(" alternative; this wizard does not manage it.")
112
+ return None
113
+
114
+ if not detect.service_active():
115
+ ui.info("The syncthing user service is not running.")
116
+ if not ui.confirm("Enable and start syncthing.service?", default=True):
117
+ ui.dim("Cancelled — nothing was changed.")
118
+ return None
119
+ try:
120
+ _run(["systemctl", "--user", "enable", "--now", "syncthing.service"])
121
+ except RuntimeError as exc:
122
+ ui.error(f"Could not start the service: {escape(str(exc))}")
123
+ ui.dim(" Look at: systemctl --user status syncthing.service")
124
+ return None
125
+
126
+ endpoint = api.discover(detect.config_file())
127
+ if isinstance(endpoint, str):
128
+ ui.error(escape(endpoint))
129
+ ui.dim(" Look at: systemctl --user status syncthing.service")
130
+ return None
131
+ with ui.spinner("Waiting for syncthing's API…"):
132
+ status = api.wait_ready(endpoint)
133
+ if status is None:
134
+ ui.error("syncthing's local API did not come up in time.")
135
+ ui.dim(" Look at: systemctl --user status syncthing.service")
136
+ return None
137
+ client = api.Client(endpoint)
138
+
139
+ linger = detect.linger_enabled()
140
+ if linger is False:
141
+ ui.info("Linger is off: syncthing stops when you log out and only starts on login.")
142
+ ui.dim(" Enabling it keeps sync running while you are logged out — it is a")
143
+ ui.dim(" system-wide setting and needs sudo.")
144
+ if ui.confirm("Enable linger for this user? (sudo loginctl enable-linger)", default=True):
145
+ try:
146
+ _run(["sudo", "loginctl", "enable-linger", getpass.getuser()])
147
+ except RuntimeError as exc:
148
+ ui.warn(f"Could not enable linger: {escape(str(exc))}")
149
+ if detect.linger_enabled() is not True:
150
+ ui.warn("Linger still reads as off — sync will pause when you are logged out.")
151
+ # linger None means loginctl could not say — stay quiet rather than warn.
152
+
153
+ try:
154
+ config = client.get("/rest/config")
155
+ status = client.get("/rest/system/status")
156
+ local_id = status.get("myID", "")
157
+ except api.ApiError as exc:
158
+ ui.error(f"The local API refused: {escape(str(exc))}")
159
+ ui.dim(" Look at: systemctl --user status syncthing.service")
160
+ return None
161
+ if not local_id:
162
+ ui.error("syncthing did not report a Device ID — the API is answering but not ready.")
163
+ return None
164
+
165
+ # -- the questions ---------------------------------------------------------
166
+ while True:
167
+ raw_id = ui.text_input(
168
+ "Server's Device ID (on the server: Actions → Show ID):", required=True
169
+ )
170
+ problem = model.device_id_problem(raw_id)
171
+ if problem:
172
+ ui.error(f"That ID {escape(problem)}.")
173
+ continue
174
+ server_id = model.normalize_device_id(raw_id)
175
+ if server_id == local_id:
176
+ ui.error("That is this machine's own Device ID — put the server's ID here.")
177
+ continue
178
+ break
179
+
180
+ device_known = any(d.get("deviceID") == server_id for d in config.get("devices", []))
181
+ server_name = (
182
+ next(d.get("name", "") for d in config.get("devices", []) if d.get("deviceID") == server_id)
183
+ if device_known
184
+ else ui.text_input("A name for the server:", default=DEFAULT_SERVER_NAME)
185
+ )
186
+
187
+ folder_id = ui.text_input(
188
+ "Folder ID to share — it must match the server's exactly:", required=True
189
+ )
190
+ while True:
191
+ raw_path = ui.text_input("Local folder to sync:", default=DEFAULT_FOLDER_PATH)
192
+ folder_path = Path(raw_path).expanduser()
193
+ if not folder_path.is_absolute():
194
+ ui.error("That does not expand to an absolute path — use ~ or a leading /.")
195
+ continue
196
+ folder_path = folder_path.resolve()
197
+ break
198
+
199
+ mode = ui.select(
200
+ "Folder mode:",
201
+ [
202
+ questionary.Choice(title=label, value=value)
203
+ for value, label in FOLDER_MODES.items()
204
+ ],
205
+ default="sendreceive",
206
+ )
207
+ if not mode: # Escape — a silently defaulted mode is a choice nobody made
208
+ ui.dim("Cancelled — nothing was changed.")
209
+ return None
210
+
211
+ req = Request(
212
+ server_id=server_id,
213
+ server_name=server_name or DEFAULT_SERVER_NAME,
214
+ folder_id=folder_id,
215
+ folder_path=folder_path,
216
+ mode=mode,
217
+ )
218
+
219
+ outcome = model.plan(config, local_id, req)
220
+ if isinstance(outcome, model.Refusal):
221
+ ui.error(escape(outcome.reason))
222
+ return None
223
+
224
+ if outcome.add_device or outcome.folder_action != "none":
225
+ ui.console.print()
226
+ ui.heading("This will", note="nothing is written until you confirm")
227
+ for line in outcome.lines:
228
+ ui.console.print(Text(f" {line}"))
229
+ ui.console.print()
230
+ if not ui.confirm("Apply this to the running syncthing?", default=True):
231
+ ui.dim("Cancelled — nothing was changed.")
232
+ return None
233
+
234
+ try:
235
+ apply(client, config, local_id, req, outcome)
236
+ except api.ApiError as exc:
237
+ ui.error(f"The API write failed: {escape(str(exc))}")
238
+ wrote = getattr(exc, "wrote", [])
239
+ ui.dim(
240
+ f" Written before the failure: {', '.join(wrote)}."
241
+ if wrote
242
+ else " Nothing was written."
243
+ )
244
+ return None
245
+ else:
246
+ ui.info("This folder is already shared with that device — nothing to change.")
247
+
248
+ try:
249
+ config = client.get("/rest/config")
250
+ except api.ApiError as exc:
251
+ ui.error(f"Could not re-read the config to verify it: {escape(str(exc))}")
252
+ return None
253
+ problems = model.verify(config, req)
254
+ if problems:
255
+ for problem in problems:
256
+ ui.error(escape(problem))
257
+ ui.dim(" Check the state in the web GUI — the API returned 200 but the")
258
+ ui.dim(" stored config does not match what was asked for.")
259
+ return None
260
+ ui.success("Verified: the device and folder are in syncthing's config.")
261
+ _summary(endpoint, local_id, req)
262
+
263
+ try:
264
+ restart = client.get("/rest/config/restart-required")
265
+ except api.ApiError:
266
+ restart = {}
267
+ if (
268
+ isinstance(restart, dict)
269
+ and restart.get("requiresRestart")
270
+ and ui.confirm("syncthing says a restart is required — restart the service?", default=True)
271
+ ):
272
+ try:
273
+ _run(["systemctl", "--user", "restart", "syncthing.service"])
274
+ except RuntimeError as exc:
275
+ ui.error(f"Restart failed: {escape(str(exc))}")
276
+
277
+ return req
dev_setup/links.yaml CHANGED
@@ -162,3 +162,27 @@ links:
162
162
  description: Automates Docker container image updates, with scheduling, registry auth, notifications, and an HTTP API
163
163
  category: containers
164
164
  url: https://watchtower.nickfedor.com/
165
+
166
+ regex101:
167
+ name: regex101
168
+ description: Online regex tester, builder, converter, and debugger across PCRE2, JavaScript, Python, Go, Java, .NET, and Rust flavors
169
+ category: utilities
170
+ url: https://regex101.com/
171
+
172
+ prometheus-docs:
173
+ name: Prometheus
174
+ description: Open source metrics and monitoring — time-series storage, the PromQL query language, and alerting
175
+ category: monitoring
176
+ url: https://prometheus.io/
177
+
178
+ cvedetails:
179
+ name: CVEdetails
180
+ description: CVE vulnerability database combining CVE records with exploits, EPSS and CISA KEV flags, and search by vendor, product, or date
181
+ category: security
182
+ url: https://www.cvedetails.com/
183
+
184
+ security-onion:
185
+ name: Security Onion
186
+ description: Free and open platform for network and host visibility, honeypots, and log and case management, with a Pro edition
187
+ category: security
188
+ url: https://securityonionsolutions.com/software
dev_setup/tools.yaml CHANGED
@@ -859,6 +859,37 @@ tools:
859
859
  PY
860
860
  fi
861
861
 
862
+ syncthing:
863
+ name: Syncthing
864
+ description: Peer-to-peer file sync daemon (`devstuff configure syncthing` to pair devices)
865
+ category: tools
866
+ type: bash
867
+ check_cmd: syncthing
868
+ help_cmd: syncthing --help
869
+ docs_url: https://docs.syncthing.net/
870
+ install_script: |
871
+ set -euo pipefail
872
+ # The official apt repo (v2), not the Ubuntu archive (which ships 1.29).
873
+ sudo install -d -m 0755 /etc/apt/keyrings
874
+ sudo curl -fsSL -o /etc/apt/keyrings/syncthing-archive-keyring.gpg https://syncthing.net/release-key.gpg
875
+ echo "deb [signed-by=/etc/apt/keyrings/syncthing-archive-keyring.gpg] https://apt.syncthing.net/ syncthing stable-v2" | sudo tee /etc/apt/sources.list.d/syncthing.list >/dev/null
876
+ sudo apt-get update -q
877
+ sudo apt-get install -y syncthing
878
+ # The packaged unit is a systemd *user* service. A CI container has no user
879
+ # session to enable it in, and that is not a failure of the install.
880
+ if systemctl --user show-environment >/dev/null 2>&1; then
881
+ systemctl --user enable --now syncthing.service
882
+ else
883
+ echo "No systemd user session here; start it later with: systemctl --user enable --now syncthing.service"
884
+ fi
885
+ remove_script: |
886
+ set -euo pipefail
887
+ systemctl --user disable --now syncthing.service 2>/dev/null || true
888
+ sudo apt-get remove -y syncthing
889
+ echo "Config and keys in ~/.local/state/syncthing were left in place."
890
+ echo "The apt source and keyring were left in place — they may predate this install."
891
+ echo "Linger (loginctl enable-linger), if it was enabled, was left unchanged."
892
+
862
893
  uv:
863
894
  name: uv
864
895
  description: Astral Python package and project manager
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: devstuff
3
- Version: 2.20.0
3
+ Version: 2.22.0
4
4
  Summary: Development environment setup CLI for Linux
5
5
  Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
6
6
  Author-email: Sawyer <sawyerksu@gmail.com>
@@ -581,6 +581,7 @@ devstuff configure starship --output /tmp/try.toml # write elsewhere, leave th
581
581
  | `lazygit` | Icons, diff pager, panels and git behaviour |
582
582
  | `pre-commit` | Which git hooks run, when they run, and what they're allowed to rewrite |
583
583
  | `starship` | Prompt style, colour palette, which sections appear, and layout |
584
+ | `syncthing` | Pair this machine with a server device and share one folder, via the local API |
584
585
 
585
586
  The reptyr wizard verifies the live kernel setting after applying it. Other wizards check
586
587
  their result against the real tool before saving. What that check can prove
@@ -593,6 +594,7 @@ varies a lot, and the wizards say so rather than implying more than they know:
593
594
  | `docker` | key typos, malformed CIDRs, numeric log options | **five configs `dockerd --validate` accepts that stop every container from starting** |
594
595
  | `lazygit` | wrong types (refuses to start) | **unknown keys and invalid enum values** — both silently ignored |
595
596
  | `pre-commit` | the file's shape | **hook ids** — `validate-config` never opens a repository |
597
+ | `syncthing` | malformed IDs and payloads (HTTP 400) | **whether the config actually stored what was sent** — the API returns 200 while dropping a folder's unknown device or coercing an unknown folder type |
596
598
 
597
599
  #### Commitizen wizard
598
600
 
@@ -1668,6 +1670,7 @@ links:
1668
1670
  | `pre-commit` | pre-commit | Git hook manager for automated code quality checks (`devstuff configure pre-commit`) | `pre-commit --help` |
1669
1671
  | `saml2aws` | saml2aws | SAML → AWS STS credentials CLI (Versent) | `saml2aws --help` |
1670
1672
  | `starship` | Starship | Fast, cross-shell customizable prompt (`devstuff configure starship`) | `starship --help` |
1673
+ | `syncthing` | Syncthing | Peer-to-peer file sync daemon (`devstuff configure syncthing` to pair devices) | `syncthing --help` |
1671
1674
  | `yq` | yq | Portable command-line YAML/JSON/XML processor | `yq --help` |
1672
1675
 
1673
1676
  ### Languages
@@ -16,13 +16,13 @@ dev_setup/functions_catalog.py,sha256=YgR2hY9HM1iol1AZcF-_j02EXCP9U4P3e_5eWes9KH
16
16
  dev_setup/functions_registry.py,sha256=YSl-VgNXPf0hj4WgReg-pZUj4fAjFlwvC165dgon_BE,3682
17
17
  dev_setup/generic.py,sha256=Lg0c41TVT4Vj6yT1H9qH1zWYmZN4c_JtA9wtM6bdopc,43921
18
18
  dev_setup/links.schema.json,sha256=V9_1UA8Ejfu0j6-VczH0blW1mlGupXx56NhApLtHHKc,1938
19
- dev_setup/links.yaml,sha256=HwuTpvWoWuaTxsK3TkoUug-53f5YygjbS8-s3EpnSVk,5203
19
+ dev_setup/links.yaml,sha256=GB4KlZwsZwwnz9_UUFT6YwlJpYuCMnY3Ak36FdVEekg,6136
20
20
  dev_setup/links_catalog.py,sha256=Xe7s9oqiCrfQPUwE-X9o6p5VkU7mH9PjY9NMyn6VbHg,4610
21
21
  dev_setup/links_registry.py,sha256=xyq49oH1u_CX85UcizKSuxuy_pzurNoDwSRg3YftUMY,2439
22
22
  dev_setup/profile.py,sha256=NiSOXXwEPX6IIT8FagnAC-tcg49HWijFDSm2jn3hjts,13632
23
23
  dev_setup/registry.py,sha256=eHEuo4p0O0CHDWatFuOlSFiSAz5L6YFYmv9tAGHYMt4,2510
24
24
  dev_setup/snapshot.py,sha256=A2G_6pHSaGhDT1PJAZ6eW83GdSdCGs2r79yH8FCa0Qs,5330
25
- dev_setup/tools.yaml,sha256=D-8gtXs421EBU-s-8o6ZQitn1R2HvbiFqeL3q4wky8Y,35686
25
+ dev_setup/tools.yaml,sha256=4zv4ZDPIj-cYeXiiXAt5VfiEdKo2lt9F_3HkJOB0R1c,37314
26
26
  dev_setup/ui.py,sha256=B0t4hYlZ7jIMIdldMCImLNBJT1NQgZ4ff8ItjfHRNl0,23879
27
27
  dev_setup/updates.py,sha256=p9_nbfaX_73hE71kr5ZDZA5o85T9XTR0mjbo15f950I,6046
28
28
  dev_setup/verbose.py,sha256=N3U9JAYOvFwdd8DT6W7Pqq6RCIUfbcQnPsm0O1TnvQY,5003
@@ -68,7 +68,7 @@ dev_setup/commands/remove_cmd.py,sha256=Az0qMes4M5237c_ntQ1SemS38gTpLZy2GhSK_gUr
68
68
  dev_setup/commands/run_cmd.py,sha256=e1xfWt09UALiAe03AxzdvZyYpj0V7WKk2-E_nbk9hIw,2933
69
69
  dev_setup/commands/skills_cmd.py,sha256=j4rleYEW4lt-O2ssDwGyhwmk2Wiip64C4Z7iPT6c3y0,7482
70
70
  dev_setup/commands/update_cmd.py,sha256=9W4mEmdF7Ao7xnrRbOKB2myj6eNLxXAO5ZXm281N2v0,6337
71
- dev_setup/configure/__init__.py,sha256=PXOtKObPRXnBZlVNSaJIUNscuysaUy3cJppiCEhTRhE,3488
71
+ dev_setup/configure/__init__.py,sha256=7gsB8XaH83A95hkYsvtC2lahd6pXsY4lly4T-c7WVF4,3723
72
72
  dev_setup/configure/ansible/__init__.py,sha256=huQL_tfiU1l0WI6nzjTnGZlxCQX2aH7E9n9TrfwmIpU,407
73
73
  dev_setup/configure/ansible/detect.py,sha256=5LkdbJg5BU2lrIU4CZm_Lhr6Sm4TJMCh1sMrsRK6rgc,9531
74
74
  dev_setup/configure/ansible/model.py,sha256=uqVPf-tS5VdMn3NSEvcV46GXrqmbVecWNkF2xvx1uGI,22584
@@ -114,6 +114,11 @@ dev_setup/configure/starship/model.py,sha256=ct1YrR3xLqcKMP20TvKZQ0Oc-OxHMrRjnei
114
114
  dev_setup/configure/starship/preview.py,sha256=ZaNhNA3AeHHtPnMqrJbB9XVVXDFbH1R36jm8xyYdt2U,6145
115
115
  dev_setup/configure/starship/render.py,sha256=25O8w4IteVd_ELwmIWhcYAn042W6yZ--zbTMcJpzVJc,11277
116
116
  dev_setup/configure/starship/wizard.py,sha256=F3-xVQmZjYtiQAICyJXeSogjcASSsVbaP2b8YHAX9TM,28726
117
+ dev_setup/configure/syncthing/__init__.py,sha256=HC-d7y06Spbr2CjiiVvDrd5blA6LOz40s3LQIVBlu5c,86
118
+ dev_setup/configure/syncthing/api.py,sha256=TGZxH2r3dYhgYpvjdFGge4YweS8dQA48vxTbGwG3T7U,5530
119
+ dev_setup/configure/syncthing/detect.py,sha256=oW1JNLA4nT8fQmMjTSLR06i29ms6lQ9ZxVtjkg_8Y1M,2190
120
+ dev_setup/configure/syncthing/model.py,sha256=XMU_eF18ImQ05vQQecnE1e0Caa_Vll9jhqBr-PeB6UY,9446
121
+ dev_setup/configure/syncthing/wizard.py,sha256=i7SJfJ2WtXdIfmsS1F-V5vX_kENIMoraf3HQvinUQJA,10913
117
122
  dev_setup/mcp/__init__.py,sha256=a3DUEjK_mIpC4QsaPaArwKqaVvtujfzSu8WMpMh6G70,89
118
123
  dev_setup/mcp/core.py,sha256=I0zNOWLByBAcpJjE1oz9Bh2VefZF9sZL88TfTENwFHo,20038
119
124
  dev_setup/mcp/http.py,sha256=w51uX-5LdgqS7M673JhGe_dHH9Oqdeg6qMkNrP6UjnU,17605
@@ -122,7 +127,7 @@ dev_setup/mcp/printconfig.py,sha256=3u_b4UpDwJ95u0_AfZuZuch1_-bOojdAg-08c5l6g28,
122
127
  dev_setup/mcp/process.py,sha256=IV203HLaCelWb89IhV73_8NWNAGglXRtXpwpHk39dD4,4752
123
128
  dev_setup/mcp/stdio.py,sha256=k-s2722_N2j92umkKo_Bq6KijfQGKFRudYVsh2H4xAk,6121
124
129
  dev_setup/mcp/token.py,sha256=Pr7MCY6FtY8g2oQWB291mMooiZY0eu659Qk3mh9auWE,3397
125
- devstuff-2.20.0.dist-info/METADATA,sha256=ovK1n1ErBKE-zIEK6zx6VkkSi7DGuYOGVUxv0g5iKwU,98767
126
- devstuff-2.20.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
127
- devstuff-2.20.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
128
- devstuff-2.20.0.dist-info/RECORD,,
130
+ devstuff-2.22.0.dist-info/METADATA,sha256=L6KuJPKJ9hUYZCVTd9n8CuNWYqA4KTZ_468-1o8gcqk,99205
131
+ devstuff-2.22.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
132
+ devstuff-2.22.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
133
+ devstuff-2.22.0.dist-info/RECORD,,