MertCapkin-GraphStack 4.5.1__py3-none-any.whl

graphstack/platform_utils.py

@@ -0,0 +1,127 @@
+"""OS-agnostic helpers: python detection, git wrappers, console output.
+
+The package intentionally avoids any third-party dependencies — only the
+Python standard library is used so that a fresh ``pip install graphifyy``
+already covers all runtime requirements.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+IS_WINDOWS = sys.platform == "win32"
+
+
+def _reconfigure_stdout() -> None:
+    """Make stdout/stderr tolerant of Unicode on Windows code pages.
+
+    Many Windows shells default to cp1252/cp1254 which cannot represent box
+    drawing characters or emoji. Python 3.7+ exposes ``reconfigure`` so we
+    can switch to UTF-8 with replacement mode and never crash on output.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (OSError, ValueError):
+            try:
+                reconfigure(errors="replace")
+            except (OSError, ValueError):
+                pass
+
+
+_reconfigure_stdout()
+
+
+def find_python() -> list[str]:
+    """Return the argv prefix to launch a Python interpreter.
+
+    Order: ``python3`` → ``python`` → ``py -3``. Returns the first one that
+    actually exists on PATH. Falls back to ``sys.executable`` if nothing is
+    discoverable (we are obviously running under one already).
+    """
+    for name in ("python3", "python"):
+        if shutil.which(name):
+            return [name]
+    if IS_WINDOWS and shutil.which("py"):
+        return ["py", "-3"]
+    return [sys.executable]
+
+
+def run_git(*args: str, capture: bool = True) -> subprocess.CompletedProcess[str]:
+    """Run a git subcommand without ever raising on non-zero exit.
+
+    Returns the CompletedProcess so callers can decide what to do with
+    stdout/stderr. Mirrors the silent-fail behaviour of the original bash
+    scripts (``2>/dev/null || true``).
+    """
+    return subprocess.run(
+        ["git", *args],
+        capture_output=capture,
+        text=True,
+        check=False,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def git_available() -> bool:
+    return shutil.which("git") is not None
+
+
+def graphify_available() -> bool:
+    return shutil.which("graphify") is not None
+
+
+def utc_now_iso() -> str:
+    """ISO 8601 timestamp in UTC, second precision (matches old shell output)."""
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def file_mtime_seconds(path: Path) -> int | None:
+    try:
+        return int(path.stat().st_mtime)
+    except OSError:
+        return None
+
+
+def emoji_safe(text: str) -> str:
+    """Return ``text`` unchanged on UTF-8 capable stdouts, ASCII-flatten otherwise.
+
+    Windows ``cmd.exe`` defaults to cp1252 and chokes on emoji. We detect
+    the encoding once and downgrade if needed instead of crashing the user.
+    """
+    encoding = (sys.stdout.encoding or "").lower()
+    if "utf" in encoding:
+        return text
+    replacements = {
+        "🧠": "[*]", "📋": "[#]", "📁": "[+]", "🤖": "[~]", "🎭": "[~]",
+        "🚀": "[>]", "📝": "[w]", "📚": "[b]", "🔗": "[L]", "🎉": "[!]",
+        "✅": "[ok]", "❌": "[x]", "⚠️": "[!]", "⏭️": "[-]", "🟢": "[+]",
+        "🔄": "[~]", "📜": "[H]", "✓": "[ok]", "✗": "[x]",
+    }
+    for k, v in replacements.items():
+        text = text.replace(k, v)
+    return text
+
+
+def echo(message: str = "") -> None:
+    """``print`` with emoji-safe fallback. Always flushes for shim transparency.
+
+    Defensive against encoding errors: if the runtime locale still cannot
+    encode the message (older Pythons or odd ``cmd.exe`` configurations),
+    we fall back to an ASCII transliteration via ``encode(errors='replace')``.
+    """
+    safe = emoji_safe(message)
+    try:
+        print(safe, flush=True)
+    except UnicodeEncodeError:
+        encoding = sys.stdout.encoding or "ascii"
+        ascii_only = safe.encode(encoding, errors="replace").decode(encoding, errors="replace")
+        print(ascii_only, flush=True)

graphstack/run.py

@@ -0,0 +1,103 @@
+"""Run shell commands with token-safe output compaction.
+
+Usage:
+  graphstack run -- git status
+  graphstack run --raw -- git diff
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+
+from .compact.registry import compact_command_output
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="graphstack run",
+        description="Run a command and print token-safe output (stderr preserved).",
+    )
+    parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="Disable compaction; print stdout verbatim (quality/debug).",
+    )
+    parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        help="Command after -- (e.g. git status)",
+    )
+    return parser
+
+
+def _strip_leading_dashes(argv: list[str]) -> list[str]:
+    if argv and argv[0] == "--":
+        return argv[1:]
+    return argv
+
+
+def _quality_git_argv(cmd: list[str], *, raw: bool) -> list[str]:
+    """Use porcelain status for reliable path preservation when compacting."""
+    if raw or len(cmd) < 2:
+        return cmd
+    exe = cmd[0].lower().removesuffix(".exe")
+    if exe != "git":
+        return cmd
+    sub = cmd[1].lower()
+    joined = " ".join(cmd[2:]).lower()
+    if sub == "status" and "--porcelain" not in joined and " -s" not in f" {joined} ":
+        return cmd[:2] + ["--porcelain=v1", "-b"] + cmd[2:]
+    if sub == "log" and "--oneline" not in joined:
+        return cmd[:2] + ["--oneline"] + cmd[2:]
+    return cmd
+
+
+def execute(argv: list[str], *, raw: bool = False) -> int:
+    cmd = _quality_git_argv(_strip_leading_dashes(argv), raw=raw)
+    if not cmd:
+        print(
+            "graphstack run: missing command (use: graphstack run -- git status)",
+            file=sys.stderr,
+        )
+        return 2
+
+    executable = cmd[0]
+    if shutil.which(executable) is None and not executable.startswith("."):
+        print(f"graphstack run: command not found: {executable}", file=sys.stderr)
+        return 127
+
+    proc = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+
+    stdout = proc.stdout or ""
+    stderr = proc.stderr or ""
+
+    if raw:
+        if stdout:
+            print(stdout, end="" if stdout.endswith("\n") else "\n")
+        if stderr:
+            print(stderr, end="" if stderr.endswith("\n") else "", file=sys.stderr)
+        return proc.returncode
+
+    result = compact_command_output(cmd, stdout, stderr)
+    if result.text:
+        print(result.text)
+    elif proc.returncode == 0:
+        print(f"(ok, {result.used_compactor}, no stdout)")
+
+    return proc.returncode
+
+
+def run(argv: list[str] | None = None) -> int:
+    args_list = sys.argv[2:] if argv is None else argv
+    parser = _build_parser()
+    args = parser.parse_args(args_list)
+    cmd = _strip_leading_dashes(args.command)
+    return execute(cmd, raw=args.raw)

graphstack/state.py

@@ -0,0 +1,117 @@
+"""Machine-readable session state — ``handoff/STATE.json``.
+
+Complements the human-readable ``handoff/STATE.md`` log (which stays
+append-only and unchanged). The JSON file holds only the *current* state so
+hooks and the process gate can verify it deterministically.
+
+Schema: ``{"role": str, "task_id": str | None, "updated_at": str, "note": str}``
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .constants import STATE_JSON
+from .platform_utils import echo, utc_now_iso
+
+VALID_ROLES = (
+    "idle", "architect", "builder", "reviewer", "qa", "ship", "bootstrapper",
+)
+
+
+def load_state() -> dict | None:
+    """Return the current state dict, or None if missing/unreadable."""
+    try:
+        return json.loads(STATE_JSON.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return None
+
+
+def save_state(role: str, task_id: str | None = None, note: str = "") -> dict:
+    state = {
+        "role": role,
+        "task_id": task_id,
+        "updated_at": utc_now_iso(),
+        "note": note,
+    }
+    STATE_JSON.parent.mkdir(parents=True, exist_ok=True)
+    STATE_JSON.write_text(
+        json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    return state
+
+
+def cmd_set(args: argparse.Namespace) -> int:
+    role = args.role.lower()
+    if role not in VALID_ROLES:
+        echo(f"⚠️  Unknown role '{role}' (expected one of: {', '.join(VALID_ROLES)})")
+    state = save_state(role, args.task, args.note or "")
+    echo(f"✅ STATE.json: role={state['role']} task={state['task_id'] or '-'}")
+    return 0
+
+
+def cmd_get(args: argparse.Namespace) -> int:
+    state = load_state()
+    if state is None:
+        if args.json:
+            echo("null")
+        else:
+            echo("(no STATE.json — run: python -m graphstack state set --role <role>)")
+        return 1
+    if args.json:
+        echo(json.dumps(state, ensure_ascii=False))
+    else:
+        echo(f"role={state.get('role', '-')} task={state.get('task_id') or '-'} "
+             f"updated={state.get('updated_at', '-')}")
+        if state.get("note"):
+            echo(f"note: {state['note']}")
+    return 0
+
+
+def cmd_clear(_args: argparse.Namespace) -> int:
+    try:
+        STATE_JSON.unlink()
+        echo("✅ STATE.json cleared")
+    except FileNotFoundError:
+        echo("(STATE.json already absent)")
+    except OSError as exc:
+        echo(f"❌ Could not remove STATE.json: {exc}")
+        return 1
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="graphstack state",
+        description="Manage the machine-readable session state (handoff/STATE.json).",
+    )
+    sub = p.add_subparsers(dest="action", required=True)
+
+    p_set = sub.add_parser("set", help="write current role/task state")
+    p_set.add_argument("--role", required=True)
+    p_set.add_argument("--task", default=None, help="board task id")
+    p_set.add_argument("--note", default="", help="free-text note")
+
+    p_get = sub.add_parser("get", help="print current state")
+    p_get.add_argument("--json", action="store_true")
+
+    sub.add_parser("clear", help="remove STATE.json")
+    return p
+
+
+_DISPATCH = {"set": cmd_set, "get": cmd_get, "clear": cmd_clear}
+
+
+def run(argv: list[str]) -> int:
+    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/tests/conftest.py

@@ -0,0 +1,30 @@
+"""Shared pytest fixtures for the graphstack package."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def project_root(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Provide an isolated, writable directory and chdir into it.
+
+    All board operations are resolved relative to ``cwd`` so each test gets a
+    pristine handoff/board layout without touching the real repository.
+    """
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "handoff" / "board" / "todo").mkdir(parents=True)
+    (tmp_path / "handoff" / "board" / "doing").mkdir(parents=True)
+    (tmp_path / "handoff" / "board" / "done").mkdir(parents=True)
+    return tmp_path
+
+
+@pytest.fixture(autouse=True)
+def _disable_git_in_tests(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Prevent any board command from creating real git commits during tests."""
+    from graphstack import board
+
+    monkeypatch.setattr(board, "_git_commit_board", lambda _msg: None)

graphstack/tests/test_assets.py

@@ -0,0 +1,35 @@
+"""Tests for bundled assets and install source resolution."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from graphstack.installer import PACKAGE_ROOT, install_source_root
+
+
+def test_install_source_root_from_dev_repo() -> None:
+    root = install_source_root()
+    assert (root / "orchestrator" / "ORCHESTRATOR.md").is_file()
+
+
+def test_bundled_assets_exist_in_package() -> None:
+    assets = PACKAGE_ROOT / "assets"
+    assert (assets / "orchestrator" / "ORCHESTRATOR.md").is_file()
+    assert (assets / ".cursor" / "rules" / "graphstack.mdc").is_file()
+
+
+def test_install_from_bundled_assets_only(tmp_path: Path, monkeypatch) -> None:
+    from graphstack import installer
+
+    assets = PACKAGE_ROOT / "assets"
+    monkeypatch.setattr(
+        installer,
+        "_source_root",
+        lambda: assets,
+    )
+    target = tmp_path / "consumer"
+    target.mkdir()
+    assert installer.install(target, non_interactive=True) == 0
+    assert (target / "orchestrator" / "ORCHESTRATOR.md").is_file()
+    assert (target / ".cursor" / "rules" / "graphstack.mdc").is_file()
+    assert (target / "handoff" / "BRIEF.md").is_file()

graphstack/tests/test_board.py

@@ -0,0 +1,166 @@
+"""Round-trip tests for the GNAP board lifecycle."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from graphstack import board
+
+
+def _read(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def test_status_empty_board(project_root: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    rc = board.run(["status"])
+    captured = capsys.readouterr()
+    assert rc == 0
+    assert "Todo: 0" in captured.out
+    assert "(no tasks yet)" in captured.out
+
+
+def test_new_task_creates_file(project_root: Path) -> None:
+    rc = board.run(["new", "add-oauth", "Add", "OAuth", "login"])
+    assert rc == 0
+    task_path = project_root / "handoff" / "board" / "todo" / "add-oauth.json"
+    assert task_path.is_file()
+    data = _read(task_path)
+    assert data["id"] == "add-oauth"
+    assert data["title"] == "Add OAuth login"
+    assert data["status"] == "todo"
+    assert data["assigned_to"] is None
+
+
+def test_new_task_rejects_duplicates(project_root: Path) -> None:
+    assert board.run(["new", "dup", "First"]) == 0
+    assert board.run(["new", "dup", "Second"]) == 1
+
+
+def test_full_lifecycle_todo_to_done(project_root: Path) -> None:
+    assert board.run(["new", "rate-limit", "Add", "rate", "limiting"]) == 0
+
+    todo = project_root / "handoff" / "board" / "todo" / "rate-limit.json"
+    doing = project_root / "handoff" / "board" / "doing" / "rate-limit.json"
+    done = project_root / "handoff" / "board" / "done" / "rate-limit.json"
+
+    assert todo.is_file()
+
+    assert board.run(["claim", "rate-limit", "builder"]) == 0
+    assert not todo.exists()
+    assert doing.is_file()
+    claimed = _read(doing)
+    assert claimed["status"] == "doing"
+    assert claimed["assigned_to"] == "builder"
+    assert claimed["started_at"] is not None
+
+    assert board.run(["complete", "rate-limit"]) == 0
+    assert not doing.exists()
+    assert done.is_file()
+    completed = _read(done)
+    assert completed["status"] == "done"
+    assert completed["completed_at"] is not None
+
+
+def test_claim_missing_task_returns_error(project_root: Path) -> None:
+    assert board.run(["claim", "ghost", "builder"]) == 1
+
+
+def test_claim_already_doing_is_idempotent(project_root: Path) -> None:
+    board.run(["new", "twice", "Do", "it", "once"])
+    board.run(["claim", "twice", "builder"])
+    rc = board.run(["claim", "twice", "builder"])
+    assert rc == 0  # already-claimed path returns 0 with a warning
+
+
+def test_complete_already_done_is_idempotent(project_root: Path) -> None:
+    board.run(["new", "loop", "Loop", "task"])
+    board.run(["claim", "loop", "qa"])
+    board.run(["complete", "loop"])
+    rc = board.run(["complete", "loop"])
+    assert rc == 0
+
+
+def test_status_lists_tasks_in_each_column(
+    project_root: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    board.run(["new", "a", "Task", "A"])
+    board.run(["new", "b", "Task", "B"])
+    board.run(["new", "c", "Task", "C"])
+    board.run(["claim", "b", "builder"])
+    board.run(["claim", "c", "reviewer"])
+    board.run(["complete", "c"])
+
+    rc = board.run(["status"])
+    out = capsys.readouterr().out
+    assert rc == 0
+    assert "Todo: 1" in out
+    assert "In Progress: 1" in out
+    assert "Done: 1" in out
+    assert "a" in out and "b" in out and "c" in out
+
+
+def test_help_prints_usage(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = board.run([])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "GraphStack Board" in out
+    assert "status" in out
+    assert "claim" in out
+
+
+def test_reopen_done_to_todo(project_root: Path) -> None:
+    board.run(["new", "fix-bug", "Fix", "production", "bug"])
+    board.run(["claim", "fix-bug", "builder"])
+    board.run(["complete", "fix-bug"])
+
+    done = project_root / "handoff" / "board" / "done" / "fix-bug.json"
+    todo = project_root / "handoff" / "board" / "todo" / "fix-bug.json"
+    assert done.is_file()
+
+    assert board.run(["reopen", "fix-bug", "--to", "todo"]) == 0
+    assert not done.exists()
+    assert todo.is_file()
+    data = _read(todo)
+    assert data["status"] == "todo"
+    assert data["assigned_to"] is None
+    assert data["completed_at"] is None
+
+
+def test_reopen_done_to_doing(project_root: Path) -> None:
+    board.run(["new", "hotfix", "Hotfix"])
+    board.run(["claim", "hotfix", "builder"])
+    board.run(["complete", "hotfix"])
+
+    doing = project_root / "handoff" / "board" / "doing" / "hotfix.json"
+    assert board.run(["reopen", "hotfix", "--to", "doing"]) == 0
+    assert doing.is_file()
+    assert _read(doing)["status"] == "doing"
+
+
+def test_list_done_empty(project_root: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    rc = board.run(["list-done"])
+    assert rc == 0
+    assert "(none)" in capsys.readouterr().out
+
+
+def test_list_done_shows_completed(project_root: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    board.run(["new", "a", "Task", "A"])
+    board.run(["claim", "a", "builder"])
+    board.run(["complete", "a"])
+    board.run(["new", "b", "Task", "B"])
+    board.run(["claim", "b", "qa"])
+    board.run(["complete", "b"])
+
+    board.run(["list-done", "--limit", "1"])
+    out = capsys.readouterr().out
+    assert "b" in out
+    assert "Showing 1 task" in out
+
+
+def test_unicode_title_is_preserved(project_root: Path) -> None:
+    board.run(["new", "tr", "Türkçe", "başlık", "ışık"])
+    task = _read(project_root / "handoff" / "board" / "todo" / "tr.json")
+    assert task["title"] == "Türkçe başlık ışık"

graphstack/tests/test_compact.py

@@ -0,0 +1,93 @@
+"""Quality tests for output compaction — paths and errors must survive."""
+
+from __future__ import annotations
+
+from graphstack.compact.git import compact_git_diff, compact_git_log, compact_git_status
+from graphstack.compact.generic import compact_generic, compact_pytest
+from graphstack.compact.registry import compact_command_output
+
+
+SAMPLE_STATUS = """\
+On branch feature/login
+Your branch is ahead of 'origin/main' by 2 commits.
+Changes to be committed:
+  (use "git restore --staged <file>..." to unstage)
+\tmodified:   src/auth/login.ts
+\tnew file:   src/auth/session.ts
+
+Changes not staged for commit:
+\tmodified:   src/api/types.ts
+
+Untracked files:
+\tREADME.local.md
+"""
+
+SAMPLE_DIFF = """\
+diff --git a/src/a.py b/src/a.py
+--- a/src/a.py
++++ b/src/a.py
+@@ -1,3 +1,4 @@
+ line1
+-line2
++line2changed
+ line3
+"""
+
+SAMPLE_PYTEST_FAIL = """\
+============================= test session starts ==============================
+collected 3 items
+
+tests/test_auth.py::test_login FAILED
+
+=================================== FAILURES ===================================
+_______________________________ test_login ___________________________________
+E   AssertionError: expected 200
+
+========================== 1 failed, 2 passed in 0.12s ==========================
+"""
+
+
+def test_git_status_keeps_branch_and_paths() -> None:
+    out = compact_git_status(SAMPLE_STATUS)
+    assert "feature/login" in out or "On branch" in out
+    assert "login.ts" in out
+    assert "types.ts" in out
+
+
+def test_git_diff_keeps_hunk_headers() -> None:
+    out = compact_git_diff(SAMPLE_DIFF)
+    assert "diff --git" in out
+    assert "@@" in out
+    assert "-line2" in out or "+line2changed" in out
+
+
+def test_git_log_truncates_but_keeps_recent() -> None:
+    lines = [f"{i:07x} commit message {i}" for i in range(50)]
+    raw = "\n".join(lines)
+    out = compact_git_log(raw, max_entries=10)
+    assert "commit message 0" in out
+    assert "omitted" in out
+
+
+def test_pytest_keeps_failure_and_summary() -> None:
+    out = compact_pytest(SAMPLE_PYTEST_FAIL)
+    assert "FAILED" in out or "AssertionError" in out
+    assert "failed" in out.lower()
+
+
+def test_registry_falls_back_when_compaction_empty() -> None:
+    raw = "important error on line 1\n" + ("noise\n" * 500)
+    result = compact_command_output(["unknown-tool"], raw)
+    assert "error" in result.text.lower() or len(result.text) > 0
+
+
+def test_critical_lines_survive_generic_truncate() -> None:
+    lines = ["ok"] * 200 + ["Fatal: disk full"] + ["ok"] * 200
+    out = compact_generic("\n".join(lines))
+    assert "Fatal" in out
+
+
+def test_registry_git_status_route() -> None:
+    result = compact_command_output(["git", "status"], SAMPLE_STATUS)
+    assert result.used_compactor == "git-status"
+    assert "login.ts" in result.text