claude-memory-agent 2.0.1 → 2.2.0

package/bin/lib/steps/confirm.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const { confirm } = require('@inquirer/prompts');
+const chalk = require('chalk');
+const { stepHeader, printBox, TOTAL_STEPS } = require('../ui.js');
+
+/**
+ * Step 7: Review & Install
+ * Displays a summary of all collected configuration and asks for confirmation.
+ *
+ * @param {{ scope: string, projectPath: string|null, provider: string, model: string,
+ *           port: number, host: string, autoStart: boolean, logLevel?: string,
+ *           dbPath?: string, authEnabled?: boolean, hotTierDays?: number,
+ *           warmTierDays?: number, hooks?: string[] }} config
+ * @returns {boolean} true if user confirms, false to abort
+ */
+async function promptConfirm(config) {
+    stepHeader(7, TOTAL_STEPS, 'Review & Install');
+
+    // Format scope display
+    const scopeLabels = { global: 'Global', project: 'Project-specific', both: 'Both' };
+    const scopeDisplay = scopeLabels[config.scope] || config.scope;
+
+    // Format binding display
+    const bindingDisplay = config.host === '127.0.0.1'
+        ? 'localhost only'
+        : 'all interfaces (0.0.0.0)';
+
+    // Format auto-start display
+    const autoStartDisplay = config.autoStart ? 'Yes' : 'No';
+
+    // Format log level (use default if not customized)
+    const logLevel = config.logLevel || 'INFO';
+
+    // Format auth display
+    const authDisplay = config.authEnabled ? 'Enabled' : 'Disabled';
+
+    // Format hooks display
+    const defaultHooks = ['session_start', 'grounding', 'session_end'];
+    const hooks = config.hooks || defaultHooks;
+    const hooksDisplay = hooks.join(', ');
+
+    const label = (text) => chalk.dim(text);
+    const value = (text) => chalk.white.bold(text);
+
+    const lines = [
+        `${label('Scope:')}      ${value(scopeDisplay)}`,
+    ];
+
+    if (config.projectPath) {
+        lines.push(`${label('Project:')}    ${value(config.projectPath)}`);
+    }
+
+    lines.push(
+        `${label('Provider:')}   ${value(config.provider)}`,
+        `${label('Model:')}      ${value(config.model)}`,
+        `${label('Port:')}       ${value(String(config.port))}`,
+        `${label('Binding:')}    ${value(bindingDisplay)}`,
+        `${label('Auto-start:')} ${value(autoStartDisplay)}`,
+        `${label('Log Level:')}  ${value(logLevel)}`,
+        `${label('Auth:')}       ${value(authDisplay)}`,
+        `${label('Hooks:')}      ${value(hooksDisplay)}`,
+    );
+
+    if (config.dbPath) {
+        lines.push(`${label('DB Path:')}    ${value(config.dbPath)}`);
+    }
+
+    if (config.hotTierDays) {
+        lines.push(`${label('Hot Tier:')}   ${value(config.hotTierDays + ' days')}`);
+    }
+
+    if (config.warmTierDays) {
+        lines.push(`${label('Warm Tier:')}  ${value(config.warmTierDays + ' days')}`);
+    }
+
+    printBox('Installation Summary', lines);
+
+    const proceed = await confirm({
+        message: 'Proceed with installation?',
+        default: true,
+    });
+
+    return proceed;
+}
+
+module.exports = { promptConfirm };

package/bin/lib/steps/model.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { select, confirm } = require('@inquirer/prompts');
+const chalk = require('chalk');
+const { stepHeader, TOTAL_STEPS } = require('../ui.js');
+const { getModelsByProvider, formatModelChoice } = require('../models.js');
+
+/**
+ * Step 4: Embedding Model
+ * Prompts the user to choose an embedding model based on their selected provider.
+ *
+ * @param {'ollama'|'sentence-transformers'} provider
+ * @param {{ ollama: { running: boolean, models: string[] } }} env
+ * @returns {{ model: string, pullModel: boolean }}
+ */
+async function promptModel(provider, env) {
+    stepHeader(4, TOTAL_STEPS, 'Embedding Model');
+
+    console.log(chalk.dim('  Models are ordered from lightest to most powerful:\n'));
+
+    const installedModels = (env.ollama && env.ollama.models) || [];
+    const models = getModelsByProvider(provider);
+
+    const choices = models.map((model) => ({
+        name: formatModelChoice(model, installedModels),
+        value: model.name,
+    }));
+
+    // Find and mark the recommended model as default
+    const recommendedIndex = models.findIndex((m) => m.recommended);
+    if (recommendedIndex !== -1) {
+        choices[recommendedIndex].default = true;
+    }
+
+    const defaultModel = recommendedIndex !== -1 ? models[recommendedIndex].name : undefined;
+
+    const model = await select({
+        message: 'Select an embedding model:',
+        choices,
+        default: defaultModel,
+    });
+
+    let pullModel = false;
+
+    if (provider === 'ollama' && !installedModels.includes(model)) {
+        console.log(chalk.yellow('\n  This model is not installed in Ollama.'));
+
+        pullModel = await confirm({
+            message: `Download it now? (ollama pull ${model})`,
+            default: true,
+        });
+    }
+
+    return { model, pullModel };
+}
+
+module.exports = { promptModel };

package/bin/lib/steps/provider.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const { select, confirm } = require('@inquirer/prompts');
+const chalk = require('chalk');
+const { stepHeader, printBox, TOTAL_STEPS } = require('../ui.js');
+
+/**
+ * Step 3: Embedding Provider
+ * Prompts the user to choose between Ollama and sentence-transformers.
+ *
+ * @param {{ ollama: { running: boolean, models: string[] } }} env
+ * @returns {{ provider: 'ollama'|'sentence-transformers' }}
+ */
+async function promptProvider(env) {
+    stepHeader(3, TOTAL_STEPS, 'Embedding Provider');
+
+    const ollamaRunning = env.ollama && env.ollama.running;
+    const ollamaStatus = ollamaRunning
+        ? chalk.green(' (running)')
+        : chalk.yellow(' (not detected)');
+
+    let provider = null;
+
+    while (provider === null) {
+        const choice = await select({
+            message: 'Which embedding provider would you like to use?',
+            choices: [
+                {
+                    name: `Standalone (sentence-transformers) - runs locally, no external service needed`,
+                    value: 'sentence-transformers',
+                },
+                {
+                    name: `Ollama - uses Ollama for embeddings${ollamaStatus}`,
+                    value: 'ollama',
+                },
+            ],
+        });
+
+        if (choice === 'ollama' && !ollamaRunning) {
+            printBox('Warning', [
+                chalk.yellow('Ollama is not running. To install:'),
+                '',
+                '  1. Download from https://ollama.ai/download',
+                '  2. Run: ollama serve',
+                '  3. Then re-run this installer',
+            ]);
+
+            const continueAnyway = await confirm({
+                message: 'Continue with Ollama anyway?',
+                default: false,
+            });
+
+            if (!continueAnyway) {
+                // Re-prompt by continuing the loop
+                continue;
+            }
+        }
+
+        provider = choice;
+    }
+
+    return { provider };
+}
+
+module.exports = { promptProvider };

package/bin/lib/steps/scope.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { select, input } = require('@inquirer/prompts');
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { stepHeader, TOTAL_STEPS } = require('../ui.js');
+
+/**
+ * Step 2: Installation Scope
+ * Prompts the user to choose where the memory agent configuration is installed.
+ *
+ * @returns {{ scope: 'global'|'project'|'both', projectPath: string|null }}
+ */
+async function promptScope() {
+    stepHeader(2, TOTAL_STEPS, 'Installation Scope');
+
+    const scope = await select({
+        message: 'Where should the memory agent be configured?',
+        choices: [
+            {
+                name: 'Global (recommended)',
+                value: 'global',
+                description: 'Configures ~/.claude/settings.json',
+            },
+            {
+                name: 'Project-specific',
+                value: 'project',
+                description: 'Configures .claude/settings.local.json in your project',
+            },
+            {
+                name: 'Both',
+                value: 'both',
+                description: 'Global config + project-specific override',
+            },
+        ],
+    });
+
+    let projectPath = null;
+
+    if (scope === 'project' || scope === 'both') {
+        projectPath = await input({
+            message: 'Project directory path:',
+            default: process.cwd(),
+            validate: (value) => {
+                const resolved = path.resolve(value);
+                if (!fs.existsSync(resolved)) {
+                    return `Directory does not exist: ${resolved}`;
+                }
+                return true;
+            },
+        });
+        projectPath = path.resolve(projectPath);
+    }
+
+    return { scope, projectPath };
+}
+
+module.exports = { promptScope };

package/bin/lib/steps/server.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const { input, select, confirm } = require('@inquirer/prompts');
+const chalk = require('chalk');
+const net = require('net');
+const { stepHeader, TOTAL_STEPS } = require('../ui.js');
+
+/**
+ * Check if a port is available by attempting to listen on it briefly.
+ *
+ * @param {number} port
+ * @returns {Promise<boolean>} true if the port is available
+ */
+function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+
+/**
+ * Step 5: Server Settings
+ * Prompts the user for port, host binding, and auto-start preference.
+ *
+ * @returns {{ port: number, host: string, autoStart: boolean }}
+ */
+async function promptServer() {
+    stepHeader(5, TOTAL_STEPS, 'Server Settings');
+
+    const portStr = await input({
+        message: 'Server port:',
+        default: '8102',
+        validate: async (value) => {
+            const num = Number(value);
+            if (!Number.isInteger(num) || num < 1 || num > 65535) {
+                return 'Port must be a number between 1 and 65535';
+            }
+            const available = await isPortAvailable(num);
+            if (!available) {
+                return `Port ${num} is already in use`;
+            }
+            return true;
+        },
+    });
+
+    const port = Number(portStr);
+
+    const host = await select({
+        message: 'Dashboard binding:',
+        choices: [
+            {
+                name: 'Localhost only (127.0.0.1) - Secure, recommended',
+                value: '127.0.0.1',
+            },
+            {
+                name: 'All interfaces (0.0.0.0) - Access from other devices',
+                value: '0.0.0.0',
+            },
+        ],
+    });
+
+    const autoStart = await confirm({
+        message: 'Start the agent after installation?',
+        default: true,
+    });
+
+    return { port, host, autoStart };
+}
+
+module.exports = { promptServer };

package/bin/lib/ui.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const chalk = require('chalk');
+const boxen = require('boxen');
+
+/**
+ * Total number of steps in the onboarding wizard.
+ */
+const TOTAL_STEPS = 7;
+
+/**
+ * Print a step header for the wizard.
+ * Renders as:
+ *
+ *   Step 3/7 -- Embedding Model
+ *   ----------------------------------------
+ *
+ * @param {number} step - Current step number
+ * @param {number} total - Total number of steps
+ * @param {string} title - Step title
+ */
+function stepHeader(step, total, title) {
+    console.log('');
+    console.log('  ' + chalk.bold.cyan('Step ' + step + '/' + total) + chalk.bold(' \u2014 ' + title));
+    console.log('  ' + chalk.dim('\u2500'.repeat(40)));
+    console.log('');
+}
+
+/**
+ * Return a star rating string (filled + empty, out of 5), colored yellow.
+ * @param {number} count - Number of filled stars
+ * @returns {string}
+ */
+function stars(count) {
+    const filled = '\u2605'.repeat(Math.min(count, 5));
+    const empty = '\u2606'.repeat(Math.max(5 - count, 0));
+    return chalk.yellow(filled + empty);
+}
+
+/**
+ * Print a bordered box with a title and content lines.
+ * Uses the boxen package for drawing.
+ *
+ * @param {string} title - Box title
+ * @param {string[]} lines - Array of content lines to display inside the box
+ */
+function printBox(title, lines) {
+    const content = lines.join('\n');
+    const box = boxen(content, {
+        title: title,
+        titleAlignment: 'left',
+        padding: 1,
+        margin: { top: 0, bottom: 0, left: 2, right: 0 },
+        borderColor: 'cyan',
+        borderStyle: 'round',
+    });
+    console.log(box);
+}
+
+/**
+ * Print a thin horizontal divider across the terminal width.
+ * Falls back to 60 columns if terminal width is not available.
+ */
+function divider() {
+    const width = process.stdout.columns || 60;
+    console.log(chalk.dim('\u2500'.repeat(width)));
+}
+
+module.exports = {
+    TOTAL_STEPS,
+    stepHeader,
+    stars,
+    printBox,
+    divider,
+};

package/bin/onboarding.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { spawn } = require('child_process');
+
+const AGENT_DIR = path.resolve(path.dirname(__dirname));
+
+async function runWizard() {
+  // Import lib modules
+  const { printBanner } = require('./lib/banner');
+  const { detectEnvironment, printEnvironment } = require('./lib/environment');
+  const { stepHeader, TOTAL_STEPS } = require('./lib/ui');
+  const { promptScope } = require('./lib/steps/scope');
+  const { promptProvider } = require('./lib/steps/provider');
+  const { promptModel } = require('./lib/steps/model');
+  const { promptServer } = require('./lib/steps/server');
+  const { promptAdvanced } = require('./lib/steps/advanced');
+  const { promptConfirm } = require('./lib/steps/confirm');
+  const { runInstaller } = require('./lib/installer');
+
+  // Screen 1: Banner + Environment Detection
+  printBanner();
+  stepHeader(1, TOTAL_STEPS, 'Environment Detection');
+  const env = await detectEnvironment();
+  printEnvironment(env);
+
+  console.log(''); // spacing
+
+  // Screen 2: Installation Scope
+  const { scope, projectPath } = await promptScope();
+
+  // Screen 3: Embedding Provider
+  const { provider } = await promptProvider(env);
+
+  // Screen 4: Model Selection
+  const { model, pullModel } = await promptModel(provider, env);
+
+  // Pull Ollama model if needed
+  if (pullModel && provider === 'ollama') {
+    const ora = require('ora');
+    const spinner = ora(`Downloading ${model}...`).start();
+    try {
+      const { execSync } = require('child_process');
+      execSync(`ollama pull ${model}`, { stdio: ['pipe', 'pipe', 'pipe'], timeout: 300000 });
+      spinner.succeed(`Downloaded ${model}`);
+    } catch (e) {
+      spinner.fail(`Failed to download ${model}. You can run "ollama pull ${model}" manually later.`);
+    }
+  }
+
+  // Screen 5: Server Settings
+  const { port, host, autoStart } = await promptServer();
+
+  // Screen 6: Advanced Settings
+  const advancedResult = await promptAdvanced();
+
+  // Build final config
+  const config = {
+    scope,
+    projectPath,
+    provider,
+    model,
+    port,
+    host,
+    autoStart,
+    logLevel: advancedResult ? advancedResult.logLevel : 'INFO',
+    dbPath: advancedResult ? advancedResult.dbPath : null,
+    authEnabled: advancedResult ? advancedResult.authEnabled : false,
+    hotTierDays: advancedResult ? advancedResult.hotTierDays : 14,
+    warmTierDays: advancedResult ? advancedResult.warmTierDays : 90,
+    hooks: advancedResult ? advancedResult.hooks : ['session_start', 'grounding', 'session_end'],
+  };
+
+  // Screen 7: Review & Confirm
+  const confirmed = await promptConfirm(config);
+  if (!confirmed) {
+    console.log('\n  Installation cancelled.\n');
+    process.exit(0);
+  }
+
+  // Run Installation
+  console.log('');
+  const result = await runInstaller(config, AGENT_DIR);
+
+  if (result.success) {
+    const chalk = require('chalk');
+    const boxen = require('boxen');
+
+    const completionMsg = [
+      '',
+      chalk.green.bold('  Installation Complete!'),
+      '',
+      `  Dashboard:  ${chalk.cyan(`http://localhost:${port}/dashboard`)}`,
+      `  Health:     ${chalk.cyan(`http://localhost:${port}/health`)}`,
+      '',
+      chalk.dim('  Quick commands:'),
+      `    ${chalk.bold('claude-memory-agent status')}    - Check agent status`,
+      `    ${chalk.bold('claude-memory-agent dashboard')} - Open dashboard`,
+      `    ${chalk.bold('claude-memory-agent doctor')}    - Diagnose issues`,
+      `    ${chalk.bold('claude-memory-agent logs')}      - View logs`,
+      '',
+    ].join('\n');
+
+    console.log(boxen(completionMsg, {
+      padding: 1,
+      margin: 1,
+      borderStyle: 'round',
+      borderColor: 'green',
+    }));
+  } else {
+    console.log('\n  Installation completed with errors:');
+    result.errors.forEach(e => console.log(`    - ${e}`));
+    console.log('');
+  }
+}
+
+// Non-interactive fallback for CI/piped
+function runDefaults() {
+  const { runInstaller } = require('./lib/installer');
+  const config = {
+    scope: 'global',
+    projectPath: null,
+    provider: 'sentence-transformers',
+    model: 'BAAI/bge-base-en-v1.5',
+    port: 8102,
+    host: '127.0.0.1',
+    autoStart: false,
+    logLevel: 'INFO',
+    dbPath: null,
+    authEnabled: false,
+    hotTierDays: 14,
+    warmTierDays: 90,
+    hooks: ['session_start', 'grounding', 'session_end'],
+  };
+
+  return runInstaller(config, AGENT_DIR);
+}
+
+// Main entry
+async function main() {
+  try {
+    if (!process.stdin.isTTY) {
+      // Non-interactive: use defaults silently
+      await runDefaults();
+    } else {
+      await runWizard();
+    }
+  } catch (err) {
+    if (err.name === 'ExitPromptError') {
+      // User pressed Ctrl+C
+      console.log('\n  Setup cancelled.\n');
+      process.exit(0);
+    }
+    console.error('Setup error:', err.message);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { main, runWizard, runDefaults };