mia-code 0.2.0 → 0.3.0

package/rispecs/engines.rispecs.md

@@ -0,0 +1,241 @@
+# mia-code Engines Specification
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/engines.rispecs.md
+
+## Creative Intent
+
+mia-code enables developers to create seamless multi-engine agent workflows where the choice of underlying AI engine (Gemini or Claude) becomes a configuration concern rather than an interface barrier. Users achieve optimal tool selection for their task context while maintaining consistent ceremonial output format.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Gemini CLI and Claude CLI have different argument syntaxes and output formats
+- YOLO/auto-approval flags differ between engines (`--yolo` vs `--dangerously-skip-permissions`)
+- Output format handling requires engine-specific parsing
+- System prompt support varies (Claude supports `--system-prompt`, Gemini does not)
+
+**Desired Structural State:**
+- Single unified interface abstracts engine differences
+- Users specify engine preference; system handles translation
+- Output normalization produces consistent `GeminiJsonEvent` stream
+- Unifier layer always functions regardless of primary engine choice
+
+## Engine Architecture
+
+### Engine Selection Flow
+
+```
+User specifies engine preference
+    ↓ (--claude, --gemini, config, or env var)
+Config resolves engine: "gemini" | "claude"
+    ↓
+Binary selection: config.geminiBinary or config.claudeBinary
+    ↓
+Argument translation layer applies engine-specific flags
+    ↓
+Child process spawned with translated arguments
+    ↓
+Output parser normalizes events to GeminiJsonEvent format
+```
+
+## Components
+
+### Engine Configuration
+
+**Description:** Multi-source engine preference resolution.
+
+**Behavior:**
+- CLI flag highest priority: `--claude` or `--gemini`
+- Environment variable: `MIA_CODE_ENGINE=claude`
+- Config file: `~/.mia-code.json` → `engine` field
+- Default fallback: `gemini`
+
+**Resolution Order:**
+1. CLI flag (`opts.claude` → "claude", `opts.gemini` → "gemini")
+2. Environment variable (`process.env.MIA_CODE_ENGINE`)
+3. Config file (`loadConfig().engine`)
+4. Default: `"gemini"`
+
+### Argument Translation
+
+**Description:** Engine-specific flag transformation.
+
+**Gemini CLI Arguments:**
+```bash
+gemini <prompt> \
+  --output-format stream-json \
+  --model gemini-2.5-pro \
+  --yolo \                       # Auto-approval
+  --resume <sessionId>
+```
+
+**Claude CLI Arguments:**
+```bash
+claude <prompt> \
+  --print \                      # Non-interactive mode
+  --output-format json \         # Note: stream-json requires --verbose
+  --model sonnet \
+  --dangerously-skip-permissions \  # Auto-approval equivalent
+  --resume <sessionId>
+```
+
+**Translation Logic:**
+```typescript
+const args: string[] = [prompt];
+
+if (config.engine === "claude") {
+  args.push("--print");
+  // Claude --print with stream-json requires --verbose; use json instead
+  const outputFormat = config.headlessOutputFormat === "stream-json" 
+    ? "json" 
+    : config.headlessOutputFormat;
+  args.push("--output-format", outputFormat);
+} else {
+  args.push("--output-format", config.headlessOutputFormat);
+}
+
+if (config.yoloMode) {
+  if (config.engine === "claude") {
+    args.push("--dangerously-skip-permissions");
+  } else {
+    args.push("--yolo");
+  }
+}
+```
+
+### Stdio Configuration
+
+**Description:** Engine-specific stdin handling.
+
+**Behavior:**
+- Claude `--print` mode needs stdin closed: `stdio: ["ignore", "pipe", "pipe"]`
+- Gemini interactive mode needs stdin open: `stdio: ["pipe", "pipe", "pipe"]`
+
+### Output Parsing
+
+**Description:** Normalize engine-specific output formats to unified event stream.
+
+**Gemini stream-json:**
+- Line-delimited JSON (JSONL)
+- Each line is a complete `GeminiJsonEvent`
+- Session ID in `session_id` field
+
+**Claude json:**
+- Single JSON object (not line-delimited)
+- Structure: `{ type: "result", result: "text", session_id: "..." }`
+- Requires buffering until process closes
+
+**Normalization Logic:**
+```typescript
+if (isClaudeJsonMode) {
+  // Buffer entire response, parse on close
+  child.on("close", () => {
+    const obj = JSON.parse(stdoutBuf);
+    if (obj.type === "result" && obj.result) {
+      events.push({
+        type: "message",
+        role: "assistant",
+        text: obj.result,
+        session_id: obj.session_id
+      });
+    }
+  });
+} else {
+  // Parse JSONL line-by-line
+  const lines = stdoutBuf.split("\n");
+  for (const line of lines) {
+    const evt = JSON.parse(line.trim());
+    events.push(evt);
+  }
+}
+```
+
+## Data
+
+### Engine-Specific Defaults
+
+| Setting | Gemini | Claude |
+|---------|--------|--------|
+| Default Model | `gemini-2.5-pro` | `sonnet` |
+| Output Format | `stream-json` | `json` (for --print) |
+| Auto-Approval | `--yolo` | `--dangerously-skip-permissions` |
+| Non-Interactive | (default) | `--print` |
+| System Prompt | Not supported | `--system-prompt` |
+
+### Environment Variables
+
+```bash
+MIA_CODE_ENGINE=gemini|claude    # Default engine
+MIA_CODE_GEMINI_BIN=/path/to/gemini  # Custom gemini binary
+MIA_CODE_CLAUDE_BIN=/path/to/claude  # Custom claude binary
+MIA_CODE_MODEL=model-name        # Override model
+```
+
+## Creative Advancement Scenarios
+
+### Creative Advancement Scenario: Engine-Optimized Workflow
+
+**Desired Outcome:** Developer uses Claude's reasoning for complex analysis, Gemini for fast iteration
+
+**Current Structural Reality:** Different CLIs with different invocation patterns
+
+**Natural Progression:**
+1. User configures default engine via `mia-code config --set-engine gemini`
+2. For specific tasks requiring Claude, user adds `--claude` flag
+3. Engine translation layer handles argument differences transparently
+4. Output normalization ensures consistent event structure
+5. Unifier always uses Claude (system-prompt requirement)
+
+**Achieved Outcome:** Developer optimizes engine selection per-task while maintaining consistent experience
+
+### Creative Advancement Scenario: Auto-Approval Mode
+
+**Desired Outcome:** Developer enables automated action approval for trusted workflows
+
+**Current Structural Reality:** YOLO flags differ between engines
+
+**Natural Progression:**
+1. User specifies `--yolo` or configures `yoloMode: true`
+2. Engine translation applies correct flag per engine
+3. Agent executes without approval prompts
+4. Actions complete faster with reduced interaction friction
+
+**Achieved Outcome:** Trusted workflows execute without interruption regardless of engine choice
+
+## Supporting Structures
+
+### Unifier Engine Constraint
+
+**Why Claude for Unifier?**
+The unifier session always uses Claude because:
+- Gemini CLI lacks `--system-prompt` flag
+- Without it, system instructions leak into output
+- Claude's `--system-prompt` keeps ceremonial instructions separate from response
+
+**Implementation:**
+```typescript
+// Unifier always uses Claude
+const binary = config.claudeBinary;
+const args = [
+  sessionSummary,
+  "--print",
+  "--dangerously-skip-permissions",
+  "--output-format", "json",
+  "--system-prompt", UNIFIER_SYSTEM_PROMPT,
+  "--model", config.model.includes("gemini") ? "sonnet" : config.model
+];
+```
+
+## Advancing Patterns
+
+1. **Engine Abstraction:** Single interface hides implementation differences
+2. **Model Auto-Mapping:** Engine change auto-selects appropriate default model
+3. **Output Normalization:** Consistent event structure regardless of source
+4. **Unifier Independence:** Ceremonial layer functions with any primary engine
+
+## Implementation Reference
+
+- **Engine Wrapper:** `src/geminiHeadless.ts` - `runGeminiHeadless()`, `streamGemini()`
+- **Config Resolution:** `src/config.ts` - Engine and binary path defaults
+- **CLI Options:** `src/index.ts` - `--claude`, `--gemini` flags

package/rispecs/formatting.rispecs.md

@@ -0,0 +1,252 @@
+# mia-code Formatting Specification
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/formatting.rispecs.md
+
+## Creative Intent
+
+mia-code enables developers to create readable, aesthetically consistent terminal output that reduces cognitive load. Users achieve immediate understanding of session state, errors, and results through carefully designed visual hierarchy using chalk-based styling.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Terminal output is plain text without visual hierarchy
+- Errors, success, and information blend together
+- Session metadata competes with primary content for attention
+- Agent response boundaries are unclear
+
+**Desired Structural State:**
+- Clear visual hierarchy separates metadata from content
+- Errors immediately visible through color and symbols
+- Success confirmations provide positive feedback
+- Ceremonial output (🧠/🌸) stands out as primary content
+
+## Formatting Architecture
+
+### Color Semantics
+
+| Element | Color | Chalk Function | Symbol |
+|---------|-------|----------------|--------|
+| User prompt | Yellow | `chalk.yellow()` | `you>` |
+| Session metadata | Dim | `chalk.dim()` | - |
+| Agent header | Green bold | `chalk.green.bold()` | 🧠🌸 |
+| Error | Red | `chalk.red()` | ❌ |
+| Success | Green | `chalk.green()` | ✓ |
+| Warning | Yellow | `chalk.yellow()` | ⚠ |
+| Tool events | Magenta | `chalk.magenta()` | 🔧/✓ |
+| Processing | Dim | `chalk.dim()` | ⏳ |
+
+## Components
+
+### Event Renderer
+
+**Description:** Transforms `GeminiJsonEvent[]` into formatted terminal output.
+
+**Behavior:**
+- Consolidates consecutive assistant messages
+- Applies event-type-specific formatting
+- Supports compact mode for minimal output
+- Optional tool event and timestamp display
+
+**Implementation:**
+```typescript
+function renderEventsToText(
+  events: GeminiJsonEvent[],
+  opts: RenderOptions = {}
+): string {
+  const { showRawToolEvents = false, showTimestamps = false, compact = false } = opts;
+  const out: string[] = [];
+  let assistantTextBuffer: string[] = [];
+  
+  const flushAssistantBuffer = () => {
+    if (assistantTextBuffer.length > 0) {
+      const fullText = assistantTextBuffer.join("").trim();
+      if (fullText) {
+        out.push(formatAssistantText(fullText, compact));
+      }
+      assistantTextBuffer = [];
+    }
+  };
+
+  for (const evt of events) {
+    switch (evt.type) {
+      case "init":
+        flushAssistantBuffer();
+        out.push(chalk.dim(`🧠🌸 session init${sid}${ts}`));
+        break;
+      case "message":
+        if (evt.role === "assistant") {
+          assistantTextBuffer.push(content);
+        } else if (evt.role === "user") {
+          flushAssistantBuffer();
+          out.push(chalk.cyan.bold(`you:`));
+          out.push(chalk.cyan(evt.text || evt.content || ""));
+        }
+        break;
+      case "tool_use":
+        flushAssistantBuffer();
+        if (showRawToolEvents) {
+          out.push(chalk.magenta(`🔧 tool_use: ${toolName}`));
+        }
+        break;
+      // ... other event types
+    }
+  }
+  
+  flushAssistantBuffer();
+  return out.join("\n");
+}
+```
+
+### Assistant Text Formatter
+
+**Description:** Formats assistant response text with ceremonial header.
+
+**Behavior:**
+- Detects if agent self-formatted with `🧠🌸 miawa:` prefix
+- Adds prefix if not present
+- Respects compact mode
+
+**Implementation:**
+```typescript
+function formatAssistantText(text: string, compact: boolean): string {
+  const trimmed = text.trim();
+  if (!trimmed) return "";
+
+  const hasPrefix = trimmed.startsWith("🧠🌸 miawa:");
+  
+  if (compact || hasPrefix) {
+    return trimmed;
+  }
+
+  return [chalk.green.bold("🧠🌸 miawa:"), "", trimmed].join("\n");
+}
+```
+
+### Header Formatter
+
+**Description:** Generates session header with project and engine info.
+
+**Output Format:**
+```
+🧠🌸 mia-code — Gemini-backed terminal agent
+project: /path/to/project
+session: abc123def456...
+```
+
+**Implementation:**
+```typescript
+function formatHeader(projectRoot: string, sessionId?: string, engine?: string): string {
+  const lines: string[] = [];
+  const engineName = engine === "claude" ? "Claude" : "Gemini";
+  lines.push(chalk.bold(`🧠🌸 mia-code — ${engineName}-backed terminal agent`));
+  lines.push(chalk.dim(`project: ${projectRoot}`));
+  if (sessionId) {
+    lines.push(chalk.dim(`session: ${sessionId.slice(0, 12)}...`));
+  }
+  return lines.join("\n");
+}
+```
+
+### Status Formatters
+
+**Description:** Consistent formatting for status messages.
+
+```typescript
+function formatSpinner(message: string): string {
+  return chalk.dim(`⏳ ${message}`);
+}
+
+function formatError(message: string): string {
+  return chalk.red(`❌ ${message}`);
+}
+
+function formatSuccess(message: string): string {
+  return chalk.green(`✓ ${message}`);
+}
+```
+
+### Help Text Formatter
+
+**Description:** Formatted slash command reference.
+
+**Output:**
+```
+Commands:
+  /exit, /quit     Exit the CLI
+  /session         Show current session info
+  /sessions        List all sessions
+  /clear           Clear session for current project
+  /config          Show configuration
+  /help            Show this help
+
+Note: By default, output is interpreted through the Miawa Unifier.
+      Use --raw flag to see uninterpreted agent output.
+```
+
+## Data
+
+### RenderOptions
+
+```typescript
+interface RenderOptions {
+  showRawToolEvents?: boolean;  // Display tool use/result events
+  showTimestamps?: boolean;     // Include event timestamps
+  compact?: boolean;            // Minimal output mode
+}
+```
+
+## Creative Advancement Scenarios
+
+### Creative Advancement Scenario: Clear Error Communication
+
+**Desired Outcome:** Developer immediately understands error context
+
+**Current Structural Reality:** Error occurred during agent execution
+
+**Natural Progression:**
+1. Error event parsed from agent stream
+2. Error code and message extracted
+3. Red color and ❌ symbol applied
+4. Error displayed prominently
+
+**Achieved Outcome:**
+```
+❌ gemini exited with code 1
+TypeScript compilation failed: Cannot find module 'missing-dep'
+```
+
+### Creative Advancement Scenario: Session Context Visibility
+
+**Desired Outcome:** Developer knows current project and session state
+
+**Current Structural Reality:** Starting interactive session
+
+**Natural Progression:**
+1. Header formatter receives project root and session ID
+2. Engine name resolved from config
+3. Styled header with metadata displayed
+
+**Achieved Outcome:**
+```
+🧠🌸 mia-code — Gemini-backed terminal agent
+project: /home/user/my-project
+session: abc123def456...
+new session will be created on first prompt
+type /help for commands, ctrl+c to exit
+```
+
+## Advancing Patterns
+
+1. **Visual Hierarchy:** Color and symbols create immediate recognition
+2. **Metadata Dimming:** Session info visible but not distracting
+3. **Ceremonial Prominence:** 🧠🌸 content is visually primary
+4. **Consistent Symbolism:** Same symbols always mean same things
+
+## Implementation Reference
+
+- **Formatting Module:** `src/formatting.ts`
+- **Event Rendering:** `renderEventsToText()`
+- **Header:** `formatHeader()`
+- **Status:** `formatError()`, `formatSuccess()`, `formatSpinner()`
+- **Help:** `formatHelpText()`