demian-cli 1.0.3

package/architecture-tui.md

@@ -0,0 +1,468 @@
+# demian TUI Architecture
+
+> Status: canonical TUI design  
+> Depends on: `nodejs/architecture.md`  
+> Scope: terminal UI layer for the integrated `demian` package
+
+`demian` has two terminal experiences:
+
+- `demian-plain`: plain CLI. It preserves raw Markdown output and uses an interactive startup flow when a TTY is available.
+- `demian` and `demian-cli`: rich terminal UI powered by Ink.
+
+The TUI is a presentation layer over the existing `SessionRunner` and `EventBus`. It must not change provider behavior, tool policy, permission ordering, transcript format, or safety rules.
+
+---
+
+## 1. Goals
+
+- Provide a high-quality terminal experience for interactive coding-agent sessions.
+- Render model Markdown richly inside the terminal.
+- Keep plain CLI output raw and automation-friendly.
+- Preserve the existing `SessionRunner` and `EventBus` contracts.
+- Make Markdown rendering an independent module so it can be tested and improved without touching the session loop.
+- Keep streaming responsive while still producing high-quality final output.
+
+---
+
+## 2. Command Split
+
+| Command | Experience | Output contract |
+|---------|------------|-----------------|
+| `demian` | TUI | Interactive Ink UI |
+| `demian-cli` | TUI alias | Interactive Ink UI |
+| `demian-plain` | Plain CLI | Raw Markdown final answer on stdout |
+
+Rationale:
+
+- `demian` should be the best human-facing experience.
+- `demian` and `demian-cli` open the TUI first, show the resolved defaults, and collect the first message inside the interface.
+- Prompt arguments may remain as a compatibility shortcut, but the canonical UX is not shell-argument driven.
+- `demian-plain` keeps raw Markdown output, but it also has an interactive settings/message flow when run in a TTY.
+- The command split avoids adding mode ambiguity to the session runtime.
+
+---
+
+## 3. Dependencies
+
+TUI dependencies:
+
+- `ink`: terminal UI renderer
+- `react`: Ink component runtime
+- `marked`: Markdown parser
+- `highlight.js`: code fence syntax highlighting
+- `chalk`: terminal styling
+- `string-width`, `wrap-ansi`, `slice-ansi`: terminal width and wrapping helpers
+
+Dependency policy:
+
+- These dependencies belong to the UI layer.
+- Provider, tools, hooks, permissions, and transcript modules must not import Ink or Markdown renderer code.
+- TUI modules may be dynamically imported by the TUI entrypoint so plain CLI and unit tests remain lightweight.
+
+---
+
+## 4. Module Layout
+
+```text
+src/
+  cli.ts                         # existing plain CLI main
+  tui.ts                         # TUI main
+  ui/
+    settings.ts                  # shared provider/model selection rules
+    plain-renderer.ts            # current stderr/stdout renderer extracted later
+    plain/
+      interactive.ts             # plain CLI settings/message startup flow
+    tui/
+      app.ts                     # Ink root component
+      controller.ts              # config/session setup and event bridge
+      store.ts                   # event reducer, settings state, and view model
+      input.ts                   # initial prompt input helpers, extracted as needed
+      permission.ts              # TUI permission prompt adapter
+      theme.ts                   # colors and semantic styles
+    markdown/
+      render.ts                  # Markdown -> render blocks
+      component.ts               # Ink component for rendered blocks
+      highlight.ts               # code fence highlighting
+      tables.ts                  # v1 simple table alignment
+      wrap.ts                    # terminal wrapping helpers
+```
+
+Initial implementation may keep `plain-renderer.ts` implicit inside `cli.ts`. TUI modules should still be separate from CLI rendering.
+
+---
+
+## 5. Rendering Model
+
+The Markdown renderer is independent from Ink session orchestration.
+
+```text
+markdown string
+  -> marked tokens
+  -> RenderBlock[]
+  -> Ink component rendering
+```
+
+Render blocks:
+
+- paragraph
+- heading
+- list
+- blockquote
+- code fence
+- table
+- horizontal rule
+- plain fallback
+
+Rendering policy:
+
+- Plain CLI never renders Markdown. It prints raw Markdown.
+- TUI renders Markdown for final assistant messages.
+- Streaming uses an incremental fallback render.
+- Once the assistant message is complete, the TUI re-renders with the full Markdown parser.
+
+---
+
+## 6. Streaming Policy
+
+During streaming:
+
+```text
+model.text.delta events
+  -> append to active assistant buffer
+  -> display incremental fallback render
+```
+
+The incremental fallback renderer:
+
+- preserves responsiveness
+- does not require balanced Markdown syntax
+- treats unclosed code fences as plain preformatted text
+- avoids expensive full parse on every token
+
+After completion:
+
+```text
+model.text event or session.ended
+  -> parse full assistant Markdown
+  -> replace fallback output with final rich render
+```
+
+Rationale:
+
+- Markdown streams often contain temporarily invalid syntax.
+- Full parsing every delta is expensive and can cause visual churn.
+- Final render should prioritize quality and correct layout.
+
+---
+
+## 7. Markdown Quality
+
+### Code Fences
+
+Code fences support syntax highlighting with `highlight.js`.
+
+Policy:
+
+- If language is known, use language-specific highlighting.
+- If language is unknown, use auto-detect only when cheap enough; otherwise render as plain code.
+- Preserve indentation.
+- Wrap long lines only when the pane width requires it.
+- Show the language label when present.
+
+### Tables
+
+v1 table support is simple alignment:
+
+- parse Markdown table rows
+- calculate display width per column
+- align with spaces
+- wrap very long cells conservatively
+
+v1.x improvements:
+
+- column truncation
+- horizontal scrolling
+- border styles
+- alignment markers (`:---`, `---:`, `:---:`)
+
+### Links
+
+Links render as `label (url)` initially. v1.x can add terminal hyperlink escape sequences where supported.
+
+### Width
+
+All layout must use terminal display width, not string length. CJK and ANSI styling require `string-width`, `wrap-ansi`, and `slice-ansi`.
+
+---
+
+## 8. TUI Layout
+
+Default layout:
+
+```text
+┌ status ─ provider / model / agent / cwd / sandbox ───────────┐
+│ settings ─ p provider · m model · enter submit · ctrl+c exit ─│
+│ transcript                                                     │
+│  user prompt                                                   │
+│  assistant markdown                                            │
+│  tool activity summaries                                       │
+│                                                               │
+├ activity / diagnostics ─ tool, retry, usage, transcript path ─┤
+│ permission prompt or current action                            │
+└ composer ─ first message input or permission keys ────────────┘
+```
+
+The first implementation can be a single-column layout with:
+
+- status bar
+- settings/help bar
+- scroll-like transcript area using recent events
+- activity/status line
+- initial prompt input line
+- permission prompt line
+
+The architecture should not require a full-screen widget system before the core TUI is useful.
+
+### Interactive Message Loop
+
+TUI prompt handling is split from the runtime session. The TUI process outlives individual task runs:
+
+```text
+demian
+  -> render TUI
+  -> show resolved provider/model defaults
+  -> allow provider/model edits before first submit
+  -> wait for first message in input line
+  -> submit prompt to SessionRunner
+  -> render assistant answer
+  -> return to standby composer
+  -> repeat until /exit or /quit
+```
+
+The controller keeps prior non-system messages in memory and passes them as `SessionRunner.history` on the next run. The system prompt is rebuilt for each run so environment notes stay fresh.
+
+If a prompt argument is supplied as a compatibility shortcut:
+
+```text
+demian [flags] "prompt"
+  -> render TUI
+  -> show selected provider/model briefly
+  -> start SessionRunner with that prompt
+  -> return to standby composer after the answer
+```
+
+Keys in composer mode:
+
+- `Enter`: submit non-empty prompt
+- `Ctrl+U`: clear input
+- `Up`: recall the previous submitted prompt
+- `Down`: move toward newer submitted prompts, then restore the current draft
+- `p`: open provider selector when the composer is empty
+- `m`: open model editor when the composer is empty
+- `/exit` or `/quit`: exit the TUI
+- `/stop`: report that no task is running while standby
+
+Policy:
+
+- The TUI owns initial settings selection and message collection.
+- Submitted prompt history is stored only in the in-memory TUI store. It is capped and is not written to transcript or grants storage.
+- Prompt history stores user prompts only. `/stop`, `/exit`, and `/quit` are control commands and are not recall entries.
+- `SessionRunner` receives a normal `prompt: string` plus optional prior `history`, and remains unaware of TUI input state.
+- Provider/model changes are allowed only before a run starts. A running tool loop has a stable provider and model.
+
+During a running task, the bottom composer switches to command mode:
+
+- `/stop`: abort the active run and return to standby.
+- `/exit` or `/quit`: abort the active run and exit the TUI.
+- Other text is rejected until the current run finishes.
+
+This keeps the UI available for control commands while avoiding concurrent task runs in v1.
+
+### Provider And Model Selection
+
+The TUI must make configured defaults visible before the first prompt.
+
+Status/settings display:
+
+```text
+provider openai  model gpt-model-name  agent build  cwd ./repo
+[p] provider  [m] model  [enter] send  [ctrl+c] exit
+```
+
+Provider selector:
+
+- Opens with `p` while the composer is empty and no session is running.
+- Lists configured provider keys from resolved config.
+- Highlights the current provider and marks the source as `config`, `saved`, `flag`, or `interactive`.
+- `Up`/`Down` moves selection.
+- `Enter` selects provider.
+- `Esc` returns to composer without changes.
+
+Model editor:
+
+- Opens with `m` while the composer is empty and no session is running.
+- Shows the selected provider's configured model as the default.
+- Accepts free-form model or deployment name text.
+- `Enter` accepts the typed model or keeps the default when blank.
+- `Esc` returns to composer without changes.
+
+Provider/model state:
+
+```ts
+interface InteractiveModelSelection {
+  providerName: string
+  providerSource: "config" | "saved" | "flag" | "interactive"
+  model: string
+  modelSource: "config" | "saved" | "flag" | "interactive"
+}
+```
+
+Rules:
+
+- Saved UI preferences from `.demian/preferences.json` override config defaults.
+- CLI flags preselect provider/model, override saved preferences, and mark values as flag-sourced.
+- `config` means the resolved value after built-in defaults, user config, workspace config, and `--config` merge. The current config loader does not expose finer provenance.
+- `saved` means the last explicit provider/model selection from this workspace. Only provider key and model name are stored; API keys and provider config are never copied into preferences.
+- If the user changes provider, the model resets to that provider's configured default.
+- If the new provider has no configured model, the TUI opens model editor immediately.
+- Provider/model selection is committed into the `SessionRunner` options only when the message is submitted.
+- The selector must not import provider SDKs or make network calls. It only reads resolved local config.
+- The selected provider/model is saved after an interactive or flag-sourced selection.
+
+---
+
+## 9. Event Mapping
+
+TUI subscribes to `RuntimeEvent`:
+
+| Event | TUI behavior |
+|-------|--------------|
+| `session.started` | initialize status |
+| `user.message` | append user block |
+| `model.request` | show model activity |
+| `model.text.delta` | update streaming fallback buffer |
+| `model.text` | finalize rich Markdown block |
+| `model.usage` | update usage summary |
+| `model.content_filter` | show warning block |
+| `provider.retry` | show retry diagnostics |
+| `tool.requested` | append pending tool item |
+| `tool.started` | mark tool running |
+| `tool.completed` | mark tool done and preview |
+| `tool.failed` | mark tool failed |
+| `permission.requested` | show permission prompt and make it the bottom bar priority |
+| `permission.granted` | show grant key |
+| `permission.denied` | show denial |
+| `session.ended` | show completion state, then return to standby composer |
+
+---
+
+## 10. Permission UX
+
+TUI provides `SessionRunner.permissionPrompt`.
+
+Permission prompts are modal inside the TUI. When a tool is waiting for approval, the bottom bar must show the permission prompt instead of the generic running command bar. This is important because keypresses are handled as permission answers while the session is otherwise still in `running` mode.
+
+The prompt displays a human-readable summary of the tool input before shortcuts. For `bash`, the command is shown explicitly; for file tools, the path is shown explicitly; for text-heavy inputs, content is summarized by character count and a short preview. Raw JSON is only a fallback for unknown shapes.
+
+Keys:
+
+- `y`: allow once
+- `a`: allow and persist according to configured grant scope
+- `n`: deny
+- `Enter`: deny by default
+- `Ctrl+C`: emergency exit from the TUI
+
+Policy:
+
+- TUI permission answers must call the same permission engine path as plain CLI.
+- Deny and hook blocks still win over `y`, `a`, and `--yes`.
+- When stdin is not a TTY, TUI should refuse to start and suggest `demian-plain`.
+
+---
+
+## 11. Failure And Fallback
+
+If TUI dependencies are missing:
+
+- `demian` and `demian-cli` should print a clear install hint.
+- `demian-plain` should still work.
+
+If terminal is not interactive:
+
+- TUI should fail fast with a message.
+- Plain CLI remains the supported non-interactive path only when an explicit automation input path is provided.
+- Interactive provider/model prompts require a TTY.
+
+If Markdown rendering fails:
+
+- render raw Markdown in the TUI block
+- show a low-noise warning in diagnostics
+- do not fail the session
+
+---
+
+## 12. Implementation Sequence
+
+1. Add `architecture-tui.md`.
+2. Add TUI dependencies to `package.json`.
+3. Add `bin/demian-plain.js` for existing plain CLI.
+4. Change `bin/demian.js` to TUI entrypoint.
+5. Add `bin/demian-cli.js` as TUI alias.
+6. Implement `src/tui.ts`.
+7. Implement Ink app/controller/state.
+8. Implement initial TUI prompt input for promptless startup.
+9. Implement provider selector and model editor before session start.
+10. Implement plain CLI interactive provider/model/message flow.
+11. Keep CLI/TUI alive after each run and support `/stop`, `/exit`, and `/quit`.
+12. Implement independent Markdown renderer with parser and syntax highlighting.
+13. Wire TUI permission prompt.
+14. Add smoke tests:
+    - `demian-plain --help`
+    - `demian --help`
+    - TUI promptless startup in a pseudo-TTY
+    - plain CLI promptless startup in a pseudo-TTY
+    - Markdown renderer fixture tests without running an interactive TUI.
+
+---
+
+## 13. Non-goals
+
+- Replacing JSONL transcripts.
+- Changing provider/tool/session contracts.
+- Implementing a full editor inside the TUI beyond the initial single-line prompt input.
+- Building an IDE-like file explorer in v1.
+- Perfect Markdown/GFM rendering in the first implementation.
+
+---
+
+## 14. Decision Log
+
+| Decision | Choice | Reason |
+|----------|--------|--------|
+| Default command | `demian` opens TUI | Human-facing default should be high quality |
+| Plain command | `demian-plain` | Preserve raw Markdown and automation |
+| TUI alias | `demian-cli` | Explicit terminal UI command requested |
+| Promptless start | all commands enter UI/CLI first | Interactive use should not require long shell-argument prompts |
+| TUI provider selector | `p` before run | Defaults are visible and can be corrected without editing config |
+| TUI model editor | `m` before run | Model names and Azure deployment names are often deployment-specific |
+| Provider/model source labels | `config`, `saved`, `flag`, `interactive` | Shows whether the value came from config, remembered UI preferences, flags, or current UI edits |
+| Provider/model lock | locked during a run | Keeps one tool loop deterministic and transcript-readable |
+| Persistent UI loop | return to standby after each run | The command should feel like an interactive session, not a one-shot wrapper |
+| Stop command | `/stop` | User needs a clear in-UI way to abort active work without closing the whole UI |
+| Exit command | `/exit` and `/quit` | User needs an explicit way to close the interactive CLI/TUI |
+| Prompt recall | `Up`/`Down` over in-memory submitted prompts | Fast prompt reuse without adding persistence or leaking commands into history |
+| Provider/model preferences | project-local `.demian/preferences.json` | Reuse the last explicit selection without mutating user config or storing secrets |
+| Framework | Ink + React | Best balance of UI quality and implementation speed |
+| Markdown parser | `marked` | Practical parser with simple token API |
+| Syntax highlight | `highlight.js` | Good quality with reasonable weight |
+| Streaming render | incremental fallback | Streaming Markdown is often incomplete |
+| Final render | full Markdown parse | Quality matters once message is complete |
+| Tables | v1 simple alignment | Useful baseline, advanced layout later |
+
+---
+
+## 15. Summary
+
+The TUI is a rich presentation layer over the existing agent runtime. It shows provider/model defaults before the first message and lets the user change them with focused shortcuts. Plain CLI remains raw and scriptable, but also offers a TTY-based provider/model/message flow. Markdown rendering is independent, high-quality final rendering is prioritized, and streaming stays responsive through a fallback renderer.
+
+`demian` and `demian-cli` are interactive TUI commands. `demian-plain` is the stable plain CLI with interactive startup when a TTY is available.