agent-mind 1.0.0

package/src/commands/init.js

@@ -0,0 +1,345 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+const detectTools = require('../utils/detect-tools');
+const { copyTemplate, replaceVarsInDir } = require('../utils/template');
+const { injectSnippet, getSnippet, hasSnippet } = require('../utils/inject-adapter');
+
+/**
+ * Handle both TTY and piped stdin modes.
+ *
+ * TTY mode: Use readline.createInterface directly
+ * Piped mode: Read all stdin lines upfront into a buffer, then consume them
+ *
+ * This fixes the issue where piped stdin loses data when multiple readline
+ * interfaces are created/destroyed.
+ */
+let rl = null;
+let isTTY = process.stdin.isTTY === true;
+let pipeBuffer = [];
+let pipeIndex = 0;
+
+/**
+ * Read all stdin lines into buffer (for piped mode only)
+ */
+function initPipeBuffer() {
+  return new Promise((resolve) => {
+    const lines = [];
+    process.stdin.setEncoding('utf8');
+
+    process.stdin.on('data', (chunk) => {
+      const allLines = chunk.split('\n');
+      allLines.forEach((line) => {
+        if (line.length > 0) {
+          lines.push(line);
+        }
+      });
+    });
+
+    process.stdin.on('end', () => {
+      pipeBuffer = lines;
+      pipeIndex = 0;
+      resolve();
+    });
+  });
+}
+
+/**
+ * Get next line from pipe buffer
+ */
+function getNextPipeLine() {
+  if (pipeIndex < pipeBuffer.length) {
+    return pipeBuffer[pipeIndex++];
+  }
+  return '';
+}
+
+/**
+ * Create and return a shared readline interface (TTY mode only)
+ */
+function getRL() {
+  if (!rl) {
+    rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+  }
+  return rl;
+}
+
+function closeRL() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+
+/**
+ * Interactive prompt - handles both TTY and piped modes
+ */
+function prompt(question, defaultValue = '') {
+  return new Promise((resolve) => {
+    const displayQuestion = defaultValue
+      ? `${question} [${defaultValue}]: `
+      : `${question}: `;
+
+    if (isTTY) {
+      // TTY mode: use readline
+      getRL().question(displayQuestion, (answer) => {
+        resolve(answer.trim() || defaultValue);
+      });
+    } else {
+      // Piped mode: get next line from buffer
+      const answer = getNextPipeLine();
+      resolve(answer.trim() || defaultValue);
+    }
+  });
+}
+
+/**
+ * Confirm prompt - returns true/false
+ */
+function confirm(question) {
+  return new Promise((resolve) => {
+    const confirmQuestion = `${question} (y/n): `;
+
+    if (isTTY) {
+      // TTY mode: use readline
+      getRL().question(confirmQuestion, (answer) => {
+        resolve(
+          answer.trim().toLowerCase() === 'y' ||
+            answer.trim().toLowerCase() === 'yes'
+        );
+      });
+    } else {
+      // Piped mode: get next line from buffer
+      const answer = getNextPipeLine();
+      resolve(
+        answer.trim().toLowerCase() === 'y' ||
+          answer.trim().toLowerCase() === 'yes'
+      );
+    }
+  });
+}
+
+/**
+ * Select from multiple choice
+ */
+async function select(question, choices) {
+  console.log(`\n${question}`);
+  choices.forEach((choice, idx) => {
+    console.log(`  ${idx + 1}. ${choice}`);
+  });
+
+  while (true) {
+    const answer = await prompt('Select', '1');
+    const idx = parseInt(answer, 10) - 1;
+    if (idx >= 0 && idx < choices.length) {
+      return choices[idx];
+    }
+    console.log('Invalid selection. Please try again.');
+  }
+}
+
+/**
+ * Make shell scripts executable
+ */
+function makeExecutable(dirPath) {
+  try {
+    const toolsDir = path.join(dirPath, '.am-tools');
+    if (fs.existsSync(toolsDir)) {
+      const files = fs.readdirSync(toolsDir);
+      files.forEach((file) => {
+        if (file.endsWith('.sh')) {
+          const filePath = path.join(toolsDir, file);
+          try {
+            execSync(`chmod +x "${filePath}"`, { stdio: 'pipe' });
+          } catch {
+            // Silently fail — Windows doesn't support chmod
+          }
+        }
+      });
+    }
+  } catch {
+    // Silently handle errors
+  }
+}
+
+/**
+ * Parse comma-separated values into array
+ */
+function parseCommaList(str) {
+  return str
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+async function init() {
+  const cwd = process.cwd();
+  const agentMindPath = path.join(cwd, '.agent-mind');
+
+  console.log('\n🚀 Agent Mind Initialization\n');
+
+  try {
+    // Initialize pipe buffer if stdin is piped
+    if (!isTTY) {
+      await initPipeBuffer();
+    }
+    // Check if already exists
+    if (fs.existsSync(agentMindPath)) {
+      console.log('⚠️  Agent Mind is already initialized in this directory.\n');
+      const shouldContinue = await confirm(
+        'Continue anyway and reinitialize?'
+      );
+      if (!shouldContinue) {
+        console.log('Initialization cancelled.');
+        return;
+      }
+      console.log('Reinitializing...\n');
+    }
+
+    // Interactive questions
+    const dirName = path.basename(cwd);
+    const projectName = await prompt('Project name', dirName);
+    const projectDescription = await prompt(
+      'Brief project description (optional)',
+      ''
+    );
+
+    const primaryTool = await select('Primary LLM tool?', [
+      'Claude Code',
+      'Codex',
+      'Gemini CLI',
+      'Cursor',
+      'Other',
+    ]);
+
+    const domainsInput = await prompt(
+      'Knowledge domains (comma-separated, optional)',
+      ''
+    );
+    const domains = parseCommaList(domainsInput).join(', ');
+
+    const stackInput = await prompt(
+      'Key technologies (comma-separated, optional)',
+      ''
+    );
+    const stack = parseCommaList(stackInput).join(', ');
+
+    // Copy template
+    console.log('\n📁 Creating Agent Mind structure...');
+    try {
+      copyTemplate(agentMindPath);
+    } catch (error) {
+      throw new Error(`Failed to copy template: ${error.message}`);
+    }
+
+    // Replace variables
+    const now = new Date();
+    const dateStr = now.toISOString().split('T')[0];
+
+    const variables = {
+      PROJECT_NAME: projectName,
+      PROJECT_DESCRIPTION: projectDescription || 'No description provided',
+      DATE: dateStr,
+      PRIMARY_AGENT: primaryTool,
+      DOMAINS: domains || '(none yet — add as project evolves)',
+      STACK: stack || '(none yet — add as needed)',
+      VERSION: getPackageVersion(),
+    };
+
+    replaceVarsInDir(agentMindPath, variables);
+
+    // Make scripts executable
+    makeExecutable(agentMindPath);
+
+    console.log('✅ Agent Mind structure created\n');
+
+    // Detect and integrate with existing tools
+    console.log('🔍 Checking for existing LLM tool configurations...\n');
+    const detectedTools = detectTools(cwd);
+
+    if (detectedTools.length > 0) {
+      console.log(`Found ${detectedTools.length} tool configuration(s):\n`);
+
+      for (const tool of detectedTools) {
+        const shouldIntegrate = await confirm(
+          `  Add Agent Mind integration to ${tool.tool} (${tool.configFile})?`
+        );
+
+        if (shouldIntegrate) {
+          const result = injectSnippet(tool.path);
+          if (result.success) {
+            console.log(`  ✅ Integrated with ${tool.tool}\n`);
+            console.log('  Added snippet:');
+            console.log(
+              getSnippet()
+                .split('\n')
+                .map((l) => '    ' + l)
+                .join('\n')
+            );
+            console.log('');
+          } else if (result.reason === 'already-present') {
+            console.log(
+              `  ℹ️  ${tool.tool} already has Agent Mind integration\n`
+            );
+          } else {
+            console.log(`  ❌ Failed to integrate: ${result.message}\n`);
+          }
+        } else {
+          console.log(`\n  Add this to your ${tool.configFile} manually:\n`);
+          console.log('  ---');
+          console.log(
+            getSnippet()
+              .split('\n')
+              .map((l) => '  ' + l)
+              .join('\n')
+          );
+          console.log('  ---\n');
+        }
+      }
+    } else {
+      console.log(
+        'No existing LLM tool configs found. You can set up integration later.\n'
+      );
+      console.log('When ready, add this snippet to your tool config');
+      console.log('(CLAUDE.md, AGENTS.md, GEMINI.md, or .cursorrules):\n');
+      console.log(
+        getSnippet()
+          .split('\n')
+          .map((l) => '  ' + l)
+          .join('\n')
+      );
+      console.log('');
+    }
+
+    // Success message
+    console.log('🎉 Agent Mind is ready!\n');
+    console.log('Next steps:');
+    console.log('  1. Your agent reads .agent-mind/BOOT.md at every session start');
+    console.log('  2. Review .agent-mind/config.md to customize settings');
+    console.log('  3. Run `agent-mind doctor` anytime to check memory health\n');
+  } finally {
+    closeRL();
+  }
+}
+
+/**
+ * Get package version
+ */
+function getPackageVersion() {
+  try {
+    const packageJsonPath = path.join(__dirname, '../../package.json');
+    const content = fs.readFileSync(packageJsonPath, 'utf8');
+    const pkg = JSON.parse(content);
+    return pkg.version;
+  } catch {
+    return '1.0.0';
+  }
+}
+
+module.exports = {
+  init,
+};

package/src/commands/meta.js

@@ -0,0 +1,34 @@
+const { getPackageVersion } = require('../utils/version');
+
+async function version() {
+  const ver = getPackageVersion();
+  console.log(`agent-mind ${ver}`);
+}
+
+async function help() {
+  console.log(`
+Agent Mind - Cognitive memory system for LLM agents
+
+USAGE:
+  agent-mind <command> [options]
+
+COMMANDS:
+  init      Initialize Agent Mind in your project
+  upgrade   Upgrade Agent Mind to the latest version
+  doctor    Check Agent Mind health and integrity
+  version   Show Agent Mind version
+  help      Show this help message
+
+EXAMPLES:
+  agent-mind init              # Start interactive setup
+  agent-mind upgrade           # Update existing Agent Mind
+  agent-mind doctor            # Check system health
+
+Learn more at: https://github.com/shikhar1verma/agent-mind
+`);
+}
+
+module.exports = {
+  version,
+  help
+};

package/src/commands/upgrade.js

@@ -0,0 +1,177 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { getPackageVersion, getCurrentVersion } = require('../utils/version');
+const { copyTemplate, replaceVars } = require('../utils/template');
+
+/**
+ * Confirm prompt - returns true/false
+ */
+function confirm(question) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    rl.question(`${question} (y/n): `, answer => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+/**
+ * List of core files that should be updated (not user files)
+ */
+const CORE_FILES = [
+  'BOOT.md',
+  'VERSION.md',
+  'protocols/compaction.md',
+  'protocols/maintenance.md',
+  'protocols/workflow.md',
+  'protocols/quality-gate.md',
+  'protocols/memory-ops.md',
+  'adapters/claude.md',
+  'adapters/codex.md',
+  'adapters/gemini.md',
+  'adapters/cursor.md'
+];
+
+/**
+ * Recursively copy core files only
+ */
+function copyOnlyCore(srcDir, destDir) {
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  function isCoreFile(relativePath) {
+    return CORE_FILES.some(core => {
+      // Handle both exact matches and directory prefixes
+      return relativePath === core || relativePath.startsWith(core + '/');
+    });
+  }
+
+  function copyDirFiltered(src, dest, basePath = '') {
+    const items = fs.readdirSync(src);
+
+    items.forEach(item => {
+      const srcPath = path.join(src, item);
+      const destPath = path.join(dest, item);
+      const relativePath = basePath ? `${basePath}/${item}` : item;
+      const stat = fs.statSync(srcPath);
+
+      if (stat.isDirectory()) {
+        // Check if this directory contains core files
+        if (isCoreFile(relativePath)) {
+          if (!fs.existsSync(destPath)) {
+            fs.mkdirSync(destPath, { recursive: true });
+          }
+          copyDirFiltered(srcPath, destPath, relativePath);
+        }
+      } else if (isCoreFile(relativePath)) {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    });
+  }
+
+  copyDirFiltered(srcDir, destDir);
+}
+
+/**
+ * Make shell scripts executable
+ */
+function makeExecutable(dirPath) {
+  try {
+    const toolsDir = path.join(dirPath, '.am-tools');
+    if (fs.existsSync(toolsDir)) {
+      const files = fs.readdirSync(toolsDir);
+      files.forEach(file => {
+        if (file.endsWith('.sh')) {
+          const filePath = path.join(toolsDir, file);
+          try {
+            const { execSync } = require('child_process');
+            execSync(`chmod +x "${filePath}"`, { stdio: 'pipe' });
+          } catch {
+            // Silently fail - Windows doesn't support chmod
+          }
+        }
+      });
+    }
+  } catch (error) {
+    // Silently handle errors
+  }
+}
+
+async function upgrade() {
+  const cwd = process.cwd();
+  const agentMindPath = path.join(cwd, '.agent-mind');
+
+  console.log('\n⬆️  Agent Mind Upgrade\n');
+
+  // Check if Agent Mind exists
+  if (!fs.existsSync(agentMindPath)) {
+    throw new Error('Agent Mind not found. Run "agent-mind init" first.');
+  }
+
+  // Get versions
+  const currentVersion = getCurrentVersion(agentMindPath);
+  const packageVersion = getPackageVersion();
+
+  console.log(`Current version: ${currentVersion}`);
+  console.log(`Package version: ${packageVersion}\n`);
+
+  if (currentVersion === packageVersion) {
+    console.log('✅ Already up to date!');
+    return;
+  }
+
+  // Show what will be updated
+  console.log('Files that will be updated:');
+  CORE_FILES.forEach(file => {
+    console.log(`  • ${file}`);
+  });
+  console.log('\nNote: Your user files (config.md, knowledge/, workspace/, history/) are never touched.\n');
+
+  // Ask for confirmation
+  const shouldProceed = await confirm('Continue upgrade?');
+  if (!shouldProceed) {
+    console.log('Upgrade cancelled.');
+    return;
+  }
+
+  // Perform upgrade
+  console.log('\n📦 Upgrading...');
+
+  const templatePath = path.join(__dirname, '../../template');
+  if (!fs.existsSync(templatePath)) {
+    throw new Error('Template directory not found');
+  }
+
+  // Copy only core files
+  copyOnlyCore(templatePath, agentMindPath);
+
+  // Update VERSION.md
+  const versionPath = path.join(agentMindPath, 'VERSION.md');
+  const now = new Date().toISOString().split('T')[0];
+
+  replaceVars(versionPath, {
+    VERSION: packageVersion,
+    DATE: now
+  });
+
+  // Make scripts executable
+  makeExecutable(agentMindPath);
+
+  console.log(`✅ Upgraded to ${packageVersion}\n`);
+  console.log('Updated files:');
+  CORE_FILES.forEach(file => {
+    console.log(`  ✓ ${file}`);
+  });
+  console.log('\nYour project data is safe and unchanged.\n');
+}
+
+module.exports = {
+  upgrade
+};

package/src/index.js

@@ -0,0 +1,18 @@
+// Agent Mind CLI main router
+// Exports command modules for dispatch
+
+module.exports = {
+  commands: {
+    init: require('./commands/init').init,
+    upgrade: require('./commands/upgrade').upgrade,
+    doctor: require('./commands/doctor').doctor,
+    version: require('./commands/meta').version,
+    help: require('./commands/meta').help
+  },
+  utils: {
+    detectTools: require('./utils/detect-tools'),
+    template: require('./utils/template'),
+    version: require('./utils/version'),
+    injectAdapter: require('./utils/inject-adapter')
+  }
+};

package/src/utils/detect-tools.js

@@ -0,0 +1,62 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Detect which LLM tool configuration files exist in the current directory
+ * @param {string} [cwd=process.cwd()] - Directory to search
+ * @returns {Array<{tool: string, path: string}>} - Detected tools with their config paths
+ */
+function detectTools(cwd = process.cwd()) {
+  const detected = [];
+
+  // Check for Claude Code
+  const claudePath = path.join(cwd, 'CLAUDE.md');
+  if (fs.existsSync(claudePath)) {
+    detected.push({
+      tool: 'Claude Code',
+      path: claudePath,
+      configFile: 'CLAUDE.md'
+    });
+  }
+
+  // Check for Codex
+  const agentsPath = path.join(cwd, 'AGENTS.md');
+  if (fs.existsSync(agentsPath)) {
+    detected.push({
+      tool: 'Codex',
+      path: agentsPath,
+      configFile: 'AGENTS.md'
+    });
+  }
+
+  // Check for Gemini CLI
+  const geminiPath = path.join(cwd, 'GEMINI.md');
+  if (fs.existsSync(geminiPath)) {
+    detected.push({
+      tool: 'Gemini CLI',
+      path: geminiPath,
+      configFile: 'GEMINI.md'
+    });
+  }
+
+  // Check for Cursor
+  const cursorRulesPath = path.join(cwd, '.cursorrules');
+  const cursorRulesDirPath = path.join(cwd, '.cursor', 'rules');
+  if (fs.existsSync(cursorRulesPath)) {
+    detected.push({
+      tool: 'Cursor',
+      path: cursorRulesPath,
+      configFile: '.cursorrules'
+    });
+  } else if (fs.existsSync(cursorRulesDirPath)) {
+    detected.push({
+      tool: 'Cursor',
+      path: cursorRulesDirPath,
+      configFile: '.cursor/rules/'
+    });
+  }
+
+  return detected;
+}
+
+module.exports = detectTools;

package/src/utils/inject-adapter.js

@@ -0,0 +1,65 @@
+const fs = require('fs');
+
+const SNIPPET = `## Agent Mind Memory System
+This project uses Agent Mind for structured memory management.
+At the start of every session, read \`.agent-mind/BOOT.md\` and follow its protocols.
+Use \`.agent-mind/workspace/\` as working memory for the current task.
+After completing a task, follow \`.agent-mind/protocols/compaction.md\`.
+When asked about memory health, follow \`.agent-mind/protocols/maintenance.md\`.`;
+
+/**
+ * Get the Agent Mind adapter snippet
+ */
+function getSnippet() {
+  return SNIPPET;
+}
+
+/**
+ * Check if the snippet is already present in the file
+ * @param {string} filePath - Path to config file
+ */
+function hasSnippet(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return content.includes('Agent Mind Memory System');
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Inject the Agent Mind snippet into a tool config file
+ * @param {string} filePath - Path to config file
+ */
+function injectSnippet(filePath) {
+  try {
+    if (hasSnippet(filePath)) {
+      return {
+        success: false,
+        reason: 'already-present',
+        message: 'Agent Mind snippet already present in file'
+      };
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const newContent = content + '\n\n' + SNIPPET + '\n';
+    fs.writeFileSync(filePath, newContent, 'utf8');
+
+    return {
+      success: true,
+      message: 'Agent Mind snippet injected successfully'
+    };
+  } catch (error) {
+    return {
+      success: false,
+      reason: 'write-error',
+      message: `Failed to inject snippet: ${error.message}`
+    };
+  }
+}
+
+module.exports = {
+  getSnippet,
+  hasSnippet,
+  injectSnippet
+};