{"id":49901480,"url":"https://github.com/mihailfox/proxmox-openapi","last_synced_at":"2026-05-16T06:38:12.186Z","repository":{"id":319388899,"uuid":"1078545807","full_name":"mihailfox/proxmox-openapi","owner":"mihailfox","description":"Tooling to scrape the Proxmox API viewer and generate OpenAPI specifications.","archived":false,"fork":false,"pushed_at":"2025-11-03T21:11:12.000Z","size":1960,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-03T21:21:27.657Z","etag":null,"topics":["api","openapi","openapi-generator","proxmox"],"latest_commit_sha":null,"homepage":"https://mihailfox.github.io/proxmox-openapi/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mihailfox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-17T23:13:12.000Z","updated_at":"2025-11-03T21:08:32.000Z","dependencies_parsed_at":"2025-10-27T07:11:27.611Z","dependency_job_id":null,"html_url":"https://github.com/mihailfox/proxmox-openapi","commit_stats":null,"previous_names":["mihailfox/proxmox-openapi"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/mihailfox/proxmox-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihailfox%2Fproxmox-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihailfox%2Fproxmox-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihailfox%2Fproxmox-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihailfox%2Fproxmox-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mihailfox","download_url":"https://codeload.github.com/mihailfox/proxmox-openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihailfox%2Fproxmox-openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33092816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","openapi","openapi-generator","proxmox"],"created_at":"2026-05-16T06:38:11.264Z","updated_at":"2026-05-16T06:38:12.176Z","avatar_url":"https://github.com/mihailfox.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proxmox OpenAPI Tooling\n\nUtilities for scraping the official Proxmox API viewer, normalizing responses, and publishing OpenAPI specs plus a companion SPA.\n\nThis toolkit provides third‑party automation building blocks for Proxmox VE. It supplies the ingredients required\nto deliver a full‑featured Terraform provider and other infrastructure‑as‑code integrations.\n\n## At a Glance\n- Install and run the pipeline\n  ```bash\n  npm install @mihailfox/proxmox-openapi --registry=https://npm.pkg.github.com\n  npx proxmox-openapi pipeline --mode full --report var/automation-summary.json\n  ```\n- Build and preview the SPA\n  ```bash\n  npm install\n  npm run ui:dev\n  ```\n- Use the GitHub Action (CI)\n  ```yaml\n  jobs:\n    openapi:\n      runs-on: ubuntu-latest\n      steps:\n        - uses: actions/checkout@v5\n        - name: Generate Proxmox OpenAPI artifacts\n          uses: ./.github/actions/proxmox-openapi-artifacts\n          with:\n            mode: ci\n            fallback-to-cache: true\n  ```\n\n## Requirements\n- Node.js 24 or newer (`\"engines\": { \"node\": \"\u003e=24.0.0\" }`).\n- macOS, Linux, or Windows for local development. CI runs on Ubuntu.\n- For npm installs from GitHub Packages, configure an auth token (see package README).\n\n## Project Vision\n- Deliver first-party quality building blocks that unblock a Terraform provider and future IaC integrations for Proxmox VE.\n- Keep schema generation reproducible so external tooling can track upstream releases with confidence.\n- Provide an approachable UI and documentation hub that mirrors the automation behaviour available through the npm package and GitHub Action.\n\n## Packages\n- `app/`: Vite-based SPA that surfaces the generated specifications and embeds Swagger UI with lazy loading.\n- `packages/proxmox-openapi/`: Consolidated source for scraping, normalization, OpenAPI generation, automation orchestration, and the published CLI (`@mihailfox/proxmox-openapi`).\n- `.github/actions/proxmox-openapi-artifacts/`: First-party GitHub Action wrapping the automation pipeline for CI.\n- `.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.\n- `.devcontainer/`: Containerized development environment configs. See [docs/devcontainer.md](docs/devcontainer.md).\n- `var/`: Workspace-local output directory (automation summaries, OpenAPI bundles, release staging, static site builds).\n  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.\n\n### Git hooks \u0026 formatting\n- We pin Git’s hooks directory to `.githooks` (`git config core.hooksPath .githooks`) so every commit runs Biome on staged\n  sources. The pre-commit script (`.githooks/pre-commit`) exits quietly if `npx` or `@biomejs/biome` are missing.\n- The hook executes `npx @biomejs/biome check --write --staged --files-ignore-unknown=true --no-errors-on-unmatched`.\n  It formats only staged files, sorts imports, and applies autofixable lint fixes without touching unstaged work.\n- Format the entire tree manually with `npx @biomejs/biome check --write --organize-imports-enabled=true .` whenever you\n  want a clean sweep.\n\n## SPA Overview\nThe SPA under `app/` is a React + Vite project that ships the marketing pages, API explorer, and statically bundled\nOpenAPI artifacts. The build expects fresh schema bundles under `var/openapi`, which are synced into the public assets\nvia `npm run openapi:prepare` before Vite serves or builds the site. GitHub Pages deploys the compiled assets located in\n`dist/` together with the generated OpenAPI bundle. See [docs/spa-deployment.md](docs/spa-deployment.md) for the\ndeployment workflow and rollback guidance.\n\n## Automation Pipeline Overview\nThe automation pipeline chains the following stages (implemented in `packages/proxmox-openapi/src/internal/automation/pipeline.ts`):\n1. **Scrape** – `@proxmox-openapi/api-scraper` launches Playwright, fetches `apidoc.js`, and persists a raw snapshot (JSON).\n2. **Normalize** – `@proxmox-openapi/api-normalizer` converts the raw tree into a versioned intermediate representation (IR).\n3. **Generate** – `@proxmox-openapi/openapi-generator` emits OpenAPI 3.1 JSON/YAML documents and enriches tags/metadata.\n4. **Validate** – Swagger Parser validates the JSON output and persists a structured run summary.\n\nRun the end-to-end flow with `npx proxmox-openapi pipeline` (or `npm run automation:pipeline`, which proxies the same CLI).\nPass `--mode=full` for a live scrape or `--no-fallback-to-cache` to fail fast when Proxmox endpoints are unreachable. The\ncommand writes a JSON summary to `var/automation-summary.json` when invoked with `--report \u003cpath\u003e`. Stage-specific\ncommands (`scrape`, `normalize`, `generate`) mirror the library internals under `packages/proxmox-openapi/src/internal/`\nfor targeted debugging.\n\n### Local Development Quickstart\n1. Install dependencies with `npm install`.\n2. Generate or refresh the OpenAPI artifacts (`npx proxmox-openapi pipeline --mode full --report var/automation-summary.json`).\n3. Start the SPA dev server (`npm run ui:dev`). The script copies the current artifacts and launches Vite at\n   `http://127.0.0.1:5173`.\n4. When finished, stop the dev server with `Ctrl+C`. Regenerate artifacts whenever the API schema changes.\n\n### Devcontainer \u0026 launcher helpers\n- The devcontainer definition lives under `.devcontainer/`; see [docs/devcontainer.md](docs/devcontainer.md) for the full\n  image layout, helper scripts, and troubleshooting tips.\n- Shell history persists through the `${HOME}/.dev_con_bash_history` bind mount so multiple Devcontainer workspaces can\n  coexist without clobbering `~/.bash_history` on the host.\n- `./launcher.sh` wraps the most common devcontainer actions:\n  - `./launcher.sh vscode --attach-shell` opens the repo in VS Code and waits for the container before spawning a shell.\n  - `./launcher.sh get_config customizations.vscode.settings` queries arbitrary paths from `devcontainer.json` if you\n    need to script against the configuration.\n- The launcher sources `scripts/common.sh`, which also powers other automation helpers. Use `./launcher.sh help` for the\n  full command list.\n\n## Working With Automation\nThe \"Project Stage Sync\" workflow keeps the delivery project up to date. Review the [automation runbook](docs/automation.md) for triggers,\ntoken requirements, CLI flags, and manual override instructions. When opening a pull request, ensure the relevant issue is linked so the\nworkflow can reconcile status changes. Use `packages/proxmox-openapi/scripts/automation/format-summary.ts` to turn pipeline summaries into Markdown for PRs.\nCI workflows run under concurrency groups (`${{ github.workflow }}-${{ github.ref }}`) so any superseded run is cancelled before new work starts.\n\n## Monitoring \u0026 Quality\n- Run a Lighthouse audit (Performance, Accessibility, Best Practices ≥ 90) against the deployed pages site after significant UI changes.\n- Check for broken links using a crawler such as `npx broken-link-checker https://mihailfox.github.io/proxmox-openapi/` before publishing.\n- Verify that the embedded Swagger UI loads the latest `openapi/proxmox-ve.json` bundle after every automation pipeline run.\n\n## Testing\n- `npm run test:all` executes unit suites for the scraper, normalizer, generator, and automation helpers.\n- 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`).\n\n## GitHub Action Usage\nThe bundled action in `.github/actions/proxmox-openapi-artifacts` runs the automation pipeline directly from source.\nIt leverages the `@mihailfox/proxmox-openapi` package so GitHub Actions, local scripts, and downstream consumers rely on\nan identical code path. After cloning, lint updates with `npm run action:lint` to ensure the action workspace stays clean.\n\n### GitHub-hosted runners\n\n```yaml\njobs:\n  openapi:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v5\n      - name: Generate Proxmox OpenAPI artifacts\n        uses: mihailfox/proxmox-openapi/.github/actions/proxmox-openapi-artifacts@v1\n        with:\n          mode: ci\n          fallback-to-cache: true\n```\n\n\u003e **Note**\n\u003e Workflows that install `@mihailfox/proxmox-openapi` must configure npm for GitHub Packages. For example:\n\u003e \n\u003e ```bash\n\u003e cat \u003c\u003c'RC' \u003e\u003e ~/.npmrc\n\u003e //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\u003e @mihailfox:registry=https://npm.pkg.github.com\n\u003e RC\n\u003e ```\n\n### Self-hosted runners (offline-compatible)\n\nDownload the release bundle and reference it locally:\n\n```bash\nmkdir -p .github/actions/proxmox-openapi-artifacts\ncurl -sSL https://github.com/mihailfox/proxmox-openapi/releases/download/v1.0.0/proxmox-openapi-artifacts-action-v1.0.0.tgz \\\n  | tar -xz -C .github/actions/proxmox-openapi-artifacts --strip-components=1 proxmox-openapi-artifacts-action\n```\n\n```yaml\njobs:\n  openapi:\n    runs-on: self-hosted\n    steps:\n      - uses: actions/checkout@v5\n      - name: Generate Proxmox OpenAPI artifacts\n        uses: ./.github/actions/proxmox-openapi-artifacts\n        with:\n          mode: full\n          offline: true\n```\n\n## npm Package\n- Configure an `.npmrc` entry with your GitHub Packages token:\n\n  ```ini\n  @mihailfox:registry=https://npm.pkg.github.com\n  //npm.pkg.github.com/:_authToken=${NPM_TOKEN}\n  ```\n\n- Install and run the CLI:\n\n  ```bash\n  npm install @mihailfox/proxmox-openapi\n  npx proxmox-openapi pipeline --mode full --report var/automation-summary.json\n  npx proxmox-openapi scrape --output var/cache/api-scraper/raw/proxmox-openapi-schema.json\n  npx proxmox-openapi generate --output var/openapi --basename proxmox-ve\n  ```\n\n- See [docs/packages.md](docs/packages.md) for CLI flag reference, library usage, and release cadence details.\n\n## Schema Releases\n- 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.\n- Use semantic tags (for example `v1.2.3`) and optional prerelease suffixes (`-alpha.*`, `-beta.*`, `-rc.*`) when drafting the release.\n- See [docs/releases.md](docs/releases.md) for download commands, checksum verification, and release metadata.\n- 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.\n\n## Contributing\n0. Create a fork of the repo and clone it locally.\n1. Install dependencies with `npm install`.\n2. Run targeted checks (`npm run lint`, `npm run test:all`, etc.) before pushing.\n3. Reference the linked issue in branch names/PR bodies and document any automation impact.\n4. 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).\n5. Prefer conventional commits (e.g. `feat:`, `fix(ci):`, `docs(action):`) and small, focused pull requests.\n6. See [docs/automation.md](docs/automation.md) for expectations around project updates and troubleshooting.\n7. See CONTRIBUTING.md for Documentation Style guidelines applied across this repository.\n\n## Notes\n\u003e Git hooks run Biome on staged files via `.githooks/pre-commit`. Use `npm run format` for a full sweep across the repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmihailfox%2Fproxmox-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmihailfox%2Fproxmox-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmihailfox%2Fproxmox-openapi/lists"}