@yeaft/webchat-agent 0.1.662 → 0.1.663

package/unify/memory/migrate-r6-to-v2.js

@@ -1,462 +0,0 @@
-/**
- * memory/migrate-r6-to-v2.js — one-shot migration of R6 shard layout to v2.
- *
- * R6 layout (input):
- *   ~/.yeaft/memory/
- *     user/
- *       MEMORY.md                      ← legacy R5 user profile (optional)
- *       summary.md                     ← R6 paragraph synopsis (optional)
- *       index.md                       ← R6 markdown table (optional)
- *       memory-<shard>.md              ← R6 semantic shards (zero or more)
- *       entries/<date>-<slug>.md       ← R6 entries (zero or more)
- *       scopes.md                      ← legacy R5 scope index (optional)
- *     groups/<id>/                     ← (R6 plural)  same shape
- *     vp/<id>/                         ← same shape
- *     features/<id>/                   ← (R6 plural)  same shape
- *
- * v2 layout (output):
- *   ~/.yeaft/memory/
- *     user/
- *       memory.md
- *       summary.md
- *     vp/<id>/                         ← (singular)
- *       memory.md
- *       summary.md
- *     group/<id>/                      ← (singular)
- *       memory.md
- *       summary.md
- *     feature/<id>/                    ← (singular)
- *       memory.md
- *       summary.md
- *
- *   ~/.yeaft/memory.v1.bak/<ts>/...    ← snapshot of input prior to deletion
- *
- * Strategy:
- *   - Concatenate, don't synthesise. We preserve every byte of the R6 data
- *     by appending it to the new memory.md under labelled sections. The
- *     first post-migration dream (PR-C) will rewrite into a clean form.
- *     This means: zero LLM calls, zero data loss, fully deterministic.
- *   - summary.md: prefer R6 summary.md verbatim if present; otherwise leave
- *     empty for dream to fill.
- *   - Topic scope: not generated by migration (no R6 source). Topic is a
- *     pure v2 concept, populated only by future dreams.
- *
- * Modes:
- *   - dryRun: true (default) → report planned writes, touch nothing
- *   - apply: true            → actually write v2 files + take backup
- *
- * Output:
- *   { plan: [...], backedUpTo: '...', migratedScopes: N, errors: [...] }
- *
- * This module performs no LLM work and does not depend on store-v2; it
- * speaks raw filesystem so it can run before any v2 process initialises.
- */
-
-import {
-  promises as fsp,
-  existsSync,
-} from 'fs';
-import { join, dirname } from 'path';
-
-const HEADER = `<!-- migrated from R6 by migrate-r6-to-v2.js -->`;
-
-/**
- * Run migration.
- *
- * @param {{
- *   root?: string,            // default ~/.yeaft/memory
- *   backupRoot?: string,      // default ~/.yeaft/memory.v1.bak/<ts>
- *   apply?: boolean,          // false = dry-run
- *   onProgress?: (event: object) => void,
- * }} [opts]
- * @returns {Promise<{
- *   plan: object[],
- *   migratedScopes: number,
- *   skippedScopes: string[],
- *   errors: object[],
- *   backedUpTo: string|null,
- * }>}
- */
-export async function migrateR6toV2(opts = {}) {
-  const root = opts.root;
-  if (!root) throw new Error('migrateR6toV2: opts.root is required');
-  const apply = !!opts.apply;
-  const onProgress = typeof opts.onProgress === 'function' ? opts.onProgress : () => {};
-  const backupRoot = opts.backupRoot
-    || join(dirname(root), 'memory.v1.bak', new Date().toISOString().replace(/[:.]/g, '-'));
-
-  const plan = [];
-  const errors = [];
-  const skippedScopes = [];
-
-  if (!existsSync(root)) {
-    return { plan, migratedScopes: 0, skippedScopes, errors, backedUpTo: null };
-  }
-
-  const scopeRoots = await discoverR6Scopes(root);
-  onProgress({ phase: 'discover', count: scopeRoots.length });
-
-  for (const sr of scopeRoots) {
-    try {
-      const action = await planScope(root, sr);
-      plan.push(action);
-      if (action.kind === 'skip') skippedScopes.push(sr.relPath);
-    } catch (err) {
-      errors.push({ scope: sr.relPath, error: err.message });
-    }
-  }
-
-  if (!apply) {
-    return { plan, migratedScopes: 0, skippedScopes, errors, backedUpTo: null };
-  }
-
-  // 1) backup the entire memory root before we mutate
-  await fsp.mkdir(backupRoot, { recursive: true });
-  await copyDir(root, backupRoot);
-  onProgress({ phase: 'backup', backupRoot });
-
-  // 2) write v2 files
-  let migrated = 0;
-  for (const action of plan) {
-    if (action.kind !== 'migrate') continue;
-    try {
-      await applyScope(root, action);
-      onProgress({ phase: 'migrated', scope: action.dstRelPath });
-      migrated += 1;
-    } catch (err) {
-      errors.push({ scope: action.dstRelPath, error: err.message });
-    }
-  }
-
-  // 3) delete R6 leftovers (only the files we knew about — we don't rm -rf)
-  for (const action of plan) {
-    if (action.kind !== 'migrate') continue;
-    try {
-      await purgeR6Leftovers(root, action);
-    } catch (err) {
-      errors.push({ scope: action.dstRelPath, error: `purge: ${err.message}` });
-    }
-  }
-
-  return { plan, migratedScopes: migrated, skippedScopes, errors, backedUpTo: backupRoot };
-}
-
-// ─── discovery ────────────────────────────────────────────────
-
-/**
- * Walk the R6 memory root and return one entry per detected scope.
- * Returns shapes:
- *   { relPath: 'user',                  kind: 'user' }
- *   { relPath: 'vp/<id>',               kind: 'vp', id }
- *   { relPath: 'groups/<id>',           kind: 'group', id }
- *   { relPath: 'features/<id>',         kind: 'feature', id }
- *
- * @returns {Promise<{relPath: string, kind: string, id?: string}[]>}
- */
-async function discoverR6Scopes(root) {
-  const out = [];
-  if (existsSync(join(root, 'user'))) out.push({ relPath: 'user', kind: 'user' });
-
-  for (const [r6Folder, kind] of [
-    ['vp', 'vp'],
-    ['groups', 'group'],
-    ['features', 'feature'],
-    // Tolerate already-singular layouts (a partially migrated tree)
-    ['group', 'group'],
-    ['feature', 'feature'],
-  ]) {
-    const dir = join(root, r6Folder);
-    if (!existsSync(dir)) continue;
-    let names;
-    try { names = await fsp.readdir(dir, { withFileTypes: true }); }
-    catch { continue; }
-    for (const ent of names) {
-      if (!ent.isDirectory()) continue;
-      out.push({ relPath: `${r6Folder}/${ent.name}`, kind, id: ent.name, r6Folder });
-    }
-  }
-  return out;
-}
-
-// ─── plan ─────────────────────────────────────────────────────
-
-/**
- * Build a migration action for one scope: where to read from, where to
- * write to, and what content the new memory.md / summary.md will hold.
- *
- * @param {string} root
- * @param {{relPath: string, kind: string, id?: string, r6Folder?: string}} sr
- * @returns {Promise<object>}
- */
-async function planScope(root, sr) {
-  const srcAbs = join(root, sr.relPath);
-
-  // v2 destination dir (singular paths)
-  let dstRel;
-  switch (sr.kind) {
-    case 'user': dstRel = 'user'; break;
-    case 'vp': dstRel = `vp/${sr.id}`; break;
-    case 'group': dstRel = `group/${sr.id}`; break;
-    case 'feature': dstRel = `feature/${sr.id}`; break;
-    default:
-      return { kind: 'skip', srcRelPath: sr.relPath, reason: 'unknown kind' };
-  }
-
-  const r6Files = await readR6Files(srcAbs);
-  if (!r6Files.hasAny) {
-    return { kind: 'skip', srcRelPath: sr.relPath, reason: 'no R6 content' };
-  }
-
-  // If destination already has v2 layout, skip — caller may have run
-  // migration before. We do NOT clobber.
-  const dstAbs = join(root, dstRel);
-  const dstHasV2 = existsSync(join(dstAbs, 'memory.md')) || existsSync(join(dstAbs, 'summary.md'));
-  if (dstHasV2) {
-    if (sr.relPath === dstRel) {
-      // src == dst (already-singular layout). The memory.md/summary.md at
-      // `dst` are the source's own R6 files — not a foreign v2 layout. Only
-      // skip if there is genuinely no R6-specific content to fold; otherwise
-      // proceed and concatenate the R6 surfaces into a fresh memory.md.
-      if (!r6Files.hasShards && !r6Files.hasEntries
-          && !r6Files.hasIndex && !r6Files.hasLegacyMemoryMd && !r6Files.hasScopesMd) {
-        return { kind: 'skip', srcRelPath: sr.relPath, reason: 'already v2' };
-      }
-      // fall through → migrate
-    } else {
-      return {
-        kind: 'skip',
-        srcRelPath: sr.relPath,
-        reason: 'destination already has v2 files; refusing to overwrite',
-      };
-    }
-  }
-
-  return {
-    kind: 'migrate',
-    srcRelPath: sr.relPath,
-    dstRelPath: dstRel,
-    files: r6Files,
-  };
-}
-
-/**
- * Read every R6 surface file we might want to fold in.
- * @param {string} dir absolute scope dir
- */
-async function readR6Files(dir) {
-  const out = {
-    summaryMd: null,
-    indexMd: null,
-    legacyMemoryMd: null,   // R5 user profile
-    scopesMd: null,         // R5 scope index
-    shards: [],             // [{name, content}]
-    entries: [],            // [{name, content}]
-    hasShards: false,
-    hasEntries: false,
-    hasIndex: false,
-    hasLegacyMemoryMd: false,
-    hasScopesMd: false,
-    hasAny: false,
-  };
-
-  const safeRead = async (p) => {
-    try { return await fsp.readFile(p, 'utf8'); }
-    catch (err) { if (err && err.code === 'ENOENT') return null; throw err; }
-  };
-
-  out.summaryMd = await safeRead(join(dir, 'summary.md'));
-  out.indexMd   = await safeRead(join(dir, 'index.md'));
-  out.legacyMemoryMd = await safeRead(join(dir, 'MEMORY.md'));
-  out.scopesMd  = await safeRead(join(dir, 'scopes.md'));
-  out.hasIndex = !!out.indexMd;
-  out.hasLegacyMemoryMd = !!out.legacyMemoryMd;
-  out.hasScopesMd = !!out.scopesMd;
-
-  // memory-<shard>.md files (semantic shards). Skip the literal v2 file
-  // `memory.md` so a partially-migrated tree isn't double-counted.
-  let names;
-  try { names = await fsp.readdir(dir, { withFileTypes: true }); }
-  catch (err) { if (err && err.code === 'ENOENT') names = []; else throw err; }
-  for (const ent of names) {
-    if (!ent.isFile()) continue;
-    if (ent.name === 'memory.md') continue;
-    const m = /^memory-(.+)\.md(\.compacting)?$/.exec(ent.name);
-    if (!m) continue;
-    const content = await safeRead(join(dir, ent.name));
-    if (content !== null) out.shards.push({ name: ent.name, content });
-  }
-  out.hasShards = out.shards.length > 0;
-
-  // entries/*.md
-  const entriesDir = join(dir, 'entries');
-  if (existsSync(entriesDir)) {
-    let entryNames;
-    try { entryNames = (await fsp.readdir(entriesDir)).filter(n => n.endsWith('.md')).sort(); }
-    catch { entryNames = []; }
-    for (const n of entryNames) {
-      const content = await safeRead(join(entriesDir, n));
-      if (content !== null) out.entries.push({ name: n, content });
-    }
-  }
-  out.hasEntries = out.entries.length > 0;
-
-  out.hasAny = !!(out.summaryMd || out.indexMd || out.legacyMemoryMd || out.scopesMd
-                  || out.hasShards || out.hasEntries);
-  return out;
-}
-
-// ─── apply ────────────────────────────────────────────────────
-
-/**
- * Execute one planned migrate action.
- *
- * @param {string} root
- * @param {object} action
- */
-async function applyScope(root, action) {
-  const dstAbs = join(root, action.dstRelPath);
-  await fsp.mkdir(dstAbs, { recursive: true });
-
-  const memoryMd = composeMemoryMd(action.files);
-  await atomicWrite(join(dstAbs, 'memory.md'), memoryMd);
-
-  const summary = (action.files.summaryMd || '').trim();
-  if (summary) {
-    await atomicWrite(join(dstAbs, 'summary.md'), `${summary}\n`);
-  } else {
-    // Initialise an empty summary.md so listScopes detects 1-level scopes.
-    await atomicWrite(join(dstAbs, 'summary.md'), '\n');
-  }
-}
-
-/**
- * Compose the v2 memory.md by labelled-section concatenation. We keep
- * everything; dream will rewrite later.
- */
-function composeMemoryMd(files) {
-  const parts = [HEADER, ''];
-
-  if (files.legacyMemoryMd) {
-    parts.push('## Legacy MEMORY.md (R5 user profile)');
-    parts.push('');
-    parts.push(files.legacyMemoryMd.trim());
-    parts.push('');
-  }
-
-  if (files.shards.length > 0) {
-    parts.push('## R6 shards');
-    parts.push('');
-    for (const sh of files.shards) {
-      parts.push(`### ${sh.name}`);
-      parts.push('');
-      parts.push(sh.content.trim());
-      parts.push('');
-    }
-  }
-
-  if (files.entries.length > 0) {
-    parts.push('## R6 entries');
-    parts.push('');
-    for (const e of files.entries) {
-      parts.push(`### ${e.name}`);
-      parts.push('');
-      parts.push(e.content.trim());
-      parts.push('');
-    }
-  }
-
-  if (files.indexMd) {
-    parts.push('## R6 index.md (deprecated; preserved for first dream)');
-    parts.push('');
-    parts.push(files.indexMd.trim());
-    parts.push('');
-  }
-
-  if (files.scopesMd) {
-    parts.push('## Legacy scopes.md');
-    parts.push('');
-    parts.push(files.scopesMd.trim());
-    parts.push('');
-  }
-
-  parts.push('<!-- dream-state -->');
-  parts.push(`migratedAt: ${new Date().toISOString()}`);
-  parts.push('<!-- /dream-state -->');
-  parts.push('');
-
-  return parts.join('\n');
-}
-
-/**
- * Remove the R6 surface files we just folded in. Leaves any unrelated files
- * alone (for safety). Does NOT remove parent directories — listScopes will
- * tolerate empty `groups/`, `features/`, `vp/` shells.
- *
- * @param {string} root
- * @param {object} action
- */
-async function purgeR6Leftovers(root, action) {
-  const srcAbs = join(root, action.srcRelPath);
-  // The destination may equal the source (already-singular vp/group/feature),
-  // in which case we must NOT delete memory.md / summary.md — those are the
-  // newly written v2 files. Track the v2 names as protected.
-  const dstAbs = join(root, action.dstRelPath);
-  const dstSame = srcAbs === dstAbs;
-
-  // shards
-  const names = await fsp.readdir(srcAbs);
-  for (const n of names) {
-    if (dstSame && (n === 'memory.md' || n === 'summary.md')) continue;
-    const full = join(srcAbs, n);
-    if (/^memory-.+\.md(\.compacting)?$/.test(n)) {
-      await fsp.unlink(full).catch(() => {});
-    } else if (n === 'index.md' || n === 'MEMORY.md' || n === 'scopes.md') {
-      await fsp.unlink(full).catch(() => {});
-    } else if (n === 'entries') {
-      await rmDir(full);
-    } else if (n === 'index.json') {
-      await fsp.unlink(full).catch(() => {});
-    } else if (!dstSame && (n === 'memory.md' || n === 'summary.md')) {
-      // Source dir differs from dst: these were the R6 originals, already
-      // folded into the new dst. Remove so the source dir can be rmdir'd.
-      await fsp.unlink(full).catch(() => {});
-    }
-  }
-
-  // If the source path differs from destination (groups/<id> → group/<id>),
-  // remove the now-empty source dir to avoid two parallel trees. Only when
-  // it's actually empty.
-  if (!dstSame) {
-    try {
-      const remaining = await fsp.readdir(srcAbs);
-      if (remaining.length === 0) await fsp.rmdir(srcAbs);
-    } catch { /* tolerate */ }
-  }
-}
-
-// ─── tiny fs helpers ──────────────────────────────────────────
-
-async function atomicWrite(absPath, content) {
-  await fsp.mkdir(dirname(absPath), { recursive: true });
-  const tmp = `${absPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
-  await fsp.writeFile(tmp, content, 'utf8');
-  await fsp.rename(tmp, absPath);
-}
-
-async function copyDir(src, dst) {
-  await fsp.mkdir(dst, { recursive: true });
-  const entries = await fsp.readdir(src, { withFileTypes: true });
-  for (const e of entries) {
-    const s = join(src, e.name);
-    const d = join(dst, e.name);
-    if (e.isDirectory()) await copyDir(s, d);
-    else if (e.isFile()) await fsp.copyFile(s, d);
-    // ignore symlinks/sockets
-  }
-}
-
-async function rmDir(p) {
-  try {
-    await fsp.rm(p, { recursive: true, force: true });
-  } catch { /* tolerate */ }
-}