digidem
diff --git a/‎.env.example‎
Lines changed: 29 additions & 3 deletions b/‎.env.example‎
Lines changed: 29 additions & 3 deletions
diff --git a/‎.github/workflows/translate-docs.yml‎
Lines changed: 84 additions & 48 deletions b/‎.github/workflows/translate-docs.yml‎
Lines changed: 84 additions & 48 deletions
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.gitleaks.toml‎
Lines changed: 63 additions & 0 deletions b/‎.gitleaks.toml‎
Lines changed: 63 additions & 0 deletions
@@ -1,10 +1,17 @@
 # Notion API Configuration
 NOTION_API_KEY=your_notion_api_key_here
-DATABASE_ID=your_database_id_here
-# DATA_SOURCE_ID is required for Notion API v5 (may be the same as DATABASE_ID for existing databases)
-# Run: bun scripts/migration/discoverDataSource.ts to find the correct value
+
+# DATA_SOURCE_ID is the primary variable for Notion API v5 (version 2025-09-03)
+# This is the ID of the "data source" in Notion's new API architecture
+# Run the discovery script to find the correct value for your database:
+#   bun scripts/migration/discoverDataSource.ts
 DATA_SOURCE_ID=your_data_source_id_here
 
+# DATABASE_ID is kept for backward compatibility during migration
+# In Notion API v5, DATABASE_ID and DATA_SOURCE_ID may be DIFFERENT values
+# The DATABASE_ID fallback will be deprecated in a future release
+DATABASE_ID=your_database_id_here
+
 # Docusaurus Configuration
 # Default landing page for docs redirect (e.g., 'introduction', 'introduction-remove', 'getting-started')
 DEFAULT_DOCS_PAGE=introduction-remove
@@ -23,3 +30,22 @@ ENABLE_RETRY_IMAGE_PROCESSING=true
 # Default: "3"
 # Recommendation: 3 attempts is optimal balance between recovery and performance
 MAX_IMAGE_RETRIES=3
+
+# Test Environment Configuration
+# For translation workflow testing, you can use a dedicated test database
+# When TEST_DATABASE_ID or TEST_DATA_SOURCE_ID is set, translation scripts
+# will use the test database instead of the production database
+#
+# To enable test mode:
+# 1. Set TEST_DATABASE_ID or TEST_DATA_SOURCE_ID to your test database ID
+# 2. Optionally set TEST_MODE=true to explicitly enable test mode
+#
+# In test mode:
+# - All translation operations use the test database
+# - GitHub workflow dispatch validates target_branch against safe patterns
+# - Safe branches: "test/*", "fix/*", "feat/*", or branches with "test" in name
+# - Production branches ("main", "master", "content") are rejected in test mode
+#
+# Example:
+# TEST_DATA_SOURCE_ID=test-database-id-here
+# TEST_MODE=true
@@ -98,11 +98,29 @@ jobs:
       - name: Notion Translate
         id: notion_translate
         run: |
-          # Use test database if test mode is enabled
-          if [ -n "${{ secrets.TEST_DATA_SOURCE_ID }}" ] || [ -n "${{ secrets.TEST_DATABASE_ID }}" ] || [ "${{ secrets.TEST_MODE }}" = "true" ]; then
+          # Check if any test mode indicator is set
+          HAS_TEST_MODE="${{ secrets.TEST_MODE }}"
+          HAS_TEST_DATA_SOURCE="${{ secrets.TEST_DATA_SOURCE_ID }}"
+          HAS_TEST_DATABASE="${{ secrets.TEST_DATABASE_ID }}"
+
+          if [ "$HAS_TEST_MODE" = "true" ] || [ -n "$HAS_TEST_DATA_SOURCE" ] || [ -n "$HAS_TEST_DATABASE" ]; then
+            echo "🧪 Test mode detected"
+
+            # Require at least one test ID to be set - fail if test mode is enabled without test IDs
+            if [ -z "$HAS_TEST_DATA_SOURCE" ] && [ -z "$HAS_TEST_DATABASE" ]; then
+              echo "❌ ERROR: Test mode enabled but no test IDs provided"
+              echo "   Set TEST_DATA_SOURCE_ID or TEST_DATABASE_ID to use test mode"
+              exit 1
+            fi
+
             echo "🧪 Running in test mode with test database"
-            export DATA_SOURCE_ID="${{ secrets.TEST_DATA_SOURCE_ID }}"
-            export DATABASE_ID="${{ secrets.TEST_DATABASE_ID }}"
+            # Only override if test secret is non-empty to avoid breaking with empty secrets
+            if [ -n "$HAS_TEST_DATA_SOURCE" ]; then
+              export DATA_SOURCE_ID="$HAS_TEST_DATA_SOURCE"
+            fi
+            if [ -n "$HAS_TEST_DATABASE" ]; then
+              export DATABASE_ID="$HAS_TEST_DATABASE"
+            fi
             export TEST_MODE="true"
           fi
 
@@ -121,7 +139,7 @@ jobs:
         if: always()
         id: parse_summary
         run: |
-          # Default values if TRANSLATION_SUMMARY not found
+          # Default values if summary not found
           export TOTAL_PAGES="0"
           export PROCESSED_LANGS="0"
           export NEW_TRANSLATIONS="0"
@@ -132,8 +150,27 @@ jobs:
           export THEME_FAILURES="0"
           export HAS_FAILURES="false"
 
-          # Extract TRANSLATION_SUMMARY line from output
-          if [ -f /tmp/translate_output.log ]; then
+          # Prefer JSON file (more reliable than log parsing)
+          # Fall back to log parsing for backward compatibility
+          if [ -f translation-summary.json ]; then
+            echo "Using translation-summary.json for summary parsing"
+            TOTAL_PAGES=$(jq -r '.totalEnglishPages // 0' translation-summary.json)
+            PROCESSED_LANGS=$(jq -r '.processedLanguages // 0' translation-summary.json)
+            NEW_TRANSLATIONS=$(jq -r '.newTranslations // 0' translation-summary.json)
+            UPDATED_TRANSLATIONS=$(jq -r '.updatedTranslations // 0' translation-summary.json)
+            SKIPPED_TRANSLATIONS=$(jq -r '.skippedTranslations // 0' translation-summary.json)
+            FAILED_TRANSLATIONS=$(jq -r '.failedTranslations // 0' translation-summary.json)
+            CODE_JSON_FAILURES=$(jq -r '.codeJsonFailures // 0' translation-summary.json)
+            THEME_FAILURES=$(jq -r '.themeFailures // 0' translation-summary.json)
+
+            # Determine if there were any failures
+            TOTAL_FAILURES=$((FAILED_TRANSLATIONS + CODE_JSON_FAILURES + THEME_FAILURES))
+            if [ "$TOTAL_FAILURES" -gt 0 ]; then
+              HAS_FAILURES="true"
+            fi
+          elif [ -f /tmp/translate_output.log ]; then
+            # Fallback: extract TRANSLATION_SUMMARY line from output (legacy)
+            echo "Falling back to log parsing for summary"
             SUMMARY_LINE=$(grep "^TRANSLATION_SUMMARY " /tmp/translate_output.log | head -1 || echo "")
 
             if [ -n "$SUMMARY_LINE" ]; then
@@ -152,7 +189,7 @@ jobs:
               THEME_FAILURES=$(echo "$JSON_PART" | jq -r '.themeFailures // "0"' 2>/dev/null || echo "0")
 
               # Determine if there were any failures
-              TOTAL_FAILURES=$$((FAILED_TRANSLATIONS + CODE_JSON_FAILURES + THEME_FAILURES))
+              TOTAL_FAILURES=$((FAILED_TRANSLATIONS + CODE_JSON_FAILURES + THEME_FAILURES))
               if [ "$TOTAL_FAILURES" -gt 0 ]; then
                 HAS_FAILURES="true"
               fi
@@ -185,7 +222,7 @@ jobs:
           echo "  Has failures: $HAS_FAILURES"
 
       - name: Update Notion Status → Auto Translation Generated
-        if: success()
+        if: success() && (steps.parse_summary.outputs.new_translations != '0' || steps.parse_summary.outputs.updated_translations != '0')
         run: |
           # Use test database if test mode is enabled
           if [ -n "${{ secrets.TEST_DATA_SOURCE_ID }}" ] || [ -n "${{ secrets.TEST_DATABASE_ID }}" ] || [ "${{ secrets.TEST_MODE }}" = "true" ]; then
@@ -225,12 +262,12 @@ jobs:
           PUSH_SUCCESS=false
 
           while [ $RETRY_COUNT -lt $MAX_RETRIES ] && [ "$PUSH_SUCCESS" = false ]; do
-            CURRENT_ATTEMPT=$$((RETRY_COUNT + 1))
+            CURRENT_ATTEMPT=$((RETRY_COUNT + 1))
             if PUSH_OUTPUT=$(git push origin "${TARGET_BRANCH}" 2>&1); then
               PUSH_SUCCESS=true
               echo "✅ Push succeeded on attempt $CURRENT_ATTEMPT"
             else
-              RETRY_COUNT=$$((RETRY_COUNT + 1))
+              RETRY_COUNT=$((RETRY_COUNT + 1))
 
               # Check if error is due to non-fast-forward (push race condition)
               if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
@@ -245,7 +282,7 @@ jobs:
                   echo "Rebasing local changes on top of origin/${TARGET_BRANCH}..."
                   if git rebase "origin/${TARGET_BRANCH}" 2>&1; then
                     # Calculate exponential backoff: 2^N seconds (2s, 4s, 8s)
-                    BACKOFF_TIME=$$((2 ** RETRY_COUNT))
+                    BACKOFF_TIME=$((2 ** RETRY_COUNT))
                     echo "Waiting ${BACKOFF_TIME}s before retry..."
                     sleep $BACKOFF_TIME
                   else
@@ -276,39 +313,38 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-
-      # - name: Notify Slack
-      #   if: always()
-      #   uses: slackapi/slack-github-action@v2.1.1
-      #   with:
-      #     webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
-      #     webhook-type: incoming-webhook
-      #     payload: |
-      #       text: "*Translation sync*: ${{ job.status }}"
-      #       blocks:
-      #         - type: "section"
-      #           text:
-      #             type: "mrkdwn"
-      #             text: "*Translation sync*: ${{ job.status == 'success' && fromJSON('["✅"]')[0] || fromJSON('["❌"]')[0] }} *${{ job.status }}*\n_Updated locales committed to `${{ env.TARGET_BRANCH }}`_"
-      #         - type: "section"
-      #           text:
-      #             type: "mrkdwn"
-      #             text: |
-      #               *Translation Results:*
-      #               • Pages processed: ${{ steps.parse_summary.outputs.total_pages }}
-      #               • Languages: ${{ steps.parse_summary.outputs.processed_langs }}
-      #               • New translations: ${{ steps.parse_summary.outputs.new_translations }}
-      #               • Updated translations: ${{ steps.parse_summary.outputs.updated_translations }}
-      #               • Skipped: ${{ steps.parse_summary.outputs.skipped_translations }}
-      #               ${{ steps.parse_summary.outputs.has_failures == 'true' && '*Failures:*' || '' }}
-      #               ${{ steps.parse_summary.outputs.failed_translations != '0' && fromJSON('["  • Doc translation failures: "]')[0] || '' }}${{ steps.parse_summary.outputs.failed_translations }}${{ steps.parse_summary.outputs.failed_translations != '0' && fromJSON('["']')[0] || '' }}
-      #               ${{ steps.parse_summary.outputs.code_json_failures != '0' && fromJSON('["  • Code.json failures: "]')[0] || '' }}${{ steps.parse_summary.outputs.code_json_failures }}${{ steps.parse_summary.outputs.code_json_failures != '0' && fromJSON('["']')[0] || '' }}
-      #               ${{ steps.parse_summary.outputs.theme_failures != '0' && fromJSON('["  • Theme (navbar/footer) failures: "]')[0] || '' }}${{ steps.parse_summary.outputs.theme_failures }}${{ steps.parse_summary.outputs.theme_failures != '0' && fromJSON('["']')[0] || '' }}
-      #         - type: "section"
-      #           text:
-      #             type: "mrkdwn"
-      #             text: "Trigger: <https://github.com/${{ github.triggering_actor }}|${{ github.triggering_actor }}>\nRun: <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View logs>"
-      #         - type: "section"
-      #           text:
-      #             type: "mrkdwn"
-      #             text: "${{ steps.parse_summary.outputs.has_failures == 'true' || job.status != 'success' && '⚠️ *Attention required*: Review failures before re-running.' || 'ℹ️ Reminder: Review translations before publishing.' }}"
+      - name: Notify Slack
+        if: always()
+        uses: slackapi/slack-github-action@v2.1.1
+        with:
+          webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+          webhook-type: incoming-webhook
+          payload: |
+            text: "*Translation sync*: ${{ job.status }}"
+            blocks:
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: "*Translation sync*: ${{ job.status == 'success' && fromJSON('["✅"]')[0] || fromJSON('["❌"]')[0] }} *${{ job.status }}*\n_Updated locales committed to `${{ env.TARGET_BRANCH }}`_"
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *Translation Results:*
+                    • Pages processed: ${{ steps.parse_summary.outputs.total_pages }}
+                    • Languages: ${{ steps.parse_summary.outputs.processed_langs }}
+                    • New translations: ${{ steps.parse_summary.outputs.new_translations }}
+                    • Updated translations: ${{ steps.parse_summary.outputs.updated_translations }}
+                    • Skipped: ${{ steps.parse_summary.outputs.skipped_translations }}
+                    ${{ steps.parse_summary.outputs.has_failures == 'true' && '*Failures:*' || '' }}
+                    ${{ steps.parse_summary.outputs.failed_translations != '0' && fromJSON('["  • Doc translation failures: "]')[0] || '' }}${{ steps.parse_summary.outputs.failed_translations }}${{ steps.parse_summary.outputs.failed_translations != '0' && fromJSON('["']')[0] || '' }}
+                    ${{ steps.parse_summary.outputs.code_json_failures != '0' && fromJSON('["  • Code.json failures: "]')[0] || '' }}${{ steps.parse_summary.outputs.code_json_failures }}${{ steps.parse_summary.outputs.code_json_failures != '0' && fromJSON('["']')[0] || '' }}
+                    ${{ steps.parse_summary.outputs.theme_failures != '0' && fromJSON('["  • Theme (navbar/footer) failures: "]')[0] || '' }}${{ steps.parse_summary.outputs.theme_failures }}${{ steps.parse_summary.outputs.theme_failures != '0' && fromJSON('["']')[0] || '' }}
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: "Trigger: <https://github.com/${{ github.triggering_actor }}|${{ github.triggering_actor }}>\nRun: <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View logs>"
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: "${{ ((steps.parse_summary.outputs.has_failures == 'true') || (job.status != 'success')) && '⚠️ *Attention required*: Review failures before re-running.' || 'ℹ️ Reminder: Review translations before publishing.' }}"
@@ -90,3 +90,6 @@ NEXT_STEPS.md
 
 # Runtime metrics files
 retry-metrics.json
+
+# Claude Code command history
+.claude/command-history.log
@@ -0,0 +1,63 @@
+# Gitleaks configuration for CoMapeo Docs
+# https://github.com/gitleaks/gitleaks
+
+title = "gitleaks config for CoMapeo Docs"
+
+# Extend default gitleaks config
+[extend]
+useDefault = true
+
+# Custom rules for this project
+[[rules]]
+id = "notion-api-key"
+description = "Notion API Key"
+regex = '''(?i)ntn_[a-zA-Z0-9]{43,}'''
+tags = ["key", "notion"]
+
+[[rules]]
+id = "openai-api-key"
+description = "OpenAI API Key"
+regex = '''sk-[a-zA-Z0-9]{20,}'''
+tags = ["key", "openai"]
+
+[[rules]]
+id = "cloudflare-api-token"
+description = "Cloudflare API Token"
+regex = '''(?i)cloudflare[_-]?(api)?[_-]?token[_-]?[:=]\s*['\"]?([a-zA-Z0-9_-]{40,})['\"]?'''
+tags = ["key", "cloudflare"]
+
+[[rules]]
+id = "generic-api-key"
+description = "Generic API Key"
+regex = '''(?i)(api[_-]?key|apikey)[_-]?[:=]\s*['\"]?([a-zA-Z0-9_-]{20,})['\"]?'''
+tags = ["key", "generic"]
+[rules.allowlist]
+# Allow .env.example file
+paths = [
+  '''\.env\.example$''',
+]
+
+# Global allowlist
+[allowlist]
+description = "Allowlist for safe files and patterns"
+paths = [
+  '''\.env\.example$''',
+  '''\.gitleaks\.toml$''',
+  '''node_modules/''',
+  '''\.git/''',
+  '''docs/developer-tools/github-setup\.md$''',  # Documentation may contain example patterns
+]
+
+# Stop words that indicate example/placeholder values
+stopwords = [
+  "your_notion_api_key_here",
+  "your_data_source_id_here",
+  "your_database_id_here",
+  "your_openai_api_key_here",
+  "REDACTED",
+  "example",
+  "sample",
+  "placeholder",
+  "fake",
+  "test",
+]