mkit-cli 0.3.1__py3-none-any.whl

mkit/datasafety.py

@@ -0,0 +1,302 @@
+"""Build Play's data safety CSV from a few lines of `mkit.toml`.
+
+Play's Data safety form is 782 questions. The API takes the same CSV the
+Console's import accepts, and there is no API that hands the current answers
+back - `applications.dataSafety` is POST only - so the declaration has to be
+kept in the repo, next to the code it describes.
+
+Every app was doing that by hand: one wrote a script to fill Google's sample
+CSV, two others carry a byte-identical copy of the result. That is the
+duplication the engine exists to remove, so the question set ships here
+(`data/datasafety-questions.csv`, answers stripped) and an app declares only
+what it collects:
+
+    [datasafety]
+    collects             = true
+    encrypted_in_transit = true
+    deletion             = "no"
+    account_creation     = "none"
+
+    [datasafety.collected]
+    crash_logs       = ["app_functionality", "analytics"]
+    diagnostics      = ["app_functionality", "analytics"]
+    app_interactions = ["analytics"]
+    device_ids       = ["app_functionality", "analytics"]
+
+`mkit datasafety build` turns that into the CSV at the `datasafety` path under
+`[store]`; `check` validates it and `apply` uploads it. A data type left out of
+[datasafety.collected] is declared as not collected, which is the whole point:
+the file says what the app does, and nothing is true by omission.
+
+**This is a declaration, not a description.** Whatever is written here is what
+Play publishes on the store page and holds the developer to, so it follows the
+code: an SDK added is a line added.
+"""
+import csv
+import io
+from pathlib import Path
+
+from .errors import UsageError
+
+QUESTIONS = Path(__file__).parent / 'data' / 'datasafety-questions.csv'
+
+COLUMNS = (
+    'Question ID (machine readable)',
+    'Response ID (machine readable)',
+    'Response value',
+    'Answer requirement',
+    'Human-friendly question label',
+)
+
+# The questions that are answered once for the whole app rather than per data type.
+COLLECTS = 'PSL_DATA_COLLECTION_COLLECTS_PERSONAL_DATA'
+ENCRYPTED = 'PSL_DATA_COLLECTION_ENCRYPTED_IN_TRANSIT'
+ACCOUNT_CREATION = 'PSL_SUPPORTED_ACCOUNT_CREATION_METHODS'
+DELETION = 'PSL_SUPPORT_DATA_DELETION_BY_USER'
+OUTSIDE_ACCOUNTS = 'PSL_HAS_OUTSIDE_APP_ACCOUNTS'
+DELETION_URL = 'PSL_DATA_DELETION_URL'
+ACCOUNT_DELETION_URL = 'PSL_ACCOUNT_DELETION_URL'
+USAGE = 'PSL_DATA_USAGE_RESPONSES'
+
+# How a purpose is spelled in mkit.toml, and the response id it answers.
+PURPOSES = {
+    'app_functionality': 'PSL_APP_FUNCTIONALITY',
+    'analytics': 'PSL_ANALYTICS',
+    'developer_communications': 'PSL_DEVELOPER_COMMUNICATIONS',
+    'fraud_prevention': 'PSL_FRAUD_PREVENTION_SECURITY',
+    'advertising': 'PSL_ADVERTISING',
+    'personalization': 'PSL_PERSONALIZATION',
+    'account_management': 'PSL_ACCOUNT_MANAGEMENT',
+}
+
+ACCOUNT_METHODS = {
+    'none': 'PSL_ACM_NONE',
+    'password': 'PSL_ACM_USER_ID_PASSWORD',
+    'other_auth': 'PSL_ACM_USER_ID_OTHER_AUTH',
+    'password_other_auth': 'PSL_ACM_USER_ID_PASSWORD_OTHER_AUTH',
+    'oauth': 'PSL_ACM_OAUTH',
+    'other': 'PSL_ACM_OTHER',
+}
+
+DELETION_CHOICES = {
+    'yes': 'DATA_DELETION_YES',
+    'no': 'DATA_DELETION_NO',
+    'auto': 'DATA_DELETION_NO_AUTO_DELETED',
+}
+
+# Short spellings for types whose own label is a mouthful or repeats itself.
+# Every type also answers to the name derived from its label, and to its raw
+# PSL id, so nobody has to guess which of the three was meant.
+ALIASES = {
+    'device_ids': 'PSL_DEVICE_ID',
+    'diagnostics': 'PSL_PERFORMANCE_DIAGNOSTICS',
+    'app_interactions': 'PSL_USER_INTERACTION',
+    'user_ids': 'PSL_USER_ACCOUNT',
+    'installed_apps': 'PSL_APPS_ON_DEVICE',
+    'payment_info': 'PSL_CREDIT_DEBIT_BANK_ACCOUNT_NUMBER',
+    'user_generated_content': 'PSL_USER_GENERATED_CONTENT',
+}
+
+
+def _slug(text):
+    """A label's last segment as a mkit.toml name: 'App activity / App interactions'."""
+    tail = (text or '').replace('\n', ' / ').split(' / ')[-1].strip().lower()
+    return ''.join(c if c.isalnum() else '_' for c in tail).strip('_')
+
+
+def question_rows():
+    """The shipped question set, as dicts. Read once per call; it is 782 rows."""
+    text = QUESTIONS.read_text(encoding='utf-8-sig')
+    return list(csv.DictReader(io.StringIO(text)))
+
+
+def data_types(rows=None):
+    """Every data type: its PSL id, the names it answers to, and its label."""
+    types = {}
+    for row in rows or question_rows():
+        if not row[COLUMNS[0]].startswith('PSL_DATA_TYPES_'):
+            continue
+        psl = row[COLUMNS[1]]
+        label = (row[COLUMNS[4]] or '').replace('\n', ' / ')
+        names = {psl, _slug(label)}
+        names |= {alias for alias, target in ALIASES.items() if target == psl}
+        types[psl] = {'id': psl, 'names': sorted(n for n in names if n), 'label': label}
+    return types
+
+
+def _resolve(name, types):
+    """The PSL id a mkit.toml name means, or a UsageError naming the near misses."""
+    wanted = str(name).strip()
+    for psl, info in types.items():
+        if wanted == psl or wanted.lower() in info['names']:
+            return psl
+    close = sorted(n for info in types.values() for n in info['names']
+                   if wanted.lower()[:4] and wanted.lower()[:4] in n)
+    raise UsageError(f'unknown data type "{name}" in [datasafety.collected]',
+                     hint=('Did you mean: ' + ', '.join(close[:5]) + '?') if close
+                          else 'Run `mkit datasafety types` for every name.',
+                     code='DATASAFETY_UNKNOWN_TYPE')
+
+
+def _purposes(values, where):
+    out = set()
+    for value in values:
+        key = str(value).strip().lower()
+        if key not in PURPOSES:
+            raise UsageError(f'unknown purpose "{value}" in {where}',
+                             hint='One of: ' + ', '.join(sorted(PURPOSES)),
+                             code='DATASAFETY_UNKNOWN_PURPOSE')
+        out.add(PURPOSES[key])
+    return out
+
+
+def _collected(config, types):
+    """[datasafety.collected] as {psl id: {purposes, collected, shared, ephemeral, optional}}."""
+    collected = {}
+    for name, value in (config.get('collected') or {}).items():
+        psl = _resolve(name, types)
+        # Two spellings, because most types only ever need the short one:
+        #   crash_logs = ["analytics"]           purposes, collected, not shared
+        #   [datasafety.collected.photos]        the same plus sharing and controls
+        #   purposes = [...]
+        if isinstance(value, dict):
+            entry = value
+        elif isinstance(value, (list, tuple)):
+            entry = {'purposes': list(value)}
+        else:
+            raise UsageError(f'[datasafety.collected] {name} must be a list of purposes '
+                             f'or a table, not {type(value).__name__}',
+                             code='DATASAFETY_BAD_TYPE')
+        purposes = _purposes(entry.get('purposes') or [], f'[datasafety.collected] {name}')
+        if not purposes:
+            raise UsageError(f'[datasafety.collected] {name} lists no purpose',
+                             hint='Play requires at least one: ' + ', '.join(sorted(PURPOSES)),
+                             code='DATASAFETY_NO_PURPOSE')
+        shared = _purposes(entry.get('shared') or [], f'[datasafety.collected] {name} shared')
+        # Play's "collected, shared, or both" is two checkboxes. Data the app
+        # sends off the device is collected; sharing it on is on top of that,
+        # so only a type that goes to a third party straight from the device
+        # (an SDK the app never sees the data from) sets collected = false.
+        is_collected = bool(entry.get('collected', True))
+        if not is_collected and not shared:
+            raise UsageError(f'[datasafety.collected] {name} is neither collected nor shared',
+                             hint='Leave the type out instead, or set shared.',
+                             code='DATASAFETY_NOT_COLLECTED')
+        collected[psl] = {
+            'purposes': purposes,
+            'collected': is_collected,
+            'shared': shared,
+            'ephemeral': bool(entry.get('ephemeral', False)),
+            'optional': bool(entry.get('optional', False)),
+        }
+    return collected
+
+
+def _flag(value):
+    return 'TRUE' if value else 'FALSE'
+
+
+def _account_methods(config):
+    """account_creation as the set of response ids it chooses."""
+    methods = config.get('account_creation', 'none')
+    methods = [methods] if isinstance(methods, str) else list(methods)
+    chosen = set()
+    for method in methods:
+        key = str(method).strip().lower()
+        if key not in ACCOUNT_METHODS:
+            raise UsageError(f'unknown account_creation "{method}"',
+                             hint='One of: ' + ', '.join(ACCOUNT_METHODS),
+                             code='DATASAFETY_UNKNOWN_ACCOUNT')
+        chosen.add(ACCOUNT_METHODS[key])
+    return chosen
+
+
+def _answer(row, config, collected):
+    """One row's Response value: TRUE, FALSE, a string, or blank where it does not apply."""
+    question, response = row[COLUMNS[0]], row[COLUMNS[1]]
+
+    if question == COLLECTS:
+        return _flag(config.get('collects', bool(collected)))
+    if question == ENCRYPTED:
+        return _flag(config.get('encrypted_in_transit', True))
+    if question == OUTSIDE_ACCOUNTS:
+        # Play only asks this of an app with no account creation of its own,
+        # and rejects an answer from one that has it.
+        if _account_methods(config) != {'PSL_ACM_NONE'}:
+            return ''
+        return _flag(config.get('outside_app_accounts', False))
+    if question == ACCOUNT_CREATION:
+        return _flag(response in _account_methods(config))
+    if question == DELETION:
+        key = str(config.get('deletion', 'no')).strip().lower()
+        if key not in DELETION_CHOICES:
+            raise UsageError(f'unknown deletion "{key}"',
+                             hint='One of: ' + ', '.join(DELETION_CHOICES),
+                             code='DATASAFETY_UNKNOWN_DELETION')
+        return _flag(response == DELETION_CHOICES[key])
+    if question in (DELETION_URL, ACCOUNT_DELETION_URL):
+        key = 'deletion_url' if question == DELETION_URL else 'account_deletion_url'
+        return str(config.get(key, '') or '')
+
+    if question.startswith('PSL_DATA_TYPES_'):
+        return _flag(response in collected)
+
+    if not question.startswith(USAGE + ':'):
+        # Everything else - family policy, independent validation, the account
+        # types - is left as Play's own default rather than guessed at here.
+        return ''
+
+    _, data_type, part = question.split(':', 2)
+    entry = collected.get(data_type)
+    if entry is None:
+        # A type that is not collected answers nothing further; the Console
+        # greys these out for the same reason.
+        return ''
+    if part == 'PSL_DATA_USAGE_COLLECTION_AND_SHARING':
+        if response == 'PSL_DATA_USAGE_ONLY_COLLECTED':
+            return _flag(entry['collected'])
+        if response == 'PSL_DATA_USAGE_ONLY_SHARED':
+            return _flag(bool(entry['shared']))
+        return ''
+    if part == 'PSL_DATA_USAGE_EPHEMERAL':
+        # Asked about collection only; Play rejects it for a type that is
+        # only shared.
+        return _flag(entry['ephemeral']) if entry['collected'] else ''
+    if part == 'DATA_USAGE_USER_CONTROL':
+        wanted = ('PSL_DATA_USAGE_USER_CONTROL_OPTIONAL' if entry['optional']
+                  else 'PSL_DATA_USAGE_USER_CONTROL_REQUIRED')
+        return _flag(response == wanted)
+    if part == 'DATA_USAGE_COLLECTION_PURPOSE':
+        return _flag(response in entry['purposes'])
+    if part == 'DATA_USAGE_SHARING_PURPOSE':
+        return _flag(response in entry['shared'])
+    raise UsageError(f'unhandled data usage question {question}',
+                     hint='The shipped question set is newer than this engine; '
+                          'update mkit, or report it.',
+                     code='DATASAFETY_UNHANDLED')
+
+
+def build(config):
+    """The whole CSV as text, from a [datasafety] section."""
+    if not config:
+        raise UsageError('no [datasafety] section in mkit.toml',
+                         hint='See docs/config.md; `mkit datasafety types` lists the '
+                              'data type names.',
+                         code='NO_DATASAFETY_CONFIG')
+    rows = question_rows()
+    types = data_types(rows)
+    collected = _collected(config, types)
+    if config.get('collects', bool(collected)) and not collected:
+        raise UsageError('[datasafety] says the app collects data but lists none',
+                         hint='Add [datasafety.collected], or set collects = false.',
+                         code='DATASAFETY_NO_TYPES')
+
+    out = io.StringIO()
+    writer = csv.DictWriter(out, fieldnames=list(COLUMNS), lineterminator='\r\n')
+    writer.writeheader()
+    for row in rows:
+        row = dict(row)
+        row[COLUMNS[2]] = _answer(row, config, collected)
+        writer.writerow(row)
+    labels = sorted(types[psl]['label'].split(' / ')[-1] for psl in collected)
+    return out.getvalue(), {'rows': len(rows), 'data_types': labels}

mkit/device.py

@@ -0,0 +1,246 @@
+"""adb and emulator helpers: pick a device, install, launch, follow logs."""
+import os
+import re
+import subprocess
+import sys
+import time
+
+from . import output, proc, toolchain
+from .errors import MkitError, UsageError
+
+
+class Adb:
+    def __init__(self, root=None):
+        self.exe = toolchain.adb(root)
+
+    def __call__(self, *args, device=None, check=False, timeout=120):
+        argv = [self.exe] + (['-s', device] if device else []) + list(args)
+        return proc.run(argv, check=check, timeout=timeout)
+
+    def devices(self):
+        found = []
+        for line in self('devices').splitlines()[1:]:
+            m = re.match(r'^(\S+)\s+(device|unauthorized|offline)$', line.strip())
+            if m:
+                found.append((m.group(1), m.group(2)))
+        return found
+
+    def model(self, device):
+        try:
+            return self('shell', 'getprop', 'ro.product.model', device=device).strip() or device
+        except Exception:
+            return device
+
+    def app_uid(self, device, package):
+        """The Linux uid the package runs as, or None if it is not installed.
+
+        Used to narrow logcat to one app. The uid rather than the pid because the pid changes
+        every time the app restarts, and restarting the app without leaving the log is the whole
+        point of the Shift+R in follow_logs.
+        """
+        try:
+            out = self('shell', 'pm', 'list', 'packages', '-U', package, device=device)
+        except Exception:
+            return None
+        for line in out.splitlines():
+            line = line.strip()
+            if line.startswith(f'package:{package} ') and 'uid:' in line:
+                uid = line.rsplit('uid:', 1)[1].strip()
+                return uid if uid.isdigit() else None
+        return None
+
+
+def is_emulator(serial):
+    return serial.startswith('emulator-')
+
+
+def pick(adb, want=None, serial=None):
+    """One ready device. want: 'phone' | 'emulator' | None. Asks at a terminal
+    when several match; anywhere else that is an error naming --device."""
+    listed = adb.devices()
+    if serial:
+        if not any(s == serial and st == 'device' for s, st in listed):
+            raise MkitError(f'device {serial} is not attached and ready', code='NO_DEVICE')
+        return serial
+    for s, state in listed:
+        if state == 'unauthorized':
+            output.out.warn(f'{s} is unauthorized: accept the USB debugging prompt on the phone')
+    ready = [s for s, st in listed if st == 'device']
+    if want == 'phone':
+        ready = [s for s in ready if not is_emulator(s)]
+    elif want == 'emulator':
+        ready = [s for s in ready if is_emulator(s)]
+    if not ready:
+        what = {'phone': 'phone', 'emulator': 'running emulator'}.get(want, 'device')
+        raise MkitError(f'no {what} attached', code='NO_DEVICE',
+                        hint='Plug in a phone with USB debugging on, or start one with `mkit emu`.')
+    if len(ready) == 1:
+        return ready[0]
+    out = output.out
+    if out.json or not sys.stdin.isatty():
+        raise UsageError(f'{len(ready)} devices attached ({", ".join(ready)}); pass --device SERIAL',
+                         code='SEVERAL_DEVICES')
+    out.line()
+    for i, s in enumerate(ready, 1):
+        out.line(f'  {i}) {adb.model(s)}  ({s}, {"emulator" if is_emulator(s) else "phone"})')
+    choice = input(f'\nWhich one? (1-{len(ready)}, Enter for 1) ').strip() or '1'
+    try:
+        return ready[int(choice) - 1]
+    except (ValueError, IndexError):
+        raise UsageError(f'not one of the choices: {choice}') from None
+
+
+def clean_state(adb, device, package):
+    """Remove the app for every user and wipe its backup, so the next install
+    is a true first run (Auto Backup would otherwise restore old prefs)."""
+    users = re.findall(r'UserInfo\{(\d+):', adb('shell', 'pm', 'list', 'users', device=device)) or ['0']
+    removed = 0
+    for user in users:
+        adb('shell', 'pm', 'clear', '--user', user, package, device=device)
+        if 'Success' in adb('shell', 'pm', 'uninstall', '--user', user, package, device=device):
+            removed += 1
+    if 'Success' in adb('uninstall', package, device=device):
+        removed += 1
+    transports = []
+    for line in adb('shell', 'bmgr', 'list', 'transports', device=device).splitlines():
+        t = re.sub(r'^\s*\*?\s*', '', line).strip()
+        if '/' in t:
+            transports.append(t)
+    for t in transports:
+        adb('shell', 'bmgr', 'wipe', t, package, device=device)
+    return removed, len(transports)
+
+
+def launch(adb, device, package, clear_log=True):
+    listed = adb('shell', 'cmd', 'package', 'resolve-activity', '--brief', '-a',
+                 'android.intent.action.MAIN', '-c', 'android.intent.category.LAUNCHER', package,
+                 device=device, check=True).splitlines()
+    component = next((l.strip() for l in reversed(listed) if l.strip().startswith(package + '/')), None)
+    if not component:
+        raise MkitError(f'no launcher activity for {package}', code='NO_LAUNCHER')
+    adb('shell', 'am', 'force-stop', package, device=device, check=True)
+    if clear_log:
+        adb('logcat', '-c', device=device)
+    result = adb('shell', 'am', 'start', '-n', component, device=device, check=True)
+    if 'Error' in result or 'Exception' in result:
+        raise MkitError(result.strip(), code='LAUNCH_FAILED')
+    return component
+
+
+def _logcat_argv(adb, device, package, tags, everything):
+    """What to follow, resolved fresh each time the stream starts.
+
+    The uid is looked up here rather than once at the top, because an install can move an app to a
+    new uid. A filter worked out before a reinstall goes on matching the old one, and the log then
+    runs empty while the app is plainly doing things, which looks like the app broke.
+    """
+    if tags:
+        return [adb.exe, '-s', device, 'logcat', '-s', *tags]
+    if everything:
+        return [adb.exe, '-s', device, 'logcat']
+    uid = adb.app_uid(device, package)
+    if uid:
+        return [adb.exe, '-s', device, 'logcat', '--uid', uid]
+    output.out.line(f'{package} is not installed, so the whole log follows', 'dim')
+    return [adb.exe, '-s', device, 'logcat']
+
+
+def _stop(process):
+    if process.poll() is None:
+        process.terminate()
+        try:
+            process.wait(timeout=3)
+        except subprocess.TimeoutExpired:
+            process.kill()
+
+
+def _wait_for_restart(process, restart):
+    """True when R was pressed, False when the stream ended or Ctrl+C arrived."""
+    try:
+        if os.name == 'nt':
+            import msvcrt
+            while process.poll() is None:
+                if restart and msvcrt.kbhit() and msvcrt.getwch() == 'R':
+                    return True
+                time.sleep(0.05)
+        else:
+            import select
+            while process.poll() is None:
+                ready, _, _ = select.select([sys.stdin], [], [], 0.1)
+                if restart and ready and sys.stdin.read(1) == 'R':
+                    return True
+    except KeyboardInterrupt:
+        pass
+    return False
+
+
+def follow_logs(adb, device, package, tags, restart=True, everything=False, rebuild=None):
+    """logcat until Ctrl+C. Shift+R puts the current code on the device without leaving.
+
+    Narrowed to the app unless asked otherwise. Named tags win where a project sets them; with
+    none, the app's own uid does it, which needs nothing configured and still catches the lines
+    an app never chose a tag for, crashes included. A phone's own firmware can write a thousand
+    lines a minute, so an unfiltered stream is not a log of your app in any useful sense.
+
+    Given a [rebuild], Shift+R builds and installs before launching, which is what somebody
+    watching their own log almost always means by restart: it used to relaunch whatever was
+    already on the device, so the log filled with the code they had just changed away from and
+    nothing said why. Without one it relaunches, which is all `mkit logs` can do from outside a
+    project.
+
+    The stream is stopped and started around each restart rather than left running. A rebuild
+    prints over the top of a live log otherwise, and after an install the filter has to be worked
+    out again; see [_logcat_argv].
+    """
+    out = output.out
+    out.line('following logs; Shift+R rebuilds, installs and restarts, Ctrl+C stops' if rebuild
+             else 'following logs; Shift+R restarts the app, Ctrl+C stops' if restart
+             else 'following logs; Ctrl+C stops', 'dim')
+
+    while True:
+        process = subprocess.Popen(_logcat_argv(adb, device, package, tags, everything))
+        try:
+            asked = _wait_for_restart(process, restart)
+        finally:
+            _stop(process)
+        if not asked:
+            return
+
+        if rebuild:
+            out.line('rebuilding', 'dim')
+            try:
+                rebuild()
+            except Exception as error:
+                # Back to the log rather than out of it. A build breaks constantly and the
+                # whole point of this key is not having to leave; the app on the device is
+                # simply still the last one that built.
+                out.warn(f'rebuild failed, app left as it was: {error}')
+                continue
+        out.line('restarting app', 'dim')
+        launch(adb, device, package, clear_log=False)
+
+
+def avds(root=None):
+    exe = toolchain.emulator(root)
+    return exe, [l.strip() for l in proc.run([exe, '-list-avds'], check=False).splitlines()
+                 if l.strip() and not l.startswith('INFO')]
+
+
+def start_emulator(adb, exe, avd, root=None, wait=240):
+    """Kill running emulators, boot `avd` cold, wait for boot to complete."""
+    adb('emu', 'kill')
+    if os.name == 'nt':
+        for image in ('emulator.exe', 'qemu-system-x86_64.exe'):
+            subprocess.run(['taskkill', '/F', '/IM', image, '/T'],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    flags = getattr(subprocess, 'CREATE_NEW_PROCESS_GROUP', 0)
+    subprocess.Popen([exe, '-avd', avd, '-no-boot-anim', '-no-audio', '-gpu', 'host', '-no-snapshot'],
+                     cwd=root, creationflags=flags, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    deadline = time.time() + wait
+    while time.time() < deadline:
+        time.sleep(2)
+        output.out.tick()
+        serial = next((s for s, st in adb.devices() if is_emulator(s) and st == 'device'), None)
+        if serial and adb('shell', 'getprop', 'sys.boot_completed', device=serial).strip() == '1':
+            return serial
+    raise MkitError(f'{avd} did not finish booting in {wait}s', code='EMULATOR_TIMEOUT')

mkit/docgen.py

@@ -0,0 +1,100 @@
+"""docs/commands.md, generated from the command registry.
+
+The reference is built from the same declarations the CLI is built from, so
+it cannot describe a flag that does not exist. tests/test_docs.py fails when
+the committed file is stale; `python scripts/gen_docs.py` rewrites it.
+"""
+from . import __version__
+from .registry import GROUPS, REGISTRY, RISKS
+
+RISK_NOTE = {
+    'read': 'looks only, changes nothing',
+    'plan': 'reads remote state and shows a diff, changes nothing',
+    'write': 'changes local files/git or a non-user-facing remote thing',
+    'publish': 'changes what users, testers or Play review see; always confirmed',
+}
+
+SECTIONS = (
+    ('Develop', ('run', 'devices', 'logs', 'emu', 'studio', 'version', 'bump', 'gradle')),
+    ('Release', ('deploy', 'status', 'promote', 'rollout', 'share')),
+    ('Store', ('listing', 'whatsnew', 'datasafety', 'testers')),
+    ('Money', ('products', 'prices')),
+    ('Insight', ('stats', 'vitals', 'crashes', 'reviews', 'aso')),
+    ('Firebase', ('rules', 'config', 'remoteconfig', 'firebase')),
+    ('About mkit', ('doctor', 'commands', 'schema', 'manual', 'init', 'self')),
+)
+
+
+def _usage(cmd):
+    parts = [f'mkit {cmd.name}']
+    for a in cmd.args:
+        flag = f'--{a.name.replace("_", "-")}'
+        if a.kind == 'positional':
+            parts.append(f'[{a.name}]' if a.nargs in ('?', '*') else f'<{a.name}...>' if a.nargs == '...' else f'<{a.name}>')
+        elif a.kind == 'flag':
+            parts.append(f'[-{a.short}]' if a.short and not a.long
+                         else f'[-{a.short}|{flag}]' if a.short else f'[{flag}]')
+        else:
+            parts.append(f'[{flag} {a.name.upper()}]')
+    return ' '.join(parts)
+
+
+def _section_of(name):
+    head = name.split(' ')[0]
+    for title, names in SECTIONS:
+        if head in names:
+            return title
+    return 'Other'
+
+
+def render():
+    lines = [
+        '# mkit command reference',
+        '',
+        f'Generated from the command registry (mkit {__version__.rsplit(".", 1)[0]}.x). '
+        'Do not edit by hand: run `python scripts/gen_docs.py`.',
+        '',
+        'Global options, accepted before or after any command: `--json`, `--human`, '
+        '`--project PATH`, `--dry-run`, `--strict`, `--yes --confirm PACKAGE`, `--no-color`.',
+        '',
+        '## Risk classes',
+        '',
+        '| Class | Meaning |',
+        '|---|---|',
+    ]
+    lines += [f'| {r} | {RISK_NOTE[r]} |' for r in RISKS]
+    by_section = {}
+    for name in sorted(REGISTRY):
+        by_section.setdefault(_section_of(name), []).append(REGISTRY[name])
+    for title, _ in SECTIONS + (('Other', ()),):
+        cmds = by_section.get(title)
+        if not cmds:
+            continue
+        lines += ['', f'## {title}', '']
+        lines += ['| Command | Risk | What |', '|---|---|---|']
+        lines += [f'| `{c.name}` | {c.risk} | {c.summary} |' for c in cmds]
+        for c in cmds:
+            lines += ['', f'### mkit {c.name}', '', f'`{c.risk}`'
+                      + (f', needs `[{"]`, `[".join(c.needs)}]` in mkit.toml' if c.needs else ''), '']
+            text = c.description or c.summary
+            # Collapse the whitespace rather than swapping newlines for spaces: a
+            # source file checked out with CRLF leaves a stray carriage return in
+            # the middle of the line, so the same command rendered differently on
+            # Windows than on Linux and the committed reference could not be
+            # current on both at once. CI found this the day it was switched on.
+            summary = ' '.join(text.split('\n\n')[0].split())
+            lines += [summary, '', '```', _usage(c), '```']
+            if c.args:
+                lines += ['', '| Argument | What |', '|---|---|']
+                for a in c.args:
+                    label = a.name if a.kind == 'positional' else f'--{a.name.replace("_", "-")}'
+                    if a.short:
+                        label = f'-{a.short}' if not a.long else f'-{a.short}, {label}'
+                    extra = f' (one of {", ".join(a.choices)})' if a.choices else ''
+                    extra += f' (default {a.default})' if a.default not in (None, False) else ''
+                    lines.append(f'| `{label}` | {a.help}{extra} |')
+            if c.examples:
+                lines += ['', 'Examples:', '', '```'] + list(c.examples) + ['```']
+    group_lines = [f'- `{g}`: {s}' for g, s in sorted(GROUPS.items())]
+    lines += ['', '## Command groups', ''] + group_lines + ['']
+    return '\n'.join(lines)