Merge branch 'dev'

Author: tw93

CLAUDE.md

@@ -9,6 +9,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Clear intent over clever code**: Prioritize readability and maintainability
 - **Simple over complex**: Keep all implementations simple and straightforward - prioritize solving problems and ease of maintenance over complex solutions
 
+## Claude Code Eight Honors and Eight Shames
+
+- **Shame** in guessing APIs, **Honor** in careful research
+- **Shame** in vague execution, **Honor** in seeking confirmation
+- **Shame** in assuming business logic, **Honor** in human verification
+- **Shame** in creating interfaces, **Honor** in reusing existing ones
+- **Shame** in skipping validation, **Honor** in proactive testing
+- **Shame** in breaking architecture, **Honor** in following specifications
+- **Shame** in pretending to understand, **Honor** in honest ignorance
+- **Shame** in blind modification, **Honor** in careful refactoring
+
 ## Project Overview
 
 Pake transforms any webpage into a lightweight desktop app using Rust and Tauri. It's significantly lighter than Electron (~5M vs ~100M+) with better performance.
@@ -21,146 +32,43 @@ Pake transforms any webpage into a lightweight desktop app using Rust and Tauri.
 
 ## Development Workflow
 
-### 1. Planning Phase
-
-Break complex work into 3-5 stages:
+1. **Understand**: Study existing patterns in codebase
+2. **Plan**: Break complex work into 3-5 stages
+3. **Test**: Write tests first (when applicable)
+4. **Implement**: Minimal working solution
+5. **Refactor**: Optimize and clean up
 
-1. Understand existing patterns in codebase
-2. Plan implementation approach
-3. Write tests first (when applicable)
-4. Implement minimal working solution
-5. Refactor and optimize
-
-### 2. Implementation Flow
-
-**Understanding First:**
+**Key Commands:**
 
 ```bash
-# Explore codebase structure
-find src-tauri/src -name "*.rs" | head -10
-grep -r "window_config" src-tauri/src/
+pnpm test           # Run comprehensive test suite
+pnpm run cli:build  # Build CLI for testing
+pnpm run dev        # Development with hot reload
 ```
 
-**Development Commands:**
-
-```bash
-# Install dependencies
-pnpm i
-
-# Development with hot reload (for testing app functionality)
-pnpm run dev
-
-# CLI development
-pnpm run cli:dev
-
-# Production build
-pnpm run build
-```
-
-### 3. Testing and Validation
-
-**Key Testing Commands:**
-
-```bash
-# Run comprehensive test suite (unit + integration + builder)
-pnpm test
-
-# Build CLI for testing
-pnpm run cli:build
-
-# Debug build for development
-pnpm run build:debug
-
-# Multi-platform testing
-pnpm run build:mac  # macOS universal build
-```
-
-**Testing Checklist:**
-
-- [ ] Run `npm test` for comprehensive validation (35 tests)
-- [ ] Test on target platforms
-- [ ] Verify injection system works
-- [ ] Check system tray integration
-- [ ] Validate window behavior
-- [ ] Test with weekly.tw93.fun URL
-- [ ] Verify remote icon functionality (https://cdn.tw93.fun/pake/weekly.icns)
+**Testing:**
 
-**Testing Notes:**
-
-- Do NOT use `PAKE_NO_CONFIG_OVERWRITE=1` - this environment variable is not implemented
+- Always run `pnpm test` before committing
 - For CLI testing: `node dist/cli.js https://example.com --name TestApp --debug`
-- **For app functionality testing**: Use `pnpm run dev` to start development server with hot reload. This allows real-time testing of injected JavaScript changes without rebuilding the entire app.
-- The dev server automatically reloads when you modify files in `src-tauri/src/inject/` directory
+- For app functionality testing: Use `pnpm run dev` for hot reload
 
 ## Core Components
 
-### CLI Tool (`bin/`)
-
-- `bin/cli.ts` - Main entry point with Commander.js
-- `bin/builders/` - Platform-specific builders (Mac, Windows, Linux)
-- `bin/options/` - CLI option processing and validation
-- `bin/helpers/merge.ts` - Configuration merging (name setting at line 55)
-
-### Tauri Application (`src-tauri/`)
-
-- `src/lib.rs` - Application entry point
-- `src/app/` - Core modules (window, tray, shortcuts)
-- `src/inject/` - Web page injection logic
+- **CLI Tool** (`bin/`): Main entry point, builders, options processing
+- **Tauri App** (`src-tauri/`): Rust application, window/tray management, injection logic
+- **Config Files**: `pake.json`, `tauri.conf.json`, platform-specific configs
 
 ## Documentation Guidelines
 
-- **Main README**: Only include common, frequently-used parameters to avoid clutter
-- **CLI Documentation** (`docs/cli-usage.md`): Include ALL parameters with detailed usage examples
-- **Rare/Advanced Parameters**: Should have full documentation in CLI docs but minimal/no mention in main README
-- **Examples of rare parameters**: `--title`, `--incognito`, `--system-tray-icon`, etc.
-
-### Key Configuration Files
-
-- `pake.json` - App configuration
-- `tauri.conf.json` - Tauri settings
-- Platform configs: `tauri.{macos,windows,linux}.conf.json`
-
-## Problem-Solving Approach
-
-**When stuck:**
-
-1. **Limit attempts to 3** before stopping to reassess
-2. **Document what doesn't work** and why
-3. **Research alternative approaches** in similar projects
-4. **Question assumptions** - is there a simpler way?
-
-**Example debugging flow:**
-
-```bash
-# 1. Check logs
-pnpm run dev 2>&1 | grep -i error
-
-# 2. Verify dependencies
-cargo check --manifest-path=src-tauri/Cargo.toml
-
-# 3. Test minimal reproduction
-# Create simple test case isolating the issue
-```
-
-## Platform-Specific Development
-
-### macOS
-
-- Universal builds: `--multi-arch` flag
-- Uses `.icns` icons
-- Title bar customization available
-
-### Windows
-
-- Requires Visual Studio Build Tools
-- Uses `.ico` icons
-- MSI installer support
+- **Main README**: Common parameters only
+- **CLI Documentation** (`docs/cli-usage.md`): ALL parameters with examples
+- **Rare parameters**: Full docs in CLI usage, minimal in main README
 
-### Linux
+## Platform Specifics
 
-- Multiple formats: deb, AppImage, rpm
-- Requires `libwebkit2gtk` and dependencies
-- Uses `.png` icons
+- **macOS**: `.icns` icons, universal builds with `--multi-arch`
+- **Windows**: `.ico` icons, requires Visual Studio Build Tools
+- **Linux**: `.png` icons, multiple formats (deb, AppImage, rpm)
 
 ## Quality Standards
 
@@ -170,15 +78,15 @@ cargo check --manifest-path=src-tauri/Cargo.toml
 - Use explicit types over implicit
 - Write self-documenting code
 - Follow existing patterns consistently
+- **NO Chinese comments** - Use English only
+- **NO unnecessary comments** - For simple, obvious code, let the code speak for itself
 
-**Git and Commit Guidelines:**
+**Git Guidelines:**
 
-- **NEVER commit code automatically** - User handles all git operations
-- **NEVER generate commit messages** - User writes their own commit messages
-- **NEVER run npm publish automatically** - Always remind user to run it manually
-- **NEVER execute git tag or push operations** - User handles all tag creation and GitHub pushes
-- Only make code changes, user decides when and how to commit
-- Test before user commits
+- **NEVER commit automatically** - User handles all git operations
+- **NEVER generate commit messages** - User writes their own
+- Only make code changes, user decides when/how to commit
+- Always test before user commits
 
 ## Branch Strategy
 
@@ -187,6 +95,6 @@ cargo check --manifest-path=src-tauri/Cargo.toml
 
 ## Prerequisites
 
-- Node.js ≥22.0.0 (recommended LTS, older versions ≥18.0.0 may work)
-- Rust ≥1.89.0 (recommended stable, older versions ≥1.78.0 may work)
-- Platform build tools (see CONTRIBUTING.md for details)
+- Node.js ≥22.0.0 (≥18.0.0 may work)
+- Rust ≥1.89.0 (≥1.78.0 may work)
+- Platform build tools (see CONTRIBUTING.md)

CONTRIBUTING.md

@@ -70,17 +70,18 @@ If you're running macOS 26 Beta and encounter compilation errors related to `mac
 [env]
 # Fix for macOS 26 Beta compatibility issues
 # Forces use of compatible SDK when building on macOS 26 Beta
-MACOSX_DEPLOYMENT_TARGET = "15.5"
-SDKROOT = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.5.sdk"
+MACOSX_DEPLOYMENT_TARGET = "15.0"
+SDKROOT = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"
 ```
 
 This file is already in `.gitignore` and should not be committed to the repository.
 
-**Root Cause**: macOS 26 Beta uses newer system frameworks that aren't yet supported by the current Xcode SDK (15.5). This configuration forces the build to use the compatible SDK version.
+**Root Cause**: macOS 26 Beta uses newer system frameworks that aren't yet fully compatible with Tauri's dependencies. This configuration uses the universal SDK symlink which automatically points to your system's available SDK version.
 
 ### Common Build Issues
 
 - **Rust compilation errors**: Run `cargo clean` in `src-tauri/` directory
+- **`cargo` command not found after installation**: Pake CLI now reloads the Rust environment automatically, but if the issue persists reopen your terminal or run `source ~/.cargo/env` (macOS/Linux) / `call %USERPROFILE%\.cargo\env` (Windows) before retrying
 - **Node dependency issues**: Delete `node_modules` and run `pnpm install`
 - **Permission errors on macOS**: Run `sudo xcode-select --reset`
 

README.md

@@ -29,6 +29,7 @@
 - **Beginners**: Download ready-made [Popular Packages](#popular-packages) or use [Online Building](docs/github-actions-usage.md) with no environment setup required
 - **Developers**: Install [CLI Tool](docs/cli-usage.md) for one-command packaging of any website with customizable icons, window settings, and more
 - **Advanced Users**: Clone the project locally for [Custom Development](#development), or check [Advanced Usage](docs/advanced-usage.md) for style customization and feature enhancement
+- **Troubleshooting**: Check [FAQ](docs/faq.md) for common issues and solutions
 
 ## Popular Packages
 

README_CN.md

@@ -29,6 +29,7 @@
 - **新手用户**：直接下载现成的 [常用包](#常用包下载)，或通过 [在线构建](docs/github-actions-usage_CN.md) 无需环境配置即可打包
 - **开发者**：安装 [CLI 工具](docs/cli-usage_CN.md) 后一行命令打包任意网站，支持自定义图标、窗口等参数
 - **高级用户**：本地克隆项目进行 [定制开发](#定制开发)，或查看 [高级用法](docs/advanced-usage_CN.md) 实现样式定制、功能增强
+- **遇到问题**：查看 [常见问题](docs/faq_CN.md) 获取常见问题的解决方案
 
 ## 常用包下载
 

bin/builders/BaseBuilder.ts

@@ -4,9 +4,10 @@ import chalk from 'chalk';
 import prompts from 'prompts';
 
 import { PakeAppOptions } from '@/types';
-import { checkRustInstalled, installRust } from '@/helpers/rust';
+import { checkRustInstalled, ensureRustEnv, installRust } from '@/helpers/rust';
 import { mergeConfig } from '@/helpers/merge';
 import tauriConfig from '@/helpers/tauriConfig';
+import { generateIdentifierSafeName } from '@/utils/name';
 import { npmDirectory } from '@/utils/dir';
 import { getSpinner } from '@/utils/info';
 import { shellExec } from '@/utils/shell';
@@ -76,6 +77,8 @@ export default abstract class BaseBuilder {
       logger.warn('✼ See more in https://tauri.app/start/prerequisites/.');
     }
 
+    ensureRustEnv();
+
     if (!checkRustInstalled()) {
       const res = await prompts({
         type: 'confirm',
@@ -117,15 +120,17 @@ export default abstract class BaseBuilder {
       const projectCnConf = path.join(tauriSrcPath, 'rust_proxy.toml');
       await fsExtra.copy(projectCnConf, projectConf);
       await shellExec(
-        `cd "${npmDirectory}" && ${packageManager} install${registryOption}${peerDepsOption} --silent`,
+        `cd "${npmDirectory}" && ${packageManager} install${registryOption}${peerDepsOption}`,
         timeout,
         buildEnv,
+        this.options.debug,
       );
     } else {
       await shellExec(
-        `cd "${npmDirectory}" && ${packageManager} install${peerDepsOption} --silent`,
+        `cd "${npmDirectory}" && ${packageManager} install${peerDepsOption}`,
         timeout,
         buildEnv,
+        this.options.debug,
       );
     }
     spinner.succeed(chalk.green('Package installed!'));
@@ -159,12 +164,16 @@ export default abstract class BaseBuilder {
     // Show static message to keep the status visible
     logger.warn('✸ Building app...');
 
-    const buildEnv = this.getBuildEnvironment();
+    const buildEnv = {
+      ...this.getBuildEnvironment(),
+      ...(process.env.NO_STRIP && { NO_STRIP: process.env.NO_STRIP }),
+    };
 
     await shellExec(
       `cd "${npmDirectory}" && ${this.getBuildCommand(packageManager)}`,
       this.getBuildTimeout(),
       buildEnv,
+      this.options.debug,
     );
 
     // Copy app
@@ -409,7 +418,7 @@ export default abstract class BaseBuilder {
 
     // Linux uses the unique binary name we set in merge.ts
     if (process.platform === 'linux') {
-      return `pake-${appName.toLowerCase()}${extension}`;
+      return `pake-${generateIdentifierSafeName(appName)}${extension}`;
     }
 
     // Windows and macOS use 'pake' as binary name

bin/cli.ts

@@ -24,8 +24,7 @@ ${green('|_|   \\__,_|_|\\_\\___|  can turn any webpage into a desktop app with
 program
   .addHelpText('beforeAll', logo)
   .usage(`[url] [options]`)
-  .showHelpAfterError()
-  .helpOption(false);
+  .showHelpAfterError();
 
 program
   .argument('[url]', 'The web URL you want to package', validateUrlInput)
@@ -127,10 +126,16 @@ program
   )
   .addOption(
     new Option(
-      '--hide-on-close',
+      '--hide-on-close [boolean]',
       'Hide window on close instead of exiting (default: true for macOS, false for others)',
     )
       .default(DEFAULT.hideOnClose)
+      .argParser((value) => {
+        if (value === undefined) return true; // --hide-on-close without value
+        if (value === 'true') return true;
+        if (value === 'false') return false;
+        throw new Error('--hide-on-close must be true or false');
+      })
       .hideHelp(),
   )
   .addOption(new Option('--title <string>', 'Window title').hideHelp())
@@ -154,6 +159,11 @@ program
       .default(DEFAULT.keepBinary)
       .hideHelp(),
   )
+  .addOption(
+    new Option('--multi-instance', 'Allow multiple app instances')
+      .default(DEFAULT.multiInstance)
+      .hideHelp(),
+  )
   .addOption(
     new Option('--installer-language <string>', 'Installer language')
       .default(DEFAULT.installerLanguage)
@@ -163,11 +173,13 @@ program
   .configureHelp({
     sortSubcommands: true,
     optionTerm: (option) => {
-      if (option.flags === '-v, --version') return '';
+      if (option.flags === '-v, --version' || option.flags === '-h, --help')
+        return '';
       return option.flags;
     },
     optionDescription: (option) => {
-      if (option.flags === '-v, --version') return '';
+      if (option.flags === '-v, --version' || option.flags === '-h, --help')
+        return '';
       return option.description;
     },
   })

bin/defaults.ts

@@ -27,6 +27,7 @@ export const DEFAULT_PAKE_OPTIONS: PakeCliOptions = {
   wasm: false,
   enableDragDrop: false,
   keepBinary: false,
+  multiInstance: false,
 };
 
 // Just for cli development