procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/connector-builder/handlers/raw.py

@@ -0,0 +1,38 @@
+"""Generic escape hatch: call ANY connector-builder endpoint not first-classed.
+
+Keeps the tool complete as the API evolves — new endpoints are reachable via
+`api --method ... --path ...` without a code change, while the common workflow
+stays ergonomic through the dedicated actions.
+"""
+from __future__ import annotations
+
+import argparse
+
+from actiondef import ActionDef
+from handlers.common import parse_json
+
+
+def api(client, args) -> dict:
+    params = parse_json(args.query, what="query", expect=dict)
+    body = parse_json(args.body, what="body", expect=(dict, list)) if args.body else None
+    if args.out:
+        # Binary / file response: stream to disk (GET only makes sense here).
+        return client.download(args.path, args.out, params=params)
+    result = client.request(args.method, args.path, params=params, json_body=body)
+    return {"path": args.path, "method": args.method.upper(), "response": result}
+
+
+def _api_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--method", default="GET",
+                   help="HTTP method (GET/POST/PUT/PATCH/DELETE)")
+    p.add_argument("--path", required=True,
+                   help="Endpoint path, e.g. /builds or /admin/users")
+    p.add_argument("--query", help="Query params as a JSON object")
+    p.add_argument("--body", help="Request body as JSON (object or array)")
+    p.add_argument("--out", help="If set, stream the response to this file (binary)")
+
+
+ACTIONS: dict[str, ActionDef] = {
+    "api": ActionDef(api, _api_args,
+                     description="Call any endpoint (method/path/query/body); --out streams binary."),
+}

procesio_cli/tools/connector-builder/handlers/telemetry.py

@@ -0,0 +1,39 @@
+"""Cross-build telemetry: GET /telemetry/logs (own builds; all builds for admin)."""
+from __future__ import annotations
+
+import argparse
+
+from actiondef import ActionDef
+
+
+def telemetry(client, args) -> dict:
+    params: dict = {"page": args.page, "page_size": args.page_size}
+    for f in ("build_id", "stage", "model", "model_search", "after", "before"):
+        v = getattr(args, f)
+        if v:
+            params[f] = v
+    if args.success is not None:
+        params["success"] = str(args.success).lower()
+    return client.get("/telemetry/logs", params)
+
+
+def _telemetry_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--page", type=int, default=1)
+    p.add_argument("--page-size", dest="page_size", type=int, default=100,
+                   help="Max 500")
+    p.add_argument("--build-id", dest="build_id",
+                   help="Comma-separated build UUIDs to filter")
+    p.add_argument("--stage", help="Comma-separated stage names")
+    p.add_argument("--success", type=lambda v: v.lower() in ("1", "true", "yes"),
+                   default=None, help="Filter by success true/false")
+    p.add_argument("--model", help="Comma-separated model names")
+    p.add_argument("--model-search", dest="model_search", help="Substring model search")
+    p.add_argument("--after", help="ISO datetime lower bound")
+    p.add_argument("--before", help="ISO datetime upper bound")
+
+
+ACTIONS: dict[str, ActionDef] = {
+    "telemetry": ActionDef(
+        telemetry, _telemetry_args,
+        description="Cross-build LLM telemetry (cost/tokens/latency), filterable."),
+}

procesio_cli/tools/connector-builder/main.py

@@ -0,0 +1,94 @@
+"""connector-builder tool entrypoint — action dispatch.
+
+Drives the AI Connector Builder (connector-builder.procesio.app): the platform
+that turns API documentation into compiled PROCESIO Custom Action `.nupkg`
+connectors via an 8-stage LLM pipeline (gather → clarify → plan → generate →
+validate → compile → fix → deliver).
+
+Two auth modes, both resolving to an `Authorization: Bearer <token>` header
+(see client.py): an `acb_...` API key, or username/password → POST /auth/login.
+
+The dir name has a hyphen, so this tool's own modules are imported by BARE name
+with the tool root on sys.path (mirrors quickmail-web / fgo-web); the shared libs
+are imported as the valid package `tools._lib`.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+TOOL_ROOT = Path(__file__).resolve().parent
+FRAMEWORK_ROOT = TOOL_ROOT.parents[1]
+_VENV_PY = FRAMEWORK_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)
+
+import argparse  # noqa: E402
+
+for _p in (str(TOOL_ROOT), str(FRAMEWORK_ROOT)):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+from tools._lib.io import emit, fail  # noqa: E402
+
+import errors  # noqa: E402
+from actiondef import ActionDef  # noqa: E402
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str):
+        raise errors.UsageError(message)
+
+
+def collect_actions() -> dict[str, ActionDef]:
+    from handlers import auth, builds, files, telemetry, admin, raw
+    actions: dict[str, ActionDef] = {}
+    for module in (auth, builds, files, telemetry, admin, raw):
+        for name, defn in module.ACTIONS.items():
+            if name in actions:
+                raise RuntimeError(f"duplicate connector-builder action: {name}")
+            actions[name] = defn
+    return actions
+
+
+ACTIONS = collect_actions()
+
+
+def _default_client_factory():
+    from client import ConnectorBuilderClient
+    return ConnectorBuilderClient()
+
+
+def dispatch(action: str, argv: list[str], *, client_factory=None) -> dict:
+    if action not in ACTIONS:
+        raise errors.UsageError(
+            f"unknown action: {action}. Known: {', '.join(sorted(ACTIONS))}")
+    defn = ACTIONS[action]
+    parser = _Parser(prog=f"connector-builder {action}", description=defn.description)
+    defn.add_args(parser)
+    parsed = parser.parse_args(argv)
+    if defn.needs_client:
+        factory = client_factory or _default_client_factory
+        return defn.func(factory(), parsed)
+    return defn.func(parsed)
+
+
+def main(argv=None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print("Actions:", file=sys.stderr)
+        for name in sorted(ACTIONS):
+            print(f"  {name:<28} {ACTIONS[name].description}", file=sys.stderr)
+        sys.exit(0)
+    action, rest = argv[0], argv[1:]
+    try:
+        result = dispatch(action, rest)
+    except Exception as exc:  # noqa: BLE001
+        code, message, details, exit_code = errors.classify(exc)
+        fail(code, message, details, exit_code)
+    emit(result)
+
+
+if __name__ == "__main__":
+    main()

procesio_cli/tools/connector-builder/tests/conftest.py

@@ -0,0 +1,146 @@
+"""Pytest fixtures + hyphen-safe module loading for the connector-builder tool.
+
+The tool dir name has a hyphen, so its own modules (errors, actiondef, client,
+handlers.*, main) cannot be imported as ``tools.connector-builder.*``. At runtime
+main.py imports them by BARE name with the tool root on sys.path. Under pytest
+those bare names collide across hyphenated tools, so — exactly like fgo-web /
+quickmail-web — we load THIS tool's modules under unique ``cb_*`` aliases via
+importlib, registering the bare names only TRANSIENTLY during load so each
+module's intra-tool bare imports resolve to THIS tool's files, then restore.
+
+NOTE: there is intentionally NO tests/__init__.py here and every test file has a
+unique ``test_cb_*`` basename — otherwise pytest's rootdir import collides with
+other hyphenated tools' identically-named test modules.
+"""
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+TOOL_ROOT = Path(__file__).resolve().parents[1]          # tools/connector-builder
+FRAMEWORK_ROOT = Path(__file__).resolve().parents[3]     # repo root
+
+if str(FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(FRAMEWORK_ROOT))
+
+_BARE_NAMES = (
+    "errors", "actiondef", "client",
+    "handlers", "handlers.common", "handlers.auth", "handlers.builds",
+    "handlers.files", "handlers.telemetry", "handlers.admin", "handlers.raw",
+    "main",
+)
+_MISSING = object()
+_saved_bare = {n: sys.modules.get(n, _MISSING) for n in _BARE_NAMES}
+
+
+def _load(bare_name: str, relpath: str) -> ModuleType:
+    path = TOOL_ROOT / relpath
+    spec = importlib.util.spec_from_file_location(bare_name, path)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[bare_name] = mod  # transient: lets intra-tool bare imports work
+    spec.loader.exec_module(mod)
+    sys.modules["cb_" + bare_name.replace(".", "_")] = mod
+    return mod
+
+
+# Leaf modules first.
+errors = _load("errors", "errors.py")
+actiondef = _load("actiondef", "actiondef.py")
+client = _load("client", "client.py")
+
+_handlers_pkg = ModuleType("handlers")
+_handlers_pkg.__path__ = [str(TOOL_ROOT / "handlers")]  # type: ignore[attr-defined]
+sys.modules["handlers"] = _handlers_pkg
+sys.modules["cb_handlers"] = _handlers_pkg
+common = _load("handlers.common", "handlers/common.py")
+auth = _load("handlers.auth", "handlers/auth.py")
+builds = _load("handlers.builds", "handlers/builds.py")
+files = _load("handlers.files", "handlers/files.py")
+telemetry = _load("handlers.telemetry", "handlers/telemetry.py")
+admin = _load("handlers.admin", "handlers/admin.py")
+raw = _load("handlers.raw", "handlers/raw.py")
+
+main = _load("main", "main.py")
+
+# Friendly aliases for tests.
+sys.modules["cb_main"] = main
+sys.modules["cb_errors"] = errors
+sys.modules["cb_client"] = client
+
+# Strip TOOL_ROOT from sys.path so another hyphenated tool's bare imports don't
+# resolve to OUR files for the rest of the session, then restore bare-name slots.
+_tool_root_str = str(TOOL_ROOT)
+sys.path[:] = [p for p in sys.path if p != _tool_root_str]
+for _bn, _prev in _saved_bare.items():
+    if _prev is _MISSING:
+        sys.modules.pop(_bn, None)
+    else:
+        sys.modules[_bn] = _prev
+
+
+class FakeClient:
+    """Records calls and returns canned responses. Mirrors the
+    ConnectorBuilderClient verb surface used by handlers."""
+
+    def __init__(self, responses=None, base_url="https://example/api"):
+        self.base_url = base_url
+        self.calls: list[tuple] = []
+        self.responses = responses or {}
+
+    def _ret(self, key, default):
+        return self.responses.get(key, default)
+
+    def get(self, path, params=None):
+        self.calls.append(("GET", path, params, None))
+        return self._ret(("GET", path), {"ok": True, "path": path, "params": params})
+
+    def post(self, path, json_body=None, params=None):
+        self.calls.append(("POST", path, params, json_body))
+        return self._ret(("POST", path), {"ok": True, "path": path, "body": json_body})
+
+    def put(self, path, json_body=None):
+        self.calls.append(("PUT", path, None, json_body))
+        return self._ret(("PUT", path), {"ok": True, "path": path, "body": json_body})
+
+    def patch(self, path, json_body=None):
+        self.calls.append(("PATCH", path, None, json_body))
+        return self._ret(("PATCH", path), {"ok": True, "path": path, "body": json_body})
+
+    def delete(self, path, params=None):
+        self.calls.append(("DELETE", path, params, None))
+        return self._ret(("DELETE", path), {"ok": True, "path": path})
+
+    def request(self, method, path, params=None, json_body=None):
+        self.calls.append((method.upper(), path, params, json_body))
+        return self._ret((method.upper(), path),
+                         {"ok": True, "path": path, "method": method.upper()})
+
+    def download(self, path, out_path, params=None):
+        self.calls.append(("DOWNLOAD", path, params, out_path))
+        return {"out": out_path, "bytes": 123, "filename": "pkg.nupkg",
+                "content_type": "application/octet-stream"}
+
+
+@pytest.fixture
+def fake_client():
+    return FakeClient()
+
+
+@pytest.fixture
+def cb_main():
+    return main
+
+
+@pytest.fixture
+def cb_errors():
+    return errors
+
+
+@pytest.fixture
+def cb_client():
+    return client

procesio_cli/tools/connector-builder/tests/test_cb_client.py

@@ -0,0 +1,86 @@
+"""Auth-resolution + client behaviour tests (no network)."""
+from __future__ import annotations
+
+import pytest
+
+import cb_client as client
+import cb_errors as errors
+
+
+@pytest.fixture(autouse=True)
+def _clear_auth_env(monkeypatch):
+    for k in ("CONNECTOR_BUILDER_AUTH", "CONNECTOR_BUILDER_API_KEY",
+              "CONNECTOR_BUILDER_USERNAME", "CONNECTOR_BUILDER_PASSWORD"):
+        monkeypatch.delenv(k, raising=False)
+
+
+def _set_creds(monkeypatch, mapping):
+    monkeypatch.setattr(client, "_cred", lambda name: mapping.get(name))
+
+
+def test_apikey_mode_default_when_key_present(monkeypatch):
+    _set_creds(monkeypatch, {"api-key": "acb_abc"})
+    assert client.resolve_token() == "acb_abc"
+
+
+def test_userpass_mode_when_only_userpass(monkeypatch):
+    _set_creds(monkeypatch, {"username": "u@e", "password": "pw"})
+    monkeypatch.setattr(client, "login", lambda u, p: f"jwt:{u}:{p}")
+    assert client.resolve_token() == "jwt:u@e:pw"
+
+
+def test_explicit_userpass_overrides_apikey(monkeypatch):
+    monkeypatch.setenv("CONNECTOR_BUILDER_AUTH", "userpass")
+    _set_creds(monkeypatch, {"api-key": "acb_abc", "username": "u", "password": "p"})
+    monkeypatch.setattr(client, "login", lambda u, p: "jwt-tok")
+    assert client.resolve_token() == "jwt-tok"
+
+
+def test_no_credential_raises(monkeypatch):
+    _set_creds(monkeypatch, {})
+    with pytest.raises(errors.CredentialError):
+        client.resolve_token()
+
+
+def test_apikey_mode_without_key_raises(monkeypatch):
+    monkeypatch.setenv("CONNECTOR_BUILDER_AUTH", "apikey")
+    _set_creds(monkeypatch, {"username": "u", "password": "p"})
+    with pytest.raises(errors.CredentialError):
+        client.resolve_token()
+
+
+def test_bearer_header_shape():
+    c = client.ConnectorBuilderClient(token="acb_xyz")
+    h = c._headers()
+    assert h["Authorization"] == "Bearer acb_xyz"
+    assert h["Accept"] == "application/json"
+
+
+def test_base_url_env_override(monkeypatch):
+    monkeypatch.setenv("CONNECTOR_BUILDER_BASE_URL", "https://local/api/")
+    assert client.get_base_url() == "https://local/api"
+
+
+class _Resp:
+    def __init__(self, status, body):
+        self.status_code = status
+        self._body = body
+        self.headers = {}
+        self.content = b"{}"
+        self.text = "{}"
+
+    def json(self):
+        return self._body
+
+
+def test_request_raises_apierror_on_4xx(monkeypatch):
+    c = client.ConnectorBuilderClient(token="t")
+
+    class _S:
+        def request(self, *a, **k):
+            return _Resp(404, {"detail": "nope"})
+
+    c._s = _S()
+    with pytest.raises(errors.ApiError) as ei:
+        c.get("/builds/x")
+    assert ei.value.status_code == 404

procesio_cli/tools/connector-builder/tests/test_cb_dispatch.py

@@ -0,0 +1,105 @@
+"""Dispatch + handler routing tests with a FakeClient (zero network)."""
+from __future__ import annotations
+
+import pytest
+
+import cb_main as main
+
+
+def _run(action, argv, fake_client):
+    return main.dispatch(action, argv, client_factory=lambda: fake_client)
+
+
+def test_unknown_action_raises(fake_client):
+    import cb_errors as errors
+    with pytest.raises(errors.UsageError):
+        _run("nope", [], fake_client)
+
+
+def test_check_hits_auth_me(fake_client):
+    fake_client.responses[("GET", "/auth/me")] = {
+        "email": "x@example.com", "role": "admin", "has_llm_key": True}
+    out = _run("check", [], fake_client)
+    assert out["ok"] is True and out["role"] == "admin"
+    assert fake_client.calls[0][:2] == ("GET", "/auth/me")
+
+
+def test_create_build_requires_a_source(fake_client):
+    import cb_errors as errors
+    with pytest.raises(errors.UsageError):
+        _run("create-build", ["--user-requirements", "do x"], fake_client)
+
+
+def test_create_build_posts_body(fake_client):
+    _run("create-build", ["--api-url", "https://docs", "--user-requirements", "x"],
+         fake_client)
+    method, path, _params, body = fake_client.calls[0]
+    assert (method, path) == ("POST", "/builds")
+    assert body["api_url"] == "https://docs" and body["user_requirements"] == "x"
+
+
+def test_answer_wraps_answers_object(fake_client):
+    _run("answer", ["--build-id", "B1", "--answers", '{"q1":"a1"}'], fake_client)
+    method, path, _p, body = fake_client.calls[0]
+    assert (method, path) == ("POST", "/builds/B1/answers")
+    assert body == {"answers": {"q1": "a1"}}
+
+
+def test_answer_rejects_bad_json(fake_client):
+    import cb_errors as errors
+    with pytest.raises(errors.UsageError):
+        _run("answer", ["--build-id", "B1", "--answers", "not-json"], fake_client)
+
+
+def test_override_stage_payload(fake_client):
+    _run("override-stage",
+         ["--build-id", "B1", "--target-step", "3", "--target-status", "waiting_user"],
+         fake_client)
+    method, path, _p, body = fake_client.calls[0]
+    assert (method, path) == ("POST", "/builds/B1/override-stage")
+    assert body == {"target_step": 3, "target_status": "waiting_user"}
+
+
+def test_download_artifact_streams_to_out(fake_client):
+    out = _run("download-artifact", ["--build-id", "B1", "--out", "pkg.nupkg"],
+               fake_client)
+    assert out["bytes"] == 123
+    assert fake_client.calls[0][:2] == ("DOWNLOAD", "/builds/B1/artifact")
+
+
+def test_update_file_requires_content(fake_client):
+    import cb_errors as errors
+    with pytest.raises(errors.UsageError):
+        _run("update-file", ["--build-id", "B1", "--filename", "A.cs"], fake_client)
+
+
+def test_knowledge_create_validates_module_type(fake_client):
+    import cb_errors as errors
+    with pytest.raises(errors.UsageError):
+        _run("knowledge-create",
+             ["--module-type", "bogus", "--name", "x.md", "--content", "y"],
+             fake_client)
+
+
+def test_knowledge_update_puts_content(fake_client):
+    _run("knowledge-update",
+         ["--module-type", "prompt", "--name", "clarify.md", "--content", "hi"],
+         fake_client)
+    method, path, _p, body = fake_client.calls[0]
+    assert (method, path) == ("PUT", "/admin/knowledge/prompt/clarify.md")
+    assert body == {"content": "hi"}
+
+
+def test_api_escape_hatch_get(fake_client):
+    out = _run("api", ["--method", "GET", "--path", "/builds", "--query", '{"page":1}'],
+               fake_client)
+    assert out["method"] == "GET" and out["path"] == "/builds"
+    assert fake_client.calls[0][:2] == ("GET", "/builds")
+
+
+def test_all_actions_present():
+    # Sanity: the full surface is wired (auth+builds+files+telemetry+admin+raw).
+    for a in ("check", "create-build", "gather", "answer", "approve-plan",
+              "approve-generate", "download-artifact", "telemetry",
+              "knowledge-list", "build-selftest", "api"):
+        assert a in main.ACTIONS

procesio_cli/tools/connector-builder/tests/test_cb_manifest_sync.py

@@ -0,0 +1,76 @@
+"""Guard: tool.yaml (source of truth) declares exactly the actions the dispatcher
+registers, every CLI flag appears as a manifest arg (and vice-versa), required
+flags are marked required, and the three auth secrets are declared.
+
+``main`` comes in via the ``cb_main`` alias from conftest."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import cb_main as main
+from tools._lib.manifest import load_tool
+
+
+def _manifest():
+    tool_root = Path(main.__file__).resolve().parent
+    return load_tool(tool_root / "tool.yaml")
+
+
+def test_manifest_loads():
+    m = _manifest()
+    assert m.name == "connector-builder"
+    assert m.routing is not None
+
+
+def test_manifest_actions_match_dispatch():
+    m = _manifest()
+    manifest_actions = set(m.action_names())
+    dispatch_actions = set(main.ACTIONS)
+    assert manifest_actions == dispatch_actions, (
+        f"only in manifest: {manifest_actions - dispatch_actions}; "
+        f"only in code: {dispatch_actions - manifest_actions}"
+    )
+
+
+def test_manifest_args_match_argparse():
+    m = _manifest()
+    for name, defn in main.ACTIONS.items():
+        parser = argparse.ArgumentParser()
+        defn.add_args(parser)
+        argparse_names = set()
+        for action in parser._actions:
+            for opt in action.option_strings:
+                if opt.startswith("--") and opt != "--help":
+                    argparse_names.add(opt[2:])
+        spec = m.get_action(name)
+        manifest_names = {a.name for a in spec.args}
+        assert manifest_names == argparse_names, (
+            f"action {name}: only in manifest {manifest_names - argparse_names}; "
+            f"only in argparse {argparse_names - manifest_names}"
+        )
+
+
+def test_required_args_marked_required_in_manifest():
+    m = _manifest()
+    for name, defn in main.ACTIONS.items():
+        parser = argparse.ArgumentParser()
+        defn.add_args(parser)
+        required_argparse = set()
+        for action in parser._actions:
+            if getattr(action, "required", False):
+                for opt in action.option_strings:
+                    if opt.startswith("--") and opt != "--help":
+                        required_argparse.add(opt[2:])
+        spec = m.get_action(name)
+        required_manifest = {a.name for a in spec.args if a.required}
+        assert required_argparse <= required_manifest, (
+            f"action {name}: argparse-required but not manifest-required: "
+            f"{required_argparse - required_manifest}"
+        )
+
+
+def test_secrets_declared():
+    m = _manifest()
+    names = {s.name for s in m.secrets}
+    assert names == {"api-key", "username", "password"}