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

project_kit/backlog.py

@@ -0,0 +1,312 @@
+""".project-kit/backlog.json: the project backlog, source of truth for provisioning.
+
+Shape (see docs/backlog-schema.md for the full description)::
+
+    {
+      "version": 1,
+      "phases":  [{"id", "title", "description"?}],          # -> milestones / Phase field
+      "labels":  [{"name", "color"?, "description"?}],       # extra labels, optional
+      "issues":  [{"id", "type", "phase", "title", "priority", "size",
+                   "parent"?, "body"?, "acceptance"?, "labels"?}]
+    }
+
+Validation collects every problem it finds, so the user can fix them in one pass.
+"""
+
+import json
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from project_kit.config import PROJECT_DIR
+from project_kit.fsutil import atomic_write_text
+
+BACKLOG_VERSION = 1
+ISSUE_TYPES = ("epic", "feature", "adr", "chore", "bug", "docs")
+PRIORITIES = ("P0", "P1", "P2", "P3")
+SIZES = ("XS", "S", "M", "L", "XL")
+# Work that gets implemented needs a definition of done; epics and decisions do not.
+NEEDS_ACCEPTANCE = frozenset({"feature", "bug", "chore"})
+
+_ID = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_COLOR = re.compile(r"^[0-9a-fA-F]{6}$")
+_DEFAULT_COLOR = "ededed"
+
+
+class BacklogError(ValueError):
+    """The backlog is missing, unreadable or invalid. ``problems`` lists every issue found."""
+
+    def __init__(self, problems: list[str]) -> None:
+        super().__init__("Invalid backlog:\n" + "\n".join(f"  - {p}" for p in problems))
+        self.problems = problems
+
+
+def backlog_path(root: Path) -> Path:
+    return root / PROJECT_DIR / "backlog.json"
+
+
+@dataclass
+class Phase:
+    id: str
+    title: str
+    description: str = ""
+
+
+@dataclass
+class Label:
+    name: str
+    color: str = _DEFAULT_COLOR
+    description: str = ""
+
+
+@dataclass
+class Issue:
+    id: str
+    type: str
+    phase: str
+    title: str
+    priority: str
+    size: str
+    parent: str | None = None
+    body: str = ""
+    acceptance: list[str] = field(default_factory=list)
+    labels: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Backlog:
+    phases: list[Phase] = field(default_factory=list)
+    issues: list[Issue] = field(default_factory=list)
+    labels: list[Label] = field(default_factory=list)
+
+    def children_of(self, epic_id: str) -> list[Issue]:
+        return [i for i in self.issues if i.parent == epic_id]
+
+    def summary(self) -> str:
+        by_type = Counter(i.type for i in self.issues)
+        lines = [f"{len(self.phases)} phase(s), {len(self.issues)} issue(s)"]
+        for phase in self.phases:
+            items = [i for i in self.issues if i.phase == phase.id]
+            counts = ", ".join(f"{by}: {n}" for by, n in Counter(i.type for i in items).items())
+            lines.append(f"  {phase.title}: {len(items)} ({counts or 'empty'})")
+        if by_type:
+            lines.append(
+                "by priority: "
+                + ", ".join(
+                    f"{p}: {n}" for p, n in sorted(Counter(i.priority for i in self.issues).items())
+                )
+            )
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        def issue(i: Issue) -> dict[str, Any]:
+            d: dict[str, Any] = {
+                "id": i.id,
+                "type": i.type,
+                "phase": i.phase,
+                "title": i.title,
+                "priority": i.priority,
+                "size": i.size,
+            }
+            if i.parent:
+                d["parent"] = i.parent
+            if i.body:
+                d["body"] = i.body
+            if i.acceptance:
+                d["acceptance"] = list(i.acceptance)
+            if i.labels:
+                d["labels"] = list(i.labels)
+            return d
+
+        return {
+            "version": BACKLOG_VERSION,
+            "phases": [
+                {k: v for k, v in vars(p).items() if v != ""} | {"id": p.id, "title": p.title}
+                for p in self.phases
+            ],
+            "labels": [{k: v for k, v in vars(label).items() if v != ""} for label in self.labels],
+            "issues": [issue(i) for i in self.issues],
+        }
+
+
+class _Collector:
+    """Reads typed values out of untyped JSON, recording problems instead of raising."""
+
+    def __init__(self) -> None:
+        self.problems: list[str] = []
+
+    def add(self, where: str, message: str) -> None:
+        self.problems.append(f"{where}: {message}")
+
+    def obj(self, value: Any, where: str, allowed: set[str]) -> dict[str, Any] | None:
+        if not isinstance(value, dict):
+            self.add(where, "must be an object")
+            return None
+        for key in sorted(set(value) - allowed, key=str):
+            self.add(where, f"unknown field {key!r}")
+        return value
+
+    def text(self, data: dict[str, Any], key: str, where: str, *, required: bool = True) -> str:
+        if key not in data or data[key] is None:
+            if required:
+                self.add(where, f"missing required field {key!r}")
+            return ""
+        value = data[key]
+        if not isinstance(value, str):
+            self.add(where, f"{key!r} must be a string")
+            return ""
+        if required and not value.strip():
+            self.add(where, f"{key!r} must not be empty")
+        return value
+
+    def choice(self, data: dict[str, Any], key: str, where: str, options: tuple[str, ...]) -> str:
+        value = self.text(data, key, where)
+        if value and value not in options:
+            self.add(where, f"{key!r} must be one of {', '.join(options)}, got {value!r}")
+        return value
+
+    def strings(self, data: dict[str, Any], key: str, where: str) -> list[str]:
+        value = data.get(key, [])
+        if not isinstance(value, list) or not all(isinstance(v, str) and v.strip() for v in value):
+            self.add(where, f"{key!r} must be a list of non-empty strings")
+            return []
+        return list(value)
+
+
+def _ident(c: _Collector, data: dict[str, Any], where: str) -> str:
+    value = c.text(data, "id", where)
+    if value and not _ID.match(value):
+        c.add(where, f"'id' must be lowercase letters, digits and hyphens, got {value!r}")
+    return value
+
+
+def parse_backlog(text: str) -> Backlog:
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise BacklogError([f"backlog.json is not valid JSON: {exc}"]) from exc
+
+    c = _Collector()
+    root = c.obj(raw, "backlog", {"version", "phases", "labels", "issues"})
+    if root is None:
+        raise BacklogError(c.problems)
+    if root.get("version") != BACKLOG_VERSION:
+        c.add(
+            "backlog", f"unsupported version {root.get('version')!r} (expected {BACKLOG_VERSION})"
+        )
+
+    backlog = Backlog()
+
+    for n, item in enumerate(root.get("phases") or [], 1):
+        where = f"phases[{n}]"
+        if (d := c.obj(item, where, {"id", "title", "description"})) is not None:
+            backlog.phases.append(
+                Phase(
+                    _ident(c, d, where),
+                    c.text(d, "title", where),
+                    c.text(d, "description", where, required=False),
+                )
+            )
+
+    for n, item in enumerate(root.get("labels") or [], 1):
+        where = f"labels[{n}]"
+        if (d := c.obj(item, where, {"name", "color", "description"})) is not None:
+            color = c.text(d, "color", where, required=False) or _DEFAULT_COLOR
+            if not _COLOR.match(color):
+                c.add(where, f"'color' must be 6 hex digits without '#', got {color!r}")
+            backlog.labels.append(
+                Label(
+                    c.text(d, "name", where),
+                    color,
+                    c.text(d, "description", where, required=False),
+                )
+            )
+
+    allowed = {"id", "type", "phase", "title", "priority", "size", "parent", "body",
+               "acceptance", "labels"}  # fmt: skip
+    for n, item in enumerate(root.get("issues") or [], 1):
+        where = f"issues[{n}]"
+        if (d := c.obj(item, where, allowed)) is None:
+            continue
+        ident = _ident(c, d, where)
+        where = f"issue {ident!r}" if ident else where
+        parent = c.text(d, "parent", where, required=False) or None
+        backlog.issues.append(
+            Issue(
+                id=ident,
+                type=c.choice(d, "type", where, ISSUE_TYPES),
+                phase=c.text(d, "phase", where),
+                title=c.text(d, "title", where),
+                priority=c.choice(d, "priority", where, PRIORITIES),
+                size=c.choice(d, "size", where, SIZES),
+                parent=parent,
+                body=c.text(d, "body", where, required=False),
+                acceptance=c.strings(d, "acceptance", where),
+                labels=c.strings(d, "labels", where),
+            )
+        )
+
+    _check_references(backlog, c)
+    if c.problems:
+        raise BacklogError(c.problems)
+    return backlog
+
+
+def _duplicates(values: list[str]) -> list[str]:
+    return sorted(v for v, n in Counter(values).items() if v and n > 1)
+
+
+def _check_references(backlog: Backlog, c: _Collector) -> None:
+    for dup in _duplicates([p.id for p in backlog.phases]):
+        c.add("phases", f"duplicate id {dup!r}")
+    for dup in _duplicates([p.title for p in backlog.phases]):
+        c.add("phases", f"duplicate title {dup!r}")
+    for dup in _duplicates([label.name for label in backlog.labels]):
+        c.add("labels", f"duplicate name {dup!r}")
+    for dup in _duplicates([i.id for i in backlog.issues]):
+        c.add("issues", f"duplicate id {dup!r}")
+
+    phase_ids = {p.id for p in backlog.phases}
+    declared = {label.name for label in backlog.labels}
+    by_id = {i.id: i for i in backlog.issues}
+
+    for i in backlog.issues:
+        where = f"issue {i.id!r}"
+        if i.phase and i.phase not in phase_ids:
+            c.add(where, f"unknown phase {i.phase!r}")
+        if i.type in NEEDS_ACCEPTANCE and not i.acceptance:
+            c.add(where, f"a {i.type} needs at least one acceptance criterion")
+        for name in i.labels:
+            if name not in declared:
+                c.add(where, f"label {name!r} is not declared in 'labels'")
+        if i.parent is None:
+            continue
+        if i.type == "epic":
+            c.add(where, "an epic cannot have a parent")
+        parent = by_id.get(i.parent)
+        if parent is None:
+            c.add(where, f"unknown parent {i.parent!r}")
+        elif parent.type != "epic":
+            c.add(where, f"parent {i.parent!r} is a {parent.type}, not an epic")
+
+
+def validate_backlog(backlog: Backlog) -> None:
+    """Re-validate a backlog built in code (``parse_backlog`` validates on load)."""
+    parse_backlog(json.dumps(backlog.to_dict()))
+
+
+def load_backlog(root: Path) -> Backlog:
+    path = backlog_path(root)
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise BacklogError([f"No backlog found at {path}. Run the pk-plan skill first."]) from exc
+    return parse_backlog(text)
+
+
+def save_backlog(root: Path, backlog: Backlog) -> None:
+    validate_backlog(backlog)
+    text = json.dumps(backlog.to_dict(), indent=2, ensure_ascii=False) + "\n"
+    atomic_write_text(backlog_path(root), text)

project_kit/cli.py

@@ -0,0 +1,286 @@
+"""Command-line entry point."""
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from project_kit import (
+    __version__,
+    agents,
+    approval,
+    backlog,
+    doctor,
+    handoff,
+    installer,
+    provision,
+)
+from project_kit import (
+    help as help_guide,
+)
+from project_kit.config import (
+    PROVIDERS,
+    Config,
+    ConfigError,
+    config_path,
+    load_config,
+    save_config,
+)
+from project_kit.gh import Gh, GhError
+from project_kit.providers.github import GitHubProvider
+from project_kit.state import PHASES, StateError, load_state
+from project_kit.templating import TemplateError
+from project_kit.workflow import WorkflowError, default_workflow, load_workflow, render_status
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="project-kit",
+        description="Define, plan and set up a project before handing off to Spec Kit.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("doctor", help="check that the required tools are available")
+
+    init = sub.add_parser(
+        "init",
+        help="install project-kit into the current directory (never overwrites existing files)",
+    )
+    init.add_argument(
+        "--here", action="store_true", help="accepted for compatibility; init always installs here"
+    )
+    init.add_argument("--project-name", help="project name (default: the directory name)")
+    init.add_argument("--provider", choices=PROVIDERS, default="github")
+    init.add_argument("--language", default="en", help="language of the generated documents")
+    init.add_argument(
+        "--ai-coauthor",
+        choices=("keep", "remove"),
+        help="whether AI assistants appear as co-authors of commits and PRs "
+        "(asked when omitted and a terminal is attached)",
+    )
+
+    init.add_argument(
+        "--agent",
+        choices=(*agents.AGENT_IDS, "none"),
+        help="AI agent to open when init finishes, or none (asked when omitted and a terminal "
+        "is attached)",
+    )
+
+    sub.add_parser("status", help="show the phases of the project and what comes next")
+    sub.add_parser("help", help="show a visual guide to the flow and the commands")
+
+    bl = sub.add_parser("backlog", help="work with .project-kit/backlog.json")
+    bl_sub = bl.add_subparsers(dest="backlog_command", required=True)
+    bl_sub.add_parser("validate", help="validate the backlog and print a summary")
+
+    pv = sub.add_parser(
+        "provision",
+        help="create milestones, labels and branches on GitHub from the backlog",
+    )
+    pv.add_argument("--repo", help="owner/name (default: the repository of the current directory)")
+    pv.add_argument(
+        "--project",
+        help="GitHub Project to use: its number or exact title, or a new title to create "
+        "(default: detect the ones linked to the repository)",
+    )
+    pv.add_argument("--dry-run", action="store_true", help="show the plan and change nothing")
+    pv.add_argument("--yes", action="store_true", help="do not ask for confirmation")
+
+    ho = sub.add_parser(
+        "handoff", help="generate the constitution input and hand the project over to Spec Kit"
+    )
+    ho.add_argument(
+        "--install-speckit",
+        action="store_true",
+        help="install the Spec Kit CLI and initialise this repository, after confirmation",
+    )
+    ho.add_argument("--dry-run", action="store_true", help="show what would happen, change nothing")
+    ho.add_argument("--yes", action="store_true", help="do not ask for confirmation")
+
+    ap = sub.add_parser("approve", help="record the user's approval of a phase")
+    ap.add_argument("phase", choices=PHASES)
+    return parser
+
+
+def _print_init_report(report: installer.Report) -> None:
+    for label, paths in (
+        ("created", report.created),
+        ("kept (differs from the shipped version)", report.kept),
+        ("already up to date", report.unchanged),
+    ):
+        if paths:
+            print(f"{label}:")
+            for path in paths:
+                print(f"  {path.as_posix()}")
+    for note in report.notes:
+        print(f"\nNote: {note}")
+    if not report.created:
+        print("\nNothing to do: project-kit is already installed here.")
+
+
+NEXT_AFTER_INIT = """
+Next: open Claude Code in this directory (restart it if it was already open, so it loads
+the new skills) and run /pk-start. It asks whether to stop here or to start defining the
+project. `project-kit status` shows where you are at any time."""
+
+
+def _status() -> int:
+    root = Path.cwd()
+    try:
+        config = load_config(root)
+        print(render_status(load_workflow(root), load_state(root), config.project_name))
+    except (ConfigError, StateError, WorkflowError) as exc:
+        print(f"project-kit status: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _offer_agent(root: Path, requested: str | None) -> bool:
+    """List the supported AI agents and open the chosen one with /pk-start.
+
+    Returns True when an agent was started, so the caller does not repeat the instructions.
+    """
+    if requested == "none":
+        return False
+    if requested is None and not sys.stdin.isatty():
+        return False  # nobody to ask, and nothing must start by surprise
+    for known in agents.AGENTS:
+        if agents.is_inside(known):
+            print(f"\nYou are already inside {known.name}: run {known.prompt} here.")
+            return True
+    agent = agents.get_agent(requested) if requested else agents.choose()
+    if agent is None:
+        return False
+    if agents.find_executable(agent) is None:
+        print(f"\n{agent.name} was not found on your PATH. Install it from {agent.install_hint}.")
+        return False
+    try:
+        config = load_config(root)
+        if config.agent != agent.id:
+            config.agent = agent.id
+            save_config(root, config)
+    except ConfigError as exc:
+        print(f"project-kit init: {exc}", file=sys.stderr)
+        return False
+    print(f"\nStarting {agent.name} with {agent.prompt}...\n")
+    agents.launch(agent, root)
+    return True
+
+
+def _help() -> int:
+    root = Path.cwd()
+    workflow, state, name = default_workflow(), None, None
+    try:
+        name = load_config(root).project_name
+        workflow, state = load_workflow(root), load_state(root)
+    except (ConfigError, StateError, WorkflowError):
+        workflow, state, name = default_workflow(), None, None  # not a project here: generic guide
+    print(help_guide.render_help(workflow, state, name, help_guide.Style.detect()))
+    return 0
+
+
+def _init(args: argparse.Namespace) -> int:
+    root = Path.cwd()
+    choice = args.ai_coauthor
+    if choice is None and sys.stdin.isatty() and not config_path(root).exists():
+        remove = _ask("Remove AI assistants (Claude, Copilot...) as co-authors of commits and PRs?")
+        choice = "remove" if remove else "keep"
+    config = Config(
+        project_name=args.project_name or root.name,
+        provider=args.provider,
+        language=args.language,
+        ai_coauthor=choice != "remove",
+    )
+    try:
+        config.validate()
+        report = installer.init_project(root, config)
+    except (ConfigError, StateError) as exc:
+        print(f"project-kit init: {exc}", file=sys.stderr)
+        return 1
+    _print_init_report(report)
+    if not _offer_agent(root, args.agent):
+        print(NEXT_AFTER_INIT)
+    return 0
+
+
+def _backlog_validate() -> int:
+    try:
+        loaded = backlog.load_backlog(Path.cwd())
+    except backlog.BacklogError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    print("Backlog is valid.\n" + loaded.summary())
+    return 0
+
+
+def _approve(phase: str) -> int:
+    try:
+        approval.approve_phase(Path.cwd(), phase)
+    except (ConfigError, StateError, backlog.BacklogError, WorkflowError) as exc:
+        print(f"project-kit approve: {exc}", file=sys.stderr)
+        return 1
+    print(f"Phase '{phase}' approved.")
+    return 0
+
+
+def _ask(question: str) -> bool:
+    try:
+        return input(f"{question} [y/N] ").strip().lower() in ("y", "yes")
+    except EOFError:  # no terminal attached: never assume consent
+        return False
+
+
+def _provision(args: argparse.Namespace) -> int:
+    try:
+        return provision.run_provision(
+            Path.cwd(),
+            GitHubProvider(Gh(), args.repo),
+            dry_run=args.dry_run,
+            assume_yes=args.yes,
+            confirm=_ask,
+            project=args.project,
+            interactive=sys.stdin.isatty(),
+        )
+    except (ConfigError, StateError, backlog.BacklogError, GhError) as exc:
+        print(f"project-kit provision: {exc}", file=sys.stderr)
+        return 1
+
+
+def _handoff(args: argparse.Namespace) -> int:
+    try:
+        return handoff.run_handoff(
+            Path.cwd(),
+            install=args.install_speckit,
+            assume_yes=args.yes,
+            dry_run=args.dry_run,
+            confirm=_ask,
+        )
+    except (ConfigError, StateError, TemplateError) as exc:
+        print(f"project-kit handoff: {exc}", file=sys.stderr)
+        return 1
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "doctor":
+        checks = doctor.run_checks()
+        print(doctor.render(checks))
+        return doctor.exit_code(checks)
+    if args.command == "init":
+        return _init(args)
+    if args.command == "status":
+        return _status()
+    if args.command in ("help", None):
+        return _help()
+    if args.command == "backlog":
+        return _backlog_validate()
+    if args.command == "provision":
+        return _provision(args)
+    if args.command == "handoff":
+        return _handoff(args)
+    if args.command == "approve":
+        return _approve(args.phase)
+    parser.print_help()
+    return 0