total-recall-brain 3.32.2 → 3.32.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.32.2",
+  "version": "3.32.4",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [
@@ -23,6 +23,7 @@
     "frontend/src/",
     "extension/",
     "plugins/",
+    "!plugins/**/*.spec.mjs",
     "templates/",
     "scaffold/",
     "docs/ARCHITECTURE.md",

package/plugins/operator-alerts/README.md

@@ -0,0 +1,27 @@
+# Operator Alerts
+
+Operator alerts from agents, scripts and scheduled tasks.
+
+**Channels:** `os` (terminal-notifier, osascript, notify-send), `email`
+(SMTP2GO), `sms` (Telnyx), `webhook`, `github`. `slack`, `discord`, `telegram`
+and `expo` are stubs: they report `stub` and send nothing.
+
+**Config** (later wins): `~/.total-recall/notifications/config.json`,
+`<repo>/.agent/notify.json`, `--config <file>`.
+
+```json
+{
+  "email": { "key_secret": "SMTP2GO_KEY", "to": "secret:OPERATOR_EMAIL", "from": "alerts@your-verified-domain" },
+  "sms":   { "key_secret": "TELNYX_KEY", "to": "secret:OPERATOR_PHONE", "from": "+1XXXXXXXXXX" }
+}
+```
+
+`*_secret` values name Total Recall secrets read with `secret get` in-process.
+`to` is a literal or `secret:NAME`.
+
+**Commands:** `alerts send|test|config|log`. `status: accepted` means the
+provider took it, not that it arrived. Ledger: `sent.jsonl` beside the log in
+`~/.total-recall/notifications/` (override with `TR_NOTIFY_HOME`).
+
+**Network access:** api.smtp2go.com, api.telnyx.com, api.github.com, and the
+webhook URL you configure. Nothing else.

package/plugins/operator-alerts/cli.mjs

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { sendNotification, loadConfig } from './notify-core.mjs';
+
+const USAGE = `usage:
+  total-recall alerts send --title T --message M [--channels os,email,sms,webhook,github] [--event-id ID]
+                                  [--severity info|high|critical] [--source S] [--quiet-hours 22-7] [--config file] [--dry-run]
+  total-recall alerts test [--channels ...]     dry-run every configured channel
+  total-recall alerts config                    show the merged config (secret names only)
+  total-recall alerts log [--limit N]           recent sends from the ledger`;
+
+function flags(args) {
+  const a = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const t = args[i];
+    if (t === '--dry-run') a.dry = true;
+    else if (t.startsWith('--')) a[t.slice(2)] = args[++i];
+    else a._.push(t);
+  }
+  return a;
+}
+
+export async function run(argv = []) {
+  const args = Array.isArray(argv) ? argv.slice(3) : [];
+  const sub = args[0] || 'help';
+  const a = flags(args.slice(1));
+  const config = loadConfig(process.cwd(), a.config || null);
+
+  if (sub === 'config') {
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+  if (sub === 'log') {
+    const home = process.env.TR_NOTIFY_HOME || path.join(process.env.HOME || '', '.total-recall', 'notifications');
+    const file = path.join(home, 'sent.jsonl');
+    const lines = fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n').filter(Boolean) : [];
+    console.log(lines.slice(-Number(a.limit || 20)).join('\n'));
+    return;
+  }
+  if (sub === 'send' || sub === 'test') {
+    const test = sub === 'test';
+    if (!test && (!a.title || !a.message)) { console.error(USAGE); process.exitCode = 2; return; }
+    const channels = (a.channels || (test ? Object.keys(config).join(',') : 'os')).split(',').filter(Boolean);
+    const results = await sendNotification({
+      title: a.title || 'Notification test', message: a.message || 'Dry run of every configured channel.',
+      channels, eventId: a['event-id'], severity: a.severity, source: a.source,
+      dry: test || a.dry, quietHours: a['quiet-hours'], config,
+    });
+    console.log(JSON.stringify(results, null, 2));
+    if (results.some((r) => r.status === 'failed')) process.exitCode = 1;
+    return;
+  }
+  console.log(USAGE);
+  if (sub !== 'help') process.exitCode = 2;
+}
+
+export default run;

package/plugins/operator-alerts/notify-core.mjs

@@ -0,0 +1,193 @@
+/**
+ * notify-core: send an alert to the operator over one or more channels.
+ *
+ * Generic: no recipients, senders or key names are hardcoded. Everything comes
+ * from flags, a notify.json config, or the Total Recall secret store.
+ * See README.md.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const run = promisify(execFile);
+const HOME_DIR = process.env.TR_NOTIFY_HOME || path.join(os.homedir(), '.total-recall', 'notifications');
+const LEDGER = path.join(HOME_DIR, 'sent.jsonl');
+const LOG = path.join(HOME_DIR, 'notification-log.md');
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return {}; }
+}
+
+export function loadConfig(cwd = process.cwd(), explicit = null) {
+  const layers = [
+    readJson(path.join(HOME_DIR, 'config.json')),
+    readJson(path.join(cwd, '.agent', 'notify.json')),
+    explicit ? readJson(explicit) : {},
+  ];
+  const out = {};
+  for (const layer of layers) {
+    for (const [k, v] of Object.entries(layer)) out[k] = { ...(out[k] || {}), ...v };
+  }
+  return out;
+}
+
+async function secret(name, cwd) {
+  if (!name) return null;
+  if (process.env[name]) return process.env[name];
+  try {
+    const { stdout } = await run('total-recall', ['secret', 'get', name], { cwd, maxBuffer: 1 << 20 });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** A recipient is a literal (contains @ or starts with +) or `secret:NAME`. */
+async function recipient(spec, cwd) {
+  if (!spec) return null;
+  if (spec.startsWith('secret:')) return secret(spec.slice(7), cwd);
+  return spec;
+}
+
+async function need(cfg, field, cwd, channel) {
+  const v = field.endsWith('_secret') ? await secret(cfg[field], cwd) : await recipient(cfg[field], cwd);
+  if (!v) throw new Error(`${channel}: missing ${field} (set it in notify.json or via flags)`);
+  return v;
+}
+
+async function post(url, body, headers = {}) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json', ...headers },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${res.status} ${text.slice(0, 200)}`);
+  try { return JSON.parse(text); } catch { return { raw: text }; }
+}
+
+const ADAPTERS = {
+  async os({ title, message }, cfg, ctx) {
+    if (ctx.dry) return { dry: true };
+    try {
+      await run('terminal-notifier', ['-title', title, '-message', message, '-open', `file://${LOG}`, '-group', `notify-${ctx.source || 'alert'}`]);
+    } catch {
+      if (process.platform === 'darwin') {
+        const q = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        await run('osascript', ['-e', `display notification "${q(message)}" with title "${q(title)}"`]);
+      } else {
+        await run('notify-send', [title, message]);
+      }
+    }
+    return { accepted: true };
+  },
+
+  // SMTP2GO
+  async email({ title, message }, cfg, ctx) {
+    const to = await need(cfg, 'to', ctx.cwd, 'email');
+    const sender = cfg.from;
+    if (!sender) throw new Error('email: missing from (a verified SMTP2GO sender)');
+    if (ctx.dry) return { dry: true, to, sender };
+    const key = await need(cfg, 'key_secret', ctx.cwd, 'email');
+    const r = await post('https://api.smtp2go.com/v3/email/send', {
+      to: [to], sender, subject: title, text_body: message,
+    }, { 'X-Smtp2go-Api-Key': key });
+    if (r?.data?.succeeded < 1) throw new Error(`email: not accepted ${JSON.stringify(r.data)}`);
+    return { accepted: true, provider_id: r?.data?.email_id };
+  },
+
+  // Telnyx Messaging
+  async sms({ title, message }, cfg, ctx) {
+    const to = await need(cfg, 'to', ctx.cwd, 'sms');
+    const from = cfg.from;
+    if (!from) throw new Error('sms: missing from (a Telnyx number or messaging profile sender)');
+    if (ctx.dry) return { dry: true, to, from };
+    const key = await need(cfg, 'key_secret', ctx.cwd, 'sms');
+    const r = await post('https://api.telnyx.com/v2/messages', { from, to, text: `${title}\n${message}` }, { Authorization: `Bearer ${key}` });
+    return { accepted: true, provider_id: r?.data?.id };
+  },
+
+  // Stubs: not wired yet. They report `stub` instead of pretending to send.
+  async slack() { return { stub: true, note: 'slack adapter not implemented' }; },
+  async discord() { return { stub: true, note: 'discord adapter not implemented' }; },
+  async telegram() { return { stub: true, note: 'telegram adapter not implemented' }; },
+  async expo() { return { stub: true, note: 'expo adapter not implemented' }; },
+
+  async webhook({ title, message, eventId, severity, source }, cfg, ctx) {
+    if (ctx.dry) return { dry: true };
+    const url = await need(cfg, 'url_secret', ctx.cwd, 'webhook');
+    await post(url, { title, message, event_id: eventId, severity, source });
+    return { accepted: true };
+  },
+
+  async github({ title, message }, cfg, ctx) {
+    const repo = cfg.repo;
+    if (!repo) throw new Error('github: missing repo (owner/name)');
+    if (ctx.dry) return { dry: true, repo };
+    const token = await need(cfg, 'key_secret', ctx.cwd, 'github');
+    const r = await post(`https://api.github.com/repos/${repo}/issues`, { title, body: message, labels: cfg.labels || [] }, {
+      Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json',
+    });
+    return { accepted: true, provider_id: r?.number };
+  },
+};
+
+function inQuietHours(spec, now = new Date()) {
+  const m = /^(\d{1,2})-(\d{1,2})$/.exec(spec || '');
+  if (!m) return false;
+  const [s, e, h] = [Number(m[1]), Number(m[2]), now.getHours()];
+  return s <= e ? h >= s && h < e : h >= s || h < e;
+}
+
+function sentBefore(eventId, channel) {
+  if (!eventId || !fs.existsSync(LEDGER)) return false;
+  return fs.readFileSync(LEDGER, 'utf8').split('\n').some((l) => {
+    try { const r = JSON.parse(l); return r.event_id === eventId && r.channel === channel && r.status === 'accepted'; } catch { return false; }
+  });
+}
+
+function record(entry) {
+  fs.mkdirSync(HOME_DIR, { recursive: true });
+  fs.appendFileSync(LEDGER, JSON.stringify(entry) + '\n');
+}
+
+function logMarkdown(title, message, results, severity, source) {
+  try {
+    fs.mkdirSync(HOME_DIR, { recursive: true });
+    const summary = results.map((r) => `${r.channel}:${r.status}`).join(', ');
+    const entry = `### [${new Date().toISOString()}] ${title}\n> ${message}\n\n*${[severity, source].filter(Boolean).join(' · ')} | ${summary}*\n\n---\n\n`;
+    const old = fs.existsSync(LOG) ? fs.readFileSync(LOG, 'utf8') : '';
+    fs.writeFileSync(LOG, entry + old);
+  } catch { /* the log never blocks an alert */ }
+}
+
+export async function sendNotification(opts) {
+  const {
+    title, message, channels = ['os'], eventId = null, severity = 'info', source = '',
+    dry = false, quietHours = null, cwd = process.cwd(), config = null,
+  } = opts;
+  const cfg = config || loadConfig(cwd);
+  const critical = severity === 'critical' || severity === 'high';
+  const quiet = !critical && inQuietHours(quietHours);
+  const results = [];
+  for (const channel of channels) {
+    const base = { channel, event_id: eventId, at: new Date().toISOString() };
+    if (!ADAPTERS[channel]) { results.push({ ...base, status: 'failed', error: 'unknown channel' }); continue; }
+    if (quiet && channel !== 'os') { results.push({ ...base, status: 'suppressed', reason: 'quiet-hours' }); continue; }
+    if (!dry && sentBefore(eventId, channel)) { results.push({ ...base, status: 'duplicate' }); continue; }
+    try {
+      const r = await ADAPTERS[channel]({ title, message, eventId, severity, source }, cfg[channel] || {}, { dry, cwd, source });
+      const row = { ...base, status: r.stub ? 'stub' : dry ? 'dry-run' : 'accepted', ...r };
+      results.push(row);
+      if (!dry && !r.stub) record({ ...row, channel, event_id: eventId });
+    } catch (e) {
+      const row = { ...base, status: 'failed', error: String(e.message || e) };
+      results.push(row);
+      if (!dry) record(row);
+    }
+  }
+  if (!dry) logMarkdown(title, message, results, severity, source);
+  return results;
+}

package/plugins/operator-alerts/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "operator-alerts",
+  "name": "Operator Alerts",
+  "version": "1.0.0",
+  "description": "Send operator alerts over desktop, email (SMTP2GO), SMS (Telnyx), webhook and issue-tracker alerts with dedupe, quiet hours and delivery evidence. Keys come from the secret store; recipients from config.",
+  "author": "Total Recall",
+  "license": "MIT",
+  "use_cases": ["alerting"],
+  "cli": {
+    "command": "alerts",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      { "name": "send", "description": "Send an alert (--dry-run to resolve config without sending)" },
+      { "name": "test", "description": "Dry-run every configured channel" },
+      { "name": "config", "description": "Show the merged notify config" },
+      { "name": "log", "description": "Recent sends from the ledger" }
+    ]
+  }
+}

package/src/cli/command.mjs

@@ -170,7 +170,7 @@ function printHelp() {
 `);
 }
 
-function resolveTargetDir(isGlobal) {
+export function resolveTargetDir(isGlobal) {
   if (isGlobal) {
     try {
       const gBrain = resolveBrainLayer('global');
@@ -235,7 +235,7 @@ function existingTag(file, key) {
  * Composable instructions: the surfaces list every command, so any change to
  * the command set recompiles them (project layer, or every project for global).
  */
-function recompileSurfaces(isGlobal) {
+export function recompileSurfaces(isGlobal) {
   if (process.env.TR_COMMAND_NO_COMPILE === '1' || !process.argv[1]) return;
   try {
     const child = spawn(process.execPath, [process.argv[1], 'compile', isGlobal ? '--global' : '--project'], { detached: true, stdio: 'ignore' });
@@ -246,6 +246,48 @@ function recompileSurfaces(isGlobal) {
   }
 }
 
+/**
+ * Register every `commands` entry of an installed plugin as a composable command.
+ * A command that already exists and was generated from this plugin is refreshed;
+ * one that exists from anywhere else is left alone and reported.
+ */
+export function syncPluginCommands(pluginDir, { global: isGlobal = false } = {}) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(fs.realpathSync(pluginDir), 'plugin.json'), 'utf8'));
+  const commandsDir = resolveTargetDir(isGlobal);
+  const result = { created: [], skipped: [] };
+  for (const entry of manifest.commands || []) {
+    const file = path.join(commandsDir, `${entry.name}.mjs`);
+    if (fs.existsSync(file)) {
+      if (!fs.readFileSync(file, 'utf8').startsWith(`// Generated from plugin ${manifest.id};`)) {
+        result.skipped.push({ name: entry.name, reason: 'a different command with this name exists' });
+        continue;
+      }
+      fs.rmSync(file);
+    }
+    generatePluginCommand(pluginDir, entry.name, commandsDir);
+    result.created.push(entry.name);
+  }
+  if (result.created.length) recompileSurfaces(isGlobal);
+  return result;
+}
+
+/** Remove the commands a plugin generated (only files carrying its generated header). */
+export function removePluginCommands(pluginId, { global: isGlobal = false } = {}) {
+  const commandsDir = resolveTargetDir(isGlobal);
+  const removed = [];
+  if (!fs.existsSync(commandsDir)) return removed;
+  for (const name of fs.readdirSync(commandsDir)) {
+    if (!name.endsWith('.mjs')) continue;
+    const file = path.join(commandsDir, name);
+    if (fs.readFileSync(file, 'utf8').startsWith(`// Generated from plugin ${pluginId};`)) {
+      fs.rmSync(file);
+      removed.push(name.replace(/\.mjs$/, ''));
+    }
+  }
+  if (removed.length) recompileSurfaces(isGlobal);
+  return removed;
+}
+
 export default async function commandCmd(rawArgs = []) {
   const isGlobal = rawArgs.includes('--global') || rawArgs.includes('-g');
   const asJson = rawArgs.includes('--json');

package/src/cli/plugin/install.mjs

@@ -1,4 +1,5 @@
 import { installPlugin as install } from '../../core/plugin-store.mjs';
+import { syncPluginCommands } from '../command.mjs';
 
 export async function installPlugin(args = []) {
   const isGlobal = args.includes('--global') || args.includes('-g');
@@ -16,7 +17,11 @@ export async function installPlugin(args = []) {
     const from = result.source.kind === 'peer' ? `peer ${result.source.peer_hostname}` : result.source.kind;
     console.log(`\n✅ Installed '${result.plugin.name}' (id: ${result.plugin.id}, v${result.plugin.version}) from ${from}`);
     console.log(`   Location: ${result.plugin.dir}`);
-    console.log(`   sha256:   ${result.sha256}\n`);
+    console.log(`   sha256:   ${result.sha256}`);
+    const cmds = syncPluginCommands(result.plugin.dir, { global: isGlobal });
+    if (cmds.created.length) console.log(`   Commands: ${cmds.created.map((c) => `total-recall ${c}`).join(', ')}`);
+    for (const c of cmds.skipped) console.log(`   Skipped command '${c.name}': ${c.reason}`);
+    console.log('');
   } catch (err) {
     console.error(`❌ ${err.message}`);
     process.exit(1);

package/src/cli/plugin/remove.mjs

@@ -1,4 +1,5 @@
 import { uninstallPlugin, setPluginShared } from '../../core/plugin-store.mjs';
+import { removePluginCommands } from '../command.mjs';
 import { publicPluginShareUrl } from '../../core/plugin-public.mjs';
 
 export async function removePlugin(args = []) {
@@ -13,7 +14,10 @@ export async function removePlugin(args = []) {
 
   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`);
+    const removed = removePluginCommands(id, { global: result.scope === 'global' });
+    console.log(`\n✅ Removed plugin '${id}' (${result.scope}) from ${result.dir}`);
+    if (removed.length) console.log(`   Removed commands: ${removed.join(', ')}`);
+    console.log('');
   } catch (err) {
     console.error(`❌ ${err.message}`);
     process.exit(1);

package/src/core/env-import.mjs

@@ -10,6 +10,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { setSecret, listSecretsMeta, updateSecretMeta } from './secrets-store.mjs';
+import { providerForKeyName } from './provider-catalog.mjs';
 
 /**
  * @deprecated Kept as empty/export for older callers. Import does NOT use this
@@ -108,13 +109,9 @@ export function inferProvider(key) {
   if (!key) return null;
   const k = String(key);
 
-  // Lazy catalog match (optional enrichment only)
-  try {
-    // Dynamic import avoided in sync path — inline thin match from catalog module if already loadable
-    // Use sync require-free approach: duplicate-free segment heuristic only here for speed.
-  } catch {
-    /* ignore */
-  }
+  // A known provider anywhere in the key name wins (JSN_SMTP2GO_API_KEY -> smtp2go).
+  const known = providerForKeyName(k);
+  if (known) return known.id;
 
   // Strip common prefixes that are not the vendor
   let base = k