plinth-cli 0.2.0__py3-none-any.whl

plinth/plan.py

@@ -0,0 +1,70 @@
+"""Turn a validated config into a deterministic generation plan."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from plinth.schema import AppKind, Layout, ProjectConfig
+
+RepoRole = Literal["app", "gitops"]
+
+
+@dataclass(frozen=True)
+class WorkloadPlan:
+    name: str
+    kind: AppKind
+    port: int | None  # None for workers
+    source_dir: str  # "" at repo root, or "apps/<name>/" in a monorepo
+
+    @property
+    def score_path(self) -> str:
+        return f"{self.source_dir}score.yaml"
+
+
+@dataclass(frozen=True)
+class RepoPlan:
+    folder: str
+    role: RepoRole
+    url: str
+    workloads: tuple[WorkloadPlan, ...]
+
+
+@dataclass(frozen=True)
+class Plan:
+    config: ProjectConfig
+    repos: tuple[RepoPlan, ...]
+
+    @property
+    def gitops(self) -> RepoPlan:
+        return next(r for r in self.repos if r.role == "gitops")
+
+    @property
+    def app_repos(self) -> tuple[RepoPlan, ...]:
+        return tuple(r for r in self.repos if r.role == "app")
+
+    def workloads(self) -> list[tuple[RepoPlan, WorkloadPlan]]:
+        return [(r, w) for r in self.app_repos for w in r.workloads]
+
+
+def build_plan(config: ProjectConfig) -> Plan:
+    project = config.project
+    base = project.git_base_url
+
+    def repo(folder: str, role: RepoRole, workloads: tuple[WorkloadPlan, ...]) -> RepoPlan:
+        return RepoPlan(folder, role, f"{base}/{folder}.git", workloads)
+
+    repos: list[RepoPlan] = []
+    if project.layout is Layout.MONOREPO:
+        workloads = tuple(
+            WorkloadPlan(a.name, a.kind, a.http_port, f"apps/{a.name}/")
+            for a in config.applications
+        )
+        repos.append(repo(f"{project.name}-app", "app", workloads))
+    else:
+        for a in config.applications:
+            workload = WorkloadPlan(a.name, a.kind, a.http_port, "")
+            repos.append(repo(f"{project.name}-{a.name}", "app", (workload,)))
+
+    repos.append(repo(f"{project.name}-gitops", "gitops", ()))
+    return Plan(config=config, repos=tuple(repos))

plinth/render.py

@@ -0,0 +1,119 @@
+"""Render blueprints into an in-memory file map."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as dist_version
+from pathlib import Path
+
+import yaml
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+from plinth import config as defaults
+from plinth.plan import Plan, RepoPlan
+
+BLUEPRINTS_DIR = Path(__file__).resolve().parent / "blueprints"
+TEMPLATE_SUFFIX = ".j2"
+DOT_PREFIX = "dot-"  # blueprint "dot-gitignore" renders as ".gitignore"
+EXECUTABLE_SUFFIXES = (".sh",)
+
+try:
+    GENERATOR_VERSION = dist_version("plinth-cli")
+except PackageNotFoundError:  # running from a bare checkout without install
+    GENERATOR_VERSION = "0.0.0+uninstalled"
+
+FileMap = dict[str, bytes]
+
+
+def make_env(blueprints_root: Path) -> Environment:
+    return Environment(
+        loader=FileSystemLoader(str(blueprints_root)),
+        undefined=StrictUndefined,
+        autoescape=False,
+        keep_trailing_newline=True,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+
+def _output_path(rel: str) -> str:
+    parts = ["." + p[len(DOT_PREFIX) :] if p.startswith(DOT_PREFIX) else p for p in rel.split("/")]
+    out = "/".join(parts)
+    return out.removesuffix(TEMPLATE_SUFFIX)
+
+
+def render_tree(
+    env: Environment, blueprints_root: Path, blueprint: str, context: dict, prefix: str
+) -> FileMap:
+    base = blueprints_root / blueprint
+    if not base.is_dir():
+        return {}
+    out: FileMap = {}
+    for src in sorted(p for p in base.rglob("*") if p.is_file() and "__pycache__" not in p.parts):
+        rel = src.relative_to(base).as_posix()
+        if rel.endswith(TEMPLATE_SUFFIX):
+            content = env.get_template(f"{blueprint}/{rel}").render(**context).encode("utf-8")
+        else:
+            content = src.read_bytes()
+        out[prefix + _output_path(rel)] = content
+    return out
+
+
+def _render_one(env: Environment, template: str, context: dict) -> bytes:
+    return env.get_template(template).render(**context).encode("utf-8")
+
+
+def _metadata(repo: RepoPlan, plan: Plan) -> bytes:
+    data = {
+        "generator": {"name": "plinth", "version": GENERATOR_VERSION},
+        "project": plan.config.project.name,
+        "repo": {"folder": repo.folder, "role": repo.role},
+    }
+    return yaml.safe_dump(data, sort_keys=True).encode("utf-8")
+
+
+def render_plan(plan: Plan, blueprints_root: Path = BLUEPRINTS_DIR) -> FileMap:
+    env = make_env(blueprints_root)
+    project = plan.config.project
+    base_ctx = {
+        "config": plan.config,
+        "project": project,
+        "plan": plan,
+        "defaults": defaults,
+        "git_token_user": defaults.GIT_TOKEN_USER[project.git_provider.value],
+    }
+    files: FileMap = {}
+
+    for repo in plan.repos:
+        ctx = {**base_ctx, "repo": repo}
+        root = f"{repo.folder}/"
+        files.update(render_tree(env, blueprints_root, f"repo/{repo.role}", ctx, root))
+        files[root + defaults.REPO_METADATA_FILENAME] = _metadata(repo, plan)
+
+        if repo.role == "app":
+            files.update(
+                render_tree(env, blueprints_root, f"ci/{project.git_provider.value}", ctx, root)
+            )
+            for wl in repo.workloads:
+                wctx = {**ctx, "workload": wl}
+                for blueprint in ("workload/common", f"workload/{wl.kind.value}"):
+                    files.update(
+                        render_tree(env, blueprints_root, blueprint, wctx, root + wl.source_dir)
+                    )
+        else:
+            for environment in plan.config.environments:
+                ectx = {**ctx, "environment": environment}
+                files[f"{root}apps/{environment}.yaml"] = _render_one(
+                    env, "gitops/applicationset.yaml.j2", ectx
+                )
+                for app_repo, wl in plan.workloads():
+                    wctx = {**ectx, "workload": wl, "app_repo": app_repo}
+                    files[f"{root}environments/{environment}/{wl.name}/values.yaml"] = _render_one(
+                        env, "gitops/values.yaml.j2", wctx
+                    )
+
+    return files
+
+
+def is_executable(rel: str) -> bool:
+    return rel.endswith(EXECUTABLE_SUFFIXES)

plinth/schema.py

@@ -0,0 +1,158 @@
+"""Project configuration schema (plinth.yaml)."""
+
+from __future__ import annotations
+
+import re
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from plinth import config as defaults
+
+NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$")
+GIT_BASE_URL_RE = re.compile(r"^https://[^\s/]+(?:/[^\s/]+)+$")
+
+
+def validate_name(value: str, what: str) -> str:
+    if not NAME_RE.fullmatch(value):
+        raise ValueError(
+            f"{what} '{value}' must be lowercase kebab-case "
+            "(start with a letter; only a-z, 0-9, and single hyphens)"
+        )
+    if not defaults.NAME_MIN_LEN <= len(value) <= defaults.NAME_MAX_LEN:
+        raise ValueError(
+            f"{what} '{value}' must be {defaults.NAME_MIN_LEN}-{defaults.NAME_MAX_LEN} characters"
+        )
+    return value
+
+
+class Architecture(StrEnum):
+    MODULAR_MONOLITH = "modular-monolith"
+    MICROSERVICES = "microservices"
+    HYBRID = "hybrid"
+
+
+class Layout(StrEnum):
+    MONOREPO = "monorepo"
+    SPLIT_REPO = "split-repo"
+
+
+class GitProvider(StrEnum):
+    GITHUB = "github"
+    GITLAB = "gitlab"
+    GENERIC = "generic"
+
+
+class AppKind(StrEnum):
+    MODULAR_MONOLITH = "modular-monolith"
+    SERVICE = "service"
+    WORKER = "worker"
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, populate_by_name=True)
+
+
+class ProjectSpec(StrictModel):
+    name: str
+    architecture: Architecture
+    layout: Layout
+    git_provider: GitProvider = Field(alias="gitProvider")
+    git_base_url: str = Field(alias="gitBaseUrl")
+    registry: str
+
+    @field_validator("name")
+    @classmethod
+    def _name(cls, v: str) -> str:
+        return validate_name(v, "project.name")
+
+    @field_validator("registry")
+    @classmethod
+    def _registry(cls, v: str) -> str:
+        if "://" in v or v.endswith("/") or not v:
+            raise ValueError("registry must be host[/path] without scheme or trailing slash")
+        return v
+
+    @field_validator("git_base_url")
+    @classmethod
+    def _git_base_url(cls, v: str) -> str:
+        if not GIT_BASE_URL_RE.fullmatch(v):
+            raise ValueError(
+                "gitBaseUrl must look like https://host/org (no trailing slash), "
+                "e.g. https://github.com/acme"
+            )
+        return v
+
+
+class ApplicationSpec(StrictModel):
+    name: str
+    kind: AppKind
+    port: int | None = Field(default=None, ge=1, le=65535)
+
+    @field_validator("name")
+    @classmethod
+    def _name(cls, v: str) -> str:
+        validate_name(v, "application name")
+        if v in defaults.RESERVED_APP_NAMES:
+            raise ValueError(f"application name '{v}' is reserved")
+        return v
+
+    @model_validator(mode="after")
+    def _worker_has_no_port(self) -> ApplicationSpec:
+        if self.kind is AppKind.WORKER and self.port is not None:
+            raise ValueError(f"application '{self.name}': workers have no HTTP port")
+        return self
+
+    @property
+    def http_port(self) -> int | None:
+        if self.kind is AppKind.WORKER:
+            return None
+        return self.port if self.port is not None else defaults.DEFAULT_PORT
+
+
+class ProjectConfig(StrictModel):
+    project: ProjectSpec
+    applications: list[ApplicationSpec] = Field(min_length=1)
+    environments: list[str] = Field(default_factory=lambda: list(defaults.DEFAULT_ENVIRONMENTS))
+
+    @field_validator("environments")
+    @classmethod
+    def _envs(cls, v: list[str]) -> list[str]:
+        if not v:
+            raise ValueError("at least one environment is required")
+        for e in v:
+            validate_name(e, "environment")
+        if len(set(v)) != len(v):
+            raise ValueError("environment names must be unique")
+        if defaults.RELEASE_ENVIRONMENT not in v:
+            raise ValueError(
+                f"an environment named '{defaults.RELEASE_ENVIRONMENT}' is required (CI releases to it)"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def _architecture_rules(self) -> ProjectConfig:
+        names = [a.name for a in self.applications]
+        dupes = sorted({n for n in names if names.count(n) > 1})
+        if dupes:
+            raise ValueError(f"duplicate application names: {dupes}")
+
+        monoliths = [a for a in self.applications if a.kind is AppKind.MODULAR_MONOLITH]
+        others = [a for a in self.applications if a.kind is not AppKind.MODULAR_MONOLITH]
+        arch = self.project.architecture
+
+        if arch is Architecture.MODULAR_MONOLITH and (len(monoliths) != 1 or others):
+            raise ValueError(
+                "architecture 'modular-monolith' requires exactly one application "
+                "of kind 'modular-monolith' and no others"
+            )
+        if arch is Architecture.MICROSERVICES and monoliths:
+            raise ValueError(
+                "architecture 'microservices' must not contain kind 'modular-monolith'"
+            )
+        if arch is Architecture.HYBRID and (len(monoliths) != 1 or not others):
+            raise ValueError(
+                "architecture 'hybrid' requires exactly one 'modular-monolith' "
+                "plus at least one 'service' or 'worker'"
+            )
+        return self

plinth/wizard.py

@@ -0,0 +1,129 @@
+"""Interactive questions for `plinth project`. Produces a config dict only."""
+
+from __future__ import annotations
+
+import questionary
+from questionary import Choice
+
+from plinth import config as defaults
+from plinth.schema import NAME_RE, AppKind, Architecture, GitProvider, Layout
+
+
+def _name_ok(value: str) -> bool | str:
+    if NAME_RE.fullmatch(value) and defaults.NAME_MIN_LEN <= len(value) <= defaults.NAME_MAX_LEN:
+        return True
+    return (
+        f"lowercase kebab-case, {defaults.NAME_MIN_LEN}-{defaults.NAME_MAX_LEN} chars, e.g. atlas"
+    )
+
+
+def _port_ok(value: str) -> bool | str:
+    return True if value.isdigit() and 0 < int(value) < 65536 else "port must be 1-65535"
+
+
+def _ask_port(question: str) -> int:
+    answer = questionary.text(question, default=str(defaults.DEFAULT_PORT), validate=_port_ok)
+    return int(answer.unsafe_ask())
+
+
+def _ask_applications(architecture: str) -> list[dict]:
+    apps: list[dict] = []
+    if architecture in (Architecture.MODULAR_MONOLITH, Architecture.HYBRID):
+        name = questionary.text(
+            "Monolith application name:", default="api", validate=_name_ok
+        ).unsafe_ask()
+        apps.append(
+            {
+                "name": name,
+                "kind": AppKind.MODULAR_MONOLITH.value,
+                "port": _ask_port("Monolith HTTP port:"),
+            }
+        )
+        if architecture == Architecture.MODULAR_MONOLITH:
+            return apps
+
+    while True:
+        name = questionary.text(
+            "Service or worker name (leave empty to finish):",
+            validate=lambda v: True if v == "" else _name_ok(v),
+        ).unsafe_ask()
+        if name == "":
+            if any(a["kind"] != AppKind.MODULAR_MONOLITH for a in apps):
+                return apps
+            questionary.print("At least one service or worker is required.", style="bold")
+            continue
+        kind = questionary.select(
+            f"Kind of '{name}':",
+            choices=[
+                Choice("service  (HTTP, gets a port and health check)", AppKind.SERVICE.value),
+                Choice("worker   (no HTTP port)", AppKind.WORKER.value),
+            ],
+        ).unsafe_ask()
+        app = {"name": name, "kind": kind}
+        if kind == AppKind.SERVICE:
+            app["port"] = _ask_port("Port:")
+        apps.append(app)
+
+
+def run_wizard() -> dict:
+    name = questionary.text("Project name:", validate=_name_ok).unsafe_ask()
+
+    architecture = questionary.select(
+        "Application architecture:",
+        choices=[
+            Choice(
+                "modular-monolith  (one process, one image, internal modules)",
+                Architecture.MODULAR_MONOLITH.value,
+            ),
+            Choice(
+                "microservices     (several independently built apps)",
+                Architecture.MICROSERVICES.value,
+            ),
+            Choice(
+                "hybrid            (one monolith plus independent services/workers)",
+                Architecture.HYBRID.value,
+            ),
+        ],
+    ).unsafe_ask()
+
+    layout = questionary.select(
+        "Repository layout:",
+        choices=[
+            Choice("monorepo    (all apps in <project>-app)", Layout.MONOREPO.value),
+            Choice("split-repo  (one repo per app)", Layout.SPLIT_REPO.value),
+        ],
+    ).unsafe_ask()
+
+    provider = questionary.select(
+        "Git provider (decides which CI file is generated):",
+        choices=[Choice(p.value, p.value) for p in GitProvider],
+    ).unsafe_ask()
+
+    git_base_url = questionary.text(
+        "Git base URL the repos will live under (https://host/org):",
+        default=defaults.DEFAULT_GIT_BASE_URL[provider],
+    ).unsafe_ask()
+
+    registry = questionary.text(
+        "Container registry (host/path, no scheme):", default=defaults.DEFAULT_REGISTRY
+    ).unsafe_ask()
+
+    applications = _ask_applications(architecture)
+
+    envs = questionary.text(
+        f"Environments (comma separated, must include {defaults.RELEASE_ENVIRONMENT}):",
+        default=",".join(defaults.DEFAULT_ENVIRONMENTS),
+    ).unsafe_ask()
+
+    return {
+        "project": {
+            "name": name,
+            "architecture": architecture,
+            "layout": layout,
+            "gitProvider": provider,
+            "gitBaseUrl": git_base_url,
+            "registry": registry,
+        },
+        "applications": applications,
+        "environments": [e.strip() for e in envs.split(",") if e.strip()],
+    }

plinth/write.py

@@ -0,0 +1,72 @@
+"""Write rendered files to disk and initialise git repositories."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from plinth.render import FileMap, is_executable
+
+INITIAL_COMMIT_MESSAGE = "chore: initial commit"
+
+
+class OutputExistsError(Exception):
+    pass
+
+
+def write_tree(root: Path, files: FileMap) -> None:
+    for rel in sorted(files):
+        dest = root / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(files[rel])
+        if is_executable(rel):
+            dest.chmod(0o755)
+
+
+def write_project(
+    target: Path, files: FileMap, repo_urls: dict[str, str], init_git: bool
+) -> list[str]:
+    """Write a whole project atomically: everything lands in a temp folder that is
+    renamed into place only once it is complete. Returns warnings."""
+    if target.exists():
+        raise OutputExistsError(f"refusing to write into existing path: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = Path(tempfile.mkdtemp(prefix=f".{target.name}.", suffix=".plinth-tmp", dir=target.parent))
+    try:
+        write_tree(tmp, files)
+        warnings = init_repos(tmp, repo_urls) if init_git else []
+        if target.exists():
+            raise OutputExistsError(f"refusing to write into existing path: {target}")
+        os.rename(tmp, target)
+    except BaseException:
+        shutil.rmtree(tmp, ignore_errors=True)
+        raise
+    return warnings
+
+
+def init_repos(root: Path, repo_urls: dict[str, str]) -> list[str]:
+    if shutil.which("git") is None:
+        return ["git not found; repositories were not initialised"]
+    warnings = []
+    for folder, url in repo_urls.items():
+        warning = init_repo(root / folder, url)
+        if warning:
+            warnings.append(warning)
+    return warnings
+
+
+def init_repo(path: Path, url: str) -> str | None:
+    def git(*args: str) -> subprocess.CompletedProcess:
+        return subprocess.run(["git", *args], cwd=path, capture_output=True, text=True, check=False)
+
+    for args in (("init", "-q", "-b", "main"), ("remote", "add", "origin", url), ("add", "-A")):
+        result = git(*args)
+        if result.returncode != 0:
+            return f"{path.name}: git {args[0]} failed: {result.stderr.strip()}"
+    result = git("commit", "-q", "-m", INITIAL_COMMIT_MESSAGE)
+    if result.returncode != 0:
+        return f"{path.name}: initialised but not committed: {result.stderr.strip()}"
+    return None