MertCapkin-GraphStack 4.5.1__py3-none-any.whl

graphstack/board.py

@@ -0,0 +1,361 @@
+"""GNAP board manager — pure Python port of ``scripts/board.sh``.
+
+JSON schema is preserved verbatim so existing ``handoff/board/*.json`` files
+created under v3.0.0 continue to work without migration.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .constants import BOARD_DIR, DOING_DIR, DONE_DIR, TODO_DIR
+from .platform_utils import echo, run_git, utc_now_iso
+
+VALID_ROLES = ("architect", "builder", "reviewer", "qa", "ship", "bootstrapper")
+
+
+def _load_task(path: Path) -> dict:
+    with path.open(encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _save_task(path: Path, data: dict) -> None:
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def _get(data: dict, key: str) -> str:
+    value = data.get(key)
+    if value in (None, ""):
+        return "-"
+    return str(value)
+
+
+def _print_task(path: Path) -> None:
+    try:
+        data = _load_task(path)
+    except (OSError, json.JSONDecodeError):
+        echo(f"  ! could not read {path.name}")
+        return
+    echo(
+        f"  {_get(data, 'id'):<32} {_get(data, 'status'):<10} "
+        f"{_get(data, 'assigned_to'):<12} {_get(data, 'title')}"
+    )
+
+
+def _iter_tasks(directory: Path) -> list[Path]:
+    if not directory.is_dir():
+        return []
+    return sorted(directory.glob("*.json"))
+
+
+def _git_commit_board(message: str) -> None:
+    """Stage the board directory and commit silently — never fails the command."""
+    run_git("add", str(BOARD_DIR))
+    run_git("commit", "-m", message)
+
+
+def cmd_status(_args: argparse.Namespace) -> int:
+    echo("")
+    echo("📋 GraphStack GNAP Board")
+    echo("=" * 56)
+    echo(f"  {'TASK ID':<32} {'STATUS':<10} {'ASSIGNED':<12} TITLE")
+    echo("  " + "-" * 54)
+
+    todo = _iter_tasks(TODO_DIR)
+    doing = _iter_tasks(DOING_DIR)
+    done = _iter_tasks(DONE_DIR)
+
+    for f in todo + doing + done:
+        _print_task(f)
+
+    if not (todo or doing or done):
+        echo("  (no tasks yet)")
+
+    echo("")
+    echo(f"  Todo: {len(todo)}  |  In Progress: {len(doing)}  |  Done: {len(done)}")
+    echo("")
+    return 0
+
+
+def cmd_new(args: argparse.Namespace) -> int:
+    task_id: str = args.task_id
+    title = " ".join(args.title) if args.title else "New task"
+
+    TODO_DIR.mkdir(parents=True, exist_ok=True)
+    dst = TODO_DIR / f"{task_id}.json"
+    if dst.exists():
+        echo(f"❌ Task '{task_id}' already exists in todo/")
+        return 1
+
+    task = {
+        "id": task_id,
+        "title": title,
+        "created_at": utc_now_iso(),
+        "created_by": "architect",
+        "brief": "handoff/BRIEF.md",
+        "graph_nodes": [],
+        "criteria_count": 0,
+        "priority": "normal",
+        "status": "todo",
+        "assigned_to": None,
+        "started_at": None,
+        "completed_at": None,
+        "notes": "",
+    }
+    _save_task(dst, task)
+    _git_commit_board(f"board: new task {task_id} — {title}")
+
+    echo(f"✅ Task '{task_id}' created in todo/")
+    echo(f"   Title: {title}")
+    return 0
+
+
+def cmd_claim(args: argparse.Namespace) -> int:
+    task_id: str = args.task_id
+    role: str = args.role.lower()
+
+    if role not in VALID_ROLES:
+        echo(f"⚠️  Unknown role '{role}'. Continuing anyway "
+             f"(expected one of: {', '.join(VALID_ROLES)})")
+
+    src = TODO_DIR / f"{task_id}.json"
+    dst = DOING_DIR / f"{task_id}.json"
+
+    if not src.exists():
+        existing = DOING_DIR / f"{task_id}.json"
+        if existing.exists():
+            current_role = _load_task(existing).get("assigned_to") or "?"
+            echo(f"⚠️  Task '{task_id}' is already in doing/ "
+                 f"(claimed by {current_role})")
+            return 0
+        if (DONE_DIR / f"{task_id}.json").exists():
+            echo(f"⚠️  Task '{task_id}' is already done.")
+            return 0
+        echo(f"❌ Task '{task_id}' not found in todo/")
+        echo("   Run: python -m graphstack board status")
+        return 1
+
+    data = _load_task(src)
+    data["status"] = "doing"
+    data["assigned_to"] = role
+    data["started_at"] = utc_now_iso()
+    _save_task(src, data)
+
+    DOING_DIR.mkdir(parents=True, exist_ok=True)
+    src.replace(dst)
+
+    _git_commit_board(f"board: {role} claims {task_id}")
+    echo(f"✅ Task '{task_id}' claimed by {role}")
+    return 0
+
+
+def cmd_complete(args: argparse.Namespace) -> int:
+    task_id: str = args.task_id
+
+    src = DOING_DIR / f"{task_id}.json"
+    dst = DONE_DIR / f"{task_id}.json"
+
+    if not src.exists():
+        if (DONE_DIR / f"{task_id}.json").exists():
+            echo(f"⚠️  Task '{task_id}' is already done.")
+            return 0
+        echo(f"❌ Task '{task_id}' not found in doing/")
+        echo("   Run: python -m graphstack board status")
+        return 1
+
+    data = _load_task(src)
+    data["status"] = "done"
+    data["completed_at"] = utc_now_iso()
+    _save_task(src, data)
+
+    DONE_DIR.mkdir(parents=True, exist_ok=True)
+    src.replace(dst)
+
+    _git_commit_board(f"board: complete {task_id}")
+    echo(f"✅ Task '{task_id}' marked complete")
+    return 0
+
+
+def cmd_list_done(args: argparse.Namespace) -> int:
+    limit = args.limit
+    done = _iter_tasks(DONE_DIR)
+    if not done:
+        echo("")
+        echo("📋 Done tasks: (none)")
+        echo("")
+        return 0
+
+    if limit is not None and limit > 0:
+        done = done[-limit:]
+
+    echo("")
+    echo("📋 Done tasks")
+    echo("=" * 56)
+    echo(f"  {'TASK ID':<32} {'COMPLETED':<22} TITLE")
+    echo("  " + "-" * 54)
+    for path in done:
+        try:
+            data = _load_task(path)
+        except (OSError, json.JSONDecodeError):
+            echo(f"  ! could not read {path.name}")
+            continue
+        completed = _get(data, "completed_at")
+        echo(f"  {_get(data, 'id'):<32} {completed:<22} {_get(data, 'title')}")
+    echo("")
+    echo(f"  Showing {len(done)} task(s)")
+    echo("")
+    return 0
+
+
+def cmd_reopen(args: argparse.Namespace) -> int:
+    task_id: str = args.task_id
+    dest = args.to.lower()
+
+    if dest not in ("todo", "doing"):
+        echo(f"❌ Invalid destination '{dest}'. Use: todo or doing")
+        return 1
+
+    src_done = DONE_DIR / f"{task_id}.json"
+    src_doing = DOING_DIR / f"{task_id}.json"
+    src_todo = TODO_DIR / f"{task_id}.json"
+
+    if src_todo.exists():
+        echo(f"⚠️  Task '{task_id}' is already in todo/")
+        return 0
+
+    if src_doing.exists() and dest == "doing":
+        echo(f"⚠️  Task '{task_id}' is already in doing/")
+        return 0
+
+    src: Path | None = None
+    if src_done.exists():
+        src = src_done
+    elif src_doing.exists() and dest == "todo":
+        src = src_doing
+    else:
+        echo(f"❌ Task '{task_id}' not found in done/ (or doing/ for todo reopen)")
+        echo("   Run: python -m graphstack board list-done")
+        return 1
+
+    data = _load_task(src)
+    data["status"] = dest
+    data["completed_at"] = None
+    if dest == "todo":
+        data["assigned_to"] = None
+        data["started_at"] = None
+    elif data.get("started_at") is None:
+        data["started_at"] = utc_now_iso()
+
+    dst_dir = TODO_DIR if dest == "todo" else DOING_DIR
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    dst = dst_dir / f"{task_id}.json"
+    _save_task(dst, data)
+    src.unlink()
+
+    _git_commit_board(f"board: reopen {task_id} -> {dest}")
+    echo(f"✅ Task '{task_id}' reopened to {dest}/")
+    return 0
+
+
+def cmd_log(_args: argparse.Namespace) -> int:
+    echo("")
+    echo("📜 Board History")
+    result = run_git("log", "--oneline", "--", str(BOARD_DIR))
+    if result.returncode == 0 and result.stdout.strip():
+        echo(result.stdout.rstrip())
+    else:
+        echo("(no git history yet — initialize with: git init)")
+    echo("")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="graphstack board",
+        description="GNAP board: todo → doing → done lifecycle.",
+    )
+    sub = p.add_subparsers(dest="action", required=True)
+
+    sub.add_parser("status", help="show full board status")
+
+    p_new = sub.add_parser("new", help="create a new task in todo/")
+    p_new.add_argument("task_id")
+    p_new.add_argument("title", nargs="*", help="task title (no quotes needed)")
+
+    p_claim = sub.add_parser("claim", help="move task from todo → doing")
+    p_claim.add_argument("task_id")
+    p_claim.add_argument("role")
+
+    p_complete = sub.add_parser("complete", help="move task from doing → done")
+    p_complete.add_argument("task_id")
+
+    p_reopen = sub.add_parser("reopen", help="move task from done/ back to todo/ or doing/")
+    p_reopen.add_argument("task_id")
+    p_reopen.add_argument(
+        "--to",
+        default="todo",
+        choices=("todo", "doing"),
+        help="destination column (default: todo)",
+    )
+
+    p_list_done = sub.add_parser("list-done", help="list completed tasks only")
+    p_list_done.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="show only the last N completed tasks",
+    )
+
+    sub.add_parser("log", help="show git history of board changes")
+
+    return p
+
+
+def _print_help() -> None:
+    echo("")
+    echo("GraphStack Board — Commands:")
+    echo("  status                             show full board")
+    echo("  new <id> <title words...>          create task (no quotes needed)")
+    echo("  claim <id> <role>                  claim task (builder/reviewer/qa)")
+    echo("  complete <id>                      mark done")
+    echo("  reopen <id> [--to todo|doing]      move done task back to todo/doing")
+    echo("  list-done [--limit N]              list completed tasks only")
+    echo("  log                                git history of board")
+    echo("")
+    echo("Examples:")
+    echo("  python -m graphstack board new add-rate-limit Add rate limiting to login")
+    echo("  python -m graphstack board claim add-rate-limit builder")
+    echo("  python -m graphstack board complete add-rate-limit")
+    echo("")
+
+
+_DISPATCH = {
+    "status": cmd_status,
+    "new": cmd_new,
+    "claim": cmd_claim,
+    "complete": cmd_complete,
+    "reopen": cmd_reopen,
+    "list-done": cmd_list_done,
+    "log": cmd_log,
+}
+
+
+def run(argv: list[str]) -> int:
+    if not argv or argv[0] in ("help", "-h", "--help"):
+        _print_help()
+        return 0
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as e:
+        return int(e.code) if isinstance(e.code, int) else 2
+    return _DISPATCH[args.action](args)
+
+
+if __name__ == "__main__":
+    sys.exit(run(sys.argv[1:]))

graphstack/bootstrap.py

@@ -0,0 +1,50 @@
+"""Dependency bootstrap helpers for one-shot ``graphstack init``."""
+
+from __future__ import annotations
+
+import subprocess
+
+from .platform_utils import echo, find_python, graphify_available
+
+# PyPI distribution name (``graphstack`` was taken). CLI command remains ``graphstack``.
+PIP_SPEC = "MertCapkin_GraphStack[graphify]"
+PIP_SPEC_GIT = (
+    "MertCapkin_GraphStack[graphify] @ git+https://github.com/MertCapkin/GraphStack.git"
+)
+
+
+def pip_install(*specs: str, quiet: bool = True) -> int:
+    """Install packages with the same Python running graphstack."""
+    if not specs:
+        return 0
+    cmd = [*find_python(), "-m", "pip", "install", "--upgrade"]
+    if quiet:
+        cmd.append("--quiet")
+    cmd.extend(specs)
+    echo(f"  pip install {' '.join(specs)}")
+    return subprocess.run(cmd, check=False).returncode
+
+
+def ensure_graphify(*, install: bool = True) -> bool:
+    if graphify_available():
+        return True
+    if not install:
+        return False
+    echo("")
+    echo("Installing Graphify (graphifyy)...")
+    rc = pip_install("graphifyy>=0.7,<0.9")
+    return rc == 0 and graphify_available()
+
+
+def ensure_graphstack_from_git() -> int:
+    """Fallback when PyPI package is not published yet."""
+    echo("Trying GitHub install (PyPI fallback)...")
+    return pip_install(PIP_SPEC_GIT)
+
+
+def run_graphify_cursor_install() -> int:
+    if not graphify_available():
+        return 1
+    cmd = [*find_python(), "-m", "graphify", "cursor", "install"]
+    proc = subprocess.run(cmd, check=False)
+    return proc.returncode

graphstack/cli.py

@@ -0,0 +1,99 @@
+"""Top-level CLI dispatcher.
+
+Ten sub-commands:
+- ``board``     — GNAP task board manager (replaces ``scripts/board.sh``)
+- ``install``   — install GraphStack into a target project (replaces ``install.sh``)
+- ``init``      — one-shot install + graph refresh + doctor
+- ``hook``      — post-commit graph-update logic (replaces ``scripts/post-commit``)
+- ``validate``  — check handoff layout, brief, board tasks, graph freshness
+- ``doctor``    — human-friendly health report (same checks as validate)
+- ``run``       — execute shell commands with token-safe output compaction
+- ``gate``      — deterministic process gate (check / cursor hook / claude hook)
+- ``state``     — machine-readable session state (handoff/STATE.json)
+- ``graph``     — graphify query wrappers (query / path / explain / update)
+
+Each sub-command parses its own arguments to keep the dispatcher minimal.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="graphstack",
+        description="GraphStack cross-platform helper (board / install / hook / validate / doctor / run).",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"graphstack {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("board", help="GNAP board commands", add_help=False)
+    sub.add_parser("install", help="Install GraphStack into a project", add_help=False)
+    sub.add_parser("init", help="Install + graph refresh + doctor", add_help=False)
+    sub.add_parser("hook", help="Run the post-commit hook logic", add_help=False)
+    sub.add_parser("validate", help="Validate handoff and graph layout", add_help=False)
+    sub.add_parser("doctor", help="Project health report", add_help=False)
+    sub.add_parser("run", help="Run shell command with compact output", add_help=False)
+    sub.add_parser("gate", help="Process gate (check / hook adapters)", add_help=False)
+    sub.add_parser("state", help="Session state (handoff/STATE.json)", add_help=False)
+    sub.add_parser("graph", help="Graphify query wrappers", add_help=False)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for both ``python -m graphstack`` and unit tests."""
+    args = sys.argv[1:] if argv is None else argv
+    if not args or args[0] in ("-h", "--help"):
+        _build_parser().print_help()
+        return 0
+    if args[0] == "--version":
+        print(f"graphstack {__version__}")
+        return 0
+
+    cmd, rest = args[0], args[1:]
+
+    if cmd == "board":
+        from .board import run as board_run
+        return board_run(rest)
+    if cmd == "install":
+        from .installer import run as install_run
+        return install_run(rest)
+    if cmd == "init":
+        from .init_cmd import run as init_run
+        return init_run(rest)
+    if cmd == "hook":
+        from .hook import run as hook_run
+        return hook_run(rest)
+    if cmd == "validate":
+        from .validate import run_validate
+        return run_validate(rest)
+    if cmd == "doctor":
+        from .validate import run_doctor
+        return run_doctor(rest)
+    if cmd == "run":
+        from .run import run as run_cmd
+        return run_cmd(rest)
+    if cmd == "gate":
+        from .gate import run as gate_run
+        return gate_run(rest)
+    if cmd == "state":
+        from .state import run as state_run
+        return state_run(rest)
+    if cmd == "graph":
+        from .graph import run as graph_run
+        return graph_run(rest)
+
+    print(f"Unknown command: {cmd}", file=sys.stderr)
+    _build_parser().print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

graphstack/compact/__init__.py

@@ -0,0 +1,9 @@
+"""Token-safe shell output compaction (independent implementation).
+
+Preserves actionable detail (paths, errors, hunks). Falls back to raw output
+when compaction would drop too much signal.
+"""
+
+from .registry import compact_command_output
+
+__all__ = ["compact_command_output"]

graphstack/compact/base.py

@@ -0,0 +1,115 @@
+"""Shared helpers for safe output compaction."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Lines matching these patterns are never dropped during truncation.
+_CRITICAL_RE = re.compile(
+    r"(?i)(error|failed|failure|exception|traceback|fatal|panic|assertion|"
+    r"not found|cannot |can't |conflict|denied|fatal:|FAILED|ERROR\b|"
+    r"^\+{3}|^-{3}|^@@\s|^\?\?\s|^[MADRCU!]{1,2}\s)",
+)
+
+_DEFAULT_MAX_LINES = 120
+_MIN_RETAINED_RATIO = 0.05  # if output shrinks below 5% of input, prefer raw
+
+
+@dataclass(frozen=True)
+class CompactResult:
+    text: str
+    used_compactor: str
+    fell_back_to_raw: bool = False
+
+
+def is_critical_line(line: str) -> bool:
+    stripped = line.strip()
+    if not stripped:
+        return False
+    return bool(_CRITICAL_RE.search(stripped))
+
+
+def dedupe_consecutive(lines: list[str]) -> list[str]:
+    if not lines:
+        return []
+    out: list[str] = []
+    prev = lines[0]
+    count = 1
+    for line in lines[1:]:
+        if line == prev:
+            count += 1
+            continue
+        if count > 1:
+            out.append(f"{prev}  (×{count})")
+        else:
+            out.append(prev)
+        prev = line
+        count = 1
+    if count > 1:
+        out.append(f"{prev}  (×{count})")
+    else:
+        out.append(prev)
+    return out
+
+
+def truncate_preserving_critical(
+    lines: list[str],
+    *,
+    max_lines: int = _DEFAULT_MAX_LINES,
+) -> tuple[list[str], int]:
+    """Keep critical lines and a head/tail window; return (lines, omitted_count)."""
+    if len(lines) <= max_lines:
+        return lines, 0
+
+    critical_idx = [i for i, line in enumerate(lines) if is_critical_line(line)]
+    keep: set[int] = set()
+    head = max_lines // 3
+    tail = max_lines // 3
+    for i in range(min(head, len(lines))):
+        keep.add(i)
+    for i in range(max(0, len(lines) - tail), len(lines)):
+        keep.add(i)
+    keep.update(critical_idx)
+
+    if len(keep) > max_lines:
+        # Too many critical lines — keep all critical + fill with head/tail budget
+        ordered = sorted(keep)
+        keep = set(ordered[: max_lines])
+    else:
+        # Fill remaining budget with lines near critical regions
+        for idx in critical_idx:
+            for j in range(max(0, idx - 2), min(len(lines), idx + 3)):
+                if len(keep) >= max_lines:
+                    break
+                keep.add(j)
+
+    selected = [lines[i] for i in sorted(keep)]
+    omitted = len(lines) - len(selected)
+    return selected, omitted
+
+
+def safe_compact(
+    raw: str,
+    compactor_name: str,
+    compacted: str,
+) -> CompactResult:
+    """Return compacted text unless it lost too much signal vs raw."""
+    raw_stripped = raw.strip()
+    compact_stripped = compacted.strip()
+
+    if not raw_stripped:
+        return CompactResult("", compactor_name, fell_back_to_raw=False)
+
+    if not compact_stripped:
+        return CompactResult(raw.rstrip("\n"), compactor_name, fell_back_to_raw=True)
+
+    raw_lines = raw.splitlines()
+    compact_lines = compacted.splitlines()
+    if len(compact_lines) < max(1, int(len(raw_lines) * _MIN_RETAINED_RATIO)):
+        # Extreme shrink — only accept if raw was huge noise (progress bars only)
+        if not any(is_critical_line(line) for line in raw_lines):
+            return CompactResult(compacted.rstrip("\n"), compactor_name, fell_back_to_raw=False)
+        return CompactResult(raw.rstrip("\n"), compactor_name, fell_back_to_raw=True)
+
+    return CompactResult(compacted.rstrip("\n"), compactor_name, fell_back_to_raw=False)