ghost-api-cli 0.2.0__py3-none-any.whl

ghost_api/project.py

@@ -0,0 +1,186 @@
+"""A Ghost API project: a `ghost-api.toml` file and the folder it sits in.
+
+`ghost-api init` writes one. Commands run anywhere inside that folder (or below it) then use
+the project's database, output folder and defaults, wherever they are started from:
+
+    [project]
+    database = ".ghost-api/ghost_api.db"   # relative to this file
+    output = "output"
+
+    [defaults]                              # any command option, by its name
+    lang = "typescript"
+    rate_limit = 0.5
+
+Per-site rules (a team can write down what is acceptable on each site):
+
+    [project]
+    require_terms = true            # every site needs terms_ok = true before the first run
+
+    [sites."example.com"]
+    terms_ok = true                 # someone checked the site's terms allow this
+    deny_paths = ["/admin", "/api/private"]   # never requested, by the browser or directly
+    max_direct_calls = 30           # endpoint tests and fetches per run
+    agent = false                   # no AI explores this site (Ghost API's or an assistant)
+
+Without a project file, Ghost API behaves as before: `ghost_api.db` and `output/` in the
+current folder. `GHOST_API_DB` and command-line options always win.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+PROJECT_FILE = "ghost-api.toml"
+STATE_FOLDER = ".ghost-api"
+
+
+class ProjectError(Exception):
+    """The project file can't be read."""
+
+
+@dataclass(frozen=True)
+class SitePolicy:
+    terms_ok: bool = False
+    deny_paths: tuple[str, ...] = ()
+    max_direct_calls: int | None = None
+    agent: bool = True
+
+    def denies(self, path: str) -> bool:
+        return any(path == p or path.startswith(p.rstrip("/") + "/") for p in self.deny_paths)
+
+
+@dataclass(frozen=True)
+class Project:
+    root: Path
+    database: Path
+    output: Path
+    defaults: dict[str, Any] = field(default_factory=dict)
+    sites: dict[str, SitePolicy] = field(default_factory=dict)
+    require_terms: bool = False
+
+    def policy(self, site: str) -> SitePolicy:
+        """The rules for a site: its own entry, else its host's, else none."""
+        return self.sites.get(site) or self.sites.get(site.split("/")[0]) or SitePolicy()
+
+    @property
+    def file(self) -> Path:
+        return self.root / PROJECT_FILE
+
+
+def find_project(start: Path | None = None) -> Project | None:
+    """The nearest `ghost-api.toml` in `start` or a folder above it."""
+    if os.getenv("GHOST_API_NO_PROJECT"):
+        return None
+    here = (start or Path.cwd()).resolve()
+    for folder in (here, *here.parents):
+        candidate = folder / PROJECT_FILE
+        if candidate.is_file():
+            return load_project(candidate)
+    return None
+
+
+def load_project(path: Path) -> Project:
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ProjectError(f"{path} can't be read: {exc}") from exc
+    root = path.parent
+    settings = data.get("project", {})
+    defaults = data.get("defaults", {})
+    if not isinstance(settings, dict) or not isinstance(defaults, dict):
+        raise ProjectError(f"{path}: [project] and [defaults] must be tables")
+    sites = data.get("sites", {})
+    if not isinstance(sites, dict):
+        raise ProjectError(f"{path}: [sites] must be a table of sites")
+    return Project(
+        root=root,
+        database=root / str(settings.get("database", f"{STATE_FOLDER}/ghost_api.db")),
+        output=root / str(settings.get("output", "output")),
+        defaults=dict(defaults),
+        sites={name: _policy(path, name, rules) for name, rules in sites.items()},
+        require_terms=bool(settings.get("require_terms", False)),
+    )
+
+
+def _policy(path: Path, name: str, rules: Any) -> SitePolicy:
+    if not isinstance(rules, dict):
+        raise ProjectError(f'{path}: [sites."{name}"] must be a table')
+    deny = rules.get("deny_paths", [])
+    if not isinstance(deny, list) or not all(isinstance(p, str) and p.startswith("/")
+                                             for p in deny):  # fmt: skip
+        raise ProjectError(f'{path}: deny_paths for "{name}" must be paths like "/admin"')
+    limit = rules.get("max_direct_calls")
+    return SitePolicy(
+        terms_ok=bool(rules.get("terms_ok", False)),
+        deny_paths=tuple(deny),
+        max_direct_calls=int(limit) if limit is not None else None,
+        agent=bool(rules.get("agent", True)),
+    )
+
+
+def site_policy(site: str) -> tuple[SitePolicy, bool]:
+    """(the site's rules, whether the project requires terms_ok), from ghost-api.toml."""
+    project = find_project()
+    if project is None:
+        return SitePolicy(), False
+    return project.policy(site), project.require_terms
+
+
+TEMPLATE = """\
+# Ghost API project settings. Commands run in this folder (or below it) use them.
+# Docs: https://github.com/Danielraj5605/Ghost-api#project-settings
+
+[project]
+database = ".ghost-api/ghost_api.db"  # runs, captured traffic, endpoints (keep private)
+output = "output"                     # reports, clients, downloads
+
+[defaults]
+# Any command option, by its name (dashes or underscores). Command-line options win.
+lang = "{lang}"
+rate_limit = 1.0        # requests per second Ghost API sends to a site
+# max_steps = 40        # agent actions per run
+# max_llm_calls = 50
+"""
+
+GITIGNORE_LINES = (".env", ".ghost-api/", "output/")
+
+
+def write_project(root: Path, lang: str = "python") -> Path:
+    path = root / PROJECT_FILE
+    path.write_text(TEMPLATE.format(lang=lang), encoding="utf-8")
+    (root / STATE_FOLDER).mkdir(exist_ok=True)
+    return path
+
+
+def ensure_gitignore(root: Path) -> list[str]:
+    """Keep keys and collected data out of git. Returns the lines that were added."""
+    path = root / ".gitignore"
+    existing = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    missing = [line for line in GITIGNORE_LINES if line not in existing]
+    if missing:
+        text = "\n".join(existing).rstrip()
+        block = "\n".join(["# Ghost API: keys and collected data", *missing])
+        path.write_text(f"{text}\n\n{block}\n" if text else f"{block}\n", encoding="utf-8")
+    return missing
+
+
+def default_map(project: Project, command: Any) -> dict[str, Any]:
+    """Click `default_map` for every (sub)command: the project's output folder and
+    [defaults] for each command that has an option of that name."""
+    values = {k.replace("-", "_"): v for k, v in project.defaults.items()}
+    values.setdefault("out", str(project.output))
+
+    def build(cmd: Any) -> dict[str, Any]:
+        names = {p.name for p in getattr(cmd, "params", [])}
+        result: dict[str, Any] = {k: v for k, v in values.items() if k in names}
+        for name, sub in getattr(cmd, "commands", {}).items():
+            nested = build(sub)
+            if nested:
+                result[name] = nested
+        return result
+
+    return build(command)

ghost_api/runtime.py

@@ -0,0 +1,397 @@
+"""Run a site's endpoints by name, from stored data: the base for fetch, watch and serve.
+
+A `SiteRuntime` needs no generated code. Each operation replays the endpoint's latest
+stored sample with the caller's parameters, through the same `Replayer` the prober uses
+(robots.txt, rate limit, read-only rule), follows pages, and turns replies into rows.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field, replace
+from typing import Any
+from urllib.parse import parse_qsl, urlsplit
+
+from ghost_api.analysis.analyzer import endpoint_keys
+from ghost_api.analysis.detectors import (
+    find_items,
+    guess_pagination,
+    item_fingerprints,
+    next_cursor,
+)
+from ghost_api.analysis.models import Endpoint
+from ghost_api.audit import AuditLog
+from ghost_api.browser import auth_state
+from ghost_api.capture import personal
+from ghost_api.capture.filters import REDACTED, is_sensitive_name
+from ghost_api.capture.models import CapturedRequest, RawRequest
+from ghost_api.generator.naming import NamingPlan, apply_plan
+from ghost_api.memory.knowledge import rebuild_raw
+from ghost_api.memory.store import Store
+from ghost_api.net import DenyPaths, RateLimiter, RobotsPolicy, fetch_robots
+from ghost_api.probe.replay import Replayer, ReplayResult, apply_params, is_replayable
+from ghost_api.project import site_policy
+from ghost_api.site import site_host
+
+MAX_PAGES = 50
+MAX_ROWS = 10_000
+
+
+class OperationError(Exception):
+    """A problem the user can act on (unknown operation, needs a fresh sample...)."""
+
+
+@dataclass
+class Input:
+    name: str
+    location: str  # "path", "query" or "body"
+    type: str
+    example: str
+    required: bool
+
+
+@dataclass
+class Operation:
+    name: str
+    summary: str
+    endpoint: Endpoint
+    inputs: list[Input]
+    allowed: bool  # the user checked it only reads (a POST search, `generate --allow`)
+    pagination: dict[str, Any] | None = None
+
+    @property
+    def label(self) -> str:
+        return self.endpoint.label
+
+
+@dataclass
+class Page:
+    number: int
+    result: ReplayResult
+    records: list[Any] = field(default_factory=list)
+
+
+class SiteRuntime:
+    def __init__(
+        self,
+        store: Store,
+        site: str,
+        replayer: Replayer | None = None,
+        rate: float = 1.0,
+        include_sensitive: bool = False,
+    ) -> None:
+        """`include_sensitive`: return personal data (emails, phones, PAN...) as the site
+        sends it. Only for auditing your own site; by default such values are hidden."""
+        self.site = site
+        self.include_sensitive = include_sensitive
+        run_id = store.latest_endpoint_run(site)
+        if run_id is None:
+            raise OperationError(f"Nothing stored for {site}. Run `ghost-api run` first.")
+        self.endpoints = store.current_endpoints(site)
+        self.allowed = store.allowed_endpoints(site)
+        plan = load_plan(store.load_naming_plan(site))
+        _, self.names = apply_plan(plan, self.endpoints, site)
+        stored = store.requests_for_domain(site)
+        self.samples: dict[str, list[CapturedRequest]] = {}
+        for key, req in zip(endpoint_keys(stored), stored, strict=False):
+            self.samples.setdefault(key, []).append(req)
+        policy, _ = site_policy(site)
+        self.replayer = replayer or Replayer(
+            site_host(site),
+            RateLimiter(rate),
+            max_requests=policy.max_direct_calls or 10**6,
+            robots_fetcher=_with_rules(policy.deny_paths, site_host(site)),
+        )
+        if replayer is None:  # fetch, watch, serve, MCP: audited like a run's direct calls
+            log = AuditLog(store.path, site)
+            self.replayer.on_sent = lambda method, url, status, decision: log.record(
+                "direct", method, url, status, decision
+            )
+        try:  # ghost-api login: its cookies are added to direct calls
+            found = auth_state.load(store.path, site)
+        except auth_state.LoginError:
+            found = None
+        self.login = found[0] if found else None
+
+    def close(self) -> None:
+        self.replayer.close()
+
+    def __enter__(self) -> SiteRuntime:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # --- what can be called ---
+
+    def operations(self) -> list[Operation]:
+        ops = []
+        for ep in self.endpoints:
+            allowed = ep.key in self.allowed
+            if not is_callable(ep, allowed):
+                continue  # may change data, or can't be called outside the browser
+            names = self.names[ep.key]
+            ops.append(
+                Operation(
+                    names.method_name,
+                    names.summary,
+                    ep,
+                    inputs_for(ep, self.samples.get(ep.key, [])),
+                    allowed,
+                    ep.pagination or self._guess_pagination(ep),
+                )
+            )
+        return ops
+
+    def operation(self, name: str) -> Operation:
+        ops = self.operations()
+        for op in ops:
+            if name in (op.name, op.endpoint.key, op.label):
+                return op
+        choices = ", ".join(o.name for o in ops) or "none"
+        raise OperationError(f"No operation {name!r} for {self.site}. Choose one of: {choices}")
+
+    # --- calling ---
+
+    def call(self, op: Operation, params: dict[str, str] | None = None) -> ReplayResult:
+        sample = self._sample(op)
+        values = self._coerce(op, sample, params or {})
+        request = apply_params(
+            sample, op.endpoint.path_template, {p.name for p in op.endpoint.path_params}, values
+        )
+        result = self.replayer.send(request, trusted_read=op.allowed)
+        if self.include_sensitive or result.body is None:
+            return result
+        body, hidden = personal.hide(result.body)
+        return replace(result, body=body, hidden=personal.summarize(hidden))
+
+    def iterate(
+        self,
+        op: Operation,
+        params: dict[str, str] | None = None,
+        max_pages: int = 5,
+        max_rows: int = 1000,
+    ) -> Iterator[Page]:
+        """Pages of records, following the endpoint's pagination; stops when a page is
+        empty, repeats what was seen, or a limit is reached."""
+        params = dict(params or {})
+        pag = op.pagination
+        if pag and pag["style"] != "cursor" and pag["param"] not in params:
+            params[pag["param"]] = self._first_position(op, pag)  # start at the beginning
+        seen: set[str] = set()
+        rows = 0
+        for number in range(1, min(max_pages, MAX_PAGES) + 1):
+            result = self.call(op, params)
+            records = records_of(result.body, is_single(op)) if result.ok else []
+            fresh = [k for k in item_fingerprints(records) if k not in seen]
+            if result.ok and records and not fresh:
+                return  # the "next page" repeated the last one: pagination ignored
+            if result.ok and not records and number > 1:
+                return  # ran past the last page
+            seen.update(fresh)
+            records = records[: max(0, min(max_rows, MAX_ROWS) - rows)]
+            rows += len(records)
+            yield Page(number, result, records)
+            if not result.ok or not records or not pag or rows >= min(max_rows, MAX_ROWS):
+                return
+            if _says_last_page(result.body):
+                return
+            nxt = _next_position(pag, params, result.body, len(records))
+            if nxt is None:
+                return
+            params[pag["param"]] = nxt
+
+    # --- helpers ---
+
+    def _sample(self, op: Operation) -> RawRequest:
+        for captured in reversed(self.samples.get(op.endpoint.key, [])):
+            raw = rebuild_raw(self._with_login(captured), op.endpoint.required_headers)
+            if raw is not None:
+                return raw
+        raise OperationError(
+            f"{op.label} needs a fresh key or session. Run `ghost-api refresh {self.site}` first."
+        )
+
+    def _with_login(self, captured: CapturedRequest) -> CapturedRequest:
+        """The stored sample's redacted cookie, filled in from the saved login (if any)."""
+        if self.login is None:
+            return captured
+        cookies = auth_state.cookie_header(self.login, captured.url)
+        headers = dict(captured.req_headers)
+        names = [k for k in headers if k.lower() == "cookie"]
+        if not cookies or (names and headers[names[0]] != REDACTED):
+            return captured
+        for name in names:
+            del headers[name]
+        headers["cookie"] = cookies
+        return replace(captured, req_headers=headers)
+
+    def _guess_pagination(self, ep: Endpoint) -> dict[str, Any] | None:
+        samples = self.samples.get(ep.key, [])
+        if not samples:
+            return None
+        last = samples[-1]
+        query = dict(parse_qsl(urlsplit(last.url).query, keep_blank_values=True))
+        guess = guess_pagination(query, _json_body([last]), _json(last.resp_body))
+        if guess is None or (guess.location == "query" and guess.param not in query):
+            return None  # only follow pages the request really has a parameter for
+        return {"style": guess.style, "param": guess.param, "location": guess.location,
+                "size_param": guess.size_param}  # fmt: skip
+
+    def _first_position(self, op: Operation, pag: dict[str, Any]) -> str:
+        """The first page (or offset 0): the smallest value seen, so 0-based APIs work."""
+        values = []
+        for req in self.samples.get(op.endpoint.key, []):
+            if pag["location"] == "query":
+                value = dict(parse_qsl(urlsplit(req.url).query)).get(pag["param"])
+            else:
+                value = (_json_body([req]) or {}).get(pag["param"])
+            try:
+                values.append(int(float(str(value))))
+            except ValueError:
+                continue
+        default = 1 if pag["style"] == "page" else 0
+        return str(min(values) if values else default)
+
+    def _coerce(self, op: Operation, sample: RawRequest, params: dict[str, str]) -> dict[str, str]:
+        """Friendlier inputs: 'football' or 'football,cricket' for a list body field."""
+        body = _json(sample.body) if sample.body else None
+        out = {}
+        for name, value in params.items():
+            current = body.get(name) if isinstance(body, dict) else None
+            if isinstance(current, list) and not str(value).lstrip().startswith("["):
+                value = json.dumps([v.strip() for v in str(value).split(",") if v.strip()])
+            out[name] = str(value)
+        return out
+
+
+def is_callable(ep: Endpoint, allowed: bool) -> bool:
+    """Ghost API calls an endpoint only if it reads data: by its URL, or because the user
+    checked it (`allowed`), and only if it worked outside the browser."""
+    if allowed:
+        return True
+    probe = RawRequest(ep.method, f"https://{ep.host}{ep.path_template}", {}, None)
+    return ep.replayable is not False and is_replayable(probe)
+
+
+def inputs_for(ep: Endpoint, samples: list[CapturedRequest]) -> list[Input]:
+    """What a caller can set: path and query parameters, and top-level JSON body fields."""
+    inputs = [Input(p.name, "path", p.type, (p.examples or [""])[0], True) for p in ep.path_params]
+    inputs += [
+        Input(p.name, "query", p.type, (p.examples or [""])[0], p.kind == "required")
+        for p in ep.query_params
+        if not p.sensitive
+    ]
+    body = _json_body(samples)
+    for key, value in (body or {}).items():
+        if is_sensitive_name(key):
+            continue
+        kind = "list" if isinstance(value, list) else type(value).__name__
+        example = json.dumps(value) if isinstance(value, list | dict) else str(value)
+        inputs.append(Input(key, "body", kind, example, False))
+    return inputs
+
+
+_WRAPPERS = ("data", "result", "item", "record", "payload")
+
+
+def records_of(body: Any, single: bool = False) -> list[Any]:
+    """The rows in a reply: its main list, or the reply itself as one row.
+
+    `single`: the endpoint returns one thing (its path ends in an ID, like
+    /venue/details/{id}), so lists inside it (reviews, photos) are not the rows."""
+    if single and isinstance(body, dict):
+        inner = next((body[k] for k in _WRAPPERS if isinstance(body.get(k), dict)), None)
+        return [inner if inner is not None else body]
+    items = find_items(body)
+    if items is not None:
+        return items
+    return [body] if isinstance(body, dict) else []
+
+
+def is_single(op: Operation) -> bool:
+    """One record per reply: /books/{id}, not /books or /books/{id}/reviews."""
+    return op.pagination is None and op.endpoint.path_template.rstrip("/").endswith("}")
+
+
+def flatten(record: Any, prefix: str = "") -> dict[str, Any]:
+    """{'venue': {'name': 'X'}, 'tags': ['a', 'b']} -> {'venue.name': 'X', 'tags': 'a; b'}."""
+    if not isinstance(record, dict):
+        return {prefix or "value": record}
+    out: dict[str, Any] = {}
+    for key, value in record.items():
+        name = f"{prefix}.{key}" if prefix else str(key)
+        if isinstance(value, dict):
+            out.update(flatten(value, name))
+        elif isinstance(value, list):
+            scalars = all(not isinstance(v, dict | list) for v in value)
+            out[name] = "; ".join(str(v) for v in value) if scalars else json.dumps(value)
+        else:
+            out[name] = value
+    return out
+
+
+def _next_position(
+    pag: dict[str, Any], params: dict[str, str], body: Any, count: int
+) -> str | None:
+    """The value to send for the next page, counted from what was just sent."""
+    if pag["style"] == "cursor":
+        return next_cursor(body)
+    try:
+        position = int(float(params[pag["param"]]))
+    except (KeyError, ValueError):
+        return None
+    if pag["style"] == "page":
+        return str(position + 1)
+    return str(position + count)  # offset: skip what this page returned
+
+
+# Reply fields that say whether another page exists.
+_MORE_FIELDS = ("has_more", "hasMore", "has_next", "hasNext", "more", "has_next_page")
+
+
+def _says_last_page(body: Any) -> bool:
+    if not isinstance(body, dict):
+        return False
+    for obj in (body, body.get("meta"), body.get("pagination"), body.get("data")):
+        if isinstance(obj, dict):
+            for key in _MORE_FIELDS:
+                if obj.get(key) is False:
+                    return True
+    return False
+
+
+def _json(text: str | None) -> Any:
+    try:
+        return json.loads(text or "")
+    except ValueError:
+        return None
+
+
+def _json_body(samples: list[CapturedRequest]) -> dict[str, Any] | None:
+    for req in reversed(samples):
+        data = _json(req.req_body)
+        if isinstance(data, dict):
+            return data
+    return None
+
+
+def load_plan(stored: str | None) -> NamingPlan | None:
+    if not stored:
+        return None
+    try:
+        return NamingPlan.model_validate_json(stored)
+    except ValueError:
+        return None
+
+
+def _with_rules(deny: tuple[str, ...], host: str) -> Callable[[str], RobotsPolicy]:
+    """robots.txt for direct calls, plus the project's denied paths on the site's host."""
+
+    def fetch(url: str) -> RobotsPolicy:
+        rules = fetch_robots(url)
+        same_host = (urlsplit(url).hostname or "").lower() == host.lower()
+        return DenyPaths(rules, deny) if deny and same_host else rules
+
+    return fetch

ghost_api/serve/__init__.py

@@ -0,0 +1,101 @@
+"""Use sites from other tools: a local REST API (`rest.py`) and an MCP server (`mcp.py`).
+
+Both serve the operations of `SiteRuntime`: read-only, rate-limited, robots.txt respected,
+personal data hidden. One runtime per site, used one call at a time, so a busy client
+can't make Ghost API hammer a site.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ghost_api.memory.store import Store
+from ghost_api.runtime import Operation, OperationError, SiteRuntime
+
+__all__ = [
+    "MAX_PAGES",
+    "ServedSite",
+    "coerce",
+    "load_sites",
+    "tool_name",
+]
+
+MAX_PAGES = 20
+_COMMON_LABELS = {"www", "com", "in", "org", "net", "io", "co"}
+
+
+@dataclass
+class ServedSite:
+    site: str
+    runtime: SiteRuntime
+    operations: list[Operation]
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def fetch(
+        self, op: Operation, params: dict[str, str], pages: int, max_rows: int
+    ) -> dict[str, Any]:
+        """All rows for these inputs (one call at a time per site)."""
+        records: list[Any] = []
+        hidden = 0
+        read = 0
+        error = ""
+        with self.lock:
+            for page in self.runtime.iterate(op, params, min(pages, MAX_PAGES), max_rows):
+                read += 1
+                if not page.result.ok:
+                    error = page.result.error or f"HTTP {page.result.status}"
+                    break
+                records += page.records
+                hidden += sum(int(h.get("count", 1)) for h in page.result.hidden)
+        return {
+            "site": self.site,
+            "operation": op.name,
+            "rows": len(records),
+            "pages": read,
+            "personal_values_hidden": hidden,
+            "error": error,
+            "data": records,
+        }
+
+
+def load_sites(db: Path, names: list[str] | None = None) -> dict[str, ServedSite]:
+    """The sites to serve: the ones named, or every stored site with something callable."""
+    with Store(db) as store:
+        sites = names or sorted({r.domain for r in store.list_runs()})
+        served = {}
+        for site in sites:
+            try:
+                rt = SiteRuntime(store, site)
+            except OperationError:
+                if names:
+                    raise
+                continue
+            ops = rt.operations()
+            if ops:
+                served[site] = ServedSite(site, rt, ops)
+            else:
+                rt.close()
+    return served
+
+
+def tool_name(site: str, op: Operation) -> str:
+    """'turftown.in/chennai' + get_nearby_venues -> 'turftown_chennai_get_nearby_venues'."""
+    host, _, section = site.partition("/")
+    labels = [p for p in host.lower().split(".") if p not in _COMMON_LABELS]
+    slug = "_".join([*labels[:2], section] if section else labels[:2]) or "site"
+    return re.sub(r"[^a-zA-Z0-9_-]", "_", f"{slug}_{op.name}")[:64]
+
+
+def coerce(value: Any) -> str:
+    """Inputs arrive as JSON values (MCP) or text (REST); runtime takes text."""
+    if isinstance(value, list | dict):
+        import json
+
+        return json.dumps(value)
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)