project-kit-cli 0.1.0__py3-none-any.whl

project_kit/config.py

@@ -0,0 +1,139 @@
+""".project-kit/config.yml: project-level settings, versioned with the repo."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from project_kit.agents import AGENT_IDS
+from project_kit.fsutil import atomic_write_text
+
+PROJECT_DIR = ".project-kit"
+PROVIDERS = ("github", "gitlab")
+BRANCH_KEYS = ("main", "release", "develop")
+
+
+class ConfigError(ValueError):
+    """The configuration file is missing, unreadable or invalid."""
+
+
+def config_path(root: Path) -> Path:
+    return root / PROJECT_DIR / "config.yml"
+
+
+def _default_branches() -> dict[str, str]:
+    return {"main": "main", "release": "release", "develop": "develop"}
+
+
+@dataclass
+class Config:
+    project_name: str
+    provider: str = "github"
+    language: str = "en"
+    branches: dict[str, str] = field(default_factory=_default_branches)
+    # False: AI assistants must not appear as co-authors of commits and pull requests.
+    ai_coauthor: bool = True
+    # The AI agent that guides the phases (see agents.py); empty until one is chosen.
+    agent: str = ""
+
+    def validate(self) -> None:
+        problems = []
+        if not self.project_name.strip():
+            problems.append("project_name must not be empty")
+        if self.provider not in PROVIDERS:
+            problems.append(
+                f"provider must be one of {', '.join(PROVIDERS)}, got {self.provider!r}"
+            )
+        if self.agent and self.agent not in AGENT_IDS:
+            problems.append(f"agent must be one of {', '.join(AGENT_IDS)}, got {self.agent!r}")
+        if not self.language.strip():
+            problems.append("language must not be empty")
+        if set(self.branches) != set(BRANCH_KEYS):
+            problems.append(f"branches must define exactly: {', '.join(BRANCH_KEYS)}")
+        else:
+            for key, name in self.branches.items():
+                if not isinstance(name, str) or not name.strip():
+                    problems.append(f"branches.{key} must be a non-empty string")
+            names = list(self.branches.values())
+            if len(set(names)) != len(names):
+                problems.append("branches must use three different names")
+        if problems:
+            raise ConfigError("Invalid config: " + "; ".join(problems))
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "project_name": self.project_name,
+            "provider": self.provider,
+            "language": self.language,
+            "branches": dict(self.branches),
+            "ai_coauthor": self.ai_coauthor,
+        }
+        if self.agent:
+            data["agent"] = self.agent
+        return data
+
+
+_HEADER = "# project-kit configuration. Safe to edit by hand.\n"
+
+
+def parse_config(text: str) -> Config:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"config.yml is not valid YAML: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError("config.yml must contain a mapping of settings")
+
+    unknown = set(data) - {
+        "project_name",
+        "provider",
+        "language",
+        "branches",
+        "ai_coauthor",
+        "agent",
+    }
+    if unknown:
+        raise ConfigError(
+            f"Unknown setting(s) in config.yml: {', '.join(sorted(map(str, unknown)))}"
+        )
+    if "project_name" not in data:
+        raise ConfigError("config.yml is missing required setting: project_name")
+
+    raw_branches = data.get("branches") or {}
+    if not isinstance(raw_branches, dict):
+        raise ConfigError("branches must be a mapping (main, release, develop)")
+    branches = {**_default_branches(), **raw_branches}
+    for key in ("project_name", "provider", "language", "agent"):
+        if key in data and not isinstance(data[key], str):
+            raise ConfigError(f"{key} must be a string")
+
+    ai_coauthor = data.get("ai_coauthor", True)
+    if not isinstance(ai_coauthor, bool):
+        raise ConfigError("ai_coauthor must be true or false")
+
+    config = Config(
+        project_name=data["project_name"],
+        provider=data.get("provider", "github"),
+        language=data.get("language", "en"),
+        branches=branches,
+        ai_coauthor=ai_coauthor,
+        agent=data.get("agent", ""),
+    )
+    config.validate()
+    return config
+
+
+def load_config(root: Path) -> Config:
+    path = config_path(root)
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise ConfigError(f"No config found at {path}. Run `project-kit init` first.") from exc
+    return parse_config(text)
+
+
+def save_config(root: Path, config: Config) -> None:
+    config.validate()
+    body = yaml.safe_dump(config.to_dict(), sort_keys=False, allow_unicode=True)
+    atomic_write_text(config_path(root), _HEADER + body)

project_kit/doctor.py

@@ -0,0 +1,187 @@
+"""``project-kit doctor``: check that the tools project-kit relies on are available."""
+
+import re
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from project_kit.gh import Gh, GhAuthError, GhError, GhNotFoundError
+
+REQUIRED_GH_SCOPES = ("repo", "project")
+
+
+class Status(Enum):
+    OK = "ok"
+    WARN = "warn"  # something optional is missing; project-kit still works
+    FAIL = "fail"  # a hard requirement is missing; project-kit cannot do its job
+
+
+@dataclass(frozen=True)
+class Check:
+    name: str
+    status: Status
+    detail: str
+    hint: str = ""
+
+
+Which = Callable[[str], str | None]
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+
+
+def _version(exe: str, runner: Runner) -> str:
+    """First line of ``<exe> --version``, or an empty string if it cannot be read."""
+    try:
+        proc = runner([exe, "--version"], capture_output=True, text=True, encoding="utf-8")
+    except OSError:
+        return ""
+    return (proc.stdout or "").strip().splitlines()[0] if proc.returncode == 0 else ""
+
+
+def check_git(which: Which, runner: Runner) -> Check:
+    if not which("git"):
+        return Check(
+            "git",
+            Status.FAIL,
+            "not found",
+            "Install Git from https://git-scm.com/downloads and make sure it is on PATH.",
+        )
+    return Check("git", Status.OK, _version("git", runner) or "found")
+
+
+def parse_scopes(auth_status: str) -> list[str] | None:
+    """Scopes listed by ``gh auth status``; ``None`` if the output does not list any."""
+    match = re.search(r"token scopes:\s*(.+)", auth_status, re.IGNORECASE)
+    if not match:
+        return None
+    return re.findall(r"[\w:.-]+", match.group(1))
+
+
+def check_gh(gh: Gh) -> list[Check]:
+    """One check for the CLI itself and, if usable, one for the session and its scopes."""
+    try:
+        version = gh.run("--version").strip().splitlines()[0]
+    except GhNotFoundError:
+        return [
+            Check(
+                "gh",
+                Status.FAIL,
+                "not found",
+                "Install the GitHub CLI from https://cli.github.com/ and make sure it is on PATH.",
+            )
+        ]
+    except GhError as exc:
+        return [Check("gh", Status.FAIL, str(exc))]
+
+    checks = [Check("gh", Status.OK, version)]
+    try:
+        scopes = parse_scopes(gh.run("auth", "status"))
+    except GhAuthError:
+        checks.append(
+            Check(
+                "gh auth",
+                Status.FAIL,
+                "not logged in",
+                "Run `gh auth login` and grant the scopes: " + ", ".join(REQUIRED_GH_SCOPES),
+            )
+        )
+        return checks
+    except GhError as exc:
+        checks.append(Check("gh auth", Status.FAIL, str(exc)))
+        return checks
+
+    if scopes is None:
+        # Fine-grained tokens and GH_TOKEN do not list scopes, so this cannot be verified.
+        checks.append(
+            Check(
+                "gh auth",
+                Status.WARN,
+                "logged in, but token scopes cannot be verified",
+                f"Make sure the token allows: {', '.join(REQUIRED_GH_SCOPES)}.",
+            )
+        )
+        return checks
+
+    missing = [s for s in REQUIRED_GH_SCOPES if s not in scopes]
+    if missing:
+        checks.append(
+            Check(
+                "gh auth",
+                Status.FAIL,
+                f"missing scopes: {', '.join(missing)}",
+                f"Run `gh auth refresh -s {','.join(missing)}`.",
+            )
+        )
+    else:
+        checks.append(Check("gh auth", Status.OK, f"scopes: {', '.join(scopes)}"))
+    return checks
+
+
+def check_uv(which: Which, runner: Runner) -> Check:
+    if not which("uv"):
+        return Check(
+            "uv",
+            Status.WARN,
+            "not found",
+            "Needed to install Spec Kit. See https://docs.astral.sh/uv/ .",
+        )
+    return Check("uv", Status.OK, _version("uv", runner) or "found")
+
+
+def check_speckit(which: Which, runner: Runner, cwd: Path) -> Check:
+    initialised = (cwd / ".specify").is_dir()
+    if which("specify"):
+        version = _version("specify", runner)
+        detail = version or "specify found"
+        return Check(
+            "spec-kit", Status.OK, detail + ("" if initialised else " (not initialised here)")
+        )
+    if initialised:
+        return Check("spec-kit", Status.OK, ".specify/ found (specify CLI not on PATH)")
+    return Check(
+        "spec-kit",
+        Status.WARN,
+        "not installed",
+        "Optional until the handoff phase; project-kit can install it for you.",
+    )
+
+
+def run_checks(
+    *,
+    gh: Gh | None = None,
+    which: Which = shutil.which,
+    runner: Runner = subprocess.run,
+    cwd: Path | None = None,
+) -> list[Check]:
+    return [
+        check_git(which, runner),
+        *check_gh(gh or Gh()),
+        check_uv(which, runner),
+        check_speckit(which, runner, cwd or Path.cwd()),
+    ]
+
+
+_MARK = {Status.OK: "ok  ", Status.WARN: "warn", Status.FAIL: "FAIL"}
+
+
+def render(checks: list[Check]) -> str:
+    lines = []
+    for c in checks:
+        lines.append(f"[{_MARK[c.status]}] {c.name}: {c.detail}")
+        if c.hint and c.status is not Status.OK:
+            lines.append(f"       -> {c.hint}")
+    failed = sum(c.status is Status.FAIL for c in checks)
+    warned = sum(c.status is Status.WARN for c in checks)
+    if failed:
+        lines.append(f"\n{failed} blocking problem(s). Fix them before using project-kit.")
+    elif warned:
+        lines.append(f"\nReady, with {warned} warning(s).")
+    else:
+        lines.append("\nAll good.")
+    return "\n".join(lines)
+
+
+def exit_code(checks: list[Check]) -> int:
+    return 1 if any(c.status is Status.FAIL for c in checks) else 0

project_kit/fsutil.py

@@ -0,0 +1,27 @@
+"""File helpers."""
+
+import contextlib
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` so readers see either the old or the new content, never a
+    half-written file, even if the process is killed mid-write.
+
+    The data goes to a temporary file in the same directory (so the final rename stays on
+    one filesystem), is flushed to disk, and then replaces the target in a single step.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as tmp:
+            tmp.write(text)
+            tmp.flush()
+            os.fsync(tmp.fileno())
+        os.replace(tmp_name, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_name)
+        raise

project_kit/gh.py

@@ -0,0 +1,152 @@
+"""Thin wrapper around the GitHub CLI (``gh``), run as a subprocess (design decision D7).
+
+``gh`` inherits the user's authentication and scopes. Transient failures (HTTP 5xx, flaky
+GraphQL responses, network hiccups) are retried with exponential backoff; anything else
+is raised immediately with a clear message.
+"""
+
+import json
+import re
+import subprocess
+import time
+from collections.abc import Callable, Sequence
+from typing import Any
+
+# Matched case-insensitively against stderr. Kept narrow on purpose: retrying a real
+# error (bad arguments, missing permissions) would only hide it behind a delay.
+_TRANSIENT = re.compile(
+    r"\b(50[0-4])\b"
+    r"|bad gateway|service unavailable|gateway time-?out"
+    r"|something went wrong while executing your query"
+    r"|timeout|timed out|connection reset|unexpected eof|\beof\b"
+    r"|temporary failure|try again later|secondary rate limit",
+    re.IGNORECASE,
+)
+# A *primary* limit or a burst limit: retrying within seconds does not help, so it is reported
+# instead (the "secondary rate limit" wording is still retried, see _TRANSIENT).
+_RATE_LIMITED = re.compile(r"rate limit exceeded|api rate limit", re.IGNORECASE)
+_NOT_AUTHENTICATED = re.compile(
+    r"gh auth login|not logged in|authentication required|bad credentials|http 401",
+    re.IGNORECASE,
+)
+
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+
+
+class GhError(Exception):
+    """A ``gh`` invocation failed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        args_: Sequence[str] = (),
+        returncode: int | None = None,
+        stderr: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.gh_args = list(args_)
+        self.returncode = returncode
+        self.stderr = stderr
+
+
+class GhNotFoundError(GhError):
+    """The ``gh`` executable is not installed or not on PATH."""
+
+
+class GhAuthError(GhError):
+    """``gh`` is installed but there is no valid session."""
+
+
+class GhRateLimitError(GhError):
+    """GitHub's API rate limit was reached."""
+
+
+def _decode(data: bytes | str | None) -> str:
+    """Output as text with LF line endings, whatever the platform or how GitHub stored it
+    (bodies typed in the web editor come back with CRLF)."""
+    if data is None:
+        return ""
+    text = data.decode("utf-8", errors="replace") if isinstance(data, bytes) else data
+    return text.replace("\r\n", "\n")
+
+
+class Gh:
+    """Runs ``gh`` commands. ``runner`` and ``sleep`` are injectable for tests."""
+
+    def __init__(
+        self,
+        *,
+        executable: str = "gh",
+        retries: int = 3,
+        backoff: float = 1.0,
+        runner: Runner = subprocess.run,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.executable = executable
+        self.retries = retries
+        self.backoff = backoff
+        self._runner = runner
+        self._sleep = sleep
+
+    def run(self, *args: str, input: str | None = None) -> str:
+        """Run ``gh <args>`` and return stdout. Retries transient failures."""
+        cmd = [self.executable, *args]
+        attempt = 0
+        while True:
+            try:
+                proc = self._runner(
+                    cmd,
+                    # Bytes, not text: in text mode Windows turns every LF we send into
+                    # CRLF, which would end up in issue bodies.
+                    input=None if input is None else input.encode("utf-8"),
+                    capture_output=True,
+                )
+            except FileNotFoundError as exc:
+                raise GhNotFoundError(
+                    "GitHub CLI (gh) not found. Install it from https://cli.github.com/ "
+                    "and make sure it is on your PATH.",
+                    args_=args,
+                ) from exc
+
+            if proc.returncode == 0:
+                return _decode(proc.stdout)
+
+            stderr = _decode(proc.stderr).strip()
+            if _RATE_LIMITED.search(stderr) and not _TRANSIENT.search(stderr):
+                raise GhRateLimitError(
+                    "GitHub's API rate limit was reached. Wait a minute (longer if it "
+                    "happens again) and run the command again; progress so far is saved.",
+                    args_=args,
+                    returncode=proc.returncode,
+                    stderr=stderr,
+                )
+            if _NOT_AUTHENTICATED.search(stderr):
+                raise GhAuthError(
+                    "gh is not authenticated. Run `gh auth login` (scopes needed: repo, project).",
+                    args_=args,
+                    returncode=proc.returncode,
+                    stderr=stderr,
+                )
+            if attempt < self.retries and _TRANSIENT.search(stderr):
+                self._sleep(self.backoff * 2**attempt)
+                attempt += 1
+                continue
+
+            shown = " ".join(args)
+            raise GhError(
+                f"`gh {shown}` failed (exit {proc.returncode}): {stderr or 'no error output'}",
+                args_=args,
+                returncode=proc.returncode,
+                stderr=stderr,
+            )
+
+    def json(self, *args: str, input: str | None = None) -> Any:
+        """Run ``gh <args>`` and parse stdout as JSON."""
+        out = self.run(*args, input=input)
+        try:
+            return json.loads(out)
+        except json.JSONDecodeError as exc:
+            raise GhError(
+                f"`gh {' '.join(args)}` did not return valid JSON: {exc}", args_=args
+            ) from exc