@opensoftware/contracts 2.0.0 → 2.2.0

package/README.md

@@ -51,9 +51,11 @@ Each format has one schema, generated from `typespec/`, and fixtures that CONTRA
 `openapi/openapi.json` also holds the paths of the module APIs, from the operations in `typespec/` (ADR 0048). The
 first is gatekeeper's: `POST /v1/gates` and `GET /v1/gates/{gateId}` with the models `GateRequest`, `GateView` and
 `ApiProblem` (RFC 9457). The second is intake's (ADR 0063): `POST /v1/work-items` and
-`GET /v1/work-items/{workItemId}` with the models `WorkSubmission`, `WorkItemView` and `WorkRequest`. The third is the
+`GET /v1/work-items/{workItemId}` with the models `WorkSubmission`, `WorkItemView` and `WorkRequest`, and
+`GET /v1/inbox` with `WorkItemList`. The third is the
 foreman's (ADR 0067): `POST /v1/runs`, `GET /v1/runs/{runId}` and `POST /v1/runs/{runId}/signals` with the models
-`RunView`, `StageView`, `CheckView` (ADR 0069) and `RunSignal`. `pnpm build` compiles the operations with the TypeSpec OpenAPI 3 emitter and copies their
+`RunView`, `StageView`, `CheckView` (ADR 0069) and `RunSignal`. All three answer `GET /v1/health` with the models
+`Health` and `HealthCheck` (`HealthApi`, ADR 0086). `pnpm build` compiles the operations with the TypeSpec OpenAPI 3 emitter and copies their
 paths next to the named models; an operation that uses a type that is no model fails the build. The package exports
 the type `paths`, which types a client such as openapi-fetch.
 
@@ -91,18 +93,42 @@ the workflow by hand with the tag. The CONTRACT check and `osf-contracts breakin
 Only the TypeScript package exists (ADR 0012). A client for another language can be generated from
 `openapi/openapi.json` with any OpenAPI generator when someone needs one.
 
+A new package gets its publish workflow and its release-please entries with `osf release-files`; the check RELEASE
+fails until they are current, and also when a workflow differs from `tools/scaffold/publish-workflow.yml`.
+
 One-time setup (no credential is ever stored in the repository):
 
 1. npm: the organization `opensoftware` owns the scope `@opensoftware`, under which every package of this
    repository is published.
 2. GitHub: the publish job runs in the environment `npm` (Settings → Environments; GitHub creates it on the first
    run).
-3. First version only: npm configures trusted publishing per existing package, so `1.0.0` needs a token. Add a
-   granular npm access token with read and write access to the `opensoftware` organization's packages as the
-   secret `NPM_TOKEN` (a repository secret or a secret of the environment `npm`), or publish `1.0.0` by hand.
-4. After the first version: on npmjs.com, package settings → Trusted publishing, add GitHub Actions with the
-   repository `sesigl/open-software-factory`, the workflow `publish-contracts.yml` and the environment `npm`.
-   Then delete the secret `NPM_TOKEN` and revoke the token. Later versions publish through OIDC only.
+3. New package only: npm adds a trusted publisher only to a package that exists. Before the release pull request
+   with its first version merges, a maintainer creates it: build and pack it as version `0.0.0`, then run
+   `npm publish <file>.tgz --tag placeholder --access public` without `--otp`. npm stages that version, so the
+   package exists and nothing is public (`skills/release-packages`).
+4. Then add the trusted publisher, on npmjs.com (package settings → Trusted publishing) or with
+   `npm trust github <package> --file publish-<name>.yml --repository sesigl/open-software-factory --environment npm
+   --allow-publish --allow-stage-publish`. Every later version publishes through OIDC only, with a provenance
+   statement; the repository holds no npm token.
+
+An agent can do step 4 and the checks below with the npm CLI (11.19 or later). It needs a maintainer's
+`npm login --registry https://registry.npmjs.org`. Every `npm trust` call needs two-factor authentication, also
+`list`. Without a terminal, the call fails with `EOTP` and prints an `authUrl` and a `doneUrl`. The maintainer
+opens the `authUrl` and approves. Then a `GET` of the `doneUrl`, with the login's token as a bearer token, returns
+a `token`. The agent passes it as `--otp=<token>` to the next `npm trust` calls; it stays valid for some minutes.
+
+To check all packages, run `npm trust list <package>` for each `publish-*.yml` that publishes to npm. Each package
+has exactly one entry: this repository, its own workflow file, the environment `npm`, and the permissions
+`createPackage` and `createStagedPackage`.
+
+When a publish fails with `E404 Not Found - PUT https://registry.npmjs.org/@opensoftware%2f<name>`:
+
+- npm did not accept the job as a trusted publisher. Check that the job has `id-token: write` and
+  `environment: npm`, and compare the package's entry with the rule above.
+- An entry can look correct and still fail. Then remove it with `npm trust revoke <package> --id=<id>`, add it
+  again with step 4 and run the workflow again with the tag.
+- After a successful publish, npm can take some minutes before the version is available. A build that installs
+  the new version in this time fails with `ETARGET`; run it again.
 
 ## Configuration
 

package/dist/generated/types.d.ts

@@ -33,6 +33,40 @@ export type paths = {
         patch?: never;
         trace?: never;
     };
+    "/v1/health": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description The server's health. Needs no token, and names no secret. 503 when a check fails. */
+        get: operations["HealthApi_getHealth"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/inbox": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description The 50 latest work items, the one received last first; with `status`, only the work items in that status. */
+        get: operations["IntakeApi_listWorkItems"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/runs": {
         parameters: {
             query?: never;
@@ -439,6 +473,19 @@ export type components = {
             /** @description The record, once the gate is decided. */
             record?: components["schemas"]["GateRecord"];
         };
+        /** @description The state of a server: `ok` when every check is ok. */
+        Health: {
+            status: "ok" | "failing";
+            checks: components["schemas"]["HealthCheck"][];
+        };
+        /** @description One system a server needs, such as its database or NATS, and whether the server reaches it now. */
+        HealthCheck: {
+            /** @description The system, like "database", "nats" or "temporal". */
+            name: components["schemas"]["Name"];
+            ok: boolean;
+            /** @description What failed and how to fix it, when `ok` is false. Never a secret. */
+            detail?: string;
+        };
         /** @description A hostname without scheme or port, for example "api.linear.app". */
         Hostname: string;
         /** @description An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque. */
@@ -840,6 +887,8 @@ export type components = {
             startedAt: string;
             /** Format: date-time */
             endedAt?: string;
+            /** @description The OpenTelemetry trace of the run: the first 32 hex digits of the SHA-256 of `runId` (ADR 0087). */
+            traceId?: components["schemas"]["TraceId"];
             /** @description The stages of the workflow, in order. */
             stages: components["schemas"]["StageView"][];
         };
@@ -1039,6 +1088,10 @@ export type components = {
             /** @description Related material: an error report, a change, a document. */
             links?: components["schemas"]["Link"][];
         };
+        /** @description intake: the latest work items, as `GET /v1/inbox` answers them, the one received last first. */
+        WorkItemList: {
+            workItems: components["schemas"]["WorkItemView"][];
+        };
         /**
          * @description Where a work item stands: received, then as its run in the foreman goes (ADR 0071).
          * @enum {string}
@@ -1200,6 +1253,75 @@ export interface operations {
             };
         };
     };
+    HealthApi_getHealth: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The request has succeeded. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Health"];
+                };
+            };
+            /** @description Service unavailable. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Health"];
+                };
+            };
+        };
+    };
+    IntakeApi_listWorkItems: {
+        parameters: {
+            query?: {
+                status?: components["schemas"]["WorkItemStatus"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The request has succeeded. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkItemList"];
+                };
+            };
+            /** @description The server could not understand the request due to invalid syntax. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiProblem"];
+                };
+            };
+            /** @description Access is unauthorized. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiProblem"];
+                };
+            };
+        };
+    };
     ForemanApi_listRuns: {
         parameters: {
             query?: {

package/dist/index.d.ts

@@ -26,12 +26,15 @@ export type GateView = Schemas["GateView"];
 export type ApiProblem = Schemas["ApiProblem"];
 export type WorkSubmission = Schemas["WorkSubmission"];
 export type WorkItemView = Schemas["WorkItemView"];
+export type WorkItemList = Schemas["WorkItemList"];
 export type WorkRequest = Schemas["WorkRequest"];
 export type RunView = Schemas["RunView"];
 export type StageView = Schemas["StageView"];
 export type CheckView = Schemas["CheckView"];
 export type RunSignal = Schemas["RunSignal"];
 export type SandboxSpec = Schemas["SandboxSpec"];
+export type Health = Schemas["Health"];
+export type HealthCheck = Schemas["HealthCheck"];
 /** One reason a document does not match its format. `path` is a JSON Pointer into the document. */
 export interface Problem {
     path: string;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "2.0.0",
+    "version": "2.2.0",
     "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",
@@ -117,6 +117,87 @@
         }
       }
     },
+    "/v1/health": {
+      "get": {
+        "operationId": "HealthApi_getHealth",
+        "description": "The server's health. Needs no token, and names no secret. 503 when a check fails.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Health"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service unavailable.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Health"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {}
+        ]
+      }
+    },
+    "/v1/inbox": {
+      "get": {
+        "operationId": "IntakeApi_listWorkItems",
+        "description": "The 50 latest work items, the one received last first; with `status`, only the work items in that status.",
+        "parameters": [
+          {
+            "name": "status",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "$ref": "#/components/schemas/WorkItemStatus"
+            },
+            "explode": false
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemList"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/runs": {
       "post": {
         "operationId": "ForemanApi_startRun",
@@ -1388,6 +1469,55 @@
         ],
         "description": "gatekeeper: a gate as the HTTP API shows it (ADR 0048)."
       },
+      "Health": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "ok"
+              },
+              {
+                "type": "string",
+                "const": "failing"
+              }
+            ]
+          },
+          "checks": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/HealthCheck"
+            }
+          }
+        },
+        "required": [
+          "status",
+          "checks"
+        ],
+        "description": "The state of a server: `ok` when every check is ok."
+      },
+      "HealthCheck": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The system, like \"database\", \"nats\" or \"temporal\"."
+          },
+          "ok": {
+            "type": "boolean"
+          },
+          "detail": {
+            "type": "string",
+            "description": "What failed and how to fix it, when `ok` is false. Never a secret."
+          }
+        },
+        "required": [
+          "name",
+          "ok"
+        ],
+        "description": "One system a server needs, such as its database or NATS, and whether the server reaches it now."
+      },
       "Hostname": {
         "type": "string",
         "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$",
@@ -2423,6 +2553,10 @@
             "type": "string",
             "format": "date-time"
           },
+          "traceId": {
+            "$ref": "#/components/schemas/TraceId",
+            "description": "The OpenTelemetry trace of the run: the first 32 hex digits of the SHA-256 of `runId` (ADR 0087)."
+          },
           "stages": {
             "type": "array",
             "items": {
@@ -2959,6 +3093,21 @@
         ],
         "description": "One unit of requested work: the `data` of a `work.received@v1` CloudEvent."
       },
+      "WorkItemList": {
+        "type": "object",
+        "properties": {
+          "workItems": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/WorkItemView"
+            }
+          }
+        },
+        "required": [
+          "workItems"
+        ],
+        "description": "intake: the latest work items, as `GET /v1/inbox` answers them, the one received last first."
+      },
       "WorkItemStatus": {
         "type": "string",
         "enum": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,7 +44,7 @@
     "@typespec/openapi": "1.17.0",
     "@typespec/openapi3": "1.17.0",
     "openapi-typescript": "7.13.0",
-    "@opensoftware/testkit": "0.28.0"
+    "@opensoftware/testkit": "0.31.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",

package/typespec/foreman.tsp

@@ -97,6 +97,9 @@ model RunView {
   startedAt: utcDateTime;
   endedAt?: utcDateTime;
 
+  /** The OpenTelemetry trace of the run: the first 32 hex digits of the SHA-256 of `runId` (ADR 0087). */
+  traceId?: TraceId;
+
   /** The stages of the workflow, in order. */
   stages: StageView[];
 }

package/typespec/health.tsp

@@ -0,0 +1,42 @@
+// The health route that intake, gatekeeper and the foreman each serve (ADR 0086): the state of the server and of each
+// system it needs. `console doctor` and the Compose profile's health checks read it.
+import "@typespec/http";
+import "./common.tsp";
+import "./gatekeeper-api.tsp";
+
+using TypeSpec.Http;
+
+namespace Osf.Contracts;
+
+/** One system a server needs, such as its database or NATS, and whether the server reaches it now. */
+model HealthCheck {
+  /** The system, like "database", "nats" or "temporal". */
+  name: Name;
+
+  ok: boolean;
+
+  /** What failed and how to fix it, when `ok` is false. Never a secret. */
+  detail?: string;
+}
+
+/** The state of a server: `ok` when every check is ok. */
+model Health {
+  status: "ok" | "failing";
+  checks: HealthCheck[];
+}
+
+namespace HealthApi {
+  /** The server's health. Needs no token, and names no secret. 503 when a check fails. */
+  @route("/v1/health")
+  @get
+  @useAuth(NoAuth)
+  op getHealth():
+    | {
+        @statusCode statusCode: 200;
+        @body health: Health;
+      }
+    | {
+        @statusCode statusCode: 503;
+        @body health: Health;
+      };
+}

package/typespec/intake-api.tsp

@@ -33,6 +33,14 @@ namespace IntakeApi {
     | GatekeeperApi.Failure<401>
     | GatekeeperApi.Failure<404>;
 
+  /** The 50 latest work items, the one received last first; with `status`, only the work items in that status. */
+  @route("/v1/inbox")
+  @get
+  op listWorkItems(@query status?: WorkItemStatus):
+    | WorkItemList
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>;
+
   /** A work item, its status and every request that asked for it. */
   @route("/v1/work-items/{workItemId}")
   @get

package/typespec/intake.tsp

@@ -43,6 +43,11 @@ model WorkRequest {
   receivedAt: utcDateTime;
 }
 
+/** intake: the latest work items, as `GET /v1/inbox` answers them, the one received last first. */
+model WorkItemList {
+  workItems: WorkItemView[];
+}
+
 /** intake: a work item as the HTTP API shows it (ADR 0063). */
 model WorkItemView {
   /** Its ID is "wi_" and 20 hex digits of the SHA-256 of its dedupe key. */

package/typespec/main.tsp

@@ -15,3 +15,4 @@ import "./intake-api.tsp";
 import "./foreman.tsp";
 import "./foreman-api.tsp";
 import "./sandbox.tsp";
+import "./health.tsp";