total-recall-brain 3.28.2 → 3.30.0

package/src/cli/plugin/list.mjs

@@ -1,4 +1,5 @@
-import { discoverPlugins } from '../../core/plugin-loader.mjs';
+import { listInstalledPlugins } from '../../core/plugin-store.mjs';
+import { projectPluginsDir, globalPluginsDir } from '../../core/plugin-loader.mjs';
 
 function stripAnsi(str) {
   return String(str || '').replace(/\x1b\[[0-9;]*m/g, '');
@@ -10,10 +11,14 @@ function padAnsi(str, targetLen) {
   return String(str || '') + ' '.repeat(paddingNeeded);
 }
 
+function clip(str, len) {
+  const s = String(str || '');
+  return s.length > len ? s.slice(0, len - 1) + '…' : s;
+}
+
 export async function listPlugins(args = []) {
   const isJson = args.includes('--json');
-  const projectRoot = process.cwd();
-  const plugins = discoverPlugins(projectRoot);
+  const plugins = listInstalledPlugins(process.cwd());
 
   if (isJson) {
     console.log(JSON.stringify(plugins, null, 2));
@@ -23,61 +28,56 @@ export async function listPlugins(args = []) {
   console.log(`\n🔌 Total Recall — Installed Plugins\n`);
 
   if (plugins.length === 0) {
-    console.log('  No plugins installed in this project or globally (~/.agent/plugins/).');
-    console.log('  Install one with: npx total-recall plugin install <path|git-url>\n');
+    console.log(`  No plugins installed in ${projectPluginsDir(process.cwd())}`);
+    console.log(`  or globally in ${globalPluginsDir()}.`);
+    console.log('  See what you can install: npx total-recall plugin available\n');
     return;
   }
 
-  const colId = 20;
-  const colName = 28;
-  const colVer = 10;
-  const colStatus = 12;
-  const colCats = 24;
-
-  const topBorder = `┌${'─'.repeat(colId + 2)}┬${'─'.repeat(colName + 2)}┬${'─'.repeat(colVer + 2)}┬${'─'.repeat(colStatus + 2)}┬${'─'.repeat(colCats + 2)}┐`;
-  const midBorder = `├${'─'.repeat(colId + 2)}┼${'─'.repeat(colName + 2)}┼${'─'.repeat(colVer + 2)}┼${'─'.repeat(colStatus + 2)}┼${'─'.repeat(colCats + 2)}┤`;
-  const botBorder = `└${'─'.repeat(colId + 2)}┴${'─'.repeat(colName + 2)}┴${'─'.repeat(colVer + 2)}┴${'─'.repeat(colStatus + 2)}┴${'─'.repeat(colCats + 2)}┘`;
+  const cols = [
+    ['Plugin ID', 22],
+    ['Version', 9],
+    ['Scope', 8],
+    ['Source', 22],
+    ['Shared', 7],
+    ['Status', 10]
+  ];
+  const line = (l, m, r) => l + cols.map(([, w]) => '─'.repeat(w + 2)).join(m) + r;
+  const row = (cells) => '│ ' + cells.map((c, i) => padAnsi(c, cols[i][1])).join(' │ ') + ' │';
 
-  console.log(topBorder);
-  console.log(
-    `│ ${padAnsi('Plugin ID', colId)} │ ` +
-    `${padAnsi('Name', colName)} │ ` +
-    `${padAnsi('Version', colVer)} │ ` +
-    `${padAnsi('Status', colStatus)} │ ` +
-    `${padAnsi('SSSS Categories', colCats)} │`
-  );
-  console.log(midBorder);
+  console.log(line('┌', '┬', '┐'));
+  console.log(row(cols.map(([h]) => h)));
+  console.log(line('├', '┼', '┤'));
 
   for (const p of plugins) {
-    const id = p.id;
-    const name = (p.manifest.name || id).slice(0, colName);
-    const ver = p.manifest.version ? `v${p.manifest.version}` : '—';
-    const status = p.valid ? '\x1b[32mActive ✅\x1b[0m' : '\x1b[31mInvalid ❌\x1b[0m';
-    const cats = (p.manifest.ssss_schemas?.categories || []).map(c => c.name).join(', ') || '—';
-    const catStr = cats.length > colCats ? cats.slice(0, colCats - 3) + '...' : cats;
-
-    console.log(
-      `│ \x1b[1m${padAnsi(id, colId)}\x1b[0m │ ` +
-      `${padAnsi(name, colName)} │ ` +
-      `${padAnsi(ver, colVer)} │ ` +
-      `${padAnsi(status, colStatus)} │ ` +
-      `${padAnsi(catStr, colCats)} │`
-    );
+    const source = p.source.kind === 'peer' ? `peer ${p.source.peer_hostname}` : p.source.kind;
+    const status = !p.valid
+      ? '\x1b[31minvalid\x1b[0m'
+      : p.modified_since_install ? '\x1b[33mmodified\x1b[0m' : '\x1b[32mok\x1b[0m';
+    console.log(row([
+      `\x1b[1m${clip(p.id, 22)}\x1b[0m`,
+      `v${p.version}`,
+      p.scope,
+      clip(source, 22),
+      p.shared ? 'yes' : 'no',
+      status
+    ]));
   }
 
-  console.log(botBorder);
+  console.log(line('└', '┴', '┘'));
 
-  // Show detailed validation errors if any
   const invalid = plugins.filter(p => !p.valid);
   if (invalid.length > 0) {
-    console.log(`\n⚠️  Configuration Warnings:`);
+    console.log(`\n⚠️  Manifest problems:`);
     for (const inv of invalid) {
-      console.log(`  Plugin '${inv.id}':`);
-      for (const err of inv.errors) {
-        console.log(`    - ${err}`);
-      }
+      console.log(`  ${inv.id}:`);
+      for (const err of inv.errors) console.log(`    - ${err}`);
     }
   }
+  const modified = plugins.filter(p => p.modified_since_install);
+  if (modified.length > 0) {
+    console.log(`\nℹ️  Changed on disk since install (content hash differs): ${modified.map(p => p.id).join(', ')}`);
+  }
 
   console.log();
 }

package/src/cli/plugin/remove.mjs

@@ -1,12 +1,9 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
+import { uninstallPlugin, setPluginShared } from '../../core/plugin-store.mjs';
+import { publicPluginShareUrl } from '../../core/plugin-public.mjs';
 
 export async function removePlugin(args = []) {
   const isGlobal = args.includes('--global') || args.includes('-g');
-  const cleanArgs = args.filter(a => a !== '--global' && a !== '-g');
-
-  const id = cleanArgs[0];
+  const id = args.find(a => !a.startsWith('-'));
 
   if (!id) {
     console.error('❌ Error: Missing plugin ID to remove.');
@@ -14,38 +11,34 @@ export async function removePlugin(args = []) {
     process.exit(1);
   }
 
-  const searchDirs = isGlobal
-    ? [path.join(os.homedir(), '.agent', 'plugins')]
-    : [
-        path.join(process.cwd(), '.agent', 'plugins'),
-        path.join(os.homedir(), '.agent', 'plugins')
-      ];
-
-  let targetPath = null;
-  for (const dir of searchDirs) {
-    const candidate = path.join(dir, id);
-    if (fs.existsSync(candidate)) {
-      targetPath = candidate;
-      break;
-    }
+  try {
+    const result = await uninstallPlugin(id, { projectRoot: process.cwd(), global: isGlobal ? true : undefined });
+    console.log(`\n✅ Removed plugin '${id}' (${result.scope}) from ${result.dir}\n`);
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
   }
+}
 
-  if (!targetPath) {
-    console.error(`❌ Plugin '${id}' was not found in installed plugin directories.`);
+export async function sharePlugin(args = [], shared = true) {
+  const id = args.find(a => !a.startsWith('-'));
+  if (!id) {
+    console.error(`❌ Error: Missing plugin ID. Usage: total-recall plugin ${shared ? 'share' : 'unshare'} <id>`);
     process.exit(1);
   }
-
   try {
-    const stat = fs.lstatSync(targetPath);
-    if (stat.isSymbolicLink()) {
-      fs.unlinkSync(targetPath);
-      console.log(`\n✅ Unlinked plugin '${id}' from ${targetPath}\n`);
+    const plugin = await setPluginShared(id, shared, { projectRoot: process.cwd() });
+    if (shared) {
+      console.log(`\n✅ '${id}' is now shared (sha256 ${plugin.sha256?.slice(0, 16)}…).`);
+      const url = publicPluginShareUrl(id, plugin.sha256);
+      if (url) console.log(`   Send this link to another Total Recall user: ${url}`);
+      else console.log('   Set TR_PUBLIC_BASE_URL to your public HTTPS origin to print a share link.');
+      console.log('   Mesh peers can also install it with: npx total-recall plugin install peer:<this-node>/' + id + '\n');
     } else {
-      fs.rmSync(targetPath, { recursive: true, force: true });
-      console.log(`\n✅ Removed plugin '${id}' from ${targetPath}\n`);
+      console.log(`\n✅ '${id}' is no longer shared.\n`);
     }
   } catch (err) {
-    console.error(`❌ Failed to remove plugin '${id}': ${err.message}`);
+    console.error(`❌ ${err.message}`);
     process.exit(1);
   }
 }

package/src/cli/plugin/scaffold-cmd.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Scaffold CLI command handler
+ * Handles:
+ *   npx total-recall scaffold-plugin <id> [options]
+ *   npx total-recall scaffold plugin <id> [options]
+ *   npx total-recall scaffold repo <path> [options]
+ */
+
+import { createPlugin } from './create.mjs';
+
+export async function run(argv = []) {
+  let args = Array.isArray(argv) ? argv.slice(2) : [];
+  if (args[0] === 'scaffold' || args[0] === 'scaffold-plugin') {
+    args = args.slice(1);
+  }
+  if (args[0] === 'plugin') {
+    args = args.slice(1);
+  }
+
+  await createPlugin(args);
+}
+
+export default async function (args = []) {
+  let cleanArgs = Array.isArray(args) ? args : [];
+  if (cleanArgs[0] === 'plugin') {
+    cleanArgs = cleanArgs.slice(1);
+  }
+  await createPlugin(cleanArgs);
+}

package/src/cli/plugin/search.mjs

@@ -1,37 +1,122 @@
-import { CURATED_CATALOG } from "../../server/routes/plugins.mjs";
+import { listAvailableBundled } from '../../core/plugin-store.mjs';
+import { listPeerPlugins } from '../../core/plugin-peers.mjs';
 
-export async function searchCatalog(args = []) {
-  const isJson = args.includes("--json");
-  const cleanArgs = args.filter(a => a !== "--json");
-  const query = cleanArgs.join(" ").toLowerCase().trim();
-
-  let results = CURATED_CATALOG;
-  if (query) {
-    results = CURATED_CATALOG.filter(p =>
-      p.id.toLowerCase().includes(query) ||
-      p.name.toLowerCase().includes(query) ||
-      p.description.toLowerCase().includes(query) ||
-      p.tags.some(t => t.toLowerCase().includes(query))
-    );
+function parseArgs(args) {
+  const isJson = args.includes('--json');
+  let useCase = null;
+  const words = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--json') continue;
+    if (args[i] === '--use-case' && args[i + 1]) {
+      useCase = args[++i];
+      continue;
+    }
+    words.push(args[i]);
   }
+  return { isJson, useCase, query: words.join(' ').toLowerCase().trim() };
+}
+
+function matches(p, query, useCase) {
+  if (useCase && !(p.use_cases || []).includes(useCase)) return false;
+  if (!query) return true;
+  return [p.id, p.name, p.description, ...(p.use_cases || [])]
+    .some((v) => String(v || '').toLowerCase().includes(query));
+}
+
+function printPlugin(p, installHint) {
+  const installed = p.installed ? ' \x1b[32m(installed)\x1b[0m' : '';
+  console.log(`\x1b[1;36m● ${p.name}\x1b[0m (id: \x1b[33m${p.id}\x1b[0m, v${p.version})${installed}`);
+  console.log(`  ${p.description}`);
+  if (p.use_cases?.length) console.log(`  Use cases: ${p.use_cases.join(', ')}`);
+  if (p.sha256) console.log(`  sha256:    ${p.sha256.slice(0, 16)}… (${p.file_count} files, ${p.size_bytes} bytes)`);
+  if (!p.installed) console.log(`  Install:   \x1b[32mnpx total-recall plugin install ${installHint}\x1b[0m`);
+  console.log();
+}
+
+/** `plugin available` — plugins bundled with this Total Recall package. */
+export async function listAvailable(args = []) {
+  const { isJson, useCase, query } = parseArgs(args);
+  const results = listAvailableBundled(process.cwd()).filter((p) => matches(p, query, useCase));
 
   if (isJson) {
     console.log(JSON.stringify(results, null, 2));
     return;
   }
 
-  console.log("\n🔌 Total Recall — Plugin Catalog & Discovery\n");
+  console.log('\n📦 Total Recall — Bundled Plugins\n');
   if (results.length === 0) {
-    console.log("No plugins found matching \"" + query + "\".\n");
+    console.log(`No bundled plugins match${query ? ` "${query}"` : ''}${useCase ? ` for use case "${useCase}"` : ''}.\n`);
+    return;
+  }
+  for (const p of results) printPlugin(p, p.id);
+}
+
+/** `plugin peers` — plugins shared by mesh peers, asked live. */
+export async function listPeers(args = []) {
+  const { isJson, useCase, query } = parseArgs(args);
+  const result = await listPeerPlugins();
+  for (const peer of result.peers) {
+    peer.plugins = peer.plugins.filter((p) => matches(p, query, useCase));
+  }
+
+  if (isJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log('\n🛰️  Total Recall — Plugins Shared on the Mesh\n');
+  if (!result.mesh.available) {
+    console.log('  This node is not connected to a mesh. Set one up with: npx total-recall mesh enroll (see: npx total-recall mesh --help)\n');
+    return;
+  }
+  if (result.peers.length === 0) {
+    console.log('  No other nodes on the mesh.\n');
     return;
   }
+  for (const peer of result.peers) {
+    const label = peer.status === 'ok'
+      ? `\x1b[32m${peer.plugins.length} shared\x1b[0m`
+      : `\x1b[33m${peer.status}\x1b[0m${peer.error ? ` — ${peer.error}` : ''}`;
+    console.log(`\x1b[1m${peer.hostname}\x1b[0m (${peer.ip}) ${label}`);
+    for (const p of peer.plugins) {
+      console.log(`  ● ${p.name} (id: \x1b[33m${p.id}\x1b[0m, v${p.version})`);
+      console.log(`    ${p.description}`);
+      if (p.use_cases.length) console.log(`    Use cases: ${p.use_cases.join(', ')}`);
+      console.log(`    sha256 ${p.sha256.slice(0, 16)}… · ${p.file_count} files · ${p.size_bytes} bytes`);
+      console.log(`    Install: \x1b[32mnpx total-recall plugin install peer:${peer.hostname}/${p.id}\x1b[0m`);
+    }
+    console.log();
+  }
+}
+
+/** `plugin search <query>` — bundled plugins plus whatever mesh peers share. */
+export async function searchPlugins(args = []) {
+  const { isJson, useCase, query } = parseArgs(args);
+  const bundled = listAvailableBundled(process.cwd()).filter((p) => matches(p, query, useCase));
+  const peers = await listPeerPlugins();
+  const shared = [];
+  for (const peer of peers.peers) {
+    for (const p of peer.plugins) {
+      if (matches(p, query, useCase)) shared.push({ ...p, peer: peer.hostname, source: `peer:${peer.hostname}/${p.id}` });
+    }
+  }
 
-  for (const p of results) {
-    const verifiedBadge = p.verified ? " [Verified]" : "";
-    console.log("\x1b[1;36m● " + p.name + "\x1b[0m (id: \x1b[33m" + p.id + "\x1b[0m, v" + p.version + ")" + verifiedBadge);
-    console.log("  Rating:      ★ " + p.rating + " (" + p.reviewCount + " reviews) | Installs: " + p.installCount);
-    console.log("  Description: " + p.description);
-    console.log("  Tags:        " + p.tags.join(", "));
-    console.log("  Install:     \x1b[32mnpx total-recall plugin install " + p.sourceUrl + "\x1b[0m\n");
+  if (isJson) {
+    console.log(JSON.stringify({ bundled, peers: shared }, null, 2));
+    return;
+  }
+
+  console.log(`\n🔎 Plugins matching "${query || '*'}"${useCase ? ` (use case: ${useCase})` : ''}\n`);
+  if (bundled.length === 0 && shared.length === 0) {
+    console.log('No plugins found.\n');
+    return;
+  }
+  if (bundled.length) {
+    console.log('Bundled:\n');
+    for (const p of bundled) printPlugin(p, p.id);
+  }
+  if (shared.length) {
+    console.log('Shared on the mesh:\n');
+    for (const p of shared) printPlugin({ ...p, name: `${p.name} — from ${p.peer}` }, p.source);
   }
 }

package/src/cli/rebuild.mjs

@@ -4,6 +4,7 @@ import { compileSurface } from '../core/surface.mjs';
 import { detectIndexDrift } from '../core/drift-detector.mjs';
 import { resolveAgentDir, resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 import { logger } from '../core/logger.mjs';
+import { listLocalBrains } from '../core/brain-registry.mjs';
 
 /**
  * SSSS Projection Rebuild Command
@@ -107,12 +108,47 @@ export async function runRebuild(options = {}) {
   }
 }
 
+/**
+ * Recompile every registered project brain's surfaces. Each project's rules
+ * are the global rules plus its own (see mergeGlobalRuleNodes), so a global
+ * change is not done until every project has been rebuilt. Incremental: a
+ * project whose vault and the global rules are unchanged is skipped.
+ */
+export async function compileRegisteredProjects({ brains = listLocalBrains(), compile = compileSurface } = {}) {
+  let failed = 0;
+  for (const brain of brains) {
+    if (brain.kind !== 'project' || !brain.exists) continue;
+    const agentDir = path.dirname(path.dirname(brain.brainDir));
+    try {
+      const stats = await compile({
+        vaultDir: path.join(brain.brainDir, 'memory-vault'),
+        skillsDir: path.join(agentDir, 'skills'),
+        derivedDir: path.join(brain.brainDir, 'memory-derived'),
+        instructionsFile: path.join(agentDir, 'INSTRUCTIONS.md'),
+      });
+      console.log(`✅ ${brain.name}: ${stats.skipped ? 'unchanged' : `rules recompiled (${stats.skillsInjected} surfaces)`}`);
+    } catch (err) {
+      failed += 1;
+      console.error(`❌ ${brain.name}: ${err.message}`);
+      logger.error('rebuild', `Project compile failed for ${brain.brainDir}: ${err.message}`);
+    }
+  }
+  return failed;
+}
+
 export default async function cli(args) {
   const { layer, remainingArgs } = parseLayerFlag(args);
   const options = {
     check: remainingArgs.includes('--check'),
     layer,
   };
-  const code = await runRebuild(options);
+  let code = await runRebuild(options);
+  // Global rules land in every project's surfaces, so a global compile (what
+  // `remember --global` runs) or an explicit --all rebuilds each project too.
+  if (code === 0 && !options.check && (layer === 'global' || remainingArgs.includes('--all'))) {
+    console.log('--------------------------');
+    console.log('🔁 Recompiling registered project brains...');
+    if (await compileRegisteredProjects()) code = 1;
+  }
   process.exit(code);
 }

package/src/cli/recall.mjs

@@ -106,7 +106,7 @@ export default async function recall(args) {
 
   // Determine which brains to search
   const brains = getBothBrains();
-  const searchTargets = [];
+  let searchTargets = [];
 
   if (layer === 'global' || layer === 'auto') {
     if (brains.global) {
@@ -119,8 +119,23 @@ export default async function recall(args) {
     }
   }
 
+  // Brains switched off with `brain off` are not read. Filtered here, after
+  // layer selection, so an explicit --layer on an off brain says why it came
+  // back empty instead of silently searching nothing.
+  const { isBrainEnabled, readBrainToggles } = await import('../core/brain-registry.mjs');
+  const toggles = readBrainToggles();
+  const skipped = searchTargets.filter((t) => !isBrainEnabled(t.brainDir, { toggles }));
+  if (skipped.length) {
+    searchTargets = searchTargets.filter((t) => !skipped.includes(t));
+    for (const t of skipped) {
+      console.error(`  ⏸  ${t.label} brain is switched off (npx total-recall brain on ${t.label === 'global' ? 'global' : t.brainDir})`);
+    }
+  }
+
   if (searchTargets.length === 0) {
-    console.error('No brain found. Run `npx total-recall init` to create one.');
+    console.error(skipped.length
+      ? 'Every brain in scope is switched off. Run `npx total-recall brain list` to see them.'
+      : 'No brain found. Run `npx total-recall init` to create one.');
     process.exit(1);
   }
 

package/src/cli/research.mjs

@@ -51,11 +51,9 @@ function getStatusBadge(status) {
 
 function getPhaseLabel(phase) {
   switch (phase) {
-    case 'acquisition': return 'Acquisition (1/5)';
-    case 'deliberation': return 'Deliberation (2/5)';
-    case 'improvement': return 'Refinement & Clarity (3/5)';
-    case 'monitoring': return 'Sources & Feeds (4/5)';
-    case 'expansion': return 'Tangent Expansion (5/5)';
+    case 'acquisition': return 'Acquisition (1/3)';
+    case 'deliberation': return 'Deliberation (2/3)';
+    case 'improvement': return 'Refinement & Clarity (3/3)';
     default: return phase || 'unknown';
   }
 }
@@ -174,7 +172,7 @@ function handleAdd(args, resolvedBrainDir) {
   }
 
   try {
-    const item = addToQueue({ topic, priority, notes, brainDir: resolvedBrainDir });
+    const item = addToQueue({ topic, priority, notes, brainDir: resolvedBrainDir, origin: 'user', requested_via: 'cli' });
     console.log();
     console.log(`  ${green('✅ Successfully enqueued research project:')}`);
     console.log(`  ${bold('Topic:')}    "${item.topic}"`);

package/src/cli/share.mjs

@@ -112,6 +112,8 @@ export default async function share(args) {
       topic,
       priority: 'medium',
       notes: text || '',
+      origin: 'user',
+      requested_via: 'cli',
     });
     console.log(`  ✅ Queued research: "${topic}" (id: ${item.id})`);
     return;