refacil-sdd-ai 5.2.2 → 5.3.0

package/lib/project-root.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Walk up from startDir and return the topmost directory that contains a .git entry.
+ * @param {string} [startDir]
+ * @returns {string|null}
+ */
+function findGitRoot(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+  let gitRoot = null;
+
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, '.git'))) gitRoot = dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return gitRoot;
+}
+
+/**
+ * Walk up from startDir and return the topmost directory that contains refacil-sdd/.
+ * @param {string} [startDir]
+ * @returns {string|null}
+ */
+function findRefacilSddRoot(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+  let sddRoot = null;
+
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, 'refacil-sdd'))) sddRoot = dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return sddRoot;
+}
+
+/**
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isRefacilSddAiPackageDir(dir) {
+  try {
+    const pkgPath = path.join(dir, 'package.json');
+    if (!fs.existsSync(pkgPath)) return false;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg && pkg.name === 'refacil-sdd-ai';
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * If dir is the methodology npm package inside a monorepo, return the git repo root above it.
+ * @param {string} dir
+ * @returns {string}
+ */
+function elevateFromEmbeddedPackage(dir) {
+  const resolved = path.resolve(dir);
+  if (!isRefacilSddAiPackageDir(resolved)) return resolved;
+
+  const parent = path.dirname(resolved);
+  if (fs.existsSync(path.join(parent, '.git'))) return parent;
+
+  const gitRoot = findGitRoot(parent);
+  return gitRoot || resolved;
+}
+
+/**
+ * Repo root for SDD commands: prefer .git (full tree), then refacil-sdd/, else cwd.
+ * @param {string} [startDir]
+ * @returns {string}
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  const gitRoot = findGitRoot(startDir);
+  if (gitRoot) return gitRoot;
+
+  const sddRoot = findRefacilSddRoot(startDir);
+  if (sddRoot) return sddRoot;
+
+  return path.resolve(startDir);
+}
+
+/**
+ * Read optional JSON from stdin (Cursor/Claude hooks).
+ * @returns {object|null}
+ */
+function readHookStdinJson() {
+  try {
+    if (process.stdin.isTTY) return null;
+    const stdin = fs.readFileSync(0, 'utf8');
+    if (!stdin.trim()) return null;
+    return JSON.parse(stdin);
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Root of the workspace/repo for hook-driven commands (check-update, CodeGraph).
+ *
+ * Resolution order (first match wins):
+ *  1. CURSOR_PROJECT_DIR — Cursor hooks (sessionStart, workspaceOpen, preToolUse, …)
+ *  2. CLAUDE_PROJECT_DIR — Claude Code hooks (SessionStart, PreToolUse, …); Codex uses the same alias
+ *  3. workspace_roots[0] from hook JSON stdin — Cursor workspaceOpen when env is absent
+ *  4. Ascend from process.cwd(): topmost .git, then topmost refacil-sdd/
+ *  5. If result is the embedded refacil-sdd-ai npm package inside a monorepo → parent .git root
+ *
+ * OpenCode: session.created passes event.projectRoot as child `cwd` and mirrors it into (1)/(2)
+ * in runCheckUpdateCli — same effective root without Cursor-specific APIs.
+ *
+ * @param {{ hookInput?: object|null, skipStdin?: boolean }} [options]
+ * @returns {string}
+ */
+function resolveWorkspaceRoot(options = {}) {
+  const hookInput = options.hookInput !== undefined
+    ? options.hookInput
+    : (options.skipStdin ? null : readHookStdinJson());
+
+  const envDir = process.env.CURSOR_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR;
+  if (envDir) {
+    const resolved = path.resolve(envDir);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+
+  const workspaceRoot = hookInput && Array.isArray(hookInput.workspace_roots)
+    ? hookInput.workspace_roots[0]
+    : null;
+  if (workspaceRoot) {
+    const resolved = path.resolve(workspaceRoot);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+
+  const fromTraversal = findProjectRoot(process.cwd());
+  return elevateFromEmbeddedPackage(fromTraversal);
+}
+
+module.exports = {
+  findGitRoot,
+  findRefacilSddRoot,
+  findProjectRoot,
+  isRefacilSddAiPackageDir,
+  elevateFromEmbeddedPackage,
+  readHookStdinJson,
+  resolveWorkspaceRoot,
+};

package/lib/repo-ide-sync.js

@@ -7,6 +7,7 @@ const {
   globalClaudeDir,
   globalCursorDir,
   globalOpenCodeDir,
+  legacyOpenCodeDirs,
   globalCodexDir,
   readSelectedIDEs,
   writeSelectedIDEs,
@@ -36,9 +37,13 @@ function resolveSelectedIDEsForRepo(projectRoot, homeDir = os.homedir()) {
       detectedIds.includes('cursor') ||
       fs.existsSync(path.join(globalCursorDir(homeDir), 'skills')) ||
       fs.existsSync(path.join(projectRoot, '.cursor'));
+    const hasLegacyOpenCodeSkills = legacyOpenCodeDirs(homeDir).some((dir) =>
+      fs.existsSync(path.join(dir, 'skills')),
+    );
     const hasOpenCodeDir =
       detectedIds.includes('opencode') ||
       fs.existsSync(path.join(globalOpenCodeDir(homeDir), 'skills')) ||
+      hasLegacyOpenCodeSkills ||
       fs.existsSync(path.join(projectRoot, '.opencode'));
     const hasCodexFallback =
       detectedIds.includes('codex') || fs.existsSync(path.join(globalCodexDir(homeDir), 'skills'));

package/lib/spec-reader/lang.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const { loadBranchConfigWithSources } = require('../config');
+
+/** Supertonic language codes supported for TTS. */
+const TTS_LANG_CODES = new Set([
+  'en', 'ko', 'ja', 'ar', 'bg', 'cs', 'da', 'de', 'el', 'es', 'et', 'fi', 'fr',
+  'hi', 'hr', 'hu', 'id', 'it', 'lt', 'lv', 'nl', 'pl', 'pt', 'ro', 'ru', 'sk',
+  'sl', 'sv', 'tr', 'uk', 'vi',
+]);
+
+const ARTIFACT_TO_TTS = {
+  spanish: 'es',
+  english: 'en',
+};
+
+const DEFAULT_TTS_LANG = 'es';
+
+/**
+ * Map SDD artifactLanguage (english | spanish) to Supertonic code.
+ * @param {string} artifactLanguage
+ * @returns {string}
+ */
+function artifactLanguageToTtsCode(artifactLanguage) {
+  return ARTIFACT_TO_TTS[artifactLanguage] || DEFAULT_TTS_LANG;
+}
+
+/**
+ * Default TTS language from project/global SDD config.
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function resolveDefaultTtsLang(projectRoot) {
+  const { artifactLanguage } = loadBranchConfigWithSources(projectRoot);
+  return artifactLanguageToTtsCode(artifactLanguage);
+}
+
+/**
+ * @param {string} code
+ * @returns {boolean}
+ */
+function isValidTtsLang(code) {
+  return TTS_LANG_CODES.has(code);
+}
+
+// Heading patterns that unambiguously identify the artifact language from content.
+const ENGLISH_CONTENT_RE = /^##\s+(?:Objective|Purpose|Scope|Requirements?|Acceptance Criteria|Rejection Criteria)\b/im;
+const SPANISH_CONTENT_RE = /^##\s+(?:Objetivo|Propósito|Alcance|Requisitos?|Criterios? de Aceptación|Criterios? de Rechazo)\b/im;
+
+/**
+ * Detect TTS language from markdown content when no explicit meta comment is present.
+ * Returns 'en', 'es', or null if the content is ambiguous.
+ * @param {string} content
+ * @returns {string|null}
+ */
+function detectTtsLangFromContent(content) {
+  const hasEnglish = ENGLISH_CONTENT_RE.test(content);
+  const hasSpanish = SPANISH_CONTENT_RE.test(content);
+  if (hasEnglish && !hasSpanish) return 'en';
+  if (hasSpanish && !hasEnglish) return 'es';
+  return null;
+}
+
+module.exports = {
+  TTS_LANG_CODES,
+  ARTIFACT_TO_TTS,
+  DEFAULT_TTS_LANG,
+  artifactLanguageToTtsCode,
+  resolveDefaultTtsLang,
+  isValidTtsLang,
+  detectTtsLangFromContent,
+};

package/lib/spec-reader/md-parser.js

@@ -0,0 +1,299 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_FILE_BYTES = 512 * 1024;
+
+const SPEAKABLE_REPLACEMENTS = {
+  '→': ' arrow ',
+  '←': ' back ',
+  '⇒': ' then ',
+  '✅': '',
+  '❌': '',
+  '⚠️': '',
+  'ℹ️': '',
+};
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function stripFencedCodeBlocks(raw) {
+  return raw.replace(/```(\w*)[\s\S]*?```/g, (_match, lang) => {
+    if (lang && lang.trim()) {
+      // Named language: actual code — replace with spoken label, never read source
+      return ` code block: ${lang.trim()} `;
+    }
+    // No language specifier: plain-text diagram or prose — extract body and read it
+    const firstNewline = _match.indexOf('\n');
+    const lastFence = _match.lastIndexOf('```');
+    if (firstNewline < 0 || firstNewline >= lastFence) return '';
+    return _match.slice(firstNewline + 1, lastFence).trim();
+  });
+}
+
+/**
+ * Replace markdown table blocks with a spoken label.
+ * Extracts column headers from the first row: "tabla: ColA, ColB."
+ * The separator row (|----|) is used to confirm a real table.
+ * @param {string} text
+ * @returns {string}
+ */
+function stripMarkdownTables(text) {
+  const lines = text.split('\n');
+  const result = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (/^\|.+\|/.test(line)) {
+      const nextLine = lines[i + 1] || '';
+      if (/^\|[-:| ]+\|/.test(nextLine)) {
+        const headers = line.split('|').map((h) => h.trim()).filter(Boolean);
+        const label = headers.length > 0
+          ? `tabla: ${headers.join(', ')}.`
+          : 'tabla.';
+        result.push(label);
+        i += 2; // skip header + separator
+        // Read each data row as a comma-separated list
+        while (i < lines.length && /^\|/.test(lines[i])) {
+          const cells = lines[i].split('|').map((c) => c.trim()).filter(Boolean);
+          if (cells.length > 0) result.push(`${cells.join(', ')}.`);
+          i++;
+        }
+        continue;
+      }
+    }
+    result.push(line);
+    i++;
+  }
+  return result.join('\n');
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function stripInlineMarkdown(text) {
+  let out = text;
+  out = out.replace(/!\[([^\]]*)\]\([^)]+\)/g, '$1');
+  out = out.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+  out = out.replace(/`([^`]+)`/g, '$1');
+  out = out.replace(/\*\*([^*]+)\*\*/g, '$1');
+  out = out.replace(/\*([^*]+)\*/g, '$1');
+  out = out.replace(/__([^_]+)__/g, '$1');
+  out = out.replace(/_([^_]+)_/g, '$1');
+  out = out.replace(/^#{1,6}\s+/gm, '');
+  out = out.replace(/^>\s?/gm, '');
+  out = out.replace(/^[-*+]\s+/gm, '');
+  out = out.replace(/^\d+\.\s+/gm, '');
+  out = out.replace(/~~([^~]+)~~/g, '$1');
+  // Replace HTML tag references with the tag name so TTS can pronounce them
+  out = out.replace(/<\/?([a-zA-Z][a-zA-Z0-9]*)(?:\s[^>]*)?\/?>/g, (_, name) => ` ${name} `);
+  return out;
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function normalizeSpeakable(text) {
+  const emojiPattern = /[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}]/gu;
+  const lines = text.split('\n').map((line) => {
+    let out = line;
+    out = out.replace(emojiPattern, '');
+    for (const [sym, repl] of Object.entries(SPEAKABLE_REPLACEMENTS)) {
+      out = out.split(sym).join(repl);
+    }
+    out = out.replace(/\s+/g, ' ').trim();
+    // CA-07: add period at end of paragraph lines without terminal punctuation.
+    // Exclude lines ending with :,; — colons introduce lists, semicolons/commas
+    // already have their own prosodic meaning in TTS.
+    if (out && !/[.!?:,;]$/.test(out)) {
+      out = `${out}.`;
+    }
+    return out;
+  }).filter(Boolean);
+  return lines.join('\n');
+}
+
+/**
+ * @param {string} content
+ * @returns {string}
+ */
+function preprocessMarkdown(content) {
+  let out = content
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/^\s*---\s*$/gm, '');
+  const isSpanish = /artifactLanguage=spanish/i.test(content) || /^##\s+Propósito\s*$/im.test(content);
+  if (isSpanish) {
+    out = out
+      .replace(/^####\s+Scenario:/gim, '#### Escenario:')
+      .replace(/^###\s+Requirement:/gim, '### Requisito:');
+  }
+  return out;
+}
+
+/**
+ * @param {string} content
+ * @returns {string|null}
+ */
+function extractArtifactLanguageMeta(content) {
+  const m = content.match(/<!--\s*refacil-sdd:\s*artifactLanguage=(\w+)\s*-->/i);
+  return m ? m[1].toLowerCase() : null;
+}
+
+/**
+ * CA-08: Given the raw body and its already-normalized speakable text, replace the
+ * terminal period of each list item (except the last) with a comma, and ensure the
+ * last list item ends with a period. Non-list lines are left untouched.
+ *
+ * Strategy: scan the raw body to identify which *line indices* (after stripping) came
+ * from list items, then apply comma/period punctuation to those speakable lines.
+ *
+ * @param {string} rawBody  — original body before stripping
+ * @param {string} speakable — already-normalized speakable text (output of normalizeSpeakable)
+ * @returns {string}
+ */
+function applyListPunctuation(rawBody, speakable) {
+  // Identify list-item line positions in rawBody
+  const rawLines = rawBody.split('\n');
+  const isListItem = rawLines.map((l) => /^[-*+]\s+/.test(l) || /^\d+\.\s+/.test(l));
+
+  // Collect consecutive list-item runs; mark which speakable-line index corresponds
+  // We re-derive speakable lines from the speakable text (already joined by \n, filtered)
+  const speakLines = speakable.split('\n');
+  if (speakLines.length === 0) return speakable;
+
+  // Map each raw line to its speakable equivalent by filtering empty lines as done in
+  // normalizeSpeakable (filter(Boolean)). We walk both arrays together.
+  let speakIdx = 0;
+  /** @type {boolean[]} — parallel to speakLines: true if this speakable line is a list item */
+  const speakIsListItem = new Array(speakLines.length).fill(false);
+
+  for (let r = 0; r < rawLines.length && speakIdx < speakLines.length; r++) {
+    const rawTrimmed = rawLines[r].trim();
+    if (!rawTrimmed) continue; // blank lines are filtered by normalizeSpeakable
+    speakIsListItem[speakIdx] = isListItem[r];
+    speakIdx += 1;
+  }
+
+  // Find all consecutive list-item runs in speakLines and apply punctuation
+  let i = 0;
+  const result = [...speakLines];
+  while (i < result.length) {
+    if (!speakIsListItem[i]) {
+      i += 1;
+      continue;
+    }
+    // Find end of this run
+    let runEnd = i;
+    while (runEnd + 1 < result.length && speakIsListItem[runEnd + 1]) {
+      runEnd += 1;
+    }
+    if (runEnd > i) {
+      // More than one item: replace period with comma for all except last
+      for (let j = i; j < runEnd; j++) {
+        result[j] = result[j].replace(/\.$/, ',');
+      }
+      // Ensure last item ends with period (normalizeSpeakable already adds it, but be safe)
+      if (!/[.!?]$/.test(result[runEnd])) {
+        result[runEnd] = `${result[runEnd]}.`;
+      }
+    }
+    // Single-item lists already have a period from normalizeSpeakable — nothing to do
+    i = runEnd + 1;
+  }
+
+  return result.join('\n');
+}
+
+/**
+ * Split markdown into sections by ATX headings (## and deeper; # starts new section too).
+ * @param {string} content
+ * @returns {{ title: string, text: string, rawMarkdown: string }[]}
+ */
+function parseMarkdown(content) {
+  const normalized = preprocessMarkdown(content).replace(/\r\n/g, '\n');
+  const lines = normalized.split('\n');
+  const sections = [];
+  let currentTitle = '';
+  let currentLines = [];
+
+  const flush = () => {
+    const body = currentLines.join('\n').trim();
+    const rawMarkdown = body;
+    const afterCode = stripFencedCodeBlocks(body);
+    const afterTables = stripMarkdownTables(afterCode);
+    const inline = stripInlineMarkdown(afterTables);
+    const speakable = normalizeSpeakable(inline);
+    // TTS flattens \n to space (supertonic-helper line 107), so each line must end
+    // with sentence-ending punctuation to create natural pauses. Commas produce only
+    // a brief pause that runs long list items together; periods create a full stop.
+    // applyListPunctuation (CA-08 comma conversion) is intentionally skipped here.
+    const text = speakable;
+    if (!text) {
+      currentLines = [];
+      return;
+    }
+    sections.push({ title: currentTitle.trim(), text, rawMarkdown });
+    currentLines = [];
+  };
+
+  for (const line of lines) {
+    const heading = line.match(/^(#{1,6})\s+(.+)$/);
+    if (heading) {
+      const level = heading[1].length;
+      // #### and deeper: stay inside the current requirement (avoid 40+ micro-sections)
+      if (level >= 4) {
+        const sub = normalizeSpeakable(stripInlineMarkdown(heading[2]));
+        if (sub) currentLines.push(sub);
+        continue;
+      }
+      const hasBody = currentLines.some((l) => l.trim());
+      if (level === 1) {
+        if (hasBody) flush();
+        currentTitle = normalizeSpeakable(stripInlineMarkdown(heading[2]));
+        currentLines = [];
+        continue;
+      }
+      if (hasBody) flush();
+      else if (currentTitle) currentLines = [];
+      currentTitle = normalizeSpeakable(stripInlineMarkdown(heading[2]));
+      continue;
+    }
+    if (line.trim()) currentLines.push(line);
+  }
+
+  flush();
+
+  if (sections.length === 0) {
+    return [{ title: '', text: '' }];
+  }
+
+  return sections;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {{ title: string, text: string }[]}
+ */
+function parseFile(filePath) {
+  const stat = fs.statSync(filePath);
+  if (stat.size > MAX_FILE_BYTES) {
+    throw new Error(`File exceeds maximum size (${MAX_FILE_BYTES} bytes)`);
+  }
+  const content = fs.readFileSync(filePath, 'utf8');
+  if (!content.trim()) {
+    return [{ title: '', text: '' }];
+  }
+  return parseMarkdown(content);
+}
+
+module.exports = {
+  parseMarkdown,
+  parseFile,
+  preprocessMarkdown,
+  extractArtifactLanguageMeta,
+  MAX_FILE_BYTES,
+};

package/lib/spec-reader/session.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const HOME_DIR = path.join(os.homedir(), '.refacil-sdd-ai');
+const SESSIONS_DIR = path.join(HOME_DIR, 'read-spec-sessions');
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+const SESSION_ID_RE = /^[a-f0-9-]{36}$/i;
+
+function ensureSessionsDir() {
+  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+}
+
+/**
+ * @param {string} sessionId
+ * @returns {boolean}
+ */
+function isValidSessionId(sessionId) {
+  return typeof sessionId === 'string' && SESSION_ID_RE.test(sessionId);
+}
+
+function sessionFilePath(sessionId) {
+  return path.join(SESSIONS_DIR, `${sessionId}.json`);
+}
+
+/**
+ * Remove session files older than SESSION_TTL_MS.
+ */
+function cleanupStaleSessions() {
+  ensureSessionsDir();
+  const now = Date.now();
+  let entries;
+  try {
+    entries = fs.readdirSync(SESSIONS_DIR);
+  } catch (_) {
+    return;
+  }
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    const full = path.join(SESSIONS_DIR, name);
+    try {
+      const stat = fs.statSync(full);
+      if (now - stat.mtimeMs > SESSION_TTL_MS) {
+        fs.unlinkSync(full);
+      }
+    } catch (_) {
+      // ignore per-file errors
+    }
+  }
+}
+
+/**
+ * Write a file-mode session (single file).
+ *
+ * @param {{ sections: object[], meta: object, sourcePath: string, createdAt?: string }} payload
+ * @returns {string} sessionId
+ */
+function writeSession(payload) {
+  ensureSessionsDir();
+  cleanupStaleSessions();
+  const sessionId = crypto.randomUUID();
+  const filePath = sessionFilePath(sessionId);
+  const data = {
+    mode: 'file',
+    sections: payload.sections,
+    meta: payload.meta,
+    sourcePath: payload.sourcePath,
+    createdAt: payload.createdAt || new Date().toISOString(),
+  };
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  return sessionId;
+}
+
+/**
+ * Write a folder-mode session (multiple files with sidebar).
+ *
+ * Session format:
+ * {
+ *   mode: "folder",
+ *   files: [{ name: string, relPath: string, sections: object[] }],
+ *   selectedFile: string,
+ *   meta: { lang, voice, speed, changeName },
+ *   sourcePath: string,
+ *   createdAt: string
+ * }
+ *
+ * @param {{ files: Array<{ name: string, relPath: string, sections: object[] }>, selectedFile: string, meta: object, sourcePath: string, createdAt?: string }} payload
+ * @returns {string} sessionId
+ */
+function writeFolderSession(payload) {
+  ensureSessionsDir();
+  cleanupStaleSessions();
+  const sessionId = crypto.randomUUID();
+  const filePath = sessionFilePath(sessionId);
+  // Expose the sections of the selected file at the top level for backward compat
+  // with the /api/read-spec handler which reads sessionData.sections.
+  const selectedFile = payload.files.find((f) => f.name === payload.selectedFile) || payload.files[0];
+  const data = {
+    mode: 'folder',
+    files: payload.files,
+    selectedFile: payload.selectedFile,
+    // sections of the initially selected file (for compat with existing HTTP handler)
+    sections: selectedFile ? selectedFile.sections : [],
+    meta: payload.meta,
+    sourcePath: payload.sourcePath,
+    createdAt: payload.createdAt || new Date().toISOString(),
+  };
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  return sessionId;
+}
+
+/**
+ * @param {string} sessionId
+ * @returns {object | null}
+ */
+function readSession(sessionId) {
+  if (!isValidSessionId(sessionId)) return null;
+  const filePath = sessionFilePath(sessionId);
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = {
+  HOME_DIR,
+  SESSIONS_DIR,
+  SESSION_TTL_MS,
+  isValidSessionId,
+  writeSession,
+  writeFolderSession,
+  readSession,
+  cleanupStaleSessions,
+};