namnam-skills 1.0.0 → 1.0.1

package/src/conversation.js

@@ -0,0 +1,447 @@
+/**
+ * Conversation Management Utilities
+ *
+ * Handles saving, loading, and managing conversation context
+ * for the @conversation feature
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import crypto from 'crypto';
+
+// Default conversation directory
+const CONV_DIR_NAME = 'conversations';
+const INDEX_FILE = 'index.json';
+const META_FILE = 'meta.json';
+const CONTEXT_FILE = 'context.md';
+const FULL_LOG_FILE = 'full.md';
+
+/**
+ * Validate conversation options
+ */
+function validateConversationOptions(options) {
+  const errors = [];
+
+  if (options.title !== undefined && typeof options.title !== 'string') {
+    errors.push('title must be a string');
+  }
+
+  if (options.summary !== undefined && typeof options.summary !== 'string') {
+    errors.push('summary must be a string');
+  }
+
+  if (options.context !== undefined && typeof options.context !== 'string') {
+    errors.push('context must be a string');
+  }
+
+  if (options.fullLog !== undefined && typeof options.fullLog !== 'string') {
+    errors.push('fullLog must be a string');
+  }
+
+  if (options.tags !== undefined && !Array.isArray(options.tags)) {
+    errors.push('tags must be an array');
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Invalid conversation options: ${errors.join(', ')}`);
+  }
+}
+
+/**
+ * Escape XML special characters
+ */
+function escapeXml(str) {
+  if (!str) return '';
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Get the conversations directory path
+ */
+export function getConversationsDir(cwd = process.cwd()) {
+  return path.join(cwd, '.claude', CONV_DIR_NAME);
+}
+
+/**
+ * Get the index file path
+ */
+export function getIndexPath(cwd = process.cwd()) {
+  return path.join(getConversationsDir(cwd), INDEX_FILE);
+}
+
+/**
+ * Generate a unique conversation ID
+ */
+export function generateConvId() {
+  const timestamp = Date.now().toString(36);
+  const random = crypto.randomBytes(3).toString('hex');
+  return `conv_${timestamp}_${random}`;
+}
+
+/**
+ * Generate a short ID for easy reference
+ */
+export function generateShortId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+/**
+ * Initialize conversations directory
+ */
+export async function initConversations(cwd = process.cwd()) {
+  const convDir = getConversationsDir(cwd);
+  const indexPath = getIndexPath(cwd);
+
+  await fs.ensureDir(convDir);
+
+  if (!(await fs.pathExists(indexPath))) {
+    await fs.writeJson(indexPath, {
+      version: '1.0.0',
+      conversations: [],
+      lastUpdated: new Date().toISOString()
+    }, { spaces: 2 });
+  }
+
+  return convDir;
+}
+
+/**
+ * Load the conversation index
+ */
+export async function loadIndex(cwd = process.cwd()) {
+  const indexPath = getIndexPath(cwd);
+
+  if (!(await fs.pathExists(indexPath))) {
+    return { version: '1.0.0', conversations: [], lastUpdated: null };
+  }
+
+  return await fs.readJson(indexPath);
+}
+
+/**
+ * Save the conversation index
+ */
+export async function saveIndex(index, cwd = process.cwd()) {
+  const indexPath = getIndexPath(cwd);
+  index.lastUpdated = new Date().toISOString();
+  await fs.writeJson(indexPath, index, { spaces: 2 });
+}
+
+/**
+ * Save a new conversation
+ */
+export async function saveConversation(options, cwd = process.cwd()) {
+  validateConversationOptions(options);
+
+  const {
+    title,
+    summary,
+    context,
+    fullLog = null,
+    tags = [],
+    metadata = {}
+  } = options;
+
+  await initConversations(cwd);
+
+  const id = generateConvId();
+  const shortId = generateShortId();
+  const convDir = path.join(getConversationsDir(cwd), id);
+
+  await fs.ensureDir(convDir);
+
+  // Create metadata file
+  const meta = {
+    id,
+    shortId,
+    title: title || 'Untitled Conversation',
+    summary: summary || '',
+    tags,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...metadata
+  };
+
+  await fs.writeJson(path.join(convDir, META_FILE), meta, { spaces: 2 });
+
+  // Create context file (loadable summary)
+  if (context) {
+    await fs.writeFile(path.join(convDir, CONTEXT_FILE), context);
+  }
+
+  // Create full log if provided
+  if (fullLog) {
+    await fs.writeFile(path.join(convDir, FULL_LOG_FILE), fullLog);
+  }
+
+  // Update index
+  const index = await loadIndex(cwd);
+  index.conversations.push({
+    id,
+    shortId,
+    title: meta.title,
+    summary: meta.summary,
+    tags,
+    createdAt: meta.createdAt
+  });
+  await saveIndex(index, cwd);
+
+  return { id, shortId, path: convDir };
+}
+
+/**
+ * Get a conversation by ID (full or short)
+ */
+export async function getConversation(convId, cwd = process.cwd()) {
+  const index = await loadIndex(cwd);
+
+  // Find by full ID or short ID
+  const entry = index.conversations.find(
+    c => c.id === convId || c.shortId === convId || c.id.includes(convId)
+  );
+
+  if (!entry) {
+    return null;
+  }
+
+  const convDir = path.join(getConversationsDir(cwd), entry.id);
+
+  if (!(await fs.pathExists(convDir))) {
+    return null;
+  }
+
+  const meta = await fs.readJson(path.join(convDir, META_FILE));
+
+  let context = null;
+  let fullLog = null;
+
+  const contextPath = path.join(convDir, CONTEXT_FILE);
+  const fullPath = path.join(convDir, FULL_LOG_FILE);
+
+  if (await fs.pathExists(contextPath)) {
+    context = await fs.readFile(contextPath, 'utf-8');
+  }
+
+  if (await fs.pathExists(fullPath)) {
+    fullLog = await fs.readFile(fullPath, 'utf-8');
+  }
+
+  return { ...meta, context, fullLog };
+}
+
+/**
+ * List all conversations
+ */
+export async function listConversations(options = {}, cwd = process.cwd()) {
+  const { limit = 20, tag = null, search = null } = options;
+  const index = await loadIndex(cwd);
+
+  let conversations = index.conversations || [];
+
+  // Filter by tag
+  if (tag) {
+    conversations = conversations.filter(c =>
+      c.tags && c.tags.includes(tag)
+    );
+  }
+
+  // Filter by search term
+  if (search) {
+    const term = search.toLowerCase();
+    conversations = conversations.filter(c =>
+      c.title.toLowerCase().includes(term) ||
+      c.summary.toLowerCase().includes(term) ||
+      c.id.includes(term) ||
+      c.shortId.includes(term)
+    );
+  }
+
+  // Sort by date (newest first)
+  conversations.sort((a, b) =>
+    new Date(b.createdAt) - new Date(a.createdAt)
+  );
+
+  // Limit results
+  if (limit > 0) {
+    conversations = conversations.slice(0, limit);
+  }
+
+  return conversations;
+}
+
+/**
+ * Update a conversation
+ */
+export async function updateConversation(convId, updates, cwd = process.cwd()) {
+  validateConversationOptions(updates);
+
+  const conversation = await getConversation(convId, cwd);
+
+  if (!conversation) {
+    return null;
+  }
+
+  const convDir = path.join(getConversationsDir(cwd), conversation.id);
+
+  // Store context and fullLog before processing
+  const newContext = updates.context;
+  const newFullLog = updates.fullLog;
+
+  // Prepare metadata updates (exclude file content fields)
+  const metaUpdates = { ...updates };
+  delete metaUpdates.id;
+  delete metaUpdates.context;
+  delete metaUpdates.fullLog;
+
+  // Update metadata
+  const meta = await fs.readJson(path.join(convDir, META_FILE));
+  const updatedMeta = {
+    ...meta,
+    ...metaUpdates,
+    updatedAt: new Date().toISOString()
+  };
+
+  await fs.writeJson(path.join(convDir, META_FILE), updatedMeta, { spaces: 2 });
+
+  // Update context if provided
+  if (newContext !== undefined) {
+    await fs.writeFile(path.join(convDir, CONTEXT_FILE), newContext);
+  }
+
+  // Update full log if provided
+  if (newFullLog !== undefined) {
+    await fs.writeFile(path.join(convDir, FULL_LOG_FILE), newFullLog);
+  }
+
+  // Update index
+  const index = await loadIndex(cwd);
+  const idx = index.conversations.findIndex(c => c.id === conversation.id);
+  if (idx !== -1) {
+    index.conversations[idx] = {
+      ...index.conversations[idx],
+      title: updatedMeta.title,
+      summary: updatedMeta.summary,
+      tags: updatedMeta.tags
+    };
+    await saveIndex(index, cwd);
+  }
+
+  return updatedMeta;
+}
+
+/**
+ * Delete a conversation
+ */
+export async function deleteConversation(convId, cwd = process.cwd()) {
+  const conversation = await getConversation(convId, cwd);
+
+  if (!conversation) {
+    return false;
+  }
+
+  const convDir = path.join(getConversationsDir(cwd), conversation.id);
+
+  // Remove directory
+  await fs.remove(convDir);
+
+  // Update index
+  const index = await loadIndex(cwd);
+  index.conversations = index.conversations.filter(c => c.id !== conversation.id);
+  await saveIndex(index, cwd);
+
+  return true;
+}
+
+/**
+ * Export conversation to a single markdown file
+ */
+export async function exportConversation(convId, outputPath, cwd = process.cwd()) {
+  const conversation = await getConversation(convId, cwd);
+
+  if (!conversation) {
+    return null;
+  }
+
+  const content = `# ${conversation.title}
+
+**ID:** ${conversation.shortId}
+**Created:** ${conversation.createdAt}
+**Tags:** ${conversation.tags?.join(', ') || 'none'}
+
+## Summary
+
+${conversation.summary || 'No summary available.'}
+
+## Context
+
+${conversation.context || 'No context available.'}
+
+${conversation.fullLog ? `## Full Log\n\n${conversation.fullLog}` : ''}
+`;
+
+  await fs.writeFile(outputPath, content);
+  return outputPath;
+}
+
+/**
+ * Get conversation context for AI consumption
+ * This is what gets loaded when @conversation:id is used
+ */
+export async function getConversationContext(convId, cwd = process.cwd()) {
+  const conversation = await getConversation(convId, cwd);
+
+  if (!conversation) {
+    return null;
+  }
+
+  const id = escapeXml(conversation.shortId);
+  const title = escapeXml(conversation.title);
+  const content = conversation.context || conversation.summary || 'No context available.';
+
+  return `
+<conversation-context id="${id}" title="${title}">
+${content}
+</conversation-context>
+`.trim();
+}
+
+/**
+ * Parse @conversation references from text
+ */
+export function parseConversationRefs(text) {
+  const pattern = /@conversation[:\s]+([a-zA-Z0-9_-]+)/gi;
+  const matches = [];
+  let match;
+
+  while ((match = pattern.exec(text)) !== null) {
+    matches.push(match[1]);
+  }
+
+  return [...new Set(matches)]; // Remove duplicates
+}
+
+/**
+ * Resolve all @conversation references in text
+ */
+export async function resolveConversationRefs(text, cwd = process.cwd()) {
+  const refs = parseConversationRefs(text);
+  const contexts = [];
+
+  for (const ref of refs) {
+    const context = await getConversationContext(ref, cwd);
+    if (context) {
+      contexts.push(context);
+    }
+  }
+
+  return {
+    refs,
+    contexts,
+    combined: contexts.join('\n\n')
+  };
+}