@digitalforgestudios/openclaw-sulcus 3.2.2 → 3.4.0

package/bin/configure.mjs

@@ -0,0 +1,626 @@
+#!/usr/bin/env node
+/**
+ * Sulcus Configuration Wizard
+ * Interactive CLI to configure the openclaw-sulcus plugin in openclaw.json
+ *
+ * Usage:
+ *   npx @digitalforgestudios/openclaw-sulcus configure
+ *   node bin/configure.mjs [--no-color] [--help]
+ */
+
+import readline from 'readline';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import https from 'https';
+import { execSync } from 'child_process';
+
+// ─── Colour support ───────────────────────────────────────────────────────────
+
+const noColor =
+  process.argv.includes('--no-color') ||
+  process.env.NO_COLOR !== undefined ||
+  !process.stdout.isTTY;
+
+const c = {
+  reset:   noColor ? '' : '\x1b[0m',
+  bold:    noColor ? '' : '\x1b[1m',
+  dim:     noColor ? '' : '\x1b[2m',
+  red:     noColor ? '' : '\x1b[31m',
+  green:   noColor ? '' : '\x1b[32m',
+  yellow:  noColor ? '' : '\x1b[33m',
+  blue:    noColor ? '' : '\x1b[34m',
+  magenta: noColor ? '' : '\x1b[35m',
+  cyan:    noColor ? '' : '\x1b[36m',
+  white:   noColor ? '' : '\x1b[37m',
+};
+
+const bold    = (s) => `${c.bold}${s}${c.reset}`;
+const dim     = (s) => `${c.dim}${s}${c.reset}`;
+const green   = (s) => `${c.green}${s}${c.reset}`;
+const yellow  = (s) => `${c.yellow}${s}${c.reset}`;
+const red     = (s) => `${c.red}${s}${c.reset}`;
+const cyan    = (s) => `${c.cyan}${s}${c.reset}`;
+const magenta = (s) => `${c.magenta}${s}${c.reset}`;
+
+// ─── Help ─────────────────────────────────────────────────────────────────────
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+${bold('Sulcus Configuration Wizard')}
+
+Interactively configure the openclaw-sulcus plugin inside your openclaw.json.
+
+${bold('Usage:')}
+  npx @digitalforgestudios/openclaw-sulcus configure [options]
+  node bin/configure.mjs [options]
+
+${bold('Options:')}
+  --help, -h      Show this help message
+  --no-color      Disable coloured output
+
+${bold('What it does:')}
+  1. Locates your openclaw.json (checks \$OPENCLAW_CONFIG_PATH, ~/.openclaw/, ./)
+  2. Walks you through backend mode, dylib path, namespace, hooks, and tools
+  3. Deep-merges settings under plugins.entries.openclaw-sulcus.config
+  4. Validates that your native dylibs exist and warns if they are missing
+  5. Reminds you to restart the OpenClaw gateway
+
+${bold('Example:')}
+  npx @digitalforgestudios/openclaw-sulcus configure
+`);
+  process.exit(0);
+}
+
+// ─── Readline helpers ─────────────────────────────────────────────────────────
+
+const rl = readline.createInterface({
+  input:  process.stdin,
+  output: process.stdout,
+});
+
+// Graceful Ctrl+C
+rl.on('SIGINT', () => {
+  console.log(`\n\n${yellow('⚡ Wizard cancelled — no changes were written.')}\n`);
+  process.exit(0);
+});
+
+/**
+ * Prompt the user with an optional default value.
+ * Returns the trimmed answer, or the default if empty.
+ */
+function ask(question, defaultValue = '') {
+  return new Promise((resolve) => {
+    const hint = defaultValue !== '' ? dim(` [${defaultValue}]`) : '';
+    rl.question(`${question}${hint} `, (answer) => {
+      const trimmed = answer.trim();
+      resolve(trimmed === '' ? defaultValue : trimmed);
+    });
+  });
+}
+
+/**
+ * Ask a yes/no question. Returns boolean.
+ * @param {string} question
+ * @param {boolean} defaultVal
+ */
+function askYN(question, defaultVal = false) {
+  return new Promise((resolve) => {
+    const hint = dim(` [${defaultVal ? 'Y/n' : 'y/N'}]`);
+    rl.question(`  ${question}${hint} `, (answer) => {
+      const a = answer.trim().toLowerCase();
+      if (a === '') resolve(defaultVal);
+      else resolve(a === 'y' || a === 'yes');
+    });
+  });
+}
+
+// ─── openclaw.json discovery ──────────────────────────────────────────────────
+
+function expandHome(p) {
+  if (p.startsWith('~')) return path.join(os.homedir(), p.slice(1));
+  return p;
+}
+
+function findOpenclawJson() {
+  const candidates = [
+    process.env.OPENCLAW_CONFIG_PATH,
+    path.join(os.homedir(), '.openclaw', 'openclaw.json'),
+    path.join(process.cwd(), 'openclaw.json'),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    const resolved = expandHome(candidate);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+  return null;
+}
+
+// Deep-merge two plain objects (target mutated).
+function deepMerge(target, source) {
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] !== null &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      typeof target[key] === 'object' &&
+      target[key] !== null &&
+      !Array.isArray(target[key])
+    ) {
+      deepMerge(target[key], source[key]);
+    } else {
+      target[key] = source[key];
+    }
+  }
+  return target;
+}
+
+// ─── Prebuilt binary download ─────────────────────────────────────────────────
+
+/**
+ * Detect the current platform slug used in GitHub release asset names.
+ * Returns { platform, ext } or throws if unsupported.
+ */
+function detectPlatform() {
+  const plat = process.platform;
+  const arch = process.arch;
+
+  const ext = plat === 'darwin' ? '.dylib' : '.so';
+
+  if (plat === 'darwin' && arch === 'arm64') return { platform: 'macos-arm64', ext };
+  if (plat === 'darwin' && arch === 'x64')   return { platform: 'macos-x64',   ext };
+  if (plat === 'linux'  && arch === 'x64')   return { platform: 'linux-x64',   ext };
+  if (plat === 'linux'  && arch === 'arm64') return { platform: 'linux-arm64', ext };
+
+  throw new Error(
+    `Prebuilt binaries are not available for your platform (${plat}/${arch}).\n` +
+    `  Supported: darwin/arm64, darwin/x64, linux/x64, linux/arm64`,
+  );
+}
+
+/**
+ * Follow redirects and download `url` into `destFile`.
+ * Shows a simple percentage progress bar (or dots when content-length is unknown).
+ * Follows up to maxRedirects hops.
+ */
+function downloadFile(url, destFile, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    let hops = 0;
+
+    function attempt(currentUrl) {
+      if (hops > maxRedirects) {
+        return reject(new Error('Too many redirects while downloading'));
+      }
+      hops++;
+
+      const parsed = new URL(currentUrl);
+      const opts = {
+        hostname: parsed.hostname,
+        path:     parsed.pathname + parsed.search,
+        method:   'GET',
+        headers:  { 'User-Agent': 'sulcus-configure/1.0' },
+      };
+
+      const req = https.request(opts, (res) => {
+        const { statusCode, headers: resHeaders } = res;
+
+        // Follow 301/302/307/308 redirects
+        if (
+          (statusCode === 301 || statusCode === 302 ||
+           statusCode === 307 || statusCode === 308) &&
+          resHeaders.location
+        ) {
+          res.resume(); // drain
+          return attempt(resHeaders.location);
+        }
+
+        if (statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`HTTP ${statusCode} for ${currentUrl}`));
+        }
+
+        const total   = parseInt(resHeaders['content-length'] || '0', 10);
+        let received  = 0;
+        let lastPct   = -1;
+
+        const out = fs.createWriteStream(destFile);
+
+        res.on('data', (chunk) => {
+          received += chunk.length;
+          out.write(chunk);
+
+          if (total > 0) {
+            const pct = Math.floor((received / total) * 100);
+            if (pct !== lastPct && pct % 5 === 0) {
+              lastPct = pct;
+              process.stdout.write(`\r    Downloading... ${pct}%   `);
+            }
+          } else {
+            // No content-length — show dots
+            if (received % (64 * 1024) === 0) process.stdout.write('.');
+          }
+        });
+
+        res.on('end', () => {
+          out.end(() => {
+            process.stdout.write(`\r    Downloaded ${(received / 1024 / 1024).toFixed(1)} MB    \n`);
+            resolve();
+          });
+        });
+
+        res.on('error', (err) => {
+          out.destroy();
+          reject(err);
+        });
+      });
+
+      req.on('error', reject);
+      req.end();
+    }
+
+    attempt(url);
+  });
+}
+
+/**
+ * Download and install prebuilt dylibs for the current platform.
+ * Returns true on success, false if the user skips or something goes wrong.
+ *
+ * @param {string} resolvedLibDir  Absolute path where dylibs should be placed
+ * @param {string[]} dylibNames    Base names without extension, e.g. ['libsulcus_store', ...]
+ */
+async function downloadAndInstallBinaries(resolvedLibDir, dylibNames) {
+  let platformInfo;
+  try {
+    platformInfo = detectPlatform();
+  } catch (err) {
+    console.log(`  ${yellow('⚠')}  ${err.message}`);
+    return false;
+  }
+
+  const { platform, ext } = platformInfo;
+  const displayDir = resolvedLibDir.replace(os.homedir(), '~');
+  const tarUrl = `https://github.com/digitalforgeca/sulcus/releases/latest/download/sulcus-${platform}.tar.gz`;
+
+  console.log();
+  console.log(`  ${yellow('⚠')}  Native libraries not found at ${cyan(displayDir)}`);
+  console.log(`  ${dim(`Download prebuilt binaries for ${bold(platform)}?`)}`);
+
+  const doDownload = await askYN(`Download prebuilt binaries for ${platform}?`, true);
+  if (!doDownload) {
+    console.log(`  ${dim('Skipped. Install dylibs manually to use Sulcus.')}`);
+    return false;
+  }
+
+  // Create libDir if needed
+  try {
+    fs.mkdirSync(resolvedLibDir, { recursive: true });
+  } catch (err) {
+    console.log(`  ${red('✗')} Cannot create ${cyan(resolvedLibDir)}: ${err.message}`);
+    console.log(`  ${dim('Try running with appropriate permissions.')}`);
+    return false;
+  }
+
+  const tmpDir  = fs.mkdtempSync(path.join(os.tmpdir(), 'sulcus-'));
+  const tarPath = path.join(tmpDir, `sulcus-${platform}.tar.gz`);
+
+  console.log(`  ${dim(`→ ${tarUrl}`)}`);
+  process.stdout.write(`    Downloading...`);
+
+  try {
+    await downloadFile(tarUrl, tarPath);
+  } catch (err) {
+    console.log(`  ${red('✗')} Download failed: ${err.message}`);
+    console.log(`  ${dim('Check your internet connection or download manually:')}`);
+    console.log(`    ${cyan(tarUrl)}`);
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+    return false;
+  }
+
+  // Extract
+  console.log(`    Extracting...`);
+  try {
+    execSync(`tar xzf ${JSON.stringify(tarPath)} -C ${JSON.stringify(tmpDir)}`, { stdio: 'pipe' });
+  } catch (err) {
+    console.log(`  ${red('✗')} Extraction failed: ${err.message}`);
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+    return false;
+  }
+
+  // Move each dylib into libDir
+  let allInstalled = true;
+  for (const lib of dylibNames) {
+    const srcFile  = path.join(tmpDir, lib + ext);
+    const destFile = path.join(resolvedLibDir, lib + ext);
+
+    if (!fs.existsSync(srcFile)) {
+      console.log(`  ${yellow('⚠')}  ${lib + ext} not found in tarball`);
+      allInstalled = false;
+      continue;
+    }
+
+    try {
+      fs.copyFileSync(srcFile, destFile);
+      console.log(`  ${green('✓')} Installed: ${dim(destFile)}`);
+    } catch (err) {
+      console.log(`  ${red('✗')} Failed to install ${lib + ext}: ${err.message}`);
+      if (err.code === 'EACCES') {
+        console.log(`  ${dim('Try running with appropriate permissions (e.g. sudo).')}`);
+      }
+      allInstalled = false;
+    }
+  }
+
+  // Cleanup temp dir
+  try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+
+  return allInstalled;
+}
+
+// ─── Main wizard ──────────────────────────────────────────────────────────────
+
+async function run() {
+  console.log(`
+${bold(magenta('🧠  Sulcus Configuration Wizard'))}
+${dim('────────────────────────────────────────────')}
+Configures the ${cyan('openclaw-sulcus')} plugin inside your ${cyan('openclaw.json')}.
+Press ${bold('Enter')} to accept defaults. ${bold('Ctrl+C')} to cancel at any time.
+`);
+
+  // ── Step 1: Locate openclaw.json ──────────────────────────────────────────
+
+  console.log(`${bold('Step 1 · Locate openclaw.json')}`);
+
+  let configPath = findOpenclawJson();
+
+  if (configPath) {
+    console.log(`  ${green('✓')} Found: ${cyan(configPath)}\n`);
+  } else {
+    console.log(`  ${yellow('⚠')}  Could not find openclaw.json in the usual locations.`);
+    console.log(`     Checked:`);
+    if (process.env.OPENCLAW_CONFIG_PATH)
+      console.log(`       • \$OPENCLAW_CONFIG_PATH → ${process.env.OPENCLAW_CONFIG_PATH}`);
+    console.log(`       • ~/.openclaw/openclaw.json`);
+    console.log(`       • ./openclaw.json\n`);
+
+    const choice = await ask(
+      `  Enter full path to openclaw.json, or press Enter to create ~/.openclaw/openclaw.json:`,
+      path.join(os.homedir(), '.openclaw', 'openclaw.json'),
+    );
+    configPath = expandHome(choice);
+
+    if (!fs.existsSync(configPath)) {
+      const dir = path.dirname(configPath);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(configPath, JSON.stringify({}, null, 2), 'utf8');
+      console.log(`  ${green('✓')} Created: ${cyan(configPath)}\n`);
+    } else {
+      console.log(`  ${green('✓')} Using: ${cyan(configPath)}\n`);
+    }
+  }
+
+  // Read existing config
+  let existingConfig = {};
+  try {
+    existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    console.log(`  ${red('✗')} Failed to parse openclaw.json: ${err.message}`);
+    console.log(`  Fix the JSON syntax and re-run the wizard.\n`);
+    rl.close();
+    process.exit(1);
+  }
+
+  // ── Step 2: Wizard questions ──────────────────────────────────────────────
+
+  console.log(`${bold('Step 2 · Configure Sulcus')}`);
+  console.log();
+
+  // Backend mode
+  console.log(`  ${bold('Backend mode:')}`);
+  console.log(`    ${cyan('[1]')} Local only ${dim('(WASM + native dylibs, no network)')}`);
+  console.log(`    ${cyan('[2]')} Cloud sync  ${dim('(local + server replication)')}`);
+  const modeRaw = await ask(`  >`, '1');
+  const cloudSync = modeRaw === '2';
+  console.log();
+
+  // Native dylib path
+  const libDirDefault = '~/.sulcus/lib';
+  const libDirRaw = await ask(
+    `  ${bold('Where are your native dylibs?')}`,
+    libDirDefault,
+  );
+  const libDir = libDirRaw;
+  console.log();
+
+  // Agent namespace
+  const namespace = await ask(`  ${bold('Agent namespace:')}`, 'default');
+  console.log();
+
+  // Hooks
+  console.log(`  ${bold('Enable hooks:')}`);
+  const injectAwareness = await askYN(
+    'Inject memory awareness into prompts? (before_prompt_build)',
+    false,
+  );
+  const autoRecall = await askYN(
+    'Auto-recall memories on each turn? (before_agent_start)',
+    false,
+  );
+  console.log();
+
+  // Tools
+  console.log(`  ${bold('Enable tools:')}`);
+  const toolMemoryRecall    = await askYN('memory_recall    — search memories',               true);
+  const toolMemoryStore     = await askYN('memory_store     — save memories',                 true);
+  const toolMemoryStatus    = await askYN('memory_status    — check memory stats',            true);
+  const toolConsolidate     = await askYN('consolidate      — cluster similar memories',      false);
+  const toolExportMarkdown  = await askYN('export_markdown  — export memories as markdown',   false);
+  const toolImportMarkdown  = await askYN('import_markdown  — import from markdown',          false);
+  const toolEvalTriggers    = await askYN('evaluate_triggers — reactive trigger engine',      false);
+  console.log();
+
+  // Cloud sync extras
+  let serverUrl = '';
+  let apiKey    = '';
+  if (cloudSync) {
+    console.log(`  ${bold('Cloud sync settings:')}`);
+    serverUrl = await ask(`  Server URL:`, 'https://api.sulcus.ca');
+    apiKey    = await ask(`  API Key:`,    '');
+    console.log();
+  }
+
+  // ── Step 3: Build and write config ───────────────────────────────────────
+
+  console.log(`${bold('Step 3 · Write openclaw.json')}`);
+
+  const sulcusConfig = {
+    libDir,
+    namespace: namespace === 'default' ? undefined : namespace,
+    ...(cloudSync && serverUrl ? { serverUrl } : {}),
+    ...(cloudSync && apiKey    ? { apiKey }    : {}),
+    hooks: {
+      before_prompt_build: { action: 'inject_awareness', enabled: injectAwareness },
+      before_agent_start:  { action: 'auto_recall',      enabled: autoRecall, limit: 5, minScore: 0.3 },
+    },
+    tools: {
+      memory_recall:     { enabled: toolMemoryRecall },
+      memory_store:      { enabled: toolMemoryStore },
+      memory_status:     { enabled: toolMemoryStatus },
+      consolidate:       { enabled: toolConsolidate },
+      export_markdown:   { enabled: toolExportMarkdown },
+      import_markdown:   { enabled: toolImportMarkdown },
+      evaluate_triggers: { enabled: toolEvalTriggers },
+    },
+  };
+
+  // Remove undefined keys
+  Object.keys(sulcusConfig).forEach(
+    (k) => sulcusConfig[k] === undefined && delete sulcusConfig[k],
+  );
+
+  // Deep-merge into existing config
+  const merged = deepMerge(existingConfig, {
+    plugins: {
+      entries: {
+        'openclaw-sulcus': {
+          enabled: true,
+          config: sulcusConfig,
+        },
+      },
+    },
+  });
+
+  let written = false;
+  try {
+    fs.writeFileSync(configPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+    written = true;
+  } catch (err) {
+    console.log(`  ${red('✗')} Failed to write ${configPath}: ${err.message}\n`);
+    rl.close();
+    process.exit(1);
+  }
+
+  if (written) {
+    console.log(`  ${green('✓')} Written to ${cyan(configPath)}`);
+    console.log();
+
+    // Summary
+    console.log(`  ${dim('──── Summary ────────────────────────────────────')}`);
+    console.log(`  Plugin:    ${cyan('openclaw-sulcus')}  ${green('enabled')}`);
+    console.log(`  Backend:   ${cyan(cloudSync ? 'cloud sync' : 'local only')}`);
+    console.log(`  Dylib dir: ${cyan(libDir)}`);
+    console.log(`  Namespace: ${cyan(namespace)}`);
+    if (cloudSync && serverUrl) console.log(`  Server:    ${cyan(serverUrl)}`);
+
+    const enabledHooks = [];
+    if (injectAwareness) enabledHooks.push('before_prompt_build');
+    if (autoRecall)      enabledHooks.push('before_agent_start');
+    console.log(`  Hooks:     ${enabledHooks.length ? cyan(enabledHooks.join(', ')) : dim('(none enabled)')}`);
+
+    const enabledTools = [
+      toolMemoryRecall    && 'memory_recall',
+      toolMemoryStore     && 'memory_store',
+      toolMemoryStatus    && 'memory_status',
+      toolConsolidate     && 'consolidate',
+      toolExportMarkdown  && 'export_markdown',
+      toolImportMarkdown  && 'import_markdown',
+      toolEvalTriggers    && 'evaluate_triggers',
+    ].filter(Boolean);
+    console.log(`  Tools:     ${enabledTools.length ? cyan(enabledTools.join(', ')) : dim('(none enabled)')}`);
+    console.log(`  ${dim('─────────────────────────────────────────────────')}`);
+    console.log();
+  }
+
+  // ── Step 4: Validate dylib path (+ auto-download if missing) ─────────────
+
+  console.log(`${bold('Step 4 · Validate')}`);
+
+  const resolvedLibDir = expandHome(libDir);
+  const dylibNames = ['libsulcus_store', 'libsulcus_vectors'];
+  const ext = process.platform === 'darwin' ? '.dylib'
+            : process.platform === 'win32'  ? '.dll'
+            :                                 '.so';
+
+  /**
+   * Check which dylibs are present. Returns true when all are found.
+   */
+  function checkDylibs() {
+    if (!fs.existsSync(resolvedLibDir)) return false;
+    return dylibNames.every((lib) => fs.existsSync(path.join(resolvedLibDir, lib + ext)));
+  }
+
+  let dylibsOk = checkDylibs();
+
+  if (dylibsOk) {
+    // All present — just print them
+    for (const lib of dylibNames) {
+      console.log(`  ${green('✓')} Found: ${dim(path.join(resolvedLibDir, lib + ext))}`);
+    }
+  } else {
+    // Some or all missing — try auto-download
+    const downloaded = await downloadAndInstallBinaries(resolvedLibDir, dylibNames);
+
+    if (downloaded) {
+      // Re-validate after successful download
+      dylibsOk = checkDylibs();
+      if (!dylibsOk) {
+        console.log(`  ${yellow('⚠')}  Some dylibs still missing after installation.`);
+      }
+    } else if (!downloaded) {
+      // Download skipped or failed — show manual instructions
+      if (fs.existsSync(resolvedLibDir)) {
+        // Directory exists but files missing — list what we found / didn't find
+        for (const lib of dylibNames) {
+          const full = path.join(resolvedLibDir, lib + ext);
+          if (fs.existsSync(full)) {
+            console.log(`  ${green('✓')} Found: ${dim(full)}`);
+          } else {
+            console.log(`  ${yellow('⚠')}  Missing: ${dim(full)}`);
+          }
+        }
+      }
+      console.log();
+      console.log(`  ${yellow(bold('Native dylibs missing — Sulcus will not load.'))}`);
+      console.log(`  Download manually from:`);
+      console.log(`    ${cyan('https://github.com/digitalforgeca/sulcus/releases/latest')}`);
+      console.log(`  Or visit: ${cyan('https://sulcus.ca/docs/install')}`);
+    }
+  }
+
+  if (dylibsOk) {
+    console.log(`  ${green('✓')} All dylibs present — Sulcus is ready to go.`);
+  }
+
+  console.log();
+  console.log(`  ${bold(green('✅  Configuration complete!'))} Restart the OpenClaw gateway to pick up changes:`);
+  console.log(`     ${cyan('openclaw gateway restart')}`);
+  console.log();
+
+  rl.close();
+}
+
+run().catch((err) => {
+  console.error(`\n${red('Fatal error:')} ${err.message}\n`);
+  rl.close();
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalforgestudios/openclaw-sulcus",
-  "version": "3.2.2",
+  "version": "3.4.0",
   "description": "Sulcus — reactive, thermodynamic memory plugin for OpenClaw. Opt-in persistent memory with heat-based decay, semantic search, and cross-agent sync. Auto-recall and auto-capture disabled by default.",
   "keywords": [
     "openclaw",
@@ -37,7 +37,11 @@
       "openclawVersion": "2026.3.28"
     }
   },
+  "bin": {
+    "openclaw-sulcus": "./bin/configure.mjs"
+  },
   "files": [
+    "bin/",
     "index.ts",
     "wasm/",
     "openclaw.plugin.json",