forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/sdk/version.py

@@ -0,0 +1,316 @@
+"""Version parsing + comparison + dependency resolution.
+
+The SDK uses a pragmatic PEP-440-ish semver triple with optional
+pre-release and build-metadata tags. Compatibility resolution uses
+the same algorithm pip uses for ``~=`` and ``>=``:
+
+* ``~=X.Y``     — ``>=X.Y, <(X+1)``
+* ``~=X.Y.Z``   — ``>=X.Y.Z, <X.(Y+1)``
+* ``X.Y.Z``     — exact match
+* ``X.Y``       — any patch of X.Y
+* ``>=X.Y.Z``   — at least X.Y.Z
+* ``>X.Y.Z``    — strictly greater
+* ``*``         — wildcard
+
+Missing version specifier means "any version".
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Version parsing
+# ---------------------------------------------------------------------------
+
+
+class VersionParseError(ValueError):
+    """Raised when a version string is malformed."""
+
+
+@dataclass(frozen=True, order=True)
+class Version:
+    """A parsed semantic-style version."""
+
+    major: int
+    minor: int
+    patch: int
+    pre: tuple[tuple[str, int], ...] = ()
+    build: str = ""
+
+    @classmethod
+    def parse(cls, value: str) -> Version:
+        if not value or not isinstance(value, str):
+            raise VersionParseError(f"invalid version: {value!r}")
+        # Accept both ``1.2.3a1`` (PEP-440-ish) and ``1.2.3-a1``
+        # (semver-style). We normalise to the second form so the
+        # pre-release parsing below sees a single canonical shape.
+        normalised = value.strip()
+        m = re.match(
+            r"^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?"
+            r"(?:(-[0-9A-Za-z-.]+)|([0-9]+[A-Za-z]+[0-9A-Za-z-]*))?"
+            r"(?:\+([0-9A-Za-z-.]+))?$",
+            normalised,
+        )
+        if not m:
+            raise VersionParseError(f"invalid version: {value!r}")
+        major, minor, patch, dash_pre, no_dash_pre, build = m.groups()
+        pre_tuple: tuple[tuple[str, int], ...] = ()
+        # ``dash_pre`` is the canonical ``-foo.bar`` form. ``no_dash_pre``
+        # is the bare ``1.2.3a1`` form; we prefix a dash so the
+        # downstream splitter sees a single shape.
+        pre_str = dash_pre or ("-" + no_dash_pre if no_dash_pre else "")
+        if pre_str:
+            for chunk in pre_str.lstrip("-").split("."):
+                match = re.match(r"^([0-9A-Za-z]+)(\d*)$", chunk)
+                if not match:
+                    raise VersionParseError(f"invalid pre-release: {pre_str!r}")
+                ident, num = match.groups()
+                pre_tuple = (*pre_tuple, (ident, int(num) if num else -1))
+        return cls(
+            major=int(major),
+            minor=int(minor or 0),
+            patch=int(patch or 0),
+            pre=pre_tuple,
+            build=build or "",
+        )
+
+    def __str__(self) -> str:
+        base = f"{self.major}.{self.minor}.{self.patch}"
+        if self.pre:
+            base += "-" + ".".join(
+                f"{ident}{num}" if num >= 0 else ident
+                for ident, num in self.pre
+            )
+        if self.build:
+            base += f"+{self.build}"
+        return base
+
+    def __repr__(self) -> str:
+        return f"Version({self})"
+
+    def is_prerelease(self) -> bool:
+        return bool(self.pre)
+
+    def without_prerelease(self) -> Version:
+        return Version(self.major, self.minor, self.patch)
+
+
+# ---------------------------------------------------------------------------
+# Spec parsing
+# ---------------------------------------------------------------------------
+
+
+class Op(str, Enum):
+    EQ = "=="
+    NEQ = "!="
+    GT = ">"
+    GE = ">="
+    LT = "<"
+    LE = "<="
+    CARET = "^"  # NOT USED; kept for documentation
+    TILDE = "~="
+
+
+@dataclass(frozen=True)
+class Spec:
+    """A single dependency specifier like ``>=1.2,<2.0``."""
+
+    op: Op
+    version: Version
+
+    def matches(self, other: Version) -> bool:
+        if self.op is Op.EQ:
+            return other == self.version
+        if self.op is Op.NEQ:
+            return other != self.version
+        if self.op is Op.GT:
+            return other > self.version
+        if self.op is Op.GE:
+            return other >= self.version
+        if self.op is Op.LT:
+            return other < self.version
+        if self.op is Op.LE:
+            return other <= self.version
+        if self.op is Op.TILDE:
+            return other >= self.version
+        raise ValueError(f"unsupported op: {self.op}")
+
+    def __str__(self) -> str:
+        return f"{self.op}{self.version}"
+
+
+# A spec string like ``"^1.0 ; extras: graphify"`` is a comma-separated
+# set of Spec clauses plus an optional ``;extras:...`` annotation.
+_SPEC_SEP = ";"
+
+
+@dataclass(frozen=True)
+class Requirement:
+    """A full requirement: name + set of version specs + optional extras."""
+
+    name: str
+    specs: tuple[Any, ...] = ()
+    extras: tuple[str, ...] = ()
+
+    def matches(self, version: Version) -> bool:
+        if not self.specs:
+            return True
+        return all(spec.matches(version) for spec in self.specs)
+
+    @classmethod
+    def parse(cls, name: str, spec_string: str = "") -> Requirement:
+        if not name:
+            raise ValueError("requirement name must be non-empty")
+        specs: list[Any] = []
+        extras: tuple[str, ...] = ()
+        body, sep, tail = spec_string.partition(_SPEC_SEP)
+        if sep:
+            extras_str = tail.strip()
+            if extras_str.startswith("extras:"):
+                extras = tuple(
+                    chunk.strip()
+                    for chunk in extras_str[len("extras:") :].split(",")
+                    if chunk.strip()
+                )
+        for raw in body.split(","):
+            raw = raw.strip()
+            if not raw or raw == "*":
+                continue
+            for op_token in ("==", "!=", ">=", "<=", "~=", ">", "<"):
+                if raw.startswith(op_token):
+                    version_str = raw[len(op_token) :].strip()
+                    if op_token == "~=":
+                        specs.append(_tilde(version_str))
+                    else:
+                        try:
+                            specs.append(Spec(Op(op_token), Version.parse(version_str)))
+                        except VersionParseError:
+                            continue
+                    break
+            else:
+                # Bare version string == exact match.
+                try:
+                    specs.append(Spec(Op.EQ, Version.parse(raw)))
+                except VersionParseError:
+                    continue
+        return cls(name=name, specs=tuple(specs), extras=tuple(extras))
+
+    def __str__(self) -> str:
+        base = self.name
+        if self.specs:
+            base += " " + ",".join(str(s) for s in self.specs)
+        if self.extras:
+            base += f" ; extras: {','.join(self.extras)}"
+        return base
+
+
+def _tilde(version_str: str) -> Any:
+    """Implement the ``~=X.Y`` and ``~=X.Y.Z`` operators."""
+    parts = version_str.split(".")
+    if len(parts) == 1:
+        # ~=2 is invalid; treat as ==
+        return Spec(Op.EQ, Version.parse(version_str))
+    if len(parts) == 2:
+        major, minor = parts
+        low = Version.parse(version_str)
+        high = Version.parse(f"{int(major) + 1}.0")
+    else:
+        major, minor, _patch = parts
+        low = Version.parse(version_str)
+        high = Version.parse(f"{major}.{int(minor) + 1}")
+    # ~="X.Y" means ">=X.Y, <(X+1).0"; the high is exclusive.
+    # We return a synthetic GE spec; the LT spec is folded in below.
+    return _TildeSpec(ge=low, lt=high)
+
+
+@dataclass(frozen=True)
+class _TildeSpec:
+    ge: Version
+    lt: Version
+
+    def matches(self, other: Version) -> bool:
+        return self.ge <= other < self.lt
+
+
+# Replace the simple Spec with one that also supports tilde.
+_Spec = Spec  # type alias retained for clarity; not used below
+
+
+# ---------------------------------------------------------------------------
+# Dependency resolution
+# ---------------------------------------------------------------------------
+
+
+class DependencyCycleError(RuntimeError):
+    """Raised when dependency resolution hits a cycle."""
+
+
+class UnsatisfiableRequirementError(RuntimeError):
+    """Raised when two requirements for the same name disagree."""
+
+
+def resolve(
+    requirements: Iterable[Requirement],
+    candidates: dict[str, tuple[Version, ...]],
+) -> dict[str, Version]:
+    """Pick a single version for every named requirement.
+
+    ``requirements`` is the union of constraints (multiple
+    :class:`Requirement` objects with the same name are intersected).
+    ``candidates`` maps a name to the available versions on PyPI /
+    a local index / etc. The resolver picks the *highest* version
+    that satisfies every constraint, and raises on cycles or
+    contradictions.
+    """
+    constraints: dict[str, list[Requirement]] = {}
+    for req in requirements:
+        constraints.setdefault(req.name, []).append(req)
+
+    chosen: dict[str, Version] = {}
+    while constraints:
+        progress = False
+        for name, reqs in list(constraints.items()):
+            if name in chosen:
+                continue
+            available = candidates.get(name, ())
+            for version in sorted(available, reverse=True):
+                if all(req.matches(version) for req in reqs):
+                    chosen[name] = version
+                    del constraints[name]
+                    progress = True
+                    break
+            else:
+                # Try partial: did we have any candidate at all?
+                if not available:
+                    # Soft skip: caller may not have provided a local
+                    # index for this plugin. We drop the constraint
+                    # silently.
+                    del constraints[name]
+                    progress = True
+                    continue
+                raise UnsatisfiableRequirementError(
+                    f"no version of {name!r} satisfies {', '.join(map(str, reqs))}"
+                )
+        if not progress:
+            # Cycle or stuck.
+            raise DependencyCycleError(
+                f"could not resolve: {sorted(constraints)}"
+            )
+    return chosen
+
+
+__all__ = [
+    "DependencyCycleError",
+    "Op",
+    "Requirement",
+    "Spec",
+    "UnsatisfiableRequirementError",
+    "Version",
+    "VersionParseError",
+    "resolve",
+]

forgecli/templates/__init__.py

@@ -0,0 +1,9 @@
+"""Reusable workflow and project templates."""
+
+from forgecli.templates.engine import TemplateEngine
+from forgecli.templates.registry import TemplateRegistry
+
+__all__ = [
+    "TemplateEngine",
+    "TemplateRegistry",
+]

forgecli/templates/engine.py

@@ -0,0 +1,37 @@
+"""Render reusable project/workflow templates."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+from forgecli.core.service import Service
+from forgecli.utils.fs import atomic_write
+
+
+class TemplateEngine(Service):
+    """Render template strings and materialize them to disk."""
+
+    name = "templates.engine"
+
+    def __init__(self, *, renderer=None) -> None:
+        super().__init__()
+        # Lazy import to keep the templates module usable in tests.
+        from forgecli.prompts.renderer import PromptRenderer
+
+        self._renderer = renderer or PromptRenderer()
+
+    def render(self, template: str, **variables: object) -> str:
+        """Render ``template`` with ``variables`` using the prompt renderer."""
+        return self._renderer.render(template, **variables)
+
+    def materialize(
+        self,
+        target: Path,
+        template: str,
+        *,
+        variables: Mapping[str, object] | None = None,
+    ) -> Path:
+        """Render ``template`` and atomically write it to ``target``."""
+        content = self.render(template, **(dict(variables) if variables else {}))
+        return atomic_write(target, content)

forgecli/templates/registry.py

@@ -0,0 +1,32 @@
+"""In-memory registry of named templates."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from forgecli.core.service import Service
+
+
+class TemplateRegistry(Service):
+    """Stores named templates; higher-level loaders can hydrate it from disk."""
+
+    name = "templates.registry"
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._templates: dict[str, str] = {}
+
+    def register(self, name: str, template: str) -> None:
+        self._templates[name] = template
+
+    def get(self, name: str) -> str:
+        try:
+            return self._templates[name]
+        except KeyError as exc:
+            raise KeyError(f"Template not registered: {name!r}") from exc
+
+    def names(self) -> list[str]:
+        return sorted(self._templates)
+
+    def items(self) -> Iterable[tuple[str, str]]:
+        return self._templates.items()

forgecli/utils/__init__.py

@@ -0,0 +1,19 @@
+"""Shared utility helpers."""
+
+from forgecli.utils.fs import atomic_write, ensure_dir, read_text, write_text
+from forgecli.utils.ids import new_id
+from forgecli.utils.io import aio_read_text, aio_write_text
+from forgecli.utils.paths import ProjectPaths
+from forgecli.utils.timing import Timer
+
+__all__ = [
+    "ProjectPaths",
+    "Timer",
+    "aio_read_text",
+    "aio_write_text",
+    "atomic_write",
+    "ensure_dir",
+    "new_id",
+    "read_text",
+    "write_text",
+]

forgecli/utils/fs.py

@@ -0,0 +1,91 @@
+"""Filesystem helpers (sync)."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from collections.abc import Iterable
+from pathlib import Path
+
+
+def ensure_dir(path: os.PathLike[str] | str) -> Path:
+    """Create ``path`` (and parents) if missing; return the resolved Path."""
+    p = Path(path).expanduser()
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def read_text(path: os.PathLike[str] | str, *, encoding: str = "utf-8") -> str:
+    """Read text from ``path`` and return it as a string."""
+    return Path(path).read_text(encoding=encoding)
+
+
+def write_text(
+    path: os.PathLike[str] | str,
+    content: str,
+    *,
+    encoding: str = "utf-8",
+) -> Path:
+    """Write ``content`` to ``path``, creating parent directories as needed."""
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(content, encoding=encoding)
+    return p
+
+
+def atomic_write(
+    path: os.PathLike[str] | str,
+    content: str,
+    *,
+    encoding: str = "utf-8",
+) -> Path:
+    """Atomically write ``content`` to ``path`` via a temporary file."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=target.name + ".",
+        dir=str(target.parent),
+    )
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as fh:
+            fh.write(content)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp_name, target)
+    except Exception:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_name)
+        raise
+    return target
+
+
+def iter_files(root: os.PathLike[str] | str, patterns: Iterable[str]) -> Iterable[Path]:
+    """Yield files under ``root`` matching any of the given glob ``patterns``."""
+    base = Path(root)
+    for pattern in patterns:
+        yield from base.glob(pattern)
+
+
+def has_supported_source_files(path: Path) -> bool:
+    supported_exts = {
+        '.py', '.js', '.ts', '.jsx', '.tsx', '.go', '.rs', '.c', '.cpp', '.cc', '.h', '.hpp',
+        '.java', '.rb', '.php', '.cs', '.html', '.css', '.sh', '.md', '.toml', '.json', '.yaml', '.yml'
+    }
+    ignored_dirs = {
+        '.git', '.venv', '__pycache__', 'node_modules', 'dist', 'build', '.forge',
+        'graphify-out', '.mypy_cache', '.pytest_cache', '.ruff_cache'
+    }
+    if not path.exists() or not path.is_dir():
+        return False
+    for p in path.rglob('*'):
+        try:
+            parts = p.relative_to(path).parts
+            if any(part.startswith('.') or part in ignored_dirs for part in parts[:-1]):
+                continue
+            if p.is_file() and not p.name.startswith('.') and p.suffix.lower() in supported_exts:
+                return True
+        except ValueError:
+            continue
+    return False
+

forgecli/utils/ids.py

@@ -0,0 +1,11 @@
+"""Identifier generation helpers."""
+
+from __future__ import annotations
+
+import secrets
+
+
+def new_id(prefix: str = "id", *, length: int = 12) -> str:
+    """Return a short URL-safe unique identifier, optionally prefixed."""
+    body = secrets.token_hex(length)
+    return f"{prefix}_{body}" if prefix else body

forgecli/utils/io.py

@@ -0,0 +1,27 @@
+"""Async filesystem helpers."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import aiofiles  # type: ignore[import-untyped]
+
+
+async def aio_read_text(path: os.PathLike[str] | str, *, encoding: str = "utf-8") -> str:
+    """Asynchronously read text from ``path``."""
+    async with aiofiles.open(path, encoding=encoding) as fh:
+        return await fh.read()
+
+
+async def aio_write_text(
+    path: os.PathLike[str] | str,
+    content: str,
+    *,
+    encoding: str = "utf-8",
+) -> None:
+    """Asynchronously write text to ``path``."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    async with aiofiles.open(target, mode="w", encoding=encoding) as fh:
+        await fh.write(content)

forgecli/utils/paths.py

@@ -0,0 +1,70 @@
+"""Resolve common filesystem locations used by ForgeCLI."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ProjectPaths:
+    """Bundle of well-known paths used across the application."""
+
+    cwd: Path
+    config_dir: Path
+    data_dir: Path
+    cache_dir: Path
+    logs_dir: Path
+    prompts_dir: Path
+    plugins_dir: Path
+
+    @classmethod
+    def from_env(cls, *, cwd: os.PathLike[str] | str | None = None) -> ProjectPaths:
+        """Compute the default project paths using ``platformdirs`` semantics.
+
+        ``FORGECLI_DATA_DIR`` and ``FORGECLI_CONFIG_DIR`` may be set to
+        override the per-OS defaults (useful for tests and CI).
+        """
+        from platformdirs import PlatformDirs  # local import to keep deps light
+
+        dirs = PlatformDirs("forgecli", appauthor=False, version=None)
+        cwd_path = Path(cwd) if cwd is not None else Path.cwd()
+        data_dir = Path(os.environ["FORGECLI_DATA_DIR"]) if os.environ.get("FORGECLI_DATA_DIR") else Path(dirs.user_data_dir)
+        config_dir = Path(os.environ["FORGECLI_CONFIG_DIR"]) if os.environ.get("FORGECLI_CONFIG_DIR") else Path(dirs.user_config_dir)
+        return cls(
+            cwd=cwd_path,
+            config_dir=config_dir,
+            data_dir=data_dir,
+            cache_dir=Path(dirs.user_cache_dir),
+            logs_dir=Path(dirs.user_log_dir),
+            prompts_dir=config_dir / "prompts",
+            plugins_dir=config_dir / "plugins",
+        )
+
+    def ensure(self) -> ProjectPaths:
+        """Create all directories in place; returns ``self`` for chaining."""
+        for attr in (
+            "config_dir",
+            "data_dir",
+            "cache_dir",
+            "logs_dir",
+            "prompts_dir",
+            "plugins_dir",
+        ):
+            getattr(self, attr).mkdir(parents=True, exist_ok=True)
+        return self
+
+
+def to_privacy_path(p: Path | str | None) -> str:
+    """Convert an absolute path to a home-relative path with ~ for privacy."""
+    if p is None:
+        return ""
+    try:
+        path_obj = Path(p).resolve()
+        home = Path.home().resolve()
+        if home in path_obj.parents or path_obj == home:
+            return f"~/{path_obj.relative_to(home)}"
+        return str(path_obj)
+    except Exception:
+        return str(p)

forgecli/utils/timing.py

@@ -0,0 +1,25 @@
+"""Simple timing utilities."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+
+@contextmanager
+def Timer(label: str = "elapsed") -> Iterator[dict[str, Any]]:
+    """Context manager that measures wall-clock duration.
+
+    Usage:
+        with Timer() as t:
+            ...
+        print(t["seconds"])
+    """
+    result: dict[str, Any] = {"label": label, "seconds": 0.0}
+    started = time.perf_counter()
+    try:
+        yield result
+    finally:
+        result["seconds"] = time.perf_counter() - started