@plexor-dev/claude-code-plugin-staging 0.1.0-beta.2 → 0.1.0-beta.21

package/lib/constants.js

@@ -4,7 +4,23 @@
 
 const path = require('path');
 
-const PLEXOR_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '', '.plexor');
+/**
+ * Get the user's home directory with proper validation
+ * @returns {string} Home directory path
+ * @throws {Error} If HOME is not set or empty
+ */
+function getHomeDir() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home || home.trim() === '') {
+    console.error('Error: HOME environment variable is not set.');
+    console.error('       Please set HOME to your user directory before running Plexor commands.');
+    process.exit(1);
+  }
+  return home;
+}
+
+const HOME_DIR = getHomeDir();
+const PLEXOR_DIR = path.join(HOME_DIR, '.plexor');
 const CONFIG_PATH = path.join(PLEXOR_DIR, 'config.json');
 const SESSION_PATH = path.join(PLEXOR_DIR, 'session.json');
 const CACHE_PATH = path.join(PLEXOR_DIR, 'cache.json');
@@ -16,6 +32,8 @@ const DEFAULT_API_URL = 'https://staging.api.plexor.dev';
 const DEFAULT_TIMEOUT = 5000;
 
 module.exports = {
+  getHomeDir,
+  HOME_DIR,
   PLEXOR_DIR,
   CONFIG_PATH,
   SESSION_PATH,

package/lib/logger.js

@@ -2,35 +2,94 @@
  * Plexor Logger
  *
  * Simple logger that outputs to stderr to avoid interfering with stdout JSON.
+ * Uses ANSI-colored badges for branded Plexor messages.
  */
 
+// ANSI color codes for branded badge output
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const WHITE = '\x1b[37m';
+const YELLOW_FG = '\x1b[33m';
+const RED_FG = '\x1b[31m';
+const CYAN_FG = '\x1b[36m';
+const BLUE_BG = '\x1b[44m';
+const YELLOW_BG = '\x1b[43m';
+const RED_BG = '\x1b[41m';
+
+// Pre-built badge strings
+const BADGE_INFO = `${BOLD}${WHITE}${BLUE_BG} PLEXOR ${RESET}`;
+const BADGE_WARN = `${BOLD}${WHITE}${YELLOW_BG} PLEXOR ${RESET}`;
+const BADGE_ERROR = `${BOLD}${WHITE}${RED_BG} PLEXOR ${RESET}`;
+
+function parseBooleanEnv(name, defaultValue) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null || raw === '') {
+    return defaultValue;
+  }
+  const normalized = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  return defaultValue;
+}
+
+function formatUxMessage(message) {
+  const text = String(message || '').trim();
+  if (!text) {
+    return '[PLEXOR: message]';
+  }
+  if (text.startsWith('[PLEXOR:')) {
+    return text;
+  }
+  if (text.startsWith('[PLEXOR') && text.endsWith(']')) {
+    return text.replace(/^\[PLEXOR[^\]]*\]\s*/i, '[PLEXOR: ');
+  }
+  return `[PLEXOR: ${text}]`;
+}
+
 class Logger {
   constructor(component = 'plexor') {
     this.component = component;
-    this.debug_enabled = process.env.PLEXOR_DEBUG === '1' || process.env.PLEXOR_DEBUG === 'true';
+    this.debug_enabled = parseBooleanEnv('PLEXOR_DEBUG', false);
+    this.ux_messages_enabled =
+      parseBooleanEnv('PLEXOR_UX_MESSAGES', true) &&
+      parseBooleanEnv('PLEXOR_UX_DEBUG_MESSAGES', true);
   }
 
   debug(msg, data = null) {
     if (this.debug_enabled) {
-      const output = data ? `[DEBUG][${this.component}] ${msg} ${JSON.stringify(data)}` : `[DEBUG][${this.component}] ${msg}`;
+      const output = data ? `${DIM}[${this.component}]${RESET} ${msg} ${JSON.stringify(data)}` : `${DIM}[${this.component}]${RESET} ${msg}`;
       console.error(output);
     }
   }
 
   info(msg, data = null) {
-    const output = data ? `${msg} ${JSON.stringify(data)}` : msg;
+    const output = data ? `${BADGE_INFO} ${msg} ${JSON.stringify(data)}` : `${BADGE_INFO} ${msg}`;
     console.error(output);
   }
 
   warn(msg, data = null) {
-    const output = data ? `[WARN][${this.component}] ${msg} ${JSON.stringify(data)}` : `[WARN][${this.component}] ${msg}`;
+    const output = data ? `${BADGE_WARN} ${YELLOW_FG}${msg} ${JSON.stringify(data)}${RESET}` : `${BADGE_WARN} ${YELLOW_FG}${msg}${RESET}`;
     console.error(output);
   }
 
   error(msg, data = null) {
-    const output = data ? `[ERROR][${this.component}] ${msg} ${JSON.stringify(data)}` : `[ERROR][${this.component}] ${msg}`;
+    const output = data ? `${BADGE_ERROR} ${RED_FG}${msg} ${JSON.stringify(data)}${RESET}` : `${BADGE_ERROR} ${RED_FG}${msg}${RESET}`;
     console.error(output);
   }
+
+  ux(msg, data = null) {
+    if (!this.ux_messages_enabled) {
+      return;
+    }
+    const prefixed = formatUxMessage(msg);
+    const output = data ? `${prefixed} ${JSON.stringify(data)}` : prefixed;
+    console.error(`${CYAN_FG}${output}${RESET}`);
+  }
 }
 
 module.exports = Logger;

package/lib/settings-manager.js

@@ -12,13 +12,111 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
 
 const CLAUDE_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude');
 const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
+const LOCK_TIMEOUT_MS = 5000; // 5 second lock timeout
 
 // Plexor gateway endpoints
 const PLEXOR_STAGING_URL = 'https://staging.api.plexor.dev/gateway/anthropic';
 const PLEXOR_PROD_URL = 'https://api.plexor.dev/gateway/anthropic';
+const PREVIOUS_API_KEY_ENV = 'PLEXOR_PREVIOUS_ANTHROPIC_API_KEY';
+const PREVIOUS_AUTH_TOKEN_ENV = 'PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN';
+
+/**
+ * Check if a base URL is a Plexor-managed gateway URL.
+ * Detects all variants: production, staging, localhost, tunnels.
+ */
+function isManagedGatewayUrl(baseUrl) {
+  if (!baseUrl) return false;
+  return (
+    baseUrl.includes('plexor') ||
+    baseUrl.includes('staging.api') ||
+    baseUrl.includes('localhost') ||
+    baseUrl.includes('127.0.0.1') ||
+    baseUrl.includes('ngrok') ||
+    baseUrl.includes('localtunnel')
+  );
+}
+
+function isPlexorApiKey(value = '') {
+  return typeof value === 'string' && value.startsWith('plx_');
+}
+
+function getPlexorAuthKey(env = {}) {
+  const apiKey = env.ANTHROPIC_API_KEY || '';
+  const authToken = env.ANTHROPIC_AUTH_TOKEN || '';
+
+  if (isPlexorApiKey(apiKey)) return apiKey;
+  if (isPlexorApiKey(authToken)) return authToken;
+  return apiKey || authToken || '';
+}
+
+function hasPlexorManagedAuth(env = {}) {
+  return (
+    isManagedGatewayUrl(env.ANTHROPIC_BASE_URL || '') ||
+    isPlexorApiKey(env.ANTHROPIC_API_KEY || '') ||
+    isPlexorApiKey(env.ANTHROPIC_AUTH_TOKEN || '')
+  );
+}
+
+function stashDirectAuthEnv(env, plexorApiKey) {
+  const alreadyManaged = hasPlexorManagedAuth(env);
+  const currentApiKey = env.ANTHROPIC_API_KEY || '';
+  const currentAuthToken = env.ANTHROPIC_AUTH_TOKEN || '';
+
+  if (currentApiKey && !isPlexorApiKey(currentApiKey) && currentApiKey !== plexorApiKey) {
+    env[PREVIOUS_API_KEY_ENV] = currentApiKey;
+  } else if (!alreadyManaged) {
+    delete env[PREVIOUS_API_KEY_ENV];
+  }
+
+  if (currentAuthToken && !isPlexorApiKey(currentAuthToken) && currentAuthToken !== plexorApiKey) {
+    env[PREVIOUS_AUTH_TOKEN_ENV] = currentAuthToken;
+  } else if (!alreadyManaged) {
+    delete env[PREVIOUS_AUTH_TOKEN_ENV];
+  }
+}
+
+function setPlexorAuthKey(env, apiKey) {
+  stashDirectAuthEnv(env, apiKey);
+  env.ANTHROPIC_API_KEY = apiKey;
+  env.ANTHROPIC_AUTH_TOKEN = apiKey;
+}
+
+function clearPlexorRoutingEnv(env = {}) {
+  const hasManagedBaseUrl = isManagedGatewayUrl(env.ANTHROPIC_BASE_URL || '');
+  const hasPlexorApiKey = isPlexorApiKey(env.ANTHROPIC_API_KEY || '');
+  const hasPlexorAuthToken = isPlexorApiKey(env.ANTHROPIC_AUTH_TOKEN || '');
+
+  if (!hasManagedBaseUrl && !hasPlexorApiKey && !hasPlexorAuthToken) {
+    return false;
+  }
+
+  if (hasManagedBaseUrl) {
+    delete env.ANTHROPIC_BASE_URL;
+  }
+  if (hasPlexorAuthToken) {
+    delete env.ANTHROPIC_AUTH_TOKEN;
+  }
+  if (hasPlexorApiKey) {
+    delete env.ANTHROPIC_API_KEY;
+  }
+
+  if (!env.ANTHROPIC_API_KEY && env[PREVIOUS_API_KEY_ENV]) {
+    env.ANTHROPIC_API_KEY = env[PREVIOUS_API_KEY_ENV];
+  }
+  if (!env.ANTHROPIC_AUTH_TOKEN && env[PREVIOUS_AUTH_TOKEN_ENV]) {
+    env.ANTHROPIC_AUTH_TOKEN = env[PREVIOUS_AUTH_TOKEN_ENV];
+  }
+
+  delete env[PREVIOUS_API_KEY_ENV];
+  delete env[PREVIOUS_AUTH_TOKEN_ENV];
+
+  return true;
+}
 
 class ClaudeSettingsManager {
   constructor() {
@@ -27,8 +125,8 @@ class ClaudeSettingsManager {
   }
 
   /**
-   * Load current Claude settings
-   * @returns {Object} settings object or empty object if not found
+   * Load current Claude settings with integrity checking
+   * @returns {Object} settings object or empty object if not found/corrupted
    */
   load() {
     try {
@@ -36,15 +134,84 @@ class ClaudeSettingsManager {
         return {};
       }
       const data = fs.readFileSync(this.settingsPath, 'utf8');
-      return JSON.parse(data);
+
+      // Check for empty file
+      if (!data || data.trim() === '') {
+        return {};
+      }
+
+      const parsed = JSON.parse(data);
+
+      // Basic schema validation - must be an object
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        const backupPath = this._backupCorruptedFile();
+        console.warn('');
+        console.warn('WARNING: Claude settings file has invalid format!');
+        if (backupPath) {
+          console.warn(`         Corrupted file backed up to: ${backupPath}`);
+        }
+        console.warn('         Using default settings. Your previous settings may need manual recovery.');
+        console.warn('');
+        return {};
+      }
+
+      return parsed;
     } catch (err) {
-      // Return empty object if file doesn't exist or parse error
+      if (err.code === 'ENOENT') {
+        return {};
+      }
+      // JSON parse error or corrupted file
+      if (err instanceof SyntaxError) {
+        const backupPath = this._backupCorruptedFile();
+        console.warn('');
+        console.warn('WARNING: Claude settings file is corrupted (invalid JSON)!');
+        if (backupPath) {
+          console.warn(`         Corrupted file backed up to: ${backupPath}`);
+        }
+        console.warn('         Using default settings. Your previous settings may need manual recovery.');
+        console.warn('');
+        return {};
+      }
+      // Permission error
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        console.warn(`Warning: Cannot read ${this.settingsPath} (permission denied)`);
+        return {};
+      }
+      console.warn('Warning: Failed to load Claude settings:', err.message);
       return {};
     }
   }
 
   /**
-   * Save Claude settings
+   * Backup a corrupted settings file with numbered suffix for debugging
+   * Creates settings.json.corrupted.1, .corrupted.2, etc. to preserve history
+   * @returns {string|null} path to backup file, or null if backup failed
+   */
+  _backupCorruptedFile() {
+    try {
+      if (fs.existsSync(this.settingsPath)) {
+        // Find next available numbered backup
+        let backupNum = 1;
+        let backupPath;
+        while (true) {
+          backupPath = `${this.settingsPath}.corrupted.${backupNum}`;
+          if (!fs.existsSync(backupPath)) {
+            break;
+          }
+          backupNum++;
+        }
+        fs.copyFileSync(this.settingsPath, backupPath);
+        return backupPath;
+      }
+    } catch {
+      // Ignore backup errors silently
+    }
+    return null;
+  }
+
+  /**
+   * Save Claude settings using atomic write pattern
+   * Prevents race conditions by writing to temp file then renaming
    * @param {Object} settings - settings object to save
    * @returns {boolean} success status
    */
@@ -55,10 +222,27 @@ class ClaudeSettingsManager {
         fs.mkdirSync(this.claudeDir, { recursive: true });
       }
 
-      fs.writeFileSync(this.settingsPath, JSON.stringify(settings, null, 2));
+      // Atomic write: write to temp file, then rename
+      // This prevents race conditions where concurrent writes corrupt the file
+      const tempId = crypto.randomBytes(8).toString('hex');
+      const tempPath = path.join(this.claudeDir, `.settings.${tempId}.tmp`);
+
+      // Write to temp file
+      const content = JSON.stringify(settings, null, 2);
+      fs.writeFileSync(tempPath, content, { mode: 0o600 });
+
+      // Atomic rename (on POSIX systems, rename is atomic)
+      fs.renameSync(tempPath, this.settingsPath);
+
       return true;
     } catch (err) {
-      console.error('Failed to save Claude settings:', err.message);
+      // Clean error message for permission errors
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        console.error(`Error: Cannot write to ${this.settingsPath}`);
+        console.error('       Check file permissions or run with appropriate access.');
+      } else {
+        console.error('Failed to save Claude settings:', err.message);
+      }
       return false;
     }
   }
@@ -66,8 +250,9 @@ class ClaudeSettingsManager {
   /**
    * Enable Plexor routing by setting env vars in settings.json
    *
-   * This is the KEY mechanism: setting ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN
-   * in the env block redirects ALL Claude Code sessions to Plexor automatically.
+   * This is the KEY mechanism: setting ANTHROPIC_BASE_URL plus both Claude auth
+   * env vars in settings.json redirects ALL Claude Code sessions to Plexor
+   * automatically, even when the user previously configured direct API auth.
    *
    * @param {string} apiKey - Plexor API key (plx_*)
    * @param {Object} options - { useStaging: boolean }
@@ -86,10 +271,10 @@ class ClaudeSettingsManager {
         settings.env = {};
       }
 
-      // Set the magic environment variables
-      // ANTHROPIC_AUTH_TOKEN has higher precedence than ANTHROPIC_API_KEY
+      // Mirror the Plexor key into both Claude auth env vars so every Claude
+      // runtime path uses the gateway instead of any previously saved direct key.
       settings.env.ANTHROPIC_BASE_URL = apiUrl;
-      settings.env.ANTHROPIC_AUTH_TOKEN = apiKey;
+      setPlexorAuthKey(settings.env, apiKey);
 
       const success = this.save(settings);
 
@@ -124,9 +309,10 @@ class ClaudeSettingsManager {
         return true;
       }
 
-      // Remove Plexor-specific env vars
-      delete settings.env.ANTHROPIC_BASE_URL;
-      delete settings.env.ANTHROPIC_AUTH_TOKEN;
+      if (!clearPlexorRoutingEnv(settings.env)) {
+        console.log('Plexor routing is not currently enabled.');
+        return true;
+      }
 
       // Clean up empty env block
       if (Object.keys(settings.env).length === 0) {
@@ -157,26 +343,48 @@ class ClaudeSettingsManager {
       const settings = this.load();
 
       const baseUrl = settings.env?.ANTHROPIC_BASE_URL || null;
-      const hasToken = !!settings.env?.ANTHROPIC_AUTH_TOKEN;
+      const authKey = getPlexorAuthKey(settings.env);
+      const hasToken = !!authKey;
 
-      // Check if routing to Plexor
-      const isPlexorRouting = baseUrl && (
-        baseUrl.includes('plexor') ||
-        baseUrl.includes('staging.api')
-      );
+      // Check if routing to Plexor (any variant: prod, staging, localhost, tunnel)
+      const isPlexorRouting = isManagedGatewayUrl(baseUrl);
 
       return {
         enabled: isPlexorRouting,
         baseUrl,
         hasToken,
         isStaging: baseUrl?.includes('staging') || false,
-        tokenPreview: hasToken ? settings.env.ANTHROPIC_AUTH_TOKEN.substring(0, 12) + '...' : null
+        tokenPreview: hasToken ? authKey.substring(0, 12) + '...' : null
       };
     } catch {
       return { enabled: false, baseUrl: null, hasToken: false };
     }
   }
 
+  /**
+   * Detect partial routing state where URL points to Plexor but auth is missing/invalid
+   * This can cause confusing auth errors for users
+   * @returns {Object} { partial: boolean, issue: string|null }
+   */
+  detectPartialState() {
+    try {
+      const settings = this.load();
+      const baseUrl = settings.env?.ANTHROPIC_BASE_URL || '';
+      const authKey = getPlexorAuthKey(settings.env);
+      const isPlexorUrl = isManagedGatewayUrl(baseUrl);
+
+      if (isPlexorUrl && !authKey) {
+        return { partial: true, issue: 'Plexor URL set but no Plexor auth key' };
+      }
+      if (isPlexorUrl && !isPlexorApiKey(authKey)) {
+        return { partial: true, issue: 'Plexor URL set but auth key is not a Plexor key' };
+      }
+      return { partial: false, issue: null };
+    } catch {
+      return { partial: false, issue: null };
+    }
+  }
+
   /**
    * Update just the API key without changing other settings
    * @param {string} apiKey - new Plexor API key
@@ -190,7 +398,7 @@ class ClaudeSettingsManager {
         settings.env = {};
       }
 
-      settings.env.ANTHROPIC_AUTH_TOKEN = apiKey;
+      setPlexorAuthKey(settings.env, apiKey);
       return this.save(settings);
     } catch (err) {
       console.error('Failed to update API key:', err.message);
@@ -208,7 +416,7 @@ class ClaudeSettingsManager {
       const settings = this.load();
 
       if (!settings.env?.ANTHROPIC_BASE_URL) {
-        console.log('Plexor routing is not enabled. Run /plexor-login first.');
+        console.log('Plexor routing is not enabled. Run /plexor-setup first.');
         return false;
       }
 
@@ -232,6 +440,7 @@ const settingsManager = new ClaudeSettingsManager();
 module.exports = {
   ClaudeSettingsManager,
   settingsManager,
+  isManagedGatewayUrl,
   CLAUDE_DIR,
   SETTINGS_PATH,
   PLEXOR_STAGING_URL,

package/lib/verify-route.js

@@ -0,0 +1,84 @@
+const { spawnSync } = require('child_process');
+const { HOME_DIR } = require('./constants');
+
+const VERIFY_PROMPT = 'Reply with exactly PONG. Do not use tools.';
+const EXPECTED_VERIFY_RESPONSE = 'PONG';
+
+function normalizeVerifyOutput(output = '') {
+  return String(output).trim();
+}
+
+function createVerifyEnv(sourceEnv = process.env) {
+  const env = { ...sourceEnv };
+  delete env.CLAUDECODE;
+  return env;
+}
+
+function interpretVerifyResult(result = {}) {
+  const stdout = normalizeVerifyOutput(result.stdout);
+  const stderr = normalizeVerifyOutput(result.stderr);
+
+  if (result.error) {
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      code: null,
+      reason: result.error.message || 'Claude verification failed to start'
+    };
+  }
+
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      code: result.status,
+      reason: stderr || stdout || `Claude exited with status ${result.status}`
+    };
+  }
+
+  if (stdout !== EXPECTED_VERIFY_RESPONSE) {
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      code: result.status,
+      reason: `Expected "${EXPECTED_VERIFY_RESPONSE}" but received "${stdout || '(empty)'}"`
+    };
+  }
+
+  return {
+    ok: true,
+    stdout,
+    stderr,
+    code: result.status,
+    reason: ''
+  };
+}
+
+function runClaudeRouteVerification(options = {}, runCommand = spawnSync) {
+  const result = runCommand(options.claudeCommand || 'claude', [
+    '-p',
+    '--tools', '',
+    '--output-format', 'text',
+    VERIFY_PROMPT
+  ], {
+    cwd: options.cwd || HOME_DIR,
+    env: createVerifyEnv(options.env || process.env),
+    encoding: 'utf8',
+    timeout: options.timeoutMs || 30000,
+    maxBuffer: 1024 * 1024
+  });
+
+  return interpretVerifyResult(result);
+}
+
+module.exports = {
+  EXPECTED_VERIFY_RESPONSE,
+  VERIFY_PROMPT,
+  createVerifyEnv,
+  interpretVerifyResult,
+  normalizeVerifyOutput,
+  runClaudeRouteVerification
+};

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@plexor-dev/claude-code-plugin-staging",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.21",
   "description": "STAGING - LLM cost optimization plugin for Claude Code (internal testing)",
   "main": "lib/constants.js",
   "bin": {
     "plexor-status": "./commands/plexor-status.js",
-    "plexor-mode": "./commands/plexor-mode.js",
+    "plexor-setup": "./commands/plexor-setup.js",
     "plexor-enabled": "./commands/plexor-enabled.js",
-    "plexor-provider": "./commands/plexor-provider.js",
     "plexor-login": "./commands/plexor-login.js",
     "plexor-logout": "./commands/plexor-logout.js",
+    "plexor-uninstall": "./commands/plexor-uninstall.js",
     "plexor-settings": "./commands/plexor-settings.js",
-    "plexor-config": "./commands/plexor-config.js"
+    "plexor-routing": "./commands/plexor-routing.js",
+    "plexor-agent": "./commands/plexor-agent.js",
+    "plexor-provider": "./commands/plexor-provider.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",