luckyd-code 1.2.2__py3-none-any.whl

luckyd_code/tools/project_gen.py

@@ -0,0 +1,187 @@
+"""Project scaffold generator tool.
+
+Generates complete, ready-to-run project scaffolds from a plain-English
+description using the DeepSeek model. Writes every file directly to disk.
+
+Any project type is supported — web app, CLI tool, REST API, Discord bot,
+data pipeline, etc. Just describe what you want.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from pathlib import Path
+
+from .registry import Tool
+
+# ---------------------------------------------------------------------------
+# Prompt for the scaffold generator
+# ---------------------------------------------------------------------------
+
+_SYSTEM_PROMPT = """\
+You are an expert software architect and developer.
+
+Your job is to generate a COMPLETE project scaffold from a plain-English
+description. The scaffold must be immediately usable: clone, install deps, run.
+
+OUTPUT FORMAT — respond with a single JSON object and nothing else:
+{
+  "project_name": "<slug, lowercase, hyphens only>",
+  "description":  "<one sentence>",
+  "stack":        "<comma-separated key tech>",
+  "files": [
+    { "path": "relative/path/to/file.ext", "content": "<full file content>" },
+    ...
+  ],
+  "install":  "<shell command to install dependencies>",
+  "run":      "<shell command to start the project>",
+  "notes":    "<optional short notes for the developer>"
+}
+
+RULES:
+1. Output ONLY the JSON — no markdown fences, no prose before or after.
+2. Every file must have COMPLETE content — no placeholders, no TODOs.
+3. Always include: README.md, .gitignore, a dependency manifest
+   (requirements.txt, package.json, pyproject.toml, go.mod, etc.).
+4. Include at least one working entry-point file and one basic test file.
+5. Keep the scaffold focused and minimal — just enough to be genuinely useful.
+6. Use modern, idiomatic conventions for the chosen language/framework.
+7. All secrets/API keys must use environment variables loaded from a .env file;
+   include a .env.example but never a real .env.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Tool
+# ---------------------------------------------------------------------------
+
+class ProjectGenTool(Tool):
+    """Generate a complete project scaffold from a plain-English description.
+
+    Use this tool when the user asks to:
+      - Start a new project ("create a FastAPI CRUD app")
+      - Generate boilerplate for any language or framework
+      - Scaffold a CLI tool, web API, Discord bot, data pipeline, etc.
+    """
+
+    name = "ProjectGen"
+    description = (
+        "Generate a complete, ready-to-run project scaffold from a plain-English "
+        "description. Writes all files to disk. Any project type is supported — "
+        "web app, CLI tool, REST API, Discord bot, data pipeline, browser extension, etc."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "description": {
+                "type": "string",
+                "description": (
+                    "Plain-English description of the project to generate. "
+                    "Include the language/framework if you have a preference. "
+                    "Examples: 'a FastAPI CRUD API with SQLite', "
+                    "'a React todo app with Tailwind', "
+                    "'a Python CLI that converts Markdown to PDF'."
+                ),
+            },
+            "output_dir": {
+                "type": "string",
+                "description": (
+                    "Parent directory to create the project folder inside. "
+                    "Defaults to the current working directory."
+                ),
+                "default": ".",
+            },
+        },
+        "required": ["description"],
+    }
+    permission_risk = "medium"
+
+    def _call_model(self, description: str) -> dict[str, Any]:
+        """Ask the model to generate the scaffold JSON."""
+        raw = self._call_model_direct(description)
+        raw = raw.strip()
+        if raw.startswith("```"):
+            raw = "\n".join(
+                ln for ln in raw.splitlines() if not ln.startswith("```")
+            ).strip()
+
+        return json.loads(raw)
+
+    def _call_model_direct(self, description: str) -> str:
+        from ..config import get_api_key, get_base_url  # noqa: PLC0415
+        payload = {
+            "model": "deepseek-chat",
+            "max_tokens": 8192,
+            "temperature": 0.2,
+            "messages": [
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "user", "content": f"Project description: {description}"},
+            ],
+        }
+        req = urllib.request.Request(
+            f"{get_base_url()}/chat/completions",
+            data=json.dumps(payload).encode(),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {get_api_key()}",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            data = json.loads(resp.read())
+        return data["choices"][0]["message"]["content"]
+
+    def run(self, description: str, output_dir: str = ".") -> str:  # type: ignore[override]
+        parent = Path(output_dir).expanduser().resolve()
+        try:
+            parent.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            return f"Error: cannot create output directory: {e}"
+
+        try:
+            scaffold = self._call_model(description)
+        except json.JSONDecodeError as e:
+            return f"Error: model returned invalid JSON — {e}"
+        except Exception as e:
+            return f"Error: model call failed — {e}"
+
+        project_name = scaffold.get("project_name", "generated-project")
+        files: list[dict] = scaffold.get("files", [])
+        if not files:
+            return "Error: model returned no files."
+
+        project_dir = parent / project_name
+        written: list[str] = []
+        errors: list[str] = []
+
+        for f in files:
+            rel = f.get("path", "").lstrip("/")
+            content = f.get("content", "")
+            if not rel:
+                continue
+            target = project_dir / rel
+            try:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(content, encoding="utf-8")
+                written.append(rel)
+            except OSError as e:
+                errors.append(f"{rel}: {e}")
+
+        lines = [
+            f"Project '{project_name}' created at {project_dir}",
+            f"Stack   : {scaffold.get('stack', 'n/a')}",
+            f"Files   : {len(written)} written",
+        ]
+        if errors:
+            lines.append(f"Errors  : {len(errors)}")
+            lines.extend(f"  {e}" for e in errors)
+        lines += [
+            "",
+            f"Install : {scaffold.get('install', 'n/a')}",
+            f"Run     : {scaffold.get('run', 'n/a')}",
+        ]
+        if scaffold.get("notes"):
+            lines += ["", f"Notes   : {scaffold['notes']}"]
+
+        return "\n".join(lines)

luckyd_code/tools/readme_gen.py

@@ -0,0 +1,227 @@
+"""README generator tool.
+
+Scans the current project directory and generates a polished, professional
+README.md using the DeepSeek model. Understands any language or framework.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from pathlib import Path
+
+from .registry import Tool
+
+# ---------------------------------------------------------------------------
+# Prompt
+# ---------------------------------------------------------------------------
+
+_SYSTEM_PROMPT = """\
+You are a senior technical writer. Your job is to write a polished, professional
+README.md for a software project based on the source files you are given.
+
+RULES:
+1. Output ONLY valid Markdown — no preamble, no code fences around the whole output.
+2. Structure: title, one-line description, badges (if applicable), Features,
+   Prerequisites, Installation, Usage, Configuration (.env vars if any),
+   Contributing, License.
+3. Be concise but complete. Real examples over generic placeholders.
+4. Infer the tech stack, purpose, and usage from the files provided.
+5. Use proper Markdown code blocks with language tags for all code/commands.
+6. If a LICENSE file is present, reference the licence type in the badge/section.
+"""
+
+_MAX_FILE_CHARS = 3000
+_MAX_FILES      = 20
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_SKIP_DIRS = {
+    ".git", ".venv", "venv", "env", "__pycache__", "node_modules",
+    ".mypy_cache", ".pytest_cache", "dist", "build", ".claude", ".deepseek-code",
+}
+
+_SKIP_EXTS = {
+    ".pyc", ".pyo", ".pyd", ".so", ".dll", ".exe", ".egg",
+    ".png", ".jpg", ".jpeg", ".gif", ".ico", ".svg",
+    ".lock", ".min.js", ".min.css",
+}
+
+_PRIORITY_FILES = {
+    "main.py", "app.py", "cli.py", "server.py", "index.js", "index.ts",
+    "main.go", "main.rs", "Cargo.toml", "go.mod", "pyproject.toml",
+    "package.json", "requirements.txt", "setup.py", "Makefile",
+    "Dockerfile", ".env.example", "LICENSE",
+}
+
+
+def _collect_files(root: Path) -> list[tuple[str, str]]:
+    """Return list of (relative_path, content_snippet) for key project files."""
+    collected: list[tuple[str, str]] = []
+    seen_names: set[str] = set()
+
+    def _walk(path: Path, depth: int = 0):
+        if depth > 5 or len(collected) >= _MAX_FILES:
+            return
+        try:
+            entries = sorted(path.iterdir(), key=lambda p: (p.is_dir(), p.name))
+        except PermissionError:
+            return
+        for entry in entries:
+            if entry.name.startswith(".") and entry.name not in {".env.example"}:
+                continue
+            if entry.name in _SKIP_DIRS:
+                continue
+            if entry.is_dir():
+                _walk(entry, depth + 1)
+            elif entry.is_file() and entry.suffix not in _SKIP_EXTS:
+                rel = str(entry.relative_to(root))
+                if rel in seen_names or len(collected) >= _MAX_FILES:
+                    continue
+                seen_names.add(rel)
+                try:
+                    text = entry.read_text(encoding="utf-8", errors="replace")
+                    snippet = text[:_MAX_FILE_CHARS]
+                    if len(text) > _MAX_FILE_CHARS:
+                        snippet += f"\n... ({len(text) - _MAX_FILE_CHARS} chars truncated)"
+                    collected.append((rel, snippet))
+                except Exception:
+                    pass
+
+    for name in _PRIORITY_FILES:
+        candidate = root / name
+        if candidate.exists() and candidate.is_file():
+            try:
+                text = candidate.read_text(encoding="utf-8", errors="replace")
+                snippet = text[:_MAX_FILE_CHARS]
+                collected.append((str(candidate.relative_to(root)), snippet))
+                seen_names.add(str(candidate.relative_to(root)))
+            except Exception:
+                pass
+
+    _walk(root)
+    return collected
+
+
+def _format_context(files: list[tuple[str, str]]) -> str:
+    parts = []
+    for rel, content in files:
+        parts.append(f"=== {rel} ===\n{content}")
+    return "\n\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Tool
+# ---------------------------------------------------------------------------
+
+class ReadmeGenTool(Tool):
+    """Generate a polished README.md by scanning the current project.
+
+    Use this tool when the user asks to:
+      - Write or improve the README for their project
+      - Auto-generate documentation from source files
+      - Create a professional project description
+    """
+
+    name = "ReadmeGen"
+    description = (
+        "Scan the current project directory and generate a professional README.md. "
+        "Works with any language or framework. Infers stack, features, and usage "
+        "automatically from source files."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "project_dir": {
+                "type": "string",
+                "description": "Root directory of the project to document. Defaults to cwd.",
+                "default": ".",
+            },
+            "output_path": {
+                "type": "string",
+                "description": "Where to write the README. Defaults to <project_dir>/README.md.",
+                "default": "",
+            },
+            "overwrite": {
+                "type": "boolean",
+                "description": "Overwrite an existing README.md. Defaults to false.",
+                "default": False,
+            },
+        },
+        "required": [],
+    }
+    permission_risk = "medium"
+
+    def _call_model(self, context: str) -> str:
+        return self._call_model_direct(context)
+
+    def _call_model_direct(self, context: str) -> str:
+        from ..config import get_api_key, get_base_url  # noqa: PLC0415
+        payload = {
+            "model": "deepseek-chat",
+            "max_tokens": 4096,
+            "temperature": 0.2,
+            "messages": [
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "user", "content": f"Project files:\n\n{context}\n\nGenerate the README.md."},
+            ],
+        }
+        req = urllib.request.Request(
+            f"{get_base_url()}/chat/completions",
+            data=json.dumps(payload).encode(),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {get_api_key()}",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=90) as resp:
+            data = json.loads(resp.read())
+        return data["choices"][0]["message"]["content"]
+
+    def run(
+        self,
+        project_dir: str = ".",
+        output_path: str = "",
+        overwrite: bool = False,
+    ) -> str:  # type: ignore[override]
+        root = Path(project_dir).expanduser().resolve()
+        if not root.is_dir():
+            return f"Error: '{root}' is not a directory."
+
+        out = Path(output_path).expanduser().resolve() if output_path else root / "README.md"
+
+        if out.exists() and not overwrite:
+            return (
+                f"README already exists at {out}. "
+                "Pass overwrite=true to replace it."
+            )
+
+        files = _collect_files(root)
+        if not files:
+            return "Error: no readable source files found."
+
+        context = _format_context(files)
+
+        try:
+            readme = self._call_model(context)
+        except Exception as e:
+            return f"Error: model call failed — {e}"
+
+        readme = readme.strip()
+        if readme.startswith("```markdown"):
+            readme = readme[len("```markdown"):].lstrip("\n")
+        if readme.endswith("```"):
+            readme = readme[:-3].rstrip("\n")
+
+        try:
+            out.write_text(readme, encoding="utf-8")
+        except OSError as e:
+            return f"Error: could not write file — {e}"
+
+        return (
+            f"README.md generated from {len(files)} file(s).\n"
+            f"Written to: {out}"
+        )

luckyd_code/tools/registry.py

@@ -0,0 +1,157 @@
+import time
+from typing import Any, Dict, Optional
+
+# Tools in this set are read-only and safe to cache.
+# Write/Bash/Git tools are explicitly excluded — their results must never be stale.
+_CACHEABLE_TOOLS: frozenset[str] = frozenset({
+    "Read", "Glob", "Grep", "WebFetch", "WebSearch", "DateTime",
+    "YouTubePlaylist",  # pure URL construction — no I/O, deterministic output
+})
+
+# Default TTL for cached tool results (seconds).
+_DEFAULT_CACHE_TTL: float = 300.0  # 5 minutes
+
+
+class _CacheEntry:
+    __slots__ = ("value", "expires_at")
+
+    def __init__(self, value: str, ttl: float) -> None:
+        self.value = value
+        self.expires_at = time.monotonic() + ttl
+
+
+class Tool:
+    """Base class for all tools."""
+
+    name: str = ""
+    description: str = ""
+    parameters: Dict[str, Any] = {}
+    permission_risk: str = "safe"  # safe | medium | high
+
+    def run(self, **kwargs) -> str:
+        raise NotImplementedError
+
+    def to_openai_tool(self) -> Dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+class ToolRegistry:
+    """Registry of all available tools with optional result caching.
+
+    Caching is applied only to read-only tools (``_CACHEABLE_TOOLS``).
+    Cache keys are derived from the tool name and its sorted arguments, so
+    calling ``Read`` on the same file twice within the TTL window costs only
+    one real I/O operation.
+
+    Set ``cache_ttl=0`` to disable caching entirely.
+    """
+
+    def __init__(self, cache_ttl: float = _DEFAULT_CACHE_TTL):
+        self._tools: Dict[str, Tool] = {}
+        self._cache: Dict[str, _CacheEntry] = {}
+        self._cache_ttl = cache_ttl
+
+    def register(self, tool: Tool) -> None:
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Optional[Tool]:
+        return self._tools.get(name)
+
+    def list_tools(self) -> list[Dict[str, Any]]:
+        return [t.to_openai_tool() for t in self._tools.values()]
+
+    # ------------------------------------------------------------------ #
+    #  Cache helpers
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _cache_key(name: str, arguments: Dict[str, Any]) -> str:
+        """Stable cache key: tool name + sorted argument pairs."""
+        arg_repr = ",".join(f"{k}={v!r}" for k, v in sorted(arguments.items()))
+        return f"{name}|{arg_repr}"
+
+    def _get_cached(self, key: str) -> Optional[str]:
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+        if time.monotonic() > entry.expires_at:
+            del self._cache[key]
+            return None
+        return entry.value
+
+    def _set_cached(self, key: str, value: str) -> None:
+        if self._cache_ttl <= 0:
+            return
+        # Evict expired entries when the cache grows large, OR unconditionally
+        # every 60 seconds so short-lived sessions don't accumulate stale
+        # entries indefinitely.
+        now = time.monotonic()
+        should_evict = (
+            len(self._cache) % 100 == 0          # every 100th insert (large cache)
+            or getattr(self, "_last_evict", 0) + 60 < now  # time-based fallback
+        )
+        if should_evict:
+            expired = [k for k, e in self._cache.items() if now > e.expires_at]
+            for k in expired:
+                del self._cache[k]
+            self._last_evict = now
+        self._cache[key] = _CacheEntry(value, self._cache_ttl)
+
+    def invalidate(self, tool_name: Optional[str] = None) -> int:
+        """Invalidate cache entries.
+
+        Args:
+            tool_name: If given, only entries for this tool are removed.
+                       If None, the entire cache is cleared.
+
+        Returns:
+            Number of entries removed.
+        """
+        if tool_name is None:
+            count = len(self._cache)
+            self._cache.clear()
+            return count
+        prefix = f"{tool_name}|"
+        keys = [k for k in self._cache if k.startswith(prefix)]
+        for k in keys:
+            del self._cache[k]
+        return len(keys)
+
+    # ------------------------------------------------------------------ #
+    #  Execution
+    # ------------------------------------------------------------------ #
+
+    def execute(self, name: str, arguments: Dict[str, Any], check_perm=None) -> str:
+        tool = self.get(name)
+        if not tool:
+            return f"Error: unknown tool '{name}'"
+
+        if check_perm:
+            allowed = check_perm(name)
+            if not allowed:
+                return f"Permission denied for tool '{name}'"
+
+        # Check cache for eligible read-only tools
+        use_cache = name in _CACHEABLE_TOOLS and self._cache_ttl > 0
+        if use_cache:
+            key = self._cache_key(name, arguments)
+            cached = self._get_cached(key)
+            if cached is not None:
+                return cached
+
+        try:
+            result = tool.run(**arguments)
+        except Exception as e:
+            return f"Error executing {name}: {e}"
+
+        if use_cache:
+            self._set_cached(key, result)
+
+        return result

luckyd_code/tools/shell_detect.py

@@ -0,0 +1,109 @@
+"""Shell auto-detection for Windows — finds Git Bash, WSL, or falls back to cmd.exe."""
+
+import os
+import shutil
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ShellInfo:
+    name: str          # "git_bash", "wsl", "cmd", "powershell"
+    path: str          # executable path
+    args: list[str]    # extra args (e.g. ["--login"] for bash)
+    unix_like: bool    # True if ls/grep/find/curl etc. are available
+    description: str   # Human-readable name
+
+
+def detect_shell() -> ShellInfo:
+    """Probe for the best available shell on Windows.
+
+    Detection order:
+      1. Git Bash (most common for developers on Windows)
+      2. WSL (Windows Subsystem for Linux)
+      3. cmd.exe (stock Windows — always available)
+
+    Returns the first match found.
+    """
+    git_bash = _find_git_bash()
+    if git_bash:
+        return ShellInfo(
+            name="git_bash",
+            path=git_bash,
+            args=["--norc", "--noprofile"],
+            unix_like=True,
+            description="Git Bash",
+        )
+
+    wsl = _find_wsl()
+    if wsl:
+        return ShellInfo(
+            name="wsl",
+            path=wsl,
+            args=["--", "bash"],
+            unix_like=True,
+            description="WSL (Ubuntu)",
+        )
+
+    return ShellInfo(
+        name="cmd",
+        path=os.environ.get("COMSPEC", "cmd.exe"),
+        args=[],
+        unix_like=False,
+        description="cmd.exe",
+    )
+
+
+def _find_git_bash() -> Optional[str]:
+    """Locate Git Bash — use PATH lookup first, then common install paths."""
+    bash_in_path = shutil.which("bash")
+    if bash_in_path:
+        return bash_in_path
+    candidates = [
+        r"C:\Program Files\Git\bin\bash.exe",
+        r"C:\Program Files (x86)\Git\bin\bash.exe",
+        os.path.expanduser(r"~\AppData\Local\Programs\Git\bin\bash.exe"),
+    ]
+    for path in candidates:
+        if os.path.isfile(path):
+            return path
+    return None
+
+
+def _find_wsl() -> Optional[str]:
+    """Check if WSL is available."""
+    wsl_path = shutil.which("wsl.exe") or shutil.which("wsl")
+    if wsl_path:
+        return wsl_path
+    return None
+
+
+def resolve_shell(shell_setting: str = "auto") -> ShellInfo:
+    """Resolve the shell to use based on a user setting.
+
+    Args:
+        shell_setting: One of "auto", "git_bash", "wsl", "cmd".
+
+    Returns:
+        The resolved ShellInfo.
+    """
+    mapping = {
+        "git_bash": lambda: _find_git_bash(),
+        "wsl": lambda: _find_wsl(),
+        "cmd": lambda: os.environ.get("COMSPEC", "cmd.exe"),
+    }
+
+    if shell_setting != "auto":
+        finder = mapping.get(shell_setting)
+        if finder:
+            path = finder()
+            if path:
+                if shell_setting == "git_bash":
+                    return ShellInfo("git_bash", path, ["--norc", "--noprofile"], True, "Git Bash")
+                elif shell_setting == "wsl":
+                    return ShellInfo("wsl", path, ["--", "bash"], True, "WSL (Ubuntu)")
+                else:
+                    return ShellInfo("cmd", path, [], False, "cmd.exe")
+        # Fall through to auto if the override shell wasn't found
+
+    return detect_shell()