Skip to content
GBLMXPublic

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,013 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Anvil desktop icon

Anvil

Anvil is a Linux-first terminal editor. The project targets a reusable Rust kernel, a per-session Go policy gateway, and a capability-scoped plugin host. The official standard edition is one composition; third-party distributions can compose the kernel with their own UI and trusted Rust code. Runtime plugins remain untrusted and sandboxed.

Status: 0.6.0 remains the frozen workspace/release version while the 0.7.x optional-module line is developed in-tree; no public release or tag during this phase. See internal polish plan and the 0.7.x module plan. Development uses Rust from rust-toolchain.toml and Go 1.26.11 or newer; CI installs the exact Go version from the root go.mod. The ratatui editor now includes insert mode (i/a/A/o/O), multi-cursor selection (s/S/C/Alt-C), :w/:wa/:wq/:w file/:q!, an unsaved-change guard, undo/redo, x/dd/yy/p, w/b/e word motions with dw/db/de/yw/yb/ye, G to the last line, line joining (J), indent/outdent (>/<), literal :s/:%s substitution, / search with n/N, multi-buffer switching, vertical splits with independent pane cursors, read-only :git-diff views with hunk staging, :git-blame, conflict listing, base/ours/theirs previews, and whole-file :git-resolve-ours / :git-resolve-theirs resolution (with ! to discard a modified buffer), workspace session restore, dirty-buffer swap conflict commands, and a fresh undo stack after restore, horizontal scrolling, and dirty-only redraws, insert-mode Tab indentation, a workspace file tree, and a fuzzy file finder. Rust, TOML, Go, Bash/Zsh/Brush, Fish, Python, YAML, JSON/JSONC, HTML (.html, .htm), Markdown, Makefile, Dockerfile, and LaTeX (.tex, .ltx, .sty, .cls) use Tree-sitter highlighting on a debounced background thread, capped at 256 KiB so large files keep plain-text latency. Trusted language servers (rust-analyzer, gopls, pyright/pylsp, typescript-language-server/vtsls, clangd, jdtls, lua-language-server, vscode-json-language-server, yaml-language-server, bash-language-server, marksman, taplo, vscode-html-language-server, vscode-css-language-server, zls, texlab) run without the plugin sandbox; diagnostics, completion with resolved documentation and snippets (Ctrl+Space), definition (gd), references (gr), document highlights (gh), incoming/outgoing calls (gi/go), folding ranges (za/zM/zR), code lens, semantic token colors, hover (K), rename (Space r), code actions/quick fixes (Space a), formatting (Space F), document symbols (Space s), signature help, and workspace symbols (Space S) use canonicalized LSP UTF-16 positions. Rename, code-action, and formatting edits go through a shared WorkspaceEdit engine that checks document versions and request-time buffer revisions, applies documentChanges create/rename/delete operations, keeps unopened files as background buffers, and does not write files during an edit; :wa saves every modified buffer. Supported files start their language server automatically. Each trusted workspace root owns a separate (tool, language_id) worker and LSP connection; the project root is the server's working directory. The client answers workspace/workspaceFolders and workspace/configuration, and sends workspace/didChangeConfiguration after :config-reload. Language servers are not bundled; install them on PATH.

  • TypeScript prefers a project-local compiler (npm install -D typescript). Without one, the global tsc installation is used; override the compiler path with ANVIL_TSSERVER=/path/to/tsserver.js.
  • C/C++ support works best with a compilation database: bear -- make, or configure CMake with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON. Without it, clangd may report unresolved includes.

Built-in semantic themes are anvil-dark, tokyonight, omp-kde, helix-base16, one-dark, gruvbox-dark, nord, catppuccin-mocha, and solarized-light. The boxpigma family adds boxpigma, dracula, gruvbox, solarized, tokyo-night, catppuccin, monokai, rose-pine, kanagawa, github-light, gruvbox-light, one-light, catppuccin-latte, cyberpunk-volt, cyberpunk-fury, and cyberpunk-hot. Use :theme to list them. :theme <name> and :theme-auto [dark] [light] switch and persist to $XDG_CONFIG_HOME/anvil/settings.toml (override with ANVIL_SETTINGS); :theme-save re-saves the runtime choice explicitly. ANVIL_THEME selects the startup theme. The command palette (Space p) lists themes and previews them while arrowing.

The same file owns theme and typed editor/search/LSP settings:

[theme]
mode = "fixed"
name = "anvil-dark"

[editor]
scroll_margin = 3
max_buffers = 9
auto_save = false
file_watching = true
sidebar_percent = 20

[search]
case_sensitive = false

[lsp]
inlay_hints = true

[lsp.commands]
# Optional command override; the first argv element is the executable.
json = ["node", "/path/to/vscode-json-language-server", "--stdio"]

[watch]
mode = "auto"        # auto | native | poll | off
max_dirs = 8192
cross_mounts = false

[watch] controls the Linux native watcher. auto starts native and keeps polling as fallback; native requests native coverage; poll disables the native watcher; off disables workspace observation. editor.file_watching remains the on/off compatibility switch.

[lsp.commands] is keyed by language id. A value may be a command string or an argv array; array arguments are passed unchanged.

User settings may also override one launch profile per workspace root:

[lsp.roots."/home/me/src/project".rust]
command = "/opt/rust-analyzer"
args = ["--log-file", "/tmp/ra.log"]
root_markers = ["Cargo.toml", "rust-toolchain.toml"]
env = { RA_LOG = "info" }
settings = { check = { command = "clippy" } }

[lsp.roots] is keyed by the canonical workspace-root path and then by language id. command, args, and root_markers override the built-in launch profile; env extends the server environment; settings becomes the value returned for workspace/configuration requests. Root profiles are read from user settings, not project settings.

A trusted workspace may add .anvil.toml. Its theme, editor, search, ui, and lsp.inlay_hints values merge over the user file for that workspace. Project settings are read-only and cannot set [lsp.commands]; that table is rejected because it would let a repository select an executable. [lsp.roots] is only honored from user settings. An explicit ANVIL_SETTINGS file remains a complete override and disables the project layer. An explicit ANVIL_SETTINGS file remains a complete override and disables the project layer.

ANVIL_EDITOR_SCROLL_MARGIN, ANVIL_EDITOR_MAX_BUFFERS, ANVIL_EDITOR_AUTO_SAVE, ANVIL_EDITOR_FILE_WATCHING, ANVIL_EDITOR_SIDEBAR_PERCENT, ANVIL_SEARCH_CASE_SENSITIVE, and ANVIL_LSP_INLAY_HINTS override the file for the current process. :settings opens the minimal overlay: j/k select, h/l or Enter adjust, r resets the row, s saves, and Esc cancels. The Appearance section includes the active theme row. Each row shows its effective source (default, environment, user, or trusted project file), including ignored project files and the reason. :config-reload reports the files that actually loaded. See settings sources; typed settings are not currently overridden by CLI flags. Auto-save is off by default; when enabled it writes the active named buffer on buffer switch/close, split focus/close changes, opening another file, focus loss, and :q. Insert/search/rename input modes are eligible; only confirmation prompts and modal overlays are excluded. External edits are watched through the gateway in bounded watch sets: open buffers, the visible tree, and (when the distribution provides Git) .git/HEAD/.git/index. Clean buffers reload, dirty buffers prompt with y/N, tree changes refresh Git status, and external deletion closes the LSP document and marks the buffer missing. :config-reload applies settings, keymap, and theme changes without restarting and reports the effective settings paths. Set [editor] file_watching = false or ANVIL_EDITOR_FILE_WATCHING=0 to disable polling; the tree then relies on explicit refresh and buffer opens.

:watch-status reports the active scope, root count, tree-watch cap, and stale state. :tree-refresh performs a manual tree and Git status refresh; the watcher is not a recursive whole-workspace scanner.

At the : prompt, Tab completes Ex command names, :theme / :theme-auto arguments, and :plugin-enable IDs; Up/Down selects a candidate and Enter accepts it. Esc closes the completion list first.

The plugin-host path has a sandboxed host with token-FD delivery, close_range, no_new_privs, Landlock read/no-exec rules, native-ABI seccomp with a preconnected editor socket, a plugin-id/token handshake on that socket, and dangerous-syscall denial, cgroup-before-exec v2 limits with OOM classification, sys.ping/sys.exec dispatch, and a TUI debug PluginSession (:plugin-start/:plugin-exec/:plugin-stop/:plugin-oom). Official release layouts install plugin sources under share/anvil/official/plugins and, when signed, packages under share/anvil/packages. install.sh copies them and runs anvil-gateway -install-bundled; managed packages take precedence over the bundled fallback and support enable/disable, uninstall, and rollback. :pkg install <url> downloads a signed package through the gateway, shows its declared capabilities, and installs only the reviewed SHA-256 digest. Downloads require -allow-fetch and an explicit -fetch-allow host. :pkg install-file <package> <signature> <public-key> reviews and installs a local signed package without network access. For development, point ANVIL_PLUGIN_DIR at plugins/official, open the command palette (Space p), and run Trim Trailing Whitespace. onLanguage and onWorkspaceContains events start matching sandboxed hosts with no grants. onStartup requires explicit opt-in via ANVIL_PLUGIN_ALLOW_STARTUP=1; workspace activation is disabled with ANVIL_PLUGIN_DISABLE_WORKSPACE_ACTIVATION=1. Manifest-declared onCommand entries and dynamic editor.register_command commands are dispatched from the command palette. Plugins can also call ui.notify and ui.status. The optional LANDLOCK_SCOPE_SIGNAL layer is pending. This is not a VM or public plugin API.

Distribution and modules

anvil-distro-standard owns the process entrypoint; anvil-distro-minimal is the independent second consumer. Official modules are trusted source-level Rust crates compiled into the binary. There is no dynamic Rust ABI, runtime module loading, or marketplace-installed Rust module. Module contract v1 is frozen; the 0.7.1-0.7.3 module, workspace-index, and compatibility-gate slices and the 0.7.4 desktop, LaTeX, and Typst slices are complete.

The full Cargo feature enables every official module at runtime; building with --all-features selects it. The default anvil binary remains the standard Git-only composition unless full is selected.

  • official.git is part of the default standard composition. :git-* dispatch and completion are gated off when the Git service is absent.
  • official.workspace-index is opt-in through the official-workspace-index feature. When a distribution installs it, quick-open prefers its bounded index and cancels in-flight builds when the picker closes. Without it, quick-open falls back to gateway enumeration.
  • official.desktop is opt-in through official-desktop. It enables :open-url <http(s)-url> with a fixed xdg-open handoff and no general command runner.
  • official.language-latex is opt-in through official-language-latex. It supplies texlab profiles for LaTeX and BibTeX; .tex, .ltx, .sty, and .cls get Tree-sitter highlighting through the latex syntax feature.
  • official.language-typst is opt-in through official-language-typst. It supplies a tinymist profile for Typst; .typ files get Tree-sitter highlighting through the typst syntax feature.
  • anvil-distro-minimal composes none of these modules.

Module compatibility, caps, and deprecation rules are in module compatibility.

Phase 0 still consists of the anvil-api contracts, anvil-core PieceTable, anvil-editor snapshots, anvil-ipc framing/JSON-RPC/Unix transport, and the Go gateway with openat2, Landlock/seccomp exec sandboxing, SSRF-constrained fetch, and a synchronous Rust gateway client. The TUI discovers the gateway beside the binary or via ANVIL_GATEWAY.

Set ANVIL_SKIP_TERMINAL_QUERY=1 for CI or synthetic PTYs; it bypasses crossterm's keyboard-enhancement query and the OSC 11 background query.

Usage

anvil [OPTIONS] [FILE|-]
  anvil doctor [--json] [--profile auto|dev|installed]
  anvil modules [--json]

  -w, --workspace <DIR>  Workspace directory; --workspace=DIR is also accepted
  --editor              External-editor mode; allows one explicit file outside
                        the cwd by using its parent as the default workspace
  --read-only           Reject mutating commands
  -h, --help             Show help and exit
  -V, --version          Show the version and exit
  --                     Treat the next argument as FILE

anvil doctor checks the gateway and companion binaries, locale, truecolor, SSH/tmux color forwarding, runtime/config paths, Landlock, and supported language servers. --profile defaults to auto (installed layout vs cargo target); dev target sidecars are warnings, installed-layout sidecars are errors. --json emits schema version 1 with stable check ids and remediation; required failures exit nonzero. See doctor checks.

anvil modules lists the compiled-in modules in the running distribution with their contract range, command count, and compiled-in source. --json emits schema version 1 with stable module ids, enabled state, feature name, contract, and source. It is read-only and does not contact a marketplace. Only modules compiled into the binary appear: a default build lists official.git, while a full build also lists workspace index, desktop, LaTeX, and Typst. Runtime plugins are separate: :plugin-inventory is the read-only installed plugin view, while :plugin-list opens the mutable manager.

FILE must be inside the selected workspace. --editor is intended for $EDITOR-style invocations; :cq exits 1 and a failed save keeps the final exit status nonzero. anvil -, or any non-terminal stdin such as git diff | anvil, creates a [stdin] buffer and reattaches keyboard input to /dev/tty; combine with --read-only for logs. Use -- before a file name that starts with a dash. Launching without FILE shows the start dashboard; the first key dismisses it.

Stdin text containing path:line:column: message, --> path:line:column, or path(line,column): message shows a bounded Locations panel. Alt-j / Alt-k selects a row and Enter opens it; locations outside the workspace are rejected.

Control

anvil-ctl controls the running instance for one workspace. Each workspace gets its own socket under $XDG_RUNTIME_DIR/anvil/; --workspace selects it and defaults to the current directory. anvil-mcp uses ANVIL_WORKSPACE or its own cwd.

anvil-ctl status
anvil-ctl --workspace /path/to/project status
anvil-ctl --json open src/main.rs +12:3
anvil-ctl --json edit set $'alpha\nbeta\n'
printf 'alpha\nbeta\n' | anvil-ctl --json edit set --stdin
anvil-ctl --json query 1:200
anvil-ctl --json command ':git-diff'
anvil-ctl --json quit --force

--json emits one machine-readable object; failures include ok: false, exit_code, kind, message, and rpc_code. Exit codes: 0 success, 2 usage, 3 no instance, 4 timeout, 5 editor RPC error. open, save, edit, query, command, and quit all pass through the control socket into the TUI actor; they do not edit files directly. query reports buffer text, cursor, selection, revision, undo depth/bytes, tabs, and active buffer, and accepts a bounded START[:END] line range. command executes allowlisted Ex commands through the same editor state machine; admin commands such as :pkg and :plugin-* are denied on the remote surface.

The control protocol is version 3 (protocol_version and capabilities are returned by status). open is workspace-relative. --spawn starts Anvil only when a terminal is attached. --editor and stdin instances do not claim the control socket, so they can run alongside a normal interactive instance. scripts/ctl-smoke.sh drives a real TUI through this CLI and asserts files, buffer state, undo, Git index state, and session output.

scripts/lsp-real-smoke.sh switches a real TUI across C, Java, Rust, and Go and asserts one active language server. It exits 0 with SKIP when clangd, jdtls, rust-analyzer, or gopls is absent; CI does not require them.

anvil-mcp is a thin stdio MCP adapter over anvil-control. It exposes anvil_status, anvil_open, anvil_query, anvil_edit, anvil_save, anvil_command, and anvil_quit; it never reads or writes workspace files directly. scripts/mcp-smoke.sh starts the adapter against a real TUI.

Quick open: Space f filters workspace files and previews the selected file through the gateway. Wide terminals show the preview beside the list; narrow terminals stack it below. Space b filters the open buffers; Enter switches to the selected buffer.

Documents

Current decisions

  • Plugins are untrusted by default and run in a separate plugin-host process, never in the editor process.

  • The Rust v1 stack uses ratatui + crossterm directly, with no Tokio or Ferriso runtime dependency. Ferriso is reference material.

  • Lua plugins use mlua with Luau; TS uses rquickjs (QuickJS-NG), not V8.

  • The Go gateway is a per-session policy gateway, not the plugin sandbox. One gateway process owns one session socket; closing the server removes the socket.

  • sys.exec routes through anvil-exec-runner. The Phase 0.6 gateway uses a one-shot 32-byte bootstrap token: the gateway holds only its SHA-256 verifier, the raw token appears only in session.hello, and a second handshake is rejected. SO_PEERCRED UID plus the token are both required. -allow-exec is currently per gateway instance; per-session permission negotiation remains open.

  • The public API starts small and is defined from Rust types plus generated JSON Schema and TypeScript/Lua stubs. Smithy is deferred until the API justifies its code-generation cost.

  • The text model is PieceTable, exposed as anvil-core::TextDocument; Rope and Gap Buffer remain benchmark-only. See ADR-0009.

  • Syntax highlighting is derived state, not stored in PieceTable. Parsing runs on a background worker after a 50 ms debounce; stale spans remain visible until the replacement arrives. Files over 256 KiB are intentionally plain text.

  • The plugin host is a real process/sandbox boundary. cgroup v2 limits are applied before execve; a missing delegated cgroup2 root fails closed rather than running without the promised limits.

  • Official Rust modules are source-level, feature-gated, and registered through a typed ModuleRegistry; contract v1 is frozen. Modules receive no ambient plugin capability, cannot shadow kernel commands, and may not depend on anvil-tui internals. See module contract.

  • The native editor/API interaction model is selection-first. The current TUI exposes that core through a Vim-like keymap implemented in Rust. Normal, operator-pending, and editor/global context bindings can be remapped through keymap.toml, and bundled ergo and Vim presets can be selected as a base. Lua/TS keymap plugins are not implemented yet.

  • Full untrusted-plugin support targets Linux 5.13+ (Landlock). Linux 5.6-5.12 may run the editor with trusted plugins only.

License

Licensed under either of Apache-2.0 or MIT, at your option. See LICENSE-APACHE and LICENSE-MIT.

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages