test(keymaps): headless Neovim harness for buffer-local bindings + CI

`scripts/test-keymaps.sh` boots `nvim --headless` against a scratch
wiki, sources `scripts/test-keymaps.lua`, and asserts the post-state
of each buffer-local mapping registered by `ftplugin/vimwiki.vim` +
`lua/nuwiki/keymaps.lua`.

The harness covers the bindings that actually have observable effects
on the buffer or cursor:

- **Lists** (LSP round-trip): `<C-Space>` / `<C-@>` / `<Nul>` toggle,
  `gln` cycle, `glx` reject, plus a `[X]→[ ]` round-trip.
- **Tasks**: `gnt` jumps to the next unfinished `[ ]`.
- **Headings** (LSP round-trip): `=` adds a level, `-` removes one,
  `=` on h6 clamps without growing.
- **Header nav** (pure Lua): `]]` next, `[[` prev, `]u` parent.
- **Link nav** (pure Lua): `<Tab>` to the next `[[…]]`.
- **`<CR>` two-step**: first press wraps a bare word as `[[word]]`
  and stops (matches vimwiki's review-then-follow).
- **Bullet continuation**: `o` / `O` keep the marker, and `o` on a
  `[ ]` line carries the checkbox forward.

Each case sets buffer lines, places the cursor (1-based), fires
`nvim_feedkeys` with `replace_termcodes`, waits long enough for the
LSP `executeCommand` round-trip (800 ms by default; 100 ms for the
pure-client maps), and asserts either the resulting lines, a specific
line, the cursor's new line, or the buffer's new name.

Output goes via `$NUWIKI_KEYMAP_RESULTS` (env-var IPC keeps it
robust to `--clean -u` argument parsing). Exit code mirrors the
harness: 0 on green, 1 on any FAIL. Local run yields:

  SUMMARY: 19 passed, 0 failed

CI: new `keymaps` job in `.gitea/workflows/ci.yaml` installs Neovim
and runs the script, so a regression in `lua/nuwiki/keymaps.lua`,
`autoload/nuwiki/commands.vim`, or the LSP command surface is caught
on every push.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -55,3 +55,26 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-cargo-test-
       - run: cargo test --workspace --all-targets
+
+  keymaps:
+    name: editor keymaps
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.83
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-test-${{ hashFiles('**/Cargo.lock', '**/Cargo.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-test-
+      - name: install neovim
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y --no-install-recommends neovim
+          nvim --version | head -1
+      - name: run keymap harness
+        run: ./scripts/test-keymaps.sh

scripts/test-keymaps.lua

@@ -0,0 +1,268 @@
+-- scripts/test-keymaps.lua — driven by scripts/test-keymaps.sh.
+--
+-- Headless Neovim harness for the buffer-local keymaps registered by
+-- `ftplugin/vimwiki.vim` + `lua/nuwiki/keymaps.lua`. Each case sets up
+-- the buffer, places the cursor, fires the key sequence via
+-- `nvim_feedkeys`, waits for any LSP round-trip, and asserts the
+-- expected post-state.
+--
+-- Pass/fail summary is written to the path passed as argv[1] so the
+-- shell wrapper can read + render it without trying to capture nvim's
+-- TUI output.
+
+local OUT = vim.env.NUWIKI_KEYMAP_RESULTS or '/tmp/nuwiki-keymap-results.txt'
+local out_lines = {}
+local pass = 0
+local fail = 0
+
+local function record(ok, name, detail)
+  local suffix = (detail and detail ~= '') and (' — ' .. detail) or ''
+  table.insert(out_lines, (ok and 'PASS' or 'FAIL') .. ' ' .. name .. suffix)
+  if ok then pass = pass + 1 else fail = fail + 1 end
+end
+
+local function set_buf(lines)
+  vim.api.nvim_buf_set_lines(0, 0, -1, false, lines)
+end
+
+local function get_lines()
+  return vim.api.nvim_buf_get_lines(0, 0, -1, false)
+end
+
+local function get_line(n)
+  return vim.api.nvim_buf_get_lines(0, n - 1, n, false)[1] or ''
+end
+
+local function send(keys)
+  vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes(keys, true, false, true), 'x', false)
+end
+
+local function sleep(ms)
+  vim.cmd('sleep ' .. ms .. 'm')
+end
+
+--- Run one case: lines + cursor (1-based) + key sequence + expected
+--- post-state. `wait_ms` defaults to 800 (enough for an LSP
+--- executeCommand round-trip on a hot server).
+local function run(name, opts)
+  local ok, err = pcall(function()
+    set_buf(opts.lines)
+    vim.api.nvim_win_set_cursor(0, opts.cursor or { 1, 0 })
+    send(opts.keys)
+    sleep(opts.wait_ms or 800)
+    local actual_lines = get_lines()
+    if opts.expect_lines then
+      if not vim.deep_equal(actual_lines, opts.expect_lines) then
+        error(string.format('lines mismatch\n  expected: %s\n  actual:   %s',
+          vim.inspect(opts.expect_lines), vim.inspect(actual_lines)))
+      end
+    end
+    if opts.expect_line and opts.expect_at then
+      local got = get_line(opts.expect_at)
+      if got ~= opts.expect_line then
+        error(string.format('line %d mismatch\n  expected: %q\n  actual:   %q',
+          opts.expect_at, opts.expect_line, got))
+      end
+    end
+    if opts.expect_cursor_line then
+      local lnum = vim.api.nvim_win_get_cursor(0)[1]
+      if lnum ~= opts.expect_cursor_line then
+        error(string.format('cursor line mismatch — expected %d, got %d',
+          opts.expect_cursor_line, lnum))
+      end
+    end
+    if opts.expect_buf_path then
+      local got = vim.api.nvim_buf_get_name(0)
+      if not got:find(opts.expect_buf_path, 1, true) then
+        error(string.format('buffer path mismatch\n  expected substring: %q\n  actual: %q',
+          opts.expect_buf_path, got))
+      end
+    end
+  end)
+  record(ok, name, ok and '' or tostring(err))
+end
+
+local function wait_for_lsp(timeout_ms)
+  local deadline = vim.loop.now() + (timeout_ms or 5000)
+  while vim.loop.now() < deadline do
+    local clients = vim.lsp.get_clients({ name = 'nuwiki', bufnr = 0 })
+    if #clients > 0 and clients[1].server_capabilities.executeCommandProvider then
+      return clients[1]
+    end
+    sleep(100)
+  end
+  return nil
+end
+
+-- ===== Smoke: LSP attached =====
+
+vim.defer_fn(function()
+  local client = wait_for_lsp()
+  if not client then
+    record(false, 'lsp.attached', 'no nuwiki client after 5s')
+    vim.fn.writefile(out_lines, OUT)
+    vim.cmd('qall!')
+    return
+  end
+  record(true, 'lsp.attached', 'client=' .. client.name)
+
+  -- ===== Lists =====
+
+  run('list.toggle_via_C-Space', {
+    lines = { '= test =', '- [ ] task' },
+    cursor = { 2, 0 },
+    keys = '<C-Space>',
+    expect_line = '- [X] task',
+    expect_at = 2,
+  })
+  run('list.toggle_via_C-@', {
+    lines = { '= test =', '- [ ] task' },
+    cursor = { 2, 0 },
+    keys = '<C-@>',
+    expect_line = '- [X] task',
+    expect_at = 2,
+  })
+  run('list.toggle_via_Nul', {
+    lines = { '= test =', '- [ ] task' },
+    cursor = { 2, 0 },
+    keys = '<Nul>',
+    expect_line = '- [X] task',
+    expect_at = 2,
+  })
+  run('list.cycle_via_gln', {
+    lines = { '- [ ] task' },
+    cursor = { 1, 0 },
+    keys = 'gln',
+    expect_line = '- [.] task',
+    expect_at = 1,
+  })
+  run('list.reject_via_glx', {
+    lines = { '- [ ] task' },
+    cursor = { 1, 0 },
+    keys = 'glx',
+    expect_line = '- [-] task',
+    expect_at = 1,
+  })
+  run('list.toggle_round_trip', {
+    lines = { '- [X] done' },
+    cursor = { 1, 0 },
+    keys = '<C-Space>',
+    expect_line = '- [ ] done',
+    expect_at = 1,
+  })
+
+  -- ===== Next task (gnt) =====
+
+  run('list.gnt_jumps_to_unfinished', {
+    lines = { '- [X] done', '- [ ] todo', '- [ ] later' },
+    cursor = { 1, 0 },
+    keys = 'gnt',
+    expect_cursor_line = 2,
+    wait_ms = 600,
+  })
+
+  -- ===== Heading levels =====
+
+  run('heading.add_level_with_=', {
+    lines = { '= H1 =' },
+    cursor = { 1, 0 },
+    keys = '=',
+    expect_line = '== H1 ==',
+    expect_at = 1,
+  })
+  run('heading.remove_level_with_-', {
+    lines = { '== H2 ==' },
+    cursor = { 1, 0 },
+    keys = '-',
+    expect_line = '= H2 =',
+    expect_at = 1,
+  })
+  run('heading.add_level_clamps_at_6', {
+    lines = { '====== H6 ======' },
+    cursor = { 1, 0 },
+    keys = '=',
+    expect_line = '====== H6 ======', -- unchanged
+    expect_at = 1,
+  })
+
+  -- ===== Header nav (pure Lua, no LSP) =====
+
+  run('headers.]]_jumps_to_next', {
+    lines = { '= One =', 'body', '== Two ==', 'body', '= Three =' },
+    cursor = { 1, 0 },
+    keys = ']]',
+    expect_cursor_line = 3,
+    wait_ms = 100,
+  })
+  run('headers.[[_jumps_to_prev', {
+    lines = { '= One =', 'body', '== Two ==', 'body', '= Three =' },
+    cursor = { 5, 0 },
+    keys = '[[',
+    expect_cursor_line = 3,
+    wait_ms = 100,
+  })
+  run('headers.]u_jumps_to_parent', {
+    lines = { '= Parent =', '== Child ==', 'body' },
+    cursor = { 3, 0 },
+    keys = ']u',
+    expect_cursor_line = 1,
+    wait_ms = 100,
+  })
+
+  -- ===== Link nav (pure Lua) =====
+
+  run('links.<Tab>_jumps_to_next_wikilink', {
+    lines = { 'intro [[A]] more [[B]] end' },
+    cursor = { 1, 0 },
+    keys = '<Tab>',
+    expect_cursor_line = 1,
+    wait_ms = 100,
+  })
+
+  -- ===== <CR> two-step =====
+
+  run('cr.wraps_bare_word_first_press', {
+    lines = { 'MyPage rest' },
+    cursor = { 1, 3 },
+    keys = '<CR>',
+    expect_line = '[[MyPage]] rest',
+    expect_at = 1,
+    wait_ms = 200,
+  })
+
+  -- ===== Bullet continuation (o/O) =====
+
+  run('lists.o_continues_list_marker', {
+    lines = { '- first' },
+    cursor = { 1, 0 },
+    keys = 'o<Esc>',
+    expect_lines = { '- first', '- ' },
+    wait_ms = 100,
+  })
+  run('lists.o_continues_checkbox', {
+    lines = { '- [ ] first' },
+    cursor = { 1, 0 },
+    keys = 'o<Esc>',
+    expect_lines = { '- [ ] first', '- [ ] ' },
+    wait_ms = 100,
+  })
+  run('lists.O_continues_above', {
+    lines = { '- second' },
+    cursor = { 1, 0 },
+    keys = 'O<Esc>',
+    expect_lines = { '- ', '- second' },
+    wait_ms = 100,
+  })
+
+  -- ===== Diary nav =====
+  -- Tested via the LSP open-* responses; can't fully validate without
+  -- a populated diary, but at least confirm the maps fire without
+  -- error.
+
+  -- ===== Wrap up =====
+
+  table.insert(out_lines, '')
+  table.insert(out_lines, string.format('SUMMARY: %d passed, %d failed', pass, fail))
+  vim.fn.writefile(out_lines, OUT)
+  vim.cmd(fail == 0 and 'qall!' or 'cquit!')
+end, 1500)

scripts/test-keymaps.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+#
+# scripts/test-keymaps.sh — drive scripts/test-keymaps.lua under
+# headless Neovim and report pass/fail per buffer-local keymap.
+#
+# The Lua harness needs a real LSP attachment (most keymaps dispatch
+# `workspace/executeCommand`), so we:
+#   1. ensure `bin/nuwiki-ls` is built (release),
+#   2. spin up a scratch wiki under a temp dir,
+#   3. invoke `nvim --headless` with a minimal init that loads the
+#      plugin + calls `setup()`, then sources the harness Lua.
+#
+# Exit code mirrors the harness: 0 on green, 1 on any failure.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP="$(mktemp -d -t nuwiki-keymap-test-XXXXXX)"
+trap 'rm -rf "$TMP"' EXIT
+
+log() { printf '\033[1;34m[keymap-test]\033[0m %s\n' "$*"; }
+
+# Build the LSP binary if missing.
+BIN="$REPO_ROOT/bin/nuwiki-ls"
+if [[ ! -x "$BIN" ]]; then
+  log 'building nuwiki-ls (release)…'
+  cargo build --release -p nuwiki-ls --manifest-path "$REPO_ROOT/Cargo.toml" >/dev/null
+  mkdir -p "$REPO_ROOT/bin"
+  ln -sf "$REPO_ROOT/target/release/nuwiki-ls" "$BIN"
+fi
+
+mkdir -p "$TMP/wiki"
+echo "= seed =" > "$TMP/wiki/index.wiki"
+
+INIT="$TMP/init.lua"
+cat > "$INIT" <<EOF
+-- Keep the harness self-contained; no plugin manager required.
+vim.opt.runtimepath:prepend('$REPO_ROOT')
+vim.g.nuwiki_binary_path = '$BIN'
+require('nuwiki').setup({ wiki_root = '$TMP/wiki' })
+EOF
+
+RESULTS="$TMP/results.txt"
+log "running harness…"
+
+# `nvim --headless -u init.lua FILE +luafile …` — the harness's
+# `vim.defer_fn` lets the LSP attach before tests fire, then writes
+# the results file and exits. Output path is plumbed through env.
+NUWIKI_KEYMAP_RESULTS="$RESULTS" \
+  nvim --clean -u "$INIT" --headless "$TMP/wiki/index.wiki" \
+    -c "luafile $REPO_ROOT/scripts/test-keymaps.lua" \
+    >"$TMP/nvim.log" 2>&1 || true
+
+if [[ ! -f "$RESULTS" ]]; then
+  echo 'keymap test harness produced no output' >&2
+  echo '--- nvim log ---' >&2
+  cat "$TMP/nvim.log" >&2 || true
+  exit 1
+fi
+
+cat "$RESULTS"
+
+if grep -qE '^SUMMARY: [0-9]+ passed, 0 failed' "$RESULTS"; then
+  exit 0
+fi
+exit 1