pollaris-cli 0.1.0__tar.gz

pollaris_cli-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: pollaris-cli
+Version: 0.1.0
+Summary: Agent-friendly Pollaris CLI and MCP bridge
+Project-URL: Repository, https://github.com/devsapariya94/Pollaris
+Project-URL: Documentation, https://github.com/devsapariya94/Pollaris/blob/main/cli/README.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25
+Requires-Dist: cryptography>=43
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# Pollaris CLI
+
+Create and publish Pollaris forms from terminal-capable agents. The CLI starts a
+browser authorization flow when needed, preserves the original operation, and resumes
+it after the user grants access. It returns an authorization URL; it does not open
+a browser automatically.
+
+Development install from the repository root:
+
+```bash
+uv tool install --editable ./cli
+```
+
+For package publication and production testing, see [publishing](PUBLISHING.md).
+
+For the optional local MCP bridge, include its dependencies:
+
+```bash
+uv tool install --editable './cli[mcp]'
+```
+
+Point the CLI at an agent-enabled deployment (see [server setup](../docs/mcp/agent-access.md)):
+
+```bash
+export POLLARIS_API_URL=https://api.example.com
+pollaris capabilities --json
+```
+
+Create a form:
+
+```bash
+pollaris forms create \
+  --prompt "Create a short library feedback form" \
+  --publish \
+  --wait \
+  --json
+```
+
+When the command returns `requires_authorization`, open `authorization.url` and
+run the returned `next_action.command`. The finished result contains
+`form.public_url`.
+
+Creation publishes by default. Use `--draft-only` to create an editable draft.
+`--wait` polls for completion up to `--timeout` seconds (default: 45); a pending
+job can be checked with `pollaris jobs get JOB_ID --json` or
+`pollaris jobs wait JOB_ID --json`.
+
+To update or publish an existing form, inspect it first with
+`pollaris forms get FORM_ID --json`, then pass its current `draft_revision` as
+`--expected-revision` to `forms save` or `forms publish`. Saving also requires
+`--definition path/to/definition.json`.
+
+Use `pollaris --help` and each command's `--help` for options. Credentials use an
+OS keychain, or encrypted file storage configured by `POLLARIS_CLI_SECRET_KEY`
+(a Fernet key) on headless hosts. Local state defaults to `~/.config/pollaris`;
+`POLLARIS_CLI_HOME` overrides it and `--profile` selects a separate profile.
+
+See [OAuth agent access](../docs/mcp/agent-access.md), [MCP tools](../docs/mcp/tools.md),
+and the [integration index](../docs/README.md) for deployment and connection guides.

pollaris_cli-0.1.0/README.md

@@ -0,0 +1,59 @@
+# Pollaris CLI
+
+Create and publish Pollaris forms from terminal-capable agents. The CLI starts a
+browser authorization flow when needed, preserves the original operation, and resumes
+it after the user grants access. It returns an authorization URL; it does not open
+a browser automatically.
+
+Development install from the repository root:
+
+```bash
+uv tool install --editable ./cli
+```
+
+For package publication and production testing, see [publishing](PUBLISHING.md).
+
+For the optional local MCP bridge, include its dependencies:
+
+```bash
+uv tool install --editable './cli[mcp]'
+```
+
+Point the CLI at an agent-enabled deployment (see [server setup](../docs/mcp/agent-access.md)):
+
+```bash
+export POLLARIS_API_URL=https://api.example.com
+pollaris capabilities --json
+```
+
+Create a form:
+
+```bash
+pollaris forms create \
+  --prompt "Create a short library feedback form" \
+  --publish \
+  --wait \
+  --json
+```
+
+When the command returns `requires_authorization`, open `authorization.url` and
+run the returned `next_action.command`. The finished result contains
+`form.public_url`.
+
+Creation publishes by default. Use `--draft-only` to create an editable draft.
+`--wait` polls for completion up to `--timeout` seconds (default: 45); a pending
+job can be checked with `pollaris jobs get JOB_ID --json` or
+`pollaris jobs wait JOB_ID --json`.
+
+To update or publish an existing form, inspect it first with
+`pollaris forms get FORM_ID --json`, then pass its current `draft_revision` as
+`--expected-revision` to `forms save` or `forms publish`. Saving also requires
+`--definition path/to/definition.json`.
+
+Use `pollaris --help` and each command's `--help` for options. Credentials use an
+OS keychain, or encrypted file storage configured by `POLLARIS_CLI_SECRET_KEY`
+(a Fernet key) on headless hosts. Local state defaults to `~/.config/pollaris`;
+`POLLARIS_CLI_HOME` overrides it and `--profile` selects a separate profile.
+
+See [OAuth agent access](../docs/mcp/agent-access.md), [MCP tools](../docs/mcp/tools.md),
+and the [integration index](../docs/README.md) for deployment and connection guides.

pollaris_cli-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pollaris-cli"
+version = "0.1.0"
+description = "Agent-friendly Pollaris CLI and MCP bridge"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27", "keyring>=25", "cryptography>=43"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=2,<3"]
+dev = ["pytest>=8"]
+
+[project.urls]
+Repository = "https://github.com/devsapariya94/Pollaris"
+Documentation = "https://github.com/devsapariya94/Pollaris/blob/main/cli/README.md"
+
+[project.scripts]
+pollaris = "pollaris_cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pollaris_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pollaris_cli-0.1.0/src/pollaris_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Pollaris client. No server or database imports."""
+
+__version__ = "0.1.0"

pollaris_cli-0.1.0/src/pollaris_cli/bridge.py

@@ -0,0 +1,64 @@
+"""Transparent stdio-to-remote-MCP bridge using a connection-specific grant."""
+
+import anyio
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.shared._httpx_utils import create_mcp_http_client
+from mcp.types import CallToolRequestParams, PaginatedRequestParams
+
+from .client import Client
+
+
+async def serve(store, api_url=None):
+    client = Client(store, api_url)
+    capabilities = await anyio.to_thread.run_sync(client.discover)
+    mcp_url = capabilities["mcp_url"]
+
+    async def remote():
+        token = await anyio.to_thread.run_sync(client.access_token)
+        if token is None:
+            raise RuntimeError(
+                "Pollaris MCP authorization is required. Run pollaris mcp connect first."
+            )
+        http = create_mcp_http_client(headers={"Authorization": f"Bearer {token}"})
+        transport = streamable_http_client(mcp_url, http_client=http)
+        streams = await transport.__aenter__()
+        session = ClientSession(streams[0], streams[1])
+        await session.__aenter__()
+        await session.initialize()
+        return transport, session, http
+
+    async def list_tools(_context, params: PaginatedRequestParams | None):
+        transport, session, http = await remote()
+        try:
+            return await session.list_tools(params=params)
+        finally:
+            await session.__aexit__(None, None, None)
+            await transport.__aexit__(None, None, None)
+            await http.aclose()
+
+    async def call_tool(_context, params: CallToolRequestParams):
+        transport, session, http = await remote()
+        try:
+            return await session.call_tool(
+                params.name,
+                params.arguments,
+                input_responses=params.input_responses,
+                request_state=params.request_state,
+            )
+        finally:
+            await session.__aexit__(None, None, None)
+            await transport.__aexit__(None, None, None)
+            await http.aclose()
+
+    server = Server(
+        "pollaris-cli-bridge",
+        version="0.1.0",
+        instructions="Pollaris remote tools through a local connection grant.",
+        on_list_tools=list_tools,
+        on_call_tool=call_tool,
+    )
+    async with stdio_server() as streams:
+        await server.run(streams[0], streams[1], server.create_initialization_options())

pollaris_cli-0.1.0/src/pollaris_cli/client.py

@@ -0,0 +1,236 @@
+"""HTTP/auth continuation without coupling to the Pollaris application package."""
+
+import time
+import uuid
+from urllib.parse import urlsplit
+
+import httpx
+
+from .storage import LocalError
+
+SCOPES = "pollaris.forms.read pollaris.forms.write pollaris.forms.generate pollaris.forms.publish"
+CLIENT_ID = "pollaris-cli"
+
+
+class APIError(Exception):
+    def __init__(self, code, message, status=400):
+        self.code, self.message, self.status = code, message, status
+        super().__init__(message)
+
+
+def validate_origin(url):
+    parsed = urlsplit(url)
+    if (not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment
+            or (parsed.scheme != "https" and not (
+                parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}
+            ))):
+        raise LocalError("Use an HTTPS deployment URL (HTTP is allowed only for loopback development)")
+    return url.rstrip("/")
+
+
+class Client:
+    def __init__(self, store, api_url=None, http=None):
+        self.store = store
+        config = store.read("config", {})
+        self.api_url = validate_origin(api_url or config.get("api_url") or "http://localhost:8000")
+        if config.get("api_url") and config["api_url"] != self.api_url:
+            raise LocalError("Deployment differs from this profile; use a separate --profile")
+        self.http = http or httpx.Client(timeout=30, follow_redirects=False)
+        self.capabilities = None
+
+    def raw(self, method, url, **kwargs):
+        response = self.http.request(method, url, **kwargs)
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise APIError("invalid_response", "Server returned an invalid response", response.status_code) from exc
+        if not response.is_success:
+            code = data.get("error", "request_failed") if isinstance(data, dict) else "request_failed"
+            message = data.get("error_description", "Pollaris request failed") if isinstance(data, dict) else "Pollaris request failed"
+            raise APIError(code if isinstance(code, str) else "request_failed", message, response.status_code)
+        return data
+
+    def discover(self):
+        if self.capabilities is None:
+            data = self.raw("GET", f"{self.api_url}/v1/agent/capabilities")
+            validate_origin(data["issuer"])
+            validate_origin(data["mcp_url"])
+            # Issuer comes from the explicitly chosen trusted deployment, never a model argument.
+            self.capabilities = data
+        return self.capabilities
+
+    def remember_tokens(self, tokens):
+        tokens["expires_at"] = time.time() + tokens["expires_in"]
+        self.store.secret("tokens", tokens)
+        self.store.write("config", {"api_url": self.api_url, "resource": tokens["resource"],
+                                    "workspace_id": tokens["workspace_id"],
+                                    "issuer": self.discover()["issuer"],
+                                    "connection_id": tokens["connection_id"]})
+
+    def access_token(self):
+        tokens = self.store.secret("tokens")
+        if not tokens:
+            return None
+        if tokens["expires_at"] <= time.time() + 30:
+            config = self.store.read("config", {})
+            try:
+                tokens = self.raw("POST", f"{config['issuer']}/oauth/token", data={
+                    "grant_type": "refresh_token", "client_id": CLIENT_ID,
+                    "refresh_token": tokens["refresh_token"], "resource": tokens["resource"],
+                })
+                self.remember_tokens(tokens)
+            except APIError as exc:
+                if exc.status < 500 and exc.status != 429:
+                    self.store.secret("tokens", None)
+                raise
+        return tokens["access_token"]
+
+    def request(self, method, path, **kwargs):
+        token = self.access_token()
+        if token is None:
+            raise APIError("invalid_token", "Authorization required", 401)
+        headers = kwargs.pop("headers", {})
+        return self.raw(method, self.api_url + path,
+                        headers={**headers, "Authorization": f"Bearer {token}"}, **kwargs)
+
+    def operation(self, kind, payload, *, key=None, resource="api", extras=None):
+        if key is not None and not 8 <= len(key) <= 100:
+            raise LocalError("Idempotency key must contain 8–100 characters")
+        # Explicit same key maps to the same local operation, including auth continuation.
+        operation_id = str(uuid.uuid5(uuid.NAMESPACE_URL, f"{self.api_url}:{self.store.profile}:{key}")) if key else str(uuid.uuid4())
+        existing = self.store.read(f"operations/{operation_id}")
+        if existing:
+            if (existing["kind"] != kind or existing["payload"] != payload
+                    or existing["resource"] != resource
+                    or any(existing.get(name) != value for name, value in (extras or {}).items())):
+                raise APIError("idempotency_conflict", "Key was used with different input", 409)
+            return existing
+        value = {"operation_id": operation_id, "key": key or operation_id, "kind": kind,
+                 "payload": payload, "resource": resource, "status": "prepared",
+                 "api_url": self.api_url, "created_at": time.time(), **(extras or {})}
+        self.store.save_operation(value)
+        self.store.write("config", {**self.store.read("config", {}), "api_url": self.api_url})
+        return value
+
+    def start_auth(self, operation):
+        info = self.discover()
+        resource = info["mcp_url"].rstrip("/") if operation["resource"] == "mcp" else info["resource"]
+        tokens = self.store.secret("tokens")
+        if tokens and tokens["resource"] != resource:
+            raise LocalError("This profile belongs to another resource; use a separate connection profile")
+        auth = self.raw("POST", f"{info['issuer'].rstrip('/')}/oauth/device_authorization", data={
+            "client_id": CLIENT_ID, "scope": SCOPES, "resource": resource,
+            "workspace_id": operation["payload"].get("workspace_id") or "",
+            "connection_name": f"Pollaris {self.store.profile}",
+        })
+        auth.update({"expires_at": time.time() + auth["expires_in"],
+                     "next_poll": time.time() + auth["interval"], "issuer": info["issuer"]})
+        self.store.secret(f"device:{operation['operation_id']}", auth)
+        operation["status"] = "awaiting_authorization"
+        self.store.save_operation(operation)
+        return auth
+
+    def authorization(self, operation):
+        token = None
+        try:
+            token = self.access_token()
+        except APIError as exc:
+            if exc.code not in {"invalid_grant", "invalid_token", "access_denied"}:
+                raise
+        if token:
+            return None
+        auth = self.store.secret(f"device:{operation['operation_id']}")
+        if not auth or auth["expires_at"] <= time.time():
+            auth = self.start_auth(operation)
+        if time.time() >= auth["next_poll"]:
+            try:
+                tokens = self.raw("POST", f"{auth['issuer']}/oauth/token", data={
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "client_id": CLIENT_ID, "device_code": auth["device_code"],
+                })
+                self.remember_tokens(tokens)
+                self.store.secret(f"device:{operation['operation_id']}", None)
+                operation["status"] = "authorized"
+                self.store.save_operation(operation)
+                return None
+            except APIError as exc:
+                if exc.code == "slow_down":
+                    auth["interval"] += 5
+                elif exc.code == "access_denied":
+                    operation["status"] = "denied"
+                    self.store.save_operation(operation)
+                    self.store.secret(f"device:{operation['operation_id']}", None)
+                    raise
+                elif exc.code == "expired_token":
+                    auth = self.start_auth(operation)
+                elif exc.code != "authorization_pending":
+                    raise
+            auth["next_poll"] = time.time() + auth["interval"]
+            self.store.secret(f"device:{operation['operation_id']}", auth)
+        return {"status": "requires_authorization", "operation_id": operation["operation_id"],
+                "authorization": {"url": auth["verification_uri_complete"],
+                                  "user_code": auth["user_code"], "expires_at": auth["expires_at"]},
+                "next_action": {"command": f"pollaris operations resume {operation['operation_id']} --profile {self.store.profile} --wait --timeout 45 --json"}}
+
+    def advance(self, operation):
+        if operation.get("result"):
+            return operation["result"]
+        if operation["api_url"] != self.api_url:
+            raise LocalError("Operation belongs to another deployment")
+        if operation["status"] == "denied":
+            raise APIError("access_denied", "Authorization was declined; start a new request")
+        auth = self.authorization(operation)
+        if auth:
+            return auth
+        kind = operation["kind"]
+        if kind in {"login", "connect"}:
+            result = {"status": "completed", "connection": self.store.read("config")}
+            if kind == "connect":
+                from .connections import install
+                result.update(install(self.store, operation))
+        elif kind == "create":
+            if not operation.get("job_id"):
+                job = self.request("POST", "/v1/agent/form-jobs", json=operation["payload"],
+                    headers={"Idempotency-Key": operation["key"]})
+                operation["job_id"] = job["job_id"]
+                operation["status"] = "submitted"
+                self.store.save_operation(operation)
+            job = self.request("GET", f"/v1/agent/jobs/{operation['job_id']}")
+            if job["status"] == "requires_authorization":
+                # Refresh cannot restore a revoked grant. Resume after a new consent.
+                self.store.secret("tokens", None)
+                operation["needs_job_resume"] = True
+                self.store.save_operation(operation)
+                return self.authorization(operation)
+            if operation.pop("needs_job_resume", False):
+                job = self.request("POST", f"/v1/agent/jobs/{operation['job_id']}/resume")
+                self.store.save_operation(operation)
+            if job["status"] == "failed":
+                raise APIError(job["error"]["code"], job["error"]["message"], 422)
+            if job["status"] != "completed":
+                return {**job, "status": "pending", "operation_id": operation["operation_id"],
+                        "next_action": {"command": f"pollaris operations resume {operation['operation_id']} --profile {self.store.profile} --wait --timeout 45 --json"}}
+            result = {"status": "completed", "job_id": job["job_id"], **job["result"]}
+        else:
+            result = {"status": "completed", "data": self.request(
+                operation["method"], operation["path"], json=operation["payload"] or None,
+                headers={"Idempotency-Key": operation["key"]})}
+        operation["status"] = "completed"
+        operation["result"] = {"operation_id": operation["operation_id"], **result}
+        self.store.save_operation(operation)
+        return operation["result"]
+
+    def run(self, operation, wait=False, timeout=45):
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                result = self.advance(operation)
+            except APIError as exc:
+                if exc.status == 401 or exc.code in {"invalid_grant", "insufficient_scope"}:
+                    self.store.secret("tokens", None)
+                    result = self.authorization(operation)
+                else:
+                    raise
+            if not wait or result["status"] == "completed" or time.monotonic() >= deadline:
+                return result
+            time.sleep(min(2, max(0, deadline - time.monotonic())))

pollaris_cli-0.1.0/src/pollaris_cli/connections.py

@@ -0,0 +1,57 @@
+"""A bounded JSON MCP config adapter; existing entries are never overwritten."""
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+from .storage import LocalError, atomic_json
+
+
+def configuration(store):
+    return {"command": sys.executable, "args": ["-m", "pollaris_cli.main", "mcp", "serve",
+                                                 "--profile", store.profile]}
+
+
+def install(store, operation):
+    entry = configuration(store)
+    config_path = operation.get("config_file")
+    if not config_path:
+        return {"mcp_config": {"mcpServers": {"pollaris": entry}},
+                "installed": False, "message": "Pass --config-file to install in a JSON MCP host configuration"}
+    path = Path(config_path).expanduser().absolute()
+    if path.is_symlink():
+        raise LocalError("Refusing a symbolic-link config target")
+    existing = json.loads(path.read_text()) if path.exists() else {}
+    if not isinstance(existing, dict) or not isinstance(existing.get("mcpServers", {}), dict):
+        raise LocalError("Expected a JSON object with an mcpServers mapping")
+    servers = existing.setdefault("mcpServers", {})
+    if "pollaris" in servers and servers["pollaris"] != entry:
+        raise LocalError("A different Pollaris configuration exists; choose another config file")
+    backup = None
+    if path.exists() and servers.get("pollaris") != entry:
+        import uuid
+        backup = str(path) + f".pollaris-{uuid.uuid4().hex[:8]}.bak"
+        shutil.copy2(path, backup)
+    servers["pollaris"] = entry
+    atomic_json(path, existing)
+    store.write("mcp_install", {"path": str(path), "entry": entry})
+    return {"installed": True, "config_file": str(path), "backup": backup,
+            "reload_required": True, "mcp_config": {"mcpServers": {"pollaris": entry}}}
+
+
+def uninstall(store):
+    saved = store.read("mcp_install")
+    if not saved:
+        return {"removed": False}
+    path = Path(saved["path"])
+    data = json.loads(path.read_text())
+    if data.get("mcpServers", {}).get("pollaris") != saved["entry"]:
+        raise LocalError("The managed entry changed; it was not removed")
+    backup = str(path) + ".pollaris-disconnect.bak"
+    if Path(backup).exists():
+        raise LocalError("Disconnect backup already exists; preserve it before retrying")
+    shutil.copy2(path, backup)
+    del data["mcpServers"]["pollaris"]
+    atomic_json(path, data)
+    return {"removed": True, "backup": backup}

pollaris_cli-0.1.0/src/pollaris_cli/main.py

@@ -0,0 +1,220 @@
+"""Machine-readable commands and explicit, resumable browser authorization."""
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+from . import __version__
+from .client import APIError, CLIENT_ID, Client
+from .storage import LocalError, Store
+
+
+def parser():
+    p = argparse.ArgumentParser(prog="pollaris", description="Create and publish forms through your agent")
+    p.add_argument("--version", action="version", version=__version__)
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true")
+    common.add_argument("--profile", default="default")
+    common.add_argument("--api-url", default=os.getenv("POLLARIS_API_URL"))
+    common.add_argument("--non-interactive", action="store_true", help="Never prompt or open a browser (also the default)")
+    common.add_argument("--wait", action="store_true")
+    common.add_argument("--timeout", type=float, default=45)
+    groups = p.add_subparsers(dest="group", required=True)
+    for group, commands in {
+        "auth": ["login", "status", "logout"],
+        "forms": ["create", "get", "list", "validate", "save", "publish"],
+        "operations": ["resume"], "jobs": ["get", "wait", "resume"],
+        "workspaces": ["list", "use"], "connections": ["list", "revoke"],
+        "mcp": ["connect", "serve", "status", "disconnect"],
+    }.items():
+        subs = groups.add_parser(group).add_subparsers(dest="command", required=True)
+        for command in commands:
+            sub = subs.add_parser(command, parents=[common])
+            if (group == "forms" and command in {"get", "save", "publish"}) or group in {"jobs", "operations"} or (group == "workspaces" and command == "use") or (group == "connections" and command == "revoke"):
+                sub.add_argument("id")
+            if group == "forms" and command in {"create", "save", "publish"}:
+                sub.add_argument("--idempotency-key")
+            if group == "forms" and command in {"create", "save", "validate"}:
+                sub.add_argument("--definition", help="JSON definition file, or - for stdin")
+            if group == "forms" and command == "create":
+                sub.add_argument("--prompt")
+                sub.add_argument("--prompt-file")
+                sub.add_argument("--title")
+                modes = sub.add_mutually_exclusive_group()
+                modes.add_argument("--publish", action="store_true", default=True)
+                modes.add_argument("--draft-only", action="store_true")
+                sub.add_argument("--workspace")
+            if group == "forms" and command in {"save", "publish"}:
+                sub.add_argument("--expected-revision", required=True, type=int)
+            if group == "forms" and command == "list":
+                sub.add_argument("--after")
+                sub.add_argument("--limit", type=int, default=50)
+            if group == "mcp" and command == "connect":
+                sub.add_argument("--connection", required=True)
+                sub.add_argument("--config-file", help="Install into a JSON mcpServers config (for example Cursor)")
+                sub.add_argument("--workspace")
+    for command in ("capabilities", "doctor"):
+        groups.add_parser(command, parents=[common]).set_defaults(command=command)
+    return p
+
+
+def read_input(path):
+    return sys.stdin.read() if path == "-" else Path(path).read_text()
+
+
+def execute(args, store, client):
+    group, command = args.group, args.command
+    if group == "capabilities":
+        return {"status": "completed", "version": __version__, **client.discover()}
+    if group == "doctor":
+        return {"status": "completed", "api_url": client.api_url,
+                "server": client.discover(), "credential_store_available": store.secret("tokens") is not None}
+    if group == "operations":
+        return client.run(store.operation(args.id), args.wait, args.timeout)
+    if group == "auth" or (group == "mcp" and command == "status"):
+        if command == "status":
+            token = client.access_token()
+            return {"status": "completed" if token else "requires_authorization",
+                    "authenticated": token is not None, "profile": store.read("config", {})}
+        if command == "logout":
+            tokens = store.secret("tokens")
+            if tokens:
+                config = store.read("config")
+                client.raw("POST", f"{config['issuer']}/oauth/revoke",
+                           data={"client_id": CLIENT_ID, "token": tokens["refresh_token"]})
+                store.secret("tokens", None)
+            return {"status": "completed", "revoked": bool(tokens)}
+    if group == "mcp":
+        if command == "serve":
+            raise LocalError("MCP bridge must run outside the command lock")
+        if command == "disconnect":
+            from .connections import uninstall
+            tokens = store.secret("tokens")
+            if tokens:
+                config = store.read("config")
+                client.raw("POST", f"{config['issuer']}/oauth/revoke",
+                           data={"client_id": CLIENT_ID, "token": tokens["refresh_token"]})
+                store.secret("tokens", None)
+            return {"status": "completed", **uninstall(store)}
+        op = client.operation("connect", {"workspace_id": args.workspace}, resource="mcp",
+                              extras={"config_file": str(Path(args.config_file).expanduser().absolute()) if args.config_file else None})
+    elif group == "auth":
+        op = client.operation("login", {})
+    elif group == "forms" and command == "create":
+        prompt = read_input(args.prompt_file) if args.prompt_file else args.prompt
+        if sum(bool(x) for x in (args.prompt, args.prompt_file, args.definition)) != 1:
+            raise LocalError("Provide exactly one of --prompt, --prompt-file or --definition")
+        if prompt and not 10 <= len(prompt.strip()) <= 2000:
+            raise LocalError("Prompt must contain 10–2000 characters")
+        definition = json.loads(read_input(args.definition)) if args.definition else None
+        if definition is not None and not args.title:
+            raise LocalError("--title is required with --definition")
+        op = client.operation("create", {"prompt": prompt, "definition": definition,
+            "title": args.title, "workspace_id": args.workspace, "publish": not args.draft_only},
+            key=args.idempotency_key)
+    else:
+        method, payload = "GET", {}
+        path = f"/v1/agent/{group}"
+        if group == "forms":
+            if command == "list":
+                from urllib.parse import urlencode
+                path += "?" + urlencode({"limit": args.limit, **({"after": args.after} if args.after else {})})
+            elif command == "validate":
+                if not args.definition:
+                    raise LocalError("--definition is required")
+                method, path, payload = "POST", path + "/validate", json.loads(read_input(args.definition))
+            else:
+                path += f"/{args.id}"
+                if command in {"save", "publish"}:
+                    if args.expected_revision < 0:
+                        raise LocalError("Revision cannot be negative")
+                    method = "PUT" if command == "save" else "POST"
+                    path += "/draft" if command == "save" else "/publish"
+                    payload = {"expected_revision": args.expected_revision}
+                    if command == "save":
+                        if not args.definition:
+                            raise LocalError("--definition is required")
+                        payload["definition"] = json.loads(read_input(args.definition))
+        elif group == "jobs":
+            path += f"/{args.id}"
+            if command == "resume":
+                method, path = "POST", path + "/resume"
+        elif group == "connections" and command == "revoke":
+            method, path = "DELETE", path + f"/{args.id}"
+        elif group == "workspaces" and command == "use":
+            config = store.read("config", {})
+            if config.get("workspace_id") != args.id:
+                raise LocalError("Authorize a new profile for a different workspace")
+            return {"status": "completed", "workspace_id": args.id}
+        op = client.operation("request", payload, key=getattr(args, "idempotency_key", None),
+                              extras={"method": method, "path": path})
+    result = client.run(op, args.wait, args.timeout)
+    if group == "jobs" and command == "wait" and result["status"] == "completed":
+        deadline = time.monotonic() + args.timeout
+        job = result["data"]
+        while job["status"] in {"queued", "generating", "committing", "retry_wait"} and time.monotonic() < deadline:
+            time.sleep(min(2, max(0, deadline - time.monotonic())))
+            job = client.request("GET", f"/v1/agent/jobs/{args.id}")
+        if job["status"] == "failed":
+            raise APIError(job["error"]["code"], job["error"]["message"], 422)
+        return {"status": "completed" if job["status"] == "completed" else
+                "requires_authorization" if job["status"] == "requires_authorization" else "pending",
+                "data": job}
+    return result
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    result, code = None, 0
+    try:
+        if not 0 <= args.timeout <= 300:
+            raise LocalError("--timeout must be between 0 and 300 seconds")
+        profile = args.connection if args.group == "mcp" and args.command == "connect" else args.profile
+        store = Store(profile)
+        client = Client(store, args.api_url)
+        if args.group == "mcp" and args.command == "serve":
+            from .bridge import serve
+            import asyncio
+            asyncio.run(serve(store, args.api_url))
+            return 0
+        with store.lock:
+            result = execute(args, store, client)
+        code = {"requires_authorization": 10, "pending": 11}.get(result["status"], 0)
+    except APIError as exc:
+        code = 12 if exc.code == "access_denied" else (
+            13 if exc.status in {401, 403} or exc.code in {"invalid_grant", "expired_token"} else
+            21 if exc.status == 409 else 22 if exc.status == 429 else 20 if exc.status == 422 else 30)
+        result = {"status": "error", "error": {"code": exc.code, "message": exc.message,
+                    "retryable": code in {22, 30}}}
+    except (LocalError, OSError, ValueError, ImportError) as exc:
+        code = 31
+        result = {"status": "error", "error": {"code": "local_error", "message": str(exc), "retryable": False}}
+    except httpx.HTTPError:
+        code = 30
+        result = {"status": "error", "error": {"code": "network_error", "message": "Unable to reach Pollaris; retry the saved operation", "retryable": True}}
+    except KeyboardInterrupt:
+        code = 11
+        result = {"status": "pending", "message": "Interrupted; the saved operation can be resumed"}
+    if args.group == "mcp" and args.command == "serve":
+        # Even startup errors must never corrupt the MCP stdout channel.
+        print(json.dumps({"schema_version": "1", **result}), file=sys.stderr)
+    elif args.json:
+        print(json.dumps({"schema_version": "1", **result}))
+    else:
+        if result.get("authorization"):
+            print(f"Authorize Pollaris: {result['authorization']['url']}")
+            print(result["next_action"]["command"])
+        elif result.get("form", {}).get("public_url"):
+            print(result["form"]["public_url"])
+        else:
+            print(json.dumps(result, indent=2))
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pollaris_cli-0.1.0/src/pollaris_cli/storage.py

@@ -0,0 +1,131 @@
+"""Atomic local state and OS-keychain credentials, serialized per profile."""
+
+import hashlib
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+
+class LocalError(ValueError):
+    pass
+
+
+class ProcessLock:
+    """Small cross-platform advisory lock with a context-manager API."""
+
+    def __init__(self, path):
+        self.path = path
+        self.stream = None
+
+    def __enter__(self):
+        self.stream = open(self.path, "a+")
+        if os.name == "nt":
+            import msvcrt
+            self.stream.seek(0)
+            msvcrt.locking(self.stream.fileno(), msvcrt.LK_LOCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(self.stream, fcntl.LOCK_EX)
+        return self
+
+    def __exit__(self, *_):
+        if os.name == "nt":
+            import msvcrt
+            self.stream.seek(0)
+            msvcrt.locking(self.stream.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(self.stream, fcntl.LOCK_UN)
+        self.stream.close()
+
+
+def atomic_json(path: Path, data):
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=".pollaris-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w") as stream:
+            json.dump(data, stream, indent=2)
+            stream.write("\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+class Store:
+    def __init__(self, profile="default", root=None, secrets_backend=None):
+        if not re.fullmatch(r"[a-zA-Z0-9_-]{1,64}", profile):
+            raise LocalError("Profile/connection names must use letters, digits, underscores or hyphens")
+        base = Path(root or os.environ.get("POLLARIS_CLI_HOME") or Path.home() / ".config/pollaris")
+        self.root = base / profile
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.profile = profile
+        self.lock = ProcessLock(self.root / ".lock")
+        self.backend = secrets_backend
+
+    def read(self, name, default=None):
+        path = self.root / f"{name}.json"
+        if not path.exists():
+            return default
+        return json.loads(path.read_text())
+
+    def write(self, name, value):
+        atomic_json(self.root / f"{name}.json", value)
+
+    def operation(self, operation_id):
+        if not re.fullmatch(r"[a-f0-9-]{36}", operation_id):
+            raise LocalError("Invalid operation ID")
+        value = self.read(f"operations/{operation_id}")
+        if value is None:
+            raise LocalError("Operation not found in this profile")
+        return value
+
+    def save_operation(self, operation):
+        self.write(f"operations/{operation['operation_id']}", operation)
+
+    def secret(self, name, value=...):
+        """An explicit Fernet key enables encrypted file storage on headless hosts."""
+        key = os.environ.get("POLLARIS_CLI_SECRET_KEY")
+        if key and self.backend is None:
+            from cryptography.fernet import Fernet
+            try:
+                cipher = Fernet(key.encode())
+                path = self.root / (hashlib.sha256(name.encode()).hexdigest() + ".secret.json")
+                if value is ...:
+                    if not path.exists():
+                        return None
+                    return json.loads(cipher.decrypt(json.loads(path.read_text())["ciphertext"].encode()))
+                if value is None:
+                    path.unlink(missing_ok=True)
+                else:
+                    atomic_json(path, {"ciphertext": cipher.encrypt(json.dumps(value).encode()).decode()})
+                return None
+            except Exception as exc:
+                raise LocalError("Unable to use encrypted credential store; check POLLARIS_CLI_SECRET_KEY") from exc
+        try:
+            backend = self.backend
+            if backend is None:
+                import keyring
+                backend = keyring
+                implementation = keyring.get_keyring()
+                # Reject third-party plaintext fallback backends.
+                if not type(implementation).__module__.startswith((
+                    "keyring.backends.macOS", "keyring.backends.Windows", "keyring.backends.SecretService",
+                    "keyring.backends.kwallet",
+                )):
+                    raise LocalError("No supported OS keychain")
+            account = f"{self.root.resolve()}:{name}"
+            if value is ...:
+                raw = backend.get_password("pollaris-cli", account)
+                return json.loads(raw) if raw else None
+            if value is None:
+                if backend.get_password("pollaris-cli", account):
+                    backend.delete_password("pollaris-cli", account)
+            else:
+                backend.set_password("pollaris-cli", account, json.dumps(value))
+            return None
+        except Exception as exc:
+            raise LocalError("Configure an OS keychain or supply POLLARIS_CLI_SECRET_KEY for encrypted headless storage") from exc

pollaris_cli-0.1.0/src/pollaris_cli.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: pollaris-cli
+Version: 0.1.0
+Summary: Agent-friendly Pollaris CLI and MCP bridge
+Project-URL: Repository, https://github.com/devsapariya94/Pollaris
+Project-URL: Documentation, https://github.com/devsapariya94/Pollaris/blob/main/cli/README.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25
+Requires-Dist: cryptography>=43
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# Pollaris CLI
+
+Create and publish Pollaris forms from terminal-capable agents. The CLI starts a
+browser authorization flow when needed, preserves the original operation, and resumes
+it after the user grants access. It returns an authorization URL; it does not open
+a browser automatically.
+
+Development install from the repository root:
+
+```bash
+uv tool install --editable ./cli
+```
+
+For package publication and production testing, see [publishing](PUBLISHING.md).
+
+For the optional local MCP bridge, include its dependencies:
+
+```bash
+uv tool install --editable './cli[mcp]'
+```
+
+Point the CLI at an agent-enabled deployment (see [server setup](../docs/mcp/agent-access.md)):
+
+```bash
+export POLLARIS_API_URL=https://api.example.com
+pollaris capabilities --json
+```
+
+Create a form:
+
+```bash
+pollaris forms create \
+  --prompt "Create a short library feedback form" \
+  --publish \
+  --wait \
+  --json
+```
+
+When the command returns `requires_authorization`, open `authorization.url` and
+run the returned `next_action.command`. The finished result contains
+`form.public_url`.
+
+Creation publishes by default. Use `--draft-only` to create an editable draft.
+`--wait` polls for completion up to `--timeout` seconds (default: 45); a pending
+job can be checked with `pollaris jobs get JOB_ID --json` or
+`pollaris jobs wait JOB_ID --json`.
+
+To update or publish an existing form, inspect it first with
+`pollaris forms get FORM_ID --json`, then pass its current `draft_revision` as
+`--expected-revision` to `forms save` or `forms publish`. Saving also requires
+`--definition path/to/definition.json`.
+
+Use `pollaris --help` and each command's `--help` for options. Credentials use an
+OS keychain, or encrypted file storage configured by `POLLARIS_CLI_SECRET_KEY`
+(a Fernet key) on headless hosts. Local state defaults to `~/.config/pollaris`;
+`POLLARIS_CLI_HOME` overrides it and `--profile` selects a separate profile.
+
+See [OAuth agent access](../docs/mcp/agent-access.md), [MCP tools](../docs/mcp/tools.md),
+and the [integration index](../docs/README.md) for deployment and connection guides.

pollaris_cli-0.1.0/src/pollaris_cli.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/pollaris_cli/__init__.py
+src/pollaris_cli/bridge.py
+src/pollaris_cli/client.py
+src/pollaris_cli/connections.py
+src/pollaris_cli/main.py
+src/pollaris_cli/storage.py
+src/pollaris_cli.egg-info/PKG-INFO
+src/pollaris_cli.egg-info/SOURCES.txt
+src/pollaris_cli.egg-info/dependency_links.txt
+src/pollaris_cli.egg-info/entry_points.txt
+src/pollaris_cli.egg-info/requires.txt
+src/pollaris_cli.egg-info/top_level.txt
+tests/test_cli.py

pollaris_cli-0.1.0/src/pollaris_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pollaris_cli-0.1.0/src/pollaris_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pollaris = pollaris_cli.main:main

pollaris_cli-0.1.0/src/pollaris_cli.egg-info/requires.txt

@@ -0,0 +1,9 @@
+httpx>=0.27
+keyring>=25
+cryptography>=43
+
+[dev]
+pytest>=8
+
+[mcp]
+mcp<3,>=2

pollaris_cli-0.1.0/src/pollaris_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+pollaris_cli

pollaris_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,157 @@
+import json
+
+import pytest
+import httpx
+
+from pollaris_cli.client import APIError, Client
+from pollaris_cli.connections import install, uninstall
+from pollaris_cli.main import execute, parser
+from pollaris_cli.storage import LocalError, Store
+
+
+class MemorySecrets:
+    values = {}
+
+    @classmethod
+    def get_password(cls, service, account):
+        return cls.values.get((service, account))
+
+    @classmethod
+    def set_password(cls, service, account, value):
+        cls.values[(service, account)] = value
+
+    @classmethod
+    def delete_password(cls, service, account):
+        del cls.values[(service, account)]
+
+
+def test_agent_create_command_contract():
+    args = parser().parse_args([
+        "forms", "create", "--prompt", "Create a library feedback form",
+        "--draft-only", "--json",
+    ])
+    assert args.group == "forms"
+    assert args.command == "create"
+    assert args.draft_only is True
+
+
+def test_secret_and_operation_storage(tmp_path):
+    store = Store("agent-one", tmp_path, MemorySecrets)
+    store.secret("tokens", {"refresh_token": "secret"})
+    assert store.secret("tokens") == {"refresh_token": "secret"}
+    operation = {"operation_id": "00000000-0000-0000-0000-000000000001", "status": "prepared"}
+    store.save_operation(operation)
+    assert store.operation(operation["operation_id"])["status"] == "prepared"
+    assert "secret" not in "".join(path.read_text() for path in tmp_path.rglob("*.json"))
+
+
+def test_mcp_config_merge_and_guarded_removal(tmp_path):
+    store = Store("agent-two", tmp_path / "state", MemorySecrets)
+    config = tmp_path / "mcp.json"
+    config.write_text(json.dumps({"mcpServers": {"existing": {"command": "safe"}}}))
+    result = install(store, {"config_file": str(config)})
+    assert result["installed"] is True
+    assert json.loads(config.read_text())["mcpServers"]["existing"] == {"command": "safe"}
+    assert uninstall(store)["removed"] is True
+    assert "pollaris" not in json.loads(config.read_text())["mcpServers"]
+
+
+def test_mcp_config_refuses_an_existing_different_entry(tmp_path):
+    store = Store("agent-three", tmp_path / "state", MemorySecrets)
+    config = tmp_path / "mcp.json"
+    config.write_text(json.dumps({"mcpServers": {"pollaris": {"command": "other"}}}))
+    with pytest.raises(LocalError, match="different Pollaris"):
+        install(store, {"config_file": str(config)})
+
+
+def test_idempotency_key_cannot_target_a_different_form(tmp_path):
+    store = Store("default", tmp_path, MemorySecrets)
+    client = Client(store)
+    client.operation("request", {"expected_revision": 1}, key="same-key",
+                     extras={"method": "POST", "path": "/v1/agent/forms/one/publish"})
+    with pytest.raises(APIError, match="different input"):
+        client.operation("request", {"expected_revision": 1}, key="same-key",
+                         extras={"method": "POST", "path": "/v1/agent/forms/two/publish"})
+
+
+def test_mcp_config_refuses_symlink(tmp_path):
+    store = Store("default", tmp_path / "state", MemorySecrets)
+    target = tmp_path / "target.json"
+    target.write_text('{}')
+    link = tmp_path / "link.json"
+    link.symlink_to(target)
+    with pytest.raises(LocalError, match="symbolic-link"):
+        install(store, {"config_file": str(link)})
+    assert target.read_text() == '{}'
+
+
+@pytest.mark.parametrize("status", ["failed", "requires_authorization", "queued", "completed"])
+def test_job_wait_terminal_status(tmp_path, status):
+    class JobClient:
+        def operation(self, *args, **kwargs):
+            return {}
+
+        def run(self, *args):
+            return {"status": "completed", "data": {
+                "status": status, "error": {"code": "generation_failed", "message": "Failed"}}}
+
+    args = parser().parse_args(["jobs", "wait", "job-one", "--timeout", "0", "--json"])
+    if status == "failed":
+        with pytest.raises(APIError, match="Failed"):
+            execute(args, Store(root=tmp_path), JobClient())
+    else:
+        result = execute(args, Store(root=tmp_path), JobClient())
+        assert result["status"] == ("pending" if status == "queued" else status)
+
+
+def test_create_authorize_restart_publish_and_replay(tmp_path):
+    calls = []
+
+    def server(request):
+        calls.append(request)
+        path = request.url.path
+        if path == "/v1/agent/capabilities":
+            data = {"issuer": "http://localhost:8000", "resource": "http://localhost:8000/v1/agent",
+                    "mcp_url": "http://localhost:8002/mcp"}
+        elif path == "/oauth/device_authorization":
+            data = {"device_code": "private-device-code", "user_code": "ABCD-EFGH",
+                    "verification_uri_complete": "http://localhost:3000/connect/device?user_code=ABCD-EFGH",
+                    "expires_in": 600, "interval": 5}
+        elif path == "/oauth/token":
+            data = {"access_token": "private-access", "refresh_token": "private-refresh",
+                    "expires_in": 900, "resource": "http://localhost:8000/v1/agent",
+                    "workspace_id": "workspace-one", "connection_id": "connection-one"}
+        elif path == "/v1/agent/form-jobs":
+            assert request.headers["Idempotency-Key"] == "library-feedback"
+            assert json.loads(request.content)["publish"] is True
+            data = {"job_id": "job-one", "status": "queued"}
+        elif path == "/v1/agent/jobs/job-one":
+            if sum(r.url.path == path for r in calls) == 1:
+                return httpx.Response(200, json={"job_id": "job-one", "status": "queued"})
+            data = {"job_id": "job-one", "status": "completed", "result": {
+                "form": {"id": "form-one", "public_url": "https://forms.example.com/f/library"}}}
+        else:
+            raise AssertionError(path)
+        return httpx.Response(200, json=data)
+
+    store = Store("default", tmp_path, MemorySecrets)
+    http = httpx.Client(transport=httpx.MockTransport(server))
+    client = Client(store, http=http)
+    operation = client.operation("create", {"prompt": "Create a library feedback form", "publish": True},
+                                 key="library-feedback")
+    first = client.run(operation)
+    assert first["status"] == "requires_authorization"
+    assert "private-" not in json.dumps(first)
+    auth = store.secret(f"device:{operation['operation_id']}")
+    auth["next_poll"] = 0
+    store.secret(f"device:{operation['operation_id']}", auth)
+    restarted = Client(Store("default", tmp_path, MemorySecrets), http=http)
+    pending = restarted.run(store.operation(operation["operation_id"]))
+    assert pending["status"] == "pending"
+    assert pending["job_id"] == "job-one"
+    result = restarted.run(store.operation(operation["operation_id"]))
+    assert result["status"] == "completed"
+    assert result["form"]["public_url"].endswith("/f/library")
+    assert restarted.run(store.operation(operation["operation_id"])) == result
+    assert sum(r.url.path == "/v1/agent/form-jobs" for r in calls) == 1
+    assert "private-" not in "".join(p.read_text() for p in tmp_path.rglob("*.json"))