Cursorless neovim support

Author: Cedric Halbronn

.github/workflows/deploy.yaml

@@ -40,6 +40,41 @@ jobs:
           registryUrl: https://marketplace.visualstudio.com
           extensionFile: ${{ steps.publishToOpenVSX.outputs.vsixPath }}
 
+  publish-neovim-extension:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    environment: production
+    env:
+      CURSORLESS_REPO_ROOT: ${{ github.workspace }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.CURSORLESS_BOT_TOKEN }}
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm --color install
+      - run: pnpm --color compile
+      - run: pnpm --color --filter '!cursorless-org' --filter '!cursorless-org-*' build
+        env:
+          CURSORLESS_DEPLOY: true
+      - name: Configure GPG Key
+        run: |
+          echo -n "$GPG_SIGNING_KEY" | base64 --decode | gpg --import
+        env:
+          GPG_SIGNING_KEY: ${{ secrets.CURSORLESS_BOT_GPG_SIGNING_KEY }}
+      - name: git config
+        run: |
+          git config user.name cursorless-bot
+          git config user.email [email protected]
+          git config user.signingkey A9387720AFC62221
+          git config commit.gpgsign true
+      - name: Push compiled files to cursorless.nvim plugin repo
+        run: bash -x scripts/deploy-cursorless-nvim.sh
+
   push-cursorless-talon:
     name: Push cursorless-talon subrepo
     runs-on: ubuntu-latest

.github/workflows/pre-commit.yml

@@ -24,6 +24,8 @@ jobs:
           node-version-file: .nvmrc
           cache: pnpm
       - run: pnpm --color install
+      - uses: leafo/gh-actions-lua@v9
+      - uses: leafo/gh-actions-luarocks@v4
       - uses: pre-commit/[email protected]
       - uses: pre-commit-ci/[email protected]
         if: always()

.github/workflows/test.yml

@@ -16,24 +16,25 @@ jobs:
       fail-fast: false
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest]
-        vscode_version: [stable]
+        app_version: [stable]
         include:
           - os: ubuntu-latest
-            vscode_version: legacy
+            app_version: legacy
     runs-on: ${{ matrix.os }}
     env:
-      VSCODE_VERSION: ${{ matrix.vscode_version }}
+      APP_VERSION: ${{ matrix.app_version }}
       VSCODE_CRASH_DIR: ${{ github.workspace }}/artifacts/dumps
       VSCODE_LOGS_DIR: ${{ github.workspace }}/artifacts/logs
       CURSORLESS_REPO_ROOT: ${{ github.workspace }}
+      TEMP_DIR: ${{ github.workspace }}/temp
     steps:
       - uses: actions/checkout@v4
       - run: corepack enable
       - uses: actions/setup-node@v4
         with:
           node-version-file: .nvmrc
           cache: pnpm
-      - run: mkdir -p "${{ env.VSCODE_CRASH_DIR }}" "${{ env.VSCODE_LOGS_DIR }}"
+      - run: mkdir -p "${{ env.VSCODE_CRASH_DIR }}" "${{ env.VSCODE_LOGS_DIR }}" "${{ env.TEMP_DIR }}"
         shell: bash
       - run: pnpm --color install
       - run: pnpm --color compile
@@ -42,9 +43,21 @@ jobs:
         if: runner.os == 'Linux'
       - run: pnpm --color test
         if: runner.os != 'Linux'
+      - run: bash -x scripts/install-neovim-dependencies.sh
+      - uses: rhysd/action-setup-vim@v1
+        if: matrix.app_version != 'legacy'
+        id: vim
+        with:
+          version: ${{ matrix.app_version }}
+          neovim: true
+      - name: Run neovim unit tests using test-harness
+        run: xvfb-run -a pnpm -F @cursorless/test-harness testNeovim
+        if: runner.os == 'Linux' && matrix.app_version == 'stable'
+        env:
+          NEOVIM_PATH: ${{ steps.vim.outputs.executable }}
       - name: Create vscode dist that can be installed locally
         run: pnpm -F @cursorless/cursorless-vscode populate-dist --local-install
-        if: runner.os == 'Linux' && matrix.vscode_version == 'stable'
+        if: runner.os == 'Linux' && matrix.app_version == 'stable'
       - name: Test create vsix
         id: createVsix
         uses: HaaLeo/publish-vscode-extension@v1
@@ -53,10 +66,10 @@ jobs:
           packagePath: packages/cursorless-vscode/dist
           dryRun: true
       - run: mv ${{ steps.createVsix.outputs.vsixPath }} cursorless-development.vsix
-        if: runner.os == 'Linux' && matrix.vscode_version == 'stable'
+        if: runner.os == 'Linux' && matrix.app_version == 'stable'
       - name: Upload vsix
         uses: actions/upload-artifact@v4
-        if: runner.os == 'Linux' && matrix.vscode_version == 'stable'
+        if: runner.os == 'Linux' && matrix.app_version == 'stable'
         with:
           name: vsix
           path: cursorless-development.vsix

.gitignore

@@ -5,6 +5,7 @@ node_modules
 *.vsix
 /package-lock.json
 *.DS_Store
+.luacheckcache
 
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 

.luacheckrc

@@ -0,0 +1,8 @@
+std = luajit
+cache = true
+codes = true
+ignore = { "432" }
+
+globals = {
+    "vim",
+}

.pre-commit-config.yaml

@@ -81,3 +81,13 @@ repos:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
+  - repo: https://github.com/lunarmodules/luacheck
+    rev: v1.2.0
+    hooks:
+      - id: luacheck
+        exclude: ^data/playground/lua/.*\.lua$
+  - repo: https://github.com/JohnnyMorganz/StyLua
+    rev: v0.20.0
+    hooks:
+      - id: stylua
+        exclude: ^data/playground/lua/.*\.lua$

.vscode/extensions.json

@@ -7,7 +7,9 @@
     "dbaeumer.vscode-eslint",
     "esbenp.prettier-vscode",
     "jrieken.vscode-tree-sitter-query",
-    "wenkokke.tree-sitter-talon",
-    "usernamehw.commands"
+    "wenkokke.talonfmt-vscode",
+    "usernamehw.commands",
+    "sumneko.lua",
+    "JohnnyMorganz.stylua"
   ]
 }

.vscode/launch.json

@@ -5,6 +5,22 @@
 {
   "version": "0.2.0",
   "configurations": [
+    {
+      "name": "Run neovim extension",
+      "request": "attach",
+      "continueOnAttach": true,
+      "skipFiles": ["<node_internals>/**"],
+      "preLaunchTask": "Build neovim extension",
+      "type": "node"
+    },
+    {
+      "name": "Neovim extension tests",
+      "request": "attach",
+      "continueOnAttach": true,
+      "skipFiles": ["<node_internals>/**"],
+      "preLaunchTask": "Build neovim extension tests",
+      "type": "node"
+    },
     {
       "name": "Run extension",
       "type": "extensionHost",

.vscode/settings.json

@@ -7,7 +7,7 @@
     "editor.defaultFormatter": "AndreasArvidsson.andreas-talon"
   },
   "[talon]": {
-    "editor.defaultFormatter": "wenkokke.tree-sitter-talon"
+    "editor.defaultFormatter": "wenkokke.talonfmt-vscode"
   },
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
@@ -25,5 +25,10 @@
   "files.eol": "\n",
   "typescript.enablePromptUseWorkspaceTsdk": true,
   "typescript.tsdk": "node_modules/typescript/lib",
-  "eslint.workingDirectories": [{ "pattern": "packages/*/" }]
+  "eslint.workingDirectories": [{ "pattern": "packages/*/" }],
+  "Lua.runtime.version": "Lua 5.1",
+  "Lua.diagnostics.globals": ["vim", "talon"],
+  "[lua]": {
+    "editor.defaultFormatter": "JohnnyMorganz.stylua"
+  }
 }

.vscode/tasks.json

@@ -16,6 +16,86 @@
         "isDefault": true
       }
     },
+    {
+      "label": "Build neovim extension",
+      "dependsOn": ["neovim start", "ESBuild-cursorless-neovim"],
+      "group": "build"
+    },
+    {
+      "label": "Build neovim extension tests",
+      "dependsOn": [
+        "neovim test start",
+        "ESBuild-cursorless-neovim",
+        "TSBuild",
+        "Build test harness"
+      ],
+      "group": "build"
+    },
+    {
+      "label": "ESBuild-cursorless-neovim",
+      "type": "npm",
+      "script": "compile",
+      "path": "packages/cursorless-neovim",
+      "dependsOn": [],
+      "presentation": {
+        "reveal": "silent"
+      },
+      "group": "build"
+    },
+    {
+      "label": "neovim start",
+      "type": "process",
+      "windows": {
+        "command": "powershell",
+        "args": [
+          "(New-Object -ComObject WScript.Shell).Run(\"\"\"nvim\"\"\", 1, $false)"
+        ]
+      },
+      "osx": {
+        "command": "osascript",
+        "args": [
+          "-e",
+          "tell app \"Terminal\" to do script \"${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.sh ${workspaceFolder} development\""
+        ]
+      },
+      "group": "build",
+      "options": {
+        "env": {
+          "CURSORLESS_REPO_ROOT": "${workspaceFolder}",
+          "NVIM_NODE_HOST_DEBUG": "1",
+          "NVIM_NODE_LOG_FILE": "${workspaceFolder}/packages/cursorless-neovim/out/nvim_node.log",
+          "NVIM_NODE_LOG_LEVEL": "info",
+          "CURSORLESS_MODE": "development"
+        }
+      }
+    },
+    {
+      "label": "neovim test start",
+      "type": "process",
+      "windows": {
+        "command": "powershell",
+        "args": [
+          "(New-Object -ComObject WScript.Shell).Run(\"\"\"nvim\"\"\", 1, $false)"
+        ]
+      },
+      "osx": {
+        "command": "osascript",
+        "args": [
+          "-e",
+          "tell app \"Terminal\" to do script \"${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.sh ${workspaceFolder} test\""
+        ]
+      },
+      "group": "build",
+      "options": {
+        "env": {
+          "CURSORLESS_REPO_ROOT": "${workspaceFolder}",
+          "NVIM_NODE_HOST_DEBUG": "1",
+          "NVIM_NODE_LOG_FILE": "${workspaceFolder}/packages/cursorless-neovim/out/nvim_node.log",
+          "NVIM_NODE_LOG_LEVEL": "info",
+          "CURSORLESS_MODE": "test"
+        }
+      }
+    },
     {
       "label": "Build extension only",
       "dependsOn": ["Populate dist", "ESBuild"],

cursorless.nvim/README.md

@@ -0,0 +1,105 @@
+<!-- vim-markdown-toc GFM -->
+
+- [cursorless.nvim](#cursorlessnvim)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+  - [Frequently asked questions](#frequently-asked-questions)
+  - [Contributors](#contributors)
+
+<!-- vim-markdown-toc -->
+
+# cursorless.nvim
+
+Neovim plugin to support Cursorless
+
+## Prerequisites
+
+- [neovim](https://neovim.io/.) Tested with neovim version `v0.10.0` and above, but it may work with earlier versions.
+- [Talon voice](https://talonvoice.com/)
+- [neovim-talon](https://github.com/hands-free-vim/neovim-talon)
+- [node/npm](https://nodejs.org/en)
+- [neovim node package](https://github.com/neovim/node-client) (>= 5.1.0 installed globally)
+- [talon.nvim](https://github.com/hands-free-vim/talon.nvim) (likely required, unless standalone neovim
+  GUI (nvim-qt.exe, neovide, etc)
+
+## Installation
+
+### 1. Install Cursorless neovim plugin
+
+Ideally, you want to use a neovim plugin manager like [lazy.nvim](https://github.com/folke/lazy.nvim).
+
+#### Option A: Lazy installation
+
+After the typical [lazy setup](https://github.com/folke/lazy.nvim?tab=readme-ov-file#-installation), you'll have to add the `cursorless.nvim` plugin to your `init.lua`.
+
+```lua
+require('lazy').setup({
+  'hands-free-vim/cursorless.nvim',
+})
+```
+
+#### Option B: Manual installation
+
+This method is not recommended but you can try directly cloning the plugin into your nvim data folder:
+
+```
+git clone https://github.com/hands-free-vim/cursorless.nvim
+```
+
+### 2. Tell neovim to run the plugin
+
+If you aren't using a plugin manager that automatically calls setup for you (e.g. it is needed for lazy), you will need this somewhere in your neovim config, e.g. in [init.lua](https://neovim.io/doc/user/lua-guide.html#lua-guide-config):
+
+```lua
+require("cursorless").setup()
+```
+
+### 3. Activate Cursorless commands in Talon
+
+Add a `.talon` file like the following anywhere in your Talon user directory (e.g. named `cursorless_neovim.talon`):
+
+```talon
+app: neovim
+-
+tag(): user.cursorless
+```
+
+## Configuration
+
+### Keyboard shortcut
+
+By default the keyboard shortcut used to communicate with cursorless is `<C-S-f12>`, but this might not work for
+everybody and is configurable. You can change it by passing a different value in the configuration options passed to
+`setup()`:
+
+```lua
+require("cursorless").setup({ shortcut = `<C-Q>`})
+```
+
+_IMPORTANT_: If you change this shortcut, be sure to set the corresponding neovim-talon setting. This can be done by
+having a `.talon` file somewhere in your talon user directory that contains the following:
+
+```talon
+settings():
+    user.neovim_command_server_shortcut = "ctrl-q"
+```
+
+### Absolute row numbers
+
+You MUST currently use absolute row numbers in order to target rows using cursorless. The `talon.nvim` plugin will
+configure this automatically, but your own config may be overriding it. Be sure to disable relative numbers.
+
+## Frequently asked questions
+
+### nvim does not support Lazy?
+
+Some Linux package managers ship with a version of `nvim` too old for Lazy. If this is the case, [install nvim](https://github.com/neovim/neovim/blob/master/INSTALL.md) via another method.
+
+### nvim does not find the `neovim` globally installed package?
+
+If you are on Linux, avoid using the snap package for `npm` as it may not be able to globally expose the neovim npm package due to sandboxing. If this is the case, install node via another method (nvm, brew, etc).
+
+## Contributors
+
+Welcome! So glad you've decided to help make Cursorless in Neovim better. You'll want to start by getting [set up](https://github.com/saidelike/cursorless/blob/nvim-talon/docs/contributing/cursorless-in-neovim.md). You may also find the [Neovim API docs](https://neovim.io/doc/user/api.html) helpful to learn about Neovim extension development.