feat: add config-backed ask keymaps

2026-04-28 22:35:43 +02:00
parent 5c0d8964fb
commit e8a36b72ef
31 changed files with 2192 additions and 422 deletions
@@ -0,0 +1,175 @@
+# pi-ask configuration
+
+This file is the source of truth for configuring `@eko24ive/pi-ask`.
+
+When changing pi-ask settings:
+
+1. Edit the config file.
+2. Validate keymaps against the rules below.
+3. Run `/reload` or restart pi so the new config is picked up.
+
+## Config file path
+
+Default path:
+
+`~/.pi/agent/extensions/eko24ive-pi-ask.json`
+
+## Config shape
+
+```json
+{
+  "schemaVersion": 1,
+  "behaviour": {
+    "autoSubmitWhenAnsweredWithoutNotes": false
+  },
+  "keymaps": {
+    "cancel": "esc",
+    "dismiss": "ctrl+c",
+    "toggle": "space",
+    "confirm": "enter",
+    "optionNote": "n",
+    "questionNote": "shift+n"
+  }
+}
+```
+
+## Behaviour
+
+### `behaviour.autoSubmitWhenAnsweredWithoutNotes`
+
+- type: boolean
+- default: `false`
+- effect: when enabled, a fully answered ask flow with no notes can auto-submit from the review tab
+
+## Keymaps
+
+`keymaps` must contain all 6 configurable actions if present.
+
+### Configurable actions
+
+- `cancel`
+- `dismiss`
+- `toggle`
+- `confirm`
+- `optionNote`
+- `questionNote`
+
+### Defaults
+
+- `cancel: "esc"`
+- `dismiss: "ctrl+c"`
+- `toggle: "space"`
+- `confirm: "enter"`
+- `optionNote: "n"`
+- `questionNote: "shift+n"`
+
+### Allowed bindings
+
+Each configurable action accepts any single `pi-tui` key id string, as long as it is:
+
+- supported by `pi-tui`
+- not reserved
+- not duplicated across configurable actions
+
+Examples of valid bindings:
+
+- `esc`
+- `ctrl+c`
+- `space`
+- `enter`
+- `n`
+- `shift+n`
+- `alt+f7`
+- `ctrl+[`
+- `ctrl+shift+p`
+- `super+k`
+
+### Accepted alias normalization
+
+Common aliases are normalized to canonical `pi-tui`-style strings.
+
+Examples:
+
+- `escape` -> `esc`
+- `return` -> `enter`
+- `control+c` -> `ctrl+c`
+- `Shift+N` -> `shift+n`
+- `pageup` -> `pageUp`
+- `pagedown` -> `pageDown`
+
+### Reserved bindings
+
+These bindings are fixed and cannot be used by configurable actions:
+
+- `?`
+- `tab`
+- `shift+tab`
+- `left`
+- `right`
+- `up`
+- `down`
+- `1`
+- `2`
+- `3`
+- `4`
+- `5`
+- `6`
+- `7`
+- `8`
+- `9`
+
+### Fixed bindings
+
+These are intentionally not configurable:
+
+- `?` opens ask settings
+- `tab`, `shift+tab`, `left`, `right` move between tabs
+- `up`, `down` move between options/actions
+- `1..9` triggers option/review shortcuts
+- `@` remains file-reference affordance in editors
+
+## Invalid keymaps behavior
+
+If configured keymaps are invalid:
+
+- valid `behaviour` settings still load
+- invalid `keymaps` fall back to default keymaps for the current session
+- ask remains usable
+- a warning notice is shown
+- after fixing the file, run `/reload` or restart pi
+
+Invalid keymaps include:
+
+- missing one of the 6 required actions
+- unsupported key syntax
+- duplicate bindings across configurable actions
+- use of reserved bindings
+
+## Example custom config
+
+```json
+{
+  "schemaVersion": 1,
+  "behaviour": {
+    "autoSubmitWhenAnsweredWithoutNotes": true
+  },
+  "keymaps": {
+    "cancel": "q",
+    "dismiss": "ctrl+c",
+    "toggle": "ctrl+t",
+    "confirm": "ctrl+k",
+    "optionNote": "x",
+    "questionNote": "shift+x"
+  }
+}
+```
+
+## Agent editing rule
+
+When editing this config for a user:
+
+- preserve unrelated fields
+- keep `schemaVersion` at `1`
+- do not assign reserved bindings to configurable actions
+- do not create duplicate configurable bindings
+- after changing the file, tell the user to run `/reload` or restart pi