From 51387498a5f473792d31a660f13c27a7af8264b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jim=20Liu=20=E5=AE=9D=E7=8E=89?= <junminliu@gmail.com>
Date: Thu, 5 Mar 2026 10:31:24 -0600
Subject: [PATCH] refactor(project): add BUN_X runtime detection with bun-first
 fallback

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 45 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6b70eae..64626fc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -43,27 +43,51 @@ Each skill contains:
 
 ## Running Skills
 
-All scripts run via Bun (no build step):
+All scripts are TypeScript, executed via Bun runtime (no build step).
+
+### Runtime Detection (`${BUN_X}`)
+
+Before running any script, the agent MUST detect the runtime **once per session** and set `${BUN_X}`:
 
 ```bash
-npx -y bun skills/<skill>/scripts/main.ts [options]
+# Detect runtime (run once, reuse result)
+if command -v bun &>/dev/null; then
+  BUN_X="bun"
+elif command -v npx &>/dev/null; then
+  BUN_X="npx -y bun"
+else
+  echo "Error: Neither bun nor npx found. Install bun: curl -fsSL https://bun.sh/install | bash"
+  exit 1
+fi
+```
+
+| Priority | Condition | `${BUN_X}` value | Notes |
+|----------|-----------|-------------------|-------|
+| 1 | `bun` installed | `bun` | Fastest, native execution |
+| 2 | `npx` available | `npx -y bun` | Downloads bun on first run via npm |
+| 3 | Neither found | Error + install guide | Suggest: `curl -fsSL https://bun.sh/install \| bash` |
+
+### Script Execution
+
+```bash
+${BUN_X} skills/<skill>/scripts/main.ts [options]
 ```
 
 Examples:
 ```bash
 # Text generation
-npx -y bun skills/baoyu-danger-gemini-web/scripts/main.ts "Hello"
+${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts "Hello"
 
 # Image generation
-npx -y bun skills/baoyu-danger-gemini-web/scripts/main.ts --prompt "A cat" --image cat.png
+${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts --prompt "A cat" --image cat.png
 
 # From prompt files
-npx -y bun skills/baoyu-danger-gemini-web/scripts/main.ts --promptfiles system.md content.md --image out.png
+${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts --promptfiles system.md content.md --image out.png
 ```
 
 ## Key Dependencies
 
-- **Bun**: TypeScript runtime (via `npx -y bun`)
+- **Bun**: TypeScript runtime (native `bun` preferred, fallback `npx -y bun`)
 - **Chrome**: Required for `baoyu-danger-gemini-web` auth and `baoyu-post-to-x` automation
 - **No npm packages**: Self-contained TypeScript, no external dependencies
 
@@ -176,7 +200,8 @@ Every SKILL.md with scripts MUST include this section after Usage:
 **Agent Execution Instructions**:
 1. Determine this SKILL.md file's directory path as `SKILL_DIR`
 2. Script path = `${SKILL_DIR}/scripts/<script-name>.ts`
-3. Replace all `${SKILL_DIR}` in this document with the actual path
+3. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun
+4. Replace all `${SKILL_DIR}` and `${BUN_X}` in this document with actual values
 
 **Script Reference**:
 | Script | Purpose |
@@ -185,7 +210,7 @@ Every SKILL.md with scripts MUST include this section after Usage:
 | `scripts/other.ts` | Other functionality |
 ```
 
-When referencing scripts in workflow sections, use `${SKILL_DIR}/scripts/<name>.ts` so agents can resolve the correct path.
+When referencing scripts in workflow sections, use `${BUN_X} ${SKILL_DIR}/scripts/<name>.ts` so agents can resolve the correct runtime and path.
 
 ### Progressive Disclosure
 
@@ -320,13 +345,13 @@ When adding, updating, or deleting styles for `baoyu-comic`, follow this workflo
    - Add auto-selection entry if applicable
 3. **Generate showcase image**:
    ```bash
-   npx -y bun skills/baoyu-danger-gemini-web/scripts/main.ts \
+   ${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts \
      --prompt "A single comic book page in <style-name> style showing [appropriate scene]. Features: [style characteristics from style definition]. 3:4 portrait aspect ratio comic page." \
      --image screenshots/comic-styles/<style-name>.png
    ```
 4. **Compress to WebP**:
    ```bash
-   npx -y bun skills/baoyu-compress-image/scripts/main.ts screenshots/comic-styles/<style-name>.png
+   ${BUN_X} skills/baoyu-compress-image/scripts/main.ts screenshots/comic-styles/<style-name>.png
    ```
 5. **Update both READMEs** (`README.md` and `README.zh.md`):
    - Add style to `--style` options