Blocklet Updater

Bumps a blocklet project version and creates a release bundle.

Workflow

1. Version Bump (Smart Detection)

Check for project-specific version update scripts before falling back to blocklet version patch.

1.1 Detect Version Update Method

Check the following in priority order and use the first match:

| Priority | Detection | Command | |----------|-----------|---------| | 1 | Makefile has bump-version target | make bump-version | | 2 | package.json has bump-version script | pnpm run bump-version | | 3 | package.json has version script | pnpm run version | | 4 | lerna.json exists | lerna version patch --yes | | 5 | None of the above | blocklet version patch (fallback) |

Detection commands:

bash
# Priority 1: Check Makefile for bump-version target
if [ -f "Makefile" ] && grep -q "^bump-version:" Makefile 2>/dev/null; then
    VERSION_CMD="make bump-version"
fi

# Priority 2: Check package.json for bump-version script
if [ -z "$VERSION_CMD" ] && [ -f "package.json" ]; then
    if cat package.json | jq -e '.scripts["bump-version"]' > /dev/null 2>&1; then
        VERSION_CMD="pnpm run bump-version"
    fi
fi

# Priority 3: Check package.json for version script
if [ -z "$VERSION_CMD" ] && [ -f "package.json" ]; then
    if cat package.json | jq -e '.scripts["version"]' > /dev/null 2>&1; then
        VERSION_CMD="pnpm run version"
    fi
fi

# Priority 4: Check for lerna.json
if [ -z "$VERSION_CMD" ] && [ -f "lerna.json" ]; then
    VERSION_CMD="lerna version patch --yes"
fi

# Priority 5: Fallback to blocklet version
if [ -z "$VERSION_CMD" ]; then
    VERSION_CMD="blocklet version patch"
fi

1.2 Execute Version Bump

Run the detected command:

bash
$VERSION_CMD

Important: Project-specific scripts (like make bump-version) often:

• Update version file
• Auto-generate CHANGELOG.md entries
• Update multiple package versions in monorepos
• Call additional tooling scripts

If fails → EXIT with error output.

1.3 Update CHANGELOG (If Exists)

After version bump, verify and fix CHANGELOG.md if needed.

##### 1.3.1 Get Actual Version

First, get the actual version that was set (from blocklet.yml or package.json):

bash
# Get version from blocklet.yml
ACTUAL_VERSION=$(grep -E "^version:" blocklet.yml | sed 's/version: *//' | tr -d '"'"'" 2>/dev/null)

# Fallback to package.json if no blocklet.yml
if [ -z "$ACTUAL_VERSION" ]; then
    ACTUAL_VERSION=$(cat package.json | jq -r '.version' 2>/dev/null)
fi

##### 1.3.2 Find CHANGELOG Location

bash
# Common CHANGELOG locations in monorepos
CHANGELOG_PATHS=(
    "CHANGELOG.md"
    "blocklets/*/CHANGELOG.md"
    "packages/*/CHANGELOG.md"
)

for pattern in "${CHANGELOG_PATHS[@]}"; do
    for file in $pattern; do
        if [ -f "$file" ]; then
            echo "Found: $file"
        fi
    done
done

##### 1.3.3 Validate CHANGELOG Entry

For each CHANGELOG.md found, check if the latest entry matches the actual version:

bash
# Extract first version number from CHANGELOG.md
CHANGELOG_VERSION=$(grep -E "^## \[?[0-9]+\.[0-9]+\.[0-9]+\]?" CHANGELOG.md | head -1 | grep -oE "[0-9]+\.[0-9]+\.[0-9]+")

if [ "$CHANGELOG_VERSION" != "$ACTUAL_VERSION" ]; then
    echo "⚠️ Version mismatch!"
    echo "   CHANGELOG shows: $CHANGELOG_VERSION"
    echo "   Actual version:  $ACTUAL_VERSION"
fi

##### 1.3.4 Fix Version Mismatch

If CHANGELOG version doesn't match actual version, fix it:

1. If CHANGELOG has a newer entry with wrong version (e.g., script partially ran):

• Replace the wrong version number with the correct one

1. If CHANGELOG has no entry for the new version:

• Add a new entry at the top

bash
# Example fix: Replace wrong version in first heading
sed -i "0,/^## \[*$WRONG_VERSION\]*/s//## $ACTUAL_VERSION/" CHANGELOG.md

##### 1.3.5 Check Entry Content

After fixing version, check if the entry has content:

bash
# Get content between first ## and second ##
ENTRY_CONTENT=$(sed -n '/^## /,/^## /p' CHANGELOG.md | sed '1d;$d' | grep -v "^$")

if [ -z "$ENTRY_CONTENT" ]; then
    echo "⚠️ CHANGELOG entry is empty, needs content"
fi

##### 1.3.6 Generate Content for Empty Entry

If entry is empty, generate content based on:

1. Git commits since last version tag:

bash
# Get commits since last tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -n "$LAST_TAG" ]; then
    git log $LAST_TAG..HEAD --oneline --no-merges
fi

1. Categorize by commit type (feat, fix, chore, etc.):

markdown
## X.Y.Z (YYYY-MM-DD)

- feat: description of new feature
- fix: description of bug fix
- chore: description of maintenance task

1. If no meaningful commits found, use AskUserQuestion to ask user for changelog content.

##### 1.3.7 Common CHANGELOG Formats

Detect and follow the existing format:

| Format | Example | |--------|---------| | Keep a Changelog | ## [1.2.3] - 2024-01-20 | | Simple with date | ## 1.2.3 (2024-1-20) | | Simple no date | ## 1.2.3 |

Date format: Match the existing format in the file (e.g., 2024-01-20 vs 2024-1-20).

2. Build System Detection

Check if package.json exists and contains a build script.

If Build Script Exists

Install dependencies and build:

bash
pnpm install && pnpm run build

If either fails → EXIT with error output.

If No Build Script

Skip build step - project is likely pre-built or static.

3. Entry Point Verification

Locate Output Directory & Entry Point

Find index.html in common locations: dist/ → build/ → out/ → public/ → ./

If not found → EXIT with error message: "No index.html entry point found."

Verify blocklet.yml Main Field

Read blocklet.yml and check the main field:

• If main points to directory containing index.html → valid
• If main is misaligned → update it to the correct output directory
• After any update, inform user of the change

4. Metadata Verification

bash
blocklet meta

If fails → EXIT with error output and suggestions.

5. Bundle Creation

bash
blocklet bundle --create-release

If fails → EXIT with error output.

6. Finalization

Do NOT output any summary or recap after completion. Simply end silently after successful bundle creation. The tool outputs already provide sufficient feedback to the user.

Error Reference

See {baseDir}/errors.md for all error conditions and suggestions.

Supporting Files

• errors.md - Error reference
• examples.md - Workflow examples

{baseDir} resolves to the skill's installation directory.