feat: docsfy - AI-powered documentation generator

.env.example

@@ -0,0 +1,22 @@
+# AI Configuration
+AI_PROVIDER=claude
+# [1m] = 1 million token context window, this is a valid model identifier
+AI_MODEL=claude-opus-4-6[1m]
+AI_CLI_TIMEOUT=60
+
+# Claude - Option 1: API Key
+# ANTHROPIC_API_KEY=
+
+# Claude - Option 2: Vertex AI
+# CLAUDE_CODE_USE_VERTEX=1
+# CLOUD_ML_REGION=
+# ANTHROPIC_VERTEX_PROJECT_ID=
+
+# Gemini
+# GEMINI_API_KEY=
+
+# Cursor
+# CURSOR_API_KEY=
+
+# Logging
+LOG_LEVEL=INFO

.flake8

@@ -0,0 +1,11 @@
+[flake8]
+select=M511
+
+exclude =
+    doc,
+    .tox,
+    .git,
+    *.yml,
+    Pipfile.*,
+    docs/*,
+    .cache/*

.gitleaks.toml

@@ -0,0 +1,7 @@
+[extend]
+useDefault = true
+
+[allowlist]
+paths = [
+    '''tests/test_repository\.py''',
+]

.pre-commit-config.yaml

@@ -0,0 +1,60 @@
+---
+default_language_version:
+  python: python3
+
+ci:
+  autofix_prs: false
+  autoupdate_commit_msg: "ci: [pre-commit.ci] pre-commit autoupdate"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-docstring-first
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: detect-private-key
+      - id: mixed-line-ending
+      - id: debug-statements
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: check-ast
+      - id: check-builtin-literals
+      - id: check-toml
+
+  # flake8 retained for RedHatQE M511 plugin; ruff handles standard linting
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.3.0
+    hooks:
+      - id: flake8
+        args: [--config=.flake8]
+        additional_dependencies:
+          # Tracks main branch intentionally for latest RedHatQE flake8 plugins
+          [git+https://github.com/RedHatQE/flake8-plugins.git, flake8-mutable]
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
+    hooks:
+      - id: ruff
+      - id: ruff-format
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        exclude: (tests/)
+        additional_dependencies:
+          [types-requests, types-PyYAML, types-colorama, types-aiofiles, pydantic, types-Markdown]

Dockerfile

@@ -0,0 +1,99 @@
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim AS builder
+
+WORKDIR /app
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:0.5.14 /uv /usr/local/bin/uv
+
+# Install git (needed for gitpython dependency)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy project files
+COPY pyproject.toml uv.lock ./
+COPY src/ src/
+
+# Create venv and install dependencies
+RUN uv sync --frozen --no-dev
+
+# Production stage
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install bash (needed for CLI install scripts), git (required at runtime for gitpython), curl (for Claude CLI), and nodejs/npm (for Gemini CLI)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    bash \
+    git \
+    curl \
+    nodejs \
+    npm \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user, data directory, and set permissions
+# OpenShift runs containers as a random UID in the root group (GID 0)
+RUN useradd --create-home --shell /bin/bash -g 0 appuser \
+    && mkdir -p /data \
+    && chown appuser:0 /data \
+    && chmod -R g+w /data
+
+# Copy uv for runtime
+COPY --from=ghcr.io/astral-sh/uv:0.5.14 /uv /usr/local/bin/uv
+
+# Switch to non-root user for CLI installs
+USER appuser
+
+# Install Claude Code CLI (installs to ~/.local/bin)
+RUN /bin/bash -o pipefail -c "curl -fsSL https://claude.ai/install.sh | bash"
+
+# Install Cursor Agent CLI (installs to ~/.local/bin)
+RUN /bin/bash -o pipefail -c "curl -fsSL https://cursor.com/install | bash"
+
+# Configure npm for non-root global installs and install Gemini CLI
+RUN mkdir -p /home/appuser/.npm-global \
+    && npm config set prefix '/home/appuser/.npm-global' \
+    && npm install -g @google/gemini-cli
+
+# Switch to root for file copies and permission fixes
+USER root
+
+# Copy the virtual environment from builder
+COPY --chown=appuser:0 --from=builder /app/.venv /app/.venv
+
+# Copy project files needed by uv
+COPY --chown=appuser:0 --from=builder /app/pyproject.toml /app/uv.lock ./
+
+# Copy source code
+COPY --chown=appuser:0 --from=builder /app/src /app/src
+
+# Make /app group-writable for OpenShift compatibility
+RUN chmod -R g+w /app
+
+# Make appuser home accessible by OpenShift arbitrary UID
+# Only chmod directories (not files) — files are already group-readable by default.
+# Directories need group write+execute for OpenShift's arbitrary UID (in GID 0)
+# to create config/cache files at runtime.
+RUN find /home/appuser -type d -exec chmod g=u {} + \
+    && npm cache clean --force 2>/dev/null; \
+    rm -rf /home/appuser/.npm/_cacache
+
+# Switch back to non-root user for runtime
+USER appuser
+
+# Ensure CLIs are in PATH
+ENV PATH="/home/appuser/.local/bin:/home/appuser/.npm-global/bin:${PATH}"
+# Set HOME for OpenShift compatibility (random UID has no passwd entry)
+ENV HOME="/home/appuser"
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Use uv run for uvicorn
+# --no-sync prevents uv from attempting to modify the venv at runtime.
+# This is required for OpenShift where containers run as an arbitrary UID
+# and may not have write access to the .venv directory.
+ENTRYPOINT ["uv", "run", "--no-sync", "uvicorn", "docsfy.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -0,0 +1,30 @@
+# docsfy
+
+AI-powered documentation generator that creates polished static HTML docs from GitHub repositories using Claude, Gemini, or Cursor CLI.
+
+[**Documentation**](https://myk-org.github.io/docsfy/) | [**GitHub**](https://github.com/myk-org/docsfy)
+
+## Quick Start
+
+```bash
+# Clone and configure
+git clone https://github.com/myk-org/docsfy.git
+cd docsfy
+cp .env.example .env
+# Edit .env with your AI provider credentials
+
+# Run
+docker compose up
+
+# Generate docs for any repo
+curl -X POST http://localhost:8000/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{"repo_url": "https://github.com/org/repo"}'
+
+# Browse docs
+open http://localhost:8000/docs/repo/
+```
+
+## License
+
+Apache-2.0

docker-compose.yaml

@@ -0,0 +1,13 @@
+services:
+  docsfy:
+    build: .
+    ports:
+      - "8000:8000"
+    env_file: .env
+    volumes:
+      - ./data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3

docs/plans/2026-03-04-docsfy-design.md

@@ -5,7 +5,7 @@
 
 ## Overview
 
-docsfy is an open-source FastAPI service that generates polished, Mintlify-quality static HTML documentation sites from GitHub repositories using AI CLI tools. It supports multiple AI providers (Claude Code, Cursor Agent, Gemini CLI), incremental updates on repository changes, and flexible hosting -- serve docs directly from the API or download the static HTML to host anywhere.
+docsfy is an open-source FastAPI service that generates polished, production-quality static HTML documentation sites from GitHub repositories using AI CLI tools. It supports multiple AI providers (Claude Code, Cursor Agent, Gemini CLI), incremental updates on repository changes, and flexible hosting -- serve docs directly from the API or download the static HTML to host anywhere.
 
 ## Architecture