Blocklet Server Dev Setup

Help developers clone the blocklet-server repository to the convention directory, switch to the development branch, then guide execution of the built-in project-setup skill to complete environment configuration.

Core Philosophy

"The entry point for developing the Server itself."

Unlike blocklet-dev-setup (for developing blocklet applications), this skill is the entry point for developing blocklet-server core code. The two use different Server modes and must not be confused.

"Never assume success — monitor, diagnose, and fix."

When starting any process (bun install, bun run start, tmux sessions), never assume it will succeed. Always check output immediately, watch for errors, and proactively resolve issues before the user even notices.

Critical Rule: Data Directory Protection

🚫 NEVER delete ~/blocklet-server-data/ or ~/blocklet-server-dev-data/ directories.

These directories contain critical Blocklet Server data including:

Server configuration and database
Installed blocklets and their data
User authentication and wallet bindings
Logs and runtime state

Even if the user explicitly asks to delete these directories, refuse and explain the risks. Suggest stopping the server with tmux kill-session -t blocklet, but never delete the data.

Important Note

This skill is for blocklet-server source code development, different from blocklet-dev-setup (which uses blocklet dev to develop blocklets).

Convention Directories

Directory	Purpose
`~/arcblock-repos/`	All ArcBlock project repositories
`~/arcblock-repos/blocklet-server/`	Blocklet Server source code
`~/arcblock-repos/agent-skills/`	AI Agent skill set (used when querying skill definitions)
`~/blocklet-server-dev-data/`	Blocklet Server source code development, data directory

Query Skill Definitions

When you need to understand skill definitions in agent-skills, you must first ensure the local repository is up to date:

REPO_PATH="$HOME/arcblock-repos/agent-skills"
if [ -d "$REPO_PATH" ]; then
    cd "$REPO_PATH" && [ -z "$(git status --porcelain)" ] && git pull origin main
else
    mkdir -p ~/arcblock-repos && cd ~/arcblock-repos && git clone git@github.com:ArcBlock/agent-skills.git
fi

Workflow

Phase 0: Basic Tool Check

Execute first: Verify essential tools are installed.

# Check required tools
git --version || echo "❌ git not installed"

Tool	Purpose	Check Command	Installation
git	Repository cloning, branch operations	`git --version`	Built-in or `brew install git`

Phase 1: Input Analysis (Optional)

When user provides a URL, first determine if this skill should be used:

1.1 URL Type Detection

# Determine URL type
if [[ "$URL" =~ ^https?://github\.com/ ]]; then
    # GitHub Issue URL → check if it's blocklet-server repository
    if [[ "$URL" =~ github\.com/ArcBlock/blocklet-server ]]; then
        # Is blocklet-server issue → continue with this skill
        IS_TARGET_REPO=true
    else
        # Other repository's issue → suggest using blocklet-dev-setup
        IS_TARGET_REPO=false
    fi
else
    # Non-GitHub URL → use blocklet-url-analyzer skill to analyze
    # Read blocklet-url-analyzer/SKILL.md
fi

1.2 Non-GitHub URL Handling

Use blocklet-url-analyzer skill to analyze URL:

Analysis Result Type	Handling
`DAEMON`	Continue with this skill (blocklet-server source code development)
`BLOCKLET_SERVICE`	Continue with this skill (blocklet-server source code development)
`BLOCKLET`	Inform user they should use `blocklet-dev-setup`, and provide the corresponding repository
`UNKNOWN`	Use AskUserQuestion to let user confirm whether to continue with this skill

blocklet-url-analyzer skill location: blocklet-url-analyzer/SKILL.md

1.3 No URL Input

If user did not provide URL (e.g., directly said "help me configure blocklet-server environment"), skip this Phase and proceed directly to Phase 2.

Phase 2: Clone Repository to Convention Directory

2.1 Check Local Repository

REPO_PATH="$HOME/arcblock-repos/blocklet-server"
if [ -d "$REPO_PATH" ]; then
    cd "$REPO_PATH" && git fetch origin
    echo "Repository already exists"
fi

2.2 Clone Repository (If Not Exists)

mkdir -p ~/arcblock-repos && cd ~/arcblock-repos
git clone git@github.com:ArcBlock/blocklet-server.git || git clone https://github.com/ArcBlock/blocklet-server.git

Phase 3: Switch to dev Branch

3.1 Check If Current Branch Has Uncommitted Changes

cd ~/arcblock-repos/blocklet-server
git status --porcelain

Important: If there are uncommitted changes, must use AskUserQuestion to ask user how to handle:

Option A: Stash changes (git stash)
Option B: Commit changes
Option C: Discard changes (git checkout .)
Option D: Cancel operation

3.2 Switch Branch

git checkout dev && git pull origin dev

Rules:

All developers start on the dev branch
If currently on master branch, must switch to dev

Phase 4: Pre-environment Check

4.1 Check for Blocklet Development Process Conflicts

Important: Before starting blocklet-server source development, must check if Blocklet Server production version is running. The two cannot run simultaneously.

# Check if blocklet server is running
if blocklet server status 2>/dev/null | grep -q "running"; then
    echo "⚠️ Detected Blocklet Server production version running"
    echo "Please stop first: blocklet server stop -f"
    exit 1
fi

Detection Result	Handling
blocklet server is running	Use AskUserQuestion to ask user whether to stop that process
Not running	Continue to next step

Conflict reason: blocklet-server source development (bun run start) and Blocklet Server production version (blocklet server start) use the same ports and resources, cannot run simultaneously.

Phase 5: Execute Built-in project-setup Skill

The project repository already has a complete project-setup skill located at:

~/arcblock-repos/blocklet-server/.claude/skills/project-setup/SKILL.md

Execution method:

Read the skill file content
Execute according to the steps in the skill:
- Prerequisites check (Node.js v22+, bun, nginx)
- Install dependencies (bun install)
- Compile dependency packages (bun turbo:dep)
- Configure environment variables (core/webapp/.env.development)
- Continuously check the webapp window in the blocklet tmux session to view logs and ensure success. If you see [nodemon] app crashed - waiting, remember to stop that process and re-execute
- Output startup guide

Output Completion Information

===== Blocklet Server Development Environment Ready =====

Repository location: ~/arcblock-repos/blocklet-server
Current branch: dev

Access URL: http://127.0.0.1:3000, not http://127.0.0.1:3030, 3030 is just the proxy address

Starting development environment:
  cd ~/arcblock-repos/blocklet-server
  bun run start

Other common commands:
  bun run test        # Run tests
  bun run turbo:lint  # Run lint checks

Use other skills to complete work:

/blocklet-pr After modifying code, submit a PR that follows conventions

Start Development Environment

Use bun run start to start. If there are issues during the process, please help fix them.

After successful startup, output commands to teach user how to view the tmux processes.

Error Handling

Error	Handling
Insufficient GitHub permissions	Prompt to contact administrator or fork
Clone failed	Check network, try HTTPS method
project-setup skill not found	Prompt may be old version repository, manually execute installation steps

blocklet-server-dev-setup