localcode 0.3.57__tar.gz → 0.3.59__tar.gz

{localcode-0.3.57/src/localcode.egg-info → localcode-0.3.59}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localcode
-Version: 0.3.57
+Version: 0.3.59
 Summary: High-performance AI coding on consumer hardware.
 Author: LocalCode contributors
 License-Expression: Apache-2.0

{localcode-0.3.57 → localcode-0.3.59}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "localcode"
-version = "0.3.57"
+version = "0.3.59"
 description = "High-performance AI coding on consumer hardware."
 readme = "README.md"
 requires-python = ">=3.10"

{localcode-0.3.57 → localcode-0.3.59}/src/localcode/__init__.py

@@ -8,4 +8,4 @@ from importlib.metadata import PackageNotFoundError, version as _pkg_version
 try:
     __version__ = _pkg_version("localcode")
 except PackageNotFoundError:  # not installed (e.g. raw source checkout)
-    __version__ = "0.3.57"
+    __version__ = "0.3.59"

{localcode-0.3.57 → localcode-0.3.59}/src/localcode/agent/prompts.py

@@ -65,7 +65,7 @@ TOOLS & FILES:
 
 DON'T GUESS:
 - Don't invent dependencies: before importing a library, confirm it's in the project's manifest (package.json / requirements.txt / Cargo.toml / go.mod) or a neighboring file. When installing, don't pin a guessed version — let the resolver pick.
-- Never assume a library's API. Verify exports/types/signatures by reading its installed source, checking neighboring usage, or web_fetch'ing its docs. Implementing from a spec or reference? Work from the real source, not memory.
+- Never assume a library's API. Before calling a third-party function/method you're not 100% sure of (argument order, return shape, method names), call `inspect_symbol` (module + symbol) to get its REAL signature from the installed types — don't guess. You can also read its installed source, check neighboring usage, or web_fetch its docs. Implementing from a spec or reference? Work from the real source, not memory.
 - If a setup command fails with "unknown command" / "could not determine executable" / "command not found", it's usually a version mismatch (the "Installed deps" line above shows the major versions) — do that step by hand instead of retrying the same command.
 - If you don't recognize a term, library, or command, say so — search the web before asserting. If results are empty, say that.
 

{localcode-0.3.57 → localcode-0.3.59}/src/localcode/headless_json.py

@@ -198,6 +198,16 @@ def run_headless_json(config, args) -> int:
     _sys.stdout = devnull
 
     try:
+        # Connect user-configured MCP servers (~/.localcode/mcp.json) so headless
+        # `run --json` gets the same MCP tools (incl. LSP) as the TUI. Best-effort:
+        # a server that fails to start must never break the run, and no mcp.json
+        # is a fast no-op. Without this, MCP tools were silently absent in
+        # headless mode (CI, eval, scripting) even when configured.
+        try:
+            from .mcp import connect_all as _mcp_connect_all
+            _mcp_connect_all()
+        except Exception:
+            pass
         result_text = app.ask(args.goal, stream=True)
     except TimeoutError:
         return _emit_result("timeout", 124, f"run exceeded {args.timeout}s")
@@ -206,6 +216,11 @@ def run_headless_json(config, args) -> int:
     except Exception as e:  # noqa: BLE001 — headless: surface any failure as exit 1
         return _emit_result("error", 1, f"{type(e).__name__}: {e}")
     finally:
+        try:
+            from .mcp import shutdown_all as _mcp_shutdown_all
+            _mcp_shutdown_all()
+        except Exception:
+            pass
         if args.timeout and args.timeout > 0:
             import signal
             signal.alarm(0)

{localcode-0.3.57 → localcode-0.3.59}/src/localcode/tools/__init__.py

@@ -32,6 +32,7 @@ from . import (
     edit_file,
     glob_tool,
     grep,
+    inspect_symbol,
     launch_app,
     list_files,
     multi_edit,
@@ -60,6 +61,7 @@ _TOOLS: dict[str, tuple[dict, Callable[[ToolContext, dict], str]]] = {
     "code_navigation": (code_navigation.SCHEMA, code_navigation.execute),
     "launch_app":     (launch_app.SCHEMA,     launch_app.execute),
     "grep":           (grep.SCHEMA,           grep.execute),
+    "inspect_symbol": (inspect_symbol.SCHEMA, inspect_symbol.execute),
     "glob":           (glob_tool.SCHEMA,      glob_tool.execute),
     "list_files":     (list_files.SCHEMA,     list_files.execute),
     "web_search":     (web_search.SCHEMA,     web_search.execute),
@@ -83,6 +85,7 @@ _PUBLIC_TOOL_NAMES = [
     "code_navigation",
     "launch_app",
     "grep",
+    "inspect_symbol",
     "glob",
     "list_files",
     "web_search",
@@ -133,6 +136,9 @@ def schemas_for_goal(
         # Search/discovery — without these the model resorts to bash+grep / curl
         # for everything and the user sees the "google scraped HTML" failure mode.
         "grep", "glob", "web_search", "web_fetch", "skill",
+        # Read a third-party API's REAL signature from installed types instead of
+        # guessing it (the fsrs.repeat()[1] failure class). LSP-hover, on demand.
+        "inspect_symbol",
         # Sub-agent — lets the model spawn focused sub-tasks (explore/plan/verify
         # /general-purpose) so it doesn't burn its own context on long searches.
         "agent",
@@ -162,6 +168,7 @@ _MODULES = {
     "bash": bash,
     "launch_app": launch_app,
     "grep": grep,
+    "inspect_symbol": inspect_symbol,
     "glob": glob_tool,
     "list_files": list_files,
     "web_search": web_search,

localcode-0.3.59/src/localcode/tools/inspect_symbol.py

@@ -0,0 +1,266 @@
+"""inspect_symbol — return an installed library's REAL signature/types.
+
+A weak local model tends to GUESS a third-party API (e.g. call `fsrs.repeat()`
+and index `[1]`, ignoring the rating arg) instead of reading the installed
+package. This tool resolves a package name to its installed type declarations
+(`.d.ts` for JS/TS, `.pyi`/source for Python) and returns the actual signature
+for a symbol — so the model calls the real API, not a hallucinated one.
+
+Filesystem-only by design: no language server, no code execution (safe to run
+unattended, and cheap enough for a 16 GB Mac running a big quantized model).
+This is the "LSP hover, as a tool you call on demand" mechanism.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from .base import ToolContext
+
+SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "inspect_symbol",
+        "description": (
+            "Look up the REAL signature/types of a library symbol from its INSTALLED "
+            "source, so you call the actual API instead of guessing. Give the package "
+            "name and (optionally) the symbol. Returns the declaration from "
+            "node_modules `.d.ts` (JS/TS) or site-packages `.pyi`/source (Python). "
+            "Use it BEFORE calling any third-party API you are not 100% sure of "
+            "(argument order, return shape, method names)."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "module": {
+                    "type": "string",
+                    "description": "Package/module name, e.g. 'fsrs', 'react', 'numpy'.",
+                },
+                "symbol": {
+                    "type": "string",
+                    "description": (
+                        "Optional: the function/class/type/method to look up, e.g. "
+                        "'repeat'. Omit to list the module's exported names."
+                    ),
+                },
+            },
+            "required": ["module"],
+        },
+    },
+}
+
+_MAX_CHARS = 3500
+_DECL_RE_TMPL = (
+    r"\b(?:export\s+)?(?:declare\s+)?(?:default\s+)?"
+    r"(?:async\s+)?(?:function|const|let|var|class|interface|type|enum|namespace|abstract\s+class)\s+{sym}\b"
+)
+
+
+def execute(ctx: ToolContext, args: dict) -> str:
+    module = str(args.get("module") or "").strip()
+    if not module:
+        return "Error: 'module' is required (the package/module name)."
+    symbol = str(args.get("symbol") or "").strip()
+    repo = ctx.repo
+
+    ts = _inspect_ts(repo, module, symbol)
+    if ts:
+        return ts[:_MAX_CHARS]
+    py = _inspect_python(repo, module, symbol)
+    if py:
+        return py[:_MAX_CHARS]
+    return (
+        f"No installed types found for '{module}'. If it's a dependency, make sure it's "
+        f"installed (npm install / pip install) then retry. You can also read its source "
+        f"directly (node_modules/{module}/ for JS/TS, the site-packages dir for Python)."
+    )
+
+
+# ── TypeScript / JavaScript ───────────────────────────────────────────────
+
+def _find_node_modules_pkg(repo: Path, module: str) -> Path | None:
+    """Locate node_modules/<module>, checking the repo root and one level of
+    subdirectories (scaffolds often live in a subfolder)."""
+    candidates = [repo / "node_modules" / module]
+    try:
+        for child in sorted(repo.iterdir()):
+            if child.is_dir() and not child.name.startswith("."):
+                candidates.append(child / "node_modules" / module)
+    except OSError:
+        pass
+    for c in candidates:
+        if c.is_dir():
+            return c
+    return None
+
+
+def _dts_files(pkg_dir: Path, repo: Path, module: str) -> list[Path]:
+    files: list[Path] = []
+    # 1) the package's declared entry types
+    pj = pkg_dir / "package.json"
+    if pj.is_file():
+        try:
+            data = json.loads(pj.read_text(errors="replace"))
+            entry = data.get("types") or data.get("typings")
+            if entry:
+                p = (pkg_dir / str(entry)).resolve()
+                if p.is_file():
+                    files.append(p)
+        except Exception:
+            pass
+    # 2) @types/<module> (DefinitelyTyped)
+    nm = pkg_dir.parent
+    at = nm / f"@types" / module / "index.d.ts"
+    if at.is_file():
+        files.append(at)
+    # 3) fallback: bounded glob of the package's own .d.ts files
+    if not files:
+        try:
+            files.extend(sorted(pkg_dir.rglob("*.d.ts"))[:12])
+        except OSError:
+            pass
+    # de-dup, preserve order
+    seen: set[str] = set()
+    out: list[Path] = []
+    for f in files:
+        k = str(f)
+        if k not in seen:
+            seen.add(k)
+            out.append(f)
+    return out
+
+
+def _inspect_ts(repo: Path, module: str, symbol: str) -> str | None:
+    pkg = _find_node_modules_pkg(repo, module)
+    if not pkg:
+        return None
+    files = _dts_files(pkg, repo, module)
+    if not files:
+        return None
+    if not symbol:
+        # List exported names from the entry declaration file.
+        head = files[0]
+        text = _read(head)
+        exports = sorted(set(re.findall(r"\bexport\s+(?:declare\s+)?(?:default\s+)?(?:async\s+)?(?:function|const|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)", text)))
+        rel = _rel(head, repo)
+        if exports:
+            return f"[{module}] exports (from {rel}):\n" + ", ".join(exports[:60])
+        return f"[{module}] type entry: {rel}\n\n" + text[:_MAX_CHARS]
+    # Extract declaration blocks for the symbol across the type files.
+    blocks = _extract_blocks(files, symbol, repo)
+    if blocks:
+        return f"[{module}.{symbol}] real signature(s) from installed types:\n\n" + blocks
+    return None
+
+
+# ── Python ────────────────────────────────────────────────────────────────
+
+def _find_python_pkg(repo: Path, module: str) -> list[Path]:
+    """Find installed <module> source/stub files under the project's venv or a
+    site-packages dir. Best-effort, bounded."""
+    hits: list[Path] = []
+    top = module.split(".")[0]
+    roots: list[Path] = []
+    try:
+        for sp in list(repo.rglob("site-packages"))[:4]:
+            roots.append(sp)
+    except OSError:
+        pass
+    for sp in roots:
+        for name in (f"{top}.pyi", f"{top}.py", f"{top}/__init__.pyi", f"{top}/__init__.py"):
+            p = sp / name
+            if p.is_file():
+                hits.append(p)
+    return hits[:4]
+
+
+def _inspect_python(repo: Path, module: str, symbol: str) -> str | None:
+    files = _find_python_pkg(repo, module)
+    if not files:
+        return None
+    if not symbol:
+        text = _read(files[0])
+        names = sorted(set(re.findall(r"^(?:def|class)\s+([A-Za-z_]\w*)", text, re.M)))
+        if names:
+            return f"[{module}] top-level defs (from {_rel(files[0], repo)}):\n" + ", ".join(names[:60])
+        return f"[{module}] {_rel(files[0], repo)}\n\n" + text[:_MAX_CHARS]
+    blocks = _extract_py_blocks(files, symbol, repo)
+    if blocks:
+        return f"[{module}.{symbol}] real signature(s) from installed source:\n\n" + blocks
+    return None
+
+
+# ── shared extraction ─────────────────────────────────────────────────────
+
+def _extract_blocks(files: list[Path], symbol: str, repo: Path) -> str:
+    """Return declaration windows for `symbol` from TS declaration files."""
+    decl_re = re.compile(_DECL_RE_TMPL.format(sym=re.escape(symbol)))
+    # also catch a class METHOD or property signature: `symbol(...)` / `symbol:`
+    method_re = re.compile(rf"^\s*(?:readonly\s+|public\s+|static\s+|abstract\s+)*{re.escape(symbol)}\s*[<(:]")
+    out: list[str] = []
+    count = 0
+    for f in files:
+        lines = _read(f).splitlines()
+        for i, line in enumerate(lines):
+            if decl_re.search(line) or method_re.search(line):
+                window = _window(lines, i)
+                out.append(f"// {_rel(f, repo)}:{i + 1}\n" + window)
+                count += 1
+                if count >= 6:
+                    return "\n\n".join(out)
+    return "\n\n".join(out)
+
+
+def _extract_py_blocks(files: list[Path], symbol: str, repo: Path) -> str:
+    decl_re = re.compile(rf"^\s*(?:async\s+)?(?:def|class)\s+{re.escape(symbol)}\b")
+    out: list[str] = []
+    count = 0
+    for f in files:
+        lines = _read(f).splitlines()
+        for i, line in enumerate(lines):
+            if decl_re.search(line):
+                window = _window(lines, i, stop_on_dedent=True)
+                out.append(f"# {_rel(f, repo)}:{i + 1}\n" + window)
+                count += 1
+                if count >= 6:
+                    return "\n\n".join(out)
+    return "\n\n".join(out)
+
+
+def _window(lines: list[str], start: int, stop_on_dedent: bool = False, max_lines: int = 14) -> str:
+    """Capture a declaration block from `start`: until a blank line / a line that
+    closes the statement (`;`, `}`) / a dedent to the declaration's indent."""
+    out = [lines[start]]
+    base_indent = len(lines[start]) - len(lines[start].lstrip())
+    depth = lines[start].count("{") - lines[start].count("}")
+    for j in range(start + 1, min(len(lines), start + max_lines)):
+        ln = lines[j]
+        if stop_on_dedent:
+            if ln.strip() and (len(ln) - len(ln.lstrip())) <= base_indent:
+                break
+            out.append(ln)
+            continue
+        out.append(ln)
+        depth += ln.count("{") - ln.count("}")
+        if depth <= 0 and (ln.rstrip().endswith(";") or ln.rstrip().endswith("}") or not ln.strip()):
+            break
+    return "\n".join(out).rstrip()
+
+
+def _read(p: Path) -> str:
+    try:
+        return p.read_text(errors="replace")
+    except OSError:
+        return ""
+
+
+def _rel(p: Path, repo: Path) -> str:
+    try:
+        return str(p.relative_to(repo))
+    except ValueError:
+        return str(p)
+
+
+def is_concurrency_safe(args: dict) -> bool:
+    return True

{localcode-0.3.57 → localcode-0.3.59/src/localcode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localcode
-Version: 0.3.57
+Version: 0.3.59
 Summary: High-performance AI coding on consumer hardware.
 Author: LocalCode contributors
 License-Expression: Apache-2.0

{localcode-0.3.57 → localcode-0.3.59}/src/localcode.egg-info/SOURCES.txt

@@ -893,6 +893,7 @@ src/localcode/tools/edit_file.py
 src/localcode/tools/facts.py
 src/localcode/tools/glob_tool.py
 src/localcode/tools/grep.py
+src/localcode/tools/inspect_symbol.py
 src/localcode/tools/launch_app.py
 src/localcode/tools/list_files.py
 src/localcode/tools/multi_edit.py
@@ -965,6 +966,7 @@ tests/test_evidence_and_lifecycle_hooks.py
 tests/test_execution_policies.py
 tests/test_fresh_install.py
 tests/test_home_build_anchor.py
+tests/test_inspect_symbol.py
 tests/test_kv_cap.py
 tests/test_loop_recovery_ladder.py
 tests/test_model_config.py

localcode-0.3.59/tests/test_inspect_symbol.py

@@ -0,0 +1,76 @@
+"""inspect_symbol: return a library's REAL signature from installed types, so a
+weak model calls the actual API instead of guessing it (the fsrs.repeat()[1]
+failure class)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+from localcode.tools import AVAILABLE_NAMES, dispatch
+from localcode.tools import inspect_symbol
+
+
+def _ctx(repo: Path) -> SimpleNamespace:
+    return SimpleNamespace(repo=repo, app=SimpleNamespace(repo_root=repo))
+
+
+def _npm_pkg(repo: Path, name: str, dts: str, types_entry: str = "index.d.ts") -> None:
+    pkg = repo / "node_modules" / name
+    pkg.mkdir(parents=True)
+    (pkg / "package.json").write_text(json.dumps({"name": name, "types": types_entry}))
+    (pkg / types_entry).write_text(dts)
+
+
+def test_registered():
+    assert "inspect_symbol" in AVAILABLE_NAMES
+
+
+def test_returns_real_ts_signature(tmp_path: Path):
+    _npm_pkg(tmp_path, "fsrs", (
+        "export declare enum Rating { Again = 1, Hard = 2, Good = 3, Easy = 4 }\n"
+        "export declare class FSRS {\n"
+        "  repeat(card: Card, now: Date): Record<Rating, RecordLogItem>;\n"
+        "  next(card: Card, now: Date, grade: Rating): RecordLogItem;\n"
+        "}\n"
+    ))
+    out = dispatch("inspect_symbol", _ctx(tmp_path), {"module": "fsrs", "symbol": "repeat"})
+    # the model must SEE that repeat returns a record keyed by Rating (index by
+    # the rating), not a positional array — the whole point of the tool.
+    assert "repeat(card: Card, now: Date): Record<Rating, RecordLogItem>" in out
+    assert "guess" not in out.lower() or "installed types" in out.lower()
+
+
+def test_lists_exports_without_symbol(tmp_path: Path):
+    _npm_pkg(tmp_path, "fsrs",
+             "export declare class FSRS {}\nexport declare enum Rating {}\n")
+    out = dispatch("inspect_symbol", _ctx(tmp_path), {"module": "fsrs"})
+    assert "FSRS" in out and "Rating" in out
+
+
+def test_finds_pkg_in_subdirectory(tmp_path: Path):
+    # scaffolds live in a subfolder; the tool must find node_modules there.
+    (tmp_path / "app").mkdir()
+    _npm_pkg(tmp_path / "app", "dexie",
+             "export declare class Dexie {\n  version(n: number): Version;\n}\n")
+    out = dispatch("inspect_symbol", _ctx(tmp_path), {"module": "dexie", "symbol": "version"})
+    assert "version(n: number)" in out
+
+
+def test_not_installed_is_actionable(tmp_path: Path):
+    out = dispatch("inspect_symbol", _ctx(tmp_path), {"module": "nope", "symbol": "x"})
+    assert "No installed types" in out or "npm install" in out
+
+
+def test_missing_module_arg_is_rejected(tmp_path: Path):
+    # dispatch enforces the schema's required fields.
+    out = dispatch("inspect_symbol", _ctx(tmp_path), {})
+    assert "module" in out.lower()
+
+
+def test_python_signature(tmp_path: Path):
+    sp = tmp_path / ".venv" / "lib" / "python3.12" / "site-packages"
+    sp.mkdir(parents=True)
+    (sp / "widget.py").write_text("def render(node, depth: int = 0) -> str:\n    return ''\n")
+    out = dispatch("inspect_symbol", _ctx(tmp_path), {"module": "widget", "symbol": "render"})
+    assert "def render(node, depth: int = 0) -> str" in out