docsfy 1.0.0__tar.gz

docsfy-1.0.0/.coderabbit.yaml

@@ -0,0 +1,90 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# CodeRabbit AI Review Instructions
+# Based on project-specific rules from CLAUDE.md
+
+# Language for reviews
+language: en-US
+
+# Review tone and communication style (max 250 chars)
+tone_instructions: "Be direct and specific. Explain WHY rules exist. Provide code examples. Distinguish critical violations from suggestions. Use severity levels: CRITICAL (blocking/security), HIGH (types/defensive), MEDIUM (style), LOW (suggestions)."
+
+# Enable early access features
+early_access: true
+
+reviews:
+  # Review profile: assertive for strict enforcement
+  profile: assertive
+
+  # Request changes for critical violations
+  request_changes_workflow: true
+
+  # Review display settings
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: false
+
+  # Auto-review configuration
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches:
+      - main
+
+  # Enable relevant tools for Python/JavaScript project
+  tools:
+    # Python linting
+    ruff:
+      enabled: true
+    pylint:
+      enabled: true
+
+    # JavaScript linting
+    eslint:
+      enabled: true
+
+    # Shell script checking
+    shellcheck:
+      enabled: true
+
+    # YAML validation
+    yamllint:
+      enabled: true
+
+    # Security scanning
+    gitleaks:
+      enabled: true
+    semgrep:
+      enabled: true
+
+    # GitHub Actions workflow validation
+    actionlint:
+      enabled: true
+
+    # Dockerfile linting
+    hadolint:
+      enabled: true
+
+# Knowledge base configuration
+knowledge_base:
+  # Enable code guidelines enforcement from CLAUDE.md
+  code_guidelines:
+    enabled: true
+    filePatterns:
+      - "CLAUDE.md"
+
+  # Enable learning from repository patterns
+  learnings:
+    scope: auto
+
+  # Enable learning from issues
+  issues:
+    scope: auto
+
+  # Enable learning from pull requests
+  pull_requests:
+    scope: auto
+
+# Chat settings
+chat:
+  auto_reply: true

docsfy-1.0.0/.env.example

@@ -0,0 +1,20 @@
+# Required: Admin password (minimum 16 characters)
+ADMIN_KEY=
+
+# AI provider and model defaults
+# (pydantic_settings reads these case-insensitively)
+AI_PROVIDER=cursor
+AI_MODEL=gpt-5.4-xhigh-fast
+AI_CLI_TIMEOUT=60
+
+# Logging
+LOG_LEVEL=INFO
+
+# Data directory for database and generated docs
+DATA_DIR=/data
+
+# Cookie security (set to false for local HTTP development)
+SECURE_COOKIES=true
+
+# Development mode: starts Vite dev server on port 5173 alongside FastAPI
+# DEV_MODE=true

docsfy-1.0.0/.flake8

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

docsfy-1.0.0/.git

@@ -0,0 +1 @@
+gitdir: /tmp/github-webhook-docsfy-wzaziokq/.git/worktrees/github-webhook-docsfy-wzaziokq-worktree-b648ccfc-c727-42e5-9ced-53b32db8489e

docsfy-1.0.0/.gitignore

@@ -0,0 +1,43 @@
+# Environment files with secrets
+.env
+.dev/.env
+*.env.local
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+
+# Tox
+.tox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Data
+data/
+.dev/data/
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Build
+dist/
+build/
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+
+UI-TESTS-RESULTS.md

docsfy-1.0.0/.gitleaks.toml

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

docsfy-1.0.0/.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.6
+    hooks:
+      - id: ruff
+      - id: ruff-format
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    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]

docsfy-1.0.0/CLAUDE.md

@@ -0,0 +1,91 @@
+# docsfy Project Rules
+
+## Private Data (HARD RULE)
+
+**NEVER include private data in any file tracked by git.** This includes:
+- API keys, passwords, tokens, credentials
+- Internal URLs, IP addresses, hostnames
+- User-specific configuration values
+
+All secrets MUST be read from environment variables at runtime. Test plans use placeholders like `<ADMIN_KEY>`, `<TEST_USER_PASSWORD>` — never actual values.
+
+## Entry Points
+
+- `docsfy` — CLI for managing projects, users, and config from the terminal
+- `docsfy-server` — starts the FastAPI server (uvicorn)
+
+## Code Reusability (MANDATORY)
+
+**Every element used more than once MUST be defined in ONE place and reused everywhere.**
+
+When adding new code:
+1. Check if a shared constant, style, or function already exists (see inventory below)
+2. If it does, USE IT — do not redefine
+3. If it doesn't but will be used in 2+ places, CREATE it in the appropriate shared location
+4. Never duplicate CSS classes, constants, validators, or utility functions across files
+
+### Where Shared Resources Live
+
+| Resource Type | Location | Examples |
+|---|---|---|
+| Python constants | `src/docsfy/models.py` | `VALID_PROVIDERS`, `DEFAULT_BRANCH`, `DOCSFY_DOCS_URL`, `DOCSFY_REPO_URL` |
+| Data models | `src/docsfy/models.py` | `GenerateRequest`, `DocPlan`, `DocPage`, `NavGroup` |
+| DB constants & validators | `src/docsfy/storage.py` | `VALID_STATUSES`, `VALID_ROLES`, `_validate_name()`, `_validate_owner()` |
+| Git timeouts | `src/docsfy/repository.py` | `_CLONE_TIMEOUT`, `_FETCH_TIMEOUT`, `_DIFF_TIMEOUT` |
+| Prompt constants | `src/docsfy/prompts.py` | `_MAX_DIFF_LENGTH`, `_PAGE_WRITING_RULES` |
+| Frontend constants | `frontend/src/lib/constants.ts` | API base URL, poll intervals, toast durations |
+| Frontend types | `frontend/src/types/index.ts` | `Project`, `User`, `Variant`, `AuthState` |
+| Frontend API client | `frontend/src/lib/api.ts` | `fetchProjects()`, `login()`, `generateDocs()` |
+| Frontend WebSocket | `frontend/src/lib/websocket.ts` | `useWebSocket()`, connection manager |
+| Doc site base template | `src/docsfy/templates/_doc_base.html` | Sidebar, top bar, footer, script imports |
+| CLI config | `~/.config/docsfy/config.toml` | Server URL, API key, default provider/model |
+
+### Rules for New CSS
+
+- App UI styles are managed by Tailwind CSS in the React frontend (`frontend/`)
+- The old `_app_styles.html` has been removed — do not recreate it
+- Doc site templates (`_doc_base.html`, `index.html`, `page.html`) have their own self-contained CSS
+- Use Tailwind utility classes and shadcn/ui components for all new app UI
+
+### Rules for New Constants
+
+- If a value is used in 2+ files → define in `models.py` and import
+- If a value is used in SQL → accepted exception (SQL DDL can't reference Python vars)
+- Magic numbers → named constants in the file that owns them
+- Frontend constants → define in `frontend/src/lib/constants.ts`
+
+### Rules for Templates
+
+- Only doc site templates remain: `_doc_base.html`, `_sidebar.html`, `_theme.html`, `index.html`, `page.html`
+- `index.html` and `page.html` extend `_doc_base.html`
+- App UI (dashboard, admin, login, status) is now a React SPA in `frontend/`
+- Template variables (provider list, branch, URLs) come from the backend — never hardcoded in HTML
+
+## Branch Support
+
+- `branch` is a field on `GenerateRequest` (default: `"main"`)
+- Branch is part of the DB primary key: `(name, branch, ai_provider, ai_model, owner)`
+- URL pattern: `/{name}/{branch}/{provider}/{model}`
+- Branch validation: `^[a-zA-Z0-9][a-zA-Z0-9._-]*$` — slashes are rejected because branch appears as a single FastAPI path segment and in JS split('/') parsing. Use hyphens instead (e.g., `release-1.x` instead of `release/1.x`).
+- Disk path: `PROJECTS_DIR / owner / name / branch / provider / model`
+
+## Default AI Provider/Model
+
+- Configured via environment variables (pydantic_settings loads environment variables which override config defaults)
+- Currently: `cursor` / `gpt-5.4-xhigh-fast`
+- The UI always uses server defaults for new repos — provider/model are NOT persisted in sessionStorage
+
+## Testing
+
+- Run tests: `uv run pytest -v --tb=short`
+- E2e test plans: `test-plans/e2e-*.md`
+- Test repo: `https://github.com/myk-org/for-testing-only` (branches: `main`, `dev`)
+
+## E2E Test Plans
+
+- E2e test plans live in `test-plans/e2e-*.md`
+- **After ANY code change that affects the UI, API endpoints, or user-facing behavior, update or add e2e tests accordingly**
+- When adding a new feature: add a new test section to the relevant e2e plan file (or create a new `e2e-XX-*.md` file)
+- When modifying existing behavior: update the affected test steps, expected results, and URLs
+- When changing URL patterns: update ALL e2e test files that reference those URLs
+- The e2e test index is `test-plans/e2e-ui-test-plan.md` — update the Summary table when adding new tests

docsfy-1.0.0/Dockerfile

@@ -0,0 +1,122 @@
+# Stage 1: Frontend Builder
+FROM node:20-slim AS frontend-builder
+
+WORKDIR /app/frontend
+
+# Install dependencies first (better layer caching)
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+
+# Copy full frontend directory and build
+COPY frontend/ ./
+RUN npm run build
+
+# Stage 2: Python Builder
+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
+
+# Stage 3: Runtime
+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
+
+# Always fetch the latest versions of these CLI tools at build time.
+
+# 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
+
+# Copy frontend build output
+COPY --chown=appuser:0 --from=frontend-builder /app/frontend/dist /app/frontend/dist
+
+# Copy frontend package files for DEV_MODE (npm ci)
+COPY --chown=appuser:0 frontend/package.json frontend/package-lock.json /app/frontend/
+
+# Copy entrypoint script
+COPY --chown=appuser:0 entrypoint.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+
+# 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
+# Vite dev server (DEV_MODE only)
+EXPOSE 5173
+
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+  CMD curl -f http://localhost:8000/health || exit 1
+
+ENTRYPOINT ["/app/entrypoint.sh"]

docsfy-1.0.0/OWNERS

@@ -0,0 +1,4 @@
+approvers:
+  - myakove
+reviewers:
+  - myakove

docsfy-1.0.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: docsfy
+Version: 1.0.0
+Summary: AI-powered documentation generator - generates polished static HTML docs from GitHub repos
+Project-URL: Documentation, https://myk-org.github.io/docsfy-docs/
+Project-URL: Repository, https://github.com/myk-org/docsfy
+Requires-Python: >=3.12
+Requires-Dist: ai-cli-runner
+Requires-Dist: aiosqlite
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: jinja2
+Requires-Dist: markdown
+Requires-Dist: pydantic-settings
+Requires-Dist: pygments
+Requires-Dist: python-multipart>=0.0.22
+Requires-Dist: python-simple-logger
+Requires-Dist: tomli-w
+Requires-Dist: typer[all]
+Requires-Dist: uvicorn
+Requires-Dist: websockets
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'

docsfy-1.0.0/README.md

@@ -0,0 +1,98 @@
+# 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-docs/) | [**GitHub**](https://github.com/myk-org/docsfy)
+
+## Architecture
+
+- **React SPA** -- Single-page web UI with sidebar project tree, inline generation progress, and admin panels
+- **WebSocket** -- Real-time generation progress streamed to the browser (no polling)
+- **CLI** -- Full-featured `docsfy` command for scripting and terminal workflows
+- **FastAPI backend** -- REST API with JWT authentication
+
+Entry points:
+
+| Command | Description |
+|---|---|
+| `docsfy` | CLI tool for generating docs, managing projects, and admin tasks |
+| `docsfy-server` | Starts the FastAPI web server with the React UI |
+
+## Documentation
+
+Full documentation is available at [https://myk-org.github.io/docsfy-docs/](https://myk-org.github.io/docsfy-docs/)
+
+## Quick Start
+
+### Web UI
+
+```bash
+# Clone and configure
+git clone https://github.com/myk-org/docsfy.git
+cd docsfy
+cp .env.example .env
+# Edit .env -- set ADMIN_KEY (minimum 16 characters)
+
+# Run
+docker compose up
+
+# Open the web UI
+open http://localhost:8000         # macOS
+# xdg-open http://localhost:8000   # Linux
+# start http://localhost:8000      # Windows
+```
+
+Log in with admin credentials, add a GitHub repository URL, and watch generation progress in real time via WebSocket.
+
+### CLI
+
+```bash
+# Install
+pip install docsfy
+
+# Initialize CLI config
+docsfy config init
+# Edit ~/.config/docsfy/config.toml with server URL and credentials
+
+# Generate docs for a repository
+docsfy generate https://github.com/org/repo
+
+# List projects
+docsfy projects list
+
+# View generation status
+docsfy projects status org/repo
+```
+
+### API
+
+```bash
+# Authenticate
+TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "admin", "password": "<ADMIN_KEY>"}' | jq -r .access_token)
+
+# Generate docs
+curl -X POST http://localhost:8000/api/projects \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"repo_url": "https://github.com/org/repo"}'
+
+# List projects
+curl http://localhost:8000/api/projects \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## Configuration
+
+### Server (.env)
+
+See `.env.example` for all available environment variables.
+
+### CLI (~/.config/docsfy/config.toml)
+
+See `config.toml.example` for the CLI configuration format.
+
+## License
+
+Apache-2.0

docsfy-1.0.0/config.toml.example

@@ -0,0 +1,25 @@
+# docsfy CLI configuration
+# Copy to ~/.config/docsfy/config.toml or run: docsfy config init
+#
+# SECURITY: This file contains passwords. Keep it private:
+#   chmod 600 ~/.config/docsfy/config.toml
+
+# Default server to use when --server is not specified
+[default]
+server = "dev"
+
+# Server profiles -- add as many as you need
+[servers.dev]
+url = "http://localhost:8000"
+username = "admin"
+password = "<your-dev-key>"
+
+[servers.prod]
+url = "https://docsfy.example.com"
+username = "admin"
+password = "<your-prod-key>"
+
+[servers.staging]
+url = "https://staging.docsfy.example.com"
+username = "deployer"
+password = "<your-staging-key>"

docsfy-1.0.0/docker-compose.yaml

@@ -0,0 +1,22 @@
+services:
+  docsfy:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+      # Uncomment for development (DEV_MODE=true)
+      # - "5173:5173"
+    volumes:
+      - ./data:/data
+      # Uncomment for development (hot reload)
+      # - ./frontend:/app/frontend
+    env_file:
+      - .env
+    environment:
+      # WARNING: ADMIN_KEY must be set in your .env file or shell environment.
+      # An empty ADMIN_KEY will cause the application to reject all admin requests.
+      - ADMIN_KEY=${ADMIN_KEY}
+      # Uncomment for development
+      # - DEV_MODE=true
+    restart: unless-stopped

docsfy-1.0.0/entrypoint.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -e
+
+if [ "$DEV_MODE" = "true" ]; then
+    echo "DEV_MODE enabled - installing frontend dependencies..."
+    cd /app/frontend || exit 1
+    npm ci
+    echo "Starting Vite dev server on port 5173..."
+    npm run dev &
+    VITE_PID=$!
+    # Forward signals to the background Vite process for clean shutdown
+    trap 'kill $VITE_PID 2>/dev/null; wait $VITE_PID 2>/dev/null' SIGTERM SIGINT
+    cd /app
+    echo "Starting FastAPI with hot reload on port 8000..."
+    uv run --no-sync uvicorn docsfy.main:app \
+        --host 0.0.0.0 --port 8000 \
+        --reload --reload-dir /app/src
+else
+    exec uv run --no-sync uvicorn docsfy.main:app \
+        --host 0.0.0.0 --port 8000
+fi

docsfy-1.0.0/frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?