mia-code 0.2.0 → 0.3.0

package/miatel/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mia-code/miatel",
+  "version": "0.1.0",
+  "description": "Miatel: Story World terminal agent for narrative intelligence operations",
+  "bin": {
+    "miatel": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "npx tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "author": "Guillaume D. Isabelle",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "coaiajs": "^0.1.0",
+    "commander": "^12.0.0",
+    "enquirer": "^2.4.1",
+    "ora": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "narrative-intelligence",
+    "storytelling",
+    "story-world",
+    "mia-code",
+    "terminal-agent"
+  ]
+}

package/miatel/src/commands/analyze.ts

@@ -0,0 +1,109 @@
+/**
+ * Analyze command - Story analysis operations
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+
+export const analyzeCommand = new Command("analyze")
+  .description("Story analysis operations (connects to narrative-intelligence)");
+
+analyzeCommand
+  .command("coherence")
+  .description("Analyze narrative coherence across all dimensions")
+  .option("-s, --session <id>", "Session ID")
+  .option("--dimension <dim>", "Specific dimension (flow, character, pacing, theme, continuity)")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Coherence Analysis"));
+    console.log(chalk.dim(`Session: ${opts.session || "current"}`));
+    console.log(chalk.dim(`Dimension: ${opts.dimension || "all"}`));
+    console.log();
+    
+    // Mock coherence output matching NarrativeCoherenceEngine
+    console.log(chalk.bold("  Coherence Scores:"));
+    console.log(chalk.dim("    Narrative Flow:      -- /100"));
+    console.log(chalk.dim("    Character Consistency: -- /100"));
+    console.log(chalk.dim("    Pacing:              -- /100"));
+    console.log(chalk.dim("    Theme Saturation:    -- /100"));
+    console.log(chalk.dim("    Continuity:          -- /100"));
+    console.log(chalk.dim("    ─────────────────────────"));
+    console.log(chalk.dim("    Overall:             -- /100"));
+    console.log();
+    console.log(chalk.yellow("⚠ No story data to analyze. Add beats first."));
+  });
+
+analyzeCommand
+  .command("gaps")
+  .description("Identify quality gaps in the narrative")
+  .option("-s, --session <id>", "Session ID")
+  .option("--severity <level>", "Filter by severity (critical, major, minor)")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Gap Analysis"));
+    console.log(chalk.dim(`Session: ${opts.session || "current"}`));
+    console.log(chalk.dim(`Severity filter: ${opts.severity || "all"}`));
+    console.log();
+    console.log(chalk.green("✓ No gaps identified (or no data to analyze)."));
+  });
+
+analyzeCommand
+  .command("trinity")
+  .description("Get Trinity assessment (Mia/Miette/Ava8 perspectives)")
+  .option("-s, --session <id>", "Session ID")
+  .option("-b, --beat <id>", "Specific beat ID (optional)")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Trinity Assessment"));
+    console.log(chalk.dim(`Session: ${opts.session || "current"}`));
+    if (opts.beat) {
+      console.log(chalk.dim(`Beat: ${opts.beat}`));
+    }
+    console.log();
+    
+    console.log(chalk.bold("  🧠 Mia (Structure):"));
+    console.log(chalk.dim("    No structural analysis available yet."));
+    console.log();
+    console.log(chalk.bold("  🌸 Miette (Resonance):"));
+    console.log(chalk.dim("    No emotional analysis available yet."));
+    console.log();
+    console.log(chalk.bold("  🎨 Ava8 (Atmosphere):"));
+    console.log(chalk.dim("    No sensory analysis available yet."));
+  });
+
+analyzeCommand
+  .command("three-universe")
+  .description("Analyze through three-universe lens")
+  .requiredOption("-b, --beat <id>", "Beat ID to analyze")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Three-Universe Analysis"));
+    console.log(chalk.dim(`Beat: ${opts.beat}`));
+    console.log();
+    
+    console.log(chalk.bold("  🔧 Engineer World:"));
+    console.log(chalk.dim("    Schema valid: --"));
+    console.log(chalk.dim("    Types correct: --"));
+    console.log();
+    console.log(chalk.bold("  🙏 Ceremony World:"));
+    console.log(chalk.dim("    K'é honored: --"));
+    console.log(chalk.dim("    Sacred pause: --"));
+    console.log();
+    console.log(chalk.bold("  📖 Story Engine World:"));
+    console.log(chalk.dim("    Arc coherent: --"));
+    console.log(chalk.dim("    Theme threads: --"));
+    console.log();
+    console.log(chalk.yellow("⚠ Beat not found. Check ID and try again."));
+  });
+
+analyzeCommand
+  .command("arc-completeness")
+  .description("Check narrative arc completeness")
+  .option("-s, --session <id>", "Session ID")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Arc Completeness"));
+    console.log(chalk.dim(`Session: ${opts.session || "current"}`));
+    console.log();
+    console.log(chalk.dim("  Act 1 (Setup):        0%"));
+    console.log(chalk.dim("  Act 2 (Confrontation): 0%"));
+    console.log(chalk.dim("  Act 3 (Resolution):   0%"));
+    console.log();
+    console.log(chalk.dim("  Missing elements: --"));
+    console.log(chalk.dim("  Suggested next: Add initial beats"));
+  });

package/miatel/src/commands/arc.ts

@@ -0,0 +1,78 @@
+/**
+ * Arc command - Character arc tracking operations
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+
+export const arcCommand = new Command("arc")
+  .description("Character arc tracking operations");
+
+arcCommand
+  .command("init")
+  .description("Initialize tracking for a character")
+  .requiredOption("-n, --name <name>", "Character name")
+  .option("--wound <wound>", "Character's core wound")
+  .option("--desire <desire>", "Character's deep desire")
+  .option("--role <role>", "Role in story (protagonist, antagonist, mentor, etc.)")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Initializing Character Arc"));
+    console.log(chalk.dim(`Name: ${opts.name}`));
+    console.log(chalk.dim(`Wound: ${opts.wound || "undefined"}`));
+    console.log(chalk.dim(`Desire: ${opts.desire || "undefined"}`));
+    console.log(chalk.dim(`Role: ${opts.role || "supporting"}`));
+    console.log();
+    
+    const charId = opts.name.toLowerCase().replace(/\s+/g, '_');
+    console.log(chalk.green(`✓ Character arc initialized: ${charId}`));
+  });
+
+arcCommand
+  .command("list")
+  .description("List tracked character arcs")
+  .action(async () => {
+    console.log(chalk.bold("🌸 Character Arcs"));
+    console.log(chalk.dim("No characters tracked. Use `miatel arc init` to add one."));
+  });
+
+arcCommand
+  .command("progress")
+  .description("Show character arc progress")
+  .argument("<characterId>", "Character ID")
+  .action(async (characterId) => {
+    console.log(chalk.bold(`🌸 Arc Progress: ${characterId}`));
+    console.log(chalk.dim("Position: 0% (beginning)"));
+    console.log(chalk.dim("Arc points: 0"));
+    console.log(chalk.dim("Direction: static"));
+    console.log();
+    console.log(chalk.yellow("⚠ Character not found. Use `miatel arc list` to see available."));
+  });
+
+arcCommand
+  .command("record")
+  .description("Record a beat's impact on character arc")
+  .requiredOption("-c, --character <id>", "Character ID")
+  .requiredOption("-b, --beat <id>", "Beat ID")
+  .option("--direction <dir>", "Arc direction (ascending, descending, static)")
+  .option("--impact <n>", "Impact magnitude (0-1)", "0.3")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Recording Arc Impact"));
+    console.log(chalk.dim(`Character: ${opts.character}`));
+    console.log(chalk.dim(`Beat: ${opts.beat}`));
+    console.log(chalk.dim(`Direction: ${opts.direction || "auto-detect"}`));
+    console.log(chalk.dim(`Impact: ${opts.impact}`));
+    console.log();
+    console.log(chalk.yellow("⚠ Character or beat not found."));
+  });
+
+arcCommand
+  .command("context")
+  .description("Get character arc context for prompts")
+  .argument("<characterId>", "Character ID")
+  .option("-d, --depth <n>", "Number of recent arc points", "3")
+  .action(async (characterId, opts) => {
+    console.log(chalk.bold(`🌸 Arc Context: ${characterId}`));
+    console.log(chalk.dim(`Depth: ${opts.depth} recent points`));
+    console.log();
+    console.log(chalk.yellow("⚠ Character not found."));
+  });

package/miatel/src/commands/beat.ts

@@ -0,0 +1,176 @@
+/**
+ * Beat command - Story beat operations
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import { SessionStorage, Beat } from "../storage.js";
+
+const BEATS_FILE = "beats.jsonl";
+
+export const beatCommand = new Command("beat")
+  .description("Story beat operations");
+
+beatCommand
+  .command("create")
+  .description("Create a new story beat")
+  .requiredOption("-t, --text <text>", "Beat text/content")
+  .option("--character <id>", "Character ID for this beat")
+  .option("--tone <tone>", "Emotional tone (joy, fear, anticipation, etc.)")
+  .option("--phase <phase>", "Narrative phase (setup, confrontation, resolution)")
+  .option("--session <id>", "Session ID")
+  .option("--json", "Output JSON for programmatic parsing")
+  .action(async (opts) => {
+    const storage = new SessionStorage({ sessionId: opts.session });
+    const beatId = `beat_${Date.now().toString(36)}`;
+    
+    const beat: Beat = {
+      id: beatId,
+      text: opts.text,
+      character: opts.character || "narrator",
+      tone: opts.tone || "neutral",
+      phase: opts.phase || "unspecified",
+      createdAt: Date.now()
+    };
+    
+    storage.append(BEATS_FILE, beat);
+    
+    if (opts.json) {
+      console.log(JSON.stringify({ success: true, beat }));
+    } else {
+      console.log(chalk.bold("🌸 Creating Story Beat"));
+      console.log(chalk.dim(`Text: ${opts.text.substring(0, 50)}...`));
+      console.log(chalk.dim(`Character: ${beat.character}`));
+      console.log(chalk.dim(`Tone: ${beat.tone}`));
+      console.log(chalk.dim(`Phase: ${beat.phase}`));
+      console.log();
+      console.log(chalk.green(`✓ Beat created: ${beatId}`));
+      console.log(chalk.dim(`Session: ${storage.getSessionId()}`));
+    }
+  });
+
+beatCommand
+  .command("list")
+  .description("List story beats in current session")
+  .option("-n, --limit <n>", "Limit number of results", "10")
+  .option("--character <id>", "Filter by character")
+  .option("--session <id>", "Session ID")
+  .option("--json", "Output JSON for programmatic parsing")
+  .action(async (opts) => {
+    const storage = new SessionStorage({ sessionId: opts.session });
+    let beats = storage.readAll<Beat>(BEATS_FILE);
+    
+    // Filter by character if specified
+    if (opts.character) {
+      beats = beats.filter(b => b.character === opts.character);
+    }
+    
+    // Limit results
+    const limit = parseInt(opts.limit, 10);
+    beats = beats.slice(-limit);
+    
+    if (opts.json) {
+      console.log(JSON.stringify({ beats }));
+    } else {
+      console.log(chalk.bold("🌸 Story Beats"));
+      console.log(chalk.dim(`Session: ${storage.getSessionId()}`));
+      console.log();
+      
+      if (beats.length === 0) {
+        console.log(chalk.dim("No beats yet. Use `miatel beat create` to add one."));
+      } else {
+        beats.forEach((beat, i) => {
+          console.log(chalk.bold(`${i + 1}. ${beat.id}`));
+          console.log(chalk.dim(`   ${beat.text.substring(0, 60)}...`));
+          console.log(chalk.dim(`   Character: ${beat.character} | Tone: ${beat.tone} | Phase: ${beat.phase}`));
+          console.log();
+        });
+      }
+    }
+  });
+
+beatCommand
+  .command("analyze")
+  .description("Analyze a specific beat")
+  .argument("<beatId>", "Beat ID to analyze")
+  .option("--universe <universe>", "Universe lens (engineer, ceremony, story_engine)")
+  .option("--session <id>", "Session ID")
+  .option("--json", "Output JSON for programmatic parsing")
+  .action(async (beatId, opts) => {
+    const storage = new SessionStorage({ sessionId: opts.session });
+    const beat = storage.findById<Beat>(BEATS_FILE, beatId);
+    
+    if (!beat) {
+      if (opts.json) {
+        console.log(JSON.stringify({ success: false, error: "Beat not found" }));
+      } else {
+        console.log(chalk.yellow(`⚠ Beat not found: ${beatId}`));
+      }
+      return;
+    }
+    
+    // Basic analysis (can be enhanced with narrative-intelligence package)
+    const analysis = {
+      beatId: beat.id,
+      text: beat.text,
+      character: beat.character,
+      tone: beat.tone,
+      phase: beat.phase,
+      universe: opts.universe || "all",
+      wordCount: beat.text.split(/\s+/).length,
+      emotionalIntensity: beat.tone === "neutral" ? "low" : "medium"
+    };
+    
+    if (opts.json) {
+      console.log(JSON.stringify({ success: true, analysis }));
+    } else {
+      console.log(chalk.bold(`🌸 Analyzing Beat: ${beatId}`));
+      console.log(chalk.dim(`Universe: ${opts.universe || "all three"}`));
+      console.log();
+      console.log(chalk.dim(`Text: ${beat.text}`));
+      console.log(chalk.dim(`Character: ${beat.character}`));
+      console.log(chalk.dim(`Tone: ${beat.tone}`));
+      console.log(chalk.dim(`Phase: ${beat.phase}`));
+      console.log(chalk.dim(`Word count: ${analysis.wordCount}`));
+    }
+  });
+
+beatCommand
+  .command("enrich")
+  .description("Apply emotional enrichment to a beat")
+  .argument("<beatId>", "Beat ID to enrich")
+  .option("--technique <technique>", "Enrichment technique (sensory, stakes, dialogue)")
+  .option("--session <id>", "Session ID")
+  .option("--json", "Output JSON for programmatic parsing")
+  .action(async (beatId, opts) => {
+    const storage = new SessionStorage({ sessionId: opts.session });
+    const beat = storage.findById<Beat>(BEATS_FILE, beatId);
+    
+    if (!beat) {
+      if (opts.json) {
+        console.log(JSON.stringify({ success: false, error: "Beat not found" }));
+      } else {
+        console.log(chalk.yellow(`⚠ Beat not found: ${beatId}`));
+      }
+      return;
+    }
+    
+    if (opts.json) {
+      console.log(JSON.stringify({ 
+        success: true, 
+        beat,
+        enrichment: { 
+          technique: opts.technique || "auto-detect",
+          suggestions: ["Add sensory details", "Increase emotional stakes"] 
+        }
+      }));
+    } else {
+      console.log(chalk.bold(`🌸 Enriching Beat: ${beatId}`));
+      console.log(chalk.dim(`Technique: ${opts.technique || "auto-detect"}`));
+      console.log();
+      console.log(chalk.dim("Suggestions:"));
+      console.log(chalk.dim("  - Add sensory details to the scene"));
+      console.log(chalk.dim("  - Increase emotional stakes"));
+      console.log(chalk.dim("  - Consider character internal dialogue"));
+    }
+  });

package/miatel/src/commands/theme.ts

@@ -0,0 +1,60 @@
+/**
+ * Theme command - Thematic thread management
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+
+export const themeCommand = new Command("theme")
+  .description("Thematic thread management");
+
+themeCommand
+  .command("add")
+  .description("Add a thematic thread to the story")
+  .requiredOption("-n, --name <name>", "Theme name (e.g., redemption, sacrifice)")
+  .option("-d, --description <desc>", "Theme description")
+  .option("--weight <n>", "Theme importance weight (0-1)", "0.5")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Adding Thematic Thread"));
+    console.log(chalk.dim(`Name: ${opts.name}`));
+    console.log(chalk.dim(`Description: ${opts.description || "none"}`));
+    console.log(chalk.dim(`Weight: ${opts.weight}`));
+    console.log();
+    
+    const themeId = opts.name.toLowerCase().replace(/\s+/g, '_');
+    console.log(chalk.green(`✓ Theme added: ${themeId}`));
+  });
+
+themeCommand
+  .command("list")
+  .description("List thematic threads in current session")
+  .action(async () => {
+    console.log(chalk.bold("🌸 Thematic Threads"));
+    console.log(chalk.dim("No themes defined. Use `miatel theme add` to create one."));
+  });
+
+themeCommand
+  .command("saturation")
+  .description("Check theme saturation across beats")
+  .argument("[themeName]", "Specific theme to check (all if omitted)")
+  .action(async (themeName) => {
+    console.log(chalk.bold("🌸 Theme Saturation Analysis"));
+    console.log(chalk.dim(`Theme: ${themeName || "all themes"}`));
+    console.log();
+    console.log(chalk.yellow("⚠ No beats or themes to analyze."));
+  });
+
+themeCommand
+  .command("connect")
+  .description("Connect a beat to a theme")
+  .requiredOption("-t, --theme <name>", "Theme name")
+  .requiredOption("-b, --beat <id>", "Beat ID")
+  .option("--strength <n>", "Connection strength (0-1)", "0.5")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 Connecting Beat to Theme"));
+    console.log(chalk.dim(`Theme: ${opts.theme}`));
+    console.log(chalk.dim(`Beat: ${opts.beat}`));
+    console.log(chalk.dim(`Strength: ${opts.strength}`));
+    console.log();
+    console.log(chalk.yellow("⚠ Theme or beat not found."));
+  });

package/miatel/src/index.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * miatel - Story World Terminal Agent
+ * 
+ * Part of the mia-code family:
+ * - miaco: Engineering World CLI
+ * - miatel: Story World CLI (this one)
+ * - miawa: Ceremony World CLI
+ * 
+ * Provides narrative intelligence operations:
+ * - Story beat generation and analysis
+ * - Character arc tracking
+ * - Thematic thread management
+ * - NCP state operations
+ * - Integration with storytelling package
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import { beatCommand } from "./commands/beat.js";
+import { arcCommand } from "./commands/arc.js";
+import { themeCommand } from "./commands/theme.js";
+import { analyzeCommand } from "./commands/analyze.js";
+
+const program = new Command();
+
+program
+  .name("miatel")
+  .description("🌸 miatel — Story World terminal agent for narrative intelligence")
+  .version("0.1.0");
+
+// Story beat operations
+program.addCommand(beatCommand);
+
+// Character arc operations  
+program.addCommand(arcCommand);
+
+// Theme operations
+program.addCommand(themeCommand);
+
+// Analysis operations
+program.addCommand(analyzeCommand);
+
+// Quick status command
+program
+  .command("status")
+  .description("Show current story session status")
+  .option("-s, --session <id>", "Session ID")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 miatel — Story World Status"));
+    console.log(chalk.dim("Session: " + (opts.session || "none active")));
+    console.log(chalk.dim("Beats: 0 | Characters: 0 | Themes: 0"));
+    console.log();
+    console.log(chalk.yellow("⚠ Story session not initialized. Run `miatel init` to begin."));
+  });
+
+// Initialize session
+program
+  .command("init")
+  .description("Initialize a new story session")
+  .option("-s, --story-id <id>", "Story identifier")
+  .option("-t, --title <title>", "Story title")
+  .action(async (opts) => {
+    console.log(chalk.bold("🌸 miatel — Initializing Story Session"));
+    console.log(chalk.dim(`Story ID: ${opts.storyId || "auto-generated"}`));
+    console.log(chalk.dim(`Title: ${opts.title || "Untitled Story"}`));
+    console.log();
+    console.log(chalk.green("✓ Story session initialized"));
+    console.log(chalk.dim("Use `miatel beat create` to add your first beat."));
+  });
+
+// Help with examples
+program
+  .command("examples")
+  .description("Show usage examples")
+  .action(() => {
+    console.log(chalk.bold("\n🌸 miatel Examples\n"));
+    console.log(chalk.dim("# Initialize a story session"));
+    console.log("  miatel init --title 'Hero\\'s Journey'\n");
+    
+    console.log(chalk.dim("# Create a story beat"));
+    console.log("  miatel beat create --text 'The hero receives the call' --tone anticipation\n");
+    
+    console.log(chalk.dim("# Track character arc"));
+    console.log("  miatel arc init --name 'Hero' --wound 'past failure' --desire 'redemption'\n");
+    
+    console.log(chalk.dim("# Analyze story coherence"));
+    console.log("  miatel analyze coherence --session <id>\n");
+    
+    console.log(chalk.dim("# Add thematic thread"));
+    console.log("  miatel theme add --name 'redemption' --description 'Finding worth again'\n");
+  });
+
+program.parseAsync(process.argv);