avrae-ls 0.3.1__tar.gz → 0.4.1__tar.gz

avrae_ls-0.4.1/PKG-INFO

@@ -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

avrae_ls-0.4.1/README.md

@@ -0,0 +1,67 @@
+# 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

{avrae_ls-0.3.1 → avrae_ls-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "avrae-ls"
-version = "0.3.1"
+version = "0.4.1"
 description = "Language server for Avrae draconic aliases"
 authors = [
   { name = "1drturtle" }

{avrae_ls-0.3.1 → avrae_ls-0.4.1}/src/avrae_ls/alias_preview.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import re
 import shlex
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass, field
 from typing import Any, Optional, Tuple
 
 from .parser import DRACONIC_RE
@@ -19,6 +19,45 @@ class RenderedAlias:
     last_value: Any | None = None
 
 
+@dataclass
+class EmbedFieldPreview:
+    name: str
+    value: str
+    inline: bool = False
+
+
+@dataclass
+class EmbedPreview:
+    title: str | None = None
+    description: str | None = None
+    footer: str | None = None
+    thumbnail: str | None = None
+    image: str | None = None
+    color: str | None = None
+    timeout: int | None = None
+    fields: list[EmbedFieldPreview] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "description": self.description,
+            "footer": self.footer,
+            "thumbnail": self.thumbnail,
+            "image": self.image,
+            "color": self.color,
+            "timeout": self.timeout,
+            "fields": [asdict(f) for f in self.fields],
+        }
+
+
+@dataclass
+class SimulatedCommand:
+    preview: str | None
+    command_name: str | None
+    validation_error: str | None
+    embed: EmbedPreview | None = None
+
+
 def _strip_alias_header(text: str) -> str:
     lines = text.splitlines()
     if lines and lines[0].lstrip().startswith("!alias"):
@@ -82,6 +121,58 @@ def validate_embed_payload(payload: str) -> Tuple[bool, str | None]:
     return _validate_embed_flags(text)
 
 
+def parse_embed_payload(payload: str) -> EmbedPreview:
+    """Parse an embed payload into a structured preview object."""
+    tokens = shlex.split(payload.strip())
+    preview = EmbedPreview()
+
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+        if not tok.startswith("-"):
+            i += 1
+            continue
+        key = tok.lower()
+        next_val = tokens[i + 1] if i + 1 < len(tokens) else None
+        if key == "-title":
+            preview.title = next_val or ""
+            i += 2
+            continue
+        if key == "-desc":
+            preview.description = next_val or ""
+            i += 2
+            continue
+        if key == "-footer":
+            preview.footer = next_val or ""
+            i += 2
+            continue
+        if key == "-thumb":
+            preview.thumbnail = next_val or ""
+            i += 2
+            continue
+        if key == "-image":
+            preview.image = next_val or ""
+            i += 2
+            continue
+        if key == "-color":
+            preview.color = _normalize_color(next_val)
+            i += 2 if next_val is not None else 1
+            continue
+        if key == "-t":
+            preview.timeout = _parse_timeout(next_val)
+            i += 2
+            continue
+        if key == "-f":
+            field = _parse_field_value(next_val)
+            if field:
+                preview.fields.append(field)
+            i += 2
+            continue
+        i += 1
+
+    return preview
+
+
 def _validate_embed_flags(text: str) -> Tuple[bool, str | None]:
     """Validate embed flags according to Avrae's help text."""
     if not text:
@@ -164,17 +255,92 @@ def _validate_timeout_arg(value: str | None) -> Tuple[bool, str | None, int]:
     return True, None, consumed
 
 
-def simulate_command(command: str) -> tuple[str | None, str | None, str | None]:
+def _parse_timeout(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _normalize_color(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if not value:
+        return None
+    match = re.match(r"^(?:#|0x)?([0-9a-fA-F]{6})$", value)
+    if not match:
+        return value
+    return f"#{match.group(1)}"
+
+
+def _parse_field_value(value: str | None) -> EmbedFieldPreview | None:
+    if value is None:
+        return None
+    parts = value.split("|")
+    if len(parts) < 2:
+        return None
+    inline_flag = parts[2].lower() == "inline" if len(parts) == 3 else False
+    return EmbedFieldPreview(name=parts[0], value=parts[1], inline=inline_flag)
+
+
+def simulate_command(command: str) -> SimulatedCommand:
     """Very small shim to preview common commands."""
-    text = command.strip()
+    text = _strip_alias_header(command).strip()
     if not text:
-        return None, None, None
-    head, *rest = text.split(maxsplit=1)
-    payload = rest[0] if rest else ""
+        return SimulatedCommand(None, None, None, None)
+    head, payload = _extract_command_head_and_payload(text)
+    if not head:
+        return SimulatedCommand(None, None, None, None)
     lowered = head.lower()
     if lowered == "echo":
-        return payload, "echo", None
+        return SimulatedCommand(payload, "echo", None, None)
     if lowered == "embed":
         valid, error = validate_embed_payload(payload)
-        return payload, "embed", error
-    return None, head, None
+        embed_preview = parse_embed_payload(payload) if valid else None
+        return SimulatedCommand(payload, "embed", error, embed_preview)
+    if head.startswith("-") and _is_embed_flag(head):
+        payload = text
+        valid, error = validate_embed_payload(payload)
+        embed_preview = parse_embed_payload(payload) if valid else None
+        return SimulatedCommand(payload, "embed", error, embed_preview)
+    return SimulatedCommand(None, head, None, None)
+
+
+def _extract_command_head_and_payload(text: str) -> tuple[str | None, str]:
+    """Prefer the first non-empty line; fall back to any embed line later."""
+    lines = [ln.strip() for ln in text.splitlines() if ln.strip()]
+    if not lines:
+        return None, ""
+    head, payload = _split_head_and_payload_from_line(lines[0])
+    if _is_embed_flag(head):
+        # Treat the entire payload (including the head line) as embed flags so multiple lines are preserved.
+        return head, "\n".join(lines)
+    if head and head.lower() in ("embed", "echo"):
+        return head, _merge_payload(payload, lines[1:])
+    for idx, line in enumerate(lines[1:], start=1):
+        possible_head, possible_payload = _split_head_and_payload_from_line(line)
+        if possible_head and (possible_head.lower() == "embed" or _is_embed_flag(possible_head)):
+            return possible_head, _merge_payload(possible_payload, lines[idx + 1 :])
+    return head, _merge_payload(payload, lines[1:])
+
+
+def _split_head_and_payload_from_line(line: str) -> tuple[str | None, str]:
+    if not line:
+        return None, ""
+    parts = line.split(maxsplit=1)
+    head = parts[0]
+    payload = parts[1] if len(parts) > 1 else ""
+    return head, payload
+
+
+def _merge_payload(first_payload: str, trailing_lines: list[str]) -> str:
+    payload = first_payload
+    if trailing_lines:
+        payload = (payload + "\n" if payload else "") + "\n".join(trailing_lines)
+    return payload
+
+
+def _is_embed_flag(flag: str) -> bool:
+    return flag.lower() in {"-title", "-desc", "-thumb", "-image", "-footer", "-f", "-color", "-t"}