CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository generates OpenAPI 3.0.3 specifications for Proxmox APIs by parsing their JavaScript documentation files. It supports both Proxmox Virtual Environment (PVE) and Proxmox Backup Server (PBS).

Essential Commands

Development Setup

# Install all dependencies (ALWAYS use UV, never pip)
uv sync --extra all

# Run any Python script
uv run python script_name.py

Generate API Specifications

# Generate PVE API specifications
cd scripts/pve && uv run python generate_openapi.py && uv run python convert_to_yaml.py

# Generate PBS API specifications  
cd scripts/pbs && uv run python generate_openapi.py && uv run python convert_to_yaml.py

Code Quality Checks (MUST run before commits)

# Format code
uv run ruff format scripts/

# Check linting
uv run ruff check scripts/

# Type checking
uv run mypy scripts/

# Validate OpenAPI specs
uv run python scripts/validate_openapi.py

# Run ALL validation (recommended)
./scripts/validate-commit.sh

Git Commit Validation

# Validate commit readiness
./scripts/validate-commit.sh

# Commit with automatic validation
./scripts/validate-commit.sh --commit

High-Level Architecture

Data Flow

apidoc.js → Parser → generate_openapi.py → {pve,pbs}-api.json → convert_to_yaml.py → {pve,pbs}-api.yaml

Core Components

Unified Parser (
```
scripts/unified_parser.py
```
):
- Central parsing engine with file caching for performance
- Handles both PVE and PBS with API-specific configurations
- Extracts API schemas from JavaScript using regex patterns
- Standardizes authentication across specifications
API Generators (
```
scripts/{pve,pbs}/generate_openapi.py
```
):
- API-specific wrappers around the unified parser
- Generate JSON specifications in respective output directories
- Handle file path discovery and output placement
Format Converters (
```
scripts/{pve,pbs}/convert_to_yaml.py
```
):
- Convert JSON specifications to YAML format
- Maintain consistent file naming:
```
{pve,pbs}-api.{json,yaml}
```

Key Design Patterns

File Caching: The unified parser caches
```
apidoc.js
```
content with mtime checking to avoid repeated file reads during development.
Configuration-Driven: Each API (PVE/PBS) has an
```
APIConfig
```
dataclass defining:
- Port numbers (PVE: 8006, PBS: 8007)
- Authentication schemes
- Tag mappings for endpoint grouping
- Server paths and metadata
Path Discovery: Scripts automatically search multiple locations for
```
apidoc.js
```
files, supporting flexible directory structures.
Atomic Commits: The project enforces strict commit conventions with separate commits for different change types (features, fixes, dependencies).

Critical File Locations

PVE Output:

proxmox-virtual-environment/pve-api.{json,yaml}

PBS Output:

proxmox-backup-server/pbs-api.{json,yaml}

Source Docs:

{proxmox-virtual-environment,proxmox-backup-server}/apidoc.js

Parsers:

scripts/unified_parser.py

scripts/{pve,pbs}/generate_openapi.py

Expected Outputs

Validate generation success by checking:

PVE: ~1.8MB JSON, ~1.2MB YAML, ~385 endpoints, ~687 operations
PBS: ~1.1MB JSON, ~821KB YAML, ~233 endpoints, ~348 operations

Common Issues and Solutions

CI/CD Failures:
- Scripts generate files in
```
scripts/{pve,pbs}/
```
  but CI expects them in output directories
- Solution: Ensure file move commands in workflows
Validation Errors:
- Run
```
uv run python scripts/validate_openapi.py
```
  to check specifications
- Common issues: missing required fields, invalid schema references
Import Errors:
- Always use
```
uv run
```
  to execute scripts, not direct Python
- UV manages virtual environments automatically

Development Workflow

Before Making Changes:
- Understand existing patterns in similar files
- Check file naming conventions (especially for API specs)
- Review the Git commit workflow in
```
docs/GIT_COMMIT_WORKFLOW.md
```
Making Changes:
- Use the unified parser for new features when possible
- Maintain compatibility with both JSON and YAML outputs
- Follow existing authentication patterns
Before Committing:
- Run
```
./scripts/validate-commit.sh
```
  for all quality checks
- Use conventional commit format:
```
type(scope): description
```
- Ensure atomic commits (one logical change per commit)

Project-Specific Conventions

Dependency Management: ONLY use UV (
```
uv add
```
,
```
uv sync
```
), never pip
Python Version: 3.9+ (check
```
.python-version
```
)
Code Style: Ruff for formatting/linting (configured in
```
pyproject.toml
```
)
Commit Style: Conventional commits with project-specific scopes (api, pve, pbs, parser, schema, deps)

Essential Commands

# Install all dependencies (ALWAYS use UV, never pip)
uv sync --extra all

# Run any Python script
uv run python script_name.py

# Generate PVE API specifications
cd scripts/pve && uv run python generate_openapi.py && uv run python convert_to_yaml.py

# Generate PBS API specifications  
cd scripts/pbs && uv run python generate_openapi.py && uv run python convert_to_yaml.py

# Format code
uv run ruff format scripts/

# Check linting
uv run ruff check scripts/

# Type checking
uv run mypy scripts/

# Validate OpenAPI specs
uv run python scripts/validate_openapi.py

# Run ALL validation (recommended)
./scripts/validate-commit.sh

# Validate commit readiness
./scripts/validate-commit.sh

# Commit with automatic validation
./scripts/validate-commit.sh --commit

High-Level Architecture

apidoc.js → Parser → generate_openapi.py → {pve,pbs}-api.json → convert_to_yaml.py → {pve,pbs}-api.yaml

Unified Parser (

scripts/unified_parser.py

Central parsing engine with file caching for performance
Handles both PVE and PBS with API-specific configurations
Extracts API schemas from JavaScript using regex patterns
Standardizes authentication across specifications

API Generators (

scripts/{pve,pbs}/generate_openapi.py

API-specific wrappers around the unified parser
Generate JSON specifications in respective output directories
Handle file path discovery and output placement

Format Converters (

scripts/{pve,pbs}/convert_to_yaml.py

Convert JSON specifications to YAML format
Maintain consistent file naming:
```
{pve,pbs}-api.{json,yaml}
```

File Caching: The unified parser caches

apidoc.js

content with mtime checking to avoid repeated file reads during development.

Configuration-Driven: Each API (PVE/PBS) has an

APIConfig

dataclass defining:

Port numbers (PVE: 8006, PBS: 8007)
Authentication schemes
Tag mappings for endpoint grouping
Server paths and metadata

Path Discovery: Scripts automatically search multiple locations for

apidoc.js

files, supporting flexible directory structures.

Atomic Commits: The project enforces strict commit conventions with separate commits for different change types (features, fixes, dependencies).

Common Issues and Solutions

CI/CD Failures:

Scripts generate files in
```
scripts/{pve,pbs}/
```
but CI expects them in output directories
Solution: Ensure file move commands in workflows

Validation Errors:

Run

uv run python scripts/validate_openapi.py

to check specifications

Common issues: missing required fields, invalid schema references

Import Errors:

Always use
```
uv run
```
to execute scripts, not direct Python
UV manages virtual environments automatically

Development Workflow

Before Making Changes:

Understand existing patterns in similar files
Check file naming conventions (especially for API specs)
Review the Git commit workflow in
```
docs/GIT_COMMIT_WORKFLOW.md
```

Making Changes:

Use the unified parser for new features when possible
Maintain compatibility with both JSON and YAML outputs
Follow existing authentication patterns

Before Committing:

Run
```
./scripts/validate-commit.sh
```
for all quality checks
Use conventional commit format:
```
type(scope): description
```
Ensure atomic commits (one logical change per commit)

CLAUDE.md

CLAUDE.md

Project Overview

Essential Commands

Development Setup

Generate API Specifications

Code Quality Checks (MUST run before commits)

Git Commit Validation

High-Level Architecture

Data Flow

Core Components

Key Design Patterns

Critical File Locations

Expected Outputs

Common Issues and Solutions

Development Workflow

Project-Specific Conventions

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

Project Overview

Essential Commands

Development Setup

Generate API Specifications

Code Quality Checks (MUST run before commits)

Git Commit Validation

High-Level Architecture

Data Flow

Core Components

Key Design Patterns

Critical File Locations

Expected Outputs

Common Issues and Solutions

Development Workflow

Project-Specific Conventions