@saulwade/swl-ses 1.0.0

package/hooks/lib/session-fts.js

@@ -0,0 +1,379 @@
+'use strict';
+
+/**
+ * Session FTS — Índice invertido TF-IDF para búsqueda en sesiones.
+ *
+ * Implementación zero-dependencies que reemplaza el scan lineal de
+ * memory-search.js con un índice invertido persistido en JSON.
+ *
+ * Inspirado en Hermes Agent (hermes_state.py → FTS5 en SQLite).
+ * Adaptado a JSON puro para mantener zero-dependencies en SWL-SES.
+ *
+ * Características:
+ *   - Índice invertido con scoring TF-IDF (BM25-like)
+ *   - Persistencia en .planning/sessions/search-index.json
+ *   - Indexación incremental (solo sesiones nuevas/modificadas)
+ *   - Validación por manifest (mtime + size) para invalidación
+ *   - Búsqueda sub-millisegundo en índices de <1000 sesiones
+ *
+ * @module hooks/lib/session-fts
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { atomicWriteJSON } = require('./atomic-write');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const INDEX_FILENAME = 'search-index.json';
+const INDEX_VERSION  = 1;
+
+/** Palabras vacías en español que no aportan a la búsqueda. */
+const STOPWORDS = new Set([
+  'de', 'la', 'el', 'en', 'los', 'las', 'un', 'una', 'del', 'al',
+  'y', 'o', 'a', 'que', 'es', 'se', 'no', 'por', 'con', 'para',
+  'su', 'lo', 'como', 'mas', 'pero', 'sus', 'le', 'ya', 'este',
+  'si', 'sin', 'sobre', 'todo', 'fue', 'ha', 'son', 'ser', 'puede',
+  'the', 'and', 'or', 'is', 'in', 'to', 'of', 'for', 'with', 'on',
+  'at', 'by', 'an', 'be', 'as', 'it', 'was', 'are', 'not', 'from',
+]);
+
+/** Longitud mínima de token para indexar. */
+const MIN_TOKEN_LEN = 2;
+
+/** BM25 parameters. */
+const BM25_K1 = 1.2;
+const BM25_B  = 0.75;
+
+// ---------------------------------------------------------------------------
+// Tokenización
+// ---------------------------------------------------------------------------
+
+/**
+ * Tokeniza texto para indexación o búsqueda.
+ * Normaliza a minúsculas, elimina stopwords y tokens cortos.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenize(text) {
+  if (!text || typeof text !== 'string') return [];
+  return text
+    .toLowerCase()
+    .replace(/[^a-záéíóúüñ0-9\s_-]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length > MIN_TOKEN_LEN && !STOPWORDS.has(t));
+}
+
+// ---------------------------------------------------------------------------
+// Índice invertido
+// ---------------------------------------------------------------------------
+
+/**
+ * Construye el texto indexable de una sesión.
+ * @param {object} session
+ * @returns {string}
+ */
+function buildIndexableText(session) {
+  const parts = [
+    session.summary || '',
+    session.mode || '',
+    ...(session.filesChanged || []),
+    ...(session.agentsInvoked || []),
+    ...(Object.keys(session.metricas?.herramientas || {})),
+  ];
+  return parts.join(' ');
+}
+
+/**
+ * Calcula term frequency normalizada para un documento.
+ * @param {string[]} tokens
+ * @returns {Map<string, number>}
+ */
+function computeTF(tokens) {
+  const freq = new Map();
+  for (const t of tokens) {
+    freq.set(t, (freq.get(t) || 0) + 1);
+  }
+  // Normalizar por longitud del documento
+  const len = tokens.length || 1;
+  for (const [term, count] of freq) {
+    freq.set(term, count / len);
+  }
+  return freq;
+}
+
+/**
+ * Carga el índice persistido o retorna uno vacío.
+ * @param {string} indexPath
+ * @returns {object}
+ */
+function loadIndex(indexPath) {
+  try {
+    if (!fs.existsSync(indexPath)) return null;
+    const data = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    if (data.version !== INDEX_VERSION) return null;
+    return data;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Construye o actualiza incrementalmente el índice de búsqueda.
+ *
+ * Compara manifest (mtime+size) de cada archivo para detectar cambios.
+ * Solo re-indexa sesiones nuevas o modificadas.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {object} Índice actualizado.
+ */
+function buildIndex(baseDir) {
+  const sessionsDir = path.join(baseDir, '.planning', 'sessions');
+  const indexPath   = path.join(sessionsDir, INDEX_FILENAME);
+
+  if (!fs.existsSync(sessionsDir)) return _emptyIndex();
+
+  // Cargar índice existente
+  const existing = loadIndex(indexPath);
+
+  // Listar archivos de sesión
+  let files;
+  try {
+    files = fs.readdirSync(sessionsDir)
+      .filter(f => f.startsWith('ses-') && f.endsWith('.json'));
+  } catch (_) {
+    return existing || _emptyIndex();
+  }
+
+  // Construir manifest actual (mtime + size por archivo)
+  const currentManifest = {};
+  for (const f of files) {
+    try {
+      const stat = fs.statSync(path.join(sessionsDir, f));
+      currentManifest[f] = `${stat.mtimeMs}:${stat.size}`;
+    } catch (_) {}
+  }
+
+  // Determinar si necesitamos re-indexar
+  const existingManifest = existing?.manifest || {};
+  const needsReindex = !existing ||
+    files.length !== Object.keys(existingManifest).length ||
+    files.some(f => currentManifest[f] !== existingManifest[f]);
+
+  if (!needsReindex) return existing;
+
+  // Re-indexar solo archivos nuevos/cambiados
+  const invertedIndex = existing ? { ...existing.invertedIndex } : {};
+  const docMeta       = existing ? { ...existing.docMeta } : {};
+  const docLengths    = existing ? { ...existing.docLengths } : {};
+
+  // Detectar archivos eliminados
+  const currentFileSet = new Set(files);
+  for (const f of Object.keys(existingManifest)) {
+    if (!currentFileSet.has(f)) {
+      const sessionId = f.replace('.json', '');
+      _removeFromIndex(invertedIndex, docMeta, docLengths, sessionId);
+    }
+  }
+
+  // Indexar archivos nuevos o modificados
+  let totalDocLen = 0;
+  let docCount = 0;
+
+  for (const f of files) {
+    const sessionId = f.replace('.json', '');
+
+    if (currentManifest[f] === existingManifest[f] && docMeta[sessionId]) {
+      // No cambió, mantener en índice
+      totalDocLen += docLengths[sessionId] || 0;
+      docCount++;
+      continue;
+    }
+
+    // Leer y parsear sesión
+    let session;
+    try {
+      session = JSON.parse(fs.readFileSync(path.join(sessionsDir, f), 'utf8'));
+    } catch (_) {
+      continue;
+    }
+
+    // Remover entrada previa si existe
+    _removeFromIndex(invertedIndex, docMeta, docLengths, sessionId);
+
+    // Tokenizar e indexar
+    const text   = buildIndexableText(session);
+    const tokens = tokenize(text);
+    const tf     = computeTF(tokens);
+
+    docLengths[sessionId] = tokens.length;
+    docMeta[sessionId] = {
+      id:        session.id,
+      summary:   (session.summary || '').substring(0, 200),
+      startTime: session.startTime,
+      mode:      session.mode,
+      toolCalls: session.toolCalls,
+      cost:      session.costEstimated,
+      status:    session.status,
+    };
+
+    for (const [term, freq] of tf) {
+      if (!invertedIndex[term]) invertedIndex[term] = {};
+      invertedIndex[term][sessionId] = freq;
+    }
+
+    totalDocLen += tokens.length;
+    docCount++;
+  }
+
+  const avgDocLen = docCount > 0 ? totalDocLen / docCount : 0;
+
+  const index = {
+    version: INDEX_VERSION,
+    manifest: currentManifest,
+    invertedIndex,
+    docMeta,
+    docLengths,
+    avgDocLen,
+    docCount,
+    updatedAt: new Date().toISOString(),
+  };
+
+  // Persistir atómicamente
+  try {
+    atomicWriteJSON(indexPath, index);
+  } catch (_) {
+    // Si falla la escritura, retornar índice en memoria
+  }
+
+  return index;
+}
+
+/**
+ * Busca en el índice usando scoring BM25-like.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {string} query   - Texto de búsqueda.
+ * @param {object} [opts]
+ * @param {number} [opts.limit=10]     - Máximo de resultados.
+ * @param {string} [opts.dateFrom]     - Fecha mínima (YYYY-MM-DD).
+ * @param {string} [opts.dateTo]       - Fecha máxima (YYYY-MM-DD).
+ * @param {string} [opts.mode]         - Filtrar por modo (dev/review/research).
+ * @param {string} [opts.status]       - Filtrar por estado.
+ * @returns {object[]} Resultados rankeados: [{id, summary, score, startTime, ...}]
+ */
+function search(baseDir, query, opts = {}) {
+  const index = buildIndex(baseDir);
+  if (!index || index.docCount === 0) return [];
+
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return [];
+
+  const { invertedIndex, docMeta, docLengths, avgDocLen, docCount } = index;
+  const limit    = opts.limit || 10;
+  const scores   = {};
+
+  // Calcular score BM25 por documento
+  for (const term of queryTokens) {
+    const postings = invertedIndex[term];
+    if (!postings) continue;
+
+    const df  = Object.keys(postings).length;
+    const idf = Math.log((docCount - df + 0.5) / (df + 0.5) + 1);
+
+    for (const [docId, tf] of Object.entries(postings)) {
+      const docLen   = docLengths[docId] || 1;
+      const numerator   = tf * (BM25_K1 + 1);
+      const denominator = tf + BM25_K1 * (1 - BM25_B + BM25_B * (docLen / (avgDocLen || 1)));
+      const score = idf * (numerator / denominator);
+
+      scores[docId] = (scores[docId] || 0) + score;
+    }
+  }
+
+  // Convertir a array y filtrar
+  let results = Object.entries(scores)
+    .map(([docId, score]) => ({
+      ...docMeta[docId],
+      score: Math.round(score * 1000) / 1000,
+    }))
+    .filter(r => r.id); // Descartar entradas sin metadata
+
+  // Filtros opcionales
+  if (opts.dateFrom) {
+    results = results.filter(r => {
+      const d = r.startTime ? r.startTime.split('T')[0] : '';
+      return d >= opts.dateFrom;
+    });
+  }
+  if (opts.dateTo) {
+    results = results.filter(r => {
+      const d = r.startTime ? r.startTime.split('T')[0] : '';
+      return d <= opts.dateTo;
+    });
+  }
+  if (opts.mode) {
+    results = results.filter(r => r.mode === opts.mode);
+  }
+  if (opts.status) {
+    results = results.filter(r => r.status === opts.status);
+  }
+
+  // Ordenar por score descendente
+  return results
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}
+
+/**
+ * Re-indexa todas las sesiones desde cero.
+ * Útil para migración o reparación del índice.
+ *
+ * @param {string} baseDir
+ * @returns {object} Índice reconstruido.
+ */
+function reindexAll(baseDir) {
+  const sessionsDir = path.join(baseDir, '.planning', 'sessions');
+  const indexPath   = path.join(sessionsDir, INDEX_FILENAME);
+
+  // Eliminar índice existente para forzar reconstrucción completa
+  try { fs.unlinkSync(indexPath); } catch (_) {}
+
+  return buildIndex(baseDir);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+function _emptyIndex() {
+  return {
+    version: INDEX_VERSION,
+    manifest: {},
+    invertedIndex: {},
+    docMeta: {},
+    docLengths: {},
+    avgDocLen: 0,
+    docCount: 0,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function _removeFromIndex(invertedIndex, docMeta, docLengths, sessionId) {
+  delete docMeta[sessionId];
+  delete docLengths[sessionId];
+  for (const term of Object.keys(invertedIndex)) {
+    if (invertedIndex[term][sessionId] !== undefined) {
+      delete invertedIndex[term][sessionId];
+      if (Object.keys(invertedIndex[term]).length === 0) {
+        delete invertedIndex[term];
+      }
+    }
+  }
+}
+
+module.exports = { search, buildIndex, reindexAll, tokenize };

package/hooks/lib/session-store.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Session Store — Persistencia de sesiones SWL en JSON.
+ *
+ * Almacena metricas por sesion en .planning/sessions/
+ * Cada sesion es un archivo JSON con id, timestamps, metricas.
+ *
+ * No usa SQLite para mantener zero-dependencies.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { atomicWriteJSON } = require('./atomic-write');
+
+const SESSIONS_DIR = '.planning/sessions';
+
+/**
+ * Asegura que el directorio de sesiones exista.
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @returns {string} Ruta absoluta al directorio de sesiones.
+ */
+function ensureDir(baseDir) {
+  const dir = path.join(baseDir, SESSIONS_DIR);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Genera un ID de sesion basado en timestamp.
+ * Formato: ses-YYYYMMDD-HHmmss
+ * @returns {string}
+ */
+function generarSessionId() {
+  const now = new Date();
+  const ts = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+  return `ses-${ts}`;
+}
+
+/**
+ * Crea una nueva sesion.
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @param {object} opts - Opciones iniciales.
+ * @param {string} [opts.mode='dev'] - Modo activo de la sesion.
+ * @returns {object} Sesion creada.
+ */
+function crearSesion(baseDir, opts = {}) {
+  const dir = ensureDir(baseDir);
+  const id  = generarSessionId();
+
+  const sesion = {
+    id,
+    startTime:       new Date().toISOString(),
+    endTime:         null,
+    status:          'active',
+    mode:            opts.mode || 'dev',
+    toolCalls:       0,
+    tokensEstimated: 0,
+    costEstimated:   0,
+    filesChanged:    [],
+    agentsInvoked:   [],
+    summary:         '',
+    decisiones:      [],
+    logros:          [],
+    metricas: {
+      herramientas: {},
+      modelos:      {},
+    },
+  };
+
+  const filePath = path.join(dir, `${id}.json`);
+  atomicWriteJSON(filePath, sesion);
+
+  // Actualizar latest.json como puntero logico a la sesion activa
+  const latestPath = path.join(dir, 'latest.json');
+  atomicWriteJSON(latestPath, { currentSession: id, path: filePath });
+
+  return sesion;
+}
+
+/**
+ * Actualiza la sesion activa con datos incrementales de un tool call.
+ *
+ * Campos aceptados en updates:
+ *   toolCall        {string}  - Nombre de la herramienta invocada.
+ *   modelo          {string}  - Etiqueta o ID del modelo.
+ *   tokensEstimated {number}  - Tokens a sumar al acumulado.
+ *   costEstimated   {number}  - Costo en USD a sumar al acumulado.
+ *   fileChanged     {string}  - Ruta de archivo modificado (se agrega si no existe).
+ *   agentInvoked    {string}  - Nombre del agente invocado (se agrega si no existe).
+ *   status          {string}  - Nuevo estado de la sesion.
+ *   endTime         {string}  - Timestamp de cierre ISO.
+ *   summary         {string}  - Resumen de la sesion.
+ *
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @param {object} updates - Campos a actualizar.
+ * @returns {object|null} Sesion actualizada, o null si no hay sesion activa.
+ */
+function actualizarSesion(baseDir, updates) {
+  const latestPath = path.join(baseDir, SESSIONS_DIR, 'latest.json');
+  if (!fs.existsSync(latestPath)) return null;
+
+  let latestMeta;
+  try {
+    latestMeta = JSON.parse(fs.readFileSync(latestPath, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+
+  const { path: sessionPath } = latestMeta;
+  if (!sessionPath || !fs.existsSync(sessionPath)) return null;
+
+  let sesion;
+  try {
+    sesion = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+
+  // Incrementos numericos
+  if (updates.toolCall) {
+    sesion.toolCalls++;
+    const tool = String(updates.toolCall);
+    sesion.metricas.herramientas[tool] = (sesion.metricas.herramientas[tool] || 0) + 1;
+  }
+  if (updates.modelo) {
+    const modelo = String(updates.modelo);
+    sesion.metricas.modelos[modelo] = (sesion.metricas.modelos[modelo] || 0) + 1;
+  }
+  if (typeof updates.tokensEstimated === 'number') {
+    sesion.tokensEstimated += updates.tokensEstimated;
+  }
+  if (typeof updates.costEstimated === 'number') {
+    sesion.costEstimated += updates.costEstimated;
+  }
+
+  // Listas de deduplicacion
+  if (updates.fileChanged && !sesion.filesChanged.includes(updates.fileChanged)) {
+    sesion.filesChanged.push(updates.fileChanged);
+  }
+  if (updates.agentInvoked && !sesion.agentsInvoked.includes(updates.agentInvoked)) {
+    sesion.agentsInvoked.push(updates.agentInvoked);
+  }
+
+  // Decisiones y logros de la sesión
+  if (updates.decision) {
+    const dec = typeof updates.decision === 'string'
+      ? { texto: updates.decision, fecha: new Date().toISOString() }
+      : updates.decision;
+    sesion.decisiones = sesion.decisiones || [];
+    sesion.decisiones.push(dec);
+  }
+  if (updates.logro) {
+    const logro = typeof updates.logro === 'string'
+      ? { texto: updates.logro, fecha: new Date().toISOString() }
+      : updates.logro;
+    sesion.logros = sesion.logros || [];
+    sesion.logros.push(logro);
+  }
+
+  // Campos de estado y cierre
+  if (updates.status)  sesion.status  = updates.status;
+  if (updates.endTime) sesion.endTime = updates.endTime;
+  if (updates.summary) sesion.summary = updates.summary;
+
+  atomicWriteJSON(sessionPath, sesion);
+  return sesion;
+}
+
+/**
+ * Cierra la sesion activa marcandola como completada con timestamp de fin.
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @returns {object|null} Sesion cerrada, o null si no habia sesion activa.
+ */
+function cerrarSesion(baseDir) {
+  return actualizarSesion(baseDir, {
+    status:  'completed',
+    endTime: new Date().toISOString(),
+  });
+}
+
+/**
+ * Obtiene la sesion activa actual sin modificarla.
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @returns {object|null} Sesion activa, o null si no existe.
+ */
+function obtenerSesionActiva(baseDir) {
+  const latestPath = path.join(baseDir, SESSIONS_DIR, 'latest.json');
+  if (!fs.existsSync(latestPath)) return null;
+
+  try {
+    const { path: sessionPath } = JSON.parse(fs.readFileSync(latestPath, 'utf8'));
+    if (!sessionPath || !fs.existsSync(sessionPath)) return null;
+    return JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Lista las ultimas N sesiones ordenadas por fecha descendente.
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @param {number} [limit=10] - Numero maximo de sesiones a retornar.
+ * @returns {object[]} Array de objetos de sesion.
+ */
+function listarSesiones(baseDir, limit = 10) {
+  const dir = path.join(baseDir, SESSIONS_DIR);
+  if (!fs.existsSync(dir)) return [];
+
+  return fs.readdirSync(dir)
+    .filter(f => f.startsWith('ses-') && f.endsWith('.json'))
+    .sort()
+    .reverse()
+    .slice(0, limit)
+    .map(f => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      } catch (_) {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Genera el contenido de un continue-here.md desde una sesion.
+ * El documento esta disenado para leerse en menos de 2 minutos y dar
+ * contexto suficiente para retomar el trabajo.
+ *
+ * @param {object} sesion - Objeto de sesion tal como se persiste en disco.
+ * @returns {string} Contenido markdown del documento de retoma.
+ */
+function generarContinueHere(sesion) {
+  const duracion = sesion.endTime
+    ? `${Math.round((new Date(sesion.endTime) - new Date(sesion.startTime)) / 60000)} min`
+    : 'en progreso';
+
+  const topTools = Object.entries(sesion.metricas.herramientas)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([tool, count]) => `  - ${tool}: ${count} llamadas`)
+    .join('\n');
+
+  const archivos  = sesion.filesChanged.length > 0
+    ? sesion.filesChanged.map(f => `- ${f}`).join('\n')
+    : '(ninguno)';
+
+  const agentes   = sesion.agentsInvoked.length > 0
+    ? sesion.agentsInvoked.map(a => `- ${a}`).join('\n')
+    : '(ninguno)';
+
+  return [
+    `# Continue Here — ${sesion.id}`,
+    '',
+    `**Sesion**: ${sesion.id}`,
+    `**Inicio**: ${sesion.startTime}`,
+    `**Duracion**: ${duracion}`,
+    `**Modo**: ${sesion.mode}`,
+    `**Tool calls**: ${sesion.toolCalls}`,
+    `**Costo estimado**: $${sesion.costEstimated.toFixed(2)} USD`,
+    '',
+    '## Archivos modificados',
+    archivos,
+    '',
+    '## Agentes invocados',
+    agentes,
+    '',
+    '## Herramientas mas usadas',
+    topTools || '(sin datos)',
+    '',
+    '## Resumen',
+    sesion.summary || '(sin resumen)',
+    '',
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  crearSesion,
+  actualizarSesion,
+  cerrarSesion,
+  obtenerSesionActiva,
+  listarSesiones,
+  generarContinueHere,
+  SESSIONS_DIR,
+};