From ac37a4c2df2d918e824814616c6278a35ae5c6d5 Mon Sep 17 00:00:00 2001
From: Den <2119348+dzianisv@users.noreply.github.com>
Date: Fri, 17 Jul 2026 21:48:33 -0700
Subject: [PATCH] chore(docs): add safe gh-pages deploy script (#115)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

There is no auto-deploy for the docs site — gh-pages is updated manually,
which is why fixes (e.g. the opencode->opencode-ai guide correction in #113)
land on main but not on the live site. This ad-hoc process also risks wiping
the live F-Droid repo (gh-pages/fdroid/) since docs-site/ doesn't contain it.

scripts/deploy-docs.sh copies docs-site/ over gh-pages ADDITIVELY (never
--delete) and hard-aborts if fdroid/, privacy/, or .nojekyll would go missing
or the F-Droid repo index is empty. Supports --dry-run. A dry-run against the
current site shows it would ship exactly the pending changes (the guide
install-command fix + demo.gif/mp4 + updated screenshots) and touch nothing
under fdroid/.

Usage: bash scripts/deploy-docs.sh [--dry-run]


Claude-Session: https://claude.ai/code/session_01T12AhSnQVrSxNnvwfCx2z6

Co-authored-by: engineer <engineer@macbookpro.lan>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 scripts/deploy-docs.sh | 83 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100755 scripts/deploy-docs.sh

diff --git a/scripts/deploy-docs.sh b/scripts/deploy-docs.sh
new file mode 100755
index 0000000..499a533
--- /dev/null
+++ b/scripts/deploy-docs.sh
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+#
+# Deploy the static site in docs-site/ to the gh-pages branch (the live site
+# at https://dzianisv.github.io/opencode-mobile/).
+#
+# WHY THIS EXISTS: there is no auto-deploy. GitHub Pages serves the gh-pages
+# branch as-is, and gh-pages holds content that is NOT in docs-site/ and must
+# survive every deploy:
+#   - fdroid/    the LIVE F-Droid repo (built by publish-fdroid.yml). Wiping
+#                it breaks every user's F-Droid client. NEVER touch it.
+#   - privacy/   the privacy policy, maintained directly on gh-pages.
+#   - .nojekyll  required so Pages serves files literally.
+# So this deploy is ADDITIVE: it copies docs-site/ over the gh-pages root
+# (overwriting docs pages, adding new assets) but never deletes, and it aborts
+# if any protected path would go missing.
+#
+# Usage:
+#   bash scripts/deploy-docs.sh            # deploy
+#   bash scripts/deploy-docs.sh --dry-run  # stage + show diff, do not push
+#
+set -euo pipefail
+
+DRY_RUN=0
+[ "${1:-}" = "--dry-run" ] && DRY_RUN=1
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+SRC="$REPO_ROOT/docs-site"
+[ -d "$SRC" ] || { echo "error: $SRC not found" >&2; exit 1; }
+
+# Protected paths that live on gh-pages but not in docs-site/.
+PROTECTED=(fdroid privacy .nojekyll)
+
+WORKTREE="$(mktemp -d)"
+cleanup() { git worktree remove --force "$WORKTREE" 2>/dev/null || true; rm -rf "$WORKTREE"; }
+trap cleanup EXIT
+
+echo "==> Fetching origin/gh-pages"
+git fetch --quiet origin gh-pages
+git worktree add --quiet "$WORKTREE" origin/gh-pages
+
+# Sanity: the protected paths must exist in the current gh-pages before we start.
+for p in "${PROTECTED[@]}"; do
+  [ -e "$WORKTREE/$p" ] || { echo "error: expected '$p' on gh-pages but it's missing — aborting before any change" >&2; exit 1; }
+done
+
+echo "==> Copying docs-site/ into gh-pages worktree (additive, no deletes)"
+# Trailing '/.' copies contents (including dotfiles) without removing anything
+# already present in the destination — so fdroid/, privacy/, .nojekyll stay.
+cp -a "$SRC/." "$WORKTREE/"
+
+# Post-copy guard: the protected paths must STILL be present and non-empty.
+for p in "${PROTECTED[@]}"; do
+  if [ ! -e "$WORKTREE/$p" ]; then
+    echo "error: '$p' disappeared after copy — refusing to deploy" >&2; exit 1
+  fi
+done
+# fdroid/ must still contain its repo index, or we'd be shipping a broken repo.
+if [ ! -s "$WORKTREE/fdroid/repo/index-v1.json" ] && [ ! -s "$WORKTREE/fdroid/repo/index-v2.json" ]; then
+  echo "error: fdroid/repo index missing/empty after copy — refusing to deploy" >&2; exit 1
+fi
+
+cd "$WORKTREE"
+git add -A
+if git diff --cached --quiet; then
+  echo "==> No changes to deploy — gh-pages already matches docs-site/."
+  exit 0
+fi
+
+echo "==> Changes to deploy:"
+git diff --cached --stat
+
+if [ "$DRY_RUN" = "1" ]; then
+  echo "==> --dry-run: not committing or pushing."
+  exit 0
+fi
+
+SRC_SHA="$(cd "$REPO_ROOT" && git rev-parse --short HEAD)"
+git commit --quiet -m "deploy: docs-site from ${SRC_SHA}"
+echo "==> Pushing to origin gh-pages"
+git push --quiet origin HEAD:gh-pages
+echo "==> Deployed. Live at https://dzianisv.github.io/opencode-mobile/"