ssl-pydev 0.1.0__tar.gz

ssl_pydev-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+## C-specific ignores
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Linker files
+*.ilk
+
+# Debugger Files
+*.pdb
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+# debug information files
+*.dwo
+
+## Python-specific ignores
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+*.whl
+.venv/
+
+# Development tools
+.pytest_cache/
+.ruff_cache/
+.tox/
+.coverage
+htmlcov/
+cov.xml
+.mypy_cache/
+.vscode/
+.idea/
+
+# External dependencies
+external/
+
+# Temporary files
+*.tmp
+*.temp
+*~
+.DS_Store
+
+## Others
+/tmp
+/output
+
+_version.py
+
+# Doc site
+site
+
+# Security scan results
+semgrep-results.json

ssl_pydev-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesús Bautista Villar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ssl_pydev-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: ssl_pydev
+Version: 0.1.0
+Summary: Shared local-dev CLI for Swarm Systems Lab Python projects
+Author-email: Jesus Bautista Villar <jesbauti20@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: semgrep>=1.54.0; extra == 'dev'
+Requires-Dist: tox-uv>=1.9; extra == 'dev'
+Requires-Dist: tox>=4.18; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Requires-Dist: ty>=0.0.14; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: ruff>=0.9.0; extra == 'lint'
+Requires-Dist: semgrep>=1.54.0; extra == 'lint'
+Provides-Extra: pre-commit
+Requires-Dist: pre-commit>=3.0; extra == 'pre-commit'
+Provides-Extra: release
+Requires-Dist: build>=1.2.2; extra == 'release'
+Requires-Dist: twine>=5.1.1; extra == 'release'
+Provides-Extra: tests
+Requires-Dist: pytest-cov>=4.0; extra == 'tests'
+Requires-Dist: pytest>=7.0; extra == 'tests'
+Provides-Extra: type-checking
+Requires-Dist: ty>=0.0.14; extra == 'type-checking'
+Description-Content-Type: text/markdown
+
+# ssl_pydev
+
+Shared local-dev CLI for `Swarm-Systems-Lab` Python projects. Wraps the same
+build/publish/docs-validation logic that `ssl_ci`'s composite actions run in CI,
+packaged here so it can be installed **once per machine** instead of copy-pasted
+into every project's `scripts/` directory.
+
+## Install
+
+```bash
+uv tool install ssl_pydev
+```
+
+This installs a single `ssl-pydev` command, available from any project
+directory, independent of that project's own virtualenv/dependencies.
+
+## Usage
+
+```bash
+ssl-pydev setup-env --extras dev,tests
+ssl-pydev build
+ssl-pydev build-native     # for compiled-extension (pybind11/scikit-build-core) projects
+ssl-pydev publish          # uv-based publish, requires UV_PUBLISH_* env vars
+ssl-pydev publish-ci       # twine-based publish, requires TWINE_* env vars
+ssl-pydev validate-docs
+```
+
+Every command operates on the current working directory, so run it from the
+root of the project you want to act on - same as the `scripts/*.sh` files it
+replaces. A project's `justfile` recipes become one-liners, e.g.:
+
+```just
+setup:
+    ssl-pydev setup-env --extras dev,lint,tests,type-checking,pre-commit
+```
+
+## Relationship to `ssl_ci`
+
+- `ssl_ci` holds the **GitHub Actions** side: reusable workflows and composite
+  actions that CI calls directly via `uses:`.
+- `ssl_pydev` (this repo) holds the **local-dev** side: the same logic,
+  installed once per developer machine via `uv tool install`.
+
+Today the two are maintained in parallel (the underlying `.sh` scripts started
+as copies of each other). Once this package has at least one published
+release, the plan is to update `ssl_ci`'s composite actions to install and
+call `ssl_pydev` themselves, so there's a single source of truth used by
+both CI and local dev.
+
+## Versioning
+
+Released the same way as the other `Swarm-Systems-Lab` packages: tag `vX.Y.Z`,
+push, and `ssl_ci`'s `publish.yml` builds and uploads to PyPI.

ssl_pydev-0.1.0/README.md

@@ -0,0 +1,53 @@
+# ssl_pydev
+
+Shared local-dev CLI for `Swarm-Systems-Lab` Python projects. Wraps the same
+build/publish/docs-validation logic that `ssl_ci`'s composite actions run in CI,
+packaged here so it can be installed **once per machine** instead of copy-pasted
+into every project's `scripts/` directory.
+
+## Install
+
+```bash
+uv tool install ssl_pydev
+```
+
+This installs a single `ssl-pydev` command, available from any project
+directory, independent of that project's own virtualenv/dependencies.
+
+## Usage
+
+```bash
+ssl-pydev setup-env --extras dev,tests
+ssl-pydev build
+ssl-pydev build-native     # for compiled-extension (pybind11/scikit-build-core) projects
+ssl-pydev publish          # uv-based publish, requires UV_PUBLISH_* env vars
+ssl-pydev publish-ci       # twine-based publish, requires TWINE_* env vars
+ssl-pydev validate-docs
+```
+
+Every command operates on the current working directory, so run it from the
+root of the project you want to act on - same as the `scripts/*.sh` files it
+replaces. A project's `justfile` recipes become one-liners, e.g.:
+
+```just
+setup:
+    ssl-pydev setup-env --extras dev,lint,tests,type-checking,pre-commit
+```
+
+## Relationship to `ssl_ci`
+
+- `ssl_ci` holds the **GitHub Actions** side: reusable workflows and composite
+  actions that CI calls directly via `uses:`.
+- `ssl_pydev` (this repo) holds the **local-dev** side: the same logic,
+  installed once per developer machine via `uv tool install`.
+
+Today the two are maintained in parallel (the underlying `.sh` scripts started
+as copies of each other). Once this package has at least one published
+release, the plan is to update `ssl_ci`'s composite actions to install and
+call `ssl_pydev` themselves, so there's a single source of truth used by
+both CI and local dev.
+
+## Versioning
+
+Released the same way as the other `Swarm-Systems-Lab` packages: tag `vX.Y.Z`,
+push, and `ssl_ci`'s `publish.yml` builds and uploads to PyPI.

ssl_pydev-0.1.0/pyproject.toml

@@ -0,0 +1,179 @@
+[build-system]
+requires = [
+    "hatchling",
+    "hatch-vcs",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "ssl_pydev"
+dynamic = ["version"]
+description = "Shared local-dev CLI for Swarm Systems Lab Python projects"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+    { name = "Jesus Bautista Villar", email = "jesbauti20@gmail.com" }
+]
+dependencies = []
+
+[project.scripts]
+ssl-pydev = "ssl_pydev.cli:main"
+
+# --- Optional dependencies for tooling ---
+[project.optional-dependencies]
+dev = [
+    "tox>=4.18",
+    "tox-uv>=1.9",
+    "ruff>=0.9.0",
+    "semgrep>=1.54.0",
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "pre-commit>=3.0",
+    "ty>=0.0.14",
+    "build>=1.2.2",
+    "twine>=5.1.1",
+]
+lint = [
+    "ruff>=0.9.0",
+    "semgrep>=1.54.0",
+]
+tests = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+pre-commit = [
+    "pre-commit>=3.0",
+]
+type-checking = [
+    "ty>=0.0.14",
+]
+release = [
+    "build>=1.2.2",
+    "twine>=5.1.1",
+]
+
+# --- Hatch Configuration ---
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+local_scheme = "no-local-version"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ssl_pydev"]
+artifacts = ["src/ssl_pydev/scripts/*.sh"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]
+exclude = ["tests"]
+
+# --- Tool Configuration ---
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W", "I", "UP", "B", "A", "C4", "T20", "SIM", "RUF", "S",
+]
+ignore = [
+    "D100", "D104", "E501", "F403", "F401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S603"]
+"src/ssl_pydev/cli.py" = ["T201", "S603", "S607"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = ["-v", "--tb=short", "--strict-markers"]
+
+[tool.coverage.run]
+source = ["src/ssl_pydev"]
+omit = ["tests/*"]
+
+# Use uv for fast, reproducible environments
+[tool.tox]
+requires = ["tox-uv>=1.0"]
+env_list = [
+    "pre-commit",
+    "lint",
+    "security",
+    "tests",
+    "py312",
+    "py313",
+    "py314",
+    "build",
+]
+
+[tool.tox.env_run_base]
+passenv = ["*"]
+
+[tool.tox.env.pre-commit]
+description = "Run pre-commit hooks"
+extras = ["pre-commit"]
+commands = [
+    ["pre-commit", "run", "--all-files", "--show-diff-on-failure"],
+]
+
+[tool.tox.env.lint]
+description = "Run ruff linting and formatting"
+extras = ["lint"]
+commands = [
+    ["ruff", "check", "src", "tests"],
+    ["ruff", "format", "--check", "src", "tests"],
+]
+
+[tool.tox.env.security]
+description = "Run semgrep security scans"
+extras = ["lint"]
+commands = [
+    ["semgrep", "--config", "p/ci", "--config", ".semgrep.yml"],
+]
+
+[tool.tox.env.type-checking]
+description = "Run ty type checks"
+extras = ["type-checking"]
+commands = [
+    ["ty", "check"],
+]
+
+[tool.tox.env.tests]
+extras = ["tests"]
+commands = [
+    ["pytest", "--cov=ssl_pydev", "--cov-report", "term", "--cov-report", "xml:cov.xml"],
+]
+
+[tool.tox.env.py312]
+base_python = ["python3.12"]
+extras = ["tests"]
+commands = [
+    ["pytest", "tests"],
+]
+
+[tool.tox.env.py313]
+base_python = ["python3.13"]
+extras = ["tests"]
+commands = [
+    ["pytest", "tests"],
+]
+
+[tool.tox.env.py314]
+base_python = ["python3.14"]
+extras = ["tests"]
+commands = [
+    ["pytest", "tests"],
+]
+
+[tool.tox.env.build]
+description = "Build sdist and wheel artifacts"
+extras = ["release"]
+commands = [
+    ["python", "-m", "build", "--sdist", "--wheel", "--outdir", "dist"],
+]

ssl_pydev-0.1.0/src/ssl_pydev/__init__.py

@@ -0,0 +1 @@
+"""Shared local-dev CLI for Swarm Systems Lab Python projects."""

ssl_pydev-0.1.0/src/ssl_pydev/cli.py

@@ -0,0 +1,86 @@
+"""ssl_pydev CLI - shared local-dev commands for Swarm Systems Lab Python projects.
+
+These wrap the same scripts ssl_ci's composite actions use in CI, packaged here so
+they can be installed once per machine (``uv tool install ssl-pydev``) instead
+of being copy-pasted into every project's scripts/ directory.
+"""
+
+import argparse
+import subprocess
+import sys
+from importlib import resources
+
+SCRIPTS_MAP = {
+    "setup-env": "setup-env.sh",
+    "build": "build.sh",
+    "build-native": "build_native.sh",
+    "publish": "publish.sh",
+    "publish-ci": "publish_ci.sh",
+    "validate-docs": "validate_docs.sh",
+}
+
+EPILOG = """
+Examples:
+  ssl-pydev setup-env --extras dev,tests
+  ssl-pydev build
+  ssl-pydev build-native
+  ssl-pydev publish-ci
+  ssl-pydev validate-docs
+
+All commands accept additional arguments which are passed through to the
+underlying script. Commands run against the current working directory, so
+invoke this from the root of the project you want to act on.
+"""
+
+
+def _get_script(command: str) -> str:
+    """Return the path to a bundled script by command name."""
+    if command not in SCRIPTS_MAP:
+        raise ValueError(f"Unknown command: {command}")
+
+    script_ref = resources.files("ssl_pydev.scripts").joinpath(SCRIPTS_MAP[command])
+    if not script_ref.is_file():
+        raise FileNotFoundError(f"Bundled script not found: {script_ref}")
+    return str(script_ref)
+
+
+def _run_script(command: str, args: list) -> int:
+    """Execute a bundled script with the given arguments."""
+    try:
+        script_path = _get_script(command)
+    except (FileNotFoundError, ValueError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    result = subprocess.run(["bash", script_path, *args], check=False)
+    return result.returncode
+
+
+def main() -> int:
+    """Main CLI entry point."""
+    if len(sys.argv) < 2 or sys.argv[1] in ["-h", "--help", "help"]:
+        parser = argparse.ArgumentParser(
+            prog="ssl-pydev",
+            description="Swarm Systems Lab shared local-dev CLI",
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+            epilog=EPILOG,
+        )
+        subparsers = parser.add_subparsers(dest="command", help="Available commands")
+        for cmd in sorted(SCRIPTS_MAP.keys()):
+            subparsers.add_parser(cmd, help=f"Run {cmd}")
+        parser.print_help()
+        return 0
+
+    command = sys.argv[1]
+    script_args = sys.argv[2:]
+
+    if command not in SCRIPTS_MAP:
+        print(f"Error: Unknown command '{command}'", file=sys.stderr)
+        print(f"Available commands: {', '.join(sorted(SCRIPTS_MAP.keys()))}", file=sys.stderr)
+        return 1
+
+    return _run_script(command, script_args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ssl_pydev-0.1.0/src/ssl_pydev/scripts/build.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build sdist + wheel for a pure-Python project. Bootstraps the venv if needed.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(pwd)"
+
+if [ ! -d "$ROOT_DIR/.venv" ]; then
+	"$SCRIPT_DIR/setup-env.sh" --extras dev,release
+fi
+
+. .venv/bin/activate
+
+echo "Preparing build output directory"
+rm -rf dist
+mkdir -p dist
+
+echo "Running tox build environment"
+uv run tox -e build
+
+echo "Build artifacts placed in dist/"

ssl_pydev-0.1.0/src/ssl_pydev/scripts/build_native.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build sdist + cibuildwheel wheels for a compiled-extension project.
+# Bootstraps the venv if needed.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(pwd)"
+
+if [ ! -d "$ROOT_DIR/.venv" ]; then
+	"$SCRIPT_DIR/setup-env.sh" --extras dev,release
+fi
+
+. .venv/bin/activate
+
+echo "Preparing build output directory"
+rm -rf dist
+mkdir -p dist
+
+echo "Running tox build environment (sdist + wheel)"
+uv run tox -e build
+
+echo "Running tox cibuildwheel environment (multiplatform wheels)"
+uv run tox -e cibuildwheel
+
+echo "Build artifacts placed in dist/"

ssl_pydev-0.1.0/src/ssl_pydev/scripts/publish.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Local publish using uv's built-in publishing support.
+# SCRIPT_DIR: where this script is located (for finding setup-env.sh)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(pwd)"
+
+if [ ! -d "$ROOT_DIR/.venv" ]; then
+	"$SCRIPT_DIR/setup-env.sh" --extras dev,release
+fi
+
+. .venv/bin/activate
+
+if [ -z "${UV_PUBLISH_USERNAME-}" ] || [ -z "${UV_PUBLISH_PASSWORD-}" ] || [ -z "${UV_PUBLISH_REPOSITORY_URL-}" ]; then
+	echo "Missing publishing credentials (UV_PUBLISH_USERNAME / UV_PUBLISH_PASSWORD / UV_PUBLISH_REPOSITORY_URL)" >&2
+	exit 1
+fi
+
+if [ ! -d dist ] || [ -z "$(ls -A dist 2>/dev/null)" ]; then
+	echo "No artifacts found in dist/ - nothing to publish" >&2
+	exit 1
+fi
+
+echo "Publishing artifacts from dist/ using uv"
+uv publish --repository-url "$UV_PUBLISH_REPOSITORY_URL" --username "$UV_PUBLISH_USERNAME" --password "$UV_PUBLISH_PASSWORD" dist/*
+
+echo "Publish finished"

ssl_pydev-0.1.0/src/ssl_pydev/scripts/publish_ci.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# CI-friendly publish using twine with credentials from the environment.
+# SCRIPT_DIR: where this script is located (for finding setup-env.sh)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(pwd)"
+
+if [ ! -d "$ROOT_DIR/.venv" ]; then
+	"$SCRIPT_DIR/setup-env.sh" --extras dev,release
+fi
+
+. .venv/bin/activate
+
+if [ -z "${TWINE_USERNAME-}" ] || [ -z "${TWINE_PASSWORD-}" ] || [ -z "${TWINE_REPOSITORY_URL-}" ]; then
+	echo "Missing publishing credentials (TWINE_USERNAME / TWINE_PASSWORD / TWINE_REPOSITORY_URL)" >&2
+	exit 1
+fi
+
+if [ ! -d dist ] || [ -z "$(ls -A dist 2>/dev/null)" ]; then
+	echo "No artifacts found in dist/ - nothing to publish" >&2
+	exit 1
+fi
+
+echo "Publishing artifacts from dist/ using twine"
+python -m twine upload --verbose --non-interactive --repository-url "$TWINE_REPOSITORY_URL" dist/*
+
+echo "Publish finished"

ssl_pydev-0.1.0/src/ssl_pydev/scripts/setup-env.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Bootstraps a uv-managed virtualenv for the calling project.
+# Mirrors ssl_ci's actions/env-setup/setup-env.sh - this is the local-dev counterpart.
+
+EXTRA_LIST=()
+ALL_EXTRAS=0
+FROZEN=1
+EXTRA_PACKAGES=()
+
+usage() {
+	echo "Usage: $0 [--extras <comma-separated>] [--all-extras] [--no-frozen] [--with <pkg> ...]" >&2
+	exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+	case "$1" in
+		--extras)
+			[[ $# -ge 2 ]] || usage
+			IFS=',' read -r -a EXTRA_LIST <<< "$2"
+			shift 2
+			;;
+		--all-extras)
+			ALL_EXTRAS=1
+			shift
+			;;
+		--no-frozen)
+			FROZEN=0
+			shift
+			;;
+		--with)
+			[[ $# -ge 2 ]] || usage
+			EXTRA_PACKAGES+=("$2")
+			shift 2
+			;;
+		*)
+			usage
+			;;
+	esac
+done
+
+if ! command -v uv >/dev/null 2>&1; then
+	curl -LsSf https://astral.sh/uv/install.sh | sh
+	export PATH="$HOME/.local/bin:$PATH"
+fi
+
+if ! command -v just >/dev/null 2>&1; then
+	curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin
+	export PATH="$HOME/.local/bin:$PATH"
+fi
+
+if [ ! -d .venv ]; then
+	uv venv .venv
+fi
+
+. .venv/bin/activate
+
+SYNC_ARGS=(sync)
+((FROZEN)) && SYNC_ARGS+=("--frozen")
+
+if ((ALL_EXTRAS)); then
+	SYNC_ARGS+=("--all-extras")
+elif [ ${#EXTRA_LIST[@]} -gt 0 ]; then
+	for extra in "${EXTRA_LIST[@]}"; do
+		SYNC_ARGS+=("--extra" "$extra")
+	done
+fi
+
+uv "${SYNC_ARGS[@]}"
+
+if [ ${#EXTRA_PACKAGES[@]} -gt 0 ]; then
+	uv add "${EXTRA_PACKAGES[@]}"
+fi

ssl_pydev-0.1.0/src/ssl_pydev/scripts/validate_docs.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Validate the documentation build output without rebuilding it.
+
+set -euo pipefail
+IFS=$'\n\t'
+
+PROJECT_ROOT="$(pwd)"
+SITE_DIR="${SITE_DIR:-$PROJECT_ROOT/site}"
+MKDOCS_CONFIG="${MKDOCS_CONFIG:-$PROJECT_ROOT/mkdocs.yml}"
+
+echo "Validating documentation build output..."
+
+if [[ ! -f "$MKDOCS_CONFIG" ]]; then
+  echo "Error: mkdocs config not found at $MKDOCS_CONFIG" >&2
+  exit 1
+fi
+
+if [[ ! -d "$SITE_DIR" ]]; then
+  echo "Error: site directory not found at $SITE_DIR" >&2
+  echo "Build the docs first (e.g., just docs-build)." >&2
+  exit 1
+fi
+
+if [[ ! -s "$SITE_DIR/index.html" ]]; then
+  echo "Error: missing or empty index.html in $SITE_DIR" >&2
+  exit 1
+fi
+
+html_count=$(find "$SITE_DIR" -type f -name '*.html' | wc -l | tr -d ' ')
+if [[ "$html_count" -lt 2 ]]; then
+  echo "Error: expected more than one HTML file in $SITE_DIR" >&2
+  exit 1
+fi
+
+if [[ -f "$SITE_DIR/search/search_index.json" ]]; then
+  if [[ ! -s "$SITE_DIR/search/search_index.json" ]]; then
+    echo "Warning: search index exists but is empty" >&2
+  fi
+else
+  echo "Warning: search index not found at $SITE_DIR/search/search_index.json" >&2
+fi
+
+echo "Documentation validation successful."
+echo "Validated $html_count HTML files in $SITE_DIR"