sdtk-ops-kit 0.3.3 → 0.4.0

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 (40) hide show
  1. package/README.md +2 -1
  2. package/assets/manifest/toolkit-bundle.manifest.json +144 -19
  3. package/assets/manifest/toolkit-bundle.sha256.txt +35 -10
  4. package/assets/toolkit/toolkit/AGENTS.md +2 -1
  5. package/assets/toolkit/toolkit/SDTKOPS_TOOLKIT.md +4 -2
  6. package/assets/toolkit/toolkit/scripts/install-claude-skills.ps1 +4 -4
  7. package/assets/toolkit/toolkit/scripts/install-codex-skills.ps1 +4 -4
  8. package/assets/toolkit/toolkit/scripts/uninstall-claude-skills.ps1 +2 -2
  9. package/assets/toolkit/toolkit/scripts/uninstall-codex-skills.ps1 +2 -2
  10. package/assets/toolkit/toolkit/skills/ops-discover/SKILL.md +2 -0
  11. package/assets/toolkit/toolkit/skills/ops-framer-deploy/SKILL.md +15 -1
  12. package/assets/toolkit/toolkit/skills/ops-framer-deploy/package.json +10 -0
  13. package/assets/toolkit/toolkit/skills/ops-framer-deploy/scripts/framer-install.mjs +5 -1
  14. package/assets/toolkit/toolkit/skills/ops-framer-deploy/scripts/lib/config.mjs +6 -0
  15. package/assets/toolkit/toolkit/skills/ops-local-env/SKILL.md +172 -0
  16. package/assets/toolkit/toolkit/skills/ops-local-env/references/CLUSTER_CA.md +83 -0
  17. package/assets/toolkit/toolkit/skills/ops-local-env/references/GOTCHAS.md +17 -0
  18. package/assets/toolkit/toolkit/skills/ops-local-env/references/K3D_CILIUM_BOOTSTRAP.md +39 -0
  19. package/assets/toolkit/toolkit/skills/ops-local-env/references/PROFILE.md +44 -0
  20. package/assets/toolkit/toolkit/skills/ops-local-env/references/bootstrap/cilium-values.yaml +37 -0
  21. package/assets/toolkit/toolkit/skills/ops-local-env/references/bootstrap/k3d-cluster.yaml +37 -0
  22. package/assets/toolkit/toolkit/skills/ops-local-env/references/profile.example.json +80 -0
  23. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/admin_creds.py +212 -0
  24. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/cilium_heal.py +136 -0
  25. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/ensure_repos.py +69 -0
  26. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/envprofile.py +139 -0
  27. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/explain_config.py +116 -0
  28. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/health.py +109 -0
  29. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/hosts_entry.py +158 -0
  30. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/init_profile.py +217 -0
  31. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/k3d_images.py +70 -0
  32. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/preflight.py +96 -0
  33. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/registry_secret.py +64 -0
  34. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/shared_config.py +178 -0
  35. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/stack_plan.py +94 -0
  36. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/teardown.py +86 -0
  37. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/test_local_env.py +307 -0
  38. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/trust_ca.py +153 -0
  39. package/package.json +1 -1
  40. package/src/lib/scope.js +1 -0
@@ -0,0 +1,109 @@
1
+ #!/usr/bin/env python3
2
+ """health.py - run every component's `health` commands of the profile and print one table, OK / FAIL.
3
+ For "is the environment still alive?" -- after a reboot, before a test run, at the end of an install.
4
+
5
+ health.py # every component
6
+ health.py --only db mq # some components
7
+ health.py --timeout 30 # seconds per command (default 20)
8
+
9
+ `{key}` placeholders are filled from the primary config. Commands run from the workspace without a
10
+ shell (no pipes, redirections or `&&`), and only read-only ones: the program must be kubectl, helm,
11
+ k3d, docker, openssl, curl or test, and no token may be a changing verb (apply, delete, upgrade,
12
+ rollout restart, exec, ...), nor a curl upload / non-GET method. A refused command is reported as
13
+ REFUSED and counts as a failure: fix the profile. Exit 0 when every check is OK.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import argparse
19
+ import shlex
20
+ import subprocess
21
+ import sys
22
+
23
+ from envprofile import Stack, add_common_args
24
+
25
+ PROGRAMS = {"kubectl", "helm", "k3d", "docker", "openssl", "curl", "test"}
26
+ CHANGING = {"apply", "create", "delete", "patch", "edit", "replace", "scale", "annotate", "label", "drain",
27
+ "cordon", "uncordon", "taint", "exec", "cp", "run", "expose", "set", "install", "upgrade",
28
+ "uninstall", "rollback", "restart", "rm", "kill", "stop", "start", "import", "push", "pull",
29
+ "autoscale", "port-forward", "proxy", "attach", "debug", "certificate"}
30
+ CURL_WRITES = {"-X", "--request", "-d", "--data", "--data-raw", "--data-binary", "--data-urlencode",
31
+ "-F", "--form", "-T", "--upload-file", "-o", "--output", "-O", "--remote-name"}
32
+ SHELL_CHARS = ("|", "&&", ";", ">", "<", "`", "$(")
33
+
34
+
35
+ def refusal(argv: list[str], raw: str) -> str | None:
36
+ if any(ch in raw for ch in SHELL_CHARS):
37
+ return "shell syntax (pipe, redirection, &&) is not run"
38
+ if not argv or argv[0] not in PROGRAMS:
39
+ return f"program {argv[0] if argv else '?'} is not in the read-only list"
40
+ if argv[0] == "curl":
41
+ bad = [a for a in argv if a in CURL_WRITES or a.split("=")[0] in CURL_WRITES]
42
+ # `-o /dev/null` is the usual status-code check: allow exactly that
43
+ if bad and not (set(bad) <= {"-o", "--output"} and "/dev/null" in argv):
44
+ return f"curl option {bad[0]} may write"
45
+ return None
46
+ words = [a for a in argv[1:] if not a.startswith("-")]
47
+ if argv[0] == "kubectl" and "rollout" in words:
48
+ return None if "status" in words else "kubectl rollout other than status"
49
+ hit = next((w for w in words if w in CHANGING), None)
50
+ return f"changing verb {hit!r}" if hit else None
51
+
52
+
53
+ def main() -> int:
54
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
55
+ add_common_args(parser)
56
+ parser.add_argument("--only", nargs="+", metavar="ID")
57
+ parser.add_argument("--timeout", type=int, default=20)
58
+ args = parser.parse_args()
59
+ stack = Stack(args.profile, args.root)
60
+ comps = [c for c in stack.get("components") or [] if not args.only or c.get("id") in args.only]
61
+ if args.only:
62
+ unknown = set(args.only) - {c.get("id") for c in comps}
63
+ if unknown:
64
+ print(f"error: unknown component(s): {', '.join(sorted(unknown))}", file=sys.stderr)
65
+ return 2
66
+ print(f"stack: {stack.name} workspace: {stack.root} context: "
67
+ + (subprocess.run(["kubectl", "config", "current-context"], capture_output=True, text=True, check=False).stdout.strip()
68
+ or "(none)") if _has("kubectl") else f"stack: {stack.name} workspace: {stack.root}")
69
+ print("\n| component | check | result | detail |\n|---|---|---|---|")
70
+ failed = 0
71
+ for comp in comps:
72
+ checks = comp.get("health") or []
73
+ if not checks:
74
+ print(f"| {comp['id']} | - | NONE | no health commands in the profile |")
75
+ continue
76
+ for raw in checks:
77
+ cmd = stack.expand(raw)
78
+ try:
79
+ argv = shlex.split(cmd)
80
+ except ValueError as exc:
81
+ argv, why = [], f"cannot parse: {exc}"
82
+ else:
83
+ why = refusal(argv, cmd)
84
+ if why:
85
+ failed += 1
86
+ print(f"| {comp['id']} | `{cmd}` | REFUSED | {why} |")
87
+ continue
88
+ try:
89
+ res = subprocess.run(argv, cwd=str(stack.root), capture_output=True, text=True,
90
+ timeout=args.timeout, check=False)
91
+ ok, out = res.returncode == 0, (res.stdout if res.returncode == 0 else res.stderr or res.stdout)
92
+ except subprocess.TimeoutExpired:
93
+ ok, out = False, f"timed out after {args.timeout}s"
94
+ except FileNotFoundError:
95
+ ok, out = False, f"{argv[0]} not found"
96
+ failed += not ok
97
+ last = (out.strip().splitlines() or [""])[-1][:100].replace("|", "\\|")
98
+ print(f"| {comp['id']} | `{cmd}` | {'OK' if ok else 'FAIL'} | {last} |")
99
+ print(f"\n{'all checks OK' if not failed else f'{failed} check(s) not OK'}")
100
+ return 1 if failed else 0
101
+
102
+
103
+ def _has(program: str) -> bool:
104
+ import shutil
105
+ return shutil.which(program) is not None
106
+
107
+
108
+ if __name__ == "__main__":
109
+ sys.exit(main())
@@ -0,0 +1,158 @@
1
+ #!/usr/bin/env python3
2
+ """hosts_entry.py - map every host name of the stack to 127.0.0.1 in the hosts file, on macOS, Linux
3
+ and Windows.
4
+
5
+ hosts_entry.py --show # names found, what the hosts file has, what is missing (exit 1 if not in sync)
6
+ hosts_entry.py --apply # write the managed block (needs root / Administrator)
7
+ hosts_entry.py --remove # take the block out again (after a teardown; elevated)
8
+
9
+ Host names: every `*_domain` key (except the base domain) of the configs listed in the profile's
10
+ `hosts.configs` (default: every config). They go on one line inside a block this script owns,
11
+ replaced on every --apply:
12
+
13
+ # BEGIN <stack name> (ops-local-env)
14
+ 127.0.0.1 app.example.test admin.example.test ...
15
+ # END <stack name>
16
+
17
+ Lines outside the block are never touched; a name mapped there to another address is reported.
18
+ The previous file is kept as hosts.<stack name>.bak; the DNS cache is flushed after writing.
19
+ Standard library only, so it runs under sudo or an elevated prompt.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import argparse
25
+ import os
26
+ import platform
27
+ import re
28
+ import shutil
29
+ import subprocess
30
+ import sys
31
+ from pathlib import Path
32
+
33
+ from envprofile import Stack, add_common_args
34
+
35
+ DOMAIN_LINE = re.compile(r'^([a-z0-9_]+_domain):\s*"?([A-Za-z0-9.-]+)"?\s*(?:#.*)?$', re.M)
36
+
37
+
38
+ def hosts_path() -> Path:
39
+ if platform.system() == "Windows":
40
+ return Path(os.environ.get("SystemRoot", r"C:\Windows")) / "System32" / "drivers" / "etc" / "hosts"
41
+ return Path("/etc/hosts")
42
+
43
+
44
+ def domains(stack: Stack) -> list[str]:
45
+ conf = stack.get("hosts") or {}
46
+ base_key = stack.get("base_domain_key") or "base_domain"
47
+ found: list[str] = []
48
+ for name in conf.get("configs") or list(stack.configs):
49
+ path = stack.configs.get(name)
50
+ if not path or not path.is_file():
51
+ continue
52
+ for key, value in DOMAIN_LINE.findall(path.read_text(encoding="utf-8")):
53
+ if key != base_key and "." in value and value.lower() not in found:
54
+ found.append(value.lower())
55
+ for extra in conf.get("extra") or []:
56
+ if extra.lower() not in found:
57
+ found.append(extra.lower())
58
+ return found
59
+
60
+
61
+ def flush_dns() -> None:
62
+ cmds = {"Darwin": [["dscacheutil", "-flushcache"], ["killall", "-HUP", "mDNSResponder"]],
63
+ "Windows": [["ipconfig", "/flushdns"]],
64
+ "Linux": [["resolvectl", "flush-caches"]] if shutil.which("resolvectl") else []}.get(platform.system(), [])
65
+ for cmd in cmds:
66
+ subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
67
+
68
+
69
+ def elevated_command(argv_tail: str) -> str:
70
+ me = Path(__file__).resolve()
71
+ if platform.system() == "Windows":
72
+ return f'(elevated PowerShell) python "{me}" {argv_tail} --apply'
73
+ return f'sudo python3 "{me}" {argv_tail} --apply'
74
+
75
+
76
+ def main() -> int:
77
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
78
+ add_common_args(parser)
79
+ parser.add_argument("--hosts-file", metavar="FILE", help=argparse.SUPPRESS) # tests
80
+ mode = parser.add_mutually_exclusive_group(required=True)
81
+ mode.add_argument("--show", action="store_true")
82
+ mode.add_argument("--apply", action="store_true")
83
+ mode.add_argument("--remove", action="store_true")
84
+ args = parser.parse_args()
85
+
86
+ stack = Stack(args.profile, args.root)
87
+ ip = (stack.get("hosts") or {}).get("ip", "127.0.0.1")
88
+ begin, end = f"# BEGIN {stack.name} (ops-local-env)", f"# END {stack.name}"
89
+ block_rx = rf"^{re.escape(begin)}\r?\n.*?^{re.escape(end)}\r?\n?"
90
+ names = domains(stack)
91
+ if not names and not args.remove:
92
+ sys.exit(f"error: no *_domain keys found in the stack's configs under {stack.root}")
93
+ path = Path(args.hosts_file) if args.hosts_file else hosts_path()
94
+ text = ""
95
+ if path.is_file():
96
+ with open(path, encoding="utf-8", errors="replace", newline="") as fh: # keep \r\n as is
97
+ text = fh.read()
98
+ newline = "\r\n" if "\r\n" in text or platform.system() == "Windows" else "\n"
99
+ wanted = newline.join([begin, f"{ip} {' '.join(names)}", end]) + newline
100
+ current = re.search(block_rx, text, re.M | re.S)
101
+ outside = re.sub(block_rx, "", text, flags=re.M | re.S)
102
+
103
+ print(f"hosts file: {path}")
104
+ print(f"host names ({len(names)}): {' '.join(names)}")
105
+ for line in outside.splitlines():
106
+ fields = line.split("#", 1)[0].split()
107
+ for name in fields[1:]:
108
+ if name.lower() in names and fields[0] != ip:
109
+ print(f"WARNING: {name} is also mapped to {fields[0]} outside the block; the first line in the file wins")
110
+ in_sync = current is not None and current.group(0).replace("\r\n", "\n") == wanted.replace("\r\n", "\n")
111
+ tail = f'--profile "{stack.profile_path}" --root "{stack.root}"'
112
+
113
+ if args.remove:
114
+ if not current:
115
+ print("block: not there; nothing to remove")
116
+ return 0
117
+ try:
118
+ shutil.copy2(path, path.with_name(f"hosts.{stack.name}.bak"))
119
+ with open(path, "w", encoding="utf-8", newline="") as fh:
120
+ fh.write(outside)
121
+ except PermissionError:
122
+ print(f"error: no permission to write {path}; run it elevated with --remove", file=sys.stderr)
123
+ return 1
124
+ if not args.hosts_file:
125
+ flush_dns()
126
+ print("block removed")
127
+ return 0
128
+ if args.show:
129
+ if in_sync:
130
+ print("block: up to date")
131
+ return 0
132
+ print("block: " + ("out of date" if current else "missing"))
133
+ print(f"to write it, run:\n {elevated_command(tail)}")
134
+ return 1
135
+ if in_sync:
136
+ print("block: already up to date; nothing written")
137
+ return 0
138
+ new = outside
139
+ if new and not new.endswith(("\n", "\r\n")):
140
+ new += newline
141
+ new += wanted
142
+ backup = path.with_name(f"hosts.{stack.name}.bak")
143
+ try:
144
+ if path.is_file():
145
+ shutil.copy2(path, backup)
146
+ with open(path, "w", encoding="utf-8", newline="") as fh:
147
+ fh.write(new)
148
+ except PermissionError:
149
+ print(f"error: no permission to write {path}; run:\n {elevated_command(tail)}", file=sys.stderr)
150
+ return 1
151
+ if not args.hosts_file:
152
+ flush_dns()
153
+ print(f"block written ({len(names)} names -> {ip}); backup: {backup}")
154
+ return 0
155
+
156
+
157
+ if __name__ == "__main__":
158
+ sys.exit(main())
@@ -0,0 +1,217 @@
1
+ #!/usr/bin/env python3
2
+ """init_profile.py - draft ops-env.profile.json by reading a workspace that already holds the stack's
3
+ repositories side by side. Nothing is guessed silently: every inference is listed under `_todo` for
4
+ the person to confirm, and the draft must pass stack_plan.py --check before it is used.
5
+
6
+ init_profile.py --root DIR [--name NAME] [--anchor REPO] [--registry HOST] # print the draft
7
+ init_profile.py --root DIR ... --write [--force] # write <anchor>/ops-env.profile.json
8
+
9
+ What it reads (read-only):
10
+ repos every direct subdirectory that is a git clone; `origin` gives url / https
11
+ configs config.yaml, k8s/config.yaml, deploy/config.yaml of each repo (top-level `key: value` lines)
12
+ anchor --anchor, else the repo whose config holds the base domain and the most *_domain keys
13
+ shared keys present in two or more configs (users / passwords excluded); different values are listed
14
+ admin *_user / *_login / *_username keys -> users; *password* keys of the secrets.yaml beside each
15
+ config -> passwords (a password found in a config file is reported: it belongs in secrets.yaml)
16
+ hosts the configs that hold *_domain keys
17
+ ca <anchor>/**/certs/<base_domain>/ca.crt when it exists
18
+ components the anchor first, then each repo with an install skill (.claude/.codex skills named
19
+ install-* / *-install*), else a launcher (launch.py, deploy.sh, install.sh, Makefile)
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import argparse
25
+ import json
26
+ import re
27
+ import subprocess
28
+ import sys
29
+ from pathlib import Path
30
+
31
+ from envprofile import PROFILE_NAME, load_flat
32
+
33
+ CONFIG_CANDIDATES = ("config.yaml", "k8s/config.yaml", "deploy/config.yaml")
34
+ USER_KEY = re.compile(r"(_user|_login|_username)$")
35
+ PASSWORD_KEY = re.compile(r"password", re.I)
36
+ LAUNCHERS = ("launch.py", "deploy.sh", "install.sh", "Makefile")
37
+
38
+
39
+ def origin(repo: Path) -> str | None:
40
+ res = subprocess.run(["git", "-C", str(repo), "remote", "get-url", "origin"], capture_output=True, text=True, check=False)
41
+ return res.stdout.strip() or None
42
+
43
+
44
+ def https_of(url: str | None) -> str | None:
45
+ if not url:
46
+ return None
47
+ m = re.match(r"^git@([^:]+):(.+)$", url)
48
+ return f"https://{m.group(1)}/{m.group(2)}" if m else (url if url.startswith("https://") else None)
49
+
50
+
51
+ def short_name(repo: str, prefix: str) -> str:
52
+ return repo[len(prefix):] if prefix and repo.startswith(prefix) and len(repo) > len(prefix) else repo
53
+
54
+
55
+ def common_prefix(names: list[str]) -> str:
56
+ if len(names) < 2:
57
+ return ""
58
+ first, last = min(names), max(names)
59
+ i = 0
60
+ while i < min(len(first), len(last)) and first[i] == last[i]:
61
+ i += 1
62
+ prefix = first[:i]
63
+ return prefix[: prefix.rfind("-") + 1] if "-" in prefix else ""
64
+
65
+
66
+ def install_skill(repo: Path) -> str | None:
67
+ for base in (".claude/skills", ".codex/skills"):
68
+ d = repo / base
69
+ if d.is_dir():
70
+ hits = sorted(p.name for p in d.iterdir() if p.is_dir() and re.search(r"(^install-|-install)", p.name))
71
+ if hits:
72
+ return hits[0]
73
+ return None
74
+
75
+
76
+ def draft(root: Path, name: str | None, anchor: str | None, registry: str | None) -> dict:
77
+ todo: list[str] = []
78
+ repos = sorted(p for p in root.iterdir() if p.is_dir() and (p / ".git").exists())
79
+ if not repos:
80
+ raise SystemExit(f"error: no git clone directly under {root}")
81
+ prefix = common_prefix([r.name for r in repos])
82
+ repo_entries = []
83
+ for r in repos:
84
+ url = origin(r)
85
+ if not url:
86
+ todo.append(f"repos.{r.name}: no origin remote; fill url / https")
87
+ repo_entries.append({"dir": r.name, "url": url, "https": https_of(url)})
88
+
89
+ configs: dict[str, str] = {}
90
+ values: dict[str, dict] = {}
91
+ for r in repos:
92
+ for cand in CONFIG_CANDIDATES:
93
+ path = r / cand
94
+ if path.is_file():
95
+ key = short_name(r.name, prefix) + ("" if cand == "config.yaml" else "-" + cand.split("/")[0])
96
+ configs[key] = f"{r.name}/{cand}"
97
+ values[key] = load_flat(path)
98
+ if not configs:
99
+ todo.append("configs: no config.yaml found; list each repo's config file by hand")
100
+
101
+ def score(cfg: str) -> tuple:
102
+ v = values[cfg]
103
+ return ("base_domain" in v, sum(k.endswith("_domain") for k in v))
104
+ if anchor:
105
+ primary = next((c for c, rel in configs.items() if rel.split("/")[0] == anchor), None)
106
+ if not primary:
107
+ todo.append(f"anchor {anchor}: no config file found in it")
108
+ else:
109
+ primary = max(configs, key=score) if configs else None
110
+ anchor = configs[primary].split("/")[0] if primary else repos[0].name
111
+ todo.append(f"anchor / primary_config inferred as {anchor} ({primary}); confirm")
112
+
113
+ counts: dict[str, list[str]] = {}
114
+ for cfg, v in values.items():
115
+ for k, val in v.items():
116
+ if val is None or USER_KEY.search(k) or PASSWORD_KEY.search(k):
117
+ continue
118
+ counts.setdefault(k, []).append(cfg)
119
+ shared = sorted(k for k, cfgs in counts.items() if len(cfgs) >= 2)
120
+ for k in shared:
121
+ distinct = {values[c][k] for c in counts[k]}
122
+ if len(distinct) > 1:
123
+ todo.append(f"shared key {k} differs between configs ({', '.join(f'{c}={values[c][k]}' for c in counts[k])}): "
124
+ "same meaning (fix the values) or a different meaning (add an alias)?")
125
+
126
+ users, passwords = [], []
127
+ for cfg, rel in configs.items():
128
+ for k, val in values[cfg].items():
129
+ if USER_KEY.search(k):
130
+ users.append({"file": rel, "key": k})
131
+ if PASSWORD_KEY.search(k) and val:
132
+ todo.append(f"{rel}: {k} holds a password in a config file; move it to secrets.yaml (gitignored)")
133
+ secrets_rel = str(Path(rel).parent / "secrets.yaml")
134
+ for k in load_flat(root / secrets_rel):
135
+ if PASSWORD_KEY.search(k):
136
+ passwords.append({"file": secrets_rel, "key": k})
137
+ if users and not passwords:
138
+ todo.append("admin.passwords: no secrets.yaml with password keys found; list them (they may not exist yet)")
139
+
140
+ hosts = [c for c, v in values.items() if any(k.endswith("_domain") and k != "base_domain" for k in v)]
141
+ base = values.get(primary, {}).get("base_domain") if primary else None
142
+ ca = None
143
+ if base:
144
+ for crt in sorted((root / anchor).rglob(f"certs/{base}/ca.crt")):
145
+ rel_dir = str(crt.parent.relative_to(root)).replace(base, "{base_domain}")
146
+ ca = {"dir": rel_dir, "ca": "ca.crt", "leaf": "tls.crt", "site_key": "site_domain"}
147
+ break
148
+ if not ca:
149
+ todo.append("ca: no certs/<base_domain>/ca.crt yet; set ca.dir once the bootstrap has made it")
150
+
151
+ components = []
152
+ order = [anchor] + [r.name for r in repos if r.name != anchor]
153
+ for rname in order:
154
+ r = root / rname
155
+ comp: dict = {"id": short_name(rname, prefix), "repo": rname}
156
+ skill = install_skill(r)
157
+ launcher = next((l for l in LAUNCHERS if (r / l).is_file() or (r / "k8s" / l).is_file()), None)
158
+ if skill:
159
+ comp["skill"] = skill
160
+ elif launcher:
161
+ where = "k8s/" if (r / "k8s" / launcher).is_file() else ""
162
+ comp["run"] = f"cd {rname}{'/' + where.rstrip('/') if where else ''} && " + ("make" if launcher == "Makefile" else f"./{launcher}")
163
+ todo.append(f"components.{comp['id']}: `run` guessed from {where}{launcher}; check the arguments")
164
+ else:
165
+ continue
166
+ cfgs = [c for c, rel in configs.items() if rel.split("/")[0] == rname]
167
+ if cfgs:
168
+ comp["configs"] = cfgs
169
+ if components:
170
+ comp["after"] = [components[0]["id"]]
171
+ comp["health"] = []
172
+ components.append(comp)
173
+ todo.append("components: check the order and `after`, add `health` commands (read-only: kubectl get, helm list, ...)")
174
+
175
+ profile = {"name": name or (prefix.rstrip("-") or root.name), "repos": repo_entries, "configs": configs,
176
+ "primary_config": primary, "base_domain_key": "base_domain",
177
+ "core_keys": [k for k in ("apps_namespace", "base_domain") if k in shared or k in values.get(primary, {})],
178
+ "shared_keys": shared, "admin": {"users": users, "passwords": passwords},
179
+ "hosts": {"configs": hosts, "ip": "127.0.0.1"}, "components": components}
180
+ if ca:
181
+ profile["ca"] = ca
182
+ if registry:
183
+ profile["registry"] = {"host": registry, "token_env": "REGISTRY_TOKEN", "pull_secret": "registry-pull"}
184
+ if registry == "ghcr.io":
185
+ profile["registry"].update({"kind": "github-classic-pat", "scope": "read:packages"})
186
+ profile["_todo"] = todo
187
+ return profile
188
+
189
+
190
+ def main() -> int:
191
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
192
+ parser.add_argument("--root", metavar="DIR", default=".", help="workspace holding the repositories")
193
+ parser.add_argument("--name")
194
+ parser.add_argument("--anchor", metavar="REPO", help="repository that bootstraps the cluster and holds the profile")
195
+ parser.add_argument("--registry", metavar="HOST", help="image registry the charts pull from (e.g. ghcr.io)")
196
+ parser.add_argument("--write", action="store_true")
197
+ parser.add_argument("--force", action="store_true", help="overwrite an existing profile")
198
+ args = parser.parse_args()
199
+ root = Path(args.root).expanduser().resolve()
200
+ profile = draft(root, args.name, args.anchor, args.registry)
201
+ text = json.dumps(profile, indent=2, ensure_ascii=False) + "\n"
202
+ if not args.write:
203
+ sys.stdout.write(text)
204
+ print(f"\n(draft; {len(profile['_todo'])} item(s) to review in _todo -- add --write to save it)", file=sys.stderr)
205
+ return 0
206
+ anchor = profile["components"][0]["repo"] if profile["components"] else profile["repos"][0]["dir"]
207
+ target = root / anchor / PROFILE_NAME
208
+ if target.exists() and not args.force:
209
+ print(f"error: {target} exists; review it, or pass --force to overwrite", file=sys.stderr)
210
+ return 1
211
+ target.write_text(text, encoding="utf-8")
212
+ print(f"wrote {target}; review the {len(profile['_todo'])} _todo item(s), then run stack_plan.py --check")
213
+ return 0
214
+
215
+
216
+ if __name__ == "__main__":
217
+ sys.exit(main())
@@ -0,0 +1,70 @@
1
+ #!/usr/bin/env python3
2
+ """k3d_images.py - is an image in a local k3d cluster, for every node's own platform?
3
+
4
+ An image listed by a node is not enough: `k3d image import` of an image built for another
5
+ architecture (an amd64 build on an arm64 machine) leaves one the node lists but can never run
6
+ (ErrImagePull, "no match for platform"). This checks each node's containerd for the image with the
7
+ node's own platform.
8
+
9
+ k3d_images.py --cluster NAME IMAGE:TAG [...] # one line per image: PRESENT | MISSING
10
+
11
+ Images built locally and imported (`k3d image import`) are named docker.io/library/<name> inside the
12
+ nodes unless they carry a registry; pass them as you tagged them. Exit 0 when every image is
13
+ PRESENT, 1 otherwise. Read-only.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import argparse
19
+ import subprocess
20
+ import sys
21
+
22
+
23
+ def sh(*cmd: str) -> str:
24
+ return subprocess.run(cmd, capture_output=True, text=True, check=False).stdout
25
+
26
+
27
+ def full_ref(image: str) -> str:
28
+ first = image.split("/", 1)[0]
29
+ if "/" not in image:
30
+ return f"docker.io/library/{image}"
31
+ if "." in first or ":" in first or first == "localhost":
32
+ return image
33
+ return f"docker.io/{image}"
34
+
35
+
36
+ def nodes(cluster: str) -> list[str]:
37
+ names = sh("docker", "ps", "--format", "{{.Names}}").split()
38
+ prefix = f"k3d-{cluster}-"
39
+ return [n for n in names if n.startswith(prefix) and n[len(prefix):].split("-")[0] in ("server", "agent")]
40
+
41
+
42
+ def present(node: str, ref: str) -> bool:
43
+ arch = {"aarch64": "arm64", "arm64": "arm64", "x86_64": "amd64"}.get(sh("docker", "exec", node, "uname", "-m").strip())
44
+ if not arch:
45
+ return False
46
+ listing = sh("docker", "exec", node, "ctr", "-n", "k8s.io", "images", "ls", f"name=={ref}")
47
+ platforms = ",".join(line.split()[-2] for line in listing.splitlines()[1:] if line.split())
48
+ return f"linux/{arch}" in platforms.split(",")
49
+
50
+
51
+ def main() -> int:
52
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
53
+ parser.add_argument("--cluster", required=True)
54
+ parser.add_argument("images", nargs="+")
55
+ args = parser.parse_args()
56
+ node_list = nodes(args.cluster)
57
+ if not node_list:
58
+ print(f"no running node of k3d cluster {args.cluster}", file=sys.stderr)
59
+ return 1
60
+ ok = True
61
+ for image in args.images:
62
+ ref = full_ref(image)
63
+ good = all(present(n, ref) for n in node_list)
64
+ ok &= good
65
+ print(f"{image} {'PRESENT' if good else 'MISSING'}")
66
+ return 0 if ok else 1
67
+
68
+
69
+ if __name__ == "__main__":
70
+ sys.exit(main())
@@ -0,0 +1,96 @@
1
+ #!/usr/bin/env python3
2
+ """preflight.py - what the stack install needs before anything starts. One line per check:
3
+
4
+ tools the CLI tools of the profile's `tools` (default: docker k3d kubectl helm openssl git curl)
5
+ python3 the Python modules of `python_modules` ({"yaml": "pyyaml", ...}), for this interpreter
6
+ <TOKEN> the registry token of `registry.token_env`, checked without printing it
7
+
8
+ Exit 0 when every line is OK, 1 otherwise. The token is never printed, put on a command line or
9
+ written anywhere: for a GitHub token (`registry.kind: github-classic-pat`) the check asks the GitHub
10
+ API who owns it and which scopes it has (classic PAT with `registry.scope`, e.g. read:packages:
11
+ fine-grained PATs get 403 from ghcr.io).
12
+
13
+ preflight.py [--profile FILE] [--root DIR]
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import argparse
19
+ import importlib.util
20
+ import json
21
+ import os
22
+ import platform
23
+ import shutil
24
+ import sys
25
+ import urllib.error
26
+ import urllib.request
27
+
28
+ from envprofile import Stack, add_common_args
29
+
30
+ DEFAULT_TOOLS = ["docker", "k3d", "kubectl", "helm", "openssl", "git", "curl"]
31
+ failed = False
32
+
33
+
34
+ def line(name: str, state: str, detail: str) -> None:
35
+ global failed
36
+ print(f"{name:12} {state:8} {detail}")
37
+ failed |= state != "OK"
38
+
39
+
40
+ def github_token(token: str, scope: str | None) -> tuple[str, str]:
41
+ if token.startswith("github_pat_"):
42
+ return "WRONG", "fine-grained PAT: the registry answers 403; needs a classic PAT (ghp_...)" + (
43
+ f" with {scope}" if scope else "")
44
+ req = urllib.request.Request("https://api.github.com/user", headers={"Authorization": f"token {token}"})
45
+ try:
46
+ with urllib.request.urlopen(req, timeout=20) as resp:
47
+ login = json.loads(resp.read()).get("login", "?")
48
+ scopes = resp.headers.get("X-OAuth-Scopes", "") or ""
49
+ except urllib.error.HTTPError as exc:
50
+ return "WRONG", f"GitHub answered HTTP {exc.code}: token invalid or expired"
51
+ except OSError as exc:
52
+ return "WRONG", f"GitHub not reachable: {exc}"
53
+ have = {s.strip() for s in scopes.split(",") if s.strip()}
54
+ if scope:
55
+ accepted = {scope, scope.replace("read:", "write:")}
56
+ if not have & accepted:
57
+ return "WRONG", f"no {scope} scope (scopes: {scopes or 'none'})"
58
+ return "OK", f"classic PAT of {login}, scopes: {scopes or 'none'}"
59
+
60
+
61
+ def main() -> int:
62
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
63
+ add_common_args(parser)
64
+ args = parser.parse_args()
65
+ stack = Stack(args.profile, args.root)
66
+ print(f"stack: {stack.name} workspace: {stack.root}")
67
+
68
+ tools = stack.get("tools") or DEFAULT_TOOLS
69
+ missing = [t for t in tools if not shutil.which(t)]
70
+ line("tools", "MISSING" if missing else "OK",
71
+ f"not on PATH: {' '.join(missing)}" if missing else " ".join(tools))
72
+
73
+ modules = stack.get("python_modules") or {}
74
+ lacking = [pkg for mod, pkg in modules.items() if importlib.util.find_spec(mod) is None]
75
+ py = f"{sys.executable} {platform.python_version()}"
76
+ if modules:
77
+ line("python3", "MISSING" if lacking else "OK",
78
+ f"{py} lacks: {' '.join(lacking)}" if lacking else f"{py}: {' '.join(modules.values())}")
79
+ else:
80
+ line("python3", "OK", py)
81
+
82
+ registry = stack.get("registry") or {}
83
+ env = registry.get("token_env")
84
+ if env:
85
+ token = os.environ.get(env, "")
86
+ if not token:
87
+ line(env, "MISSING", "not set in the environment of this session")
88
+ elif registry.get("kind") == "github-classic-pat":
89
+ line(env, *github_token(token, registry.get("scope")))
90
+ else:
91
+ line(env, "OK", "set (not checked against the registry)")
92
+ return 1 if failed else 0
93
+
94
+
95
+ if __name__ == "__main__":
96
+ sys.exit(main())