datasheets-md 2.0.0a11__py3-none-any.whl

datasheets_md/__init__.py

@@ -0,0 +1,4 @@
+"""datasheets-md: the `dsmd` CLI and the dBsync GUI on one sync engine."""
+
+__version__ = "2.0.0a11"
+APP_NAME = "dBsync"

datasheets_md/agents.md

@@ -0,0 +1,88 @@
+# dsmd for agents
+
+`dsmd` keeps a folder in sync with a datasheets.md workspace. Use it from a
+shell; add `--json` to any command for machine-readable output.
+
+## Loop
+
+1. `dsmd pull` -- bring the working copy up to date.
+2. Find what to change with grep, e.g. `grep -rn '"VOH"' parts/`.
+3. Edit only these files:
+   - `parts/<MFR>/<PN>/parameters.jsonl` -- one parameter row per line.
+   - `parts/<MFR>/<PN>/pins.csv` -- one physical pin per line.
+   - `parts/<MFR>/<PN>/cad.yaml` -- the part's CAD configuration.
+   - `settings/mapping.yaml`, `settings/symbol_style.yaml` -- the workspace's
+     settings (see below; owner or admin only).
+4. `dsmd diff` -- and show the diff to the user before pushing.
+5. `dsmd push -m "<what changed and why>"`.
+6. Exit code 2 from `clone` or `pull` with a `library/ was not built` warning means the parts and
+   datasheets are in place; run `dsmd pull --library` to retry. A clone that stopped continues when you
+   run the same command again. Exit code 2 from `push` means some parts were not applied: read the per-part lines
+   (`stale` -> run `dsmd pull`, then push again; `rejected` -> fix the named
+   `file:line` and push again).
+
+## Rules
+
+- Keep `k` (parameters.jsonl) and `id` (pins.csv) unchanged on rows you edit;
+  they are how the server knows which row you mean. A new row has no `k`; a
+  new pin has an empty `id`.
+- A part's digitised PDF is the `datasheet.md` that `datasheet:` in its
+  `part.yaml` points at (`datasheets/<manufacturer>/<pdf name>/`, one per
+  family, shared by every part of it; null until the PDF is digitised). Its
+  `{{para:<id> ...}}`, `{{table:<id> ...}}`, `{{row:<id> ...}}` and
+  `{{figure:<id> ...}}` markers carry the element ids that a row's
+  `source.element_id` cites; figures are PNGs in `images/` next to it.
+  `dsmd pdf <part>` downloads the original PDF.
+- When you correct a value, set `source` to the element you read it from:
+  `"source": {"element_id": "<id>"}`.
+- To confirm a row is right, change its `review` from `unchecked` to
+  `confirmed`. Unconfirming is not supported.
+- Never edit `library/` (generated), `part.yaml` or `datasheet.md`
+  (read-only); `push` refuses them. `dsmd restore <path>` undoes a local edit.
+- Conflict markers (`<<<<<<< local` / `=======` / `>>>>>>> server`) after a
+  pull surround one row (or, in a YAML file, the whole file): keep the right
+  side, delete the markers, push.
+
+## Workspace settings
+
+Both files are YAML, pushed with the parts (settings first, so a category you
+add is there for the parts in the same push). The server validates them like
+the web settings pages and answers `rejected` with the reason.
+
+`settings/mapping.yaml` -- how the workspace names and groups things (it
+drives the web app, comparisons, the API, the MCP server and the CAD exports
+listed in `used_by`):
+- `custom_categories`: your category names; `category_parents`:
+  `{child: parent}` to nest them.
+- `category_map`: `{catalogue category id: your category}`. `dsmd categories`
+  lists the catalogue's ids and names.
+- `parameter_map`: `{your category: {parameter: {name, unit, export, ...}}}`
+  -- rename a parameter, set its unit, choose whether it is exported; a
+  column you invent has `custom: true` and may carry a fixed `value`.
+- `custom_parameters`: `{name: {unit, units?, kind?, shortcut?}}`;
+  `custom_units`: `[{symbol, name?}]`.
+- `cad_fields`: `{kicad: [...]}` -- the properties each KiCad symbol gets.
+- `used_by`: which outputs use this mapping (`web_app`, `comparisons`,
+  `kicad_export`, `concept_hdl_export`, `altium_export`, `rest_api`,
+  `mcp_server`).
+
+`settings/symbol_style.yaml` -- how symbols are generated:
+- `style`: the workspace's overrides of `reference.system_style` (only the
+  keys you want different; unknown keys are rejected).
+- `categories`: `{category: style overrides}` for one category; an empty
+  value removes the override. Category names are your mapping's categories
+  or catalogue category names.
+- `designator_options`: the reference designators the workspace uses,
+  `[{id, say, value?}]` (`value` = the parameter shown as the symbol's
+  Value), or null for `reference.system_designator_options`.
+- `reference_designators`: `{category: designator}`.
+- `version` and `reference` are for reading only.
+
+## When something is missing
+
+If a setting, parameter, category or command you need does not exist, or the
+server refuses something that should work, tell the datasheets.md team:
+
+    dsmd feedback --kind suggestion "what you tried, what you needed"
+
+Use `--kind bug` for something broken. Then tell the user you sent it.

datasheets_md/auth.py

@@ -0,0 +1,216 @@
+"""Sign-in for dsmd and the GUI (Spec 27a 3.2).
+
+Browser OAuth against main-api's authorization server: dynamic client
+registration once per server, PKCE S256, and a loopback redirect on a free
+port. Credentials live in the user config dir (mode 0600), keyed by server.
+`DSMD_TOKEN` (a `dsh_` key) overrides them for headless use, `DSMD_SERVER`
+the server.
+"""
+import base64
+import hashlib
+import http.server
+import json
+import os
+import secrets
+import threading
+import time
+import urllib.parse
+import webbrowser
+from pathlib import Path
+
+import platformdirs
+import requests
+
+DEFAULT_SERVER = "https://api.datasheets.md"
+CLIENT_NAME = "dsmd"
+REDIRECT_PATH = "/callback"
+LOGIN_TIMEOUT = 300
+# Refresh this long before the access token expires.
+EXPIRY_MARGIN = 60
+
+
+class AuthError(Exception):
+    pass
+
+
+def credentials_path():
+    return Path(platformdirs.user_config_dir("datasheets-md")) / "credentials.json"
+
+
+def _load():
+    path = credentials_path()
+    try:
+        return json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {"servers": {}}
+
+
+def _save(data):
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        json.dump(data, fh, indent=2)
+    os.replace(tmp, path)
+
+
+def default_server(explicit=None):
+    """--server, else DSMD_SERVER, else the server last signed in to, else production."""
+    return (explicit or os.environ.get("DSMD_SERVER") or _load().get("default_server") or DEFAULT_SERVER).rstrip("/")
+
+
+def metadata(server):
+    resp = requests.get(f"{server}/.well-known/oauth-authorization-server", timeout=30)
+    if resp.status_code != 200:
+        raise AuthError(f"{server} does not offer sign-in (HTTP {resp.status_code})")
+    return resp.json()
+
+
+class Credentials:
+    """The bearer for one server: DSMD_TOKEN when set, else the stored OAuth tokens."""
+
+    def __init__(self, server):
+        self.server = server.rstrip("/")
+        self.env_token = os.environ.get("DSMD_TOKEN") or None
+
+    def stored(self):
+        return _load().get("servers", {}).get(self.server)
+
+    def token(self):
+        if self.env_token:
+            return self.env_token
+        entry = self.stored()
+        if not entry:
+            raise AuthError(f"not signed in to {self.server}; run dsmd login --server {self.server}")
+        if entry.get("expires_at", 0) - EXPIRY_MARGIN < time.time():
+            self.refresh()
+            entry = self.stored() or entry
+        return entry["access_token"]
+
+    def refresh(self):
+        """Renew the access token with the refresh token; False when there is nothing to renew with."""
+        if self.env_token:
+            return False
+        data = _load()
+        entry = data.get("servers", {}).get(self.server)
+        if not entry or not entry.get("refresh_token"):
+            return False
+        resp = requests.post(entry["token_endpoint"], data={
+            "grant_type": "refresh_token", "refresh_token": entry["refresh_token"],
+            "client_id": entry["client_id"]}, timeout=30)
+        if resp.status_code != 200:
+            return False
+        _store_tokens(data, self.server, entry, resp.json())
+        return True
+
+
+def _store_tokens(data, server, entry, tokens):
+    entry.update(access_token=tokens["access_token"],
+                 refresh_token=tokens.get("refresh_token") or entry.get("refresh_token"),
+                 expires_at=int(time.time()) + int(tokens.get("expires_in") or 3600))
+    data.setdefault("servers", {})[server] = entry
+    data["default_server"] = server
+    _save(data)
+
+
+def _pkce():
+    verifier = secrets.token_urlsafe(64)
+    challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+class _Callback(http.server.BaseHTTPRequestHandler):
+    result = None
+
+    def do_GET(self):  # noqa: N802 -- http.server's name
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != REDIRECT_PATH:
+            self.send_response(404)
+            self.end_headers()
+            return
+        type(self).result = dict(urllib.parse.parse_qsl(parsed.query))
+        body = b"<html><body><h3>dsmd is signed in.</h3>You can close this window.</body></html>"
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *args):
+        pass
+
+
+def login(server, *, open_browser=True, say=print):
+    """The browser flow. Returns the stored entry (without tokens)."""
+    server = server.rstrip("/")
+    meta = metadata(server)
+    data = _load()
+    entry = dict(data.get("servers", {}).get(server) or {})
+    if not entry.get("client_id"):
+        resp = requests.post(meta["registration_endpoint"], json={
+            "client_name": CLIENT_NAME, "redirect_uris": [f"http://127.0.0.1{REDIRECT_PATH}"],
+            "grant_types": ["authorization_code", "refresh_token"], "token_endpoint_auth_method": "none",
+        }, timeout=30)
+        if resp.status_code not in (200, 201):
+            raise AuthError(f"client registration failed (HTTP {resp.status_code}): {resp.text[:200]}")
+        entry["client_id"] = resp.json()["client_id"]
+    entry.update(token_endpoint=meta["token_endpoint"], revocation_endpoint=meta.get("revocation_endpoint"))
+
+    handler = type("Callback", (_Callback,), {"result": None})
+    httpd = http.server.HTTPServer(("127.0.0.1", 0), handler)
+    redirect_uri = f"http://127.0.0.1:{httpd.server_port}{REDIRECT_PATH}"
+    verifier, challenge = _pkce()
+    state = secrets.token_urlsafe(16)
+    url = meta["authorization_endpoint"] + "?" + urllib.parse.urlencode({
+        "response_type": "code", "client_id": entry["client_id"], "redirect_uri": redirect_uri,
+        "code_challenge": challenge, "code_challenge_method": "S256", "state": state})
+    say(f"Opening the browser to sign in. If it does not open, visit:\n  {url}")
+    if open_browser:
+        webbrowser.open(url)
+    thread = threading.Thread(target=_serve_until_called, args=(httpd, handler), daemon=True)
+    thread.start()
+    thread.join(LOGIN_TIMEOUT)
+    httpd.server_close()
+    result = handler.result
+    if not result:
+        raise AuthError("timed out waiting for the browser sign-in")
+    if result.get("state") != state:
+        raise AuthError("sign-in answered with the wrong state; try again")
+    if "code" not in result:
+        raise AuthError(f"sign-in refused: {result.get('error', 'no code returned')}")
+    resp = requests.post(meta["token_endpoint"], data={
+        "grant_type": "authorization_code", "code": result["code"], "redirect_uri": redirect_uri,
+        "client_id": entry["client_id"], "code_verifier": verifier}, timeout=30)
+    if resp.status_code != 200:
+        raise AuthError(f"token exchange failed (HTTP {resp.status_code}): {resp.text[:200]}")
+    _store_tokens(data, server, entry, resp.json())
+    return {"server": server, "client_id": entry["client_id"]}
+
+
+def _serve_until_called(httpd, handler):
+    deadline = time.time() + LOGIN_TIMEOUT
+    httpd.timeout = 1
+    while handler.result is None and time.time() < deadline:
+        httpd.handle_request()
+
+
+def logout(server):
+    """Revoke the refresh token and forget the server's credentials. True when there were any."""
+    server = server.rstrip("/")
+    data = _load()
+    entry = data.get("servers", {}).pop(server, None)
+    if entry is None:
+        return False
+    if entry.get("revocation_endpoint") and entry.get("refresh_token"):
+        try:
+            requests.post(entry["revocation_endpoint"], data={"token": entry["refresh_token"]}, timeout=15)
+        except requests.RequestException:
+            pass
+    if data.get("default_server") == server:
+        data.pop("default_server")
+    if data.get("servers"):
+        _save(data)
+    else:
+        credentials_path().unlink(missing_ok=True)
+    return True

datasheets_md/cli.py

@@ -0,0 +1,370 @@
+"""`dsmd` -- a git-like working copy of a datasheets.md workspace.
+
+Exit codes: 0 ok; 1 error; 2 completed, but with conflicts, stale/rejected parts or no library/.
+"""
+import argparse
+import json
+import os
+import shlex
+import sys
+from importlib import resources
+
+import requests
+
+from . import __version__, auth, sync, update
+from .http import ApiError, Client
+from .repo import Repo, RepoError
+
+EXIT_OK, EXIT_ERROR, EXIT_PARTIAL = 0, 1, 2
+
+
+class Output:
+    def __init__(self, as_json=False, quiet=False):
+        self.as_json, self.quiet = as_json, quiet
+
+    def say(self, *lines):
+        """Progress: stderr, so --json stdout stays one document."""
+        if not self.quiet:
+            for line in lines:
+                print(line, file=sys.stderr)
+
+    def result(self, data, text=None):
+        if self.as_json:
+            print(json.dumps(data, indent=2, default=str))
+        elif text and not self.quiet:
+            print(text)
+
+
+def _client(server=None, workspace_id=None):
+    server = auth.default_server(server)
+    return Client(server, auth.Credentials(server), workspace_id)
+
+
+def _repo_client(args):
+    repo = Repo.find(args.C or ".")
+    return repo, _client(repo.state["server"], repo.state["workspace_id"])
+
+
+# ----- commands ----------------------------------------------------------------------
+
+def cmd_login(args, out):
+    server = auth.default_server(args.server)
+    done = auth.login(server, open_browser=not args.no_browser, say=out.say)
+    me = _client(server).get("/users/me/", workspace=False)
+    out.result({**done, "email": me.get("email")}, f"Signed in to {server} as {me.get('email')}")
+
+
+def cmd_logout(args, out):
+    server = auth.default_server(args.server)
+    had = auth.logout(server)
+    out.result({"server": server, "signed_out": had}, f"Signed out of {server}" if had else f"Not signed in to {server}")
+
+
+def cmd_whoami(args, out):
+    client = _client(args.server)
+    me = client.get("/users/me/", workspace=False)
+    via = "DSMD_TOKEN" if os.environ.get("DSMD_TOKEN") else "dsmd login"
+    out.result({"server": client.server, "email": me.get("email"), "username": me.get("username"), "via": via},
+               f"{me.get('email')} on {client.server} (via {via})")
+
+
+def cmd_workspaces(args, out):
+    rows = _client(args.server).get("/workspaces/", workspace=False)
+    text = "\n".join(f"{w['id']:>6}  {w.get('name')}{'  (default)' if w.get('is_default') else ''}  [{w.get('user_role')}]"
+                     for w in rows)
+    out.result(rows, text or "No workspaces.")
+
+
+def cmd_clone(args, out):
+    client = _client(args.server)
+    parts = [p.strip() for p in args.parts.split(",") if p.strip()] if args.parts else None
+    directory = args.dir or str(args.workspace).replace(" ", "-").lower()
+    done = sync.clone(client, args.workspace, os.path.join(args.C or ".", directory), parts=parts, say=out.say)
+    lines = [f"Cloned {done['parts']} parts into {done['root']}"]
+    lines += [f"warning   {done['library_error']}"] if done["library_error"] else []
+    out.result(done, "\n".join(lines))
+    return EXIT_PARTIAL if done["library_error"] else EXIT_OK
+
+
+def cmd_fetch(args, out):
+    repo, client = _repo_client(args)
+    with repo.lock():
+        got = sync.fetch(repo, client, say=out.say)
+    out.result(got, (f"{got['changed_files']} files and {got['changed_datasheets']} datasheets changed on the server "
+                     f"({got['new_parts']} new parts, {got['removed_parts']} removed, {got['moved_parts']} moved); "
+                     "run dsmd pull to merge them"))
+
+
+def cmd_pull(args, out):
+    repo, client = _repo_client(args)
+    with repo.lock():
+        report = sync.pull(repo, client, rebuild_library=args.library, say=out.say)
+    lines = [f"Pulled: {report['changed_files']} files, {report['changed_datasheets']} datasheets, "
+             f"{report['new_parts']} new parts, "
+             f"{report['removed_parts']} removed, {report['moved_parts']} moved"]
+    lines += [f"merged    {p}" for p in report["merged"]]
+    lines += [f"CONFLICT  {c['path']} ({c['conflicts']} rows)" for c in report["conflicts"]]
+    lines += [f"saved     {p} (your edit of a read-only file)" for p in report["saved_local"]]
+    lines += [f"warning   {w}" for w in report["warnings"]]
+    out.result(report, "\n".join(lines))
+    return EXIT_PARTIAL if report["conflicts"] or report.get("library_error") else EXIT_OK
+
+
+def cmd_status(args, out):
+    repo = Repo.find(args.C or ".")
+    report = sync.status(repo)
+    lines = [f"Workspace {report['workspace']['name']} ({report['workspace']['id']}) on {report['server']}"]
+    for part in report["parts"]:
+        lines.append(f"{part['path']}/")
+        lines += [f"    {f['state']:<18} {f['name']}" for f in part["files"]]
+    lines += [f"{s['state']:<22} {s['path']}" for s in report["settings"] + report["datasheets"]]
+    lines += [f"generated, will be overwritten: {p}" for p in report["generated_edited"]]
+    lines += [f"untracked, ignored: {p}/" for p in report["untracked"]]
+    if report["incomplete"]:
+        lines.append(f"The clone did not finish; continue it with: {report['incomplete']}")
+    elif report["library_missing"]:
+        lines.append("library/ is not built; run dsmd pull --library")
+    if report["clean"]:
+        lines.append("Nothing to push; working copy clean.")
+    elif report["nothing_to_push"]:
+        lines.append("Nothing to push.")
+    out.result(report, "\n".join(lines))
+
+
+def cmd_diff(args, out):
+    repo = Repo.find(args.C or ".")
+    text = sync.diff(repo, args.target)
+    out.result({"diff": text}, text.rstrip("\n") if text else "No local changes.")
+
+
+def cmd_restore(args, out):
+    repo = Repo.find(args.C or ".")
+    with repo.lock():
+        done = sync.restore(repo, args.target)
+    out.result({"restored": done}, "\n".join(f"restored {p}" for p in done) or "Nothing to restore.")
+
+
+def _where(path, error):
+    """`parts/X/Y/pins.csv:3` for a part's file, `settings/mapping.yaml:3` for a settings file."""
+    name = error.get("file")
+    where = path if not name or name == path else f"{path}/{name}"
+    return where + (f":{error['line']}" if error.get("line") else "")
+
+
+def cmd_push(args, out):
+    repo, client = _repo_client(args)
+    with repo.lock():
+        result = sync.push(repo, client, args.message, say=out.say)
+    lines = [f"applied   {r['path']}" for r in result["applied"]]
+    lines += [f"stale     {r['path']}: changed on the server; run dsmd pull, then push again" for r in result["stale"]]
+    for r in result["rejected"]:
+        lines += [f"rejected  {_where(r['path'], e)}: {e['error']}" for e in r["errors"]] or [f"rejected  {r['path']}"]
+    out.result(result, "\n".join(lines) or "Nothing to push.")
+    return EXIT_PARTIAL if result["stale"] or result["rejected"] else EXIT_OK
+
+
+def cmd_log(args, out):
+    repo, client = _repo_client(args)
+    data = sync.log(repo, client, args.part, args.page)
+    lines = []
+    for e in data["entries"]:
+        counts = ", ".join(f"{k} {v}" if not isinstance(v, dict) else
+                           f"{k}: " + " ".join(f"{op} {n}" for op, n in v.items() if n)
+                           for k, v in (e.get("summary") or {}).items())
+        lines.append(f"{e['at'][:19]}  {e.get('user') or '?'}  {e.get('part_number') or e['part_uuid']}  "
+                     f"{e.get('message') or ''}\n    {counts}")
+    out.result(data, "\n".join(lines) or "No pushes yet.")
+
+
+def cmd_part(args, out):
+    repo, client = _repo_client(args)
+    with repo.lock():
+        if args.part_cmd == "add":
+            done = sync.part_add(repo, client, args.part_number, args.manufacturer, say=out.say)
+            out.result(done, f"Added {args.part_number}")
+            return
+        uuid = repo.resolve(args.ident)
+        path = repo.parts()[uuid]["path"]
+        if not args.yes:
+            if not sys.stdin.isatty():
+                raise RepoError("refusing to remove without confirmation; pass --yes")
+            if input(f"Remove {path} from the workspace on the server? [y/N] ").strip().lower() != "y":
+                out.result({"removed": False}, "Cancelled.")
+                return
+        done = sync.part_rm(repo, client, uuid, say=out.say)
+        out.result(done, f"Removed {path}")
+
+
+def cmd_pdf(args, out):
+    repo, client = _repo_client(args)
+    path = sync.pdf(repo, client, args.part)
+    out.result({"path": path}, path)
+
+
+def cmd_open(args, out):
+    repo = Repo.find(args.C or ".")
+    url = sync.open_part(repo, args.part)
+    out.result({"url": url}, url)
+
+
+def cmd_categories(args, out):
+    _, client = _repo_client(args)
+    rows = sync.categories(client)
+    names = {r["id"]: r["name"] for r in rows}
+    out.result(rows, "\n".join(f"{r['id']}  {r['name']}"
+                                + (f"  (under {names.get(r['parent_id'], '?')})" if r["parent_id"] else "")
+                                + (f"  [{r['parts']} parts]" if r["parts"] else "") for r in rows))
+
+
+def cmd_feedback(args, out):
+    try:
+        _, client = _repo_client(args)
+    except RepoError:                       # outside a working copy: no workspace, still fine
+        client = _client(args.server)
+    sync.feedback(client, " ".join(args.message), args.kind)
+    out.result({"sent": True}, "Sent. Thank you -- the datasheets.md team reads every note.")
+
+
+def cmd_gui(args, out):
+    try:
+        from .gui.app import main as gui_main
+    except ImportError as exc:
+        raise RepoError(f'the GUI needs PySide6: pip install datasheets-md-gui ({exc})') from None
+    return gui_main(["--foreground"] if args.foreground else [])
+
+
+def cmd_self_update(args, out):
+    try:
+        latest = update.latest_version(timeout=15)
+    except (requests.RequestException, ValueError) as exc:
+        raise RepoError(f"cannot ask {update.index_url()} for the latest version: {exc}") from None
+    report = {"current": __version__, "latest": latest, "updated": False}
+    if not update.newer(latest):
+        out.result(report, f"dsmd {__version__} is the latest version")
+        return
+    if args.check:
+        out.result(report, f"dsmd {latest} is available (you have {__version__}); run: dsmd self-update")
+        return
+    argv, why_not = update.upgrade_command(latest)
+    if argv is None:
+        raise RepoError(why_not)
+    out.say(f"Updating dsmd {__version__} -> {latest}: {shlex.join(argv)}")
+    code = update.run(argv)
+    if code:
+        raise RepoError(f"the update failed (exit {code}); the command above shows why")
+    if code is None:
+        out.result({**report, "deferred": True}, f"The update to {latest} continues in a new window once dsmd exits.")
+        return
+    installed = update.installed_version()
+    if installed != latest:                 # pipx and uv exit 0 when they find nothing to do
+        raise RepoError(f"dsmd is still {installed} after the update, not {latest}; it was probably installed "
+                        "without --pre or from another index, so reinstall it the way you installed it")
+    out.result({**report, "updated": True}, f"Updated to dsmd {latest}")
+
+
+def cmd_help(args, out):
+    if args.topic != "agents":
+        raise RepoError("unknown help topic; try: dsmd help agents")
+    text = resources.files("datasheets_md").joinpath("agents.md").read_text(encoding="utf-8")
+    out.result({"agents": text}, text.rstrip("\n"))
+
+
+# ----- parser ------------------------------------------------------------------------------
+
+def _globals(suppress):
+    """The global flags. Subcommands accept them too, with SUPPRESS defaults so
+    `dsmd --json status` is not reset by the subparser's own default."""
+    kw = {"default": argparse.SUPPRESS} if suppress else {}
+    flags = argparse.ArgumentParser(add_help=False)
+    flags.add_argument("--json", action="store_true", help="machine-readable output on stdout", **kw)
+    flags.add_argument("--quiet", "-q", action="store_true", help="no progress output", **kw)
+    flags.add_argument("-C", metavar="DIR", help="run as if started in DIR", **kw)
+    return flags
+
+
+def parser():
+    common = _globals(suppress=True)
+    p = argparse.ArgumentParser(prog="dsmd", parents=[_globals(suppress=False)],
+                                description="A git-like working copy of your datasheets.md workspace.",
+                                epilog="Settings are files: edit settings/mapping.yaml or settings/symbol_style.yaml "
+                                       "(owner/admin), then dsmd push. Guide: dsmd help agents")
+    p.add_argument("--version", action="version", version=f"dsmd {__version__}")
+    sub = p.add_subparsers(dest="command", required=True, metavar="<command>")
+
+    def add(name, fn, help_text):
+        cmd = sub.add_parser(name, parents=[common], help=help_text, description=help_text)
+        cmd.set_defaults(fn=fn)
+        return cmd
+
+    for name, fn, text in (("login", cmd_login, "sign in through the browser"),
+                           ("logout", cmd_logout, "sign out and revoke the stored session"),
+                           ("whoami", cmd_whoami, "show who you are signed in as")):
+        cmd = add(name, fn, text)
+        cmd.add_argument("--server", help=f"API server (default: DSMD_SERVER or {auth.DEFAULT_SERVER})")
+        if name == "login":
+            cmd.add_argument("--no-browser", action="store_true", help="print the sign-in URL instead of opening it")
+    add("workspaces", cmd_workspaces, "list your workspaces").add_argument("--server")
+    cmd = add("clone", cmd_clone, "create a working copy of a workspace")
+    cmd.add_argument("workspace", help="workspace id or name")
+    cmd.add_argument("dir", nargs="?", help="target folder (default: the workspace name)")
+    cmd.add_argument("--parts", help="comma-separated part uuids for a sparse clone")
+    cmd.add_argument("--server")
+    add("fetch", cmd_fetch, "download server changes without merging them")
+    add("pull", cmd_pull, "fetch and merge server changes; rebuild library/").add_argument(
+        "--library", action="store_true", help="rebuild library/ even when nothing changed")
+    add("status", cmd_status, "show local changes")
+    add("diff", cmd_diff, "show local changes as a diff").add_argument("target", nargs="?", help="part or path")
+    add("restore", cmd_restore, "discard local changes").add_argument("target", nargs="?", help="part or path")
+    add("push", cmd_push, "send local changes (parts and settings) to the workspace").add_argument(
+        "-m", "--message", required=True, help="what changed and why")
+    cmd = add("log", cmd_log, "server-side history of pushes")
+    cmd.add_argument("part", nargs="?")
+    cmd.add_argument("--page", type=int, default=1)
+    part = add("part", cmd_part, "add or remove parts in the workspace")
+    part_sub = part.add_subparsers(dest="part_cmd", required=True, metavar="<add|rm>")
+    padd = part_sub.add_parser("add", parents=[common], help="add a public catalogue part")
+    padd.add_argument("part_number")
+    padd.add_argument("--manufacturer")
+    prm = part_sub.add_parser("rm", parents=[common], help="remove a part from the workspace")
+    prm.add_argument("ident", help="part number, uuid or folder")
+    prm.add_argument("--yes", "-y", action="store_true", help="do not ask")
+    add("pdf", cmd_pdf, "download a part's PDF into .dsmd/cache and print its path").add_argument("part")
+    add("open", cmd_open, "open a part's web page").add_argument("part")
+    add("categories", cmd_categories, "list the catalogue categories (the ids settings/mapping.yaml's category_map uses)")
+    cmd = add("feedback", cmd_feedback, "tell the datasheets.md team about a bug or a missing setting")
+    cmd.add_argument("message", nargs="+")
+    cmd.add_argument("--kind", choices=sync.FEEDBACK_KINDS, default="other")
+    cmd.add_argument("--server")
+    add("gui", cmd_gui, "launch the desktop app in the background (needs datasheets-md-gui)").add_argument(
+        "--foreground", action="store_true", help="stay attached to the terminal and print its output")
+    add("self-update", cmd_self_update, "upgrade dsmd to the latest release").add_argument(
+        "--check", action="store_true", help="only say whether a newer release exists")
+    add("help", cmd_help, "extra help topics").add_argument("topic", choices=["agents"])
+    return p
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    out = Output(args.json, args.quiet)
+    try:
+        code = args.fn(args, out)
+    except (ApiError, RepoError, auth.AuthError) as exc:
+        if args.json:
+            print(json.dumps({"error": str(exc), "status": getattr(exc, "status", None)}))
+        else:
+            print(f"dsmd: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        return EXIT_ERROR
+    if args.command != "self-update" and not (args.json or args.quiet) and sys.stderr.isatty():
+        try:
+            line = update.notice()
+        except Exception:                   # a broken check never fails the command
+            line = None
+        if line:
+            print(line, file=sys.stderr)
+    return code or EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())