refactor(initial-project-setup): initial project setup

Author: Datata1

.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: Python backend server tests
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, draft]
+    paths:
+      - 'src/codesphere_sdk/**'
+      - '.github/workflows/backend-app.yml'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Install uv package manager
+      uses: astral-sh/setup-uv@v6
+      with:
+        activate-environment: true
+
+    - name: Install dependencies using uv
+      run: |
+        uv sync
+      shell: bash
+
+    - name: Run Bandit security check on backend code
+      id: bandit_check
+      run: |
+        echo "Running Bandit security check..."
+        set +e
+        bandit -r . -c pyproject.toml --format=custom --msg-template "{abspath}:{line}: {test_id}[{severity}]: {msg}" -o bandit-results.txt
+        cat bandit-results.txt
+        BANDIT_EXIT_CODE=$?
+        set -e
+        echo "Bandit scan finished. Exit code: $BANDIT_EXIT_CODE"
+        echo "BANDIT_EXIT_CODE=${BANDIT_EXIT_CODE}" >> $GITHUB_ENV
+      shell: bash
+
+    - name: Prepare Bandit comment body
+      id: prep_bandit_comment
+      if: github.event_name == 'pull_request'
+      run: |
+        echo "Preparing Bandit comment body..."
+        COMMENT_BODY_FILE="bandit-comment-body.md"
+        echo "COMMENT_BODY_FILE=${COMMENT_BODY_FILE}" >> $GITHUB_ENV
+
+        echo "### 🛡️ Bandit Security Scan Results" > $COMMENT_BODY_FILE
+        echo "" >> $COMMENT_BODY_FILE
+        echo "" >> $COMMENT_BODY_FILE
+        echo "" >> $COMMENT_BODY_FILE
+
+        if [ -s backend/bandit-results.txt ]; then
+          echo "\`\`\`text" >> $COMMENT_BODY_FILE
+          cat backend/bandit-results.txt >> $COMMENT_BODY_FILE
+          echo "\`\`\`" >> $COMMENT_BODY_FILE
+        else
+          echo "✅ No security issues found by Bandit." >> $COMMENT_BODY_FILE
+        fi
+      shell: bash
+
+    - name: Find Comment
+      uses: peter-evans/find-comment@v3
+      id: fc
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-author: 'github-actions[bot]'
+        body-includes: Bandit Security Scan Results
+
+    - name: Post Bandit results as PR comment
+      if: github.event_name == 'pull_request' && always()
+      uses: peter-evans/create-or-update-comment@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        repository: ${{ github.repository }}
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-id: ${{ steps.fc.outputs.comment-id }}
+        body-file: ${{ env.COMMENT_BODY_FILE }}
+        edit-mode: replace
+
+    - name: Run tests with pytest using uv
+      run: |
+        pytest --junitxml=junit/test-results.xml --cov-report=xml --cov-report=html --cov=. | tee pytest-coverage.txt
+      shell: bash
+
+    - name: Pytest coverage comment
+      if: github.event_name == 'pull_request' && always()
+      uses: MishaKav/pytest-coverage-comment@main
+      with:
+        unique-id-for-comment: coverage-report
+        pytest-xml-coverage-path: coverage.xml
+        pytest-coverage-path: pytest-coverage.txt
+        junitxml-path: junit/test-results.xml
+        title: Pytest Coverage Report
+        junitxml-title: Test Execution Summary
+
+    - name: Minimize uv cache
+      run: uv cache prune --ci

.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+# .github/workflows/release.yml
+
+name: Create Release and Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+    branches:
+      - main
+
+env:
+  UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+
+jobs:
+  uv-example:
+    name: python
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Build package
+        run: make pypi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+*.pyc
+*.pyo
+*.pyd
+build/
+dist/
+wheels/
+*.egg-info
+
+# Ruff cache
+.ruff_cache
+
+# Virtual environment
+.venv/
+venv/
+env/

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+    -   id: check-yaml
+    -   id: check-toml
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.11.13
+  hooks:
+    - id: ruff-check
+      args: [ --fix ]
+    - id: ruff-format
+
+- repo: https://github.com/commitizen-tools/commitizen
+  rev: v4.8.3
+  hooks:
+    - id: commitizen
+    - id: commitizen-branch
+      stages: [pre-push]

.python-version

@@ -0,0 +1 @@
+3.12.9

CONTRIBUTING

@@ -0,0 +1,68 @@
+.PHONY: help install commit lint format test bump
+
+.DEFAULT_GOAL := help
+
+help: ## Shows a help message with all available commands
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Sets up the development environment
+	@echo ">>> Setting up the development environment..."
+	@echo "1. Creating virtual environment with uv..."
+	uv venv
+	@echo "2. Installing all dependencies (including 'dev')..."
+	uv pip install -e '.[dev]'
+	@echo "3. Installing git hooks with pre-commit..."
+	pre-commit install --hook-type commit-msg --hook-type pre-commit --hook-type pre-push
+	@echo "\n\033[0;32mSetup complete! Please activate the virtual environment with 'source .venv/bin/activate'.\033[0m"
+
+commit: ## Starts Commitizen for a guided commit message
+	@echo ">>> Starting Commitizen for a guided commit message..."
+	@if git diff --cached --quiet; then \
+		echo "\033[0;33mWarning: No changes added to commit (please use 'git add ...' first).\033[0m"; \
+		exit 1; \
+	fi
+	uv run cz commit
+	uv run cz bump --changelog --allow-no-commit
+
+
+lint: ## Checks code quality with ruff
+	@echo ">>> Checking code quality with ruff..."
+	uv run ruff check src tests
+
+format: ## Formats code with ruff
+	@echo ">>> Formatting code with ruff..."
+	uv run ruff format src tests
+
+test: ## Runs tests with pytest
+	@echo ">>> Running tests with pytest..."
+	uv run pytest
+
+release: ## Pushes a new tag and release
+	@echo ">>> Starting release process..."
+	git config --global push.followTags true
+
+	@echo "\n>>> Verifying tag and pushing to remote..."
+	export VERSION=$$(uv run cz version --project); \
+	if [ -z "$${VERSION}" ]; then \
+		echo "\033[0;31mERROR: Could not determine version using 'cz version --project'.\033[0m"; \
+		exit 1; \
+	fi; \
+	echo "--- Found project version: v$${VERSION} ---"; \
+	if git rev-parse "v$${VERSION}" >/dev/null 2>&1; then \
+		echo "--- Verified local tag v$${VERSION} exists. ---"; \
+	else \
+		echo "\033[0;31mERROR: Git tag v$${VERSION} was not found! Please check for errors.\033[0m"; \
+		exit 1; \
+	fi; \
+	echo "--- Pushing commit and tag to remote... ---"; \
+	git tag -d v$${VERSION}; \
+	git tag -a v$${VERSION} -m "Release $${VERSION}"; \
+	git push --follow-tags; \
+	echo "\n\033[0;32m✅ SUCCESS: Tag v$${VERSION} pushed to GitHub. The release workflow has been triggered.\033[0m"
+
+pypi: ## publishes to PyPI
+	@echo "\n>>> Building package for distribution..."
+	uv build
+	@echo "\n>>> Publishing to PyPI..."
+	uv publish
+	@echo "\n\033[0;32mPyPI release complete! The GitHub Action will now create the GitHub Release.\033[0m"