procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/agents/procesio/tests/test_workspace_scope.py

@@ -0,0 +1,97 @@
+"""Guard: the credential SCOPE (profile + workspace) reaches every inner
+`procesio` call.
+
+Regression. `verify` and `audit` used to forward only `--profile`, so any
+process outside the profile's default workspace failed with HTTP 400
+`{"statusCode": 501, "value": "User is not authorized for the requested
+resource."}` - and a user/password profile cannot carry a workspace of its own,
+so there was no workaround at all. The scope must be splatted into EVERY inner
+invoke, not just the first one: the gate fetches, validates, runs, and reads
+instance status, and each of those is a separately scoped call.
+"""
+from __future__ import annotations
+
+import argparse
+
+from agents.procesio import verifylib
+from agents.procesio.handlers import audit as audit_h
+from agents.procesio.handlers import verify as verify_h
+from agents.procesio.tests.conftest import action, flow
+
+WS = "3fd85e9d-121e-415b-877f-f488cd685ce3"
+START = action("Start")
+CONFIGURED = action("Add", params=[{"Value": "x", "Variable": []}],
+                    settings=[{"value": "x"}])
+STOP = action("Stop")
+
+
+class _Ctx:
+    def __init__(self, invoke):
+        self.invoke = invoke
+
+
+def _parse(add_args, argv):
+    p = argparse.ArgumentParser()
+    add_args(p)
+    return p.parse_args(argv)
+
+
+def _flags(call_args: list, flag: str):
+    """The value passed for `flag` in one recorded invoke, or None."""
+    return call_args[call_args.index(flag) + 1] if flag in call_args else None
+
+
+def test_scope_args_builds_both_flags():
+    assert verifylib.scope_args("account", WS) == [
+        "--profile", "account", "--workspace-id", WS]
+
+
+def test_scope_args_omits_what_was_not_given():
+    assert verifylib.scope_args(None, None) == []
+    assert verifylib.scope_args("account", None) == ["--profile", "account"]
+    assert verifylib.scope_args(None, WS) == ["--workspace-id", WS]
+
+
+def test_verify_forwards_workspace_to_every_inner_call(fake_invoke):
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    fake_invoke.set("run-process", {"result": {"id": "iid", "status": 50}})
+    fake_invoke.set("get-instance-status", {"result": {"status": 50, "actions": []}})
+
+    verifylib.verify_process(fake_invoke, "pid", profile="account",
+                             workspace_id=WS, run=True)
+
+    seen = {a for _, a, _ in fake_invoke.calls}
+    assert seen == {"get-process", "request", "run-process", "get-instance-status"}
+    for _tool, action_name, args in fake_invoke.calls:
+        assert _flags(args, "--workspace-id") == WS, f"{action_name} lost the workspace"
+        assert _flags(args, "--profile") == "account", f"{action_name} lost the profile"
+
+
+def test_verify_without_workspace_sends_no_flag(fake_invoke):
+    """Omitting it must stay a no-op, so the profile's own workspace still works."""
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    verifylib.verify_process(fake_invoke, "pid", profile="account")
+    assert all("--workspace-id" not in args for _t, _a, args in fake_invoke.calls)
+
+
+def test_verify_handler_threads_the_flag(fake_invoke):
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    args = _parse(verify_h._args,
+                  ["--process-id", "pid", "--profile", "account", "--workspace-id", WS])
+    verify_h._verify(_Ctx(fake_invoke), args)
+    assert _flags(fake_invoke.calls[0][2], "--workspace-id") == WS
+
+
+def test_audit_handler_threads_the_flag(fake_invoke):
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    args = _parse(audit_h._args,
+                  ["--process-id", "pid", "--profile", "account", "--workspace-id", WS])
+    report = audit_h._audit(_Ctx(fake_invoke), args)
+    assert report["process_id"] == "pid"
+    tool, action_name, call_args = fake_invoke.calls[0]
+    assert (tool, action_name) == ("procesio", "get-process")
+    assert _flags(call_args, "--workspace-id") == WS
+    assert _flags(call_args, "--profile") == "account"

procesio_cli/agents/procesio/verifylib.py

@@ -0,0 +1,222 @@
+"""The `verify` gate: run the automatable self-test steps against a live process.
+
+Turns the playbook checklist from prose into an executable gate. It drives the
+`procesio` tool (never the API directly) and is defensive: a tool error or an
+unexpected response shape downgrades a check to `skip` with the reason, so the
+gate reports the truth instead of crashing or lying. Manual steps it cannot run
+are returned in `manual_checks` so they cannot be silently skipped.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from typing import Any, Callable
+
+from agents._lib.toolrunner import ToolError
+from agents.procesio import audit, checklist
+
+
+def scope_args(profile: str | None, workspace_id: str | None = None) -> list[str]:
+    """The credential-scope flags that EVERY inner `procesio` call must forward.
+
+    Forwarding `--profile` alone is not enough: a session is bound to one default
+    workspace, so a resource living in any other workspace answers HTTP 400
+    `{"statusCode": 501, "value": "User is not authorized for the requested
+    resource."}` unless the `workspaceid` header is set per call, which is what
+    `--workspace-id` does. Only an api-key profile can carry a workspace of its
+    own, so for a user/password profile there is no fallback - the flag is the
+    only way to reach another workspace. Build the flags here and splat them into
+    every invoke, so a new inner call cannot forget one.
+    """
+    args: list[str] = []
+    if profile:
+        args += ["--profile", profile]
+    if workspace_id:
+        args += ["--workspace-id", workspace_id]
+    return args
+
+
+def _flow_from(data: dict) -> dict:
+    """Unwrap get-process. Live API and tests both nest the flow under result.flow
+    (camelCase live, but ci() is case-insensitive)."""
+    res = data.get("result") if isinstance(data, dict) else None
+    if isinstance(res, dict):
+        f = audit.ci(res, "flow")
+        return f if isinstance(f, dict) else res
+    return data if isinstance(data, dict) else {}
+
+
+def _check(cid: str, phase: str, status: str, detail: Any) -> dict:
+    return {"id": cid, "phase": phase, "status": status, "detail": detail}
+
+
+def _instance_ids(res: dict) -> tuple[str | None, Any]:
+    if not isinstance(res, dict):
+        return None, None
+    inst = audit.ci(res, "instance")
+    inst = inst if isinstance(inst, dict) else res
+    iid = audit.ci(inst, "id", "instanceId", "flowInstanceId") or \
+        audit.ci(res, "instanceId", "id")
+    status = audit.ci(inst, "status")
+    if status is None:
+        status = audit.ci(res, "status")
+    return (str(iid) if iid else None), status
+
+
+def _validation_messages(details: dict):
+    """PROCESIO's /api/Projects/validate returns HTTP 400 with a list of
+    {statusCode, value, target} when a process is invalid (the tool surfaces that
+    as an error envelope). Return that list (possibly empty = valid) for a real
+    validation response, or None when this is not one (e.g. a 500 / wrong shape)."""
+    if not isinstance(details, dict) or details.get("status") != 400:
+        return None
+    body = details.get("body")
+    inner = body.get("body") if isinstance(body, dict) else body
+    return inner if isinstance(inner, list) else None
+
+
+def _action_errors(status_res: dict) -> list[dict]:
+    inst = audit.ci(status_res, "instance")
+    inst = inst if isinstance(inst, dict) else status_res
+    actions = audit.ci(inst, "actions")
+    out = []
+    for a in actions or []:
+        if isinstance(a, dict) and audit.ci(a, "errorMessage"):
+            out.append({"action": audit.ci(a, "actionName", "name"),
+                        "errorMessage": audit.ci(a, "errorMessage")})
+    return out
+
+
+def verify_process(invoke: Callable, process_id: str, *, profile: str | None = None,
+                   workspace_id: str | None = None,
+                   run: bool = False, payload: str | None = None,
+                   timeout: int | None = None) -> dict:
+    checks: list[dict] = []
+    scope = scope_args(profile, workspace_id)
+
+    # 1. fetch -----------------------------------------------------------------
+    try:
+        flow = _flow_from(invoke("procesio", "get-process", "--id", process_id, *scope))
+    except ToolError as e:
+        return {"process_id": process_id, "verdict": "fail",
+                "checks": [_check("fetch", "validate", "fail",
+                                  {"code": e.code, "message": e.message})],
+                "manual_checks": checklist.manual_steps()}
+    title = audit.ci(flow, "title", "name")
+    checks.append(_check("fetch", "validate", "pass", {"title": title}))
+
+    # 2. validate --------------------------------------------------------------
+    # The flow JSON is often large; send it via a temp file (--body-file), never as an
+    # inline --body argv. A big process overflows the OS command-line limit (Windows
+    # WinError 206 "filename or extension is too long" / POSIX E2BIG), which crashed the
+    # gate on exactly the real processes it must check.
+    bf = tempfile.NamedTemporaryFile("w", suffix=".json", delete=False, encoding="utf-8")
+    try:
+        json.dump(flow, bf, ensure_ascii=False)
+        bf.close()
+        vd = invoke("procesio", "request", "--method", "POST",
+                    "--path", "/api/Projects/validate",
+                    "--body-file", bf.name, *scope)
+        res = vd.get("result")
+        errors = None
+        if isinstance(res, dict):
+            errors = audit.ci(res, "validationErrors", "errors", "messages")
+            valid = audit.ci(res, "isValid", "valid")
+        else:
+            valid = None
+        if errors:
+            checks.append(_check("validate-process", "validate", "warn",
+                                 {"errors": errors}))
+        elif valid is False:
+            checks.append(_check("validate-process", "validate", "warn",
+                                 {"valid": False, "raw": res}))
+        else:
+            checks.append(_check("validate-process", "validate", "pass",
+                                 {"valid": True if valid else "no errors reported"}))
+    except ToolError as e:
+        msgs = _validation_messages(e.details)
+        if msgs is not None:
+            checks.append(_check("validate-process", "validate",
+                                 "warn" if msgs else "pass",
+                                 {"errors": msgs} if msgs else {"valid": True}))
+        else:
+            checks.append(_check("validate-process", "validate", "skip",
+                                 {"reason": "validate endpoint not callable",
+                                  "code": e.code, "message": e.message,
+                                  "detail": e.details}))
+    finally:
+        try:
+            os.unlink(bf.name)
+        except OSError:
+            pass
+
+    # 3. config parity (gating correctness audit) ------------------------------
+    cf = audit.correctness_findings(flow)
+    blocking = [f for f in cf if f["severity"] in ("warn", "fail")]
+    if blocking:
+        # a correctness finding marked `fail` (e.g. a Call-API node masquerading as a
+        # Data Store/cache op) is a hard defect, not a smell - fail the gate outright.
+        hard = any(f["severity"] == "fail" for f in blocking)
+        checks.append(_check("config-parity-audit", "validate",
+                             "fail" if hard else "warn",
+                             {"findings": blocking}))
+    else:
+        checks.append(_check("config-parity-audit", "validate", "pass",
+                             {"findings": cf}))
+
+    # 4. run + instance status -------------------------------------------------
+    if run:
+        try:
+            args = ["run-process", "--id", process_id, "--synchronous"]
+            if payload:
+                args += ["--payload", payload]
+            if timeout:
+                args += ["--timeout", str(timeout)]
+            rd = invoke("procesio", *args, *scope)
+            iid, status_code = _instance_ids(rd.get("result") or {})
+            action_errors: list[dict] = []
+            if iid:
+                try:
+                    sd = invoke("procesio", "get-instance-status", "--id", iid,
+                                "--flow-template-id", process_id, "--actions", *scope)
+                    sres = sd.get("result") or {}
+                    s2 = _instance_ids(sres)[1]
+                    status_code = s2 if s2 is not None else status_code
+                    action_errors = _action_errors(sres)
+                except ToolError:
+                    pass
+            if status_code == 50 and not action_errors:
+                checks.append(_check("run-instance", "run", "pass",
+                                     {"instance_id": iid, "status": 50}))
+            elif status_code == 40 or action_errors:
+                checks.append(_check("run-instance", "run", "fail",
+                                     {"instance_id": iid, "status": status_code,
+                                      "action_errors": action_errors}))
+            else:
+                checks.append(_check("run-instance", "run", "warn",
+                                     {"instance_id": iid, "status": status_code,
+                                      "note": "unrecognized status; inspect manually"}))
+        except ToolError as e:
+            checks.append(_check("run-instance", "run", "fail",
+                                 {"code": e.code, "message": e.message}))
+    else:
+        checks.append(_check("run-instance", "run", "skip",
+                             {"reason": "not run; pass --run to execute the process"}))
+
+    # practice findings (non-gating) + verdict ---------------------------------
+    full = audit.audit_process(flow)
+    practice = [f for f in full["findings"] if f["kind"] == "practice"]
+    statuses = [c["status"] for c in checks]
+    verdict = "fail" if "fail" in statuses else ("warn" if "warn" in statuses else "pass")
+
+    return {
+        "process_id": process_id,
+        "title": title,
+        "verdict": verdict,
+        "ran": run,
+        "checks": checks,
+        "practice_findings": practice,
+        "manual_checks": checklist.manual_steps(),
+        "summary": full["summary"],
+    }

procesio_cli/dashboard/README.md

@@ -0,0 +1,117 @@
+# Setup & Health Dashboard
+
+A local web console for setting up and monitoring the framework. Built for
+onboarding: a colleague who has just cloned the repo can see every tool, agent,
+and skill, see exactly what each one is missing, and perform every setup action
+from the browser instead of the terminal or a chat with Claude.
+
+It is a framework component (like `scripts/`), not a registered tool - it is a
+long-running local server, not a JSON-in/JSON-out command. It carries **zero
+user data**: all state stays under `context-state-knowledge/` via
+`tools/_lib/userdata.py`, so the wipe-safe boundary is intact.
+
+## Launch
+
+```powershell
+python dashboard/serve.py
+```
+
+It binds to `127.0.0.1` only, prints a URL containing a one-time token, and opens
+your browser. Options: `--port <n>`, `--no-browser`, `--host` (loopback only).
+
+> Run it from a terminal (it needs an interactive console for the credential
+> store). If you launch it from a detached/service context, force the backend
+> with `PYTHON_KEYRING_BACKEND=keyring.backends.Windows.WinVaultKeyring`
+> (serve.py already sets this).
+
+## What you get
+
+- **Inventory** - every tool, agent, and skill from the live registry, grouped
+  into tabs, each with a readiness dot, its description, and its actions.
+- **Credential status** - per secret: present or missing, with a one-click
+  **Store** / **update** / **delete**. Values go straight to Windows Credential
+  Manager and are never written to disk or logged.
+- **Live validation** - beyond "present", each capability with a probe is
+  actively checked: **connected**, **invalid** (with the error), or **no live
+  probe**. Streams in as results land; **Re-check all** re-runs it.
+- **Config editor** - the LLM Providers tab and each config template open a
+  validated JSON editor. `llm/providers.json` is schema-checked; every config
+  is scanned for leftover template placeholders.
+- **Web login** - tools that log in via a browser declare a `web_session:` block
+  (ryver-web, whatsapp, quickmail-web, fgo-web, linkedin-web, the *-invoices tools).
+  Their card shows a **Connect** button prefilled with the right session name and
+  URL - no guessing - and a missing login counts as needs-setup.
+- **OAuth** - tools with an `auth-login` action (google-*, linkedin) show a
+  **Connect** button on the card; the oauth token/accounts secrets (produced by
+  the flow, not typed) are hidden so only the client key is settable.
+- **Bootstrap** - on a fresh install a banner offers one-click
+  `orchestrator bootstrap --with-templates`.
+- **Plain-language status** - each card leads with one line - "Ready to use",
+  "Needs a credential", "Needs a browser login", "Needs Google/LinkedIn sign-in",
+  or "Not working" - and only shows a live-check row where a probe exists. When a
+  check fails, an **Explain** button asks the LLM why.
+- **LLM-backed verification & copilot** - once an LLM provider is configured, the
+  Context tab summarizes what the store knows, **Explain** judges a failing probe,
+  and **Copilot** answers setup questions with one-click suggested actions. All of
+  this goes through the provider-agnostic `llm` tool - the dashboard never calls
+  Claude or any hardcoded provider.
+
+## The live-validation convention
+
+"Is the credential actually connected?" is answered by a probe resolved in this
+order per capability:
+
+1. an explicit `healthcheck:` block in the manifest (a cheap, read-only action),
+2. else a conventional `auth-status` action,
+3. else **no live probe** (presence only).
+
+A capability with a missing secret is not probed - it is already known
+unconfigured. To make a tool live-validatable, add to its `tool.yaml`:
+
+```yaml
+healthcheck:
+  action: list-users      # a cheap, read-only, side-effect-free action
+  args: { limit: 1 }      # forwarded as --limit 1
+  label: "list one user"
+```
+
+Probes run concurrently, cache briefly, and are single-flighted so a client can
+never storm the machine.
+
+## Security model
+
+Single user, own laptop. The server binds loopback only and gates every `/api/*`
+call with a one-time token (in the launch URL, then stripped from the address
+bar). It is **not** multi-user auth - that is out of scope until a shared/remote
+mode is built. No GET ever returns a stored secret value.
+
+## Architecture
+
+```
+dashboard/
+  serve.py              launcher (venv re-exec, loopback bind, token)
+  server/
+    handler.py          routing, token gate, JSON + SSE + static
+    routes.py           URL -> handler wiring
+    inventory.py        read model (in-process: registry + store + providers)
+    validate.py         live probes (concurrent, cached, single-flight)
+    setup.py            credentials, config, bootstrap, sessions, OAuth
+    jobs.py             background jobs for interactive logins
+    config_schemas.py   per-config validation (jsonschema + placeholder scan)
+    llmtest.py          provider-agnostic tests, context inspect, copilot
+    runner.py           subprocess bridge to the framework scripts
+    security.py         loopback token
+  web/                  vanilla JS + CSS SPA (no build step, no npm)
+  tests/
+```
+
+Reads are in-process (fast, always current). Anything that runs a tool/agent or
+writes a credential goes through the existing scripts as a subprocess, so each
+runs exactly as it does from the terminal - the dashboard never reimplements a
+tool's logic or credential handling.
+
+## Tests
+
+```powershell
+.venv\Scripts\python.exe -m pytest dashboard/tests -q
+```

procesio_cli/dashboard/__init__.py

@@ -0,0 +1,18 @@
+"""Framework setup & health dashboard.
+
+A local, single-user web console for onboarding: see every tool, agent, skill,
+and the context/state store; see exactly what each is missing; and perform every
+setup action (store credentials, fill config, capture logins, verify) from the UI
+instead of the terminal or a chat with Claude.
+
+Not a JSON-in/JSON-out tool (it is a long-running local server), so it lives here
+as its own framework component beside scripts/, tools/, agents/, skills/. It
+carries ZERO user data: all state stays under context-state-knowledge/ resolved
+through tools/_lib/userdata.py, keeping the wipe-safe boundary intact.
+
+LLM-agnostic: any model work (functional tests, context inspection, the setup
+copilot) goes through the `llm` tool, which is provider-neutral. The dashboard
+never calls Claude or any hardcoded provider.
+
+Launch:  python dashboard/serve.py
+"""

procesio_cli/dashboard/serve.py

@@ -0,0 +1,98 @@
+"""Launch the framework setup & health dashboard.
+
+    python dashboard/serve.py [--port 8765] [--host 127.0.0.1] [--no-browser]
+
+Binds to loopback only, mints a one-time access token, prints the URL, and opens
+the browser. Stdlib http.server (ThreadingHTTPServer) - no web framework, no
+install step, so a colleague who has only cloned the repo can run it immediately.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# Force keyring's Windows backend explicitly. keyring's default backend
+# AUTO-DETECTION probes several backends and blocks when the process has no
+# interactive console (as a server launched from a preview manager, a service,
+# or a detached shell does) - which would hang the very first credential read.
+# Naming the backend skips detection entirely and still uses the real Windows
+# Credential Manager. Subprocesses (run-tool / set-credential) inherit this env.
+os.environ.setdefault("PYTHON_KEYRING_BACKEND", "keyring.backends.Windows.WinVaultKeyring")
+
+# Auto-switch to the project's .venv Python (keyring/pydantic/yaml live there).
+_PROJECT_ROOT = Path(__file__).resolve().parents[1]
+_VENV_PY = _PROJECT_ROOT / ".venv" / "Scripts" / "python.exe"
+if _VENV_PY.exists() and Path(sys.executable).resolve() != _VENV_PY.resolve():
+    import subprocess
+    sys.exit(subprocess.run([str(_VENV_PY), __file__, *sys.argv[1:]]).returncode)
+
+sys.path.insert(0, str(_PROJECT_ROOT))
+
+import argparse  # noqa: E402
+import socket  # noqa: E402
+import threading  # noqa: E402
+import webbrowser  # noqa: E402
+from http.server import ThreadingHTTPServer  # noqa: E402
+
+from dashboard.server import security  # noqa: E402
+from dashboard.server.handler import Handler  # noqa: E402
+
+
+def _free_port(host: str, preferred: int) -> int:
+    """Use the preferred port if free, else let the OS pick one."""
+    for candidate in (preferred, 0):
+        try:
+            s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host, candidate))
+            port = s.getsockname()[1]
+            s.close()
+            return port
+        except OSError:
+            continue
+    raise SystemExit("could not bind a local port")
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Framework setup & health dashboard.")
+    p.add_argument("--host", default="127.0.0.1",
+                   help="Bind address (loopback only; do not expose).")
+    p.add_argument("--port", type=int, default=8765)
+    p.add_argument("--no-browser", action="store_true",
+                   help="Do not auto-open the browser.")
+    args = p.parse_args()
+
+    if args.host not in ("127.0.0.1", "localhost", "::1"):
+        print(f"refusing to bind non-loopback host {args.host!r}: this dashboard "
+              "stores credentials and is single-user, local-only.", file=sys.stderr)
+        return 2
+
+    port = _free_port(args.host, args.port)
+    url = f"http://{args.host}:{port}/?token={security.token()}"
+
+    httpd = ThreadingHTTPServer((args.host, port), Handler)
+    httpd.daemon_threads = True
+
+    print("=" * 68)
+    print(" Agents & Tools - Setup & Health Dashboard")
+    print("=" * 68)
+    print(f" Open:  {url}")
+    print(" Bound to loopback only. The token gates the API; keep the URL private.")
+    print(" Press Ctrl+C to stop.")
+    print("=" * 68)
+
+    if not args.no_browser:
+        threading.Timer(0.5, lambda: webbrowser.open(url)).start()
+
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nshutting down.")
+    finally:
+        httpd.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

procesio_cli/dashboard/server/__init__.py

@@ -0,0 +1 @@
+"""Dashboard HTTP server package (Python stdlib only - no web framework)."""

procesio_cli/dashboard/server/config_schemas.py

@@ -0,0 +1,92 @@
+"""Per-config validation for the config editor.
+
+Two layers:
+  1. A precise JSON Schema for configs where structure matters - notably
+     llm/providers.json, which gates every LLM-backed feature. jsonschema
+     (already a framework dependency) does the heavy lifting.
+  2. A generic pass for every config: it must be a JSON object, and any value
+     still holding a template PLACEHOLDER (YOUR-..., REPLACE_ME, <...>) is
+     flagged so a half-filled config never reads as ready.
+
+Returns {ok, errors, warnings}. `ok` is False only on a hard schema/JSON error;
+leftover placeholders are warnings (the user may be mid-edit).
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+try:
+    import jsonschema
+except Exception:  # noqa: BLE001 - degrade to generic checks if absent
+    jsonschema = None
+
+_PLACEHOLDER = re.compile(r"YOUR[-_ ]|REPLACE|CHANGE[-_ ]?ME|<[^>]+>|xxxxx", re.I)
+
+# component/name (without .json) -> JSON Schema
+_SCHEMAS: dict[str, dict] = {
+    "llm/providers": {
+        "type": "object",
+        "required": ["providers"],
+        "properties": {
+            "comment": {"type": "string"},
+            "default": {"type": "string"},
+            "providers": {
+                "type": "object",
+                "minProperties": 1,
+                "additionalProperties": {
+                    "type": "object",
+                    "required": ["adapter"],
+                    "properties": {
+                        "adapter": {"enum": ["openai_compat", "claude_api", "codex_cli"]},
+                        "base_url": {"type": "string"},
+                        "model": {"type": "string"},
+                        "auth_style": {"enum": ["bearer", "api-key", "none"]},
+                    },
+                },
+            },
+        },
+    },
+}
+
+
+def _walk_placeholders(node: Any, path: str, out: list[str]) -> None:
+    if isinstance(node, str):
+        if _PLACEHOLDER.search(node):
+            out.append(f"{path or '(root)'}: still a placeholder ({node!r})")
+    elif isinstance(node, dict):
+        for k, v in node.items():
+            _walk_placeholders(v, f"{path}.{k}" if path else k, out)
+    elif isinstance(node, list):
+        for i, v in enumerate(node):
+            _walk_placeholders(v, f"{path}[{i}]", out)
+
+
+def validate(component: str, name: str, data: Any) -> dict[str, Any]:
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not isinstance(data, dict):
+        return {"ok": False, "errors": ["top-level value must be a JSON object"],
+                "warnings": []}
+
+    schema = _SCHEMAS.get(f"{component}/{name}")
+    if schema is not None and jsonschema is not None:
+        validator = jsonschema.Draft7Validator(schema)
+        for err in sorted(validator.iter_errors(data), key=lambda e: list(e.path)):
+            loc = ".".join(str(p) for p in err.path) or "(root)"
+            errors.append(f"{loc}: {err.message}")
+        # cross-field: `default` must name an existing provider
+        if component == "llm" and name == "providers":
+            default = data.get("default")
+            provs = data.get("providers") or {}
+            if default and default not in provs:
+                errors.append(f"default: {default!r} is not one of the providers "
+                              f"({', '.join(provs) or 'none'})")
+
+    _walk_placeholders(data, "", warnings)
+    return {"ok": not errors, "errors": errors, "warnings": warnings}
+
+
+def has_schema(component: str, name: str) -> bool:
+    return f"{component}/{name}" in _SCHEMAS