dna-cli 0.1.0__py3-none-any.whl

dna_cli/_github_bridge.py

@@ -0,0 +1,294 @@
+"""DNA ↔ GitHub Issues bridge — pure builders + ``gh`` plumbing.
+
+The philosophy (s-github-issues-bridge)
+---------------------------------------
+GitHub Issues are artifacts of the github.com domain — DNA **bridges**
+to them with provenance, it does not replace them. Same stance as the
+PR half of the symbiosis (``pr_cmd.py``): the ``gh`` CLI is the door,
+the 🧬 attribution footer is the signature, and the provenance fields
+(``github_number`` / ``github_url`` / ``github_state`` /
+``github_synced_at`` on the Issue Kind schema) are the machine-readable
+link back.
+
+This module is the single home for the bridge's *mechanics* so both
+``issue_bridge_cmd.py`` (the ``dna sdlc issue publish|import|sync``
+commands) and ``sdlc_cmd.cmd_issue_resolve`` (the fail-soft close-on-
+resolve hook) share one implementation:
+
+- **pure builders** — issue title/body assembly, ``owner/name`` repo
+  parsing, ``#N``/URL reference parsing, the label→type/severity
+  heuristic. All offline-testable, no subprocess.
+- **gh plumbing** — a bounded ``subprocess.run`` wrapper in two
+  flavors: ``run_gh`` (raises ``GhError`` with a didactic message —
+  publish/import/sync want fail-loud) and ``close_issue_best_effort``
+  (returns a warning string — ``issue resolve`` must NEVER fail because
+  the network did).
+
+Label → type/severity heuristic (documented contract for ``import``):
+
+=================================  =============
+GitHub label (case-insensitive)    Issue field
+=================================  =============
+``bug`` / ``regression``           type=bug
+``enhancement`` / ``feature``      type=enhancement
+``question`` / ``help wanted``     type=question
+``documentation`` / ``docs`` /
+``task`` / ``chore``               type=task
+(none of the above)                type=task
+``critical`` / ``urgent`` / ``p0``  severity=critical
+``high`` / ``p1``                  severity=high
+``low`` / ``minor`` / ``p3`` /
+``trivial``                        severity=low
+(none of the above)                severity=medium
+=================================  =============
+
+Deliberately simple: first match wins in label order; anything fancier
+belongs to a human triage, not an import heuristic.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from typing import Any
+
+from dna_cli import _git_symbiosis as gs
+
+GH_TIMEOUT = 60  # seconds — every gh call here talks to the network
+
+#: One comment template for the close-on-resolve sync so tests + prose
+#: can't drift from the implementation.
+CLOSE_COMMENT_TEMPLATE = (
+    "Resolved in DNA SDLC{resolution}.\n\n{footer}"
+)
+
+
+class GhError(Exception):
+    """A ``gh`` invocation failed in a way the caller should surface.
+
+    The message is already didactic (install/auth/network hints) — CLI
+    commands wrap it in ``fail()`` verbatim.
+    """
+
+
+# ─── pure builders (the offline-testable surface) ─────────────────────
+
+
+def parse_repo_from_remote(remote_url: str) -> str | None:
+    """``owner/name`` from a git remote URL, or ``None``.
+
+    Handles the three shapes GitHub remotes come in::
+
+        https://github.com/owner/name.git
+        git@github.com:owner/name.git
+        ssh://git@github.com/owner/name
+
+    Non-GitHub remotes → ``None`` (the bridge is a github.com bridge).
+    """
+    url = (remote_url or "").strip()
+    m = re.search(r"github\.com[:/]([^/\s]+)/([^/\s]+?)(?:\.git)?/?$", url)
+    if not m:
+        return None
+    return f"{m.group(1)}/{m.group(2)}"
+
+
+def default_repo() -> str | None:
+    """``owner/name`` derived from the current repo's ``origin`` remote.
+
+    Fail-soft (``None``) — callers turn absence into a didactic error
+    asking for ``--repo``.
+    """
+    out = gs._run_git(["remote", "get-url", "origin"])
+    if not out:
+        return None
+    return parse_repo_from_remote(out.strip())
+
+
+def parse_issue_ref(ref: str) -> tuple[int, str | None]:
+    """Parse ``#N`` / ``N`` / a full GitHub issue URL → ``(number, repo)``.
+
+    The URL form also yields the repo (``owner/name``); the numeric
+    forms yield ``(N, None)`` and the caller resolves the repo. Raises
+    ``ValueError`` with a didactic message on anything else.
+    """
+    r = (ref or "").strip()
+    m = re.match(r"^https?://github\.com/([^/\s]+)/([^/\s]+)/issues/(\d+)/?$", r)
+    if m:
+        return int(m.group(3)), f"{m.group(1)}/{m.group(2)}"
+    m = re.match(r"^#?(\d+)$", r)
+    if m:
+        return int(m.group(1)), None
+    raise ValueError(
+        f"referência de issue inválida: {ref!r} — use '#N', 'N' ou a URL "
+        f"completa (https://github.com/<owner>/<repo>/issues/N)."
+    )
+
+
+def slug_from_title(title: str, *, max_words: int = 6) -> str:
+    """Kebab-case slug from a GitHub issue title (for ``i-NNN-<slug>``)."""
+    words = re.sub(r"[^a-z0-9]+", " ", (title or "").lower()).split()
+    return "-".join(words[:max_words]) or "imported"
+
+
+def build_issue_title(name: str, spec: dict[str, Any]) -> str:
+    """GitHub issue title: ``<title> (<i-x>)`` — pure.
+
+    Same convention as ``build_pr_title``: the slug rides along so the
+    GitHub title alone is ⌘K-pasteable back to the work item. Issues
+    often have no ``title`` field — fall back to the description's
+    first line, squeezed and bounded (GitHub caps titles at 256 chars).
+    """
+    title = str(spec.get("title") or "").strip()
+    if not title:
+        desc = " ".join(str(spec.get("description") or name).split())
+        title = desc[:120] + ("…" if len(desc) > 120 else "")
+    return f"{title} ({name})"
+
+
+def doc_url(repo: str, scope: str, name: str) -> str:
+    """GitHub blob URL of the Issue doc inside the repo (main branch)."""
+    return f"https://github.com/{repo}/blob/main/.dna/{scope}/issues/{name}.yaml"
+
+
+def build_issue_body(name: str, spec: dict[str, Any], *, scope: str, repo: str) -> str:
+    """GitHub issue body: description + facts + doc link + 🧬 footer — pure.
+
+    The footer reuses the exact PR attribution template
+    (``_git_symbiosis.pr_footer_block``) with ``Issue/<i-x>`` as the
+    work item — one convention, three surfaces (commits, PRs, issues).
+    """
+    parts: list[str] = []
+    desc = str(spec.get("description") or "").strip()
+    if desc:
+        parts.append(desc)
+    facts = [
+        f"**{label}:** {spec.get(key)}"
+        for label, key in (("Type", "type"), ("Severity", "severity"))
+        if spec.get(key)
+    ]
+    if facts:
+        parts.append(" · ".join(facts))
+    parts.append(f"Tracked as [`{name}`]({doc_url(repo, scope, name)}) on the DNA SDLC board.")
+    parts.append(gs.pr_footer_block("Issue", name))
+    return "\n\n".join(parts) + "\n"
+
+
+def map_labels(labels: list[str]) -> tuple[str, str]:
+    """GitHub labels → ``(type, severity)`` — the documented heuristic.
+
+    First match wins in label order; defaults ``("task", "medium")``.
+    """
+    type_map = {
+        "bug": "bug", "regression": "bug",
+        "enhancement": "enhancement", "feature": "enhancement",
+        "question": "question", "help wanted": "question",
+        "documentation": "task", "docs": "task", "task": "task", "chore": "task",
+    }
+    sev_map = {
+        "critical": "critical", "urgent": "critical", "p0": "critical",
+        "high": "high", "p1": "high",
+        "low": "low", "minor": "low", "p3": "low", "trivial": "low",
+    }
+    issue_type = severity = None
+    for raw in labels or []:
+        lbl = str(raw).strip().lower()
+        if issue_type is None and lbl in type_map:
+            issue_type = type_map[lbl]
+        if severity is None and lbl in sev_map:
+            severity = sev_map[lbl]
+    return issue_type or "task", severity or "medium"
+
+
+def close_comment(name: str, resolution: str | None) -> str:
+    """The comment posted when ``issue resolve`` closes the GitHub twin."""
+    res = f": {resolution}" if resolution else ""
+    return CLOSE_COMMENT_TEMPLATE.format(
+        resolution=res, footer=gs.pr_footer("Issue", name),
+    )
+
+
+# ─── gh plumbing ──────────────────────────────────────────────────────
+
+
+def gh_available() -> bool:
+    return shutil.which("gh") is not None
+
+
+def gh_missing_message(context: str) -> str:
+    """The didactic no-gh error, shared by publish/import/sync."""
+    return (
+        f"gh (GitHub CLI) não encontrado no PATH — {context} precisa dele. "
+        "Instale via https://cli.github.com e autentique com `gh auth login`."
+    )
+
+
+def run_gh(args: list[str], *, context: str) -> str:
+    """Run ``gh`` fail-LOUD: returns stdout, raises ``GhError`` didactically.
+
+    ``context`` names the operation for the error message ("issue
+    publish", "issue import", …). Never lets a raw traceback escape.
+    """
+    if not gh_available():
+        raise GhError(gh_missing_message(context))
+    try:
+        proc = subprocess.run(args, capture_output=True, text=True, timeout=GH_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        raise GhError(
+            f"gh excedeu {GH_TIMEOUT}s durante {context} — rede/gateway? Tente de novo."
+        ) from None
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or "").strip()
+        raise GhError(
+            f"gh falhou durante {context}:\n{detail}\n"
+            "Dicas: `gh auth status` mostra a autenticação; --repo "
+            "aponta o repositório explicitamente."
+        )
+    return proc.stdout or ""
+
+
+def fetch_issue(number: int, repo: str, *, context: str) -> dict[str, Any]:
+    """``gh issue view N --json …`` → parsed dict (fail-loud via GhError)."""
+    out = run_gh(
+        [
+            "gh", "issue", "view", str(number), "--repo", repo,
+            "--json", "number,title,body,state,url,author,labels,createdAt,closedAt",
+        ],
+        context=context,
+    )
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError:
+        raise GhError(
+            f"gh devolveu JSON inválido durante {context} — saída: {out[:200]!r}"
+        ) from None
+
+
+def close_issue_best_effort(
+    number: int, repo: str | None, comment: str,
+) -> str | None:
+    """Close the GitHub twin with a comment — NEVER raises.
+
+    Returns ``None`` on success, else a human warning string the caller
+    prints (the local resolve already happened; the sync is best-effort
+    by contract).
+    """
+    if not gh_available():
+        return (
+            f"gh não encontrado — issue #{number} NÃO foi fechada no GitHub "
+            f"(feche à mão ou rode `dna sdlc issue sync` depois)."
+        )
+    args = ["gh", "issue", "close", str(number), "--comment", comment]
+    if repo:
+        args += ["--repo", repo]
+    try:
+        proc = subprocess.run(args, capture_output=True, text=True, timeout=GH_TIMEOUT)
+    except Exception as e:  # noqa: BLE001 — best-effort by contract
+        return f"não consegui fechar a issue #{number} no GitHub ({e}) — feche à mão."
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or "").strip()
+        return (
+            f"gh issue close #{number} falhou (non-fatal): {detail} — "
+            f"o resolve local já aconteceu; feche no GitHub à mão."
+        )
+    return None

dna_cli/_methodology_gates.py

@@ -0,0 +1,164 @@
+"""Methodology gates — pure functions enforcing the superpowers contract.
+
+`methodology=superpowers` was historically just a string label in
+`JOURNEY_METHODOLOGIES`. These gates turn it into a verifiable
+contract: spec/plan artifacts must exist, build → reflect requires
+test files in the diff, and the Auditor blocks ad-hoc streaks.
+
+The four gates are PURE FUNCTIONS — no I/O beyond filesystem stat and
+a single subprocess call in `_git_diff_files` (which is monkeypatched
+in tests). The CLI in `sdlc_cmd.py` calls these at phase boundaries
+and translates GateResult.FAIL into exit code 2.
+
+Spec: docs/superpowers/specs/2026-05-11-f-superpowers-skill-integration.md
+"""
+from __future__ import annotations
+
+import subprocess
+from enum import Enum
+from pathlib import Path
+
+
+class GateResult(Enum):
+    """Outcome of a gate check.
+
+    PASS — gate satisfied, proceed.
+    FAIL — gate violated, caller should exit 2 unless --force --reason.
+    SKIP — gate not applicable in this context (e.g. methodology=ad-hoc).
+    """
+
+    PASS = "pass"
+    FAIL = "fail"
+    SKIP = "skip"
+
+
+# ───── spec_gate ─────────────────────────────────────────────────────
+
+
+def spec_gate(*, methodology: str, phase: str, artifact: str | None) -> GateResult:
+    """Specify phase under superpowers requires a real Spec doc.
+
+    Returns SKIP unless `methodology == "superpowers"` and `phase == "specify"`.
+    Returns FAIL if `artifact` is None or points to a missing file.
+    Returns PASS otherwise.
+    """
+    if methodology != "superpowers" or phase != "specify":
+        return GateResult.SKIP
+    if not artifact:
+        return GateResult.FAIL
+    return GateResult.PASS if Path(artifact).exists() else GateResult.FAIL
+
+
+# ───── plan_gate ─────────────────────────────────────────────────────
+
+
+def plan_gate(
+    *,
+    methodology: str,
+    phase: str,
+    artifact: str | None,
+    auto_stub: bool,
+) -> GateResult:
+    """Plan phase under superpowers requires Plan doc OR --auto-stub.
+
+    SKIP if not (superpowers + plan).
+    PASS if --auto-stub (caller will stub the plan file) or artifact exists.
+    FAIL otherwise.
+    """
+    if methodology != "superpowers" or phase != "plan":
+        return GateResult.SKIP
+    if auto_stub:
+        return GateResult.PASS
+    if not artifact:
+        return GateResult.FAIL
+    return GateResult.PASS if Path(artifact).exists() else GateResult.FAIL
+
+
+# ───── tdd_gate ──────────────────────────────────────────────────────
+
+
+def _git_diff_files(since: str) -> list[str]:
+    """Return list of files changed between ``since..HEAD``.
+
+    Returns [] on any git error (we fail-open at the caller via SKIP
+    when since_sha is missing).
+    """
+    out = subprocess.run(
+        ["git", "diff", "--name-only", f"{since}..HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if out.returncode != 0:
+        return []
+    return [line for line in out.stdout.splitlines() if line]
+
+
+def _looks_like_test_file(path: str) -> bool:
+    """Heuristic: does this path look like a test file?
+
+    Accepts: anything under ``tests/`` (Python convention) or files
+    matching ``test_*.py`` / ``*_test.py`` / ``*.test.ts`` / ``*.spec.ts``.
+    """
+    if "tests/" in path or "/test_" in path:
+        return True
+    name = path.rsplit("/", 1)[-1]
+    if name.startswith("test_") and name.endswith(".py"):
+        return True
+    if name.endswith("_test.py"):
+        return True
+    if name.endswith(".test.ts") or name.endswith(".test.tsx"):
+        return True
+    if name.endswith(".spec.ts") or name.endswith(".spec.tsx"):
+        return True
+    return False
+
+
+def tdd_gate(
+    *,
+    methodology: str,
+    prev_phase: str,
+    next_phase: str,
+    since_sha: str | None,
+) -> GateResult:
+    """Transition build → reflect under superpowers requires test files in diff.
+
+    SKIP if methodology is not superpowers, transition is not build→reflect,
+    or `since_sha` is missing (cannot verify honestly).
+    PASS if any file in the git diff since `since_sha` looks like a test.
+    FAIL otherwise.
+    """
+    if methodology != "superpowers" or prev_phase != "build" or next_phase != "reflect":
+        return GateResult.SKIP
+    if not since_sha:
+        return GateResult.SKIP
+    files = _git_diff_files(since_sha)
+    return GateResult.PASS if any(_looks_like_test_file(f) for f in files) else GateResult.FAIL
+
+
+# ───── auditor_gate ──────────────────────────────────────────────────
+
+
+_AUDITOR_WINDOW = 5
+_AUDITOR_THRESHOLD = 3
+
+
+def auditor_gate(
+    *,
+    recent_methodologies: list[str],
+    next_methodology: str,
+) -> GateResult:
+    """Block ad-hoc streaks. Looks at the last 5 methodologies.
+
+    SKIP when history < 4 (insufficient data).
+    PASS when next_methodology is `superpowers` (any streak satisfied by upgrade).
+    PASS when last 5 contain < 3 ad-hoc entries.
+    FAIL when last 5 contain >= 3 ad-hoc AND next is not superpowers.
+    """
+    if len(recent_methodologies) < 4:
+        return GateResult.SKIP
+    window = recent_methodologies[-_AUDITOR_WINDOW:]
+    ad_hoc_count = sum(1 for m in window if m == "ad-hoc")
+    if ad_hoc_count >= _AUDITOR_THRESHOLD and next_methodology != "superpowers":
+        return GateResult.FAIL
+    return GateResult.PASS

dna_cli/data/git-hooks/prepare-commit-msg

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""prepare-commit-msg — DNA git↔SDLC symbiosis hook (s-sdlc-git-symbiosis).
+
+Stamps every commit made while a Story is active with two trailers:
+
+    Work-Item: Story/<story-name>
+    Co-Authored-By: dna-sdlc[bot] <dna-sdlc[bot]@users.noreply.github.com>
+
+The active Story comes from `.dna/active-story.txt` at the repo root
+(single line, `<scope>:<story-name>` — written by `dna sdlc story start`,
+cleared by `story done|block|cancel`). No active Story → no stamp:
+absence is signal too. The co-author is the dna sdlc TOOL identity (a
+provenance seal: "this commit was born under story governance"), not a
+human co-author; override it with $DNA_SDLC_COAUTHOR.
+
+Rules:
+  - zero dependencies: python3 + git only (runs without any venv);
+  - idempotent: never duplicates a trailer already present
+    (`git interpret-trailers --if-exists addIfDifferent`);
+  - respects merge/squash/amend messages (2nd hook arg in
+    {merge, squash, commit}) and empty messages: no stamp;
+  - fail-soft: any unexpected error exits 0 — never blocks a commit.
+
+Install: `dna sdlc hooks install`  (→ git config core.hooksPath scripts/git-hooks)
+
+Keep in sync with packages/cli/dna_cli/_git_symbiosis.py — the CLI test
+suite asserts the constants below match, and that the repo copy at
+scripts/git-hooks/prepare-commit-msg is byte-identical to the packaged
+copy in dna_cli/data/git-hooks/.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+WORK_ITEM_TRAILER = "Work-Item"
+COAUTHOR_TRAILER = "Co-Authored-By"
+DEFAULT_SDLC_COAUTHOR = "dna-sdlc[bot] <dna-sdlc[bot]@users.noreply.github.com>"
+COAUTHOR_ENV = "DNA_SDLC_COAUTHOR"
+
+ACTIVE_STORY_FILE = ".dna/active-story.txt"
+
+# 2nd hook argument values that must NEVER be stamped: merges, squashes and
+# amend/-c/-C reuse an existing message that was (or wasn't) stamped when it
+# was born — rewriting it here would be surprising.
+SKIP_SOURCES = {"merge", "squash", "commit"}
+
+
+def _git(args, cwd=None):
+    """Run git; return stdout or None on any failure (fail-soft)."""
+    try:
+        proc = subprocess.run(
+            ["git"] + list(args),
+            capture_output=True, text=True, timeout=10, cwd=cwd,
+        )
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    return proc.stdout
+
+
+def read_active_story(repo_root):
+    """Parse `.dna/active-story.txt` → (scope, name) or None."""
+    path = os.path.join(repo_root, ACTIVE_STORY_FILE)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            raw = fh.read().strip()
+    except OSError:
+        return None
+    if not raw or ":" not in raw:
+        return None
+    scope, _, name = raw.partition(":")
+    scope, name = scope.strip(), name.strip()
+    if not scope or not name:
+        return None
+    return scope, name
+
+
+def message_is_empty(msg_file):
+    """True when the message has no content outside comment lines."""
+    try:
+        with open(msg_file, encoding="utf-8") as fh:
+            text = fh.read()
+    except OSError:
+        return True
+    comment_char = (_git(["config", "--get", "core.commentchar"]) or "#").strip() or "#"
+    if comment_char == "auto":
+        comment_char = "#"
+    for line in text.splitlines():
+        if line.strip() and not line.startswith(comment_char):
+            return False
+    return True
+
+
+def stamp(msg_file, trailers):
+    """Append trailers idempotently via git interpret-trailers."""
+    args = ["interpret-trailers", "--in-place", "--if-exists", "addIfDifferent"]
+    for t in trailers:
+        args += ["--trailer", t]
+    args.append(msg_file)
+    return _git(args) is not None
+
+
+def main(argv):
+    if len(argv) < 2:
+        return 0
+    msg_file = argv[1]
+    source = argv[2] if len(argv) > 2 else ""
+    if source in SKIP_SOURCES:
+        return 0
+    root = (_git(["rev-parse", "--show-toplevel"]) or "").strip() or os.getcwd()
+    active = read_active_story(root)
+    if active is None:
+        return 0  # no active story — absence is signal
+    if message_is_empty(msg_file):
+        return 0  # don't turn an aborted (empty) commit into a non-empty one
+    _scope, name = active
+    coauthor = os.environ.get(COAUTHOR_ENV, "").strip() or DEFAULT_SDLC_COAUTHOR
+    stamp(msg_file, [
+        "%s: Story/%s" % (WORK_ITEM_TRAILER, name),
+        "%s: %s" % (COAUTHOR_TRAILER, coauthor),
+    ])
+    return 0  # fail-soft: never block the commit
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except Exception:
+        sys.exit(0)  # fail-soft by contract