chore: promote v0.2.1 to stable

.githooks/pre-commit

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Auto-updates the "Last updated" footer in staged Markdown docs.
+# Enable once per clone with: git config core.hooksPath .githooks
+
+python "$(git rev-parse --show-toplevel)/scripts/update_docs_dates.py"

.github/workflows/build.yml

@@ -9,10 +9,15 @@ on:
       - 'CHANGELOG.md'
       - 'LICENSE'
       - '*.md'
+  workflow_dispatch: {}
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   # ─────────────────────────────────────────────────────────────────────────────
   # TEST BUILD (develop only) — Verify code compiles and tests pass
@@ -63,6 +68,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    env:
+      ELECTRON_CACHE: ${{ github.workspace }}/.electron-cache
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
@@ -97,35 +104,53 @@ jobs:
           cd frontend
           npm ci
           npm run build
+      - name: Cache Electron download
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.ELECTRON_CACHE }}
+          key: electron-${{ runner.os }}-${{ hashFiles('electron/package-lock.json') }}
       - name: Test electron setup
         run: |
           cd electron
           npm ci --include=dev
 
   # ─────────────────────────────────────────────────────────────────────────────
-  # RELEASE BUILD (main only) — Create and publish stable release
+  # BETA RELEASE (develop only) — Package and publish a prerelease build
   # ─────────────────────────────────────────────────────────────────────────────
-  get-version:
-    if: github.ref == 'refs/heads/main'
+  get-version-beta:
+    if: github.ref == 'refs/heads/develop'
+    needs: [test-python, test-frontend, test-electron]
     runs-on: ubuntu-latest
     permissions:
       contents: read
     outputs:
-      version: ${{ steps.ver.outputs.version }}
+      base_version: ${{ steps.ver.outputs.base_version }}
+      beta_version: ${{ steps.ver.outputs.beta_version }}
     steps:
       - uses: actions/checkout@v6
       - id: ver
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          VERSION=$(grep -oP 'VERSION\s*=\s*"\K[^"]+' python/config.py)
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "Building MetaLens v$VERSION"
+          BASE=$(grep -oP 'VERSION\s*=\s*"\K[^"]+' python/config.py)
+          # Count existing beta releases for this exact base version and increment —
+          # keeps beta.N scoped to the version instead of the workflow's global run number.
+          LAST=$(gh release list --repo "${{ github.repository }}" --limit 200 \
+            | grep -oP "v${BASE}-beta\.\K[0-9]+" | sort -n | tail -1)
+          NEXT=$(( ${LAST:-0} + 1 ))
+          BETA="${BASE}-beta.${NEXT}"
+          echo "base_version=$BASE" >> "$GITHUB_OUTPUT"
+          echo "beta_version=$BETA" >> "$GITHUB_OUTPUT"
+          echo "Building MetaLens beta v$BETA"
 
-  build-windows:
-    if: github.ref == 'refs/heads/main'
-    needs: get-version
+  build-windows-beta:
+    if: github.ref == 'refs/heads/develop'
+    needs: get-version-beta
     runs-on: windows-latest
     permissions:
       contents: read
+    env:
+      ELECTRON_CACHE: ${{ github.workspace }}/.electron-cache
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
@@ -160,28 +185,35 @@ jobs:
           npm run build
       - name: Copy frontend dist into electron
         run: cp -r frontend/dist electron/frontend
-      - name: Sync electron version
+      - name: Sync electron version to beta
         run: |
           cd electron
-          npm version ${{ needs.get-version.outputs.version }} --no-git-tag-version --allow-same-version
+          npm version ${{ needs.get-version-beta.outputs.beta_version }} --no-git-tag-version --allow-same-version
+      - name: Cache Electron download
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.ELECTRON_CACHE }}
+          key: electron-${{ runner.os }}-${{ hashFiles('electron/package-lock.json') }}
       - name: Package with Electron Forge
         run: |
           cd electron
           npm ci --include=dev
           npx electron-forge make
-      - name: Upload Windows artifact
+      - name: Upload Windows beta artifact
         uses: actions/upload-artifact@v7
         with:
-          name: windows-installer
+          name: windows-installer-beta
           path: electron/out/make/**/*.exe
           if-no-files-found: error
 
-  build-linux:
-    if: github.ref == 'refs/heads/main'
-    needs: get-version
+  build-linux-beta:
+    if: github.ref == 'refs/heads/develop'
+    needs: get-version-beta
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    env:
+      ELECTRON_CACHE: ${{ github.workspace }}/.electron-cache
     steps:
       - uses: actions/checkout@v6
       - name: Install system dependencies
@@ -217,20 +249,25 @@ jobs:
           npm run build
       - name: Copy frontend dist into electron
         run: cp -r frontend/dist electron/frontend
-      - name: Sync electron version
+      - name: Sync electron version to beta
         run: |
           cd electron
-          npm version ${{ needs.get-version.outputs.version }} --no-git-tag-version --allow-same-version
+          npm version ${{ needs.get-version-beta.outputs.beta_version }} --no-git-tag-version --allow-same-version
       - name: Configure RPM macros
         run: echo '%_build_id_links none' >> ~/.rpmmacros
+      - name: Cache Electron download
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.ELECTRON_CACHE }}
+          key: electron-${{ runner.os }}-${{ hashFiles('electron/package-lock.json') }}
       - name: Package with Electron Forge
         run: |
           cd electron
           npm ci --include=dev
           npx electron-forge make
       - name: Create Linux tar.gz
         run: |
-          VERSION=${{ needs.get-version.outputs.version }}
+          VERSION=${{ needs.get-version-beta.outputs.beta_version }}
           APP_DIR=$(find electron/out -maxdepth 1 -type d -name "MetaLens-linux-*" | head -1)
           if [ -n "$APP_DIR" ]; then
             tar -czf "electron/out/make/MetaLens-${VERSION}-Linux.tar.gz" \
@@ -239,19 +276,19 @@ jobs:
           else
             echo "Warning: no MetaLens-linux-* directory found, skipping tar.gz"
           fi
-      - name: Upload Linux artifacts
+      - name: Upload Linux beta artifacts
         uses: actions/upload-artifact@v7
         with:
-          name: linux-packages
+          name: linux-packages-beta
           path: |
             electron/out/make/**/*.deb
             electron/out/make/**/*.rpm
             electron/out/make/**/*.tar.gz
           if-no-files-found: error
 
-  release:
-    if: github.ref == 'refs/heads/main'
-    needs: [get-version, build-windows, build-linux]
+  release-beta:
+    if: github.ref == 'refs/heads/develop'
+    needs: [get-version-beta, build-windows-beta, build-linux-beta]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -261,7 +298,89 @@ jobs:
           path: artifacts
       - name: List artifacts
         run: find artifacts -type f
-      - name: Create GitHub Release
+      - name: Create beta GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          tag_name: v${{ needs.get-version-beta.outputs.beta_version }}
+          name: MetaLens v${{ needs.get-version-beta.outputs.beta_version }} (beta)
+          draft: false
+          prerelease: true
+          generate_release_notes: true
+          make_latest: false
+          files: |
+            artifacts/windows-installer-beta/**
+            artifacts/linux-packages-beta/**
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # STABLE RELEASE (main only) — Promote the matching beta build, no rebuild
+  # ─────────────────────────────────────────────────────────────────────────────
+  get-version:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+      - id: ver
+        run: |
+          VERSION=$(grep -oP 'VERSION\s*=\s*"\K[^"]+' python/config.py)
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Building MetaLens v$VERSION"
+
+  find-latest-beta:
+    if: github.ref == 'refs/heads/main'
+    needs: get-version
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      beta_tag: ${{ steps.find.outputs.beta_tag }}
+    steps:
+      - id: find
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.get-version.outputs.version }}
+        run: |
+          TAG=$(gh release list --repo "$GITHUB_REPOSITORY" --limit 200 --json tagName \
+            --jq '.[].tagName' \
+            | grep -E "^v${VERSION}-beta\.[0-9]+$" \
+            | sort -t. -k4 -n \
+            | tail -1)
+          if [ -z "$TAG" ]; then
+            echo "::error::Nessuna release beta trovata per v${VERSION}. Genera prima una beta da develop con la stessa VERSION in python/config.py."
+            exit 1
+          fi
+          echo "beta_tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "Promuovendo $TAG a stable v${VERSION}"
+
+  promote-stable:
+    if: github.ref == 'refs/heads/main'
+    needs: [get-version, find-latest-beta]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download beta release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          mkdir -p promoted
+          gh release download "${{ needs.find-latest-beta.outputs.beta_tag }}" \
+            --repo "$GITHUB_REPOSITORY" --dir promoted
+      - name: Strip beta suffix from filenames
+        run: |
+          cd promoted
+          # Each maker encodes the beta suffix differently: "-beta.N" (exe/tar.gz),
+          # "beta.N" with no separator (rpm, dash stripped for Version field rules),
+          # ".beta.N" (deb, dot-separated per Debian version conventions).
+          for f in *; do
+            new=$(echo "$f" | sed -E 's/[-.]?beta\.?[0-9]+//')
+            if [ "$f" != "$new" ]; then mv -- "$f" "$new"; fi
+          done
+          ls -la
+      - name: Create stable GitHub Release
         uses: softprops/action-gh-release@v3
         with:
           tag_name: v${{ needs.get-version.outputs.version }}
@@ -270,6 +389,4 @@ jobs:
           prerelease: false
           generate_release_notes: true
           make_latest: true
-          files: |
-            artifacts/windows-installer/**
-            artifacts/linux-packages/**
+          files: promoted/*

CHANGELOG.md

@@ -1,17 +1,32 @@
 # Changelog
 
 All notable changes to MetaLens are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) — `MAJOR.MINOR.PATCH`.
 
-Format: [Semantic Versioning](https://semver.org/) — `MAJOR.MINOR.PATCH`
+---
+
+## [Unreleased] — Next Release
+
+### Roadmap
+
+- [ ] **CSV/JSON Export** — Export metadata for the current file or folder
+- [ ] **Batch Edit** — Apply a field change to multiple selected files at once
+- [ ] **Search/Filter Bar** — Filter the file list by name or extension
 
 ---
 
-## [Unreleased]
+## [0.2.1] — 2026-07-14
+
+### Dependencies
+- electron: 43.0.0 → 43.1.0 (fixed crash on replacing an open application menu, Chromium 150.0.7871.47, Node.js 24.18.0)
+- vite: 8.1.3 → 8.1.4 (oxc minifier preference for legacy builds, StackBlitz build workaround, SSR stacktrace alignment)
+- uvicorn: 0.49.0 → 0.51.0 (near-zero-downtime worker reload on SIGHUP, removed colorama from standard extra)
+- lucide-react: 1.23.0 → 1.24.0 (new icons, several upstream icon fixes)
 
-### Planned
-- Export metadata as CSV/JSON
-- Batch edit on multiple selected files
-- Search/filter bar in file list
+### Quality
+- All tests passing: 47 passed, 1 skipped
+- Frontend build and Electron startup verified with updated dependencies
+- No regressions
 
 ---
 
@@ -194,9 +209,9 @@ Format: [Semantic Versioning](https://semver.org/) — `MAJOR.MINOR.PATCH`
 
 ### Documentation
 - Added comprehensive security documentation (2000+ lines)
-  - `SECURITY_ANALYSIS_Q_AND_A.md`: Deep threat model analysis
   - `python/SECURITY.md`: Security design and implementation guide
   - `python/core/PATH_SECURITY_USAGE.md`: API reference for developers
+  - *(internal threat-model notes were later removed from the repo as temporary development files — see [0.1.2])*
 
 ---
 
@@ -222,3 +237,7 @@ Format: [Semantic Versioning](https://semver.org/) — `MAJOR.MINOR.PATCH`
 - About dialog with version from `/health`
 - GitHub Actions CI: automated Windows (.exe) + Linux (.deb/.rpm) builds on push to `main`
 - MIT License — © 2026 Graziano Mariella
+
+---
+
+*← [Back to README](./README.md)*