feat(code-mode): add opt-in execution runner - #7

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp_ynab/code_mode/stubs.py`:
- Around line 34-38: The generated method stubs inside the class are missing the
implicit instance parameter; update the stub generator in
src/mcp_ynab/code_mode/stubs.py so the signature for instance methods includes
"self" as the first parameter (i.e., build the param list for the string for
f"async def {tool.name}(...)" by prepending "self" to params before joining),
and ensure the code handles the case where params is empty (result should be
"self" not "self, "). Use the existing symbols (tool.name, params, return_type,
description) when constructing the final stub lines.

In `@src/mcp_ynab/resources.py`:
- Line 61: The function _read_code_mode_examples() currently raises a generic
RuntimeError when the code-mode examples file isn't found; change that to raise
FileNotFoundError with the same informative message (including the searched
variable) so callers can explicitly handle missing-file cases and tests can
assert the specific exception type. Locate the raise in
src/mcp_ynab/resources.py (the line with raise RuntimeError(f"Code Mode examples
file not found; searched: {searched}")) and replace the exception type to
FileNotFoundError while preserving the message.

In `@src/mcp_ynab/tools/code_mode.py`:
- Around line 36-38: The timeout calculation can produce non-positive values
when timeout <= 0, which will make asyncio.wait_for raise immediately; in the
block that sets timeout_s (using timeout, prefs.code_mode_timeout_s) clamp the
computed value to a sensible positive minimum (e.g., max(timeout_s, 0.1) or
max(timeout_s, 1)) after applying the min(...) so timeout_s is always > 0 before
it is passed to asyncio.wait_for; update the logic that assigns timeout_s (and
any callers that use timeout or prefs.code_mode_timeout_s) to enforce this lower
bound.

---

Nitpick comments:
In `@docs/code-mode-plan.md`:
- Around line 347-351: The fenced code block containing
get_transactions_needing_attention() and bulk_categorize([...]) lacks a language
identifier; update that code fence to include a language (e.g., add ```python)
so it matches the rest of the document and satisfies markdown linting, ensuring
the block begins with ```python and ends with ``` without changing the code
inside.

In `@src/mcp_ynab/code_mode/runner.py`:
- Line 188: The loop is iterating the private FastMCP internals via
mcp._tool_manager._tools; replace that with the public async API by calling
await mcp.list_tools() (and adjust the code in both
src/mcp_ynab/code_mode/runner.py and src/mcp_ynab/code_mode/stubs.py
accordingly). Specifically, stop using mcp._tool_manager._tools and instead
await mcp.list_tools(), then iterate the returned tool entries (adapting to the
returned structure) so the existing server-side code_mode_replace_tools
filtering is respected.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/code-mode-examples.md`:
- Line 8: Update the docs line about the LIMIT constant to explicitly state its
purpose and default value: mention that LIMIT is used to keep returned data
small and that LIMIT defaults to 10 (or the actual default used in the codebase)
so readers know what to expect; reference the LIMIT constant in the sentence and
add a short parenthetical or clause like "LIMIT defaults to 10" to the existing
line in docs/code-mode-examples.md.

In `@src/mcp_ynab/code_mode/runner.py`:
- Around line 231-232: The current await asyncio.wait_for(main(),
timeout=timeout_s) inside the contextlib.redirect_stdout(logs_buffer) block
cannot abort synchronous/blocking user code; to enforce timeout_s reliably run
the user-executing main() in an isolated worker process (or a separate OS
thread/process via multiprocessing.Process or
concurrent.futures.ProcessPoolExecutor) and kill/terminate that worker if
timeout_s elapses. Change the runner to spawn the worker that executes main()
with its stdout/stderr captured (redirect logs_buffer into the child or pipe
stdout back), wait for the worker with a hard timeout, and on timeout terminate
the worker and return a timeout error; reference main(), timeout_s, and the
contextlib.redirect_stdout(logs_buffer) usage to locate where to replace the
await asyncio.wait_for call.
- Around line 102-118: The function _truncate_result currently returns the raw
result in the early-return paths which can include non-JSON-safe values; change
it to always use the JSON-safe serialized form from _serialize_result.
Specifically, call _serialize_result(result) for all cases (including when
max_chars < 0 and when len(serialized) <= max_chars) and return that serialized
value along with the truncated flag (False in non-truncated cases); keep the
existing truncated branch that returns the preview from _truncate(serialized,
max_chars). Ensure this makes CodeModeResult.result JSON-safe for
model_dump(mode="json").
- Around line 221-228: The audit currently parses the raw snippet via
_audit_code(code, ...) which can miss syntax errors introduced by wrapping;
change the flow to call _audit_code on the wrapped body instead by first
generating wrapped = _wrap_code(code) and then invoking _audit_code(wrapped,
mutations_enabled=mutations_enabled) before compiling; ensure you still pass the
same flags and that errors raised are CodeModeAuditError so invalid constructs
(e.g., break/continue) are caught during audit rather than at compile().

---

Nitpick comments:
In `@docs/code-mode-plan.md`:
- Around line 347-351: The code block showing the multi-call sequence is missing
a Markdown language identifier; update the fenced block containing
get_transactions_needing_attention() and bulk_categorize([...]) to include a
language tag (e.g., `text` or `python`) so the markdown linter is satisfied and
formatting is consistent—locate the fence around the calls to
get_transactions_needing_attention and bulk_categorize and add the chosen
language identifier immediately after the opening ``` fence.

In `@tests/test_server.py`:
- Around line 205-214: The test
test_code_mode_examples_resource_uses_current_namespaces is brittle because it
asserts a minimum content length via assert len(text.strip()) > 500; remove that
length-based assertion in the block that calls server.get_code_mode_examples()
and instead rely on verifying required namespace snippets (e.g.,
"ynab.read.get_budgets", "ynab.read.get_transactions_needing_attention",
"ynab.write.bulk_categorize") are present in text; keep the existing checks that
the examples list has one item and that those namespace strings are in text to
validate the contract without coupling to document length.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/mcp_ynab/code_mode/runner.py`:
- Around line 219-231: _build_ynab_proxy currently reads
mcp._tool_manager._tools directly; change it to use the centralized iterator
helper (_iter_mcp_tools) provided in stubs (or extract a shared helper) so there
is a single fix point for MCP internals; specifically, replace the for loop over
mcp._tool_manager._tools in _build_ynab_proxy with iteration from
_iter_mcp_tools(mcp) and keep the existing logic that selects target = write if
_is_mutating_tool(tool) else read and calls _bind_tool(tool, ctx), while
preserving the mutations_enabled branch that may replace write with
_DisabledWriteNamespace.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 56-58: The fenced code block in README.md is missing a language
label and triggers MD040; update the unlabeled block (the triple-backtick block
containing "set_preference: code_mode_replace_tools = false") to include a
language identifier (e.g., add "text" after the opening ``` to become ```text)
so the markdown linter stops reporting `fenced-code-language`.

---

Outside diff comments:
In `@src/mcp_ynab/code_mode/runner.py`:
- Around line 243-274: The logs truncation behavior is inconsistent because
_run_snippet uses _BoundedStringIO(max_output_chars) which treats negative caps
as "no capacity" and appends suffix after fill; instead, instantiate
_BoundedStringIO with a positive capacity only when max_output_chars >= 0 (or
pass a sentinel/None for unlimited) but do not rely on its truncated flag; after
capturing full logs from logs_buffer.getvalue(), call _truncate(logs,
max_output_chars) (the same helper used on timeout) and use its returned
truncated boolean to set CodeModeResult.truncated, and ensure result truncation
still uses _truncate_result; update references in _run_snippet to stop using
logs_buffer.truncated and to consistently use _truncate(...) so negative
max_output_chars means unlimited and suffix handling matches the contract.

In `@src/mcp_ynab/server.py`:
- Around line 226-241: The current filter in _list_tools_with_code_mode_filter
only returns tools whose name is in _CODE_MODE_REPLACEMENT_VISIBLE_TOOLS, which
drops required bootstrap tools when code_mode_replace_tools is enabled; update
the filter so it preserves bootstrap tools as well (e.g., return [tool for tool
in tools if tool.name in _CODE_MODE_REPLACEMENT_VISIBLE_TOOLS or getattr(tool,
"is_bootstrap", False)]), or alternatively expand
_CODE_MODE_REPLACEMENT_VISIBLE_TOOLS to include known bootstrap tool names; make
this change inside _list_tools_with_code_mode_filter and ensure it honors
ynab_resources.preferences.code_mode_replace_tools.

---

Nitpick comments:
In `@src/mcp_ynab/code_mode/stubs.py`:
- Around line 77-97: Define a TypedDict for the fixed schema and update
build_spec's return annotation to use it: create a ToolSpec (TypedDict) with
keys "name": str, "namespace": str, "signature": str, "doc": str, and "returns":
str; import TypedDict (and Optional if needed) and replace the function
signature def build_spec(...)-> list[dict] with def build_spec(...)->
list[ToolSpec]; ensure the entries.append() payload created in build_spec (which
uses _iter_mcp_tools, _is_mutating_tool, inspect.signature, _format_param, and
_annotation_name) conforms to the TypedDict types so static checkers can
validate callers.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/test_server.py`:
- Around line 250-255: The test block around the simulated missing package data
is misformatted for Ruff/Black; reformat the block to satisfy ruff format
(Black-compatible) by adjusting whitespace and indentation around the _raise
function, the monkeypatch.setattr call (targeting
server.resources._resource_files), and the assignment original_is_file =
Path.is_file so the function definition and subsequent statements follow Black
style; run `uv run ruff format --check src/ tests/` locally and apply the
formatter (uv run ruff format) until the test_server.py block with _raise,
monkeypatch.setattr(server.resources, "_resource_files", _raise), and
original_is_file = Path.is_file passes.