@ondrej-svec/hog 1.3.0 → 1.5.0

package/README.md

@@ -9,7 +9,7 @@ Your personal command deck — a unified task dashboard for GitHub Projects and
 
 ```sh
 npm install -g @ondrej-svec/hog
-hog init     # interactive setup wizard
+hog init        # interactive setup wizard
 hog board --live
 ```
 
@@ -17,18 +17,22 @@ Requires **Node.js 22+** and the [GitHub CLI](https://cli.github.com/) (`gh auth
 
 ## Features
 
-**Unified Dashboard** — See GitHub issues from multiple repos and TickTick tasks in one view. Filter by repo, assignee, or backlog status.
+**Unified Dashboard** — GitHub issues from multiple repos and TickTick tasks in one view. Filter by repo, assignee, or backlog status.
 
 **Interactive TUI** — Vim-style navigation (`j`/`k`), section collapsing, search (`/`), multi-select with bulk actions, and a detail panel on wide terminals.
 
-**Issue Actions** — Pick up issues (`p`), assign/unassign (`a`/`u`), change status (`m`), comment (`c`), create issues (`n`) — all without leaving the terminal.
+**Issue Actions** — Pick up issues (`p`), assign/unassign (`a`/`u`), change status (`m`), comment (`c`), create issues (`n`), add/remove labels (`l`) — all without leaving the terminal.
+
+**Natural Language Issue Creation** — Press `I` and type `fix login bug #backend @alice due friday`. hog extracts the title, labels, assignee, and due date automatically. Optional LLM enhancement via OpenRouter.
+
+**Multi-Line Comments** — Press `ctrl+e` in the comment overlay to open your `$EDITOR` (vim, nano, VS Code, etc.) for longer notes.
+
+**Copy Link** — Press `y` to copy the selected issue's URL to your clipboard.
 
 **Focus Mode** — Built-in Pomodoro timer (`f`). Lock onto an issue and focus for 25 minutes (configurable).
 
 **Auto-Refresh** — Background refresh with age indicators (green/yellow/red) and failure tracking. Manual refresh with `r`.
 
-**Toast Notifications** — Every async operation shows clear feedback. Errors persist with retry hints.
-
 **Board Profiles** — Multiple board configurations for different contexts (work, personal, etc.).
 
 **TickTick Optional** — Works with just GitHub. Enable TickTick integration when you want it.
@@ -40,20 +44,94 @@ Requires **Node.js 22+** and the [GitHub CLI](https://cli.github.com/) (`gh auth
 | Key | Action |
 |-----|--------|
 | `j` / `k` | Navigate down / up |
+| `↓` / `↑` | Navigate down / up |
 | `Tab` / `Shift+Tab` | Next / previous section |
-| `Enter` | Open in browser (item) or toggle (section) |
-| `Space` | Toggle section or multi-select |
+| `Space` | Toggle section (on header) or enter multi-select (on issue) |
+| `Enter` | Open issue in browser (item) or toggle collapse (section) |
 | `/` | Search |
+| `n` | Create issue (form wizard) |
+| `I` | Create issue from natural language |
 | `p` | Pick issue (assign + sync to TickTick) |
 | `a` / `u` | Assign / unassign |
-| `m` | Change status |
-| `c` | Comment |
-| `n` | Create issue |
-| `f` | Focus mode (Pomodoro) |
-| `r` | Refresh |
-| `?` | Help |
+| `m` | Change project status |
+| `l` | Add / remove labels |
+| `c` | Add comment |
+| `ctrl+e` | Open `$EDITOR` for multi-line comment |
+| `y` | Copy issue URL to clipboard |
+| `f` | Focus mode (Pomodoro timer) |
+| `C` | Collapse all sections |
+| `r` / `R` | Refresh |
+| `?` | Toggle help |
 | `q` | Quit |
 
+### Multi-Select
+
+Press `Space` on any issue to enter multi-select mode, then:
+
+| Key | Action |
+|-----|--------|
+| `Space` | Toggle item selection |
+| `Enter` / `m` | Open bulk action menu |
+| `Escape` | Clear selection and exit multi-select |
+
+## Natural Language Issue Creation
+
+Press `I` on the board to open the NL input. Type a description in plain English:
+
+```
+fix auth timeout on mobile #backend #bug @alice due friday
+```
+
+hog extracts:
+- **Title** — `fix auth timeout on mobile`
+- **Labels** — `backend`, `bug` (validated against repo labels)
+- **Assignee** — `alice`
+- **Due date** — parsed from `due friday`, `due end of month`, `due 2026-03-01`, etc.
+
+A live preview shows the parsed fields before you confirm with `Enter`.
+
+### Heuristic Tokens
+
+These are extracted without any API key:
+
+| Token | Example | Extracts |
+|-------|---------|---------|
+| `#word` | `#backend` | label |
+| `@user` | `@alice` | assignee (`@me` → your GitHub login) |
+| `due <expr>` | `due friday` | due date (chrono-node) |
+
+Everything else becomes the title.
+
+### LLM Enhancement (optional)
+
+With an [OpenRouter](https://openrouter.ai) API key, hog sends ambiguous input to an LLM for richer title cleanup and inference. The heuristic tokens still take priority — LLM only fills gaps.
+
+Set up during `hog init`, or any time with:
+
+```sh
+hog config ai:set-key sk-or-...   # store key
+hog config ai:clear-key            # remove key
+hog config ai:status               # show active source
+```
+
+Or set an environment variable (takes priority over the stored key):
+
+```sh
+export OPENROUTER_API_KEY=sk-or-...
+# or
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Agent-Native: `hog issue create`
+
+Create issues non-interactively from scripts or AI agents:
+
+```sh
+hog issue create "fix login bug #backend @alice due friday" --repo owner/repo
+hog issue create "add dark mode" --repo owner/repo --dry-run   # preview only
+hog issue create "add dark mode" --repo owner/repo --json      # structured output
+```
+
 ## Commands
 
 ### `hog board`
@@ -69,6 +147,15 @@ hog board --repo myrepo --json      # filter by repo
 hog board --profile work --live     # use a named profile
 ```
 
+### `hog issue`
+
+Manage issues from the command line.
+
+```sh
+hog issue create "fix login bug #backend due friday" --repo owner/repo
+hog issue create "add dark mode" --repo owner/repo --dry-run
+```
+
 ### `hog pick`
 
 Assign a GitHub issue to yourself and create a linked TickTick task.
@@ -82,8 +169,8 @@ hog pick myrepo/145
 Manage TickTick tasks directly.
 
 ```sh
-hog task list                       # list tasks
-hog task add "Ship the feature"     # create task
+hog task list
+hog task add "Ship the feature"
 hog task add "Bug fix" -p high -t "urgent"
 hog task complete <taskId>
 hog task update <taskId> --title "New title" -p medium
@@ -97,22 +184,31 @@ hog task use-project <projectId>    # set default project
 View and manage configuration.
 
 ```sh
-hog config show                     # show full config
-hog config repos                    # list tracked repos
+hog config show
+
+# Repos
+hog config repos
 hog config repos:add owner/repo --project-number 1 --status-field-id PVTSSF_xxx --completion-type closeIssue
 hog config repos:rm reponame
 
-hog config ticktick:enable          # enable TickTick integration
-hog config ticktick:disable         # disable TickTick integration
+# TickTick
+hog config ticktick:enable
+hog config ticktick:disable
+
+# AI / natural language issue creation
+hog config ai:set-key sk-or-...     # store OpenRouter key
+hog config ai:clear-key             # remove stored key
+hog config ai:status                # show active source and provider
 
-hog config profile:create work      # create profile from current config
+# Profiles
+hog config profile:create work
 hog config profile:delete work
-hog config profile:default work     # set default profile
+hog config profile:default work
 ```
 
 ### `hog init`
 
-Interactive setup wizard. Detects your GitHub user, lets you pick repos, and configures everything.
+Interactive setup wizard. Detects your GitHub user, picks repos, configures projects, and optionally sets up an OpenRouter key for AI-enhanced issue creation.
 
 ```sh
 hog init            # interactive setup
@@ -131,7 +227,7 @@ hog sync status         # show sync mappings
 
 ## Configuration
 
-Config lives at `~/.config/hog/config.json`. Created by `hog init` or manually.
+Config lives at `~/.config/hog/config.json`. Created by `hog init` or edited manually.
 
 ```jsonc
 {
@@ -150,25 +246,27 @@ Config lives at `~/.config/hog/config.json`. Created by `hog init` or manually.
     "refreshInterval": 60,   // seconds (min: 10)
     "backlogLimit": 20,
     "assignee": "your-github-username",
-    "focusDuration": 1500    // seconds (25 min)
+    "focusDuration": 1500    // seconds (25 min default)
   },
   "ticktick": {
     "enabled": true          // set false to use without TickTick
   },
-  "profiles": {},            // named board profiles
-  "defaultProfile": ""       // profile to use by default
+  "profiles": {},
+  "defaultProfile": ""
 }
 ```
 
+Credentials (TickTick OAuth token, OpenRouter API key) are stored separately in `~/.config/hog/auth.json` with `0600` permissions.
+
 ### Status Groups
 
-By default, hog auto-detects status columns from your GitHub Project. Override per-repo with `statusGroups`:
+By default, hog auto-detects status columns from your GitHub Project. Override per-repo:
 
 ```json
 "statusGroups": ["In Progress", "In Review", "Todo,Backlog"]
 ```
 
-Each entry is a section. Comma-separated values merge into one section (header = first value). Terminal statuses (Done, Shipped, Closed, etc.) are always hidden.
+Each entry is a board section. Comma-separated values merge into one section (header = first value). Terminal statuses (Done, Shipped, Closed, etc.) are always hidden.
 
 ### Profiles
 
@@ -185,6 +283,7 @@ hog board --profile personal --live
 - **Node.js 22+**
 - **GitHub CLI** (`gh`) — authenticated via `gh auth login`
 - **TickTick account** — optional, for task sync
+- **OpenRouter API key** — optional, for AI-enhanced issue creation (`hog config ai:set-key`)
 
 ## License