2.0.0

.github/actions/check-docs-deploy/action.yml

@@ -0,0 +1,76 @@
+name: Check Docs Deploy
+description: Validate docs deployment inputs and set defaults
+inputs:
+  host:
+    description: Target host for deployment
+    required: false
+  user:
+    description: SSH username
+    required: false
+  ssh_key:
+    description: SSH private key for deployment
+    required: false
+  port:
+    description: SSH port
+    required: false
+  path:
+    description: Remote path for documentation files
+    required: false
+outputs:
+  ready:
+    description: Indicates whether deployment can proceed
+    value: ${{ steps.evaluate.outputs.ready }}
+  host:
+    description: Resolved SSH host
+    value: ${{ steps.evaluate.outputs.host }}
+  user:
+    description: Resolved SSH username
+    value: ${{ steps.evaluate.outputs.user }}
+  port:
+    description: Resolved SSH port
+    value: ${{ steps.evaluate.outputs.port }}
+  path:
+    description: Resolved remote path
+    value: ${{ steps.evaluate.outputs.path }}
+runs:
+  using: composite
+  steps:
+    - id: evaluate
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        host="${{ inputs.host }}"
+        user="${{ inputs.user }}"
+        ssh_key="${{ inputs.ssh_key }}"
+        port="${{ inputs.port }}"
+        path="${{ inputs.path }}"
+
+        ready=true
+        for var in host user ssh_key; do
+          value="${!var}"
+          if [ -z "$value" ]; then
+            case "$var" in
+              host) label="DOCS_HOST" ;;
+              user) label="DOCS_USER" ;;
+              ssh_key) label="DOCS_SSH_KEY" ;;
+              *) label="$var" ;;
+            esac
+            echo "::warning::Missing required deploy secret: $label"
+            ready=false
+          fi
+        done
+
+        if [ -z "$port" ]; then
+          port=2200
+        fi
+
+        if [ -z "$path" ]; then
+          path="/var/www/datamapper/docs"
+        fi
+
+        echo "ready=$ready" >> "$GITHUB_OUTPUT"
+        echo "host=$host" >> "$GITHUB_OUTPUT"
+        echo "user=$user" >> "$GITHUB_OUTPUT"
+        echo "port=$port" >> "$GITHUB_OUTPUT"
+        echo "path=$path" >> "$GITHUB_OUTPUT"

.github/actions/deploy-docs/action.yml

@@ -0,0 +1,41 @@
+name: Deploy Docs Bundle
+description: Upload built documentation via rsync over SSH
+inputs:
+  host:
+    description: Target host for deployment
+    required: true
+  user:
+    description: SSH username
+    required: true
+  port:
+    description: SSH port
+    required: true
+  path:
+    description: Remote path for documentation files
+    required: true
+  ssh_key:
+    description: SSH private key used for deployment
+    required: true
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        set -euo pipefail
+
+        host="${{ inputs.host }}"
+        user="${{ inputs.user }}"
+        port="${{ inputs.port }}"
+        path="${{ inputs.path }}"
+        ssh_key="${{ inputs.ssh_key }}"
+
+        mkdir -p "$HOME/.ssh"
+        printf '%s\n' "$ssh_key" > "$HOME/.ssh/id_rsa"
+        chmod 600 "$HOME/.ssh/id_rsa"
+
+        if ! ssh-keygen -F "$host" >/dev/null 2>&1; then
+          ssh-keyscan -p "$port" -H "$host" >> "$HOME/.ssh/known_hosts"
+        fi
+
+        rsync -az --delete -e "ssh -p $port -i $HOME/.ssh/id_rsa -o StrictHostKeyChecking=yes" \
+          docs/.vitepress/dist/ "$user@$host:$path/"

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - 2.0.0-beta1
+  pull_request:
+    branches:
+      - master
+      - 2.0.0-beta1
+
+jobs:
+  tests:
+    name: PHP ${{ matrix.php-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php-version: ["8.1", "8.2", "8.3", "8.4", "8.5"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate composer.json
+        run: composer validate --no-check-publish
+
+      - name: Cache Composer dependencies
+        uses: actions/cache@v4
+        with:
+          path: vendor
+          key: ${{ runner.os }}-php-${{ matrix.php-version }}-${{ hashFiles('composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-php-${{ matrix.php-version }}-
+            ${{ runner.os }}-php-
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      - name: Run test suite
+        run: vendor/bin/phpunit -c tests/phpunit.xml

.github/workflows/docs-deploy.yml

@@ -0,0 +1,64 @@
+# actionlint: allow-secrets DOCS_HOST,DOCS_USER,DOCS_SSH_KEY,DOCS_PORT,DOCS_PATH
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - 2.0.0-beta1
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/docs-deploy.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: docs-deploy-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build VitePress site
+        run: npm run docs:build
+        env:
+          DOCS_BASE: /
+
+      - name: Check deployment prerequisites
+        id: check
+        uses: ./.github/actions/check-docs-deploy
+        with:
+          host: ${{ secrets.DOCS_HOST }} # actionlint: allow
+          user: ${{ secrets.DOCS_USER }} # actionlint: allow
+          ssh_key: ${{ secrets.DOCS_SSH_KEY }} # actionlint: allow
+          port: ${{ secrets.DOCS_PORT }} # actionlint: allow
+          path: ${{ secrets.DOCS_PATH }} # actionlint: allow
+
+      - name: Deploy documentation bundle
+        if: steps.check.outputs.ready == 'true'
+        uses: ./.github/actions/deploy-docs
+        with:
+          host: ${{ steps.check.outputs.host }}
+          user: ${{ steps.check.outputs.user }}
+          port: ${{ steps.check.outputs.port }}
+          path: ${{ steps.check.outputs.path }}
+          ssh_key: ${{ secrets.DOCS_SSH_KEY }} # actionlint: allow
+
+      - name: Deployment skipped
+        if: steps.check.outputs.ready != 'true'
+        run: echo "Documentation build complete, but deploy secrets are missing so upload was skipped."

.gitignore

@@ -1,4 +1,51 @@
-# Ignore Eclipse project files
+# Composer dependencies
+/vendor/
+
+# Composer utility artifacts
+/composer.phar
+/.composer/
+
+# Node-based docs build output
+/node_modules/
+/docs/.vitepress/cache/
+/docs/.vitepress/dist/
+
+# Python helper cache (conversion scripts, etc.)
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+
+# Logs & coverage
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+/coverage/
+.phpunit.result.cache
+
+# Editor/IDE settings
+.vscode/
+.idea/
 .buildpath
 .project
-.settings/
+.settings/
+*.code-workspace
+*.swp
+*.swo
+*~
+
+# Operating system junk
+Thumbs.db
+.DS_Store
+
+# Local environment overrides & temp files
+.env
+.env.*
+*.tmp
+*.temp
+
+# Local documentation notes
+copilot/
+TODO_PRODUCTION_READINESS.md