mia-code 0.2.0 → 0.3.0

package/rispecs/_sync_/miadi-code/multiline-input/SPEC.md

@@ -0,0 +1,232 @@
+# RISE Specification: Multiline Input Handler
+
+## Status: IMPLEMENTED ✅
+
+**Version**: 1.0.0
+**Module**: `miadi-code/src/multiline-input.ts`
+**Document ID**: miadi-code-multiline-input-rise-spec-v1
+**Last Updated**: 2026-01-31
+
+---
+
+## Core Creative Intent
+
+The Multiline Input Handler enables CLI agent developers to create **rich, multiline text input experiences** in interactive terminal applications. This pattern supports:
+
+- **Ctrl+J** to add new lines without submitting
+- **Enter** to submit the complete multiline input
+- **Pasting** multiline content that gets properly collected
+- **Cursor navigation** with arrow keys
+- **TTY detection** with graceful fallback to readline
+
+---
+
+## R - Reverse Engineering
+
+### Problem Statement
+
+Standard Node.js `readline` fires on every line break, making it impossible to:
+1. Compose multiline prompts interactively
+2. Paste multiline content without immediate submission
+3. Use Ctrl+J (like many chat interfaces) to add lines
+
+### Solution Architecture
+
+```
+User Types/Pastes
+       ↓
+┌──────────────────────────────────────────────────────────────────────┐
+│                    MultilineInput (Raw Mode)                          │
+├──────────────────────────────────────────────────────────────────────┤
+│  process.stdin.setRawMode(true)                                       │
+│                                                                       │
+│  Character-by-character processing:                                   │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐      │
+│  │ Ctrl+J     │  │ Enter      │  │ Paste      │  │ Backspace  │      │
+│  │ → addLine  │  │ → submit   │  │ → collect  │  │ → delete   │      │
+│  └────────────┘  └────────────┘  └────────────┘  └────────────┘      │
+│                                                                       │
+│  Line Accumulator: ['line1', 'line2', ...] + currentLine              │
+└──────────────────────────────────────────────────────────────────────┘
+       ↓
+  onSubmit(fullInput: string)  // All lines joined with \n
+```
+
+### Core Dependencies
+
+| Dependency | Purpose |
+|------------|---------|
+| Node.js TTY | Raw mode input processing |
+| EventEmitter | State management |
+| chalk | Visual prompt styling |
+
+---
+
+## I - Intent Extraction
+
+### Primary Intent
+
+Enable natural multiline input in terminal applications where:
+
+1. Users compose complex prompts across multiple lines
+2. Users paste code blocks or structured content
+3. The interface feels like modern chat applications
+
+### User Stories
+
+1. **As a developer**, I want to write multiline prompts so I can provide detailed context to the AI.
+
+2. **As a user pasting code**, I want pasted content to be collected properly so newlines don't trigger premature submission.
+
+3. **As a power user**, I want Ctrl+J to add lines like in Slack/Discord so I can compose without reaching for the mouse.
+
+### Success Criteria
+
+- [x] Ctrl+J adds a new line without submitting
+- [x] Enter submits the complete input
+- [x] Pasted multiline content is collected properly
+- [x] Arrow keys navigate within the current line
+- [x] Backspace works across line boundaries
+- [x] Non-TTY fallback to readline
+- [x] Integration with CLI pause/resume for subcommands
+
+---
+
+## S - Specification
+
+### Class: MultilineInput
+
+```typescript
+interface MultilineInputOptions {
+  prompt: string;                    // Main prompt (e.g., "🌌 you> ")
+  continuationPrompt?: string;       // Continuation prompt (e.g., "... ")
+  maxLines?: number;                 // Maximum allowed lines (default: 100)
+  onSubmit: (input: string) => Promise<void>;  // Called with full input
+  onClose?: () => void;              // Called on Ctrl+D/exit
+}
+
+class MultilineInput extends EventEmitter {
+  // Lifecycle
+  start(): void;       // Begin listening in raw mode
+  stop(): void;        // Stop and cleanup
+  reset(): void;       // Clear state, show prompt
+  pause(): void;       // Pause for subcommands
+  resume(): void;      // Resume after pause
+}
+```
+
+### Key Bindings
+
+| Key | Char Code | Action |
+|-----|-----------|--------|
+| Enter | 13 | Submit all accumulated lines |
+| Ctrl+J | 10 | Add new line, continue input |
+| Ctrl+C | 3 | Cancel current input / Exit |
+| Ctrl+D | 4 | Exit (if empty) |
+| Ctrl+U | 21 | Clear current line |
+| Ctrl+W | 23 | Delete previous word |
+| Ctrl+L | 12 | Clear screen, redraw |
+| Backspace | 127/8 | Delete character / merge lines |
+| Arrow Left | \x1B[D | Move cursor left |
+| Arrow Right | \x1B[C | Move cursor right |
+
+### Paste Detection
+
+Paste is detected by receiving multiple characters in a single `data` event:
+
+```typescript
+private handleData = async (data: string): Promise<void> => {
+  // Paste detection: multiple chars without escape sequence
+  if (data.length > 1 && !data.startsWith('\x1B')) {
+    this.handlePaste(data);
+    return;
+  }
+  // Single character processing...
+};
+```
+
+### Visual Rendering
+
+```
+🌌 you> First line of my prompt
+... and this is a continuation
+... with multiple lines
+... [Enter to submit, Ctrl+J for more lines]
+```
+
+---
+
+## E - Export Optimization
+
+### Integration Pattern
+
+```typescript
+import { MultilineInput, supportsMultilineInput } from './multiline-input.js';
+
+if (supportsMultilineInput()) {
+  const input = new MultilineInput({
+    prompt: chalk.yellow('> '),
+    onSubmit: async (text) => {
+      console.log('Received:', text);
+    },
+    onClose: () => process.exit(0),
+  });
+  input.start();
+} else {
+  // Fallback to readline
+}
+```
+
+### Pause/Resume for Subcommands
+
+```typescript
+// Before launching dashboard or other interactive mode
+multilineInput.pause();
+
+await dashboard.start();
+
+// After dashboard exits
+multilineInput.resume();
+```
+
+### TTY Detection
+
+```typescript
+export function supportsMultilineInput(): boolean {
+  return process.stdin.isTTY === true;
+}
+```
+
+---
+
+## Testing
+
+### Unit Tests
+
+| Test | Description |
+|------|-------------|
+| Line accumulation | Combines lines with newlines |
+| Paste handling | Splits by \n and \r\n |
+| Cursor tracking | Insert/delete at position |
+| Character codes | Detects control characters |
+| Escape sequences | Detects arrow keys |
+
+### Test Location
+
+`miadi-code/src/multiline-input.test.ts` - 16 tests
+
+---
+
+## Known Limitations
+
+1. **History**: Arrow up/down for command history not yet implemented
+2. **Long lines**: No horizontal scrolling for lines exceeding terminal width
+3. **Terminal compatibility**: Some terminal multiplexers may have raw mode issues
+
+---
+
+## References
+
+- Implementation: `miadi-code/src/multiline-input.ts`
+- Tests: `miadi-code/src/multiline-input.test.ts`
+- CLI Integration: `miadi-code/src/cli.ts` (lines 198-354)

package/rispecs/_sync_/miadi-code/multiline-input/STATUS.md

@@ -0,0 +1,108 @@
+# Multiline Input Handler - STATUS
+
+**Version**: 1.0
+**Date**: 2026-01-31
+**Status**: ✅ IMPLEMENTED
+
+---
+
+## Implementation Checklist
+
+### ✅ Phase 1: Core Implementation (COMPLETE)
+- [x] Create `src/multiline-input.ts` - Main handler class
+- [x] Implement raw mode input processing
+- [x] Implement Ctrl+J for new line
+- [x] Implement Enter for submit
+- [x] Implement paste detection and collection
+- [x] Implement cursor navigation (left/right)
+- [x] Implement backspace across line boundaries
+- [x] Implement Ctrl+U (clear line), Ctrl+W (delete word)
+- [x] Implement TTY detection with `supportsMultilineInput()`
+
+### ✅ Phase 2: CLI Integration (COMPLETE)
+- [x] Update `src/cli.ts` to use MultilineInput when TTY available
+- [x] Implement fallback to readline for non-TTY
+- [x] Implement pause/resume for dashboard integration
+- [x] Add multiline hint to startup message
+
+### ✅ Phase 3: Testing (COMPLETE)
+- [x] Create `src/multiline-input.test.ts`
+- [x] Test line accumulation logic
+- [x] Test paste handling
+- [x] Test cursor position tracking
+- [x] Test character code detection
+- [x] Total: 16 tests passing
+
+---
+
+## Files Created
+
+| File | Purpose | Lines |
+|------|---------|-------|
+| `src/multiline-input.ts` | Main handler class | ~310 |
+| `src/multiline-input.test.ts` | Unit tests | ~115 |
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `src/cli.ts` | Added multiline input integration with fallback |
+
+---
+
+## Feature Summary
+
+### Key Bindings
+| Key | Action |
+|-----|--------|
+| Ctrl+J | Add new line |
+| Enter | Submit input |
+| Ctrl+C | Cancel/Exit |
+| Ctrl+U | Clear line |
+| Ctrl+W | Delete word |
+| Backspace | Delete char / merge lines |
+| ← → | Navigate cursor |
+
+### Capabilities
+| Feature | Status |
+|---------|--------|
+| Multiline composition | ✅ |
+| Paste handling | ✅ |
+| TTY detection | ✅ |
+| Readline fallback | ✅ |
+| Pause/resume | ✅ |
+| Visual continuation prompt | ✅ |
+
+---
+
+## Test Coverage
+
+```
+Multiline Input Logic
+  Line accumulation
+    ✓ should combine multiple lines with newlines
+    ✓ should trim final result
+    ✓ should handle empty input
+  Paste handling simulation
+    ✓ should split pasted content by newlines
+    ✓ should handle Windows line endings
+    ✓ should handle mixed line endings
+  Cursor position tracking
+    ✓ should insert character at cursor position
+    ✓ should handle backspace at cursor
+    ✓ should handle delete word
+  Character code detection
+    ✓ should detect Ctrl+J (newline)
+    ✓ should detect Ctrl+C
+    ✓ should detect Enter (carriage return)
+    ✓ should detect Backspace
+    ✓ should detect printable characters
+  Escape sequence detection
+    ✓ should detect arrow key sequences
+Multiline Input TTY Detection
+    ✓ should check for isTTY property
+```
+
+---
+
+**Last Updated**: 2026-01-31T20:15:00Z

package/rispecs/_sync_/miadi-code/pde/SPEC.md

@@ -0,0 +1,253 @@
+# RISE Specification: PDE (Prompt Decomposition Engine)
+
+## Status: IMPLEMENTED ✅
+
+**Version**: 1.0.0
+**Module**: `miadi-code/src/pde/`
+**Last Updated**: 2026-01-30
+
+---
+
+## R - Reverse Engineering
+
+### Current State Analysis
+
+The PDE module implements a 5-layer decomposition pipeline based on academic research from the PDE Generalization literature survey. It transforms complex, multi-intent prompts into structured, executable workflows.
+
+### File Structure
+
+```
+miadi-code/src/pde/
+├── pde-types.ts          # TypeScript interfaces for all layers
+├── intent-extractor.ts   # Layer 1: Intent extraction & classification
+├── dependency-analyzer.ts # Layer 2: Dependency graph construction
+├── medicine-wheel-mapper.ts # Layer 3: Medicine Wheel direction mapping
+├── workflow-generator.ts # Layer 4: Workflow template generation
+├── execution-planner.ts  # Layer 5: Execution plan with checkpoints
+├── decomposer.ts         # Main orchestrator
+├── pde-commands.ts       # CLI command handlers
+└── index.ts              # Module exports
+```
+
+### Architecture
+
+```
+User Prompt
+    ↓
+┌─────────────────────────────────────────────────────────────┐
+│                  PDE Decomposition Pipeline                  │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 1: Intent Extraction                                  │
+│    • Extract explicit intents (action verbs + targets)       │
+│    • Discover implicit intents (assumptions, expectations)   │
+│    • Classify by type (CREATION, MODIFICATION, etc.)         │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 2: Dependency Analysis                                │
+│    • Build dependency graph from intent relationships        │
+│    • Detect prerequisite, blocker, data_flow edges           │
+│    • Generate topological execution order                    │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 3: Medicine Wheel Mapping                             │
+│    • Map intents to Four Directions (EAST/SOUTH/WEST/NORTH)  │
+│    • Assign ceremony types (vision_inquiry, wave_counting...)│
+│    • Validate ceremonial order                               │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 4: Workflow Generation                                │
+│    • Group intents into workflow stages                      │
+│    • Mark parallel vs sequential execution                   │
+│    • Add checkpoint markers                                  │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 5: Execution Planning                                 │
+│    • Generate CLI commands for each task                     │
+│    • Define success criteria and fallback strategies         │
+│    • Create progress checkpoints                             │
+└─────────────────────────────────────────────────────────────┘
+    ↓
+Structured DecomposedPrompt Object
+```
+
+---
+
+## I - Intent Extraction
+
+### Primary Intent
+
+Transform complex, multi-intent user prompts into structured, actionable workflows that prevent:
+- Implicit intention blindness
+- Context fragmentation
+- Sequential dependency failures
+
+### User Stories
+
+1. **As a developer** using miadi-code, I want complex prompts automatically decomposed so I don't miss secondary requirements.
+
+2. **As an AI agent**, I need prompt decomposition to understand multi-step tasks and track progress through checkpoints.
+
+3. **As a ceremonial practitioner**, I want workflow stages mapped to Medicine Wheel directions for epistemological awareness.
+
+### Success Criteria
+
+- [x] Extracts both explicit and implicit intents from natural language
+- [x] Builds dependency graphs that identify parallel execution opportunities
+- [x] Maps all intents to ceremonial directions
+- [x] Generates workflow templates with checkpoints
+- [x] Produces execution plans with success criteria and fallbacks
+- [x] CLI accessible via `/pde` commands
+
+---
+
+## S - Specification
+
+### Layer 1: Intent Extraction
+
+**Input**: Raw prompt string
+**Output**: `IntentExtractionResult`
+
+```typescript
+interface IntentExtractionResult {
+  explicitIntents: ExplicitIntent[];   // Action + target + constraints
+  implicitIntents: ImplicitIntent[];   // Inferred requirements
+  classifiedIntents: ClassifiedIntent[]; // Typed intents
+  originalPrompt: string;
+  timestamp: string;
+}
+```
+
+**Intent Types**:
+- `CREATION` - Generate new artifacts
+- `MODIFICATION` - Update existing resources
+- `ANALYSIS` - Investigate, understand
+- `VALIDATION` - Test, verify
+- `INTEGRATION` - Connect, deploy
+- `COMMUNICATION` - Notify, report
+
+### Layer 2: Dependency Analysis
+
+**Input**: `ClassifiedIntent[]`
+**Output**: `DependencyGraph`
+
+```typescript
+interface DependencyGraph {
+  nodes: Map<string, DependencyNode>;
+  edges: DependencyEdge[];
+  hasCycles: boolean;
+  maxDepth: number;
+  executionOrder: string[][]; // Grouped by parallel stages
+}
+```
+
+**Edge Types**:
+- `prerequisite` - Must complete before
+- `blocker` - Cannot run in parallel
+- `enabler` - Optional path enabler
+- `data_flow` - Output becomes input
+
+### Layer 3: Medicine Wheel
+
+**Input**: `ClassifiedIntent[]`
+**Output**: `MedicineWheelAssignment[]`
+
+| Direction | Ceremony | Focus |
+|-----------|----------|-------|
+| EAST | vision_inquiry | Exploration, questions |
+| SOUTH | wave_counting | Data gathering, building |
+| WEST | talking_circles | Validation, reflection |
+| NORTH | elder_council | Action, completion |
+
+### Layer 4: Workflow Generation
+
+**Input**: Intents + Graph + Wheel assignments
+**Output**: `WorkflowTemplate`
+
+```typescript
+interface WorkflowTemplate {
+  workflowId: string;
+  name: string;
+  stages: WorkflowStage[];
+  totalTasks: number;
+  createdAt: string;
+}
+```
+
+### Layer 5: Execution Planning
+
+**Input**: `WorkflowTemplate`
+**Output**: `ExecutionPlan`
+
+```typescript
+interface ExecutionPlan {
+  planId: string;
+  tasks: ExecutionTask[];
+  checkpoints: ExecutionCheckpoint[];
+  totalSteps: number;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  requiredTools: string[];
+}
+```
+
+---
+
+## E - Export Optimization
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `/pde decompose "prompt"` | Full 5-layer decomposition |
+| `/pde quick "prompt"` | Summary workflow view |
+| `/pde intents "prompt"` | Layer 1 only |
+| `/pde deps "prompt"` | Layer 2 only |
+| `/pde wheel "prompt"` | Layer 3 only |
+| `/pde workflow "prompt"` | Layer 4 only |
+| `/pde plan "prompt"` | Layer 5 only |
+| `/pde check "prompt"` | Complexity analysis |
+| `/pde ceremony [type]` | Ceremony requirements |
+| `/pde export [format]` | Export (json/yaml/md) |
+| `/pde last` | Show last decomposition |
+
+### Export Formats
+
+- **JSON**: Full structured output
+- **YAML**: Workflow-as-code format
+- **Markdown**: Human-readable checklist
+
+### Programmatic API
+
+```typescript
+import { 
+  decomposePrompt, 
+  formatDecomposition,
+  isComplexPrompt 
+} from './pde/index.js';
+
+// Check complexity
+if (isComplexPrompt(userInput)) {
+  const result = decomposePrompt(userInput);
+  console.log(formatDecomposition(result));
+}
+```
+
+---
+
+## Implementation Notes
+
+### Academic Grounding
+
+Based on PDE Generalization literature survey:
+- Chain-of-Thought prompting for reasoning
+- Decomposed Prompting for modularity
+- Tree-of-Thoughts for dependency exploration
+- ReAct pattern for reasoning + action
+
+### Integration Points
+
+1. **CLI Integration**: `/pde` command in `cli.ts`
+2. **Help Text**: Added to `formatting.ts`
+3. **Module Exports**: Full API via `index.ts`
+
+### Future Enhancements
+
+- [ ] LLM-powered intent extraction (beyond pattern matching)
+- [ ] Integration with workflow execution engine
+- [ ] Persistent decomposition storage
+- [ ] Interactive workflow editing

package/rispecs/_sync_/miadi-code/pde/STATUS.md

@@ -0,0 +1,56 @@
+# PDE Module Status
+
+## Implementation Status: ✅ COMPLETE
+
+**Module**: `miadi-code/src/pde/`
+**Version**: 1.0.0
+**Date**: 2026-01-30
+
+---
+
+## Files Implemented
+
+| File | Purpose | Status |
+|------|---------|--------|
+| `pde-types.ts` | TypeScript interfaces | ✅ Complete |
+| `intent-extractor.ts` | Layer 1: Intent extraction | ✅ Complete |
+| `dependency-analyzer.ts` | Layer 2: Dependency graphs | ✅ Complete |
+| `medicine-wheel-mapper.ts` | Layer 3: Ceremonial mapping | ✅ Complete |
+| `workflow-generator.ts` | Layer 4: Workflow templates | ✅ Complete |
+| `execution-planner.ts` | Layer 5: Execution plans | ✅ Complete |
+| `decomposer.ts` | Main orchestrator | ✅ Complete |
+| `pde-commands.ts` | CLI command handlers | ✅ Complete |
+| `index.ts` | Module exports | ✅ Complete |
+
+## CLI Integration
+
+- [x] `/pde` command routing in `cli.ts`
+- [x] Help text added to `formatting.ts`
+- [x] Build passes
+
+## Commands Available
+
+```
+/pde decompose "prompt"  - Full 5-layer decomposition
+/pde quick "prompt"      - Summary workflow view  
+/pde intents "prompt"    - Intent extraction only
+/pde deps "prompt"       - Dependency graph only
+/pde wheel "prompt"      - Medicine Wheel mapping
+/pde workflow "prompt"   - Workflow template
+/pde plan "prompt"       - Execution plan
+/pde check "prompt"      - Complexity check
+/pde ceremony [type]     - Ceremony requirements
+/pde export [format]     - Export (json/yaml/md)
+/pde last                - Show last decomposition
+```
+
+## Testing Status
+
+- [ ] Manual testing with sample prompts
+- [ ] Integration with workflow execution
+- [ ] Persistence of decompositions
+
+## Related Documentation
+
+- RISE Spec: `rispecs/PDE_SPEC.md`
+- Academic grounding: `/src/IAIP/prototypes/artefacts/PDE-generalization--*/CONTENT.md`