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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. 1panel_toolkit-0.3.0.dist-info/METADATA +407 -0
  2. 1panel_toolkit-0.3.0.dist-info/RECORD +47 -0
  3. 1panel_toolkit-0.3.0.dist-info/WHEEL +4 -0
  4. 1panel_toolkit-0.3.0.dist-info/entry_points.txt +2 -0
  5. 1panel_toolkit-0.3.0.dist-info/licenses/LICENSE +21 -0
  6. p1toolkit/__init__.py +3 -0
  7. p1toolkit/checks/__init__.py +21 -0
  8. p1toolkit/checks/compose.py +188 -0
  9. p1toolkit/checks/forms.py +129 -0
  10. p1toolkit/checks/hygiene.py +73 -0
  11. p1toolkit/checks/i18n.py +140 -0
  12. p1toolkit/checks/lessons.py +111 -0
  13. p1toolkit/checks/structure.py +140 -0
  14. p1toolkit/checks/substance.py +55 -0
  15. p1toolkit/cli.py +890 -0
  16. p1toolkit/config.py +114 -0
  17. p1toolkit/dependencies.py +218 -0
  18. p1toolkit/deploy.py +302 -0
  19. p1toolkit/depth.py +414 -0
  20. p1toolkit/errors.py +18 -0
  21. p1toolkit/evidence.py +523 -0
  22. p1toolkit/fix.py +394 -0
  23. p1toolkit/gen.py +728 -0
  24. p1toolkit/lifecycle.py +143 -0
  25. p1toolkit/loader.py +110 -0
  26. p1toolkit/logo.py +174 -0
  27. p1toolkit/model.py +71 -0
  28. p1toolkit/net.py +81 -0
  29. p1toolkit/panel.py +154 -0
  30. p1toolkit/patterns/__init__.py +250 -0
  31. p1toolkit/patterns/catalog.py +271 -0
  32. p1toolkit/patterns/data/patterns.json +724 -0
  33. p1toolkit/patterns/extract.py +402 -0
  34. p1toolkit/remote.py +554 -0
  35. p1toolkit/report.py +96 -0
  36. p1toolkit/resolve/__init__.py +554 -0
  37. p1toolkit/resolve/analyze.py +329 -0
  38. p1toolkit/resolve/sources.py +306 -0
  39. p1toolkit/rules/__init__.py +99 -0
  40. p1toolkit/rules/data/decisions.yaml +132 -0
  41. p1toolkit/rules/data/dependencies.yaml +113 -0
  42. p1toolkit/rules/data/envkeys.yaml +19 -0
  43. p1toolkit/rules/data/form-design.yaml +59 -0
  44. p1toolkit/rules/data/i18n.yaml +354 -0
  45. p1toolkit/rules/data/lessons.yaml +84 -0
  46. p1toolkit/rules/data/store.yaml +171 -0
  47. p1toolkit/selftest.py +211 -0
p1toolkit/fix.py ADDED
@@ -0,0 +1,394 @@
1
+ """Apply what `p1 check` found, idempotently.
2
+
3
+ Two kinds of repair live here:
4
+
5
+ * **Mechanical** — line endings, quoting, missing recommended keys, a logo
6
+ that is not on the store's 180x180 canvas. These are always safe.
7
+ * **Disciplined** — moving optional form fields with safe defaults out of the
8
+ install form and into the compose file. This is the fix for the "thirty boxes,
9
+ six required" package, and it changes what the user sees during install.
10
+
11
+ Anything that needs judgement (which fields a user genuinely must decide, how
12
+ to translate a label) is reported as a skip rather than invented.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import re
18
+ from dataclasses import dataclass, field
19
+ from pathlib import Path
20
+
21
+ import yaml
22
+
23
+ from . import rules
24
+ from .checks.forms import is_secret
25
+ from .loader import find_version_dirs, line_ending_issues, load_yaml
26
+ from .logo import LogoError, fit_square
27
+
28
+ TEXT_SUFFIXES = {".yml", ".yaml", ".sh", ".md", ".json", ".sample", ".conf", ".txt"}
29
+
30
+ # The lookahead has to swallow the whitespace itself: with `\s*` outside it, a
31
+ # greedy match backtracks to zero spaces, the check then sees a space instead of
32
+ # the quote, and an already-quoted value gets quoted a second time.
33
+ QUOTE_IMAGE = re.compile(r"(?m)^([ \t]*image:[ \t]*)(?![ \t]*['\"])(.+?)[ \t]*$")
34
+ QUOTE_PORT = re.compile(r"(?m)^([ \t]*-[ \t]*)(\$\{[^}]+\}:\d+(?:/\w+)?)[ \t]*$")
35
+ QUOTE_CONTAINER = re.compile(
36
+ r"(?m)^([ \t]*container_name:[ \t]*)(?![ \t]*['\"])(.+?)[ \t]*$"
37
+ )
38
+
39
+
40
+ @dataclass
41
+ class Change:
42
+ rule: str
43
+ file: str
44
+ detail: str
45
+
46
+ def render(self) -> str:
47
+ return f"{self.rule:<5} {self.file}: {self.detail}"
48
+
49
+
50
+ @dataclass
51
+ class FixResult:
52
+ root: Path
53
+ changes: list[Change] = field(default_factory=list)
54
+ skipped: list[str] = field(default_factory=list)
55
+ dry_run: bool = False
56
+
57
+ def add(self, rule: str, file: str | Path, detail: str) -> None:
58
+ self.changes.append(Change(rule, str(file), detail))
59
+
60
+ def render(self) -> str:
61
+ head = "预览(未写入)" if self.dry_run else "已修复"
62
+ lines = [f"{head} {self.root}"]
63
+ if not self.changes:
64
+ lines.append(" 没有需要修复的内容")
65
+ for change in self.changes:
66
+ lines.append(f" {change.render()}")
67
+ if self.skipped:
68
+ lines.append(" 需要人工处理:")
69
+ for item in self.skipped:
70
+ lines.append(f" - {item}")
71
+ return "\n".join(lines)
72
+
73
+
74
+ def _dump(value) -> str:
75
+ return yaml.safe_dump(value, allow_unicode=True, sort_keys=False, width=100)
76
+
77
+
78
+ def _write(path: Path, text: str, result: FixResult, rule: str, detail: str, dry_run: bool) -> None:
79
+ current = path.read_text(encoding="utf-8-sig", errors="replace") if path.exists() else None
80
+ if current == text:
81
+ return
82
+ result.add(rule, path.name, detail)
83
+ if not dry_run:
84
+ path.write_text(text, encoding="utf-8", newline="\n")
85
+
86
+
87
+ # --------------------------------------------------------------------------
88
+ # mechanical
89
+ # --------------------------------------------------------------------------
90
+
91
+
92
+ def normalize_text(root: Path, result: FixResult, dry_run: bool) -> None:
93
+ for path in sorted(root.rglob("*")):
94
+ if not path.is_file():
95
+ continue
96
+ if path.suffix.lower() not in TEXT_SUFFIXES and path.name != ".env.sample":
97
+ continue
98
+ problem = line_ending_issues(path)
99
+ if not problem:
100
+ continue
101
+ raw = path.read_bytes()
102
+ text = raw.decode("utf-8-sig", errors="replace").replace("\r\n", "\n")
103
+ result.add("H001", path.relative_to(root), f"归一化为 LF 无 BOM(原为 {problem})")
104
+ if not dry_run:
105
+ path.write_text(text, encoding="utf-8", newline="\n")
106
+
107
+
108
+ def fix_logo(root: Path, result: FixResult, dry_run: bool) -> None:
109
+ logo = root / "logo.png"
110
+ if not logo.exists():
111
+ result.skipped.append("logo.png 缺失:需要补一张 180x180 的图标")
112
+ return
113
+ raw = logo.read_bytes()
114
+ try:
115
+ fixed = fit_square(raw)
116
+ except LogoError as exc:
117
+ result.skipped.append(f"logo.png 无法自动处理({exc}):请手动换成 180x180 PNG")
118
+ return
119
+ if fixed is raw or fixed == raw:
120
+ return
121
+ from .logo import decode_png
122
+
123
+ before = decode_png(raw)
124
+ if before.width == 180 and before.height == 180:
125
+ return
126
+ result.add(
127
+ "P022",
128
+ "logo.png",
129
+ f"{before.width}x{before.height} → 180x180(等比缩放后居中,未放大)",
130
+ )
131
+ if not dry_run:
132
+ logo.write_bytes(fixed)
133
+
134
+
135
+ def fix_compose_text(text: str, result: FixResult, name: str, dry_run: bool) -> str:
136
+ original = text
137
+ if re.search(r"(?m)^version:\s", text):
138
+ text = re.sub(r"(?m)^version:\s.*\n", "", text, count=1)
139
+ result.add("C001", name, "移除顶层 version:")
140
+ text, count = re.subn(QUOTE_IMAGE, r'\1"\2"', text)
141
+ if count:
142
+ result.add("C002", name, f"{count} 处 image 加引号")
143
+ text, count = re.subn(QUOTE_PORT, r'\1"\2"', text)
144
+ if count:
145
+ result.add("C002", name, f"{count} 处端口映射加引号")
146
+ if text != original and not dry_run:
147
+ pass # written by the caller
148
+ return text
149
+
150
+
151
+ def ensure_created_by(compose: dict, result: FixResult, name: str, dry_run: bool) -> bool:
152
+ changed = False
153
+ for service_name, service in (compose.get("services") or {}).items():
154
+ if not isinstance(service, dict):
155
+ continue
156
+ labels = service.get("labels")
157
+ if isinstance(labels, list):
158
+ continue
159
+ if not isinstance(labels, dict):
160
+ labels = {}
161
+ if labels.get("createdBy") == "Apps":
162
+ continue
163
+ labels["createdBy"] = "Apps"
164
+ service["labels"] = labels
165
+ result.add("C011", name, f"服务 {service_name} 补 labels.createdBy: Apps")
166
+ changed = True
167
+ return changed
168
+
169
+
170
+ def fix_env_sample(version_dir: Path, compose_text: str, result: FixResult, dry_run: bool) -> None:
171
+ from .checks.compose import env_refs
172
+
173
+ try:
174
+ compose = yaml.safe_load(compose_text) or {}
175
+ except yaml.YAMLError:
176
+ return
177
+ referenced = {ref for ref, _ in env_refs(compose)}
178
+ if not referenced:
179
+ return
180
+ sample = version_dir / ".env.sample"
181
+ text = sample.read_text(encoding="utf-8-sig", errors="replace") if sample.exists() else ""
182
+ present = {
183
+ line.split("=", 1)[0].strip()
184
+ for line in text.splitlines()
185
+ if "=" in line and not line.lstrip().startswith("#")
186
+ }
187
+ missing = sorted(referenced - present)
188
+ if not missing:
189
+ return
190
+ if text and not text.endswith("\n"):
191
+ text += "\n"
192
+ text += "\n".join(f"{key}=" for key in missing) + "\n"
193
+ result.add("H021", ".env.sample", f"补 {len(missing)} 个变量: {', '.join(missing)}")
194
+ if not dry_run:
195
+ sample.write_text(text, encoding="utf-8", newline="\n")
196
+
197
+
198
+ # --------------------------------------------------------------------------
199
+ # metadata + form design
200
+ # --------------------------------------------------------------------------
201
+
202
+
203
+ def fix_root_metadata(root: Path, result: FixResult, dry_run: bool) -> None:
204
+ path = root / "data.yml"
205
+ if not path.exists():
206
+ return
207
+ data = load_yaml(path)
208
+ additional = data.get("additionalProperties")
209
+ if not isinstance(additional, dict):
210
+ return
211
+ changed = False
212
+
213
+ for key, default in (("recommend", 0), ("memoryRequired", 0)):
214
+ if key not in additional:
215
+ additional[key] = default
216
+ result.add("P004", "data.yml", f"补 additionalProperties.{key}: {default}")
217
+ changed = True
218
+
219
+ one_liner = str(additional.get("shortDescZh") or "").strip()
220
+ if one_liner:
221
+ for key in ("title",):
222
+ if str(data.get(key) or "").strip() != one_liner:
223
+ result.add(
224
+ "I005",
225
+ "data.yml",
226
+ f"{key} 对齐到 shortDescZh(商店约定三者同一句)",
227
+ )
228
+ data[key] = one_liner
229
+ changed = True
230
+ if str(data.get("description") or "").strip() != one_liner:
231
+ result.add("I005", "data.yml", "description 对齐到 shortDescZh")
232
+ data["description"] = one_liner
233
+ changed = True
234
+
235
+ if changed and not dry_run:
236
+ path.write_text(_dump(data), encoding="utf-8", newline="\n")
237
+
238
+
239
+ def _complete_label(field: dict) -> bool:
240
+ """Fill a full label map from labelEn/labelZh, reusing store translations."""
241
+ dictionary = rules.i18n().get("label_dictionary") or {}
242
+ languages = rules.all_languages()
243
+ english = str(field.get("labelEn") or "")
244
+ chinese = str(field.get("labelZh") or "")
245
+ label = field.get("label")
246
+ if isinstance(label, dict):
247
+ english = english or str(label.get("en") or "")
248
+ chinese = chinese or str(label.get("zh") or "")
249
+ if not english:
250
+ return False
251
+ merged = (
252
+ {lang: dictionary[english].get(lang, english) for lang in languages}
253
+ if english in dictionary
254
+ else {lang: english for lang in languages}
255
+ )
256
+ if chinese:
257
+ merged["zh"] = chinese
258
+ missing = [lang for lang in rules.required_languages() if not merged.get(lang)]
259
+ if not missing and isinstance(label, dict) and len(label) == len(languages):
260
+ return False
261
+ field["label"] = merged
262
+ field.setdefault("labelEn", english)
263
+ if chinese:
264
+ field["labelZh"] = chinese
265
+ return True
266
+
267
+
268
+ def fix_form_design(
269
+ root: Path, result: FixResult, dry_run: bool
270
+ ) -> dict[str, str]:
271
+ """Move optional fields with defaults out of the form.
272
+
273
+ Returns the defaults that must now appear in the compose file, so the
274
+ variable keeps a working value once it is no longer a form field.
275
+ """
276
+ hidden: dict[str, str] = {}
277
+ budget = rules.load("form-design").get("budget") or {}
278
+ limit = int(budget.get("fields_warn") or 11)
279
+
280
+ for version_dir in find_version_dirs(root):
281
+ path = version_dir / "data.yml"
282
+ if not path.exists():
283
+ continue
284
+ data = load_yaml(path)
285
+ additional = data.get("additionalProperties")
286
+ if not isinstance(additional, dict):
287
+ continue
288
+ fields = [f for f in (additional.get("formFields") or []) if isinstance(f, dict)]
289
+ if not fields:
290
+ continue
291
+
292
+ kept: list[dict] = []
293
+ labels_changed = False
294
+ for field in fields:
295
+ env_key = str(field.get("envKey") or "")
296
+ default = field.get("default")
297
+ default_text = "" if default is None else str(default)
298
+ removable = (
299
+ not field.get("required")
300
+ and not is_secret(env_key)
301
+ and env_key
302
+ and not env_key.startswith("PANEL_APP_PORT_")
303
+ )
304
+ if removable:
305
+ hidden[env_key] = default_text
306
+ continue
307
+ if _complete_label(field):
308
+ result.add("I010", path.name, f"{env_key} 补齐多语言 label")
309
+ labels_changed = True
310
+ kept.append(field)
311
+
312
+ removed = len(fields) - len(kept)
313
+ if not removed and not labels_changed:
314
+ continue
315
+
316
+ if removed:
317
+ result.add(
318
+ "F001",
319
+ path.name,
320
+ f"表单 {len(fields)} → {len(kept)} 个字段"
321
+ "(把可选且有默认值的项收进 compose 默认值)",
322
+ )
323
+ if len(kept) > limit:
324
+ result.skipped.append(
325
+ f"{path.name}: 收拢后仍有 {len(kept)} 个字段(p90={limit}),"
326
+ "需要人工判断哪些是用户真正必须决定的"
327
+ )
328
+ additional["formFields"] = kept
329
+ data["additionalProperties"] = additional
330
+ if not dry_run:
331
+ path.write_text(_dump(data), encoding="utf-8", newline="\n")
332
+ return hidden
333
+
334
+
335
+ def apply_hidden_defaults(
336
+ version_dir: Path, hidden: dict[str, str], result: FixResult, dry_run: bool
337
+ ) -> None:
338
+ """Give every hidden field a compose default so nothing silently goes empty."""
339
+ path = version_dir / "docker-compose.yml"
340
+ if not path.exists() or not hidden:
341
+ return
342
+ text = path.read_text(encoding="utf-8-sig", errors="replace")
343
+ original = text
344
+ for key, default in hidden.items():
345
+ pattern = re.compile(r"\$\{" + re.escape(key) + r"\}")
346
+ replacement = f"${{{key}:-{default}}}" if default else f"${{{key}:-}}"
347
+ text = pattern.sub(replacement, text)
348
+ if text != original:
349
+ result.add(
350
+ "F004",
351
+ f"{version_dir.name}/docker-compose.yml",
352
+ f"{len(hidden)} 个变量改为带默认值(不再出现在表单里)",
353
+ )
354
+ if not dry_run:
355
+ path.write_text(text, encoding="utf-8", newline="\n")
356
+
357
+
358
+ # --------------------------------------------------------------------------
359
+ # entry point
360
+ # --------------------------------------------------------------------------
361
+
362
+
363
+ def fix(root: Path, dry_run: bool = False) -> FixResult:
364
+ result = FixResult(root=root, dry_run=dry_run)
365
+ if not (root / "data.yml").exists():
366
+ raise FileNotFoundError(f"{root} 不是应用包根目录(缺少 data.yml)")
367
+
368
+ normalize_text(root, result, dry_run)
369
+ fix_logo(root, result, dry_run)
370
+ fix_root_metadata(root, result, dry_run)
371
+
372
+ hidden = fix_form_design(root, result, dry_run)
373
+ for version_dir in find_version_dirs(root):
374
+ apply_hidden_defaults(version_dir, hidden, result, dry_run)
375
+ compose_path = version_dir / "docker-compose.yml"
376
+ if not compose_path.exists():
377
+ continue
378
+ text = compose_path.read_text(encoding="utf-8-sig", errors="replace")
379
+ text = fix_compose_text(text, result, f"{version_dir.name}/docker-compose.yml", dry_run)
380
+ try:
381
+ compose = yaml.safe_load(text) or {}
382
+ except yaml.YAMLError:
383
+ compose = {}
384
+ if isinstance(compose, dict) and ensure_created_by(
385
+ compose, result, f"{version_dir.name}/docker-compose.yml", dry_run
386
+ ):
387
+ text = _dump(compose)
388
+ text = QUOTE_IMAGE.sub(r'\1"\2"', text)
389
+ text = QUOTE_PORT.sub(r'\1"\2"', text)
390
+ text = QUOTE_CONTAINER.sub(r'\1"\2"', text)
391
+ if not dry_run:
392
+ compose_path.write_text(text, encoding="utf-8", newline="\n")
393
+ fix_env_sample(version_dir, text, result, dry_run)
394
+ return result