geodeploy 1.3.0__py3-none-any.whl

geodeploy/__init__.py

@@ -0,0 +1,52 @@
+"""GeoDeploy — command-line client and Python API.
+
+    from geodeploy import Client
+    gd = Client("https://geodeploy.example.org", token="gdp_…")
+    layer = gd.uploads.upload("roads.gpkg", wait=True)
+    portal = gd.portals.create("Roads")
+    gd.portals.add_layer(portal["id"], layer.layer_id, "vector", {"color": "#e11d48"})
+    gd.portals.publish(portal["id"])
+
+Zero runtime dependencies, Python 3.9+, so the QGIS plugin can vendor this package as-is.
+"""
+from __future__ import annotations
+
+# The CLI's version tracks the GeoDeploy release it ships with. A PyPI version can never be
+# re-uploaded, so a number is only spent once the release it names exists: 1.3.0b1 proved the
+# packaging against the real index, and this is the release it was rehearsing for.
+__version__ = "1.3.0"
+
+from .client import Client  # noqa: E402  (after __version__ — the user agent reads it)
+from .errors import (  # noqa: E402
+    APIError,
+    AuthError,
+    ConfigError,
+    ConflictError,
+    GeoDeployError,
+    NotFoundError,
+    PermissionError_,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+from .jobs import JobFailed, JobTimeout  # noqa: E402
+from .styles import Style, parse_style  # noqa: E402
+
+__all__ = [
+    "Client",
+    "Style",
+    "parse_style",
+    "GeoDeployError",
+    "APIError",
+    "AuthError",
+    "ConfigError",
+    "ConflictError",
+    "NotFoundError",
+    "PermissionError_",
+    "ServerError",
+    "TransportError",
+    "ValidationError",
+    "JobFailed",
+    "JobTimeout",
+    "__version__",
+]

geodeploy/__main__.py

@@ -0,0 +1,13 @@
+"""`python -m geodeploy` — the same entry point as the `geodeploy` console script.
+
+Worth having: inside QGIS's bundled Python, or a virtualenv whose `Scripts/` is not on PATH, the
+module form is the one that works.
+"""
+from __future__ import annotations
+
+import sys
+
+from .cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

geodeploy/admin.py

@@ -0,0 +1,191 @@
+"""Operating an instance: health, services, updates, backups, the audit log, and users.
+
+**These routes refuse API tokens.** `deps.require_role`/`require_admin` reject a token-authenticated
+request outright, so a leaked `gdp_…` cannot restart your database, read your storage credentials,
+or mint more tokens. That is a deliberate security property, not an oversight — so everything in
+this module needs a *session*: `geodeploy login --password`, or `Client(url, jwt=…)`.
+
+`Users` is the exception: `/users/*` is scope-gated (`users:admin`), so a token with that scope can
+manage members.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .errors import PermissionError_, ValidationError
+
+#: Services the health endpoint reports on. `api` is deliberately not controllable — it is the
+#: process serving the request that would stop it.
+SERVICES = ("postgres", "minio", "redis", "martin", "titiler", "nginx", "celery", "ui", "api")
+ACTIONS = ("start", "stop", "restart")
+
+
+def _session_only(exc: PermissionError_) -> PermissionError_:
+    """Turn the API's bare 403 into the actionable version of the same fact."""
+    if exc.status == 403 and "token" in (exc.detail or "").lower():
+        return PermissionError_(
+            exc.status,
+            "{0} — administration is session-only by design, so a leaked API token cannot "
+            "reconfigure the instance. Run `geodeploy login --password` first.".format(exc.detail),
+            exc.url, exc.payload)
+    return exc
+
+
+class Admin(object):
+    def __init__(self, client: Any):
+        self._c = client
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        try:
+            return self._c.get(path, params)
+        except PermissionError_ as exc:
+            raise _session_only(exc)
+
+    def _post(self, path: str, json: Any = None) -> Any:
+        try:
+            return self._c.post(path, json)
+        except PermissionError_ as exc:
+            raise _session_only(exc)
+
+    # ── health & services ───────────────────────────────────────────────────────────────────────
+
+    def health(self) -> List[Dict[str, Any]]:
+        return self._get("/admin/health")
+
+    def service(self, name: str, action: str) -> Any:
+        if action not in ACTIONS:
+            raise ValidationError(400, "Action must be one of {0}.".format(", ".join(ACTIONS)))
+        return self._post("/admin/services/{0}/{1}".format(name, action))
+
+    def logs(self, name: str, tail: int = 200, timestamps: bool = True) -> Any:
+        return self._get("/admin/services/{0}/logs".format(name),
+                         {"tail": tail, "timestamps": timestamps})
+
+    def reload_martin(self) -> Any:
+        """Regenerate Martin's config from every ready PostGIS layer — the manual recovery hook
+        for a tile server that has ended up with a stale or empty config."""
+        return self._post("/admin/reload-martin")
+
+    def storage_stats(self) -> Dict[str, Any]:
+        """Per-store usage. A store that could not be measured is `null`, NOT 0 — the difference
+        between "the database is unreachable" and "the database is empty"."""
+        return self._get("/admin/storage-stats")
+
+    # ── updates ─────────────────────────────────────────────────────────────────────────────────
+
+    def updates(self, refresh: bool = False) -> Dict[str, Any]:
+        """What this instance could move to: `main`, the latest release, every release, branches.
+
+        `refresh=True` bypasses the 10-minute cache. That cache protects GitHub's unauthenticated
+        rate limit against page loads; a deliberate check must not answer from it, or a commit
+        pushed a minute ago looks like it never landed.
+        """
+        return self._get("/admin/updates", {"refresh": refresh} if refresh else None)
+
+    def preflight(self) -> Dict[str, Any]:
+        """Whether an update is safe to start right now (it refuses over work in progress)."""
+        return self._get("/admin/update/preflight")
+
+    def update(self, target: Optional[str] = None) -> Dict[str, Any]:
+        """Start an update. The API container restarts as part of it, so the call that STARTS an
+        update is not the one that reports its outcome — poll `update_status`."""
+        return self._post("/admin/update", {"target": target} if target else None)
+
+    def update_status(self) -> Dict[str, Any]:
+        return self._get("/admin/update/status")
+
+    def deployments(self, limit: int = 20) -> Any:
+        return self._get("/admin/deployments", {"limit": limit})
+
+    def credentials(self) -> Dict[str, Any]:
+        """Connection details for the managed PostGIS/MinIO. Owner-only, and audited."""
+        return self._get("/admin/credentials")
+
+    # ── the public listing ──────────────────────────────────────────────────────────────────────
+
+    def public_index(self) -> Dict[str, Any]:
+        """Whether this instance publishes `GET /api/public` — its anonymous index."""
+        return self._get("/admin/public-index")
+
+    def set_public_index(self, enabled: bool) -> Dict[str, Any]:
+        """List, or stop listing, what this instance publishes.
+
+        Discoverability, not access: a published public portal stays reachable by its link either
+        way. Audited, because "why did our datasets stop appearing" deserves an answer.
+        """
+        try:
+            return self._c.put("/admin/public-index", {"enabled": bool(enabled)})
+        except PermissionError_ as exc:
+            raise _session_only(exc)
+
+    # ── audit ───────────────────────────────────────────────────────────────────────────────────
+
+    def audit(self, limit: int = 20, offset: int = 0, action: Optional[str] = None,
+              resource_type: Optional[str] = None, resource_id: Optional[str] = None,
+              actor_id: Optional[int] = None, query: Optional[str] = None,
+              since: Optional[str] = None, until: Optional[str] = None) -> Dict[str, Any]:
+        """A PAGE of the activity log. Every filter is applied server-side before the page is cut —
+        never fetch the log and filter locally, that searches only the slice you downloaded."""
+        return self._get("/audit", {"limit": limit, "offset": offset, "action": action,
+                                    "resource_type": resource_type, "resource_id": resource_id,
+                                    "actor_id": actor_id, "q": query, "since": since,
+                                    "until": until})
+
+    def audit_actions(self) -> List[str]:
+        return self._get("/audit/actions")
+
+    # ── backups ─────────────────────────────────────────────────────────────────────────────────
+
+    def backup_settings(self) -> Dict[str, Any]:
+        return self._get("/backups/settings")
+
+    def backup_runs(self, limit: int = 20) -> Any:
+        return self._get("/backups/runs", {"limit": limit})
+
+    def backup_stored(self) -> Any:
+        """The destination's own manifests — the only trustworthy inventory, since our run table
+        lives in the state database that is itself part of what gets backed up."""
+        return self._get("/backups/stored")
+
+    def backup_run(self) -> Any:
+        return self._post("/backups/run")
+
+    def backup_test(self) -> Any:
+        return self._post("/backups/settings/test")
+
+
+class Users(object):
+    """Members, roles and invitations — `users:admin` scope, so a token can do this."""
+
+    def __init__(self, client: Any):
+        self._c = client
+
+    def list(self) -> List[Dict[str, Any]]:
+        return self._c.get("/users")
+
+    def invite(self, email: str, role: str = "viewer") -> Dict[str, Any]:
+        """Create an invitation. The raw token is returned ONCE — regenerate is the only way to get
+        a link again. It is emailed too when SMTP is configured, but the link always works."""
+        if role not in ("viewer", "editor", "admin"):
+            raise ValidationError(400, "Role must be viewer, editor or admin (owner is transferred).")
+        return self._c.post("/users/invitations", {"email": email, "role": role})
+
+    def invitations(self) -> List[Dict[str, Any]]:
+        return self._c.get("/users/invitations")
+
+    def revoke_invitation(self, invitation_id: int) -> Any:
+        return self._c.delete("/users/invitations/{0}".format(int(invitation_id)))
+
+    def regenerate_invitation(self, invitation_id: int) -> Any:
+        return self._c.post("/users/invitations/{0}/regenerate".format(int(invitation_id)))
+
+    def set_role(self, user_id: int, role: str) -> Dict[str, Any]:
+        return self._c.put("/users/{0}/role".format(int(user_id)), {"role": role})
+
+    def delete(self, user_id: int) -> Any:
+        """Delete a member. Their layers, portals and sources are REASSIGNED to the owner —
+        nothing of theirs is destroyed."""
+        return self._c.delete("/users/{0}".format(int(user_id)))
+
+    def reset_link(self, user_id: int) -> Dict[str, Any]:
+        return self._c.post("/users/{0}/reset-password-link".format(int(user_id)))

geodeploy/catalog.py

@@ -0,0 +1,96 @@
+"""The public read surfaces: STAC, OGC API - Features, templates and basemaps.
+
+These need no credentials — they are what an instance offers the rest of the world, and what QGIS,
+ArcGIS, FME and GDAL connect to. Only layers explicitly shared as **public** appear here; the CLI
+reaching them anonymously is therefore also the honest way to check what you have actually exposed:
+if `geodeploy catalog collections` does not list it, nor can anyone else.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class Catalog(object):
+    def __init__(self, client: Any):
+        self._c = client
+
+    # ── the instance index ──────────────────────────────────────────────────────────────────────
+
+    def public(self) -> Dict[str, Any]:
+        """Everything this instance offers anonymously: public portals, and public layers grouped
+        by storage kind (`raster`, `postgis`, `geoparquet`).
+
+        This is the "paste a URL and see what is there" call — the first screen of a plugin. An
+        instance may switch its index off, in which case this raises `NotFoundError`: that is a
+        decision ("no index here"), distinct from an empty one ("nothing published").
+        """
+        return self._c.get("/public", auth=False)
+
+    def public_portals(self) -> List[Dict[str, Any]]:
+        return self._c.get("/public/portals", auth=False) or []
+
+    def portal_style(self, style_url: str) -> Dict[str, Any]:
+        """A published portal's own `style.json` — sources, layers, folder tree, bounds.
+
+        The whole portal in one anonymous fetch, which is what makes "open this portal in QGIS"
+        possible without a token. The URL comes from `public()`; it is a static file in the
+        published bundle, not an API route.
+        """
+        response = self._c.send_absolute("GET", style_url)
+        if response.status >= 400:
+            from .errors import from_status
+            raise from_status(response.status, "Could not read the portal style.", response.url)
+        return response.json()
+
+    # ── OGC API - Features ──────────────────────────────────────────────────────────────────────
+
+    def collections(self) -> List[Dict[str, Any]]:
+        """One collection per public, ready vector layer. Ids mirror the STAC item ids."""
+        data = self._c.get("/ogc/collections", auth=False) or {}
+        return data.get("collections") or []
+
+    def collection(self, cid: str) -> Dict[str, Any]:
+        return self._c.get("/ogc/collections/{0}".format(cid), auth=False)
+
+    def items(self, cid: str, bbox: Optional[str] = None, limit: int = 10,
+              offset: int = 0) -> Dict[str, Any]:
+        return self._c.get("/ogc/collections/{0}/items".format(cid),
+                           {"bbox": bbox, "limit": limit, "offset": offset}, auth=False)
+
+    def item(self, cid: str, fid: str) -> Dict[str, Any]:
+        return self._c.get("/ogc/collections/{0}/items/{1}".format(cid, fid), auth=False)
+
+    def conformance(self) -> Dict[str, Any]:
+        """What the OGC endpoint claims to support — Core + GeoJSON, and nothing it does not do."""
+        return self._c.get("/ogc/conformance", auth=False)
+
+    # ── STAC ────────────────────────────────────────────────────────────────────────────────────
+
+    def stac(self) -> Dict[str, Any]:
+        return self._c.get("/stac", auth=False)
+
+    def stac_collections(self) -> List[Dict[str, Any]]:
+        data = self._c.get("/stac/collections", auth=False) or {}
+        return data.get("collections") or []
+
+    def stac_items(self, cid: str, bbox: Optional[str] = None, datetime: Optional[str] = None,
+                   limit: int = 100, offset: int = 0) -> Dict[str, Any]:
+        return self._c.get("/stac/collections/{0}/items".format(cid),
+                           {"bbox": bbox, "datetime": datetime, "limit": limit, "offset": offset},
+                           auth=False)
+
+    def search(self, bbox: Optional[str] = None, collections: Optional[str] = None,
+               datetime: Optional[str] = None, ids: Optional[str] = None,
+               limit: int = 100) -> Dict[str, Any]:
+        return self._c.get("/stac/search", {"bbox": bbox, "collections": collections,
+                                            "datetime": datetime, "ids": ids, "limit": limit},
+                           auth=False)
+
+    # ── portal building blocks ──────────────────────────────────────────────────────────────────
+
+    def templates(self) -> List[Dict[str, Any]]:
+        """Portal templates, each declaring the experiences (`archetypes`) it may be used for."""
+        return self._c.get("/templates", auth=False)
+
+    def basemaps(self) -> List[Dict[str, Any]]:
+        return self._c.get("/basemaps", auth=False)

geodeploy/cli/__init__.py

@@ -0,0 +1,7 @@
+"""The `geodeploy` command-line interface.
+
+Everything user-facing lives under here — argument parsing, tables, progress bars, exit codes. The
+package above it (`geodeploy.client` and friends) is a library and never prints or exits, which is
+what lets the QGIS plugin import it without dragging a CLI along.
+"""
+from __future__ import annotations

geodeploy/cli/commands/__init__.py

@@ -0,0 +1,2 @@
+"""One module per command group. Each exposes `register(subparsers)`."""
+from __future__ import annotations

geodeploy/cli/commands/_common.py

@@ -0,0 +1,233 @@
+"""Argument groups and helpers shared by several command modules.
+
+The styling flags live here because THREE commands take the same set — `portals add-layer`,
+`portals style` and `layers style` (a layer's own default). Defining them once is not only less
+code: it is the only way the three stay consistent, and inconsistency between them is exactly the
+kind of thing nobody notices until someone's map is wrong.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional
+
+from ...errors import ValidationError
+from ...styles import (CLASSIFY_METHODS, COLOR_MODES, LINE_TYPES, MARKERS, RAMPS, build_style,
+                       parse_categories, parse_classes)
+
+
+def add_style_args(parser, raster: bool = True) -> None:
+    """Every styling flag the API accepts, including the v1.1 data-driven symbology."""
+    single = parser.add_argument_group(
+        "symbology (single symbol)",
+        "Only the flags you pass are changed; everything else keeps its current value.")
+    single.add_argument("--color", help="main colour: polygon fill, line, or point (hex or name)")
+    single.add_argument("--fill-opacity", type=float, help="polygon fill opacity, 0-1")
+    single.add_argument("--outline-color",
+                        help="outline colour, or 'none' for no outline at all")
+    single.add_argument("--outline-width", type=float,
+                        help="point outline width as a FRACTION of the radius (0-1, default 0.28) "
+                             "— a wide one on a small marker is how a ring is drawn")
+    single.add_argument("--line-width", type=float, help="line width in px")
+    single.add_argument("--radius", type=float, help="point radius in px")
+    single.add_argument("--marker", choices=MARKERS, help="point marker shape")
+    single.add_argument("--line-type", choices=LINE_TYPES, help="line dash pattern")
+    single.add_argument("--opacity", type=float, help="layer opacity, 0-1")
+
+    driven = parser.add_argument_group(
+        "symbology (data-driven, v1.1)",
+        "Colour or size from a feature property. --classify asks the instance to compute the "
+        "breaks with the same code the editor and the published portal use.")
+    driven.add_argument("--color-field", help="property to colour by")
+    driven.add_argument("--color-mode", choices=COLOR_MODES,
+                        help="single | graduated (numeric classes) | categorized (text values)")
+    driven.add_argument("--classify", nargs="?", const="quantile", choices=CLASSIFY_METHODS,
+                        help="compute classes from the data: quantile (default), equal, jenks")
+    driven.add_argument("--classes", type=int, default=None,
+                        help="how many classes to compute (2-12, default 5)")
+    driven.add_argument("--ramp", choices=RAMPS, help="colour ramp for computed classes")
+    driven.add_argument("--reverse-ramp", action="store_true",
+                        help="run the ramp the other way (light end for the low values)")
+    driven.add_argument("--class-breaks",
+                        help="explicit classes instead of computing them: '0-10:#fee,10-50:#f00' "
+                             "(* is an open edge)")
+    driven.add_argument("--categories",
+                        help="explicit categories: 'forest:#2c7,water:#39f'")
+    driven.add_argument("--other-color", help="colour for values in no category")
+    driven.add_argument("--size-field", help="property to size points/lines by")
+    driven.add_argument("--size-stops", help="proportional size: 'value:size,value:size' "
+                                             "(at least two, ascending)")
+    driven.add_argument("--no-classification", action="store_true",
+                        help="drop data-driven colouring and go back to a single symbol")
+
+    three_d = parser.add_argument_group("3D")
+    three_d.add_argument("--extrude", action="store_true", default=None,
+                         help="extrude by a numeric field (polygons) or draw points as bars")
+    three_d.add_argument("--no-extrude", action="store_true", help="turn 3D off")
+    three_d.add_argument("--extrude-field", help="numeric property giving the height")
+    three_d.add_argument("--extrude-scale", type=float, help="multiply the height by this")
+    three_d.add_argument("--extrude-base", help="base height: a number, or a property name")
+    three_d.add_argument("--extrude-color", help="override the extrusion colour")
+    three_d.add_argument("--extrude-opacity", type=float, help="extrusion opacity, 0-1")
+    three_d.add_argument("--extrude-radius", type=float,
+                         help="POINT bar footprint radius in metres (default: derived from the "
+                              "layer's own extent, because a fixed one is invisible on a world map)")
+
+    if raster:
+        rast = parser.add_argument_group("raster")
+        rast.add_argument("--colormap", help="TiTiler colormap, e.g. viridis (see `layers colormaps`)")
+        rast.add_argument("--rescale", help="stretch as 'min,max' (see `layers stats` for a suggestion)")
+        rast.add_argument("--algorithm", help="e.g. hillshade (single-band)")
+        rast.add_argument("--zfactor", type=float, help="hillshade vertical exaggeration")
+        rast.add_argument("--bidx", help="band selection: '1' or '3,2,1' for an RGB composite")
+
+    parser.add_argument("--style-json",
+                        help="a JSON object (or @file.json) merged in last — the escape hatch for "
+                             "anything these flags do not cover")
+
+
+def style_from_args(args, client=None, layer_ref: Optional[Any] = None,
+                    base: Optional[Dict[str, Any]] = None, out=None) -> Dict[str, Any]:
+    """Turn the parsed styling flags into a style dict, classifying against the layer if asked."""
+    style = dict(base or {})
+
+    if getattr(args, "classify", None):
+        if not getattr(args, "color_field", None):
+            raise ValidationError(400, "--classify needs --color-field.")
+        if client is None or layer_ref is None:  # pragma: no cover - guarded by the callers
+            raise ValidationError(400, "Classification needs a layer to read.")
+        from ... import styles as styles_mod
+        style, stats = styles_mod.classify(
+            client, layer_ref, args.color_field, mode=getattr(args, "color_mode", None),
+            classes=getattr(args, "classes", None) or 5, method=args.classify,
+            ramp=getattr(args, "ramp", None) or "viridis",
+            reverse=bool(getattr(args, "reverse_ramp", False)), base=style)
+        if out is not None:
+            count = len(style.get("classes") or style.get("categories") or [])
+            out.info("Classified {0} on {1}: {2} {3} from {4} values.".format(
+                args.color_field, args.classify, count,
+                "classes" if style.get("color_mode") == "graduated" else "categories",
+                (stats or {}).get("count") or (stats or {}).get("total") or "the"))
+
+    kwargs = {}  # type: Dict[str, Any]
+    for name in ("color", "fill_opacity", "outline_color", "outline_width", "line_width",
+                 "radius", "marker", "line_type", "colormap", "rescale", "algorithm", "zfactor",
+                 "color_field", "color_mode", "size_field", "other_color", "size_stops",
+                 "extrude_field", "extrude_scale", "extrude_base", "extrude_color",
+                 "extrude_opacity", "extrude_radius"):
+        kwargs[name] = getattr(args, name, None)
+    if getattr(args, "bidx", None):
+        kwargs["bidx"] = [int(b) for b in str(args.bidx).replace(" ", "").split(",") if b]
+    if getattr(args, "extrude", None):
+        kwargs["extrude"] = True
+    if getattr(args, "no_extrude", False):
+        kwargs["extrude"] = False
+    if getattr(args, "class_breaks", None):
+        kwargs["classes"] = parse_classes(args.class_breaks)
+    if getattr(args, "categories", None):
+        kwargs["categories"] = parse_categories(args.categories)
+    if getattr(args, "no_classification", False):
+        kwargs["clear_classification"] = True
+
+    style = build_style(style, **kwargs)
+
+    extra = getattr(args, "style_json", None)
+    if extra:
+        style.update(read_json_arg(extra, "--style-json"))
+    return style
+
+
+def read_json_arg(value: str, label: str) -> Dict[str, Any]:
+    """A JSON object given inline, or `@path` to read it from a file (or `@-` for stdin).
+
+    `utf-8-sig` on the file: PowerShell's `>` writes UTF-16 or a BOM, which is how the reference
+    script's `portal-set` used to fail on Windows with an unreadable JSON error.
+    """
+    text = value
+    if value.startswith("@"):
+        path = value[1:]
+        if path == "-":
+            text = sys.stdin.read()
+        else:
+            with open(path, "r", encoding="utf-8-sig") as fh:
+                text = fh.read()
+    try:
+        data = json.loads(text)
+    except ValueError as exc:
+        raise ValidationError(400, "{0} is not valid JSON: {1}".format(label, exc))
+    if not isinstance(data, dict):
+        raise ValidationError(400, "{0} must be a JSON object.".format(label))
+    return data
+
+
+def read_text_arg(value: str) -> str:
+    """Text, or `@file` to read it from disk (Markdown for an About page, typically)."""
+    if value.startswith("@"):
+        path = value[1:]
+        if path == "-":
+            return sys.stdin.read()
+        with open(path, "r", encoding="utf-8-sig") as fh:
+            return fh.read()
+    return value
+
+
+def write_json_file(path: str, payload: Any) -> None:
+    """Write JSON as UTF-8 ourselves rather than letting the shell redirect it.
+
+    PowerShell's `>` writes UTF-16 with a BOM, which then cannot be read back — the reference CLI
+    grew an explicit output-file argument for exactly this reason, and so does this one.
+    """
+    directory = os.path.dirname(os.path.abspath(path))
+    if directory and not os.path.isdir(directory):
+        os.makedirs(directory, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(payload, fh, indent=2, ensure_ascii=False, default=str)
+        fh.write("\n")
+
+
+def confirm(out, question: str, assume_yes: bool = False, expect: Optional[str] = None) -> bool:
+    """Ask before something irreversible. `--yes` skips it; a non-interactive shell refuses.
+
+    Refusing rather than assuming yes is deliberate: a script piping into this has not consented to
+    a delete, and `--yes` is one character to add when it has.
+    """
+    if assume_yes:
+        return True
+    if not sys.stdin.isatty():
+        out.error("Refusing to {0} without --yes when not attached to a terminal.".format(question))
+        return False
+    if expect:
+        answer = input("{0}\nType {1!r} to confirm: ".format(question, expect)).strip()
+        return answer == expect
+    answer = input("{0} [y/N] ".format(question)).strip().lower()
+    return answer in ("y", "yes")
+
+
+def layer_ref_arg(parser, name: str = "layer", help_text: Optional[str] = None) -> None:
+    parser.add_argument(name, help=help_text or
+                        "layer id, uid, or name (a unique part of the name is enough)")
+    parser.add_argument("--type", dest="layer_type", choices=["vector", "raster"],
+                        help="disambiguate when a vector and a raster share a name")
+
+
+def resolve_layer(ctx, args, ref_attr: str = "layer", public_ok: bool = False) -> Dict[str, Any]:
+    """Find the layer a command was pointed at, by id, uid or name.
+
+    `public_ok` marks a command that works on public data alone (downloads, links to shared
+    artifacts). With no credential those resolve through the instance's PUBLIC INDEX instead of the
+    authenticated layer list, so `geodeploy --url … layers download roads` works for someone who
+    has no account — which is the whole point of a public layer.
+    """
+    ref = getattr(args, ref_attr)
+    kind = getattr(args, "layer_type", None)
+    info = ctx.resolved
+    if public_ok and not (info.token or info.jwt):
+        return ctx.client(auth_required=False).layers.resolve_public(ref, kind)
+    return ctx.client().layers.resolve(ref, kind)
+
+
+def parse_fields(value: Optional[str]) -> Optional[List[str]]:
+    if value is None:
+        return None
+    return [f.strip() for f in value.split(",") if f.strip()]