@zenera/cli 1.1.24 → 1.1.26

package/dist/commands/memory.js

@@ -1,15 +1,15 @@
-import { ALL_AGENTS, buildMemoryReport, createEmbedder, GREP_FIELDS, grepMemory, hostPath, memoryDir, MemoryError, MemoryIndex, MemoryStore, MergeConflicts, mergeMemories, readProjectConfig, renderMemoryHtml, renderRecollection, } from '@zenera/neo';
+import { ALL_AGENTS, buildMemoryReport, createEmbedder, diffMemories, GREP_FIELDS, grepMemory, hostPath, memoryDir, MemoryError, MemoryIndex, MemoryStore, MergeConflicts, mergeMemories, readProjectConfig, renderMemoryHtml, renderRecollection, } from '@zenera/neo';
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
-import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, isAbsolute, join, resolve } from 'node:path';
 import { parse } from "../args.js";
 import { loadProjectEnv } from "../env.js";
 import { KeyStore } from "../keys.js";
 import { project as resolveProject } from "../resolve.js";
-import { ago, bold, bytes, CliError, confirm, count, cyan, dim, EXIT, green, isInteractive, json, note, table, usageError, write, writeAll, yellow, } from "../term.js";
-const USAGE = 'zen memory [stats|ls|search|grep|show|export|merge|forget] [args] [options]';
-const SUBCOMMANDS = ['stats', 'ls', 'search', 'grep', 'show', 'export', 'merge', 'forget'];
+import { ago, bold, bytes, CliError, confirm, count, cyan, dim, EXIT, green, isInteractive, json, note, plain, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen memory [stats|ls|search|grep|show|diff|export|merge|forget] [args] [options]';
+const SUBCOMMANDS = ['stats', 'ls', 'search', 'grep', 'show', 'diff', 'export', 'merge', 'forget'];
 /** Enough to see the shape of it; the rest is a number. */
 const LISTED = 30;
 // ---------------------------------------------------------------------------
@@ -42,12 +42,14 @@ export const memory = {
         '  search <text>          Recall it, the way an agent does. Ranked.',
         '  grep <pattern>         Every node containing it, with the matching lines.',
         '  show <id>              One node in full, with what it links to.',
+        '  diff <base>            What this memory holds that <base> did not.',
         '  export [file]          The whole graph as one HTML page.',
         '  merge <dir...>         Fold other memories into this one.',
         '  forget <id...>         Remove nodes, their vectors and their files.',
         '',
         '  --project <name|dir>   Which project. Defaults to the one you are in.',
         '  --dir <dir>            Read this memory directory instead of the project’s.',
+        '                         Run from inside a memory directory, that one is the default.',
         '  --kind <name>          Only this kind of node.',
         '  --audience <name>      Only nodes committed under this label.',
         '  --files                Only nodes that remember a file.',
@@ -104,6 +106,12 @@ export const memory = {
         '  zen memory merge <batch-dir>/*/memory',
         '',
         'which is where `zen run batch` leaves them.',
+        '',
+        '`diff` is the question after a run that started from a copy: what it',
+        'added, which of those `merge` would fold onto a node <base> already held',
+        '(a re-commit), what it revised, and which nodes `memory_load` read:',
+        '',
+        '  zen memory diff <candidate> --dir <batch-dir>/<id>/memory',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
@@ -156,6 +164,8 @@ export const memory = {
                     return await grep(opened, rest, values, ctx.json);
                 case 'show':
                     return show(opened, rest, ctx.json);
+                case 'diff':
+                    return await diff(opened, rest, ctx.cwd, ctx.json);
                 case 'export':
                     return await write_(opened, rest, values, ctx.cwd, ctx.json);
                 case 'merge':
@@ -189,6 +199,11 @@ export const memory = {
  */
 async function open(cwd, want, at, opts = {}) {
     const { create = false, lock = true } = opts;
+    // Standing inside a memory (a merged or batch copy) means that memory, not
+    // the project's own one a few directories up.
+    if (!at && !want && isMemoryDir(cwd)) {
+        at = cwd;
+    }
     if (at) {
         const dir = resolve(cwd, at);
         if (!create && !existsSync(join(dir, 'manifest.json'))) {
@@ -212,6 +227,19 @@ async function open(cwd, want, at, opts = {}) {
         at: { root: project.dir, config },
     };
 }
+/** A rag index also has a manifest and a graph.json; only a memory's manifest counts nodes and edges. */
+function isMemoryDir(dir) {
+    if (!existsSync(join(dir, 'graph.json'))) {
+        return false;
+    }
+    try {
+        const m = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8'));
+        return typeof m?.nodes === 'number' && typeof m?.edges === 'number';
+    }
+    catch {
+        return false;
+    }
+}
 // ---------------------------------------------------------------------------
 // stats
 // ---------------------------------------------------------------------------
@@ -309,23 +337,22 @@ function list(o, flags, asJson) {
         .filter((n) => !flags.stale || stale.has(n.id))
         .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
     if (asJson) {
-        json({ total: all.length, nodes: all.slice(0, limit) });
+        json({ total: all.length, nodes: all.slice(0, limit).map((n) => onHost(o, n)) });
         return;
     }
     if (!all.length) {
         note('nothing matches');
         return;
     }
-    writeAll(table(all
+    writeAll(textLast(all
         .slice(0, limit)
         .map((n) => [
         cyan(n.id),
-        n.kind,
-        n.file ? dim('⎘ ' + n.file.format) : '',
-        clip(n.text, 56),
-        dim(ago(n.createdAt)),
-        stale.has(n.id) ? yellow('superseded') : '',
-    ])));
+        n.kind + (n.file ? dim(' ⎘ ' + n.file.format) : ''),
+        n.audience.join(','),
+        dim(`r${n.revision}`),
+        dim(ago(n.createdAt)) + (stale.has(n.id) ? ' ' + yellow('superseded') : ''),
+    ]), all.slice(0, limit).map((n) => n.text)));
     if (all.length > limit) {
         write();
         note(dim(`${all.length - limit} more — raise --limit, or use \`zen memory export\``));
@@ -552,7 +579,7 @@ async function grep(o, rest, flags, asJson) {
                 hits: m.hits,
                 more: m.more,
             })),
-            unsearched: res.skipped,
+            unsearched: res.skipped.map((s) => ({ ...s, path: hostPath(o.dir, s) })),
         });
         return;
     }
@@ -562,7 +589,7 @@ async function grep(o, rest, flags, asJson) {
     }
     if (!res.found) {
         note(`nothing matches ${pattern}`);
-        unsearched(res.skipped);
+        unsearched(o, res.skipped);
         return;
     }
     for (const m of res.matches) {
@@ -570,7 +597,7 @@ async function grep(o, rest, flags, asJson) {
             ' ' +
             m.node.kind +
             (m.stale ? ' ' + yellow('superseded') : '') +
-            (m.node.file ? ' ' + dim(m.node.file.path) : ''));
+            (m.node.file ? ' ' + dim(hostPath(o.dir, m.node.file)) : ''));
         writeAll(table(m.hits.map((h) => [`  ${dim(h.where + ':' + h.line)}`, clip(h.text, 120)])));
         if (m.more) {
             write(dim(`  … ${count(m.more, 'more line')} in this node`));
@@ -580,19 +607,19 @@ async function grep(o, rest, flags, asJson) {
     if (res.truncated) {
         note(dim(`${res.found - res.matches.length} more nodes — raise --limit`));
     }
-    unsearched(res.skipped);
+    unsearched(o, res.skipped);
 }
 /**
  * Named rather than counted. A file that was not read is a hole in an answer
  * whose whole value is that it has none, so the ids have to be printable.
  */
-function unsearched(skipped) {
+function unsearched(o, skipped) {
     if (!skipped.length) {
         return;
     }
     write();
     note(yellow(`${count(skipped.length, 'file')} not searched`));
-    writeAll(table(skipped.map((s) => [`  ${cyan(s.id)}`, dim(s.reason), s.path])));
+    writeAll(table(skipped.map((s) => [`  ${cyan(s.id)}`, dim(s.reason), hostPath(o.dir, s)])));
 }
 // ---------------------------------------------------------------------------
 // show
@@ -608,7 +635,11 @@ function show(o, ids, asJson) {
     }
     const links = o.store.graph.neighbors(id);
     if (asJson) {
-        json({ node, links, file: node.file ? hostPath(o.dir, node.file) : undefined });
+        json({
+            node: onHost(o, node),
+            links,
+            file: node.file ? hostPath(o.dir, node.file) : undefined,
+        });
         return;
     }
     write(bold(node.id) + ' ' + cyan(node.kind));
@@ -653,6 +684,82 @@ function show(o, ids, asJson) {
     })));
 }
 // ---------------------------------------------------------------------------
+// diff
+// ---------------------------------------------------------------------------
+async function diff(o, rest, cwd, asJson) {
+    if (rest.length !== 1) {
+        throw usageError('diff takes exactly one base memory', 'zen memory diff <base> [--dir <dir>]');
+    }
+    const at = resolve(cwd, rest[0]);
+    if (!existsSync(join(at, 'manifest.json'))) {
+        throw usageError(`${at} is not a memory`, 'no manifest.json in it');
+    }
+    const base = await MemoryStore.open(at, { lock: false });
+    try {
+        const d = diffMemories(base, o.store);
+        const mine = (n) => onHost(o, n);
+        const theirs = (n) => n.file ? { ...n, file: { ...n.file, path: hostPath(at, n.file) } } : n;
+        if (asJson) {
+            json({
+                ...d,
+                added: d.added.map((a) => ({ ...a, node: mine(a.node) })),
+                revised: d.revised.map((r) => ({ before: theirs(r.before), after: mine(r.after) })),
+                used: d.used.map((u) => ({ ...u, node: mine(u.node) })),
+                removed: d.removed.map(theirs),
+            });
+            return;
+        }
+        const twins = d.added.filter((a) => a.twin).length;
+        write(bold(o.dir) + dim(` against ${at} · nearest by ${d.by}`));
+        write();
+        write(`${bold('added')} ${d.added.length}` +
+            (twins ? ` · ${yellow(`${twins} already held`)}` : '') +
+            ` · ${bold('revised')} ${d.revised.length}` +
+            ` · ${bold('used')} ${d.used.length}` +
+            ` · ${bold('removed')} ${d.removed.length}` +
+            ` · ${bold('edges')} +${d.edges}`);
+        if (d.added.length) {
+            write();
+            write(dim('added'));
+            writeAll(textLast(d.added.map((a) => [
+                `  ${cyan(a.node.id)}`,
+                a.node.kind,
+                a.node.audience.join(','),
+                a.nearest
+                    ? `${a.twin ? yellow('twin of') : dim('near')} ${a.nearest.id} ${dim(a.nearest.score.toFixed(2))}`
+                    : dim('nothing near'),
+            ]), d.added.map((a) => a.node.text)));
+        }
+        if (d.revised.length) {
+            write();
+            write(dim('revised'));
+            writeAll(textLast(d.revised.map((r) => [
+                `  ${cyan(r.after.id)}`,
+                r.after.kind,
+                dim(`r${r.before.revision} → r${r.after.revision}`),
+            ]), d.revised.map((r) => r.after.text)));
+        }
+        if (d.used.length) {
+            write();
+            write(dim('used — returned by memory_load'));
+            writeAll(textLast(d.used.map((u) => [`  ${cyan(u.node.id)}`, u.node.kind, `${u.loads}×`]), d.used.map((u) => u.node.text)));
+        }
+        if (d.removed.length) {
+            write();
+            write(dim('removed'));
+            writeAll(textLast(d.removed.map((n) => [`  ${cyan(n.id)}`, n.kind]), d.removed.map((n) => n.text)));
+        }
+        if (d.supersedes.length) {
+            write();
+            write(dim('supersedes'));
+            writeAll(table(d.supersedes.map((s) => [`  ${cyan(s.source)}`, '→', cyan(s.target)])));
+        }
+    }
+    finally {
+        base.release();
+    }
+}
+// ---------------------------------------------------------------------------
 // export
 // ---------------------------------------------------------------------------
 async function write_(o, rest, flags, cwd, asJson) {
@@ -661,13 +768,20 @@ async function write_(o, rest, flags, cwd, asJson) {
     }
     const named = rest[0] ?? flags.out ?? 'memory.html';
     const target = isAbsolute(named) ? named : resolve(cwd, named);
-    const report = await buildMemoryReport(o.store, { title: `${o.project} · memory` });
+    const built = await buildMemoryReport(o.store, { title: `${o.project} · memory` });
+    const report = { ...built, nodes: built.nodes.map((n) => onHost(o, n)) };
     await writeFile(target, renderMemoryHtml(report), 'utf8');
     if (asJson) {
-        json({ path: target, nodes: report.nodes.length, edges: report.edges.length });
+        json({
+            path: target,
+            from: o.dir,
+            nodes: report.nodes.length,
+            edges: report.edges.length,
+        });
     }
     else {
-        note(`${green('wrote')} ${target} ${dim(`· ${count(report.nodes.length, 'node')}, ${count(report.edges.length, 'edge')}`)}`);
+        note(`${green('wrote')} ${target} ${dim(`· ${count(report.nodes.length, 'node')}, ${count(report.edges.length, 'edge')}` +
+            ` · from ${o.dir}`)}`);
     }
     if (flags.open) {
         reveal(target);
@@ -720,7 +834,7 @@ async function merge(o, dirs, flags, cwd, asJson) {
     }
     catch (err) {
         if (err instanceof MergeConflicts) {
-            throw diverged(err, cwd, asJson);
+            throw diverged(err, asJson);
         }
         throw err;
     }
@@ -731,7 +845,7 @@ async function merge(o, dirs, flags, cwd, asJson) {
     writeAll(table([
         [dim('memory'), dim('nodes'), dim('new'), dim('shared'), dim('folded'), dim('files')],
         ...report.sources.map((s) => [
-            near(s.dir, cwd),
+            s.dir,
             String(s.nodes),
             s.added ? green(String(s.added)) : '0',
             String(s.shared),
@@ -752,7 +866,7 @@ async function merge(o, dirs, flags, cwd, asJson) {
  * point of stopping is that a person decides, and they cannot decide from a
  * count.
  */
-function diverged(err, cwd, asJson) {
+function diverged(err, asJson) {
     if (asJson) {
         json({ error: err.message, conflicts: err.conflicts });
     }
@@ -761,7 +875,7 @@ function diverged(err, cwd, asJson) {
             cyan(c.id),
             dim(`r${c.mine} ↔ r${c.theirs}`),
             clip(c.text, 48),
-            dim(near(c.dir, cwd)),
+            dim(c.dir),
         ])));
         write();
     }
@@ -818,9 +932,19 @@ function clip(text, n) {
     const one = text.replace(/\s+/g, ' ').trim();
     return one.length > n ? one.slice(0, n - 1) + '…' : one;
 }
-/** A path as it was probably typed: relative when it is below here, absolute when it is not. */
-function near(dir, cwd) {
-    const rel = relative(cwd, dir);
-    return rel && !rel.startsWith('..') ? rel : dir;
+/**
+ * A table whose last column is the text: cut to what the terminal has left,
+ * and whole when nobody is looking at a terminal — a pipe or an agent wants all of it.
+ */
+function textLast(rows, texts) {
+    const widths = rows[0]?.map((_, c) => Math.max(...rows.map((r) => plain(r[c] ?? '').length)));
+    const room = process.stdout.isTTY
+        ? Math.max(24, (process.stdout.columns || 120) - (widths ?? []).reduce((t, w) => t + w + 2, 0))
+        : Infinity;
+    return table(rows.map((r, i) => [...r, clip(texts[i] ?? '', room)]));
+}
+/** The stored `/memory/<id>.<ext>` is the agent's mount path; a terminal needs the host one. */
+function onHost(o, n) {
+    return n.file ? { ...n, file: { ...n.file, path: hostPath(o.dir, n.file) } } : n;
 }
 //# sourceMappingURL=memory.js.map