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

p1toolkit/checks/compose.py

@@ -0,0 +1,188 @@
+"""docker-compose.yml shape and its closure against the install form."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Iterator
+
+from .. import rules
+from ..model import Package, Version
+from ..report import Report
+
+# Deliberately does not require a closing brace: `${A:-${B}}` is legal Compose,
+# and a strict pattern would swallow the inner reference.
+ENV_REF = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)([^}$]*)")
+IMAGE_LINE = re.compile(r"^\s*image:\s*(.+?)\s*$")
+PORT_LINE = re.compile(r"^\s*-\s*[\"']?\$\{([A-Za-z_][A-Za-z0-9_]*)\}([^\"']*)[\"']?:")
+
+
+def env_refs(value: Any) -> Iterator[tuple[str, str]]:
+    """Yield ``(name, trailing)`` for every ``${NAME...}`` in a structure."""
+    if isinstance(value, str):
+        for match in ENV_REF.finditer(value):
+            yield match.group(1), match.group(2)
+    elif isinstance(value, dict):
+        for item in value.values():
+            yield from env_refs(item)
+    elif isinstance(value, list):
+        for item in value:
+            yield from env_refs(item)
+
+
+def declared_envkeys(version: Version) -> set[str]:
+    keys: set[str] = set()
+    for field in version.form_fields:
+        if field.get("envKey"):
+            keys.add(str(field["envKey"]))
+        child = field.get("child")
+        if isinstance(child, dict) and child.get("envKey"):
+            keys.add(str(child["envKey"]))
+    return keys
+
+
+def run(package: Package, report: Report, strict: bool = False) -> None:
+    store = rules.store()
+    implicit = rules.implicit_envkeys()
+    generic = set(store.get("generic_service_names") or [])
+    for version in package.versions:
+        if not version.compose:
+            continue
+        name = f"{version.name}/docker-compose.yml"
+        if store.get("compose_forbids_top_level_version") and "version" in version.compose:
+            report.fail(
+                "C001",
+                "top-level version: is deprecated in 1Panel compose files; remove it",
+                name,
+            )
+        _check_images(version, report, name, strict)
+        _check_env_closure(version, report, name, implicit)
+        _check_services(version, report, name, generic)
+        _check_ports(version, report, name)
+        _check_networks(version, report, name)
+
+
+def _check_images(version: Version, report: Report, name: str, strict: bool) -> None:
+    for number, line in enumerate(version.compose_text.splitlines(), start=1):
+        match = IMAGE_LINE.match(line)
+        if not match:
+            continue
+        value = match.group(1)
+        if not (value.startswith('"') and value.endswith('"')) and not (
+            value.startswith("'") and value.endswith("'")
+        ):
+            text = "image should be double-quoted to avoid YAML/digest parsing edge cases"
+            (report.fail if strict else report.warn)("C002", text, name, number)
+
+
+def _check_env_closure(
+    version: Version, report: Report, name: str, implicit: set[str]
+) -> None:
+    declared = declared_envkeys(version)
+    seen: dict[str, str] = {}
+    for ref, trailing in env_refs(version.compose):
+        seen.setdefault(ref, trailing)
+    for ref, trailing in sorted(seen.items()):
+        if ref in declared or ref in implicit:
+            continue
+        if trailing.startswith(":-"):
+            # Deliberate: the generator keeps non-decision variables out of the
+            # install form and gives them a working default in the compose.
+            report.info(
+                "C003",
+                f"${{{ref}}} has no matching formFields envKey (a compose default is present)",
+                name,
+            )
+        else:
+            report.fail(
+                "C004",
+                f"${{{ref}}} has no matching formFields envKey and no compose default",
+                name,
+            )
+
+
+def _check_services(
+    version: Version, report: Report, name: str, generic: set[str]
+) -> None:
+    expect_label = rules.store().get("service_label_created_by")
+    for service_name, service in version.services.items():
+        if not isinstance(service, dict):
+            continue
+        if service.get("container_name") != "${CONTAINER_NAME}" and not str(
+            service.get("container_name") or ""
+        ).startswith("${CONTAINER_NAME}"):
+            report.warn(
+                "C010",
+                f"service {service_name}: container_name should be ${{CONTAINER_NAME}}"
+                " (or ${{CONTAINER_NAME}}-<suffix>)",
+                name,
+            )
+        labels = service.get("labels") or {}
+        if isinstance(labels, list):
+            labels = dict(
+                item.split("=", 1) for item in labels if isinstance(item, str) and "=" in item
+            )
+        if expect_label and str(labels.get("createdBy")) != str(expect_label):
+            report.warn(
+                "C011",
+                f'service {service_name}: missing labels.createdBy: "{expect_label}"',
+                name,
+            )
+        networks = service.get("networks") or []
+        if isinstance(networks, dict):
+            networks = list(networks)
+        if service_name in generic and len(networks) > 1:
+            report.warn(
+                "C012",
+                f"service {service_name}: generic name on a shared network can shadow "
+                "a same-named service; use an app-prefixed name or an alias",
+                name,
+            )
+
+
+def _check_ports(version: Version, report: Report, name: str) -> None:
+    prefix = str(rules.store().get("port_envkey_prefix"))
+    for service_name, service in version.services.items():
+        if not isinstance(service, dict):
+            continue
+        for mapping in service.get("ports") or []:
+            if not isinstance(mapping, str) or not mapping.startswith("${"):
+                continue
+            match = PORT_LINE.match(f"  - {mapping}:")
+            if not match:
+                continue
+            env_key = match.group(1)
+            if not env_key.startswith(prefix):
+                report.warn(
+                    "C020",
+                    f"service {service_name}: published port uses {env_key}; 1Panel only "
+                    f"tracks occupancy for {prefix}* envKeys",
+                    name,
+                )
+
+
+def _check_networks(version: Version, report: Report, name: str) -> None:
+    networks = version.compose.get("networks") or {}
+    external = False
+    if isinstance(networks, dict):
+        for config in networks.values():
+            if isinstance(config, dict) and config.get("external"):
+                external = True
+            elif config is None:
+                continue
+    published = any(
+        isinstance(service, dict) and service.get("ports")
+        for service in version.services.values()
+    )
+    # `version.services.get("network_mode")` would look up a *service named*
+    # "network_mode"; the question is whether any service declares it.
+    uses_host_network = any(
+        isinstance(service, dict) and service.get("network_mode")
+        for service in version.services.values()
+    )
+    if published and not external and not uses_host_network:
+        report.warn(
+            "C030",
+            "no external network declared; a bridge-type app normally joins one so it "
+            "can be reached through 1Panel's entry",
+            name,
+        )

p1toolkit/checks/forms.py

@@ -0,0 +1,129 @@
+"""Install-form design: keep the form a decision list, not a config dump."""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from .. import rules
+from ..model import Package
+from ..report import Report
+
+
+def _budget() -> dict:
+    return rules.load("form-design").get("budget") or {}
+
+
+def is_secret(env_key: str) -> bool:
+    fragments = rules.load("form-design").get("secret_fragments") or []
+    upper = env_key.upper()
+    return any(fragment in upper for fragment in fragments)
+
+
+def _prefix(env_key: str) -> str:
+    return env_key.rsplit("_", 1)[0] if "_" in env_key else env_key
+
+
+def run(package: Package, report: Report, strict: bool = False) -> None:
+    budget = _budget()
+    warn_at = int(budget.get("fields_warn") or 11)
+    fail_at = int(budget.get("fields_fail") or 20)
+    min_ratio = float(budget.get("min_required_ratio") or 0.6)
+    max_per_prefix = int(budget.get("max_fields_per_prefix") or 5)
+
+    for version in package.versions:
+        fields = version.form_fields
+        if not fields:
+            continue
+        label = f"{version.name}/data.yml"
+        total = len(fields)
+        required = [f for f in fields if f.get("required")]
+        ratio = len(required) / total
+
+        if total > fail_at:
+            report.fail(
+                "F001",
+                f"安装表单有 {total} 个字段（官方中位数 {budget.get('fields_median_official')}，"
+                f"上限 {fail_at}）。请把上游变量写进 compose 默认值，只暴露用户必须决定的项",
+                label,
+            )
+        elif total > warn_at:
+            report.warn(
+                "F001",
+                f"安装表单有 {total} 个字段，超过官方 p90（{warn_at}）。"
+                "确认每一项都是用户必须决定的，否则收进默认值",
+                label,
+            )
+
+        if total >= 6 and ratio < min_ratio:
+            report.warn(
+                "F002",
+                f"只有 {len(required)}/{total} 个字段标为必填（{ratio:.0%}，官方均值 88%）；"
+                "必填/可选混在一起会让用户不知道该填哪个",
+                label,
+            )
+
+        for field in fields:
+            env_key = str(field.get("envKey") or "")
+            default = str(field.get("default") or "").strip()
+            secret = is_secret(env_key)
+            if field.get("required") and not default and not secret:
+                report.warn(
+                    "F003",
+                    f"{env_key} 标了必填却没有默认值，而且不像密钥字段；"
+                    "要么给默认值，要么降为可选",
+                    label,
+                )
+            if not default and not secret and field.get("type") != "password":
+                report.warn(
+                    "F004",
+                    f"{env_key} 默认值为空；非密钥字段应当有可用默认值，"
+                    "否则用户会卡在一个他无从判断的输入上",
+                    label,
+                )
+            if secret and field.get("type") != "password":
+                report.warn(
+                    "F005",
+                    f"{env_key} 看起来是密钥，但 type 是 {field.get('type')!r}；"
+                    "密钥字段应为 password",
+                    label,
+                )
+
+        clusters = Counter(
+            _prefix(str(f.get("envKey") or "")) for f in fields if f.get("envKey")
+        )
+        for prefix, count in clusters.most_common():
+            if count > max_per_prefix:
+                report.warn(
+                    "F006",
+                    f"{prefix}_* 有 {count} 个字段（官方仅 27/1617 个版本超过 5 个）；"
+                    "这类「提供商矩阵」应折叠成一个 select + 默认值",
+                    label,
+                )
+
+        _check_fields_are_wired(version, report, label)
+
+
+# Panel-provided variables are consumed by the platform, not by the compose text.
+_PLATFORM_PREFIXES = ("PANEL_DB_", "PANEL_REDIS_", "REDIS_", "PANEL_APP_PORT_")
+
+
+def _check_fields_are_wired(version, report: Report, label: str) -> None:
+    """A form field nobody reads is a box the user fills in for nothing."""
+    haystack = version.compose_text
+    for name, path in version.files.items():
+        if name.startswith("scripts/") or name.endswith((".sh", ".conf", ".yaml", ".json")):
+            try:
+                haystack += "\n" + path.read_text(encoding="utf-8-sig", errors="replace")
+            except OSError:
+                continue
+    for field in version.form_fields:
+        env_key = str(field.get("envKey") or "")
+        if not env_key or env_key.startswith(_PLATFORM_PREFIXES):
+            continue
+        if env_key not in haystack:
+            report.warn(
+                "F007",
+                f"{env_key} 出现在安装表单里，但 compose 和脚本里都没有引用它；"
+                "填了也不会生效，要么接线要么移除",
+                label,
+            )

p1toolkit/checks/hygiene.py

@@ -0,0 +1,73 @@
+"""File hygiene: line endings, README shape, .env.sample closure."""
+
+from __future__ import annotations
+
+from ..loader import line_ending_issues
+from ..model import Package
+from ..report import Report
+from .compose import env_refs
+
+
+def run(package: Package, report: Report, strict: bool = False) -> None:
+    _check_text_files(package, report)
+    _check_readme(package, report)
+    _check_env_sample(package, report)
+
+
+def _check_text_files(package: Package, report: Report) -> None:
+    for rel, path in package.files.items():
+        problem = line_ending_issues(path)
+        if problem:
+            report.warn(
+                "H001",
+                f"{problem}; store files should be LF without BOM",
+                rel,
+            )
+
+
+def _check_readme(package: Package, report: Report) -> None:
+    readme = package.root / "README.md"
+    if not readme.exists():
+        report.warn("H010", "README.md is missing", "README.md")
+        return
+    text = readme.read_text(encoding="utf-8-sig", errors="replace")
+    if "## 产品介绍" not in text:
+        report.warn(
+            "H011", "README.md should follow the store style with a 产品介绍 section", "README.md"
+        )
+    if "## 主要功能" not in text and "## 访问说明" not in text:
+        report.info(
+            "H012",
+            "README.md has neither 主要功能 nor 访问说明; store READMEs usually include one",
+            "README.md",
+        )
+
+
+def _check_env_sample(package: Package, report: Report) -> None:
+    for version in package.versions:
+        if not version.compose:
+            continue
+        referenced = {name for name, _ in env_refs(version.compose)}
+        if not referenced:
+            continue
+        sample = version.env_sample
+        if not sample:
+            report.warn(
+                "H020",
+                f"{version.name}/.env.sample is missing; standalone compose users need it",
+                f"{version.name}/.env.sample",
+            )
+            continue
+        present = {
+            line.split("=", 1)[0].strip()
+            for line in sample.splitlines()
+            if "=" in line and not line.lstrip().startswith("#")
+        }
+        missing = sorted(referenced - present)
+        if missing:
+            report.warn(
+                "H021",
+                f"{version.name}/.env.sample does not list: {missing}",
+                f"{version.name}/.env.sample",
+            )
+

p1toolkit/checks/i18n.py

@@ -0,0 +1,140 @@
+"""Translation coverage and label shape."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .. import rules
+from ..model import Package
+from ..report import Report
+
+_BOOL_LABEL = re.compile(r"^\s*(?:-\s*)?label:\s*(true|false)\s*$", re.IGNORECASE)
+_LABEL_LINE = re.compile(r"^\s*(?:-\s*)?label:\s*(\S+)")
+
+
+def _missing(data: Any, languages: list[str]) -> list[str]:
+    if not isinstance(data, dict):
+        return list(languages)
+    return [lang for lang in languages if not str(data.get(lang) or "").strip()]
+
+
+def run(package: Package, report: Report, strict: bool = False) -> None:
+    required = rules.required_languages()
+    all_langs = rules.all_languages()
+    additional = package.additional
+
+    top_description = package.app.get("description")
+    if isinstance(top_description, dict):
+        report.fail(
+            "I001",
+            "root data.yml description must be a single-line string, not a language map",
+            "data.yml",
+        )
+
+    description = additional.get("description")
+    if description is None:
+        report.warn("I002", "additionalProperties.description is missing", "data.yml")
+    else:
+        missing = _missing(description, required)
+        if missing:
+            report.fail(
+                "I003",
+                f"additionalProperties.description is missing languages: {missing}",
+                "data.yml",
+            )
+        if isinstance(description, dict):
+            absent = [lang for lang in all_langs if lang not in description]
+            if absent:
+                report.warn(
+                    "I004",
+                    f"description does not use the store's full language set; missing {absent}",
+                    "data.yml",
+                )
+
+    title = package.app.get("title")
+    short_zh = additional.get("shortDescZh")
+    if title and short_zh:
+        # title and shortDescZh are both the store's one-liner slot and must
+        # agree; 741/771 official apps do. The top-level description is allowed
+        # to be a longer sentence — about 4% of shipped apps differ there — so
+        # that mismatch is reported without blocking.
+        if str(title).strip() != str(short_zh).strip():
+            report.fail(
+                "I005",
+                "root title and additionalProperties.shortDescZh must be the same "
+                f"short text; got title={title!r} shortDescZh={short_zh!r}",
+                "data.yml",
+            )
+        elif top_description and str(top_description).strip() != str(short_zh).strip():
+            report.warn(
+                "I006",
+                "top-level description differs from shortDescZh; the store mostly "
+                f"repeats the same sentence (got description={top_description!r})",
+                "data.yml",
+            )
+
+    for version in package.versions:
+        label = f"{version.name}/data.yml"
+        for field in version.form_fields:
+            env_key = field.get("envKey")
+            label_map = field.get("label")
+            if isinstance(label_map, dict):
+                missing = _missing(label_map, required)
+                if missing:
+                    report.warn(
+                        "I010",
+                        f"{env_key}: label is missing languages {missing}",
+                        label,
+                    )
+            elif field.get("labelZh") or field.get("labelEn"):
+                report.warn(
+                    "I011",
+                    f"{env_key}: only labelZh/labelEn present; add the full label map",
+                    label,
+                )
+            else:
+                report.warn(
+                    "I012", f"{env_key}: no label or labelZh/labelEn", label
+                )
+            _check_values(env_key, field, report, label)
+        _check_bool_labels(version.files.get("data.yml"), report)
+
+
+def _check_values(env_key: Any, field: dict[str, Any], report: Report, label: str) -> None:
+    values = field.get("values")
+    if field.get("type") in {"select", "apps"} and not values:
+        report.fail(
+            "I013", f"{env_key}: type {field.get('type')!r} requires values", label
+        )
+    for item in values or []:
+        if not isinstance(item, dict):
+            continue
+        item_label = item.get("label")
+        if isinstance(item_label, dict):
+            report.fail(
+                "I014",
+                f"{env_key}: values[].label must be a plain string, not a language map "
+                "(1Panel fails to unmarshal it)",
+                label,
+            )
+        if item_label is None or item.get("value") is None:
+            report.fail(
+                "I015", f"{env_key}: each values[] entry needs both label and value", label
+            )
+
+
+def _check_bool_labels(path, report: Report) -> None:
+    """YAML would parse an unquoted `label: true` as a bool; catch it in the raw text."""
+    if path is None or not path.exists():
+        return
+    for number, line in enumerate(
+        path.read_text(encoding="utf-8-sig", errors="replace").splitlines(), start=1
+    ):
+        if _BOOL_LABEL.match(line):
+            report.fail(
+                "I016",
+                "values[].label must be quoted when it is true/false",
+                path,
+                number,
+            )

p1toolkit/checks/lessons.py

@@ -0,0 +1,111 @@
+"""Pre-flight detectors derived from real packaging failures.
+
+Each detector corresponds to an entry in ``rules/data/lessons.yaml``. They are
+deliberately conservative: a false positive here costs a reviewer two minutes,
+a missed one costs a broken install.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .. import rules
+from ..model import Package, Version
+from ..report import Report
+
+_IGNORED_ARTIFACTS = {".gitkeep", ".keep", ".DS_Store"}
+
+
+def _lesson(lesson_id: str) -> dict:
+    for entry in rules.lessons():
+        if entry.get("id") == lesson_id:
+            return entry
+    return {}
+
+
+def run(package: Package, report: Report, strict: bool = False) -> None:
+    for version in package.versions:
+        if not version.compose:
+            continue
+        _first_run_config_missing(package, version, report)
+        _dependency_without_healthcheck(version, report)
+
+
+def _bind_host_paths(version: Version) -> list[str]:
+    hosts: list[str] = []
+    for service in version.services.values():
+        if not isinstance(service, dict):
+            continue
+        for volume in service.get("volumes") or []:
+            if not isinstance(volume, str) or ":" not in volume:
+                continue
+            host = volume.split(":", 1)[0].strip()
+            if host.startswith("./") or host.startswith("../"):
+                hosts.append(host)
+    return hosts
+
+
+def _default_of(version: Version, env_key: str) -> str | None:
+    for field in version.form_fields:
+        if field.get("envKey") == env_key:
+            value = field.get("default")
+            return str(value) if value is not None else None
+    return None
+
+
+def _resolve_host(version: Version, host: str) -> Path | None:
+    """Resolve a bind host path, substituting form defaults for ${VAR}."""
+    def substitute(match: re.Match[str]) -> str:
+        return _default_of(version, match.group(1)) or ""
+
+    resolved = re.sub(r"\$\{([A-Za-z_][A-Za-z0-9_]*)[^}]*\}", substitute, host)
+    if not resolved or "${" in resolved:
+        return None
+    return (version.dir / resolved).resolve()
+
+
+def _first_run_config_missing(package: Package, version: Version, report: Report) -> None:
+    hosts = _bind_host_paths(version)
+    if not hosts:
+        return
+    # version.files keys are relative to the version directory
+    has_init = "scripts/init.sh" in version.files
+    if has_init:
+        return
+    shipped = 0
+    for host in hosts:
+        target = _resolve_host(version, host)
+        if target is None or not target.is_dir():
+            continue
+        if any(
+            child.name not in _IGNORED_ARTIFACTS for child in target.rglob("*") if child.is_file()
+        ):
+            shipped += 1
+    if shipped:
+        return
+    lesson = _lesson("L001")
+    report.warn(
+        "L001",
+        f"{lesson.get('title', 'first-run config may be missing')} — "
+        f"{version.name}/ mounts {sorted(set(hosts))} with no files and no scripts/init.sh; "
+        "if the app needs a config file there it will crash-loop on first start",
+        f"{version.name}/docker-compose.yml",
+    )
+
+
+def _dependency_without_healthcheck(version: Version, report: Report) -> None:
+    for service_name, service in version.services.items():
+        if not isinstance(service, dict):
+            continue
+        depends = service.get("depends_on") or {}
+        names = list(depends) if isinstance(depends, dict) else list(depends)
+        for dependency in names:
+            target = version.services.get(dependency)
+            if isinstance(target, dict) and not target.get("healthcheck"):
+                report.info(
+                    "L002",
+                    f"{service_name} depends_on {dependency}, which has no healthcheck; "
+                    "compose only orders container start, not readiness",
+                    f"{version.name}/docker-compose.yml",
+                )