mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/plugins/__init__.py

@@ -0,0 +1,3 @@
+"""Plugins: a folder in the Claude Code plugin layout that adds connectors (its .mcp.json), skills (skills/*/SKILL.md),
+workflows (mobster/workflows) and destinations (mobster/destinations) to Mobster for Mac. A plugin is data: its MCP
+servers are connectors, each its own process, so a plugin can't bypass an approval, the journal or the device lock."""

mobile_agent/plugins/install.py

@@ -0,0 +1,163 @@
+"""Where a plugin comes from: a folder on this Mac, a ``.zip``, or a GitHub repository (``owner/repo`` or
+``owner/repo@ref``, downloaded as GitHub's tarball over https)."""
+
+import io
+import os
+import re
+import shutil
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path, PurePosixPath
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .. import __version__
+from .manifest import PluginError
+
+MAX_FILES = 2000
+MAX_BYTES = 50 * 1024 * 1024
+MAX_ARCHIVE = 20 * 1024 * 1024
+REPO = re.compile(r"(?:https://github\.com/)?([A-Za-z0-9][A-Za-z0-9-]{0,38})/([A-Za-z0-9._-]{1,100}?)(?:\.git)?"
+                  r"(?:@([A-Za-z0-9._/-]{1,100}))?/?")
+SKIP = {".git", "node_modules", "__pycache__", ".DS_Store"}
+
+
+def staging():
+    """A fresh folder each source is copied into first, so what is read, shown and installed is one fixed copy."""
+    return Path(tempfile.mkdtemp(prefix="mobster-plugin-"))
+
+
+def _safe_name(name):
+    """``name`` as a relative path inside the archive, or None for one that would land outside it."""
+    path = PurePosixPath(name.replace("\\", "/"))
+    if path.is_absolute() or any(part == ".." for part in path.parts) or not path.parts:
+        return None
+    return Path(*path.parts)
+
+
+def _budget():
+    return {"files": 0, "bytes": 0}
+
+
+def _count(budget, size):
+    budget["files"] += 1
+    budget["bytes"] += size
+    if budget["files"] > MAX_FILES:
+        raise PluginError(f"This plugin has more than {MAX_FILES} files.")
+    if budget["bytes"] > MAX_BYTES:
+        raise PluginError("This plugin is larger than 50 MB unpacked.")
+
+
+def from_folder(path, into):
+    source = Path(os.path.expanduser(str(path))).resolve()
+    if not source.is_dir():
+        raise PluginError("There's no folder at that path. Check it and try again.")
+    budget = _budget()
+    for folder, dirs, files in os.walk(source):
+        dirs[:] = [d for d in dirs if d not in SKIP and not os.path.islink(os.path.join(folder, d))]
+        for name in files:
+            file = Path(folder) / name
+            if name in SKIP or file.is_symlink() or not file.is_file():
+                continue
+            _count(budget, file.stat().st_size)
+            target = into / file.relative_to(source)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(file, target)
+    return root_of(into)
+
+
+def from_zip(data, into):
+    if len(data) > MAX_ARCHIVE:
+        raise PluginError("This archive is larger than 20 MB.")
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(data))
+    except zipfile.BadZipFile:
+        raise PluginError("That file isn't a zip archive.") from None
+    budget = _budget()
+    with archive:
+        for info in archive.infolist():
+            if info.is_dir():
+                continue
+            relative = _safe_name(info.filename)
+            if relative is None:
+                raise PluginError("This archive has a file that would land outside its folder, so Mobster refused it.")
+            mode = (info.external_attr >> 16) & 0o170000
+            if mode and mode != 0o100000:
+                raise PluginError("This archive has a link or a special file, so Mobster refused it.")
+            if relative.parts[0] in SKIP or relative.name in SKIP:
+                continue
+            _count(budget, info.file_size)
+            target = into / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            with archive.open(info) as stream, open(target, "wb") as out:
+                out.write(stream.read(MAX_BYTES + 1))
+    return root_of(into)
+
+
+def from_tar(data, into):
+    if len(data) > MAX_ARCHIVE:
+        raise PluginError("This archive is larger than 20 MB.")
+    try:
+        archive = tarfile.open(fileobj=io.BytesIO(data), mode="r:*")
+    except tarfile.TarError:
+        raise PluginError("GitHub's download isn't an archive Mobster can read.") from None
+    budget = _budget()
+    with archive:
+        for member in archive.getmembers():
+            if member.isdir() or member.type == tarfile.XGLTYPE or member.type == tarfile.XHDTYPE:
+                continue
+            relative = _safe_name(member.name)
+            if relative is None:
+                raise PluginError("This archive has a file that would land outside its folder, so Mobster refused it.")
+            if not member.isfile():
+                continue  # links and special files are left out
+            if any(part in SKIP for part in relative.parts):
+                continue
+            _count(budget, member.size)
+            target = into / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            stream = archive.extractfile(member)
+            with open(target, "wb") as out:
+                out.write(stream.read(MAX_BYTES + 1) if stream else b"")
+    return root_of(into)
+
+
+def parse_repo(text):
+    """(owner, repo, ref) from ``owner/repo``, ``owner/repo@ref`` or a github.com URL; PluginError otherwise."""
+    match = REPO.fullmatch(str(text or "").strip())
+    if not match:
+        raise PluginError("Write a GitHub repository as owner/repo, or owner/repo@branch.")
+    return match.group(1), match.group(2), match.group(3) or "HEAD"
+
+
+def download(url, opener=None):
+    if not url.startswith("https://"):
+        raise PluginError("Mobster downloads plugins over https only.")
+    request = Request(url, headers={"User-Agent": f"Mobster/{__version__}"})
+    try:
+        with (opener or urlopen)(request, timeout=30) as response:
+            data = response.read(MAX_ARCHIVE + 1)
+    except HTTPError as error:
+        if error.code == 404:
+            raise PluginError("GitHub has no such repository, or it's private.") from None
+        raise PluginError(f"GitHub answered HTTP {error.code}. Try again.") from None
+    except (URLError, OSError):
+        raise PluginError("Mobster couldn't reach GitHub. Check this Mac's connection, then try again.") from None
+    return data
+
+
+def from_github(text, into, opener=None):
+    owner, repo, ref = parse_repo(text)
+    data = download(f"https://codeload.github.com/{owner}/{repo}/tar.gz/{ref}", opener)
+    return from_tar(data, into)
+
+
+def root_of(folder):
+    """The folder holding .claude-plugin/plugin.json: ``folder``, or the one folder inside it."""
+    if (folder / ".claude-plugin" / "plugin.json").is_file():
+        return folder
+    inside = [p for p in folder.iterdir() if p.is_dir()]
+    if len(inside) == 1 and (inside[0] / ".claude-plugin" / "plugin.json").is_file():
+        return inside[0]
+    raise PluginError("This isn't a plugin: it has no .claude-plugin/plugin.json.")

mobile_agent/plugins/manifest.py

@@ -0,0 +1,242 @@
+"""Read a plugin folder: the Claude Code plugin layout, so one folder works in Claude Code and in Mobster."""
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import jsonschema
+import yaml
+
+NAME = r"^[a-z0-9][a-z0-9-]{0,47}$"
+MAX_SKILLS, MAX_WORKFLOWS, MAX_DESTINATIONS, MAX_SERVERS = 20, 20, 10, 10
+SKILL_CHARS = 20_000           # a SKILL.md longer than this is refused
+JSON_BYTES = 256_000
+PLACEHOLDER = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]{0,63})\}")
+ROOT_VARIABLE = "CLAUDE_PLUGIN_ROOT"
+RESERVED = frozenset({"preview", "preview-zip", "install"})   # /api/plugins/<name> would read as these routes
+
+MANIFEST = {"type": "object", "required": ["name"], "properties": {
+    "name": {"type": "string", "pattern": NAME},
+    "version": {"type": "string", "maxLength": 40},
+    "description": {"type": "string", "maxLength": 500},
+    "author": {"anyOf": [{"type": "string", "maxLength": 200},
+                         {"type": "object", "properties": {"name": {"type": "string", "maxLength": 200}}}]},
+    "homepage": {"type": "string", "maxLength": 500}}}
+SERVER = {"type": "object", "oneOf": [
+    {"required": ["command"], "properties": {
+        "type": {"enum": ["stdio"]}, "command": {"type": "string", "minLength": 1, "maxLength": 1000},
+        "args": {"type": "array", "maxItems": 40, "items": {"type": "string", "maxLength": 1000}},
+        "env": {"type": "object", "maxProperties": 20, "additionalProperties": {"type": "string", "maxLength": 4000}}}},
+    {"required": ["url"], "properties": {
+        "type": {"enum": ["http", "streamable-http"]}, "url": {"type": "string", "maxLength": 2000},
+        "headers": {"type": "object", "maxProperties": 10,
+                    "additionalProperties": {"type": "string", "maxLength": 8000}}}}]}
+MCP = {"type": "object", "required": ["mcpServers"], "properties": {
+    "mcpServers": {"type": "object", "maxProperties": MAX_SERVERS,
+                   "propertyNames": {"pattern": r"^[A-Za-z0-9][A-Za-z0-9 _.-]{0,39}$"},
+                   "additionalProperties": SERVER}}}
+WORKFLOW = {"type": "object", "required": ["name", "goal"], "properties": {
+    "name": {"type": "string", "minLength": 1, "maxLength": 120},
+    "goal": {"type": "string", "minLength": 1, "maxLength": 4000},
+    "appId": {"type": ["string", "null"], "maxLength": 200}, "appName": {"type": ["string", "null"], "maxLength": 120},
+    "engine": {"type": ["string", "null"]}, "outputFormat": {"type": "string"}, "outputSchema": {},
+    "cron": {"type": ["string", "null"], "maxLength": 100}, "timezone": {"type": "string", "maxLength": 64},
+    "enabled": {"type": "boolean"},
+    # The result blocks it hands back (docs/results.mdx), shown on the Apps page as a preview.
+    "produces": {"type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": True,
+                 "items": {"enum": ["review_queue", "table", "media_list", "evidence", "checklist", "markdown",
+                                    "chart"]}}}}
+DESTINATION = {"type": "object", "required": ["name", "url"], "properties": {
+    "name": {"type": "string", "minLength": 1, "maxLength": 60}, "url": {"type": "string", "maxLength": 2000},
+    "secret": {"type": "string", "maxLength": 200}, "screenshot": {"type": "boolean"}}}
+# What a plugin's workflow keeps of its file: never a device, an account or a destination of this Mac.
+WORKFLOW_FIELDS = ("name", "goal", "appId", "appName", "engine", "outputFormat", "outputSchema", "cron", "timezone",
+                   "produces")
+
+
+class PluginError(ValueError):
+    """A plugin that can't be installed, with one sentence that says why."""
+
+
+@dataclass
+class Plugin:
+    name: str
+    version: str
+    description: str
+    root: Path
+    author: str = ""                                   # who makes it, from plugin.json's author (a name, or {"name"})
+    # {"name", "transport", "command"?, "args"?, "env"?, "url"?, "token"?}
+    servers: list = field(default_factory=list)
+    skills: list = field(default_factory=list)         # {"name", "description", "file", "chars"}
+    workflows: list = field(default_factory=list)      # create bodies (enabled false)
+    destinations: list = field(default_factory=list)   # {"name", "url", "secret"?, "screenshot"?}
+    asks: list = field(default_factory=list)           # {"key", "label", "secret"}
+
+    def summary(self):
+        """What the API shows before and after install: never a value."""
+        return {"name": self.name, "version": self.version, "description": self.description, "author": self.author,
+                "connectors": [{"name": s["name"], "transport": s["transport"],
+                                "where": s.get("url") or " ".join([Path(s["command"]).name, *s.get("args", ())])[:300]}
+                               for s in self.servers],
+                "skills": [{"name": s["name"], "description": s["description"]} for s in self.skills],
+                "workflows": [{"name": w["name"], "goal": w["goal"][:300],
+                               **({"produces": w["produces"]} if w.get("produces") else {})} for w in self.workflows],
+                "destinations": [{"name": d["name"]} for d in self.destinations],
+                "asks": list(self.asks)}
+
+
+def _json(path, schema, what):
+    try:
+        if path.stat().st_size > JSON_BYTES:
+            raise PluginError(f"{what} is too large.")
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError):
+        raise PluginError(f"Mobster couldn't read {what}.") from None
+    except ValueError:
+        raise PluginError(f"{what} isn't valid JSON.") from None
+    try:
+        jsonschema.validate(value, schema)
+    except jsonschema.ValidationError as error:
+        where = "/".join(str(p) for p in error.absolute_path)
+        raise PluginError(f"{what} doesn't fit the plugin format" + (f" at {where}" if where else "") + ".") from None
+    return value
+
+
+def frontmatter(text):
+    """({key: value}, body) of a SKILL.md: a leading ``---`` block."""
+    if not text.startswith("---"):
+        return {}, text
+    end = text.find("\n---", 3)
+    if end < 0:
+        return {}, text
+    block, body = text[3:end], text[end + 4:].lstrip("\n")
+    try:
+        loaded = yaml.safe_load(block)
+    except yaml.YAMLError:
+        loaded = None
+    if isinstance(loaded, dict):
+        return {str(key).strip().lower(): str(value).strip() for key, value in loaded.items()
+                if isinstance(value, (str, int, float))}, body
+    meta = {}
+    for line in block.splitlines():
+        key, sep, value = line.partition(":")
+        if sep and key.strip():
+            meta[key.strip().lower()] = value.strip().strip('"').strip("'")
+    return meta, body
+
+
+def _ask(asks, key, label, secret):
+    if not any(a["key"] == key for a in asks):
+        asks.append({"key": key, "label": label, "secret": secret})
+
+
+def _placeholders(value, asks, label, secret=True):
+    for name in PLACEHOLDER.findall(value):
+        if name != ROOT_VARIABLE:
+            _ask(asks, name, label, secret)
+
+
+
+def _author(value):
+    """plugin.json's author as one line: the string itself, or the object's name. Empty when it names no one."""
+    name = value.get("name") if isinstance(value, dict) else value
+    return " ".join(str(name or "").split())[:200]
+
+def read(root):
+    root = Path(root)
+    manifest_path = root / ".claude-plugin" / "plugin.json"
+    if not manifest_path.is_file():
+        raise PluginError("This isn't a plugin: it has no .claude-plugin/plugin.json.")
+    manifest = _json(manifest_path, MANIFEST, "plugin.json")
+    if manifest["name"] in RESERVED:
+        raise PluginError(f"A plugin can't be called {manifest['name']}. Rename it in plugin.json.")
+    plugin = Plugin(name=manifest["name"], version=str(manifest.get("version") or ""),
+                    description=" ".join(str(manifest.get("description") or "").split()), root=root,
+                    author=_author(manifest.get("author")))
+
+    mcp_path = root / ".mcp.json"
+    if mcp_path.is_file():
+        servers = _json(mcp_path, MCP, ".mcp.json")["mcpServers"]
+        for key, spec in servers.items():
+            if "command" in spec:
+                env = dict(spec.get("env") or {})
+                for name, value in env.items():
+                    if not re.fullmatch(r"[A-Z_][A-Z0-9_]{0,63}", name):
+                        raise PluginError(f"{key}'s environment name {name[:40]} isn't in capitals.")
+                    _placeholders(value, plugin.asks, f"Used by the connector {key}")
+                for arg in [spec["command"], *spec.get("args", ())]:
+                    _placeholders(arg, plugin.asks, f"Used by the connector {key}")
+                plugin.servers.append({"name": key, "transport": "stdio", "command": spec["command"],
+                                       "args": list(spec.get("args", ())), "env": env})
+            else:
+                headers = dict(spec.get("headers") or {})
+                token = None
+                for header, value in headers.items():
+                    if header.lower() != "authorization":
+                        raise PluginError(f"{key} sends a {header[:40]} header; Mobster sends only Authorization.")
+                    match = re.fullmatch(r"\s*Bearer\s+(\S+)\s*", value)
+                    if not match:
+                        raise PluginError(f"{key}'s Authorization header must be Bearer and a token.")
+                    token = match.group(1)
+                    _placeholders(token, plugin.asks, f"Used by the connector {key}")
+                if PLACEHOLDER.search(spec["url"]):
+                    raise PluginError(f"{key}'s URL can't hold a ${{…}} value. Put the secret in its token.")
+                plugin.servers.append({"name": key, "transport": "http", "url": spec["url"], "token": token})
+
+    skills_dir = root / "skills"
+    if skills_dir.is_dir():
+        for folder in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
+            file = folder / "SKILL.md"
+            if not file.is_file():
+                continue
+            try:
+                text = file.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                raise PluginError(f"Mobster couldn't read skills/{folder.name}/SKILL.md.") from None
+            if len(text) > SKILL_CHARS:
+                raise PluginError(f"skills/{folder.name}/SKILL.md is longer than {SKILL_CHARS:,} characters.")
+            meta, body = frontmatter(text)
+            description = " ".join(meta.get("description", "").split())
+            if not description:
+                raise PluginError(f"skills/{folder.name}/SKILL.md needs a description in its frontmatter.")
+            plugin.skills.append({"name": (meta.get("name") or folder.name)[:60], "description": description[:500],
+                                  "file": str(file.relative_to(root)), "chars": len(body)})
+        if len(plugin.skills) > MAX_SKILLS:
+            raise PluginError(f"A plugin has at most {MAX_SKILLS} skills.")
+
+    for kind, schema, limit, target in (("workflows", WORKFLOW, MAX_WORKFLOWS, plugin.workflows),
+                                         ("destinations", DESTINATION, MAX_DESTINATIONS, plugin.destinations)):
+        folder = root / "mobster" / kind
+        if not folder.is_dir():
+            continue
+        files = sorted(folder.glob("*.json"))
+        if len(files) > limit:
+            raise PluginError(f"A plugin has at most {limit} {kind}.")
+        for file in files:
+            value = _json(file, schema, f"mobster/{kind}/{file.name}")
+            if kind == "workflows":
+                target.append({k: value[k] for k in WORKFLOW_FIELDS if k in value})
+            else:
+                if PLACEHOLDER.search(value["name"]):
+                    raise PluginError(f"mobster/destinations/{file.name}'s name can't hold a ${{…}} value.")
+                _placeholders(value["url"], plugin.asks, f"Used by the destination {value['name']}")
+                if value.get("secret"):
+                    _placeholders(value["secret"], plugin.asks, f"Used by the destination {value['name']}")
+                target.append({k: value[k] for k in ("name", "url", "secret", "screenshot") if k in value})
+
+    if not (plugin.servers or plugin.skills or plugin.workflows or plugin.destinations):
+        raise PluginError("This plugin adds nothing Mobster uses: no MCP servers, skills, workflows or destinations.")
+    return plugin
+
+
+def fill(text, values, root):
+    """``text`` with ``${NAME}`` replaced by the value given at install, and ``${CLAUDE_PLUGIN_ROOT}`` by ``root``."""
+    def one(match):
+        name = match.group(1)
+        if name == ROOT_VARIABLE:
+            return str(root)
+        if name not in values or not isinstance(values[name], str) or not values[name].strip():
+            raise PluginError(f"Fill in {name} to install this plugin.")
+        return values[name].strip()
+    return PLACEHOLDER.sub(one, text)

mobile_agent/plugins/register.py

@@ -0,0 +1,15 @@
+"""Track ``plugins``' registrations (tracks.load calls ``register(api)`` once per process, staged)."""
+
+from . import routes, service, skills
+
+PROVIDER_ORDER = 45
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    from .. import journal
+    from . import store
+    journal.register_schema(store.SCHEMA, store.VERSION, store.migrate)
+    api.register_context_provider(skills.provider_factory, order=PROVIDER_ORDER)
+    api.register_service(service.start, service.close)
+    routes.register_routes()

mobile_agent/plugins/routes.py

@@ -0,0 +1,82 @@
+"""The local API for plugins, under /api/plugins (api_routes, owner "plugins")."""
+
+from ..api_errors import APIError
+from ..api_routes import Response, Route, register
+from ..service_support import needs_app
+from . import install as sources
+from . import manifest
+from . import service as plugin_service
+
+OFF = "Plugins aren't available right now. Restart Mobster, then try again."
+NAME = r"(?P<name>[a-z0-9][a-z0-9-]{0,47})"
+
+
+def service_of(request):
+    service = plugin_service.service_for(request.runtime)
+    if service is None:
+        raise APIError(OFF, 503, "unavailable")
+    return service
+
+
+def refused(error):
+    return APIError(str(error), 400, "plugin_invalid")
+
+
+def listed(request):
+    return Response.json({"plugins": service_of(request).list()})
+
+
+def preview(request):
+    service = service_of(request)
+    needs_app(request)
+    try:
+        return Response.json(service.preview(request.body))
+    except manifest.PluginError as error:
+        raise refused(error) from None
+
+
+def preview_zip(request):
+    service = service_of(request)
+    needs_app(request)
+    try:
+        return Response.json(service.preview(zip_data=request.body or b""))
+    except manifest.PluginError as error:
+        raise refused(error) from None
+
+
+def install(request):
+    service = service_of(request)
+    needs_app(request)
+    try:
+        return Response.json({"plugin": service.install(request.body)}, 201)
+    except manifest.PluginError as error:
+        raise refused(error) from None
+
+
+def update(request):
+    service = service_of(request)
+    needs_app(request)
+    body = request.body
+    if not isinstance(body, dict) or set(body) != {"enabled"}:
+        raise ValueError("A plugin's enabled can change")
+    try:
+        return Response.json({"plugin": service.set_enabled(request.params["name"], body["enabled"])})
+    except manifest.PluginError as error:
+        raise refused(error) from None
+
+
+def delete(request):
+    service = service_of(request)
+    needs_app(request)
+    return Response.json({"name": service.uninstall(request.params["name"])})
+
+
+def register_routes():
+    for route in (Route("plugins", "GET", "/api/plugins", listed, body="none"),
+                  Route("plugins", "POST", "/api/plugins/preview", preview),
+                  Route("plugins", "POST", "/api/plugins/preview-zip", preview_zip, body="raw",
+                        max_bytes=sources.MAX_ARCHIVE),
+                  Route("plugins", "POST", "/api/plugins/install", install),
+                  Route("plugins", "POST", f"/api/plugins/{NAME}", update),
+                  Route("plugins", "DELETE", f"/api/plugins/{NAME}", delete, body="none")):
+        register(route)