squawkit 0.1.0__py3-none-any.whl

squawkit/__init__.py

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

squawkit/__main__.py

@@ -0,0 +1,5 @@
+"""Run fledgling MCP server: python -m squawkit"""
+
+from squawkit.server import main
+
+main()

squawkit/db.py

@@ -0,0 +1,17 @@
+"""DuckDB connection for squawkit.
+
+Thin wrapper over pluckit's Plucker that returns a fledgling-enabled
+connection proxy with auto-generated macro wrappers.
+"""
+
+from pluckit import Plucker
+
+
+def create_connection(**kwargs):
+    """Create a fledgling-enabled DuckDB connection via pluckit.
+
+    Accepts the same kwargs as :class:`pluckit.Plucker` (``repo``,
+    ``profile``, ``modules``, ``init``). Returns the fledgling Connection
+    proxy — the same object squawkit's server.py uses as ``con``.
+    """
+    return Plucker(**kwargs).connection

squawkit/defaults.py

@@ -0,0 +1,225 @@
+"""Smart project-aware defaults for fledgling tools.
+
+Infers sensible default patterns (code globs, doc paths, git revisions)
+from the project at server startup. Users can override via
+.fledgling-python/config.toml. Explicit tool parameters always win.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+log = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from duckdb import DuckDBPyConnection as Connection
+
+
+@dataclass
+class ProjectDefaults:
+    """Inferred at server startup, cached for the session."""
+
+    code_pattern: str = "**/*"
+    doc_pattern: str = "**/*.md"
+    main_branch: str = "main"
+    from_rev: str = "HEAD~1"
+    to_rev: str = "HEAD"
+    languages: list[str] = field(default_factory=list)
+
+    def scoped_code_pattern(self, path: str | Path) -> str:
+        """Scope the code pattern to a subdirectory path."""
+        filename_glob = self.code_pattern.rsplit("/", 1)[-1]
+        return str(Path(path) / "**" / filename_glob)
+
+
+def apply_defaults(
+    defaults: ProjectDefaults,
+    tool_name: str,
+    kwargs: dict[str, object],
+) -> dict[str, object]:
+    """Substitute None params with smart defaults for a given tool.
+
+    Returns a new dict — does not mutate the input.
+    """
+    mapping = TOOL_DEFAULTS.get(tool_name)
+    if not mapping:
+        return dict(kwargs)
+    result = dict(kwargs)
+    for param, field_name in mapping.items():
+        if result.get(param) is None:
+            result[param] = getattr(defaults, field_name)
+    return result
+
+
+def load_config(root: str | Path) -> dict[str, str]:
+    """Read defaults overrides from .fledgling-python/config.toml.
+
+    Returns the [defaults] section as a flat dict, or {} if the file
+    doesn't exist or has no [defaults] section.
+    """
+    config_path = Path(root) / ".fledgling-python" / "config.toml"
+    if not config_path.is_file():
+        return {}
+    with open(config_path, "rb") as f:
+        data = tomllib.load(f)
+    return dict(data.get("defaults", {}))
+
+
+# Tool name → {param_name: defaults_field_name}
+TOOL_DEFAULTS: dict[str, dict[str, str]] = {
+    "find_definitions":         {"file_pattern": "code_pattern"},
+    "find_in_ast":              {"file_pattern": "code_pattern"},
+    "code_structure":           {"file_pattern": "code_pattern"},
+    "complexity_hotspots":      {"file_pattern": "code_pattern"},
+    "changed_function_summary": {"file_pattern": "code_pattern"},
+    "doc_outline":              {"file_pattern": "doc_pattern"},
+    "file_changes":             {"from_rev": "from_rev", "to_rev": "to_rev"},
+    "file_diff":                {"from_rev": "from_rev", "to_rev": "to_rev"},
+    "structural_diff":          {"from_rev": "from_rev", "to_rev": "to_rev"},
+}
+
+
+# ── Language detection ──────────────────────────────────────────────
+
+# Language name (as returned by project_overview) → file extensions.
+# Hardcoded for now; will be replaced by sitting_duck's extension listing
+# when available.
+LANGUAGE_EXTENSIONS: dict[str, list[str]] = {
+    "Python": ["py", "pyi"],
+    "JavaScript": ["js", "jsx", "mjs"],
+    "TypeScript": ["ts", "tsx"],
+    "Rust": ["rs"],
+    "Go": ["go"],
+    "Java": ["java"],
+    "Ruby": ["rb"],
+    "C": ["c"],
+    "C++": ["cpp", "cc"],
+    "C/C++": ["h", "hpp"],
+    "SQL": ["sql"],
+    "Shell": ["sh", "bash", "zsh"],
+    "Kotlin": ["kt", "kts"],
+    "Swift": ["swift"],
+    "Dart": ["dart"],
+    "PHP": ["php"],
+    "Lua": ["lua"],
+    "Zig": ["zig"],
+    "R": ["r", "R"],
+    "C#": ["cs"],
+    "HCL": ["hcl", "tf"],
+}
+
+# Directories to check for docs, in priority order.
+_DOC_DIRS = ["docs", "documentation", "doc", "wiki"]
+
+
+def _code_glob(extensions: list[str]) -> str:
+    """Build a glob pattern from a list of extensions.
+
+    Uses only the primary (first) extension because DuckDB's glob()
+    does not support brace expansion (e.g. ``**/*.{py,pyi}``).
+    """
+    return f"**/*.{extensions[0]}"
+
+
+def _find_doc_dir(con: Connection, root: str | Path) -> str | None:
+    """Check for common doc directories under `root` using list_files.
+
+    Uses an absolute glob (``{root}/{d}/*``) so the probe doesn't depend
+    on the connection's ``session_root`` matching the caller's intended
+    project root. The previous relative-pattern form silently failed when
+    ``session_root`` and the ``root`` parameter diverged, causing
+    doc_pattern to fall back to ``**/*.md``.
+    """
+    root_path = Path(root)
+    for d in _DOC_DIRS:
+        try:
+            pattern = str(root_path / d / "*")
+            rows = con.list_files(pattern).fetchall()
+            if rows:
+                return d
+        except Exception:
+            log.debug("doc dir probe failed for %s", d, exc_info=True)
+            continue
+    return None
+
+
+def _infer_main_branch(root: str | Path) -> str:
+    """Detect the default branch from git remote HEAD."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "origin/HEAD"],
+            capture_output=True, text=True, cwd=str(Path(root)), timeout=5,
+        )
+        if result.returncode == 0:
+            # Output is "origin/main" or "origin/master" — strip prefix
+            branch = result.stdout.strip().removeprefix("origin/")
+            if branch:
+                return branch
+    except Exception:
+        log.debug("git main branch detection failed", exc_info=True)
+    return "main"
+
+
+def infer_defaults(
+    con: Connection,
+    overrides: dict[str, str] | None = None,
+    root: str | Path | None = None,
+) -> ProjectDefaults:
+    """Analyze the project and build smart defaults.
+
+    Args:
+        con: A fledgling Connection to the project.
+        overrides: Values from config file that override inference.
+        root: Project root for git operations. Defaults to cwd.
+
+    Returns:
+        ProjectDefaults with inferred + overridden values.
+    """
+    overrides = overrides or {}
+
+    # ── Code pattern ────────────────────────────────────────────
+    code_pattern = "**/*"
+    languages: list[str] = []
+    try:
+        rows = con.project_overview().fetchall()
+        # rows are (language, extension, file_count) ordered by count DESC
+        if rows:
+            # Group by language, sum file counts
+            lang_counts: dict[str, int] = {}
+            for lang, _ext, count in rows:
+                lang_counts[lang] = lang_counts.get(lang, 0) + count
+            languages = sorted(lang_counts.keys())
+            # Find the top language that we have extension mappings for
+            ranked = sorted(lang_counts, key=lang_counts.get, reverse=True)  # type: ignore[arg-type]
+            for lang in ranked:
+                if lang in LANGUAGE_EXTENSIONS:
+                    code_pattern = _code_glob(LANGUAGE_EXTENSIONS[lang])
+                    break
+    except Exception:
+        log.debug("project_overview inference failed", exc_info=True)
+
+    # ── Doc pattern ─────────────────────────────────────────────
+    doc_dir = _find_doc_dir(con, root or ".")
+    doc_pattern = str(Path(doc_dir) / "**" / "*.md") if doc_dir else "**/*.md"
+
+    # ── Main branch ─────────────────────────────────────────────
+    main_branch = _infer_main_branch(root or ".")
+
+    # ── Build defaults, apply overrides ─────────────────────────
+    defaults = ProjectDefaults(
+        code_pattern=code_pattern,
+        doc_pattern=doc_pattern,
+        main_branch=main_branch,
+        languages=languages,
+    )
+
+    for key, value in overrides.items():
+        if hasattr(defaults, key):
+            setattr(defaults, key, value)
+
+    return defaults

squawkit/formatting.py

@@ -0,0 +1,89 @@
+"""Shared formatting and truncation helpers for fledgling.
+
+Used by both server.py (auto-registered tools) and workflows.py
+(compound tools) without circular imports.
+"""
+
+from __future__ import annotations
+
+
+# ── Truncation config ──────────────────────────────────────────────
+# These dicts live here so _truncate_rows can reference them without
+# importing server.py.
+
+_MAX_LINES = {
+    "read_source": 200,
+    "read_context": 50,
+    "file_diff": 300,
+    "file_at_version": 200,
+}
+
+_MAX_ROWS = {
+    "find_definitions": 50,
+    "find_in_ast": 50,
+    "list_files": 100,
+    "doc_outline": 50,
+    "file_changes": 25,
+    "recent_changes": 20,
+}
+
+_HINTS = {
+    "read_source": "Use lines='N-M' to see a range, or match='keyword' to filter.",
+    "read_context": "Use a smaller context window or match='keyword' to filter.",
+    "file_diff": "Use a narrower revision range.",
+    "file_at_version": "Use lines='N-M' to see a range.",
+    "find_definitions": "Use name_pattern='%keyword%' to narrow, or file_pattern to scope.",
+    "find_in_ast": "Use name='keyword' to narrow results.",
+    "list_files": "Use a more specific glob pattern.",
+    "doc_outline": "Use search='keyword' to filter.",
+    "file_changes": "Use a narrower revision range.",
+    "recent_changes": "Use a smaller count.",
+}
+
+_HEAD_TAIL = 5  # rows to show at each end of truncated output
+
+
+def _truncate_rows(rows, max_rows, macro_name):
+    """Truncate rows to head + tail with an omission message.
+
+    Returns (display_rows, omission_line) where omission_line is None
+    if no truncation occurred.
+    """
+    total = len(rows)
+    if max_rows <= 0 or total <= max_rows:
+        return rows, None
+    # Not enough rows for a clean head/tail split — return all
+    if total <= 2 * _HEAD_TAIL:
+        return rows, None
+    head = rows[:_HEAD_TAIL]
+    tail = rows[-_HEAD_TAIL:]
+    omitted = total - 2 * _HEAD_TAIL
+    hint = _HINTS.get(macro_name, "")
+    unit = "lines" if macro_name in _MAX_LINES else "rows"
+    msg = f"--- omitted {omitted} of {total} {unit} ---"
+    if hint:
+        msg += f"\n{hint}"
+    return head + tail, msg
+
+
+def _format_markdown_table(cols: list[str], rows: list[tuple]) -> str:
+    """Format query results as a markdown table."""
+    # Calculate column widths
+    widths = [len(c) for c in cols]
+    str_rows = []
+    for row in rows:
+        str_row = [str(v) if v is not None else "" for v in row]
+        str_rows.append(str_row)
+        for i, v in enumerate(str_row):
+            widths[i] = max(widths[i], len(v))
+
+    # Build table
+    lines = []
+    header = "| " + " | ".join(c.ljust(widths[i]) for i, c in enumerate(cols)) + " |"
+    sep = "|-" + "-|-".join("-" * widths[i] for i in range(len(cols))) + "-|"
+    lines.append(header)
+    lines.append(sep)
+    for str_row in str_rows:
+        line = "| " + " | ".join(v.ljust(widths[i]) for i, v in enumerate(str_row)) + " |"
+        lines.append(line)
+    return "\n".join(lines)

squawkit/prompts.py

@@ -0,0 +1,236 @@
+"""Fledgling: MCP prompt templates.
+
+Parameterized workflow instructions with live project data pre-filled.
+Each prompt calls the corresponding P4-004 workflow function to gather
+context, then embeds it into condensed instructions derived from the
+skill guides in skills/.
+
+The agent uses prompts to learn *how* to approach a task; it uses
+compound tools to get the *information* for the task.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from squawkit.workflows import explore, investigate, review
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from duckdb import DuckDBPyConnection as Connection
+    from squawkit.defaults import ProjectDefaults
+
+log = logging.getLogger(__name__)
+
+
+def _escape_braces(value: str) -> str:
+    """Escape curly braces so user input is safe for str.format()."""
+    return value.replace("{", "{{").replace("}", "}}")
+
+
+# ── Templates ─────────────────────────────────────────────────────
+# Condensed from skills/*.md — actionable steps with {briefing}
+# placeholder for live data and tool suggestions pre-filled with
+# the project's inferred patterns.
+
+EXPLORE_TEMPLATE = """\
+## Explore Codebase
+
+You are exploring {scope}. Below is a pre-loaded briefing followed by \
+a workflow for deeper exploration.
+
+### Project Briefing
+
+{briefing}
+
+### Exploration Workflow
+
+Work top-down through these phases:
+
+**Phase 1: Landscape** (loaded above)
+Review the Languages, Key Definitions, and Documentation sections. \
+Note the dominant language and most complex definitions.
+
+**Phase 2: Architecture**
+- `CodeStructure('{code_pattern}')` — definitions per file, complexity
+- `FindDefinitions('{code_pattern}')` — functions, classes, modules
+
+**Phase 3: Dependencies**
+- `FindInAST('{code_pattern}', 'imports')` — external dependencies
+- `FindInAST('{code_pattern}', 'calls')` — internal call graph
+
+**Phase 4: History**
+- `recent_changes(20)` — commit history
+- `GitDiffSummary(from_rev='HEAD~10', to_rev='HEAD')` — changed files
+- `changed_function_summary('HEAD~10', 'HEAD', '{code_pattern}')` — semantic changes
+
+**Phase 5: Deep Dive**
+- `ReadLines(file_path='...', lines='42-60')` — specific range
+- `MDSection(file_path='...', section_id='...')` — doc sections
+
+### Anti-Patterns
+- Use `ReadLines` with line ranges, not `cat` or `head`
+- Use `FindDefinitions` then `ReadLines`, not `grep -r`
+- Use `list_files` with globs, not `find . -name`
+"""
+
+INVESTIGATE_TEMPLATE = """\
+## Investigate Issue
+
+You are investigating: **{symptom}**
+
+### Initial Findings
+
+{briefing}
+
+### Investigation Workflow
+
+**Step 1: Locate** (findings above)
+Review the definitions and source above. If not found, try:
+- `FindDefinitions('{code_pattern}', '%{symptom}%')` — broader search
+- `ReadLines(file_path='...', match='{symptom}')` — grep-like search
+
+**Step 2: Understand the Code**
+- `ReadLines(file_path='...', lines='42', ctx='10')` — context around a line
+- `CodeStructure('...')` — file overview with complexity
+
+**Step 3: Check History**
+- `GitDiffSummary(from_rev='HEAD~20', to_rev='HEAD')` — what files changed
+- `GitDiffFile(file='...', from_rev='HEAD~5', to_rev='HEAD')` — line-level diff
+- `changed_function_summary('HEAD~10', 'HEAD', '{code_pattern}')` — complexity changes
+
+**Step 4: Trace Dependencies**
+- `FindInAST('...', 'imports')` — external dependencies
+- `FindInAST('...', 'calls')` — function calls made
+
+**Step 5: Check Related Code**
+- `FindDefinitions('{code_pattern}', '%similar_name%')` — related functions
+- `function_callers('{code_pattern}', 'func_name')` — callers
+
+### Key Principles
+- Locate before reading — find the right file and line first
+- History is data — check what changed recently
+- Compose queries — use the query tool for complex joins
+"""
+
+REVIEW_TEMPLATE = """\
+## Review Changes
+
+You are reviewing: **{rev_range}**
+
+### Change Summary
+
+{briefing}
+
+### Review Checklist
+
+**Step 1: File-Level Overview** (loaded above)
+Review Changed Files. Prioritize largest changes; note new/deleted files.
+
+**Step 2: Function-Level Analysis** (loaded above)
+Review Changed Functions. Focus on:
+- High-complexity new functions (need most scrutiny)
+- Functions where complexity increased
+- Deleted functions (check for orphaned callers)
+
+**Step 3: Read Diffs** (top diffs loaded above)
+For additional files:
+- `GitDiffFile(file='...', from_rev='{from_rev}', to_rev='{to_rev}')`
+
+**Step 4: Understand Context**
+- `ReadLines(file_path='...', lines='42', ctx='15')` — surrounding code
+- `CodeStructure('...')` — file structure
+
+**Step 5: Check Impact**
+- `function_callers('{code_pattern}', 'func_name')` — callers of changed functions
+- `FindInAST('...', 'imports')` — dependency changes
+
+**Step 6: Compare Versions**
+- `GitShow(file='...', rev='{from_rev}')` — old implementation
+
+### Review Quality Checks
+- New functions without tests? Check `changed_function_summary` where change_status='added'
+- Complexity increases above 5? Inspect those functions
+- Large new files (>5000 bytes)? Consider splitting
+"""
+
+
+# ── Registration ──────────────────────────────────────────────────
+
+
+def register_prompts(mcp: FastMCP, con: Connection, defaults: ProjectDefaults):
+    """Register MCP prompt templates on the FastMCP server."""
+
+    @mcp.prompt(
+        name="explore",
+        description="Exploration workflow with live project data: languages, "
+                    "key definitions, docs, recent activity, and step-by-step "
+                    "guidance for deeper exploration.",
+    )
+    def explore_prompt(path: str | None = None) -> str:
+        scope = f"path: {path}" if path else "the full project"
+        code_pattern = (
+            defaults.scoped_code_pattern(path)
+            if path else defaults.code_pattern
+        )
+        # Escape user input for safe str.format() interpolation
+        scope = _escape_braces(scope)
+        code_pattern = _escape_braces(code_pattern)
+        try:
+            briefing = explore(con, defaults, path=path)
+        except Exception:
+            log.debug("explore prompt: data gathering failed", exc_info=True)
+            briefing = "(Project data could not be loaded. Use the tools below to gather context manually.)"
+
+        return EXPLORE_TEMPLATE.format(
+            scope=scope,
+            briefing=briefing,
+            code_pattern=code_pattern,
+        )
+
+    @mcp.prompt(
+        name="investigate",
+        description="Investigation workflow with pre-found definitions and "
+                    "source code for a symptom (error message, function name, "
+                    "or file path), plus step-by-step debugging guidance.",
+    )
+    def investigate_prompt(symptom: str) -> str:
+        code_pattern = defaults.code_pattern
+        try:
+            briefing = investigate(con, defaults, name=symptom)
+        except Exception:
+            log.debug("investigate prompt: data gathering failed", exc_info=True)
+            briefing = f"(Could not find data for '{symptom}'. Use the tools below to search manually.)"
+
+        return INVESTIGATE_TEMPLATE.format(
+            symptom=_escape_braces(symptom),
+            briefing=briefing,
+            code_pattern=_escape_braces(code_pattern),
+        )
+
+    @mcp.prompt(
+        name="review",
+        description="Code review checklist with pre-loaded change summary, "
+                    "complexity deltas, and diffs, plus step-by-step review "
+                    "guidance.",
+    )
+    def review_prompt(from_rev: str | None = None, to_rev: str | None = None) -> str:
+        effective_from = from_rev or defaults.from_rev
+        effective_to = to_rev or defaults.to_rev
+        rev_range = f"{effective_from}..{effective_to}"
+        code_pattern = defaults.code_pattern
+
+        try:
+            briefing = review(con, defaults, from_rev=from_rev, to_rev=to_rev)
+        except Exception:
+            log.debug("review prompt: data gathering failed", exc_info=True)
+            briefing = "(Change data could not be loaded. Use the tools below to gather context manually.)"
+
+        return REVIEW_TEMPLATE.format(
+            rev_range=rev_range,
+            briefing=briefing,
+            from_rev=effective_from,
+            to_rev=effective_to,
+            code_pattern=code_pattern,
+        )