ci(cpp-tui): add lint, build and integration test

.github/workflows/cpp-tui-ci.yml

@@ -0,0 +1,148 @@
+name: C++ TUI CI
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'cpp-tui/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'cpp-tui/**'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang-format
+
+      - name: Run clang-format check
+        working-directory: cpp-tui/taskscpp
+        run: |
+          make format
+          if ! git diff --exit-code; then
+            echo "❌ Code style issues found. Run 'make format' to fix."
+            exit 1
+          fi
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: lint
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake clang build-essential
+
+      - name: Create .env file
+        run: |
+          echo "DITTO_APP_ID=${{ secrets.DITTO_APP_ID }}" > .env
+          echo "DITTO_PLAYGROUND_TOKEN=${{ secrets.DITTO_PLAYGROUND_TOKEN }}" >> .env
+          echo "DITTO_AUTH_URL=${{ secrets.DITTO_AUTH_URL }}" >> .env
+          echo "DITTO_WEBSOCKET_URL=${{ secrets.DITTO_WEBSOCKET_URL }}" >> .env
+
+      - name: Download and setup Ditto C++ SDK
+        working-directory: cpp-tui/taskscpp
+        run: make download-sdk
+
+      - name: Build application
+        working-directory: cpp-tui/taskscpp
+        run: |
+          awk -f scripts/generate_env.awk ../../.env > src/env.h
+          make build
+
+  integration-test:
+    name: Integration Test
+    runs-on: ubuntu-latest
+    needs: [lint, build]
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake clang build-essential
+
+      - name: Create .env file
+        run: |
+          echo "DITTO_APP_ID=${{ secrets.DITTO_APP_ID }}" > .env
+          echo "DITTO_PLAYGROUND_TOKEN=${{ secrets.DITTO_PLAYGROUND_TOKEN }}" >> .env
+          echo "DITTO_AUTH_URL=${{ secrets.DITTO_AUTH_URL }}" >> .env
+          echo "DITTO_WEBSOCKET_URL=${{ secrets.DITTO_WEBSOCKET_URL }}" >> .env
+
+      - name: Insert test document into Ditto Cloud
+        run: |
+          TIMESTAMP=$(date +%s)
+          INVERTED_TIMESTAMP=$((9999999999 - TIMESTAMP))
+          DOC_ID="${INVERTED_TIMESTAMP}_ci_test_${GITHUB_RUN_ID}_${GITHUB_RUN_NUMBER}"
+          DOC_TITLE="${INVERTED_TIMESTAMP}_ci_test_${GITHUB_RUN_ID}_${GITHUB_RUN_NUMBER}"
+
+          RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
+            -H 'Content-type: application/json' \
+            -H "Authorization: Bearer ${{ secrets.DITTO_API_KEY }}" \
+            -d "{
+              \"statement\": \"INSERT INTO tasks DOCUMENTS (:newTask) ON ID CONFLICT DO UPDATE\",
+              \"args\": {
+                \"newTask\": {
+                  \"_id\": \"${DOC_ID}\",
+                  \"title\": \"${DOC_TITLE}\",
+                  \"done\": false,
+                  \"deleted\": false
+                }
+              }
+            }" \
+          "https://${{ secrets.DITTO_API_URL }}/api/v4/store/execute")
+
+          HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+          BODY=$(echo "$RESPONSE" | head -n-1)
+
+          if [ "$HTTP_CODE" -eq 200 ] || [ "$HTTP_CODE" -eq 201 ]; then
+            echo "GITHUB_TEST_DOC_TITLE=${DOC_TITLE}" >> $GITHUB_ENV
+          else
+            echo "❌ Failed to insert document. HTTP Status: $HTTP_CODE"
+            echo "Response: $BODY"
+            exit 1
+          fi
+
+      - name: Download and setup Ditto C++ SDK
+        working-directory: cpp-tui/taskscpp
+        run: make download-sdk
+
+      - name: Build and run integration test
+        working-directory: cpp-tui/taskscpp
+        env:
+          GITHUB_TEST_DOC_TITLE: ${{ env.GITHUB_TEST_DOC_TITLE }}
+          GITHUB_RUN_ID: ${{ github.run_id }}
+          GITHUB_RUN_NUMBER: ${{ github.run_number }}
+        run: |
+          awk -f scripts/generate_env.awk ../../.env > src/env.h
+          mkdir -p build
+          g++ -std=c++17 -I./src -I./sdk -I./third_party/cxxopts/include \
+            tests/integration_test.cpp \
+            src/task.cpp src/tasks_peer.cpp src/tasks_log.cpp \
+            -L./sdk -lditto -ldl -lrt -pthread \
+            -o build/integration_test
+          ./build/integration_test

.github/workflows/pr-checks.yml

@@ -102,66 +102,6 @@ jobs:
         working-directory: javascript-tui
         run: npm run test
 
-  cpp:
-    name: CPP Quickstart (ubuntu-latest)
-    strategy:
-      matrix:
-        os: ["ubuntu-latest"]
-
-    runs-on: ${{ matrix.os }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install dependencies
-        run: |
-          if [ "${{ matrix.os }}" = "ubuntu-latest" ]; then
-            sudo apt-get update
-            sudo apt-get install -y cmake build-essential
-          elif [ "${{ matrix.os }}" = "macos-latest" ]; then
-            brew install cmake
-          fi
-
-      - name: Create .env file
-        run: |
-          echo "DITTO_APP_ID=test_app_id" > .env
-          echo "DITTO_PLAYGROUND_TOKEN=test_playground_token" >> .env
-          echo "DITTO_AUTH_URL=https://auth.example.com" >> .env
-          echo "DITTO_WEBSOCKET_URL=wss://websocket.example.com" >> .env
-
-      - name: Download and setup Ditto SDK
-        working-directory: cpp-tui/taskscpp/sdk
-        run: |
-          # Determine architecture and download appropriate Ditto SDK
-          if [ "${{ matrix.os }}" = "ubuntu-latest" ]; then
-            ARCH=$(uname -m)
-            if [ "$ARCH" = "x86_64" ]; then
-              curl -O https://software.ditto.live/cpp-linux-x86_64/Ditto/4.10.0/dist/Ditto.tar.gz
-            elif [ "$ARCH" = "aarch64" ]; then
-              curl -O https://software.ditto.live/cpp-linux-aarch64/Ditto/4.10.0/dist/Ditto.tar.gz
-            fi
-          fi
-          # Extract the SDK
-          tar xvfz Ditto.tar.gz
-
-      - name: Configure CMake
-        working-directory: cpp-tui/taskscpp
-        run: cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
-
-      - name: Build
-        working-directory: cpp-tui/taskscpp
-        run: cmake --build build
-
-      - name: Test app startup
-        working-directory: cpp-tui/taskscpp
-        run: |
-          # Test that the app can start and show help
-          ./build/taskscpp --help
-          echo "✅ Help command works"
-
-          # Test that the app can show SDK version
-          ./build/taskscpp --ditto-sdk-version
-          echo "✅ SDK version command works"
 
   kotlin-multiplatform:
     name: Kotlin Multiplatform (ubuntu-24.04)

cpp-tui/README.md

@@ -1,17 +1,24 @@
 # Ditto C++ Console QuickStart Tasks App
 
+## Platform Support
+
+**Linux Console Application** - Runs on modern Linux distributions with full Ditto sync capabilities:
+
+- ✅ **Linux (x64)**: Ubuntu 20.04 LTS and later
+- ✅ **Linux (AArch64)**: Ubuntu 22.04 LTS and later
+
+For Android development, see the separate `android-cpp` project.
+
 ## Prerequisites
 
 After you have completed the [common prerequisites] you will need the following:
 
 - A C++ compiler (clang or gcc)
 - CMake 3.10 or later
 - Make
+- **Linux operating system** (Ubuntu 20.04+ recommended)
 
-Download and unpack the C++ Ditto SDK for your platform by following the
-instructions in the [Ditto C++ Install Guide](https://docs.ditto.live/install-guides/cpp).
-Then, copy the `Ditto.h` and `libditto.a` files from the SDK into the `sdk/`
-subdirectory of this project.
+The build system will automatically download the Ditto C++ SDK when you run `make build` on Linux. No manual SDK installation is required!
 
 ## Documentation
 
@@ -27,7 +34,9 @@ Assuming you have the prerequisites installed, you can build and run the app by
 
 1. Create an application at <https://portal.ditto.live/>.  Make note of the app ID and online playground token.
 2. Copy the `.env.sample` file at the top level of the `quickstart` repo to `.env` and add your app ID and online playground token.
-3. In a shell, navigate to the `quickstart/cpp-tui/taskscpp` directory and run the command `make build` to build the C++ application.
+3. In a shell, navigate to the `quickstart/cpp-tui/taskscpp` directory and run the command `make build` to automatically download the Ditto SDK and build the C++ application.
+
+The build system will detect your Linux architecture (x86_64/arm64) and download the appropriate Ditto C++ SDK version automatically.
 
 ## Running the Application
 

cpp-tui/taskscpp/CMakeLists.txt

@@ -77,3 +77,29 @@ endif()
 
 # Add dependency on cxxopts library
 target_include_directories(taskscpp PRIVATE third_party/cxxopts/include)
+
+# Enable testing
+option(BUILD_TESTS "Build tests" ON)
+
+if(BUILD_TESTS)
+  enable_testing()
+
+  # Integration tests
+  add_executable(integration_test
+    tests/integration_test.cpp
+    src/task.cpp
+    src/tasks_peer.cpp
+    src/tasks_log.cpp
+  )
+  target_include_directories(integration_test PRIVATE src sdk third_party/cxxopts/include)
+  target_link_libraries(integration_test PRIVATE ${CMAKE_SOURCE_DIR}/sdk/libditto.a)
+  add_dependencies(integration_test env_h)
+  add_test(NAME IntegrationTests COMMAND integration_test)
+
+  # Custom test target
+  add_custom_target(run_tests
+    COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure
+    DEPENDS integration_test
+    COMMENT "Running integration tests"
+  )
+endif()

cpp-tui/taskscpp/Makefile

@@ -1,6 +1,26 @@
 # CMake build type: Debug, Release, RelWithDebInfo
 BUILD_TYPE ?= Debug
 
+# Ditto SDK version and platform detection
+DITTO_SDK_VERSION ?= 4.12.0
+PLATFORM := $(shell uname -s | tr '[:upper:]' '[:lower:]')
+ARCH := $(shell uname -m)
+
+# Determine Ditto SDK platform string
+ifeq ($(PLATFORM),linux)
+    DITTO_PLATFORM = cpp-linux-$(ARCH)
+else ifeq ($(PLATFORM),darwin)
+    ifeq ($(ARCH),arm64)
+        DITTO_PLATFORM = cpp-macos-arm64
+    else
+        DITTO_PLATFORM = cpp-macos-x86_64
+    endif
+else
+    $(error Unsupported platform: $(PLATFORM))
+endif
+
+DITTO_SDK_URL = https://software.ditto.live/$(DITTO_PLATFORM)/Ditto/$(DITTO_SDK_VERSION)/dist/Ditto.tar.gz
+
 # Utility paths
 CMAKE ?= cmake
 CTEST ?= ctest
@@ -26,10 +46,28 @@ help: ## (default) Displays this message
 	@grep -E '^[A-Z0-9_-]* ?\?=.*?##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = " ?\\?=.*?##"}; {printf $(MAKEFILE_FMT), $$1, $$2}'
 
 .PHONY: build
-build: ## Generates all targets
+build: download-sdk ## Generates all targets (downloads SDK first)
 	$(CMAKE) -B $(BUILD_DIR) . -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -Wno-dev
 	$(CMAKE) --build $(BUILD_DIR) --parallel
 
+.PHONY: download-sdk
+download-sdk: ## Downloads and installs the Ditto C++ SDK
+	@echo "📥 Downloading Ditto C++ SDK v$(DITTO_SDK_VERSION) for $(DITTO_PLATFORM)..."
+	@if [ ! -f sdk/Ditto.h ] || [ ! -f sdk/libditto.a ]; then \
+		mkdir -p sdk; \
+		if curl -L -f $(DITTO_SDK_URL) | tar xz --strip-components=0 -C sdk/; then \
+			echo "✅ Ditto C++ SDK v$(DITTO_SDK_VERSION) installed successfully"; \
+		else \
+			echo "❌ Failed to download SDK for $(DITTO_PLATFORM)"; \
+			echo "💡 The Ditto C++ SDK only supports Linux x64/ARM64 platforms"; \
+			echo "💡 macOS and Windows are not supported by Ditto C++ SDK"; \
+			echo "💡 See: https://docs.ditto.live/reference/compatibility/cpp"; \
+			exit 1; \
+		fi; \
+	else \
+		echo "✅ Ditto C++ SDK already installed"; \
+	fi
+
 .PHONY: build-no-tui
 build-no-tui: ## Generates all targets, without TUI support
 	$(CMAKE) -B $(BUILD_DIR) . -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -Wno-dev -DDITTO_QUICKSTART_TUI=OFF
@@ -69,6 +107,22 @@ lint: build ## Runs clang-format -n and clang-tidy on all .cpp and .h files
 	$(CLANG_FORMAT) --dry-run --Werror $(CPP_SRC_FILES)
 	$(CLANG_TIDY) -p $(BUILD_DIR) $(CPP_SRC_FILES)
 
+.PHONY: test
+test: build ## Build and run all tests
+	cd $(BUILD_DIR) && $(CTEST) --output-on-failure
+
+.PHONY: test-unit
+test-unit: build ## Build and run unit tests only
+	cd $(BUILD_DIR) && ./unit_test
+
+.PHONY: test-integration
+test-integration: build ## Build and run integration tests only
+	cd $(BUILD_DIR) && ./integration_test
+
+.PHONY: test-script
+test-script: build ## Run tests using the shell script
+	tests/run_tests.sh
+
 .PHONY: clean
 clean: ## Removes all generated files and directories
 	- rm -r $(BUILD_DIR)

cpp-tui/taskscpp/sdk/.gitignore

@@ -1,2 +1 @@
-Ditto.h
-libditto.a
+# SDK files downloaded by CI