Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Installs both pre-commit and commit-msg hooks with a `pre-commit install`
default_install_hook_types: [pre-commit, commit-msg]

repos:
# Secret scanning
- repo: https://github.com/leaktk/leaktk
rev: 398b9d71573e1bf99b4eed0271729c4796df57ff # frozen: v0.3.13
hooks:
- id: leaktk.git.pre-commit

# HyperFleet commit message standard
- repo: https://github.com/openshift-hyperfleet/hyperfleet-hooks
rev: 0c42dbf10d4087ac8c788b19b9d29afd7bccdd4a # frozen: v0.3.0
hooks:
- id: hyperfleet-commitlint
stages: [commit-msg]

# Schema build + Spectral lint. Needs `npm install` first; rewrites schemas/ when
# the TypeSpec sources changed, so commit the regenerated files with the change.
- repo: local
hooks:
- id: build-and-lint-schema
name: Build and lint OpenAPI schema
entry: bash -c './build-schema.sh && npx spectral lint schemas/template/openapi.yaml --fail-severity warn'
Comment thread
Mischulee marked this conversation as resolved.
Resolved
language: system
files: \.tsp$
pass_filenames: false

# File hygiene
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # frozen: v6.0.0
hooks:
- id: trailing-whitespace
args: [--markdown-linebreak-ext=md]
- id: end-of-file-fixer
258 changes: 258 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,258 @@
# HyperFleet Template API Spec - AI Agent Context

This repository generates the HyperFleet Template OpenAPI specification from TypeSpec definitions. It imports shared models and services from the [hyperfleet-api-spec](https://github.com/openshift-hyperfleet/hyperfleet-api-spec) core repository as the `hyperfleet` npm package, and adds Template-specific models (cluster spec, channels, versions) and their service endpoints.

## Quick Reference

**Build commands:**

```bash
npm run build # Generate Template OpenAPI 3.0 + Swagger 2.0
./build-schema.sh # Same as npm run build
```

**Swagger UI (GitHub Pages):**

- `index.html` loads `schemas/template/openapi.yaml` via raw.githubusercontent.com (swagger-ui-dist 5.32.6 from jsDelivr)
- Published at <https://openshift-hyperfleet.github.io/hyperfleet-api-spec-template/>

**Validation workflow:**

```bash
npm install # Install dependencies (includes hyperfleet package)
./build-schema.sh # Build Template OpenAPI 3.0
ls -l schemas/template/openapi.yaml # Confirm output exists
```

## Key Concepts

### Dependency on Core Repo

Template-specific TypeSpec imports shared definitions via the `hyperfleet` npm package:

```typescript
// main.tsp
import "hyperfleet/shared/services/clusters.tsp";
import "hyperfleet/shared/services/statuses.tsp";
import "hyperfleet/shared/services/nodepools.tsp";
import "hyperfleet/shared/services/resources.tsp";
```

The `hyperfleet` package is sourced from the core repo branch/tag in `package.json`:

```json
"hyperfleet": "github:openshift-hyperfleet/hyperfleet-api-spec#vX.Y.Z"
```

To use a local core checkout during development, use `npm link` or a local path:

```json
"hyperfleet": "file:../hyperfleet-api-spec"
```

### What Lives Here vs Core

| Concern | Location |
| -------------------------------------------- | ------------------------------------------------ |
| Cluster/nodepool/status/resource CRUD routes | Core repo (`hyperfleet` package) |
| `TemplateClusterSpec` fields | `models/cluster/model.tsp` |
| Template nodepool fields | `models/nodepool/model.tsp` |
| Channels and versions models | `models/channel/`, `models/version/` |
| Channels and versions service endpoints | `services/channels.tsp`, `services/versions.tsp` |
| Generated output | `schemas/template/openapi.yaml` (committed) |

### Public vs Internal APIs

The internal status and force-delete endpoints come from the core shared contract. This repo generates the public Template API contract only (no internal adapter endpoints).

## Code Style

### TypeSpec Conventions

**Imports first, namespace second:**

```typescript
import "@typespec/http";
import "hyperfleet/shared/models/common/model.tsp";
import "../models/cluster/model.tsp";

namespace HyperFleet;
```

**Model naming:**

- Template resources: `TemplateClusterSpec`, `ReleaseSpec`, `ChannelSpec`, `VersionSpec`
- Lists: `ChannelList`, `VersionList`
- Requests: `ChannelCreateRequest`, `ChannelPatchRequest`

### File Organization

```
models/{resource}/
├── model.tsp # Model definitions
├── example_{resource}.tsp # GET example constant
├── example_post.tsp # POST example constant
└── example_patch.tsp # PATCH example constant

services/
└── {resource}.tsp # Service endpoints
```

## Boundaries

**DO NOT:**

- Modify generated files in `schemas/` or `tsp-output-template/` directly
- Add shared/core models here — they belong in the core repo's `shared/` directory
- Commit `node_modules/` or build artifacts

**DO:**

- Run `./build-schema.sh` and commit both `schemas/template/openapi.yaml` and `schemas/template/swagger.yaml` with your changes
- Keep TypeSpec files focused (one resource per service file)
- Update `package.json` to pin a new core version when consuming new shared models

## Common Tasks

### Add a field to Template cluster spec

```typescript
// models/cluster/model.tsp
model ReleaseSpec {
// ... existing fields ...
newField?: string;
}
```

Rebuild: `npm run build`

### Add a new Template-specific service endpoint

```typescript
// services/channels.tsp
namespace HyperFleet;

@route("/channels")
interface Channels {
// ... existing endpoints ...

@get
@route("/{id}/summary")
getSummary(@path id: string): ChannelSummary | Error;
}
```

Rebuild: `npm run build`

### Add a new Template-specific resource

1. Create model:

```typescript
// models/policy/model.tsp
import "@typespec/http";
import "hyperfleet/shared/models/common/model.tsp";

namespace HyperFleet;

model PolicySpec {
rules: string[];
}
```

1. Create service:

```typescript
// services/policies.tsp
import "@typespec/http";
import "@typespec/openapi";
import "hyperfleet/shared/models/common/model.tsp";
import "../models/policy/model.tsp";

namespace HyperFleet;

@route("/policies")
interface Policies {
@get list(): PolicySpec[] | Error;
}
```

1. Import both in `main.tsp`:

```typescript
import "./models/policy/model.tsp";
import "./services/policies.tsp";
```

1. Build: `npm run build`

### Update the hyperfleet core dependency

1. Edit `package.json`:

```json
"hyperfleet": "github:openshift-hyperfleet/hyperfleet-api-spec#vX.Y.Z"
```

1. Reinstall and rebuild:

```bash
npm install
npm run build
```

## Version Bump and Changelog

When bumping the version in `main.tsp`, always update `CHANGELOG.md`:

1. Keep `## [Unreleased]` at the top, then add a new version section as `## [X.Y.Z] - YYYY-MM-DD`
2. List changes under appropriate headings (`Added`, `Changed`, `Fixed`, `Removed`)
3. Update the comparison links at the bottom of the file
4. Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format

## Validation Checklist

Before submitting changes:

- [ ] Dependencies installed: `npm install`
- [ ] Template schemas build (OpenAPI 3.0 and Swagger 2.0): `./build-schema.sh`
- [ ] Schema files generated: `ls schemas/template/openapi.yaml schemas/template/swagger.yaml`
- [ ] No TypeSpec compilation errors (check output)
- [ ] Schema passes linting: `npx spectral lint schemas/template/openapi.yaml --fail-severity warn`
- [ ] Changes committed including schema updates
- [ ] PR description references related issue

## Build System Details

**The build-schema.sh script:**

1. Runs `node_modules/.bin/tsp compile main.tsp --output-dir tsp-output-template`
2. Moves output to `schemas/template/openapi.yaml`
3. Converts to OpenAPI 2.0 via `api-spec-converter` -> `schemas/template/swagger.yaml`

**Output locations:**

- TypeSpec temp: `tsp-output-template/schema/openapi.yaml` (auto-deleted)
- Final: `schemas/template/openapi.yaml` and `schemas/template/swagger.yaml` (committed)

## Release Process

Releases are **fully automated** via GitHub Actions (`.github/workflows/release.yml`).

On every push to `main`, the release workflow:

1. Extracts the version from the `@info` decorator in `main.tsp`
2. Skips if a tag for that version already exists
3. Builds both schema formats (`openapi.yaml` and `swagger.yaml`)
4. Creates an annotated Git tag (`vX.Y.Z`)
5. Publishes a GitHub Release with `template-openapi.yaml` and `template-swagger.yaml` attached

The CI workflow enforces that the version in `main.tsp` is bumped from the latest release tag before a PR can be merged.

To release a new version, bump the version in `main.tsp` and merge to `main`.

## Architecture Context

- Core spec repo: <https://github.com/openshift-hyperfleet/hyperfleet-api-spec>
- Architecture repo: <https://github.com/openshift-hyperfleet/architecture>
- Main API implementation: <https://github.com/openshift-hyperfleet/hyperfleet-api>
Loading
Loading