forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/runtime/prepare.py

@@ -0,0 +1,199 @@
+"""Fast repository context for AI wrapper commands — no full codebase indexing."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from forgecli.optimizer.optimizer import ContextOptimizer
+from forgecli.optimizer.ponytail import Intensity, PonytailRulesetOptimizer
+from forgecli.providers.base import ChatMessage, ChatRequest, Role
+from forgecli.runtime.cache_store import (
+    CachedRuntime,
+    load_runtime_cache,
+    repo_fingerprint,
+    save_runtime_cache,
+)
+from forgecli.utils.paths import ProjectPaths
+
+_SKIP_DIRS = {
+    ".git",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+    "dist",
+    "build",
+    ".forge",
+    "graphify-out",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+}
+
+
+@dataclass(frozen=True)
+class PreparedRuntime:
+    """Optimized repository context ready for a wrapper CLI."""
+
+    root: Path
+    context_summary: str
+    context_file: Path
+    from_cache: bool
+
+    @classmethod
+    def from_cached(cls, root: Path, cached: CachedRuntime) -> PreparedRuntime:
+        return cls(
+            root=root,
+            context_summary=cached.context_summary,
+            context_file=Path(cached.context_file),
+            from_cache=True,
+        )
+
+
+def resolve_repo_root(start: Path) -> Path:
+    """Return the nearest git repository root, or ``start`` when not in a repo."""
+    start = start.resolve()
+    for candidate in (start, *start.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return start
+
+
+def _git_line(root: Path) -> str | None:
+    from forgecli.platform.shell import run
+
+    branch = run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=root)
+    if branch.ok and branch.stdout.strip():
+        return f"Branch: {branch.stdout.strip()}"
+    return None
+
+
+def _scan_repo_light(root: Path) -> str:
+    """Build a small repo snapshot without indexing the full codebase."""
+    lines = [
+        f"Repository: {root.name}",
+        f"Root: {root}",
+    ]
+    git_info = _git_line(root)
+    if git_info:
+        lines.append(git_info)
+
+    layout: list[str] = []
+    try:
+        for entry in sorted(root.iterdir(), key=lambda p: p.name.lower())[:36]:
+            if entry.name in _SKIP_DIRS or entry.name.startswith("."):
+                continue
+            if entry.is_dir():
+                layout.append(f"{entry.name}/")
+                try:
+                    for child in sorted(entry.iterdir(), key=lambda p: p.name.lower())[:6]:
+                        if child.name in _SKIP_DIRS or child.name.startswith("."):
+                            continue
+                        suffix = "/" if child.is_dir() else ""
+                        layout.append(f"  {child.name}{suffix}")
+                except OSError:
+                    pass
+            else:
+                layout.append(entry.name)
+    except OSError:
+        pass
+
+    if layout:
+        lines.extend(["", "Project layout (shallow scan):", *layout[:72]])
+
+    graph_marker = root / "graphify-out" / "graph.json"
+    if graph_marker.is_file():
+        lines.append("")
+        lines.append(
+            "Knowledge graph already on disk at graphify-out/. "
+            "Run `forge graph build` separately when you want a full refresh."
+        )
+
+    return "\n".join(lines)
+
+
+def _optimize_prompt(context: str) -> str:
+    import asyncio
+
+    optimizer = PonytailRulesetOptimizer(intensity=Intensity.LITE)
+    request = ChatRequest(
+        model="runtime",
+        messages=[
+            ChatMessage(
+                role=Role.SYSTEM,
+                content="Prepare concise repository context for an AI coding assistant.",
+            ),
+            ChatMessage(
+                role=Role.USER,
+                content=(
+                    "Optimize this repo snapshot for the next coding task. "
+                    "Prefer reuse, minimal diffs, and existing patterns.\n\n"
+                    f"{context}"
+                ),
+            ),
+        ],
+    )
+    optimized = asyncio.run(optimizer.optimize_chat(request))
+    user = next(
+        (message.content for message in optimized.request.messages if message.role is Role.USER),
+        context,
+    )
+    return user.strip() or context
+
+
+def _optimize_tokens(text: str) -> str:
+    optimizer = ContextOptimizer(max_context_tokens=8_000)
+    result = optimizer.optimize(text)
+    if not result.chunks:
+        return text[:12_000]
+    merged = "\n".join(chunk.text for chunk in result.chunks[:24])
+    return merged[:12_000]
+
+
+def prepare_runtime_sync(
+    start: Path,
+    *,
+    force: bool = False,
+    quiet: bool = False,
+) -> PreparedRuntime:
+    """Prepare lightweight optimized context — no full graph build."""
+    root = resolve_repo_root(start)
+    fingerprint = repo_fingerprint(root)
+
+    if not force:
+        cached = load_runtime_cache(fingerprint)
+        if cached is not None:
+            return PreparedRuntime.from_cached(root, cached)
+
+    raw_context = _scan_repo_light(root)
+    prompt_optimized = _optimize_prompt(raw_context)
+    token_optimized = _optimize_tokens(prompt_optimized)
+
+    cache_dir = ProjectPaths.from_env().cache_dir / "runtime" / "context"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    context_file = cache_dir / f"{fingerprint}.md"
+    context_file.write_text(token_optimized, encoding="utf-8")
+
+    save_runtime_cache(
+        fingerprint,
+        CachedRuntime(
+            context_summary=token_optimized,
+            context_file=str(context_file),
+            node_count=0,
+            edge_count=0,
+            created_at=time.time(),
+        ),
+    )
+
+    if not quiet:
+        from forgecli.cli.ui import info
+
+        info(f"Optimized context for [accent]{root.name}[/accent] (cached for reuse)")
+
+    return PreparedRuntime(
+        root=root,
+        context_summary=token_optimized,
+        context_file=context_file,
+        from_cache=False,
+    )

forgecli/runtime/wrappers.py

@@ -0,0 +1,152 @@
+"""Launch Claude Code, Codex, Cursor, OpenCode, and CommandCode CLI with Forge-optimized context."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+
+from forgecli.cli.commands_graph import setup_graphify_credentials
+from forgecli.cli.ui import error, get_console, info
+from forgecli.graph.backend_graphify import GraphifyRepositoryGraph
+from forgecli.platform.shell import which
+from forgecli.runtime.prepare import prepare_runtime_sync, resolve_repo_root
+from forgecli.utils.fs import has_supported_source_files
+
+_SKIP_DIRS = {
+    ".git",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+    "dist",
+    "build",
+    ".forge",
+    "graphify-out",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+}
+
+
+@dataclass(frozen=True)
+class WrapperSpec:
+    name: str
+    binary: str
+    install_hint: str
+
+
+WRAPPERS: dict[str, WrapperSpec] = {
+    "claude": WrapperSpec(
+        name="Claude Code",
+        binary="claude",
+        install_hint="Install Claude Code: https://docs.anthropic.com/en/docs/claude-code",
+    ),
+    "codex": WrapperSpec(
+        name="Codex CLI",
+        binary="codex",
+        install_hint="Install OpenAI Codex CLI: https://developers.openai.com/codex/cli/",
+    ),
+    "cursor": WrapperSpec(
+        name="Cursor CLI",
+        binary="cursor",
+        install_hint="Install Cursor CLI: https://cursor.com/docs/cli/overview",
+    ),
+    "opencode": WrapperSpec(
+        name="OpenCode CLI",
+        binary="opencode",
+        install_hint="Install OpenCode CLI: https://opencode.ai/",
+    ),
+    "commandcode": WrapperSpec(
+        name="CommandCode CLI",
+        binary="commandcode",
+        install_hint="Install CommandCode CLI: https://commandcode.ai/",
+    ),
+}
+
+
+def launch_wrapper(
+    wrapper_id: str,
+    extra_args: list[str] | None = None,
+    *,
+    path: Path | None = None,
+    force_prepare: bool = False,
+) -> None:
+    """Prepare lightweight context, build/update graph, and launch the selected AI CLI."""
+    spec = WRAPPERS.get(wrapper_id)
+    if spec is None:
+        error(f"Unknown wrapper: {wrapper_id}")
+        raise typer.Exit(code=1)
+
+    binary_path = which(spec.binary)
+    if binary_path is None and wrapper_id == "commandcode":
+        # Check alternative binary names for commandcode
+        binary_path = which("command-code")
+
+    if binary_path is None:
+        console = get_console()
+        console.print(f"[red]✗[/red] {spec.name} is not installed.")
+        console.print(spec.install_hint)
+        raise typer.Exit(code=1)
+
+    # 1. Detect current repository
+    cwd = (path or Path.cwd()).resolve()
+    repo_root = resolve_repo_root(cwd)
+
+    # 2. Build or update the repository knowledge graph
+    backend = GraphifyRepositoryGraph(root=repo_root)
+    if asyncio.run(backend.is_available()) and has_supported_source_files(repo_root):
+        active_provider = setup_graphify_credentials(repo_root)
+        if not active_provider:
+            error(
+                "No API key configured. Run 'forge auth login' or export "
+                "OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY before running 'forge graph build'."
+            )
+            raise typer.Exit(code=1)
+
+        graph_json = backend.artifacts.graph_json
+        needs_build = not graph_json.exists()
+        needs_update = False
+
+        if graph_json.exists() and not force_prepare:
+            graph_mtime = graph_json.stat().st_mtime
+            for p in repo_root.rglob('*'):
+                try:
+                    parts = p.relative_to(repo_root).parts
+                    if any(part.startswith('.') or part in _SKIP_DIRS for part in parts[:-1]):
+                        continue
+                    if p.is_file() and not p.name.startswith('.') and p.stat().st_mtime > graph_mtime:
+                        needs_update = True
+                        break
+                except ValueError:
+                    continue
+
+            if force_prepare or needs_build:
+                info("Building repository knowledge graph...")
+                asyncio.run(backend.build(force=force_prepare))
+            elif needs_update:
+                info("Updating repository knowledge graph...")
+                asyncio.run(backend.update_graph())
+
+    # 3-6. Optimize context, prompts, and tokens (aggressively reusing cache)
+    prepared = prepare_runtime_sync(repo_root, force=force_prepare, quiet=False)
+    if prepared.from_cache:
+        info("Reusing cached Forge context.")
+
+    env = os.environ.copy()
+    env["FORGE_CONTEXT"] = prepared.context_summary
+    env["FORGE_CONTEXT_FILE"] = str(prepared.context_file)
+    env["FORGE_REPO_ROOT"] = str(prepared.root)
+
+    argv = [binary_path, *(extra_args or [])]
+    info(f"Launching [accent]{spec.name}[/accent] ...")
+
+    completed = subprocess.run(
+        argv,
+        cwd=str(prepared.root),
+        env=env,
+    )
+    raise typer.Exit(code=completed.returncode)

forgecli/sdk/__init__.py

@@ -0,0 +1,132 @@
+"""The ForgeCLI Plugin SDK.
+
+The SDK is the *contract* third-party developers use to extend
+ForgeCLI. It provides:
+
+* :mod:`forgecli.sdk.manifest`  — typed plugin metadata (TOML).
+* :mod:`forgecli.sdk.version`    — semver parsing + dep resolution.
+* :mod:`forgecli.sdk.loader`     — discovery (filesystem + entry-point).
+* :mod:`forgecli.sdk.events`     — pub/sub bus + hook manager.
+* :mod:`forgecli.sdk.sandbox`    — restricted-exec for plugin callbacks.
+* :mod:`forgecli.sdk.interfaces` — the 10 canonical plugin types.
+* :mod:`forgecli.sdk.manager`    — the :class:`PluginManager` façade
+  (install / enable / disable / uninstall / update / configure).
+
+See :file:`PLUGINS.md` for the end-to-end developer guide.
+"""
+
+from forgecli.sdk.events import (
+    HookManager,
+    PluginEvent,
+    PluginEventBus,
+    PluginEventKind,
+    PluginHook,
+)
+from forgecli.sdk.interfaces import (
+    AIProviderPlugin,
+    CodeGeneratorPlugin,
+    ContextOptimizerPlugin,
+    DeploymentProviderPlugin,
+    DocumentationGeneratorPlugin,
+    GitProviderPlugin,
+    HealthIssue,
+    HealthReport,
+    NotificationProviderPlugin,
+    ObservabilityProviderPlugin,
+    PluginConfigurable,
+    PluginHealthCheck,
+    RepositoryAnalyzerPlugin,
+    TestRunnerPlugin,
+)
+from forgecli.sdk.loader import (
+    LoadedPlugin,
+    default_plugins_dir,
+    discover_entry_points,
+    discover_filesystem,
+    load_filesystem,
+)
+from forgecli.sdk.loader import (
+    PluginManifestNotFoundError as PluginManifestNotFound,
+)
+from forgecli.sdk.manager import (
+    PluginAlreadyInstalledError,
+    PluginCompatibilityError,
+    PluginError,
+    PluginManager,
+    PluginNotFoundError,
+    PluginRegistryState,
+    PluginState,
+)
+from forgecli.sdk.manifest import (
+    Compatibility,
+    EntryPoint,
+    EntryPointKind,
+    Permission,
+    PluginManifest,
+    is_valid_plugin_name,
+)
+from forgecli.sdk.sandbox import Sandbox, ScopedBuiltins, run_sandboxed, sandbox
+from forgecli.sdk.version import (
+    DependencyCycleError,
+    Op,
+    Requirement,
+    Spec,
+    UnsatisfiableRequirementError,
+    Version,
+    VersionParseError,
+    resolve,
+)
+
+__all__ = [
+    "AIProviderPlugin",
+    "CodeGeneratorPlugin",
+    "Compatibility",
+    "ContextOptimizerPlugin",
+    "DependencyCycleError",
+    "DeploymentProviderPlugin",
+    "DocumentationGeneratorPlugin",
+    "EntryPoint",
+    "EntryPointKind",
+    "GitProviderPlugin",
+    "HealthIssue",
+    "HealthReport",
+    "HookManager",
+    "LoadedPlugin",
+    "NotificationProviderPlugin",
+    "ObservabilityProviderPlugin",
+    "Op",
+    "Permission",
+    "PluginAlreadyInstalledError",
+    "PluginCompatibilityError",
+    "PluginConfigurable",
+    "PluginError",
+    "PluginEvent",
+    "PluginEventBus",
+    "PluginEventKind",
+    "PluginHealthCheck",
+    "PluginHook",
+    "PluginManager",
+    "PluginManifest",
+    "PluginManifestNotFound",
+    "PluginManifestNotFoundError",
+    "PluginNotFoundError",
+    "PluginRegistryState",
+    "PluginState",
+    "RepositoryAnalyzerPlugin",
+    "Requirement",
+    "Sandbox",
+    "ScopedBuiltins",
+    "Spec",
+    "TestRunnerPlugin",
+    "UnsatisfiableRequirementError",
+    "Version",
+    "VersionParseError",
+    "default_plugins_dir",
+    "discover_entry_points",
+    "discover_filesystem",
+    "is_valid_plugin_name",
+    "load_filesystem",
+    "resolve",
+    "run_sandboxed",
+    "sandbox",
+]

forgecli/sdk/events.py

@@ -0,0 +1,206 @@
+"""Plugin event bus + hook manager.
+
+The SDK exposes:
+
+* :class:`PluginEventBus` — a tiny pub/sub bus for plugin
+  lifecycle and runtime events. Distinct from the engine's
+  :class:`~forgecli.engine.events.EventBus` (which is for the
+  eight-stage pipeline). The two are independent so plugins can
+  listen to the engine *and* the plugin lifecycle without coupling.
+* :class:`PluginHook` and :class:`HookManager` — synchronous
+  before/after hooks the SDK fires when a plugin is installed,
+  enabled, disabled, updated, or uninstalled.
+
+Plugins subscribe at enable-time; the SDK guarantees that the
+event handlers are called for every registered subscriber, even
+if one raises (failures are logged and isolated).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+_logger = logging.getLogger("forgecli.sdk.events")
+
+
+# ---------------------------------------------------------------------------
+# Event types
+# ---------------------------------------------------------------------------
+
+
+class PluginEventKind(str, Enum):
+    """The high-level events plugins can listen to."""
+
+    INSTALLED = "installed"
+    ENABLED = "enabled"
+    DISABLED = "disabled"
+    UNINSTALLED = "uninstalled"
+    UPDATED = "updated"
+    BEFORE_COMMAND = "before_command"
+    AFTER_COMMAND = "after_command"
+    CONFIG_CHANGED = "config_changed"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class PluginEvent:
+    """A single lifecycle / runtime event."""
+
+    kind: PluginEventKind
+    plugin_name: str | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+EventHandler = Callable[[PluginEvent], "None | Awaitable[None]"]
+
+
+# ---------------------------------------------------------------------------
+# Event bus
+# ---------------------------------------------------------------------------
+
+
+class PluginEventBus:
+    """In-process pub/sub bus for plugin events.
+
+    Async-aware: subscribers may be sync or async. The bus
+    serialises fan-out for synchronous subscribers and schedules
+    coroutines for async ones.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[PluginEventKind, list[EventHandler]] = {}
+
+    def subscribe(self, kind: PluginEventKind, handler: EventHandler) -> None:
+        self._subscribers.setdefault(kind, []).append(handler)
+
+    def unsubscribe(self, kind: PluginEventKind, handler: EventHandler) -> None:
+        bucket = self._subscribers.get(kind)
+        if not bucket:
+            return
+        with _suppress(ValueError):
+            bucket.remove(handler)
+
+    def publish(self, event: PluginEvent) -> None:
+        """Publish synchronously. Async handlers are scheduled."""
+        for handler in list(self._subscribers.get(event.kind, ())):
+            try:
+                result = handler(event)
+            except Exception:
+                _logger.exception("plugin event handler raised")
+                continue
+            if asyncio.iscoroutine(result):
+                try:
+                    loop = asyncio.get_running_loop()
+                    task = loop.create_task(result)
+                    task.add_done_callback(_discard_task)
+                except RuntimeError:
+                    pass
+
+    async def publish_and_drain(self, event: PluginEvent) -> None:
+        """Publish and await any async handler results."""
+        for handler in list(self._subscribers.get(event.kind, ())):
+            try:
+                result = handler(event)
+            except Exception:
+                _logger.exception("plugin event handler raised")
+                continue
+            if asyncio.iscoroutine(result):
+                await result
+
+
+# ---------------------------------------------------------------------------
+# Hook manager
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PluginHook:
+    """A single registered hook.
+
+    ``callback`` may be sync or async. The SDK wraps it in
+    :func:`asyncio.iscoroutine` before calling so plugins can
+    return a coroutine for async work.
+    """
+
+    name: str
+    callback: Callable[..., Any]
+
+
+class HookManager:
+    """Synchronous registry of before/after hooks."""
+
+    def __init__(self) -> None:
+        self._before: list[PluginHook] = []
+        self._after: list[PluginHook] = []
+
+    def before(self, hook: PluginHook) -> None:
+        self._before.append(hook)
+
+    def after(self, hook: PluginHook) -> None:
+        self._after.append(hook)
+
+    def fire_before(self, *args: Any, **kwargs: Any) -> None:
+        for hook in self._before:
+            try:
+                hook.callback(*args, **kwargs)
+            except Exception:
+                _logger.exception("hook %s failed (before)", hook.name)
+
+    def fire_after(self, *args: Any, **kwargs: Any) -> None:
+        for hook in self._after:
+            try:
+                hook.callback(*args, **kwargs)
+            except Exception:
+                _logger.exception("hook %s failed (after)", hook.name)
+
+    async def fire_before_async(self, *args: Any, **kwargs: Any) -> None:
+        for hook in self._before:
+            try:
+                result = hook.callback(*args, **kwargs)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception:
+                _logger.exception("hook %s failed (before)", hook.name)
+
+    async def fire_after_async(self, *args: Any, **kwargs: Any) -> None:
+        for hook in self._after:
+            try:
+                result = hook.callback(*args, **kwargs)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception:
+                _logger.exception("hook %s failed (after)", hook.name)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+@contextlib.contextmanager
+def _suppress(*exceptions: type[BaseException]):
+    with contextlib.suppress(*exceptions):
+        yield
+
+
+def _discard_task(task: asyncio.Task) -> None:
+    """Keep a strong reference to a scheduled task until it completes."""
+    return None
+
+
+__all__ = [
+    "EventHandler",
+    "HookManager",
+    "PluginEvent",
+    "PluginEventBus",
+    "PluginEventKind",
+    "PluginHook",
+]