intervals-summits 0.1.0__py3-none-any.whl

intervals_summits/__init__.py

@@ -0,0 +1,2 @@
+"""Summits, huts and passes on Intervals.icu activities, from the GPS track and OpenStreetMap."""
+__version__ = "0.1.0"

intervals_summits/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

intervals_summits/cli.py

@@ -0,0 +1,266 @@
+"""Command line: sync, backfill, recompute, run, ui, page, status, fields."""
+from __future__ import annotations
+
+import argparse
+import http.server
+import json
+import logging
+import sys
+import threading
+import time
+from collections import Counter
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+from . import __version__, page
+from . import fields as F
+from .config import Settings, load
+from .intervals import IntervalsClient
+from .osm import OSM
+from .store import Store
+from .sync import Context, backfill, sync
+
+log = logging.getLogger("intervals_summits")
+
+# garmin-intervals-bridge (BRIDGE_NOTIFY_URL) can tell `run --ui` about new activities with a POST /sync
+QUIET_MINUTES = 180         # while it does, look on our own only this often (in case the bridge stops)
+NOTIFIED_DAYS = 14          # ... as long as its last note is this recent
+RECHECK_MINUTES = 10        # a reported activity without a track yet: ask once more this soon
+NOTE_DELAY = 5              # seconds: notes in quick succession make one sync
+MIN_GAP_SECONDS = 60        # and at most one sync a minute
+
+
+def context(settings: Settings) -> Context:
+    store = Store(settings.db_file, settings.tracks_dir)
+    iv = IntervalsClient(settings.api_key, settings.athlete_id, pause=settings.pause)
+    return Context(settings, iv, store, OSM(store, settings.overpass_url))
+
+
+def write_page(ctx: Context) -> None:
+    size = page.write(ctx.store, ctx.settings.page_file, ctx.settings.language, ctx.settings.page_title)
+    ctx.counts["page_kb"] = size // 1024
+
+
+def ensure_fields(ctx: Context) -> None:
+    """Create missing fields – checked once a day (the list of custom items is not small)."""
+    key = ",".join(ctx.settings.fields)
+    if ctx.store.get("fields_checked") == f"{date.today()} {key}":
+        return
+    for code in F.ensure(ctx.iv, ctx.settings.fields, ctx.settings.language, True)["missing"]:
+        ctx.counts[f"field_created_{code}"] += 1
+    ctx.store.put("fields_checked", f"{date.today()} {key}")
+
+
+def report(ctx: Context, apply: bool, **extra) -> None:
+    out = {"apply": apply, **extra, **{k: v for k, v in sorted(ctx.counts.items())},
+           "intervals_requests": ctx.iv.requests, "page": str(ctx.settings.page_file)}
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+
+
+def cmd_sync(ctx: Context, args) -> int:
+    if args.apply:
+        ensure_fields(ctx)
+    sync(ctx, apply=args.apply, force=args.force)
+    write_page(ctx)
+    report(ctx, args.apply)
+    return 0
+
+
+def cmd_backfill(ctx: Context, args, recompute: bool = False) -> int:
+    if args.apply:
+        ensure_fields(ctx)
+    oldest = date.fromisoformat(args.from_)
+    newest = date.fromisoformat(args.to) if args.to else date.today() + timedelta(days=1)
+    backfill(ctx, oldest, newest, apply=args.apply, force=args.force, recompute=recompute)
+    write_page(ctx)
+    report(ctx, args.apply, window=f"{oldest} – {newest}")
+    return 0
+
+
+def cmd_page(ctx: Context, args) -> int:
+    path = Path(args.out) if args.out else ctx.settings.page_file
+    size = page.write(ctx.store, path, args.language or ctx.settings.language, ctx.settings.page_title)
+    print(f"{path}: {size // 1024} KB")
+    return 0
+
+
+def poll_minutes(ctx: Context, now: datetime | None = None) -> int:
+    """How often to look on our own: SUMMITS_INTERVAL_MINUTES, or every 3 hours while the bridge reports."""
+    told = ctx.store.get("notified_at")
+    if told and (now or datetime.now()) - datetime.fromisoformat(told) <= timedelta(days=NOTIFIED_DAYS):
+        return max(ctx.settings.interval_minutes, QUIET_MINUTES)
+    return ctx.settings.interval_minutes
+
+
+def healthy(ctx: Context, now: datetime | None = None) -> tuple[bool, str]:
+    """No request to anyone: is the last successful sync recent enough?"""
+    last = ctx.store.get("last_sync_at")
+    if not last:
+        return True, "no sync yet"
+    age = ((now or datetime.now()) - datetime.fromisoformat(last)).total_seconds() / 60
+    limit = max(60, 3 * poll_minutes(ctx, now))
+    return age <= limit, f"last sync {age:.0f} minutes ago"
+
+
+def cmd_status(ctx: Context, args) -> int:
+    if args.check:
+        ok, text = healthy(ctx)
+        print(("healthy: " if ok else "unhealthy: ") + text)
+        return 0 if ok else 1
+    out = {"version": __version__, "data_dir": str(ctx.settings.data_dir), "fields": list(ctx.settings.fields),
+           "language": ctx.settings.language, "last_sync": ctx.store.get("last_sync_at"),
+           "last_bridge_note": ctx.store.get("notified_at"), **ctx.store.counts()}
+    if args.fields:
+        out["intervals_fields"] = F.ensure(ctx.iv, ctx.settings.fields, ctx.settings.language, False)
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_fields(ctx: Context, args) -> int:
+    print(json.dumps(F.ensure(ctx.iv, ctx.settings.fields, ctx.settings.language, args.apply), indent=2))
+    return 0
+
+
+def serve(settings: Settings, host: str, port: int, wake: threading.Event | None = None) -> http.server.ThreadingHTTPServer:
+    """The summit log, rendered fresh from the database for every request (read only). With `wake`
+    (from `run`) also POST /sync: new activities in Intervals, sync now. It takes no data, only the
+    note; the run loop keeps it to one sync a minute."""
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):  # noqa: N802
+            if self.path.split("?")[0].rstrip("/") not in ("", "/index.html"):
+                self.send_error(404)
+                return
+            store = Store(settings.db_file, settings.tracks_dir)
+            try:
+                body = page.render(store, settings.language, settings.page_title).encode("utf-8")
+            finally:
+                store.close()
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_POST(self):  # noqa: N802
+            if wake is None or self.path.split("?")[0].rstrip("/") != "/sync":
+                self.send_error(404)
+                return
+            try:
+                length = min(max(int(self.headers.get("Content-Length") or 0), 0), 65536)
+                who = str(json.loads(self.rfile.read(length) or b"{}").get("source") or "")
+            except (ValueError, AttributeError):
+                who = ""
+            log.info("%s reports new activities: a sync follows", "".join(c for c in who[:60] if c.isprintable()) or "Someone")
+            wake.set()
+            body = b'{"ok": true}'
+            self.send_response(202)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *a):
+            pass
+
+    return http.server.ThreadingHTTPServer((host, port), Handler)
+
+
+def cmd_ui(ctx: Context, args) -> int:
+    server = serve(ctx.settings, args.host, args.port)
+    print(f"Summit log on http://{args.host}:{args.port}/ (Ctrl+C stops it)")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def cmd_run(ctx: Context, args) -> int:
+    """Keep running: a sync every SUMMITS_INTERVAL_MINUTES, the page after each (and with --ui on the web)."""
+    wake = threading.Event()
+    if args.ui:
+        server = serve(ctx.settings, args.host, args.port, wake)
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        log.info("Summit log on http://%s:%d/ (POST /sync there: new activities, sync now)", args.host, args.port)
+    log.info("intervals-summits %s: a sync every %d minutes%s", __version__, poll_minutes(ctx),
+             "" if args.apply else " – a dry run: nothing is written to Intervals until --apply")
+    run_loop(ctx, apply=args.apply, wake=wake)
+    return 0
+
+
+def run_loop(ctx: Context, *, apply: bool, wake: threading.Event, iterations: int | None = None,
+             sleep=time.sleep) -> None:
+    told, count = False, 0
+    while iterations is None or count < iterations:
+        count += 1
+        started = time.monotonic()
+        ctx.counts = Counter()
+        try:
+            if told:
+                ctx.store.put("notified_at", datetime.now().isoformat(timespec="seconds"))
+            if apply:
+                ensure_fields(ctx)
+            sync(ctx, apply=apply)
+            write_page(ctx)
+            done = {k: v for k, v in ctx.counts.items() if k in ("matched", "with_summits", "activities_to_write",
+                                                                  "activities_written", "failed") and v}
+            if done:
+                log.info("Sync: %s", done)
+        except Exception as exc:  # noqa: BLE001 – keep running; the next pass tries again
+            log.warning("Sync failed: %s", exc)
+        if iterations is not None and count >= iterations:
+            return
+        wait = poll_minutes(ctx) * 60
+        if told and ctx.counts["no_gps"]:
+            wait = min(wait, RECHECK_MINUTES * 60)       # Intervals may not have read its track yet
+        told = wake.wait(wait)
+        if told:
+            sleep(max(NOTE_DELAY, started + MIN_GAP_SECONDS - time.monotonic()))
+            wake.clear()                                 # notes until now: this one sync covers them
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="intervals-summits", description="Summits on your Intervals.icu activities")
+    ap.add_argument("--version", action="version", version=__version__)
+    ap.add_argument("-v", "--verbose", action="store_true")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("sync", help="the recent days (after a pause back to the last run)")
+    p.add_argument("--apply", action="store_true", help="write to Intervals (else: a dry run)")
+    p.add_argument("--force", action="store_true", help="also overwrite values someone else wrote")
+    for name, text in (("backfill", "the past: match activities not matched yet"), ("recompute", "match again (new OSM data or rules)")):
+        p = sub.add_parser(name, help=text)
+        p.add_argument("--from", dest="from_", required=True, metavar="DATE")
+        p.add_argument("--to", metavar="DATE")
+        p.add_argument("--apply", action="store_true")
+        p.add_argument("--force", action="store_true")
+    p = sub.add_parser("run", help="keep running: a sync every few minutes")
+    p.add_argument("--apply", action="store_true")
+    p.add_argument("--ui", action="store_true", help="also serve the summit log page")
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=8766)
+    p = sub.add_parser("ui", help="serve the summit log page")
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=8766)
+    p = sub.add_parser("page", help="write the summit log page")
+    p.add_argument("--out")
+    p.add_argument("--language", choices=["en", "de"])
+    p = sub.add_parser("status")
+    p.add_argument("--check", action="store_true", help="health only, no request: exit 1 when no sync came for long")
+    p.add_argument("--fields", action="store_true", help="also ask Intervals which fields exist")
+    p = sub.add_parser("fields", help="create the activity fields that are missing")
+    p.add_argument("--apply", action="store_true")
+    args = ap.parse_args(argv)
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO, format="%(asctime)s %(levelname)s %(message)s",
+                        datefmt="%Y-%m-%d %H:%M:%S", stream=sys.stderr)
+    logging.getLogger("urllib3").setLevel(logging.WARNING)
+    ctx = context(load())
+    try:
+        if args.cmd == "sync":
+            return cmd_sync(ctx, args)
+        if args.cmd in ("backfill", "recompute"):
+            return cmd_backfill(ctx, args, recompute=args.cmd == "recompute")
+        return {"page": cmd_page, "status": cmd_status, "fields": cmd_fields, "run": cmd_run, "ui": cmd_ui}[args.cmd](ctx, args)
+    finally:
+        ctx.store.close()

intervals_summits/config.py

@@ -0,0 +1,142 @@
+"""Settings: environment variables, else a settings file.
+
+The settings file that applies: SUMMITS_ENV_FILE, else ./.env, else ~/IntervalsSummits/.env, else the
+bridge's ~/GarminBridge/.env – so next to the Garmin bridge nothing has to be set twice. Variables
+already set in the environment always win.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+HOME_FOLDER = "IntervalsSummits"
+BRIDGE_FOLDER = "GarminBridge"
+OVERPASS = "https://overpass-api.de/api/interpreter"
+# indoor and virtual types: no track worth asking for ("Other" may well have one: paragliding, ...)
+INDOOR = frozenset({"VirtualRide", "VirtualRun", "VirtualRow", "VirtualSki", "Elliptical", "Workout", "WeightTraining",
+                    "Yoga", "Pilates", "Crossfit", "StairStepper", "Rowing", "Swim", "HighIntensityIntervalTraining"})
+ALL_FIELDS = ("Summits", "SummitCount", "HighestPoint", "HutsPasses")
+DEFAULT_FIELDS = ("Summits", "SummitCount", "HighestPoint")
+
+
+def read_env_file(path: Path) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[7:]
+        key, value = line.split("=", 1)
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+            value = value[1:-1]
+        out[key.strip()] = value
+    return out
+
+
+def env_file() -> Path | None:
+    if os.environ.get("SUMMITS_ENV_FILE"):
+        return Path(os.environ["SUMMITS_ENV_FILE"]).expanduser()
+    for candidate in (Path(".env"), Path.home() / HOME_FOLDER / ".env", Path.home() / BRIDGE_FOLDER / ".env"):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def default_data_dir() -> Path:
+    """Next to a bridge set up on this computer: ~/GarminBridge/summits; else ~/IntervalsSummits."""
+    bridge = Path.home() / BRIDGE_FOLDER
+    return bridge / "summits" if bridge.is_dir() else Path.home() / HOME_FOLDER
+
+
+def _list(value: str | None) -> tuple[str, ...]:
+    return tuple(v.strip() for v in (value or "").split(",") if v.strip())
+
+
+def _bool(value: str | None, default: bool) -> bool:
+    return default if value in (None, "") else value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _metres(env: dict[str, str], key: str, default: float, low: float, high: float) -> float:
+    value = env.get(key)
+    if value in (None, ""):
+        return default
+    try:
+        number = float(value)
+    except ValueError:
+        raise SystemExit(f"{key}: a number of metres, not {value!r}") from None
+    if not low <= number <= high:
+        raise SystemExit(f"{key}: {low:g} to {high:g} m")
+    return number
+
+
+@dataclass
+class Settings:
+    api_key: str
+    athlete_id: str = "0"
+    data_dir: Path = field(default_factory=default_data_dir)
+    language: str = "en"                 # field names and the page: en or de
+    name_language: str = ""              # OSM name:<xx> when there is one; "" = the local name
+    types: tuple[str, ...] = ()          # only these activity types; () = every outdoor type
+    fields: tuple[str, ...] = DEFAULT_FIELDS
+    overpass_url: str = OVERPASS
+    lookback_days: int = 3
+    catchup_days: int = 14
+    interval_minutes: int = 15
+    pause: float = 0.6                   # seconds between Intervals requests (the key is shared with the bridge)
+    keep_tracks: bool = True
+    description: bool = False           # the line "⛰️ Summits: …" in the description (searchable)
+    peak_radius: float = 100.0
+    peak_below: float = 80.0
+    hut_radius: float = 60.0
+    pass_radius: float = 60.0
+    page_title: str = ""
+
+    @property
+    def page_file(self) -> Path:
+        return self.data_dir / "summits.html"
+
+    @property
+    def db_file(self) -> Path:
+        return self.data_dir / "summits.sqlite"
+
+    @property
+    def tracks_dir(self) -> Path:
+        return self.data_dir / "tracks"
+
+
+def load(environ: dict[str, str] | None = None) -> Settings:
+    env = dict(environ if environ is not None else os.environ)
+    if environ is None and (path := env_file()):
+        for key, value in read_env_file(path).items():
+            env.setdefault(key, value)
+    key = env.get("INTERVALS_API_KEY", "")
+    if not key:
+        raise SystemExit("INTERVALS_API_KEY is not set (environment or settings file)")
+    fields = tuple(f for f in _list(env.get("SUMMITS_FIELDS")) or DEFAULT_FIELDS)
+    unknown = [f for f in fields if f not in ALL_FIELDS]
+    if unknown:
+        raise SystemExit(f"SUMMITS_FIELDS: unknown {unknown}; possible: {', '.join(ALL_FIELDS)}")
+    language = (env.get("SUMMITS_LANGUAGE") or "en").lower()[:2]
+    return Settings(
+        api_key=key,
+        athlete_id=env.get("INTERVALS_ATHLETE_ID") or "0",
+        data_dir=Path(env["SUMMITS_DATA_DIR"]).expanduser() if env.get("SUMMITS_DATA_DIR") else default_data_dir(),
+        language=language if language in ("en", "de") else "en",
+        name_language=(env.get("SUMMITS_NAME_LANGUAGE") or "").lower(),
+        types=_list(env.get("SUMMITS_TYPES")),
+        fields=fields,
+        overpass_url=env.get("SUMMITS_OVERPASS_URL") or OVERPASS,
+        lookback_days=max(1, min(30, int(env.get("SUMMITS_LOOKBACK_DAYS") or 3))),
+        interval_minutes=max(5, int(env.get("SUMMITS_INTERVAL_MINUTES") or 15)),
+        keep_tracks=_bool(env.get("SUMMITS_KEEP_TRACKS"), True),
+        description=_bool(env.get("SUMMITS_DESCRIPTION"), False),
+        # up to 200 m: a track point needs the neighbouring OpenStreetMap cell only within 0.004° of a border
+        peak_radius=_metres(env, "SUMMITS_PEAK_RADIUS", 100.0, 10, 200),
+        peak_below=_metres(env, "SUMMITS_PEAK_BELOW", 80.0, 0, 500),
+        hut_radius=_metres(env, "SUMMITS_HUT_RADIUS", 60.0, 10, 200),
+        pass_radius=_metres(env, "SUMMITS_PASS_RADIUS", 60.0, 10, 200),
+        page_title=env.get("SUMMITS_PAGE_TITLE") or "",
+    )

intervals_summits/fields.py

@@ -0,0 +1,156 @@
+"""The Intervals activity fields: their definitions, the values for an activity, and when to write.
+
+Codes are the same for everyone (charts and scripts keep working); names follow SUMMITS_LANGUAGE
+and may be renamed in Intervals at will – the tool goes by the code.
+
+A value is written when the field is empty, or when it still holds what this tool wrote last time.
+A value someone typed or another tool wrote is kept (unless --force). HighestPoint is only ever
+filled when empty: Intervals fills it from a FIT file itself (session enhanced_max_altitude).
+
+Optional (SUMMITS_DESCRIPTION=true): one line "⛰️ Summits: …" in the activity description, because
+Intervals' search looks at names and descriptions, not at custom fields. Only that line is ever
+touched; the rest of the description stays as it is.
+"""
+from __future__ import annotations
+
+import json
+import logging
+
+log = logging.getLogger(__name__)
+ATTRIBUTION = "© OpenStreetMap contributors"
+
+DEFS = {
+    "Summits": {"names": {"en": "Summits", "de": "Gipfel"}, "type": "text", "icon": "mdi-flag-triangle",
+                "description": f"Summits reached on the activity, in order (OpenStreetMap peaks within 100 m of the track; {ATTRIBUTION})"},
+    "SummitCount": {"names": {"en": "Summit count", "de": "Gipfelanzahl"}, "type": "numeric", "icon": "mdi-flag-triangle",
+                    "aggregate": "SUM", "number_format": ".0f",
+                    "description": "Number of summits reached on the activity (intervals-summits)"},
+    "HighestPoint": {"names": {"en": "Highest point", "de": "Höchster Punkt"}, "type": "numeric",
+                     "icon": "mdi-image-filter-hdr", "aggregate": "MAX", "units": "m", "suffix": "m", "number_format": ".0f",
+                     "fit_session_field": "enhanced_max_altitude",
+                     "description": "Highest point of the activity (m): from the FIT file (session enhanced_max_altitude); "
+                                    "otherwise from the altitude stream (intervals-summits)"},
+    "HutsPasses": {"names": {"en": "Huts & passes", "de": "Hütten & Pässe"}, "type": "text", "icon": "mdi-home-variant",
+                   "description": f"Huts and passes on the activity, in order (OpenStreetMap; {ATTRIBUTION})"},
+}
+
+
+def item(code: str, language: str) -> dict:
+    d = DEFS[code]
+    name = d["names"].get(language, d["names"]["en"])
+    content = {"code": code, "name": name, "type": d["type"], "icon": d["icon"], "inline": True,
+               "fit_session_field": d.get("fit_session_field"), "script": None, "processes_fit_messages": False}
+    for key in ("aggregate", "number_format", "units", "suffix"):
+        if key in d:
+            content[key] = d[key]
+    if d["type"] == "text":
+        content["text_wrap"] = True
+    return {"type": "ACTIVITY_FIELD", "visibility": "PRIVATE", "name": name, "description": d["description"], "content": content}
+
+
+def ensure(iv, codes: tuple[str, ...], language: str, apply: bool) -> dict:
+    """Create the fields that are missing (with the next free index, else Intervals' pickers hide them)."""
+    items = [i for i in iv.custom_items() if i.get("type") == "ACTIVITY_FIELD"]
+    present = {(i.get("content") or {}).get("code") for i in items}
+    missing = [c for c in codes if c not in present]
+    if apply and missing:
+        top = max((i.get("index") or 0 for i in items), default=0)
+        for code in missing:
+            created = iv.create_custom_item(item(code, language)) or {}
+            if created.get("id"):
+                top += 1
+                iv.reorder_custom_items([dict(created, index=top)])
+            log.info("Created the activity field %s", code)
+    return {"present": sorted(c for c in codes if c in present), "missing": missing}
+
+
+def text(visits: list[dict], kinds: tuple[str, ...]) -> str | None:
+    parts = [f"{v['name']} ({round(v['ele'])} m)" if v.get("ele") is not None else v["name"]
+             for v in visits if v["kind"] in kinds]
+    return ", ".join(parts) or None
+
+
+def wanted(visits: list[dict], max_alt: float | None, codes: tuple[str, ...]) -> dict:
+    out = {}
+    if "Summits" in codes:
+        out["Summits"] = text(visits, ("peak",))
+    if "SummitCount" in codes:
+        out["SummitCount"] = sum(1 for v in visits if v["kind"] == "peak") or None
+    if "HighestPoint" in codes:
+        out["HighestPoint"] = round(max_alt) if max_alt is not None else None
+    if "HutsPasses" in codes:
+        out["HutsPasses"] = text(visits, ("hut", "pass"))
+    return out
+
+
+def same(a, b) -> bool:
+    if a in (None, "") or b in (None, ""):
+        return a in (None, "") and b in (None, "")
+    if isinstance(a, (int, float)) or isinstance(b, (int, float)):
+        try:
+            return abs(float(a) - float(b)) < 0.5
+        except (TypeError, ValueError):
+            return False
+    return str(a).strip() == str(b).strip()
+
+
+def decide(code: str, want, current, last: str | None, force: bool = False) -> str:
+    """write | same | kept (someone else's value) | none (nothing to write)."""
+    if want is None:
+        return "none"
+    if same(current, want):
+        return "same"
+    if current in (None, ""):
+        return "write"
+    if code == "HighestPoint":
+        return "kept"
+    if force or (last is not None and same(current, json.loads(last))):
+        return "write"
+    return "kept"
+
+
+DESCRIPTION_LABELS = {"en": "Summits", "de": "Gipfel"}
+MOUNTAIN = "\u26f0\ufe0f"
+
+
+def is_our_line(line: str) -> bool:
+    s = line.strip().lstrip("\u26f0\ufe0f").strip()
+    return line.strip().startswith("\u26f0") and any(s.startswith(f"{label}:") for label in DESCRIPTION_LABELS.values())
+
+
+def description_line(visits: list[dict], description: str | None, language: str) -> str | None:
+    """None when there are no summits, or when the description names them all already (peakproject's lines)."""
+    peaks = [v for v in visits if v["kind"] == "peak"]
+    if not peaks:
+        return None
+    rest = "\n".join(line for line in (description or "").split("\n") if not is_our_line(line))
+    if all(v["name"] in rest for v in peaks):
+        return None
+    return f"{MOUNTAIN} {DESCRIPTION_LABELS.get(language, 'Summits')}: {text(peaks, ('peak',))}"
+
+
+def our_line(description: str | None) -> str | None:
+    return next((line.strip() for line in (description or "").split("\n") if is_our_line(line)), None)
+
+
+def with_line(description: str | None, line: str) -> str:
+    """The description with our line replaced, or appended after a blank line: the rest stays exactly as it is."""
+    text = description or ""
+    lines = text.split("\n")
+    at = [i for i, x in enumerate(lines) if is_our_line(x)]
+    if not at:
+        if not text.strip():
+            return line
+        return text + ("" if text.endswith("\n\n") else "\n" if text.endswith("\n") else "\n\n") + line
+    lines[at[0]] = line + ("\r" if lines[at[0]].endswith("\r") else "")
+    return "\n".join(x for i, x in enumerate(lines) if i not in at[1:])
+
+
+def keeps_text(old: str | None, new: str) -> bool:
+    """The last check before a description is written: all of the user's text is still there, unchanged."""
+    old = old or ""
+    if our_line(old) is None:
+        start = old if old.strip() else ""
+        added = new[len(start):].strip()
+        return new.startswith(start) and "\n" not in added and is_our_line(added)
+    return [x for x in old.split("\n") if not is_our_line(x)] == [x for x in new.split("\n") if not is_our_line(x)]