hermes-pilot 0.0.0-stage → 0.2.2

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 (74) hide show
  1. package/LICENSE +21 -0
  2. package/README.ja.md +419 -0
  3. package/README.md +428 -2
  4. package/__init__.py +15 -0
  5. package/apps/bridge/src/api-errors.js +165 -0
  6. package/apps/bridge/src/architect.js +1298 -0
  7. package/apps/bridge/src/auth.js +202 -0
  8. package/apps/bridge/src/capabilities.js +256 -0
  9. package/apps/bridge/src/capture.js +145 -0
  10. package/apps/bridge/src/chat-profile.js +95 -0
  11. package/apps/bridge/src/config.js +73 -0
  12. package/apps/bridge/src/discord.js +89 -0
  13. package/apps/bridge/src/gitinfo.js +211 -0
  14. package/apps/bridge/src/hermes.js +97 -0
  15. package/apps/bridge/src/inbox.js +347 -0
  16. package/apps/bridge/src/kanban.js +361 -0
  17. package/apps/bridge/src/lang.js +60 -0
  18. package/apps/bridge/src/live.js +285 -0
  19. package/apps/bridge/src/memos.js +150 -0
  20. package/apps/bridge/src/ops.js +201 -0
  21. package/apps/bridge/src/pair-codes.js +125 -0
  22. package/apps/bridge/src/pipeline-optimizer.js +513 -0
  23. package/apps/bridge/src/pipeline-watcher.js +1022 -0
  24. package/apps/bridge/src/qr.js +808 -0
  25. package/apps/bridge/src/repos.js +544 -0
  26. package/apps/bridge/src/review-watcher.js +271 -0
  27. package/apps/bridge/src/review.js +1749 -0
  28. package/apps/bridge/src/search.js +162 -0
  29. package/apps/bridge/src/server.js +1745 -0
  30. package/apps/bridge/src/snippets.js +373 -0
  31. package/apps/bridge/src/specs.js +806 -0
  32. package/apps/bridge/src/tail.js +28 -0
  33. package/apps/bridge/src/telemetry.js +667 -0
  34. package/apps/bridge/src/term-snippets.js +228 -0
  35. package/apps/bridge/src/transcript.js +231 -0
  36. package/apps/bridge/src/usage.js +294 -0
  37. package/apps/bridge/src/workerFeed.js +72 -0
  38. package/apps/dashboard/index.js +2014 -0
  39. package/apps/dashboard/manifest.json +14 -0
  40. package/apps/dashboard/pilot_dashboard.py +1466 -0
  41. package/apps/dashboard/plugin_api.py +237 -0
  42. package/apps/dashboard/plugin_init.py +15 -0
  43. package/apps/dashboard/style.css +928 -0
  44. package/apps/web/dist/assets/TermPane-DYP7pi_n.css +32 -0
  45. package/apps/web/dist/assets/TermPane-q4f5Zu0I.js +12 -0
  46. package/apps/web/dist/assets/index-BzUof8lw.js +94 -0
  47. package/apps/web/dist/assets/index-DwZdbPU7.css +1 -0
  48. package/apps/web/dist/favicon.ico +0 -0
  49. package/apps/web/dist/icon-180-v6.png +0 -0
  50. package/apps/web/dist/icon-192-v6.png +0 -0
  51. package/apps/web/dist/icon-512-v6.png +0 -0
  52. package/apps/web/dist/icon-maskable-192-v6.png +0 -0
  53. package/apps/web/dist/icon-maskable-512-v6.png +0 -0
  54. package/apps/web/dist/icon-v6.svg +15 -0
  55. package/apps/web/dist/index.html +21 -0
  56. package/apps/web/dist/manifest.webmanifest +49 -0
  57. package/apps/web/dist/sw.js +69 -0
  58. package/bin/hermes-pilot.mjs +964 -0
  59. package/dashboard/dist/index.js +2014 -0
  60. package/dashboard/dist/style.css +928 -0
  61. package/dashboard/manifest.json +14 -0
  62. package/dashboard/pilot_dashboard.py +1466 -0
  63. package/dashboard/plugin_api.py +237 -0
  64. package/package.json +75 -4
  65. package/plugin.json +70 -0
  66. package/plugin.yaml +4 -0
  67. package/scripts/deploy.mjs +58 -0
  68. package/scripts/migrate-to-hermes-pilot.mjs +472 -0
  69. package/scripts/postinstall.mjs +32 -0
  70. package/scripts/sync-dashboard.mjs +98 -0
  71. package/skills/annotation/SKILL.md +138 -0
  72. package/skills/quick-review/SKILL.md +200 -0
  73. package/skills/quick-review/assets/sheet-template.html +175 -0
  74. package/skills/spec-architect/SKILL.md +226 -0
@@ -0,0 +1,1466 @@
1
+ """Logic behind the Hermes Pilot tab on the standard Hermes dashboard.
2
+
3
+ The FastAPI shim (``plugin_api.py``) deliberately stays thin: everything that can
4
+ be wrong — config validation, the atomic write, service probing, the bridge call,
5
+ and above all *not* leaking the app token to the browser — lives here so it can
6
+ be tested without FastAPI, a live bridge, or a real launchd/systemd.
7
+
8
+ Design notes
9
+ ------------
10
+ * **Token never leaves this process.** The bridge accepts ``?t=<token>`` for GET
11
+ requests (``apps/bridge/src/auth.js`` → ``authorized``). We read the token from
12
+ ``<dataDir>/token`` (0600) only to call the bridge from Python, and every
13
+ payload that goes back to the browser is passed through :func:`redact`.
14
+ * **Stdlib only.** No ``requests``; ``urllib`` is enough for a few loopback GETs.
15
+ * **Injected side effects.** Service probing, the bridge fetch, LAN detection and
16
+ the CLI spawn are parameters with real defaults, so tests pass fakes.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import json
22
+ import os
23
+ import platform as platform_module
24
+ import re
25
+ import shutil
26
+ import socket
27
+ import subprocess
28
+ import sys
29
+ import tempfile
30
+ import urllib.error
31
+ import urllib.parse
32
+ import urllib.request
33
+ from pathlib import Path
34
+ from typing import Any, Callable, Iterable, Mapping, Optional
35
+
36
+ #: Bridge default port (SPEC §8.1).
37
+ DEFAULT_PORT = 4097
38
+ #: Bridge binds loopback; the dashboard plugin talks to it server-side.
39
+ BRIDGE_HOST = "127.0.0.1"
40
+ #: Service unit per platform (SPEC §5.3 / D9).
41
+ SERVICE_UNITS = {"darwin": "ai.hermes.pilot", "linux": "hermes-pilot.service"}
42
+ SERVICE_MANAGERS = {"darwin": "launchd", "linux": "systemd"}
43
+ #: Repository scan roots (`repos.json` defaults, SPEC §5.1).
44
+ DEFAULT_SCAN_DIRS = ["~/Projects", "~/projects"]
45
+ #: Config keys this tab owns.
46
+ CONFIG_FIELDS = ("lang", "scanDirs", "tlsPort", "tailscaleDns", "servicePort")
47
+ #: Allowed UI languages (SPEC D5: English default + Japanese).
48
+ LANGUAGES = ("en", "ja", "auto")
49
+ #: Service actions the tab may trigger (SPEC §8.1).
50
+ SERVICE_ACTIONS = ("install", "restart", "status")
51
+ #: `POST /repos` actions (SPEC §4.1 — Repositories card, closes G3).
52
+ REPO_ACTIONS = ("add", "hide", "unhide", "pin", "unpin", "createBoard")
53
+ #: Snippet kinds and the bridge route each one lives on (SPEC §4.2 / §3.2).
54
+ SNIPPET_KINDS = ("chat", "term")
55
+ #: Snippet limits mirrored from `apps/bridge/src/snippets.js`.
56
+ LABEL_MAX = 20
57
+ TEXT_MAX = 400
58
+ CUSTOM_MAX = 16
59
+ HOT_LIMIT = 8
60
+ #: Log files the tab may show (SPEC §4.2). `audit` is the bridge's JSONL trail.
61
+ LOG_FILES = {
62
+ "gateway": ("gateway.log",),
63
+ "errors": ("errors.log",),
64
+ "pilot": ("pilot.out.log", "pilot.err.log"),
65
+ "audit": (),
66
+ }
67
+ #: `?token=…` / `&t=…` in a log line — the bridge logs pairing URLs, and a
68
+ #: pairing code is still a credential until it expires.
69
+ LOG_QUERY_SECRET = re.compile(r"([?&](?:token|t)=)[^&\s\"'<>]+")
70
+ #: A log response is bounded: 1000 lines from the last 256 KiB.
71
+ LOG_LINES_MAX = 1000
72
+ LOG_READ_BYTES = 256 * 1024
73
+ #: `c-<base36>` custom snippet ids, same pattern the bridge accepts.
74
+ CUSTOM_ID_RE = re.compile(r"^c-[a-z0-9]{1,20}$")
75
+ #: Anything that looks like the 256-bit hex app token, or another hex secret.
76
+ HEX_SECRET = re.compile(r"[0-9a-fA-F]{32,}")
77
+ #: Hostname (RFC 1123) — used to validate ``tailscaleDns``.
78
+ HOSTNAME_RE = re.compile(
79
+ r"^(?=.{1,253}\.?$)[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?"
80
+ r"(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*\.?$"
81
+ )
82
+
83
+
84
+ class BridgeUnavailable(RuntimeError):
85
+ """The bridge (:4097) did not answer — the tab reports this, it never crashes."""
86
+
87
+
88
+ class MissingCli(RuntimeError):
89
+ """``hermes-pilot init`` was never run in this HERMES_HOME."""
90
+
91
+
92
+ # --------------------------------------------------------------------------- paths
93
+
94
+
95
+ def hermes_home(env: Optional[Mapping[str, str]] = None) -> Path:
96
+ """Resolve ``HERMES_HOME``, unwrapping a profile directory.
97
+
98
+ Worker/cron processes point ``HERMES_HOME`` at ``~/.hermes/profiles/<name>``;
99
+ the same correction as ``bin/hermes-pilot.mjs`` / ``apps/bridge/src/config.js``.
100
+ """
101
+ env = os.environ if env is None else env
102
+ home = Path(env.get("HOME") or Path.home())
103
+ raw = env.get("HERMES_HOME") or str(home / ".hermes")
104
+ resolved = Path(os.path.expanduser(str(raw)))
105
+ if resolved.parent.name == "profiles":
106
+ return resolved.parent.parent
107
+ return resolved
108
+
109
+
110
+ def resolve_paths(env: Optional[Mapping[str, str]] = None) -> dict[str, Path]:
111
+ """Plugin data paths (SPEC §3.2 / D1)."""
112
+ env = os.environ if env is None else env
113
+ home = Path(env.get("HOME") or Path.home())
114
+ hh = hermes_home(env)
115
+ data_dir = Path(env.get("HP_DATA_DIR") or os.path.expanduser(str(hh / "plugin-data" / "hermes-pilot")))
116
+ # Same override the bridge honours (`apps/bridge/src/config.js`), so both
117
+ # processes read and write one `repos.json`.
118
+ repos_path = Path(env.get("HP_REPOS_JSON") or os.path.expanduser(str(data_dir / "repos.json")))
119
+ return {
120
+ "home": home,
121
+ "hermesHome": hh,
122
+ "dataDir": data_dir,
123
+ "configPath": data_dir / "config.json",
124
+ "tokenPath": data_dir / "token",
125
+ # Written by `hermes-pilot init`: where the CLI lives, so `service` can spawn it.
126
+ "dashboardMetaPath": data_dir / "dashboard.json",
127
+ # Repository settings (scanDirs / pinned / hidden / custom) — G3: one file,
128
+ # edited from either the PWA or this tab.
129
+ "reposPath": repos_path,
130
+ # Snippet stores (SPEC §3.2 / §4.2): built-in overrides + custom entries.
131
+ "snippetsPath": data_dir / "snippets.json",
132
+ "termSnippetsPath": data_dir / "term-snippets.json",
133
+ # Logs & audit card (SPEC §4.2).
134
+ "auditPath": data_dir / "audit.jsonl",
135
+ "logDir": hh / "logs",
136
+ }
137
+
138
+
139
+ def read_token(paths: Mapping[str, Path]) -> Optional[str]:
140
+ """Read the app token (never returned to the browser)."""
141
+ try:
142
+ token = Path(paths["tokenPath"]).read_text(encoding="utf-8").strip()
143
+ except OSError:
144
+ return None
145
+ return token or None
146
+
147
+
148
+ def read_dashboard_meta(paths: Mapping[str, Path]) -> Optional[dict[str, Any]]:
149
+ """Where the CLI lives, as recorded by ``hermes-pilot init``."""
150
+ try:
151
+ raw = json.loads(Path(paths["dashboardMetaPath"]).read_text(encoding="utf-8"))
152
+ except (OSError, ValueError):
153
+ return None
154
+ if not isinstance(raw, dict) or not raw.get("cli"):
155
+ return None
156
+ return raw
157
+
158
+
159
+ # --------------------------------------------------------------------------- config
160
+
161
+
162
+ def default_config(port: int = DEFAULT_PORT) -> dict[str, Any]:
163
+ """Config shape written by ``hermes-pilot init`` (SPEC §3.2)."""
164
+ return {
165
+ "lang": "en",
166
+ "scanDirs": list(DEFAULT_SCAN_DIRS),
167
+ "tlsPort": None,
168
+ "tailscaleDns": None,
169
+ "servicePort": port,
170
+ }
171
+
172
+
173
+ def read_config(config_path: Path | str) -> dict[str, Any]:
174
+ """Read ``config.json``, tolerating a missing or half-written file."""
175
+ cfg = default_config()
176
+ try:
177
+ raw = json.loads(Path(config_path).read_text(encoding="utf-8"))
178
+ except (OSError, ValueError):
179
+ return cfg
180
+ if not isinstance(raw, dict):
181
+ return cfg
182
+ if isinstance(raw.get("lang"), str) and raw["lang"] in LANGUAGES:
183
+ cfg["lang"] = raw["lang"]
184
+ if isinstance(raw.get("scanDirs"), list):
185
+ dirs = [str(d).strip() for d in raw["scanDirs"] if str(d).strip()]
186
+ if dirs:
187
+ cfg["scanDirs"] = dirs
188
+ raw_port = raw.get("servicePort")
189
+ if raw_port is not None and str(raw_port).strip():
190
+ try:
191
+ cfg["servicePort"] = int(str(raw_port).strip())
192
+ except (TypeError, ValueError):
193
+ cfg["servicePort"] = DEFAULT_PORT
194
+ else:
195
+ cfg["servicePort"] = DEFAULT_PORT
196
+ try:
197
+ tls = raw.get("tlsPort")
198
+ cfg["tlsPort"] = int(tls) if tls not in (None, "", 0) else None
199
+ except (TypeError, ValueError):
200
+ cfg["tlsPort"] = None
201
+ dns = raw.get("tailscaleDns")
202
+ cfg["tailscaleDns"] = str(dns).strip().rstrip(".") if isinstance(dns, str) and dns.strip() else None
203
+ return cfg
204
+
205
+
206
+ def expand_path(value: str, home: Optional[Path] = None) -> str:
207
+ """Expand ``~`` against *home* (not the process user, so tests can redirect it)."""
208
+ home = Path(home) if home is not None else Path.home()
209
+ text = str(value).strip()
210
+ if text == "~":
211
+ return str(home)
212
+ if text.startswith("~/"):
213
+ return str(home / text[2:])
214
+ return text
215
+
216
+
217
+ def shorten_path(path: str, home: Optional[Path] = None) -> str:
218
+ """Store paths ``~``-relative so ``config.json`` stays portable across machines."""
219
+ home = Path(home) if home is not None else Path.home()
220
+ try:
221
+ rel = Path(path).relative_to(home)
222
+ except ValueError:
223
+ return str(path)
224
+ return "~" if str(rel) == "." else f"~/{rel}"
225
+
226
+
227
+ def _coerce_port(
228
+ raw: Any, field: str, errors: dict[str, str], messages: dict[str, str], *, allow_null: bool = False
229
+ ) -> Optional[int]:
230
+ """Validate a TCP port; ``None`` means "not configured" when *allow_null*."""
231
+ if raw is None or (isinstance(raw, str) and not raw.strip()):
232
+ if allow_null:
233
+ return None
234
+ errors[field] = "required"
235
+ messages[field] = "A port is required"
236
+ return None
237
+ try:
238
+ value = int(str(raw).strip())
239
+ except (TypeError, ValueError):
240
+ errors[field] = "not_a_number"
241
+ messages[field] = "Port must be a number between 1 and 65535"
242
+ return None
243
+ if not 1 <= value <= 65535:
244
+ errors[field] = "out_of_range"
245
+ messages[field] = "Port must be between 1 and 65535"
246
+ return None
247
+ return value
248
+
249
+
250
+ def validate_config(
251
+ payload: Any,
252
+ *,
253
+ home: Optional[Path] = None,
254
+ is_dir: Optional[Callable[[str], bool]] = None,
255
+ ) -> dict[str, Any]:
256
+ """Validate a ``PUT /config`` body (SPEC §8.1 contract for ``config.json``).
257
+
258
+ ``scanDirs`` must be real directories (``~`` expanded), ports must be
259
+ 1..65535 and ``tailscaleDns`` a hostname. Returns per-field error *codes* plus
260
+ English messages so the browser can localise the code it knows about.
261
+ """
262
+ home_path = Path(home) if home is not None else Path.home()
263
+ is_dir = is_dir or os.path.isdir
264
+ raw: Mapping[str, Any] = payload if isinstance(payload, Mapping) else {}
265
+
266
+ errors: dict[str, str] = {}
267
+ messages: dict[str, str] = {}
268
+ value: dict[str, Any] = {}
269
+
270
+ lang = raw.get("lang", "en")
271
+ if lang not in LANGUAGES:
272
+ errors["lang"] = "invalid_lang"
273
+ messages["lang"] = f"Language must be one of {', '.join(LANGUAGES)}"
274
+ else:
275
+ value["lang"] = lang
276
+
277
+ dirs: Any = raw.get("scanDirs", list(DEFAULT_SCAN_DIRS))
278
+ if isinstance(dirs, str):
279
+ dirs = dirs.splitlines()
280
+ if not isinstance(dirs, list):
281
+ errors["scanDirs"] = "invalid_list"
282
+ messages["scanDirs"] = "Scan directories must be a list"
283
+ else:
284
+ cleaned: list[str] = []
285
+ bad: Optional[str] = None
286
+ bad_code = "not_a_directory"
287
+ for item in dirs:
288
+ text = str(item).strip()
289
+ if not text:
290
+ continue
291
+ absolute = expand_path(text, home_path)
292
+ if Path(absolute) == home_path:
293
+ # Scanning `~` itself walks every project, node_modules included.
294
+ bad = text
295
+ bad_code = "home_directory"
296
+ break
297
+ if not is_dir(absolute):
298
+ bad = text
299
+ bad_code = "not_a_directory"
300
+ break
301
+ short = shorten_path(absolute, home_path)
302
+ if short not in cleaned:
303
+ cleaned.append(short)
304
+ if bad is not None:
305
+ errors["scanDirs"] = bad_code
306
+ messages["scanDirs"] = (
307
+ f"{bad} is the home directory itself — pick the folders under it"
308
+ if bad_code == "home_directory"
309
+ else f"{bad} is not an existing directory"
310
+ )
311
+ elif not cleaned:
312
+ errors["scanDirs"] = "empty"
313
+ messages["scanDirs"] = "Register at least one directory to scan"
314
+ elif len(cleaned) > 20:
315
+ errors["scanDirs"] = "too_many"
316
+ messages["scanDirs"] = "At most 20 scan directories"
317
+ else:
318
+ value["scanDirs"] = cleaned
319
+
320
+ tls_port = _coerce_port(raw.get("tlsPort"), "tlsPort", errors, messages, allow_null=True)
321
+ if "tlsPort" not in errors:
322
+ value["tlsPort"] = tls_port
323
+
324
+ service_port = _coerce_port(raw.get("servicePort"), "servicePort", errors, messages)
325
+ if "servicePort" not in errors:
326
+ value["servicePort"] = service_port
327
+
328
+ dns = raw.get("tailscaleDns")
329
+ dns_text = str(dns).strip().rstrip(".") if isinstance(dns, str) else ""
330
+ if dns_text and not HOSTNAME_RE.match(dns_text):
331
+ errors["tailscaleDns"] = "invalid_hostname"
332
+ messages["tailscaleDns"] = "Use a hostname such as machine.tailnet-name.ts.net"
333
+ else:
334
+ value["tailscaleDns"] = dns_text or None
335
+
336
+ return {"ok": not errors, "errors": errors, "messages": messages, "value": value}
337
+
338
+
339
+ def write_config_atomic(config_path: Path | str, value: Mapping[str, Any]) -> dict[str, Any]:
340
+ """Write ``config.json`` via tmp → rename, mode 0600 (SPEC §8.1)."""
341
+ target = Path(config_path)
342
+ target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
343
+ payload = {key: value.get(key) for key in CONFIG_FIELDS if key in value}
344
+ body = json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
345
+ fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=".config-", suffix=".json")
346
+ try:
347
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
348
+ fh.write(body)
349
+ fh.flush()
350
+ os.fsync(fh.fileno())
351
+ os.chmod(tmp_name, 0o600)
352
+ os.replace(tmp_name, target)
353
+ except BaseException:
354
+ try:
355
+ os.unlink(tmp_name)
356
+ except OSError:
357
+ pass
358
+ raise
359
+ return payload
360
+
361
+
362
+ # --------------------------------------------------------------------------- service
363
+
364
+
365
+ def _run(argv: list[str], timeout: float = 4.0) -> tuple[int, str]:
366
+ """Run a probe/command, returning ``(exit code, stdout+stderr)`` — never raising."""
367
+ try:
368
+ proc = subprocess.run(
369
+ argv, capture_output=True, text=True, timeout=timeout, check=False
370
+ )
371
+ except (OSError, subprocess.SubprocessError) as exc: # missing binary, timeout
372
+ return -1, str(exc)
373
+ return proc.returncode, f"{proc.stdout or ''}{proc.stderr or ''}".strip()
374
+
375
+
376
+ def service_key(platform: Optional[str] = None) -> Optional[str]:
377
+ """Normalise ``sys.platform`` to a unit-table key."""
378
+ name = platform or sys.platform
379
+ if name == "darwin":
380
+ return "darwin"
381
+ if name.startswith("linux"):
382
+ return "linux"
383
+ return None
384
+
385
+
386
+ def service_status(
387
+ *,
388
+ platform: Optional[str] = None,
389
+ uid: Optional[int] = None,
390
+ run: Optional[Callable[[list[str]], tuple[int, str]]] = None,
391
+ ) -> dict[str, Any]:
392
+ """Probe the keep-alive service: ``{manager, unit, state}`` (SPEC §5.3 / §8.1)."""
393
+ run = run or _run
394
+ key = service_key(platform)
395
+ if key is None:
396
+ return {"manager": "none", "unit": None, "state": "unknown"}
397
+ unit = SERVICE_UNITS[key]
398
+ if key == "darwin":
399
+ owner = uid if uid is not None else os.getuid()
400
+ code, _ = run(["launchctl", "print", f"gui/{owner}/{unit}"])
401
+ state = "running" if code == 0 else "stopped"
402
+ else:
403
+ code, out = run(["systemctl", "--user", "is-active", unit])
404
+ state = "running" if code == 0 and out.strip() == "active" else "stopped"
405
+ return {"manager": SERVICE_MANAGERS[key], "unit": unit, "state": state}
406
+
407
+
408
+ def run_service(
409
+ action: str,
410
+ *,
411
+ paths: Optional[Mapping[str, Path]] = None,
412
+ run: Optional[Callable[[list[str]], tuple[int, str]]] = None,
413
+ timeout: float = 90.0,
414
+ ) -> dict[str, Any]:
415
+ """Spawn ``hermes-pilot service <action>`` and return its stdout (SPEC §8.1).
416
+
417
+ ``restart`` is only ever reached from an explicit two-tap in the browser; this
418
+ function adds no confirmation of its own because it is not a destructive
419
+ operation (the bridge process is restarted, no data is removed).
420
+ """
421
+ if action not in SERVICE_ACTIONS:
422
+ raise ValueError(f"Unknown service action: {action!r}")
423
+ paths = paths or resolve_paths()
424
+ meta = read_dashboard_meta(paths)
425
+ if meta is None:
426
+ raise MissingCli("Run `hermes-pilot init` first: the CLI location is not recorded")
427
+ cli = Path(meta["cli"])
428
+ if not cli.exists():
429
+ raise MissingCli(f"CLI not found at {cli}")
430
+ node = str(meta.get("node") or shutil.which("node") or "node")
431
+ run = run or (lambda argv: _run(argv, timeout=timeout))
432
+ code, output = run([node, str(cli), "service", action])
433
+ return {"ok": code == 0, "action": action, "code": code, "stdout": output[-8000:]}
434
+
435
+
436
+ # --------------------------------------------------------------------------- bridge
437
+
438
+
439
+ def lan_ip(timeout: float = 0.3) -> Optional[str]:
440
+ """Best-effort LAN address (no packet is sent: UDP connect only picks a route)."""
441
+ sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
442
+ try:
443
+ sock.settimeout(timeout)
444
+ # RFC 5737 TEST-NET-1 — documentation range, never a real peer.
445
+ sock.connect(("192.0.2.1", 9))
446
+ ip = sock.getsockname()[0]
447
+ except OSError:
448
+ return None
449
+ finally:
450
+ sock.close()
451
+ return ip if ip and not ip.startswith("127.") else None
452
+
453
+
454
+ def bridge_request(
455
+ base: str,
456
+ path: str,
457
+ token: Optional[str],
458
+ *,
459
+ method: str = "GET",
460
+ body: Any = None,
461
+ timeout: float = 4.0,
462
+ ) -> Any:
463
+ """Call the bridge with the app token server-side (GET/POST/PUT/DELETE).
464
+
465
+ A 4xx/5xx answer is returned as its JSON envelope (the bridge always sends
466
+ ``{ok:false, error, code?}``) so callers can pass the reason on; only a
467
+ transport failure raises :class:`BridgeUnavailable`.
468
+ """
469
+ url = base.rstrip("/") + path
470
+ if token:
471
+ sep = "&" if "?" in url else "?"
472
+ url = f"{url}{sep}{urllib.parse.urlencode({'t': token})}"
473
+ headers = {"accept": "application/json"}
474
+ if method.upper() not in ("GET", "HEAD"):
475
+ # The bridge rejects a state-changing request without this marker
476
+ # (`apps/bridge/src/auth.js` → `x-client` must be `mobile`), 401 otherwise.
477
+ headers["x-client"] = "mobile"
478
+ data: Optional[bytes] = None
479
+ if body is not None:
480
+ data = json.dumps(body, ensure_ascii=False).encode("utf-8")
481
+ headers["content-type"] = "application/json"
482
+ request = urllib.request.Request(url, data=data, headers=headers, method=method)
483
+ try:
484
+ with urllib.request.urlopen(request, timeout=timeout) as response: # noqa: S310 - loopback only
485
+ return json.loads(response.read().decode("utf-8") or "{}")
486
+ except urllib.error.HTTPError as exc:
487
+ raw = exc.read().decode("utf-8", "replace")
488
+ try:
489
+ payload = json.loads(raw or "{}")
490
+ except ValueError:
491
+ payload = None
492
+ if isinstance(payload, Mapping):
493
+ out = dict(payload)
494
+ out.setdefault("ok", False)
495
+ return out
496
+ return {"ok": False, "code": f"HTTP_{exc.code}", "error": f"bridge HTTP {exc.code}"}
497
+ except urllib.error.URLError as exc:
498
+ raise BridgeUnavailable(f"bridge {base} unreachable: {exc}") from exc
499
+ except (OSError, ValueError) as exc:
500
+ raise BridgeUnavailable(f"bridge {base} returned no JSON: {exc}") from exc
501
+
502
+
503
+ def bridge_get(base: str, path: str, token: Optional[str], timeout: float = 4.0) -> Any:
504
+ """GET JSON from the bridge using the app token server-side."""
505
+ return bridge_request(base, path, token, method="GET", timeout=timeout)
506
+
507
+
508
+ def bridge_base(paths: Mapping[str, Path], cfg: Optional[Mapping[str, Any]] = None) -> str:
509
+ """Loopback base URL of the bridge on the configured port."""
510
+ cfg = cfg if cfg is not None else read_config(paths["configPath"])
511
+ return f"http://{BRIDGE_HOST}:{int(cfg.get('servicePort') or DEFAULT_PORT)}"
512
+
513
+
514
+ def local_capabilities(
515
+ paths: Mapping[str, Path], *, which: Optional[Callable[[str], Optional[str]]] = None
516
+ ) -> dict[str, Any]:
517
+ """Fallback capability detection when the bridge is down (SPEC §5.3 shape)."""
518
+ which = which or shutil.which
519
+ key = service_key()
520
+ home = Path(paths["home"])
521
+ tailscale_app = home / "Applications" / "Tailscale.app" / "Contents" / "MacOS" / "Tailscale"
522
+ has_tailscale = bool(which("tailscale")) or Path("/Applications/Tailscale.app/Contents/MacOS/Tailscale").exists() or tailscale_app.exists()
523
+ has_hermes = bool(which("hermes")) or (home / ".hermes" / "hermes-agent" / ".hermes" / "bin" / "hermes").exists()
524
+ key = service_key()
525
+ unit = SERVICE_UNITS[key] if key else None
526
+ return {
527
+ "os": key or platform_module.system().lower(),
528
+ "serviceManager": SERVICE_MANAGERS[key] if key else "none",
529
+ "hasTailscale": has_tailscale,
530
+ "hasHermesCli": has_hermes,
531
+ "pilotServiceUnit": unit,
532
+ }
533
+
534
+
535
+ # --------------------------------------------------------------------------- redaction
536
+
537
+
538
+ def redact(value: Any, token: Optional[str] = None) -> Any:
539
+ """Strip the app token (and any long hex secret) from a payload.
540
+
541
+ Defence in depth: the tab's endpoints are built to only return whitelisted
542
+ keys, but a future field must not be able to leak the token by accident.
543
+ """
544
+ if isinstance(value, str):
545
+ text = value.replace(token, "<redacted>") if token and token in value else value
546
+ return HEX_SECRET.sub("<redacted>", text)
547
+ if isinstance(value, Mapping):
548
+ return {str(k): redact(v, token) for k, v in value.items()}
549
+ if isinstance(value, (list, tuple)):
550
+ return [redact(item, token) for item in value]
551
+ return value
552
+
553
+
554
+ # --------------------------------------------------------------------------- payloads
555
+
556
+
557
+ def _urls(cfg: Mapping[str, Any], *, ip: Optional[str]) -> tuple[Optional[str], Optional[str]]:
558
+ """``(lanUrl, tailscaleUrl)`` for the PWA links."""
559
+ port = int(cfg.get("servicePort") or DEFAULT_PORT)
560
+ lan = f"http://{ip}:{port}/" if ip else None
561
+ dns = cfg.get("tailscaleDns")
562
+ tailscale = None
563
+ if dns:
564
+ tls = cfg.get("tlsPort")
565
+ tailscale = f"https://{dns}" + (f":{int(tls)}" if tls else "") + "/"
566
+ return lan, tailscale
567
+
568
+
569
+ def build_status(
570
+ paths: Optional[Mapping[str, Path]] = None,
571
+ *,
572
+ get: Optional[Callable[[str, str, Optional[str]], Any]] = None,
573
+ service: Optional[Callable[..., dict[str, Any]]] = None,
574
+ ip_lookup: Optional[Callable[[], Optional[str]]] = None,
575
+ ) -> dict[str, Any]:
576
+ """``GET /status`` payload — service, port, reachability, version, capabilities.
577
+
578
+ Contains **no token**: everything is funnelled through :func:`redact`.
579
+ """
580
+ paths = paths or resolve_paths()
581
+ get = get or bridge_get
582
+ service = service or service_status
583
+ ip_lookup = ip_lookup or lan_ip
584
+ cfg = read_config(paths["configPath"])
585
+ token = read_token(paths)
586
+ base = f"http://{BRIDGE_HOST}:{int(cfg.get('servicePort') or DEFAULT_PORT)}"
587
+
588
+ bridge: dict[str, Any] = {"reachable": False, "version": None}
589
+ try:
590
+ me = get(base, "/api/me", token)
591
+ bridge = {"reachable": bool(isinstance(me, Mapping) and me.get("ok")), "version": (me or {}).get("version") if isinstance(me, Mapping) else None}
592
+ except BridgeUnavailable:
593
+ bridge = {"reachable": False, "version": None}
594
+
595
+ capabilities = local_capabilities(paths)
596
+ if bridge["reachable"]:
597
+ try:
598
+ remote = get(base, "/api/capabilities", token)
599
+ if isinstance(remote, Mapping) and remote:
600
+ capabilities = dict(remote)
601
+ except BridgeUnavailable:
602
+ pass
603
+
604
+ lan_url, tailscale_url = _urls(cfg, ip=ip_lookup())
605
+ payload = {
606
+ "ok": True,
607
+ "service": service(),
608
+ "port": int(cfg.get("servicePort") or DEFAULT_PORT),
609
+ "dataDir": str(paths["dataDir"]),
610
+ "lanUrl": lan_url,
611
+ "tailscaleUrl": tailscale_url,
612
+ "bridge": bridge,
613
+ "capabilities": capabilities,
614
+ }
615
+ return redact(payload, token)
616
+
617
+
618
+ def build_pairing(
619
+ paths: Optional[Mapping[str, Path]] = None,
620
+ *,
621
+ get: Optional[Callable[[str, str, Optional[str]], Any]] = None,
622
+ ) -> dict[str, Any]:
623
+ """``GET /pairing`` — proxy the bridge's one-time code QR, whitelisted fields.
624
+
625
+ The bridge mints an 8-character single-use code (never the 64-char token), so
626
+ the QR stays coarse enough for a phone camera (SPEC §8.2).
627
+ """
628
+ paths = paths or resolve_paths()
629
+ get = get or bridge_get
630
+ cfg = read_config(paths["configPath"])
631
+ token = read_token(paths)
632
+ base = f"http://{BRIDGE_HOST}:{int(cfg.get('servicePort') or DEFAULT_PORT)}"
633
+ raw = get(base, "/api/auth/pairing", token)
634
+ if not isinstance(raw, Mapping):
635
+ raise BridgeUnavailable("bridge returned an unexpected pairing payload")
636
+ payload = {
637
+ "ok": True,
638
+ "qrPng": raw.get("qrPng"),
639
+ "targets": raw.get("targets") if isinstance(raw.get("targets"), list) else [],
640
+ "expiresAt": raw.get("expiresAt"),
641
+ "port": raw.get("port") or int(cfg.get("servicePort") or DEFAULT_PORT),
642
+ "tlsPort": raw.get("tlsPort"),
643
+ "tailscale": bool(raw.get("tailscale")),
644
+ }
645
+ return redact(payload, token)
646
+
647
+
648
+ # --------------------------------------------------------------- repos (G3)
649
+ #
650
+ # `scanDirs` used to live only in `config.json`, while the bridge scanned
651
+ # `repos.json` — the audit's G3. One file is now the source of truth and every
652
+ # write goes through the bridge first, falling back to an atomic file write when
653
+ # the bridge is down.
654
+
655
+
656
+ def normalize_path(value: str, home: Optional[Path] = None) -> str:
657
+ """Comparison key for a path: expanded, absolute, lower-cased, no trailing slash."""
658
+ home = Path(home) if home is not None else Path.home()
659
+ absolute = Path(expand_path(str(value or ""), home))
660
+ text = str(absolute).lower()
661
+ return text[:-1] if len(text) > 1 and text.endswith("/") else text
662
+
663
+
664
+ def repo_id_from_path(value: str) -> str:
665
+ """Board-safe id from a path (`[a-z0-9._-]` only), same rule as the bridge."""
666
+ import posixpath
667
+
668
+ base = posixpath.basename(str(value or "").rstrip("/")) or "repo"
669
+ slug = re.sub(r"[^a-z0-9._-]+", "-", base.lower()).strip("-")[:64]
670
+ return slug or "repo"
671
+
672
+
673
+ def default_repos_config(home: Optional[Path] = None) -> dict[str, Any]:
674
+ """Empty repository config whose ``scanDirs`` are the ones that exist here."""
675
+ home = Path(home) if home is not None else Path.home()
676
+ return {
677
+ "scanDirs": [d for d in DEFAULT_SCAN_DIRS if Path(expand_path(d, home)).is_dir()],
678
+ "pinned": [],
679
+ "hidden": [],
680
+ "custom": [],
681
+ }
682
+
683
+
684
+ def normalize_repos_config(raw: Any, home: Optional[Path] = None) -> dict[str, Any]:
685
+ """Sanitise a ``repos.json`` body (garbage entries are dropped, never fatal)."""
686
+ home = Path(home) if home is not None else Path.home()
687
+ base = default_repos_config(home)
688
+ if not isinstance(raw, Mapping):
689
+ return base
690
+
691
+ def strings(value: Any) -> list[str]:
692
+ if not isinstance(value, list):
693
+ return []
694
+ out: list[str] = []
695
+ for item in value:
696
+ text = str(item).strip() if isinstance(item, str) else ""
697
+ if text and text not in out:
698
+ out.append(text)
699
+ return out
700
+
701
+ custom: list[dict[str, str]] = []
702
+ if isinstance(raw.get("custom"), list):
703
+ for entry in raw["custom"]:
704
+ if not isinstance(entry, Mapping):
705
+ continue
706
+ absolute = expand_path(str(entry.get("path") or ""), home)
707
+ if not absolute.startswith("/"):
708
+ continue
709
+ custom.append(
710
+ {
711
+ "id": str(entry.get("id") or "").strip() or repo_id_from_path(absolute),
712
+ "label": str(entry.get("label") or "").strip() or Path(absolute).name,
713
+ "path": absolute,
714
+ }
715
+ )
716
+ scan_dirs = strings(raw.get("scanDirs"))
717
+ return {
718
+ "scanDirs": scan_dirs or base["scanDirs"],
719
+ "pinned": strings(raw.get("pinned")),
720
+ "hidden": strings(raw.get("hidden")),
721
+ "custom": custom,
722
+ }
723
+
724
+
725
+ def read_repos_config(paths: Mapping[str, Path]) -> Optional[dict[str, Any]]:
726
+ """Read ``repos.json``; ``None`` when the file is absent (not yet written)."""
727
+ try:
728
+ raw = json.loads(Path(paths["reposPath"]).read_text(encoding="utf-8"))
729
+ except (OSError, ValueError):
730
+ return None
731
+ return normalize_repos_config(raw, Path(paths["home"]))
732
+
733
+
734
+ def _write_json_atomic(path: Path | str, payload: Any, home: Optional[Path] = None) -> dict[str, Any]:
735
+ """tmp → rename, 0600, no leftover temp file."""
736
+ target = Path(path)
737
+ target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
738
+ body = json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
739
+ fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=f".{target.name}-", suffix=".tmp")
740
+ try:
741
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
742
+ fh.write(body)
743
+ fh.flush()
744
+ os.fsync(fh.fileno())
745
+ os.chmod(tmp_name, 0o600)
746
+ os.replace(tmp_name, target)
747
+ except BaseException:
748
+ try:
749
+ os.unlink(tmp_name)
750
+ except OSError:
751
+ pass
752
+ raise
753
+ return payload
754
+
755
+
756
+ def write_repos_config_atomic(paths: Mapping[str, Path], data: Mapping[str, Any]) -> dict[str, Any]:
757
+ """Write ``repos.json`` atomically (0600) and return the normalised body."""
758
+ normalized = normalize_repos_config(data, Path(paths["home"]))
759
+ _write_json_atomic(paths["reposPath"], normalized)
760
+ return normalized
761
+
762
+
763
+ def scan_git_dirs(scan_dirs: Any, home: Optional[Path] = None) -> list[dict[str, str]]:
764
+ """One level under each scan dir, `.git` only — the bridge's rule, mirrored."""
765
+ home = Path(home) if home is not None else Path.home()
766
+ found: list[dict[str, str]] = []
767
+ seen: set[str] = set()
768
+ for raw in scan_dirs or []:
769
+ parent = Path(expand_path(str(raw or ""), home))
770
+ if not parent.is_absolute():
771
+ continue
772
+ try:
773
+ entries = sorted(parent.iterdir())
774
+ except OSError:
775
+ continue
776
+ for entry in entries:
777
+ if not entry.is_dir() or entry.name.startswith("."):
778
+ continue
779
+ if not (entry / ".git").exists():
780
+ continue
781
+ key = normalize_path(str(entry), home)
782
+ if key in seen:
783
+ continue
784
+ seen.add(key)
785
+ found.append({"id": repo_id_from_path(str(entry)), "label": entry.name, "path": str(entry), "source": "scan"})
786
+ return found
787
+
788
+
789
+ def local_repos(config: Mapping[str, Any], home: Optional[Path] = None) -> list[dict[str, Any]]:
790
+ """Repository rows from ``repos.json`` alone (bridge down).
791
+
792
+ The bridge also merges board workdirs and session cwds; offline this is the
793
+ subset the file itself knows, which is what the card needs to edit.
794
+ """
795
+ home = Path(home) if home is not None else Path.home()
796
+ hidden = {normalize_path(p, home) for p in config.get("hidden") or []}
797
+ pinned = [str(p) for p in config.get("pinned") or []]
798
+ rows: list[dict[str, Any]] = []
799
+ seen: set[str] = set()
800
+ candidates = list(config.get("custom") or []) + scan_git_dirs(config.get("scanDirs"), home)
801
+ for entry in candidates:
802
+ absolute = expand_path(str(entry.get("path") or ""), home)
803
+ key = normalize_path(absolute, home)
804
+ if not absolute.startswith("/") or key in seen or key in hidden or not (Path(absolute) / ".git").exists():
805
+ continue
806
+ seen.add(key)
807
+ if key == normalize_path(str(home), home):
808
+ continue
809
+ rid = str(entry.get("id") or repo_id_from_path(absolute))
810
+ rows.append(
811
+ {
812
+ "id": rid,
813
+ "label": str(entry.get("label") or Path(absolute).name),
814
+ "path": absolute,
815
+ "source": str(entry.get("source") or "custom"),
816
+ "pinned": rid in pinned or absolute in pinned,
817
+ "boards": [],
818
+ }
819
+ )
820
+ rows.sort(key=lambda r: (not r["pinned"], r["label"].lower()))
821
+ return rows
822
+
823
+
824
+ def build_config(paths: Optional[Mapping[str, Path]] = None) -> dict[str, Any]:
825
+ """``GET /config`` — ``repos.json``'s ``scanDirs`` win over ``config.json``.
826
+
827
+ That inversion is the whole point of G3: the PWA edits ``repos.json`` and the
828
+ tab must not show a stale value from the older ``config.json`` field.
829
+ """
830
+ paths = paths or resolve_paths()
831
+ cfg = read_config(paths["configPath"])
832
+ repos = read_repos_config(paths)
833
+ source = "config.json"
834
+ if repos and repos.get("scanDirs"):
835
+ cfg["scanDirs"] = list(repos["scanDirs"])
836
+ source = "repos.json"
837
+ return {
838
+ "ok": True,
839
+ "config": cfg,
840
+ "dataDir": str(paths["dataDir"]),
841
+ "scanDirsSource": source,
842
+ "reposPath": shorten_path(str(paths["reposPath"]), Path(paths["home"])),
843
+ }
844
+
845
+
846
+ def sync_scan_dirs(
847
+ paths: Optional[Mapping[str, Path]] = None,
848
+ scan_dirs: Any = None,
849
+ *,
850
+ request: Optional[Callable[..., Any]] = None,
851
+ ) -> dict[str, Any]:
852
+ """Write ``scanDirs`` to the bridge **and** ``repos.json`` (G3).
853
+
854
+ The bridge is tried first because its writer also invalidates the 30 s scan
855
+ cache, so ``GET /api/repos`` reflects the change on the next request. When it
856
+ is not running the file is written directly — the same atomic tmp→rename —
857
+ and the next bridge start picks it up.
858
+ """
859
+ paths = paths or resolve_paths()
860
+ request = request or bridge_request
861
+ dirs = [str(d).strip() for d in (scan_dirs or []) if str(d).strip()]
862
+ token = read_token(paths)
863
+ base = bridge_base(paths)
864
+ bridge: dict[str, Any] = {"attempted": True, "ok": False, "error": None}
865
+ try:
866
+ answer = request(base, "/api/repos", token, method="POST", body={"scanDirs": dirs})
867
+ if isinstance(answer, Mapping):
868
+ bridge["ok"] = bool(answer.get("ok", True))
869
+ if not bridge["ok"]:
870
+ bridge["error"] = str(answer.get("error") or "the bridge rejected scanDirs")
871
+ if isinstance(answer.get("scanDirs"), list) and answer["scanDirs"]:
872
+ dirs = [str(d) for d in answer["scanDirs"]]
873
+ except BridgeUnavailable as exc:
874
+ bridge["error"] = str(exc)
875
+ config = read_repos_config(paths) or default_repos_config(Path(paths["home"]))
876
+ config["scanDirs"] = dirs or config["scanDirs"]
877
+ write_repos_config_atomic(paths, config)
878
+ return {"scanDirs": list(config["scanDirs"]), "source": "bridge" if bridge["ok"] else "file", "bridge": bridge}
879
+
880
+
881
+ def build_repos(
882
+ paths: Optional[Mapping[str, Path]] = None,
883
+ *,
884
+ request: Optional[Callable[..., Any]] = None,
885
+ ) -> dict[str, Any]:
886
+ """``GET /repos`` — the bridge's merged list, or the file's own rows offline."""
887
+ paths = paths or resolve_paths()
888
+ request = request or bridge_request
889
+ token = read_token(paths)
890
+ base = bridge_base(paths)
891
+ payload: dict[str, Any]
892
+ try:
893
+ raw = request(base, "/api/repos", token, method="GET")
894
+ if not isinstance(raw, Mapping) or not isinstance(raw.get("repos"), list):
895
+ raise BridgeUnavailable("bridge returned an unexpected repos payload")
896
+ payload = {
897
+ "ok": True,
898
+ "source": "bridge",
899
+ "repos": raw["repos"],
900
+ "scanDirs": raw.get("scanDirs") if isinstance(raw.get("scanDirs"), list) else [],
901
+ }
902
+ except BridgeUnavailable as exc:
903
+ home = Path(paths["home"])
904
+ config = read_repos_config(paths) or default_repos_config(home)
905
+ payload = {
906
+ "ok": True,
907
+ "source": "file",
908
+ "repos": local_repos(config, home),
909
+ "scanDirs": config["scanDirs"],
910
+ "notice": str(exc),
911
+ }
912
+ # The hidden list lives only in repos.json (the bridge filters it out of the
913
+ # merged list), so the card needs it to offer "unhide".
914
+ config = read_repos_config(paths) or default_repos_config(Path(paths["home"]))
915
+ payload["config"] = {
916
+ "hidden": [shorten_path(p, Path(paths["home"])) for p in config.get("hidden") or []],
917
+ "pinned": list(config.get("pinned") or []),
918
+ "custom": [{"id": c["id"], "label": c["label"], "path": shorten_path(c["path"], Path(paths["home"]))} for c in config.get("custom") or []],
919
+ }
920
+ return redact(payload, token)
921
+
922
+
923
+ def _find_repo(config: Mapping[str, Any], home: Path, repo_id: str) -> Optional[dict[str, Any]]:
924
+ """Locate a repo row by id — including one currently hidden (unhide needs it)."""
925
+ for row in local_repos(config, home):
926
+ if row["id"] == repo_id:
927
+ return row
928
+ for entry in config.get("custom") or []:
929
+ if str(entry.get("id")) == repo_id:
930
+ return dict(entry)
931
+ for raw in config.get("hidden") or []:
932
+ absolute = expand_path(str(raw), home)
933
+ if repo_id_from_path(absolute) == repo_id or normalize_path(absolute, home) == normalize_path(repo_id, home):
934
+ return {"id": repo_id, "label": Path(absolute).name, "path": absolute}
935
+ return None
936
+
937
+
938
+ def repos_action(
939
+ paths: Optional[Mapping[str, Path]] = None,
940
+ payload: Any = None,
941
+ *,
942
+ request: Optional[Callable[..., Any]] = None,
943
+ ) -> dict[str, Any]:
944
+ """``POST /repos`` — ``add|hide|unhide|pin|unpin|createBoard``.
945
+
946
+ Adding and hiding go through the bridge so its audit trail records them (and
947
+ its validation runs); unhide/pin/unpin only exist in ``repos.json``, so those
948
+ are written here and the bridge cache is invalidated with a re-scan.
949
+ """
950
+ paths = paths or resolve_paths()
951
+ request = request or bridge_request
952
+ body: Mapping[str, Any] = payload if isinstance(payload, Mapping) else {}
953
+ action = str(body.get("action") or "").strip()
954
+ if action not in REPO_ACTIONS:
955
+ return {"ok": False, "code": "invalid_action", "error": f"action must be one of {', '.join(REPO_ACTIONS)}"}
956
+
957
+ home = Path(paths["home"])
958
+ token = read_token(paths)
959
+ base = bridge_base(paths)
960
+ repo_id = str(body.get("id") or "").strip()
961
+ config = read_repos_config(paths) or default_repos_config(home)
962
+ bridge_used = False
963
+ note: Optional[str] = None
964
+
965
+ def touch_bridge() -> None:
966
+ """Invalidate the bridge's 30 s scan cache after a file-only edit."""
967
+ try:
968
+ request(base, "/api/repos/scan", token, method="POST")
969
+ except BridgeUnavailable:
970
+ pass
971
+
972
+ if action == "add":
973
+ raw = str(body.get("path") or "").strip()
974
+ if not raw:
975
+ return {"ok": False, "code": "path_required", "error": "A path is required"}
976
+ absolute = expand_path(raw, home)
977
+ if normalize_path(absolute, home) == normalize_path(str(home), home):
978
+ return {"ok": False, "code": "home_directory", "error": "The home directory itself cannot be a repository"}
979
+ if not Path(absolute).is_dir():
980
+ return {"ok": False, "code": "not_a_directory", "error": f"{raw} is not a directory"}
981
+ if not (Path(absolute) / ".git").exists():
982
+ return {"ok": False, "code": "not_git_repo", "error": f"{raw} is not a git repository"}
983
+ label = str(body.get("label") or "").strip() or Path(absolute).name
984
+ try:
985
+ answer = request(base, "/api/repos", token, method="POST", body={"path": absolute, "label": label})
986
+ bridge_used = True
987
+ if not answer.get("ok", True):
988
+ return {"ok": False, "code": "bridge_rejected", "error": str(answer.get("error") or "the bridge rejected the path")}
989
+ except BridgeUnavailable as exc:
990
+ note = str(exc)
991
+ key = normalize_path(absolute, home)
992
+ config["custom"] = [c for c in config.get("custom") or [] if normalize_path(c.get("path", ""), home) != key]
993
+ config["custom"].append({"id": repo_id_from_path(absolute), "label": label, "path": absolute})
994
+ config["hidden"] = [p for p in config.get("hidden") or [] if normalize_path(p, home) != key]
995
+ config["pinned"] = [p for p in config.get("pinned") or [] if normalize_path(p, home) != key]
996
+ write_repos_config_atomic(paths, config)
997
+ elif action == "createBoard":
998
+ if not repo_id:
999
+ return {"ok": False, "code": "id_required", "error": "A repository id is required"}
1000
+ try:
1001
+ answer = request(base, f"/api/repos/{urllib.parse.quote(repo_id)}/board", token, method="POST")
1002
+ bridge_used = True
1003
+ except BridgeUnavailable:
1004
+ return {"ok": False, "code": "bridge_required", "error": "The bridge must be running to create a board"}
1005
+ if not answer.get("ok", True):
1006
+ return {"ok": False, "code": "board_failed", "error": str(answer.get("error") or "the board could not be created")}
1007
+ else: # hide / unhide / pin / unpin
1008
+ if not repo_id:
1009
+ return {"ok": False, "code": "id_required", "error": "A repository id is required"}
1010
+ row = _find_repo(config, home, repo_id)
1011
+ if row is None:
1012
+ return {"ok": False, "code": "unknown_repo", "error": f"unknown repository: {repo_id}"}
1013
+ key = normalize_path(str(row["path"]), home)
1014
+ pinned = [str(p) for p in config.get("pinned") or []]
1015
+ if action == "hide":
1016
+ try:
1017
+ answer = request(base, f"/api/repos/{urllib.parse.quote(repo_id)}", token, method="DELETE")
1018
+ bridge_used = bool(answer.get("ok", True))
1019
+ if not bridge_used:
1020
+ return {"ok": False, "code": "bridge_rejected", "error": str(answer.get("error") or "hide failed")}
1021
+ except BridgeUnavailable as exc:
1022
+ note = str(exc)
1023
+ is_custom = any(normalize_path(c.get("path", ""), home) == key for c in config.get("custom") or [])
1024
+ if is_custom:
1025
+ config["custom"] = [c for c in config.get("custom") or [] if normalize_path(c.get("path", ""), home) != key]
1026
+ elif key not in {normalize_path(p, home) for p in config.get("hidden") or []}:
1027
+ config["hidden"] = list(config.get("hidden") or []) + [key]
1028
+ elif action == "unhide":
1029
+ config["hidden"] = [p for p in config.get("hidden") or [] if normalize_path(p, home) != key]
1030
+ elif action == "pin":
1031
+ config["pinned"] = [repo_id] + [p for p in pinned if p not in (repo_id, key)]
1032
+ else: # unpin
1033
+ config["pinned"] = [p for p in pinned if p not in (repo_id, key) and normalize_path(p, home) != key]
1034
+ if not bridge_used:
1035
+ write_repos_config_atomic(paths, config)
1036
+ touch_bridge()
1037
+
1038
+ fresh = build_repos(paths, request=request)
1039
+ out: dict[str, Any] = {
1040
+ "ok": True,
1041
+ "action": action,
1042
+ "source": fresh.get("source"),
1043
+ "repos": fresh.get("repos", []),
1044
+ "scanDirs": fresh.get("scanDirs", []),
1045
+ }
1046
+ if note:
1047
+ out["notice"] = note
1048
+ return redact(out, token)
1049
+
1050
+
1051
+ # ------------------------------------------------------ pipeline & architect
1052
+
1053
+
1054
+ def build_pipeline(
1055
+ paths: Optional[Mapping[str, Path]] = None,
1056
+ *,
1057
+ board: Optional[str] = None,
1058
+ request: Optional[Callable[..., Any]] = None,
1059
+ ) -> dict[str, Any]:
1060
+ """``GET /pipeline`` — Architect runner, SOUL/skill status, unfiled specs.
1061
+
1062
+ Everything comes from the bridge; when it is down the payload still renders
1063
+ (``source: "offline"``) so the card explains itself instead of going blank.
1064
+ Only whitelisted keys leave this function, and ``redact`` runs last.
1065
+ """
1066
+ paths = paths or resolve_paths()
1067
+ request = request or bridge_request
1068
+ token = read_token(paths)
1069
+ base = bridge_base(paths)
1070
+ query = f"?board={urllib.parse.quote(str(board))}" if board else ""
1071
+
1072
+ payload: dict[str, Any] = {
1073
+ "ok": True,
1074
+ "source": "bridge",
1075
+ "board": board or None,
1076
+ # ランナーは Hermes Native 固定(外部 CLI の子プロセス起動は行わない)
1077
+ "runner": "hermes",
1078
+ "pipeline": None,
1079
+ "jobs": [],
1080
+ "pending": [],
1081
+ "specReady": [],
1082
+ }
1083
+
1084
+ try:
1085
+ # GET はブリッジの生死判定だけに使う(ランナー切替は廃止済み)
1086
+ request(base, "/api/architect/config", token, method="GET")
1087
+ except BridgeUnavailable as exc:
1088
+ payload["source"] = "offline"
1089
+ payload["notice"] = str(exc)
1090
+
1091
+ try:
1092
+ status = request(base, "/api/pipeline/status", token, method="GET")
1093
+ if isinstance(status, Mapping) and status.get("ok"):
1094
+ payload["pipeline"] = {
1095
+ "soul": status.get("soul"),
1096
+ "hermes": status.get("hermes"),
1097
+ "antigravity": [
1098
+ {"id": t.get("id"), "available": bool(t.get("available")), "present": t.get("present") or [], "missing": t.get("missing") or []}
1099
+ for t in (status.get("antigravity") or [])
1100
+ if isinstance(t, Mapping)
1101
+ ],
1102
+ }
1103
+ except BridgeUnavailable:
1104
+ pass
1105
+
1106
+ try:
1107
+ jobs = request(base, "/api/architect/jobs" + query, token, method="GET")
1108
+ if isinstance(jobs, Mapping) and jobs.get("ok"):
1109
+ payload["jobs"] = [
1110
+ {
1111
+ "id": j.get("id"),
1112
+ "status": j.get("status"),
1113
+ "runner": j.get("runner"),
1114
+ "autoStart": bool(j.get("autoStart")),
1115
+ "spec": j.get("spec"),
1116
+ "createdAt": j.get("createdAt"),
1117
+ }
1118
+ for j in (jobs.get("jobs") or [])[:6]
1119
+ if isinstance(j, Mapping)
1120
+ ]
1121
+ payload["jobCount"] = len(jobs.get("jobs") or [])
1122
+ payload["pending"] = [
1123
+ {"path": p.get("path"), "title": p.get("title"), "pendingCount": p.get("pendingCount")}
1124
+ for p in (jobs.get("pending") or [])[:6]
1125
+ if isinstance(p, Mapping)
1126
+ ]
1127
+ payload["specReady"] = [
1128
+ {"spec": s.get("spec"), "title": s.get("title"), "batchCount": s.get("batchCount"), "launched": bool(s.get("launched"))}
1129
+ for s in (jobs.get("specReady") or [])[:6]
1130
+ if isinstance(s, Mapping)
1131
+ ]
1132
+ except BridgeUnavailable:
1133
+ pass
1134
+
1135
+ return redact(payload, token)
1136
+
1137
+
1138
+ def pipeline_action(
1139
+ paths: Optional[Mapping[str, Path]] = None,
1140
+ payload: Any = None,
1141
+ *,
1142
+ request: Optional[Callable[..., Any]] = None,
1143
+ ) -> dict[str, Any]:
1144
+ """``POST /pipeline`` — ``{action: "optimize"} | {action: "setRunner", runner}``.
1145
+
1146
+ Both run **on the bridge**, so the audit trail records them. The runner is
1147
+ fixed to ``hermes`` (Hermes Native); anything else is rejected here and by
1148
+ the bridge, and passed back verbatim — the tab never invents success.
1149
+ """
1150
+ paths = paths or resolve_paths()
1151
+ request = request or bridge_request
1152
+ body: Mapping[str, Any] = payload if isinstance(payload, Mapping) else {}
1153
+ action = str(body.get("action") or "").strip()
1154
+ token = read_token(paths)
1155
+ base = bridge_base(paths)
1156
+
1157
+ if action == "optimize":
1158
+ try:
1159
+ answer = request(base, "/api/pipeline/optimize", token, method="POST", body={})
1160
+ except BridgeUnavailable as exc:
1161
+ return {"ok": False, "code": "bridge_unreachable", "error": str(exc)}
1162
+ out: dict[str, Any] = dict(answer) if isinstance(answer, Mapping) else {"ok": False}
1163
+ out["action"] = "optimize"
1164
+ return redact(out, token)
1165
+
1166
+ if action == "setRunner":
1167
+ runner = str(body.get("runner") or "").strip()
1168
+ if runner != "hermes":
1169
+ return {"ok": False, "code": "invalid_runner", "error": "runner must be hermes"}
1170
+ try:
1171
+ answer = request(base, "/api/architect/config", token, method="PUT", body={"runner": runner})
1172
+ except BridgeUnavailable as exc:
1173
+ return {"ok": False, "code": "bridge_unreachable", "error": str(exc)}
1174
+ out: dict[str, Any] = dict(answer) if isinstance(answer, Mapping) else {"ok": False}
1175
+ out["action"] = "setRunner"
1176
+ return redact(out, token)
1177
+
1178
+ return {
1179
+ "ok": False,
1180
+ "code": "invalid_action",
1181
+ "error": "action must be one of optimize, setRunner",
1182
+ }
1183
+
1184
+
1185
+ # ----------------------------------------------------------------- snippets
1186
+
1187
+
1188
+ def snippet_store_path(paths: Mapping[str, Path], kind: str) -> Path:
1189
+ """File behind each snippet kind (`snippets.json` / `term-snippets.json`)."""
1190
+ return Path(paths["termSnippetsPath"] if kind == "term" else paths["snippetsPath"])
1191
+
1192
+
1193
+ def normalize_snippet_store(
1194
+ raw: Any,
1195
+ *,
1196
+ kind: str = "chat",
1197
+ previous: Optional[Mapping[str, Any]] = None,
1198
+ reset: bool = False,
1199
+ ) -> dict[str, Any]:
1200
+ """Sanitise a snippet store to the bridge's version-2 shape.
1201
+
1202
+ ``overrides`` may only carry booleans (``hot`` / ``hidden``) for known-ish ids;
1203
+ ``custom`` entries need a label and text, get a ``c-`` id, and keep ``run``
1204
+ for terminal snippets.
1205
+ """
1206
+ src: Mapping[str, Any] = raw if isinstance(raw, Mapping) else {}
1207
+ if reset:
1208
+ return {"version": 2, "overrides": {}, "custom": []}
1209
+ prev = previous if isinstance(previous, Mapping) else {}
1210
+ overrides: dict[str, dict[str, bool]] = {}
1211
+ source_overrides = src.get("overrides", prev.get("overrides", {}))
1212
+ if isinstance(source_overrides, Mapping):
1213
+ for key, value in source_overrides.items():
1214
+ name = str(key or "").strip()
1215
+ if not name or not isinstance(value, Mapping):
1216
+ continue
1217
+ override: dict[str, bool] = {}
1218
+ if isinstance(value.get("hot"), bool):
1219
+ override["hot"] = value["hot"]
1220
+ if isinstance(value.get("hidden"), bool):
1221
+ override["hidden"] = value["hidden"]
1222
+ if override:
1223
+ overrides[name] = override
1224
+ custom: list[dict[str, Any]] = []
1225
+ source_custom = src.get("custom", prev.get("custom", []))
1226
+ seen: set[str] = set()
1227
+ if isinstance(source_custom, list):
1228
+ for item in source_custom[:CUSTOM_MAX]:
1229
+ if not isinstance(item, Mapping):
1230
+ continue
1231
+ label = str(item.get("label") or "").strip()[:LABEL_MAX]
1232
+ text = str(item.get("text") or "").strip()[:TEXT_MAX]
1233
+ if not label or not text:
1234
+ continue
1235
+ given = str(item.get("id") or "").strip()
1236
+ sid = given if CUSTOM_ID_RE.match(given) and given not in seen else f"c-{len(seen) + 1:x}"
1237
+ while sid in seen:
1238
+ sid = f"c-{len(seen) + 1:x}{len(seen):x}"
1239
+ seen.add(sid)
1240
+ entry: dict[str, Any] = {"id": sid, "label": label, "text": text, "hot": bool(item.get("hot")), "custom": True}
1241
+ if item.get("hidden") is True:
1242
+ entry["hidden"] = True
1243
+ if kind == "term":
1244
+ entry["run"] = item.get("run") is not False
1245
+ note = str(item.get("note") or "").strip()[:TEXT_MAX]
1246
+ if note:
1247
+ entry["note"] = note
1248
+ custom.append(entry)
1249
+ return {"version": 2, "overrides": overrides, "custom": custom}
1250
+
1251
+
1252
+ def _snippet_payload(raw: Mapping[str, Any], *, kind: str, lang: str, source: str) -> dict[str, Any]:
1253
+ """Whitelist the bridge's snippet payload so no field can smuggle a secret."""
1254
+ return {
1255
+ "ok": True,
1256
+ "source": source,
1257
+ "kind": kind,
1258
+ "lang": lang,
1259
+ "snippets": raw.get("snippets") if isinstance(raw.get("snippets"), list) else [],
1260
+ "allSnippets": raw.get("allSnippets") if isinstance(raw.get("allSnippets"), list) else [],
1261
+ "overrides": raw.get("overrides") if isinstance(raw.get("overrides"), Mapping) else {},
1262
+ "custom": raw.get("custom") if isinstance(raw.get("custom"), list) else [],
1263
+ "customMax": raw.get("customMax") or CUSTOM_MAX,
1264
+ "hotLimit": raw.get("hotLimit") or HOT_LIMIT,
1265
+ }
1266
+
1267
+
1268
+ def _snippet_route(kind: str, lang: str, *, method: str = "GET") -> str:
1269
+ suffix = f"?lang={urllib.parse.quote(str(lang or 'en'))}"
1270
+ return f"/api/snippets/term{suffix}" if kind == "term" else f"/api/snippets{suffix}"
1271
+
1272
+
1273
+ def _local_snippet_payload(paths: Mapping[str, Path], kind: str, lang: str, note: Optional[str] = None) -> dict[str, Any]:
1274
+ """Bridge-down fallback: the store as saved, no built-in labels to render."""
1275
+ file = snippet_store_path(paths, kind)
1276
+ try:
1277
+ raw = json.loads(file.read_text(encoding="utf-8"))
1278
+ except (OSError, ValueError):
1279
+ raw = {}
1280
+ store = normalize_snippet_store(raw, kind=kind)
1281
+ payload: dict[str, Any] = {
1282
+ "ok": True,
1283
+ "source": "file",
1284
+ "kind": kind,
1285
+ "lang": lang,
1286
+ "snippets": [],
1287
+ "allSnippets": [],
1288
+ "overrides": store["overrides"],
1289
+ "custom": store["custom"],
1290
+ "customMax": CUSTOM_MAX,
1291
+ "hotLimit": HOT_LIMIT,
1292
+ }
1293
+ if note:
1294
+ payload["notice"] = note
1295
+ return payload
1296
+
1297
+
1298
+ def build_snippets(
1299
+ paths: Optional[Mapping[str, Path]] = None,
1300
+ kind: str = "chat",
1301
+ lang: str = "en",
1302
+ *,
1303
+ request: Optional[Callable[..., Any]] = None,
1304
+ ) -> dict[str, Any]:
1305
+ """``GET /snippets?kind=chat|term&lang=en|ja`` — bridge first, file offline."""
1306
+ if kind not in SNIPPET_KINDS:
1307
+ raise ValueError(f"kind must be one of {', '.join(SNIPPET_KINDS)}")
1308
+ paths = paths or resolve_paths()
1309
+ request = request or bridge_request
1310
+ token = read_token(paths)
1311
+ try:
1312
+ raw = request(bridge_base(paths), _snippet_route(kind, lang), token, method="GET")
1313
+ if not isinstance(raw, Mapping):
1314
+ raise BridgeUnavailable("bridge returned an unexpected snippets payload")
1315
+ payload = _snippet_payload(raw, kind=kind, lang=lang, source="bridge")
1316
+ except BridgeUnavailable as exc:
1317
+ payload = _local_snippet_payload(paths, kind, lang, str(exc))
1318
+ return redact(payload, token)
1319
+
1320
+
1321
+ def save_snippets(
1322
+ paths: Optional[Mapping[str, Path]] = None,
1323
+ kind: str = "chat",
1324
+ lang: str = "en",
1325
+ payload: Any = None,
1326
+ *,
1327
+ request: Optional[Callable[..., Any]] = None,
1328
+ ) -> dict[str, Any]:
1329
+ """``PUT /snippets`` — bridge first (it audits), atomic file write offline."""
1330
+ if kind not in SNIPPET_KINDS:
1331
+ raise ValueError(f"kind must be one of {', '.join(SNIPPET_KINDS)}")
1332
+ paths = paths or resolve_paths()
1333
+ request = request or bridge_request
1334
+ token = read_token(paths)
1335
+ body: Mapping[str, Any] = payload if isinstance(payload, Mapping) else {}
1336
+ try:
1337
+ raw = request(bridge_base(paths), _snippet_route(kind, lang), token, method="PUT", body=dict(body))
1338
+ if isinstance(raw, Mapping) and raw.get("ok", True) is not False and isinstance(raw.get("custom"), list):
1339
+ return redact(_snippet_payload(raw, kind=kind, lang=lang, source="bridge"), token)
1340
+ except BridgeUnavailable:
1341
+ pass
1342
+ file = snippet_store_path(paths, kind)
1343
+ try:
1344
+ current = json.loads(file.read_text(encoding="utf-8"))
1345
+ except (OSError, ValueError):
1346
+ current = {}
1347
+ store = normalize_snippet_store(
1348
+ body, kind=kind, previous=current, reset=body.get("reset") is True
1349
+ )
1350
+ _write_json_atomic(file, store)
1351
+ return redact(_local_snippet_payload(paths, kind, lang), token)
1352
+
1353
+
1354
+ # -------------------------------------------------------------------- logs
1355
+
1356
+
1357
+ def log_path(paths: Mapping[str, Path], name: str) -> Path:
1358
+ """Resolve a whitelisted log name to a file (no path from the browser)."""
1359
+ if name == "audit":
1360
+ return Path(paths["auditPath"])
1361
+ candidates = LOG_FILES[name]
1362
+ for filename in candidates:
1363
+ candidate = Path(paths["logDir"]) / filename
1364
+ if candidate.exists():
1365
+ return candidate
1366
+ return Path(paths["logDir"]) / candidates[0]
1367
+
1368
+
1369
+ def read_tail_text(file_path: Path | str, max_bytes: int = LOG_READ_BYTES) -> str:
1370
+ """Last *max_bytes* of a text file, dropping the partial first line."""
1371
+ target = Path(file_path)
1372
+ stat = target.stat()
1373
+ if stat.st_size <= max_bytes:
1374
+ return target.read_text(encoding="utf-8", errors="replace")
1375
+ with target.open("rb") as fh:
1376
+ fh.seek(stat.st_size - max_bytes)
1377
+ raw = fh.read(max_bytes).decode("utf-8", "replace")
1378
+ newline = raw.find("\n")
1379
+ return raw[newline + 1 :] if newline >= 0 else raw
1380
+
1381
+
1382
+ #: Keys the audit card renders as its own row instead of `key=value` detail.
1383
+ AUDIT_ROW_KEYS = ("at", "kind", "ok")
1384
+
1385
+
1386
+ def audit_entries(lines: Iterable[str]) -> list[dict[str, Any]]:
1387
+ """``audit.jsonl`` tail → newest-first rows the dashboard draws as a list.
1388
+
1389
+ The JSON is parsed here rather than in the browser so a partially written
1390
+ line still renders (as ``detail``) and every field goes through the same
1391
+ :func:`redact` pass as the raw text — ``build_logs`` redacts the whole
1392
+ payload, ``entries`` included (SPEC V3 §3.5).
1393
+ """
1394
+ out: list[dict[str, Any]] = []
1395
+ for line in reversed(list(lines or [])):
1396
+ try:
1397
+ parsed = json.loads(line)
1398
+ except (TypeError, ValueError):
1399
+ parsed = None
1400
+ if not isinstance(parsed, dict):
1401
+ out.append({"at": "", "kind": "", "ok": None, "detail": str(line)})
1402
+ continue
1403
+ detail: list[str] = []
1404
+ for key, value in parsed.items():
1405
+ if key in AUDIT_ROW_KEYS or value is None or value == "":
1406
+ continue
1407
+ if isinstance(value, (dict, list)):
1408
+ value = json.dumps(value, ensure_ascii=False)
1409
+ detail.append(f"{key}={value}")
1410
+ at = parsed.get("at")
1411
+ kind = parsed.get("kind")
1412
+ ok = parsed.get("ok")
1413
+ out.append(
1414
+ {
1415
+ "at": at if isinstance(at, str) else "",
1416
+ "kind": kind if isinstance(kind, str) else "",
1417
+ "ok": ok if isinstance(ok, bool) else None,
1418
+ "detail": " · ".join(detail),
1419
+ }
1420
+ )
1421
+ return out
1422
+
1423
+
1424
+ def build_logs(
1425
+ paths: Optional[Mapping[str, Path]] = None,
1426
+ name: str = "gateway",
1427
+ lines: int = 120,
1428
+ *,
1429
+ read: Optional[Callable[[Path | str], str]] = None,
1430
+ ) -> dict[str, Any]:
1431
+ """``GET /logs`` — the tail of one log, always through :func:`redact`.
1432
+
1433
+ The token is the bridge's own credential; a gateway log line can contain a
1434
+ ``?t=<token>`` URL, so nothing here is returned unredacted.
1435
+ """
1436
+ if name not in LOG_FILES:
1437
+ raise ValueError(f"file must be one of {', '.join(LOG_FILES)}")
1438
+ paths = paths or resolve_paths()
1439
+ read = read or read_tail_text
1440
+ try:
1441
+ limit = int(lines)
1442
+ except (TypeError, ValueError):
1443
+ limit = 120
1444
+ limit = max(1, min(limit, LOG_LINES_MAX))
1445
+ path = log_path(paths, name)
1446
+ missing = False
1447
+ try:
1448
+ text = read(path)
1449
+ except OSError:
1450
+ text = ""
1451
+ missing = True
1452
+ tail = [line for line in text.split("\n") if line] if text else []
1453
+ tail = tail[-limit:]
1454
+ payload = {
1455
+ "ok": True,
1456
+ "file": name,
1457
+ "lines": [LOG_QUERY_SECRET.sub(r"\1<redacted>", line) for line in tail],
1458
+ "shown": len(tail),
1459
+ "missing": missing,
1460
+ "path": shorten_path(str(path), Path(paths["home"])),
1461
+ }
1462
+ if name == "audit":
1463
+ # Structured rows for the dashboard's accordion list: parsed here so the
1464
+ # browser never has to guess, and redacted by the same pass below.
1465
+ payload["entries"] = audit_entries(tail)
1466
+ return redact(payload, read_token(paths))