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

project_kit/handoff.py

@@ -0,0 +1,360 @@
+"""``project-kit handoff``: hand the project over to Spec Kit.
+
+project-kit never writes inside ``.specify/``; Spec Kit owns it. What this module does:
+
+* detects Spec Kit (CLI and ``.specify/``) and its version;
+* generates ``.project-kit/handoff/constitution-input.md``, the text to pass to
+  ``/speckit-constitution``;
+* with explicit confirmation, installs the Spec Kit CLI and initialises the repository by
+  running Spec Kit's own commands.
+
+The only contract with Spec Kit is therefore a plain file plus its public commands, so an
+unknown Spec Kit version degrades to a warning instead of breaking.
+"""
+
+import json
+import re
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+
+from project_kit.backlog import BacklogError, load_backlog
+from project_kit.config import PROJECT_DIR, Config, load_config
+from project_kit.fsutil import atomic_write_text
+from project_kit.state import load_state
+from project_kit.templating import render
+
+# Spec Kit versions (major.minor) this release was tried against.
+TESTED_SPECKIT = ("1.2",)
+MANAGED_HEADER = "<!-- project-kit:managed -->"
+TEMPLATE = "constitution-input.md"
+INPUT_FILE = Path(PROJECT_DIR) / "handoff" / "constitution-input.md"
+EXTRA_FILE = Path(PROJECT_DIR) / "handoff" / "constitution-extra.md"
+
+Which = Callable[[str], str | None]
+Runner = Callable[..., subprocess.CompletedProcess]
+
+
+# --- detecting Spec Kit ------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SpecKit:
+    cli: str | None  # path of the `specify` executable
+    cli_version: str | None
+    initialised: bool  # this repository has a .specify/ directory
+    project_version: str | None  # version recorded by Spec Kit in .specify/init-options.json
+
+    @property
+    def installed(self) -> bool:
+        return self.cli is not None
+
+
+def is_tested(version: str | None) -> bool:
+    return bool(version) and any(
+        version == t or version.startswith(t + ".")
+        for t in TESTED_SPECKIT  # type: ignore[union-attr]
+    )
+
+
+def _cli_version(exe: str, runner: Runner) -> str | None:
+    try:
+        proc = runner([exe, "--version"], capture_output=True, text=True, encoding="utf-8")
+    except OSError:
+        return None
+    match = re.search(r"\d+\.\d+\.\d+\S*", proc.stdout or "") if proc.returncode == 0 else None
+    return match.group(0) if match else None
+
+
+def _project_version(root: Path) -> str | None:
+    try:
+        data = json.loads((root / ".specify" / "init-options.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    version = data.get("speckit_version") if isinstance(data, dict) else None
+    return version if isinstance(version, str) else None
+
+
+def detect_speckit(
+    root: Path, which: Which = shutil.which, runner: Runner = subprocess.run
+) -> SpecKit:
+    cli = which("specify")
+    return SpecKit(
+        cli=cli,
+        cli_version=_cli_version(cli, runner) if cli else None,
+        initialised=(root / ".specify").is_dir(),
+        project_version=_project_version(root),
+    )
+
+
+# --- the constitution input --------------------------------------------------------------
+
+
+def _load_template(root: Path) -> str:
+    """The project's own copy if it has one (templates are overridable), else the shipped one."""
+    own = root / PROJECT_DIR / "templates" / TEMPLATE
+    if own.is_file():
+        return own.read_text(encoding="utf-8")
+    return (files("project_kit") / "assets" / "templates" / TEMPLATE).read_text(encoding="utf-8")
+
+
+def _adr_entry(path: Path, root: Path) -> str:
+    text = path.read_text(encoding="utf-8")
+    title = next(
+        (m.group(1).strip() for line in text.splitlines() if (m := re.match(r"#\s+(.+)", line))),
+        path.stem,
+    )
+    # "Status: Accepted", "**Status:** Accepted", "- Status: Accepted"...
+    status = re.search(
+        r"^[\s*_#>\-]*status[\s*_]*[:\-][\s*_]*([A-Za-z]+)", text, re.IGNORECASE | re.MULTILINE
+    )
+    label = f" ({status.group(1)})" if status else ""
+    return f"- `{path.relative_to(root).as_posix()}`: {title}{label}"
+
+
+def list_decisions(root: Path) -> list[str]:
+    adr_dir = root / "docs" / "adr"
+    if not adr_dir.is_dir():
+        return []
+    return [_adr_entry(p, root) for p in sorted(adr_dir.glob("*.md"))]
+
+
+def _references(root: Path) -> str:
+    lines = []
+    docs = [
+        f"`{p}`"
+        for p in ("docs/project/brief.md", "docs/project/roadmap.md")
+        if (root / p).is_file()
+    ]
+    if docs:
+        lines.append(f"- Project documents: {', '.join(docs)}.")
+    try:
+        phases = [p.title for p in load_backlog(root).phases]
+    except BacklogError:
+        phases = []
+    if phases:
+        lines.append(f"- Delivery phases: {', '.join(phases)}.")
+    return "\n".join(lines)
+
+
+def build_constitution_input(root: Path, config: Config) -> str:
+    decisions = list_decisions(root)
+    extra_path = root / EXTRA_FILE
+    extra = ""
+    if extra_path.is_file() and extra_path.read_text(encoding="utf-8").strip():
+        extra = (
+            "\n## Project-specific rules\n\n"
+            + extra_path.read_text(encoding="utf-8").strip()
+            + "\n"
+        )
+    variables = {
+        "project_name": config.project_name,
+        "language": config.language,
+        "provider": config.provider,
+        **{f"branches.{k}": v for k, v in config.branches.items()},
+        "stack": (
+            "defined by the decisions on record below."
+            if decisions
+            else "not decided yet; it is settled by an ADR before the first spec."
+        ),
+        "references": _references(root),
+        "decisions": "\n".join(decisions) if decisions else "No decisions are recorded yet.",
+        "extra": extra,
+    }
+    return render(_load_template(root), variables)
+
+
+def write_managed(path: Path, text: str) -> str:
+    """Write a generated file. Returns created | updated | unchanged | kept.
+
+    A file that lost its ``project-kit:managed`` header has been taken over by the user and
+    is never overwritten.
+    """
+    if not path.exists():
+        atomic_write_text(path, text)
+        return "created"
+    current = path.read_text(encoding="utf-8")
+    if current == text:
+        return "unchanged"
+    if MANAGED_HEADER not in current.splitlines()[:3]:
+        return "kept"
+    atomic_write_text(path, text)
+    return "updated"
+
+
+# --- installing Spec Kit -----------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Step:
+    description: str
+    command: list[str]
+
+
+def install_steps(sk: SpecKit, which: Which) -> tuple[list[Step], list[str]]:
+    """What has to run to get a working Spec Kit here, and what prevents it."""
+    steps: list[Step] = []
+    problems: list[str] = []
+    if not sk.installed:
+        if which("uv"):
+            steps.append(Step("Install the Spec Kit CLI", ["uv", "tool", "install", "specify-cli"]))
+        else:
+            problems.append(
+                "uv is needed to install Spec Kit (https://docs.astral.sh/uv/), or install "
+                "the `specify-cli` package yourself (for example with pipx) and run this again."
+            )
+    if not sk.initialised:
+        steps.append(
+            Step(
+                "Initialise Spec Kit in this repository (it merges its files into it)",
+                [
+                    "specify",
+                    "init",
+                    "--here",
+                    "--integration",
+                    "claude",
+                    "--force",
+                    "--non-interactive",
+                ],
+            )
+        )
+    return steps, problems
+
+
+def _resolve_specify(which: Which, runner: Runner) -> str | None:
+    """Find ``specify`` right after installing it, when the current PATH may not have it yet."""
+    if found := which("specify"):
+        return found
+    try:
+        proc = runner(
+            ["uv", "tool", "dir", "--bin"], capture_output=True, text=True, encoding="utf-8"
+        )
+    except OSError:
+        return None
+    if proc.returncode != 0:
+        return None
+    bin_dir = Path((proc.stdout or "").strip())
+    for name in ("specify.exe", "specify"):
+        if (bin_dir / name).is_file():
+            return str(bin_dir / name)
+    return None
+
+
+# --- the command -------------------------------------------------------------------------
+
+NEXT_STEPS = f"""\
+Next steps
+  1. In Claude Code, run:
+       /speckit-constitution @{INPUT_FILE.as_posix()}
+     Spec Kit owns .specify/memory/constitution.md; project-kit never edits it.
+  2. Optional: mention docs/project/ and docs/adr/ in CLAUDE.md or AGENTS.md so that
+     /speckit-specify and /speckit-plan read them.
+  3. Every card of the backlog is a candidate spec: use its issue as the input of
+     /speckit-specify.
+  4. When the constitution is in place, record it with: project-kit approve handoff"""
+
+
+def run_handoff(
+    root: Path,
+    *,
+    install: bool,
+    assume_yes: bool,
+    dry_run: bool,
+    confirm: Callable[[str], bool],
+    out: Callable[[str], None] = print,
+    which: Which = shutil.which,
+    runner: Runner = subprocess.run,
+) -> int:
+    """Returns the process exit code."""
+    config = load_config(root)
+    state = load_state(root)
+    if not state.is_approved("plan"):
+        out("Note: the plan has not been approved yet (project-kit approve plan).\n")
+
+    sk = detect_speckit(root, which, runner)
+    text = build_constitution_input(root, config)
+    target = root / INPUT_FILE
+
+    if dry_run:
+        out(f"Dry run: {INPUT_FILE.as_posix()} would contain:\n\n{text}")
+    else:
+        result = write_managed(target, text)
+        if result == "kept":
+            out(
+                f"{INPUT_FILE.as_posix()} no longer has the project-kit:managed header, so it was "
+                "left as it is. Delete it to have it generated again."
+            )
+        else:
+            out(f"{INPUT_FILE.as_posix()}: {result}.")
+
+    for note in _speckit_notes(sk):
+        out(note)
+
+    steps, problems = install_steps(sk, which)
+    if steps and not install:
+        out(
+            "\nSpec Kit is not ready in this repository. Run `project-kit handoff "
+            "--install-speckit` to set it up, or do it yourself with Spec Kit's own commands."
+        )
+    elif steps:
+        for problem in problems:
+            out(f"\nBLOCKING: {problem}")
+        if problems:
+            return 1
+        out("\nTo set up Spec Kit:")
+        for step in steps:
+            out(f"  - {step.description}: {' '.join(step.command)}")
+        if dry_run:
+            out("\nDry run: nothing was run.")
+            return 0
+        if not assume_yes and not confirm("\nRun these commands?"):
+            out("Aborted. Spec Kit was not touched.")
+            return 1
+        if not _run_steps(root, steps, out, which, runner):
+            return 1
+        sk = detect_speckit(root, which, runner)
+    elif problems:
+        for problem in problems:
+            out(f"\nBLOCKING: {problem}")
+        return 1
+
+    if sk.initialised and not dry_run:
+        out("\n" + NEXT_STEPS)
+    return 0
+
+
+def _speckit_notes(sk: SpecKit) -> list[str]:
+    notes = []
+    for label, version in (("CLI", sk.cli_version), ("this repository", sk.project_version)):
+        if version and not is_tested(version):
+            notes.append(
+                f"Note: Spec Kit {label} is version {version}, but project-kit was tried with "
+                f"{', '.join(v + '.x' for v in TESTED_SPECKIT)}. Only the constitution input "
+                "file is relied on, so this should still work."
+            )
+    return notes
+
+
+def _run_steps(
+    root: Path, steps: list[Step], out: Callable[[str], None], which: Which, runner: Runner
+) -> bool:
+    for step in steps:
+        command = list(step.command)
+        if command[0] == "specify":
+            exe = _resolve_specify(which, runner)
+            if exe is None:
+                out(
+                    "\nSpec Kit was installed but `specify` is not on your PATH yet. Run "
+                    "`uv tool update-shell`, open a new terminal and run this command again."
+                )
+                return False
+            command[0] = exe
+        out(f"\n> {' '.join(command)}")
+        proc = runner(command, cwd=root)
+        if proc.returncode != 0:
+            out(f"\nStopped: `{' '.join(step.command)}` failed (exit {proc.returncode}).")
+            return False
+    return True

project_kit/help.py

@@ -0,0 +1,152 @@
+"""``project-kit help``: a visual guide to the flow and the commands, for the terminal.
+
+Plain text with a little ANSI colour. It degrades on its own: no colour when the output is not
+a terminal or ``NO_COLOR`` is set, and ASCII instead of box-drawing characters when the output
+encoding cannot print them (the Windows console redirected to a file, for instance).
+"""
+
+import os
+import shutil
+import sys
+import textwrap
+from dataclasses import dataclass
+from typing import TextIO
+
+from project_kit import __version__
+from project_kit.state import State
+from project_kit.workflow import Workflow, step_marks
+
+# What runs in the terminal. The test suite checks that every subcommand is listed here.
+TERMINAL_COMMANDS = (
+    ("project-kit init", "install the skills, templates and workflow in this directory"),
+    ("project-kit status", "show the phases, where you are and what comes next"),
+    ("project-kit doctor", "check that git, gh, uv and Spec Kit are available"),
+    ("project-kit approve <phase>", "record your sign-off of a phase"),
+    ("project-kit backlog validate", "check .project-kit/backlog.json"),
+    ("project-kit provision [--dry-run]", "create milestones, branches, Project, issues"),
+    ("project-kit handoff [--install-speckit]", "prepare the Spec Kit constitution input"),
+    ("project-kit help", "show this guide"),
+)
+
+
+@dataclass(frozen=True)
+class Style:
+    color: bool = False
+    unicode: bool = False
+
+    @classmethod
+    def detect(cls, stream: TextIO | None = None) -> "Style":
+        stream = stream or sys.stdout
+        color = bool(getattr(stream, "isatty", lambda: False)()) and not os.environ.get("NO_COLOR")
+        try:
+            "─│→".encode(getattr(stream, "encoding", None) or "ascii")
+            unicode = True
+        except (UnicodeEncodeError, LookupError):
+            unicode = False
+        if color and os.name == "nt":
+            os.system("")  # switches the Windows console to understand ANSI escapes
+        return cls(color=color, unicode=unicode)
+
+    def paint(self, text: str, code: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if self.color else text
+
+    def bold(self, text: str) -> str:
+        return self.paint(text, "1")
+
+    def dim(self, text: str) -> str:
+        return self.paint(text, "2")
+
+    def green(self, text: str) -> str:
+        return self.paint(text, "32")
+
+    def cyan(self, text: str) -> str:
+        return self.paint(text, "1;36")
+
+    @property
+    def bar(self) -> str:
+        return "│" if self.unicode else "|"
+
+    @property
+    def arrow(self) -> str:
+        return "→" if self.unicode else "->"
+
+    def rule(self, title: str, width: int) -> str:
+        line = ("─" if self.unicode else "-") * max(width - len(title) - 2, 4)
+        return f"{self.bold(title)} {self.dim(line)}"
+
+
+def _mark(style: Style, mark: str) -> str:
+    cell = f"[{mark}]"
+    if mark == "x":
+        return style.green(cell)
+    if mark == ">":
+        return style.cyan(cell)
+    return style.dim(cell) if mark == "-" else cell
+
+
+def _flow(workflow: Workflow, state: State | None, style: Style, width: int) -> list[str]:
+    marks = (
+        step_marks(workflow, state)
+        if state is not None
+        else [(s, " " if s.enabled else "-", "") for s in workflow.steps]
+    )
+    indent = " " * 18
+    lines = []
+    for n, (step, mark, _note) in enumerate(marks):
+        name = f"{step.id:<10} /{step.skill}"
+        lines.append(f"  {_mark(style, mark)} {style.bold(name) if mark == '>' else name}")
+        detail = textwrap.wrap(step.title, max(width - len(indent) - 4, 30))
+        if step.produces:
+            detail.append(f"{style.arrow} {', '.join(step.produces)}")
+        for text in detail:
+            lines.append(f"   {style.bar}{indent[5:]}{style.dim(text)}")
+        if n < len(marks) - 1:
+            lines.append(f"   {style.bar}")
+    return lines
+
+
+def render_help(
+    workflow: Workflow,
+    state: State | None = None,
+    project_name: str | None = None,
+    style: Style | None = None,
+    width: int | None = None,
+) -> str:
+    """The guide. With a ``state`` it marks the progress of the project in this directory."""
+    style = style or Style()
+    width = min(width or shutil.get_terminal_size((80, 24)).columns, 100)
+    out = [
+        f"{style.bold('project-kit')} {__version__}",
+        "Define, plan and set up a project before handing it over to Spec Kit.",
+        "",
+        style.rule("HOW IT WORKS", width),
+        "  The terminal sets things up; your AI agent (Claude Code) runs the guided",
+        "  conversations as /pk-... skills. Every phase ends with your approval, and",
+        "  you can fill each document by hand instead.",
+        "",
+    ]
+    title = "THE FLOW" + (f"  ({project_name})" if project_name else "")
+    out += [style.rule(title, width), *_flow(workflow, state, style, width), ""]
+    if state is not None:
+        nxt = workflow.next_step(state)
+        if nxt is None:
+            out += ["Every enabled phase is done.", ""]
+        else:
+            out += [
+                f"Next: {style.cyan('/' + nxt.skill)} in your agent (or see `project-kit status`).",
+                "",
+            ]
+    out += [style.rule("IN THE TERMINAL", width)]
+    for cmd, desc in TERMINAL_COMMANDS:
+        out += [f"  {style.bold(cmd)}", f"      {style.dim(desc)}"]
+    out += [""]
+    if state is None:
+        out += [
+            style.rule("FIRST TIME", width),
+            "  1. project-kit doctor    check the tools",
+            "  2. project-kit init      in your repository; it offers to open your agent",
+            "  3. /pk-start             in the agent: only initialise, or begin",
+            "",
+        ]
+    out += ["Details of one command: project-kit <command> --help"]
+    return "\n".join(out)

project_kit/installer.py

@@ -0,0 +1,100 @@
+"""``project-kit init``: install project-kit's files into a target repository.
+
+Rule: never overwrite. A file that already exists is kept as it is (whether or not it
+differs from the shipped one), so manual edits are safe and running ``init`` again is a
+no-op. Updating shipped files is the job of the future ``upgrade`` command.
+"""
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from project_kit import ai_attribution
+from project_kit.config import PROJECT_DIR, Config, config_path, load_config, save_config
+from project_kit.fsutil import atomic_write_text
+from project_kit.state import State, save_state, state_path
+
+# Where each shipped asset directory lands in the target repository.
+_ASSET_TARGETS = {
+    "skills": Path(".claude") / "skills",
+    "templates": Path(PROJECT_DIR) / "templates",
+    "project": Path(PROJECT_DIR),
+}
+
+
+@dataclass
+class Report:
+    created: list[Path] = field(default_factory=list)
+    unchanged: list[Path] = field(default_factory=list)  # exists and identical to ours
+    kept: list[Path] = field(default_factory=list)  # exists and differs: left alone
+    notes: list[str] = field(default_factory=list)  # things the user should know or do
+
+
+def _walk(node: Traversable, prefix: Path = Path()) -> Iterator[tuple[Path, Traversable]]:
+    for child in sorted(node.iterdir(), key=lambda c: c.name):
+        rel = prefix / child.name
+        if child.is_dir():
+            yield from _walk(child, rel)
+        elif child.name != "__pycache__":
+            yield rel, child
+
+
+def iter_assets() -> Iterator[tuple[Path, bytes]]:
+    """Every shipped file as (path relative to the target repo, content)."""
+    assets = files("project_kit") / "assets"
+    for kind, target in _ASSET_TARGETS.items():
+        for rel, node in _walk(assets / kind):
+            yield target / rel, node.read_bytes()
+
+
+def _install_file(root: Path, rel: Path, content: bytes, report: Report) -> None:
+    dest = root / rel
+    if dest.exists():
+        (report.unchanged if dest.read_bytes() == content else report.kept).append(rel)
+        return
+    atomic_write_text(dest, content.decode("utf-8"))
+    report.created.append(rel)
+
+
+def _apply_ai_policy(root: Path, config: Config, report: Report) -> None:
+    """If the project asks that AI assistants are not co-authors, set that up (idempotent)."""
+    if config.ai_coauthor:
+        return
+    for create in (ai_attribution.configure_claude, ai_attribution.install_hook):
+        changed, note = create(root)
+        if changed:
+            report.created.append(changed)
+        if note:
+            report.notes.append(note)
+    if not ai_attribution.hook_is_active(root):
+        report.notes.append(
+            "To strip AI co-author trailers from every commit, run: "
+            + ai_attribution.HOOKS_PATH_COMMAND
+        )
+
+
+def init_project(root: Path, config: Config) -> Report:
+    """Install project-kit into ``root``. ``config`` is used only if there is none yet."""
+    report = Report()
+
+    cfg = config_path(root)
+    if cfg.exists():
+        load_config(root)  # fail early, with a clear message, if the existing one is invalid
+        report.unchanged.append(cfg.relative_to(root))
+    else:
+        save_config(root, config)
+        report.created.append(cfg.relative_to(root))
+
+    st = state_path(root)
+    if st.exists():
+        report.unchanged.append(st.relative_to(root))
+    else:
+        save_state(root, State())
+        report.created.append(st.relative_to(root))
+
+    for rel, content in iter_assets():
+        _install_file(root, rel, content, report)
+    _apply_ai_policy(root, load_config(root), report)
+    return report

project_kit/labels.py

@@ -0,0 +1,17 @@
+"""Labels project-kit derives from the backlog: one per issue type and per priority."""
+
+# (name, colour, description). Bugs reuse GitHub's own default "bug" label.
+TYPE_LABELS = {
+    "epic": ("type:epic", "3E4B9E", "Epic: groups child issues"),
+    "feature": ("type:feature", "1D76DB", "New functionality"),
+    "adr": ("type:adr", "5319E7", "Architecture decision"),
+    "chore": ("type:chore", "6E7781", "Maintenance or technical task"),
+    "docs": ("type:docs", "0075CA", "Documentation"),
+    "bug": ("bug", "D73A4A", "Something is not working"),
+}
+PRIORITY_LABELS = {
+    "P0": ("P0", "B60205", "Critical priority"),
+    "P1": ("P1", "D93F0B", "High priority"),
+    "P2": ("P2", "FBCA04", "Medium priority"),
+    "P3": ("P3", "C2E0C6", "Low priority"),
+}