coaiajs 0.1.0 → 0.1.1

package/src/narrative/index.ts

@@ -1,32 +0,0 @@
-// narrative/index.ts — Module barrel export
-
-export { KnowledgeGraphManager } from './graph-manager.js';
-export { handleToolCall } from './tool-handlers.js';
-export { validate, ValidationSchemas } from './validation.js';
-export {
-  ALL_TOOL_DEFINITIONS,
-  STC_TOOLS,
-  NARRATIVE_TOOLS,
-  KG_TOOLS,
-  CORE_TOOLS,
-} from './tool-definitions.js';
-export type { ToolDefinition } from './tool-definitions.js';
-export {
-  exportChartToMarkdown,
-  exportAllCharts,
-  exportChartProgress,
-  exportChartStats,
-  writeMarkdownToFile,
-  getDefaultFilename,
-} from './markdown-export.js';
-export type { MarkdownOptions } from './markdown-export.js';
-
-// Re-export narrative-relevant types
-export type {
-  Entity,
-  EntityMetadata,
-  Relation,
-  RelationMetadata,
-  KnowledgeGraph,
-  McpToolResult,
-} from './types.js';

package/src/narrative/markdown-export.ts

@@ -1,535 +0,0 @@
-/**
- * Markdown Export Module for COAIA Narrative
- *
- * Provides markdown generation for structural tension charts,
- * narrative beats, and associated data structures.
- */
-
-import { promises as fs } from 'fs';
-import path from 'path';
-import type { Entity, KnowledgeGraph } from '../types.js';
-import type { KnowledgeGraphManager } from './graph-manager.js';
-
-export interface MarkdownOptions {
-  includeMetadata?: boolean;
-  includeObservations?: boolean;
-  observationLimit?: number;
-  includeToc?: boolean;
-  outputPath?: string;
-}
-
-// ─── Utility Functions ────────────────────────────────────────────────
-
-function escapeMarkdown(text: string): string {
-  return text
-    .replace(/\\/g, '\\\\')
-    .replace(/\*/g, '\\*')
-    .replace(/\[/g, '\\[')
-    .replace(/\]/g, '\\]')
-    .replace(/\(/g, '\\(')
-    .replace(/\)/g, '\\)');
-}
-
-function formatDateForMarkdown(dateStr?: string): string {
-  if (!dateStr) return 'No due date';
-  const date = new Date(dateStr);
-  const now = new Date();
-  const days = Math.ceil((date.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
-
-  if (days < 0) return `Overdue by ${Math.abs(days)} days`;
-  if (days === 0) return 'Due today';
-  if (days === 1) return 'Due tomorrow';
-  if (days <= 7) return `Due in ${days} days`;
-  return `${date.toLocaleDateString()}`;
-}
-
-function formatProgressBar(progress: number): string {
-  const width = 20;
-  const filled = Math.round(progress * width);
-  const empty = width - filled;
-  const bar = '█'.repeat(filled) + '░'.repeat(empty);
-  const percent = Math.round(progress * 100);
-  return `[${bar}] ${percent}%`;
-}
-
-function getStatusIcon(completed: boolean): string {
-  return completed ? '✅' : '⏳';
-}
-
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, '')
-    .replace(/\s+/g, '-')
-    .replace(/-+/g, '-');
-}
-
-// ─── Single Chart Export ──────────────────────────────────────────────
-
-export async function exportChartToMarkdown(
-  chartId: string,
-  manager: KnowledgeGraphManager,
-  options: MarkdownOptions = {},
-): Promise<string> {
-  const graph = await manager.readGraph();
-  const {
-    includeMetadata = true,
-    includeObservations = true,
-    observationLimit = 0,
-  } = options;
-
-  const chart = graph.entities.find(
-    e =>
-      e.entityType === 'structural_tension_chart' &&
-      e.metadata?.chartId === chartId,
-  );
-
-  if (!chart) {
-    return `# Error\n\nChart '${chartId}' not found.`;
-  }
-
-  let md = '';
-
-  md += `# Chart: ${chartId}\n\n`;
-
-  if (includeMetadata) {
-    if (chart.metadata?.createdAt) {
-      const created = new Date(chart.metadata.createdAt).toLocaleString();
-      md += `> **Created**: ${created}\n`;
-    }
-    if (chart.metadata?.parentChart) {
-      md += `> **Parent Chart**: ${chart.metadata.parentChart} (Level ${chart.metadata.level})\n`;
-    } else {
-      md += `> **Master Chart** (Level ${chart.metadata?.level || 0})\n`;
-    }
-    if (chart.metadata?.dueDate) {
-      md += `> **Due**: ${formatDateForMarkdown(chart.metadata.dueDate)}\n`;
-    }
-    md += '\n';
-  }
-
-  // Desired Outcome
-  const outcome = graph.entities.find(
-    e =>
-      e.name === `${chartId}_desired_outcome` &&
-      e.entityType === 'desired_outcome',
-  );
-  md += '## Desired Outcome\n\n';
-  if (outcome) {
-    md += `${escapeMarkdown(outcome.observations[0])}\n\n`;
-  } else {
-    md += '*(Unknown)*\n\n';
-  }
-
-  // Current Reality
-  const currentReality = graph.entities.find(
-    e =>
-      e.name === `${chartId}_current_reality` &&
-      e.entityType === 'current_reality',
-  );
-  md += '## Current Reality\n\n';
-  if (currentReality && currentReality.observations.length > 0) {
-    if (includeObservations && observationLimit > 0) {
-      const obs = currentReality.observations.slice(-observationLimit);
-      obs.forEach(o => (md += `- ${escapeMarkdown(o)}\n`));
-    } else if (includeObservations) {
-      currentReality.observations.forEach(o => (md += `- ${escapeMarkdown(o)}\n`));
-    } else {
-      md += `- ${escapeMarkdown(currentReality.observations[currentReality.observations.length - 1])}\n`;
-    }
-    md += '\n';
-  } else {
-    md += '*(Not assessed)*\n\n';
-  }
-
-  // Progress & Structural Tension
-  const actionSteps = graph.entities.filter(
-    e => e.entityType === 'action_step' && e.metadata?.chartId === chartId,
-  );
-  const completed = actionSteps.filter(
-    a => a.metadata?.completionStatus === true,
-  ).length;
-  const total = actionSteps.length;
-  const progress = total > 0 ? completed / total : 0;
-
-  md += '## Structural Tension\n\n';
-  md += `${formatProgressBar(progress)}\n\n`;
-  md += `- **Completed**: ${completed}/${total} action steps\n\n`;
-
-  // Action Steps
-  if (actionSteps.length > 0) {
-    md += '## Action Steps\n\n';
-    actionSteps.forEach((step, idx) => {
-      const isComplete = step.metadata?.completionStatus === true;
-      const status = getStatusIcon(isComplete);
-      const stepId = (step.metadata?.chartId as string) || `step_${idx + 1}`;
-
-      md += `### ${status} ${escapeMarkdown(step.observations[0])}\n\n`;
-      md += `- **ID**: ${stepId}\n`;
-      md += `- **Status**: ${isComplete ? 'Completed' : 'In Progress'}\n`;
-      if (step.metadata?.dueDate) {
-        md += `- **Due**: ${formatDateForMarkdown(step.metadata.dueDate)}\n`;
-      }
-
-      if (step.observations.length > 1 && includeObservations) {
-        md += `- **Notes**:\n`;
-        step.observations.slice(1).forEach(note => {
-          md += `  - ${escapeMarkdown(note)}\n`;
-        });
-      }
-      md += '\n';
-    });
-  }
-
-  // Narrative Beats
-  const narrativeBeats = graph.entities
-    .filter(
-      e =>
-        e.entityType === 'narrative_beat' && e.metadata?.chartId === chartId,
-    )
-    .sort((a, b) => ((a.metadata?.act as number) || 0) - ((b.metadata?.act as number) || 0));
-
-  if (narrativeBeats.length > 0) {
-    md += '## Narrative Beats\n\n';
-    narrativeBeats.forEach(beat => {
-      const act = beat.metadata?.act || '?';
-      const type = beat.metadata?.type_dramatic || 'Unknown';
-      const universes = (beat.metadata?.universes as string[]) || [];
-
-      md += `### Act ${act}: ${escapeMarkdown(type as string)}\n\n`;
-
-      if (universes.length > 0) {
-        md += `- **Universes**: ${universes.join(', ')}\n`;
-      }
-      if (beat.metadata?.timestamp) {
-        const ts = new Date(beat.metadata.timestamp).toLocaleString();
-        md += `- **Timestamp**: ${ts}\n`;
-      }
-
-      if (beat.metadata?.narrative?.description) {
-        md += `\n**Description**:\n\n${escapeMarkdown(beat.metadata.narrative.description)}\n`;
-      }
-
-      if (beat.metadata?.narrative?.prose) {
-        md += `\n**Prose**:\n\n${escapeMarkdown(beat.metadata.narrative.prose)}\n`;
-      }
-
-      if (
-        beat.metadata?.narrative?.lessons &&
-        beat.metadata.narrative.lessons.length > 0
-      ) {
-        md += `\n**Lessons**:\n\n`;
-        beat.metadata.narrative.lessons.forEach(lesson => {
-          md += `- ${escapeMarkdown(lesson)}\n`;
-        });
-      }
-
-      const dirs = beat.metadata?.fourDirections;
-      if (
-        dirs &&
-        (dirs.north_vision ||
-          dirs.east_intention ||
-          dirs.south_emotion ||
-          dirs.west_introspection)
-      ) {
-        md += `\n**Four Directions**:\n\n`;
-        if (dirs.north_vision) md += `- **North (Vision)**: ${escapeMarkdown(dirs.north_vision)}\n`;
-        if (dirs.east_intention) md += `- **East (Intention)**: ${escapeMarkdown(dirs.east_intention)}\n`;
-        if (dirs.south_emotion) md += `- **South (Emotion)**: ${escapeMarkdown(dirs.south_emotion)}\n`;
-        if (dirs.west_introspection) md += `- **West (Introspection)**: ${escapeMarkdown(dirs.west_introspection)}\n`;
-      }
-
-      md += '\n';
-    });
-  }
-
-  return md;
-}
-
-// ─── All Charts Export ────────────────────────────────────────────────
-
-export async function exportAllCharts(
-  manager: KnowledgeGraphManager,
-  options: MarkdownOptions = {},
-): Promise<string> {
-  const graph = await manager.readGraph();
-  const { includeToc = true } = options;
-
-  const charts = graph.entities.filter(
-    e => e.entityType === 'structural_tension_chart',
-  );
-  const masterCharts = charts.filter(c => c.metadata?.level === 0);
-
-  let md = '# Structural Tension Charts\n\n';
-
-  if (includeToc && masterCharts.length > 0) {
-    md += '## Table of Contents\n\n';
-    masterCharts.forEach(master => {
-      const cId = (master.metadata?.chartId as string) || master.name;
-      const slug = slugify(cId);
-      md += `- [${cId}](#${slug})\n`;
-    });
-    md += '\n---\n\n';
-  }
-
-  masterCharts.forEach((master, masterIdx) => {
-    const cId = (master.metadata?.chartId as string) || master.name;
-
-    md += `## ${cId}\n\n`;
-
-    const outcome = graph.entities.find(
-      e =>
-        e.name === `${cId}_desired_outcome` &&
-        e.entityType === 'desired_outcome',
-    );
-    md += `**Desired Outcome**: ${outcome?.observations[0] || 'Unknown'}\n\n`;
-
-    const cr = graph.entities.find(
-      e =>
-        e.name === `${cId}_current_reality` &&
-        e.entityType === 'current_reality',
-    );
-    if (cr && cr.observations.length > 0) {
-      md += `**Current Reality**: ${cr.observations[cr.observations.length - 1]}\n\n`;
-    }
-
-    const actionSteps = graph.entities.filter(
-      e => e.entityType === 'action_step' && e.metadata?.chartId === cId,
-    );
-    const completed = actionSteps.filter(
-      a => a.metadata?.completionStatus === true,
-    ).length;
-    const total = actionSteps.length;
-    const progress = total > 0 ? completed / total : 0;
-
-    md += `**Progress**: ${formatProgressBar(progress)} (${completed}/${total})\n\n`;
-
-    if (master.metadata?.dueDate) {
-      md += `**Due**: ${formatDateForMarkdown(master.metadata.dueDate)}\n\n`;
-    }
-
-    const actionCharts = charts.filter(
-      c => c.metadata?.parentChart === cId && c.metadata?.level === 1,
-    );
-
-    if (actionCharts.length > 0) {
-      md += '### Action Steps\n\n';
-      actionCharts.forEach(actionChart => {
-        const actionChartId = actionChart.metadata?.chartId as string;
-        const actionOutcome = graph.entities.find(
-          e =>
-            e.name === `${actionChartId}_desired_outcome` &&
-            e.entityType === 'desired_outcome',
-        );
-        const actionActions = graph.entities.filter(
-          e =>
-            e.entityType === 'action_step' &&
-            e.metadata?.chartId === actionChartId,
-        );
-
-        const actionCompleted = actionActions.filter(
-          a => a.metadata?.completionStatus === true,
-        ).length;
-        const actionTotal = actionActions.length;
-        const actionProgress =
-          actionTotal > 0 ? actionCompleted / actionTotal : 0;
-        const isComplete = actionChart.metadata?.completionStatus === true;
-        const status = isComplete ? '✅' : actionProgress > 0 ? '🔄' : '⏳';
-
-        md += `- ${status} **${escapeMarkdown(actionOutcome?.observations[0] || 'Unknown')}**\n`;
-        md += `  - ID: ${actionChartId}\n`;
-        if (actionChart.metadata?.dueDate) {
-          md += `  - Due: ${formatDateForMarkdown(actionChart.metadata.dueDate)}\n`;
-        }
-        if (actionTotal > 0) {
-          md += `  - Progress: ${formatProgressBar(actionProgress)}\n`;
-        }
-      });
-      md += '\n';
-    }
-
-    if (masterIdx < masterCharts.length - 1) {
-      md += '---\n\n';
-    }
-  });
-
-  return md;
-}
-
-// ─── Progress Report ──────────────────────────────────────────────────
-
-export async function exportChartProgress(
-  chartId: string,
-  manager: KnowledgeGraphManager,
-): Promise<string> {
-  const graph = await manager.readGraph();
-
-  const chart = graph.entities.find(
-    e =>
-      e.entityType === 'structural_tension_chart' &&
-      e.metadata?.chartId === chartId,
-  );
-
-  if (!chart) {
-    return `# Error\n\nChart '${chartId}' not found.`;
-  }
-
-  const outcome = graph.entities.find(
-    e => e.name === `${chartId}_desired_outcome`,
-  );
-  const actions = graph.entities.filter(
-    e => e.entityType === 'action_step' && e.metadata?.chartId === chartId,
-  );
-
-  const completed = actions.filter(
-    a => a.metadata?.completionStatus === true,
-  );
-  const incomplete = actions.filter(
-    a => a.metadata?.completionStatus !== true,
-  );
-  const progress = actions.length > 0 ? completed.length / actions.length : 0;
-
-  let md = `# Progress Report: ${chartId}\n\n`;
-
-  md += `**Goal**: ${outcome?.observations[0] || 'Unknown'}\n\n`;
-
-  md += `## Overall Progress\n\n`;
-  md += `${formatProgressBar(progress)}\n\n`;
-
-  md += '## Completed Actions\n\n';
-  if (completed.length > 0) {
-    completed.forEach((action, idx) => {
-      md += `${idx + 1}. ${escapeMarkdown(action.observations[0])}\n`;
-      if (action.metadata?.dueDate) {
-        md += `   - Completed: ${formatDateForMarkdown(action.metadata.dueDate)}\n`;
-      }
-    });
-  } else {
-    md += '*No completed actions yet.*\n';
-  }
-  md += '\n';
-
-  md += '## Remaining Actions\n\n';
-  if (incomplete.length > 0) {
-    incomplete.forEach((action, idx) => {
-      md += `${idx + 1}. ${escapeMarkdown(action.observations[0])}\n`;
-      if (action.metadata?.dueDate) {
-        md += `   - Due: ${formatDateForMarkdown(action.metadata.dueDate)}\n`;
-      }
-    });
-  } else {
-    md += '*All actions completed!*\n';
-  }
-  md += '\n';
-
-  const currentReality = graph.entities.find(
-    e => e.name === `${chartId}_current_reality`,
-  );
-  if (currentReality && currentReality.observations.length > 0) {
-    md += '## Current Reality Notes\n\n';
-    currentReality.observations.slice(-5).forEach(obs => {
-      md += `- ${escapeMarkdown(obs)}\n`;
-    });
-  }
-
-  return md;
-}
-
-// ─── Statistics ───────────────────────────────────────────────────────
-
-export async function exportChartStats(
-  manager: KnowledgeGraphManager,
-): Promise<string> {
-  const graph = await manager.readGraph();
-
-  const charts = graph.entities.filter(
-    e => e.entityType === 'structural_tension_chart',
-  );
-  const masterCharts = charts.filter(c => c.metadata?.level === 0);
-  const actionCharts = charts.filter(c => c.metadata?.level === 1);
-
-  const allActions = graph.entities.filter(
-    e => e.entityType === 'action_step',
-  );
-  const completedActions = allActions.filter(
-    a => a.metadata?.completionStatus === true,
-  );
-
-  const narrativeBeats = graph.entities.filter(
-    e => e.entityType === 'narrative_beat',
-  );
-
-  const overdueCharts = charts.filter(chart => {
-    if (!chart.metadata?.dueDate) return false;
-    const dueDate = new Date(chart.metadata.dueDate);
-    return dueDate < new Date();
-  });
-
-  let md = '# Structural Tension Charts Statistics\n\n';
-
-  md += '## Overview\n\n';
-  md += `| Metric | Count |\n`;
-  md += `|--------|-------|\n`;
-  md += `| Master Charts | ${masterCharts.length} |\n`;
-  md += `| Action Step Charts | ${actionCharts.length} |\n`;
-  md += `| Total Charts | ${charts.length} |\n`;
-  md += `| Narrative Beats | ${narrativeBeats.length} |\n`;
-  md += '\n';
-
-  md += '## Completion Status\n\n';
-  md += `| Status | Count |\n`;
-  md += `|--------|-------|\n`;
-  md += `| Completed Actions | ${completedActions.length}/${allActions.length} |\n`;
-  const overallProgress =
-    allActions.length > 0
-      ? Math.round((completedActions.length / allActions.length) * 100)
-      : 0;
-  md += `| Overall Progress | ${overallProgress}% |\n`;
-  md += '\n';
-
-  if (overdueCharts.length > 0) {
-    md += '## ⚠️ Overdue Charts\n\n';
-    overdueCharts.forEach((chart, idx) => {
-      const chartId = (chart.metadata?.chartId as string) || chart.name;
-      md += `${idx + 1}. **${chartId}** - Due: ${formatDateForMarkdown(chart.metadata?.dueDate)}\n`;
-    });
-  } else {
-    md += '## ✅ Status\n\n';
-    md += 'All charts are on track!\n';
-  }
-  md += '\n';
-
-  return md;
-}
-
-// ─── File Output ──────────────────────────────────────────────────────
-
-export async function writeMarkdownToFile(
-  content: string,
-  outputPath: string,
-): Promise<void> {
-  const dir = path.dirname(outputPath);
-  try {
-    await fs.mkdir(dir, { recursive: true });
-  } catch (_e) {
-    // Directory may exist
-  }
-  await fs.writeFile(outputPath, content, 'utf-8');
-}
-
-export function getDefaultFilename(exportType: string, chartId?: string): string {
-  const timestamp = new Date().toISOString().split('T')[0];
-
-  switch (exportType) {
-    case 'chart':
-      return `${chartId}-export-${timestamp}.md`;
-    case 'list':
-      return `structural-tension-charts-${timestamp}.md`;
-    case 'progress':
-      return `${chartId}-progress-${timestamp}.md`;
-    case 'stats':
-      return `statistics-${timestamp}.md`;
-    default:
-      return `export-${timestamp}.md`;
-  }
-}