plinth-cli 0.2.0__py3-none-any.whl

plinth/blueprints/repo/gitops/scripts/bootstrap-local.sh.j2

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Create a local k3d cluster, install Argo CD and point it at this repository.
+# Needs: docker, k3d, kubectl, helm. Push this repo and the app repos first.
+set -euo pipefail
+
+CLUSTER="${CLUSTER:-{{ project.name }}}"
+ARGO_CD_CHART_VERSION="{{ defaults.ARGO_CD_CHART_VERSION }}"
+cd "$(dirname "$0")/.."
+
+for tool in docker k3d kubectl helm; do
+  command -v "$tool" >/dev/null || { echo "missing required tool: $tool" >&2; exit 1; }
+done
+
+k3d cluster list "$CLUSTER" >/dev/null 2>&1 || k3d cluster create "$CLUSTER" --wait
+helm repo add argo https://argoproj.github.io/argo-helm --force-update >/dev/null
+helm upgrade --install argocd argo/argo-cd --version "$ARGO_CD_CHART_VERSION" \
+  --namespace argocd --create-namespace --wait
+kubectl apply -n argocd -f bootstrap/root.yaml
+
+echo "Argo CD is running. Initial admin password:"
+kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d
+echo
+echo "Open the UI: kubectl -n argocd port-forward svc/argocd-server 8080:443, then https://localhost:8080"

plinth/blueprints/workload/common/Dockerfile.j2

@@ -0,0 +1,14 @@
+FROM {{ defaults.PYTHON_IMAGE }}
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    APP_NAME={{ workload.name }}
+WORKDIR /srv
+RUN useradd --system --uid 10001 --no-create-home app
+COPY app ./app
+USER 10001
+{% if workload.port %}
+ENV PORT={{ workload.port }}
+EXPOSE {{ workload.port }}
+{% endif %}
+CMD ["python", "-m", "app.main"]

plinth/blueprints/workload/common/dot-dockerignore

@@ -0,0 +1,4 @@
+tests/
+__pycache__/
+*.pyc
+score.yaml

plinth/blueprints/workload/common/score.yaml.j2

@@ -0,0 +1,33 @@
+apiVersion: score.dev/v1b1
+metadata:
+  name: {{ workload.name }}
+containers:
+  main:
+    image: .
+    variables:
+      APP_NAME: {{ workload.name }}
+{% if workload.port %}
+      PORT: "{{ workload.port }}"
+{% endif %}
+    resources:
+      requests:
+        cpu: "{{ defaults.RESOURCES.requests.cpu }}"
+        memory: "{{ defaults.RESOURCES.requests.memory }}"
+      limits:
+        cpu: "{{ defaults.RESOURCES.limits.cpu }}"
+        memory: "{{ defaults.RESOURCES.limits.memory }}"
+{% if workload.port %}
+    livenessProbe:
+      httpGet:
+        path: {{ defaults.HEALTH_PATH }}
+        port: {{ workload.port }}
+    readinessProbe:
+      httpGet:
+        path: {{ defaults.HEALTH_PATH }}
+        port: {{ workload.port }}
+service:
+  ports:
+    http:
+      port: {{ defaults.SERVICE_PORT }}
+      targetPort: {{ workload.port }}
+{% endif %}

plinth/blueprints/workload/modular-monolith/app/main.py.j2

@@ -0,0 +1,63 @@
+"""HTTP entry point for {{ workload.name }}, a modular monolith.
+
+Feature code lives in app/modules/. Each module exposes ROUTES; this file only
+wires them into one process. Standard library only; swap in a framework when you need one.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import signal
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from app.modules import ROUTES
+
+APP_NAME = os.environ.get("APP_NAME", "{{ workload.name }}")
+HEALTH_PATH = "{{ defaults.HEALTH_PATH }}"
+
+log = logging.getLogger(APP_NAME)
+
+
+def handle(path: str) -> tuple[int, dict]:
+    if path == HEALTH_PATH:
+        return 200, {"status": "ok"}
+    if path == "/":
+        return 200, {"service": APP_NAME, "modules": sorted({p.split("/")[1] for p in ROUTES})}
+    route = ROUTES.get(path)
+    if route is not None:
+        return route()
+    return 404, {"error": "not found"}
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:
+        status, body = handle(self.path.split("?", 1)[0])
+        payload = json.dumps(body).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, format: str, *args) -> None:
+        log.info("%s %s", self.address_string(), format % args)
+
+
+def make_server(port: int) -> ThreadingHTTPServer:
+    return ThreadingHTTPServer(("0.0.0.0", port), Handler)
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+    server = make_server(int(os.environ.get("PORT", "{{ workload.port }}")))
+    signal.signal(signal.SIGTERM, lambda *_: threading.Thread(target=server.shutdown).start())
+    log.info("listening on port %s", server.server_address[1])
+    server.serve_forever()
+    server.server_close()
+
+
+if __name__ == "__main__":
+    main()

plinth/blueprints/workload/modular-monolith/app/modules/__init__.py

@@ -0,0 +1,5 @@
+"""Internal modules. Import each module here and merge its ROUTES."""
+
+from app.modules import example
+
+ROUTES = {**example.ROUTES}

plinth/blueprints/workload/modular-monolith/app/modules/example.py

@@ -0,0 +1,12 @@
+"""An example module. Copy this file to start a new one, then register it in __init__.py.
+
+Modules talk to each other only through functions they choose to expose, which keeps
+the boundaries clean enough to split a module into its own service later.
+"""
+
+
+def hello() -> tuple[int, dict]:
+    return 200, {"module": "example", "message": "hello"}
+
+
+ROUTES = {"/example/hello": hello}

plinth/blueprints/workload/modular-monolith/tests/test_main.py.j2

@@ -0,0 +1,42 @@
+import json
+import threading
+import unittest
+import urllib.request
+
+from app.main import HEALTH_PATH, handle, make_server
+from app.modules import ROUTES
+
+
+class HandleTests(unittest.TestCase):
+    def test_health_is_ok(self):
+        self.assertEqual(handle(HEALTH_PATH), (200, {"status": "ok"}))
+
+    def test_every_module_route_answers(self):
+        for path in ROUTES:
+            with self.subTest(path=path):
+                status, _ = handle(path)
+                self.assertEqual(status, 200)
+
+    def test_unknown_path_is_not_found(self):
+        status, _ = handle("/no-such-path")
+        self.assertEqual(status, 404)
+
+
+class ServerTests(unittest.TestCase):
+    def setUp(self):
+        self.server = make_server(0)
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+        self.base = f"http://127.0.0.1:{self.server.server_address[1]}"
+
+    def tearDown(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+    def test_health_over_http(self):
+        with urllib.request.urlopen(self.base + HEALTH_PATH) as response:
+            self.assertEqual(response.status, 200)
+            self.assertEqual(json.load(response), {"status": "ok"})
+
+
+if __name__ == "__main__":
+    unittest.main()

plinth/blueprints/workload/service/app/main.py.j2

@@ -0,0 +1,54 @@
+"""HTTP entry point for {{ workload.name }}. Standard library only; swap in a framework when you need one."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import signal
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+APP_NAME = os.environ.get("APP_NAME", "{{ workload.name }}")
+HEALTH_PATH = "{{ defaults.HEALTH_PATH }}"
+
+log = logging.getLogger(APP_NAME)
+
+
+def handle(path: str) -> tuple[int, dict]:
+    if path == HEALTH_PATH:
+        return 200, {"status": "ok"}
+    if path == "/":
+        return 200, {"service": APP_NAME}
+    return 404, {"error": "not found"}
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:
+        status, body = handle(self.path.split("?", 1)[0])
+        payload = json.dumps(body).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, format: str, *args) -> None:
+        log.info("%s %s", self.address_string(), format % args)
+
+
+def make_server(port: int) -> ThreadingHTTPServer:
+    return ThreadingHTTPServer(("0.0.0.0", port), Handler)
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+    server = make_server(int(os.environ.get("PORT", "{{ workload.port }}")))
+    signal.signal(signal.SIGTERM, lambda *_: threading.Thread(target=server.shutdown).start())
+    log.info("listening on port %s", server.server_address[1])
+    server.serve_forever()
+    server.server_close()
+
+
+if __name__ == "__main__":
+    main()

plinth/blueprints/workload/service/tests/test_main.py.j2

@@ -0,0 +1,41 @@
+import json
+import threading
+import unittest
+import urllib.error
+import urllib.request
+
+from app.main import HEALTH_PATH, handle, make_server
+
+
+class HandleTests(unittest.TestCase):
+    def test_health_is_ok(self):
+        self.assertEqual(handle(HEALTH_PATH), (200, {"status": "ok"}))
+
+    def test_unknown_path_is_not_found(self):
+        status, _ = handle("/no-such-path")
+        self.assertEqual(status, 404)
+
+
+class ServerTests(unittest.TestCase):
+    def setUp(self):
+        self.server = make_server(0)
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+        self.base = f"http://127.0.0.1:{self.server.server_address[1]}"
+
+    def tearDown(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+    def test_health_over_http(self):
+        with urllib.request.urlopen(self.base + HEALTH_PATH) as response:
+            self.assertEqual(response.status, 200)
+            self.assertEqual(json.load(response), {"status": "ok"})
+
+    def test_not_found_over_http(self):
+        with self.assertRaises(urllib.error.HTTPError) as ctx:
+            urllib.request.urlopen(self.base + "/no-such-path")
+        self.assertEqual(ctx.exception.code, 404)
+
+
+if __name__ == "__main__":
+    unittest.main()

plinth/blueprints/workload/worker/app/main.py.j2

@@ -0,0 +1,44 @@
+"""Entry point for {{ workload.name }}, a background worker. Replace run_once with the real job."""
+
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import threading
+
+APP_NAME = os.environ.get("APP_NAME", "{{ workload.name }}")
+INTERVAL_SECONDS = float(os.environ.get("INTERVAL_SECONDS", "{{ defaults.WORKER_INTERVAL_SECONDS }}"))
+
+log = logging.getLogger(APP_NAME)
+
+
+def run_once() -> str:
+    """Do one unit of work."""
+    message = f"{APP_NAME}: tick"
+    log.info(message)
+    return message
+
+
+def run(stop: threading.Event, interval: float) -> int:
+    """Call run_once every `interval` seconds until `stop` is set. Returns the number of runs."""
+    runs = 0
+    while not stop.is_set():
+        run_once()
+        runs += 1
+        stop.wait(interval)
+    return runs
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+    stop = threading.Event()
+    signal.signal(signal.SIGTERM, lambda *_: stop.set())
+    signal.signal(signal.SIGINT, lambda *_: stop.set())
+    log.info("started, interval %ss", INTERVAL_SECONDS)
+    run(stop, INTERVAL_SECONDS)
+    log.info("stopped")
+
+
+if __name__ == "__main__":
+    main()

plinth/blueprints/workload/worker/tests/test_main.py.j2

@@ -0,0 +1,26 @@
+import threading
+import unittest
+
+from app.main import run, run_once
+
+
+class WorkerTests(unittest.TestCase):
+    def test_run_once_does_work(self):
+        self.assertTrue(run_once())
+
+    def test_run_stops_when_asked(self):
+        stop = threading.Event()
+        timer = threading.Timer(0.05, stop.set)
+        timer.start()
+        runs = run(stop, interval=0.01)
+        timer.join()
+        self.assertGreaterEqual(runs, 1)
+
+    def test_run_does_nothing_when_already_stopped(self):
+        stop = threading.Event()
+        stop.set()
+        self.assertEqual(run(stop, interval=0.01), 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

plinth/cli.py

@@ -0,0 +1,185 @@
+"""Command line entry point: `plinth ...` or `python -m plinth ...`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import questionary
+import yaml
+
+from plinth import config as defaults
+from plinth.add import add_application
+from plinth.loader import ConfigError, dump_config, load_config, parse_config
+from plinth.plan import Plan, build_plan
+from plinth.render import GENERATOR_VERSION, FileMap, render_plan
+from plinth.schema import AppKind
+from plinth.wizard import run_wizard
+from plinth.write import OutputExistsError, write_project
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="plinth")
+    parser.add_argument("--version", action="version", version=f"plinth {GENERATOR_VERSION}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    project = sub.add_parser("project", help="interactive setup: answer questions, then generate")
+    project.add_argument(
+        "--output",
+        type=Path,
+        default=Path("."),
+        help="parent folder; <output>/<project>/ is created",
+    )
+    project.add_argument("--no-git", action="store_true", help="skip git init and first commit")
+
+    validate = sub.add_parser("validate", help="validate a config without writing files")
+    validate.add_argument("--config", required=True, type=Path)
+
+    generate = sub.add_parser("generate", help="generate local repository folders from a config")
+    generate.add_argument("--config", required=True, type=Path)
+    generate.add_argument("--output", required=True, type=Path)
+    generate.add_argument("--dry-run", action="store_true", help="list files, write nothing")
+    generate.add_argument("--no-git", action="store_true", help="skip git init and first commit")
+
+    add = sub.add_parser("add", help="add a service or worker to a generated project")
+    add.add_argument("kind", choices=[AppKind.SERVICE.value, AppKind.WORKER.value])
+    add.add_argument("name")
+    add.add_argument("--port", type=int, help="HTTP port (services only)")
+    add.add_argument(
+        "--project-dir",
+        type=Path,
+        default=Path("."),
+        help=f"folder containing {defaults.CONFIG_FILENAME} (default: current)",
+    )
+    add.add_argument("--no-git", action="store_true", help="skip git init for new repositories")
+    return parser
+
+
+def _summary(plan: Plan, files: FileMap) -> list[str]:
+    lines = []
+    for repo in plan.repos:
+        count = sum(1 for k in files if k.startswith(repo.folder + "/"))
+        lines.append(f"  {repo.folder}/  ({repo.role}, {count} files)")
+    return lines
+
+
+def _generate(plan: Plan, target: Path, init_git: bool) -> int:
+    files = render_plan(plan)
+    files[defaults.CONFIG_FILENAME] = dump_config(plan.config).encode("utf-8")
+    try:
+        warnings = write_project(target, files, {r.folder: r.url for r in plan.repos}, init_git)
+    except OutputExistsError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 3
+    for warning in warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+    print(f"generated {len(files)} files under {target}")
+    return 0
+
+
+def save_answers(directory: Path, text: str) -> Path:
+    """Save wizard answers without overwriting anything already there."""
+    stem, suffix = Path(defaults.CONFIG_FILENAME).stem, Path(defaults.CONFIG_FILENAME).suffix
+    for n in range(1000):
+        path = directory / (f"{stem}{suffix}" if n == 0 else f"{stem}-{n}{suffix}")
+        try:
+            with path.open("x", encoding="utf-8") as fh:
+                fh.write(text)
+            return path
+        except FileExistsError:
+            continue
+    raise OSError(f"could not find a free file name for answers in {directory}")
+
+
+def run_project(output: Path, init_git: bool) -> int:
+    try:
+        answers = run_wizard()
+    except KeyboardInterrupt:
+        print("\naborted, nothing written", file=sys.stderr)
+        return 130
+
+    try:
+        config = parse_config(answers, source="your answers")
+    except ConfigError as exc:
+        saved = save_answers(Path.cwd(), yaml.safe_dump(answers, sort_keys=False))
+        print(f"error: {exc}", file=sys.stderr)
+        print(
+            f"answers saved to {saved}; edit it and run: "
+            f"plinth generate --config {saved.name} --output {output}",
+            file=sys.stderr,
+        )
+        return 2
+
+    plan = build_plan(config)
+    target = output / config.project.name
+    print(f"\nWill create under {target.resolve()}:")
+    print("\n".join(_summary(plan, render_plan(plan))))
+    if not questionary.confirm("Generate now?", default=True).unsafe_ask():
+        print("nothing written")
+        return 0
+    return _generate(plan, target, init_git)
+
+
+def run_add(args: argparse.Namespace) -> int:
+    try:
+        result = add_application(
+            args.project_dir, AppKind(args.kind), args.name, args.port, init_git=not args.no_git
+        )
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    for note in result.notes:
+        print(f"note: {note}")
+    for path in result.created:
+        print(f"created  {path}")
+    for folder in result.new_repos:
+        print(f"new repository: {folder}/ (create it on your git host and push)")
+    touched = sorted({p.split("/", 1)[0] for p in result.created} - set(result.new_repos))
+    if touched:
+        print(f"commit the new files in: {', '.join(touched)}")
+    if result.kept:
+        print("\nkept as-is (plinth would now generate these differently; review by hand):")
+        for path in result.kept:
+            print(f"  {path}")
+    for warning in result.warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "project":
+        return run_project(args.output, init_git=not args.no_git)
+    if args.command == "add":
+        return run_add(args)
+
+    try:
+        config = load_config(args.config)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    plan = build_plan(config)
+    if args.command == "validate":
+        folders = ", ".join(r.folder for r in plan.repos)
+        print(
+            f"ok: {config.project.name} ({config.project.architecture}, "
+            f"{config.project.layout}) -> {folders}"
+        )
+        return 0
+
+    target = args.output / config.project.name
+    if args.dry_run:
+        files = render_plan(plan)
+        for rel in sorted(files):
+            print(target / rel)
+        print(f"dry run: {len(files)} files, nothing written", file=sys.stderr)
+        if target.exists():
+            print(
+                f"error: {target} already exists; generate would refuse to write", file=sys.stderr
+            )
+            return 3
+        return 0
+    return _generate(plan, target, init_git=not args.no_git)

plinth/config.py

@@ -0,0 +1,51 @@
+"""Defaults and pinned versions used across the schema, wizard and blueprints.
+
+Change a value here and every generated file picks it up. Templates read this
+module as `defaults`.
+"""
+
+from __future__ import annotations
+
+CONFIG_FILENAME = "plinth.yaml"
+REPO_METADATA_FILENAME = ".plinth.yaml"
+
+# naming
+NAME_MIN_LEN = 2
+NAME_MAX_LEN = 30
+RESERVED_APP_NAMES = frozenset(("app", "gitops"))
+
+# applications
+DEFAULT_PORT = 8000
+SERVICE_PORT = 80
+HEALTH_PATH = "/health"
+WORKER_INTERVAL_SECONDS = 30
+RESOURCES = {
+    "requests": {"cpu": "250m", "memory": "256Mi"},
+    "limits": {"cpu": "1", "memory": "512Mi"},
+}
+
+# environments
+DEFAULT_ENVIRONMENTS = ("dev", "production")
+RELEASE_ENVIRONMENT = "dev"  # CI releases here; other environments are promoted by hand
+REPLICAS = {"dev": 1, "production": 2}
+DEFAULT_REPLICAS = 1
+
+# wizard defaults
+DEFAULT_REGISTRY = "ghcr.io/YOUR_ACCOUNT"
+DEFAULT_GIT_BASE_URL = {
+    "github": "https://github.com/YOUR_ACCOUNT",
+    "gitlab": "https://gitlab.com/YOUR_GROUP",
+    "generic": "https://git.example.com/YOUR_GROUP",
+}
+
+# user name paired with a token for HTTPS git pushes from CI
+GIT_TOKEN_USER = {"github": "x-access-token", "gitlab": "oauth2", "generic": "git"}
+
+# pinned tool versions
+PYTHON_IMAGE = "python:3.12-slim"
+GIT_IMAGE = "alpine:3.22"
+DOCKER_IMAGE = "docker:28"
+DAGGER_VERSION = "0.21.11"
+DAGGER_GITHUB_ACTION = "dagger/dagger-for-github@v8"
+CHECKOUT_ACTION = "actions/checkout@v5"
+ARGO_CD_CHART_VERSION = "10.10.5"  # ships Argo CD 3.5.6

plinth/loader.py

@@ -0,0 +1,49 @@
+"""Load, validate and serialise plinth.yaml."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from plinth.schema import ProjectConfig
+
+
+class ConfigError(Exception):
+    """Raised for any user-facing configuration problem."""
+
+
+def parse_config(data: Any, source: str = "<config>") -> ProjectConfig:
+    if not isinstance(data, dict):
+        raise ConfigError(f"{source}: top level must be a mapping")
+    try:
+        return ProjectConfig.model_validate(data)
+    except ValidationError as exc:
+        lines = []
+        for err in exc.errors():
+            loc = ".".join(str(part) for part in err["loc"]) or "<root>"
+            msg = err["msg"].removeprefix("Value error, ")
+            lines.append(f"  {loc}: {msg}")
+        raise ConfigError(f"{source}: invalid configuration\n" + "\n".join(lines)) from None
+
+
+def load_config(path: Path) -> ProjectConfig:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"cannot read {path}: {exc.strerror}") from None
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: YAML parse error: {exc}") from None
+    return parse_config(data, source=str(path))
+
+
+def config_to_dict(config: ProjectConfig) -> dict:
+    return config.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+
+def dump_config(config: ProjectConfig) -> str:
+    return yaml.safe_dump(config_to_dict(config), sort_keys=False)