feat: add documentation sync checker script

script/README.md

@@ -0,0 +1,170 @@
+# Scripts
+
+This directory contains utility scripts for managing configuration, credentials, and development workflows.
+
+## Documentation Scripts
+
+### check-docs-sync.sh
+
+Verifies that generated documentation is synchronized with code changes, preventing documentation drift.
+
+**Purpose**: Ensures developers keep generated documentation in sync with code by failing CI if docs are out of date.
+
+**Usage**:
+
+```bash
+./script/check-docs-sync.sh
+```
+
+**Configuration**:
+
+Set environment variables to customize behavior:
+
+```bash
+# Set documentation generation command (default: npm run docs:generate)
+export DOC_GENERATE_CMD="pnpm run docs:generate"
+
+# Set documentation directory (default: docs)
+export DOCS_DIR="documentation"
+
+# Run the checker
+./script/check-docs-sync.sh
+```
+
+**How It Works**:
+
+1. Creates a backup of current documentation
+2. Runs the documentation generation command
+3. Compares generated docs with the original
+4. Fails with helpful error message if differences are found
+
+**Example Output**:
+
+Success:
+
+```
+📚 Checking documentation sync...
+📝 Generating documentation...
+🔍 Comparing documentation...
+✅ Documentation is in sync!
+```
+
+Failure:
+
+```
+📚 Checking documentation sync...
+📝 Generating documentation...
+🔍 Comparing documentation...
+❌ ERROR: Generated documentation is out of sync!
+
+Differences found:
+...
+
+Please run the following command and commit the changes:
+  npm run docs:generate
+
+Or use the unified command (if available):
+  npm run docs:all
+```
+
+**CI Integration**:
+
+Add to `.github/workflows/ci.yml`:
+
+```yaml
+- name: Check documentation sync
+  run: ./script/check-docs-sync.sh
+```
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "docs:generate": "your-doc-generator-command",
+    "docs:check": "./script/check-docs-sync.sh",
+    "docs:all": "npm run docs:generate && npm run docs:check"
+  }
+}
+```
+
+**Use Cases**:
+
+- Projects with auto-generated API documentation
+- Template-based documentation systems
+- Schema-driven documentation
+- Any project where docs are generated from code/metadata
+
+**Benefits**:
+
+- ✅ Prevents stale documentation
+- ✅ No manual doc update reminders needed
+- ✅ Catches issues before merge
+- ✅ Clear error messages with fix commands
+- ✅ Lightweight (simple bash script, no dependencies)
+
+## Configuration Management Scripts
+
+### export.sh
+
+Exports configuration settings to the home directory.
+
+### import.sh
+
+Imports configuration settings from the home directory.
+
+### commit_changes.sh
+
+Checks for changes and makes commits.
+
+## Credential Management Scripts
+
+### credentials.sh
+
+Secure credential management using 1Password CLI integration.
+
+### setup-env.sh
+
+Sets up environment variables for DevContainer.
+
+### setup-mcp.sh
+
+Sets up MCP (Model Context Protocol) configuration.
+
+## Development Scripts
+
+### setup-claude.sh
+
+Initializes Claude Code CLI configuration.
+
+### version.sh
+
+Semantic versioning helper.
+
+### update-libraries.sh
+
+Automated library updates for Codex/Claude Code tooling.
+
+## Infrastructure Scripts
+
+### brew-deps.sh
+
+Homebrew dependency management.
+
+### verify-container-setup.sh
+
+Verifies DevContainer setup.
+
+### fix-container-plugins.sh
+
+Fixes container plugin issues.
+
+### install-claude-plugins.sh
+
+Installs Claude plugins.
+
+## See Also
+
+- [Main README](../README.md)
+- [Credentials Documentation](../credentials/README.md)
+- [DevContainer Documentation](../.devcontainer/README.md)

script/check-docs-sync.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Documentation Sync Checker
+#
+# This script verifies that generated documentation is synchronized with code changes.
+# It prevents documentation drift by failing CI if docs are out of sync.
+#
+# Usage:
+#   ./script/check-docs-sync.sh
+#
+# Configuration:
+#   Set DOC_GENERATE_CMD to your documentation generation command
+#   Set DOCS_DIR to the directory containing generated documentation
+
+set -euo pipefail
+
+# Configuration
+DOC_GENERATE_CMD="${DOC_GENERATE_CMD:-npm run docs:generate}"
+DOCS_DIR="${DOCS_DIR:-docs}"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}📚 Checking documentation sync...${NC}"
+
+# Create temporary directory for generated docs
+TEMP_DOCS_DIR=$(mktemp -d)
+trap 'rm -rf "$TEMP_DOCS_DIR"' EXIT
+
+# Copy current docs to temp directory for comparison
+if [ -d "$DOCS_DIR" ]; then
+  cp -r "$DOCS_DIR" "$TEMP_DOCS_DIR/original"
+else
+  echo -e "${YELLOW}⚠️  Warning: Documentation directory $DOCS_DIR does not exist${NC}"
+  mkdir -p "$TEMP_DOCS_DIR/original"
+fi
+
+# Generate fresh documentation
+echo -e "${BLUE}📝 Generating documentation...${NC}"
+if ! eval "$DOC_GENERATE_CMD" > /dev/null 2>&1; then
+  echo -e "${RED}❌ ERROR: Documentation generation failed!${NC}"
+  echo -e "${YELLOW}Command: $DOC_GENERATE_CMD${NC}"
+  exit 1
+fi
+
+# Copy generated docs to temp directory
+if [ -d "$DOCS_DIR" ]; then
+  cp -r "$DOCS_DIR" "$TEMP_DOCS_DIR/generated"
+else
+  echo -e "${RED}❌ ERROR: Documentation generation did not create $DOCS_DIR${NC}"
+  exit 1
+fi
+
+# Compare original and generated docs
+echo -e "${BLUE}🔍 Comparing documentation...${NC}"
+if diff -r "$TEMP_DOCS_DIR/original" "$TEMP_DOCS_DIR/generated" > /dev/null 2>&1; then
+  echo -e "${GREEN}✅ Documentation is in sync!${NC}"
+  exit 0
+else
+  echo -e "${RED}❌ ERROR: Generated documentation is out of sync!${NC}"
+  echo ""
+  echo -e "${YELLOW}Differences found:${NC}"
+  diff -r "$TEMP_DOCS_DIR/original" "$TEMP_DOCS_DIR/generated" || true
+  echo ""
+  echo -e "${YELLOW}Please run the following command and commit the changes:${NC}"
+  echo -e "  ${BLUE}$DOC_GENERATE_CMD${NC}"
+  echo ""
+  echo -e "${YELLOW}Or use the unified command (if available):${NC}"
+  echo -e "  ${BLUE}npm run docs:all${NC}"
+  exit 1
+fi