claude-pro-minmax 1.0.2 → 1.2.0

package/install.sh

@@ -1,146 +1,280 @@
 #!/bin/bash
 # Claude Pro MinMax - Installation Script
 set -e
-echo "🚀 Installing Claude Pro MinMax (CPMM)"
 
-# Check for dependencies
-if ! command -v jq &> /dev/null; then
-    echo "⚠️ Warning: jq is not installed. Some features (JSON output, cost optimization) may not work."
-    echo "  Install with: brew install jq"
+# Error handler: print failure line and exit message
+_on_error() { echo ""; echo "❌ Installation failed at line $1. Check output above."; }
+trap '_on_error $LINENO' ERR
+
+# Guard unsupported invocations (`curl | bash`, process substitution)
+if [[ -z "${BASH_SOURCE[0]}" || "${BASH_SOURCE[0]}" == "bash" ]]; then
+  echo "❌ This script cannot be run via 'curl | bash'."
+  echo "   Please clone the repository first:"
+  echo "   git clone https://github.com/move-hoon/claude-pro-minmax.git && cd claude-pro-minmax && bash install.sh"
+  exit 1
+fi
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+if [ ! -f "$SCRIPT_DIR/.claude/CLAUDE.md" ] || [ ! -f "$SCRIPT_DIR/package.json" ]; then
+  echo "❌ This script must be run from a cloned CPMM repository directory."
+  echo "   Please run:"
+  echo "   git clone https://github.com/move-hoon/claude-pro-minmax.git && cd claude-pro-minmax && bash install.sh"
+  exit 1
 fi
 
-# Check for mgrep (Critical for output reduction)
-if ! command -v mgrep &> /dev/null; then
-    echo "⚠️ Warning: mgrep is not installed. This is critical for 50% output reduction."
-    echo "  Install with: npm install -g @mixedbread/mgrep && mgrep install-claude-code"
+# Marker-based detection for Install vs Update
+CPMM_MARKER="$HOME/.claude/.cpmm-version"
+IS_UPDATE=false
+if [ -f "$CPMM_MARKER" ]; then IS_UPDATE=true; fi
+
+# Legacy CPMM detection (marker was introduced after early releases)
+LEGACY_CPMM=false
+if [ "$IS_UPDATE" = false ] && [ -d "$HOME/.claude" ]; then
+  if [ -f "$HOME/.claude/CLAUDE.md" ] &&
+     [ -f "$HOME/.claude/settings.json" ] &&
+     [ -f "$HOME/.claude/commands/do.md" ] &&
+     [ -f "$HOME/.claude/commands/do-opus.md" ]; then
+    LEGACY_CPMM=true
+  fi
 fi
 
-# Backup and Clean existing ~/.claude (True Overwrite)
-if [ -d ~/.claude ]; then
-    BACKUP_DIR=~/.claude-backup-$(date +"%Y%m%d-%H%M%S")
-    echo "📦 Backing up and clearing existing ~/.claude → $BACKUP_DIR"
-    mv ~/.claude "$BACKUP_DIR"
-    echo "  Clean overwrite enabled. Old settings preserved in backup."
+# Header message: show Install vs Update mode
+if [ "$IS_UPDATE" = true ]; then
+  echo "🔄 Updating Claude Pro MinMax (CPMM)"
+  INSTALLED_VERSION=$(head -1 "$CPMM_MARKER" 2>/dev/null || echo "unknown")
+  echo "   Current version: $INSTALLED_VERSION"
+else
+  echo "🚀 Installing Claude Pro MinMax (CPMM)"
 fi
 
-# Create fresh directories
-mkdir -p ~/.claude/{agents,commands,rules,skills/cli-wrappers/references,contexts,sessions,scripts}
+# Backup existing ~/.claude (Fresh Install Only)
+if [ "$IS_UPDATE" = false ] && [ -d "$HOME/.claude" ]; then
+  if [ -d "$HOME/.claude.pre-cpmm" ]; then
+    echo "⚠️  ~/.claude.pre-cpmm already exists, skipping backup."
+    echo "   User data preserved. Reinstalling CPMM files in-place..."
+    # No rm -rf — user data (learned/, plans/, projects/, sessions/) is safe
+  elif [ "$LEGACY_CPMM" = true ]; then
+    echo "⚠️  Detected legacy CPMM installation without marker, skipping backup."
+    echo "   User data preserved. Reinstalling CPMM files in-place..."
+    # No rm -rf — user data (learned/, plans/, projects/, sessions/) is safe
+  else
+    mv "$HOME/.claude" "$HOME/.claude.pre-cpmm"
+    echo "📦 Backed up ~/.claude → ~/.claude.pre-cpmm"
+  fi
+fi
 
-# Copy configurations
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-cp "$SCRIPT_DIR/.claude/CLAUDE.md" ~/.claude/
-cp "$SCRIPT_DIR/.claude/settings.json" ~/.claude/
-# Copy settings.local.json from example template (users customize after install)
-if [ -f "$SCRIPT_DIR/.claude/settings.local.example.json" ]; then
-    cp "$SCRIPT_DIR/.claude/settings.local.example.json" ~/.claude/settings.local.json
-fi
-cp "$SCRIPT_DIR/.claude/agents/"*.md ~/.claude/agents/
-cp "$SCRIPT_DIR/.claude/commands/"*.md ~/.claude/commands/
+# Create required directories (user-owned dirs are never rm-rf'd)
+# NITPICK #11: only create dirs not managed by rm-rf below
+mkdir -p "$HOME/.claude/rules" "$HOME/.claude/skills/learned"
+mkdir -p "$HOME/.claude/"{sessions,plans,projects}
+
+# Copy core configurations
+cp "$SCRIPT_DIR/.claude/CLAUDE.md" "$HOME/.claude/"
+cp "$SCRIPT_DIR/.claude/settings.json" "$HOME/.claude/"
+# Copy settings.local.json from example template (only if not already present)
+if [ ! -f "$HOME/.claude/settings.local.json" ] && [ -f "$SCRIPT_DIR/.claude/settings.local.example.json" ]; then
+    cp "$SCRIPT_DIR/.claude/settings.local.example.json" "$HOME/.claude/settings.local.json"
+fi
+
+shopt -s nullglob
+
+# agents/, commands/, contexts/ — fully CPMM managed: rm-rf to remove stale files
+# EDGE CASE #6: these dirs are CPMM-only; user files should not be placed here
+rm -rf "$HOME/.claude/agents" && mkdir -p "$HOME/.claude/agents"
+_agent_files=("$SCRIPT_DIR/.claude/agents/"*.md)
+if [ ${#_agent_files[@]} -gt 0 ]; then
+  for agent in "${_agent_files[@]}"; do
+    filename=$(basename "$agent")
+    [[ "$filename" == README* ]] && continue
+    [[ "$filename" == USER-MANUAL* ]] && continue
+    cp "$agent" "$HOME/.claude/agents/"
+  done
+fi
+
+rm -rf "$HOME/.claude/commands" && mkdir -p "$HOME/.claude/commands"
+_cmd_files=("$SCRIPT_DIR/.claude/commands/"*.md)
+if [ ${#_cmd_files[@]} -gt 0 ]; then
+  for cmd in "${_cmd_files[@]}"; do
+    filename=$(basename "$cmd")
+    [[ "$filename" == README* ]] && continue
+    [[ "$filename" == USER-MANUAL* ]] && continue
+    cp "$cmd" "$HOME/.claude/commands/"
+  done
+fi
+
+rm -rf "$HOME/.claude/contexts" && mkdir -p "$HOME/.claude/contexts"
+_ctx_files=("$SCRIPT_DIR/.claude/contexts/"*.md)
+if [ ${#_ctx_files[@]} -gt 0 ]; then
+  for ctx in "${_ctx_files[@]}"; do
+    filename=$(basename "$ctx")
+    [[ "$filename" == README* ]] && continue
+    [[ "$filename" == USER-MANUAL* ]] && continue
+    cp "$ctx" "$HOME/.claude/contexts/"
+  done
+fi
+
+# rules/ — language.md is user-owned: remove stale CPMM rules, preserve language.md
+# BUG #2: rules loop is now inside nullglob block to prevent literal glob expansion
+find "$HOME/.claude/rules/" -name "*.md" ! -name "language.md" -delete 2>/dev/null || true
 for rule in "$SCRIPT_DIR/.claude/rules/"*.md; do
+  [[ -f "$rule" ]] || continue  # nullglob guard (no-op with nullglob, safety net)
   filename=$(basename "$rule")
   [ "$filename" = "language.md" ] && continue
-  cp "$rule" ~/.claude/rules/
+  [[ "$filename" == README* ]] && continue
+  [[ "$filename" == USER-MANUAL* ]] && continue
+  cp "$rule" "$HOME/.claude/rules/"
 done
-cp -R "$SCRIPT_DIR/.claude/skills/"* ~/.claude/skills/
-cp "$SCRIPT_DIR/.claude/contexts/"*.md ~/.claude/contexts/
-# sessions/ dir created above; example files stay in repo only (not installed)
-cp -R "$SCRIPT_DIR/scripts/"* ~/.claude/scripts/
 
-# Clean up documentation files from ~/.claude to prevent parsing errors
-# (The 'find' command below removes all README/USER-MANUAL files from the installed directory)
-find ~/.claude -name "README*" -delete
-find ~/.claude -name "USER-MANUAL*" -delete
+shopt -u nullglob
+
+# cli-wrappers/ and scripts/ — fully CPMM managed: rm-rf to remove stale files
+if [ -d "$SCRIPT_DIR/.claude/skills/cli-wrappers" ]; then
+  rm -rf "$HOME/.claude/skills/cli-wrappers"
+  cp -R "$SCRIPT_DIR/.claude/skills/cli-wrappers" "$HOME/.claude/skills/"
+fi
+# sessions/ dir created above; example files stay in repo only (not installed)
+if [ -d "$SCRIPT_DIR/scripts" ]; then
+  rm -rf "$HOME/.claude/scripts"
+  cp -R "$SCRIPT_DIR/scripts" "$HOME/.claude/scripts"
+fi
 
-# Copy MCP Configuration (User Scope - ~/.claude.json)
+# Copy MCP Configuration
+MCP_CONFIG_PRESENT=false
 if [ -f "$SCRIPT_DIR/.claude.json" ]; then
-    if [ -f ~/.claude.json ]; then
-        echo "📦 Backing up existing ~/.claude.json → ~/.claude.json.bak"
-        cp ~/.claude.json ~/.claude.json.bak
+  MCP_CONFIG_PRESENT=true
+
+  if [ "$IS_UPDATE" = false ]; then
+    if [ -f "$HOME/.claude.json" ]; then
+      echo "📦 Backing up existing ~/.claude.json → ~/.claude.json.bak"
+      cp "$HOME/.claude.json" "$HOME/.claude.json.bak"
     fi
-    cp "$SCRIPT_DIR/.claude.json" ~/.claude.json
+    cp "$SCRIPT_DIR/.claude.json" "$HOME/.claude.json"
     echo "✅ Installed .claude.json to ~/.claude.json (User Scope)"
+  elif [ ! -f "$HOME/.claude.json" ]; then
+    cp "$SCRIPT_DIR/.claude.json" "$HOME/.claude.json"
+    echo "✅ Restored missing ~/.claude.json from repository template"
+  fi
 
-    # Create .mcp.json symlink (Force recreate to ensure it's a link)
-    if [ -e ~/.mcp.json ] || [ -L ~/.mcp.json ]; then
-        rm ~/.mcp.json
-    fi
-    ln -s ~/.claude.json ~/.mcp.json
-    echo "✅ Created .mcp.json → .claude.json symlink (Ensured Link)"
-    # Interactive Perplexity Setup (Read from /dev/tty for curl support)
-    if [ -t 0 ] || [ -c /dev/tty ]; then
-        if ! command -v jq &> /dev/null; then
-            echo "⚠️  Skipping Perplexity setup (jq not installed). Install jq and re-run to configure."
-        else
-            echo ""
-            echo "🔍 Perplexity API Setup (Recommended for /dplan)"
-            echo -n "   Enter your API Key (Press Enter to skip): "
-            read -rs PERPLEXITY_KEY < /dev/tty || PERPLEXITY_KEY=""
-            echo "" # Newline for silent read
-
-            if [ -n "$PERPLEXITY_KEY" ]; then
-                # Enable Perplexity (Rename key and inject API Key)
-                jq --arg key "$PERPLEXITY_KEY" \
-                   '.mcpServers.perplexity = .mcpServers._perplexity_disabled_by_default |
-                    .mcpServers.perplexity.env.PERPLEXITY_API_KEY = $key |
-                    del(.mcpServers._perplexity_disabled_by_default)' \
-                   ~/.claude.json > ~/.claude.json.tmp && mv ~/.claude.json.tmp ~/.claude.json
-                echo "✅ Perplexity API Key configured!"
-            else
-                # Skip: Completely remove the disabled block to keep config clean
-                echo "⚠️  Skipping Perplexity setup. Disabling feature..."
-                jq 'del(.mcpServers._perplexity_disabled_by_default)' ~/.claude.json > ~/.claude.json.tmp && mv ~/.claude.json.tmp ~/.claude.json
-                echo "   (Feature removed from config. Add manually to functionality if needed)"
-            fi
-        fi
+  # Fresh install: enforce symlink. Update: restore only when missing (do not overwrite existing file/link).
+  if [ "$IS_UPDATE" = false ]; then
+    if [ ! -L "$HOME/.mcp.json" ] || [ "$(readlink "$HOME/.mcp.json" 2>/dev/null)" != "$HOME/.claude.json" ]; then
+      ln -sf "$HOME/.claude.json" "$HOME/.mcp.json"
+      echo "✅ Ensured .mcp.json → .claude.json symlink"
     fi
+  elif [ ! -e "$HOME/.mcp.json" ] && [ ! -L "$HOME/.mcp.json" ]; then
+    ln -s "$HOME/.claude.json" "$HOME/.mcp.json"
+    echo "✅ Restored missing .mcp.json → .claude.json symlink"
+  fi
 fi
 
-# Language Selection (Interactive)
-if [ -t 0 ] || [ -c /dev/tty ]; then
-  echo ""
-  echo "🌍 Output Language"
-  echo "   1) English (default)"
-  echo "   2) 한국어 (Korean)"
-  echo "   3) 日本語 (Japanese)"
-  echo "   4) 中文 (Chinese)"
-  echo -n "   Select [1-4]: "
-  read -r LANG_CHOICE < /dev/tty || LANG_CHOICE="1"
-
-  case $LANG_CHOICE in
-    2)
-      cat > ~/.claude/rules/language.md <<'LANGEOF'
+# Perplexity setup + language selection (Fresh Install Only)
+if [ "$IS_UPDATE" = false ]; then
+  # EDGE CASE #8: check stdin is truly a terminal (not /dev/tty char-device trick)
+  # [ -c /dev/tty ] is always true on Linux/macOS — use [ -t 0 ] alone
+  if [ "$MCP_CONFIG_PRESENT" = true ] && [ -t 0 ]; then
+    if ! command -v jq &> /dev/null; then
+      echo "⚠️  Skipping Perplexity setup (jq not installed). Install jq and re-run to configure."
+    else
+      echo ""
+      echo "🔍 Perplexity API Setup (Recommended for /dplan)"
+      echo -n "   Enter your API Key (Press Enter to skip): "
+      read -rs PERPLEXITY_KEY < /dev/tty || PERPLEXITY_KEY=""
+      echo "" # Newline for silent read
+
+      if [ -n "$PERPLEXITY_KEY" ]; then
+        # Enable Perplexity (use env var to avoid key exposure in process list)
+        # EDGE CASE #10: write to tmp then atomically rename; trap cleans up on failure
+        PERPLEXITY_API_KEY="$PERPLEXITY_KEY" jq \
+          '.mcpServers.perplexity = .mcpServers._perplexity_disabled_by_default |
+           .mcpServers.perplexity.env.PERPLEXITY_API_KEY = env.PERPLEXITY_API_KEY |
+           del(.mcpServers._perplexity_disabled_by_default)' \
+          "$HOME/.claude.json" > "$HOME/.claude.json.tmp"
+        mv "$HOME/.claude.json.tmp" "$HOME/.claude.json"
+        # BUG #5: unset both variables
+        unset PERPLEXITY_KEY PERPLEXITY_API_KEY
+        echo "✅ Perplexity API Key configured!"
+      else
+        # Skip: Completely remove the disabled block to keep config clean
+        echo "⚠️  Skipping Perplexity setup. Disabling feature..."
+        jq 'del(.mcpServers._perplexity_disabled_by_default)' \
+          "$HOME/.claude.json" > "$HOME/.claude.json.tmp"
+        mv "$HOME/.claude.json.tmp" "$HOME/.claude.json"
+        echo "   (Feature removed from config. Add manually to functionality if needed)"
+      fi
+    fi
+  fi
+
+  # Language Selection (Interactive - Fresh Install Only)
+  if [ -t 0 ]; then
+    echo ""
+    echo "🌍 Output Language"
+    echo "   1) English (default)"
+    echo "   2) 한국어 (Korean)"
+    echo "   3) 日本語 (Japanese)"
+    echo "   4) 中文 (Chinese)"
+    echo -n "   Select [1-4]: "
+    read -r LANG_CHOICE < /dev/tty || LANG_CHOICE="1"
+
+    case $LANG_CHOICE in
+      2)
+        cat > "$HOME/.claude/rules/language.md" <<'LANGEOF'
 # Language Policy
 Respond in Korean (한국어). Code, commands, technical terms in English.
 LANGEOF
-      echo "✅ Output language: Korean"
-      ;;
-    3)
-      cat > ~/.claude/rules/language.md <<'LANGEOF'
+        echo "✅ Output language: Korean"
+        ;;
+      3)
+        cat > "$HOME/.claude/rules/language.md" <<'LANGEOF'
 # Language Policy
 Respond in Japanese (日本語). Code, commands, technical terms in English.
 LANGEOF
-      echo "✅ Output language: Japanese"
-      ;;
-    4)
-      cat > ~/.claude/rules/language.md <<'LANGEOF'
+        echo "✅ Output language: Japanese"
+        ;;
+      4)
+        cat > "$HOME/.claude/rules/language.md" <<'LANGEOF'
 # Language Policy
 Respond in Chinese (中文). Code, commands, technical terms in English.
 LANGEOF
-      echo "✅ Output language: Chinese"
-      ;;
-    *)
-      # English: no language.md needed (Claude defaults to English)
-      rm -f ~/.claude/rules/language.md
-      echo "✅ Output language: English"
-      ;;
-  esac
+        echo "✅ Output language: Chinese"
+        ;;
+      *)
+        # English: no language.md needed (Claude defaults to English)
+        rm -f "$HOME/.claude/rules/language.md"
+        echo "✅ Output language: English"
+        ;;
+    esac
+  fi
 fi
 
+# EDGE CASE #9: guard find against missing dir (scripts/ may not exist on minimal installs)
 # Make scripts executable (Recursive)
-find ~/.claude/scripts -name "*.sh" -exec chmod +x {} \;
-find ~/.claude/scripts -name "*.js" -exec chmod +x {} \;
+if [ -d "$HOME/.claude/scripts" ]; then
+  find "$HOME/.claude/scripts" -name "*.sh" -exec chmod +x {} \;
+  find "$HOME/.claude/scripts" -name "*.js" -exec chmod +x {} \;
+fi
+
+# Write installation marker
+# SEC #4: avoid node -p with interpolated $SCRIPT_DIR (injection risk); use node -e with argument
+PROJECT_VERSION=$(node -e "try{process.stdout.write(require(process.argv[1]).version)}catch(e){process.exit(1)}" \
+  "$SCRIPT_DIR/package.json" 2>/dev/null || \
+  grep '"version"' "$SCRIPT_DIR/package.json" 2>/dev/null | head -1 | sed 's/.*"version": *"\([^"]*\)".*/\1/' || \
+  echo "unknown")
+printf '%s\ninstalled:%s\n' "$PROJECT_VERSION" "$(date)" > "$CPMM_MARKER"
 
-echo "✅ Installation complete!"
+# Old backup cleanup hint
+OLD_BACKUPS=$(find "$HOME" -maxdepth 1 -name ".claude-backup-*" -type d 2>/dev/null | wc -l | tr -d ' ')
+if [ "$OLD_BACKUPS" -gt 0 ]; then
+  echo ""
+  echo "💡 Old backups detected: $OLD_BACKUPS directory(ies) named ~/.claude-backup-*"
+  echo "   Review and remove: rm -rf ~/.claude-backup-*"
+fi
+
+# Final success message showing mode
+echo ""
+if [ "$IS_UPDATE" = true ]; then
+  echo "✅ Update complete!"
+else
+  echo "✅ Installation complete!"
+fi
 echo ""
 echo "Quick Start:"
 echo "  claude"
@@ -148,6 +282,10 @@ echo "  > /plan Design a new feature"
 echo "  > /dplan Analyze complex architecture"
 echo "  > /do Implement the login page"
 echo ""
+echo "Dependency Check:"
+echo "  cpmm setup       # install missing deps (jq, mgrep, tmux)"
+echo "  cpmm doctor      # check status only"
+echo ""
 echo "Language:"
 echo "  To change language: edit ~/.claude/rules/language.md"
 echo "  To use English: rm ~/.claude/rules/language.md"

package/lib/cli.js

@@ -0,0 +1,244 @@
+"use strict";
+
+const { execSync, spawnSync } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+const pkg = require("../package.json");
+
+const DEPS = [
+  {
+    key: "claude",
+    command: "claude",
+    required: false,
+    installKind: "skip",
+    description: "Claude Code CLI (assumed pre-installed)",
+  },
+  {
+    key: "jq",
+    command: "jq",
+    required: true,
+    installKind: "system",
+    systemPackage: "jq",
+    description: "JSON processor for CLI workflows",
+  },
+  {
+    key: "mgrep",
+    command: "mgrep",
+    required: true,
+    installKind: "npm",
+    npmPackage: "@mixedbread/mgrep",
+    postInstall: ["mgrep", "install-claude-code"],
+    description: "Fast code search tool",
+  },
+  {
+    key: "tmux",
+    command: "tmux",
+    required: true,
+    installKind: "system",
+    systemPackage: "tmux",
+    description: "Terminal multiplexer for background agents",
+  },
+];
+
+function commandExists(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectSystemInstaller() {
+  if (commandExists("brew")) return { ok: true, installer: "brew", sudo: false };
+  if (commandExists("apt-get")) return { ok: true, installer: "apt-get", sudo: true };
+  if (commandExists("dnf")) return { ok: true, installer: "dnf", sudo: true };
+  if (commandExists("pacman")) return { ok: true, installer: "pacman", sudo: true };
+  if (commandExists("apk")) return { ok: true, installer: "apk", sudo: true };
+  return { ok: false };
+}
+
+function buildInstallCmd(installer, pkg, sudo) {
+  const prefix = sudo ? "sudo " : "";
+  switch (installer) {
+    case "brew": return `brew install ${pkg}`;
+    case "apt-get": return `${prefix}apt-get install -y ${pkg}`;
+    case "dnf": return `${prefix}dnf install -y ${pkg}`;
+    case "pacman": return `${prefix}pacman -S --noconfirm ${pkg}`;
+    case "apk": return `${prefix}apk add ${pkg}`;
+    default: return null;
+  }
+}
+
+function runCmd(cmd, label) {
+  console.log(`  $ ${cmd}`);
+  const result = spawnSync("sh", ["-c", cmd], { stdio: "inherit" });
+  if (result.status !== 0) {
+    console.error(`  FAIL: ${label} (exit ${result.status})`);
+    return false;
+  }
+  return true;
+}
+
+function installDep(dep) {
+  if (dep.installKind === "skip") return true;
+
+  if (dep.installKind === "npm") {
+    if (!commandExists("npm")) {
+      console.error(`  npm not found. Install Node.js first, then: npm i -g ${dep.npmPackage}`);
+      return false;
+    }
+    if (!runCmd(`npm install -g ${dep.npmPackage}`, dep.key)) return false;
+    if (dep.postInstall) {
+      return runCmd(dep.postInstall.join(" "), `${dep.key} post-install`);
+    }
+    return true;
+  }
+
+  if (dep.installKind === "system") {
+    const sys = detectSystemInstaller();
+    if (!sys.ok) {
+      const hint = process.platform === "darwin"
+        ? `\n  Install Homebrew first: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
+        : "";
+      console.error(`  No supported package manager found. Install ${dep.systemPackage} manually.${hint}`);
+      return false;
+    }
+    const cmd = buildInstallCmd(sys.installer, dep.systemPackage, sys.sudo);
+    return runCmd(cmd, dep.key);
+  }
+
+  return false;
+}
+
+function checkDeps() {
+  return DEPS.map((dep) => ({
+    ...dep,
+    installed: commandExists(dep.command),
+  }));
+}
+
+function printStatus(results) {
+  console.log("");
+  for (const r of results) {
+    const icon = r.installed ? "OK" : (r.required ? "MISSING" : "SKIP");
+    const tag = r.required ? "[required]" : "[optional]";
+    console.log(`  ${icon} ${r.key.padEnd(8)} ${tag} ${r.description}`);
+  }
+  console.log("");
+}
+
+function runSetup() {
+  console.log(`CPMM v${pkg.version} - Setup`);
+
+  const results = checkDeps();
+  const missing = results.filter((r) => r.required && !r.installed);
+
+  if (missing.length > 0) {
+    console.log(`\nInstalling ${missing.length} missing dependency(ies)...\n`);
+
+    for (const dep of missing) {
+      console.log(`[${dep.key}] ${dep.description}`);
+      if (!installDep(dep)) {
+        // continue to install others
+      } else {
+        console.log(`  Done.\n`);
+      }
+    }
+
+    const after = checkDeps();
+    printStatus(after);
+
+    const stillMissing = after.filter((r) => r.required && !r.installed);
+    if (stillMissing.length > 0) {
+      console.error(`${stillMissing.length} required dep(s) still missing.`);
+      return 1;
+    }
+  } else {
+    console.log("\nAll dependencies installed.");
+    printStatus(results);
+  }
+
+  // Run install.sh for config files, language, and Perplexity setup
+  if (!runInstallScript()) {
+    return 1;
+  }
+
+  console.log("Setup complete.");
+  return 0;
+}
+
+function runInstallScript() {
+  const scriptPath = path.resolve(__dirname, "..", "install.sh");
+  if (!fs.existsSync(scriptPath)) {
+    return true;
+  }
+  console.log("Configuring CPMM...\n");
+  const result = spawnSync("bash", [scriptPath], {
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+  if (result.status !== 0) {
+    console.error("Config setup had issues. Run 'bash install.sh' manually if needed.");
+    return false;
+  }
+  return true;
+}
+
+function runDoctor() {
+  console.log(`CPMM v${pkg.version} - Doctor`);
+
+  const results = checkDeps();
+  printStatus(results);
+
+  const missing = results.filter((r) => r.required && !r.installed);
+  if (missing.length > 0) {
+    console.log(`Fix: cpmm setup`);
+    return 1;
+  }
+
+  console.log("All checks passed.");
+  return 0;
+}
+
+function printHelp() {
+  console.log(`CPMM v${pkg.version}
+
+Usage:
+  cpmm setup      Install deps + configure CPMM (language, Perplexity)
+  cpmm doctor     Check dependency status
+  cpmm --help     Show this help
+  cpmm --version  Show version
+`);
+}
+
+function runCli(argv) {
+  const cmd = argv[0] || "setup";
+
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+    printHelp();
+    return 0;
+  }
+
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    console.log(pkg.version);
+    return 0;
+  }
+
+  if (process.platform === "win32") {
+    console.error("CPMM requires macOS/Linux. Windows users: use WSL.");
+    return 1;
+  }
+
+  switch (cmd) {
+    case "setup":
+      return runSetup();
+    case "doctor":
+      return runDoctor();
+    default:
+      console.error(`Unknown command: ${cmd}\nRun 'cpmm --help' for usage.`);
+      return 2;
+  }
+}
+
+module.exports = { runCli };