release: v0.5.0 multi-client one-click installation

.github/workflows/auto-release.yml

@@ -0,0 +1,129 @@
+name: Auto Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout validated main commit
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Resolve version
+        id: version
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(node -p "JSON.parse(require('fs').readFileSync('package.json','utf8')).version")"
+          tag="v${version}"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Inspect existing tag and release
+        id: existing
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "release_exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "release_exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1; then
+            echo "tag_exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag_exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Verify release metadata
+        if: steps.existing.outputs.release_exists == 'false'
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          grep -q "^## ${VERSION}\b" CHANGELOG.md
+          grep -q "export const VERSION = \"${VERSION}\";" src/core.ts
+          grep -q "JEV_MCP_GIT_REF:-v${VERSION}" scripts/install.sh
+          grep -q "\"v${VERSION}\"" scripts/install.ps1
+
+      - name: Install locked dependencies
+        if: steps.existing.outputs.release_exists == 'false'
+        run: npm ci --no-audit --no-fund
+
+      - name: Re-run repository checks
+        if: steps.existing.outputs.release_exists == 'false'
+        run: npm run check
+
+      - name: Create annotated tag
+        if: >
+          steps.existing.outputs.release_exists == 'false' &&
+          steps.existing.outputs.tag_exists == 'false'
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "jev-mcp $TAG" "${{ github.event.workflow_run.head_sha }}"
+          git push origin "$TAG"
+
+      - name: Fetch release tag
+        if: steps.existing.outputs.release_exists == 'false'
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+        shell: bash
+        run: git fetch --force origin "refs/tags/$TAG:refs/tags/$TAG"
+
+      - name: Build release assets
+        if: steps.existing.outputs.release_exists == 'false'
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          TAG: ${{ steps.version.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p release-assets
+          git archive --format=zip --prefix="jev-mcp-${VERSION}/"             --output="release-assets/jev-mcp-${VERSION}.zip" "$TAG"
+          git archive --format=tar.gz --prefix="jev-mcp-${VERSION}/"             --output="release-assets/jev-mcp-${VERSION}.tar.gz" "$TAG"
+          sha256sum release-assets/jev-mcp-* > release-assets/SHA256SUMS.txt
+          awk -v version="$VERSION" '
+            $0 ~ "^## " version { found=1; next }
+            found && /^## / { exit }
+            found { print }
+          ' CHANGELOG.md > release-assets/RELEASE_NOTES.md
+          test -s release-assets/RELEASE_NOTES.md
+
+      - name: Create GitHub Release
+        if: steps.existing.outputs.release_exists == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          gh release create "$TAG"             release-assets/jev-mcp-*.zip             release-assets/jev-mcp-*.tar.gz             release-assets/SHA256SUMS.txt             --verify-tag             --notes-file release-assets/RELEASE_NOTES.md             --title "$TAG"

CHANGELOG.md

@@ -4,9 +4,13 @@ All notable project changes are documented here.
 
 ## Unreleased
 
+## 0.5.0 — Multi-client one-click installation
+
 - Added cross-platform bootstrap installers that create/update a durable local
   runtime at `~/.jev-mcp/runtime` instead of relying on npm Git-package
   execution at every MCP startup.
+- Stable bootstrap installs now default to the `v0.5.0` tag; advanced users can
+  set `JEV_MCP_GIT_REF=main` to follow the development channel.
 - Added one-command setup for Codex, Claude Code, Kimi Code, ZCode, Cursor,
   Gemini CLI, Windsurf-compatible config, generic `.agents`, and
   project-scoped VS Code MCP configuration.

README.md

@@ -102,34 +102,34 @@ macOS / Linux:
 
 ```bash
 # Codex
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 
 # Claude Code
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- claude-code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- claude-code
 
 # Kimi Code
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- kimi
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- kimi
 
 # ZCode
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- zcode
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- zcode
 
 # Cursor
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- cursor
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- cursor
 
 # Gemini CLI
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- gemini
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- gemini
 ```
 
 Windows PowerShell (replace `codex` with another target as needed):
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 ```
 
 To configure every detected user-level client:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash
 ```
 
 The key is stored only in `~/.jev-mcp/.env`; client MCP configs contain no
@@ -259,8 +259,7 @@ consume provider credits.
 | API dependency | TypeSafe-hosted System One API |
 | Stability | pre-1.0; behavior may evolve |
 
-The project follows semantic versioning in spirit, but while it remains below
-`1.0.0`, minor releases may refine tool schemas or behavior. Breaking changes
+The project follows semantic versioning in spirit. Stable one-click installs are pinned to the current release tag (`v0.5.0`) rather than `main`; users who intentionally want development builds can set `JEV_MCP_GIT_REF=main`. While the project remains below `1.0.0`, minor releases may refine tool schemas or behavior. Breaking changes
 should be documented in [CHANGELOG.md](CHANGELOG.md) and migration notes.
 
 ## Documentation

README.zh-CN.md

@@ -81,34 +81,34 @@ macOS / Linux：
 
 ```bash
 # Codex
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 
 # Claude Code
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- claude-code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- claude-code
 
 # Kimi Code
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- kimi
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- kimi
 
 # ZCode
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- zcode
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- zcode
 
 # Cursor
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- cursor
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- cursor
 
 # Gemini CLI
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- gemini
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- gemini
 ```
 
 Windows PowerShell（把 `codex` 换成其他目标即可）：
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 ```
 
 自动配置检测到的用户级客户端：
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash
 ```
 
 TypeSafe key 只保存在本机 `~/.jev-mcp/.env`，不会写入各 AI 的 MCP 配置；
@@ -223,7 +223,7 @@ npm run inspect
 | License | MIT |
 | npm 发布 | 主动禁用 |
 | 外部依赖 | TypeSafe-hosted System One API |
-| 稳定性 | pre-1.0，行为仍可能演进 |
+| 稳定性 | pre-1.0；一键安装默认固定到 `v0.5.0` 稳定 tag |
 
 ## 文档
 

docs/INSTALLATION.md

@@ -33,43 +33,43 @@ they are changed.
 ### Codex
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 ```
 
 ### Claude Code
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- claude-code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- claude-code
 ```
 
 ### Kimi Code
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- kimi
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- kimi
 ```
 
 ### ZCode
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- zcode
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- zcode
 ```
 
 ### Cursor
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- cursor
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- cursor
 ```
 
 ### Gemini CLI
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- gemini
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- gemini
 ```
 
 ### All detected user-level clients
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash
 ```
 
 The `all` flow intentionally skips the project-scoped VS Code target. Run the
@@ -80,7 +80,7 @@ installer with `vscode` from the project that should receive `.vscode/mcp.json`.
 ### Codex
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 ```
 
 Replace `codex` with `claude-code`, `kimi`, `zcode`, `cursor`,
@@ -89,7 +89,7 @@ Replace `codex` with `claude-code`, `kimi`, `zcode`, `cursor`,
 Configure all detected user-level clients:
 
 ```powershell
-irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1 | iex
+irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1 | iex
 ```
 
 ## What the bootstrap does
@@ -135,7 +135,7 @@ If you intentionally manage `TYPESAFE_API_KEY` outside jev-mcp, skip local
 credential creation:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex --skip-key
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex --skip-key
 ```
 
 The MCP process must then inherit `TYPESAFE_API_KEY` from its environment.
@@ -145,10 +145,10 @@ The MCP process must then inherit `TYPESAFE_API_KEY` from its environment.
 Rerun the installer:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 ```
 
-The managed runtime is fetched again and checked out to the configured ref.
+The managed runtime is fetched again and checked out to the configured ref. By default that ref is the stable `v0.5.0` tag.
 
 ## Uninstalling a client integration
 
@@ -194,6 +194,31 @@ The bootstrap recognizes:
 | `JEV_MCP_CONFIG_HOME` | Override `~/.jev-mcp` |
 | `JEV_MCP_RUNTIME_DIR` | Override the managed runtime checkout |
 | `JEV_MCP_REPO_URL` | Override the Git repository URL |
-| `JEV_MCP_GIT_REF` | Override the fetched branch/tag/ref |
+| `JEV_MCP_GIT_REF` | Override the fetched branch/tag/ref; default is `v0.5.0` |
 
 These are primarily useful for testing, forks, and pinned deployments.
+
+
+## Stable vs development channel
+
+The stable bootstrap script and installed runtime are both pinned to the same release tag:
+
+```text
+v0.5.0
+```
+
+To intentionally follow the development branch:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | env JEV_MCP_GIT_REF=main bash -s -- codex
+```
+
+For PowerShell:
+
+```powershell
+$env:JEV_MCP_GIT_REF = "main"
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+```
+
+Development-channel users should expect behavior to change before the next
+tagged release.

docs/QUICKSTART.md

@@ -17,13 +17,13 @@ client configuration.
 Codex on macOS/Linux:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 ```
 
 Codex on Windows PowerShell:
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 ```
 
 Other target IDs:
@@ -42,7 +42,7 @@ vscode
 Configure every detected user-level client on macOS/Linux:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash
 ```
 
 The installer creates: