painapple-code 1.0.0__py3-none-any.whl

painapple_code/cli/netinfo.py

@@ -0,0 +1,125 @@
+"""Host network introspection shared by the setup wizards and the
+container launch path. Import-cheap: stdlib plus psutil, both imported
+inside the functions so importing this module stays nearly free."""
+
+import sys
+
+
+def detect_local_ips():
+    """[(ip, interface)] for every non-loopback IPv4 the host has.
+
+    psutil rather than parsing `ip`/`ifconfig`: neither exists on Windows,
+    and ipconfig's output is localized (and OEM-encoded), so scraping it
+    would break on any non-English install. psutil is a hard dependency
+    (requirements.txt, no environment marker), so there is no fallback to
+    keep — the old scrape sat behind an ImportError that cannot fire.
+    """
+    import socket
+
+    import psutil
+
+    results = []
+    try:
+        stats = psutil.net_if_stats()
+        for iface, addrs in psutil.net_if_addrs().items():
+            st = stats.get(iface)
+            if st is not None and not st.isup:
+                continue
+            for addr in addrs:
+                if addr.family != socket.AF_INET:
+                    continue
+                ip = addr.address
+                if ip.startswith("127.") or iface in ("lo", "lo0"):
+                    continue
+                results.append((ip, iface))
+    except Exception:
+        pass  # exotic/unsupported interface table — report what we got
+    return results
+
+
+def port_taken(host, port):
+    """Reason string when `host:port` can't be bound, '' when it's free.
+
+    A plain bind test — catches ANY holder, unlike a scan of painapple's
+    own process table. Used by the server's own pre-flight and by
+    `painapple start` so the failure is reported before a detached child
+    inherits it. Unresolvable host counts as taken (with the reason)."""
+    import socket
+    try:
+        infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    except socket.gaierror as e:
+        return f"cannot resolve host {host!r} ({e})"
+    family, socktype, proto, _canon, sockaddr = infos[0]
+    with socket.socket(family, socktype, proto) as sock:
+        # SO_REUSEADDR means opposite things on the two platforms. On POSIX
+        # it only skips the TIME_WAIT guard, which is what we want here. On
+        # Windows it permits binding a port another socket is ACTIVELY
+        # listening on (Microsoft's documented port-hijacking behavior) —
+        # so this probe would report "free" while a server was running, and
+        # every caller (boot pre-flight, `painapple start`, the container
+        # launcher) would happily start a second instance on the same port,
+        # after which Windows routes new connections to whichever bound
+        # last. Setting nothing on win32 gives the strict bind we need.
+        if sys.platform != "win32":
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind(sockaddr)
+        except OSError as e:
+            return e.strerror or str(e)
+    return ""
+
+
+def _listener_pid(port):
+    """PID of whatever holds the listening socket on `port`, or None.
+    Never raises — every caller is decoration."""
+    try:
+        import psutil
+        for conn in psutil.net_connections(kind="inet"):
+            if (conn.status == psutil.CONN_LISTEN and conn.laddr
+                    and conn.laddr.port == int(port) and conn.pid):
+                return conn.pid
+    except Exception:
+        pass  # AccessDenied for other users' sockets
+    return None
+
+
+def port_holder(port):
+    """Best-effort description of what already listens on `port` — the
+    painapple instance if it's one of ours, else whatever ss/lsof names.
+    '' when nothing can be determined. Never raises (decoration only)."""
+    try:
+        from painapple_code.cli.list_cmd import local_servers
+        rows = [r for r in local_servers() if str(r["port"]) == str(port)]
+        # One server can present as SEVERAL rows on Windows: the pipx
+        # console-script launcher (painapple.exe), the python.exe it
+        # spawns, and uvicorn's reload child all carry the same argv, so
+        # all three match. Picking the first gave whichever the process
+        # scan happened to list first — usually the launcher shim, whose
+        # cwd is %TEMP%, so the error blamed a real port conflict on a
+        # workspace the user had never heard of. Prefer the row that
+        # actually owns the listening socket.
+        listener = _listener_pid(port)
+        row = next((r for r in rows if r["pid"] == listener), None)
+        if row is None and rows:
+            row = rows[0]
+        if row:
+            label = row.get("name") or "unnamed instance"
+            return (f"painapple '{label}' (pid {row['pid']}, "
+                    f"workspace {row.get('workspace') or '?'})")
+    except Exception:
+        pass
+
+    # psutil: works on all three platforms and needs no ss/lsof. (On
+    # Windows neither exists, so the holder was always reported as unknown
+    # — the user got "port in use" with no way to tell what by.) The ss/
+    # lsof scrape that used to follow this was unreachable-by-design
+    # fallback: psutil is a hard dependency, so it only ever ran when
+    # psutil ALSO failed, in which case ss wouldn't have known better.
+    holder = _listener_pid(port)
+    if holder is not None:
+        try:
+            import psutil
+            return f"{psutil.Process(holder).name()} (pid {holder})"
+        except Exception:
+            return f"pid {holder}"
+    return ""

painapple_code/cli/profiles.py

@@ -0,0 +1,390 @@
+"""Unified profile store — named deployments with a run mode.
+
+A profile is a named, independent deployment at
+``~/.painapple-code/profiles/NAME/profile.yaml`` whose ``mode`` says
+HOW it runs:
+
+* ``mode: host``   — a local server. The profile dir IS its data home
+  (sessions, shadow DB, logs, config.json) — isolation is mandatory,
+  not cosmetic, since DuckDB is single-writer. Running it repoints
+  ``PAINAPPLE_CODE_HOME`` at the dir before the server boots
+  (:func:`activate`); every path helper follows for free.
+* ``mode: docker`` — a container sandbox. Only ``profile.yaml`` lives
+  in the profile dir; data lives in the container's volume (``/data``).
+  ``claude_home`` defaults to the shared ``shared/.claude`` so one
+  login serves every sandbox.
+
+Shared keys use the serve vocabulary (``host`` = bind, ``tls``,
+``port``, ``workspace``, ``instance_name``, ``accent``); docker mode
+adds its own (image, container, volumes, workspace_mode, …) — see
+cli/deploy/config.py for that half of the model.
+
+Migration: :func:`ensure_migrated` adopts the two pre-unification
+stores — ``serve-profiles/NAME/serve.yaml`` (moved wholesale; a
+symlink is left behind so hand-written service units keep working) and
+``docker-profiles/NAME/docker.yaml`` — plus the root ``docker.yaml``
+(runtime defaults merge into serve.yaml; the deployment itself is
+adopted as a profile only if its container/volume actually exists).
+Idempotent and loud.
+"""
+
+import os
+import re
+import shutil
+from pathlib import Path
+
+from painapple_code.cli import serve_config
+from painapple_code.cli.serve_config import (
+    HOST_KEYS, LEGACY_DOCKER_PROFILES_DIR, LEGACY_SERVE_PROFILES_DIR,
+    PROFILES_DIR, root_home,
+)
+
+PROFILE_FILE = "profile.yaml"
+MODES = ("host", "docker")
+
+_PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$")
+
+# 'default' means the flag-less root deployment in every verb — a
+# profile by that name could never be addressed.
+_RESERVED_NAMES = {"default"}
+
+
+def valid_name(name):
+    name = (name or "").strip()
+    return bool(_PROFILE_RE.match(name)) and name not in _RESERVED_NAMES
+
+
+def profiles_root(root=None):
+    return (root or root_home()) / PROFILES_DIR
+
+
+def profile_home(name, root=None):
+    return profiles_root(root) / name
+
+
+def profile_path(name, root=None):
+    return profile_home(name, root) / PROFILE_FILE
+
+
+def exists(name, root=None):
+    return profile_path(name, root).is_file()
+
+
+def list_profiles(root=None):
+    """Named profiles that have a profile.yaml on disk (sorted)."""
+    base = profiles_root(root)
+    if not base.is_dir():
+        return []
+    return sorted(p.name for p in base.iterdir()
+                  if p.is_dir() and (p / PROFILE_FILE).is_file())
+
+
+class Profile:
+    """One loaded profile: ``name``, ``mode``, raw ``data`` dict, and
+    the load ``problems`` list (unknown/bad values, reported not fatal)."""
+
+    def __init__(self, name, mode, data, problems=None):
+        self.name = name
+        self.mode = mode
+        self.data = data
+        self.problems = problems or []
+
+    @property
+    def is_docker(self):
+        return self.mode == "docker"
+
+    def home(self, root=None):
+        return profile_home(self.name, root)
+
+    def host_values(self):
+        """Validated host-vocabulary subset (what the server layers /
+        what list & lifecycle read for a host profile)."""
+        values = {}
+        for key in HOST_KEYS:
+            raw = self.data.get(key)
+            if raw in (None, ""):
+                continue
+            try:
+                values[key] = serve_config._check(key, raw)
+            except ValueError:
+                continue
+        return values
+
+    def docker_settings(self):
+        """DockerSettings for a docker-mode profile (lazy import — keeps
+        this module light for the activation path)."""
+        from painapple_code.cli.deploy.config import settings_from_data
+        return settings_from_data(self.data, profile=self.name)
+
+    def label(self):
+        return self.data.get("instance_name") or self.name
+
+
+def load(name, root=None):
+    """Load ``profiles/NAME/profile.yaml`` → :class:`Profile`. Returns
+    None when the profile doesn't exist. Never raises on bad content —
+    problems are collected on the returned object."""
+    path = profile_path(name, root)
+    if not path.is_file():
+        return None
+    import yaml
+    problems = []
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError) as e:
+        return Profile(name, "host", {}, [f"unreadable ({e})"])
+    if not isinstance(data, dict):
+        return Profile(name, "host", {}, ["not a key: value mapping"])
+    mode = str(data.pop("mode", "host") or "host").strip()
+    if mode not in MODES:
+        problems.append(f"unknown mode {mode!r} — treating as 'host'")
+        mode = "host"
+    return Profile(name, mode, data, problems)
+
+
+def save(name, mode, data, root=None):
+    """Write ``profiles/NAME/profile.yaml``. ``data`` keys with empty
+    values are dropped. Returns the path written."""
+    if not valid_name(name):
+        raise ValueError(
+            f"Bad profile name: {name!r} (letters/digits/._- only, max 32 chars)")
+    if mode not in MODES:
+        raise ValueError(f"Bad profile mode: {mode!r}")
+    import yaml
+    path = profile_path(name, root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    kept = {"mode": mode}
+    for key, value in data.items():
+        if value in (None, "", []):
+            continue
+        kept[key] = value
+    body = yaml.safe_dump(kept, default_flow_style=False, sort_keys=False)
+    path.write_text(
+        f"# Profile '{name}' — written by `painapple setup {name}`, editable by hand.\n"
+        "# mode: host (local server; this dir is its data home) or docker (container).\n"
+        + body, encoding="utf-8")
+    from painapple_code.paths import lock_mode
+    lock_mode(path, 0o600)  # icacls on win32; chmod is a no-op there
+    return path
+
+
+def resolve_home(name, root):
+    """The data home ``--profile NAME`` resolves to, given the launching
+    process's own PAINAPPLE_CODE_HOME (``root``). Pure path arithmetic,
+    creating nothing — :func:`activate` uses it for this process, and the
+    fleet-view scan uses it to reproduce the same answer for SOMEONE
+    ELSE's process from its argv. Unusable names fall back to ``root``.
+    """
+    name = (name or "").strip()
+    root = Path(root)
+    if name in ("", "default") or not valid_name(name):
+        return root
+    if root.name == name and root.parent.name in (PROFILES_DIR,
+                                                  LEGACY_SERVE_PROFILES_DIR):
+        # PAINAPPLE_CODE_HOME already points AT this profile's home (a
+        # spawner — `painapple start`, a service unit — exported both
+        # env vars). Re-appending profiles/NAME would nest a second home
+        # inside the first; adopt the given home instead.
+        return root
+    return root / PROFILES_DIR / name
+
+
+def activate(name):
+    """Repoint PAINAPPLE_CODE_HOME at a HOST profile's data home
+    (created if absent) and record the name in PAINAPPLE_PROFILE, so
+    every downstream path helper — and the config layering — targets
+    the profile. ``''``/``default`` is a no-op (the root deployment).
+    Returns the home Path. Raises ValueError on a bad name."""
+    name = (name or "").strip()
+    if name in ("", "default"):
+        return serve_config.home_root()
+    if not valid_name(name):
+        raise ValueError(
+            f"Bad profile name: {name!r} (letters/digits/._- only, max 32 chars)")
+    home = resolve_home(name, serve_config.home_root())
+    home.mkdir(parents=True, exist_ok=True)
+    os.environ["PAINAPPLE_CODE_HOME"] = str(home)
+    os.environ["PAINAPPLE_PROFILE"] = name
+    return home
+
+
+# ──── Migration (serve-profiles/ + docker-profiles/ + root docker.yaml) ──
+
+_migrated_this_process = False
+
+
+def _free_name(name, taken):
+    if name not in taken and not exists(name):
+        return name
+    for candidate in (f"{name}-docker", *(f"{name}-{i}" for i in range(2, 20))):
+        if candidate not in taken and not exists(candidate):
+            return candidate
+    return None
+
+
+def _adopt_serve_profile(root, name, notes):
+    src = root / LEGACY_SERVE_PROFILES_DIR / name
+    if exists(name, root):
+        notes.append(f"'{name}': profiles/{name} already exists — "
+                     f"left {src} untouched")
+        return
+    dst = profile_home(name, root)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    import yaml
+    try:
+        data = yaml.safe_load((src / "serve.yaml").read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError) as e:
+        notes.append(f"'{name}': unreadable serve.yaml ({e}) — skipped")
+        return
+    if not isinstance(data, dict):
+        data = {}
+    # Move the WHOLE dir — it's the profile's data home (sessions,
+    # DuckDB, logs ride along).
+    shutil.move(str(src), str(dst))
+    (dst / "serve.yaml").unlink(missing_ok=True)
+    save(name, "host", data, root)
+    # Leave a symlink so hand-written service units / scripts that
+    # exported PAINAPPLE_CODE_HOME=…/serve-profiles/NAME keep working.
+    try:
+        src.symlink_to(Path("..") / PROFILES_DIR / name)
+    except OSError:
+        pass
+    notes.append(f"adopted serve profile '{name}' → profiles/{name} (mode: host)")
+
+
+def _adopt_docker_profile(root, name, notes):
+    src = root / LEGACY_DOCKER_PROFILES_DIR / name
+    legacy_yaml = src / "docker.yaml"
+    if not legacy_yaml.is_file():
+        notes.append(f"'{name}': wrapper.conf-only docker profile — not "
+                     f"adopted (re-create with: painapple setup {name})")
+        return
+    target = _free_name(name, set())
+    if target is None:
+        notes.append(f"'{name}': no free profile name — skipped")
+        return
+    import yaml
+    try:
+        data = yaml.safe_load(legacy_yaml.read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError) as e:
+        notes.append(f"'{name}': unreadable docker.yaml ({e}) — skipped")
+        return
+    from painapple_code.cli.deploy.config import (
+        settings_from_data, settings_to_data)
+    settings = settings_from_data(data, profile=name)
+    save(target, "docker", settings_to_data(settings), root)
+    for leftover in ("docker.yaml", "wrapper.conf"):
+        (src / leftover).unlink(missing_ok=True)
+    try:
+        src.rmdir()
+    except OSError:
+        pass  # stray files — leave the dir
+    suffix = "" if target == name else f" (renamed — '{name}' was taken)"
+    notes.append(f"adopted docker profile '{name}' → profiles/{target} "
+                 f"(mode: docker){suffix}")
+
+
+def _adopt_root_docker(root, notes):
+    legacy_yaml = root / "docker.yaml"
+    if not legacy_yaml.is_file():
+        return
+    import yaml
+    try:
+        data = yaml.safe_load(legacy_yaml.read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError) as e:
+        notes.append(f"root docker.yaml unreadable ({e}) — left in place")
+        return
+    if not isinstance(data, dict):
+        data = {}
+
+    # 1. Runtime/image defaults → the global serve.yaml (the
+    #    `--in-docker` defaults), only where serve.yaml doesn't already
+    #    have a value.
+    current, _ = serve_config.load()
+    merged = dict(current)
+    took = []
+    for key in serve_config.DEPLOY_KEYS:
+        if merged.get(key) in (None, "") and data.get(key) not in (None, ""):
+            merged[key] = str(data[key])
+            took.append(key)
+    if took:
+        try:
+            serve_config.save(merged)
+            notes.append("root docker.yaml: merged "
+                         f"{', '.join(took)} into serve.yaml (--in-docker defaults)")
+        except ValueError as e:
+            notes.append(f"root docker.yaml: could not merge defaults ({e})")
+
+    # 2. The deployment itself becomes a profile only if it was real —
+    #    a container or volume with its configured names exists.
+    from painapple_code.cli.deploy.config import (
+        settings_from_data, settings_to_data)
+    settings = settings_from_data(data, profile=None)
+    live = False
+    if shutil.which("docker") or shutil.which("podman") or settings.runtime:
+        try:
+            from painapple_code.cli.deploy.runtime import Runtime
+            rt = Runtime(settings)
+            live = (rt.container_exists(settings.container)
+                    or (not settings.data_is_bind()
+                        and rt.volume_exists(settings.data_volume)))
+        except (SystemExit, OSError):
+            live = False
+    if live:
+        target = _free_name("docker", set())
+        if target:
+            save(target, "docker", settings_to_data(settings), root)
+            notes.append(f"adopted the root docker deployment → "
+                         f"profiles/{target} (mode: docker)")
+
+    # os.replace: a re-run after a partial migration already left a
+    # .migrated file behind — Path.rename would raise on win32 then.
+    os.replace(legacy_yaml, legacy_yaml.with_suffix(".yaml.migrated"))
+    notes.append("root docker.yaml → docker.yaml.migrated (superseded by "
+                 "serve.yaml + profiles)")
+
+
+def ensure_migrated(announce=None):
+    """Adopt pre-unification stores into ``profiles/``. Idempotent;
+    cheap when there's nothing to do. ``announce`` is called with one
+    human line per action (default: cli.ui.info)."""
+    global _migrated_this_process
+    if _migrated_this_process:
+        return []
+    _migrated_this_process = True
+
+    root = root_home()
+    serve_dir = root / LEGACY_SERVE_PROFILES_DIR
+    docker_dir = root / LEGACY_DOCKER_PROFILES_DIR
+    serve_names = []
+    if serve_dir.is_dir():
+        serve_names = sorted(
+            p.name for p in serve_dir.iterdir()
+            if p.is_dir() and not p.is_symlink() and (p / "serve.yaml").is_file())
+    docker_names = []
+    if docker_dir.is_dir():
+        docker_names = sorted(
+            p.name for p in docker_dir.iterdir()
+            if p.is_dir() and ((p / "docker.yaml").is_file()
+                               or (p / "wrapper.conf").is_file()))
+    has_root_docker = (root / "docker.yaml").is_file()
+    if not serve_names and not docker_names and not has_root_docker:
+        return []
+
+    notes = []
+    for name in serve_names:          # host profiles first: name wins
+        _adopt_serve_profile(root, name, notes)
+    for name in docker_names:
+        _adopt_docker_profile(root, name, notes)
+    if has_root_docker:
+        _adopt_root_docker(root, notes)
+
+    if notes:
+        if announce is None:
+            from painapple_code.cli.ui import info
+            announce = info
+        announce("Migrating to the unified profile store "
+                 f"({profiles_root(root)}):")
+        for note in notes:
+            announce(f"  {note}")
+    return notes

painapple_code/cli/serve_args.py

@@ -0,0 +1,163 @@
+"""Argument parser for ``painapple serve`` — the single source of truth.
+
+IMPORT-LIGHT ZONE: this module is the fast path for ``-v`` /
+``serve --help`` / argparse errors, which ``cli.main()`` resolves
+*before* paying the ~300ms ``painapple_code.server`` import. It may
+import ``argparse``, ``os``, ``sys``, and ``painapple_code.__version__``
+— NOTHING else. No server, no fastapi, no routes, no yaml.
+``tests/test_cli_startup.py`` asserts fastapi stays unimported.
+
+Both callers build from here, so help/error output and parsing are
+byte-identical by construction:
+
+- ``cli.main()`` — the fast gate (parse, then discard)
+- ``server.main()`` — the real boot (re-parse, ~1ms, keeps its
+  signature and late ``parser.error()`` calls unchanged)
+"""
+
+import argparse
+import os
+import sys
+
+from painapple_code import __version__
+
+#: Default bind port. Shared with ``server.resolve_allowed_origins()``, which
+#: derives its no-config trusted-origin fallback from it — keep it a constant so
+#: the two can't drift (they did: a hardcoded origin list outlived a port
+#: renumber and shipped a stale port as a trusted default for months).
+DEFAULT_PORT = 8765
+
+
+def _subcommands_epilog():
+    """Epilog for `serve --help` pointing back at the command overview
+    and the other subcommands (the curated front door is `painapple
+    help`; this page is deliberately just the full serve-flag dump).
+
+    argparse colorizes its own generated help (usage, option strings,
+    section headings) on Python 3.14+, but passes this free-form epilog
+    through verbatim — so it renders plain while everything above it is
+    colored. Match argparse's own decision: colorize the block only when
+    argparse would (3.14+, a TTY, and NO_COLOR unset), otherwise emit
+    plain text. ANSI codes have zero display width, so column alignment
+    is unaffected.
+    """
+    color = (
+        sys.version_info >= (3, 14)
+        and sys.stdout.isatty()
+        and not os.environ.get("NO_COLOR")
+    )
+    b = "\033[1m" if color else ""   # bold heading
+    g = "\033[32m" if color else ""  # green subcommand
+    d = "\033[2m" if color else ""   # dim description
+    r = "\033[0m" if color else ""
+    return "\n".join((
+        f"{b}profiles{r}:",
+        f"  painapple {g}--profile NAME{r}   {d}run a named deployment in the foreground (own port/data/sessions){r}",
+        f"  painapple {g}setup NAME{r}       {d}create/edit that profile (host or docker mode){r}",
+        "",
+        f"{b}more{r}:",
+        f"  painapple {g}help{r}          {d}command overview (setup · list · start/stop/restart · status · …){r}",
+        f"  painapple {g}setup{r}         {d}save global defaults for these flags (~/.painapple-code/serve.yaml){r}",
+        f"  painapple {g}list{r}          {d}every instance on this machine (profiles + running processes){r}",
+    ))
+
+
+def build_parser():
+    """The full ``painapple serve`` flag parser."""
+    parser = argparse.ArgumentParser(
+        prog="painapple", description="pAInapple Code Server",
+        usage="painapple [serve] [--port N] [--workspace PATH] [flags…]",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_subcommands_epilog())
+    parser.add_argument("-v", "--version", action="version",
+                        version=f"painapple {__version__}")
+
+    core = parser.add_argument_group(
+        "server", "where it listens and what it works on")
+    core.add_argument("--host", default="127.0.0.1",
+                      help="Host interface to bind (default 127.0.0.1 — this machine "
+                           "only; 0.0.0.0 = every interface, reachable on your LAN)")
+    core.add_argument("--port", type=int, default=DEFAULT_PORT, help="Port to bind to")
+    core.add_argument("--workspace", "--cwd", dest="workspace", default=".",
+                      help="Workspace root — the directory holding your projects. "
+                           "You pick the actual project in-app from the welcome "
+                           "screen, and each session's files/git/terminal follow "
+                           "its own directory. This anchors the file explorer and "
+                           "the welcome screen's project suggestions. Mapped to "
+                           "/workspace inside Docker. (--cwd is an alias)")
+    core.add_argument("--instance-name", default=None,
+                      help="Instance label for PWA icon and UI (e.g., DEV, STABLE)")
+    core.add_argument("--accent", default=None,
+                      help="Accent color: preset (blue/green/red/orange/purple/cyan/gray/yellow/pink/teal/indigo/lime) or hex (#f87171)")
+    core.add_argument("--in-docker", action="store_true",
+                      help="Run this same invocation inside a container instead "
+                           "(Docker/Podman): the workspace (default: current dir) is "
+                           "mounted into the prebuilt image, foreground, Ctrl-C stops "
+                           "it. Runtime/image defaults come from `painapple setup`; "
+                           "fetch the image once with `painapple pull`.")
+
+    net = parser.add_argument_group(
+        "network security", "TLS for non-loopback binds")
+    net.add_argument("--tls", choices=("auto", "on", "off"), default="auto",
+                     help="TLS mode. 'auto' (default) enables TLS when binding to a non-loopback "
+                          "host. 'on' forces TLS. 'off' disables it. Self-signed cert is "
+                          "auto-generated; clients accept it without verification (TLS here "
+                          "guards against passive snooping only).")
+    pw = net.add_mutually_exclusive_group()
+    pw.add_argument("--no-password", "--no-passwd", dest="no_password",
+                    action="store_true",
+                    help="Never print credentials to stdout: the startup box hides "
+                         "the password and strips the ?tkn= from the login URL. "
+                         "Retrieve them later with `painapple password` or from the "
+                         "auth config file. Useful when the console is visible to "
+                         "others (screen shares, recorded demos, shared logs). "
+                         "This is already the default on non-loopback binds.")
+    pw.add_argument("--show-password", dest="show_password",
+                    action="store_true",
+                    help="Print credentials even on a non-loopback bind. By default "
+                         "only loopback binds (127.0.0.1/::1/localhost) show the "
+                         "password and ?tkn= login URL — a LAN/public server's "
+                         "stdout tends to outlive the terminal (journald, docker "
+                         "logs), so there they're hidden unless you opt in.")
+    net.add_argument("--tls-cert", default=None, metavar="PATH",
+                     help="TLS cert path (default: <config-dir>/cert.pem, auto-generated)")
+    net.add_argument("--tls-key", default=None, metavar="PATH",
+                     help="TLS key path (default: <config-dir>/key.pem, auto-generated)")
+
+    adv = parser.add_argument_group(
+        "advanced", "provider choice and opt-in extras")
+    adv.add_argument("--default-provider", default=None, metavar="NAME",
+                     help="Provider for NEW sessions (existing sessions keep their "
+                          "recorded provider). Overrides the `default_provider` "
+                          "global-config key. E.g. 'claude-sdk' (Agent SDK driver — "
+                          "interactive permission cards, live mode/model switching; "
+                          "default) or 'claude' (line protocol).")
+    adv.add_argument("--public-origin", action="append", default=None, metavar="ORIGIN",
+                     help="Trusted browser origin for a proxied deployment, e.g. "
+                          "https://claude.example.com. Repeatable. Adds to the "
+                          "HTTP/WebSocket Origin allowlist (and replaces the default, "
+                          "which trusts only loopback on the bound port). Also "
+                          "honoured via PAINAPPLE_ALLOWED_ORIGINS.")
+    adv.add_argument("--enable-renderers", action="store_true",
+                     help="Enable server-side Vega-Lite/Excalidraw rendering (off by "
+                          "default: model-authored specs are rendered via a Node "
+                          "subprocess whose data loader can fetch external/file URLs — "
+                          "an SSRF/local-file-read vector. Also honoured via the "
+                          "PAINAPPLE_ENABLE_RENDERERS env var).")
+
+    tiers = parser.add_argument_group(
+        "multi-instance", "isolate state when several servers share one user "
+        "(each instance needs its own shadow DB — DuckDB is single-writer)")
+    tiers.add_argument("--shadow-db", default=None, metavar="PATH",
+                       help="DuckDB path for shadow DB (default: ~/.painapple-code/shadow.duckdb)")
+    tiers.add_argument("--log-dir", default=None, metavar="PATH",
+                       help="Log directory (default: ~/.painapple-code/logs/)")
+    tiers.add_argument("--state-suffix", default=None, metavar="SUFFIX",
+                       help="Per-tier suffix for UI-state files (tab-state, shortcuts, "
+                            "presets, favorites, global config) so co-located tiers don't "
+                            "share them, e.g. 'dev' gives tab-state-dev.json (a leading "
+                            "'-' is added automatically). Project and session history "
+                            "stays shared. Default: none (stable tier).")
+    tiers.add_argument("--auth-config-file", default=None, metavar="PATH",
+                       help="Config file path (default: ~/.config/painapple-code/config.yaml)")
+    return parser