Merge pull request #5 from spring-ai-community/0.2.0-M4

Release 0.2.0-M4

Author: JM-Lab

.github/workflows/desktop-release.yml

@@ -62,6 +62,23 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v5
 
+      - name: Resolve installer version from ref
+        id: ver
+        shell: bash
+        run: |
+          REF="${{ github.ref_name }}"
+          if [[ "$REF" =~ ^v?([0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9]+)*)$ ]]; then
+            VERSION="${BASH_REMATCH[1]}"
+          elif [[ "$REF" =~ ^([0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9]+)*) ]]; then
+            VERSION="${BASH_REMATCH[1]}"
+          else
+            VERSION="${REF}"
+          fi
+          # Normalize milestone marker case (e.g., -m4 -> -M4)
+          VERSION=$(echo "$VERSION" | sed -E 's/-m([0-9]+)/-M\1/')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Resolved installer version: $VERSION"
+
       - name: Set up GraalVM JDK 21
         uses: graalvm/setup-graalvm@v1
         with:
@@ -97,6 +114,11 @@ jobs:
         working-directory: electron
         run: npm ci
 
+      - name: Set installer version on electron/package.json
+        working-directory: electron
+        shell: bash
+        run: npm version "${{ steps.ver.outputs.version }}" --no-git-tag-version --allow-same-version
+
       - name: Install frontend dependencies
         if: hashFiles('package.json') != ''
         run: npm install --no-audit --no-fund
@@ -124,6 +146,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      id-token: write       # required for Sigstore OIDC token used by build provenance
+      attestations: write   # required to write the attestation back to the repo
 
     steps:
       - name: Download installer artifacts
@@ -132,6 +156,24 @@ jobs:
           path: release-assets
           merge-multiple: true
 
+      - name: Generate SHA-256 checksums
+        working-directory: release-assets
+        run: |
+          shopt -s nullglob
+          for f in *.dmg *.exe *.deb *.rpm; do
+            sha256sum "$f" > "$f.sha256"
+          done
+          ls -la
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: |
+            release-assets/*.dmg
+            release-assets/*.exe
+            release-assets/*.deb
+            release-assets/*.rpm
+
       - name: Upload assets to GitHub Release
         uses: softprops/action-gh-release@v2.5.0
         with:
@@ -143,4 +185,5 @@ jobs:
             release-assets/*.exe
             release-assets/*.deb
             release-assets/*.rpm
+            release-assets/*.sha256
           generate_release_notes: true

.github/workflows/docs-site.yml

@@ -39,6 +39,11 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Install system libraries for social card rendering
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev pkg-config
+
       - name: Install docs dependencies
         run: pip install -r docs/requirements.txt
 

CHANGELOG.md

@@ -6,6 +6,40 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.0-M4] - 2026-04-27
+
+### Added
+
+- New adaptive Home dashboard with workspace status, provider health pill, recent activity, and a Getting Started checklist that mirrors the first-run flow.
+- Agentic Chat surfaces RAG search options (query, filter, top-K, similarity threshold) and emits a structured retrieval-completion event so the UI can show retrieved doc count and titles.
+- Agentic Chat anchors the new prompt at the top of the viewport on submit, labels each step with timing/counts (`RAG · {time} · {N docs} · {titles}`, `THINK · {time}`, `MCP TOOLS · {time} · {N calls} · {names}`), preserves the partial assistant response when the user clicks Stop, and shows a Stopped/Error stream-status badge that persists across reload.
+- Common workspace shell shared by Chat, MCP, Tool Studio, and Vector Database surfaces (sidebar + content header + settings drawer) for consistent layout.
+- Telemetry opt-out (`SPRING_AI_PLAYGROUND_TELEMETRY_ENABLED=false`) now applies uniformly across the web app and every desktop launcher window (splash, server-splash, config editor, Ollama manager).
+- Release assets ship with SHA-256 checksums (`.sha256`) and Sigstore build provenance attestations, verifiable via `gh attestation verify --owner spring-ai-community`.
+- Documentation site generates per-page Open Graph / Twitter social cards (1200×630) and embeds `SoftwareApplication` JSON-LD schema for richer search results.
+- Getting Started page now hosts a platform-aware download confirm popup that resolves the latest release through the GitHub API, shows filename, size, and the typical OS download path; README and the docs home redirect platform badges to the same popup.
+
+### Changed
+
+- Persistence rewritten to save on mutation through an async executor with atomic writes; `SimpleVectorStore` dumps are debounced to coalesce bursts into a single write, keeping disk-write threads non-daemon so in-flight writes finish on shutdown.
+- Generic `RuntimeException` wrapping replaced with targeted error handling; MCP startup uses sequential per-server iteration with try/catch in place of `parallelStream` to isolate failures.
+- Standardized desktop installer filenames to `spring-ai-playground-<version>-<platform>-<arch>.<ext>` (no spaces, version included). Bumped to `0.2.0-M4`. CI now resolves the installer version from the branch/tag ref and injects it into `electron/package.json` at build time.
+- Linux `.deb` / `.rpm` package metadata renamed from `spring-ai-playground-desktop` to `spring-ai-playground` for consistency with the bundle ID, binary, and user-visible app name.
+- Architecture documentation split into a dedicated page; README and mkdocs nav aligned with the new Home dashboard.
+
+### Fixed
+
+- `APP_HOME` now defaults to `<user.home>/<app-name>` when the JVM `user.home` property is unset, preventing log/config write failures in containerized environments.
+- Loopback MCP client and embedded MCP server are closed before Tomcat graceful shutdown so the JVM exits cleanly.
+- Saved persistence files are deleted immediately on removal instead of being deferred to JVM exit, eliminating stale files after a crash.
+- MCP client map keys scoped per-server, stale clients closed on update, and self-update flows allowed without orphaning the previous client.
+- Chat history reload restores `tool_calls` and matching tool responses correctly.
+- Renamed `lancher-*` documentation assets to `launcher-*` (typo fix).
+
+### Security
+
+- Persisted file names are sanitized to prevent path traversal when writing under the application home directory.
+
 ## [0.2.0-M3] - 2026-04-18
 
 ### Added

README.md

@@ -6,6 +6,8 @@ Spring AI Playground is a cross-platform desktop app for building, testing, vali
 
 > **No pass, no run.**
 
+Every tool you build earns a **Local Pass** — a local test-run with your sample arguments. Only passing tools are added live to the built-in MCP server and become callable from Agentic Chat. A tool that has not passed is never exposed to an agent.
+
 In Tool Studio, new or updated built-in tools are test-run before they are published to the built-in MCP server. You do not need to know Java, Spring, or JVM internals to use it. If you can install a desktop app and write a small JavaScript function, you can build tools here and connect them to hosts and clients such as Claude Desktop, Claude Code, Cursor, IDEs, and other MCP-compatible environments.
 
 ## The Problem
@@ -36,13 +38,13 @@ Spring AI Playground is a standalone desktop app, so you can install it and star
 
 Choose the installer for your platform from the latest release:
 
-[![Windows](https://img.shields.io/badge/Windows-NSIS%20Installer-0078D6?logo=windows&logoColor=white)](https://github.com/spring-ai-community/spring-ai-playground/releases/latest/download/Spring.AI.Playground.exe)
-[![macOS Apple Silicon](https://img.shields.io/badge/macOS-Apple%20Silicon%20arm64-000000?logo=apple&logoColor=white)](https://github.com/spring-ai-community/spring-ai-playground/releases/latest/download/Spring.AI.Playground-arm64.dmg)
-[![macOS Intel](https://img.shields.io/badge/macOS-Intel%20x64-555555?logo=apple&logoColor=white)](https://github.com/spring-ai-community/spring-ai-playground/releases/latest/download/Spring.AI.Playground-x64.dmg)
-[![Linux DEB](https://img.shields.io/badge/Linux-DEB-A81D33?logo=debian&logoColor=white)](https://github.com/spring-ai-community/spring-ai-playground/releases/latest/download/Spring.AI.Playground.deb)
-[![Linux RPM](https://img.shields.io/badge/Linux-RPM-EE0000?logo=redhat&logoColor=white)](https://github.com/spring-ai-community/spring-ai-playground/releases/latest/download/Spring.AI.Playground.rpm)
+[![Windows](https://img.shields.io/badge/Windows-NSIS%20Installer-0078D6?logo=windows&logoColor=white)](https://spring-ai-community.github.io/spring-ai-playground/getting-started/#win-x64)
+[![macOS Apple Silicon](https://img.shields.io/badge/macOS-Apple%20Silicon%20arm64-000000?logo=apple&logoColor=white)](https://spring-ai-community.github.io/spring-ai-playground/getting-started/#mac-arm64)
+[![macOS Intel](https://img.shields.io/badge/macOS-Intel%20x64-555555?logo=apple&logoColor=white)](https://spring-ai-community.github.io/spring-ai-playground/getting-started/#mac-x64)
+[![Linux DEB](https://img.shields.io/badge/Linux-DEB-A81D33?logo=debian&logoColor=white)](https://spring-ai-community.github.io/spring-ai-playground/getting-started/#linux-deb)
+[![Linux RPM](https://img.shields.io/badge/Linux-RPM-EE0000?logo=redhat&logoColor=white)](https://spring-ai-community.github.io/spring-ai-playground/getting-started/#linux-rpm)
 
-Or browse all available assets on the [Releases page](https://github.com/spring-ai-community/spring-ai-playground/releases).
+The Getting Started page resolves to the latest published release automatically. The downloaded file keeps the version in its name (e.g. `spring-ai-playground-0.2.0-M4-mac-arm64.dmg`). Or browse all available assets on the [Releases page](https://github.com/spring-ai-community/spring-ai-playground/releases).
 
 ### 2. Install and Launch
 
@@ -80,6 +82,30 @@ If you install the app, you can run Spring AI Playground immediately without set
 >
 > For more detailed platform guidance, see the [Getting Started guide](https://spring-ai-community.github.io/spring-ai-playground/getting-started/).
 
+### Verify Your Download
+
+Each release ships with two integrity guarantees. You do not have to verify, but it is recommended for production use.
+
+**1. SHA-256 checksum** — every installer has a matching `.sha256` file in the release assets.
+
+```bash
+# macOS / Linux
+shasum -a 256 -c spring-ai-playground-0.2.0-M4-mac-arm64.dmg.sha256
+
+# Windows (PowerShell)
+Get-FileHash spring-ai-playground-0.2.0-M4-win-x64.exe -Algorithm SHA256
+# compare the value with the one inside the .sha256 file
+```
+
+**2. Sigstore build provenance (SLSA)** — every installer is signed by the official GitHub Actions release workflow using a short-lived Sigstore key, and the attestation is recorded in the public transparency log.
+
+```bash
+gh attestation verify spring-ai-playground-0.2.0-M4-mac-arm64.dmg \
+  --owner spring-ai-community
+```
+
+A successful verification proves the file came from this repo's release workflow and was not tampered with after build.
+
 <p align="center">
   <b>First-Launch Configuration Screen</b><br/>
   Desktop launcher overview with the built-in config editor
@@ -97,8 +123,8 @@ If you install the app, you can run Spring AI Playground immediately without set
 </p>
 
 <p align="center">
-  <a href="docs/assets/images/lancher-ollama-config.png">
-    <img src="docs/assets/images/lancher-ollama-config.png" width="760" alt="Spring AI Playground Ollama model manager"/>
+  <a href="docs/assets/images/launcher-ollama-config.png">
+    <img src="docs/assets/images/launcher-ollama-config.png" width="760" alt="Spring AI Playground Ollama model manager"/>
   </a>
 </p>
 
@@ -205,6 +231,23 @@ We triage issues regularly, and issues outside the current scope may be closed w
 
 If you believe you have a contribution that fits the current scope, submit a PR or a targeted issue.
 
+## Anonymous Usage Telemetry
+
+The official build sends anonymous usage data (page views, app surface, device/browser
+info) to the maintainer's Google Tag Manager / Google Analytics account so the most-used
+features can be prioritized. IPs are anonymized by Google. The same opt-out switch applies
+to both the web app and every desktop launcher window (splash, server-splash, config
+editor, Ollama manager):
+
+- **Server / Docker / `mvn`**: `SPRING_AI_PLAYGROUND_TELEMETRY_ENABLED=false`
+- **Desktop launcher**: set `SPRING_AI_PLAYGROUND_TELEMETRY_ENABLED=false` before launching
+  the app (the launcher forwards this env var to every window and to the bundled Spring
+  process)
+- **From source / IDE**: pass `-Dspring.ai.playground.telemetry.enabled=false` as a JVM arg
+
+If you self-host this project for EU users, adding cookie consent on top is the
+operator's responsibility under GDPR.
+
 ## Upcoming Improvements
 
 These are the near-term areas we plan to improve while keeping the project focused on practical, reusable tool execution.

docs-overrides/main.html

@@ -2,11 +2,25 @@
 
 {% block extrahead %}
   {{ super() }}
+  <script>
+    // Material renders mermaid diagrams inside closed shadow DOM, which blocks
+    // our pan/zoom hook and any label-wrapping CSS. Force open mode only for
+    // .mermaid hosts so we can reach into the shadow root from our own JS/CSS.
+    (function () {
+      var orig = Element.prototype.attachShadow;
+      Element.prototype.attachShadow = function (init) {
+        if (this.classList && this.classList.contains('mermaid')) {
+          return orig.call(this, Object.assign({}, init || {}, { mode: 'open' }));
+        }
+        return orig.call(this, init);
+      };
+    })();
+  </script>
   {% set ga_measurement_id = "G-52TGT1G9B3" %}
   {% set page_title = page.title ~ " - " ~ config.site_name if page and page.title else config.site_name %}
+  {% set ga_page_title = "Doc - " ~ page.title if page and page.title else "Doc - " ~ config.site_name %}
   {% set page_description = page.meta.description if page and page.meta and page.meta.description else config.site_description %}
   {% set page_url = config.site_url ~ page.url if page and page.url else config.site_url %}
-  {% set social_image = config.site_url ~ "assets/images/icon.png" %}
   <script async src="https://www.googletagmanager.com/gtag/js?id={{ ga_measurement_id }}"></script>
   <script>
     window.dataLayer = window.dataLayer || [];
@@ -17,18 +31,37 @@
     });
     gtag('config', '{{ ga_measurement_id }}', {
       app_name: 'spring-ai-playground-docs',
-      app_surface: 'docs'
+      app_surface: 'docs',
+      page_title: '{{ ga_page_title | e }}'
     });
   </script>
-  <link rel="canonical" href="{{ page_url | e }}">
+  {# Open Graph and Twitter Card meta — kept here as a fallback when the
+     mkdocs-material `social` plugin is not active (e.g. local dev without
+     the imaging extras). When the plugin runs, it injects its own og:image
+     and twitter:image with a generated 1200x630 card; browsers honor the
+     first occurrence, so we keep these tags AFTER plugin injection points.
+     The canonical link is already produced by mkdocs-material's base
+     template from `site_url`, so we do not duplicate it here. #}
   <meta property="og:site_name" content="{{ config.site_name | e }}">
   <meta property="og:type" content="website">
   <meta property="og:title" content="{{ page_title | e }}">
   <meta property="og:description" content="{{ page_description | e }}">
   <meta property="og:url" content="{{ page_url | e }}">
-  <meta property="og:image" content="{{ social_image | e }}">
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="{{ page_title | e }}">
   <meta name="twitter:description" content="{{ page_description | e }}">
-  <meta name="twitter:image" content="{{ social_image | e }}">
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "SoftwareApplication",
+    "name": "{{ config.site_name | e }}",
+    "applicationCategory": "DeveloperApplication",
+    "operatingSystem": "macOS, Windows, Linux",
+    "url": "{{ config.site_url | e }}",
+    "downloadUrl": "https://github.com/spring-ai-community/spring-ai-playground/releases/latest",
+    "license": "https://www.apache.org/licenses/LICENSE-2.0",
+    "description": "{{ config.site_description | e }}",
+    "offers": {"@type": "Offer", "price": "0", "priceCurrency": "USD"}
+  }
+  </script>
 {% endblock %}