taskill 0.1.1__py3-none-any.whl

taskill/__init__.py

@@ -0,0 +1,20 @@
+"""taskill — daily project hygiene automation.
+
+Keeps README.md / CHANGELOG.md / TODO.md in sync with reality:
+- reads git log, SUMD.md, SUMR.md, test results, coverage
+- moves completed TODO items to CHANGELOG
+- regenerates README sections that are out of date
+- runs daily (or per metric thresholds) standalone, in CI, or via Ansible
+
+Provider chain (first match wins):
+1. Windsurf MCP   (when configured — uses your existing JetBrains plugin context)
+2. OpenRouter     (LLM via OPENROUTER_API_KEY + LLM_MODEL)
+3. Algorithmic    (deterministic fallback: conventional commits + heuristics)
+"""
+
+__version__ = "0.1.1"
+
+from taskill.config import TaskillConfig, load_config
+from taskill.core import Taskill, TaskillResult
+
+__all__ = ["TaskillConfig", "load_config", "Taskill", "TaskillResult", "__version__"]

taskill/cli.py

@@ -0,0 +1,253 @@
+"""Command-line interface for taskill.
+
+Commands:
+  taskill run        — execute the pipeline (respects triggers; --force overrides)
+  taskill status     — show what would happen without running
+  taskill init       — write a starter taskill.yaml + .env.example
+  taskill release    — promote [Unreleased] CHANGELOG block to a versioned heading
+  taskill clean-todo — wipe TODO.md (use after manually moving items elsewhere)
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from taskill import __version__
+from taskill.config import load_config
+from taskill.core import Taskill
+from taskill.updaters.changelog import release_unreleased
+from taskill.updaters.todo import empty_todo
+
+console = Console()
+
+
+def _setup_logging(verbose: bool) -> None:
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+@click.group()
+@click.version_option(__version__, prog_name="taskill")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose logging")
+@click.option(
+    "--config", "-c", default="taskill.yaml", show_default=True,
+    help="Path to taskill.yaml",
+)
+@click.pass_context
+def main(ctx: click.Context, verbose: bool, config: str) -> None:
+    """taskill — keep README/CHANGELOG/TODO honest."""
+    _setup_logging(verbose)
+    ctx.ensure_object(dict)
+    ctx.obj["config_path"] = config
+
+
+@main.command()
+@click.option("--force", is_flag=True, help="Run even if triggers say no")
+@click.option("--dry-run", is_flag=True, help="Don't write files or persist state")
+@click.option("--json", "as_json", is_flag=True, help="Output result as JSON")
+@click.pass_context
+def run(ctx: click.Context, force: bool, dry_run: bool, as_json: bool) -> None:
+    """Execute the update pipeline."""
+    cfg = load_config(ctx.obj["config_path"])
+    if dry_run:
+        cfg.dry_run = True
+    tk = Taskill(config=cfg)
+    result = tk.run(force=force)
+
+    if as_json:
+        click.echo(json.dumps(result.as_dict(), indent=2))
+        sys.exit(0 if result.ran or not result.errors else 1)
+
+    if not result.ran:
+        console.print(f"[yellow]✗ Did not run.[/yellow] {result.trigger_eval.summary()}")
+        if result.errors:
+            for e in result.errors:
+                console.print(f"  [red]error:[/red] {e}")
+        sys.exit(0)
+
+    console.print(
+        f"[green]✓ Ran via [bold]{result.provider_used}[/bold][/green]"
+    )
+    if result.docs and result.docs.summary:
+        console.print(f"  [dim]{result.docs.summary}[/dim]")
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_row("Changelog entries", str(len(result.docs.changelog_entries) if result.docs else 0))
+    table.add_row("TODO completed", str(len(result.docs.todo_completed) if result.docs else 0))
+    table.add_row("TODO new", str(len(result.docs.todo_new) if result.docs else 0))
+    table.add_row("Files changed", ", ".join(result.files_changed) or "(none)")
+    console.print(table)
+
+    if result.errors:
+        console.print("[dim]Provider fallthrough:[/dim]")
+        for e in result.errors:
+            console.print(f"  [dim]- {e}[/dim]")
+
+
+@main.command()
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.pass_context
+def status(ctx: click.Context, as_json: bool) -> None:
+    """Show what taskill would do without running it."""
+    cfg = load_config(ctx.obj["config_path"])
+    tk = Taskill(config=cfg)
+    info = tk.status()
+
+    if as_json:
+        click.echo(json.dumps(info, indent=2, default=str))
+        return
+
+    table = Table(title="taskill status", show_header=True, header_style="bold cyan")
+    table.add_column("Field"); table.add_column("Value")
+    color = "green" if info["would_run"] else "yellow"
+    table.add_row("Would run?", f"[{color}]{info['would_run']}[/{color}]")
+    table.add_row("HEAD", str(info["head"] or "—")[:12])
+    table.add_row("Pending commits", str(info["commits_pending"]))
+    table.add_row("Coverage", f"{info['coverage']:.1f}%" if info["coverage"] else "—")
+    table.add_row("Failed tests", str(info["failed_tests"]) if info["failed_tests"] is not None else "—")
+    table.add_row("Last run", str(info["last_run"] or "never"))
+    console.print(table)
+
+    if info["reasons"]:
+        console.print("[green]Reasons to run:[/green]")
+        for r in info["reasons"]:
+            console.print(f"  • {r}")
+    if info["skipped_because"]:
+        console.print("[yellow]Why not running:[/yellow]")
+        for r in info["skipped_because"]:
+            console.print(f"  • {r}")
+
+
+@main.command()
+@click.option("--force", is_flag=True, help="Overwrite existing taskill.yaml")
+def init(force: bool) -> None:
+    """Generate a starter taskill.yaml + .env.example in the current directory."""
+    yml = Path("taskill.yaml")
+    env = Path(".env.example")
+
+    if yml.exists() and not force:
+        console.print(f"[yellow]{yml} already exists — use --force to overwrite[/yellow]")
+        sys.exit(1)
+
+    yml.write_text(STARTER_YAML, encoding="utf-8")
+    if not env.exists():
+        env.write_text(STARTER_ENV, encoding="utf-8")
+
+    console.print(f"[green]✓[/green] Wrote {yml} and {env}")
+    console.print("Next: copy [bold].env.example[/bold] → [bold].env[/bold] and add your OpenRouter key,")
+    console.print("then run [cyan]taskill status[/cyan] to inspect, [cyan]taskill run[/cyan] to execute.")
+
+
+@main.command()
+@click.argument("version")
+@click.option(
+    "--changelog", default="CHANGELOG.md", show_default=True,
+    help="Path to CHANGELOG.md",
+)
+def release(version: str, changelog: str) -> None:
+    """Promote [Unreleased] section to a versioned [VERSION] heading."""
+    p = Path(changelog)
+    if release_unreleased(p, version):
+        console.print(f"[green]✓[/green] Released v{version} in {p}")
+    else:
+        console.print(f"[yellow]Nothing to release in {p}[/yellow]")
+        sys.exit(1)
+
+
+@main.command("clean-todo")
+@click.option("--todo", default="TODO.md", show_default=True)
+@click.confirmation_option(prompt="This will erase TODO.md content. Continue?")
+def clean_todo(todo: str) -> None:
+    """Reset TODO.md to an empty header. Use after a release."""
+    empty_todo(Path(todo))
+    console.print(f"[green]✓[/green] {todo} reset")
+
+
+# ─── starter templates ──────────────────────────────────────────────────
+
+STARTER_YAML = """# taskill.yaml — daily project hygiene config
+# Run: taskill status   (preview)
+#      taskill run      (execute when triggers fire)
+#      taskill run --force --dry-run   (preview the actual output)
+
+# Files taskill manages
+files:
+  readme: README.md
+  changelog: CHANGELOG.md
+  todo: TODO.md
+  sumd: SUMD.md
+  sumr: SUMR.md
+
+# When should taskill run?  (OR semantics by default — any one true → run)
+triggers:
+  min_hours_since_last_run: 24
+  min_commits_since_last_run: 1
+  changed_files_threshold: 1
+  coverage_change_pct: 2.0      # absolute pp; null to disable
+  failed_tests_changed: true
+  watch_files: [SUMD.md, SUMR.md]
+  require_all: false            # set true for AND semantics
+
+# Provider chain — first one that succeeds wins.
+# Comment out any provider you don't want.
+providers:
+  - name: windsurf_mcp
+    enabled: true
+    options:
+      endpoint: stdio
+      command: ["windsurf", "mcp", "serve"]
+      tool_name: complete
+  - name: openrouter
+    enabled: true
+    options:
+      base_url: https://openrouter.ai/api/v1
+      temperature: 0.2
+      max_tokens: 4096
+      timeout: 120
+  - name: algorithmic
+    enabled: true     # always-on safety net; keep this on
+
+# Optional: reuse other tools in your stack (loose coupling — subprocess calls)
+reuse:
+  pyqual: true
+  llx: false
+  prefact: false
+
+# Where state lives (tracks last run, last sha, last coverage…)
+state_file: .taskill/state.json
+
+# CI/VCS integrations — read by `taskill ci-config` (stub for now)
+integrations:
+  github: {}
+  gitlab: {}
+  ansible: {}
+
+dry_run: false
+"""
+
+STARTER_ENV = """# Copy this file to .env and fill in your credentials.
+# .env is loaded automatically by taskill (process env wins on conflict).
+
+OPENROUTER_API_KEY=
+
+# Default: openrouter/qwen/qwen3-coder-next
+# (taskill auto-strips the openrouter/ prefix for the OpenRouter REST API)
+LLM_MODEL=openrouter/qwen/qwen3-coder-next
+
+# Optional: explicit Windsurf MCP endpoint (otherwise auto-discovered)
+# WINDSURF_MCP_ENDPOINT=ws://localhost:7777
+"""
+
+
+if __name__ == "__main__":
+    main()

taskill/config.py

@@ -0,0 +1,170 @@
+"""Config loading: taskill.yaml + .env.
+
+Mirrors pyqual's config style (declarative, YAML-first, profile-friendly).
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+from dotenv import load_dotenv
+
+
+# ───────────────────────────── data classes ─────────────────────────────
+
+@dataclass
+class Triggers:
+    """Conditions that must be met to run an update.
+
+    All thresholds are OR-ed by default (any one true → run).
+    Set `require_all: true` for AND semantics.
+    """
+    min_hours_since_last_run: float = 24.0
+    min_commits_since_last_run: int = 1
+    changed_files_threshold: int = 1
+    coverage_change_pct: float | None = None
+    failed_tests_changed: bool = False
+    require_all: bool = False
+    # File-mtime triggers (optional)
+    watch_files: list[str] = field(default_factory=lambda: ["SUMD.md", "SUMR.md"])
+
+
+@dataclass
+class ProviderConfig:
+    """Single provider configuration."""
+    name: str  # "windsurf_mcp" | "openrouter" | "algorithmic"
+    enabled: bool = True
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class IntegrationConfig:
+    """Optional CI / VCS / orchestrator integration."""
+    github: dict[str, Any] = field(default_factory=dict)
+    gitlab: dict[str, Any] = field(default_factory=dict)
+    ansible: dict[str, Any] = field(default_factory=dict)
+
+
+DEFAULT_FILES = {
+    "readme": "README.md",
+    "changelog": "CHANGELOG.md",
+    "todo": "TODO.md",
+    "sumd": "SUMD.md",
+    "sumr": "SUMR.md",
+}
+
+DEFAULT_REUSE = {
+    "pyqual": True,    # invoke `pyqual report` if available
+    "llx": False,      # invoke llx for richer LLM context
+    "prefact": False,  # invoke prefact for refactoring hints
+}
+
+
+@dataclass
+class TaskillConfig:
+    project_root: Path
+    files: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_FILES))
+    triggers: Triggers = field(default_factory=Triggers)
+    providers: list[ProviderConfig] = field(default_factory=list)
+    integrations: IntegrationConfig = field(default_factory=IntegrationConfig)
+    state_file: str = ".taskill/state.json"
+    dry_run: bool = False
+    reuse: dict[str, bool] = field(default_factory=lambda: dict(DEFAULT_REUSE))
+
+    @property
+    def env_model(self) -> str:
+        return os.getenv("LLM_MODEL", "openrouter/qwen/qwen3-coder-next")
+
+    @property
+    def env_api_key(self) -> str | None:
+        return os.getenv("OPENROUTER_API_KEY")
+
+
+# ───────────────────────────── loader ─────────────────────────────
+
+DEFAULT_PROVIDERS = [
+    ProviderConfig(name="windsurf_mcp", enabled=True, options={
+        "endpoint": "stdio",  # or ws://localhost:PORT
+        "tool_name": "windsurf",
+    }),
+    ProviderConfig(name="openrouter", enabled=True, options={
+        "base_url": "https://openrouter.ai/api/v1",
+        "temperature": 0.2,
+        "max_tokens": 4096,
+        "timeout": 120,
+    }),
+    ProviderConfig(name="algorithmic", enabled=True, options={}),
+]
+
+
+def load_config(
+    path: str | Path = "taskill.yaml",
+    project_root: Path | None = None,
+) -> TaskillConfig:
+    """Load config from YAML + .env. Missing YAML → defaults.
+
+    Resolution order for project_root:
+      1. explicit arg
+      2. directory of taskill.yaml
+      3. cwd
+    """
+    path = Path(path)
+    if project_root is None:
+        project_root = path.parent.resolve() if path.exists() else Path.cwd()
+
+    # .env has higher priority than process env? No — process env wins (CI-friendly).
+    env_path = project_root / ".env"
+    if env_path.exists():
+        load_dotenv(env_path, override=False)
+
+    raw: dict[str, Any] = {}
+    if path.exists():
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+    # Triggers
+    trig_raw = raw.get("triggers", {})
+    triggers = Triggers(
+        min_hours_since_last_run=trig_raw.get("min_hours_since_last_run", 24.0),
+        min_commits_since_last_run=trig_raw.get("min_commits_since_last_run", 1),
+        changed_files_threshold=trig_raw.get("changed_files_threshold", 1),
+        coverage_change_pct=trig_raw.get("coverage_change_pct"),
+        failed_tests_changed=trig_raw.get("failed_tests_changed", False),
+        require_all=trig_raw.get("require_all", False),
+        watch_files=trig_raw.get("watch_files", ["SUMD.md", "SUMR.md"]),
+    )
+
+    # Providers (preserve order from YAML; if missing, use defaults)
+    providers_raw = raw.get("providers")
+    if providers_raw:
+        providers = [
+            ProviderConfig(
+                name=p["name"],
+                enabled=p.get("enabled", True),
+                options=p.get("options", {}),
+            )
+            for p in providers_raw
+        ]
+    else:
+        providers = DEFAULT_PROVIDERS
+
+    # Integrations
+    integ_raw = raw.get("integrations", {})
+    integrations = IntegrationConfig(
+        github=integ_raw.get("github", {}),
+        gitlab=integ_raw.get("gitlab", {}),
+        ansible=integ_raw.get("ansible", {}),
+    )
+
+    return TaskillConfig(
+        project_root=Path(raw.get("project_root", project_root)).resolve(),
+        files={**DEFAULT_FILES, **raw.get("files", {})},
+        triggers=triggers,
+        providers=providers,
+        integrations=integrations,
+        state_file=raw.get("state_file", ".taskill/state.json"),
+        dry_run=raw.get("dry_run", False),
+        reuse={**DEFAULT_REUSE, **raw.get("reuse", {})},
+    )

taskill/core.py

@@ -0,0 +1,211 @@
+"""Taskill core orchestrator.
+
+Pipeline:
+  1. Load config + state
+  2. Collect snapshot (git + filesystem + optional pyqual report)
+  3. Evaluate triggers — bail if thresholds not met
+  4. Walk provider chain until one succeeds
+  5. Apply updates to README/CHANGELOG/TODO
+  6. Persist new state
+"""
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from taskill.config import TaskillConfig, load_config
+from taskill.git_state import ProjectSnapshot, collect_snapshot
+from taskill.providers import build_chain, GeneratedDocs, ProviderError
+from taskill.state import TaskillState, load_state, save_state
+from taskill.triggers import TriggerEvaluation, evaluate
+from taskill.updaters import update_changelog, update_readme, update_todo
+
+log = logging.getLogger("taskill")
+
+
+@dataclass
+class TaskillResult:
+    ran: bool
+    trigger_eval: TriggerEvaluation
+    provider_used: str | None = None
+    docs: GeneratedDocs | None = None
+    files_changed: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "ran": self.ran,
+            "should_have_run": self.trigger_eval.should_run,
+            "reasons": self.trigger_eval.reasons,
+            "skipped_because": self.trigger_eval.skipped,
+            "provider": self.provider_used,
+            "summary": self.docs.summary if self.docs else "",
+            "changelog_added": len(self.docs.changelog_entries) if self.docs else 0,
+            "todo_completed": len(self.docs.todo_completed) if self.docs else 0,
+            "todo_new": len(self.docs.todo_new) if self.docs else 0,
+            "files_changed": self.files_changed,
+            "errors": self.errors,
+        }
+
+
+class Taskill:
+    def __init__(self, config: TaskillConfig | None = None, config_path: str = "taskill.yaml"):
+        self.config = config or load_config(config_path)
+        self.state_path = self.config.project_root / self.config.state_file
+        self.state = load_state(self.state_path)
+
+    # ── public API ─────────────────────────────────────────────────────
+
+    def run(self, force: bool = False) -> TaskillResult:
+        snapshot = self._snapshot()
+        trig = evaluate(self.config.triggers, self.state, snapshot, self.config.project_root)
+
+        if not (trig.should_run or force):
+            log.info("Skipping: %s", trig.summary())
+            return TaskillResult(ran=False, trigger_eval=trig)
+
+        # build chain — only currently-available providers
+        chain = build_chain(self.config.providers)
+        if not chain:
+            return TaskillResult(
+                ran=False, trigger_eval=trig,
+                errors=["No providers configured"],
+            )
+
+        context = self._build_context(snapshot)
+        docs: GeneratedDocs | None = None
+        used: str | None = None
+        errors: list[str] = []
+
+        for provider in chain:
+            if not provider.is_available():
+                log.info("Provider %s unavailable, skipping", provider.name)
+                continue
+            try:
+                log.info("Trying provider: %s", provider.name)
+                docs = provider.generate(context)
+                used = docs.provider_name or provider.name
+                break
+            except ProviderError as e:
+                msg = f"{provider.name}: {e}"
+                log.warning(msg)
+                errors.append(msg)
+                continue
+
+        if docs is None:
+            return TaskillResult(
+                ran=False, trigger_eval=trig,
+                errors=errors or ["All providers failed or unavailable"],
+            )
+
+        # apply updates
+        files_changed: list[str] = []
+        if not self.config.dry_run:
+            files_changed = self._apply(docs, snapshot)
+            self._update_state(snapshot)
+            save_state(self.state_path, self.state)
+        else:
+            log.info("Dry-run: not writing files or state")
+
+        return TaskillResult(
+            ran=True,
+            trigger_eval=trig,
+            provider_used=used,
+            docs=docs,
+            files_changed=files_changed,
+            errors=errors,  # non-fatal failures from providers we skipped past
+        )
+
+    def status(self) -> dict[str, Any]:
+        """Inspect current trigger state without running anything."""
+        snapshot = self._snapshot()
+        trig = evaluate(self.config.triggers, self.state, snapshot, self.config.project_root)
+        return {
+            "would_run": trig.should_run,
+            "reasons": trig.reasons,
+            "skipped_because": trig.skipped,
+            "head": snapshot.head_sha,
+            "commits_pending": len(snapshot.commits_since_last_run),
+            "coverage": snapshot.coverage_pct,
+            "failed_tests": snapshot.failed_tests,
+            "last_run": self.state.last_run_iso,
+        }
+
+    # ── internals ──────────────────────────────────────────────────────
+
+    def _snapshot(self) -> ProjectSnapshot:
+        return collect_snapshot(
+            self.config.project_root,
+            self.config.files,
+            self.state.last_commit_sha,
+        )
+
+    def _build_context(self, snapshot: ProjectSnapshot) -> dict[str, Any]:
+        root = self.config.project_root
+
+        def _read(name: str) -> str:
+            p = root / self.config.files.get(name, f"{name.upper()}.md")
+            return p.read_text(encoding="utf-8") if p.exists() else ""
+
+        ctx: dict[str, Any] = {
+            "snapshot": snapshot,
+            "existing_readme": _read("readme"),
+            "existing_changelog": _read("changelog"),
+            "existing_todo": _read("todo"),
+            "sumd": snapshot.sumd_text,
+            "sumr": snapshot.sumr_text,
+            "project_name": root.name,
+        }
+
+        # optional: enrich with pyqual report (loose coupling — subprocess)
+        if self.config.reuse.get("pyqual"):
+            ctx["pyqual_report"] = self._maybe_pyqual_report()
+
+        return ctx
+
+    def _maybe_pyqual_report(self) -> dict[str, Any] | None:
+        """Run `pyqual report --json` if pyqual is on PATH. Tolerate failure."""
+        try:
+            res = subprocess.run(
+                ["pyqual", "report", "--json"],
+                cwd=self.config.project_root,
+                capture_output=True, text=True, timeout=30, check=False,
+            )
+            if res.returncode == 0 and res.stdout.strip():
+                return json.loads(res.stdout)
+        except (FileNotFoundError, subprocess.TimeoutExpired, json.JSONDecodeError):
+            pass
+        return None
+
+    def _apply(self, docs: GeneratedDocs, snapshot: ProjectSnapshot) -> list[str]:
+        root = self.config.project_root
+        changed: list[str] = []
+
+        cl = root / self.config.files["changelog"]
+        if update_changelog(cl, docs.changelog_entries):
+            changed.append(str(cl.relative_to(root)))
+
+        td = root / self.config.files["todo"]
+        if update_todo(td, docs.todo_completed, docs.todo_new):
+            changed.append(str(td.relative_to(root)))
+
+        rm = root / self.config.files["readme"]
+        if update_readme(rm, snapshot, docs.summary):
+            changed.append(str(rm.relative_to(root)))
+
+        return changed
+
+    def _update_state(self, snapshot: ProjectSnapshot) -> None:
+        self.state.stamp()
+        self.state.last_commit_sha = snapshot.head_sha
+        self.state.last_coverage_pct = snapshot.coverage_pct
+        self.state.last_failed_tests = snapshot.failed_tests
+        self.state.last_sumd_hash = snapshot.sumd_hash
+        for rel in self.config.triggers.watch_files:
+            p = self.config.project_root / rel
+            if p.exists():
+                self.state.file_mtimes[rel] = p.stat().st_mtime