Version 0.56.0

.dockerignore

@@ -1,4 +1,24 @@
-**/dist
-**/node_modules
-**/build
-**/.cache
+# Local dev files
+node_modules
+dist
+.env*
+.git
+.gitignore
+.vscode
+.idea
+
+# Tests
+backend/tests
+!backend/tests/actions/file-hash
+packages/*/tests
+**/*.test.ts
+**/*.spec.ts
+junit.xml
+coverage
+
+# Backend specific
+backend/tsconfig.tsbuildinfo
+backend/npm-debug.log*
+backend/yarn-debug.log*
+backend/yarn-error.log*
+backend/pnpm-debug.log*

.env

@@ -1,8 +1,8 @@
 SERVER_PORT=3000
-QUASAR_ENDPOINT=http://localhost:3000
 
 FRONTEND_URL=http://localhost:8003
 DOCS_URL=http://localhost:4000
+BACKEND_URL=http://localhost:3000
 
 MINIO_USER=minioadmin
 MINIO_PASSWORD=minioadmin
@@ -13,6 +13,7 @@ MINIO_DB_BUCKET_NAME=dbdumps
 MINIO_ARTIFACTS_BUCKET_NAME=artifacts
 MINIO_ENDPOINT=localhost
 
+
 DB_HOST=database
 DEV=true
 DB_DATABASE=dbname
@@ -26,18 +27,20 @@ ENTITIES=dist/**/*.entity.js
 SEED=true
 
 VITE_USE_FAKE_OAUTH_FOR_DEVELOPMENT=true
-GOOGLE_KEY_FILE=grandtourdatasets-5295745f7fab.json
-GOOGLE_CLIENT_ID=237481987385-av4suqf7p0qjkmvjo8bc6jdf3g6nb0u7.apps.googleusercontent.com
-GOOGLE_CLIENT_SECRET=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
+GOOGLE_KEY_FILE=google-service-account.json
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
 JWT_SECRET=SECRET
 
 # this should be replaced with your own oauth credentials
-GITHUB_CLIENT_ID=some-client-id
-GITHUB_CLIENT_SECRET=some-client-secret
+GOOGLE_CLIENT_ID=237481987385-av4suqf7p0qjkmvjo8bc6jdf3g6nb0u7.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=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
 
-# can be left empty if you don't want to use docker hub
 DOCKER_HUB_USERNAME=
 DOCKER_HUB_PASSWORD=
 VITE_DOCKER_HUB_NAMESPACE=
 
-ARTIFACTS_UPLOADER_IMAGE=rslethz/grandtour-datasets:artifact-uploader-latest
+ARTIFACTS_UPLOADER_IMAGE=rslethz/kleinkram:artifact-uploader-latest
+
+# Docker socket group ID (run: stat -c '%g' /var/run/docker.sock)
+DOCKER_GID=984

.github/AGENTS.md

@@ -0,0 +1,113 @@
+# AI Agent Instructions
+
+This document provides a quick reference for AI agents working on the Kleinkram project. For detailed information, always refer to the official documentation in the `../docs/` directory.
+
+## 🚀 Quick Start (Launch)
+
+To launch the full application stack:
+
+```bash
+docker compose up --build --watch -d
+```
+
+**Access Points:**
+
+- **API Server**: [http://localhost:3000](http://localhost:3000)
+- **Frontend**: [http://localhost:8003](http://localhost:8003)
+- **MinIO Console**: [http://localhost:9001](http://localhost:9001)
+- **Documentation**: [http://localhost:4000](http://localhost:4000)
+
+> [!NOTE]
+> See [../docs/development/getting-started.md](../docs/development/getting-started.md) for detailed setup instructions.
+
+## 🛠️ Development Workflow
+
+### API Interaction
+
+**IMPORTANT**: All API calls to the backend must include the `kleinkram-client-version` header matching the current app version (e.g., `0.56.0`).
+
+```typescript
+headers: {
+    'kleinkram-client-version': '0.56.0', // Replace with actual version from package.json
+    ...
+}
+```
+
+**Exception:** The `/api/health` endpoint does not require this header.
+
+### Formatting & Linting
+
+Run these commands before submitting changes:
+
+```bash
+# Format Python code
+black .
+
+# Format TypeScript/JavaScript/JSON/Markdown
+yarn run prettier
+
+# Run Linting
+yarn run eslint-full:quiet
+```
+
+### Testing
+
+**Backend Tests:**
+
+```bash
+# Run all tests
+yarn test
+
+# Run specific test file
+npx jest tests/actions/action-file-events.test.ts --runInBand --detectOpenHandles --forceExit
+```
+
+**CLI/Python Tests:**
+
+```bash
+# Run pytest (ensure virtualenv is active)
+pytest
+```
+
+> [!NOTE]
+> See [../docs/development/testing/getting-started.md](../docs/development/testing/getting-started.md) for detailed testing guide.
+
+## 📚 Documentation Reference
+
+- **General Setup**: [../docs/development/getting-started.md](../docs/development/getting-started.md)
+- **Testing**: [../docs/development/testing/getting-started.md](../docs/development/testing/getting-started.md)
+- **Python/CLI**: [../docs/development/python/getting-started.md](../docs/development/python/getting-started.md)
+
+## 🧪 Test Naming Conventions
+
+To ensure consistency and readability, please adhere to the following naming conventions for test files and test cases:
+
+### File Naming
+
+- **Format**: `kebab-case.test.ts`
+- **Location**: `tests/<component>/` or `tests/functional/`
+- **Examples**:
+    - `user-authentication.test.ts`
+    - `file-upload.test.ts`
+    - `action-execution.test.ts`
+
+### Test Suite Naming (`describe`)
+
+- **Format**: Title Case or Sentence case describing the component or feature under test.
+- **Examples**:
+    - `describe('User Authentication', ...)`
+    - `describe('File Upload Service', ...)`
+
+### Test Case Naming (`test` / `it`)
+
+- **Format**: Should start with a verb (e.g., "should", "if") and describe the expected behavior or scenario.
+- **Style**:
+    - **"should" style**: `test('should return 200 OK when valid credentials are provided', ...)`
+    - **"if" style**: `test('if a user can view details of a submitted action', ...)`
+- **Clarity**: Be specific about the condition and the expected result.
+
+### General Rules
+
+- Keep tests focused on a single behavior.
+- Use descriptive variable names within tests.
+- Clean up resources in `afterEach` or `afterAll` to prevent state leakage.

.github/workflows/test.yml → .github/workflows/api-tests.yml

@@ -8,59 +8,85 @@ on:
             - dev
 
 jobs:
-    test_API:
+    test-api:
         runs-on: [self-hosted, linux]
 
-        # Permissions reduced since we are no longer posting comments/checks
         permissions:
             contents: read
 
         steps:
-            - uses: actions/checkout@v5
+            - uses: actions/checkout@v6
+
+            - uses: pnpm/action-setup@v4
+              with:
+                  run_install: false
 
             - name: Use Node.js
               uses: actions/setup-node@v6
               with:
                   node-version: '22'
-                  package-manager-cache: false
-
-            - name: Install yarn
-              run: npm install -g yarn
+                  cache: 'pnpm'
 
             - name: install dependencies
-              run: yarn install --immutable
+              run: pnpm install --frozen-lockfile
+
+            - name: Build workspace packages
+              run: pnpm -r run build
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: '3.10'
+
+            - name: Generate test data
+              run: |
+                  pip install rosbags
+                  python3 cli/tests/generate_test_data.py
 
             - name: build_stack
               run: docker compose -f docker-compose.testing.yml build
+              env:
+                  BACKEND_URL: 'http://localhost:3000'
+                  GIT_BRANCH: ${{ github.head_ref || github.ref_name }}
+                  GIT_COMMIT: ${{ github.sha }}
 
             - name: clear previous volumes
               run: docker compose -f docker-compose.testing.yml down -v
 
+            - name: Pre-generate endpoints
+              working-directory: ./backend
+              run: |
+                  mkdir -p .endpoints
+                  npm run gen:docs -- .endpoints
+
             - name: launch_stack
               working-directory: ./backend
               run: |
                   docker compose -f ../docker-compose.testing.yml up -d
                   SECONDS=0
                   TIMEOUT=180
-                  while [ ! -f ./.endpoints/__generated__endpoints.json ]; do
+                  # wait for the api to be reachable
+                  while ! curl -s http://localhost:3000/ > /dev/null; do
                     if [ $SECONDS -ge $TIMEOUT ]; then
-                        echo "Timeout reached: __generated__endpoints.json not found"
+                        echo "Timeout reached: API not reachable"
+                        docker logs kleinkram-api-server-test
                         docker compose -f ../docker-compose.testing.yml down
                         exit 1
                     fi
                     sleep 1
-                    echo "waiting for endpoints"
+                    echo "waiting for API to be reachable..."
                   done
-                  echo "Endpoints found. Running tests..."
+
+                  echo "API is up. Running tests..."
 
                   # This will now cause the step to fail immediately if tests fail.
-                  yarn test --ci
+                  pnpm test --ci
 
                   echo "Tests passed successfully."
 
             - name: Clean up
               if: always()
-              run: npm uninstall -g yarn
+              run: echo "Cleanup done"
 
             - name: Stop Docker stack
               if: always()

.github/workflows/build-sample-actions.yml

@@ -0,0 +1,67 @@
+name: Build Sample Actions
+
+on:
+    workflow_dispatch:
+        inputs:
+            kleinkram_version:
+                description: 'Kleinkram version to install'
+                required: false
+                default: ''
+    workflow_run:
+        workflows: ['Update PyPI']
+        types:
+            - completed
+    push:
+        paths:
+            - 'examples/kleinkram-actions/**'
+
+jobs:
+    build-and-push:
+        runs-on: ubuntu-latest
+        if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
+        strategy:
+            matrix:
+                action:
+                    [
+                        validate-data,
+                        extract-metadata,
+                        convert-formats,
+                        python-template,
+                    ]
+                type: [dev, prod]
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v3
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v2
+
+            - name: Login to Docker Hub
+              uses: docker/login-action@v2
+              with:
+                  username: ${{ secrets.DOCKERHUB_USERNAME }}
+                  password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+            - name: Determine Tag
+              id: tag
+              run: |
+                  if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+                    echo "tag=dev" >> $GITHUB_OUTPUT
+                    echo "kleinkram_version=${{ inputs.kleinkram_version }}" >> $GITHUB_OUTPUT
+                  elif [ "${{ matrix.type }}" == "dev" ]; then
+                    echo "tag=dev" >> $GITHUB_OUTPUT
+                    echo "kleinkram_version=" >> $GITHUB_OUTPUT # Installs latest from PyPI which is updated by Update PyPI workflow
+                  else
+                    echo "tag=latest" >> $GITHUB_OUTPUT
+                    echo "kleinkram_version=" >> $GITHUB_OUTPUT # Installs latest from PyPI
+                  fi
+
+            - name: Build and push
+              uses: docker/build-push-action@v4
+              with:
+                  context: examples/kleinkram-actions/${{ matrix.action }}
+                  push: true
+                  tags: rslethz/action:${{ matrix.action }}-${{ steps.tag.outputs.tag }}
+                  build-args: |
+                      KLEINKRAM_VERSION=${{ steps.tag.outputs.kleinkram_version }}

.github/workflows/check-migrations.yml

@@ -0,0 +1,32 @@
+name: Check Migrations
+
+on:
+    pull_request:
+        branches:
+            - main
+
+jobs:
+    check-migrations:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+
+            - name: Install pnpm
+              uses: pnpm/action-setup@v2
+              with:
+                  version: 10
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: '22'
+                  cache: 'pnpm'
+
+            - name: Install dependencies
+              run: pnpm install --frozen-lockfile
+              working-directory: backend
+
+            - name: Check migrations
+              run: pnpm run migration:check
+              working-directory: backend