multi-forge 0.2.0__py3-none-any.whl

forge/cli/guards.py

@@ -0,0 +1,106 @@
+"""CWD validation guards for session commands.
+
+Enforces two invariants:
+1. CWD must be a git repo root OR a Forge project root (where .forge/ lives)
+2. CWD must be the main repo root (not a child worktree) — for --worktree commands
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+from forge.core.paths import display_path
+
+console = Console()
+
+
+def require_repo_root() -> Path:
+    """Verify CWD is a git repository root or a Forge project root.
+
+    Accepts CWD at a nested Forge project root (where .forge/ lives) for
+    monorepo support. Falls back to git root check for non-Forge directories.
+
+    Returns:
+        The validated CWD on success.
+    """
+    from forge.core.ops.context import find_forge_root
+    from forge.session.claude.paths import find_project_root
+
+    cwd = Path.cwd().resolve()
+
+    # Accept CWD at a Forge project root (nested or top-level)
+    forge_root = find_forge_root(cwd)
+    if forge_root is not None and forge_root == cwd:
+        return cwd
+
+    try:
+        repo_root = find_project_root().resolve()
+    except FileNotFoundError:
+        console.print("[red]Error:[/red] Not in a git repository")
+        sys.exit(1)
+
+    if cwd != repo_root:
+        hint = str(forge_root) if forge_root else str(repo_root)
+        console.print(
+            f"[red]Error:[/red] Must run from the repository root ({display_path(repo_root)}), " f"not a subdirectory"
+        )
+        console.print(f"\n[dim]Tip: cd {display_path(hint)}[/dim]")
+        sys.exit(1)
+
+    return cwd
+
+
+def require_main_repo_root() -> Path:
+    """Verify CWD is the main git repo root (or Forge project root), not a child worktree.
+
+    Accepts CWD at a nested Forge project root for monorepo support.
+    For --worktree commands, also checks that we're not inside a child worktree.
+
+    Returns:
+        The validated CWD on success.
+    """
+    from forge.core.ops.context import find_forge_root
+    from forge.session.claude.paths import find_project_root
+    from forge.session.exceptions import GitNotFoundError, GitWorktreeError
+    from forge.session.worktree import get_main_repo_root
+
+    cwd = Path.cwd().resolve()
+
+    try:
+        repo_root = find_project_root().resolve()
+    except FileNotFoundError:
+        console.print("[red]Error:[/red] Not in a git repository")
+        sys.exit(1)
+
+    # Resolve main repo root before any error so the tip is always correct
+    try:
+        main_root = get_main_repo_root(repo_root).resolve()
+    except (GitWorktreeError, GitNotFoundError):
+        main_root = repo_root
+
+    if repo_root != main_root:
+        # Any location inside a child worktree (root or subfolder)
+        console.print(
+            "[red]Error:[/red] Cannot create worktrees from inside a child worktree. "
+            f"Run from the main repository root ({display_path(main_root)})"
+        )
+        console.print(f"\n[dim]Tip: cd {display_path(main_root)}[/dim]")
+        sys.exit(1)
+
+    # Accept CWD at a Forge project root (nested or top-level)
+    forge_root = find_forge_root(cwd)
+    if forge_root is not None and forge_root == cwd:
+        return cwd
+
+    if cwd != repo_root:
+        # Subfolder of the main repo without .forge/
+        console.print(
+            f"[red]Error:[/red] Must run from the repository root ({display_path(repo_root)}), " f"not a subdirectory"
+        )
+        console.print(f"\n[dim]Tip: cd {display_path(repo_root)}[/dim]")
+        sys.exit(1)
+
+    return cwd

forge/cli/handoff.py

@@ -0,0 +1,110 @@
+"""Handoff agent CLI commands.
+
+Commands:
+- forge handoff run: Execute the handoff agent for a session (background process)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+import click
+
+logger = logging.getLogger(__name__)
+
+
+@click.group(hidden=True)
+def handoff() -> None:
+    """Manage handoff agent operations."""
+
+
+@handoff.command("run")
+@click.option("--session-name", required=True, help="Forge session name")
+@click.option(
+    "--worktree-path",
+    required=True,
+    type=click.Path(exists=True),
+    help="Absolute path to the worktree",
+)
+@click.option(
+    "--transcript-rel",
+    required=True,
+    help="Repo-relative path to transcript artifact",
+)
+@click.option("--timeout", default=None, type=int, help="Max seconds for agent to run")
+@click.option("--subprocess-proxy", default=None, hidden=True, help="Stop-time subprocess proxy snapshot")
+@click.option("--root", "forge_root", default=None, type=click.Path(), hidden=True, help="Explicit Forge project root")
+def run_cmd(
+    session_name: str,
+    worktree_path: str,
+    transcript_rel: str,
+    timeout: int | None,
+    subprocess_proxy: str | None,
+    forge_root: str | None,
+) -> None:
+    """Run the handoff agent for a completed session.
+
+    This is typically invoked by the work queue handler as a background process,
+    not directly by users. It reads the session manifest, checks if handoff is
+    enabled, and spawns claude -p to update project memory documents.
+    """
+    worktree = Path(worktree_path).resolve()
+    effective_root = Path(forge_root).resolve() if forge_root else worktree
+
+    # We use SessionStore directly (not resolve_session_store) because this
+    # runs as a detached background process without FORGE_SESSION env var set.
+    # The marker payload carries session_name explicitly.
+    try:
+        from forge.session.effective import compute_effective_intent
+        from forge.session.store import SessionStore
+
+        store = SessionStore(str(effective_root), session_name)
+        if not store.exists():
+            logger.info("No session manifest for %s in %s", session_name, worktree)
+            return
+
+        manifest = store.read()
+        effective = compute_effective_intent(manifest)
+    except Exception as e:
+        logger.warning("Failed to read session manifest for %s: %s", session_name, e)
+        raise SystemExit(1)
+
+    if not effective.memory or not effective.memory.auto_update:
+        logger.info("Handoff not configured for session %s", session_name)
+        return
+
+    config = effective.memory.auto_update
+    if not config.enabled:
+        logger.info("Handoff disabled for session %s", session_name)
+        return
+
+    from forge.session.handoff_agent import resolve_handoff_base_url, run_handoff_agent
+
+    confirmed_proxy_url = None
+    if manifest.confirmed.started_with_proxy:
+        confirmed_proxy_url = manifest.confirmed.started_with_proxy.base_url
+
+    base_url = resolve_handoff_base_url(
+        proxy_id=config.proxy,
+        confirmed_proxy_base_url=confirmed_proxy_url,
+        env_base_url=os.environ.get("ANTHROPIC_BASE_URL"),
+        direct=config.direct,
+        subprocess_proxy=subprocess_proxy or effective.subprocess_proxy,
+    )
+
+    designated_docs = effective.memory.designated_docs if effective.memory else []
+
+    success = run_handoff_agent(
+        session_name=session_name,
+        forge_root=effective_root,
+        transcript_snapshot_rel=transcript_rel,
+        config=config,
+        base_url=base_url,
+        timeout_seconds=timeout,
+        designated_docs=designated_docs,
+    )
+
+    if not success:
+        raise SystemExit(1)

forge/cli/hooks/__init__.py

@@ -0,0 +1,36 @@
+"""CLI hook commands for Claude Code integration.
+
+This package was decomposed from a single 2,490-line ``hooks.py`` module (L7).
+Each submodule owns a distinct concern:
+
+- ``_group``: Click group definition
+- ``commands``: Hook entry points (session-start, plan-write, stop, etc.)
+- ``verification``: Ralph-Wiggum verification logic
+- ``direct_commands``: ``%`` command dispatcher and handlers
+- ``policy``: Policy check helpers
+- ``install``: Hook enable/disable
+- ``_helpers``: Shared I/O helpers
+"""
+
+from __future__ import annotations
+
+# The Click group — imported by cli/main.py
+from ._group import hooks
+from . import commands as _commands  # noqa: F401  — registers @hooks.command() decorators
+from .install import FORGE_HOOK_CONFIG, SETTINGS_FILENAME, enable, disable
+from .verification import (
+    _get_last_assistant_text_for_verification,
+    _run_verification_check,
+)
+
+# Register enable/disable as subcommands of the hooks group
+hooks.add_command(enable)
+hooks.add_command(disable)
+
+__all__ = [
+    "hooks",
+    "FORGE_HOOK_CONFIG",
+    "SETTINGS_FILENAME",
+    "_run_verification_check",
+    "_get_last_assistant_text_for_verification",
+]

forge/cli/hooks/_group.py

@@ -0,0 +1,20 @@
+"""Click group for Forge hook commands."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.group(name="hook", hidden=True)
+@click.pass_context
+def hooks(ctx: click.Context) -> None:
+    """Hook handlers invoked by Claude Code.
+
+    Most subcommands are invoked automatically by Claude Code hooks
+    configured in .claude/settings.local.json. The 'enable' and
+    'disable' subcommands are user-facing.
+    """
+    from forge.core.logging import configure_debug_logging
+
+    hook_name = ctx.invoked_subcommand or "hook"
+    configure_debug_logging(component=hook_name, subdirectory="hooks")

forge/cli/hooks/_helpers.py

@@ -0,0 +1,149 @@
+"""Shared I/O helpers used across hook command modules."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+
+from forge.session.hooks import HookResult
+from forge.session.models import SessionState
+
+
+def _find_latest_plan_from_transcript(transcript_path: str, cwd: Path) -> Path | None:
+    """Streaming scan for last plan file write.
+
+    This is a fallback only; it avoids loading the entire transcript into memory.
+    """
+
+    path = Path(transcript_path)
+    if not path.is_file():
+        return None
+
+    latest: Path | None = None
+    try:
+        with path.open(encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                if entry.get("type") != "assistant":
+                    continue
+
+                message = entry.get("message")
+                if not isinstance(message, dict):
+                    continue
+
+                content = message.get("content")
+                if not isinstance(content, list):
+                    continue
+
+                for block in content:
+                    if not isinstance(block, dict):
+                        continue
+                    if block.get("type") != "tool_use":
+                        continue
+                    if block.get("name") != "Write":
+                        continue
+
+                    tool_input = block.get("input")
+                    if not isinstance(tool_input, dict):
+                        continue
+
+                    fp = tool_input.get("file_path")
+                    if not isinstance(fp, str) or not fp:
+                        continue
+
+                    if "/.claude/plans/" not in fp and not fp.startswith(".claude/plans/"):
+                        continue
+
+                    candidate = Path(fp)
+                    if candidate.is_absolute():
+                        try:
+                            candidate = candidate.resolve().relative_to(cwd)
+                        except Exception:
+                            pass
+
+                    latest = cwd / candidate
+    except Exception:
+        return latest
+
+    return latest
+
+
+def _output_json(data: dict[str, Any]) -> None:
+    """Output hook result as JSON to stdout.
+
+    For non-SessionStart hooks, we return a small JSON payload for debugging,
+    but avoid any UI-facing `systemMessage`.
+    """
+    click.echo(json.dumps(data, indent=2))
+
+
+def _output_result(result: HookResult) -> None:
+    """Output SessionStart hook result as JSON to stdout."""
+    _output_json(result.to_dict())
+
+
+def _read_stdin_json() -> tuple[dict[str, Any] | None, str | None]:
+    """Read hook JSON payload from stdin.
+
+    Returns:
+        (parsed_dict, error)
+
+        - If input is empty/whitespace: (None, "empty")
+        - If JSON is invalid or not an object: (None, "invalid_json")
+        - If valid: (dict, None)
+    """
+
+    stdin_data = sys.stdin.read()
+    if not stdin_data.strip():
+        return None, "empty"
+
+    try:
+        parsed = json.loads(stdin_data)
+    except Exception:
+        return None, "invalid_json"
+
+    if not isinstance(parsed, dict):
+        return None, "invalid_json"
+
+    return parsed, None
+
+
+def _print_session_tip(manifest: SessionState) -> None:
+    """No-op: SessionEnd hook output is suppressed by Claude Code.
+
+    See anthropics/claude-code#9090. The reconnect tip is printed from
+    the parent launcher process instead (_print_post_exit_tip in session.py).
+    Kept as a stub so the session-end hook doesn't break if called.
+    """
+
+
+def _append_artifact_entry(
+    confirmed_artifacts: dict[str, Any],
+    *,
+    kind: str,
+    entry: dict[str, Any],
+) -> None:
+    """Append an artifact record under confirmed.artifacts in a stable shape."""
+
+    items = confirmed_artifacts.get(kind)
+    if items is None:
+        confirmed_artifacts[kind] = [entry]
+        return
+
+    if not isinstance(items, list):
+        # If the field was corrupted or mis-typed, clobber to a list.
+        confirmed_artifacts[kind] = [entry]
+        return
+
+    items.append(entry)