Pets

Appearance

Auto-Publish Pets ​

OpenPets primarily distributes repository-maintained pets through the hosted source registry at https://pets.raggle.co/source-pets/. npm publishing remains available for explicit releases, but the default automation path refreshes source-registry tarballs and metadata after pet changes land on main.

OpenAPI Refresh PRs ​

.github/workflows/monitor-openapi-updates.yml runs weekly and can also be started manually.

The monitor checks OpenAPI pets with scripts/check-stale-pets.ts. When a pet has a hosted openapiSpec.url, the monitor compares the current hosted spec hash with the hash stamped into commands.json. If the hash is missing or changed, the pet is selected for regeneration. If the hosted spec cannot be fetched, the monitor falls back to the older commands.json.generatedAt age check.

For each selected pet, CI:

  • runs bun ../../src/core/cli.ts generate-openapi from the pet directory
  • runs bun src/core/cli.ts build <pet> from the repo root
  • bumps the pet patch version when generated files changed
  • rebuilds after the version bump so commands.json.version matches package.json
  • stamps commands.json with openapiSpecUrl, openapiSpecHash, and openapiSpecCheckedAt
  • runs bun run validate:pet -- pets/<pet>
  • opens or updates automation/openapi/<pet> with title update pet: <pet>
  • publishes a GitHub check named OpenAPI generated pet validation on the PR head commit

Auto-Merge Guardrails ​

The OpenAPI monitor may auto-merge only tiny generated-only refresh PRs after generation, build, spec-hash stamping, and pet validation pass.

Auto-merge is blocked when any of these are true:

  • the diff touches files outside commands.json, openapi-client.ts, openapi-tools.ts, TOOLS.md, or package.json
  • package.json changes anything except version
  • the generated diff is larger than the configured small-change threshold
  • validation or the published check fails
  • the PR is dirty or cannot be merged by GitHub

Large generated rewrites, custom code changes, dependency changes, dirty branches, and conflicted PRs require human review.

Stale Automation Cleanup ​

On scheduled runs, the monitor closes stale dirty automation/openapi/* PRs after they have remained conflicted for the configured cleanup window. This keeps old generated branches from accumulating. If an upstream spec still differs from main, a later monitor run will regenerate a fresh branch from the current source.

Source Registry Publishing ​

When changes land on main, .github/workflows/auto-publish.yml validates changed pets and dispatches .github/workflows/build-source-registry.yml.

The source-registry workflow:

  • builds docs and API metadata
  • creates source tarballs with scripts/build-source-registry.ts
  • writes source-manifest.json and checksums.txt
  • verifies tarball checksums
  • publishes the manifest and tarballs to Cloudflare R2 and Worker assets
  • verifies the public registry and remote client generation
  • uploads the same registry artifacts to the source-registry-latest GitHub release

Manual Commands ​

Preview source-registry artifacts locally:

bash
bun scripts/build-source-registry.ts --dryRun --skipNpmCheck --sourceBaseUrl https://pets.raggle.co/source-pets

Check OpenAPI monitor candidates:

bash
bun scripts/check-stale-pets.ts --only-openapi --json

Refresh one OpenAPI pet locally:

bash
cd pets/<pet>
bun ../../src/core/cli.ts generate-openapi
cd ../..
bun src/core/cli.ts build <pet>
bun scripts/check-stale-pets.ts --only-openapi --pet <pet> --stamp-openapi-hash --no-write-report --json
bun run validate:pet -- pets/<pet>