@opensoftware/contracts 1.9.0 → 1.10.0

package/dist/generated/types.d.ts

@@ -40,7 +40,8 @@ export type paths = {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /** @description The runs of the server, running runs first, then the runs that ended, the one that ended last first; with `state`, only the runs in that state (ADR 0071). */
+        get: operations["ForemanApi_listRuns"];
         put?: never;
         /** @description Start a run of the factory's workflow for a work item. The same work item again answers the run it started. */
         post: operations["ForemanApi_startRun"];
@@ -684,6 +685,10 @@ export type components = {
             /** Format: uri */
             evidenceBundle?: string;
         };
+        /** @description foreman: the runs of the server, running runs first, then the runs that ended, the one that ended last first, as `GET /v1/runs` answers them (ADR 0071). */
+        RunList: {
+            runs: components["schemas"]["RunView"][];
+        };
         /**
          * @description How a run ended.
          * @enum {string}
@@ -1025,10 +1030,10 @@ export type components = {
             links?: components["schemas"]["Link"][];
         };
         /**
-         * @description Where a work item stands.
+         * @description Where a work item stands: received, then as its run in the foreman goes (ADR 0071).
          * @enum {string}
          */
-        WorkItemStatus: "received";
+        WorkItemStatus: "received" | "running" | "complete" | "failed" | "cancelled";
         /** @enum {string} */
         WorkItemType: "idea" | "bug" | "task" | "automation";
         /** @description intake: a work item as the HTTP API shows it (ADR 0063). */
@@ -1036,6 +1041,8 @@ export type components = {
             /** @description Its ID is "wi_" and 20 hex digits of the SHA-256 of its dedupe key. */
             workItem: components["schemas"]["WorkItem"];
             status: components["schemas"]["WorkItemStatus"];
+            /** @description The foreman's run of the work item, once it started (ADR 0071). */
+            runId?: string;
             /** Format: date-time */
             receivedAt: string;
             /** @description Every submission that asked for the work item, oldest first; one per origin. */
@@ -1183,6 +1190,46 @@ export interface operations {
             };
         };
     };
+    ForemanApi_listRuns: {
+        parameters: {
+            query?: {
+                state?: components["schemas"]["RunState"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The request has succeeded. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RunList"];
+                };
+            };
+            /** @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_startRun: {
         parameters: {
             query?: never;

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "1.9.0",
+    "version": "1.10.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",
@@ -174,6 +174,53 @@
             }
           }
         }
+      },
+      "get": {
+        "operationId": "ForemanApi_listRuns",
+        "description": "The runs of the server, running runs first, then the runs that ended, the one that ended last first; with `state`, only the runs in that state (ADR 0071).",
+        "parameters": [
+          {
+            "name": "state",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "$ref": "#/components/schemas/RunState"
+            },
+            "explode": false
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunList"
+                }
+              }
+            }
+          },
+          "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/{runId}": {
@@ -2000,6 +2047,21 @@
           "source"
         ]
       },
+      "RunList": {
+        "type": "object",
+        "properties": {
+          "runs": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RunView"
+            }
+          }
+        },
+        "required": [
+          "runs"
+        ],
+        "description": "foreman: the runs of the server, running runs first, then the runs that ended, the one that ended last first, as `GET /v1/runs` answers them (ADR 0071)."
+      },
       "RunOutcome": {
         "type": "string",
         "enum": [
@@ -2884,9 +2946,13 @@
       "WorkItemStatus": {
         "type": "string",
         "enum": [
-          "received"
+          "received",
+          "running",
+          "complete",
+          "failed",
+          "cancelled"
         ],
-        "description": "Where a work item stands."
+        "description": "Where a work item stands: received, then as its run in the foreman goes (ADR 0071)."
       },
       "WorkItemType": {
         "type": "string",
@@ -2907,6 +2973,11 @@
           "status": {
             "$ref": "#/components/schemas/WorkItemStatus"
           },
+          "runId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The foreman's run of the work item, once it started (ADR 0071)."
+          },
           "receivedAt": {
             "type": "string",
             "format": "date-time"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
   "license": "Apache-2.0",
   "repository": {

package/typespec/foreman-api.tsp

@@ -25,6 +25,11 @@ namespace ForemanApi {
     | GatekeeperApi.Failure<400>
     | GatekeeperApi.Failure<401>;
 
+  /** The runs of the server, running runs first, then the runs that ended, the one that ended last first; with `state`, only the runs in that state (ADR 0071). */
+  @route("/v1/runs")
+  @get
+  op listRuns(@query state?: RunState): RunList | GatekeeperApi.Failure<400> | GatekeeperApi.Failure<401>;
+
   /** A run: its state and the state of each stage. */
   @route("/v1/runs/{runId}")
   @get

package/typespec/foreman.tsp

@@ -101,6 +101,11 @@ model RunView {
   stages: StageView[];
 }
 
+/** foreman: the runs of the server, running runs first, then the runs that ended, the one that ended last first, as `GET /v1/runs` answers them (ADR 0071). */
+model RunList {
+  runs: RunView[];
+}
+
 /** foreman: what a person tells a run. */
 enum RunSignalType {
   steer,

package/typespec/intake.tsp

@@ -27,9 +27,13 @@ model WorkSubmission {
   links?: Link[];
 }
 
-/** Where a work item stands. */
+/** Where a work item stands: received, then as its run in the foreman goes (ADR 0071). */
 enum WorkItemStatus {
   received,
+  running,
+  complete,
+  failed,
+  cancelled,
 }
 
 /** intake: one submission that asked for a work item. */
@@ -45,6 +49,11 @@ model WorkItemView {
   workItem: WorkItem;
 
   status: WorkItemStatus;
+
+  /** The foreman's run of the work item, once it started (ADR 0071). */
+  @minLength(1)
+  runId?: string;
+
   receivedAt: utcDateTime;
 
   /** Every submission that asked for the work item, oldest first; one per origin. */