agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/gui_gatekeeper_status.py

@@ -0,0 +1,259 @@
+"""Deterministic GUI gatekeeper status model.
+
+This module is intentionally read-only. It builds a stable status snapshot that
+GUI surfaces can render before allowing action execution.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import subprocess
+from typing import Sequence
+import yaml
+
+from agentic_project_kit.action_registry import ACTIONS, SafetyClass
+from agentic_project_kit.communication_rule_context import require_current_communication_context
+
+
+@dataclass(frozen=True)
+class GuiGatekeeperActionStatus:
+    action_id: str
+    safety_class: str
+    mutation_scope: str
+    enabled: bool
+    reason: str
+
+
+@dataclass(frozen=True)
+class GuiGatekeeperStatus:
+    branch: str
+    git_dirty: bool
+    workflow_state: str
+    current_work_present: bool
+    current_work_state: str | None
+    ready_for_read_only_actions: bool
+    ready_for_mutating_actions: bool
+    action_statuses: tuple[GuiGatekeeperActionStatus, ...]
+    blockers: tuple[str, ...]
+    communication_context_fresh: bool = True
+    communication_context_reason: str = "communication_context_current"
+    required_next_reply: str | None = None
+
+
+def build_gui_gatekeeper_status(
+    project_root: Path | str = ".",
+    *,
+    actions: Sequence[object] | None = None,
+) -> GuiGatekeeperStatus:
+    """Build a deterministic, read-only GUI gatekeeper snapshot."""
+
+    root = Path(project_root)
+    branch = _git_branch(root)
+    git_dirty = _git_dirty(root)
+    workflow_state = _read_text(root / ".agentic" / "workflow_state", "missing").strip() or "missing"
+    current_work_path = root / ".agentic" / "current_work.yaml"
+    current_work_present = current_work_path.exists()
+    current_work_state = _read_current_work_state(current_work_path) if current_work_present else None
+    communication_context = require_current_communication_context(root)
+    communication_context_fresh = communication_context.result_status == "PASS"
+
+    blockers: list[str] = []
+    if branch == "unknown":
+        blockers.append("git branch could not be determined")
+    if git_dirty:
+        blockers.append("working tree is dirty")
+    if workflow_state not in {"IDLE", "READY"}:
+        blockers.append(f"workflow_state is {workflow_state}")
+    if not communication_context_fresh:
+        blockers.append(communication_context.reason)
+
+    ready_for_read_only_actions = not git_dirty
+    ready_for_mutating_actions = (
+        not git_dirty
+        and branch != "unknown"
+        and workflow_state in {"IDLE", "READY"}
+        and communication_context_fresh
+    )
+
+    action_statuses = tuple(
+        classify_gui_gatekeeper_action(
+            action,
+            git_dirty=git_dirty,
+            local_only_allowed=ready_for_mutating_actions,
+        )
+        for action in (actions if actions is not None else ACTIONS)
+    )
+
+    return GuiGatekeeperStatus(
+        branch=branch,
+        git_dirty=git_dirty,
+        workflow_state=workflow_state,
+        current_work_present=current_work_present,
+        current_work_state=current_work_state,
+        ready_for_read_only_actions=ready_for_read_only_actions,
+        ready_for_mutating_actions=ready_for_mutating_actions,
+        action_statuses=action_statuses,
+        blockers=tuple(blockers),
+        communication_context_fresh=communication_context_fresh,
+        communication_context_reason=communication_context.reason,
+        required_next_reply=communication_context.required_next_reply,
+    )
+
+
+def classify_gui_gatekeeper_action(
+    action: object,
+    *,
+    git_dirty: bool,
+    local_only_allowed: bool = False,
+) -> GuiGatekeeperActionStatus:
+    action_id = str(getattr(action, "name", getattr(action, "action_id", "<unknown>")))
+    safety_class = _safety_value(getattr(action, "safety_class", getattr(action, "safety", "unknown")))
+    mutation_scope = str(getattr(action, "mutation_scope", "unknown"))
+
+    if safety_class == SafetyClass.READ_ONLY.value and not git_dirty:
+        return GuiGatekeeperActionStatus(
+            action_id=action_id,
+            safety_class=safety_class,
+            mutation_scope=mutation_scope,
+            enabled=True,
+            reason="read-only action allowed in clean GUI gatekeeper state",
+        )
+
+    if safety_class == SafetyClass.READ_ONLY.value and git_dirty:
+        return GuiGatekeeperActionStatus(
+            action_id=action_id,
+            safety_class=safety_class,
+            mutation_scope=mutation_scope,
+            enabled=False,
+            reason="read-only action blocked because working tree is dirty",
+        )
+
+    if safety_class == SafetyClass.LOCAL_ONLY.value and local_only_allowed:
+        return GuiGatekeeperActionStatus(
+            action_id=action_id,
+            safety_class=safety_class,
+            mutation_scope=mutation_scope,
+            enabled=True,
+            reason="local-only action allowed in clean GUI gatekeeper state",
+        )
+
+    if safety_class == SafetyClass.LOCAL_ONLY.value:
+        return GuiGatekeeperActionStatus(
+            action_id=action_id,
+            safety_class=safety_class,
+            mutation_scope=mutation_scope,
+            enabled=False,
+            reason="local-only action blocked because GUI gatekeeper is not clean",
+        )
+
+    return GuiGatekeeperActionStatus(
+        action_id=action_id,
+        safety_class=safety_class,
+        mutation_scope=mutation_scope,
+        enabled=False,
+        reason="GUI gatekeeper blocks remote mutation actions",
+    )
+
+
+def render_gui_gatekeeper_status(status: GuiGatekeeperStatus) -> str:
+    lines = [
+        "GUI_GATEKEEPER_STATUS",
+        f"branch={status.branch}",
+        f"git_dirty={str(status.git_dirty).lower()}",
+        f"workflow_state={status.workflow_state}",
+        f"current_work_present={str(status.current_work_present).lower()}",
+        f"current_work_state={status.current_work_state or '<none>'}",
+        f"ready_for_read_only_actions={str(status.ready_for_read_only_actions).lower()}",
+        f"ready_for_mutating_actions={str(status.ready_for_mutating_actions).lower()}",
+        f"communication_context_fresh={str(status.communication_context_fresh).lower()}",
+        f"communication_context_reason={status.communication_context_reason}",
+        f"required_next_reply={status.required_next_reply or '<none>'}",
+        "blockers=" + (",".join(status.blockers) if status.blockers else "<none>"),
+    ]
+    for action in status.action_statuses:
+        lines.append(
+            "action="
+            + action.action_id
+            + ";safety="
+            + action.safety_class
+            + ";enabled="
+            + str(action.enabled).lower()
+            + ";reason="
+            + action.reason
+        )
+    return "\n".join(lines)
+
+
+def gui_gatekeeper_status_as_json_data(status: GuiGatekeeperStatus) -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "branch": status.branch,
+        "git_dirty": status.git_dirty,
+        "workflow_state": status.workflow_state,
+        "current_work_present": status.current_work_present,
+        "current_work_state": status.current_work_state,
+        "ready_for_read_only_actions": status.ready_for_read_only_actions,
+        "ready_for_mutating_actions": status.ready_for_mutating_actions,
+        "communication_context_fresh": status.communication_context_fresh,
+        "communication_context_reason": status.communication_context_reason,
+        "required_next_reply": status.required_next_reply,
+        "blockers": list(status.blockers),
+        "actions": [
+            {
+                "action_id": action.action_id,
+                "safety_class": action.safety_class,
+                "mutation_scope": action.mutation_scope,
+                "enabled": action.enabled,
+                "reason": action.reason,
+            }
+            for action in status.action_statuses
+        ],
+    }
+
+
+def _safety_value(value: object) -> str:
+    raw = getattr(value, "value", value)
+    return str(raw).strip().lower().replace("_", "-")
+
+
+def _git_branch(root: Path) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "-C", str(root), "branch", "--show-current"],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip() or "unknown"
+    except (OSError, subprocess.CalledProcessError):
+        return "unknown"
+
+
+def _git_dirty(root: Path) -> bool:
+    try:
+        return bool(
+            subprocess.check_output(
+                ["git", "-C", str(root), "status", "--porcelain"],
+                text=True,
+                stderr=subprocess.DEVNULL,
+            ).strip()
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return True
+
+
+def _read_text(path: Path, default: str) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return default
+
+
+def _read_current_work_state(path: Path) -> str | None:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    state = data.get("state")
+    return str(state) if state is not None else None

agentic_project_kit/gui_layout_plan.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentic_project_kit.gui_tkinter_shell import TkinterShellSpec, build_tkinter_shell_spec
+
+
+@dataclass(frozen=True)
+class LayoutNode:
+    node_id: str
+    kind: str
+    label: str
+    parent: str
+    order: int
+    enabled: bool = True
+    tooltip: str = ""
+    command_id: str = ""
+    safety_class: str = ""
+    icon_id: str = ""
+    category: str = ""
+    implementation_state: str = ""
+    disabled_reason: str = ""
+
+
+@dataclass(frozen=True)
+class LayoutPlan:
+    title: str
+    geometry: str
+    nodes: tuple[LayoutNode, ...]
+
+    @property
+    def node_count(self) -> int:
+        return len(self.nodes)
+
+    def nodes_by_kind(self, kind: str) -> tuple[LayoutNode, ...]:
+        return tuple(node for node in self.nodes if node.kind == kind)
+
+
+def _append(
+    nodes: list[LayoutNode],
+    node_id: str,
+    kind: str,
+    label: str,
+    parent: str,
+    enabled: bool = True,
+    tooltip: str = "",
+    command_id: str = "",
+    safety_class: str = "",
+    icon_id: str = "",
+    category: str = "",
+    implementation_state: str = "",
+    disabled_reason: str = "",
+) -> None:
+    nodes.append(
+        LayoutNode(
+            node_id=node_id,
+            kind=kind,
+            label=label,
+            parent=parent,
+            order=len(nodes),
+            enabled=enabled,
+            tooltip=tooltip,
+            command_id=command_id,
+            safety_class=safety_class,
+            icon_id=icon_id,
+            category=category,
+            implementation_state=implementation_state,
+            disabled_reason=disabled_reason,
+        )
+    )
+
+
+def build_layout_plan(spec: TkinterShellSpec | None = None) -> LayoutPlan:
+    shell = build_tkinter_shell_spec() if spec is None else spec
+    nodes: list[LayoutNode] = []
+    _append(nodes, "root", "window", shell.title, "")
+    _append(nodes, "menu-bar", "menu_bar", "Menu", "root")
+    for menu in shell.design.menu_bar:
+        menu_id = "menu-" + menu.label.lower().replace(" ", "-")
+        _append(nodes, menu_id, "menu", menu.label, "menu-bar")
+        for item in menu.items:
+            _append(
+                nodes,
+                menu_id + "-" + item.command_id,
+                "menu_item",
+                item.label,
+                menu_id,
+                item.enabled,
+                item.tooltip,
+                item.command_id,
+            )
+    _append(nodes, "toolbar", "toolbar", "Toolbar", "root")
+    for button in shell.design.toolbar:
+        _append(
+            nodes,
+            "toolbar-" + button.command_id,
+            "toolbar_button",
+            button.label,
+            "toolbar",
+            button.enabled,
+            button.tooltip,
+            button.command_id,
+            button.safety_class,
+            button.icon_id,
+            button.category,
+            button.implementation_state,
+            button.disabled_reason,
+        )
+    _append(nodes, "main", "main_area", "Main", "root")
+    _append(nodes, "actions", "action_panel", "Actions", "main")
+    for button in shell.design.action_buttons:
+        _append(
+            nodes,
+            "action-" + button.command_id,
+            "action_button",
+            button.label,
+            "actions",
+            button.enabled,
+            button.tooltip,
+            button.command_id,
+            button.safety_class,
+            button.icon_id,
+            button.category,
+            button.implementation_state,
+            button.disabled_reason,
+        )
+    _append(nodes, "details", "details_panel", "Details / Parameters", "main")
+    _append(nodes, "output", "output_panel", "Output / Log", "root")
+    _append(nodes, "summary", "summary_bar", "Last Summary", "root")
+    return LayoutPlan(title=shell.title, geometry="1000x650", nodes=tuple(nodes))
+
+
+def render_layout_plan(plan: LayoutPlan) -> str:
+    lines = [
+        "GUI LAYOUT PLAN",
+        f"title={plan.title}",
+        f"geometry={plan.geometry}",
+        f"node_count={plan.node_count}",
+    ]
+    for kind in ("menu", "toolbar_button", "action_button", "output_panel", "summary_bar"):
+        lines.append(f"{kind}_count={len(plan.nodes_by_kind(kind))}")
+    categories = sorted(
+        {node.category for node in plan.nodes_by_kind("action_button") if node.category}
+    )
+    lines.append("action_categories=" + (",".join(categories) if categories else "NONE"))
+    disabled = [node.command_id for node in plan.nodes if not node.enabled]
+    lines.append("disabled_commands=" + (",".join(disabled) if disabled else "NONE"))
+    return "\n".join(lines)

agentic_project_kit/gui_open_folder.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+
+def open_folder_in_file_manager(path: Path) -> None:
+    target = Path(path)
+    target.mkdir(parents=True, exist_ok=True)
+    if sys.platform == "darwin":
+        subprocess.run(["open", str(target)], check=False)
+        return
+    if sys.platform.startswith("win"):
+        os.startfile(str(target))  # type: ignore[attr-defined]  # noqa: S606
+        return
+    subprocess.run(["xdg-open", str(target)], check=False)

agentic_project_kit/gui_output_status_panel.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class GuiOutputStatusPanel:
+    status: str
+    branch: str
+    dirty: bool
+    latest_output: str
+    terminal_log: str
+    terminal_log_remote: str
+    terminal_log_local: str
+    evidence_state: str
+    summary: str
+
+
+def build_output_status_panel(
+    *,
+    branch: str = "unknown",
+    dirty: bool = False,
+    latest_output: str = "",
+    terminal_log: str = "NONE",
+    terminal_log_remote: str = "NONE",
+    terminal_log_local: str = "NONE",
+    evidence_state: str = "local_only",
+    summary: str = "",
+) -> GuiOutputStatusPanel:
+    status = "dirty" if dirty else "clean"
+    return GuiOutputStatusPanel(
+        status=status,
+        branch=branch,
+        dirty=dirty,
+        latest_output=latest_output or "No output captured yet.",
+        terminal_log=terminal_log,
+        terminal_log_remote=terminal_log_remote,
+        terminal_log_local=terminal_log_local,
+        evidence_state=evidence_state,
+        summary=summary or "No summary captured yet.",
+    )
+
+
+def render_output_status_panel(panel: GuiOutputStatusPanel) -> str:
+    lines = [
+        "GUI OUTPUT STATUS PANEL",
+        f"status={panel.status}",
+        f"branch={panel.branch}",
+        f"dirty={str(panel.dirty).lower()}",
+        f"terminal_log={panel.terminal_log}",
+        f"terminal_log_remote={panel.terminal_log_remote}",
+        f"terminal_log_local={panel.terminal_log_local}",
+        f"evidence_state={panel.evidence_state}",
+        "latest_output_begin",
+        panel.latest_output,
+        "latest_output_end",
+        "summary_begin",
+        panel.summary,
+        "summary_end",
+    ]
+    return "\n".join(lines)

agentic_project_kit/gui_panel_state.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+from typing import Any
+
+from agentic_project_kit.workspace import LEGACY_DEFAULTS, load_workspace
+
+PANEL_STATE_FILE = "gui-panel-state.json"
+PANEL_STATE_RELATIVE_PATH = Path(LEGACY_DEFAULTS.tmp_root) / PANEL_STATE_FILE
+
+
+def panel_state_path(root: Path = Path(".")) -> Path:
+    return load_workspace(root).gui_panel_state_path()
+
+
+def _coerce_state(data: Any) -> dict[str, bool]:
+    if isinstance(data, dict) and isinstance(data.get("expanded_groups"), dict):
+        data = data["expanded_groups"]
+    if not isinstance(data, dict):
+        return {}
+    return {str(key): bool(value) for key, value in data.items() if isinstance(key, str)}
+
+
+def read_panel_state(root: Path = Path(".")) -> dict[str, bool]:
+    path = panel_state_path(root)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, OSError, json.JSONDecodeError):
+        return {}
+    return _coerce_state(data)
+
+
+def write_panel_state(root: Path = Path("."), state: dict[str, bool] | None = None) -> Path:
+    path = panel_state_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    workspace = load_workspace(root)
+    payload = {
+        "schema_version": 1,
+        "kind": "gui_panel_state",
+        "state_path": workspace.path_text(path),
+        "updated_at_utc": datetime.now(timezone.utc).isoformat(),
+        "expanded_groups": dict(sorted((state or {}).items())),
+    }
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path

agentic_project_kit/gui_presenter.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from agentic_project_kit.gui_action_renderer import (
+    render_basic_cockpit_view_model,
+    render_controller_view_model,
+)
+from agentic_project_kit.gui_gatekeeper_status import GuiGatekeeperStatus
+from agentic_project_kit.gui_viewmodel import (
+    build_basic_cockpit_view_model,
+    build_gui_controller_view_model,
+)
+
+
+@dataclass(frozen=True)
+class GuiPresenterResult:
+    ok: bool
+    action_count: int
+    rendered: str
+    message: str
+
+
+def build_no_window_presenter_result(
+    actions: Iterable[object],
+    *,
+    title: str = "agentic-project-kit Cockpit",
+    status: str = "dry-run-ready",
+    destructive_actions_enabled: bool = False,
+) -> GuiPresenterResult:
+    view_model = build_gui_controller_view_model(
+        actions,
+        title=title,
+        status=status,
+        destructive_actions_enabled=destructive_actions_enabled,
+    )
+    rendered = render_controller_view_model(view_model)
+    return GuiPresenterResult(
+        ok=True,
+        action_count=view_model.action_count,
+        rendered=rendered,
+        message="GUI no-window presenter passed.",
+    )
+
+
+def build_basic_no_window_presenter_result(
+    *,
+    gatekeeper_status: GuiGatekeeperStatus | None = None,
+    communication_mode: str = "file_transfer",
+) -> GuiPresenterResult:
+    view_model = build_basic_cockpit_view_model(
+        gatekeeper_status=gatekeeper_status,
+        communication_mode=communication_mode,
+    )
+    rendered = render_basic_cockpit_view_model(view_model)
+    return GuiPresenterResult(
+        ok=True,
+        action_count=view_model.button_count,
+        rendered=rendered,
+        message="Basic cockpit no-window presenter passed.",
+    )