@saulwade/swl-ses 1.5.1 → 1.6.0

package/scripts/lib/diary-entry.js

@@ -1,234 +1,234 @@
-'use strict';
-
-/**
- * diary-entry.js
- *
- * Diario estructurado por sesión. Captura accomplishments, decisiones,
- * challenges y aprendizajes clave en formato consumible por `/swl:aprender`.
- *
- * Patrón adaptado de `temp/cass_memory_system-main/src/diary.ts`. Diferencias:
- *   - Zero-deps (sin zod). Validación manual.
- *   - Compatible con sistema SWL existente (sessionId, sources como instintos).
- *   - Markdown-renderable para humanos + JSON para máquinas.
- *
- * Modelo:
- *   - Una entrada de diario = una sesión de trabajo.
- *   - Vive en `.planning/sessions/diary/{id}.json`.
- *   - Es input para `/swl:aprender` (genera entradas en APRENDIZAJES.md
- *     o instintos cuando aplique).
- *   - NO sustituye a sessions/search-index.json — la sesión cruda sigue
- *     siendo la fuente de verdad. Diary es derivado estructurado.
- *
- * @module scripts/lib/diary-entry
- */
-
-const crypto = require('crypto');
-
-// ── constantes ────────────────────────────────────────────────────────────────
-
-const REQUIRED_FIELDS = ['id', 'sessionId', 'date', 'createdAt'];
-const ARRAY_FIELDS = ['accomplishments', 'decisions', 'challenges', 'keyLearnings', 'tags'];
-const MAX_ITEM_LENGTH = 500;
-const MAX_ITEMS_PER_FIELD = 20;
-
-// ── helpers ───────────────────────────────────────────────────────────────────
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function todayDate() {
-  return nowIso().slice(0, 10);
-}
-
-function shortHash(input) {
-  return crypto.createHash('sha1').update(input).digest('hex').slice(0, 8);
-}
-
-function generateDiaryId(sessionId, date) {
-  const d = (date || todayDate()).replace(/-/g, '');
-  const h = shortHash(`${sessionId}|${date || todayDate()}|${Date.now()}`);
-  return `diary-${d}-${h}`;
-}
-
-function clampString(s, max) {
-  if (typeof s !== 'string') return '';
-  const t = s.trim();
-  if (t.length <= max) return t;
-  return t.slice(0, max - 3) + '...';
-}
-
-// ── API pública ───────────────────────────────────────────────────────────────
-
-/**
- * Crea una entrada de diario nueva. Pure (devuelve objeto).
- *
- * @param {object} params
- * @param {string} params.sessionId  - obligatorio
- * @param {string} [params.agent]    - agente principal (opcional)
- * @param {string} [params.date]     - YYYY-MM-DD; default hoy
- * @param {string} [params.startTime]- ISO; default ahora
- * @returns {object} entry
- */
-function createDiary({ sessionId, agent, date, startTime } = {}) {
-  if (!sessionId || typeof sessionId !== 'string') {
-    throw new TypeError('sessionId es obligatorio (string)');
-  }
-  const finalDate = date || todayDate();
-  return {
-    id: generateDiaryId(sessionId, finalDate),
-    sessionId,
-    agent: agent || null,
-    date: finalDate,
-    startTime: startTime || nowIso(),
-    endTime: null,
-    accomplishments: [],
-    decisions: [],
-    challenges: [],
-    keyLearnings: [],
-    tags: [],
-    sourceAgents: [],
-    createdAt: nowIso(),
-  };
-}
-
-function _addItem(entry, field, text) {
-  if (!ARRAY_FIELDS.includes(field)) {
-    throw new Error(`Campo desconocido: ${field}`);
-  }
-  const trimmed = clampString(text, MAX_ITEM_LENGTH);
-  if (!trimmed) return entry;  // ignorar vacíos
-  const next = { ...entry, [field]: [...(entry[field] || [])] };
-  if (next[field].length >= MAX_ITEMS_PER_FIELD) return entry;
-  if (next[field].includes(trimmed)) return entry;  // dedup exacto
-  next[field].push(trimmed);
-  return next;
-}
-
-const addAccomplishment = (e, t) => _addItem(e, 'accomplishments', t);
-const addDecision       = (e, t) => _addItem(e, 'decisions', t);
-const addChallenge      = (e, t) => _addItem(e, 'challenges', t);
-const addLearning       = (e, t) => _addItem(e, 'keyLearnings', t);
-const addTag            = (e, t) => _addItem(e, 'tags', t);
-
-/**
- * Adjunta un agente que contribuyó (mantiene unicidad). Pure.
- */
-function addSourceAgent(entry, agentName) {
-  if (!agentName || typeof agentName !== 'string') return entry;
-  const set = new Set(entry.sourceAgents || []);
-  set.add(agentName);
-  return { ...entry, sourceAgents: [...set] };
-}
-
-/**
- * Marca el cierre de la sesión. Pure.
- */
-function closeDiary(entry, endTime) {
-  return { ...entry, endTime: endTime || nowIso() };
-}
-
-/**
- * Valida estructura de la entrada.
- * @returns {{ valid: boolean, errors: string[] }}
- */
-function validateDiary(entry) {
-  const errors = [];
-  if (!entry || typeof entry !== 'object') {
-    return { valid: false, errors: ['entry no es objeto'] };
-  }
-  for (const f of REQUIRED_FIELDS) {
-    if (!entry[f]) errors.push(`falta campo obligatorio: ${f}`);
-  }
-  for (const f of ARRAY_FIELDS) {
-    if (entry[f] != null && !Array.isArray(entry[f])) {
-      errors.push(`${f} debe ser array`);
-    }
-    if (Array.isArray(entry[f]) && entry[f].length > MAX_ITEMS_PER_FIELD) {
-      errors.push(`${f} excede el máximo de ${MAX_ITEMS_PER_FIELD} items`);
-    }
-  }
-  if (entry.date && !/^\d{4}-\d{2}-\d{2}$/.test(entry.date)) {
-    errors.push('date debe ser YYYY-MM-DD');
-  }
-  if (entry.id && !/^diary-\d{8}-[a-f0-9]+$/.test(entry.id)) {
-    errors.push('id debe ser diary-YYYYMMDD-{hash}');
-  }
-  return { valid: errors.length === 0, errors };
-}
-
-/**
- * Serializa a JSON pretty (string).
- */
-function serializeDiary(entry) {
-  return JSON.stringify(entry, null, 2);
-}
-
-/**
- * Parsea desde JSON. Lanza si está malformado.
- */
-function parseDiary(jsonText) {
-  const obj = JSON.parse(jsonText);
-  const { valid, errors } = validateDiary(obj);
-  if (!valid) throw new Error(`Diary inválido: ${errors.join('; ')}`);
-  return obj;
-}
-
-/**
- * Convierte a Markdown legible para humanos. NO se persiste — es solo
- * presentación. La fuente de verdad es el JSON.
- */
-function toMarkdown(entry) {
-  const lines = [];
-  lines.push(`# Diary ${entry.id}`);
-  lines.push('');
-  lines.push(`**Sesión**: ${entry.sessionId}`);
-  if (entry.agent) lines.push(`**Agente principal**: ${entry.agent}`);
-  lines.push(`**Fecha**: ${entry.date}`);
-  if (entry.startTime) lines.push(`**Inicio**: ${entry.startTime}`);
-  if (entry.endTime) lines.push(`**Fin**: ${entry.endTime}`);
-  if (entry.tags && entry.tags.length) lines.push(`**Tags**: ${entry.tags.join(', ')}`);
-  lines.push('');
-
-  const sections = [
-    ['Logros', entry.accomplishments],
-    ['Decisiones', entry.decisions],
-    ['Challenges', entry.challenges],
-    ['Aprendizajes clave', entry.keyLearnings],
-  ];
-  for (const [titulo, items] of sections) {
-    if (!items || !items.length) continue;
-    lines.push(`## ${titulo}`);
-    lines.push('');
-    for (const item of items) lines.push(`- ${item}`);
-    lines.push('');
-  }
-
-  if (entry.sourceAgents && entry.sourceAgents.length) {
-    lines.push(`---`);
-    lines.push(`*Agentes que contribuyeron: ${entry.sourceAgents.join(', ')}*`);
-  }
-  return lines.join('\n');
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  createDiary,
-  addAccomplishment,
-  addDecision,
-  addChallenge,
-  addLearning,
-  addTag,
-  addSourceAgent,
-  closeDiary,
-  validateDiary,
-  serializeDiary,
-  parseDiary,
-  toMarkdown,
-  generateDiaryId,
-  REQUIRED_FIELDS,
-  ARRAY_FIELDS,
-  MAX_ITEM_LENGTH,
-  MAX_ITEMS_PER_FIELD,
-};
+'use strict';
+
+/**
+ * diary-entry.js
+ *
+ * Diario estructurado por sesión. Captura accomplishments, decisiones,
+ * challenges y aprendizajes clave en formato consumible por `/swl:aprender`.
+ *
+ * Patrón adaptado de `temp/cass_memory_system-main/src/diary.ts`. Diferencias:
+ *   - Zero-deps (sin zod). Validación manual.
+ *   - Compatible con sistema SWL existente (sessionId, sources como instintos).
+ *   - Markdown-renderable para humanos + JSON para máquinas.
+ *
+ * Modelo:
+ *   - Una entrada de diario = una sesión de trabajo.
+ *   - Vive en `.planning/sessions/diary/{id}.json`.
+ *   - Es input para `/swl:aprender` (genera entradas en APRENDIZAJES.md
+ *     o instintos cuando aplique).
+ *   - NO sustituye a sessions/search-index.json — la sesión cruda sigue
+ *     siendo la fuente de verdad. Diary es derivado estructurado.
+ *
+ * @module scripts/lib/diary-entry
+ */
+
+const crypto = require('crypto');
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+const REQUIRED_FIELDS = ['id', 'sessionId', 'date', 'createdAt'];
+const ARRAY_FIELDS = ['accomplishments', 'decisions', 'challenges', 'keyLearnings', 'tags'];
+const MAX_ITEM_LENGTH = 500;
+const MAX_ITEMS_PER_FIELD = 20;
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function todayDate() {
+  return nowIso().slice(0, 10);
+}
+
+function shortHash(input) {
+  return crypto.createHash('sha1').update(input).digest('hex').slice(0, 8);
+}
+
+function generateDiaryId(sessionId, date) {
+  const d = (date || todayDate()).replace(/-/g, '');
+  const h = shortHash(`${sessionId}|${date || todayDate()}|${Date.now()}`);
+  return `diary-${d}-${h}`;
+}
+
+function clampString(s, max) {
+  if (typeof s !== 'string') return '';
+  const t = s.trim();
+  if (t.length <= max) return t;
+  return t.slice(0, max - 3) + '...';
+}
+
+// ── API pública ───────────────────────────────────────────────────────────────
+
+/**
+ * Crea una entrada de diario nueva. Pure (devuelve objeto).
+ *
+ * @param {object} params
+ * @param {string} params.sessionId  - obligatorio
+ * @param {string} [params.agent]    - agente principal (opcional)
+ * @param {string} [params.date]     - YYYY-MM-DD; default hoy
+ * @param {string} [params.startTime]- ISO; default ahora
+ * @returns {object} entry
+ */
+function createDiary({ sessionId, agent, date, startTime } = {}) {
+  if (!sessionId || typeof sessionId !== 'string') {
+    throw new TypeError('sessionId es obligatorio (string)');
+  }
+  const finalDate = date || todayDate();
+  return {
+    id: generateDiaryId(sessionId, finalDate),
+    sessionId,
+    agent: agent || null,
+    date: finalDate,
+    startTime: startTime || nowIso(),
+    endTime: null,
+    accomplishments: [],
+    decisions: [],
+    challenges: [],
+    keyLearnings: [],
+    tags: [],
+    sourceAgents: [],
+    createdAt: nowIso(),
+  };
+}
+
+function _addItem(entry, field, text) {
+  if (!ARRAY_FIELDS.includes(field)) {
+    throw new Error(`Campo desconocido: ${field}`);
+  }
+  const trimmed = clampString(text, MAX_ITEM_LENGTH);
+  if (!trimmed) return entry;  // ignorar vacíos
+  const next = { ...entry, [field]: [...(entry[field] || [])] };
+  if (next[field].length >= MAX_ITEMS_PER_FIELD) return entry;
+  if (next[field].includes(trimmed)) return entry;  // dedup exacto
+  next[field].push(trimmed);
+  return next;
+}
+
+const addAccomplishment = (e, t) => _addItem(e, 'accomplishments', t);
+const addDecision       = (e, t) => _addItem(e, 'decisions', t);
+const addChallenge      = (e, t) => _addItem(e, 'challenges', t);
+const addLearning       = (e, t) => _addItem(e, 'keyLearnings', t);
+const addTag            = (e, t) => _addItem(e, 'tags', t);
+
+/**
+ * Adjunta un agente que contribuyó (mantiene unicidad). Pure.
+ */
+function addSourceAgent(entry, agentName) {
+  if (!agentName || typeof agentName !== 'string') return entry;
+  const set = new Set(entry.sourceAgents || []);
+  set.add(agentName);
+  return { ...entry, sourceAgents: [...set] };
+}
+
+/**
+ * Marca el cierre de la sesión. Pure.
+ */
+function closeDiary(entry, endTime) {
+  return { ...entry, endTime: endTime || nowIso() };
+}
+
+/**
+ * Valida estructura de la entrada.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateDiary(entry) {
+  const errors = [];
+  if (!entry || typeof entry !== 'object') {
+    return { valid: false, errors: ['entry no es objeto'] };
+  }
+  for (const f of REQUIRED_FIELDS) {
+    if (!entry[f]) errors.push(`falta campo obligatorio: ${f}`);
+  }
+  for (const f of ARRAY_FIELDS) {
+    if (entry[f] != null && !Array.isArray(entry[f])) {
+      errors.push(`${f} debe ser array`);
+    }
+    if (Array.isArray(entry[f]) && entry[f].length > MAX_ITEMS_PER_FIELD) {
+      errors.push(`${f} excede el máximo de ${MAX_ITEMS_PER_FIELD} items`);
+    }
+  }
+  if (entry.date && !/^\d{4}-\d{2}-\d{2}$/.test(entry.date)) {
+    errors.push('date debe ser YYYY-MM-DD');
+  }
+  if (entry.id && !/^diary-\d{8}-[a-f0-9]+$/.test(entry.id)) {
+    errors.push('id debe ser diary-YYYYMMDD-{hash}');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Serializa a JSON pretty (string).
+ */
+function serializeDiary(entry) {
+  return JSON.stringify(entry, null, 2);
+}
+
+/**
+ * Parsea desde JSON. Lanza si está malformado.
+ */
+function parseDiary(jsonText) {
+  const obj = JSON.parse(jsonText);
+  const { valid, errors } = validateDiary(obj);
+  if (!valid) throw new Error(`Diary inválido: ${errors.join('; ')}`);
+  return obj;
+}
+
+/**
+ * Convierte a Markdown legible para humanos. NO se persiste — es solo
+ * presentación. La fuente de verdad es el JSON.
+ */
+function toMarkdown(entry) {
+  const lines = [];
+  lines.push(`# Diary ${entry.id}`);
+  lines.push('');
+  lines.push(`**Sesión**: ${entry.sessionId}`);
+  if (entry.agent) lines.push(`**Agente principal**: ${entry.agent}`);
+  lines.push(`**Fecha**: ${entry.date}`);
+  if (entry.startTime) lines.push(`**Inicio**: ${entry.startTime}`);
+  if (entry.endTime) lines.push(`**Fin**: ${entry.endTime}`);
+  if (entry.tags && entry.tags.length) lines.push(`**Tags**: ${entry.tags.join(', ')}`);
+  lines.push('');
+
+  const sections = [
+    ['Logros', entry.accomplishments],
+    ['Decisiones', entry.decisions],
+    ['Challenges', entry.challenges],
+    ['Aprendizajes clave', entry.keyLearnings],
+  ];
+  for (const [titulo, items] of sections) {
+    if (!items || !items.length) continue;
+    lines.push(`## ${titulo}`);
+    lines.push('');
+    for (const item of items) lines.push(`- ${item}`);
+    lines.push('');
+  }
+
+  if (entry.sourceAgents && entry.sourceAgents.length) {
+    lines.push(`---`);
+    lines.push(`*Agentes que contribuyeron: ${entry.sourceAgents.join(', ')}*`);
+  }
+  return lines.join('\n');
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  createDiary,
+  addAccomplishment,
+  addDecision,
+  addChallenge,
+  addLearning,
+  addTag,
+  addSourceAgent,
+  closeDiary,
+  validateDiary,
+  serializeDiary,
+  parseDiary,
+  toMarkdown,
+  generateDiaryId,
+  REQUIRED_FIELDS,
+  ARRAY_FIELDS,
+  MAX_ITEM_LENGTH,
+  MAX_ITEMS_PER_FIELD,
+};