@unifiedmemory/cli 1.0.1 → 1.1.0

package/lib/config.js

@@ -1,39 +1,57 @@
-import fs from 'fs';
-import path from 'path';
 import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { dirname, join } from 'path';
+import { config as dotenvConfig } from 'dotenv';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Load environment variables from .env file if it exists
-const envPath = path.join(__dirname, '..', '.env');
-if (fs.existsSync(envPath)) {
-  const envContent = fs.readFileSync(envPath, 'utf8');
-  envContent.split('\n').forEach(line => {
-    const [key, ...valueParts] = line.split('=');
-    if (key && valueParts.length > 0) {
-      const value = valueParts.join('=').trim();
-      if (!process.env[key]) {
-        process.env[key] = value;
-      }
-    }
-  });
-}
+// Load environment variables from .env file using dotenv
+dotenvConfig({ path: join(__dirname, '..', '.env') });
 
 export const config = {
-  // Production Clerk OAuth client (safe to embed - public key only)
-  clerkClientId: process.env.CLERK_CLIENT_ID || 'nULlnomaKB9rRGP2',
+  // Required: Clerk OAuth configuration
+  clerkClientId: process.env.CLERK_CLIENT_ID,
   clerkClientSecret: process.env.CLERK_CLIENT_SECRET, // Optional for PKCE flow
-  clerkDomain: process.env.CLERK_DOMAIN || 'clear-caiman-45.clerk.accounts.dev',
-  apiEndpoint: process.env.API_ENDPOINT || 'https://rose-asp-main-1c0b114.d2.zuplo.dev',
+  clerkDomain: process.env.CLERK_DOMAIN,
+
+  // Required: API configuration
+  apiEndpoint: process.env.API_ENDPOINT,
+
+  // Optional: OAuth flow configuration (non-sensitive defaults OK)
   redirectUri: process.env.REDIRECT_URI || 'http://localhost:3333/callback',
   port: parseInt(process.env.PORT || '3333', 10)
 };
 
-// Validation function (no longer throws - hardcoded defaults are valid)
+// Validation function - ensures required configuration is present
 export function validateConfig() {
-  // All required values now have defaults - validation always passes
-  // Keep function for backward compatibility with existing code
+  const missing = [];
+
+  if (!config.clerkClientId) {
+    missing.push('CLERK_CLIENT_ID');
+  }
+
+  if (!config.clerkDomain) {
+    missing.push('CLERK_DOMAIN');
+  }
+
+  if (!config.apiEndpoint) {
+    missing.push('API_ENDPOINT');
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required environment variables: ${missing.join(', ')}\n\n` +
+      `Please create a .env file in the project root with these values.\n` +
+      `See .env.example for a template.`
+    );
+  }
+
+  // Validate URL format for apiEndpoint
+  try {
+    new URL(config.apiEndpoint);
+  } catch (e) {
+    throw new Error(`API_ENDPOINT must be a valid URL (got: ${config.apiEndpoint})`);
+  }
+
   return true;
 }

package/lib/jwt-utils.js

@@ -0,0 +1,63 @@
+/**
+ * JWT Utility Functions
+ *
+ * Centralized JWT parsing, validation, and expiration checking.
+ * Extracted from duplicate implementations in login.js and token-refresh.js.
+ */
+
+/**
+ * Parse a JWT token and return its payload
+ * @param {string} token - The JWT token to parse
+ * @returns {Object|null} Decoded JWT payload or null if invalid
+ */
+export function parseJWT(token) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+    const payload = Buffer.from(parts[1], 'base64').toString('utf8');
+    return JSON.parse(payload);
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Check if a JWT token is expired
+ * @param {Object} decoded - Decoded JWT payload with exp claim
+ * @param {number} bufferMs - Optional expiration buffer in milliseconds (default: 0)
+ * @returns {boolean} True if token is expired (including buffer)
+ */
+export function isJWTExpired(decoded, bufferMs = 0) {
+  if (!decoded?.exp) {
+    return true;
+  }
+  const expirationTime = decoded.exp * 1000;
+  return Date.now() >= (expirationTime - bufferMs);
+}
+
+/**
+ * Validate JWT structure has required fields
+ * @param {Object} decoded - Decoded JWT payload
+ * @returns {boolean} True if JWT has valid structure (sub and exp claims)
+ */
+export function validateJWTStructure(decoded) {
+  return decoded &&
+         typeof decoded === 'object' &&
+         decoded.sub &&
+         decoded.exp;
+}
+
+/**
+ * Get time until JWT expiration
+ * @param {Object} decoded - Decoded JWT payload with exp claim
+ * @returns {number} Milliseconds until expiration (negative if already expired)
+ */
+export function getTimeUntilExpiration(decoded) {
+  if (!decoded?.exp) {
+    return -1;
+  }
+  const expirationTime = decoded.exp * 1000;
+  return expirationTime - Date.now();
+}

package/lib/mcp-server.js

@@ -35,7 +35,7 @@ export async function startMCPServer() {
     // 5. Create MCP server
     const server = new Server(
       {
-        name: "unifiedmemory-vault",
+        name: "unifiedmemory",
         version: "1.0.0",
       },
       {

package/lib/memory-instructions.js

@@ -0,0 +1,72 @@
+// Unique marker to detect if instructions already present
+export const MEMORY_INSTRUCTIONS_MARKER = '<!-- UNIFIEDMEMORY_INSTRUCTIONS_V1 -->';
+
+export function getMemoryInstructions() {
+  return `${MEMORY_INSTRUCTIONS_MARKER}
+
+# UnifiedMemory Automatic Integration
+
+When working in this project, automatically integrate with UnifiedMemory to maintain project knowledge:
+
+## 1. Search Before Responding
+
+**When**: User submits any query or request
+**Action**: Use the \`unifiedmemory\` MCP tool to search for relevant context
+**Usage**:
+- Send the user's query to the search tool
+- Review the search results for relevant prior work, decisions, or context
+- Incorporate findings into your response
+
+Example:
+\`\`\`
+User: "Add dark mode to the dashboard"
+→ Search: unifiedmemory search --query "dark mode dashboard styling"
+→ Review results for existing patterns or decisions
+→ Respond with context-aware answer
+\`\`\`
+
+## 2. Record Plans
+
+**When**: Creating an implementation plan or design approach
+**Action**: Record the plan as a note using the \`unifiedmemory\` tool
+**Format**:
+- Include: objective, approach, key steps, important decisions
+- Keep concise but informative
+- Limit to under 1000 characters for optimal indexing
+
+Example:
+\`\`\`
+Plan created for dark mode feature
+→ unifiedmemory create_note --content "Plan: Dark mode implementation. Approach: CSS variables + localStorage persistence. Steps: 1) Define color tokens, 2) Add toggle component, 3) Persist preference. Decision: Use system preference as default."
+\`\`\`
+
+## 3. Record Task Completions
+
+**When**: After completing any task, feature, or significant milestone
+**Action**: Create a summary note using the \`unifiedmemory\` tool
+**Format**:
+- Summarize what was accomplished and why
+- Include key technical decisions or gotchas
+- **IMPORTANT**: Limit to under 1000 characters
+- Focus on outcomes, not detailed code
+
+Example:
+\`\`\`
+Completed dark mode feature
+→ unifiedmemory create_note --content "Completed: Dark mode toggle in dashboard. Implemented CSS custom properties with theme switcher component. User preference stored in localStorage. Respects system prefers-color-scheme by default. All components updated to use theme tokens."
+\`\`\`
+
+## Summary Guidelines
+
+- ✅ **DO**: Search context before responding
+- ✅ **DO**: Record plans and completions automatically
+- ✅ **DO**: Keep notes under 1000 characters
+- ✅ **DO**: Focus on decisions, outcomes, and context
+- ❌ **DON'T**: Record trivial tasks (typo fixes, minor edits)
+- ❌ **DON'T**: Include full code in notes
+- ❌ **DON'T**: Duplicate information already in git commits
+
+---
+*Auto-generated by UnifiedMemory CLI v1.0*
+`;
+}

package/lib/org-selection-ui.js

@@ -0,0 +1,104 @@
+/**
+ * Organization Selection UI
+ *
+ * Shared UI for prompting users to select an organization context.
+ * Extracted from duplicate implementations in login.js and org.js.
+ */
+
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { formatOrganization } from './clerk-api.js';
+
+/**
+ * Prompt user to select an organization context
+ * @param {Array} memberships - Array of organization memberships from Clerk
+ * @param {Object|null} currentOrg - Currently selected organization (optional)
+ * @param {Object} options - Display options
+ * @param {boolean} options.allowPersonal - Whether to show "Personal Account" option (default: true)
+ * @param {string} options.message - Custom prompt message (default: "Select account context:")
+ * @returns {Promise<Object|null>} Selected organization data or null for personal context
+ */
+export async function promptOrganizationSelection(memberships, currentOrg = null, options = {}) {
+  const {
+    allowPersonal = true,
+    message = 'Select account context (use arrow keys):',
+  } = options;
+
+  if (memberships.length === 0) {
+    if (!allowPersonal) {
+      throw new Error('No organizations available');
+    }
+    console.log(chalk.gray('No organizations found. Using personal account context.'));
+    return null;
+  }
+
+  console.log(chalk.green(`\nFound ${memberships.length} organization(s)!`));
+  console.log(chalk.cyan('💡 Use ↑/↓ arrow keys to navigate, Enter to select'));
+
+  // Format organizations for display
+  const formattedOrgs = memberships.map(formatOrganization);
+
+  const currentOrgId = currentOrg?.id;
+
+  // Build choices for inquirer
+  const choices = [];
+
+  if (allowPersonal) {
+    choices.push({
+      name: chalk.cyan('Personal Account') +
+            chalk.gray(' (no organization)') +
+            (currentOrgId ? '' : chalk.green(' ← current')),
+      value: null,
+      short: 'Personal Account',
+    });
+    choices.push(new inquirer.Separator(chalk.gray('--- Organizations ---')));
+  }
+
+  choices.push(...formattedOrgs.map(org => ({
+    name: `${chalk.green(org.name)} ${chalk.gray(`(${org.slug})`)} ${chalk.yellow(`[${org.role}]`)}${org.id === currentOrgId ? chalk.green(' ← current') : ''}`,
+    value: org,
+    short: org.name,
+  })));
+
+  // Calculate default selection
+  let defaultIndex = 0;
+  if (currentOrgId && allowPersonal) {
+    const orgIndex = formattedOrgs.findIndex(org => org.id === currentOrgId);
+    if (orgIndex >= 0) {
+      defaultIndex = orgIndex + 2; // +2 for personal + separator
+    }
+  } else if (currentOrgId && !allowPersonal) {
+    const orgIndex = formattedOrgs.findIndex(org => org.id === currentOrgId);
+    if (orgIndex >= 0) {
+      defaultIndex = orgIndex;
+    }
+  }
+
+  // Prompt user to select
+  const answer = await inquirer.prompt([
+    {
+      type: 'select',
+      name: 'organization',
+      message: message,
+      choices: choices,
+      pageSize: 15,
+      default: defaultIndex,
+    },
+  ]);
+
+  return answer.organization;
+}
+
+/**
+ * Display organization selection result
+ * @param {Object|null} selectedOrg - Selected organization or null for personal account
+ */
+export function displayOrganizationSelection(selectedOrg) {
+  if (selectedOrg) {
+    console.log(chalk.green(`\n✅ Selected organization: ${chalk.bold(selectedOrg.name)}`));
+    console.log(chalk.gray(`   Organization ID: ${selectedOrg.id}`));
+    console.log(chalk.gray(`   Your role: ${selectedOrg.role}`));
+  } else {
+    console.log(chalk.green('\n✅ Using personal account context'));
+  }
+}

package/lib/provider-detector.js

@@ -1,6 +1,8 @@
 import os from 'os';
 import path from 'path';
 import fs from 'fs-extra';
+import TOML from '@iarna/toml';
+import { getMemoryInstructions, MEMORY_INSTRUCTIONS_MARKER } from './memory-instructions.js';
 
 class ProviderDetector {
   constructor(projectDir = null) {
@@ -63,7 +65,7 @@ class BaseProvider {
     const config = this.readConfig() || { mcpServers: {} };
 
     config.mcpServers = config.mcpServers || {};
-    config.mcpServers.vault = {
+    config.mcpServers.unifiedmemory = {
       command: "um",
       args: ["mcp", "serve"]
     };
@@ -71,9 +73,37 @@ class BaseProvider {
     return this.writeConfig(config);
   }
 
-  installHook(hookType, scriptContent) {
-    // Implemented by providers that support hooks
-    return false;
+  /**
+   * Write memory instructions to specified file
+   * @param {string} filePath - Path to instruction file
+   * @param {string} assistantName - Display name for logging
+   * @returns {object} - Status object with status and optional error
+   */
+  writeMemoryInstructions(filePath, assistantName = 'assistant') {
+    try {
+      const instructions = getMemoryInstructions();
+
+      // Check if file exists
+      if (fs.existsSync(filePath)) {
+        // Check if marker already present
+        const existing = fs.readFileSync(filePath, 'utf8');
+        if (existing.includes(MEMORY_INSTRUCTIONS_MARKER)) {
+          // Instructions already present, skip
+          return { status: 'skipped', reason: 'already_present' };
+        }
+        // Append to existing file
+        fs.appendFileSync(filePath, '\n\n' + instructions);
+        return { status: 'appended' };
+      } else {
+        // Create new file
+        fs.ensureFileSync(filePath);
+        fs.writeFileSync(filePath, instructions);
+        return { status: 'created' };
+      }
+    } catch (e) {
+      console.error(`Failed to write memory instructions: ${e.message}`);
+      return { status: 'error', error: e.message };
+    }
   }
 }
 
@@ -131,12 +161,12 @@ class ClaudeProvider extends BaseProvider {
       // Add or update the required settings
       settings.enableAllProjectMcpServers = true;
 
-      // Ensure vault is in the enabled servers list
+      // Ensure unifiedmemory is in the enabled servers list
       if (!settings.enabledMcpjsonServers) {
         settings.enabledMcpjsonServers = [];
       }
-      if (!settings.enabledMcpjsonServers.includes('vault')) {
-        settings.enabledMcpjsonServers.push('vault');
+      if (!settings.enabledMcpjsonServers.includes('unifiedmemory')) {
+        settings.enabledMcpjsonServers.push('unifiedmemory');
       }
 
       // Write settings
@@ -149,19 +179,10 @@ class ClaudeProvider extends BaseProvider {
     }
   }
 
-  installHook(hookType, scriptContent) {
-    if (hookType !== 'prompt-submit' || !this.hooksDir) return false;
-
-    const hookPath = path.join(this.hooksDir, 'prompt-submit');
-
-    try {
-      fs.ensureDirSync(this.hooksDir);
-      fs.writeFileSync(hookPath, scriptContent, { mode: 0o755 });
-      return true;
-    } catch (e) {
-      console.error(`Failed to install hook: ${e.message}`);
-      return false;
-    }
+  configureMemoryInstructions() {
+    if (!this.projectDir) return { status: 'skipped', reason: 'no_project_dir' };
+    const instructionPath = path.join(this.projectDir, 'CLAUDE.md');
+    return this.writeMemoryInstructions(instructionPath, 'Claude Code');
   }
 }
 
@@ -172,6 +193,12 @@ class CursorProvider extends BaseProvider {
     // Detect by directory existence, not config file
     super('Cursor', configPath, false, baseDir);
   }
+
+  configureMemoryInstructions() {
+    // Use project-level file (assuming we're in a project directory)
+    const instructionPath = path.join(process.cwd(), 'CURSOR.md');
+    return this.writeMemoryInstructions(instructionPath, 'Cursor');
+  }
 }
 
 class ClineProvider extends BaseProvider {
@@ -181,6 +208,12 @@ class ClineProvider extends BaseProvider {
     // Detect by directory existence, not config file
     super('Cline', configPath, false, baseDir);
   }
+
+  configureMemoryInstructions() {
+    // Use project-level file
+    const instructionPath = path.join(process.cwd(), 'CLINE.md');
+    return this.writeMemoryInstructions(instructionPath, 'Cline');
+  }
 }
 
 class CodexProvider extends BaseProvider {
@@ -194,7 +227,7 @@ class CodexProvider extends BaseProvider {
     if (!fs.existsSync(this.configPath)) return null;
     try {
       const content = fs.readFileSync(this.configPath, 'utf8');
-      return this.parseTOML(content);
+      return TOML.parse(content);
     } catch (e) {
       return null;
     }
@@ -203,8 +236,8 @@ class CodexProvider extends BaseProvider {
   writeConfig(config) {
     try {
       fs.ensureFileSync(this.configPath);
-      const tomlContent = this.generateTOML(config);
-      fs.writeFileSync(this.configPath, tomlContent);
+      const tomlContent = TOML.stringify(config);
+      fs.writeFileSync(this.configPath, tomlContent, 'utf8');
       return true;
     } catch (e) {
       console.error(`Failed to write config: ${e.message}`);
@@ -212,65 +245,20 @@ class CodexProvider extends BaseProvider {
     }
   }
 
-  parseTOML(content) {
-    // Simple TOML parser for [mcp_servers.*] sections
-    const servers = {};
-    const lines = content.split('\n');
-    let currentServer = null;
-
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (trimmed.startsWith('[mcp_servers.')) {
-        const match = trimmed.match(/\[mcp_servers\.([^\]]+)\]/);
-        if (match) {
-          currentServer = match[1];
-          servers[currentServer] = {};
-        }
-      } else if (currentServer && trimmed.includes('=')) {
-        const [key, ...valueParts] = trimmed.split('=');
-        const value = valueParts.join('=').trim();
-        if (key.trim() === 'command') {
-          servers[currentServer].command = value.replace(/"/g, '');
-        } else if (key.trim() === 'args') {
-          // Parse array: ["arg1", "arg2"]
-          const argsMatch = value.match(/\[(.*)\]/);
-          if (argsMatch) {
-            servers[currentServer].args = argsMatch[1]
-              .split(',')
-              .map(s => s.trim().replace(/"/g, ''));
-          }
-        }
-      }
-    }
-
-    return { mcp_servers: servers };
-  }
-
-  generateTOML(config) {
-    let toml = '';
-    const servers = config.mcp_servers || {};
-
-    for (const [name, serverConfig] of Object.entries(servers)) {
-      toml += `[mcp_servers.${name}]\n`;
-      toml += `command = "${serverConfig.command}"\n`;
-      if (serverConfig.args && serverConfig.args.length > 0) {
-        const argsStr = serverConfig.args.map(arg => `"${arg}"`).join(', ');
-        toml += `args = [${argsStr}]\n`;
-      }
-      toml += '\n';
-    }
-
-    return toml;
-  }
-
   configureMCP() {
     const config = this.readConfig() || { mcp_servers: {} };
-    config.mcp_servers.vault = {
+    config.mcp_servers.unifiedmemory = {
       command: "um",
       args: ["mcp", "serve"]
     };
     return this.writeConfig(config);
   }
+
+  configureMemoryInstructions() {
+    // Use project-level file
+    const instructionPath = path.join(process.cwd(), 'CODEX.md');
+    return this.writeMemoryInstructions(instructionPath, 'Codex CLI');
+  }
 }
 
 class GeminiProvider extends BaseProvider {
@@ -279,6 +267,12 @@ class GeminiProvider extends BaseProvider {
     const detectionPath = path.dirname(configPath); // Detect by directory
     super('Gemini CLI', configPath, false, detectionPath);
   }
+
+  configureMemoryInstructions() {
+    // Use project-level file
+    const instructionPath = path.join(process.cwd(), 'GEMINI.md');
+    return this.writeMemoryInstructions(instructionPath, 'Gemini CLI');
+  }
 }
 
 export {

package/lib/token-refresh.js

@@ -1,5 +1,6 @@
 import { getToken, saveToken } from './token-storage.js';
 import { config } from './config.js';
+import { parseJWT } from './jwt-utils.js';
 
 /**
  * Check if token has expired
@@ -93,21 +94,3 @@ export async function refreshAccessToken(tokenData) {
     throw new Error(`Token refresh failed: ${error.message}`);
   }
 }
-
-/**
- * Parse JWT token payload
- * @param {string} token - JWT token
- * @returns {Object|null} - Decoded payload
- */
-function parseJWT(token) {
-  try {
-    const parts = token.split('.');
-    if (parts.length !== 3) {
-      return null;
-    }
-    const payload = Buffer.from(parts[1], 'base64').toString('utf8');
-    return JSON.parse(payload);
-  } catch (error) {
-    return null;
-  }
-}

package/lib/token-storage.js

@@ -6,18 +6,24 @@ const TOKEN_DIR = path.join(os.homedir(), '.um');
 const TOKEN_FILE = path.join(TOKEN_DIR, 'auth.json');
 
 export function saveToken(tokenData) {
-  // Create directory if it doesn't exist
+  // Create directory if it doesn't exist (owner-only permissions)
   if (!fs.existsSync(TOKEN_DIR)) {
-    fs.mkdirSync(TOKEN_DIR, { recursive: true });
+    fs.mkdirSync(TOKEN_DIR, { recursive: true, mode: 0o700 });
   }
 
+  // Ensure directory permissions are correct (in case it was created with wrong permissions)
+  fs.chmodSync(TOKEN_DIR, 0o700);
+
   // Preserve existing organization context if not explicitly overwritten
   const existingData = getToken();
   if (existingData && existingData.selectedOrg && !tokenData.selectedOrg) {
     tokenData.selectedOrg = existingData.selectedOrg;
   }
 
+  // Write token file with owner-only read/write permissions (0600)
   fs.writeFileSync(TOKEN_FILE, JSON.stringify(tokenData, null, 2));
+  // Explicitly set file permissions (writeFileSync mode option doesn't always work with extended attributes)
+  fs.chmodSync(TOKEN_FILE, 0o600);
 }
 
 export function getToken() {
@@ -49,8 +55,15 @@ export function updateSelectedOrg(orgData) {
     throw new Error('No token found. Please login first.');
   }
 
+  // Ensure directory permissions are correct
+  if (fs.existsSync(TOKEN_DIR)) {
+    fs.chmodSync(TOKEN_DIR, 0o700);
+  }
+
   tokenData.selectedOrg = orgData;
+  // Write with owner-only read/write permissions (0600)
   fs.writeFileSync(TOKEN_FILE, JSON.stringify(tokenData, null, 2));
+  fs.chmodSync(TOKEN_FILE, 0o600);
 }
 
 /**

package/lib/welcome.js

@@ -0,0 +1,40 @@
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+const version = packageJson.version;
+
+export function showWelcome() {
+  const pink = chalk.hex('#FF69B4');
+  const lightPink = chalk.hex('#FFB6C1');
+  const darkPink = chalk.hex('#C71585');
+  const gray = chalk.gray;
+  const white = chalk.white;
+
+  console.log('');
+  console.log(white.bold('  UnifiedMemory CLI ') + gray(`v${version}`));
+  console.log(gray('  AI-powered knowledge assistant'));
+  console.log('');
+  console.log(white('  Quick Start:'));
+  console.log(gray('    um init         ') + white('Initialize in current project'));
+  console.log(gray('    um status       ') + white('Check configuration'));
+  console.log(gray('    um login        ') + white('Authenticate with UnifiedMemory'));
+  console.log(gray('    um --help       ') + white('Show all commands'));
+  console.log('');
+  console.log(gray('  Learn more: ') + chalk.cyan.underline('https://unifiedmemory.ai'));
+  console.log('');
+}
+
+export function showShortWelcome() {
+  const pink = chalk.hex('#FF69B4');
+  const gray = chalk.gray;
+  const white = chalk.white;
+
+  console.log('');
+  console.log(pink('  🦎 ') + white.bold('UnifiedMemory CLI ') + gray(`v${version}`));
+  console.log(gray('     AI-powered knowledge assistant'));
+  console.log('');
+}