diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml index 1086709..8babead 100644 --- a/.github/workflows/code-quality.yml +++ b/.github/workflows/code-quality.yml @@ -28,7 +28,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: "20" + node-version: "22" cache: "pnpm" - name: Install dependencies diff --git a/.github/workflows/pake-cli.yaml b/.github/workflows/pake-cli.yaml index a9c61a3..f4fe9a3 100644 --- a/.github/workflows/pake-cli.yaml +++ b/.github/workflows/pake-cli.yaml @@ -67,7 +67,7 @@ jobs: - name: Install node uses: actions/setup-node@v4 with: - node-version: 18 + node-version: 22 - name: Install Rust for ubuntu-24.04 if: inputs.platform == 'ubuntu-24.04' diff --git a/CLAUDE.md b/CLAUDE.md index 639c445..d34afeb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,145 +2,164 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## Philosophy + +- **Incremental progress over big bangs**: Break complex tasks into manageable stages +- **Learn from existing code**: Understand patterns before implementing new features +- **Clear intent over clever code**: Prioritize readability and maintainability + ## Project Overview -Pake is a tool that turns any webpage into a desktop app with Rust, using Tauri framework. It's much lighter than Electron (~5M vs ~100M+) and provides better performance. The project consists of a CLI tool for packaging web apps and the core Tauri application framework. +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. -## Commands +**Core Architecture:** -### Development +- **CLI Tool** (`bin/`): TypeScript-based command interface +- **Tauri App** (`src-tauri/`): Rust desktop framework +- **Injection System**: Custom CSS/JS injection for webpages + +## Development Workflow + +### 1. Planning Phase + +Break complex work into 3-5 stages: + +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:** + +```bash +# Explore codebase structure +find src-tauri/src -name "*.rs" | head -10 +grep -r "window_config" src-tauri/src/ +``` + +**Development Commands:** ```bash # Install dependencies npm i -# Local development (right-click to open debug mode) +# Development with hot reload npm run dev -# CLI development with hot reload +# CLI development npm run cli:dev -# Build CLI tools -npm run cli:build -``` - -### Building - -```bash # Production build npm run build +``` -# Debug build +### 3. Testing and Validation + +**Key Testing Commands:** + +```bash +# Debug build for development npm run build:debug -# Mac universal build (Intel + M1) -npm run build:mac - -# Generate app configuration -npm run build:config +# Multi-platform testing +npm run build:mac # macOS universal build ``` -### CLI Usage +**Testing Checklist:** + +- [ ] Test on target platforms +- [ ] Verify injection system works +- [ ] Check system tray integration +- [ ] Validate window behavior + +## Core Components + +### CLI Tool (`bin/`) + +- `bin/cli.ts` - Main entry point +- `bin/builders/` - Platform-specific builders +- `bin/options/` - Configuration processing + +### Tauri Application (`src-tauri/`) + +- `src/lib.rs` - Application entry point +- `src/app/` - Core modules (window, tray, shortcuts) +- `src/inject/` - Web page injection logic + +### 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 -# Install CLI globally -npm install -g pake-cli +# 1. Check logs +npm run dev 2>&1 | grep -i error -# Package a webpage -pake https://example.com --name MyApp --width 1200 --height 800 +# 2. Verify dependencies +cargo check --manifest-path=src-tauri/Cargo.toml -# Also supports names with spaces (cross-platform compatible) -# pake https://translate.google.com --name "Google Translate" --hide-title-bar - -# Development with custom options -# Modify DEFAULT_DEV_PAKE_OPTIONS in bin/defaults.ts -npm run cli:dev +# 3. Test minimal reproduction +# Create simple test case isolating the issue ``` -### Analysis - -```bash -# Analyze binary size -npm run analyze -``` - -## Architecture - -### Core Components - -1. **CLI Tool** (`bin/`): Node.js/TypeScript-based command-line interface - -- `bin/cli.ts` - Main CLI entry point with Commander.js -- `bin/builders/` - Platform-specific builders (Mac, Windows, Linux) -- `bin/options/` - CLI option processing and validation -- `bin/utils/` - Utility functions for URL validation, platform detection - -2. **Tauri Application** (`src-tauri/`): Rust-based desktop app framework - -- `src-tauri/src/lib.rs` - Main application entry point -- `src-tauri/src/app/` - Application modules (config, window, system tray, shortcuts) -- `src-tauri/src/inject/` - JavaScript/CSS injection for web pages -- `src-tauri/pake.json` - Default app configuration - -3. **Build System**: Uses Rollup for CLI bundling and Tauri for app packaging - -### Configuration System - -- **pake.json**: Main configuration file defining window properties, user agents, system tray settings -- **tauri.conf.json**: Tauri-specific configuration -- Platform-specific configs: `tauri.macos.conf.json`, `tauri.windows.conf.json`, `tauri.linux.conf.json` - -### Key Features Implementation - -- **Window Management**: `src-tauri/src/app/window.rs` - Window creation, sizing, title bar handling -- **System Tray**: `src-tauri/src/app/setup.rs` - Cross-platform system tray integration -- **Window Close Behavior**: `src-tauri/src/lib.rs` - Configurable close behavior (hide vs exit) -- **Global Shortcuts**: Activation shortcuts for bringing app to foreground -- **Web Integration**: Custom user agents, proxy support, CSS/JS injection -- **Multi-platform**: Builds for macOS (Intel/M1), Windows, Linux (deb/appimage/rpm) - -## File Injection System - -The project supports injecting custom CSS/JS files into webpages: - -- Files in `src-tauri/src/inject/` contain the injection logic -- Use `--inject` CLI option to specify custom files -- Supports both local and remote injection files - -## Platform-Specific Notes +## Platform-Specific Development ### macOS -- Supports universal builds (Intel + M1) with `--multi-arch` -- Hide title bar option available with `--hide-title-bar` +- Universal builds: `--multi-arch` flag - Uses `.icns` icons +- Title bar customization available ### Windows -- Requires specific build tools and redistributables (see bin/README.md) +- Requires Visual Studio Build Tools - Uses `.ico` icons -- Supports installer language configuration +- MSI installer support ### Linux -- Multiple package formats: deb, appimage, rpm -- Requires specific system dependencies (libwebkit2gtk, etc.) +- Multiple formats: deb, AppImage, rpm +- Requires `libwebkit2gtk` and dependencies - Uses `.png` icons -## Development Workflow +## Quality Standards -1. **CLI Development**: Modify `bin/defaults.ts` for default options, use `npm run cli:dev` for hot reload -2. **Core App Development**: Work in `src-tauri/src/`, use `npm run dev` for Tauri development -3. **Testing**: Build with `--debug` flag for development tools and verbose logging -4. **Multi-platform**: Test builds on respective platforms or use GitHub Actions +**Code Standards:** -## Branch Management +- Prefer composition over inheritance +- Use explicit types over implicit +- Write self-documenting code +- Follow existing patterns consistently -- `dev` branch: Active development, feature PRs should target this branch -- `main` branch: Release branch for tags and publishing +**Commit Guidelines:** + +- Commit working code incrementally +- Use clear, descriptive messages +- Never bypass commit hooks +- Test before committing + +## Branch Strategy + +- `dev` - Active development, target for PRs +- `main` - Release branch for stable versions ## Prerequisites -- Node.js >=16.0.0 -- Rust >=1.78.0 (installed automatically by CLI if missing) -- Platform-specific build tools (see Tauri prerequisites) +- Node.js ≥22.0.0 (recommended LTS, older versions ≥16.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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ce431a..4ee7853 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,55 @@ graph LR - `main` is the release branch, we will make tag and publish version on this branch. - If it is a document modification, it can be submitted to this branch. +## Development Setup + +### Prerequisites + +- Node.js ≥22.0.0 (recommended LTS, older versions ≥16.0.0 may work) +- Rust ≥1.89.0 (recommended stable, older versions ≥1.78.0 may work) +- Platform-specific build tools: + - **macOS**: Xcode Command Line Tools (`xcode-select --install`) + - **Windows**: Visual Studio Build Tools with MSVC + - **Linux**: `build-essential`, `libwebkit2gtk`, system dependencies + +### Installation + +```bash +# Clone the repository +git clone https://github.com/tw93/Pake.git +cd Pake + +# Install dependencies +npm install + +# Start development +npm run dev +``` + +## Troubleshooting + +### macOS 26 Beta Compilation Issues + +If you're running macOS 26 Beta and encounter compilation errors related to `mac-notification-sys` or system frameworks (errors about `CoreFoundation`, `_Builtin_float` modules), create a `src-tauri/.cargo/config.toml` file with: + +```toml +[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" +``` + +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. + +### Common Build Issues + +- **Rust compilation errors**: Run `cargo clean` in `src-tauri/` directory +- **Node dependency issues**: Delete `node_modules` and run `npm install` +- **Permission errors on macOS**: Run `sudo xcode-select --reset` + ## More It is a good habit to create a feature request issue to discuss whether the feature is necessary before you implement it. However, it's unnecessary to create an issue to claim that you found a typo or improved the readability of documentation, just create a pull request. diff --git a/README.md b/README.md index 322b31e..6455821 100644 --- a/README.md +++ b/README.md @@ -179,7 +179,7 @@ If you are new to the command line, you can compile packages online with _GitHub ## Development -Prepare your environment before starting. Make sure you have Rust `>=1.63` and Node `>=16` (e.g., `16.18.1`) installed on your computer. For installation guidance, see [Tauri documentation](https://tauri.app/start/prerequisites/). +Prepare your environment before starting. Make sure you have Rust `>=1.89` and Node `>=22` (e.g., `22.11.0`) installed on your computer. *Note: Older versions (Rust ≥1.78, Node ≥16) may also work but latest stable versions are recommended.* For installation guidance, see [Tauri documentation](https://tauri.app/start/prerequisites/). If you are unfamiliar with these, it is better to try out the above tool to pack with one click. diff --git a/README_CN.md b/README_CN.md index bdff4fc..bbce4c3 100644 --- a/README_CN.md +++ b/README_CN.md @@ -178,7 +178,7 @@ pake https://weekly.tw93.fun --name Weekly --hide-title-bar ## 定制开发 -开始前请确保电脑已经安装了 Rust `>=1.63` 和 Node `>=16 如 16.18.1` 的环境，此外需参考 [Tauri 文档](https://tauri.app/start/prerequisites/) 快速配置好环境才可以开始使用，假如你太不懂，使用上面的命令行打包会更加合适。 +开始前请确保电脑已经安装了 Rust `>=1.89` 和 Node `>=22 如 22.11.0` 的环境，*注意：较旧的版本（Rust ≥1.78，Node ≥16）也可能可以工作，但推荐使用最新稳定版本。* 此外需参考 [Tauri 文档](https://tauri.app/start/prerequisites/) 快速配置好环境才可以开始使用，假如你太不懂，使用上面的命令行打包会更加合适。 ```sh # 安装依赖 diff --git a/README_JP.md b/README_JP.md index 533872e..b9a3c0c 100644 --- a/README_JP.md +++ b/README_JP.md @@ -178,7 +178,7 @@ pake https://weekly.tw93.fun --name Weekly --hide-title-bar ## 開発 -開始する前に、Rust `>=1.63` と Node `>=16` (例: `16.18.1`) がコンピュータにインストールされていることを確認してください。インストールガイドについては、[Tauri ドキュメント](https://tauri.app/start/prerequisites/)を参照してください。 +開始する前に、Rust `>=1.89` と Node `>=22` (例: `22.11.0`) がコンピュータにインストールされていることを確認してください。*注意：古いバージョン（Rust ≥1.78、Node ≥16）でも動作する可能性がありますが、最新の安定版の使用をお勧めします。* インストールガイドについては、[Tauri ドキュメント](https://tauri.app/start/prerequisites/)を参照してください。 これらに不慣れな場合は、上記のツールを使用してワンクリックでパッケージを作成することをお勧めします。 diff --git a/bin/README.md b/bin/README.md index 6483bfa..a961215 100644 --- a/bin/README.md +++ b/bin/README.md @@ -2,7 +2,7 @@ ## Installation -Ensure that your Node.js version is 18.0 or higher (e.g., 18.20.2). Avoid using `sudo` for the installation. If you encounter permission issues with npm, refer to [How to fix npm throwing error without sudo](https://stackoverflow.com/questions/16151018/how-to-fix-npm-throwing-error-without-sudo). +Ensure that your Node.js version is 22.0 or higher (e.g., 22.11.0). *Note: Older versions ≥16.0.0 may also work.* Avoid using `sudo` for the installation. If you encounter permission issues with npm, refer to [How to fix npm throwing error without sudo](https://stackoverflow.com/questions/16151018/how-to-fix-npm-throwing-error-without-sudo). ```bash npm install pake-cli -g diff --git a/bin/README_CN.md b/bin/README_CN.md index daea9a8..be06920 100644 --- a/bin/README_CN.md +++ b/bin/README_CN.md @@ -2,7 +2,7 @@ ## 安装 -请确保您的 Node.js 版本为 18 或更高版本（例如 18.7）。请避免使用 `sudo` 进行安装。如果 npm 报告权限问题，请参考 [如何在不使用 sudo 的情况下修复 npm 报错](https://stackoverflow.com/questions/16151018/how-to-fix-npm-throwing-error-without-sudo)。 +请确保您的 Node.js 版本为 22 或更高版本（例如 22.11.0）。*注意：较旧的版本 ≥16.0.0 也可能可以工作。* 请避免使用 `sudo` 进行安装。如果 npm 报告权限问题，请参考 [如何在不使用 sudo 的情况下修复 npm 报错](https://stackoverflow.com/questions/16151018/how-to-fix-npm-throwing-error-without-sudo)。 ```bash npm install pake-cli -g