squackit 0.5.0__tar.gz → 0.7.0__tar.gz

squackit-0.7.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 0.6.0
+
+### Added — `investigate(path=)` for cross-project scoping
+`investigate(name, path=)` accepts an explicit `path` argument and scopes the
+symbol-lookup to that path's `scoped_code_pattern`. Without `path=`, defaults
+to the process `cwd`-scoped pattern (was: the global registry pattern, which
+substring-matched across every indexed project — e.g. `investigate("main")`
+returned hits from vendored JS in unrelated repos). Pre-existing
+`file_pattern=` overrides still work.
+
+### Added — per-root FTS search
+`search_*` tools now accept `root=<dir>` to index + search any repo on the
+fly. Indexes are LRU-cached per root for the session, so repeated queries
+in the same root stay cheap.
+
+### Fixed — agent-ergonomics findings
+- FTS now fails loud on index errors instead of silently returning empty.
+- `investigate` no longer mislabels callers in cross-file results.
+- Selector docs verified end-to-end against the running tool surface.
+- `lackpy` 0.12 dropped top-level re-exports; switched to submodule imports
+  to keep import-time light.
+
+### Docs
+- `:has(.call#NAME)` works now that pluckit delegates selector compilation
+  to sitting_duck (was a notable known-bug in 0.5.0).
+- Tool count corrected in README (~20 was wrong; actually ~35 / ~40 full).
+- Receiver-qualified call selectors (#4) marked DONE.
+- Response-type improvement proposals collected in `docs/proposals/`.
+
+## 0.5.0
+
+### Changed — migrate off pluckit/fledgling private internals
+squackit no longer reaches into private connection attributes; it now uses the
+public, SemVer'd contract from fledgling 0.10 and pluckit 0.13:
+
+- `con._con` → `con.con`; `con._tools` → `con.tools` (`server.py`, `cli.py`).
+- The lazy FTS rebuild (which poked `con._con` + a private `_fts_built` flag)
+  now delegates to fledgling's `Connection.ensure_fts()`. squackit keeps only
+  the `_FTS_MACROS` gating (which tools need FTS).
+- `plucker._registry.pluckins` → `plucker.pluckins`; `Chain._MUTATION_OPS`
+  → `Chain.MUTATION_OPS` (`tools.py`).
+
+### Dependencies — declare what we actually use, with compatible ranges
+- `ast-pluckit>=0.13.0,<0.14` (was `>=0.9.0`) — needs the public `pluckins`
+  accessor + `pluckins.search`/`viewer`.
+- `fledgling-mcp>=0.10.0,<0.11` — **newly declared.** squackit imports
+  `fledgling.tools.ToolInfo` and needs the `Connection.con/.tools/.ensure_fts`
+  contract; declaring it makes `Plucker.connection` always a `fledgling.Connection`
+  (ending the bare-duckdb surprise that caused the `'_con' missing` failures).
+
+### Net
+The brittle, undocumented, conditionally-present coupling is gone: a grep for
+private reach-ins (`con._con`, `con._tools`, `_registry`, `_MUTATION_OPS`,
+`_fts_built`) returns zero. The suite now composes by a versioned public API.

{squackit-0.5.0 → squackit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squackit
-Version: 0.5.0
+Version: 0.7.0
 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
@@ -71,8 +71,10 @@ Tab completion is built in (`eval "$(_SQUACKIT_COMPLETE=bash_source squackit)"`)
 
 ## What agents get via MCP
 
-- **20 tools** — CSS-selector code queries (via pluckit), file I/O, git history,
-  doc navigation, diagnostics
+- **~35 tools** — CSS-selector code queries (via pluckit), file I/O, git history,
+  doc navigation, conversation analytics, and diagnostics. The exact set is dynamic
+  (fledgling macros + pluckit tools + pluckins); a full install exposes ~40 MCP tools
+  including the workflows below.
 - **4 compound workflows** — `explore`, `investigate`, `review`, `search`
 - **3 prompt templates** — pre-loaded with live project data
 - **5 resources** — project overview, docs, git status, session log, diagnostics

{squackit-0.5.0 → squackit-0.7.0}/README.md

@@ -42,8 +42,10 @@ Tab completion is built in (`eval "$(_SQUACKIT_COMPLETE=bash_source squackit)"`)
 
 ## What agents get via MCP
 
-- **20 tools** — CSS-selector code queries (via pluckit), file I/O, git history,
-  doc navigation, diagnostics
+- **~35 tools** — CSS-selector code queries (via pluckit), file I/O, git history,
+  doc navigation, conversation analytics, and diagnostics. The exact set is dynamic
+  (fledgling macros + pluckit tools + pluckins); a full install exposes ~40 MCP tools
+  including the workflows below.
 - **4 compound workflows** — `explore`, `investigate`, `review`, `search`
 - **3 prompt templates** — pre-loaded with live project data
 - **5 resources** — project overview, docs, git status, session log, diagnostics

squackit-0.7.0/docs/proposals/2026-06-04-response-type-improvements.md

@@ -0,0 +1,134 @@
+# Response-type improvements — surfaced from dogfooding
+
+Empirical findings from an exploration session against `~/Projects/blq` on 2026-06-04. The skill descriptions accurately steered me to the right verbs (`explore` → `find_names` → `investigate` → `find`), but several response-shape issues forced workarounds I wouldn't have needed. Each item below is a discrete change; cherry-pick what's worth doing.
+
+## 1. `explore` — partial failures masquerade as success
+
+**Symptom**
+
+```
+### Key Definitions (top 20 by complexity)
+(could not load)
+```
+
+The overall call returned `{"result": "..."}` — success — but the most useful section silently degraded. No reason given, no signal in the response shape that anything went wrong. A caller programming against this can't distinguish "no definitions" from "extraction failed."
+
+**Proposal**
+
+Either of:
+
+- **(a) Structured result** — switch from one giant markdown string to `{languages: ..., key_definitions: {status, data, reason?}, docs: ..., recent_activity: {status, data, reason?}}`. Each section reports its own status. A failed section still has a `reason` field ("FTS index not populated for /path", "AST extraction unsupported for language X", etc.).
+- **(b) Inline error markers** — keep markdown but replace `(could not load)` with `(error: FTS index not populated — run \`fts_stats()\` to check, then rebuild)`. Same string format, just useful enough to act on.
+
+(a) is the bigger improvement but (b) is one-line. Maybe both: (a) for the API, (b) as a fallback for the rendered output.
+
+## 2. `explore` — `recent_activity` ignores the `path` argument
+
+**Symptom**
+
+```python
+explore(path="/home/teague/Projects/blq")
+# Languages, Documentation sections correctly reflect /Projects/blq
+# Recent Activity shows commits from /home/teague/.dotfiles (session cwd)
+```
+
+The git-log subquery in `recent_activity` runs against cwd, not against the requested `path`. Language scan and doc scan both honor `path`; only this one section leaks.
+
+**Proposal**
+
+Pipe `path` through to the git-context resolver in `explore`'s `recent_activity` builder, same way it reaches `project_overview`'s language scan. If `path` isn't a git repo, return an empty `recent_activity` with `reason="not a git repository"` rather than silently falling back to cwd.
+
+## 3. `investigate` — Source section truncates without signaling
+
+**Symptom**
+
+```
+### Definition
+| ... | start_line | end_line | ... |
+| ... | 187        | 242      | ... |
+
+### Source
+ 187  def _apply_mcp_thread_limits() -> None:
+ ...
+ 236          ThreadPoolExecutor(max_workers=async_workers, ...),
+```
+
+Definition says the function ends at line 242. Source stops at 236. No "...truncated" footer, no `max_lines` parameter in the call to bump. The caller has to notice the line-number mismatch to know there's missing source.
+
+**Proposal**
+
+Either:
+
+- Always render Source through line `end_line` (the def is bounded; serving the full body is the point of `investigate`).
+- OR add a `max_source_lines` parameter (default high enough to fit most functions) plus a footer `[truncated — N more lines; fetch with read_source(file_path, lines="237-242")]` when capped.
+
+## 4. Selectors match call names, not qualified attribute paths — DONE (sitting_duck c458a11)
+
+**Symptom**
+
+```python
+find(source="/blq/**/*.py", selector=".call#connect")
+# Returns 28 rows: 21 duckdb.connect(...), 4 db.connect(), 3 bare connect()
+```
+
+`.call#connect` matches any call whose attribute name is `connect`, regardless of receiver. To ask "every call to `duckdb.connect`", I had to inspect `peek` post-hoc.
+
+**Implemented**
+
+New `[receiver=X]` attribute filter on the existing `[attr op value]` selector surface. Supports `=`, `*=`, `^=`, `$=`. Examples:
+
+```python
+find(source="/blq/**/*.py", selector=".call#connect[receiver=duckdb]")
+# 21 rows — only duckdb.connect(...)
+
+find(source="/blq/**/*.py", selector=".call#connect[receiver=db]")
+# 4 rows — only db.connect()
+
+find(source="/blq/**/*.py", selector=".call#connect[receiver$=connect]")
+# Calls whose receiver chain ENDS with "connect" (rare but expressive)
+```
+
+Chose attribute syntax over `.call#duckdb.connect` because the latter isn't valid CSS (`#` can only appear once; `.` separates classes). Receivers containing parens (`(complex).method()`) and computed receivers (`getattr(...)()`) are out of scope for the first cut.
+
+Requires sitting_duck rebuild for the change to land in production. Tests at `sitting_duck/test/sql/ast_select_native.test` (4 cases covering positive/negative + 3 operators).
+
+## 5. `find` returns ~15 columns; ~4 are useful
+
+**Symptom**
+
+A `find` row currently includes: `node_id, type, semantic_type, flags, name, qualified_name, signature_type, parameters, modifiers, annotations, file_path, language, start_line, end_line, parent_id, depth, sibling_index, children_count, descendant_count, scope, peek`.
+
+For 99% of caller intents, only `file_path`, `start_line`, `end_line`, `name`, and `peek` matter. The rest is internal AST bookkeeping that bloats responses (and Claude's context window).
+
+**Proposal**
+
+Default to a compact column set — `file_path | start_line | end_line | name | peek`. Add `verbose=True` for the current full set when the caller actually needs it (e.g., debugging AST structure).
+
+This is also the cheapest improvement on the list — table-projection at the response layer, no logic changes.
+
+## 6. Consistent shape across verbs
+
+`explore` returns markdown with sections. `find` returns a markdown table. `investigate` returns markdown with sub-headings and embedded tables. Each is sensible alone but reading three in one session means three different parse strategies.
+
+**Proposal**
+
+Either fully commit to markdown (with consistent section-header conventions across verbs) or move to JSON+embedded-markdown. The current mix forces callers (human or agent) to context-switch.
+
+## 7. Truncation signaling
+
+`explore`'s doc table did this correctly: `--- omitted 1283 of 1293 rows ---`. But `find` and `investigate` don't always indicate when results are capped at `max_results`/`max_lines`. A caller seeing 50 rows can't tell whether 50 is the universe or just the first page.
+
+**Proposal**
+
+Standardize a footer like `[showing N of M; pass max_results=K to widen]` on every verb that has a default cap.
+
+## Priority suggestion
+
+If you only do two of these:
+
+1. **#5 (compact columns)** — biggest reduction in noise across every `find`/`find_names` call.
+2. **#2 (recent_activity path leak)** — cleanest correctness bug; one-liner fix.
+
+If three: add **#3 (investigate source truncation)** — that one bit me directly and the "Definition end_line vs Source last line" mismatch is unambiguous.
+
+The selector-qualification work (#4) is the most expressive improvement but also the most design. Worth its own thread.

{squackit-0.5.0 → squackit-0.7.0}/docs/superpowers/skills/exploring-unfamiliar-code/SKILL.md

@@ -64,13 +64,23 @@ Returns:
 
 This one tool gives you the definition *and* its neighborhood. Usually enough to decide if this is the right function to focus on.
 
-**`investigate` is scoped to the MCP server's project root.** If you're exploring a different project (absolute paths in Phase 1), `investigate` will return "No definition found" — it doesn't know about the other project. Substitute Phase 2 with manual queries:
+**Working on a project other than the server's own?** Two scoping rules:
+
+- **Full-text search** (`search_code` / `search_content` / `search_docs`) defaults to the
+  server's project and ignores the structural `source` glob. To FTS a *different* repo, pass
+  **`root=<repository directory>`** (absolute path) — squackit indexes it on first use and
+  caches it. `search_code(query="...", root="/abs/repo")` works across repos.
+- **`investigate`** is scoped to the server's project; on a different project it returns "No
+  definition found." Substitute Phase 2 with the structural tools (`find` / `view` /
+  `find_names` / `read_source`), which take an absolute `source` glob per call:
 
 ```
 # Equivalent of investigate(name="X") for a non-rooted project:
 find(source="/abs/path/**/*.py", selector=".fn#X")          # → definition + line range
 view(source="/abs/path/**/*.py", selector=".fn#X")          # → source body
-# (callers/callees: not currently available without investigate)
+find(source="/abs/path/**/*.py", selector=".call#X")        # → callers: each row's scope.function is the enclosing caller
+# (a function passed as a VALUE — pool.submit(X), a decorator, a callback — is not a call
+#  site, so .call#X won't list it; search the bare name "X" to find those references.)
 ```
 
 **When to repeat vs. pivot:**

{squackit-0.5.0 → squackit-0.7.0}/docs/superpowers/skills/pluck-chains/SKILL.md

@@ -121,14 +121,32 @@ pluck(argv="--plugin AstViewer src/auth.py find .fn#validate_token view")
 
 ## Selector cheat sheet
 
-Same CSS grammar as the single-purpose tools:
-
-- `.fn` / `.class` / `.call` — by kind
-- `#name` — by exact name (e.g. `.fn#main`)
-- `[attr]` — by attribute (e.g. `.fn[name*="test"]`)
-- `.class > .fn` — direct children
-- `.fn:has(.call#foo)` — functions that call foo
-- `.class[name*="Test"]` — classes with "Test" in name
+Same CSS grammar as the single-purpose tools. **Verified working:**
+
+- `.fn` / `.class` / `.call` — by kind (`.function` / `.func` / `.def` all alias `.fn`)
+- `#name` — by exact name: `.fn#main` (function def `main`), `.class#Foo`, and crucially
+  `.call#foo` (every **call site** of `foo(...)`)
+- `[attr]` — attribute match: `.fn[name*="test"]`, `.fn[name^=test_]`, `.class[name*="Test"]`
+- `.class > .fn` — direct children (a class's methods)
+
+### Finding callers — `.call#NAME` or `.fn:has(.call#NAME)`
+
+Two reliable ways to find who calls a function:
+
+- `find ".call#get_notifications"` → every call site of `get_notifications()`. Each result
+  row's `scope.function` field is the **enclosing function** (i.e. the caller). Exact and cheap.
+- `find ".fn:has(.call#get_notifications)"` → the caller functions directly. (This now works:
+  the `#NAME` filter inside `:has` is honored — selector matching is delegated to sitting_duck's
+  `ast_select`. Earlier pluckit versions dropped it and over-matched; that's fixed.)
+- A function passed as a **value** (`pool.submit(fn)`, a decorator, a callback) is **not** a
+  call site, so neither form lists it. To find those references, search the bare name.
+
+### Filtering by decorator
+
+Use `:decorated` (functions with any decorator) or filter on the `annotations` /
+`modifiers` column that `find` / `find_names` return (e.g. `['@mcp.tool()']`, `['@property']`)
+when you need a specific decorator. Likewise attribute-chain calls (`os.environ.get(...)`) match
+on the final name: try `.call#get`, but verify with a quick `find` before relying on it.
 
 Escape whitespace in args with quotes: `containing "return None"`.
 

{squackit-0.5.0 → squackit-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "squackit"
-version = "0.5.0"
+version = "0.7.0"
 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.5.0 → squackit-0.7.0}/scripts/iterative_eval.py

@@ -38,7 +38,7 @@ def setup_lackpy():
     """Initialize lackpy service with squackit tools."""
     project_root = Path(__file__).parent.parent
     sys.path.insert(0, str(project_root))
-    from lackpy import LackpyService
+    from lackpy.service import LackpyService
     from squackit.lackpy_integration import register_squackit_kit
 
     svc = LackpyService(workspace=project_root)

{squackit-0.5.0 → squackit-0.7.0}/squackit/lackpy_integration.py

@@ -6,7 +6,7 @@ work to squackit.
 
 Usage::
 
-    from lackpy import LackpyService
+    from lackpy.service import LackpyService
     from squackit.lackpy_integration import register_squackit_kit
 
     svc = LackpyService()
@@ -153,7 +153,7 @@ def _read_source_tool(file_path: str, lines: str | None = None) -> str:
 
 
 def _make_tool_specs() -> list[Any]:
-    from lackpy import ArgSpec, ToolSpec  # type: ignore
+    from lackpy.kit.toolbox import ArgSpec, ToolSpec  # type: ignore
 
     return [
         ToolSpec(

squackit-0.7.0/squackit/runtime.py

@@ -0,0 +1,167 @@
+"""In-memory runtime configuration for the squackit MCP server.
+
+Distinct from ProjectDefaults (which is inferred-at-startup + file-loaded
+overrides from .fledgling-python/config.toml). This module holds *session*
+state that the MCP `config()` tool reads and writes — wiped on server
+restart, no disk persistence.
+
+Env vars at launch seed the initial values (e.g. SQUACKIT_ACTIVE_ROOT set
+in .mcp.json env block). Resetting reverts to those env-seeded values, not
+hardcoded defaults.
+
+Shape mirrors jetsam.config.runtime; see retritis bench/config-endpoint-plan.md
+for the cross-suite design.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, fields, replace
+from typing import Any
+
+
+_ENV_PREFIX = "SQUACKIT_"
+
+_VALID_LOG_LEVELS = {"debug", "info", "warn", "warning", "error"}
+
+
+@dataclass
+class SquackitRuntimeConfig:
+    """Session-scoped runtime knobs for the squackit MCP server.
+
+    Common keys (suite-wide convention, also on jetsam):
+        active_root: fallback when a tool's `path=`/`root=` arg is omitted.
+            None means use the server's process cwd (today's behavior).
+        log_level: debug | info | warn | error.
+
+    Squackit-specific:
+        max_results_default: default cap for token-aware result truncation
+            when tools don't get an explicit max_results.
+        complexity_max_results_default: separate cap for `complexity` tool,
+            which is usually requested in smaller batches.
+        fts_cache_size: LRU size for per-root FTS indexes. Larger = more
+            roots cached cheaply; smaller = less RAM but more rebuilds.
+            Note: takes effect on NEW roots; existing cache entries keep
+            their slot until they age out naturally.
+    """
+
+    active_root: str | None = None
+    log_level: str = "info"
+    max_results_default: int = 50
+    complexity_max_results_default: int = 20
+    fts_cache_size: int = 8
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> "SquackitRuntimeConfig":
+        """Build a config seeded from environment variables.
+
+        Variables read (each optional):
+            SQUACKIT_ACTIVE_ROOT
+            SQUACKIT_LOG_LEVEL
+            SQUACKIT_MAX_RESULTS_DEFAULT
+            SQUACKIT_COMPLEXITY_MAX_RESULTS_DEFAULT
+            SQUACKIT_FTS_CACHE_SIZE
+
+        Invalid values fall back to the dataclass default.
+        """
+        e = env if env is not None else os.environ
+        cfg = cls()
+
+        if v := e.get(f"{_ENV_PREFIX}ACTIVE_ROOT"):
+            cfg.active_root = v
+        if v := e.get(f"{_ENV_PREFIX}LOG_LEVEL"):
+            if v.lower() in _VALID_LOG_LEVELS:
+                cfg.log_level = v.lower()
+        if v := e.get(f"{_ENV_PREFIX}MAX_RESULTS_DEFAULT"):
+            try:
+                cfg.max_results_default = max(1, int(v))
+            except ValueError:
+                pass
+        if v := e.get(f"{_ENV_PREFIX}COMPLEXITY_MAX_RESULTS_DEFAULT"):
+            try:
+                cfg.complexity_max_results_default = max(1, int(v))
+            except ValueError:
+                pass
+        if v := e.get(f"{_ENV_PREFIX}FTS_CACHE_SIZE"):
+            try:
+                cfg.fts_cache_size = max(1, int(v))
+            except ValueError:
+                pass
+
+        return cfg
+
+    def to_dict(self) -> dict[str, Any]:
+        """Flat dict for the MCP `config()` response."""
+        return {f.name: getattr(self, f.name) for f in fields(self)}
+
+
+# Module-level singleton, seeded from env on import.
+_runtime: SquackitRuntimeConfig = SquackitRuntimeConfig.from_env()
+_seed: SquackitRuntimeConfig = replace(_runtime)
+
+
+def get_runtime() -> SquackitRuntimeConfig:
+    """Return the current runtime config."""
+    return _runtime
+
+
+def update_runtime(values: dict[str, Any]) -> SquackitRuntimeConfig:
+    """Merge values into the runtime config. Validates atomically.
+
+    Raises ValueError on unknown keys or invalid values, leaving the runtime
+    config unchanged.
+    """
+    global _runtime
+    valid_keys = {f.name for f in fields(SquackitRuntimeConfig)}
+    unknown = set(values) - valid_keys
+    if unknown:
+        raise ValueError(
+            f"unknown config key(s): {sorted(unknown)}. "
+            f"Valid keys: {sorted(valid_keys)}"
+        )
+
+    candidate = replace(_runtime)
+    for key, value in values.items():
+        _validate_one(key, value)
+        setattr(candidate, key, value)
+
+    _runtime = candidate
+    return _runtime
+
+
+def reset_runtime() -> SquackitRuntimeConfig:
+    """Reset to the env-seeded values captured at module import time."""
+    global _runtime
+    _runtime = replace(_seed)
+    return _runtime
+
+
+def resolve_scope_path(explicit_path: str | None = None) -> str:
+    """Resolve a scope path with the runtime config fallback chain.
+
+    Precedence: explicit_path -> runtime.active_root -> process cwd.
+    Used by tools that scope queries to a directory (investigate, etc.)
+    so a single `config(set={"active_root": X})` call configures the whole
+    session.
+    """
+    if explicit_path is not None:
+        return explicit_path
+    runtime_root = _runtime.active_root
+    if runtime_root is not None:
+        return runtime_root
+    return os.getcwd()
+
+
+def _validate_one(key: str, value: Any) -> None:
+    """Per-key value validation."""
+    if key == "log_level":
+        if not isinstance(value, str) or value.lower() not in _VALID_LOG_LEVELS:
+            raise ValueError(
+                f"log_level must be one of {sorted(_VALID_LOG_LEVELS)}, got {value!r}"
+            )
+    elif key in ("max_results_default", "complexity_max_results_default", "fts_cache_size"):
+        if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+            raise ValueError(f"{key} must be a positive int, got {value!r}")
+    elif key == "active_root":
+        if value is not None and not isinstance(value, str):
+            raise ValueError(f"active_root must be str or None, got {type(value).__name__}")