@shaykec/bridge 0.4.20 → 0.4.21

package/src/session-store.js

@@ -0,0 +1,260 @@
+/**
+ * SessionStore — persistent session storage for Socrates.
+ *
+ * Stores session metadata + full message history as one JSON file per session
+ * in the .socrates-sessions/ directory (project-local, alongside .socrates-progress.yaml).
+ *
+ * File format: .socrates-sessions/<sessionId>.json
+ * {
+ *   sessionId, title, module, topic, created, lastActive,
+ *   pinned, messageCount, messages: [{ id, role, text, data, timestamp }]
+ * }
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync, renameSync } from 'fs';
+import { join, resolve } from 'path';
+import { randomUUID } from 'crypto';
+
+const SESSION_DIR_NAME = '.socrates-sessions';
+const MAX_SESSIONS = 100;
+
+let _sessionsDir = null;
+
+/**
+ * Resolve and return the sessions directory path.
+ * Creates it if it doesn't exist. Adds to .gitignore if needed.
+ */
+export function getSessionsDir() {
+  if (_sessionsDir) return _sessionsDir;
+  _sessionsDir = resolve(process.cwd(), SESSION_DIR_NAME);
+  ensureSessionsDir();
+  return _sessionsDir;
+}
+
+/** Override sessions dir (for testing). */
+export function setSessionsDir(dir) {
+  _sessionsDir = dir;
+  ensureSessionsDir();
+}
+
+function ensureSessionsDir() {
+  if (!existsSync(_sessionsDir)) {
+    mkdirSync(_sessionsDir, { recursive: true });
+  }
+  // Best-effort: add to .gitignore
+  try {
+    const gitignore = resolve(process.cwd(), '.gitignore');
+    if (existsSync(gitignore)) {
+      const content = readFileSync(gitignore, 'utf-8');
+      if (!content.includes(SESSION_DIR_NAME)) {
+        writeFileSync(gitignore, content.trimEnd() + '\n' + SESSION_DIR_NAME + '/\n');
+      }
+    }
+  } catch { /* ignore */ }
+}
+
+function sessionPath(sessionId) {
+  return join(getSessionsDir(), `${sessionId}.json`);
+}
+
+function readSessionFile(sessionId) {
+  const fp = sessionPath(sessionId);
+  if (!existsSync(fp)) return null;
+  try {
+    return JSON.parse(readFileSync(fp, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeSessionFile(sessionId, data) {
+  const fp = sessionPath(sessionId);
+  const tmp = fp + '.tmp';
+  writeFileSync(tmp, JSON.stringify(data, null, 2));
+  renameSync(tmp, fp);
+}
+
+/**
+ * List all sessions (metadata only, no messages).
+ * Sorted by lastActive descending.
+ */
+export function listSessions() {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+  const sessions = [];
+
+  for (const file of files) {
+    try {
+      const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+      sessions.push({
+        sessionId: data.sessionId,
+        title: data.title || 'Untitled',
+        module: data.module || null,
+        topic: data.topic || null,
+        created: data.created,
+        lastActive: data.lastActive,
+        pinned: data.pinned || false,
+        messageCount: data.messageCount || 0,
+        firstMessage: data.messages?.[0]?.text?.slice(0, 100) || null,
+      });
+    } catch { /* skip corrupt files */ }
+  }
+
+  sessions.sort((a, b) => {
+    if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
+    return new Date(b.lastActive) - new Date(a.lastActive);
+  });
+
+  return sessions;
+}
+
+/**
+ * Get a full session including all messages.
+ */
+export function getSession(sessionId) {
+  return readSessionFile(sessionId);
+}
+
+/**
+ * Create a new session. Returns the created session object.
+ */
+export function createSession(sessionId, meta = {}) {
+  const now = new Date().toISOString();
+  const session = {
+    sessionId,
+    title: meta.title || 'New conversation',
+    module: meta.module || null,
+    topic: meta.topic || null,
+    created: now,
+    lastActive: now,
+    pinned: false,
+    messageCount: 0,
+    messages: [],
+  };
+  writeSessionFile(sessionId, session);
+  pruneOldSessions();
+  return session;
+}
+
+/**
+ * Append a message to a session. Creates the session if it doesn't exist.
+ */
+export function appendMessage(sessionId, message) {
+  let session = readSessionFile(sessionId);
+  if (!session) {
+    session = createSession(sessionId);
+  }
+
+  const msg = {
+    id: message.id || `msg-${Date.now()}-${randomUUID().slice(0, 8)}`,
+    role: message.role,
+    text: message.text || null,
+    data: message.data || null,
+    timestamp: message.timestamp || Date.now(),
+  };
+
+  session.messages.push(msg);
+  session.messageCount = session.messages.length;
+  session.lastActive = new Date().toISOString();
+  writeSessionFile(sessionId, session);
+  return msg;
+}
+
+/**
+ * Update session metadata (title, module, topic, pinned).
+ */
+export function updateMeta(sessionId, fields) {
+  const session = readSessionFile(sessionId);
+  if (!session) return null;
+
+  const allowed = ['title', 'module', 'topic', 'pinned'];
+  for (const key of allowed) {
+    if (fields[key] !== undefined) {
+      session[key] = fields[key];
+    }
+  }
+  session.lastActive = new Date().toISOString();
+  writeSessionFile(sessionId, session);
+  return session;
+}
+
+/**
+ * Delete a single session.
+ */
+export function deleteSession(sessionId) {
+  const fp = sessionPath(sessionId);
+  if (existsSync(fp)) {
+    unlinkSync(fp);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Delete all sessions (purge).
+ */
+export function purgeAll() {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) return 0;
+
+  const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+  for (const file of files) {
+    try {
+      unlinkSync(join(dir, file));
+    } catch { /* ignore */ }
+  }
+  return files.length;
+}
+
+/**
+ * Auto-detect module/topic from user message text.
+ * Returns { module, topic, title } or null if no command detected.
+ */
+export function detectSessionTag(text) {
+  if (!text || typeof text !== 'string') return null;
+
+  const teachMatch = text.match(/^\/teach\s+([\w-]+)/);
+  if (teachMatch) {
+    const mod = teachMatch[1];
+    return { module: mod, topic: null, title: `Teaching: ${mod}` };
+  }
+
+  const learnMatch = text.match(/^\/learn\s+(.+)/);
+  if (learnMatch) {
+    const topic = learnMatch[1].trim().slice(0, 60);
+    return { module: null, topic, title: `Learning: ${topic}` };
+  }
+
+  return null;
+}
+
+/**
+ * Generate a short title from assistant response text.
+ */
+export function generateTitle(text) {
+  if (!text || typeof text !== 'string') return 'New conversation';
+  const clean = text
+    .replace(/[#*_`~]/g, '')
+    .replace(/[\u2500-\u257F\u2580-\u259F\u25A0-\u25FF]/g, '')
+    .trim();
+  const lines = clean.split('\n').map(l => l.trim()).filter(l => l.length > 0);
+  const firstLine = lines[0] || 'New conversation';
+  if (firstLine.length <= 50) return firstLine;
+  return firstLine.slice(0, 47) + '...';
+}
+
+/**
+ * Prune sessions beyond MAX_SESSIONS, removing oldest unpinned.
+ */
+function pruneOldSessions() {
+  const sessions = listSessions();
+  if (sessions.length <= MAX_SESSIONS) return;
+
+  const unpinned = sessions.filter(s => !s.pinned);
+  const toRemove = unpinned.slice(MAX_SESSIONS - sessions.filter(s => s.pinned).length);
+  for (const s of toRemove) {
+    deleteSession(s.sessionId);
+  }
+}

package/src/session-store.test.js

@@ -0,0 +1,235 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { randomUUID } from 'crypto';
+import {
+  setSessionsDir,
+  listSessions,
+  getSession,
+  createSession,
+  appendMessage,
+  updateMeta,
+  deleteSession,
+  purgeAll,
+  detectSessionTag,
+  generateTitle,
+} from './session-store.js';
+
+let testDir;
+
+beforeEach(() => {
+  testDir = join(tmpdir(), `teach-sessions-test-${randomUUID()}`);
+  mkdirSync(testDir, { recursive: true });
+  setSessionsDir(testDir);
+});
+
+afterEach(() => {
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+describe('createSession', () => {
+  it('creates a session file with default values', () => {
+    const session = createSession('test-1');
+    expect(session.sessionId).toBe('test-1');
+    expect(session.title).toBe('New conversation');
+    expect(session.messages).toEqual([]);
+    expect(session.messageCount).toBe(0);
+    expect(session.module).toBeNull();
+    expect(session.pinned).toBe(false);
+    expect(existsSync(join(testDir, 'test-1.json'))).toBe(true);
+  });
+
+  it('creates a session with custom metadata', () => {
+    const session = createSession('test-2', { title: 'My session', module: 'git' });
+    expect(session.title).toBe('My session');
+    expect(session.module).toBe('git');
+  });
+});
+
+describe('getSession', () => {
+  it('returns null for nonexistent session', () => {
+    expect(getSession('nonexistent')).toBeNull();
+  });
+
+  it('returns full session with messages', () => {
+    createSession('s1');
+    appendMessage('s1', { role: 'user', text: 'hello' });
+    const session = getSession('s1');
+    expect(session.sessionId).toBe('s1');
+    expect(session.messages).toHaveLength(1);
+    expect(session.messages[0].text).toBe('hello');
+  });
+});
+
+describe('appendMessage', () => {
+  it('appends a message to an existing session', () => {
+    createSession('s1');
+    const msg = appendMessage('s1', { role: 'user', text: 'hello' });
+    expect(msg.role).toBe('user');
+    expect(msg.text).toBe('hello');
+    expect(msg.id).toBeTruthy();
+    expect(msg.timestamp).toBeGreaterThan(0);
+
+    const session = getSession('s1');
+    expect(session.messages).toHaveLength(1);
+    expect(session.messageCount).toBe(1);
+  });
+
+  it('auto-creates session if it does not exist', () => {
+    appendMessage('auto-created', { role: 'user', text: 'hi' });
+    const session = getSession('auto-created');
+    expect(session).not.toBeNull();
+    expect(session.messages).toHaveLength(1);
+  });
+
+  it('preserves existing messages when appending', () => {
+    createSession('s1');
+    appendMessage('s1', { role: 'user', text: 'first' });
+    appendMessage('s1', { role: 'assistant', text: 'second' });
+    const session = getSession('s1');
+    expect(session.messages).toHaveLength(2);
+    expect(session.messages[0].text).toBe('first');
+    expect(session.messages[1].text).toBe('second');
+  });
+});
+
+describe('listSessions', () => {
+  it('returns empty array when no sessions exist', () => {
+    expect(listSessions()).toEqual([]);
+  });
+
+  it('lists sessions sorted by lastActive descending', () => {
+    createSession('s1', { title: 'First' });
+    createSession('s2', { title: 'Second' });
+    appendMessage('s1', { role: 'user', text: 'bump' });
+    const list = listSessions();
+    expect(list).toHaveLength(2);
+    expect(list[0].sessionId).toBe('s1');
+    expect(list[1].sessionId).toBe('s2');
+  });
+
+  it('puts pinned sessions first', () => {
+    createSession('s1', { title: 'Unpinned' });
+    createSession('s2', { title: 'Pinned' });
+    updateMeta('s2', { pinned: true });
+    const list = listSessions();
+    expect(list[0].sessionId).toBe('s2');
+    expect(list[0].pinned).toBe(true);
+  });
+
+  it('excludes message content from list results', () => {
+    createSession('s1');
+    appendMessage('s1', { role: 'user', text: 'secret message' });
+    const list = listSessions();
+    expect(list[0].messages).toBeUndefined();
+    expect(list[0].messageCount).toBe(1);
+    expect(list[0].firstMessage).toBe('secret message');
+  });
+});
+
+describe('updateMeta', () => {
+  it('updates title', () => {
+    createSession('s1');
+    updateMeta('s1', { title: 'Renamed' });
+    expect(getSession('s1').title).toBe('Renamed');
+  });
+
+  it('updates module and topic', () => {
+    createSession('s1');
+    updateMeta('s1', { module: 'git', topic: 'branching' });
+    const session = getSession('s1');
+    expect(session.module).toBe('git');
+    expect(session.topic).toBe('branching');
+  });
+
+  it('toggles pinned', () => {
+    createSession('s1');
+    updateMeta('s1', { pinned: true });
+    expect(getSession('s1').pinned).toBe(true);
+    updateMeta('s1', { pinned: false });
+    expect(getSession('s1').pinned).toBe(false);
+  });
+
+  it('returns null for nonexistent session', () => {
+    expect(updateMeta('nope', { title: 'x' })).toBeNull();
+  });
+
+  it('ignores disallowed fields', () => {
+    createSession('s1');
+    updateMeta('s1', { messages: [], sessionId: 'hacked' });
+    const session = getSession('s1');
+    expect(session.sessionId).toBe('s1');
+    expect(session.messages).toEqual([]);
+  });
+});
+
+describe('deleteSession', () => {
+  it('deletes an existing session', () => {
+    createSession('s1');
+    expect(deleteSession('s1')).toBe(true);
+    expect(getSession('s1')).toBeNull();
+  });
+
+  it('returns false for nonexistent session', () => {
+    expect(deleteSession('nope')).toBe(false);
+  });
+});
+
+describe('purgeAll', () => {
+  it('deletes all sessions', () => {
+    createSession('s1');
+    createSession('s2');
+    createSession('s3');
+    const count = purgeAll();
+    expect(count).toBe(3);
+    expect(listSessions()).toEqual([]);
+  });
+
+  it('returns 0 when no sessions exist', () => {
+    expect(purgeAll()).toBe(0);
+  });
+});
+
+describe('detectSessionTag', () => {
+  it('detects /teach command', () => {
+    const tag = detectSessionTag('/teach git');
+    expect(tag.module).toBe('git');
+    expect(tag.title).toBe('Teaching: git');
+  });
+
+  it('detects /learn command', () => {
+    const tag = detectSessionTag('/learn React hooks');
+    expect(tag.topic).toBe('React hooks');
+    expect(tag.title).toBe('Learning: React hooks');
+    expect(tag.module).toBeNull();
+  });
+
+  it('returns null for regular messages', () => {
+    expect(detectSessionTag('hello world')).toBeNull();
+    expect(detectSessionTag('')).toBeNull();
+    expect(detectSessionTag(null)).toBeNull();
+  });
+});
+
+describe('generateTitle', () => {
+  it('generates title from short text', () => {
+    expect(generateTitle('Welcome to Git')).toBe('Welcome to Git');
+  });
+
+  it('truncates long text', () => {
+    const long = 'A'.repeat(100);
+    const title = generateTitle(long);
+    expect(title.length).toBeLessThanOrEqual(50);
+    expect(title.endsWith('...')).toBe(true);
+  });
+
+  it('strips markdown formatting', () => {
+    expect(generateTitle('# Hello **World**')).toBe('Hello World');
+  });
+
+  it('returns default for empty input', () => {
+    expect(generateTitle('')).toBe('New conversation');
+    expect(generateTitle(null)).toBe('New conversation');
+  });
+});

package/src/templates.js

@@ -1,5 +1,5 @@
 /**
- * Template engine for ClaudeTeach bridge server.
+ * Template engine for Socrates bridge server.
  * Loads HTML templates from the templates/ directory and fills
  * placeholder slots with data from visual command payloads.
  */

package/src/templates.test.js

@@ -1,5 +1,5 @@
 /**
- * Tests for ClaudeTeach bridge template engine.
+ * Tests for Socrates bridge template engine.
  */
 
 import { describe, it, expect, beforeEach } from 'vitest';

package/src/terminal.js

@@ -1,5 +1,5 @@
 /**
- * Terminal session manager for ClaudeTeach canvas terminal.
+ * Terminal session manager for Socrates canvas terminal.
  * Executes user commands via child_process with cwd tracking,
  * safety limits, and session lifecycle management.
  */
@@ -60,10 +60,10 @@ export async function createSession(initialCwd) {
       await access(initialCwd);
       cwd = resolve(initialCwd);
     } catch {
-      cwd = await mkdtemp(join(tmpdir(), 'claude-teach-'));
+      cwd = await mkdtemp(join(tmpdir(), 'socrates-'));
     }
   } else {
-    cwd = await mkdtemp(join(tmpdir(), 'claude-teach-'));
+    cwd = await mkdtemp(join(tmpdir(), 'socrates-'));
   }
 
   sessionCounter += 1;

package/src/terminal.test.js

@@ -1,5 +1,5 @@
 /**
- * Tests for ClaudeTeach bridge terminal session manager.
+ * Tests for Socrates bridge terminal session manager.
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
@@ -45,12 +45,12 @@ describe('Terminal session manager', () => {
     it('falls back to temp dir if provided cwd does not exist', async () => {
       const { cwd } = await createSession('/nonexistent/path/xyz');
       expect(cwd).not.toBe('/nonexistent/path/xyz');
-      expect(cwd).toContain('claude-teach-');
+      expect(cwd).toContain('socrates-');
     });
 
-    it('creates a temp dir with the claude-teach- prefix when no cwd given', async () => {
+    it('creates a temp dir with the socrates- prefix when no cwd given', async () => {
       const { cwd } = await createSession();
-      expect(cwd).toContain('claude-teach-');
+      expect(cwd).toContain('socrates-');
     });
 
     it('resolves provided cwd to an absolute path', async () => {
@@ -202,11 +202,11 @@ describe('Terminal session manager', () => {
 
     it('handles relative cd paths', async () => {
       const { sessionId } = await createSession('/tmp');
-      await execCommand(sessionId, 'mkdir -p /tmp/claude-teach-test-cd');
-      await execCommand(sessionId, 'cd claude-teach-test-cd');
+      await execCommand(sessionId, 'mkdir -p /tmp/socrates-test-cd');
+      await execCommand(sessionId, 'cd socrates-test-cd');
       const info = getSession(sessionId);
-      expect(info.cwd).toBe('/tmp/claude-teach-test-cd');
-      await execCommand(sessionId, 'rm -rf /tmp/claude-teach-test-cd');
+      expect(info.cwd).toBe('/tmp/socrates-test-cd');
+      await execCommand(sessionId, 'rm -rf /tmp/socrates-test-cd');
     });
 
     it('returns an error for cd to a nonexistent directory', async () => {
@@ -325,15 +325,15 @@ describe('Terminal session manager', () => {
 
     it('allows normal rm commands', async () => {
       const { sessionId } = await createSession('/tmp');
-      await execCommand(sessionId, 'touch /tmp/claude-teach-test-rm');
-      const result = await execCommand(sessionId, 'rm /tmp/claude-teach-test-rm');
+      await execCommand(sessionId, 'touch /tmp/socrates-test-rm');
+      const result = await execCommand(sessionId, 'rm /tmp/socrates-test-rm');
       expect(result.exitCode).toBe(0);
     });
 
     it('allows rm -rf on a subdirectory', async () => {
       const { sessionId } = await createSession('/tmp');
-      await execCommand(sessionId, 'mkdir -p /tmp/claude-teach-test-rmdir/sub');
-      const result = await execCommand(sessionId, 'rm -rf /tmp/claude-teach-test-rmdir');
+      await execCommand(sessionId, 'mkdir -p /tmp/socrates-test-rmdir/sub');
+      const result = await execCommand(sessionId, 'rm -rf /tmp/socrates-test-rmdir');
       expect(result.exitCode).toBe(0);
     });