1panel-toolkit 0.3.0__py3-none-any.whl

p1toolkit/cli.py

@@ -0,0 +1,890 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__, rules
+from .checks import run_all
+from . import config as config_module
+from . import depth as depth_module
+from .patterns import (
+    DATA_FILE,
+    build as build_patterns,
+    categories as pattern_categories,
+    find as find_patterns,
+    get as get_pattern,
+    load_bundled,
+    patterns as all_patterns,
+    render_markdown,
+    save as save_patterns,
+)
+from .loader import LoadError, load_package
+from .net import probe, parse_ports
+from .panel import PanelClient, PanelError, connect as connect_panel
+from .report import FAIL, Report
+from .resolve import SourceError as ResolveSourceError
+from .resolve import resolve as resolve_target
+from .resolve import write_outputs as write_resolve_outputs
+from .remote import RemoteError, SshTarget, check_host, smoke as run_smoke
+from .gen import GenResult, SpecError, generate as generate_package, load_spec
+from .deploy import DeployError, deploy as run_deploy, remove_local, uninstall as run_uninstall
+from .selftest import run as run_selftest
+from .fix import fix as run_fix
+
+
+def _iter_targets(path: Path) -> list[Path]:
+    """A package root, or a directory holding several of them."""
+    if path.is_file():
+        raise NotADirectoryError(
+            f"{path} 是文件；请传应用包根目录（含 data.yml），例如 ./project/app/1panel-apps/app"
+        )
+    if (path / "data.yml").exists():
+        return [path]
+    found = [child for child in sorted(path.iterdir()) if (child / "data.yml").exists()]
+    return found or [path]
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    target = Path(args.path).resolve()
+    if not target.exists():
+        print(f"error: no such path: {target}", file=sys.stderr)
+        return 2
+    reports: list[Report] = []
+    try:
+        roots = _iter_targets(target)
+    except NotADirectoryError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    for package_root in roots:
+        try:
+            package = load_package(package_root)
+        except LoadError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        reports.append(run_all(package, strict=args.strict))
+
+    if args.json:
+        import json
+
+        print(json.dumps([r.to_dict() for r in reports], ensure_ascii=False, indent=2))
+    else:
+        for report in reports:
+            print(report.render())
+            print()
+    return 0 if all(r.ok for r in reports) else 1
+
+
+def cmd_rules(args: argparse.Namespace) -> int:
+    data = rules.load(args.name)
+    if args.key:
+        data = data.get(args.key, {})
+    import json
+
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_ports(args: argparse.Namespace) -> int:
+    try:
+        ports = parse_ports(args.ports)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    results = probe(args.host, ports, timeout=args.timeout)
+    for result in results:
+        print(f"{result.port:>6}  {result.state:<8} {result.detail}")
+    usable = [r.port for r in results if r.usable]
+    if usable:
+        print(f"\nusable for a new service (host reachable, nothing listening): {usable}")
+    return 0
+
+
+def cmd_config(args: argparse.Namespace) -> int:
+    cfg = config_module.load()
+    if args.action == "set":
+        cfg.set(args.key, args.value)
+        path = cfg.save()
+        print(f"{args.key} -> {config_module.mask(args.key, args.value)}  ({path})")
+        return 0
+    if args.action == "unset":
+        cfg.values.pop(args.key, None)
+        print(f"removed {args.key}  ({cfg.save()})")
+        return 0
+    print(f"config: {cfg.path}")
+    if cfg.broken:
+        print(f"警告: 配置文件无法解析（{cfg.broken}）；执行 `p1 config set ...` 会重写它")
+    if not cfg.values:
+        print("(empty)")
+    for key, value in cfg.masked().items():
+        print(f"{key} = {value}")
+    return 0
+
+
+def cmd_panel(args: argparse.Namespace) -> int:
+    cfg = config_module.load()
+    try:
+        # `connect` probes v2 first and falls back to v1, so the same client
+        # works against either panel generation.
+        client = connect_panel(cfg.require("panel.url"), cfg.require("panel.api_key"))
+    except KeyError as exc:
+        print(f"error: {exc.args[0]}", file=sys.stderr)
+        return 2
+    try:
+        info = client.ping()
+    except PanelError as exc:
+        print(f"panel rejected the request: {exc}", file=sys.stderr)
+        print(
+            "check the API 接口 settings on the panel: the key must match and the "
+            "calling IP must be whitelisted.",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"panel ok: {cfg.get('panel.url')}")
+    for key in ("name", "version", "os", "arch"):
+        if info.get(key):
+            print(f"  {key}: {info[key]}")
+    return 0
+
+
+def cmd_patterns(args: argparse.Namespace) -> int:
+    import json
+
+    if args.action == "build":
+        data = build_patterns([Path(p).resolve() for p in args.corpus])
+        out = Path(args.out).resolve() if args.out else DATA_FILE
+        if args.out is None and not os.access(out.parent, os.W_OK):
+            print(
+                f"error: 默认输出位置 {out} 不可写（wheel 安装时在 site-packages 里）；"
+                "请用 --out 指定目录",
+                file=sys.stderr,
+            )
+            return 2
+        save_patterns(data, out)
+        print(f"wrote {out}")
+        for source in data["generated_from"]:
+            print(
+                f"  {source.get('label') or source.get('corpus', '?')}: "
+                f"{source['apps']} apps / {source['versions']} versions"
+            )
+        empty = [p["id"] for p in data["patterns"] if not p["examples"]]
+        if empty:
+            print(f"  patterns with no example found: {empty}")
+        if args.markdown:
+            target = Path(args.markdown).resolve()
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(render_markdown(data), encoding="utf-8")
+            print(f"wrote {target}")
+        return 0
+
+    data = load_bundled()
+    if args.action == "export":
+        target = Path(args.markdown).resolve()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(render_markdown(data), encoding="utf-8")
+        print(f"wrote {target}")
+        return 0
+
+    if args.action == "find":
+        selected = find_patterns(args.query, data)
+    elif args.action == "show":
+        pattern = get_pattern(args.pattern_id, data)
+        if pattern is None:
+            print(f"error: unknown pattern {args.pattern_id!r}", file=sys.stderr)
+            return 2
+        selected = [pattern]
+    else:
+        selected = all_patterns(data)
+        if args.category:
+            selected = [p for p in selected if p.category == args.category]
+
+    if args.json:
+        print(json.dumps([p.__dict__ for p in selected], ensure_ascii=False, indent=2))
+        return 0
+    if not selected:
+        print("no matching pattern")
+        return 1
+
+    if args.action == "show":
+        for pattern in selected:
+            print(f"# {pattern.id} — {pattern.title}")
+            print(f"\n用途：{pattern.intent}")
+            print(f"何时使用：{pattern.when_to_use}")
+            print(f"官方采用：{pattern.apps} 个应用 / {pattern.versions} 个版本")
+            for note in pattern.notes:
+                print(f"注意：{note}")
+            for index, example in enumerate(pattern.examples):
+                header = "示例" if index == 0 else f"备选示例 {index}"
+                print(f"\n--- {header}（来自 {example['app']}/{example['file']}）---")
+                print(example["snippet"])
+            return 0
+
+    width = max((len(p.id) for p in selected), default=10)
+    for pattern in selected:
+        print(f"{pattern.id:<{width}}  {pattern.apps:>4} apps  {pattern.title}")
+    return 0
+
+
+def cmd_depth(args: argparse.Namespace) -> int:
+    import json
+
+    corpora = [Path(p).resolve() for p in (args.corpus or [])]
+    if args.package:
+        target = Path(args.package).resolve()
+        profile = depth_module.profile_app(target)
+        if profile is None:
+            print(f"error: {target} is not an app package root", file=sys.stderr)
+            return 2
+        corpus: list[depth_module.Profile] = []
+        if corpora:
+            corpus = depth_module.scan(corpora)
+        if args.json:
+            payload = {
+                "profile": depth_module.asdict(profile),
+                "neighbours": [
+                    {"app": other.app, "score": round(score, 3), "shared": shared}
+                    for score, other, shared in depth_module.nearest(profile, corpus)
+                ],
+            }
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+            return 0
+        print(f"# {profile.app}/{profile.version}")
+        for label, values in (
+            ("镜像", profile.images),
+            ("容器内端口", profile.port_pairs),
+            ("容器内挂载点", profile.mount_targets),
+            ("挂载来源", profile.mount_hosts),
+            ("应用环境变量", profile.app_env_keys),
+            ("表单字段", profile.form_env_keys),
+            ("高风险/额外字段", profile.high_signal_keys + profile.service_extra_keys),
+            ("脚本", profile.scripts),
+            ("README 章节", profile.readme_sections),
+        ):
+            print(f"\n{label}（{len(values)}）:")
+            for value in values[:12]:
+                print(f"  - {value}")
+            if len(values) > 12:
+                print(f"  ... 另外 {len(values) - 12} 项")
+        if corpus:
+            verdict = depth_module.assess(profile, corpus)
+            print(f"\n判定：{verdict.status}")
+            for reason in verdict.reasons:
+                print(f"  ! {reason}")
+            print("\n与官方语料最接近的包：")
+            found = depth_module.nearest(profile, corpus)
+            if not found:
+                print("  （没有明显相似的包，说明这份包的应用特有部分足够独立）")
+            for score, other, shared in found:
+                print(f"  {score:.0%}  {other.app}")
+                for item in shared[:6]:
+                    print(f"        {item}")
+        return 0
+
+    if not corpora:
+        print("error: --corpus is required", file=sys.stderr)
+        return 2
+    profiles = depth_module.scan(corpora, limit=args.limit)
+    report = depth_module.dimension_report(profiles, top=args.top)
+    if args.json:
+        print(depth_module.to_json(report))
+        return 0
+    print(f"扫描 {report['apps']} 个应用")
+    print("\n维度                      不同取值  每应用均值  最常见取值")
+    for item in report["dimensions"]:
+        top = ", ".join(f"{v}×{c}" for v, c in item["top"][:3])
+        print(
+            f"{item['dimension']:<22} {item['distinct']:>7}  {item['per_app']:>9}   {top}"
+        )
+    print("\n服务数分布:", report["service_counts"])
+    print("带 healthcheck 的应用:", report["healthcheck"])
+    return 0
+
+
+def cmd_resolve(args: argparse.Namespace) -> int:
+    try:
+        result = resolve_target(args.target, fetch_budget=args.timeout)
+    except ResolveSourceError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(result.to_json())
+    else:
+        print(render_resolve_text(result))
+
+    if args.out:
+        written = write_resolve_outputs(result, Path(args.out).resolve())
+        for name, path in written.items():
+            print(f"\nwrote {name}: {path}")
+    return 1 if result.blocked else 0
+
+
+def cmd_gen(args: argparse.Namespace) -> int:
+    import json as _json
+
+    spec_path = Path(args.spec).resolve()
+    if not spec_path.exists():
+        print(f"error: 找不到 spec: {spec_path}", file=sys.stderr)
+        return 2
+    try:
+        spec = load_spec(spec_path)
+        result = generate_package(
+            spec,
+            Path(args.out or spec_path.parent).resolve(),
+            force=args.force,
+            allow_unresolved=args.allow_unresolved,
+        )
+    except SpecError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(
+            _json.dumps(
+                {
+                    "root": str(result.root),
+                    "files": result.files,
+                    "exposed": result.exposed,
+                    "hidden_env": result.hidden_env,
+                    "warnings": result.warnings,
+                    "audit": result.audit.to_dict() if result.audit else None,
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return 0
+    print(result.render())
+    if args.check:
+        print()
+        return cmd_check(argparse.Namespace(path=str(result.root), strict=args.strict, json=False))
+    return 0
+
+
+def cmd_deploy(args: argparse.Namespace) -> int:
+    import json as _json
+
+    cfg = config_module.load()
+    try:
+        panel = PanelClient(cfg.require("panel.url"), cfg.require("panel.api_key"))
+        ssh = _ssh_target(args)
+    except (KeyError, RemoteError) as exc:
+        print(f"error: {getattr(exc, 'args', [''])[0] or exc}", file=sys.stderr)
+        return 2
+
+    params: dict[str, str] = {}
+    for item in args.param or []:
+        key, sep, value = item.partition("=")
+        if not key or not sep:
+            print(f"error: --param 需要 KEY=VALUE 形式: {item}", file=sys.stderr)
+            return 2
+        params[key.strip()] = value
+
+    package = Path(args.package).resolve()
+    if not (package / "data.yml").exists():
+        print(f"error: {package} 不是应用包根目录（缺少 data.yml）", file=sys.stderr)
+        return 2
+
+    result = run_deploy(
+        ssh,
+        panel,
+        package,
+        name=args.name,
+        version=args.version,
+        params=params,
+        wait=not args.no_wait,
+        timeout=args.timeout,
+        uninstall_after=args.uninstall,
+        allow_port=args.allow_port,
+    )
+    if args.json:
+        print(
+            _json.dumps(
+                {
+                    "ok": result.ok,
+                    "stage": result.stage,
+                    "app_key": result.app_key,
+                    "install_id": result.install_id,
+                    "message": result.message,
+                    "containers": result.containers,
+                    "remote_dir": result.remote_dir,
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+    else:
+        print(result.render())
+    if args.cleanup_local and result.ok:
+        remove_local(ssh, package.name)
+        print(f"已移除本地包目录 {package.name}")
+    return 0 if result.ok else 1
+
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    cfg = config_module.load()
+    try:
+        panel = PanelClient(cfg.require("panel.url"), cfg.require("panel.api_key"))
+    except KeyError as exc:
+        print(f"error: {exc.args[0]}", file=sys.stderr)
+        return 2
+    if args.install_id:
+        ids = [int(args.install_id)]
+    elif args.name:
+        ids = [int(item["id"]) for item in installed_apps_matching(panel, args.name)]
+        if not ids:
+            print(f"error: 找不到已安装的应用 {args.name!r}", file=sys.stderr)
+            return 1
+    elif args.all_apps:
+        # Uninstalling everything is never an accident-safe default: an empty
+        # `p1 uninstall` used to mean "remove every app on the panel".
+        targets = installed_apps_matching(panel, "")
+        if not targets:
+            print("面板上没有已安装的应用")
+            return 0
+        print("将要卸载以下应用：")
+        for item in targets:
+            print(f"  #{item.get('id')} {item.get('name')} ({item.get('status')})")
+        if not args.yes:
+            print("确认请加 --yes（例如: p1 uninstall --all --yes）", file=sys.stderr)
+            return 2
+        ids = [int(item["id"]) for item in targets]
+    else:
+        print(
+            "error: 请指定应用名或 --install-id；卸载全部已安装应用请显式使用 --all --yes",
+            file=sys.stderr,
+        )
+        return 2
+    for install_id in ids:
+        try:
+            run_uninstall(panel, install_id)
+        except PanelError as exc:
+            print(f"error: 卸载 {install_id} 失败: {exc}", file=sys.stderr)
+            return 1
+        print(f"已卸载 installId={install_id}")
+    return 0
+
+
+def cmd_selftest(args: argparse.Namespace) -> int:
+    result = run_selftest()
+    if args.json:
+        import json as _json
+
+        print(
+            _json.dumps(
+                {
+                    "ok": result.ok,
+                    "checks": [
+                        {"name": c.name, "ok": c.ok, "detail": c.detail}
+                        for c in result.checks
+                    ],
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+    else:
+        print(result.render())
+    return 0 if result.ok else 1
+
+
+def cmd_fix(args: argparse.Namespace) -> int:
+    target = Path(args.path).resolve()
+    if not target.is_dir():
+        print(f"error: 不是目录: {target}", file=sys.stderr)
+        return 2
+    try:
+        result = run_fix(target, dry_run=args.dry_run)
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(result.render())
+    if args.check:
+        print()
+        return cmd_check(
+            argparse.Namespace(path=str(target), strict=False, json=False)
+        )
+    return 0
+
+
+def installed_apps_matching(panel, name: str) -> list[dict]:
+    from .deploy import installed_apps
+
+    items = installed_apps(panel, name)
+    if not name:
+        return items
+    return [item for item in items if name in str(item.get("name") or "")]
+
+
+def _ssh_target(args: argparse.Namespace) -> SshTarget:
+    cfg = config_module.load()
+    host = args.host or cfg.get("ssh.host")
+    if not host:
+        raise RemoteError("没有指定 host：用 --host，或 `p1 config set ssh.host <ip>`")
+    return SshTarget(
+        host=host,
+        user=args.user or cfg.get("ssh.user") or "root",
+        key_path=args.key or cfg.get("ssh.key") or "",
+        port=int(args.port or cfg.get("ssh.port") or 22),
+    )
+
+
+def cmd_remote(args: argparse.Namespace) -> int:
+    try:
+        target = _ssh_target(args)
+    except RemoteError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.action == "check":
+        try:
+            facts = check_host(target)
+        except RemoteError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        print(f"主机      : {facts.hostname} ({facts.os_release})")
+        print(f"Docker    : {facts.docker} / {facts.compose}")
+        print(f"资源      : {facts.cpus} vCPU, 可用内存 {facts.mem_available_mb} MB, "
+              f"磁盘剩余 {facts.disk_free_gb:.1f} GB")
+        print(f"已用端口  : {facts.used_ports}")
+        free = facts.free([10000, 10001, 10002, 10003, 10004, 15000, 15001])
+        print(f"空闲候选  : {free}")
+        print(f"本地应用  : {facts.local_apps}")
+        if facts.mem_available_mb < 700:
+            print("注意      : 可用内存偏低，冒烟测试请优先选小镜像")
+        return 0
+
+    if args.action == "smoke":
+        package = Path(args.package).resolve()
+        if not package.is_dir():
+            print(f"error: 不是目录: {package}", file=sys.stderr)
+            return 2
+        ports = [int(p) for p in (args.ports or [])]
+        overrides: dict[str, str] = {}
+        for item in args.env or []:
+            key, _, value = item.partition("=")
+            if not key or not _:
+                print(f"error: --env 需要 KEY=VALUE 形式: {item}", file=sys.stderr)
+                return 2
+            overrides[key.strip()] = value
+        try:
+            result = run_smoke(
+                target,
+                package,
+                version_name=args.version,
+                ports=ports,
+                overrides=overrides,
+                timeout=args.timeout,
+                ready_timeout=args.ready_timeout,
+                keep=args.keep,
+                prune_image=args.prune_image,
+                key=args.key_name,
+            )
+        except RemoteError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        print(result.render())
+        if args.json:
+            import json as _json
+
+            print(
+                _json.dumps(
+                    {
+                        "ok": result.ok,
+                        "stage": result.stage,
+                        "detail": result.detail,
+                        "containers": result.container_states,
+                        "ports": result.published_ports,
+                        "probe": result.probe,
+                        "lessons": [item.get("id") for item in result.lessons],
+                        "remote_dir": result.remote_dir,
+                        "kept": result.kept,
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+        if result.ok:
+            return 0
+        return 3 if result.outcome == "needs-input" else 1
+
+    if args.action == "logs":
+        try:
+            out = target.must(
+                f"cd {args.remote_dir} && docker compose logs --tail=200 2>&1 | tail -200"
+            )
+        except RemoteError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        print(out)
+        return 0
+    return 2
+
+
+def render_resolve_text(result) -> str:
+    from .resolve import EVIDENCED, INFERRED
+
+    icons = {EVIDENCED: "OK  ", INFERRED: "WARN", "missing": "MISS"}
+    lines = [f"# {result.target}", f"来源: {result.analysis.source.label}", ""]
+    for note in result.analysis.source.notes:
+        lines.append(f"注意: {note}")
+    if result.analysis.source.notes:
+        lines.append("")
+    for decision in result.decisions:
+        mark = icons.get(decision.status, "????")
+        lines.append(f"{mark} {decision.id} {decision.question}")
+        lines.append(f"     答案: {decision.answer or '—'}")
+        if decision.evidence:
+            first = decision.evidence[0]
+            where = f"{first.file}:{first.line}" if first.line else first.file
+            extra = f" (+{len(decision.evidence) - 1})" if len(decision.evidence) > 1 else ""
+            lines.append(f"     证据: {where}{extra}")
+    gaps = [d for d in result.decisions if d.blocking and not d.ok]
+    lines.append("")
+    if gaps:
+        lines.append(
+            "阻塞: " + ", ".join(f"{d.id} {d.question}" for d in gaps) + " —— 缺少上游证据，不能靠猜"
+        )
+    else:
+        lines.append("没有阻塞项：D03/D05/D06 都有上游证据，可以进入生成阶段。")
+    return "\n".join(lines)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="p1", description="Generate, check and verify 1Panel app packages."
+    )
+    parser.add_argument("--version", action="version", version=f"p1 {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser("check", help="validate an app package directory")
+    check.add_argument("path", help="app package root, or a directory of packages")
+    check.add_argument(
+        "--strict",
+        action="store_true",
+        help="treat artifact-style conventions as failures",
+    )
+    check.add_argument("--json", action="store_true", help="machine-readable output")
+    check.set_defaults(func=cmd_check)
+
+    rule_cmd = sub.add_parser("rules", help="print bundled rule data")
+    rule_cmd.add_argument("name", help="rule data file, e.g. store / i18n / lessons")
+    rule_cmd.add_argument("--key", help="print only this top-level key")
+    rule_cmd.set_defaults(func=cmd_rules)
+
+    ports = sub.add_parser(
+        "ports",
+        help="classify host ports as open / closed / filtered before a smoke test",
+    )
+    ports.add_argument("host", help="target host, e.g. 47.113.177.168")
+    ports.add_argument(
+        "ports", help="comma separated ports or ranges, e.g. 10000,15000 or 10000-10010"
+    )
+    ports.add_argument("--timeout", type=float, default=5.0)
+    ports.set_defaults(func=cmd_ports)
+
+    cfg_cmd = sub.add_parser("config", help="read or write local p1 configuration")
+    cfg_sub = cfg_cmd.add_subparsers(dest="action")
+    cfg_show = cfg_sub.add_parser("show", help="print current configuration")
+    cfg_show.set_defaults(action="show", func=cmd_config)
+    cfg_set = cfg_sub.add_parser("set", help="set a key")
+    cfg_set.add_argument("key")
+    cfg_set.add_argument("value")
+    cfg_set.set_defaults(action="set", func=cmd_config)
+    cfg_unset = cfg_sub.add_parser("unset", help="remove a key")
+    cfg_unset.add_argument("key")
+    cfg_unset.set_defaults(action="unset", func=cmd_config)
+    cfg_cmd.set_defaults(action="show", func=cmd_config)
+
+    panel = sub.add_parser("panel", help="talk to the 1Panel instance")
+    panel_sub = panel.add_subparsers(dest="action", required=True)
+    panel_ping = panel_sub.add_parser("ping", help="verify credentials and reachability")
+    panel_ping.set_defaults(func=cmd_panel)
+
+    pat = sub.add_parser("patterns", help="browse the pattern library")
+    pat_sub = pat.add_subparsers(dest="action")
+    pat_build = pat_sub.add_parser("build", help="rebuild the library from a corpus")
+    pat_build.add_argument(
+        "--corpus", action="append", required=True, help="apps dir or app package root"
+    )
+    pat_build.add_argument("--out", help=f"output json (default {DATA_FILE})")
+    pat_build.add_argument("--markdown", help="also write a tutorial markdown file")
+    pat_build.set_defaults(action="build", func=cmd_patterns)
+    pat_list = pat_sub.add_parser("list", help="list patterns")
+    pat_list.add_argument("--category")
+    pat_list.add_argument("--json", action="store_true")
+    pat_list.set_defaults(action="list", func=cmd_patterns)
+    pat_show = pat_sub.add_parser("show", help="print one pattern with examples")
+    pat_show.add_argument("pattern_id")
+    pat_show.add_argument("--json", action="store_true")
+    pat_show.set_defaults(action="show", func=cmd_patterns)
+    pat_find = pat_sub.add_parser("find", help="keyword search")
+    pat_find.add_argument("query")
+    pat_find.add_argument("--json", action="store_true")
+    pat_find.set_defaults(action="find", func=cmd_patterns)
+    pat_export = pat_sub.add_parser("export", help="write the tutorial markdown")
+    pat_export.add_argument("--markdown", required=True)
+    pat_export.set_defaults(action="export", func=cmd_patterns)
+    pat.set_defaults(action="list", func=cmd_patterns)
+
+    depth = sub.add_parser(
+        "depth", help="measure how app-specific a package is (template vs adapted)"
+    )
+    depth.add_argument("package", nargs="?", help="app package root to inspect")
+    depth.add_argument(
+        "--corpus", action="append", help="apps dir or app package root (repeatable)"
+    )
+    depth.add_argument("--top", type=int, default=6, help="values to show per dimension")
+    depth.add_argument("--limit", type=int, help="stop after N apps (for a quick look)")
+    depth.add_argument("--json", action="store_true")
+    depth.set_defaults(func=cmd_depth)
+
+    res = sub.add_parser(
+        "resolve", help="gather upstream evidence for the 10 generation decisions"
+    )
+    res.add_argument(
+        "target",
+        help="local checkout path, owner/repo slug, or github.com URL",
+    )
+    res.add_argument("--out", help="write decision-report.md / draft-spec.json / resolve.json")
+    res.add_argument(
+        "--timeout",
+        type=float,
+        default=60.0,
+        help="seconds allowed for the raw-file fetches (default 60; "
+        "raw.githubusercontent.com is blocked from some networks)",
+    )
+    res.add_argument("--json", action="store_true")
+    res.set_defaults(func=cmd_resolve)
+
+    gen = sub.add_parser("gen", help="generate a package from a spec")
+    gen.add_argument("spec", help="spec JSON (see `p1 resolve --out` for a draft)")
+    gen.add_argument("--out", help="output directory, default is next to the spec")
+    gen.add_argument("--force", action="store_true", help="overwrite an existing package")
+    gen.add_argument(
+        "--allow-unresolved",
+        dest="allow_unresolved",
+        action="store_true",
+        help="generate even when a blocking decision has no upstream evidence "
+        "(recorded in decision-audit.json)",
+    )
+    gen.add_argument("--check", action="store_true", help="run `p1 check` right after")
+    gen.add_argument("--strict", action="store_true", help="strict mode for the follow-up check")
+    gen.add_argument("--json", action="store_true")
+    gen.set_defaults(func=cmd_gen)
+
+    deploy = sub.add_parser(
+        "deploy",
+        help="install a package through the 1Panel API (upload, sync, install, verify)",
+    )
+    deploy.add_argument("package", help="app package root")
+    deploy.add_argument("--host", help="ssh host, default from p1 config")
+    deploy.add_argument("--user", help="ssh user, default root")
+    deploy.add_argument("--key", help="ssh private key path")
+    deploy.add_argument("--port", help="ssh port, default 22")
+    deploy.add_argument("--name", help="install name, default is the package directory name")
+    deploy.add_argument("--version", default="latest", help="version directory, default latest")
+    deploy.add_argument(
+        "--param",
+        action="append",
+        help="install form value, e.g. --param PANEL_APP_PORT_HTTP=10000 (repeatable)",
+    )
+    deploy.add_argument("--no-wait", action="store_true", help="submit and return immediately")
+    deploy.add_argument("--timeout", type=int, default=600)
+    deploy.add_argument(
+        "--no-allow-port",
+        dest="allow_port",
+        action="store_false",
+        default=True,
+        help="do not let the panel open the firewall port",
+    )
+    deploy.add_argument(
+        "--uninstall", action="store_true", help="remove the app again after verifying"
+    )
+    deploy.add_argument(
+        "--cleanup-local",
+        dest="cleanup_local",
+        action="store_true",
+        help="remove the package from the panel's local app directory afterwards",
+    )
+    deploy.add_argument("--json", action="store_true")
+    deploy.set_defaults(func=cmd_deploy)
+
+    uninstall = sub.add_parser("uninstall", help="remove an installed app")
+    uninstall.add_argument("name", nargs="?", help="installed app name")
+    uninstall.add_argument("--install-id", dest="install_id", help="install record id")
+    uninstall.add_argument(
+        "--all", dest="all_apps", action="store_true", help="remove every installed app"
+    )
+    uninstall.add_argument("--yes", action="store_true", help="skip the --all confirmation")
+    uninstall.set_defaults(func=cmd_uninstall)
+
+    selftest = sub.add_parser(
+        "selftest", help="acceptance checks against this installation"
+    )
+    selftest.add_argument("--json", action="store_true")
+    selftest.set_defaults(func=cmd_selftest)
+
+    fix = sub.add_parser(
+        "fix", help="apply what `p1 check` found to a package (idempotent)"
+    )
+    fix.add_argument("path", help="app package root")
+    fix.add_argument(
+        "--dry-run", dest="dry_run", action="store_true", help="show changes only"
+    )
+    fix.add_argument("--check", action="store_true", help="run `p1 check` afterwards")
+    fix.set_defaults(func=cmd_fix)
+
+    remote = sub.add_parser("remote", help="run a package against a real 1Panel host over SSH")
+    remote.add_argument("--host", help="host or IP (or set ssh.host in p1 config)")
+    remote.add_argument("--user", help="ssh user, default root")
+    remote.add_argument("--key", help="ssh private key path")
+    remote.add_argument("--port", help="ssh port, default 22")
+    remote_sub = remote.add_subparsers(dest="action", required=True)
+    remote_check = remote_sub.add_parser("check", help="report host facts and free ports")
+    remote_check.set_defaults(func=cmd_remote)
+    remote_smoke = remote_sub.add_parser(
+        "smoke", help="upload one version, bring it up, probe it, tear it down"
+    )
+    remote_smoke.add_argument("package", help="app package root")
+    remote_smoke.add_argument("--version", help="version directory, default latest")
+    remote_smoke.add_argument(
+        "--ports",
+        action="append",
+        help="host port for the Nth PANEL_APP_PORT_* field (repeatable)",
+    )
+    remote_smoke.add_argument("--timeout", type=int, default=420)
+    remote_smoke.add_argument(
+        "--env",
+        action="append",
+        help="override a form value, e.g. --env OV_VLM_API_KEY=sk-... (repeatable)",
+    )
+    remote_smoke.add_argument(
+        "--ready-timeout", dest="ready_timeout", type=int, default=90,
+        help="seconds to wait for the port to answer, default 90",
+    )
+    remote_smoke.add_argument("--keep", action="store_true", help="do not tear down afterwards")
+    remote_smoke.add_argument(
+        "--prune-image", dest="prune_image", action="store_true",
+        help="also remove the images the smoke test pulled",
+    )
+    remote_smoke.add_argument("--key-name", dest="key_name", help="override the container name prefix")
+    remote_smoke.add_argument("--json", action="store_true")
+    remote_smoke.set_defaults(func=cmd_remote)
+    remote_logs = remote_sub.add_parser("logs", help="read logs from a kept smoke directory")
+    remote_logs.add_argument("remote_dir")
+    remote_logs.set_defaults(func=cmd_remote)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())