mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/063-keybinding-system.rispec.md

@@ -0,0 +1,181 @@
+# RISE-063: Keybinding System
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/063-keybinding-system.rispec.md
+
+## Creative Intent
+
+mia-code provides a keyboard-driven interface where every action is reachable through a shortcut, and every shortcut is configurable. Developers who live in the terminal expect vim-like efficiency — the keybinding system delivers this by mapping physical keys to semantic actions, supporting context-aware bindings that change meaning based on what's focused, and allowing full customization without sacrificing discoverable defaults.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code uses hardcoded key handling: Enter submits, Ctrl+C exits, Ctrl+J adds a newline
+- There is no abstraction between physical key input and the action it triggers
+- Users cannot remap keys — the bindings are embedded in the readline and input handling code
+- No context awareness: the same keys do the same thing regardless of whether the user is typing, scrolling, or navigating sessions
+- There is no way to discover available keyboard shortcuts from within the application
+- Terminal key conflicts (Ctrl+S for flow control, Ctrl+Z for suspend) are not handled or warned about
+
+**Desired State:**
+- A keybinding registry maps key combinations to named actions
+- Default bindings cover all TUI interactions with ergonomic choices
+- Users customize bindings via config: `{"keybindings": {"session_navigator": "ctrl+s"}}`
+- Bindings are context-aware: different actions fire depending on focus context (input, scrollback, navigator)
+- Conflict detection warns when a user binding conflicts with terminal defaults
+- `/keys` command displays all active bindings grouped by context
+
+## Desired Outcome Definition
+
+The TUI processes all keyboard input through a keybinding registry. Each key combination maps to a named action in a specific context. Default bindings are ergonomic and discoverable. Users can remap any binding through config. Conflicts are detected and reported.
+
+## Natural Language Functional Description
+
+### Keybinding Registry
+
+The keybinding system maintains a registry of bindings:
+
+```typescript
+interface Keybinding {
+  key: string;         // e.g., "ctrl+s", "escape", "f1"
+  action: string;      // e.g., "session_navigator", "cancel", "help"
+  context: string;     // e.g., "input", "scrollback", "navigator", "global"
+  description: string; // human-readable description
+}
+```
+
+Each binding is unique within its context. The same key can map to different actions in different contexts.
+
+### Default Bindings
+
+**Global Context** (active everywhere):
+| Key | Action | Description |
+|-----|--------|-------------|
+| Ctrl+C | `cancel_or_exit` | Cancel current operation or exit if idle |
+| Ctrl+L | `clear_screen` | Clear the terminal and re-render |
+| Ctrl+S | `session_navigator` | Open session navigator overlay |
+| F1 / ? | `help` | Show keybinding help overlay |
+
+**Input Context** (when input area has focus):
+| Key | Action | Description |
+|-----|--------|-------------|
+| Enter | `submit` | Submit the current input |
+| Ctrl+J | `newline` | Insert a newline in the input |
+| Up | `history_prev` | Previous input from history |
+| Down | `history_next` | Next input from history |
+| Tab | `switch_mode` | Toggle between plan/build mode |
+| Ctrl+U | `clear_input` | Clear the input area |
+| Escape | `cancel_input` | Cancel current input / close overlay |
+| Ctrl+Up | `focus_scrollback` | Switch focus to message pane |
+
+**Scrollback Context** (when message pane has focus):
+| Key | Action | Description |
+|-----|--------|-------------|
+| Up / k | `scroll_up` | Scroll up one line |
+| Down / j | `scroll_down` | Scroll down one line |
+| Page Up | `page_up` | Scroll up one page |
+| Page Down | `page_down` | Scroll down one page |
+| Home / g | `scroll_top` | Scroll to top of history |
+| End / G | `scroll_bottom` | Scroll to bottom (latest) |
+| Escape | `focus_input` | Return focus to input area |
+| / | `search` | Search within message history |
+
+**Navigator Context** (when session navigator is open):
+| Key | Action | Description |
+|-----|--------|-------------|
+| Up / Down | `navigate` | Move selection cursor |
+| Enter | `select_session` | Switch to selected session |
+| Ctrl+N | `new_session` | Create new session |
+| Ctrl+D | `archive_session` | Archive selected session |
+| Escape | `close_navigator` | Close navigator |
+| Any letter | `filter` | Filter sessions by typing |
+
+### Key Format
+
+Keys are specified as strings with modifiers:
+- Modifiers: `ctrl+`, `alt+`, `shift+`, `meta+`
+- Special keys: `enter`, `escape`, `tab`, `space`, `backspace`, `delete`
+- Arrow keys: `up`, `down`, `left`, `right`
+- Function keys: `f1` through `f12`
+- Regular keys: `a` through `z`, `0` through `9`
+- Combinations: `ctrl+shift+s`, `alt+enter`
+
+### Configuration
+
+Users customize bindings in their config file:
+
+```jsonc
+{
+  "keybindings": {
+    // Override default bindings by action name
+    "session_navigator": "ctrl+p",      // global
+    "switch_mode": "ctrl+tab",          // input context
+    "new_session": "ctrl+n",            // navigator context
+
+    // Context-specific overrides
+    "scrollback.scroll_up": "ctrl+k",
+    "scrollback.scroll_down": "ctrl+j"
+  }
+}
+```
+
+### Conflict Detection
+
+When loading keybindings from config:
+1. Check for conflicts within the same context (two actions bound to the same key)
+2. Check for conflicts with known terminal defaults (Ctrl+S = XOFF, Ctrl+Z = SIGTSTP)
+3. On conflict: emit a warning in the status bar with the specific conflict details
+4. Terminal flow control (Ctrl+S/Ctrl+Q) is disabled by default when mia-code starts (`stty -ixon`)
+
+### Key Discovery
+
+The `/keys` command displays all active bindings:
+
+```
+Global:
+  Ctrl+C       Cancel / Exit
+  Ctrl+L       Clear screen
+  Ctrl+S       Session navigator
+  F1           Help
+
+Input:
+  Enter        Submit input
+  Ctrl+J       New line
+  Tab          Switch mode (plan/build)
+  ...
+```
+
+The help overlay (F1 or ?) shows the same information in a styled overlay within the TUI.
+
+### Context Resolution
+
+When a key is pressed, the system resolves the action:
+1. Check the current focus context (input, scrollback, navigator)
+2. If a binding exists in that context, execute it
+3. If not, check the global context
+4. If no binding matches, pass the key through as raw input (for text entry in input context)
+
+### First-Run Help
+
+On the first launch of mia-code (detected by absence of config file), a brief keybinding hint is displayed at the bottom of the screen: "Press F1 or ? for keyboard shortcuts". This hint disappears after the first input or after 10 seconds.
+
+## Supporting Structures
+
+- **Rich TUI (RISE-058)** provides the focus management system that determines active context
+- **Session Navigation (RISE-061)** defines the navigator context bindings
+- **Multi-Level Config (RISE-064)** loads keybinding customizations from the appropriate config level
+- **JSONC Config (RISE-065)** allows commenting out keybinding overrides for experimentation
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Vim-Muscle-Memory Developer:**
+A developer accustomed to vim remaps scrollback navigation to use h/j/k/l and remaps session navigator to Ctrl+P (like fuzzy-finder). Their config: `{"keybindings": {"session_navigator": "ctrl+p", "scrollback.scroll_up": "k", "scrollback.scroll_down": "j"}}`. The TUI immediately feels like home.
+
+**Scenario 2 — Discovering Available Actions:**
+A new user presses F1 and sees all available shortcuts grouped by context. They learn that Tab switches modes and Ctrl+S opens sessions. They close the help overlay and try each shortcut, building familiarity organically.
+
+**Scenario 3 — Resolving a Conflict:**
+A developer binds `ctrl+s` to "submit" in their config. On startup, mia-code warns: "Keybinding conflict: ctrl+s is already bound to session_navigator in global context." The developer either remaps one of them or accepts the override (context-specific binding wins over global).
+
+**Scenario 4 — Terminal Compatibility:**
+A developer SSHs into a server where Ctrl+S triggers XOFF flow control. mia-code detects this and disables XOFF at startup. If it cannot disable it (no tty control), it warns the user and suggests an alternative binding for the session navigator.

package/rispecs/borrowed_from_opencode/064-multi-level-config.rispec.md

@@ -0,0 +1,155 @@
+# RISE-064: Multi-Level Configuration
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/064-multi-level-config.rispec.md
+
+## Creative Intent
+
+mia-code resolves configuration from multiple sources with a clear, predictable precedence hierarchy. A developer's global preferences serve as defaults, project-specific overrides tailor behavior to each codebase, environment variables inject secrets without touching config files, and CLI flags provide instant one-off adjustments. Every configuration value has a traceable origin — the developer always knows not just what the value is, but where it came from and why it won.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code reads configuration from a single flat file: `~/.mia-code.json`
+- There is no concept of project-level configuration — all projects share the same settings
+- Environment variables for API keys work but are not formally integrated into the config system
+- CLI flags exist for some options but there is no defined relationship between flags and config file values
+- When a config value doesn't work as expected, there is no way to trace which source provided it
+- Arrays (like plugin lists) and objects (like provider configs) have no defined merge behavior across sources
+
+**Desired State:**
+- Configuration loads from six levels with explicit precedence: defaults → global → env vars → project → CLI flags → inline
+- Each level can override settings from lower levels using defined merge rules
+- Objects deep-merge (project config adds to global), scalars replace, arrays concatenate
+- `/config` command shows the resolved configuration with source annotations for each value
+- Config loading errors warn but don't crash — the system continues with values from other levels
+- First-run generates a commented config file template explaining available options
+
+## Desired Outcome Definition
+
+mia-code loads configuration by merging six levels in order. The resolved configuration is a deep merge where each level overrides values from below. The `/config` command shows every resolved value with its source (which level it came from). Invalid or missing config at any level is handled gracefully.
+
+## Natural Language Functional Description
+
+### Configuration Levels (Lowest to Highest Priority)
+
+1. **Built-in Defaults** — Hardcoded in the application source. Every config key has a default value. These are the baseline that make mia-code work out of the box with no config file at all.
+
+2. **Global Config** — File at `~/.config/mia-code/config.json` (XDG standard) or `~/.mia-code.json` (legacy). Contains user-wide preferences: default models, API keys, theme preferences, keybindings.
+
+3. **Environment Variables** — Variables prefixed with `MIA_CODE_` map to config paths. Example: `MIA_CODE_MODEL=gemini-2.5-pro` sets the `model` config key. Nested paths use double underscores: `MIA_CODE_PROVIDER__ANTHROPIC__API_KEY` maps to `provider.anthropic.apiKey`.
+
+4. **Project Config** — File at `./mia-code.json` or `./.mia-code/config.json` in the project root. Contains project-specific overrides: preferred model for this codebase, custom agents, project-specific permissions.
+
+5. **CLI Flags** — Command-line arguments: `--model`, `--engine`, `--verbose`, etc. These override any file-based config for the current invocation.
+
+6. **Inline Config** — The `MIA_CODE_CONFIG_CONTENT` environment variable contains a JSON string that is parsed as a complete config object. Useful for CI/CD environments where file creation is inconvenient.
+
+### Merge Rules
+
+When combining config from multiple levels:
+
+**Objects merge recursively:**
+```
+Global:  {"provider": {"openai": {"apiKey": "sk-1"}}}
+Project: {"provider": {"anthropic": {"apiKey": "sk-2"}}}
+Result:  {"provider": {"openai": {"apiKey": "sk-1"}, "anthropic": {"apiKey": "sk-2"}}}
+```
+
+**Scalars replace (last wins):**
+```
+Global:  {"model": "gemini-2.5-pro"}
+Project: {"model": "claude-sonnet-4"}
+Result:  {"model": "claude-sonnet-4"}
+```
+
+**Arrays concatenate:**
+```
+Global:  {"plugins": ["plugin-a"]}
+Project: {"plugins": ["plugin-b"]}
+Result:  {"plugins": ["plugin-a", "plugin-b"]}
+```
+
+**Special: null removes:**
+```
+Global:  {"provider": {"openai": {"apiKey": "sk-1"}, "anthropic": {"apiKey": "sk-2"}}}
+Project: {"provider": {"openai": null}}
+Result:  {"provider": {"anthropic": {"apiKey": "sk-2"}}}
+```
+
+**Special: empty array replaces:**
+```
+Global:  {"plugins": ["plugin-a", "plugin-b"]}
+Project: {"plugins": []}
+Result:  {"plugins": []}
+```
+
+### Environment Variable Mapping
+
+Environment variables follow a systematic mapping:
+- `MIA_CODE_<KEY>` maps to the top-level `<key>` (lowercased)
+- `MIA_CODE_<A>__<B>` maps to nested path `<a>.<b>`
+- `MIA_CODE_<A>__<B>__<C>` maps to `<a>.<b>.<c>`
+- Values are parsed as JSON if they look like JSON; otherwise treated as strings
+- Boolean strings: `"true"`, `"false"`, `"1"`, `"0"` are converted to booleans
+- Numeric strings are converted to numbers
+
+### Config File Discovery
+
+Project config is found by walking up from the current working directory:
+1. Check `./mia-code.json`
+2. Check `./.mia-code/config.json`
+3. If neither found, move to parent directory and repeat
+4. Stop at filesystem root or git repository root
+5. If no project config found, this level contributes nothing
+
+### Config Resolution Display
+
+The `/config` command shows the merged result with source annotations:
+
+```
+model: claude-sonnet-4          [project: ./mia-code.json]
+engine: gemini                   [global: ~/.config/mia-code/config.json]
+verbose: true                    [cli: --verbose]
+provider.anthropic.apiKey: sk-** [env: MIA_CODE_PROVIDER__ANTHROPIC__API_KEY]
+theme: dark                      [default]
+```
+
+Each value shows which level provided it. Secrets are masked in display.
+
+### Error Handling
+
+- **Missing config file**: silently skip that level (this is normal)
+- **Invalid JSON**: warn with file path and parse error, skip that level
+- **Unknown config keys**: warn but include them (forward compatibility)
+- **Type mismatch** (e.g., string where object expected): warn, use the higher-precedence value as-is
+
+### First-Run Config Generation
+
+On first run (no global config file exists):
+1. Create `~/.config/mia-code/config.json` with a commented template
+2. Template includes all available config keys with descriptions (using JSONC comments)
+3. All values in the template are commented out (the defaults apply)
+4. User is informed: "Created config file at ~/.config/mia-code/config.json"
+
+## Supporting Structures
+
+- **JSONC Config (RISE-065)** enables comments in config files for documentation
+- **Config Environment Variables (RISE-066)** handles `${VAR}` substitution within config values
+- **Config Deep Merging (RISE-067)** implements the recursive merge logic described here
+- **Managed Config Directory (RISE-070)** adds an even-higher-precedence enterprise level
+- **Remote Org Config (RISE-068)** adds an organizational defaults level
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Personal Defaults with Project Override:**
+A developer's global config sets `model: gemini-2.5-pro` (their preferred default). For a client project that requires Claude, they add `{"model": "claude-sonnet-4"}` to `./mia-code.json`. In that project, Claude is used. In all other projects, Gemini is used. No flags needed.
+
+**Scenario 2 — CI/CD with Inline Config:**
+A CI pipeline sets `MIA_CODE_CONFIG_CONTENT='{"model":"claude-haiku-4","permissions":{"bash":"allow"}}'`. No config file is needed on the CI runner. The inline config overrides everything except CLI flags.
+
+**Scenario 3 — Debugging Config Issues:**
+A developer's agent is using an unexpected model. They run `/config` and see: `model: gpt-4 [env: MIA_CODE_MODEL]`. They realize they set `MIA_CODE_MODEL` in their shell profile weeks ago. The source annotation makes the fix obvious: unset the environment variable.
+
+**Scenario 4 — Team Project Setup:**
+A team commits `./mia-code.json` to their repo with project-specific settings: preferred model, custom agents, permission rulesets. Every team member gets these defaults automatically. Individual developers override specific values in their global config or via CLI flags.

package/rispecs/borrowed_from_opencode/065-jsonc-config.rispec.md

@@ -0,0 +1,190 @@
+# RISE-065: JSONC Configuration
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/065-jsonc-config.rispec.md
+
+## Creative Intent
+
+mia-code configuration files speak a developer-friendly dialect of JSON that allows comments, trailing commas, and inline documentation. Configuration is not just a data format — it is a conversation between the tool and the developer. Comments explain why a setting exists, not just what it is. Developers can comment out experimental settings, leave notes for their future selves, and maintain readable config files that serve as living documentation.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code config files (`~/.mia-code.json`) are strict JSON — no comments allowed
+- Developers cannot annotate their configuration choices with reasoning or context
+- Commenting out a setting to temporarily disable it is impossible without removing the line
+- Config file templates and examples must omit explanatory comments
+- Developers who want to document their config resort to separate README files or external notes
+- JSON parse errors for trailing commas are a common friction point
+
+**Desired State:**
+- Config files support JSONC (JSON with Comments): `//` line comments, `/* */` block comments, trailing commas
+- Both `.json` and `.jsonc` extensions are recognized as config files
+- Generated config templates include comments explaining each available option
+- Config editing commands preserve existing comments when updating values
+- Parse errors for JSONC files report line and column numbers with surrounding context
+
+## Desired Outcome Definition
+
+All mia-code config files are parsed as JSONC. Developers can freely use line comments, block comments, and trailing commas. The config template generated on first run is richly commented. Programmatic config edits preserve existing comments.
+
+## Natural Language Functional Description
+
+### JSONC Syntax Support
+
+The following syntax extensions beyond standard JSON are supported:
+
+**Line comments** — `//` causes everything after it on the same line to be ignored:
+```jsonc
+{
+  "model": "gemini-2.5-pro", // Primary model for agent interactions
+  "engine": "gemini"         // Agent engine: gemini, claude, or openai
+}
+```
+
+**Block comments** — `/* ... */` can span multiple lines:
+```jsonc
+{
+  /* Provider configuration
+     Add API keys for each provider you want to use.
+     At least one provider must be configured. */
+  "provider": {
+    "anthropic": {
+      "apiKey": "${ANTHROPIC_API_KEY}"
+    }
+  }
+}
+```
+
+**Trailing commas** — a comma after the last element in an object or array is allowed:
+```jsonc
+{
+  "plugins": [
+    "plugin-a",
+    "plugin-b",  // trailing comma OK
+  ],
+}
+```
+
+### File Extension Support
+
+mia-code recognizes both extensions:
+- `.json` files are parsed as JSONC (backward compatible — valid JSON is valid JSONC)
+- `.jsonc` files are parsed as JSONC
+- The config file can be named either `config.json` or `config.jsonc`
+- When both exist in the same directory, `.jsonc` takes precedence
+
+### Parser
+
+The JSONC parser strips comments and trailing commas before parsing the underlying JSON structure. Implementation options:
+- Use `jsonc-parser` npm package (Microsoft's parser, used in VS Code)
+- Use a custom strip-and-parse approach (regex strip comments, then JSON.parse)
+- The parser preserves source positions for error reporting
+
+### Config Template
+
+On first run, mia-code generates a commented config template:
+
+```jsonc
+{
+  // mia-code Configuration
+  // Documentation: https://github.com/mia-code/docs/config
+
+  // Agent engine: "gemini", "claude", or "openai"
+  // "engine": "gemini",
+
+  // Default model for agent interactions
+  // "model": "gemini-2.5-pro",
+
+  // Provider API keys (use environment variables for security)
+  // "provider": {
+  //   "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" },
+  //   "openai": { "apiKey": "${OPENAI_API_KEY}" },
+  //   "google": { "apiKey": "${GOOGLE_API_KEY}" }
+  // },
+
+  // Theme: "dark", "light", or custom object
+  // "theme": "dark",
+
+  // Keyboard shortcut overrides
+  // "keybindings": {},
+
+  // Permission rulesets
+  // "permissions": {}
+}
+```
+
+All settings are commented out (using `//`) so defaults apply. The developer uncomments only what they want to change.
+
+### Comment Preservation
+
+When mia-code programmatically updates a config file (e.g., adding a permanent permission rule via "always allow"):
+1. The original file content is parsed while tracking comment positions
+2. The modification is applied to the parsed data structure
+3. The file is re-serialized with original comments preserved in their positions
+4. New values added by mia-code include a generated comment noting the source
+
+Example after allowing `git status`:
+```jsonc
+{
+  "engine": "gemini", // My preferred engine
+  "permissions": {
+    "bash": {
+      "allow": [
+        "git *" // Added by mia-code permission prompt (2025-01-15)
+      ]
+    }
+  }
+}
+```
+
+### Error Reporting
+
+JSONC parse errors include context:
+
+```
+Config error in ~/.config/mia-code/config.json:
+  Line 12, Column 5: Unexpected token '}'
+  
+  10 |   "provider": {
+  11 |     "anthropic": { "apiKey": "sk-123" }
+  12 |   }}
+     |     ^ unexpected token
+  
+  Tip: Check for mismatched braces or missing commas.
+```
+
+Errors include:
+- File path
+- Line and column number
+- 3 lines of context around the error
+- A pointer to the exact character
+- A hint about common causes
+
+### Validation
+
+After parsing, the config is validated against a schema:
+- Unknown keys generate warnings (not errors) for forward compatibility
+- Type mismatches (string where number expected) generate errors with the expected type
+- Required keys (none currently — all have defaults) generate errors if missing
+
+## Supporting Structures
+
+- **Multi-Level Config (RISE-064)** loads config files that are parsed as JSONC
+- **Config Environment Variables (RISE-066)** applies `${VAR}` substitution after JSONC parsing
+- **Config Deep Merging (RISE-067)** merges the parsed config objects from multiple levels
+- **Managed Config Directory (RISE-070)** uses the same JSONC format for enterprise config
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Annotated Personal Config:**
+A developer maintains a richly commented config file that documents their choices: `"model": "claude-sonnet-4", // Switched from Gemini 2025-01-10 — better at TypeScript`. Months later, they remember why they made the switch without digging through changelogs.
+
+**Scenario 2 — Experimenting with Settings:**
+A developer wants to try a new model. They comment out their current setting and add a new one: `// "model": "gemini-2.5-pro",` followed by `"model": "claude-sonnet-4"`. If the new model doesn't work out, they reverse the comments. No git diff noise, no value loss.
+
+**Scenario 3 — Team Config Documentation:**
+A team commits `.mia-code/config.jsonc` to their repository. The file includes block comments at the top explaining the team's conventions: which model to use, which permissions are required, and why certain tools are restricted. New team members read the config file and understand the project's agent policy.
+
+**Scenario 4 — Config Parse Error Recovery:**
+A developer accidentally introduces a syntax error in their config. On startup, mia-code shows the error with line number and context. The developer fixes the typo. mia-code loads the corrected config without restarting — the error was caught early, and the developer wasn't left guessing what went wrong.