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

p1toolkit/config.py

@@ -0,0 +1,114 @@
+"""Local configuration: where the panel lives and how to talk to it.
+
+Secrets never live in the repository. They live in a user-level file
+(``%APPDATA%\\p1\\config.toml`` on Windows, ``~/.config/p1/config.toml``
+elsewhere) or in the environment, which also makes CI usage straightforward.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ENV_PREFIX = "P1_"
+
+
+def config_path() -> Path:
+    override = os.environ.get("P1_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    if os.name == "nt":
+        base = Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming")
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / "p1" / "config.toml"
+
+
+@dataclass
+class Config:
+    values: dict[str, str] = field(default_factory=dict)
+    path: Path = field(default_factory=config_path)
+    source: str = "file"
+    broken: str = ""
+
+    def get(self, key: str, default: str | None = None) -> str | None:
+        env_key = ENV_PREFIX + key.upper().replace(".", "_")
+        if env_key in os.environ and os.environ[env_key]:
+            return os.environ[env_key]
+        return self.values.get(key, default)
+
+    def require(self, key: str) -> str:
+        value = self.get(key)
+        if not value:
+            raise KeyError(
+                f"{key} is not configured; run `p1 config set {key} <value>` "
+                f"or set {ENV_PREFIX}{key.upper().replace('.', '_')}"
+            )
+        return value
+
+    def set(self, key: str, value: str) -> None:
+        self.values[key] = value
+
+    def save(self) -> Path:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        lines = ["# p1 configuration. Keep this file out of any repository.\n"]
+        for key in sorted(self.values):
+            # Quoted so `panel.url` stays one flat key instead of a TOML table.
+            lines.append(f'"{_escape(key)}" = "{_escape(self.values[key])}"\n')
+        self.path.write_text("".join(lines), encoding="utf-8")
+        try:  # best effort: keep the file owner-only on POSIX
+            os.chmod(self.path, 0o600)
+        except OSError:
+            pass
+        return self.path
+
+    def masked(self) -> dict[str, str]:
+        return {key: mask(key, value) for key, value in sorted(self.values.items())}
+
+
+def mask(key: str, value: str) -> str:
+    lowered = key.lower()
+    # `ssh.key` holds a path, so masking it just makes `config show` useless.
+    path_like = lowered.endswith((".key", "_key_path", ".path", "_path"))
+    if not path_like and any(
+        word in lowered for word in ("key", "token", "password", "secret")
+    ):
+        if len(value) <= 8:
+            return "*" * len(value)
+        return f"{value[:4]}{'*' * (len(value) - 8)}{value[-4:]}"
+    return value
+
+
+def _escape(value: str) -> str:
+    """TOML basic strings treat backslash as an escape, so Windows paths break."""
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def load(path: Path | None = None) -> Config:
+    target = path or config_path()
+    values: dict[str, str] = {}
+    broken = ""
+    if target.exists():
+        try:
+            with target.open("rb") as handle:
+                raw = tomllib.load(handle)
+            values = _flatten(raw)
+        except (tomllib.TOMLDecodeError, OSError) as exc:
+            # A corrupt config must not break every command; `p1 config set`
+            # rewrites the file, which is the natural repair path.
+            broken = f"{type(exc).__name__}: {exc}"
+    return Config(values=values, path=target, broken=broken)
+
+
+def _flatten(raw: dict, prefix: str = "") -> dict[str, str]:
+    """Accept both ``"panel.url" = x`` and a ``[panel] url = x`` table."""
+    flat: dict[str, str] = {}
+    for key, value in raw.items():
+        name = f"{prefix}{key}"
+        if isinstance(value, dict):
+            flat.update(_flatten(value, prefix=f"{name}."))
+        elif isinstance(value, (str, int, float, bool)):
+            flat[name] = str(value)
+    return flat

p1toolkit/dependencies.py

@@ -0,0 +1,218 @@
+"""Wire a generated package to a dependency 1Panel already runs (D10).
+
+The install form gets a selector, the compose gets the application's own
+variable names. Two rules keep this honest:
+
+* **The mapping is the spec's job.** Only the packager knows that this app
+  reads `SPRING_DATASOURCE_URL`, not `DATABASE_URL`; the generator never
+  invents an application variable name.
+* **Only referenced variables become form fields.** Official packages declare
+  PANEL_DB_NAME / USER / USER_PASSWORD / PORT themselves, but a field nobody
+  needs is a box the user fills in for nothing (the form budget is the whole
+  point of `p1 check`'s F rules).
+
+The shapes come from ``rules/data/dependencies.yaml``, measured on the official
+corpus rather than recalled.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from . import rules
+from .errors import DependencyError
+
+ENV_REF = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def _env_map(entry: dict[str, Any], index: int) -> dict[str, str]:
+    raw = entry.get("env")
+    if isinstance(raw, dict) and raw:
+        return {str(key): str(value) for key, value in raw.items()}
+    raise DependencyError(
+        f"dependencies[{index}] 没有可用映射 env；"
+        "依赖只声明 kind 是不够的：生成器需要知道应用自己读哪个变量名（D01 证据），"
+        '例如 "env": {"DATABASE_HOST": "${PANEL_DB_HOST}"}'
+    )
+
+
+def _kinds_of(entry: dict[str, Any], primary: dict[str, Any]) -> list[dict[str, Any]]:
+    requested = entry.get("kinds") or [primary["key"]]
+    if not isinstance(requested, list) or not requested:
+        raise DependencyError("dependencies[].kinds 必须是非空数组")
+    resolved: list[dict[str, Any]] = []
+    for key in requested:
+        definition = rules.dependency_kind(str(key))
+        if not definition:
+            raise DependencyError(_unknown_kind(str(key)))
+        if definition.get("family") != primary.get("family"):
+            raise DependencyError(
+                f"dependencies[].kinds 里的 {key} 与 kind={primary['key']} 不属于同一个变量族"
+                f"（{definition.get('family')} vs {primary.get('family')}）"
+            )
+        resolved.append(definition)
+    return resolved
+
+
+def _unknown_kind(key: str) -> str:
+    known = ", ".join(str(item["key"]) for item in rules.dependency_kinds())
+    return (
+        f"未知的依赖 kind {key!r}；目前支持 {known}。"
+        "新款面板应用需要先把变量表加进 rules/data/dependencies.yaml（那是数据，不是代码）"
+    )
+
+
+def _resolve_default(spec: dict[str, Any], kind: dict[str, Any], raw: Any) -> Any:
+    if raw == "app_key":
+        return str(spec.get("key") or "")
+    if raw == "kind_port":
+        return int(kind.get("default_port") or 0)
+    return raw
+
+
+def _selector_field(
+    definition: dict[str, Any],
+    family: dict[str, Any],
+    style: str,
+    options: list[dict[str, Any]],
+) -> dict[str, Any]:
+    host_key = str(family["host_envkey"])
+    label_en = str(family.get("selector_label_en") or "Service")
+    label_zh = str(family.get("selector_label_zh") or label_en)
+    if style == "apps":
+        selector_key = str(family.get("selector_envkey") or "")
+        if not selector_key:
+            raise DependencyError(
+                f"{definition['key']} 只有一步式选择器（style: service）："
+                "它的变量族里没有「引擎类型」这一层"
+            )
+        return {
+            "envKey": selector_key,
+            "type": "apps",
+            "required": True,
+            "default": str(definition["key"]),
+            "values": [
+                {"label": str(item.get("label") or item["key"]), "value": str(item["key"])}
+                for item in options
+            ],
+            "child": {
+                "envKey": host_key,
+                "type": "service",
+                "required": True,
+                "default": "",
+            },
+            "labelEn": label_en,
+            "labelZh": label_zh,
+        }
+    # One-step: the host field *is* the selector, and `key` names the panel app.
+    return {
+        "envKey": host_key,
+        "type": "service",
+        "key": str(definition["key"]),
+        "required": True,
+        "default": "",
+        "edit": True,
+        "labelEn": label_en,
+        "labelZh": label_zh,
+    }
+
+
+def _variable_field(
+    spec: dict[str, Any],
+    definition: dict[str, Any],
+    env_key: str,
+    variable: dict[str, Any],
+) -> dict[str, Any]:
+    field: dict[str, Any] = {
+        "envKey": env_key,
+        "type": str(variable.get("type") or "text"),
+        "required": True,
+        "labelEn": str(variable.get("label_en") or env_key),
+        "labelZh": str(variable.get("label_zh") or env_key),
+    }
+    if "default" in variable:
+        field["default"] = _resolve_default(spec, definition, variable["default"])
+    elif field["type"] == "password":
+        # A secret has no usable default; the panel asks for it (official
+        # packages ship an empty password field).
+        field["default"] = ""
+    if variable.get("rule"):
+        field["rule"] = variable["rule"]
+    return field
+
+
+def build(
+    spec: dict[str, Any],
+) -> tuple[list[dict[str, Any]], dict[str, list[str]], list[str]]:
+    """Return (form fields, env lines per service, notes for the operator)."""
+    entries = spec.get("dependencies")
+    if not entries:
+        return [], {}, []
+    if not isinstance(entries, list):
+        raise DependencyError("dependencies 必须是数组")
+
+    services = spec.get("services") or []
+    default_service = str(services[0].get("name") or "") if services else ""
+    fields: list[dict[str, Any]] = []
+    env_by_service: dict[str, list[str]] = {}
+    notes: list[str] = []
+
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            raise DependencyError(f"dependencies[{index}] 必须是对象")
+        kind_key = str(entry.get("kind") or "")
+        definition = rules.dependency_kind(kind_key)
+        if not definition:
+            raise DependencyError(_unknown_kind(kind_key))
+        family = rules.dependency_family(str(definition.get("family") or ""))
+        if not family:
+            raise DependencyError(
+                f"kind={kind_key} 指向的 family {definition.get('family')!r} 在 "
+                "rules/data/dependencies.yaml 里不存在"
+            )
+
+        # Default to the two-step shape (the official majority), except for
+        # families that only have one instance type, such as Redis.
+        default_style = "apps" if family.get("selector_envkey") else "service"
+        style = str(entry.get("style") or default_style)
+        if style not in rules.dependency_styles():
+            raise DependencyError(
+                f"dependencies[{index}].style={style!r} 不是 "
+                f"{sorted(rules.dependency_styles())} 之一"
+            )
+
+        env = _env_map(entry, index)
+        options = _kinds_of(entry, definition)
+        host_key = str(family["host_envkey"])
+        selector_key = str(family.get("selector_envkey") or "")
+        variables = family.get("variables") or {}
+
+        refs = sorted({ref for value in env.values() for ref in ENV_REF.findall(value)})
+        promoted = {host_key, selector_key}
+        unknown = [ref for ref in refs if ref not in variables and ref not in promoted]
+        if unknown:
+            known = sorted(set(variables) | promoted)
+            raise DependencyError(
+                f"{kind_key}: 引用了面板没有提供的变量 {unknown}；"
+                f"这个 family 可用的是 {known}"
+            )
+
+        fields.append(_selector_field(definition, family, style, options))
+        for ref in refs:
+            if ref in promoted:
+                continue
+            fields.append(_variable_field(spec, definition, ref, variables[ref]))
+
+        target = str(entry.get("service") or default_service)
+        env_by_service.setdefault(target, []).extend(
+            f"{name}={value}" for name, value in env.items()
+        )
+        notes.append(
+            f"{kind_key}: 用户在表单里选实例，"
+            f"{', '.join(sorted(env))} 接到 {target or '(第一个服务)'} 上"
+        )
+    return fields, env_by_service, notes
+
+
+__all__ = ["DependencyError", "build"]

p1toolkit/deploy.py

@@ -0,0 +1,302 @@
+"""Install a package through 1Panel itself, not around it.
+
+An SSH smoke test proves the containers start; it does not prove the panel can
+install the thing. This module walks the real path a user walks:
+
+1. put the package in the panel's local app directory
+2. make the panel rescan local apps
+3. resolve the app and its version record to get `appDetailId`
+4. call the install endpoint
+5. watch the container until it is up, then take a probe
+
+The shapes below were discovered from the running panel (1Panel v2.2.4) rather
+than guessed: the validator names the required fields when you post an empty
+body, and the detail endpoint hands back the id the installer wants.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .panel import PanelClient, PanelError
+from .remote import SshTarget, _tarball
+
+LOCAL_APP_ROOT = "/opt/1panel/resource/apps/local"
+DEFAULT_INSTALL_TIMEOUT = 600
+
+
+@dataclass
+class DeployResult:
+    ok: bool
+    stage: str
+    app_key: str = ""
+    install_id: int | None = None
+    message: str = ""
+    containers: list[str] = field(default_factory=list)
+    remote_dir: str = ""
+    install_log: str = ""
+    kept: bool = False
+
+    def render(self) -> str:
+        lines = [f"{'PASS' if self.ok else 'FAIL'}  deploy/{self.stage}"]
+        if self.app_key:
+            lines.append(f"  应用: {self.app_key}")
+        if self.install_id:
+            lines.append(f"  安装记录: {self.install_id}")
+        if self.message:
+            lines.append(f"  {self.message}")
+        for item in self.containers:
+            lines.append(f"  容器: {item}")
+        if self.remote_dir:
+            lines.append(f"  远端: {self.remote_dir}")
+        if not self.ok and self.install_log:
+            lines.append("  --- 安装日志尾部 ---")
+            for line in self.install_log.strip().splitlines()[-20:]:
+                lines.append(f"  | {line}")
+        return "\n".join(lines)
+
+
+class DeployError(Exception):
+    pass
+
+
+# --------------------------------------------------------------------------
+# steps
+# --------------------------------------------------------------------------
+
+
+def upload(target: SshTarget, package_root: Path, key: str) -> str:
+    """Place the package where 1Panel looks for local apps."""
+    # Quote every interpolated path: a package directory containing a space or
+    # a `;` would otherwise split the command, and the first command here is
+    # `rm -rf`.
+    remote = f"{LOCAL_APP_ROOT}/{key}"
+    quoted = shlex.quote(remote)
+    target.must(f"rm -rf {quoted} && mkdir -p {quoted}")
+    payload = _tarball(package_root)
+    code, _, err = target.run(f"tar -xzf - -C {quoted}", input_bytes=payload, timeout=300)
+    if code != 0:
+        raise DeployError(f"上传失败: {err.strip()[:300]}")
+    # 1Panel reads these as its own; keep ownership consistent with the rest.
+    target.run(f"chown -R root:root {quoted}")
+    return remote
+
+
+def sync_local(client: PanelClient) -> dict:
+    return client.request("/apps/sync/local", "POST", {})
+
+
+def find_app(client: PanelClient, key: str, display_name: str = "", attempts: int = 8) -> dict:
+    """Local apps are registered as `local<key>`; wait for the rescan to land.
+
+    The search endpoint filters on the display name, not on the key, so match
+    locally over a full page instead of trusting the server-side filter.
+    """
+    wanted = {key, f"local{key}"}
+    for attempt in range(attempts):
+        data = client.request(
+            "/apps/search", "POST", {"page": 1, "pageSize": 500}
+        )
+        for item in data.get("items") or []:
+            item_key = str(item.get("key") or "")
+            item_name = str(item.get("name") or "")
+            if item_key in wanted or (display_name and item_name == display_name):
+                return item
+        if attempt < attempts - 1:
+            time.sleep(2)
+    raise DeployError(
+        f"面板里找不到应用 {key}（同步本地应用后仍未出现；"
+        "确认包根目录含 data.yml，且 key 只用小写字母数字和连字符）"
+    )
+
+
+def display_name(package_root: Path) -> str:
+    """The name the panel lists the app under (root data.yml `name`)."""
+    path = package_root / "data.yml"
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError):
+        return ""
+    return str(data.get("name") or "")
+
+
+def app_detail(client: PanelClient, app_id: int, version: str, app_type: str) -> dict:
+    return client.request(f"/apps/detail/{app_id}/{version}/{app_type}")
+
+
+def install(
+    client: PanelClient,
+    app_detail_id: int,
+    name: str,
+    params: dict[str, str] | None = None,
+    advanced: bool = False,
+    allow_port: bool = True,
+) -> int:
+    payload: dict[str, object] = {
+        "appDetailId": app_detail_id,
+        "name": name,
+        "advanced": advanced,
+        "allowPort": allow_port,
+    }
+    if params:
+        # v2 takes the install-form values as an object (v1 wanted a JSON
+        # string); sending the wrong one yields a Go unmarshal error.
+        payload["params"] = dict(params)
+    data = client.request("/apps/install", "POST", payload)
+    return int(data.get("installId") or data.get("id") or 0)
+
+
+def installed_apps(client: PanelClient, name: str = "") -> list[dict]:
+    payload = {"page": 1, "pageSize": 100}
+    if name:
+        payload["name"] = name
+    data = client.request("/apps/installed/search", "POST", payload)
+    return list(data.get("items") or [])
+
+
+def uninstall(client: PanelClient, install_id: int, delete_backup: bool = False) -> None:
+    client.request(
+        "/apps/installed/op",
+        "POST",
+        {
+            "installId": install_id,
+            "operate": "delete",
+            "deleteBackup": delete_backup,
+            "forceDelete": True,
+        },
+    )
+
+
+def container_lines(client: PanelClient, needle: str) -> list[str]:
+    """Container names and state matching a needle, for the report."""
+    try:
+        items = client.containers()
+    except PanelError:
+        return []
+    out = []
+    for item in items:
+        name = str(item.get("name") or item.get("containerName") or "")
+        if needle and needle not in name:
+            continue
+        state = str(item.get("state") or item.get("status") or "")
+        image = str(item.get("image") or "")
+        out.append(f"{name} {state} {image}".strip())
+    return out
+
+
+RUNNING = "running"
+
+
+def installed_record(client: PanelClient, name: str) -> dict | None:
+    """The panel's own record of an installed app, which carries its status."""
+    for item in installed_apps(client):
+        if str(item.get("name")) == name:
+            return item
+    return None
+
+
+def _status_of(record: dict | None) -> str:
+    return str((record or {}).get("status") or "").lower()
+
+
+# --------------------------------------------------------------------------
+# orchestration
+# --------------------------------------------------------------------------
+
+
+def deploy(
+    target: SshTarget,
+    client: PanelClient,
+    package_root: Path,
+    name: str | None = None,
+    version: str = "latest",
+    params: dict[str, str] | None = None,
+    wait: bool = True,
+    timeout: int = DEFAULT_INSTALL_TIMEOUT,
+    uninstall_after: bool = False,
+    allow_port: bool = True,
+) -> DeployResult:
+    key = package_root.name
+    app_name = name or key
+    stage = "upload"
+    remote_dir = ""
+    install_id: int | None = None
+    try:
+        remote_dir = upload(target, package_root, key)
+        stage = "sync"
+        sync_local(client)
+        stage = "resolve"
+        app = find_app(client, key, display_name=display_name(package_root))
+        app_key = str(app.get("key") or key)
+        app_type = str(app.get("type") or "tool")
+        detail = app_detail(client, int(app["id"]), version, app_type)
+        stage = "install"
+        install_id = install(
+            client,
+            int(detail["id"]),
+            app_name,
+            params=params,
+            allow_port=allow_port,
+        )
+        if not wait:
+            return DeployResult(
+                ok=True,
+                stage="install-submitted",
+                app_key=app_key,
+                install_id=install_id,
+                message="已提交安装，未等待完成",
+                remote_dir=remote_dir,
+                kept=True,
+            )
+
+        stage = "wait"
+        deadline = time.time() + timeout
+        record: dict | None = None
+        while time.time() < deadline:
+            record = installed_record(client, app_name)
+            status = _status_of(record)
+            if status == RUNNING:
+                break
+            if status in {"error", "failed", "unhealthy"}:
+                break
+            time.sleep(5)
+
+        status = _status_of(record)
+        ok = status == RUNNING
+        containers = container_lines(client, app_name)
+        if record and record.get("container"):
+            containers.insert(0, f"{record['container']} status={record.get('status')}")
+        result = DeployResult(
+            ok=ok,
+            stage="verify",
+            app_key=app_key,
+            install_id=install_id,
+            message="" if ok else f"安装状态为 {status or '未知'}",
+            containers=containers,
+            remote_dir=remote_dir,
+            kept=not ok,
+        )
+        if ok and uninstall_after:
+            uninstall(client, install_id)
+            result.message = "已安装并验证，随后按要求卸载"
+            result.kept = False
+        return result
+    except (DeployError, PanelError) as exc:
+        return DeployResult(
+            ok=False,
+            stage=stage,
+            install_id=install_id,
+            message=str(exc),
+            remote_dir=remote_dir,
+            kept=True,
+        )
+
+
+def remove_local(target: SshTarget, key: str) -> None:
+    target.run(f"rm -rf {shlex.quote(f'{LOCAL_APP_ROOT}/{key}')}")