total-recall-brain 3.40.0 → 3.40.2

package/src/core/cli-maintenance.mjs

@@ -0,0 +1,45 @@
+/** Daemon-owned change detection for CLI inventories and every registered surface. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { listLocalBrains } from './brain-registry.mjs';
+import { buildPluginCatalog } from './plugin-catalog.mjs';
+import { discoverPlugins, PACKAGE_ROOT } from './plugin-loader.mjs';
+import { runBounded } from './startup-health.mjs';
+import { logger } from './logger.mjs';
+
+export function cliInputFingerprint(root) {
+  const hash=crypto.createHash('sha256');
+  const add=file=>{try{const stat=fs.statSync(file);hash.update(`${file}:${stat.mtimeMs}:${stat.size}\n`);}catch{hash.update(`missing:${file}\n`);}};
+  for(const file of ['bin/total-recall.mjs','src/core/cli-commands.mjs','src/core/cli-quick-reference.mjs'])add(path.join(PACKAGE_ROOT,file));
+  const walk=directory=>{for(const item of fs.readdirSync(directory,{withFileTypes:true})){const file=path.join(directory,item.name);if(item.isDirectory())walk(file);else if(item.name.endsWith('.mjs'))add(file);}};
+  walk(path.join(PACKAGE_ROOT,'src/cli'));
+  hash.update(buildPluginCatalog(root).fingerprint);
+  for(const plugin of discoverPlugins(root)){add(plugin.manifestPath);if(plugin.manifest.cli?.handler)add(path.join(plugin.dir,plugin.manifest.cli.handler));}
+  return hash.digest('hex');
+}
+
+export async function maintainCliSurfaces({brainDir,brains,force=false,run=runBounded,fingerprint=cliInputFingerprint}={}) {
+  const results=[];
+  for(const brain of brains || listLocalBrains({globalBrainDir:brainDir})) {
+    if(!brain.exists || brain.enabled===false)continue;
+    const root=brain.root || path.dirname(path.dirname(brain.brainDir));
+    const file=path.join(brain.brainDir,'memory-derived/cli-maintenance.json');
+    let previous;try{previous=JSON.parse(fs.readFileSync(file,'utf8'));}catch{}
+    const current=fingerprint(root);
+    if(!force && previous?.fingerprint===current){results.push({root,status:'current'});continue;}
+    const result=await run(process.execPath,[path.join(PACKAGE_ROOT,'bin/total-recall.mjs'),'plugin','refresh',...(brain.kind==='global'?['--global']:[])],{cwd:root,timeoutMs:600000,maxBytes:262144});
+    if(result.code!==0){results.push({root,status:'failed',error:result.reason || result.output?.slice(-1000) || 'CLI compilation failed'});continue;}
+    fs.mkdirSync(path.dirname(file),{recursive:true});
+    const temp=`${file}.${process.pid}.tmp`;fs.writeFileSync(temp,JSON.stringify({fingerprint:current,compiledAt:new Date().toISOString()}));fs.renameSync(temp,file);
+    results.push({root,status:'refreshed'});
+  }
+  return {ok:results.every(row=>row.status!=='failed'),results};
+}
+
+export function startCliSurfaceMaintenance({brainDir,intervalMs=30000}={}) {
+  let busy=false;
+  const tick=async()=>{if(busy)return;busy=true;try{const result=await maintainCliSurfaces({brainDir});if(!result.ok)logger.error('cli-maintenance',JSON.stringify(result));}catch(error){logger.error('cli-maintenance',error.message);}finally{busy=false;}};
+  const timer=setInterval(tick,intervalMs);timer.unref?.();void tick();
+  return {stop(){clearInterval(timer);}};
+}

package/src/core/cli-quick-reference.mjs

@@ -0,0 +1,20 @@
+/**
+ * The command map every compiled instruction surface leads with, so an agent
+ * sees which CLI owns a job before it reaches for curl, sed or ssh. The plugin
+ * namespaces and their operations are appended live by
+ * `buildInstalledPluginsSummary`, so they cannot go stale.
+ * `cli-quick-reference.spec.mjs` fails when a listed command stops existing in
+ * `total-recall --help`.
+ */
+import { CLI_COMMANDS } from './cli-commands.mjs';
+export const CLI_QUICK_REFERENCE_COMMANDS = Object.keys(CLI_COMMANDS);
+
+export const CLI_QUICK_REFERENCE = `## TOTAL RECALL CLI — USE IT FOR EVERYTHING (run \`total-recall <command> --help\` before guessing)
+- Built-in commands: ${CLI_QUICK_REFERENCE_COMMANDS.map(command => `\`${command}\``).join(' · ')}
+- Memory: \`context "<task>" --action <a>\` · \`recall "<q>" --local\` · \`remember <category> "<text>" --global|--project\` · \`edit <slug>\` · \`compile\` · \`brief\` · \`status\` / \`doctor\`
+- CREDENTIALS GO THROUGH THE AUTH PLUGIN ONLY (Total Recall has no native secrets store; never hand-roll curl/sed/ssh for keys): \`auth secret list|get <K>|set <K> --stdin|rotate <K> --stdin|--from-clipboard [--remote <t>]|rotate-auto <K>|rotation-due|shared|meta|catalog|audit|diff-env|export-env\`; remote targets: \`auth secret remote add|list|deploy <t> [--keys a,b] [--dry-run]\`. The store follows \`TR_SECRETS_BRAIN\`.
+- Auth: \`auth status|audit|key list|issue|revoke|password set --stdin|passkey|google status\`
+- Mesh nodes: \`mesh nodes|status|ping|exec <node> <cmd>|ssh <node> [cmd]|access <node>|leader\` — never ssh a machine into itself.
+- Agents and work: \`agent spawn|list|logs|kill\` · \`harness dispatch|council\` · \`task <cmd>\` · \`plugin list|install|info|library\` · \`skill <cmd>\` · \`brain <cmd>\` · \`daemon <cmd>\` · \`update --all-brains --apply\`
+- Every installed plugin namespace and its operations is listed next; run \`total-recall <namespace> --help\` for flags.
+`;