avrae-ls 0.3.1__py3-none-any.whl → 0.4.1__py3-none-any.whl

avrae_ls/runtime.py

@@ -6,6 +6,7 @@ import json
 import logging
 import math
 import random
+import re
 import time
 from types import SimpleNamespace
 try:  # optional dependency
@@ -98,7 +99,66 @@ def _vroll_dice(dice: str, multiply: int = 1, add: int = 0) -> SimpleRollResult
     return SimpleRollResult(rolled)
 
 
-def _parse_coins(args: str):
+@dataclass
+class _CoinsArgs:
+    pp: int = 0
+    gp: int = 0
+    ep: int = 0
+    sp: int = 0
+    cp: int = 0
+    explicit: bool = False
+
+    @property
+    def total(self) -> float:
+        return (self.pp * 10) + self.gp + (self.ep * 0.5) + (self.sp * 0.1) + (self.cp * 0.01)
+
+
+def _parse_coin_args(args: str) -> _CoinsArgs:
+    cleaned = str(args).replace(",", "")
+    try:
+        return _parse_coin_args_float(float(cleaned))
+    except ValueError:
+        return _parse_coin_args_re(cleaned)
+
+
+def _parse_coin_args_float(coins: float) -> _CoinsArgs:
+    total_copper = int(round(coins * 100, 1))
+    if coins < 0:
+        return _CoinsArgs(cp=total_copper)
+    return _CoinsArgs(
+        gp=total_copper // 100,
+        sp=(total_copper % 100) // 10,
+        cp=total_copper % 10,
+    )
+
+
+def _parse_coin_args_re(args: str) -> _CoinsArgs:
+    is_valid = re.fullmatch(r"(([+-]?\d+)\s*([pgesc]p)\s*)+", args, re.IGNORECASE)
+    if not is_valid:
+        raise avrae_argparser.InvalidArgument(
+            "Coins must be a number or a currency string, e.g. `+101.2` or `10cp +101gp -2sp`."
+        )
+
+    out = _CoinsArgs(explicit=True)
+    for coin_match in re.finditer(r"(?P<amount>[+-]?\d+)\s*(?P<currency>[pgesc]p)", args, re.IGNORECASE):
+        amount = int(coin_match["amount"])
+        currency = coin_match["currency"].lower()
+
+        if currency == "pp":
+            out.pp += amount
+        elif currency == "gp":
+            out.gp += amount
+        elif currency == "ep":
+            out.ep += amount
+        elif currency == "sp":
+            out.sp += amount
+        else:
+            out.cp += amount
+
+    return out
+
+
+def _parse_coins(args: str, include_total: bool = True):
     try:
         from avrae.aliasing.api.functions import parse_coins as avrae_parse_coins
     except Exception:
@@ -106,16 +166,21 @@ def _parse_coins(args: str):
 
     if avrae_parse_coins:
         try:
-            return avrae_parse_coins(str(args))
+            return avrae_parse_coins(str(args), include_total=include_total)
         except Exception:
             pass
 
-    # Fallback: accept numeric as gp, otherwise empty mapping.
-    try:
-        gp = float(str(args))
-        return {"pp": 0, "gp": gp, "ep": 0, "sp": 0, "cp": 0, "total": gp}
-    except Exception:
-        return {"pp": 0, "gp": 0, "ep": 0, "sp": 0, "cp": 0, "total": 0}
+    coin_args = _parse_coin_args(str(args))
+    parsed = {
+        "pp": coin_args.pp,
+        "gp": coin_args.gp,
+        "ep": coin_args.ep,
+        "sp": coin_args.sp,
+        "cp": coin_args.cp,
+    }
+    if include_total:
+        parsed["total"] = coin_args.total
+    return parsed
 
 
 def _default_builtins() -> Dict[str, Any]:
@@ -414,6 +479,9 @@ class MockExecutor:
             verify_cache_sig = sig_str
             verify_cache_error = None
             verify_cache_result = None
+            timeout = float(service_cfg.verify_timeout if service_cfg else AvraeServiceConfig.verify_timeout)
+            retries = int(service_cfg.verify_retries if service_cfg else AvraeServiceConfig.verify_retries)
+            retries = max(0, retries)
 
             def _call_verify_api(signature: str) -> Dict[str, Any]:
                 base_url = (service_cfg.base_url if service_cfg else AvraeServiceConfig.base_url).rstrip("/")
@@ -421,10 +489,18 @@ class MockExecutor:
                 headers = {"Content-Type": "application/json"}
                 if service_cfg and service_cfg.token:
                     headers["Authorization"] = str(service_cfg.token)
-                try:
-                    resp = httpx.post(url, json={"signature": signature}, headers=headers, timeout=5)
-                except Exception as exc:
-                    raise ValueError(f"Failed to verify signature: {exc}") from exc
+                last_exc: Exception | None = None
+                for attempt in range(retries + 1):
+                    try:
+                        resp = httpx.post(url, json={"signature": signature}, headers=headers, timeout=timeout)
+                        break
+                    except Exception as exc:
+                        last_exc = exc
+                        if attempt >= retries:
+                            raise ValueError(f"Failed to verify signature: {exc}") from exc
+                        continue
+                else:  # pragma: no cover - defensive
+                    raise ValueError(f"Failed to verify signature: {last_exc}") from last_exc
 
                 try:
                     payload = resp.json()
@@ -432,14 +508,17 @@ class MockExecutor:
                     raise ValueError("Failed to verify signature: invalid response body") from exc
 
                 if resp.status_code != 200:
-                    message = payload.get("error") if isinstance(payload, dict) else None
-                    raise ValueError(message or f"Failed to verify signature: HTTP {resp.status_code}")
+                    message = None
+                    if isinstance(payload, dict):
+                        message = payload.get("error") or payload.get("message")
+                    detail = f"{message} (HTTP {resp.status_code})" if message else f"HTTP {resp.status_code}"
+                    raise ValueError(f"Failed to verify signature: {detail}")
 
                 if not isinstance(payload, dict):
                     raise ValueError("Failed to verify signature: invalid response")
                 if payload.get("success") is not True:
                     message = payload.get("error")
-                    raise ValueError(message or "Failed to verify signature: unsuccessful response")
+                    raise ValueError(f"Failed to verify signature: {message or 'unsuccessful response'}")
 
                 data = payload.get("data")
                 if not isinstance(data, dict):

avrae_ls/server.py

@@ -18,7 +18,8 @@ from .alias_preview import render_alias_command, simulate_command
 from .parser import find_draconic_blocks
 from .signature_help import load_signatures, signature_help_for_code
 from .completions import gather_suggestions, completion_items_for_position, hover_for_position
-from .symbols import build_symbol_table, document_symbols, find_definition_range
+from .code_actions import code_actions_for_document
+from .symbols import build_symbol_table, document_symbols, find_definition_range, find_references, range_for_word
 from .argument_parsing import apply_argument_parsing
 
 __version__ = "0.1.0"
@@ -142,6 +143,43 @@ def on_definition(server: AvraeLanguageServer, params: types.DefinitionParams):
     return types.Location(uri=params.text_document.uri, range=rng)
 
 
+@ls.feature(types.TEXT_DOCUMENT_REFERENCES)
+def on_references(server: AvraeLanguageServer, params: types.ReferenceParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    table = build_symbol_table(doc.source)
+    word = doc.word_at_position(params.position)
+    if not word or not table.lookup(word):
+        return []
+
+    ranges = find_references(table, doc.source, word, include_declaration=params.context.include_declaration)
+    return [types.Location(uri=params.text_document.uri, range=rng) for rng in ranges]
+
+
+@ls.feature(types.TEXT_DOCUMENT_PREPARE_RENAME)
+def on_prepare_rename(server: AvraeLanguageServer, params: types.PrepareRenameParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    table = build_symbol_table(doc.source)
+    word = doc.word_at_position(params.position)
+    if not word or not table.lookup(word):
+        return None
+    return range_for_word(doc.source, params.position)
+
+
+@ls.feature(types.TEXT_DOCUMENT_RENAME)
+def on_rename(server: AvraeLanguageServer, params: types.RenameParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    table = build_symbol_table(doc.source)
+    word = doc.word_at_position(params.position)
+    if not word or not table.lookup(word) or not params.new_name:
+        return None
+
+    ranges = find_references(table, doc.source, word, include_declaration=True)
+    if not ranges:
+        return None
+    edits = [types.TextEdit(range=rng, new_text=params.new_name) for rng in ranges]
+    return types.WorkspaceEdit(changes={params.text_document.uri: edits})
+
+
 @ls.feature(types.WORKSPACE_SYMBOL)
 def on_workspace_symbol(server: AvraeLanguageServer, params: types.WorkspaceSymbolParams):
     symbols: list[types.SymbolInformation] = []
@@ -223,6 +261,12 @@ def on_hover(server: AvraeLanguageServer, params: types.HoverParams):
     return None
 
 
+@ls.feature(types.TEXT_DOCUMENT_CODE_ACTION)
+def on_code_action(server: AvraeLanguageServer, params: types.CodeActionParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    return code_actions_for_document(doc.source, params, server.workspace_root)
+
+
 @ls.command(RUN_ALIAS_COMMAND)
 async def run_alias(server: AvraeLanguageServer, *args: Any):
     payload = args[0] if args else {}
@@ -252,18 +296,20 @@ async def run_alias(server: AvraeLanguageServer, *args: Any):
         server.state.context_builder.gvar_resolver,
         args=alias_args,
     )
-    preview_output, command_name, validation_error = simulate_command(rendered.command)
+    preview = simulate_command(rendered.command)
 
     response: dict[str, Any] = {
         "stdout": rendered.stdout,
-        "result": preview_output if preview_output is not None else rendered.last_value,
+        "result": preview.preview if preview.preview is not None else rendered.last_value,
         "command": rendered.command,
-        "commandName": command_name,
+        "commandName": preview.command_name,
     }
     if rendered.error:
         response["error"] = _format_runtime_error(rendered.error)
-    if validation_error:
-        response["validationError"] = validation_error
+    if preview.validation_error:
+        response["validationError"] = preview.validation_error
+    if preview.embed:
+        response["embed"] = preview.embed.to_dict()
     if uri:
         extra = []
         if rendered.error:

avrae_ls/signature_help.py

@@ -157,15 +157,29 @@ def signature_help_for_code(code: str, line: int, character: int, sigs: Dict[str
         return None
 
     target_call: ast.Call | None = None
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Call):
+    target_depth = -1
+
+    class Finder(ast.NodeVisitor):
+        def __init__(self):
+            self.stack: list[ast.AST] = []
+
+        def visit_Call(self, node: ast.Call):
+            nonlocal target_call, target_depth
             if hasattr(node, "lineno") and hasattr(node, "col_offset"):
                 start = (node.lineno - 1, node.col_offset)
                 end_line = getattr(node, "end_lineno", node.lineno) - 1
                 end_col = getattr(node, "end_col_offset", node.col_offset)
                 if _pos_within((line, character), start, (end_line, end_col)):
-                    target_call = node
-                    break
+                    depth = len(self.stack)
+                    # Prefer the most nested call covering the cursor
+                    if depth >= target_depth:
+                        target_call = node
+                        target_depth = depth
+            self.stack.append(node)
+            self.generic_visit(node)
+            self.stack.pop()
+
+    Finder().visit(tree)
 
     if not target_call:
         return None
@@ -184,7 +198,7 @@ def signature_help_for_code(code: str, line: int, character: int, sigs: Dict[str
         documentation=fsig.doc,
         parameters=[types.ParameterInformation(label=p) for p in fsig.params],
     )
-    active_param = min(len(target_call.args), max(len(fsig.params) - 1, 0))
+    active_param = _active_param_index(target_call, (line, character), fsig.params)
     return types.SignatureHelp(signatures=[sig_info], active_signature=0, active_parameter=active_param)
 
 
@@ -199,3 +213,40 @@ def _pos_within(pos: Tuple[int, int], start: Tuple[int, int], end: Tuple[int, in
     if line == el and col > ec:
         return False
     return True
+
+
+def _active_param_index(call: ast.Call, cursor: Tuple[int, int], params: List[str]) -> int:
+    if not params:
+        return 0
+
+    # Build spans for positional args and keywords in source order.
+    spans: list[tuple[Tuple[int, int], Tuple[int, int], ast.AST]] = []
+    for arg in call.args:
+        spans.append((_node_start(arg), _node_end(arg), arg))
+    for kw in call.keywords:
+        spans.append((_node_start(kw), _node_end(kw), kw))
+    spans.sort(key=lambda s: (s[0][0], s[0][1]))
+
+    def _clamp(idx: int) -> int:
+        return max(0, min(idx, max(len(params) - 1, 0)))
+
+    for idx, (start, end, node) in enumerate(spans):
+        if _pos_within(cursor, start, end):
+            if isinstance(node, ast.keyword) and node.arg and node.arg in params:
+                return _clamp(params.index(node.arg))
+            return _clamp(idx)
+
+    # If cursor is after some args but not inside one, infer next argument slot.
+    before_count = sum(1 for start, _, _ in spans if start <= cursor)
+    return _clamp(before_count)
+
+
+def _node_start(node: ast.AST) -> Tuple[int, int]:
+    return (getattr(node, "lineno", 1) - 1, getattr(node, "col_offset", 0))
+
+
+def _node_end(node: ast.AST) -> Tuple[int, int]:
+    return (
+        getattr(node, "end_lineno", getattr(node, "lineno", 1)) - 1,
+        getattr(node, "end_col_offset", getattr(node, "col_offset", 0)),
+    )

avrae_ls/symbols.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import ast
 import logging
 from dataclasses import dataclass
-from typing import Dict, List, Optional
+from typing import Dict, Iterable, List, Optional
 
 import draconic
 from lsprotocol import types
@@ -40,10 +40,10 @@ def build_symbol_table(source: str) -> SymbolTable:
     parsed_source = apply_argument_parsing(source)
     blocks = find_draconic_blocks(parsed_source)
     if not blocks:
-        entries.extend(_symbols_from_code(parsed_source, 0))
+        entries.extend(_symbols_from_code(parsed_source, 0, 0))
     else:
         for block in blocks:
-            entries.extend(_symbols_from_code(block.code, block.line_offset))
+            entries.extend(_symbols_from_code(block.code, block.line_offset, block.char_offset))
     return SymbolTable(entries)
 
 
@@ -67,31 +67,72 @@ def find_definition_range(table: SymbolTable, name: str) -> types.Range | None:
     return None
 
 
-def _symbols_from_code(code: str, line_offset: int) -> List[SymbolEntry]:
-    parser = draconic.DraconicInterpreter()
-    local_offset = line_offset
-    try:
-        body = parser.parse(code)
-    except draconic.DraconicSyntaxError:
-        wrapped, added = _wrap_draconic(code)
-        try:
-            body = parser.parse(wrapped)
-            local_offset += -added
-        except draconic.DraconicSyntaxError:
-            return []
-    except Exception as exc:  # pragma: no cover - defensive
-        log.debug("Symbol extraction failed: %s", exc)
+def find_references(
+    table: SymbolTable, source: str, name: str, include_declaration: bool = True
+) -> List[types.Range]:
+    parsed_source = apply_argument_parsing(source)
+    ranges: list[types.Range] = []
+    entry = table.lookup(name)
+    include_stores = include_declaration and entry is None
+    if include_declaration:
+        if entry:
+            ranges.append(entry.selection_range)
+
+    blocks = find_draconic_blocks(parsed_source)
+    if not blocks:
+        ranges.extend(_references_from_code(parsed_source, name, 0, 0, include_stores))
+    else:
+        for block in blocks:
+            ranges.extend(
+                _references_from_code(block.code, name, block.line_offset, block.char_offset, include_stores)
+            )
+    return _dedupe_ranges(ranges)
+
+
+def range_for_word(source: str, position: types.Position) -> types.Range | None:
+    lines = source.splitlines()
+    if position.line >= len(lines):
+        return None
+    line = lines[position.line]
+    if position.character > len(line):
+        return None
+
+    def _is_ident(ch: str) -> bool:
+        return ch.isalnum() or ch == "_"
+
+    start_idx = position.character
+    while start_idx > 0 and _is_ident(line[start_idx - 1]):
+        start_idx -= 1
+
+    end_idx = position.character
+    while end_idx < len(line) and _is_ident(line[end_idx]):
+        end_idx += 1
+
+    if start_idx == end_idx:
+        return None
+
+    return types.Range(
+        start=types.Position(line=position.line, character=start_idx),
+        end=types.Position(line=position.line, character=end_idx),
+    )
+
+
+def _symbols_from_code(code: str, line_offset: int, char_offset: int) -> List[SymbolEntry]:
+    body, offset_adjust = _parse_draconic(code)
+    if not body:
         return []
 
+    local_offset = line_offset + offset_adjust
+
     entries: list[SymbolEntry] = []
     for node in body:
-        entry = _entry_from_node(node, local_offset)
+        entry = _entry_from_node(node, local_offset, char_offset)
         if entry:
             entries.append(entry)
     return entries
 
 
-def _entry_from_node(node: ast.AST, line_offset: int = 0) -> SymbolEntry | None:
+def _entry_from_node(node: ast.AST, line_offset: int = 0, char_offset: int = 0) -> SymbolEntry | None:
     if isinstance(node, ast.FunctionDef):
         kind = types.SymbolKind.Function
         name = node.name
@@ -103,6 +144,7 @@ def _entry_from_node(node: ast.AST, line_offset: int = 0) -> SymbolEntry | None:
         if isinstance(target, ast.Name):
             kind = types.SymbolKind.Variable
             name = target.id
+            node = target
         else:
             return None
     else:
@@ -110,37 +152,99 @@ def _entry_from_node(node: ast.AST, line_offset: int = 0) -> SymbolEntry | None:
 
     rng = _range_from_positions(
         getattr(node, "lineno", 1),
-        getattr(node, "col_offset", 0) + 1,
+        getattr(node, "col_offset", 0),
         getattr(node, "end_lineno", None),
         getattr(node, "end_col_offset", None),
     )
-    rng = _shift_range(rng, line_offset)
+    rng = _shift_range(rng, line_offset, char_offset)
     return SymbolEntry(name=name, kind=kind, range=rng, selection_range=rng)
 
 
+class _ReferenceCollector(ast.NodeVisitor):
+    def __init__(self, target: str, include_stores: bool):
+        super().__init__()
+        self._target = target
+        self._include_stores = include_stores
+        self.ranges: list[types.Range] = []
+
+    def visit_Name(self, node: ast.Name):  # type: ignore[override]
+        if node.id == self._target:
+            if isinstance(node.ctx, ast.Store) and not self._include_stores:
+                return
+            rng = _range_from_positions(
+                getattr(node, "lineno", 1),
+                getattr(node, "col_offset", 0),
+                getattr(node, "end_lineno", None),
+                getattr(node, "end_col_offset", None),
+            )
+            self.ranges.append(rng)
+        self.generic_visit(node)
+
+
+def _references_from_code(
+    code: str,
+    name: str,
+    line_offset: int,
+    char_offset: int,
+    include_stores: bool,
+) -> List[types.Range]:
+    body, offset_adjust = _parse_draconic(code)
+    if not body:
+        return []
+
+    collector = _ReferenceCollector(name, include_stores)
+    for node in body:
+        collector.visit(node)
+
+    local_offset = line_offset + offset_adjust
+    return [_shift_range(rng, local_offset, char_offset) for rng in collector.ranges]
+
+
+def _parse_draconic(code: str) -> tuple[list[ast.AST], int]:
+    parser = draconic.DraconicInterpreter()
+    try:
+        return parser.parse(code), 0
+    except draconic.DraconicSyntaxError:
+        wrapped, added = _wrap_draconic(code)
+        try:
+            return parser.parse(wrapped), -added
+        except draconic.DraconicSyntaxError:
+            return [], 0
+    except Exception as exc:  # pragma: no cover - defensive
+        log.debug("Symbol extraction failed: %s", exc)
+        return [], 0
+
+
 def _range_from_positions(
     lineno: int | None,
     col_offset: int | None,
     end_lineno: int | None,
     end_col_offset: int | None,
 ) -> types.Range:
-    start = types.Position(
-        line=max((lineno or 1) - 1, 0),
-        character=max((col_offset or 1) - 1, 0),
-    )
-    end = types.Position(
-        line=max(((end_lineno or lineno or 1) - 1), 0),
-        character=max(((end_col_offset or col_offset or 1) - 1), 0),
+    start_line = max((lineno or 1) - 1, 0)
+    start_char = max(col_offset or 0, 0)
+    end_line = max(((end_lineno or lineno or 1) - 1), 0)
+    raw_end_char = end_col_offset if end_col_offset is not None else col_offset
+    end_char = max(raw_end_char or start_char, start_char)
+    if end_char <= start_char:
+        end_char = start_char + 1
+    return types.Range(
+        start=types.Position(line=start_line, character=start_char),
+        end=types.Position(line=end_line, character=end_char),
     )
-    return types.Range(start=start, end=end)
 
 
-def _shift_range(rng: types.Range, line_offset: int) -> types.Range:
+def _shift_range(rng: types.Range, line_offset: int, char_offset: int = 0) -> types.Range:
+    start_char = rng.start.character + (char_offset if rng.start.line == 0 else 0)
+    end_char = rng.end.character + (char_offset if rng.end.line == 0 else 0)
     if line_offset == 0:
-        return rng
+        return types.Range(
+            start=types.Position(line=rng.start.line, character=start_char),
+            end=types.Position(line=rng.end.line, character=end_char),
+        )
     return types.Range(
-        start=types.Position(line=max(rng.start.line + line_offset, 0), character=rng.start.character),
-        end=types.Position(line=max(rng.end.line + line_offset, 0), character=rng.end.character),
+        start=types.Position(line=max(rng.start.line + line_offset, 0), character=max(start_char, 0)),
+        end=types.Position(line=max(rng.end.line + line_offset, 0), character=max(end_char, 0)),
     )
 
 
@@ -148,3 +252,15 @@ def _wrap_draconic(code: str) -> tuple[str, int]:
     indented = "\n".join(f"    {line}" for line in code.splitlines())
     wrapped = f"def __alias_main__():\n{indented}\n__alias_main__()"
     return wrapped, 1
+
+
+def _dedupe_ranges(ranges: Iterable[types.Range]) -> List[types.Range]:
+    seen = set()
+    unique: list[types.Range] = []
+    for rng in ranges:
+        key = (rng.start.line, rng.start.character, rng.end.line, rng.end.character)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(rng)
+    return unique

avrae_ls-0.4.1.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: avrae-ls
+Version: 0.4.1
+Summary: Language server for Avrae draconic aliases
+Author: 1drturtle
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygls>=1.3.1
+Requires-Dist: lsprotocol>=2023.0.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: d20>=1.1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# Avrae Draconic Alias Language Server
+
+Language Server Protocol (LSP) implementation targeting Avrae-style draconic aliases. It provides syntax/semantic diagnostics, a mocked execution command, and a thin configuration layer driven by a workspace `.avraels.json` file. Credit to Avrae team for all code yoinked!
+
+## Install (released package)
+
+- CLI/server via `uv tool` (preferred): `uv tool install avrae-ls` then `avrae-ls --help` to see stdio/TCP options (same as `python -m avrae_ls`). The VS Code extension uses this invocation by default. The draconic interpreter is vendored, so no Git deps are needed.
+
+## VS Code extension (released)
+
+- Install from VSIX: download `avrae-ls-client.vsix` from the GitHub releases page, then in VS Code run “Extensions: Install from VSIX” and select the file.
+- Open your alias workspace; commands like `Avrae: Show Alias Preview` and `Avrae: Run Alias` will be available.
+
+## Developing locally
+
+- Prereqs: [uv](https://github.com/astral-sh/uv) and Node.js.
+- Install deps: `uv sync --all-extras` then `make vscode-deps`.
+- Build everything locally: `make package` (wheel + VSIX in `dist/`).
+- Run tests/lint: `make check`.
+- Run via uv tool from source: `uv tool install --from . avrae-ls`.
+- Run diagnostics for a single file (stdout + stderr logs): `avrae-ls --analyze path/to/alias.txt --log-level DEBUG`.
+
+## How to test
+
+- Quick check (ruff + pytest): `make check` (uses `uv run ruff` and `uv run pytest` under the hood).
+- Lint only: `make lint` or `uv run ruff check src tests`.
+- Tests only (with coverage): `make test` or `uv run pytest tests --cov=src`.
+- CLI smoke test without installing: `uv run python -m avrae_ls --analyze path/to/alias.txt`.
+
+## Runtime differences (mock vs. live Avrae)
+
+- Mock execution never writes back to Avrae: cvar/uvar/gvar mutations only live for the current run and reset before the next.
+- Network is limited to gvar fetches (when `enableGvarFetch` is true) and `verify_signature`; other Avrae/Discord calls are replaced with mocked context data from `.avraels.json`.
+- `get_gvar`/`using` values are pulled from local var files first; remote fetches go to `https://api.avrae.io/customizations/gvars/<id>` (or your `avraeService.baseUrl`) using `avraeService.token` and are cached for the session.
+- `signature()` returns a mock string (`mock-signature:<int>`). `verify_signature()` POSTs to `/bot/signature/verify`, respects `verifySignatureTimeout`/`verifySignatureRetries`, reuses the last successful response per signature, and includes `avraeService.token` if present.
+
+## Troubleshooting gvar fetch / verify_signature
+
+- `get_gvar` returns `None` or `using(...)` raises `ModuleNotFoundError`: ensure the workspace `.avraels.json` sets `enableGvarFetch: true`, includes a valid `avraeService.token`, or seed the gvar in a var file referenced by `varFiles`.
+- HTTP 401/403/404 from fetch/verify calls: check the token (401/403) and the gvar/signature id (404). Override `avraeService.baseUrl` if you mirror the API.
+- Slow or flaky calls: tune `verifySignatureTimeout` / `verifySignatureRetries`, or disable remote fetches by flipping `enableGvarFetch` off to rely purely on local vars.
+
+## Other editors (stdio)
+
+- Any client can launch the server with stdio: `avrae-ls --stdio` (flag accepted for client compatibility) or `python -m avrae_ls`. The server will also auto-discover `.avraels.json` in parent folders.
+- Neovim (nvim-lspconfig example):
+  ```lua
+  require("lspconfig").avraels.setup({
+    cmd = { "avrae-ls", "--stdio" },
+    filetypes = { "avrae" },
+    root_dir = require("lspconfig.util").root_pattern(".avraels.json", ".git"),
+  })
+  ```
+- Emacs (lsp-mode snippet):
+  ```elisp
+  (lsp-register-client
+   (make-lsp-client
+    :new-connection (lsp-stdio-connection '("avrae-ls" "--stdio"))
+    :major-modes '(fundamental-mode)  ;; bind to your Avrae alias mode
+    :server-id 'avrae-ls))
+  ```
+- VS Code commands to mirror: `Avrae: Run Alias (Mock)`, `Avrae: Show Alias Preview`, and `Avrae: Reload Workspace Config` run against the same server binary.
+
+## Releasing (maintainers)
+
+1. Bump `pyproject.toml` / `package.json`
+2. Create Github release