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

package/commands/plexor-settings.md

@@ -1,28 +1,52 @@
 ---
-description: Configure Plexor settings (API URL, mode, provider preferences) (user)
+description: View and change Plexor settings — routing mode, agent autonomy, LLM provider (user)
 ---
 
-# Plexor Settings
+**Step 1: Check if arguments were provided.**
 
-Run this command to view or update settings:
+If `$ARGUMENTS` contains both a dimension AND a value (e.g., `/plexor-settings routing eco`), apply it directly:
 
 ```bash
-node ~/.claude/plugins/plexor/commands/plexor-settings.js
+node ~/.claude/plugins/plexor/commands/plexor-settings.js $ARGUMENTS
 ```
 
-To update a setting:
+Present the output to the user and STOP. Do NOT call any other tools.
+
+**Step 2: If only a dimension was provided** (e.g., `/plexor-settings routing`), show current state then present a picker for that dimension:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-settings.js $ARGUMENTS
+```
+
+Then use **AskUserQuestion** based on which dimension:
+
+**If dimension is "routing":**
+- **Question**: "Which routing mode?"
+- **Header**: "Routing"
+- **Options**: eco (Recommended) — "Cheapest first", balanced — "Cost/quality balance", quality — "Premium models", passthrough — "Direct access"
+
+**If dimension is "agent":**
+- **Question**: "Which agent autonomy mode?"
+- **Header**: "Agent mode"
+- **Options**: supervised — "Confirm every action", autonomous (Recommended) — "Safe bounds", danger-full-auto — "No guardrails"
+
+**If dimension is "provider":**
+- **Question**: "Which LLM provider?"
+- **Header**: "Provider"
+- **Options**: auto (Recommended) — "Auto-select", anthropic — "Claude models", openai — "GPT models", deepseek — "DeepSeek models"
+
+After the user selects, apply:
 
 ```bash
-node ~/.claude/plugins/plexor/commands/plexor-settings.js cache true
-node ~/.claude/plugins/plexor/commands/plexor-settings.js timeout 10000
+node ~/.claude/plugins/plexor/commands/plexor-settings.js <dimension> <selected_value>
 ```
 
-Use the Bash tool to execute this command.
+Present the output and STOP.
+
+**Step 3: If NO arguments were provided** (just `/plexor-settings`), show the dashboard:
 
-**IMPORTANT**: After running this command and displaying the output, STOP. Do not:
-- Read any files
-- Explore the codebase
-- Run additional commands
-- Ask follow-up questions
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-settings.js
+```
 
-The command output is the complete response. Simply show the output and wait for the user's next input.
+Present the output to the user and STOP. Do NOT call any other tools.

package/commands/plexor-setup.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { PLEXOR_DIR, CONFIG_PATH, DEFAULT_API_URL } = require('../lib/constants');
+const PlexorClient = require('../lib/plexor-client');
+const { settingsManager } = require('../lib/settings-manager');
+const {
+  EXPECTED_VERIFY_RESPONSE,
+  VERIFY_PROMPT,
+  runClaudeRouteVerification
+} = require('../lib/verify-route');
+
+function isPlexorApiKey(value) {
+  return typeof value === 'string' && value.startsWith('plx_') && value.length >= 20;
+}
+
+function loadConfig() {
+  try {
+    if (!fs.existsSync(CONFIG_PATH)) {
+      return { version: 1, auth: {}, settings: {} };
+    }
+    const data = fs.readFileSync(CONFIG_PATH, 'utf8');
+    if (!data || data.trim() === '') {
+      return { version: 1, auth: {}, settings: {} };
+    }
+    const parsed = JSON.parse(data);
+    if (typeof parsed !== 'object' || parsed === null) {
+      return { version: 1, auth: {}, settings: {} };
+    }
+    return parsed;
+  } catch {
+    return { version: 1, auth: {}, settings: {} };
+  }
+}
+
+function saveConfig(config) {
+  try {
+    if (!fs.existsSync(PLEXOR_DIR)) {
+      fs.mkdirSync(PLEXOR_DIR, { recursive: true, mode: 0o700 });
+    }
+    const tempPath = path.join(PLEXOR_DIR, `.config.${Date.now()}.tmp`);
+    fs.writeFileSync(tempPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+    fs.renameSync(tempPath, CONFIG_PATH);
+    return true;
+  } catch (err) {
+    console.error(`Failed to save config: ${err.message}`);
+    return false;
+  }
+}
+
+function readFromStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    const timeout = setTimeout(() => {
+      reject(new Error('Timeout reading from stdin'));
+    }, 5000);
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timeout);
+      resolve(data.trim());
+    });
+    process.stdin.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+    process.stdin.resume();
+  });
+}
+
+function getKeySource(args, existingKey) {
+  if (process.env.PLEXOR_API_KEY) {
+    return { apiKey: process.env.PLEXOR_API_KEY, source: 'environment' };
+  }
+  if (!process.stdin.isTTY && args.length === 0) {
+    return { apiKey: null, source: 'stdin' };
+  }
+  if (args[0] && !args[0].startsWith('--')) {
+    return { apiKey: args[0], source: 'argument' };
+  }
+  if (existingKey) {
+    return { apiKey: existingKey, source: 'saved-config' };
+  }
+  return { apiKey: null, source: null };
+}
+
+function getGatewayLabel(apiUrl) {
+  return apiUrl.includes('staging') ? 'staging' : 'production';
+}
+
+function updateHealth(config, state) {
+  config.health = {
+    installed: true,
+    connected: true,
+    routing_active: state.routingEnabled,
+    verified: state.verifyResult.ok,
+    verified_at: state.verifyResult.ok ? new Date().toISOString() : null,
+    verify_prompt: VERIFY_PROMPT,
+    verify_expected: EXPECTED_VERIFY_RESPONSE,
+    verify_error: state.verifyResult.ok ? null : state.verifyResult.reason,
+    gateway: state.gateway,
+    previous_auth_preserved: state.previousAuthPreserved
+  };
+}
+
+function printUsage() {
+  console.log('Plexor setup is the guided first-run path.');
+  console.log('');
+  console.log('Provide a Plexor API key one of these ways:');
+  console.log('  /plexor-setup plx_...');
+  console.log('  echo "plx_..." | /plexor-setup');
+  console.log('  PLEXOR_API_KEY=plx_... /plexor-setup');
+}
+
+function printReceipt({ user, gateway, previousAuthPreserved, verifyResult }) {
+  const line = (content) => `│  ${String(content).slice(0, 43).padEnd(43)}│`;
+
+  console.log('┌─────────────────────────────────────────────┐');
+  console.log(line('Plexor setup complete'));
+  console.log('├─────────────────────────────────────────────┤');
+  console.log(line(`Connected: OK (${user.email || 'Unknown'})`));
+  console.log(line(`Routing Active: OK (${gateway})`));
+  console.log(line(`Verified: ${verifyResult.ok ? 'OK' : 'FAILED'}`));
+  console.log(line(`Previous Claude auth: ${previousAuthPreserved ? 'Saved' : 'None found'}`));
+  console.log('├─────────────────────────────────────────────┤');
+  if (verifyResult.ok) {
+    console.log(line('Claude is now routed through Plexor'));
+    console.log(line('Logout/uninstall restores prior auth'));
+    console.log(line('Next: Run /plexor-status for health + stats'));
+  } else {
+    console.log(line('Claude routing was configured'));
+    console.log(line('Verification did not pass'));
+    console.log(line('Next: Run /plexor-setup again to repair'));
+  }
+  console.log('└─────────────────────────────────────────────┘');
+
+  if (!verifyResult.ok) {
+    console.log('');
+    console.log(`Verification failed: ${verifyResult.reason}`);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const skipVerify = args.includes('--skip-verify');
+  const config = loadConfig();
+  const existingKey = config.auth?.api_key || '';
+  const keyInput = getKeySource(args.filter(arg => arg !== '--skip-verify'), existingKey);
+  let apiKey = keyInput.apiKey;
+
+  if (!apiKey && keyInput.source === 'stdin') {
+    try {
+      apiKey = await readFromStdin();
+    } catch {
+      apiKey = null;
+    }
+  }
+
+  if (!apiKey) {
+    printUsage();
+    process.exit(1);
+  }
+
+  if (!isPlexorApiKey(apiKey)) {
+    console.error('Error: Plexor API keys must start with "plx_" and be at least 20 characters.');
+    process.exit(1);
+  }
+
+  const apiUrl = config.settings?.apiUrl || DEFAULT_API_URL;
+  const client = new PlexorClient({ apiKey, baseUrl: apiUrl });
+
+  let user;
+  try {
+    user = await client.getUser();
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const updatedConfig = {
+    ...config,
+    version: 1,
+    auth: {
+      ...(config.auth || {}),
+      api_key: apiKey,
+      mode: 'api_key',
+      authenticated_at: new Date().toISOString()
+    },
+    settings: {
+      ...(config.settings || {}),
+      enabled: true,
+      apiUrl,
+      preferred_provider: config.settings?.preferred_provider || 'auto',
+      mode: config.settings?.mode || 'balanced',
+      localCacheEnabled: config.settings?.localCacheEnabled ?? true
+    }
+  };
+
+  if (!saveConfig(updatedConfig)) {
+    process.exit(1);
+  }
+
+  const routingEnabled = settingsManager.enablePlexorRouting(apiKey, {
+    useStaging: apiUrl.includes('staging')
+  });
+
+  if (!routingEnabled) {
+    console.error('Error: Plexor saved your key but could not activate Claude routing.');
+    console.error('Run /plexor-setup again after fixing ~/.claude/settings.json permissions.');
+    process.exit(1);
+  }
+
+  const currentSettings = settingsManager.load();
+  const previousAuthPreserved = Boolean(
+    currentSettings.env?.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY ||
+    currentSettings.env?.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN
+  );
+
+  const verifyResult = skipVerify
+    ? { ok: true, reason: '', stdout: EXPECTED_VERIFY_RESPONSE, stderr: '', code: 0 }
+    : runClaudeRouteVerification();
+
+  updateHealth(updatedConfig, {
+    gateway: getGatewayLabel(apiUrl),
+    previousAuthPreserved,
+    routingEnabled,
+    verifyResult
+  });
+
+  if (!saveConfig(updatedConfig)) {
+    process.exit(1);
+  }
+
+  printReceipt({
+    user,
+    gateway: getGatewayLabel(apiUrl),
+    previousAuthPreserved,
+    verifyResult
+  });
+
+  if (!verifyResult.ok) {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/commands/plexor-setup.md

@@ -1,172 +1,28 @@
+description: Guided first-run setup for Plexor with Claude Code (user)
 ---
-description: First-time setup wizard for Plexor with Claude Code (user)
----
-
-# Plexor Setup Wizard
-
-Guide users through first-time Plexor setup. **No manual environment variable configuration required!**
-
-The plugin automatically configures `~/.claude/settings.json` to route all Claude Code sessions through Plexor.
-
-## Steps
 
-**Step 1: Check if already configured**
+**RULE: Execute this workflow EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. DO NOT restart the workflow.**
 
-Use the Read tool to check if `~/.plexor/config.json` exists and has valid configuration.
-Also check `~/.claude/settings.json` for routing status.
+Plexor setup is the primary human setup flow.
 
-If configured, show:
-```
-Plexor Setup
-============
-Already configured!
-
-API URL: [apiUrl from config]
-Mode: [mode from config]
-Status: [Enabled/Disabled]
-Claude Routing: [Active/Inactive]
-
-Run /plexor-status to see your usage.
-Run /plexor-settings to modify configuration.
-Run /plexor-enabled off to disable routing.
-```
-
-**Step 2: Ask about Claude subscription**
-
-Use the AskUserQuestion tool:
-
-Question: "How do you pay for Claude usage?"
-Header: "Billing"
-Options:
-1. **Claude MAX subscription (Pro/Team/Enterprise)** - I have a subscription and want Plexor for optimization & tracking (you'll still need a Plexor API key)
-2. **Pay-per-use via Plexor** - I want Plexor to handle billing and route to the cheapest provider
-
-**Step 3A: Claude MAX User Setup**
-
-If user selected "Yes, I have Claude MAX":
-
-1. Ask for their Plexor API key:
-   "Please provide your Plexor API key (starts with 'plx_')."
-   "Get one at: https://plexor.dev/dashboard"
-   "Your MAX subscription will be used for Claude - the Plexor key is for tracking/optimization."
-
-2. Use the Write tool to create `~/.plexor/config.json`:
-```json
-{
-  "version": 1,
-  "auth": {
-    "api_key": "[user's Plexor key]",
-    "mode": "oauth_passthrough",
-    "authenticated_at": "[current ISO timestamp]"
-  },
-  "settings": {
-    "enabled": true,
-    "apiUrl": "https://staging.api.plexor.dev",
-    "mode": "balanced",
-    "localCacheEnabled": true
-  }
-}
-```
-
-3. Use the Write tool to update `~/.claude/settings.json` env block:
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://staging.api.plexor.dev/gateway/anthropic",
-    "ANTHROPIC_AUTH_TOKEN": "[user's Plexor key]"
-  }
-}
-```
-Note: Preserve any existing settings, just add/update the env block.
-
-4. Show the user:
-```
-Plexor Setup - Claude MAX User
-==============================
-Setup Complete! No manual configuration needed.
-
-What was configured:
-- ~/.plexor/config.json (Plexor plugin settings)
-- ~/.claude/settings.json (automatic Claude Code routing)
-
-How it works:
-- All Claude Code sessions now route through Plexor
-- Your MAX subscription OAuth token is passed through
-- You keep your MAX benefits ($0 cost, 20x rate limits)
-- Plexor optimizes prompts and tracks usage
-
-Commands:
-- /plexor-status    - See your usage stats
-- /plexor-enabled off - Temporarily disable Plexor
-- /plexor-enabled on  - Re-enable Plexor
-
-Changes take effect immediately in all Claude Code sessions!
-```
-
-**Step 3B: API Key User Setup**
-
-If user selected "No, I'll use a Plexor API key":
-
-1. Ask for their Plexor API key:
-   "Please provide your Plexor API key (starts with 'plx_')."
-   "Get one at: https://plexor.dev/dashboard"
-
-2. Once they provide the key, use the Write tool to create `~/.plexor/config.json`:
-```json
-{
-  "version": 1,
-  "auth": {
-    "api_key": "[user's API key]",
-    "mode": "api_key",
-    "authenticated_at": "[current ISO timestamp]"
-  },
-  "settings": {
-    "enabled": true,
-    "apiUrl": "https://staging.api.plexor.dev",
-    "preferred_provider": "auto",
-    "mode": "balanced",
-    "localCacheEnabled": true
-  }
-}
-```
-
-3. Use the Write tool to update `~/.claude/settings.json` env block:
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://staging.api.plexor.dev/gateway/anthropic",
-    "ANTHROPIC_AUTH_TOKEN": "[user's Plexor key]"
-  }
-}
-```
-Note: Preserve any existing settings, just add/update the env block.
+If `$ARGUMENTS` already contains a Plexor API key (`plx_...`), run:
 
-4. Show the user:
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-setup.js $ARGUMENTS
 ```
-Plexor Setup - API Key User
-===========================
-Setup Complete! No manual configuration needed.
 
-What was configured:
-- ~/.plexor/config.json (Plexor plugin settings)
-- ~/.claude/settings.json (automatic Claude Code routing)
+If the user did not provide a key yet, ask them:
 
-How it works:
-- All Claude Code sessions now route through Plexor
-- Plexor picks the best provider (can save up to 90%)
-- Your usage is tracked and optimized
+`Please paste your Plexor API key (starts with plx_). You can get one at https://plexor.dev/dashboard.`
 
-Commands:
-- /plexor-status    - See your usage and savings
-- /plexor-mode eco  - Maximize savings
-- /plexor-mode quality - Maximize quality
-- /plexor-enabled off - Temporarily disable Plexor
+After the user replies with the key, run:
 
-Changes take effect immediately in all Claude Code sessions!
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-setup.js <user_key>
 ```
 
-**IMPORTANT NOTES**:
-- The `~/.claude/settings.json` env block is the KEY mechanism that routes Claude Code through Plexor
-- ANTHROPIC_AUTH_TOKEN takes precedence over ANTHROPIC_API_KEY (use AUTH_TOKEN for the Plexor key)
-- Changes take effect immediately - no shell restart needed
-- After completing setup, STOP. Do not run additional commands.
+This command:
+- saves the Plexor key
+- routes Claude through the Plexor staging gateway
+- preserves prior direct Claude auth for restore on logout/uninstall
+- runs a deterministic Claude verification step