You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The central API exposes its functionality over HTTP from `ui/server/api`. This page is a reference to those endpoints.
14
14
15
15
> [!WARNING] > **Internal and evolving.** These endpoints currently power Codefair's own web UI and are authenticated with the browser **session cookie**, not API tokens. They are documented here as the foundation of the planned **public REST API**, so paths, payloads, and the auth model may change before a stable, token-authenticated, versioned API is released. Treat this as a contributor reference, not a public contract.
16
16
17
-
## :gear:Conventions
17
+
## Conventions
18
18
19
19
-**Routing.** Nuxt/Nitro encodes the HTTP method in the file name: `index.get.ts` → `GET`, `index.post.ts` → `POST`, `index.put.ts` → `PUT`. Path segments in brackets (`[owner]`, `[repo]`) are URL parameters.
20
20
-**Authentication.** Most endpoints call `protectRoute(event)` (a valid session is required) and `repoWritePermissions(event, owner, repo)` (the signed-in user must have write access to the repository). A CSRF/origin check runs in middleware for browser requests. Exceptions: the **webhook** endpoint uses HMAC signature verification, and the **badge** endpoint is public.
21
21
-**Errors.** Failures are returned as JSON with an HTTP status and a `statusMessage`, e.g. `{ "statusCode": 404, "statusMessage": "installation-not-found" }`.
22
22
-**Bodies.** Write endpoints validate their JSON body with [Zod](https://zod.dev/).
23
23
24
-
## :file_folder:Repository compliance
24
+
## Repository compliance
25
25
26
26
Each FAIR check exposes a consistent trio: `GET` current state, `POST` to create the file via a pull request, and `PUT` to save a draft. All are under `/api/[owner]/[repo]`.
27
27
@@ -34,15 +34,15 @@ Each FAIR check exposes a consistent trio: `GET` current state, `POST` to create
34
34
| GET / POST / PUT |`/code-of-conduct`| Read, create-PR, or update `CODE_OF_CONDUCT.md`. |
35
35
| GET / POST / PUT |`/code-metadata`| Read, create-PR, or update `codemeta.json` + `CITATION.cff`. |
Copy file name to clipboardExpand all lines: docs/dev/compliance-check.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,9 +14,9 @@ A **compliance check** is a single FAIR rule Codefair evaluates for a repository
14
14
15
15
Codefair is deliberately modular: checks are small functions that receive a platform-agnostic [`RepositoryProvider`](./providers.md) and are wired into a single orchestrator, `runComplianceChecks()`. This page walks through adding a brand-new check end-to-end by building an example that verifies an `expecto_patronum.md` file exists.
16
16
17
-
> [!NOTE]
18
-
> This page covers the **backend** check. To build the Codefair UI page where a user can create or edit the file, follow [Adding a UI Page](./ui.md) afterwards.
19
-
17
+
::: info
18
+
This page covers the **backend** check. To build the Codefair UI page where a user can create or edit the file, follow [Adding a UI Page](./ui.md) afterwards.
19
+
:::
20
20
All paths below are relative to the `ui/` directory.
21
21
22
22
## **Step 1**: Set up your development environment
This is the documentation of Codefair for developers. You will find here everything to set up the project locally and start making your contribution! Before you continue, we invite you to first read our [contributing guidelines](https://github.com/fairdataihub/codefair-app/blob/main/CONTRIBUTING.md) and our [code of conduct](https://github.com/fairdataihub/codefair-app/blob/main/CODE_OF_CONDUCT.md).
14
14
15
-
## :compass:How the project is organized
15
+
## How the project is organized
16
16
17
17
Codefair recently moved to a **central API** architecture. The [`codefair-app`](https://github.com/fairdataihub/codefair-app) repository is now organized into two active parts:
18
18
@@ -24,7 +24,7 @@ Codefair recently moved to a **central API** architecture. The [`codefair-app`](
24
24
25
25
This central API is the foundation for two ongoing goals: releasing a public **REST API** and adding **GitLab** support alongside GitHub. The architecture was deliberately built around platform-agnostic abstractions so that new checks, new platforms, and community contributions are easier to land.
26
26
27
-
## :map: Where to go next
27
+
## Where to go next
28
28
29
29
-**[Architecture](./architecture.md)**: understand how the central API, validator, database, and external platforms fit together before you write any code.
30
30
-**[Running Locally](./running-locally.md)**: set up your environment and run the stack on your machine.
Codefair is being built to work across git platforms, not just GitHub. The mechanism that makes this possible is the **provider abstraction**: every compliance check, dashboard render, and pull-request operation goes through a platform-agnostic interface instead of calling a platform SDK directly.
14
14
15
15
> [!NOTE] > **Status:** GitLab support is **planned**. The `RepositoryProvider` interface and the GitHub implementation exist today; a `GitLabRepositoryProvider` does not yet. This page documents the contract so the community can help build it.
16
16
17
-
## :jigsaw:The provider model
17
+
## The provider model
18
18
19
19
The contract lives in `ui/server/services/providers/interface.ts`:
20
20
@@ -45,7 +45,7 @@ flowchart TD
45
45
I -. "same contract" .-> GL
46
46
```
47
47
48
-
## :clipboard:The contract
48
+
## The contract
49
49
50
50
`RepositoryProvider` groups its methods into four areas:
51
51
@@ -58,7 +58,7 @@ flowchart TD
58
58
59
59
All methods take plain values (`owner`, `repo`, `path`, …) and return the neutral types defined alongside the interface: `RepoInfo`, `FileContent`, `PullRequestRef`, `IssueRef`, and so on. Nothing GitHub-specific leaks through.
`ui/server/services/providers/github.ts` is the implementation to copy. It wraps an installation-scoped Octokit client and translates each contract method into a GitHub REST call:
64
64
@@ -102,7 +102,7 @@ export class GitHubRepositoryProvider implements RepositoryProvider {
This section provides instructions for developers to run the Codefair GitHub repository locally. If you have not yet, read the [Architecture](./architecture.md) page first; it explains how the pieces below fit together.
14
14
15
-
## :file_folder:Code structure
15
+
## Code structure
16
16
17
17
Codefair is a **central API**: a single Nuxt application that serves the web UI and the backend, plus a small validation microservice. The repository has two active parts:
18
18
@@ -23,7 +23,7 @@ Codefair is a **central API**: a single Nuxt application that serves the web UI
23
23
> [!NOTE]
24
24
> The repository also contains a `bot/` folder: the original [Probot](https://probot.github.io/) backend, now **being retired**. You do **not** need to set it up for local development: all backend functionality you'll be working on lives in `ui/server`. It is still deployed in production for repositories that have not yet been migrated to the central API. See [Architecture](./architecture.md#use-central-api-flag).
25
25
26
-
## :white_check_mark:Prerequisites
26
+
## Prerequisites
27
27
28
28
Before you can run the Codefair repository, you will need the following prerequisites:
29
29
@@ -62,14 +62,14 @@ Before you can run the Codefair repository, you will need the following prerequi
62
62
63
63
After creating the App, generate a **private key** (`.pem`) and note the **App ID**. These become `GH_APP_PRIVATE_KEY` and `GH_APP_ID`.
Unlike the old Probot setup, there is now a **single**`.env` file, located in the `ui/` directory. The required variables are enforced at startup by `ui/server/plugins/env-check.ts`. If any are missing, the app refuses to boot and tells you which one. Create `ui/.env` with the following:
89
89
@@ -121,7 +121,7 @@ ZENODO_REDIRECT_URI= # Zenodo OAuth redirect URI
121
121
> [!TIP]
122
122
> For local archival testing, point the Zenodo variables at the [Zenodo Sandbox](https://sandbox.zenodo.org/) rather than production so you don't mint real DOIs.
> The example above constructs an Octokit `App` inline because that is what the existing
217
-
> per-repository routes do. For new code, prefer
218
-
> `getInstallationOctokit(installationId)` from `server/services/github-app/client.ts`. It
219
-
> centralises the App credentials instead of repeating them in every route. Better still, if
220
-
> your route only needs ordinary repository operations, take a
221
-
> [`RepositoryProvider`](./providers.md) so it stays platform-agnostic.
215
+
::: info
216
+
The example above constructs an Octokit `App` inline because that is what the existing per-repository routes do. For new code, prefer `getInstallationOctokit(installationId)` from `server/services/github-app/client.ts`. It centralises the App credentials instead of repeating them in every route. Better still, if your route only needs ordinary repository operations, take a [`RepositoryProvider`](./providers.md) so it stays platform-agnostic.
217
+
:::
222
218
223
219
> [!TIP]
224
220
> Need a read-only results page instead (like the CWL or metadata validation reports)? Put it under `pages/dashboard/[owner]/[repo]/view/<feature>.vue` and point the dashboard badge at `.../view/<feature>`.
@@ -229,7 +225,7 @@ Run the stack locally and sign in:
229
225
230
226
```bash
231
227
# In ui/
232
-
yarn dev
228
+
yarn dev:webhook
233
229
```
234
230
235
231
Visit `http://localhost:3000/dashboard/<owner>/<repo>/edit/expecto`, edit the content, and click **Save**. Confirm that a new branch and pull request are created on the repository, and that the PR URL is stored on the `ExpectoValidation` row (`yarn prisma:studio`). You can also reach the page from the **FAIR Compliance Dashboard** issue by clicking the _Create/Edit Expecto_ badge.
0 commit comments