"""Scribe-plugin support endpoints. Consumed by the Scribe Claude Code plugin (not the web UI). `GET /api/plugin/ context` is curled by the plugin's SessionStart hook to push the operator's always-on rules + active-project context into the session — Scribe's own push channel. Auth is the standard `@login_required` path, which accepts a `Bearer fmcp_` API key (a read-scoped key suffices for this GET). """ from __future__ import annotations from quart import Blueprint, g, jsonify, request from scribe.auth import admin_required, get_current_user_id, login_required from scribe.config import Config from scribe.services import plugin_context as plugin_ctx_svc from scribe.services import repo_bindings as repo_bindings_svc from scribe.services.settings import get_admin_setting, set_setting plugin_bp = Blueprint("plugin", __name__, url_prefix="/api/plugin") # Setting key for the git URL of the marketplace that serves this plugin (the # Scribe app's own repo). Instance-global (stored on an admin account) so every # user's Settings page shows the real, copyable install command. _MARKETPLACE_KEY = "plugin_marketplace_url" def _int_list(raw: str | None) -> list[int]: """A comma-separated id list from the query string; non-ints dropped.""" return [int(p) for p in (raw or "").split(",") if p.strip().isdigit()] async def _project_scope() -> tuple[int, str, str]: """(project_id, repo, unbound_repo) from the request's `project_id` / `repo` query args — the one resolution every plugin endpoint shares. An explicit project_id wins; otherwise the repo remote is resolved through the caller's bindings, and a remote nobody bound comes back as `unbound_repo` (normalised) so /context can say "bind this repo". """ try: project_id = int(request.args.get("project_id", 0) or 0) except (TypeError, ValueError): project_id = 0 repo = (request.args.get("repo") or "").strip() unbound_repo = "" if repo and not project_id: resolved = await repo_bindings_svc.resolve_project(g.user.id, repo) if resolved: project_id = resolved else: unbound_repo = repo_bindings_svc.normalize_repo_key(repo) return project_id, repo, unbound_repo @plugin_bp.get("/context") @login_required async def session_context(): """Return SessionStart context (always-on rules + active project). Query: repo (optional str) — the working repo's git remote. The server resolves it to the bound project (see services/repo_bindings); an unbound repo yields a "bind this repo" hint instead. This is how the active project is determined — the plugin never pins a project id. project_id (optional int) — explicit override, mainly for manual/ad-hoc curl testing; takes precedence over `repo` when set. """ project_id, _repo, unbound_repo = await _project_scope() result = await plugin_ctx_svc.build_session_context( g.user.id, project_id, unbound_repo=unbound_repo ) return jsonify(result) @plugin_bp.get("/retrieve") @login_required async def autoinject_retrieve(): """Title-first knowledge auto-inject for the plugin's UserPromptSubmit hook. Given the user's prompt (`q`), returns a compact awareness hint — note titles + scores only, never bodies — for the top hits that clear the per-user gates (see services.plugin_context.build_autoinject_hint). Returns empty context (most of the time) when disabled or nothing is relevant. Query: q (str) — the user's prompt to retrieve against. repo (optional) — working repo remote; resolved to the bound project to scope the search (mirrors /context). Unbound or absent → searches all the user's notes. project_id (opt) — explicit project scope override (ad-hoc/testing). exclude_ids (opt) — comma-separated note ids already injected this session; skipped so each note injects at most once. """ q = (request.args.get("q") or "").strip() project_id, _repo, _unbound = await _project_scope() exclude_ids = _int_list(request.args.get("exclude_ids")) result = await plugin_ctx_svc.build_autoinject_hint( g.user.id, q, project_id=project_id, exclude_ids=exclude_ids ) return jsonify(result) @plugin_bp.get("/prior-art") @login_required async def write_path_prior_art(): """Prior-art hint for the plugin's PreToolUse hook on Write/Edit. Answers "what is already recorded for the file about to be written?" — by place (a snippet at this path or in its directory) and by meaning (snippets resembling the code about to be written). Titles only, gated, and empty most of the time. See services.plugin_context.build_write_path_hint. Query: path (str) — the target file, REPO-RELATIVE, matching the convention snippet locations are recorded in. An absolute path simply won't match anything. code (optional) — the code about to be written; the semantic query. Omit it and only the location arm runs. repo (optional) — working repo remote; resolved to the bound project to scope the search, exactly as /retrieve does. It is NOT used as the location `repo` filter — see the service docstring for why those two differ. project_id (opt) — explicit project scope override (ad-hoc/testing). exclude_ids (opt) — comma-separated REUSE-class ids already surfaced this session. exclude_sync_ids (opt) — comma-separated SYNC-class ids (snippets recorded AT the edited file, #2708) already surfaced. A separate channel on purpose: a reuse hint shown early must not suppress the record-sync nudge when the recorded file is edited later. shapes (opt) — comma-separated `kind:name` definitions the hook found in (or enclosing) the payload, kind being css|sym. The shape ledger's write-path feed (#2791): when the session recently PULLED a snippet this payload references or resembles, these land as instance rows (classified_by=hook). Honoured only for a caller allowed to write — a read-scoped key still gets the hint, and never changes accounting on a GET. """ path = (request.args.get("path") or "").strip() code = request.args.get("code") or "" project_id, repo, _unbound = await _project_scope() exclude_ids = _int_list(request.args.get("exclude_ids")) exclude_sync_ids = _int_list(request.args.get("exclude_sync_ids")) shapes = _parse_shapes(request.args.get("shapes") or "") api_key = getattr(g, "api_key", None) may_stamp = api_key is None or getattr(api_key, "scope", "") == "write" result = await plugin_ctx_svc.build_write_path_hint( g.user.id, path, code=code, project_id=project_id, exclude_ids=exclude_ids, exclude_sync_ids=exclude_sync_ids, stamp_shapes=shapes if may_stamp else None, repo_key=repo_bindings_svc.normalize_repo_key(repo) if repo else "", ) return jsonify(result) # The hook names at most a dozen definitions per write; anything past that is # a generated file, not a shape being instantiated. _SHAPES_CAP = 12 def _parse_shapes(raw: str) -> list[tuple[str, str]]: """`css:btn-primary,sym:onTrash` → [("css", "btn-primary"), ("sym", "onTrash")]. Unknown kinds and empty names are dropped, duplicates collapse, and the list is capped — the hook's own cap, re-applied so the contract holds for any caller.""" out: list[tuple[str, str]] = [] for part in raw.split(","): kind, _sep, name = part.strip().partition(":") kind, name = kind.strip(), name.strip() if kind in ("css", "sym") and name and (kind, name) not in out: out.append((kind, name)) if len(out) >= _SHAPES_CAP: break return out @plugin_bp.get("/processes") @login_required async def process_manifest(): """Stored Processes as skill-stub specs for the plugin's sync script. The plugin's `scribe_sync_processes.sh` (run at SessionStart and via the `/scribe:sync` command) curls this and writes one auto-surfacing local skill per Process into ~/.claude/skills/. See services/plugin_context. build_process_manifest. A read-scoped API key suffices. """ result = await plugin_ctx_svc.build_process_manifest(g.user.id) return jsonify(result) @plugin_bp.get("/marketplace-url") @login_required async def get_marketplace_url(): """The plugin marketplace git URL, readable by any logged-in user so their Settings page can show a copyable install command. Falls back to the config default (this deployment's own repo) when no admin override is set.""" url = await get_admin_setting(_MARKETPLACE_KEY, default=Config.PLUGIN_MARKETPLACE_URL) return jsonify({"marketplace_url": url}) @plugin_bp.put("/marketplace-url") @admin_required async def set_marketplace_url(): """Admin-set the marketplace git URL (e.g. this app's own repo).""" data = await request.get_json() or {} url = (data.get("marketplace_url") or "").strip() if url: scheme = url.split("://")[0].lower() if "://" in url else "" if scheme not in ("http", "https"): return jsonify({"error": "Marketplace URL must use http or https"}), 400 await set_setting(get_current_user_id(), _MARKETPLACE_KEY, url) return jsonify({"status": "ok"})