squackit 0.8.2__tar.gz → 0.8.3__tar.gz

{squackit-0.8.2 → squackit-0.8.3}/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 0.8.3
+
+Three fixes with one theme: a failure must not be representable as an ordinary
+result. Nothing here changes what a working call returns.
+
+### Fixed — `investigate` reported failed lookups as confirmed absences (#14)
+
+Every exception from the definition query was caught and rendered with the
+sentence used for a genuine miss:
+
+    No definition found for 'X'. Try a broader pattern or check spelling.
+
+So a permission error, a binder error and "that symbol isn't here" were
+indistinguishable, and the advice actively misdirected — the pattern was never
+the problem. This is how the 0.8.1 sandbox bug presented: every symbol in a
+healthy project reported missing, for hours, while the server called all its
+tools healthy.
+
+A failed lookup now says so, names the underlying error, and reports the
+pattern it searched. The friendly wording is kept for the genuine empty case,
+where it is good advice.
+
+### Fixed — a raising pluckin lost its tools silently (#14)
+
+`collect_pluckin_tools` swallowed per-pluckin exceptions with a bare `pass`,
+under a comment claiming the error would be "surfaced contextually". Nothing
+surfaced it. The guard is right — one broken pluckin must not take down the
+registry — but it now logs a warning naming the pluckin and the error.
+
+Not reachable today (no shipped pluckin defines `squackit_tools`), fixed as
+latent. The symptom it would produce — a silently shorter tool surface — was
+independently hit through another mechanism and cost a four-combination version
+bisection, because a shorter tool list doesn't read as a failure. It reads as a
+different, reasonable version of the product.
+
+### Fixed — `ast_replace` / `ast_patch` read as mutating and are not (#16)
+
+Connection macros are published with a description generated from the
+signature, so these carried no semantics at all:
+
+    Query: ast_replace(source, selector, new_text, language)
+
+These are sitting_duck SQL macros. A SQL macro cannot write files — it computes
+the patched source and returns it, which is coherent, and sitting_duck is not
+misbehaving. But over MCP the caller reads a verb. One did: it called
+`ast_replace` to repair a bug, got a successful-looking table back, and changed
+nothing on disk.
+
+Generated descriptions for macros whose *name* implies an effect now state that
+they return the patched result and modify nothing. Read-only macros are
+unchanged — a disclaimer on all ninety is context every agent pays for.
+
+For an actually-mutating primitive, see #17.
+
+### Fixed — `__version__` was four releases stale (#15, #2)
+
+`squackit.__version__` was a hand-written `"0.4.1"` against a distribution
+version of `0.8.2`, and survived `--force-reinstall` because it derived from
+nothing. It is now read from `importlib.metadata`, and the smoke test asserts
+that correspondence rather than a literal — which is what let both drift in
+agreement with each other and with nothing else.
+
 ## 0.8.2
 
 ### Fixed — AST tools could not read a source outside the working directory

{squackit-0.8.2 → squackit-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: squackit
-Version: 0.8.2
+Version: 0.8.3
 Summary: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents.
 Project-URL: Homepage, https://github.com/teaguesterling/squackit
 Project-URL: Documentation, https://squackit.readthedocs.io

{squackit-0.8.2 → squackit-0.8.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "squackit"
-version = "0.8.2"
+version = "0.8.3"
 description = "Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."
 readme = "README.md"
 license = "Apache-2.0"

squackit-0.8.3/squackit/__init__.py

@@ -0,0 +1,17 @@
+"""squackit: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."""
+
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+
+# Derived, never written by hand. The literal that used to live here read
+# "0.4.1" while the installed distribution was 0.8.2 — four releases stale, and
+# immune to --force-reinstall because it was not derived from anything. Someone
+# debugging an unrelated problem read it, concluded they had a mixed install,
+# and went looking for a packaging fault that did not exist. A version string
+# that lies makes a healthy install look broken, which is the most expensive
+# direction to send a reader.
+try:
+    __version__ = _dist_version("squackit")
+except PackageNotFoundError:  # running from a source tree with no install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

{squackit-0.8.2 → squackit-0.8.3}/squackit/tool_config.py

@@ -37,6 +37,21 @@ _FALLBACK_NUMERIC = {
 }
 
 
+#: Name tokens that read as an effect. A macro whose name contains one of these
+#: gets an explicit "does not modify any file" note in its generated
+#: description. Missing a verb costs nothing beyond the status quo; a false
+#: positive adds a sentence that is true of every SQL macro anyway.
+_MUTATION_VERBS = frozenset({
+    "replace", "patch", "apply", "write", "insert", "update", "delete",
+    "remove", "rename", "edit", "set", "modify", "save", "commit",
+})
+
+
+def _name_implies_mutation(name: str) -> bool:
+    """True when a tool's NAME reads as an effect it does not perform."""
+    return any(token in _MUTATION_VERBS for token in name.split("_"))
+
+
 @dataclass
 class ToolPresentation:
     """Wraps fledgling ToolInfo with squackit's presentation/UX config."""
@@ -100,7 +115,23 @@ class ToolPresentation:
     def description(self) -> str:
         if self.description_override is not None:
             return self.description_override
-        return self.info.description or f"Query: {self.name}({', '.join(self.params)})"
+        if self.info.description:
+            return self.info.description
+        signature = f"{self.name}({', '.join(self.params)})"
+        if _name_implies_mutation(self.name):
+            # SQL macros cannot write files — they compute and return a result
+            # set. But a caller reads a verb: `ast_replace` was called to repair
+            # a bug, returned a successful-looking table, and changed nothing on
+            # disk. The bare signature said nothing either way, and the only
+            # hint was the "Query:" prefix — a category label competing against
+            # an imperative. Spell it out for the names where it misleads, and
+            # only those: a disclaimer on all ~90 macros is context every agent
+            # pays for on every call.
+            return (
+                f"Query: {signature} — computes and RETURNS the patched result "
+                f"as text. Does not modify any file."
+            )
+        return f"Query: {signature}"
 
     @property
     def parameters_schema(self) -> dict | None:

{squackit-0.8.2 → squackit-0.8.3}/squackit/tools.py

@@ -9,6 +9,7 @@ fledgling macro tools. They take priority over fledgling equivalents
 from __future__ import annotations
 
 import hashlib
+import logging
 import os
 import re
 import tempfile
@@ -16,6 +17,8 @@ import tempfile
 from fledgling.tools import ToolInfo
 from squackit.tool_config import ToolPresentation
 
+log = logging.getLogger(__name__)
+
 
 #: How much source text ``read_ast`` puts in the ``peek`` column when squackit
 #: materializes its own table. ``'smart'`` matches what pluckit's cache uses by
@@ -305,10 +308,20 @@ def collect_pluckin_tools(plucker) -> list:
         if callable(fn):
             try:
                 tools.extend(fn())
-            except Exception:
-                # A broken pluckin shouldn't break the whole registry.
-                # Squackit's server/CLI will surface the error contextually.
-                pass
+            except Exception as exc:
+                # Keep the guard — one broken pluckin must not take down the
+                # whole registry — but SAY SO. Dropping its tools silently
+                # yields a shorter tool surface, and a shorter tool list does
+                # not read as a failure: it reads as a different, reasonable
+                # version of the product, so callers reason forward from it
+                # instead of doubting it. (An earlier comment here claimed the
+                # server/CLI would "surface the error contextually". Nothing
+                # did.)
+                log.warning(
+                    "pluckin %s failed to contribute squackit tools (%s); its "
+                    "tools are missing from this session's registry",
+                    type(pluckin).__name__, exc, exc_info=True,
+                )
     return tools
 
 

{squackit-0.8.2 → squackit-0.8.3}/squackit/workflows.py

@@ -160,13 +160,22 @@ def investigate(con, defaults, name, file_pattern=None, path=None):
     #    the whole briefing describe the wrong symbol. Fall back to the full
     #    substring set only when nothing matches exactly, preserving the
     #    forgiving lookup for partial names / typos.
+    # A FAILED LOOKUP IS NOT AN ABSENT SYMBOL. Both used to return the "no
+    # definition found" sentence below, which made a permission error, a binder
+    # error and a genuine miss indistinguishable — and told the reader to
+    # broaden a pattern that was never the problem. That is exactly how the
+    # 0.8.1 sandbox bug presented: every symbol in a healthy project reported
+    # missing, for hours, while the server called all its tools healthy.
+    lookup_error: Exception | None = None
     try:
         rel = con.find_definitions(
             file_pattern=file_pattern, name_pattern=f"%{name}%",
         )
         defs = rel.fetchall()
         def_cols = rel.columns
-    except Exception:
+    except Exception as exc:
+        log.debug("find_definitions failed for %r", name, exc_info=True)
+        lookup_error = exc
         defs = []
         def_cols = []
 
@@ -176,6 +185,14 @@ def investigate(con, defaults, name, file_pattern=None, path=None):
         if _exact:
             defs = _exact
 
+    if lookup_error is not None:
+        return (
+            f"Could not look up '{name}' — the definition query failed, so "
+            f"whether this symbol exists is UNKNOWN.\n"
+            f"{type(lookup_error).__name__}: {lookup_error}\n"
+            f"Searched: {file_pattern}"
+        )
+
     if not defs:
         return f"No definition found for '{name}'. Try a broader pattern or check spelling."
 

squackit-0.8.3/tests/test_error_visibility.py

@@ -0,0 +1,198 @@
+"""A failure must not be representable as an ordinary result.
+
+Three places used to violate that, each in a different way:
+
+* ``investigate`` caught every query exception and rendered it with the same
+  sentence it uses for a genuine miss — so a permission error, a binder error
+  and "that symbol isn't here" were indistinguishable, and the advice offered
+  ("try a broader pattern") actively misdirected. This is not hypothetical: it
+  is exactly how the 0.8.1 sandbox bug presented, for hours, while the server
+  reported every tool healthy.
+* ``collect_pluckin_tools`` dropped a raising pluckin's tools with a bare
+  ``pass`` under a comment claiming the error would be surfaced elsewhere.
+  Nothing surfaced it. A silently shorter tool surface is worse than a silently
+  empty result — an empty result prompts "did that work?", a shorter tool list
+  reads as a different, reasonable version of the product.
+* Auto-generated macro descriptions were a bare signature, so a SQL macro named
+  ``ast_replace`` — which computes patched source and writes nothing, because a
+  SQL macro *cannot* write — read as a mutation to any caller.
+
+See issues #14 and #16.
+"""
+
+import logging
+
+import pytest
+
+from squackit.defaults import ProjectDefaults
+from squackit.tool_config import ToolPresentation
+from squackit.tools import collect_pluckin_tools
+from squackit.workflows import investigate
+
+
+# ── investigate: a failed query is not a miss ───────────────────────
+
+
+class _Rel:
+    def __init__(self, rows, cols):
+        self._rows, self.columns = rows, cols
+
+    def fetchall(self):
+        return self._rows
+
+
+class _ConRaises:
+    """A connection whose lookup fails the way a sandboxed one does."""
+
+    def __init__(self, exc):
+        self._exc = exc
+
+    def find_definitions(self, **kw):
+        raise self._exc
+
+
+class _ConEmpty:
+    """A connection that works and genuinely has no match."""
+
+    def find_definitions(self, **kw):
+        return _Rel([], ["file_path", "name", "kind",
+                         "start_line", "end_line", "signature"])
+
+
+@pytest.fixture
+def defaults(tmp_path):
+    return ProjectDefaults(code_pattern="**/*.py", root=str(tmp_path))
+
+
+class TestInvestigateDistinguishesFailureFromMiss:
+
+    def test_genuine_miss_keeps_the_helpful_message(self, defaults):
+        """The friendly wording is right when it IS a miss — keep it."""
+        out = investigate(_ConEmpty(), defaults, "nonexistent_symbol")
+        assert "No definition found" in out
+        assert "nonexistent_symbol" in out
+
+    def test_query_failure_does_NOT_claim_the_symbol_is_absent(self, defaults):
+        out = investigate(_ConRaises(RuntimeError("boom")), defaults, "parse_config")
+        assert "No definition found" not in out, (
+            "a failed lookup was reported as a confirmed absence"
+        )
+
+    def test_query_failure_says_it_failed(self, defaults):
+        out = investigate(_ConRaises(RuntimeError("boom")), defaults, "parse_config")
+        assert "could not" in out.lower() or "failed" in out.lower()
+
+    def test_query_failure_surfaces_the_underlying_error(self, defaults):
+        """The 0.8.1 bug was diagnosable only from this text."""
+        exc = RuntimeError(
+            'Permission Error: Cannot access file "**/*.py" '
+            "- file system operations are disabled by configuration"
+        )
+        out = investigate(_ConRaises(exc), defaults, "parse_config")
+        assert "Permission Error" in out, out
+
+    def test_query_failure_does_NOT_advise_broadening_the_pattern(self, defaults):
+        """That advice sends the reader at the wrong thing entirely."""
+        out = investigate(_ConRaises(RuntimeError("boom")), defaults, "parse_config")
+        assert "broader pattern" not in out
+
+
+# ── collect_pluckin_tools: a dropped pluckin is logged ───────────────
+
+
+class _Pluckin:
+    def __init__(self, tools=None, exc=None):
+        self._tools, self._exc = tools or [], exc
+
+    def squackit_tools(self):
+        if self._exc:
+            raise self._exc
+        return self._tools
+
+
+class _Plucker:
+    def __init__(self, pluckins):
+        self.pluckins = pluckins
+
+
+class TestPluckinFailuresAreVisible:
+
+    def test_a_raising_pluckin_does_not_break_the_registry(self):
+        """The guard itself is correct and stays."""
+        good = _Pluckin(tools=["t1", "t2"])
+        bad = _Pluckin(exc=RuntimeError("plugin exploded"))
+        assert collect_pluckin_tools(_Plucker([bad, good])) == ["t1", "t2"]
+
+    def test_a_raising_pluckin_is_LOGGED(self, caplog):
+        bad = _Pluckin(exc=RuntimeError("plugin exploded"))
+        with caplog.at_level(logging.WARNING, logger="squackit.tools"):
+            collect_pluckin_tools(_Plucker([bad]))
+        assert caplog.records, "a pluckin's tools vanished with no log record"
+
+    def test_the_log_names_the_pluckin_and_the_error(self, caplog):
+        bad = _Pluckin(exc=RuntimeError("plugin exploded"))
+        with caplog.at_level(logging.WARNING, logger="squackit.tools"):
+            collect_pluckin_tools(_Plucker([bad]))
+        text = " ".join(r.getMessage() for r in caplog.records)
+        assert "_Pluckin" in text, text
+        assert "plugin exploded" in text, text
+
+    def test_healthy_pluckins_log_nothing(self, caplog):
+        with caplog.at_level(logging.WARNING, logger="squackit.tools"):
+            collect_pluckin_tools(_Plucker([_Pluckin(tools=["t1"])]))
+        assert not caplog.records
+
+
+# ── generated descriptions state their semantics ─────────────────────
+
+
+class _Info:
+    """Stand-in for fledgling's ToolInfo carrying no description of its own.
+
+    ToolPresentation derives `name` and `params` from the info object, so the
+    stub has to supply macro_name/params rather than the presentation taking
+    them directly.
+    """
+
+    def __init__(self, macro_name, params, description=None):
+        self.macro_name = macro_name
+        self.tool_name = None
+        self.params = list(params)
+        self.description = description
+        self.required = None
+        self.required_params = []
+        self.format = None
+        self.parameters_schema = None
+
+
+def _presentation(name, params):
+    return ToolPresentation(info=_Info(name, params))
+
+
+class TestMutationNamedMacrosSayTheyDoNotMutate:
+
+    def test_ast_replace_states_it_does_not_modify(self):
+        d = _presentation("ast_replace", ["source", "selector", "new_text"])
+        assert "does not modify" in d.description.lower(), d.description
+
+    def test_ast_patch_states_it_does_not_modify(self):
+        d = _presentation("ast_patch", ["edits", "files"])
+        assert "does not modify" in d.description.lower(), d.description
+
+    def test_the_signature_is_still_there(self):
+        d = _presentation("ast_replace", ["source", "selector", "new_text"])
+        assert "ast_replace(source, selector, new_text)" in d.description
+
+    def test_read_only_macros_are_NOT_cluttered(self):
+        """A disclaimer on all 90 macros is context every agent pays for."""
+        d = _presentation("find_definitions", ["file_pattern", "name_pattern"])
+        assert "does not modify" not in d.description.lower()
+
+    def test_a_real_description_still_wins(self):
+        info = _Info("ast_replace", ["source"], description="The macro's own words.")
+        assert ToolPresentation(info=info).description == "The macro's own words."
+
+    def test_an_override_still_wins(self):
+        d = ToolPresentation(info=_Info("ast_replace", ["source"]),
+                             description_override="Overridden.")
+        assert d.description == "Overridden."

{squackit-0.8.2 → squackit-0.8.3}/tests/test_smoke.py

@@ -3,7 +3,23 @@
 
 def test_import_squackit():
     import squackit
-    assert squackit.__version__ == "0.4.1"
+    assert squackit.__version__
+
+
+def test_version_matches_the_installed_distribution():
+    """Pin the exported version to the distribution, not to a literal.
+
+    Asserting a hardcoded string here is what let `__version__` drift four
+    releases behind pyproject.toml: bumping the release left the module and
+    this test agreeing with each other and with nothing else. See #2 and #15.
+    """
+    from importlib.metadata import PackageNotFoundError, version
+    import squackit
+    try:
+        expected = version("squackit")
+    except PackageNotFoundError:
+        expected = "0.0.0.dev0"
+    assert squackit.__version__ == expected
 
 
 def test_fledgling_available():

squackit-0.8.2/squackit/__init__.py

@@ -1,3 +0,0 @@
-"""squackit: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."""
-
-__version__ = "0.4.1"