mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/integrations/textedit.py

@@ -0,0 +1,309 @@
+"""Set or remove one table of a TOML file, or one entry of a YAML mapping, as a text edit."""
+
+import copy
+import json
+import re
+import tomllib
+
+
+class EditError(ValueError):
+    """The file can't be edited safely. The message says why."""
+
+
+# ---------------------------------------------------------------------------------------------------- TOML
+
+HEADER = re.compile(r"^\s*(\[\[?)\s*(.+?)\s*(\]\]?)\s*(?:#.*)?$")
+
+
+def _toml_key_path(raw):
+    """``a."b c".d`` as ["a", "b c", "d"]; None when it can't be read."""
+    parts, pos = [], 0
+    raw = raw.strip()
+    while pos < len(raw):
+        if raw[pos] == '"':
+            end = pos + 1
+            while end < len(raw) and raw[end] != '"':
+                end += 2 if raw[end] == "\\" else 1
+            try:
+                parts.append(json.loads(raw[pos:end + 1]))
+            except ValueError:
+                return None
+            pos = end + 1
+        elif raw[pos] == "'":
+            end = raw.find("'", pos + 1)
+            if end < 0:
+                return None
+            parts.append(raw[pos + 1:end])
+            pos = end + 1
+        else:
+            match = re.match(r"[A-Za-z0-9_-]+", raw[pos:])
+            if not match:
+                return None
+            parts.append(match.group())
+            pos += match.end()
+        rest = re.match(r"\s*(\.)?\s*", raw[pos:])
+        pos += rest.end()
+        if not rest.group(1) and pos < len(raw):
+            return None
+    return parts
+
+
+def toml_string(value):
+    """A TOML basic string."""
+    return json.dumps(str(value), ensure_ascii=False).replace("\x7f", "\\u007F")
+
+
+def toml_value(value):
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    if isinstance(value, list):
+        return "[" + ", ".join(toml_value(item) for item in value) + "]"
+    if isinstance(value, dict):
+        return "{ " + ", ".join(f"{_toml_key(k)} = {toml_value(v)}" for k, v in value.items()) + " }"
+    return toml_string(value)
+
+
+def _toml_key(key):
+    return key if re.fullmatch(r"[A-Za-z0-9_-]+", key) else toml_string(key)
+
+
+def toml_table(path, value):
+    """``[a.b]`` with ``value``'s scalar and list keys, then a sub-table for each dict value."""
+    lines = ["[" + ".".join(_toml_key(part) for part in path) + "]"]
+    tables = []
+    for key, item in value.items():
+        if isinstance(item, dict):
+            tables.append((key, item))
+        else:
+            lines.append(f"{_toml_key(key)} = {toml_value(item)}")
+    for key, item in tables:
+        lines.append("")
+        lines.extend(toml_table([*path, key], item).splitlines())
+    return "\n".join(lines) + "\n"
+
+
+def toml_loads(text):
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise EditError(f"it isn't valid TOML ({error})") from None
+
+
+def _dig(data, path):
+    for part in path:
+        if not isinstance(data, dict) or part not in data:
+            return None
+        data = data[part]
+    return data
+
+
+def _toml_cut(text, path):
+    """``text`` without the table at ``path`` and its sub-tables; and the line index where the first one began."""
+    lines = text.splitlines(keepends=True)
+    kept, cut_at, cutting, in_string = [], None, False, None
+    for line in lines:
+        # A header inside a multi-line string isn't a header.
+        if in_string is None:
+            match = HEADER.match(line)
+            if match:
+                key = _toml_key_path(match.group(2))
+                cutting = key is not None and match.group(1) == "[" and key[:len(path)] == list(path)
+                if cutting and cut_at is None:
+                    cut_at = len(kept)
+        for quote in ('"""', "'''"):
+            count = line.count(quote)
+            if count % 2 == 1 and in_string in (None, quote):
+                in_string = None if in_string == quote else quote
+        if not cutting:
+            kept.append(line)
+    if cut_at is not None:
+        # Drop the blank lines the cut table left behind it.
+        while cut_at > 0 and not kept[cut_at - 1].strip() and (cut_at >= len(kept) or not kept[cut_at].strip()):
+            kept.pop(cut_at - 1)
+            cut_at -= 1
+    return "".join(kept), cut_at
+
+
+def _pruned(data, path):
+    """``data`` without the tables along ``path`` that are left empty."""
+    data = copy.deepcopy(data)
+    for depth in range(len(path), 0, -1):
+        parent = _dig(data, path[:depth - 1])
+        if isinstance(parent, dict) and parent.get(path[depth - 1]) == {}:
+            del parent[path[depth - 1]]
+    return data
+
+
+def toml_set_table(text, path, value):
+    """``text`` with the table at ``path`` (such as ("mcp_servers", "mobster")) holding exactly ``value``."""
+    data = toml_loads(text)
+    if _dig(data, path) == value:
+        return text
+    expected = copy.deepcopy(data)
+    target = expected
+    for part in path[:-1]:
+        target = target.setdefault(part, {})
+        if not isinstance(target, dict):
+            raise EditError(f"{part} is not a table")
+    target[path[-1]] = copy.deepcopy(value)
+    cut, cut_at = _toml_cut(text, path)
+    if _dig(toml_loads(cut), path) is not None:
+        raise EditError(f"{'.'.join(path)} is written inline or with dotted keys; remove it by hand first")
+    table = toml_table(path, value)
+    if cut_at is None:
+        body = cut.rstrip("\n")
+        new_text = (body + "\n\n" if body else "") + table
+    else:
+        lines = cut.splitlines(keepends=True)
+        before, after = "".join(lines[:cut_at]), "".join(lines[cut_at:])
+        if before and not before.endswith("\n"):
+            before += "\n"
+        if before.strip() and not before.endswith("\n\n"):
+            before += "\n"
+        new_text = before + table + ("\n" + after if after.strip() else after)
+    if toml_loads(new_text) != expected:
+        raise EditError("the edit would change more than Mobster's entry")
+    return new_text
+
+
+def toml_remove_table(text, path):
+    """``text`` without the table at ``path``; ``text`` itself when there is none."""
+    data = toml_loads(text)
+    if _dig(data, path) is None:
+        return text
+    expected = copy.deepcopy(data)
+    del _dig(expected, path[:-1])[path[-1]]
+    new_text, _ = _toml_cut(text, path)
+    new_text = re.sub(r"\n{3,}", "\n\n", new_text)
+    try:
+        ok = toml_loads(new_text) in (expected, _pruned(expected, path[:-1]))
+    except EditError:
+        ok = False
+    if not ok:
+        raise EditError(f"{'.'.join(path)} is written inline or with dotted keys; remove it by hand")
+    return new_text
+
+
+# ---------------------------------------------------------------------------------------------------- YAML
+
+def yaml_loads(text):
+    import yaml
+    try:
+        data = yaml.safe_load(text) if text.strip() else {}
+    except yaml.YAMLError as error:
+        raise EditError(f"it isn't valid YAML ({str(error).splitlines()[0]})") from None
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise EditError("it holds something other than a YAML mapping")
+    return data
+
+
+def _indent(line):
+    return len(line) - len(line.lstrip(" "))
+
+
+def _content(line):
+    stripped = line.strip()
+    return bool(stripped) and not stripped.startswith("#")
+
+
+def _yaml_entry(key, value, indent):
+    import yaml
+    dumped = yaml.safe_dump({key: value}, sort_keys=False, default_flow_style=False, allow_unicode=True, width=10_000)
+    return "".join(" " * indent + line + "\n" for line in dumped.splitlines())
+
+
+def _yaml_find(lines, section, key):
+    """(section line, end of the section, the child indent, the key's start, the key's end) by line index."""
+    top = re.compile(rf"^{re.escape(section)}\s*:\s*(?:#.*)?$")
+    head = next((i for i, line in enumerate(lines) if top.match(line.rstrip("\n"))), None)
+    if head is None:
+        return None
+    end, child = len(lines), None
+    for i in range(head + 1, len(lines)):
+        if _content(lines[i]) and _indent(lines[i]) == 0:
+            end = i
+            break
+        if child is None and _content(lines[i]):
+            child = _indent(lines[i])
+    start = stop = None
+    if child:
+        pattern = re.compile(rf"^ {{{child}}}{re.escape(key)}\s*:\s*(?:#.*)?$")
+        for i in range(head + 1, end):
+            if start is None and pattern.match(lines[i].rstrip("\n")):
+                start = i
+            elif start is not None and _content(lines[i]) and _indent(lines[i]) <= child:
+                stop = i
+                break
+        if start is not None and stop is None:
+            stop = end
+            while stop > start + 1 and not _content(lines[stop - 1]):
+                stop -= 1
+    return head, end, child, start, stop
+
+
+def yaml_set_entry(text, section, key, value):
+    """``text`` with ``section: {key: value}`` at the top level (Goose's ``extensions:``)."""
+    data = yaml_loads(text)
+    existing = data.get(section)
+    if existing is not None and not isinstance(existing, dict):
+        raise EditError(f"{section} is not a mapping")
+    if isinstance(existing, dict) and existing.get(key) == value:
+        return text
+    expected = copy.deepcopy(data)
+    expected.setdefault(section, None)
+    expected[section] = dict(expected[section] or {})
+    expected[section][key] = copy.deepcopy(value)
+    lines = text.splitlines(keepends=True)
+    if lines and not lines[-1].endswith("\n"):
+        lines[-1] += "\n"
+    found = _yaml_find(lines, section, key)
+    empty = re.compile(rf"^{re.escape(section)}\s*:\s*\{{\s*\}}\s*(?:#.*)?$")
+    if found is None and data.get(section) == {}:
+        lines = [f"{section}:\n" if empty.match(line.rstrip("\n")) else line for line in lines]
+        found = _yaml_find(lines, section, key)
+    if found is None:
+        if section in data:
+            raise EditError(f"{section} is written in a form this installer doesn't edit; edit it by hand")
+        body = "".join(lines)
+        new_text = (body + ("" if not body or body.endswith("\n") else "\n") + f"{section}:\n"
+                    + _yaml_entry(key, value, 2))
+    else:
+        head, end, child, start, stop = found
+        indent = child or 2
+        entry = _yaml_entry(key, value, indent)
+        if start is not None:
+            lines[start:stop] = [entry]
+        else:
+            at = end
+            while at > head + 1 and not _content(lines[at - 1]):
+                at -= 1
+            lines[at:at] = [entry]
+        new_text = "".join(lines)
+    if yaml_loads(new_text) != expected:
+        raise EditError("the edit would change more than Mobster's entry")
+    return new_text
+
+
+def yaml_remove_entry(text, section, key):
+    """``text`` without ``key`` under ``section``; ``text`` itself when there is none."""
+    data = yaml_loads(text)
+    if not isinstance(data.get(section), dict) or key not in data[section]:
+        return text
+    expected = copy.deepcopy(data)
+    del expected[section][key]
+    lines = text.splitlines(keepends=True)
+    found = _yaml_find(lines, section, key)
+    if found is None or found[3] is None:
+        raise EditError(f"{section}.{key} is written in a form this installer doesn't edit; remove it by hand")
+    head, _end, _child, start, stop = found
+    del lines[start:stop]
+    if not expected[section]:
+        lines[head] = f"{section}: {{}}\n"
+    new_text = "".join(lines)
+    if yaml_loads(new_text) != expected:
+        raise EditError("the edit would change more than Mobster's entry")
+    return new_text

mobile_agent/intents/__init__.py

@@ -0,0 +1,17 @@
+"""Deterministic path first: before tapping, ask whether the goal has a link that gets there (dark).
+
+``atlas`` reads what the apps on a phone declare (URL schemes, associated domains) as "discovered" links, a layer
+under ``deeplinks.LINKS``. ``callback`` builds and reads x-callback-url returns. ``plan`` proposes a link for a goal.
+Everything is off unless ``MOBSTER_EXPERIMENTAL_INTENTS=1``. ``deeplinks.decide`` still governs every link; a
+discovered link is never "verified" (that word is for links opened on a real iPhone, with a date).
+"""
+
+import os
+
+ENV_FLAG = "MOBSTER_EXPERIMENTAL_INTENTS"
+
+
+def enabled():
+    """Whether the experimental deterministic-path layer is on (``MOBSTER_EXPERIMENTAL_INTENTS=1``)."""
+    return os.environ.get(ENV_FLAG, "").strip().casefold() in ("1", "true", "yes", "on")
+

mobile_agent/intents/atlas.py

@@ -0,0 +1,216 @@
+"""The link atlas: the schemes and universal-link paths the apps on one phone declare.
+
+Sources, none of which needs the network here:
+- an app's Info.plist ``CFBundleURLTypes`` (schemes) and, when the bundle carries it, its entitlements'
+  ``com.apple.developer.associated-domains`` (``applinks:`` domains; a simulator build keeps
+  ``archived-expanded-entitlements.xcent``);
+- an apple-app-site-association document (the caller fetched it, when the network is allowed): the paths each
+  domain sends to the app.
+A simulator is read through ``xcrun simctl listapps``. Every entry is "discovered" until a run opens it.
+"""
+
+import fnmatch
+import json
+import plistlib
+import re
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from ..deeplinks import BLOCKED_SCHEMES, SCHEME
+
+SCHEME_NAME = re.compile(r"^[a-z][a-z0-9+.-]{0,40}$")
+DOMAIN = re.compile(r"^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$")
+ENTITLEMENTS = "archived-expanded-entitlements.xcent"
+STATE = "discovered"
+
+
+@dataclass
+class Entry:
+    bundle: str
+    name: str
+    schemes: list = field(default_factory=list)
+    domains: list = field(default_factory=list)
+    paths: dict = field(default_factory=dict)    # domain -> [{"pattern": "/invite/*", "exclude": False}]
+
+    def public(self):
+        return {"bundleId": self.bundle, "app": self.name, "schemes": self.schemes, "domains": self.domains,
+                "state": STATE}
+
+
+def _schemes(info):
+    found = []
+    for kind in info.get("CFBundleURLTypes") or ():
+        for scheme in (kind.get("CFBundleURLSchemes") or ()) if isinstance(kind, dict) else ():
+            scheme = str(scheme).strip().casefold()
+            if SCHEME_NAME.match(scheme) and scheme not in BLOCKED_SCHEMES and scheme not in found:
+                found.append(scheme)
+    return found
+
+
+def _domains(entitlements):
+    found = []
+    for item in (entitlements or {}).get("com.apple.developer.associated-domains") or ():
+        kind, _, host = str(item).partition(":")
+        host = host.split("?", 1)[0].strip().casefold()
+        if kind == "applinks" and DOMAIN.match(host) and not host.startswith("*") and host not in found:
+            found.append(host)
+    return found
+
+
+def entry_from_bundle(bundle, name, info, entitlements=None):
+    """An ``Entry`` from an app's Info.plist (a dict) and its entitlements; None when it declares no link."""
+    entry = Entry(bundle, str(info.get("CFBundleDisplayName") or info.get("CFBundleName") or name or bundle),
+                  _schemes(info), _domains(entitlements))
+    return entry if entry.schemes or entry.domains else None
+
+
+def read_app_folder(folder):
+    """An ``Entry`` from an unpacked ``.app`` folder; None when it is unreadable or declares nothing."""
+    folder = Path(folder)
+    try:
+        info = plistlib.loads((folder / "Info.plist").read_bytes())
+        bundle = str(info["CFBundleIdentifier"])
+    except (OSError, ValueError, KeyError, plistlib.InvalidFileException):
+        return None
+    try:
+        entitlements = plistlib.loads((folder / ENTITLEMENTS).read_bytes())
+    except (OSError, ValueError, plistlib.InvalidFileException):
+        entitlements = None
+    return entry_from_bundle(bundle, folder.stem, info, entitlements)
+
+
+def parse_aasa(document, bundle):
+    """The path rules an apple-app-site-association document (text or dict) gives ``bundle``: a list of
+    {"pattern", "exclude"}. Old ``paths`` ("NOT /x" excludes) and ``components`` ("/" patterns) are both read."""
+    try:
+        data = json.loads(document) if isinstance(document, (str, bytes)) else document
+        details = data["applinks"]["details"]
+    except (ValueError, KeyError, TypeError):
+        return []
+    rules = []
+    for detail in details if isinstance(details, list) else ():
+        ids = list(detail.get("appIDs") or ()) + ([detail["appID"]] if detail.get("appID") else [])
+        if not any(str(i).partition(".")[2] == bundle for i in ids):
+            continue
+        for path in detail.get("paths") or ():
+            text = str(path)
+            rules.append({"pattern": text.removeprefix("NOT ").strip(), "exclude": text.startswith("NOT ")})
+        for part in detail.get("components") or ():
+            if isinstance(part, dict) and isinstance(part.get("/"), str):
+                rules.append({"pattern": part["/"], "exclude": bool(part.get("exclude"))})
+    return [r for r in rules if r["pattern"].startswith(("/", "*"))]
+
+
+def path_allowed(rules, path):
+    """Whether the first rule that matches ``path`` includes it (a rule list that never matches refuses)."""
+    for rule in rules:
+        if fnmatch.fnmatchcase(path, rule["pattern"]):
+            return not rule["exclude"]
+    return False
+
+
+class Atlas:
+    def __init__(self, entries=()):
+        self.entries = {entry.bundle: entry for entry in entries}
+
+    def add_aasa(self, bundle, domain, document):
+        entry = self.entries.get(bundle)
+        if entry is not None and domain in entry.domains:
+            entry.paths[domain] = parse_aasa(document, bundle)
+
+    def find(self, url, installed=None):
+        """The ``Entry`` that declares ``url``'s scheme, or whose associated domain and paths send it to the app;
+        None otherwise. ``installed``: bundle ids to limit to (an app that left the phone claims nothing)."""
+        text = str(url or "").strip()
+        found = SCHEME.match(text)
+        if not found:
+            return None
+        scheme = found.group(1).casefold()
+        for entry in self.entries.values():
+            if installed is not None and entry.bundle not in installed:
+                continue
+            if scheme in ("http", "https"):
+                parts = urlsplit(text)
+                host = (parts.hostname or "").casefold()
+                if host in entry.domains and path_allowed(entry.paths.get(host, ()), parts.path or "/"):
+                    return entry
+            elif scheme in entry.schemes:
+                return entry
+        return None
+
+    def by_app(self, words):
+        """Entries whose app name or bundle id holds every word of ``words``."""
+        wants = [w for w in re.split(r"\W+", str(words or "").casefold()) if w]
+        return [e for e in self.entries.values()
+                if wants and all(w in f"{e.name} {e.bundle}".casefold() for w in wants)]
+
+    def named_in(self, goal):
+        """Entries whose app name is a whole word run in ``goal`` ("open Things and add milk" finds Things)."""
+        said = " " + " ".join(re.split(r"\W+", str(goal or "").casefold())) + " "
+        return [e for e in self.entries.values() if f" {' '.join(re.split(r'\W+', e.name.casefold()))} " in said]
+
+    def to_json(self):
+        return json.dumps({"entries": [vars(e) for e in self.entries.values()]}, indent=1)
+
+    @classmethod
+    def from_json(cls, text):
+        try:
+            rows = json.loads(text)["entries"]
+            return cls(Entry(**row) for row in rows)
+        except (ValueError, KeyError, TypeError):
+            return cls()
+
+
+def path_for(key):
+    from ..paths import dev_data_dir
+    return dev_data_dir() / "link-atlas" / (re.sub(r"[^A-Za-z0-9._-]", "_", key) + ".json")
+
+
+def load(key):
+    try:
+        return Atlas.from_json(path_for(key).read_text())
+    except OSError:
+        return Atlas()
+
+
+def save(key, atlas):
+    from ..paths import write_text_atomic
+    write_text_atomic(path_for(key), atlas.to_json())
+
+
+def harvest_simulator(udid, run):
+    """The atlas of a simulator's apps. ``run(argv, timeout)`` is ``sim.simctl.run``'s shape (a ``Result``).
+    Reads Info.plist and entitlements of each app ``simctl listapps`` names; an unreadable app is skipped."""
+    listed = run(["xcrun", "simctl", "listapps", udid], timeout=60)
+    if not listed.ok:
+        return Atlas()
+    with tempfile.TemporaryDirectory(prefix="mobster-atlas-") as folder:
+        source = Path(folder) / "apps.plist"
+        source.write_text(listed.out)
+        converted = run(["plutil", "-convert", "json", "-o", "-", str(source)], timeout=30)
+    try:
+        apps = json.loads(converted.out) if converted.ok else {}
+    except ValueError:
+        apps = {}
+    entries = []
+    for bundle, app in apps.items() if isinstance(apps, dict) else ():
+        where = str(app.get("Path") or "") if isinstance(app, dict) else ""
+        entry = read_app_folder(where) if where else None
+        if entry is None and isinstance(app, dict):
+            entry = entry_from_bundle(bundle, app.get("CFBundleDisplayName") or "", app, None)
+        if entry is not None and entry.bundle == bundle:
+            entries.append(entry)
+    return Atlas(entries)
+
+
+def discovered(args):
+    """The atlas entries (as dicts) for an ``open_url`` listing's ``app`` and ``query`` on its ``device``."""
+    words = f"{args.get('app') or ''} {args.get('query') or ''}"
+    return [e.public() for e in load(args.get("device") or "default").by_app(words)]
+
+
+def describe(rows):
+    lines = [f"{r['app']}: {', '.join(s + '://' for s in r['schemes']) or 'no scheme'}" for r in rows]
+    return "Discovered in the apps' own files, not verified. open_url still asks as usual:\n" + "\n".join(lines)

mobile_agent/intents/callback.py

@@ -0,0 +1,44 @@
+"""x-callback-url: ask an app to hand control back to Mobster's own scheme, so the answer needs no screen read.
+
+``with_callback(url, token)`` adds ``x-success``, ``x-error`` and ``x-cancel`` to a link that is already allowed by
+``deeplinks.decide``; ``parse(url)`` reads what came back. Receiving the callback needs the runner to own the
+``mobster-callback`` scheme; that part is pending a proof on a simulator. Mobster never opens a callback link
+itself: it only reads one the runner reports.
+"""
+
+import re
+from urllib.parse import parse_qsl, quote, urlsplit
+
+from ..deeplinks import LinkError, decide
+
+SCHEME = "mobster-callback"
+TOKEN = re.compile(r"^[A-Za-z0-9_-]{6,64}$")
+STATUSES = ("success", "error", "cancel")
+
+
+def with_callback(url, token):
+    """``url`` with the three return addresses added. LinkError for a link Mobster never opens, a web page (it has no
+    callback) or a bad token. The link keeps its decision: ``decide(result)`` asks exactly when ``decide(url)`` did."""
+    if not TOKEN.match(str(token or "")):
+        raise LinkError("A callback token is 6 to 64 letters, digits, - or _.")
+    decision = decide(url)
+    scheme = decision.url.partition(":")[0].casefold()
+    if scheme in ("http", "https"):
+        raise LinkError("A web page can't return to Mobster. Use an app's link.")
+    base, _, query = decision.url.partition("?")
+    returns = "&".join(f"x-{status}={quote(f'{SCHEME}://{token}/{status}', safe='')}" for status in STATUSES)
+    return f"{base}?{query}&{returns}" if query else f"{base}?{returns}"
+
+
+def parse(url):
+    """{"token", "status", "params"} for a callback address, or None when it isn't one."""
+    parts = urlsplit(str(url or "").strip())
+    status = parts.path.strip("/")
+    if parts.scheme.casefold() != SCHEME or status not in STATUSES or not TOKEN.match(parts.netloc):
+        return None
+    return {"token": parts.netloc, "status": status, "params": dict(parse_qsl(parts.query))}
+
+
+def shortcut_run(name, token):
+    """The x-callback link that runs a shortcut and returns. It acts, so it asks every time (``decide``)."""
+    return with_callback("shortcuts://x-callback-url/run-shortcut?name=" + quote(str(name).strip(), safe=""), token)

mobile_agent/intents/cli.py

@@ -0,0 +1,55 @@
+"""`mobster intents harvest`: read a simulator's apps and their associated domains into the link atlas.
+
+Hidden unless MOBSTER_EXPERIMENTAL_INTENTS=1. The AASA fetch is the only network use; `--no-network` skips it.
+Exit codes: 0 harvested, 3 couldn't (no simulator, no Xcode, usage too).
+"""
+
+import json
+import sys
+
+from ..devkit import DevError, main, say, subcommands
+
+
+def add_arguments(parser, helpers):
+    add = subcommands(parser, "intents_command")
+    harvest = add("harvest", help="read a simulator's apps and domains into the link atlas",
+                  description="Read each app's URL schemes and associated domains on a simulator through simctl, "
+                              "fetch each domain's apple-app-site-association (https), and keep the atlas under "
+                              "Mobster's data folder. Discovered links are never marked verified.")
+    harvest.add_argument("--sim", metavar="UDID", help="the simulator (default: the one booted simulator)")
+    harvest.add_argument("--force", action="store_true", help="read again although the atlas is under a day old")
+    harvest.add_argument("--no-network", action="store_true", help="skip the AASA fetch")
+    harvest.add_argument("--json", action="store_true", help="print the atlas as JSON")
+
+
+def run(args):
+    return main("intents", {"harvest": _harvest}, args)
+
+
+def booted(run):
+    """The UDID of the one booted simulator; DevError otherwise."""
+    result = run(["xcrun", "simctl", "list", "devices", "booted", "-j"], timeout=30)
+    try:
+        devices = [d["udid"] for group in json.loads(result.out)["devices"].values() for d in group
+                   if d.get("state") == "Booted"] if result.ok else []
+    except (ValueError, KeyError, TypeError):
+        devices = []
+    if len(devices) != 1:
+        raise DevError("Mobster needs one booted simulator to read.", "Pass --sim UDID, or boot just one.")
+    return devices[0]
+
+
+def _harvest(args):
+    from ..sim.simctl import run as simctl_run
+    from . import harvest
+    udid = args.sim or booted(simctl_run)
+    atlas = harvest.harvest(udid, simctl_run, fetch=None if args.no_network else harvest.fetch_aasa,
+                            log=lambda line: say(line, sys.stderr), force=args.force)
+    if args.json:
+        say(atlas.to_json())
+    else:
+        for entry in atlas.entries.values():
+            say(f"{entry.name}: {', '.join(s + '://' for s in entry.schemes) or '-'}"
+                f"  {', '.join(entry.domains) or '-'}  discovered")
+        say(f"{len(atlas.entries)} apps declare links.")
+    return 0