@vybestack/llxprt-ui 0.7.0-nightly.251211.5750c518a

package/dev-docs/ARCHITECTURE.md

@@ -0,0 +1,178 @@
+# nui Architecture
+
+## Overview
+
+nui is an alternative terminal UI for llxprt-code, built on opentui instead of Ink. It provides a cleaner separation between UI rendering and backend logic.
+
+## Design Principles
+
+1. **UI is Dumb**: The UI layer only renders what it's told. No business logic.
+2. **Adapter Owns Logic**: The adapter layer interprets events and manages state.
+3. **Delegate to Core**: Reuse llxprt-code-core for history, streaming, tools.
+4. **Stream Everything**: Real-time rendering as data arrives.
+
+## Layer Responsibilities
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     UI Layer                            │
+│  - Renders text, markdown, tool status                  │
+│  - Handles user input                                   │
+│  - Shows approval prompts                               │
+│  - NO business logic                                    │
+├─────────────────────────────────────────────────────────┤
+│                   Adapter Layer                         │
+│  - Transforms GeminiClient events → UI events           │
+│  - Manages session lifecycle                            │
+│  - Bridges approval flow                                │
+│  - Owns Config stub                                     │
+├─────────────────────────────────────────────────────────┤
+│                 llxprt-code-core                        │
+│  - GeminiClient (streaming, history, tools)             │
+│  - Providers (OpenAI, Anthropic, Gemini)                │
+│  - HistoryService, SettingsService                      │
+│  - All the battle-tested logic                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Event Flow
+
+### User Message Flow
+
+```
+User Input
+    │
+    ▼
+┌─────────────────┐
+│   UI Layer      │ captures text, sends to adapter
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Adapter Layer  │ calls GeminiClient.sendMessageStream()
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  GeminiClient   │ manages history, calls provider
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Provider      │ streams from API
+└────────┬────────┘
+         │
+    Stream Events
+         │
+         ▼
+┌─────────────────┐
+│  Adapter Layer  │ transforms events
+└────────┬────────┘
+         │
+    AdapterEvents
+         │
+         ▼
+┌─────────────────┐
+│   UI Layer      │ renders incrementally
+└─────────────────┘
+```
+
+### Event Types
+
+**From GeminiClient (ServerGeminiStreamEvent)**:
+
+- `Content` - text chunk from model
+- `Thought` - thinking/reasoning content
+- `ToolCallRequest` - model wants to call a tool
+- `ToolCallConfirmation` - tool needs approval
+- `ToolCallResponse` - tool execution result
+- `Finished` - stream complete
+- `Error` - something went wrong
+
+**To UI (AdapterEvent)**:
+
+- `text_delta` - append text to current message
+- `thinking_delta` - append to thinking section
+- `tool_pending` - show tool as waiting
+- `tool_approval_needed` - prompt user for approval
+- `tool_executing` - show spinner
+- `tool_complete` - show result
+- `complete` - message done
+- `error` - show error
+
+## Config Stub Strategy
+
+GeminiClient requires a Config object. Rather than importing the full 1700-line Config class, we create a minimal stub that satisfies GeminiClient's actual needs:
+
+```typescript
+const configStub = {
+  getSessionId: () => sessionId,
+  getModel: () => model,
+  getProvider: () => provider,
+  getSettingsService: () => settingsService,
+  getContentGeneratorConfig: () => ({ ... }),
+  getToolRegistry: () => undefined,  // No tools initially
+  getEmbeddingModel: () => undefined,
+  getComplexityAnalyzerSettings: () => ({ ... }),
+  // ... other required methods
+};
+```
+
+Use a Proxy wrapper to log any missing methods during development.
+
+## Tool Execution (Future)
+
+When tool execution is implemented:
+
+1. GeminiClient yields `ToolCallRequest` event
+2. Adapter checks approval mode:
+   - Auto-approve: Execute immediately
+   - Require approval: Yield `tool_approval_needed` to UI
+3. UI shows approval prompt
+4. User approves/rejects via callback
+5. Adapter tells GeminiClient to proceed or abort
+6. GeminiClient handles tool execution internally
+7. Results flow back as events
+
+## Session Lifecycle
+
+```
+┌──────────────┐
+│   Create     │ createSession(config)
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│  Initialize  │ session.initialize()
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│   Active     │ session.sendMessage() (repeatable)
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│   Dispose    │ session.dispose()
+└──────────────┘
+```
+
+## Streaming Markdown
+
+The UI must render markdown incrementally as chunks arrive:
+
+1. **Accumulate**: Buffer all text received so far
+2. **Parse**: Re-parse the full buffer on each chunk
+3. **Render**: Show parsed result up to current position
+4. **Grow**: Incomplete constructs (code blocks) render as if complete
+
+This ensures correct formatting even when chunks split markdown syntax.
+
+## Future: Integration with llxprt-code
+
+nui is designed to eventually move into `llxprt-code/packages/nui`:
+
+- Entry point: `llxprt --ui nui` or separate binary
+- Full access to real Config, arg parsing, profiles
+- No more Config stub needed
+- Tool execution fully integrated

package/dev-docs/CODE_ORGANIZATION.md

@@ -0,0 +1,232 @@
+# Code Organization for nui
+
+## Directory Structure
+
+```
+nui/
+├── dev-docs/                    # Documentation for LLMs and developers
+│   ├── ARCHITECTURE.md          # System design and principles
+│   ├── CODE_ORGANIZATION.md     # This file
+│   └── STANDARDS.md             # Coding standards and TDD rules
+│
+├── src/
+│   ├── features/                # Feature modules (domain-organized)
+│   │   ├── chat/                # Chat UI components
+│   │   │   ├── ChatLayout.ts
+│   │   │   ├── ChatLayout.test.ts
+│   │   │   └── index.ts
+│   │   │
+│   │   ├── config/              # Configuration and adapter
+│   │   │   ├── llxprtAdapter.ts
+│   │   │   ├── llxprtAdapter.test.ts
+│   │   │   └── index.ts
+│   │   │
+│   │   ├── markdown/            # Markdown rendering
+│   │   │   ├── StreamingMarkdown.ts
+│   │   │   ├── StreamingMarkdown.test.ts
+│   │   │   └── index.ts
+│   │   │
+│   │   └── tools/               # Tool display and approval
+│   │       ├── ToolDisplay.ts
+│   │       ├── ToolApproval.ts
+│   │       └── index.ts
+│   │
+│   ├── lib/                     # Shared utilities
+│   │   ├── logger.ts            # Logging (use this, not console)
+│   │   ├── logger.test.ts
+│   │   └── index.ts
+│   │
+│   ├── types/                   # Shared type definitions
+│   │   ├── events.ts            # AdapterEvent types
+│   │   └── index.ts
+│   │
+│   ├── renderer.ts              # opentui setup
+│   └── index.ts                 # Main entry point
+│
+├── themes/                      # UI themes
+│   └── default.json
+│
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+└── eslint.config.cjs
+```
+
+## Feature Module Pattern
+
+Each feature is a self-contained module:
+
+```
+features/
+  feature-name/
+    ├── index.ts              # Public exports only
+    ├── FeatureName.ts        # Main implementation
+    ├── FeatureName.test.ts   # Tests (colocated)
+    ├── types.ts              # Feature-specific types (if needed)
+    └── helpers.ts            # Internal helpers (if needed)
+```
+
+### Export Rules
+
+- `index.ts` exports ONLY the public API
+- Internal helpers are NOT exported
+- Tests import from the implementation file, not index
+
+```typescript
+// index.ts - public API only
+export { ChatLayout } from './ChatLayout';
+export type { ChatLayoutProps } from './ChatLayout';
+
+// ChatLayout.test.ts - imports implementation directly
+import { ChatLayout, internalHelper } from './ChatLayout';
+```
+
+## Naming Conventions
+
+### Files
+
+| Type              | Convention               | Example              |
+| ----------------- | ------------------------ | -------------------- |
+| Feature component | PascalCase               | `ChatLayout.ts`      |
+| Utility           | camelCase                | `logger.ts`          |
+| Types             | camelCase                | `events.ts`          |
+| Tests             | Same as source + `.test` | `ChatLayout.test.ts` |
+| Config            | camelCase                | `vitest.config.ts`   |
+
+### Code
+
+| Type       | Convention               | Example                     |
+| ---------- | ------------------------ | --------------------------- |
+| Classes    | PascalCase               | `class StreamingMarkdown`   |
+| Interfaces | PascalCase (no I prefix) | `interface AdapterEvent`    |
+| Types      | PascalCase               | `type EventHandler`         |
+| Functions  | camelCase                | `function transformEvent()` |
+| Variables  | camelCase                | `const eventBuffer`         |
+| Constants  | UPPER_SNAKE_CASE         | `const MAX_BUFFER_SIZE`     |
+
+## Import Order
+
+Imports must be ordered:
+
+1. Node.js built-ins
+2. External packages
+3. Internal absolute imports (if using aliases)
+4. Relative imports
+
+```typescript
+// 1. Node built-ins
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// 2. External packages
+import { GeminiClient } from '@vybestack/llxprt-code-core';
+
+// 3. Internal (relative)
+import { getLogger } from '../../lib/logger';
+import { transformEvent } from './helpers';
+```
+
+## Test Organization
+
+### Colocation
+
+Tests live next to the code they test:
+
+```
+ChatLayout.ts
+ChatLayout.test.ts   # Right next to it
+```
+
+### Test File Structure
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { functionUnderTest } from './module';
+
+describe('functionUnderTest', () => {
+  describe('when given valid input', () => {
+    it('should return expected result', () => {
+      // Arrange
+      const input = createTestInput();
+
+      // Act
+      const result = functionUnderTest(input);
+
+      // Assert
+      expect(result).toEqual(expectedOutput);
+    });
+  });
+
+  describe('when given invalid input', () => {
+    it('should return error result', () => {
+      // ...
+    });
+  });
+});
+```
+
+### Test Naming
+
+- Describe blocks: function/class name
+- Nested describes: conditions ("when...", "with...")
+- It blocks: behavior in plain English ("should...")
+
+## Types Location
+
+### Shared Types
+
+Types used across multiple features go in `src/types/`:
+
+```typescript
+// src/types/events.ts
+export type AdapterEvent =
+  | { type: 'text_delta'; text: string }
+  | { type: 'thinking_delta'; text: string }
+  | { type: 'tool_pending'; id: string; name: string }
+  | { type: 'complete' };
+```
+
+### Feature-Specific Types
+
+Types used only within a feature stay in that feature:
+
+```typescript
+// src/features/chat/types.ts
+export interface ChatLayoutProps {
+  onSubmit: (text: string) => void;
+  events: AdapterEvent[];
+}
+```
+
+## Adding a New Feature
+
+1. Create directory: `src/features/feature-name/`
+2. Write failing test: `FeatureName.test.ts`
+3. Create implementation: `FeatureName.ts`
+4. Create index: `index.ts` with public exports
+5. Add to parent index if needed
+
+## Dependencies
+
+### External Dependencies
+
+- `@vybestack/llxprt-code-core` - Backend integration
+- `opentui` - Terminal UI framework
+- `vitest` - Testing
+
+### Internal Dependencies
+
+Features should minimize cross-dependencies:
+
+```
+lib/           # No dependencies on features
+types/         # No dependencies on features or lib
+features/      # Can depend on lib and types
+              # Features should NOT depend on each other
+```
+
+If features need to communicate, use:
+
+- Events/callbacks passed through props
+- Shared types in `src/types/`
+- Coordination at the app level (`src/index.ts`)

package/dev-docs/STANDARDS.md

@@ -0,0 +1,235 @@
+# Development Standards for nui
+
+## Core Principle: Test-Driven Development is Mandatory
+
+**Every line of production code must be written in response to a failing test. No exceptions.**
+
+## Quick Reference
+
+### Must Do:
+
+- Write test first (RED) → Minimal code to pass (GREEN) → Refactor if valuable
+- Test behavior, not implementation
+- Use TypeScript strict mode (no `any`, no type assertions)
+- Use nui's Logger (`src/lib/logger.ts`) for all logging
+- Explicit return types on all functions
+- Run `npm run lint` and `npm run typecheck` before commits
+
+### Never Do:
+
+- Write production code without a failing test
+- Use `console.log`, `console.warn`, `console.error` (use Logger)
+- Use `any` type (use `unknown` with type guards)
+- Write "mock theater" tests that verify mock calls instead of behavior
+- Add comments (code must be self-documenting)
+- Create speculative abstractions
+
+## Technology Stack
+
+- **Language**: TypeScript (strict mode required)
+- **Testing**: Vitest
+- **UI Framework**: opentui (terminal UI)
+- **Backend Integration**: @vybestack/llxprt-code-core
+
+## TDD Process
+
+### Red-Green-Refactor (Follow Strictly)
+
+1. **RED**: Write a failing test for the next small behavior
+2. **GREEN**: Write ONLY enough code to make the test pass
+3. **REFACTOR**: Assess if refactoring adds value. If yes, improve. If no, move on.
+4. **COMMIT**: Feature + tests together, refactoring separately
+
+### Example TDD Flow
+
+```typescript
+// 1. RED - Test first
+describe('transformEvent', () => {
+  it('should convert Content event to text_delta', () => {
+    const input = { type: GeminiEventType.Content, value: 'hello' };
+    const result = transformEvent(input);
+    expect(result).toEqual({ type: 'text_delta', text: 'hello' });
+  });
+});
+
+// 2. GREEN - Minimal implementation
+function transformEvent(event: ServerGeminiStreamEvent): AdapterEvent {
+  if (event.type === GeminiEventType.Content) {
+    return { type: 'text_delta', text: event.value };
+  }
+  throw new Error(`Unknown event type: ${event.type}`);
+}
+
+// 3. REFACTOR - Only if it improves clarity
+// 4. COMMIT - "feat: add event transformation for Content type"
+```
+
+## TypeScript Rules
+
+### Required Practices
+
+```typescript
+// Explicit return types on all functions
+function calculateTotal(items: Item[]): number {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// Use unknown with type guards, not any
+function handleError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+// Use type predicates instead of assertions
+function isTextEvent(event: AdapterEvent): event is TextDeltaEvent {
+  return event.type === 'text_delta';
+}
+```
+
+### Forbidden Patterns
+
+```typescript
+// BAD: Using any
+function process(data: any) { ... }
+
+// BAD: Type assertions
+const user = data as User;
+
+// BAD: Non-null assertions
+const name = user!.name;
+
+// BAD: Console logging
+console.log("debug info");
+```
+
+## Testing Guidelines
+
+### What to Test
+
+- Public API behavior (input → output)
+- Edge cases and error conditions
+- Integration between units
+- Event transformations
+
+### What NOT to Test
+
+- Implementation details
+- Private methods
+- That mocks were called (mock theater)
+- Third-party library internals
+
+### Mock Theater (FORBIDDEN)
+
+```typescript
+// BAD: Testing that a mock was called
+it('should call database.find', () => {
+  const mockDb = { find: vi.fn() };
+  service.getUser('123');
+  expect(mockDb.find).toHaveBeenCalledWith('123');
+});
+
+// GOOD: Testing actual behavior
+it('should return user data for valid ID', () => {
+  const user = service.getUser('123');
+  expect(user).toEqual({ id: '123', name: 'Alice' });
+});
+```
+
+### Reverse Tests (FORBIDDEN)
+
+```typescript
+// BAD: Test that passes when code is wrong
+it('should not throw', () => {
+  expect(() => brokenFunction()).not.toThrow();
+});
+
+// GOOD: Test that verifies correct behavior
+it('should return calculated result', () => {
+  expect(calculate(2, 3)).toBe(5);
+});
+```
+
+### Stub Implementations (FORBIDDEN)
+
+```typescript
+// BAD: Stub that doesn't do anything
+function processMessage(msg: Message): void {
+  // TODO: implement
+}
+
+// GOOD: Real implementation or throw
+function processMessage(msg: Message): ProcessedMessage {
+  return { id: msg.id, processed: true, timestamp: Date.now() };
+}
+```
+
+## Logging
+
+Use nui's Logger for all logging:
+
+```typescript
+import { getLogger } from '../lib/logger';
+
+const logger = getLogger('nui:my-module');
+
+logger.debug('Processing started', { itemCount: items.length });
+logger.warn('Unexpected state', { state });
+logger.error('Operation failed', { error: err.message });
+```
+
+Logs go to `~/.llxprt/nuilog/nui.log`.
+
+## Error Handling
+
+### Use Explicit Error States
+
+```typescript
+// BAD: Throwing for control flow
+try {
+  const user = getUser(id);
+} catch (e) {
+  // Handle missing user
+}
+
+// GOOD: Explicit result types
+type Result<T> = { ok: true; value: T } | { ok: false; error: string };
+
+function getUser(id: string): Result<User> {
+  const user = users.get(id);
+  if (!user) {
+    return { ok: false, error: `User ${id} not found` };
+  }
+  return { ok: true, value: user };
+}
+```
+
+## Immutability
+
+```typescript
+// BAD: Mutation
+function addItem(cart: Cart, item: Item): Cart {
+  cart.items.push(item);
+  return cart;
+}
+
+// GOOD: Immutable
+function addItem(cart: Cart, item: Item): Cart {
+  return { ...cart, items: [...cart.items, item] };
+}
+```
+
+## Review Checklist
+
+Before submitting code, verify:
+
+- [ ] All tests pass (`npm test`)
+- [ ] No TypeScript errors (`npm run typecheck`)
+- [ ] No linting warnings (`npm run lint`)
+- [ ] No console.log or debug code
+- [ ] No stub implementations
+- [ ] No mock theater tests
+- [ ] Code is self-documenting
+- [ ] Follows immutability patterns
+- [ ] Error cases handled explicitly