56 lines
2.0 KiB
Markdown
56 lines
2.0 KiB
Markdown
# jasper.nvim
|
|
|
|
Neovim plugin for automatic time tracking via [Jasper](https://jasper.4sigma.it).
|
|
|
|
## Features
|
|
|
|
- Reads a per-project `.jasper_config.json` to know which Jasper activity to track.
|
|
- Automatically **starts** the timer when Neovim opens and **stops** it when Neovim closes.
|
|
- **Auto-pauses** after a configurable period of inactivity (no cursor movement, typing, etc.) and **resumes** on the next keystroke.
|
|
- Shares the auth token cache with `jasper_waybar.py` (`$XDG_CONFIG_HOME/jasper/token.json`).
|
|
- If no token is found, prompts for credentials inside Neovim.
|
|
|
|
## Requirements
|
|
|
|
- Neovim ≥ 0.10 (uses `vim.system` and `vim.uv`)
|
|
- `curl` available in `$PATH`
|
|
|
|
## Installation (lazy.nvim)
|
|
|
|
```lua
|
|
{
|
|
url = "https://git.donadeo.net/pdonadeo/jasper.nvim",
|
|
config = function()
|
|
require("jasper").setup({
|
|
-- Global default inactivity timeout in minutes (can be overridden per project).
|
|
-- inactivity_timeout = 10,
|
|
})
|
|
end,
|
|
}
|
|
```
|
|
|
|
## Project configuration
|
|
|
|
Place a `.jasper_config.json` file at the root of the project (next to `.git`):
|
|
|
|
```json
|
|
{
|
|
"attivita_id": 12345,
|
|
"inactivity_timeout": 10
|
|
}
|
|
```
|
|
|
|
| Key | Required | Description |
|
|
|-----|----------|-------------|
|
|
| `attivita_id` | ✅ | Numeric ID of the Jasper activity (the `value` field returned by the API). |
|
|
| `inactivity_timeout` | ❌ | Minutes of inactivity before auto-pause. Defaults to `10`. |
|
|
|
|
## How it works
|
|
|
|
1. On `VimEnter`, the plugin looks for `.jasper_config.json` by walking up from the current working directory.
|
|
2. If found, it reads the cached auth token from `$XDG_CONFIG_HOME/jasper/token.json`. If the token is missing or expired, it prompts for credentials.
|
|
3. It fetches the list of timers from Jasper and finds the one associated with `attivita_id`. If none exists, it creates one.
|
|
4. The timer is **started**. A libuv countdown is armed; after `inactivity_timeout` minutes of silence the timer is **paused**.
|
|
5. Any cursor movement or keystroke resets the countdown (and resumes the timer if it was paused).
|
|
6. On `VimLeave` the timer is **stopped**.
|