diff --git a/.serena/memories/conventions.md b/.serena/memories/conventions.md new file mode 100644 index 00000000..5c18dc52 --- /dev/null +++ b/.serena/memories/conventions.md @@ -0,0 +1,26 @@ +# Conventions + +## Style (project-instructed) +- Idiomatic, object-oriented design. Non-trivial interfaces use **explicitly typed abstractions** (strategy pattern etc.) rather than bare functions/callbacks. +- Avoid low-level data structures where an OO abstraction fits. For simple data containers use **dataclasses**, not dicts/tuples. +- Structure function bodies into **functional blocks separated by blank lines**, each prefixed with a short elliptical phrase (lowercase, no leading capital) describing the block's purpose. +- **Docstrings: reStructuredText.** Param/return/raises use `:param x:`, `:return:`, `:raises X:`. +- Parameter / method / class descriptions begin with a precise elliptical phrase defining *what* the thing is; details in subsequent sentences. + +## Formatting / lint (ruff) +- Line length 140, double quotes, target `py311`. +- Many "annoying" rules are disabled — see `[tool.ruff.lint] ignore` in `pyproject.toml` before adding workarounds (e.g. `Optional[T]` is preferred over `T | None`, `Union` is allowed, relative imports forbidden, `% string formatting` allowed). +- `ruff format` runs on `src scripts test`; same set for `ruff check`. +- mccabe complexity cap: 20. + +## Typing (mypy strict) +- `disallow_untyped_defs = true`, `disallow_incomplete_defs = true`, `strict_equality`, `strict_optional`, `warn_unreachable`, `no_implicit_optional`. +- Excluded paths: `^build/`, `^docs/`, `^test/resources/`. +- Test files relax `disallow_untyped_defs` (still type-checked otherwise). + +## Tests +- Language-server tests are pytest-marker-gated (one marker per language; see `pyproject.toml` `[tool.pytest.ini_options].markers`). Default `poe test` runs unmarked tests + whatever `PYTEST_MARKERS` selects. +- Snapshot tests use **syrupy** with custom `--snapshot-patch-pycharm-diff` plugin (auto-added via `addopts`). + +## Memories +- Follow `mem:memory_maintenance` for any new/updated memory in `.serena/memories/`. diff --git a/.serena/memories/core.md b/.serena/memories/core.md new file mode 100644 index 00000000..d4a76ff1 --- /dev/null +++ b/.serena/memories/core.md @@ -0,0 +1,29 @@ +# Serena — Project Core + +Serena is an MCP-based "IDE for coding agents": semantic code retrieval/editing/refactoring tools driven by language servers. + +## Source map + +- `src/serena/` — agent, MCP server, tools, project/config layer + - `agent.py`, `mcp.py`, `project_server.py`, `cli.py`, `hooks.py` — entrypoints/wiring + - `tools/` — tool implementations (memory_tools, symbol_tools, file_tools, workflow_tools, query_project_tools, config_tools, cmd_tools, jetbrains_tools) + - `tools/tools_base.py` — base classes for all tools + - `config/` — `serena_config.py`, `context_mode.py`, `client_setup.py` + - `resources/config/contexts/*.yml`, `resources/config/modes/*.yml` — context/mode definitions + - `code_editor.py`, `symbol.py`, `ls_manager.py` — symbolic editing / LS lifecycle + - `dashboard.py`, `gui_log_viewer.py` — web dashboard / log viewer + - `prompt_factory.py` + `generated/generated_prompt_factory.py` — prompts (regenerate with `scripts/gen_prompt_factory.py`) +- `src/solidlsp/` — LSP client framework; per-language servers under `language_servers/` +- `src/interprompt/` — prompt template library (synced from external repo; see `.syncCommitId.*`) +- `test/serena/`, `test/solidlsp//` — pytest suites; per-language tests gated by pytest markers +- `test/resources/repos//` — fixture projects used by language-server tests +- `scripts/` — utilities (prompt regen, tool overview, profiling, agno agent) +- `docs/` — Jupyter Book sources; build via poe `doc-build` + +## Project-wide invariants + +- Package name (PyPI): `serena-agent`; import root: `serena`. Wheel includes `serena`, `interprompt`, `solidlsp`. +- Python: `>=3.11, <3.15`. Dependencies are exact-pinned in `pyproject.toml` (uvx installs from git, lockfile ignored — pin exactly). +- Entry points: `serena` → `serena.cli:top_level`; `serena-hooks` → `serena.hooks:hook_commands`. +- Per-project state lives under `/.serena/` (config + `memories/` as `.md` files). +- See `mem:tech_stack`, `mem:suggested_commands`, `mem:conventions`, `mem:task_completion`. diff --git a/.serena/memories/memory_maintenance.md b/.serena/memories/memory_maintenance.md new file mode 100644 index 00000000..cfb4c05c --- /dev/null +++ b/.serena/memories/memory_maintenance.md @@ -0,0 +1,42 @@ +# Memory Maintenance + +## Discovery Model + +- Agents start with the full memory name list and should read `mem:core` first as the routing entry point. +- All other memory discovery comes from memory names plus routing already read. +- Routing is useful only before the target memory is selected. Once a memory is open, target-selection text inside it can no longer help decide to read it. +- Therefore, never put self-referential selection cues in a memory body: no "Start here", "Use when", "Use before", "Use after", or "read this when..." openers. + Such self-referential cues are an error mode: they are unreachable for selection, duplicate routing that belongs upstream, and drift independently from the actual routing graph. +- Add routing only when names are insufficient, ambiguous, or a non-obvious dependency/order matters. Do not add tautological routing such as "frontend debugging -> frontend/debugging". +- Routing can live outside core memories when needed, but core memories own most module-level routing because they are read before focused memories in that subfolder. +- Top-level/startup memory is `mem:core`; top-level memory in each memory subfolder is `/core` (for example `mem:frontend/core`). +- Memory references must use a mem: prefix inside backticks, e.g. `mem:frontend/core`. +- Do not add an index that simply re-lists the focused-memory names, the memory name list is already visible. + Only add routing pointers when a target memory's name is not self-explanatory or when a some aspect should be routed to multiple memories. + +## Style + +Dense agent notes, not prose docs. Prefer invariants, paths, commands, terse bullets. Avoid obvious context, rationale, and examples unless they prevent likely mistakes. Keep guidance durable and generalizable, not task-local. + +## Add/update threshold + +Add or update memory only for stable, non-obvious project conventions that avoid complex rediscovery. + +Do not add: quick-read/rg facts; generic language/framework knowledge; one-off task notes; volatile line-level details; behavior likely to change soon. + +Operational constants (commands, paths, version pins): phrase as current behavior; before changing the value, update it in the owning memory and run `serena memories check` to catch references that need updating. + +## Graph Ownership + +- Project-level routing: `mem:core`. +- Module-level routing/source maps: module core memories. +- Focused memories: topic details only; assume relevant routing was read before selection. + +## Maintenance Actions + +- Renamed/removed/split/merged/superseded memory: update all references. Done automatically if handled via Serena's memory rename tool. +- Stale paths/namespaces/commands/behavior: update or remove in owning memory. If working with Serena, call `serena memories check` for a report. +- Split catch-all memory when sections are commonly needed independently or agents must read unrelated domains to reach needed topic. +- Retire/delete memory when owning module/subsystem is removed or replaced; remove all references. +- Added/renamed/split/moved/deleted memory: update affected routing only where names are insufficient. +- Before finishing: list memories for old names and key new names to catch stale/missing references. \ No newline at end of file diff --git a/.serena/memories/serena_core_concepts_and_architecture.md b/.serena/memories/serena_core_concepts_and_architecture.md deleted file mode 100644 index 49edd2aa..00000000 --- a/.serena/memories/serena_core_concepts_and_architecture.md +++ /dev/null @@ -1,175 +0,0 @@ -# Serena Core Concepts and Architecture - -## High-Level Architecture - -Serena is built around a dual-layer architecture: - -1. **SerenaAgent** - The main orchestrator that manages projects, tools, and user interactions -2. **SolidLanguageServer** - A unified wrapper around Language Server Protocol (LSP) implementations - -## Core Components - -### 1. SerenaAgent (`src/serena/agent.py`) - -The central coordinator that: -- Manages active projects and their configurations -- Coordinates between different tools and contexts -- Handles language server lifecycle -- Manages memory persistence -- Provides MCP (Model Context Protocol) server interface - -Key responsibilities: -- **Project Management** - Activating, switching between projects -- **Tool Registry** - Loading and managing available tools based on context/mode -- **Language Server Integration** - Starting/stopping language servers per project -- **Memory Management** - Persistent storage of project knowledge -- **Task Execution** - Coordinating complex multi-step operations - -### 2. SolidLanguageServer (`src/solidlsp/ls.py`) - -A unified abstraction over multiple language servers that provides: -- **Language-agnostic interface** for symbol operations -- **Caching layer** for performance optimization -- **Error handling and recovery** for unreliable language servers -- **Uniform API** regardless of underlying LSP implementation - -Core capabilities: -- Symbol discovery and navigation -- Code completion and hover information -- Find references and definitions -- Document and workspace symbol search -- File watching and change notifications - -### 3. Tool System (`src/serena/tools/`) - -Modular tool architecture with several categories: - -#### File Tools (`file_tools.py`) -- File system operations (read, write, list directories) -- Text search and pattern matching -- Regex-based replacements - -#### Symbol Tools (`symbol_tools.py`) -- Language-aware symbol finding and navigation -- Symbol body replacement and insertion -- Reference finding across codebase - -#### Memory Tools (`memory_tools.py`) -- Project knowledge persistence -- Memory retrieval and management -- Onboarding information storage - -#### Configuration Tools (`config_tools.py`) -- Project activation and switching -- Mode and context management -- Tool inclusion/exclusion - -### 4. Configuration System (`src/serena/config/`) - -Multi-layered configuration supporting: -- **Contexts** - Define available tools and their behavior -- **Modes** - Specify operational patterns (interactive, editing, etc.) -- **Projects** - Per-project settings and language server configs -- **Tool Sets** - Grouped tool collections for different use cases - -## Language Server Integration - -### Language Support Model - -Each supported language has: -1. **Language Server Implementation** (`src/solidlsp/language_servers/`) -2. **Runtime Dependencies** - Managed downloads of language servers -3. **Test Repository** (`test/resources/repos//`) -4. **Test Suite** (`test/solidlsp//`) - -### Language Server Lifecycle - -1. **Discovery** - Find language servers or download them automatically -2. **Initialization** - Start server process and perform LSP handshake -3. **Project Setup** - Open workspace and configure language-specific settings -4. **Operation** - Handle requests/responses with caching and error recovery -5. **Shutdown** - Clean shutdown of server processes - -### Supported Languages - -Current language support includes: -- **C#** - Microsoft.CodeAnalysis.LanguageServer (.NET 9) -- **Python** - Pyright or Jedi -- **TypeScript/JavaScript** - TypeScript Language Server -- **Rust** - rust-analyzer -- **Go** - gopls -- **Java** - Eclipse JDT Language Server -- **Kotlin** - Kotlin Language Server -- **PHP** - Intelephense -- **Ruby** - Solargraph -- **Clojure** - clojure-lsp -- **Elixir** - ElixirLS -- **Dart** - Dart Language Server -- **C/C++** - clangd -- **Terraform** - terraform-ls - -## Memory and Knowledge Management - -### Memory System -- **Markdown-based storage** in `.serena/memories/` directory -- **Contextual retrieval** - memories loaded based on relevance -- **Project-specific** knowledge persistence -- **Onboarding support** - guided setup for new projects - -### Knowledge Categories -- **Project Structure** - Directory layouts, build systems -- **Architecture Patterns** - How the codebase is organized -- **Development Workflows** - Testing, building, deployment -- **Domain Knowledge** - Business logic and requirements - -## MCP Server Interface - -Serena exposes its functionality through Model Context Protocol: -- **Tool Discovery** - AI agents can enumerate available tools -- **Context-Aware Operations** - Tools behave based on active project/mode -- **Stateful Sessions** - Maintains project state across interactions -- **Error Handling** - Graceful degradation when tools fail - -## Error Handling and Resilience - -### Language Server Reliability -- **Timeout Management** - Configurable timeouts for LSP requests -- **Process Recovery** - Automatic restart of crashed language servers -- **Fallback Behavior** - Graceful degradation when LSP unavailable -- **Caching Strategy** - Reduces impact of server failures - -### Project Activation Safety -- **Validation** - Verify project structure before activation -- **Error Isolation** - Project failures don't affect other projects -- **Recovery Mechanisms** - Automatic cleanup and retry logic - -## Performance Considerations - -### Caching Strategy -- **Symbol Cache** - In-memory caching of expensive symbol operations -- **File System Cache** - Reduced disk I/O for repeated operations -- **Language Server Cache** - Persistent cache across sessions - -### Resource Management -- **Language Server Pooling** - Reuse servers across projects when possible -- **Memory Management** - Automatic cleanup of unused resources -- **Background Operations** - Async operations don't block user interactions - -## Extension Points - -### Adding New Languages -1. Implement language server class in `src/solidlsp/language_servers/` -2. Add runtime dependencies configuration -3. Create test repository and test suite -4. Update language enumeration and configuration - -### Adding New Tools -1. Inherit from `Tool` base class in `tools_base.py` -2. Implement required methods and parameter validation -3. Register tool in appropriate tool registry -4. Add to context/mode configurations as needed - -### Custom Contexts and Modes -- Define new contexts in YAML configuration files -- Specify tool sets and operational patterns -- Configure for specific development workflows \ No newline at end of file diff --git a/.serena/memories/suggested_commands.md b/.serena/memories/suggested_commands.md index 2ecbe796..5ae6638f 100644 --- a/.serena/memories/suggested_commands.md +++ b/.serena/memories/suggested_commands.md @@ -1,26 +1,24 @@ # Suggested Commands -## Development Tasks (using uv and poe) +Run via `uv run poe ` (or `poe ` inside the activated venv). Poe executor is `simple`, so plain `poe` works without uv re-resolving. -The following tasks should generally be executed using `uv run poe `. +## Dev loop +- `poe test` — pytest on `test/` (per-language tests are marker-gated; pass `-m ` to enable). +- `poe lint` — ruff format-check + ruff check (no fixes). +- `poe format` — ruff `--fix` then `ruff format` (mutates files). +- `poe type-check` — mypy on `src/serena`, `src/solidlsp`, and `test/` (test pass disables `no-untyped-def`). +- Single test file: `uv run pytest test/path/to/test_x.py -vv`. Language-gated: add `-m python` etc. -- `format`: This is the **only** allowed command for formatting. Run as `uv run poe format`. -- `type-check`: This is the **only** allowed command for type checking. Run as `uv run poe type-check`. -- `test`: This is the preferred command for running tests (`uv run poe test [args]`). You can select subsets of tests with markers, - the current markers are - ```toml - markers = [ - "python: language server running for Python", - "go: language server running for Go", - "java: language server running for Java", - "rust: language server running for Rust", - "typescript: language server running for TypeScript", - "php: language server running for PHP", - "snapshot: snapshot tests for symbolic editing operations", - ] - ``` - By default, `uv run poe test` uses the markers set in the env var `PYTEST_MARKERS`, or, if it unset, uses `-m "not java and not rust and not isolated process"`. - You can override this behavior by simply passing the `-m` option to `uv run poe test`, e.g. `uv run poe test -m "python or go"`. +## Docs +- `poe doc-build` — clean + autogen + sphinx (uses `rm -rf`; needs a unix-like shell, e.g. Git Bash on Windows). -For finishing a task, make sure format, type-check and test pass! Run them at the end of the task -and if needed fix any issues that come up and run them again until they pass. \ No newline at end of file +## Entrypoints +- `uv run serena ...` — main CLI (`serena.cli:top_level`). +- `uv run serena-hooks ...` — hook helpers. +- `python scripts/gen_prompt_factory.py` — regenerate `src/serena/generated/generated_prompt_factory.py` after editing prompt templates. + +## Windows shell notes (PowerShell 7+ is the project shell) +- Use `Remove-Item -Recurse -Force ` instead of `rm -rf` (the `doc-clean` poe task uses unix `rm -rf` and requires bash). +- Env vars: `$env:NAME = 'value'` (not `export`). +- Path separator in `pyproject.toml` poe tasks uses forward slashes; PowerShell accepts them in arguments. +- `git`, `uv`, `poe`, `pytest` behave identically to unix. diff --git a/.serena/memories/task_completion.md b/.serena/memories/task_completion.md new file mode 100644 index 00000000..5ca33012 --- /dev/null +++ b/.serena/memories/task_completion.md @@ -0,0 +1,11 @@ +# Task Completion Checklist + +After any code change in `src/` or `test/`, run: + +1. `uv run poe format` — applies ruff fixes + formatting (mutates files). +2. `uv run poe type-check` — mypy strict on `src/serena`, `src/solidlsp`, `test/`. +3. `uv run poe test` — pytest on affected files or affected languages, using `-m` markers. + +If prompt templates changed: `uv run python scripts/gen_prompt_factory.py` (regenerates `src/serena/generated/generated_prompt_factory.py`; use `uv run poe format` and commit the result). + +If memories were edited/renamed/split: run `uv run serena memories check` from the project root to find broken `mem:` references. diff --git a/.serena/memories/tech_stack.md b/.serena/memories/tech_stack.md new file mode 100644 index 00000000..f868cca6 --- /dev/null +++ b/.serena/memories/tech_stack.md @@ -0,0 +1,10 @@ +# Tech Stack + +- Language: Python 3.11–3.14 (`requires-python = ">=3.11, <3.15"`). +- Package/dep manager: **uv** (uv.lock present). Exact version pins in `pyproject.toml` because `uvx` installs from git and ignores the lockfile. +- Build backend: `hatchling`. Packages: `src/serena`, `src/interprompt`, `src/solidlsp`. +- Task runner: **poethepoet** (`poe `). Poe executor is `simple` (does NOT shell out via uv) — avoids env recreation while MCP server is running. +- Key runtime deps: `mcp`, `flask` (dashboard), `pydantic`, `pygls` + `lsprotocol` (LSP), `anthropic`, `jinja2`, `ruamel.yaml`, `pywebview`/`pystray` (GUI), `pythonnet` (Windows only). +- Dev deps: `ruff` (lint+format), `mypy` (strict), `pytest` (+ `pytest-xdist`, `pytest-timeout`, `syrupy` snapshots), `sphinx`/`jupyter-book` for docs. +- Optional extras: `agno` (Agno agent integration), `google` (gemini). +- LSP client core lives under `src/solidlsp/`; one subdir per supported language server under `language_servers/`.