opencode-vim-navigation 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raaghav Arya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,258 @@
-# Temporary Holding Version
+# opencode-vim-navigation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Modal Vim-style transcript navigation for the **OpenCode terminal UI**.
+Scroll the conversation inside OpenCode itself—not your terminal emulator's,
+Neovim's, or tmux's scrollback—while keeping your prompt draft safe.
+
+Press **Ctrl+Q** to switch between INPUT and NAV. A compact, right-aligned
+mode label appears on a divider just above the prompt.
+
+## Compatibility
+
+Tested with **OpenCode 2.1.4**. This uses OpenCode V2's TUI plugin API and is
+not a server plugin or a plugin for the desktop/web UI. Older releases and
+future API changes may require adaptation.
+
+No build step is needed: OpenCode supplies `@opencode/plugin/tui`, OpenTUI,
+and `solid-js`, and loads the TSX entrypoint. OpenTUI and Solid are declared
+as peer dependencies so the package documents its host compatibility.
+Do not run this entrypoint directly with Node.js.
+
+## Install
+
+### From a local checkout (available now)
+
+Clone the repository:
+
+```sh
+git clone https://github.com/Raaghav-Arya/opencode-vim-navigation.git
+```
+
+Then add its **absolute directory path** to the `plugins` array in
+`~/.config/opencode/cli.json`:
+
+```json
+{
+  "plugins": ["/absolute/path/to/opencode-vim-navigation"]
+}
+```
+
+Merge this into any existing TUI config; do not overwrite other settings.
+Restart OpenCode. No `npm install` is needed for this local package.
+
+Alternatively, symlink the package directory into
+`~/.config/opencode/plugins/opencode-vim-navigation` for automatic discovery.
+Use **one installation method**, not both.
+
+### From npm (after publication)
+
+Once the package has been published as `opencode-vim-navigation`, use:
+
+```json
+{
+  "plugins": ["opencode-vim-navigation@0.1.0"]
+}
+```
+
+This belongs in **`cli.json`**, not the server plugin list in `opencode.json`.
+OpenCode V1-era documentation may mention `tui.json`; these instructions target V2.
+OpenCode installs the package. Pin a version for reproducible configuration.
+Until the first npm release, use the local-checkout installation above.
+Check [npm](https://www.npmjs.com/package/opencode-vim-navigation) for availability.
+
+## Keys
+
+| Key | INPUT mode | NAV mode |
+| --- | --- | --- |
+| **Ctrl+Q** | Enter NAV | Return to INPUT and follow latest output |
+| **j / k**, **Down / Up** | OpenCode default | One transcript line down/up |
+| **gg / G** | OpenCode default | Jump to beginning/end |
+| **Ctrl+U / Ctrl+D** | OpenCode default | Half a viewport up/down |
+| **PageUp / PageDown** | OpenCode default | Half a viewport up/down |
+| **Ctrl+Home / Ctrl+End** | OpenCode default | Jump to beginning/end |
+| **i** | Type normally | Return to INPUT, follow latest output, preserve draft |
+| **Escape / Ctrl+C** | OpenCode default | Leave NAV without moving the viewport, then perform OpenCode's normal interrupt/clear action |
+
+Only Ctrl+Q is intercepted in INPUT. In particular, Ctrl+U/D retain their
+normal prompt-editing/exit behavior until you enter NAV.
+
+In NAV, other keys, Enter, and pasted text are ignored to protect your draft
+and prevent accidental submissions. This is **transcript navigation**, not
+Vim editing, cursor selection, or visual mode.
+
+Dialogs, autocomplete, composer panels, and other non-base modes keep their
+own keyboard handling. Incoming permission/form requests and session changes
+exit NAV. Existing mouse behavior is unchanged. The home screen is unchanged.
+
+### Neovim / Sidekick
+
+Stay in Neovim **terminal mode**. OpenCode draws its own transcript, so normal
+terminal-buffer scrollback cannot reliably navigate the conversation.
+
+Let OpenCode receive Ctrl+Q and handle scrolling:
+
+```lua
+cli = {
+  tools = {
+    opencode = { native_scroll = true },
+  },
+  win = {
+    keys = { stopinsert = false },
+  },
+}
+```
+
+Merge these options into your existing Sidekick configuration. Terminal or
+multiplexer mappings that intercept these keys must also be disabled.
+
+## Development
+
+Use Node.js 22 or newer for the development commands:
+
+```sh
+npm test
+npm run check
+npm pack --dry-run
+```
+
+There are no development dependencies to install. `npm run check` checks the
+JavaScript controller and tests; it is **not** a TSX typecheck. OpenCode itself
+loads and compiles the TUI adapter.
+
+```text
+tui.ts                    Conventional local/package entrypoint
+src/
+  navigation.mjs          Mode state and input routing
+  tui.tsx                 OpenCode adapter and mode indicator
+tests/
+  navigation.test.mjs     Controller tests using node:test
+```
+
+The 13 tests mock the host and cover toggling, navigation, INPUT passthrough,
+paste/draft protection, dialog isolation, route cleanup, and missing commands.
+They do not replace interactive rendering tests.
+
+The initial implementation also passed a live pseudo-terminal smoke test
+against OpenCode 2.1.4: INPUT/NAV switched, navigation changed the viewport,
+and returning to INPUT preserved the draft, without submitting any prompt.
+Recheck the same behavior after changing the adapter or upgrading OpenCode.
+
+### Implementation details
+
+The root `tui.ts` re-exports `src/tui.tsx`. OpenCode 2.1.4's local-directory
+loader looks for a conventional root `tui` entrypoint; npm packages also
+expose it via the `./tui` package export. Keep both when reorganizing source.
+
+See the [OpenCode V2 CLI plugin guide](https://opencode.ai/v2/docs/build/plugins/cli)
+for the host API and package conventions.
+
+The plugin uses OpenTUI's public prepended key/paste listeners to stop NAV
+input before it reaches the prompt. A named OpenCode keymap mode isolates
+normal prompt shortcuts. Host transcript commands scroll the actual
+conversation, including virtualized history/backfill; the plugin does not
+scrape a terminal buffer. Listeners, mode, effects, and the mode indicator
+are cleaned up when the plugin deactivates.
+
+In **2.1.4**, `session.page.up/down` move by half of `scroll.height`, whereas
+`session.half.page.up/down` move by a quarter. The plugin deliberately uses
+the former. It checks for expected commands before entering NAV, but future
+releases could retain names while changing semantics.
+
+## Disable / uninstall
+
+Remove the package entry from `cli.json`, then restart OpenCode. If installed
+via automatic discovery instead, remove the symlink from `plugins/`.
+Merely renaming a package directory within `plugins/` does not disable it.
+
+The plugin ID in OpenCode's TUI plugin manager is `opencode-vim-navigation`.
+
+## Maintainer: publishing to npm
+
+GitHub hosts the source; npm distributes the installable package. Publishing
+to GitHub does not automatically publish to npm. Public unscoped packages
+can be published with a free npm account.
+
+### First release
+
+1. Create an account at [npmjs.com/signup](https://www.npmjs.com/signup) if
+   needed, verify your email, and enable two-factor authentication in your
+   account settings. GitHub CLI authentication does **not** log you into npm.
+   Save your recovery codes privately; never commit tokens or recovery codes.
+2. From your checkout, log in using the browser flow:
+
+   ```sh
+   npm login --registry=https://registry.npmjs.org/
+   npm whoami --registry=https://registry.npmjs.org/
+   ```
+
+3. Check the package name:
+
+   ```sh
+   npm view opencode-vim-navigation name version --registry=https://registry.npmjs.org/
+   ```
+
+   An E404 means no public package was found; it is not a reservation or a
+   guarantee that npm will accept the name. If someone else owns it, choose
+   a scoped name such as `@YOUR_NPM_USERNAME/opencode-vim-navigation` and
+   update `package.json` and the installation examples before publishing.
+4. Review the release from the repository root:
+
+   ```sh
+   npm test
+   npm run check
+   npm pack --dry-run
+   npm publish --dry-run
+   ```
+
+   The package should include `LICENSE`, `README.md`, `package.json`, `tui.ts`,
+   and `src/`. Tests and GitHub workflows stay on GitHub, not in the tarball.
+   Dry runs do not upload the package and do not prove your account has
+   permission to publish. The `prepublishOnly` script reruns tests and
+   JavaScript syntax checks before publication.
+5. Publish version **0.1.0**:
+
+   ```sh
+   npm publish --access public
+   ```
+
+   Complete npm's browser / two-factor prompts. Do not paste authentication
+   codes or tokens into issues or chat. A successful publish ends with
+   `+ opencode-vim-navigation@0.1.0`.
+6. Verify the release:
+
+   ```sh
+   npm view opencode-vim-navigation@0.1.0 version dist.tarball
+   ```
+
+   Replace the local path in your OpenCode `cli.json` with
+   `opencode-vim-navigation@0.1.0` and restart OpenCode. Remove the
+   "after publication" wording in this README once the package is live.
+7. Optionally mark the published source on GitHub:
+
+   ```sh
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+   Tag the exact commit used for publication; commit any release changes first.
+
+### Later releases
+
+npm versions cannot be overwritten or reused. For a compatible bug fix,
+start from a clean checkout, update the changelog/README as appropriate, run
+checks, then:
+
+```sh
+npm version patch
+npm publish --access public
+git push origin main --follow-tags
+```
+
+`npm version patch` updates the version and creates a commit and tag. Use a
+minor or major bump when appropriate instead. Publish manually initially;
+if automated releases are added later, prefer npm trusted publishing rather
+than storing a long-lived npm token in the repository.
+
+## License
+
+[MIT](LICENSE) © 2026 Raaghav Arya.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "opencode-vim-navigation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Modal Vim-style transcript navigation for the OpenCode terminal UI",
+  "license": "MIT",
+  "author": "Raaghav Arya",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Raaghav-Arya/opencode-vim-navigation.git"
+  },
+  "homepage": "https://github.com/Raaghav-Arya/opencode-vim-navigation#readme",
+  "bugs": {
+    "url": "https://github.com/Raaghav-Arya/opencode-vim-navigation/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "keywords": ["opencode", "opencode-plugin", "tui", "vim", "navigation"],
+  "exports": {
+    "./tui": "./tui.ts"
+  },
+  "files": ["tui.ts", "src/"],
+  "peerDependencies": {
+    "@opentui/core": ">=0.6.8 <0.7.0",
+    "@opentui/solid": ">=0.6.8 <0.7.0",
+    "solid-js": "^1.9.15"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check": "node --check src/navigation.mjs && node --check tests/navigation.test.mjs",
+    "prepublishOnly": "npm test && npm run check"
+  }
+}

package/src/navigation.mjs

@@ -0,0 +1,97 @@
+// Input routing is separate from the TUI adapter so it can be tested without a server.
+export function navigation(context) {
+  const MODE = "transcript-navigation"
+  let popMode
+  let sessionID
+  let pendingG = false
+
+  const active = () => popMode !== undefined
+  function leave(follow = false) {
+    if (!active()) return
+    popMode()
+    popMode = undefined
+    pendingG = false
+    sessionID = undefined
+    context.changed(false)
+    if (follow) context.dispatch("session.last")
+  }
+  function sync() {
+    if (active() && context.session() !== sessionID) leave()
+  }
+  function scroll(id) {
+    context.dispatch(id)
+  }
+  function consume(event) {
+    event.preventDefault()
+    event.stopPropagation()
+  }
+  function key(event) {
+    sync()
+    if (!context.session()) return
+    // Dialogs, permission forms, autocomplete, and embedded terminals own their keys.
+    const mode = context.mode.current()
+    if (mode !== "base" && mode !== MODE) return
+    if (!active() && !context.promptFocused()) return
+    const plain = !event.ctrl && !event.meta && !event.super && !event.hyper
+    const ctrl = event.ctrl && !event.meta && !event.super && !event.hyper && !event.shift
+    const name = event.name
+    if (ctrl && name === "q") {
+      consume(event)
+      if (active()) leave(true)
+      else {
+        if (!context.ready()) return
+        sessionID = context.session()
+        popMode = context.mode.push(MODE)
+        context.changed(true)
+      }
+      return
+    }
+    if (!active()) return // INPUT mode retains every default except Ctrl+Q.
+    // OpenCode 2.1.4's session.page.* commands move by half the viewport;
+    // session.half.page.* surprisingly move by a quarter. Use the actual half-page commands.
+    const controlScroll = ctrl && ({ u: "session.page.up", d: "session.page.down" })[name]
+    const pageScroll = plain && ({
+      pageup: "session.page.up", pagedown: "session.page.down",
+    })[name]
+    const edgeScroll = ctrl && ({ home: "session.first", end: "session.last" })[name]
+    if (controlScroll || pageScroll || edgeScroll) {
+      consume(event)
+      pendingG = false
+      scroll(controlScroll || pageScroll || edgeScroll)
+      return
+    }
+    if ((plain && name === "escape") || (ctrl && name === "c")) {
+      // Let OpenCode perform its usual interrupt/clear action after leaving NAV.
+      leave()
+      return
+    }
+    consume(event) // Protect the draft, including Enter and unknown shortcuts.
+    if (plain && name === "i" && !event.shift) {
+      leave(true)
+      return
+    }
+    const upperG = plain && (name === "G" || (name === "g" && event.shift))
+    if (upperG) {
+      pendingG = false
+      scroll("session.last")
+      return
+    }
+    if (plain && name === "g" && !event.shift) {
+      if (pendingG) scroll("session.first")
+      pendingG = !pendingG
+      return
+    }
+    pendingG = false
+    if (!plain || event.shift) return
+    const command = ({
+      j: "session.line.down", down: "session.line.down",
+      k: "session.line.up", up: "session.line.up",
+    })[name]
+    if (command) scroll(command)
+  }
+  function paste(event) {
+    sync()
+    if (active() && context.mode.current() === MODE) consume(event)
+  }
+  return { key, paste, leave, sync, active }
+}

package/src/tui.tsx

@@ -0,0 +1,68 @@
+import { Plugin } from "@opencode/plugin/tui"
+import { InputRenderable, TextareaRenderable } from "@opentui/core"
+import { createEffect, createRoot, createSignal } from "solid-js"
+import { navigation } from "./navigation.mjs"
+
+export default Plugin.define({
+  id: "opencode-vim-navigation",
+  setup(context) {
+    const { renderer, keymap, ui } = context
+    if (!renderer.keyInput?.prependListener || !keymap.mode?.push) {
+      throw new Error("Transcript navigation requires the OpenCode 2.1.4 TUI API")
+    }
+    const [nav, setNav] = createSignal(false)
+    const session = () => {
+      const route = ui.router.current()
+      return route.type === "session" ? route.sessionID : undefined
+    }
+    const required = ["session.line.up", "session.line.down", "session.page.up", "session.page.down", "session.first", "session.last"]
+    const controller = navigation({
+      session,
+      mode: keymap.mode,
+      promptFocused: () => renderer.currentFocusedEditor instanceof TextareaRenderable
+        && !(renderer.currentFocusedEditor instanceof InputRenderable),
+      ready: () => {
+        const commands = new Set(keymap.commands().map((command) => command.id))
+        if (required.every((id) => commands.has(id))) return true
+        ui.toast.show({ message: "Transcript navigation: this OpenCode version lacks the expected scrolling commands", variant: "error" })
+        return false
+      },
+      dispatch: (id) => keymap.dispatch(id),
+      changed: setNav,
+    })
+    // OpenTUI's public global input listeners run before the focused editor.
+    // Prepending also precedes OpenCode's own keymap, so NAV cannot submit or edit a draft.
+    renderer.keyInput.prependListener("keypress", controller.key)
+    renderer.keyInput.prependListener("paste", controller.paste)
+    const dispose = createRoot((dispose) => {
+      createEffect(() => {
+        controller.sync()
+        const id = session()
+        // Never trap an incoming permission request or interactive form in NAV.
+        if (id && (context.data.session.permission.list(id)?.length || context.data.session.form.list(id)?.length)) {
+          controller.leave()
+        }
+      })
+      return dispose
+    })
+    const removeStatus = ui.slot({
+      append: "session.composer.top",
+      render: () => <box
+        height={1}
+        width="100%"
+        border={["top"]}
+        borderColor={context.theme.border.base}
+        title={nav() ? " NAV · i: input " : " INPUT · Ctrl+Q: navigate "}
+        titleColor={nav() ? context.theme.text.base : context.theme.text.muted}
+        titleAlignment="right"
+      />,
+    })
+    return () => {
+      renderer.keyInput.removeListener("keypress", controller.key)
+      renderer.keyInput.removeListener("paste", controller.paste)
+      controller.leave()
+      removeStatus()
+      dispose()
+    }
+  },
+})

package/tui.ts

@@ -0,0 +1,2 @@
+// Conventional entrypoint for OpenCode's local-directory plugin discovery.
+export { default } from "./src/tui.tsx"