fix(docs): make SEO sync workflow compatible with protected main (#151)

* fix(docs): avoid direct main pushes in SEO sync workflow

* fix(docs): validate MIN_SITEMAP_URLS strictly when provided

* chore(docs): log full stack for SEO check failures

Author: rubenmarcus

.github/workflows/docs-seo-aeo.yml

@@ -15,8 +15,12 @@ on:
       - 'docs/pnpm-lock.yaml'
   workflow_dispatch:
 
+env:
+  SITE_URL: https://ralphstarter.ai
+
 permissions:
   contents: write
+  pull-requests: write
 
 jobs:
   sync-seo-assets:
@@ -48,28 +52,47 @@ jobs:
       - name: Validate SEO/AEO outputs
         working-directory: docs
         run: pnpm seo:check
+        env:
+          SITE_URL: ${{ env.SITE_URL }}
 
       - name: Sync generated assets into docs/static
         working-directory: docs
         run: pnpm seo:sync
 
-      - name: Commit synced assets
+      - name: Commit synced assets and open PR
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           if git diff --quiet -- docs/static/sitemap.xml docs/static/llms.txt docs/static/llms-full.txt docs/static/docs.json docs/static/docs-urls.txt docs/static/ai-index.json docs/static/sidebar.json; then
             echo "No SEO/AEO asset changes to commit."
             exit 0
           fi
 
+          BRANCH_NAME="automation/docs-seo-aeo-sync"
+
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -B "${BRANCH_NAME}"
           git add docs/static/sitemap.xml docs/static/llms.txt docs/static/llms-full.txt docs/static/docs.json docs/static/docs-urls.txt docs/static/ai-index.json docs/static/sidebar.json
           git commit -m "chore(docs): sync generated SEO/AEO assets [skip ci]"
-          git push
+          git push origin "${BRANCH_NAME}" --force-with-lease
+
+          EXISTING_PR=$(gh pr list --head "${BRANCH_NAME}" --base main --state open --json number --jq '.[0].number // empty')
+          if [ -n "${EXISTING_PR}" ]; then
+            echo "Updated existing PR #${EXISTING_PR}"
+            exit 0
+          fi
+
+          gh pr create \
+            --base main \
+            --head "${BRANCH_NAME}" \
+            --title "chore(docs): sync generated SEO/AEO assets" \
+            --body "Automated sync of generated docs SEO/AEO artifacts from docs build."
 
       - name: Notify search engines
         run: |
           set +e
-          SITEMAP_URL="https://ralphstarter.ai/sitemap.xml"
+          SITEMAP_URL="${SITE_URL}/sitemap.xml"
 
           echo "Pinging Bing sitemap endpoint..."
           curl --connect-timeout 5 --max-time 15 -fsS "https://www.bing.com/ping?sitemap=${SITEMAP_URL}" >/dev/null && echo "Bing ping sent." || echo "Bing ping failed (non-fatal)."
@@ -79,7 +102,7 @@ jobs:
 
           if [ -n "${INDEXNOW_KEY}" ]; then
             echo "Submitting IndexNow URL update..."
-            curl --connect-timeout 5 --max-time 15 -fsS "https://api.indexnow.org/indexnow?url=https://ralphstarter.ai/docs/intro&key=${INDEXNOW_KEY}" >/dev/null && echo "IndexNow submitted." || echo "IndexNow submission failed (non-fatal)."
+            curl --connect-timeout 5 --max-time 15 -fsS "https://api.indexnow.org/indexnow?url=${SITE_URL}/docs/intro&key=${INDEXNOW_KEY}" >/dev/null && echo "IndexNow submitted." || echo "IndexNow submission failed (non-fatal)."
           else
             echo "INDEXNOW_KEY not configured; skipping IndexNow submission."
           fi

docs/scripts/check-seo-aeo.cjs

@@ -6,6 +6,31 @@ const buildDir = path.join(rootDir, 'build');
 const staticDir = path.join(rootDir, 'static');
 const siteUrl = process.env.SITE_URL || 'https://ralphstarter.ai';
 const expectedOrigin = new URL(siteUrl).origin;
+// Keep a minimum URL floor so we catch truncated/partial sitemap generation.
+const defaultMinSitemapUrls = 10;
+
+function resolveMinSitemapUrls() {
+  const rawValue = process.env.MIN_SITEMAP_URLS;
+  if (rawValue === undefined || rawValue.trim() === '') {
+    return defaultMinSitemapUrls;
+  }
+
+  const normalized = rawValue.trim();
+  if (!/^\d+$/.test(normalized)) {
+    throw new Error(
+      `Invalid MIN_SITEMAP_URLS value "${rawValue}". Expected a positive integer.`
+    );
+  }
+
+  const parsedValue = Number(normalized);
+  if (!Number.isSafeInteger(parsedValue) || parsedValue <= 0) {
+    throw new Error(
+      `Invalid MIN_SITEMAP_URLS value "${rawValue}". Expected a positive integer.`
+    );
+  }
+
+  return parsedValue;
+}
 
 const requiredBuildFiles = [
   'sitemap.xml',
@@ -24,6 +49,8 @@ function assertFileExists(fullPath, label) {
 }
 
 function main() {
+  const minSitemapUrls = resolveMinSitemapUrls();
+
   assertFileExists(buildDir, 'Build directory');
 
   for (const file of requiredBuildFiles) {
@@ -34,8 +61,10 @@ function main() {
   const sitemap = fs.readFileSync(sitemapPath, 'utf8');
   const locMatches = [...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)].map((match) => match[1]);
 
-  if (locMatches.length < 10) {
-    throw new Error(`Sitemap has too few URLs (${locMatches.length}).`);
+  if (locMatches.length < minSitemapUrls) {
+    throw new Error(
+      `Sitemap has too few URLs (${locMatches.length}). Expected at least ${minSitemapUrls}.`
+    );
   }
 
   if (!locMatches.some((url) => url.includes('/docs/intro'))) {
@@ -60,7 +89,13 @@ function main() {
   }
 
   const docsManifestRaw = fs.readFileSync(path.join(buildDir, 'docs.json'), 'utf8');
-  const docsManifest = JSON.parse(docsManifestRaw);
+  let docsManifest;
+  try {
+    docsManifest = JSON.parse(docsManifestRaw);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Malformed docs.json manifest: ${reason}. Please regenerate docs artifacts.`);
+  }
   if (!Array.isArray(docsManifest.docs) || docsManifest.docs.length === 0) {
     throw new Error('docs.json manifest has no docs entries.');
   }
@@ -77,4 +112,14 @@ function main() {
   console.log(`- docs manifest entries: ${docsManifest.docs.length}`);
 }
 
-main();
+try {
+  main();
+  process.exitCode = 0;
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Validation failed:\n', error.stack || error.message);
+  } else {
+    console.error('Validation failed:', error);
+  }
+  process.exit(1);
+}