feat(astrolabe): add Nextcloud App Store deployment automation

Add complete CI/CD pipeline for automated Astrolabe app releases: - GitHub Actions workflow for build, sign, and publish - Makefile for app store package creation - Version synchronization between info.xml and package.json - CHANGELOG.md with v0.1.0 release notes feat: configure commitizen monorepo with independent versioning Enable independent versioning for three components using scope-based commits: - MCP Server (feat(mcp) or unscoped): v* tags, updates pyproject.toml + Chart.yaml:appVersion - Helm Chart (feat(helm)): nextcloud-mcp-server-* tags, updates Chart.yaml:version - Astrolabe App (feat(astrolabe)): astrolabe-v* tags, updates info.xml + package.json Changes: - Add .cz.toml configs for Astrolabe and Helm chart - Update root pyproject.toml with scope filtering and tag ignores - Create bump helper scripts (bump-mcp.sh, bump-helm.sh, bump-astrolabe.sh) - Add CONTRIBUTING.md with version management documentation - Create component-specific changelogs - Configure appVersion/version separation for Helm chart This allows each component to release independently while maintaining proper version tracking and changelog generation.
2025-12-19 18:06:39 +01:00
parent 46b260641f
commit 4a42b947bc
14 changed files with 429 additions and 8 deletions
@@ -0,0 +1,84 @@
+name: Build and Publish Astrolabe App Release
+
+on:
+  release:
+    types: [published]
+
+env:
+  APP_NAME: astrolabe
+  APP_DIR: third_party/astrolabe
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Get version from tag
+        id: tag
+        run: |
+          echo "TAG=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Validate version in info.xml matches tag
+        working-directory: ${{ env.APP_DIR }}
+        run: |
+          INFO_VERSION=$(sed -n 's/.*<version>\(.*\)<\/version>.*/\1/p' appinfo/info.xml | tr -d '\t')
+          if [ "$INFO_VERSION" != "${{ steps.tag.outputs.TAG }}" ]; then
+            echo "Version mismatch: info.xml has $INFO_VERSION but tag is ${{ steps.tag.outputs.TAG }}"
+            exit 1
+          fi
+          echo "Version validated: $INFO_VERSION"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.1
+          coverage: none
+
+      - name: Checkout Nextcloud server (for signing)
+        uses: actions/checkout@v4
+        with:
+          repository: nextcloud/server
+          ref: stable30
+          path: server
+
+      - name: Install dependencies and build
+        working-directory: ${{ env.APP_DIR }}
+        run: |
+          composer install --no-dev --optimize-autoloader
+          npm ci
+          npm run build
+
+      - name: Setup signing certificate
+        run: |
+          mkdir -p $HOME/.nextcloud/certificates
+          echo "${{ secrets.APP_PRIVATE_KEY }}" > $HOME/.nextcloud/certificates/${{ env.APP_NAME }}.key
+          echo "${{ secrets.APP_PUBLIC_CRT }}" > $HOME/.nextcloud/certificates/${{ env.APP_NAME }}.crt
+
+      - name: Build app store package
+        working-directory: ${{ env.APP_DIR }}
+        run: make appstore
+
+      - name: Attach tarball to GitHub release
+        uses: svenstaro/upload-release-action@v2
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          file: ${{ env.APP_DIR }}/build/artifacts/${{ env.APP_NAME }}.tar.gz
+          asset_name: ${{ env.APP_NAME }}-${{ steps.tag.outputs.TAG }}.tar.gz
+          tag: ${{ github.ref }}
+
+      - name: Upload to Nextcloud App Store
+        uses: R0Wi/nextcloud-appstore-push-action@v1.0.6
+        with:
+          app_name: ${{ env.APP_NAME }}
+          appstore_token: ${{ secrets.APPSTORE_TOKEN }}
+          download_url: ${{ github.server_url }}/${{ github.repository }}/releases/download/${{ github.ref_name }}/${{ env.APP_NAME }}-${{ steps.tag.outputs.TAG }}.tar.gz
+          app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
+          nightly: ${{ github.event.release.prerelease }}
@@ -1,3 +1,10 @@
+# Changelog - MCP Server
+
+All notable changes to the Nextcloud MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [PEP 440](https://peps.python.org/pep-0440/).
+
 ## v0.53.0 (2025-12-19)

 ### Feat
@@ -0,0 +1,116 @@
+# Contributing to Nextcloud MCP Server
+
+## Version Management
+
+This monorepo uses commitizen for version management with **independent versioning** for three components:
+
+### Components
+
+| Component | Scope | Bump Command | Tag Example |
+|-----------|-------|--------------|-------------|
+| MCP Server | `mcp` or none | `./scripts/bump-mcp.sh` | `v0.54.0` |
+| Helm Chart | `helm` | `./scripts/bump-helm.sh` | `nextcloud-mcp-server-0.54.0` |
+| Astrolabe App | `astrolabe` | `./scripts/bump-astrolabe.sh` | `astrolabe-v0.2.0` |
+
+### Commit Message Format
+
+Use conventional commits with **scopes** to target specific components:
+
+```bash
+# MCP server changes
+feat(mcp): add calendar sync API
+fix(mcp): resolve authentication bug
+
+# Helm chart changes
+feat(helm): add resource limits
+docs(helm): update values documentation
+
+# Astrolabe app changes
+feat(astrolabe): add dark mode toggle
+fix(astrolabe): resolve search UI bug
+```
+
+**Unscoped commits** default to the MCP server:
+```bash
+feat: add new feature  # → MCP server (v0.54.0)
+```
+
+### Release Workflow
+
+#### 1. Make Changes with Scoped Commits
+
+```bash
+git commit -m "feat(astrolabe): add dark mode toggle"
+git commit -m "feat(helm): add ingress annotations"
+git commit -m "feat(mcp): add calendar sync"
+```
+
+#### 2. Bump Component Versions
+
+```bash
+# Bump MCP server (reads commits with scope=mcp or unscoped)
+./scripts/bump-mcp.sh
+# → Creates tag: v0.54.0
+# → Updates: pyproject.toml, Chart.yaml:appVersion
+
+# Bump Helm chart (reads commits with scope=helm)
+./scripts/bump-helm.sh
+# → Creates tag: nextcloud-mcp-server-0.54.0
+# → Updates: Chart.yaml:version
+
+# Bump Astrolabe (reads commits with scope=astrolabe)
+./scripts/bump-astrolabe.sh
+# → Creates tag: astrolabe-v0.2.0
+# → Updates: info.xml, package.json
+```
+
+#### 3. Push Tags
+
+```bash
+git push --follow-tags
+```
+
+### Changelog Filtering
+
+Each component maintains its own `CHANGELOG.md`:
+
+- **MCP Server**: `CHANGELOG.md` (root) - includes `feat(mcp):` and unscoped commits
+- **Helm Chart**: `charts/nextcloud-mcp-server/CHANGELOG.md` - includes `feat(helm):` only
+- **Astrolabe**: `third_party/astrolabe/CHANGELOG.md` - includes `feat(astrolabe):` only
+
+### Manual Version Bumps
+
+For specific increments:
+
+```bash
+# Patch bump (0.53.0 → 0.53.1)
+uv run cz bump --increment PATCH
+
+# Minor bump (0.53.0 → 0.54.0)
+uv run cz bump --increment MINOR
+
+# Major bump (0.53.0 → 1.0.0)
+uv run cz bump --increment MAJOR
+
+# For non-MCP components, use --config
+cd charts/nextcloud-mcp-server
+uv run cz --config .cz.toml bump --increment MINOR
+```
+
+### Versioning Philosophy
+
+- **MCP Server**: Follows PEP 440, `major_version_zero = true` (0.x.x for pre-1.0)
+- **Helm Chart**: Follows PEP 440, starts at 0.53.0 (continues from current)
+- **Astrolabe**: Follows PEP 440, `major_version_zero = true` (0.x.x for alpha/beta)
+
+### Chart.yaml Version vs appVersion
+
+The Helm chart has TWO version fields:
+
+- **`version`**: Chart packaging version (bumped by `feat(helm):`)
+  - Example: `0.53.0` → `0.54.0` when adding resource limits
+
+- **`appVersion`**: MCP server version being deployed (bumped by `feat(mcp):`)
+  - Example: `"0.53.0"` → `"0.54.0"` when MCP server releases
+
+This allows the chart to evolve independently from the application.
@@ -0,0 +1,24 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.53.0"
+tag_format = "nextcloud-mcp-server-$version"
+version_scheme = "pep440"
+update_changelog_on_bump = true
+major_version_zero = true
+
+# Update chart version only (NOT appVersion)
+version_files = [
+    "Chart.yaml:^version:"
+]
+
+# Ignore tags from other components
+ignored_tag_formats = [
+    "v*",              # MCP server tags
+    "astrolabe-v*",    # Astrolabe tags
+]
+
+# Filter commits by scope
+[tool.commitizen.customize]
+changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:"
+schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:\\s.+"
+message_template = "{{change_type}}(helm): {{message}}"
@@ -0,0 +1,18 @@
+# Changelog - Helm Chart
+
+All notable changes to the Helm chart will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.53.0] - 2024-12-19
+
+### Added
+- Initial independent versioning release
+- Support for Nextcloud MCP server deployment
+- Qdrant subchart integration
+- Ollama subchart integration
+- Configurable resource limits
+- Grafana dashboard annotations
@@ -89,14 +89,23 @@ version_scheme = "pep440"
 version_provider = "uv"
 update_changelog_on_bump = true
 major_version_zero = true
+
+# MCP server version files + Helm appVersion
 version_files = [
-    "charts/nextcloud-mcp-server/Chart.yaml:appVersion",
-    "charts/nextcloud-mcp-server/Chart.yaml:version"
+    "charts/nextcloud-mcp-server/Chart.yaml:^appVersion:",
 ]
+
+# Ignore tags from other components
 ignored_tag_formats = [
-    "nextcloud-mcp-server-*"
+    "nextcloud-mcp-server-*",  # Helm chart tags
+    "astrolabe-v*",            # Astrolabe tags
 ]

+# Filter commits by scope (mcp or unscoped)
+[tool.commitizen.customize]
+changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(\\(mcp\\))?(!)?:"
+schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(\\(mcp\\))?(!)?:\\s.+"
+
 [tool.ruff.lint]
 extend-select = ["I"]

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Bump Astrolabe app version
+set -e
+
+cd third_party/astrolabe
+
+echo "Bumping Astrolabe version..."
+uv run cz --config .cz.toml bump --yes
+
+echo "✓ Astrolabe version bumped"
+echo "  - Updated: appinfo/info.xml, package.json"
+echo "  - Tag format: astrolabe-v\${version}"
+
+cd ../..
@@ -0,0 +1,15 @@
+#!/bin/bash
+# Bump Helm chart version
+set -e
+
+cd charts/nextcloud-mcp-server
+
+echo "Bumping Helm chart version..."
+uv run cz --config .cz.toml bump --yes
+
+echo "✓ Helm chart version bumped"
+echo "  - Updated: Chart.yaml:version"
+echo "  - Tag format: nextcloud-mcp-server-\${version}"
+echo "  - Note: appVersion stays at MCP server version"
+
+cd ../..
@@ -0,0 +1,10 @@
+#!/bin/bash
+# Bump MCP server version
+set -e
+
+echo "Bumping MCP server version..."
+uv run cz bump --yes
+
+echo "✓ MCP server version bumped"
+echo "  - Updated: pyproject.toml, Chart.yaml:appVersion"
+echo "  - Tag format: v\${version}"
@@ -0,0 +1,25 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.1.0"
+tag_format = "astrolabe-v$version"
+version_scheme = "pep440"
+update_changelog_on_bump = true
+major_version_zero = true
+
+# Update Astrolabe-specific files only
+version_files = [
+    "appinfo/info.xml:version",
+    "package.json:version"
+]
+
+# Ignore tags from other components
+ignored_tag_formats = [
+    "v*",                      # MCP server tags
+    "nextcloud-mcp-server-*",  # Helm chart tags
+]
+
+# Filter commits by scope
+[tool.commitizen.customize]
+changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(astrolabe\\)(!)?:"
+schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(astrolabe\\)(!)?:\\s.+"
+message_template = "{{change_type}}(astrolabe): {{message}}"
@@ -8,6 +8,7 @@
 /tests/.phpunit.cache

 dist/
+build/
 node_modules/
 js/
 css/
@@ -1,12 +1,29 @@
-# Changelog
+# Changelog - Astrolabe

-All notable changes to this project will be documented in this file.
+All notable changes to the Astrolabe Nextcloud app will be documented in this file.

-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

 ## [Unreleased]

+## [0.1.0] - 2024-12-19
+
 ### Added

- First release
+- Initial alpha release
+- Semantic search across Notes, Files, Calendar, Deck, and Contacts
+- Integration with Nextcloud Unified Search
+- Personal settings UI for MCP server configuration
+- Admin settings for global MCP server URL
+- OAuth PKCE authentication flow
+- Vector visualization of semantic relationships
+- Hybrid search combining semantic and keyword matching
+- Background content indexing
+- Support for Nextcloud 30-32
+
+### Notes
+
+- This is an alpha release intended for early adopters and testing
+- Requires external MCP server deployment
+- See documentation for setup: https://github.com/cbcoutinho/nextcloud-mcp-server
@@ -0,0 +1,81 @@
+# Nextcloud App Store Release Makefile for Astrolabe
+#
+# Based on: https://nextcloudappstore.readthedocs.io/en/latest/developer.html
+
+app_name=astrolabe
+project_dir=$(CURDIR)
+build_dir=$(project_dir)/build
+appstore_dir=$(build_dir)/artifacts
+package_name=$(appstore_dir)/$(app_name)
+cert_dir=$(HOME)/.nextcloud/certificates
+
+# Signing
+private_key=$(cert_dir)/$(app_name).key
+certificate=$(cert_dir)/$(app_name).crt
+sign_cmd=php ../../server/occ integrity:sign-app --privateKey=$(private_key) --certificate=$(certificate)
+
+# Clean build artifacts
+.PHONY: clean
+clean:
+	rm -rf $(build_dir)
+
+# Install PHP and Node dependencies
+.PHONY: install-deps
+install-deps:
+	composer install --no-dev --optimize-autoloader
+	npm ci
+
+# Build production frontend assets
+.PHONY: build-frontend
+build-frontend:
+	npm run build
+
+# Run all linters
+.PHONY: lint
+lint:
+	composer lint
+	composer cs:check
+	npm run lint
+	npm run stylelint
+
+# Assemble app files into build directory (exclude dev files)
+.PHONY: assemble
+assemble: clean install-deps build-frontend
+	mkdir -p $(package_name)
+	# Copy app files
+	rsync -av \
+		--exclude='.git*' \
+		--exclude='build/' \
+		--exclude='tests/' \
+		--exclude='node_modules/' \
+		--exclude='*.log' \
+		--exclude='.github/' \
+		--exclude='composer.json' \
+		--exclude='composer.lock' \
+		--exclude='package.json' \
+		--exclude='package-lock.json' \
+		--exclude='vite.config.js' \
+		--exclude='.eslintrc.js' \
+		--exclude='.php-cs-fixer.*' \
+		--exclude='psalm.xml' \
+		--exclude='*.iml' \
+		--exclude='.idea' \
+		--exclude='src/' \
+		./ $(package_name)/
+
+# Create signed release tarball for App Store
+.PHONY: appstore
+appstore: assemble
+	# Sign the app
+	$(sign_cmd) --path=$(package_name)
+	# Create tarball
+	cd $(appstore_dir) && \
+		tar -czf $(app_name).tar.gz $(app_name)
+	# Show package info
+	@echo "========================================="
+	@echo "App package created:"
+	@echo "  $(appstore_dir)/$(app_name).tar.gz"
+	@echo ""
+	@echo "Signature:"
+	@cat $(package_name)/appinfo/signature.json | head -n 5
+	@echo "========================================="
@@ -1,6 +1,6 @@
 {
  "name": "astrolabe",
-  "version": "1.0.0",
+  "version": "0.1.0",
  "license": "AGPL-3.0-or-later",
  "engines": {
    "node": "^22.0.0",