sendsprint 0.7.1__py3-none-any.whl

sendsprint/__init__.py

@@ -0,0 +1,4 @@
+"""SendSprint - multi-agent skill that automates sprint delivery."""
+
+__version__ = "0.7.1"
+__all__ = ["__version__"]

sendsprint/agentic_starter.py

@@ -0,0 +1,281 @@
+"""Sync the agentic-starter scaffold into a repository.
+
+The sync is intentionally file-based and conservative: existing files are
+preserved unless ``force=True``. Scheduled automation can run the same command
+and open a PR for review instead of mutating ``main`` directly.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+import urllib.error
+import urllib.request
+import zipfile
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+DEFAULT_AGENTIC_STARTER_SOURCE = "https://github.com/wesleysimplicio/agentic-starter"
+DEFAULT_AGENTIC_STARTER_REF = "latest"
+AGENTIC_STARTER_LOCK = ".agentic-starter.json"
+
+AGENTIC_STARTER_PATHS: tuple[str, ...] = (
+    "AGENTS.md",
+    "CLAUDE.md",
+    "INIT.md",
+    "_BOOTSTRAP.md",
+    "bootstrap.ps1",
+    "bootstrap.sh",
+    "playwright.config.ts",
+    "bin",
+    ".agents",
+    ".claude",
+    ".codex",
+    ".skills",
+    ".github/CODEOWNERS",
+    ".github/ISSUE_TEMPLATE",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/workflows/ci.yml",
+    ".github/workflows/dod.yml",
+    ".github/workflows/scaffold-self-check.yml",
+    "templates/ADR-template.md",
+    "templates/task-template.md",
+    ".specs/architecture/ADR-template.md",
+    ".specs/product/PERSONAS.md",
+    ".specs/sprints/BACKLOG.md",
+    ".specs/sprints/task-template.md",
+    ".specs/workflow/CONTRIBUTING.md",
+    ".specs/workflow/RELEASE.md",
+    ".specs/workflow/WORKFLOW.md",
+)
+
+
+@dataclass
+class AgenticStarterSyncResult:
+    """Result returned by :func:`sync_agentic_starter`."""
+
+    repo_path: Path
+    source: str
+    requested_ref: str
+    resolved_ref: str
+    created: list[Path] = field(default_factory=list)
+    updated: list[Path] = field(default_factory=list)
+    skipped: list[Path] = field(default_factory=list)
+    missing: list[str] = field(default_factory=list)
+    dry_run: bool = False
+
+    @property
+    def changed(self) -> bool:
+        return bool(self.created or self.updated)
+
+
+def sync_agentic_starter(
+    repo_path: str | Path,
+    *,
+    source: str = DEFAULT_AGENTIC_STARTER_SOURCE,
+    ref: str = DEFAULT_AGENTIC_STARTER_REF,
+    paths: tuple[str, ...] = AGENTIC_STARTER_PATHS,
+    force: bool = False,
+    dry_run: bool = False,
+) -> AgenticStarterSyncResult:
+    """Copy the latest agentic-starter structure into ``repo_path``.
+
+    ``source`` may be a local directory, a GitHub repo URL, or ``owner/repo``.
+    GitHub sources use the latest release when ``ref="latest"`` and fall back to
+    the default branch name ``main`` if the repository has no release yet.
+    """
+
+    repo = Path(repo_path).expanduser().resolve()
+    if not repo.exists():
+        raise FileNotFoundError(f"repo path not found: {repo}")
+
+    source_path = Path(source).expanduser()
+    if source_path.exists():
+        result = AgenticStarterSyncResult(
+            repo_path=repo,
+            source=str(source_path.resolve()),
+            requested_ref=ref,
+            resolved_ref=ref,
+            dry_run=dry_run,
+        )
+        _copy_paths(source_path.resolve(), repo, paths, result, force=force, dry_run=dry_run)
+        _write_lock(result, paths, force=force, dry_run=dry_run)
+        return result
+
+    owner, repo_name = _parse_github_source(source)
+    with tempfile.TemporaryDirectory(prefix="sendsprint-agentic-starter-") as tmp:
+        tmp_path = Path(tmp)
+        archive, resolved_ref = _download_github_archive(owner, repo_name, ref, tmp_path)
+        with zipfile.ZipFile(archive) as zf:
+            zf.extractall(tmp_path / "src")
+        source_root = _archive_root(tmp_path / "src")
+
+        result = AgenticStarterSyncResult(
+            repo_path=repo,
+            source=f"https://github.com/{owner}/{repo_name}",
+            requested_ref=ref,
+            resolved_ref=resolved_ref,
+            dry_run=dry_run,
+        )
+        _copy_paths(source_root, repo, paths, result, force=force, dry_run=dry_run)
+        _write_lock(result, paths, force=force, dry_run=dry_run)
+        return result
+
+
+def _copy_paths(
+    source_root: Path,
+    repo: Path,
+    paths: tuple[str, ...],
+    result: AgenticStarterSyncResult,
+    *,
+    force: bool,
+    dry_run: bool,
+) -> None:
+    for rel in paths:
+        source = source_root / rel
+        if not source.exists():
+            result.missing.append(rel)
+            continue
+        if source.is_file():
+            _copy_file(source, _target(repo, rel), result, force=force, dry_run=dry_run)
+            continue
+        for child in source.rglob("*"):
+            if child.is_file():
+                child_rel = child.relative_to(source_root).as_posix()
+                _copy_file(child, _target(repo, child_rel), result, force=force, dry_run=dry_run)
+
+
+def _copy_file(
+    source: Path,
+    target: Path,
+    result: AgenticStarterSyncResult,
+    *,
+    force: bool,
+    dry_run: bool,
+) -> None:
+    if target.exists() and not force:
+        result.skipped.append(target)
+        return
+
+    bucket = result.updated if target.exists() else result.created
+    bucket.append(target)
+    if dry_run:
+        return
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+
+
+def _target(repo: Path, rel: str) -> Path:
+    target = (repo / rel).resolve()
+    if target != repo and repo not in target.parents:
+        raise ValueError(f"refusing to write outside repo: {rel}")
+    return target
+
+
+def _write_lock(
+    result: AgenticStarterSyncResult,
+    paths: tuple[str, ...],
+    *,
+    force: bool,
+    dry_run: bool,
+) -> None:
+    lock = result.repo_path / AGENTIC_STARTER_LOCK
+    data = {
+        "source": result.source,
+        "requested_ref": result.requested_ref,
+        "resolved_ref": result.resolved_ref,
+        "synced_at": datetime.now(tz=UTC).isoformat(timespec="seconds"),
+        "mode": "force" if force else "missing",
+        "managed_paths": list(paths),
+    }
+    if lock.exists() and not force:
+        result.skipped.append(lock)
+        return
+    if lock.exists():
+        result.updated.append(lock)
+    else:
+        result.created.append(lock)
+    if not dry_run:
+        lock.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _parse_github_source(source: str) -> tuple[str, str]:
+    normalized = source.removesuffix(".git").rstrip("/")
+    marker = "github.com/"
+    if marker in normalized:
+        normalized = normalized.split(marker, 1)[1]
+    parts = normalized.split("/")
+    if len(parts) >= 2 and parts[0] and parts[1]:
+        return parts[0], parts[1]
+    raise ValueError("agentic-starter source must be a local path, a GitHub URL, or 'owner/repo'")
+
+
+def _download_github_archive(
+    owner: str,
+    repo: str,
+    ref: str,
+    target_dir: Path,
+) -> tuple[Path, str]:
+    resolved_ref = _resolve_github_ref(owner, repo, ref)
+    archive_url = f"https://api.github.com/repos/{owner}/{repo}/zipball/{resolved_ref}"
+    archive = target_dir / "agentic-starter.zip"
+    _download(archive_url, archive)
+    return archive, resolved_ref
+
+
+def _resolve_github_ref(owner: str, repo: str, ref: str) -> str:
+    if ref != "latest":
+        return ref
+    url = f"https://api.github.com/repos/{owner}/{repo}/releases/latest"
+    try:
+        data = json.loads(_read_url(url).decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return "main"
+        raise
+    tag = data.get("tag_name")
+    return str(tag) if tag else "main"
+
+
+def _read_url(url: str) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": "sendsprint"})
+    with urllib.request.urlopen(req, timeout=30) as response:
+        return response.read()
+
+
+def _download(url: str, target: Path) -> None:
+    data = _read_url(url)
+    target.write_bytes(data)
+
+
+def _archive_root(path: Path) -> Path:
+    children = [p for p in path.iterdir() if p.is_dir()]
+    if len(children) == 1:
+        return children[0]
+    return path
+
+
+def result_to_json(result: AgenticStarterSyncResult) -> dict[str, Any]:
+    """Return a JSON-serializable sync result for CLI output/tests."""
+
+    repo = result.repo_path
+
+    def _rel(paths: list[Path]) -> list[str]:
+        return [p.relative_to(repo).as_posix() for p in paths]
+
+    return {
+        "repo_path": str(repo),
+        "source": result.source,
+        "requested_ref": result.requested_ref,
+        "resolved_ref": result.resolved_ref,
+        "created": _rel(result.created),
+        "updated": _rel(result.updated),
+        "skipped": _rel(result.skipped),
+        "missing": result.missing,
+        "dry_run": result.dry_run,
+        "changed": result.changed,
+    }

sendsprint/agents/__init__.py

@@ -0,0 +1,23 @@
+"""Agents: worktree isolation, dev, lint, test, security, PR creation/review."""
+
+from .dev import DevAgent
+from .lint_runner import LintRunner
+from .pr_body_builder import PrBodyBuilder
+from .pr_creator import PrCreator
+from .pr_reviewer import PrReviewer
+from .security_reviewer import SecurityReviewer
+from .sprint_importer import SprintImporter
+from .test_runner import TestRunner
+from .worktree import WorktreeManager
+
+__all__ = [
+    "DevAgent",
+    "LintRunner",
+    "PrBodyBuilder",
+    "PrCreator",
+    "PrReviewer",
+    "SecurityReviewer",
+    "SprintImporter",
+    "TestRunner",
+    "WorktreeManager",
+]

sendsprint/agents/dev.py

@@ -0,0 +1,105 @@
+"""DevAgent: dispatches development work by tech stack."""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from pathlib import Path
+
+from ..models.reports import StepReport
+from ..tech import TechFingerprint
+
+logger = logging.getLogger(__name__)
+
+INSTALL_COMMANDS: dict[str, list[str]] = {
+    "npm": ["npm", "install"],
+    "yarn": ["yarn", "install"],
+    "pnpm": ["pnpm", "install"],
+    "bun": ["bun", "install"],
+    "pip": ["pip", "install", "-r", "requirements.txt"],
+    "poetry": ["poetry", "install"],
+    "uv": ["uv", "sync"],
+    "nuget": ["dotnet", "restore"],
+    "maven": ["mvn", "install", "-DskipTests"],
+    "gradle": ["./gradlew", "assemble"],
+    "cargo": ["cargo", "build"],
+    "go": ["go", "build", "./..."],
+    "pub": ["flutter", "pub", "get"],
+    "bundler": ["bundle", "install"],
+    "composer": ["composer", "install"],
+}
+
+BUILD_COMMANDS: dict[str, list[str]] = {
+    "angular": ["npx", "ng", "build"],
+    "react": ["npm", "run", "build"],
+    "nextjs": ["npm", "run", "build"],
+    "vue": ["npm", "run", "build"],
+    "nestjs": ["npm", "run", "build"],
+    "dotnet": ["dotnet", "build"],
+    "spring": ["mvn", "package", "-DskipTests"],
+    "java": ["mvn", "package", "-DskipTests"],
+    "go": ["go", "build", "./..."],
+    "rust": ["cargo", "build"],
+    "flutter": ["flutter", "build"],
+}
+
+
+class DevAgent:
+    """Runs install + build for a repo based on its tech fingerprint."""
+
+    def __init__(self, repo_path: str | Path, fingerprint: TechFingerprint) -> None:
+        self.repo = Path(repo_path).resolve()
+        self.fp = fingerprint
+
+    def install(self) -> StepReport:
+        report = StepReport(step=3, name="install-deps", repo=str(self.repo))
+        report.status = "running"
+        pm = self.fp.package_managers[0] if self.fp.package_managers else None
+        if not pm:
+            report.status = "skipped"
+            report.message = "no package manager detected"
+            return report
+        cmd = INSTALL_COMMANDS.get(pm)
+        if not cmd:
+            report.status = "skipped"
+            report.message = f"no install command mapped for {pm}"
+            return report
+        return self._exec(cmd, report)
+
+    def build(self, *, custom_command: str | None = None) -> StepReport:
+        report = StepReport(step=3, name="build", repo=str(self.repo))
+        report.status = "running"
+        if custom_command:
+            cmd = custom_command.split()
+        else:
+            tech = self.fp.primary_tech
+            cmd_list = BUILD_COMMANDS.get(tech) if tech else None
+            if not cmd_list:
+                report.status = "skipped"
+                report.message = f"no build command for tech={tech}"
+                return report
+            cmd = list(cmd_list)
+        return self._exec(cmd, report)
+
+    def _exec(self, cmd: list[str], report: StepReport) -> StepReport:
+        try:
+            result = subprocess.run(
+                cmd,
+                cwd=str(self.repo),
+                capture_output=True,
+                text=True,
+                timeout=300,
+            )
+            if result.returncode == 0:
+                report.status = "ok"
+                report.message = f"{' '.join(cmd)} succeeded"
+            else:
+                report.status = "failed"
+                report.message = result.stderr[:2000] or result.stdout[:2000]
+        except FileNotFoundError:
+            report.status = "failed"
+            report.message = f"command not found: {cmd[0]}"
+        except subprocess.TimeoutExpired:
+            report.status = "failed"
+            report.message = f"timeout after 300s: {' '.join(cmd)}"
+        return report

sendsprint/agents/lint_runner.py

@@ -0,0 +1,91 @@
+"""LintRunner: runs linting per tech stack."""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+
+from ..models.reports import StepReport
+from ..tech import TechFingerprint
+
+logger = logging.getLogger(__name__)
+
+LINT_COMMANDS: dict[str, list[str]] = {
+    "angular": ["npx", "ng", "lint"],
+    "react": ["npx", "eslint", ".", "--max-warnings=0"],
+    "nextjs": ["npx", "eslint", ".", "--max-warnings=0"],
+    "vue": ["npx", "eslint", ".", "--max-warnings=0"],
+    "nestjs": ["npx", "eslint", ".", "--max-warnings=0"],
+    "node": ["npx", "eslint", "."],
+    "dotnet": ["dotnet", "format", "--verify-no-changes"],
+    "spring": ["mvn", "checkstyle:check"],
+    "java": ["mvn", "checkstyle:check"],
+    "python": ["ruff", "check", "."],
+    "django": ["ruff", "check", "."],
+    "fastapi": ["ruff", "check", "."],
+    "flask": ["ruff", "check", "."],
+    "go": ["golangci-lint", "run"],
+    "rust": ["cargo", "clippy", "--", "-D", "warnings"],
+    "flutter": ["dart", "analyze"],
+    "ruby": ["bundle", "exec", "rubocop"],
+    "php": ["vendor/bin/phpcs"],
+    "laravel": ["vendor/bin/phpcs"],
+}
+
+
+class LintRunner:
+    """Runs linting for a repo based on its tech fingerprint."""
+
+    def __init__(
+        self,
+        repo_path: str | Path,
+        fingerprint: TechFingerprint,
+        *,
+        custom_command: str | None = None,
+    ) -> None:
+        self.repo = Path(repo_path).resolve()
+        self.fp = fingerprint
+        self.custom_command = custom_command
+
+    def run(self) -> StepReport:
+        report = StepReport(step=4, name="lint", repo=str(self.repo))
+        report.started_at = datetime.now(tz=UTC)
+        report.status = "running"
+
+        if self.custom_command:
+            cmd = self.custom_command.split()
+        else:
+            tech = self.fp.primary_tech
+            cmd_list = LINT_COMMANDS.get(tech) if tech else None
+            if not cmd_list:
+                report.status = "skipped"
+                report.message = f"no lint command for tech={tech}"
+                report.finished_at = datetime.now(tz=UTC)
+                return report
+            cmd = list(cmd_list)
+
+        try:
+            result = subprocess.run(
+                cmd,
+                cwd=str(self.repo),
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+            if result.returncode == 0:
+                report.status = "ok"
+                report.message = f"{' '.join(cmd)} passed"
+            else:
+                report.status = "failed"
+                report.message = result.stdout[:2000] or result.stderr[:2000]
+        except FileNotFoundError:
+            report.status = "skipped"
+            report.message = f"linter not installed: {cmd[0]}"
+        except subprocess.TimeoutExpired:
+            report.status = "failed"
+            report.message = f"timeout after 120s: {' '.join(cmd)}"
+
+        report.finished_at = datetime.now(tz=UTC)
+        return report

sendsprint/agents/pr_body_builder.py

@@ -0,0 +1,122 @@
+"""PrBodyBuilder: composes rich PR body with evidence + AC + DoD checklist."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sendsprint.models import Sprint, SprintItem
+from sendsprint.models.reports import StepReport
+
+
+def _evidence_for_repo(steps: list[StepReport], repo: str) -> list[str]:
+    lines: list[str] = []
+    for s in steps:
+        if s.repo != repo:
+            continue
+        for ev in s.evidence:
+            mark = "✓" if ev.passed else "✗"
+            loc = f" — `{ev.path}`" if ev.path else ""
+            lines.append(f"- {mark} [{ev.kind}] {ev.title}{loc}")
+    return lines
+
+
+def _findings_for_repo(steps: list[StepReport], repo: str) -> list[str]:
+    lines: list[str] = []
+    for s in steps:
+        if s.repo != repo:
+            continue
+        for f in s.findings:
+            where = f"{f.file}:{f.line}" if f.file and f.line else (f.file or "—")
+            lines.append(f"- [{f.severity}] `{f.rule}` @ {where} — {f.message}")
+    return lines
+
+
+def _step_status_table(steps: list[StepReport], repo: str) -> str:
+    rows = [
+        f"| {s.step} | {s.name} | {s.status} | {(s.message or '')[:80]} |"
+        for s in steps
+        if s.repo == repo or s.repo is None
+    ]
+    if not rows:
+        return "_(no steps recorded)_"
+    header = "| # | Step | Status | Message |\n|---|------|--------|---------|"
+    return header + "\n" + "\n".join(rows)
+
+
+def _item_lines(items: list[SprintItem]) -> str:
+    if not items:
+        return "_(no items in scope)_"
+    return "\n".join(
+        f"- `{i.key}` — {i.title} ({i.type}, {i.status})"
+        + (f" → {i.source_url}" if i.source_url else "")
+        for i in items
+    )
+
+
+class PrBodyBuilder:
+    """Compose PR markdown body with sprint context + evidence + DoD."""
+
+    def __init__(self, repo_root: Path) -> None:
+        self.repo_root = Path(repo_root)
+
+    def build(
+        self,
+        sprint: Sprint,
+        repo_name: str,
+        steps: list[StepReport],
+        sprint_slug: str | None = None,
+    ) -> str:
+        evidence = _evidence_for_repo(steps, repo_name)
+        findings = _findings_for_repo(steps, repo_name)
+        status_table = _step_status_table(steps, repo_name)
+        items_block = _item_lines(sprint.items)
+        slug = sprint_slug or f"sprint-{sprint.id}"
+        evidence_block = "\n".join(evidence) if evidence else "_(no evidence captured)_"
+        findings_block = "\n".join(findings) if findings else "_(none)_"
+
+        return f"""## Summary
+
+Automated PR generated by **SendSprint** for sprint `{sprint.name}` ({sprint.source}).
+
+- Sprint ID: `{sprint.id}`
+- Source: `{sprint.source}` via transport `{sprint.transport}`
+- Items in scope: {len(sprint.items)}
+- Repo: `{repo_name}`
+
+## Sprint items
+
+{items_block}
+
+## Step report
+
+{status_table}
+
+## Evidence
+
+{evidence_block}
+
+## Security findings (flag-only, ADR-005)
+
+{findings_block}
+
+## Definition of Done
+
+- [ ] Sprint specs imported under `.specs/sprints/{slug}/`
+- [ ] Lint green
+- [ ] Unit tests green
+- [ ] E2E Playwright green with screenshots/traces
+- [ ] Coverage diff ≥ 80%
+- [ ] Security scan: zero findings or accepted exceptions documented
+- [ ] CHANGELOG updated if release-relevant
+- [ ] ADR opened if architectural decision
+
+## Links
+
+- Sprint spec: `.specs/sprints/{slug}/SPRINT.md`
+- DoD workflow: `.github/workflows/dod.yml`
+- Source sprint: {sprint.name}
+
+---
+
+Generated by SendSprint — see `skills/claude/SKILL.md` for orchestration flow.
+"""