feat: implement standalone binary compilation and publish workflow

.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release Binaries
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: bun-linux-x64
+            output: prospec-linux-x64
+          - os: macos-latest
+            target: bun-darwin-arm64
+            output: prospec-macos-arm64
+            sign: true
+          - os: macos-latest
+            target: bun-darwin-x64
+            output: prospec-macos-x64
+            sign: true
+          - os: windows-latest
+            target: bun-windows-x64
+            output: prospec-windows-x64.exe
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Build bundle
+        run: pnpm run bundle
+
+      - name: Compile Standalone Binary
+        run: bun build ./dist/cli-bundle.js --compile --minify --target=${{ matrix.target }} --outfile=dist/${{ matrix.output }}
+
+      - name: Code Sign (macOS only)
+        if: ${{ matrix.sign }}
+        run: codesign --sign - dist/${{ matrix.output }}
+
+      - name: Smoke Test (Non-Windows)
+        if: matrix.os != 'windows-latest'
+        run: ./dist/${{ matrix.output }} --version
+
+      - name: Smoke Test (Windows)
+        if: matrix.os == 'windows-latest'
+        run: .\dist\${{ matrix.output }} --version
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.output }}
+          path: dist/${{ matrix.output }}
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: binaries
+          merge-multiple: true
+
+      - name: Display binaries
+        run: ls -la binaries
+
+      - name: Upload to Release
+        uses: softprops/action-gh-release@v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          files: binaries/*

README.md

@@ -4,7 +4,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/tests-2090%20passing-success?style=flat-square)](tests/)
+[![Tests](https://img.shields.io/badge/tests-2092%20passing-success?style=flat-square)](tests/)
 [![Node](https://img.shields.io/badge/node-%3E%3D22.13-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org/)
 [![pnpm](https://img.shields.io/badge/pnpm-%3E%3D11-orange?style=flat-square&logo=pnpm)](https://pnpm.io/)
 
@@ -75,25 +75,43 @@ From zero to your first AI-driven change in about five minutes.
 
 Prospec is a **bootstrap/update CLI** — once `prospec quickstart` has run (it chains `init` + `agent sync`), your agent works from the committed Skills and Knowledge (Markdown); the binary isn't needed again until you regenerate.
 
-> [!TIP]
-> Since Prospec is an unpublished fork, global installation compiles TypeScript on the fly. We recommend running via **npx** (clones + builds on the fly) or installing as a **devDependency** to avoid global build failures:
->
-> **Option A: Run on demand with npx (Recommended)**
-> ```bash
-> npx github:benwu95/prospec <command>
-> ```
->
-> **Option B: Pin as devDependency (Recommended for Node.js projects)**
-> ```bash
-> npm install -D github:benwu95/prospec     # or: pnpm add -D github:benwu95/prospec
-> ```
+**Option A: Standalone Binary (Recommended & No Node.js Required)**
+For macOS and Linux, run the one-click installer script:
+```bash
+curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash
+```
+
+For Windows, run the one-click PowerShell installer script:
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"
+```
+
+Alternatively, download the precompiled binary manually from the [GitHub Releases](https://github.com/benwu95/prospec/releases) page:
+
+- **Linux (x64)**: `prospec-linux-x64`
+- **macOS (Apple Silicon)**: `prospec-macos-arm64`
+- **macOS (Intel)**: `prospec-macos-x64`
+- **Windows (x64)**: `prospec-windows-x64.exe`
 
-If you still prefer a global install:
+(For manual macOS/Linux installation, run `chmod +x prospec-<os>-<arch>` and move the file to `/usr/local/bin/prospec`).
+
+
+**Option B: Run on demand with npx (Node.js environments)**
+Run without installing globally:
 ```bash
-npm install -g github:benwu95/prospec     # or: pnpm add -g github:benwu95/prospec
-prospec --help                            # verify
+npx github:benwu95/prospec <command>
+```
+
+**Option C: Pin as devDependency (Node.js projects)**
+Install as a local project dependency:
+```bash
+npm install -D github:benwu95/prospec     # or: pnpm add -D github:benwu95/prospec
 ```
 
+> [!WARNING]
+> We do **NOT** recommend installing globally via `npm install -g` as global compiling of unpublished forks can fail depending on your local Node/compile environment.
+
+
 ### 2. Bootstrap your project
 
 One command does the deterministic setup — it chains `init` + `agent sync`, skipping any step already done:
@@ -721,7 +739,7 @@ src/
 ## Testing
 
 ```bash
-# Run all tests (2090 tests)
+# Run all tests (2092 tests)
 pnpm test
 
 # Watch mode
@@ -734,8 +752,8 @@ pnpm run typecheck
 pnpm run lint
 ```
 
-**Test Coverage**: 2090 tests across 4 categories:
-- Unit tests (types + lib + services + cli): 1362 tests
+**Test Coverage**: 2092 tests across 4 categories:
+- Unit tests (types + lib + services + cli): 1364 tests
 - Contract tests (CLI output + Skill format): 647 tests
 - Integration tests: 38 tests
 - E2E tests: 43 tests

README.zh-TW.md

@@ -4,7 +4,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
-[![測試](https://img.shields.io/badge/測試-2090%20通過-success?style=flat-square)](tests/)
+[![測試](https://img.shields.io/badge/測試-2092%20通過-success?style=flat-square)](tests/)
 [![Node](https://img.shields.io/badge/node-%3E%3D22.13-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org/)
 [![pnpm](https://img.shields.io/badge/pnpm-%3E%3D11-orange?style=flat-square&logo=pnpm)](https://pnpm.io/)
 
@@ -75,25 +75,43 @@ Prospec 是一套**以 Skills 為核心的規格驅動開發（SDD）工具組**
 
 Prospec 是 **bootstrap／update 用的 CLI** —— `prospec quickstart` 跑完後（它會串接 `init` + `agent sync`），你的 Agent 用的是已 commit 的 Skills 與 Knowledge（Markdown），除非要重新生成，否則不會再用到 binary。所以全域安裝一次即可。
 
-> [!TIP]
-> 由於 Prospec 目前為尚未發佈的 fork，全域安裝時會在本機進行編譯。我們建議使用 **npx** 執行（每次執行自動 clone + build）或安裝為專案的 **devDependency**，以避免本機全域編譯環境問題：
->
-> **選項 A：使用 npx 按需執行（推薦）**
-> ```bash
-> npx github:benwu95/prospec <command>
-> ```
->
-> **選項 B：在專案內固定為開發期依賴 (devDependency)（Node.js 專案推薦）**
-> ```bash
-> npm install -D github:benwu95/prospec     # 或：pnpm add -D github:benwu95/prospec
-> ```
+**選項 A：獨立執行檔 (Standalone Binary)（推薦 & 免安裝 Node.js 執行期環境）**
+對於 macOS 和 Linux，可執行一鍵安裝腳本：
+```bash
+curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash
+```
+
+對於 Windows，可執行一鍵 PowerShell 安裝腳本：
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"
+```
+
+或者，您也可以手動自 [GitHub Releases](https://github.com/benwu95/prospec/releases) 頁面下載適用您平台的二進位檔：
+
+- **Linux (x64)**: `prospec-linux-x64`
+- **macOS (Apple Silicon)**: `prospec-macos-arm64`
+- **macOS (Intel)**: `prospec-macos-x64`
+- **Windows (x64)**: `prospec-windows-x64.exe`
 
-如果您仍偏好全域安裝：
+（手動安裝 macOS/Linux 版本時，請執行 `chmod +x prospec-<os>-<arch>` 並將檔案移動至 `/usr/local/bin/prospec`）。
+
+
+**選項 B：使用 npx 按需執行（Node.js 環境）**
+不需全域安裝即可執行：
 ```bash
-npm install -g github:benwu95/prospec     # 或：pnpm add -g github:benwu95/prospec
-prospec --help                            # 驗證
+npx github:benwu95/prospec <command>
+```
+
+**選項 C：在專案內固定為開發期依賴 (devDependency)（Node.js 專案）**
+作為專案本地依賴進行安裝：
+```bash
+npm install -D github:benwu95/prospec     # 或：pnpm add -D github:benwu95/prospec
 ```
 
+> [!WARNING]
+> 我們**不推薦**使用 `npm install -g` 進行全域安裝，因為非發布版分支 (unpublished fork) 的全域編譯可能會因為您本機的 Node/編譯環境不同而失敗。
+
+
 ### 2. 建立專案骨架
 
 一個指令完成 deterministic 的設定 —— 它會串接 `init` + `agent sync`，已完成的步驟自動跳過：
@@ -692,7 +710,7 @@ src/
 ## 測試
 
 ```bash
-# 執行所有測試（2090 個測試）
+# 執行所有測試（2092 個測試）
 pnpm test
 
 # Watch 模式
@@ -705,8 +723,8 @@ pnpm run typecheck
 pnpm run lint
 ```
 
-**測試覆蓋率**：2090 個測試橫跨 4 大類：
-- Unit tests（types + lib + services + cli）：1362 tests
+**測試覆蓋率**：2092 個測試橫跨 4 大類：
+- Unit tests（types + lib + services + cli）：1364 tests
 - Contract tests（CLI 輸出 + Skill 格式）：647 tests
 - Integration tests：38 tests
 - E2E tests：43 tests

docs/i18n.js

@@ -128,8 +128,11 @@
     'quickstart.eyebrow': '§04 · 快速上手',
     'quickstart.h2': '約 5 分鐘，從零到你的第一個 AI 驅動變更。',
     'quickstart.lede': '前置需求：Node.js ≥ 22.13 與一個 AI CLI（推薦 Claude Code）。Prospec 只需安裝一次 —— bootstrap 後，你的 agent 就從已 commit 的 Markdown 運作。',
-    'quickstart.s1.h': '全域安裝 CLI',
-    'quickstart.s1.p': '它是尚未發佈的 GitHub fork，所以 npm/pnpm 會 clone 並透過 <code>prepare</code> script 自動 build。',
+    'quickstart.s1.h': '安裝 CLI',
+    'quickstart.s1.p': '請下載適用您系統平台的預編譯二進位執行檔，或透過 npm/pnpm 進行安裝。',
+    'quickstart.optA1': '// 選項 A1：獨立執行檔（推薦 / 適用 macOS & Linux）',
+    'quickstart.optA2': '// 選項 A2：獨立執行檔（推薦 / 適用 Windows）',
+    'quickstart.optB': '// 選項 B：使用 npx 按需執行（需要 Node.js 環境）',
     'quickstart.cm.verify': '# 驗證',
     'quickstart.s2.h': '啟動你的專案',
     'quickstart.s2.p': '一個指令串接 <code>init</code> + <code>agent sync</code> —— 選擇你的 AI Assistant 與文件語言。接著在你的 agent 內完成收尾。',

docs/index.html

@@ -301,11 +301,17 @@ <h2 data-i18n="quickstart.h2">Zero to your first AI-driven change in ~5 minutes.
       <div class="step">
         <div class="step__n" aria-hidden="true">1</div>
         <div>
-          <h3 data-i18n="quickstart.s1.h">Install the CLI globally</h3>
-          <p data-i18n="quickstart.s1.p">It's an unpublished GitHub fork, so npm/pnpm clones and builds it via the <code>prepare</code> script.</p>
+          <h3 data-i18n="quickstart.s1.h">Install the CLI</h3>
+          <p data-i18n="quickstart.s1.p">Download the precompiled binary from Releases, or install via npm/pnpm.</p>
           <div class="cmds">
-            <div class="cmd"><code><span class="pr">$ </span>npm install -g github:benwu95/prospec</code><button class="copy" data-copy="npm install -g github:benwu95/prospec">Copy</button></div>
-            <div class="cmd"><code><span class="pr">$ </span>prospec --help <span class="cm" data-i18n="quickstart.cm.verify"># verify</span></code><button class="copy" data-copy="prospec --help">Copy</button></div>
+            <div style="margin-bottom: 0.5rem; font-size: 0.85rem; color: var(--color-ink-muted);" data-i18n="quickstart.optA1">// Option A1: Standalone Binary (Recommended / macOS & Linux)</div>
+            <div class="cmd"><code><span class="pr">$ </span>curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash</code><button class="copy" data-copy="curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash">Copy</button></div>
+
+            <div style="margin-bottom: 0.5rem; font-size: 0.85rem; color: var(--color-ink-muted);" data-i18n="quickstart.optA2">// Option A2: Standalone Binary (Recommended / Windows)</div>
+            <div class="cmd"><code><span class="pr">PS> </span>powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"</code><button class="copy" data-copy="powershell -c &quot;irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex&quot;">Copy</button></div>
+
+            <div style="margin-bottom: 0.5rem; font-size: 0.85rem; color: var(--color-ink-muted);" data-i18n="quickstart.optB">// Option B: Run on demand with npx (Node.js environments)</div>
+            <div class="cmd"><code><span class="pr">$ </span>npx github:benwu95/prospec --help</code><button class="copy" data-copy="npx github:benwu95/prospec --help">Copy</button></div>
           </div>
         </div>
       </div>

install.ps1

@@ -0,0 +1,43 @@
+$ErrorActionPreference = 'Stop'
+
+$Owner = "benwu95"
+$Repo = "prospec"
+$AssetName = "prospec-windows-x64.exe"
+$InstallDir = "$Home\.prospec\bin"
+$TargetPath = "$InstallDir\prospec.exe"
+
+# Create installation directory if it doesn't exist
+if (-not (Test-Path $InstallDir)) {
+    New-Item -ItemType Directory -Path $InstallDir | Out-Null
+}
+
+$DownloadUrl = "https://github.com/$Owner/$Repo/releases/latest/download/$AssetName"
+
+Write-Host "Downloading $AssetName from latest release..."
+try {
+    # Download the binary file following redirects
+    Invoke-WebRequest -Uri $DownloadUrl -OutFile $TargetPath -UseBasicParsing
+} catch {
+    Write-Error "Failed to download $AssetName from $DownloadUrl"
+    exit 1
+}
+
+Write-Host "Successfully installed prospec.exe to $TargetPath"
+
+# Check and update PATH if not present
+$UserPath = [Environment]::GetEnvironmentVariable("PATH", "User")
+$PathSeparator = [IO.Path]::PathSeparator
+$UserPathList = $UserPath -split [Regex]::Escape($PathSeparator)
+
+if ($UserPathList -notcontains $InstallDir) {
+    Write-Host "Adding $InstallDir to user PATH..."
+    $NewUserPath = "$UserPath$PathSeparator$InstallDir"
+    [Environment]::SetEnvironmentVariable("PATH", $NewUserPath, "User")
+    # Update current session PATH
+    $env:PATH = "$env:PATH$PathSeparator$InstallDir"
+    Write-Host "PATH updated. Please restart your terminal/IDE for the changes to take full effect."
+}
+
+# Verify installation in the current session
+Write-Host "Verifying installation..."
+& prospec --version