feat: add development environment launchers

.agents/skills/development-environment/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: development-environment
+description: Start ACECode's Web, Desktop, or TUI development environment safely, reusing a compatible build from the current Git worktree when possible.
+---
+
+# Development Environment
+
+Use this skill when the user asks to run, start, or open the ACECode development environment.
+
+## Select the target
+
+If the request does not name a target, ask exactly which development surface to run:
+
+- **Web** — starts the daemon-backed browser UI.
+- **Desktop** — starts the native desktop shell against the local development frontend.
+- **TUI** — starts the terminal interface in a new terminal window.
+
+Do not start anything until the user selects one target. If they name a target, proceed without repeating the question.
+
+## Use the shared launcher
+
+Run the target-specific repository launcher instead of implementing launch logic in the conversation:
+
+```powershell
+.\scripts\dev_web.bat
+.\scripts\dev_desktop.bat
+.\scripts\dev_tui.bat
+```
+
+On macOS or Linux:
+
+```bash
+./scripts/dev_web.sh
+./scripts/dev_desktop.sh
+./scripts/dev_tui.sh
+```
+
+Pass `--build-dir <path>` only when the user explicitly supplies a candidate build directory. Do not copy `acecode`, `acecode-desktop`, DLLs, or other build artifacts between worktrees.
+
+## Build reuse and rebuild policy
+
+启动器只复用当前工作树内的 CMake 构建，检查源码路径、平台、架构、目标产物及 Desktop 配置。多配置构建会编译并启动同一配置。其他已登记工作树仅可提供经验证的前端产物和编译缓存，不提供本工作树实际运行的程序。
+
+Every launch incrementally builds the verified target, so source changes are incorporated even when the configured build is reused. Web and Desktop also refresh frontend assets when their inputs are newer than `web/dist`.
+
+If no compatible configured build exists, the launcher reports the platform CMake preset and asks for confirmation before configuration. Preserve that safety boundary:
+
+- Windows target-specific batch launchers automatically approve this first configuration so they work when double-clicked.
+- For the shared Python launcher and POSIX target-specific launchers, state that configuration is needed, name the preset, and ask the user for explicit confirmation before adding `--yes`.
+- If the user declines, do not configure, compile, or start a surface.
+
+The shared launcher calls the existing Python surface launchers: `scripts/dev_web.py` for Web and `scripts/dev_desktop.py` for Desktop. Web uses a worktree-isolated runtime directory and opens its resulting local URL; Desktop opens its application window; TUI opens a new terminal window.
+
+Windows 的 MSVC 构建会按 x64 或 ARM64 初始化 VS 环境；有效 MinGW 构建不要求 VS。Web 重建前发现既存 PID 记录时会明确失败并给出检查或停止命令；不要通过删 PID 文件、宽泛终止进程等方式绕过此检查。显式 `--run-dir` 只检查所指定的目录。
+
+## Report outcome
+
+After a successful command, report the selected target and whether the build was reused or compiled. For Web, include the URL printed by the launcher. If startup fails, provide the launcher error and do not claim the environment is running.

CMakePresets.json

@@ -64,6 +64,22 @@
         "VCPKG_TARGET_TRIPLET": "x64-windows-static"
       }
     },
+    {
+      "name": "windows-arm64-release",
+      "displayName": "Windows ARM64 Release",
+      "inherits": "release-base",
+      "cacheVariables": {
+        "VCPKG_TARGET_TRIPLET": "arm64-windows-static"
+      }
+    },
+    {
+      "name": "windows-arm64-desktop-release",
+      "displayName": "Windows ARM64 Desktop Release",
+      "inherits": "desktop-release-base",
+      "cacheVariables": {
+        "VCPKG_TARGET_TRIPLET": "arm64-windows-static"
+      }
+    },
     {
       "name": "windows-x64-winlibs-debug",
       "displayName": "Windows x64 WinLibs Debug",

openspec/changes/add-development-environment-launcher/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-19

openspec/changes/add-development-environment-launcher/design.md

@@ -0,0 +1,94 @@
+# Design
+
+## Context
+
+See `proposal.md` for motivation and `specs/development-environment-launcher/spec.md` for behavioral requirements. The repository already has Python-backed Web and Desktop launchers with thin platform wrappers. Web currently accepts an explicit build directory and runtime directory, while Desktop accepts an explicit build directory and rebuilds `web/dist` when its inputs are newer. TUI has no comparable wrapper.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Provide one shared Python orchestration entry point and thin Windows/POSIX wrappers.
+- Reuse existing Web and Desktop launch scripts rather than duplicating their surface-specific behavior.
+- Reliably identify compatible builds from Git-registered worktrees before proposing a local build.
+- Keep development daemons isolated per worktree and make start outcomes visible.
+
+**Non-Goals:**
+
+- Change production daemon, Desktop, TUI, or CMake behavior.
+- Copy build artifacts, DLLs, or resources between worktrees.
+- Search arbitrary user directories outside worktrees registered by the current Git repository.
+- Automatically compile without interactive confirmation.
+
+## Decisions
+
+### Use a Python orchestration layer with thin platform wrappers
+
+A new `scripts/dev_environment.py` will parse the selected target and coordinate discovery, confirmation, incremental building, and launch. Dedicated target wrappers will select Python and a fixed target: `dev_web.bat` / `dev_web.sh`, `dev_desktop.bat` / `dev_desktop.sh`, and `dev_tui.bat` / `dev_tui.sh`. Python matches the existing launcher implementation and is portable across Windows, macOS, and Linux.
+
+Alternatives considered:
+
+- Separate shell implementations would duplicate platform logic and Git/CMake parsing.
+- Extending `dev_web.py` or `dev_desktop.py` would couple target-independent discovery to a single surface.
+
+### Discover builds only from Git worktree registrations
+
+The orchestration layer will inspect only the current worktree's candidate build directories and read `CMakeCache.txt` to confirm that each build was configured from the current source directory. It validates platform, generator architecture clues, selected target configuration, and executable presence. Registered peer worktrees are used only for safe compiler-cache and frontend-artifact acceleration; their CMake/Ninja directories are never built or launched for the current worktree.
+
+Alternatives considered:
+
+- Scan sibling or home directories: this can find unrelated repositories and is slower.
+- Compare only executable timestamps: timestamps do not prove the source revision or Desktop capability.
+
+### Delegate surface-specific startup
+
+The shared launcher performs the target's incremental CMake build after it validates or configures a build directory. For Web and Desktop, it then invokes the existing Python surface launchers directly, forwarding the validated `--build-dir`; this avoids recursing through target wrappers. The Desktop surface launcher continues to refresh frontend assets, and the shared launcher adds the equivalent freshness check before Web launch. Web receives a deterministic runtime directory below the current worktree's ignored development state. TUI is started from the validated `acecode` binary in a new terminal window using platform-specific process invocation.
+
+Alternatives considered:
+
+- Reimplement Web and Desktop startup in the new tool: would create two sources of truth for Web assets and Desktop development-mode behavior.
+- Run TUI in the current terminal: conflicts with the agreed ability to continue launcher work after opening TUI.
+
+### Auto-configure missing builds from Windows direct entry points
+
+Double-clicked batch files do not provide a reliable input stream for the shared launcher's confirmation prompt. Each Windows target entry point will therefore append `--yes` when it calls `dev_environment.py`, approving only the missing-build configuration path. The shared Python launcher remains conservative for callers that invoke it directly, and POSIX wrappers retain their interactive confirmation behavior.
+
+### Initialize the Windows C++ toolchain in batch entry points
+
+Windows 包装脚本先选择 Python，公共启动器识别候选构建后才决定是否需要 MSVC。MinGW 构建直接使用已有编译器；MSVC 路径通过共享 `dev_windows_env.bat` 查询匹配 x64 或 ARM64 的 VS 组件并初始化环境。Python 只在子进程内捕获环境变量，再传递给后续编译，不输出环境内容。帮助、列表和 dry-run 不触发工具链初始化。Windows ARM64 对应的两个默认 configure presets 与 x64 使用相同的基础配置。
+
+Alternatives considered:
+
+- Require callers to use a Developer Command Prompt: contradicts direct double-click and normal-shell entry point behavior.
+- Duplicate Visual Studio path discovery in all three wrappers: risks inconsistent architecture and error handling.
+
+### Require interactive confirmation only for a new configuration
+
+When discovery cannot produce a compatible result, the tool calculates the native CMake preset for the selected target and prints configure/build commands. It asks a yes/no question only when stdin is interactive; non-interactive invocations fail with the same instructions rather than implicitly configuring. Once a build directory has been validated or configured, the target's incremental build runs without another confirmation so each launch reflects current sources. First-time development configurations pass `-DBUILD_TESTING=OFF`, because unit-test dependencies are optional in the vcpkg manifest and are not needed to run a development surface.
+
+Alternatives considered:
+
+- Auto-build: potentially expensive and unexpected.
+- Always fail: forces developers to reconstruct platform-specific presets manually.
+
+## Risks / Trade-offs
+
+### 发布审查收敛
+
+- 多配置构建记录实际产物的配置名称，并通过 `cmake --build --config` 编译同一配置；仅修改编译缓存 launcher 时保留已有 `CMAKE_BUILD_TYPE` 和 `BUILD_TESTING`。独立的嵌套 preset 不属于父级 CMake 构建。
+- 公共启动器向 Desktop 传递已验证的具体产物，向 Web 传递该可执行文件所在目录，避免二次发现选到其他配置。`--list` 只列举产物；`--rebuild` 强制刷新前端。
+- Windows TUI 直接创建新控制台进程；macOS 用 Terminal 的 AppleScript 入口执行经过逐参数 shell 引用的 `cd` 和 `exec`，确保工作目录与参数一致。
+- Web 重建前遇到既存 PID 记录时，复用原有 `daemon status` 身份校验并明确失败。此次不引入跨平台进程管理框架，也不调用现有仅按 PID 终止的 `daemon stop`。仅在核验成功后显示停止命令供开发者操作；无法确认身份时只显示检查命令。默认目录检查包含当前工作树旧提交的 runtime，显式目录只检查自身。
+- 回归使用临时目录与替身命令；Windows 另验证真实 VS 环境初始化。macOS/Linux 图形终端和 ARM64 原生编译不在本轮 Windows 主机验证范围内。
+
+- [A valid external build is configured with an unusual directory layout] → inspect standard build directories plus explicit `--build-dir`; require an exact `CMakeCache.txt` source match.
+- [CMake does not expose a fully portable architecture field] → require a runnable platform-native executable and compare configured generator/platform fields when present; reject uncertain configurations.
+- [A worktree-specific runtime path is untracked] → create it under the repository's ignored `.acecode` development state and document it in the launcher output.
+- [A platform lacks a supported graphical terminal launcher] → report the exact TUI executable command instead of silently starting TUI in the caller's terminal.
+
+## Migration Plan
+
+1. Add the shared launcher and thin wrappers without changing existing Web or Desktop launch commands.
+2. Add the repository-local skill, directing requests through the shared policy.
+3. Validate no-target selection, verified reuse, rejected reuse, declined rebuild, and each platform wrapper through focused tests or script help checks.
+4. Roll back by removing the new launcher, wrappers, and skill; existing Web and Desktop launchers remain unchanged.

openspec/changes/add-development-environment-launcher/proposal.md

@@ -0,0 +1,33 @@
+# Proposal
+
+## Why
+
+Developers currently need to choose and invoke separate Web or Desktop launchers manually, while TUI startup and reuse of compatible build outputs require repository-specific knowledge. A single cross-platform entry point should guide the target selection and safely reuse an existing build from a related worktree when possible.
+
+## What Changes
+
+- Add a cross-platform development-environment launcher that starts the Web daemon, Desktop shell, or terminal UI using existing repository launchers and build outputs.
+- Add dedicated Windows and POSIX entry points for Web, Desktop, and TUI so developers can start the desired target without providing a target argument or using an agent skill.
+- Validate reusable builds from the current worktree against its source directory, platform, architecture, and requested target; use related worktrees only for safe cache and frontend-artifact acceleration.
+- Incrementally rebuild every verified build before launch so source changes are incorporated; require confirmation only before configuring a missing or incompatible build.
+- Initialize the Windows Visual Studio C++ developer environment from the direct launchers so incremental builds work from a normal shell or double-clicked batch file.
+- Allow Windows direct launchers to configure a missing target build automatically, so double-clicked entry points do not wait for unavailable confirmation input.
+- Give each Web development workspace an isolated daemon runtime directory and open the selected development surface after a successful start.
+- Add a repository-local skill that asks for a target when omitted and applies the same validation and launch policy.
+
+## Capabilities
+
+### New Capabilities
+
+- `development-environment-launcher`: Guided, cross-platform selection, validation, and startup of ACECode Web, Desktop, and TUI development environments.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- New shared launcher logic and thin `.bat` and `.sh` entry points under `scripts/`.
+- Existing `scripts/dev_web.*` and `scripts/dev_desktop.*` remain the surface-specific launch mechanisms invoked by the new launcher.
+- New repository-local skill under `.agents/skills/`.
+- CMake preset selection and Git worktree metadata are used for build discovery and validation; no application protocol or production runtime behavior changes.