Proxmox OpenAPI Tooling

Utilities for scraping the official Proxmox API viewer, normalizing responses, and publishing OpenAPI specs plus a companion SPA.

This toolkit provides third‑party automation building blocks for Proxmox VE. It supplies the ingredients required to deliver a full‑featured Terraform provider and other infrastructure‑as‑code integrations.

At a Glance

• Install and run the pipeline

  npm install @mihailfox/proxmox-openapi --registry=https://npm.pkg.github.com
  npx proxmox-openapi pipeline --mode full --report var/automation-summary.json

• Build and preview the SPA

  npm install
  npm run ui:dev

• Use the GitHub Action (CI)

  jobs:
    openapi:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v5
        - name: Generate Proxmox OpenAPI artifacts
          uses: ./.github/actions/proxmox-openapi-artifacts
          with:
            mode: ci
            fallback-to-cache: true

Requirements

• Node.js 24 or newer ("engines": { "node": ">=24.0.0" }).
• macOS, Linux, or Windows for local development. CI runs on Ubuntu.
• For npm installs from GitHub Packages, configure an auth token (see package README).

Project Vision

• Deliver first-party quality building blocks that unblock a Terraform provider and future IaC integrations for Proxmox VE.
• Keep schema generation reproducible so external tooling can track upstream releases with confidence.
• Provide an approachable UI and documentation hub that mirrors the automation behaviour available through the npm package and GitHub Action.

Packages

• app/: Vite-based SPA that surfaces the generated specifications and embeds Swagger UI with lazy loading.
• packages/proxmox-openapi/: Consolidated source for scraping, normalization, OpenAPI generation, automation orchestration, and the published CLI (@mihailfox/proxmox-openapi).
• .github/actions/proxmox-openapi-artifacts/: First-party GitHub Action wrapping the automation pipeline for CI.
• .github/workflows/: CI pipelines for validations, artifact generation, GitHub Pages, and project automation. The deploy-pages workflow now includes a post-deploy lighthouse-performance job that audits key SPA routes and commits JSON/markdown reports to the performance-reports branch.
• .devcontainer/: Containerized development environment configs. See docs/devcontainer.md.
• var/: Workspace-local output directory (automation summaries, OpenAPI bundles, release staging, static site builds). GitHub Pages installs the latest published CLI (@mihailfox/proxmox-openapi@latest) before running automation, and falls back to a local build if the package is unavailable.

Git hooks & formatting

• We pin Git’s hooks directory to .githooks (git config core.hooksPath .githooks) so every commit runs Biome on staged sources. The pre-commit script (.githooks/pre-commit) exits quietly if npx or @biomejs/biome are missing.
• The hook executes npx @biomejs/biome check --write --staged --files-ignore-unknown=true --no-errors-on-unmatched. It formats only staged files, sorts imports, and applies autofixable lint fixes without touching unstaged work.
• Format the entire tree manually with npx @biomejs/biome check --write --organize-imports-enabled=true . whenever you want a clean sweep.

SPA Overview

The SPA under app/ is a React + Vite project that ships the marketing pages, API explorer, and statically bundled OpenAPI artifacts. The build expects fresh schema bundles under var/openapi, which are synced into the public assets via npm run openapi:prepare before Vite serves or builds the site. GitHub Pages deploys the compiled assets located in dist/ together with the generated OpenAPI bundle. See docs/spa-deployment.md for the deployment workflow and rollback guidance.

Automation Pipeline Overview

The automation pipeline chains the following stages (implemented in packages/proxmox-openapi/src/internal/automation/pipeline.ts):

1. Scrape – @proxmox-openapi/api-scraper launches Playwright, fetches apidoc.js, and persists a raw snapshot (JSON).
2. Normalize – @proxmox-openapi/api-normalizer converts the raw tree into a versioned intermediate representation (IR).
3. Generate – @proxmox-openapi/openapi-generator emits OpenAPI 3.1 JSON/YAML documents and enriches tags/metadata.
4. Validate – Swagger Parser validates the JSON output and persists a structured run summary.

Run the end-to-end flow with npx proxmox-openapi pipeline (or npm run automation:pipeline, which proxies the same CLI). Pass --mode=full for a live scrape or --no-fallback-to-cache to fail fast when Proxmox endpoints are unreachable. The command writes a JSON summary to var/automation-summary.json when invoked with --report <path>. Stage-specific commands (scrape, normalize, generate) mirror the library internals under packages/proxmox-openapi/src/internal/ for targeted debugging.

Local Development Quickstart

1. Install dependencies with npm install.
2. Generate or refresh the OpenAPI artifacts (npx proxmox-openapi pipeline --mode full --report var/automation-summary.json).
3. Start the SPA dev server (npm run ui:dev). The script copies the current artifacts and launches Vite at http://127.0.0.1:5173.
4. When finished, stop the dev server with Ctrl+C. Regenerate artifacts whenever the API schema changes.

Devcontainer & launcher helpers

• The devcontainer definition lives under .devcontainer/; see docs/devcontainer.md for the full image layout, helper scripts, and troubleshooting tips.
• Shell history persists through the ${HOME}/.dev_con_bash_history bind mount so multiple Devcontainer workspaces can coexist without clobbering ~/.bash_history on the host.
• ./launcher.sh wraps the most common devcontainer actions:
  • ./launcher.sh vscode --attach-shell opens the repo in VS Code and waits for the container before spawning a shell.
  • ./launcher.sh get_config customizations.vscode.settings queries arbitrary paths from devcontainer.json if you need to script against the configuration.
• The launcher sources scripts/common.sh, which also powers other automation helpers. Use ./launcher.sh help for the full command list.

Working With Automation

The "Project Stage Sync" workflow keeps the delivery project up to date. Review the automation runbook for triggers, token requirements, CLI flags, and manual override instructions. When opening a pull request, ensure the relevant issue is linked so the workflow can reconcile status changes. Use packages/proxmox-openapi/scripts/automation/format-summary.ts to turn pipeline summaries into Markdown for PRs. CI workflows run under concurrency groups (${{ github.workflow }}-${{ github.ref }}) so any superseded run is cancelled before new work starts.

Monitoring & Quality

• Run a Lighthouse audit (Performance, Accessibility, Best Practices ≥ 90) against the deployed pages site after significant UI changes.
• Check for broken links using a crawler such as npx broken-link-checker https://mihailfox.github.io/proxmox-openapi/ before publishing.
• Verify that the embedded Swagger UI loads the latest openapi/proxmox-ve.json bundle after every automation pipeline run.

Testing

• npm run test:all executes unit suites for the scraper, normalizer, generator, and automation helpers.
• Playwright suites cover scraper smoke tests (packages/proxmox-openapi/tests/api-scraper/smoke.spec.ts) and UI contrast/theme behaviour (tests/ui/theme.spec.ts).

GitHub Action Usage

The bundled action in .github/actions/proxmox-openapi-artifacts runs the automation pipeline directly from source. It leverages the @mihailfox/proxmox-openapi package so GitHub Actions, local scripts, and downstream consumers rely on an identical code path. After cloning, lint updates with npm run action:lint to ensure the action workspace stays clean.

GitHub-hosted runners

jobs:
  openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Generate Proxmox OpenAPI artifacts
        uses: mihailfox/proxmox-openapi/.github/actions/proxmox-openapi-artifacts@v1
        with:
          mode: ci
          fallback-to-cache: true

Note Workflows that install @mihailfox/proxmox-openapi must configure npm for GitHub Packages. For example:

cat <<'RC' >> ~/.npmrc
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
@mihailfox:registry=https://npm.pkg.github.com
RC

Self-hosted runners (offline-compatible)

Download the release bundle and reference it locally:

mkdir -p .github/actions/proxmox-openapi-artifacts
curl -sSL https://github.com/mihailfox/proxmox-openapi/releases/download/v1.0.0/proxmox-openapi-artifacts-action-v1.0.0.tgz \
  | tar -xz -C .github/actions/proxmox-openapi-artifacts --strip-components=1 proxmox-openapi-artifacts-action

jobs:
  openapi:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v5
      - name: Generate Proxmox OpenAPI artifacts
        uses: ./.github/actions/proxmox-openapi-artifacts
        with:
          mode: full
          offline: true

npm Package

• Configure an .npmrc entry with your GitHub Packages token:

  @mihailfox:registry=https://npm.pkg.github.com
  //npm.pkg.github.com/:_authToken=${NPM_TOKEN}

• Install and run the CLI:

  npm install @mihailfox/proxmox-openapi
  npx proxmox-openapi pipeline --mode full --report var/automation-summary.json
  npx proxmox-openapi scrape --output var/cache/api-scraper/raw/proxmox-openapi-schema.json
  npx proxmox-openapi generate --output var/openapi --basename proxmox-ve

• See docs/packages.md for CLI flag reference, library usage, and release cadence details.

Schema Releases

• Publishing a GitHub Release triggers .github/workflows/release.yml. That workflow rebuilds artifacts, validates them, and uploads release assets. It also publishes the npm package (@mihailfox/proxmox-openapi) to GitHub Packages.
• Use semantic tags (for example v1.2.3) and optional prerelease suffixes (-alpha.*, -beta.*, -rc.*) when drafting the release.
• See docs/releases.md for download commands, checksum verification, and release metadata.
• The release workflow aligns every package.json version with the tag, commits the bump back to main, and records the upstream Proxmox VE version scraped from the documentation index. Release notes and manifests include both values for traceability.

Contributing

0. Create a fork of the repo and clone it locally.
1. Install dependencies with npm install.
2. Run targeted checks (npm run lint, npm run test:all, etc.) before pushing.
3. Reference the linked issue in branch names/PR bodies and document any automation impact.
4. Keep CHANGELOG.md current. Our release workflow reads the top “Unreleased” section and uses it as the body for the next GitHub Release. Log user‑visible changes under the Common Changelog categories (Added, Changed, Deprecated, Removed, Fixed, Security).
5. Prefer conventional commits (e.g. feat:, fix(ci):, docs(action):) and small, focused pull requests.
6. See docs/automation.md for expectations around project updates and troubleshooting.
7. See CONTRIBUTING.md for Documentation Style guidelines applied across this repository.

Notes

Git hooks run Biome on staged files via .githooks/pre-commit. Use npm run format for a full sweep across the repo.