first commit

README.md

@@ -0,0 +1,55 @@
+# 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
+{
+  "yourusername/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**.