@opensoftware/contracts 1.6.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "1.6.0",
+  "version": "1.8.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.16.0"
+    "@opensoftware/testkit": "0.23.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",

package/typespec/events.tsp

@@ -39,6 +39,9 @@ model CloudEvent<Type extends string, Data> {
 /** intake: a work item was accepted. */
 model WorkReceived is CloudEvent<"work.received@v1", WorkItem>;
 
+/** foreman: a run started (ADR 0067). */
+model RunStarted is CloudEvent<"run.started@v1", RunStartedData>;
+
 /** foreman: a run ended. */
 model RunCompleted is CloudEvent<"run.completed@v1", RunCompletedData>;
 
@@ -60,6 +63,26 @@ model PrReviewed is CloudEvent<"pr.reviewed@v1", PrReviewedData>;
 /** forge adapters: a pull request was merged or closed without a merge. */
 model PrClosed is CloudEvent<"pr.closed@v1", PrClosedData>;
 
+/** forge adapters: a label was added to an issue. */
+model IssueLabeled is CloudEvent<"issue.labeled@v1", IssueLabeledData>;
+
+model RunStartedData {
+  runId: Identifier;
+  workItemId: Identifier;
+
+  /** The name of the factory. */
+  factory: Name;
+
+  factoryVersion: CommitHash;
+
+  /** The stages of the run's workflow, in order. */
+  stages: Name[];
+
+  startedAt: utcDateTime;
+  requester: Actor;
+  source: Name;
+}
+
 model RunCompletedData {
   runId: Identifier;
   workItemId: Identifier;
@@ -166,3 +189,27 @@ model PrClosedData {
 
   mergeCommit?: CommitHash;
 }
+
+model IssueLabeledData {
+  /** The issue. */
+  url: url;
+
+  repository: url;
+
+  @minValue(1)
+  number: safeint;
+
+  @minLength(1)
+  title: string;
+
+  body?: string;
+
+  /** The person who opened the issue. */
+  author: Actor;
+
+  /** Every label of the issue after the change. */
+  labels: string[];
+
+  /** The label that was added, when the forge names it. */
+  label?: string;
+}

package/typespec/factory-definition.tsp

@@ -126,10 +126,20 @@ model Stage {
   /** The stage waits for a decision before it starts. */
   gate?: Gate;
 
+  /**
+   * Checks that must succeed on the run's pull request before the stage starts, by their names on the forge, for
+   * example "verify" (ADR 0069).
+   */
+  checks?: CheckName[];
+
   /** Whether the stage must produce an evidence bundle. */
   evidence?: EvidenceRequirement;
 }
 
+/** The name of a check on the forge: a commit status context. */
+@minLength(1)
+scalar CheckName extends string;
+
 enum EvidenceRequirement {
   required,
   optional,

package/typespec/foreman-api.tsp

@@ -0,0 +1,45 @@
+// The HTTP API of `foreman serve` (ADR 0067). `pnpm build` compiles it with the OpenAPI 3 emitter and copies its paths
+// into openapi/openapi.json, next to gatekeeper's and intake's; the models are the named models of the JSON Schema
+// bundle.
+import "@typespec/http";
+import "./foreman.tsp";
+import "./gatekeeper-api.tsp";
+
+using TypeSpec.Http;
+
+namespace Osf.Contracts;
+
+namespace ForemanApi {
+  /** Start a run of the factory's workflow for a work item. The same work item again answers the run it started. */
+  @route("/v1/runs")
+  @post
+  op startRun(@body workItem: WorkItem):
+    | {
+        @statusCode statusCode: 201;
+        @body run: RunView;
+      }
+    | {
+        @statusCode statusCode: 200;
+        @body run: RunView;
+      }
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>;
+
+  /** A run: its state and the state of each stage. */
+  @route("/v1/runs/{runId}")
+  @get
+  op getRun(@path runId: string): RunView | GatekeeperApi.Failure<401> | GatekeeperApi.Failure<404>;
+
+  /** Steer the running stage's agent, or cancel the run. */
+  @route("/v1/runs/{runId}/signals")
+  @post
+  op signalRun(@path runId: string, @body signal: RunSignal):
+    | {
+        @statusCode statusCode: 202;
+        @body run: RunView;
+      }
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>
+    | GatekeeperApi.Failure<404>
+    | GatekeeperApi.Failure<409>;
+}

package/typespec/foreman.tsp

@@ -0,0 +1,110 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./work-item.tsp";
+import "./factory-definition.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/** foreman: where a run stands (vision scenario ORCH-008). */
+enum RunState {
+  running,
+  blocked,
+  complete,
+  failed,
+  cancelled,
+}
+
+/** foreman: where a stage of a run stands. */
+enum StageState {
+  pending,
+  blocked,
+  running,
+  succeeded,
+  failed,
+  rejected,
+  cancelled,
+}
+
+/** foreman: the state of a check on the forge (forge port). */
+enum CheckState {
+  pending,
+  success,
+  failure,
+  error,
+}
+
+/** foreman: a check that a stage waits for, as the foreman last read it on the run's pull request (ADR 0069). */
+model CheckView {
+  name: CheckName;
+  state: CheckState;
+}
+
+/** foreman: one stage of a run (ADR 0067). */
+model StageView {
+  stage: Name;
+
+  /** The agent that runs the stage. */
+  agent: Name;
+
+  state: StageState;
+
+  /** The harness session of the stage's agent, once it started. */
+  sessionId?: string;
+
+  /** The gate that decides whether the stage starts, once it was requested. */
+  @pattern("^g[0-9a-f]{16}$")
+  gateId?: string;
+
+  /** The checks the stage waits for, once the foreman read them (ADR 0069). */
+  checks?: CheckView[];
+
+  /** Why the stage ended without success, when the foreman knows. */
+  @minLength(1)
+  reason?: string;
+
+  startedAt?: utcDateTime;
+  endedAt?: utcDateTime;
+}
+
+/** foreman: a run of the factory's workflow for one work item, as the HTTP API shows it (ADR 0067). */
+model RunView {
+  /** "run_" and 20 hex digits of the SHA-256 of the work item's ID. */
+  @pattern("^run_[0-9a-f]{20}$")
+  runId: string;
+
+  workItem: WorkItem;
+
+  /** The name of the factory. */
+  factory: Name;
+
+  /** The commit of the factory definition the run started with. */
+  factoryVersion: CommitHash;
+
+  state: RunState;
+
+  /** The last pull request link that an agent of the run wrote (ADR 0069). */
+  pullRequest?: url;
+
+  startedAt: utcDateTime;
+  endedAt?: utcDateTime;
+
+  /** The stages of the workflow, in order. */
+  stages: StageView[];
+}
+
+/** foreman: what a person tells a run. */
+enum RunSignalType {
+  steer,
+  cancel,
+}
+
+/** foreman: a signal to a run: "steer" with a message for the running stage's agent, or "cancel". */
+model RunSignal {
+  type: RunSignalType;
+
+  /** The steering message. Required with "steer". */
+  @minLength(1)
+  message?: string;
+}

package/typespec/intake-api.tsp

@@ -0,0 +1,40 @@
+// The HTTP API of `intake serve` (ADR 0063). `pnpm build` compiles it with the OpenAPI 3 emitter and copies its paths
+// into openapi/openapi.json, next to gatekeeper's; the models are the named models of the JSON Schema bundle.
+import "@typespec/http";
+import "./intake.tsp";
+import "./gatekeeper-api.tsp";
+
+using TypeSpec.Http;
+
+namespace Osf.Contracts;
+
+namespace IntakeApi {
+  /** Put work into the inbox. A submission with the dedupe key of a work item answers that work item. */
+  @route("/v1/work-items")
+  @post
+  op submitWork(@body submission: WorkSubmission):
+    | {
+        @statusCode statusCode: 201;
+        @body workItem: WorkItemView;
+      }
+    | {
+        @statusCode statusCode: 200;
+        @body workItem: WorkItemView;
+      }
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>;
+
+  /** The work item with this dedupe key, such as an issue's link (ADR 0065). */
+  @route("/v1/work-items")
+  @get
+  op findWorkItem(@query dedupeKey: string):
+    | WorkItemView
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>
+    | GatekeeperApi.Failure<404>;
+
+  /** A work item, its status and every request that asked for it. */
+  @route("/v1/work-items/{workItemId}")
+  @get
+  op getWorkItem(@path workItemId: string): WorkItemView | GatekeeperApi.Failure<401> | GatekeeperApi.Failure<404>;
+}

package/typespec/intake.tsp

@@ -0,0 +1,52 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./work-item.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/** intake: work to put into the inbox, a work item without its ID (ADR 0063). */
+model WorkSubmission {
+  /** Default: task. */
+  type?: WorkItemType;
+
+  @minLength(1)
+  @maxLength(300)
+  title: string;
+
+  description?: string;
+  requester: Actor;
+  origin: Origin;
+
+  /** Requests with the same key become one work item. Default: the origin's url, else "<source>:<externalId>". */
+  @minLength(1)
+  dedupeKey?: string;
+
+  surface?: string;
+  links?: Link[];
+}
+
+/** Where a work item stands. */
+enum WorkItemStatus {
+  received,
+}
+
+/** intake: one submission that asked for a work item. */
+model WorkRequest {
+  requester: Actor;
+  origin: Origin;
+  receivedAt: utcDateTime;
+}
+
+/** 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. */
+  workItem: WorkItem;
+
+  status: WorkItemStatus;
+  receivedAt: utcDateTime;
+
+  /** Every submission that asked for the work item, oldest first; one per origin. */
+  requests: WorkRequest[];
+}

package/typespec/main.tsp

@@ -10,4 +10,8 @@ import "./score.tsp";
 import "./events.tsp";
 import "./gatekeeper.tsp";
 import "./gatekeeper-api.tsp";
+import "./intake.tsp";
+import "./intake-api.tsp";
+import "./foreman.tsp";
+import "./foreman-api.tsp";
 import "./sandbox.tsp";