feat: add platform provider abstraction for cross-platform support (#80)

* feat: add platform provider abstraction for cross-platform support

Introduce a platform provider pattern to centralize all platform-specific
logic (Windows, macOS, Linux) in one place. This fixes Windows shell
command execution issues and improves maintainability.

Changes:
- Add platform provider interface and implementations for Windows, macOS, Linux
- Refactor cli.ts to use platform provider for CLI installation
- Refactor terminal/env.ts to use platform provider for shell detection
- Refactor claude/env.ts to use platform provider for environment building
- Refactor claude-token.ts to use platform provider for PATH extension
- Fix path separator issues (use path.basename instead of split('/'))

The platform provider handles:
- Shell configuration and detection
- PATH building with common tool locations
- Environment variable setup
- CLI installation/uninstallation
- Locale detection

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: address PR review feedback

Based on PR #80 review by @serafimcloud:

1. Windows PATH limitation (Critical):
   - Remove `setx PATH` which has 1024 char limit and can truncate PATH
   - CLI install dir is already in buildExtendedPath() for app usage
   - Return pathHint for users who want terminal access

2. Variable shadowing (Critical):
   - Rename `path` to `filePath` in chats.ts to avoid shadowing
     the imported `path` module

3. Electron coupling (Medium):
   - Remove unused `app` import from windows.ts
   - Remove unused `exec`, `promisify`, `lstatSync` imports

4. execCommand consistency (Low):
   - Add documentation explaining execCommand is for simple commands
   - Complex shell commands (osascript, pipes) may use exec directly

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(windows): install CLI to ~/.local/bin instead of %LOCALAPPDATA%

- Install to ~/.local/bin which is already in buildExtendedPath()
- Avoids needing to modify system PATH or prompt user
- App can find CLI automatically via extended PATH
- Users with ~/.local/bin in their PATH can use it from terminal too

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: ChrisPei

src/main/lib/claude-token.ts

@@ -2,6 +2,7 @@ import { execSync, spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { buildExtendedPath, isWindows } from "./platform";
 
 interface ClaudeCredentials {
   claudeAiOauth?: {
@@ -242,23 +243,14 @@ export function isTokenExpired(expiresAt?: number): boolean {
 
 /**
  * Build extended PATH with common installation locations
- * This is necessary because when running from Finder/Dock, the PATH
- * may not include directories where claude CLI is installed
+ * This is necessary because when running from Finder/Dock (macOS) or
+ * Start Menu (Windows), the PATH may not include directories where
+ * claude CLI is installed
+ *
+ * Delegates to platform provider for cross-platform support.
  */
 function getExtendedPath(): string {
-  const home = homedir();
-  const extendedPaths = [
-    '/opt/homebrew/bin',
-    '/usr/local/bin',
-    `${home}/.local/bin`,
-    `${home}/.bun/bin`,
-    `${home}/.cargo/bin`,
-    '/opt/local/bin',
-    `${home}/.nvm/versions/node/*/bin`, // Common Node.js installations
-  ].filter(Boolean);
-
-  const currentPath = process.env.PATH || '';
-  return [...extendedPaths, ...currentPath.split(':')].join(':');
+  return buildExtendedPath(process.env.PATH);
 }
 
 /**
@@ -268,7 +260,7 @@ function getExtendedPath(): string {
 export function isClaudeCliInstalled(): boolean {
   try {
     // Use 'where' on Windows, 'which' on Unix-like systems
-    const command = process.platform === 'win32' ? 'where claude' : 'which claude';
+    const command = isWindows() ? 'where claude' : 'which claude';
     const fullPath = getExtendedPath();
 
     execSync(command, {

src/main/lib/claude/env.ts

@@ -4,6 +4,13 @@ import path from "node:path"
 import os from "node:os"
 import { app } from "electron"
 import { stripVTControlCharacters } from "node:util"
+import {
+  platform,
+  buildExtendedPath,
+  getDefaultShell,
+  isWindows,
+  isMacOS,
+} from "../platform"
 
 // Cache the shell environment
 let cachedShellEnv: Record<string, string> | null = null
@@ -37,29 +44,33 @@ export function getBundledClaudeBinaryPath(): string {
   }
 
   const isDev = !app.isPackaged
-  const platform = process.platform
+  const currentPlatform = process.platform
   const arch = process.arch
 
   // Only log verbose info on first call
   if (process.env.DEBUG_CLAUDE_BINARY) {
     console.log("[claude-binary] ========== BUNDLED BINARY PATH ==========")
     console.log("[claude-binary] isDev:", isDev)
-    console.log("[claude-binary] platform:", platform)
+    console.log("[claude-binary] platform:", currentPlatform)
     console.log("[claude-binary] arch:", arch)
     console.log("[claude-binary] appPath:", app.getAppPath())
   }
 
   // In dev: apps/desktop/resources/bin/{platform}-{arch}/claude
   // In production: {resourcesPath}/bin/claude
   const resourcesPath = isDev
-    ? path.join(app.getAppPath(), "resources/bin", `${platform}-${arch}`)
+    ? path.join(
+        app.getAppPath(),
+        "resources/bin",
+        `${currentPlatform}-${arch}`
+      )
     : path.join(process.resourcesPath, "bin")
 
   if (process.env.DEBUG_CLAUDE_BINARY) {
     console.log("[claude-binary] resourcesPath:", resourcesPath)
   }
 
-  const binaryName = platform === "win32" ? "claude.exe" : "claude"
+  const binaryName = currentPlatform === "win32" ? "claude.exe" : "claude"
   const binaryPath = path.join(resourcesPath, binaryName)
 
   if (process.env.DEBUG_CLAUDE_BINARY) {
@@ -71,8 +82,13 @@ export function getBundledClaudeBinaryPath(): string {
 
   // Always log if binary doesn't exist (critical error)
   if (!exists) {
-    console.error("[claude-binary] WARNING: Binary not found at path:", binaryPath)
-    console.error("[claude-binary] Run 'bun run claude:download' to download it")
+    console.error(
+      "[claude-binary] WARNING: Binary not found at path:",
+      binaryPath
+    )
+    console.error(
+      "[claude-binary] Run 'bun run claude:download' to download it"
+    )
   } else if (process.env.DEBUG_CLAUDE_BINARY) {
     const stats = fs.statSync(binaryPath)
     const sizeMB = (stats.size / 1024 / 1024).toFixed(1)
@@ -112,16 +128,49 @@ function parseEnvOutput(output: string): Record<string, string> {
 }
 
 /**
- * Load full shell environment using interactive login shell.
- * This captures PATH, HOME, and all shell profile configurations.
+ * Strip sensitive keys from environment
+ */
+function stripSensitiveKeys(env: Record<string, string>): void {
+  for (const key of STRIPPED_ENV_KEYS) {
+    if (key in env) {
+      console.log(`[claude-env] Stripped ${key} from shell environment`)
+      delete env[key]
+    }
+  }
+}
+
+/**
+ * Load full shell environment.
+ * - Windows: Derives PATH from process.env + common install locations (no shell spawn)
+ * - macOS/Linux: Spawns interactive login shell to capture PATH from shell profiles
  * Results are cached for the lifetime of the process.
  */
 export function getClaudeShellEnvironment(): Record<string, string> {
   if (cachedShellEnv !== null) {
     return { ...cachedShellEnv }
   }
 
-  const shell = process.env.SHELL || "/bin/zsh"
+  // Windows: use platform provider to build environment
+  if (isWindows()) {
+    console.log(
+      "[claude-env] Windows detected, deriving PATH without shell invocation"
+    )
+
+    // Use platform provider to build environment
+    const env = platform.buildEnvironment()
+
+    // Strip sensitive keys
+    stripSensitiveKeys(env)
+
+    console.log(
+      `[claude-env] Built Windows environment with ${Object.keys(env).length} vars`
+    )
+    cachedShellEnv = env
+    return { ...env }
+  }
+
+  // macOS/Linux: spawn interactive login shell to get full environment
+  const shell = getDefaultShell()
   const command = `echo -n "${DELIMITER}"; env; echo -n "${DELIMITER}"; exit`
 
   try {
@@ -139,46 +188,23 @@ export function getClaudeShellEnvironment(): Record<string, string> {
     })
 
     const env = parseEnvOutput(output)
-
-    // Strip keys that could interfere with Claude's auth resolution
-    for (const key of STRIPPED_ENV_KEYS) {
-      if (key in env) {
-        console.log(`[claude-env] Stripped ${key} from shell environment`)
-        delete env[key]
-      }
-    }
+    stripSensitiveKeys(env)
 
     console.log(
-      `[claude-env] Loaded ${Object.keys(env).length} environment variables from shell`,
+      `[claude-env] Loaded ${Object.keys(env).length} environment variables from shell`
     )
     cachedShellEnv = env
     return { ...env }
   } catch (error) {
     console.error("[claude-env] Failed to load shell environment:", error)
 
-    // Fallback: return minimal required env
-    const home = os.homedir()
-    const fallbackPath = [
-      `${home}/.local/bin`,
-      "/opt/homebrew/bin",
-      "/usr/local/bin",
-      "/usr/bin",
-      "/bin",
-      "/usr/sbin",
-      "/sbin",
-    ].join(":")
-
-    const fallback: Record<string, string> = {
-      HOME: home,
-      USER: os.userInfo().username,
-      PATH: fallbackPath,
-      SHELL: process.env.SHELL || "/bin/zsh",
-      TERM: "xterm-256color",
-    }
+    // Fallback: use platform provider
+    const env = platform.buildEnvironment()
+    stripSensitiveKeys(env)
 
-    console.log("[claude-env] Using fallback environment")
-    cachedShellEnv = fallback
-    return { ...fallback }
+    console.log("[claude-env] Using fallback environment from platform provider")
+    cachedShellEnv = env
+    return { ...env }
   }
 }
 
@@ -212,11 +238,17 @@ export function buildClaudeEnv(options?: {
     env.PATH = shellPath
   }
 
-  // 3. Ensure critical vars are present
-  if (!env.HOME) env.HOME = os.homedir()
-  if (!env.USER) env.USER = os.userInfo().username
-  if (!env.SHELL) env.SHELL = "/bin/zsh"
+  // 3. Ensure critical vars are present using platform provider
+  const platformEnv = platform.buildEnvironment()
+  if (!env.HOME) env.HOME = platformEnv.HOME
+  if (!env.USER) env.USER = platformEnv.USER
   if (!env.TERM) env.TERM = "xterm-256color"
+  if (!env.SHELL) env.SHELL = getDefaultShell()
+
+  // Windows-specific: ensure USERPROFILE is set
+  if (isWindows() && !env.USERPROFILE) {
+    env.USERPROFILE = os.homedir()
+  }
 
   // 4. Add custom overrides
   if (options?.ghToken) {
@@ -250,17 +282,17 @@ export function clearClaudeEnvCache(): void {
  */
 export function logClaudeEnv(
   env: Record<string, string>,
-  prefix: string = "",
+  prefix: string = ""
 ): void {
   console.log(`${prefix}[claude-env] HOME: ${env.HOME}`)
   console.log(`${prefix}[claude-env] USER: ${env.USER}`)
   console.log(
-    `${prefix}[claude-env] PATH includes homebrew: ${env.PATH?.includes("/opt/homebrew")}`,
+    `${prefix}[claude-env] PATH includes homebrew: ${env.PATH?.includes("/opt/homebrew")}`
   )
   console.log(
-    `${prefix}[claude-env] PATH includes /usr/local/bin: ${env.PATH?.includes("/usr/local/bin")}`,
+    `${prefix}[claude-env] PATH includes /usr/local/bin: ${env.PATH?.includes("/usr/local/bin")}`
   )
   console.log(
-    `${prefix}[claude-env] ANTHROPIC_AUTH_TOKEN: ${env.ANTHROPIC_AUTH_TOKEN ? "set" : "not set"}`,
+    `${prefix}[claude-env] ANTHROPIC_AUTH_TOKEN: ${env.ANTHROPIC_AUTH_TOKEN ? "set" : "not set"}`
   )
 }

src/main/lib/cli.ts

@@ -8,7 +8,8 @@
 
 import { app } from "electron"
 import { join } from "path"
-import { existsSync, lstatSync, readlinkSync } from "fs"
+import { existsSync, lstatSync } from "fs"
+import { platform } from "./platform"
 
 // Launch directory from CLI (e.g., `1code /path/to/project`)
 let launchDirectory: string | null = null
@@ -51,88 +52,42 @@ export function parseLaunchDirectory(): void {
   }
 }
 
-// CLI command installation paths
-const CLI_INSTALL_PATH = "/usr/local/bin/1code"
-
+/**
+ * Get the CLI source path (where the CLI script is bundled)
+ */
 function getCliSourcePath(): string {
+  const cliName = platform.getCliConfig().scriptName
   if (app.isPackaged) {
-    return join(process.resourcesPath, "cli", "1code")
+    return join(process.resourcesPath, "cli", cliName)
   }
-  return join(__dirname, "..", "..", "resources", "cli", "1code")
+  return join(__dirname, "..", "..", "resources", "cli", cliName)
 }
 
 /**
  * Check if the CLI command is installed
  */
 export function isCliInstalled(): boolean {
-  try {
-    if (!existsSync(CLI_INSTALL_PATH)) return false
-    const stat = lstatSync(CLI_INSTALL_PATH)
-    if (!stat.isSymbolicLink()) return false
-    const target = readlinkSync(CLI_INSTALL_PATH)
-    return target === getCliSourcePath()
-  } catch {
-    return false
-  }
+  return platform.isCliInstalled(getCliSourcePath())
 }
 
 /**
- * Install the CLI command to /usr/local/bin/1code
- * Requires admin privileges on macOS
+ * Install the CLI command
+ * Platform-specific behavior is handled by the platform provider
  */
-export async function installCli(): Promise<{ success: boolean; error?: string }> {
-  const { exec } = await import("child_process")
-  const { promisify } = await import("util")
-  const execAsync = promisify(exec)
-
-  const sourcePath = getCliSourcePath()
-
-  if (!existsSync(sourcePath)) {
-    return { success: false, error: "CLI script not found in app bundle" }
-  }
-
-  try {
-    // Remove existing if present
-    if (existsSync(CLI_INSTALL_PATH)) {
-      await execAsync(
-        `osascript -e 'do shell script "rm -f ${CLI_INSTALL_PATH}" with administrator privileges'`,
-      )
-    }
-
-    // Create symlink with admin privileges
-    await execAsync(
-      `osascript -e 'do shell script "ln -s \\"${sourcePath}\\" ${CLI_INSTALL_PATH}" with administrator privileges'`,
-    )
-
-    console.log("[CLI] Installed 1code command to", CLI_INSTALL_PATH)
-    return { success: true }
-  } catch (error: unknown) {
-    const errorMessage = error instanceof Error ? error.message : "Installation failed"
-    console.error("[CLI] Failed to install:", error)
-    return { success: false, error: errorMessage }
-  }
+export async function installCli(): Promise<{
+  success: boolean
+  error?: string
+}> {
+  return platform.installCli(getCliSourcePath())
 }
 
 /**
- * Uninstall the CLI command from /usr/local/bin/1code
- * Requires admin privileges on macOS
+ * Uninstall the CLI command
+ * Platform-specific behavior is handled by the platform provider
  */
-export async function uninstallCli(): Promise<{ success: boolean; error?: string }> {
-  const { exec } = await import("child_process")
-  const { promisify } = await import("util")
-  const execAsync = promisify(exec)
-
-  try {
-    if (existsSync(CLI_INSTALL_PATH)) {
-      await execAsync(
-        `osascript -e 'do shell script "rm -f ${CLI_INSTALL_PATH}" with administrator privileges'`,
-      )
-    }
-    console.log("[CLI] Uninstalled 1code command")
-    return { success: true }
-  } catch (error: unknown) {
-    const errorMessage = error instanceof Error ? error.message : "Uninstallation failed"
-    console.error("[CLI] Failed to uninstall:", error)
-    return { success: false, error: errorMessage }
-  }
+export async function uninstallCli(): Promise<{
+  success: boolean
+  error?: string
+}> {
+  return platform.uninstallCli()
 }