@foss.global/interfaces 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/changelog.md +22 -0
  2. package/dist_ts/00_commitinfo_data.js +1 -1
  3. package/dist_ts/data/gitmanager.d.ts +82 -0
  4. package/dist_ts/data/index.d.ts +1 -0
  5. package/dist_ts/data/index.js +2 -1
  6. package/dist_ts/data/runner.d.ts +189 -0
  7. package/dist_ts/data/runner.js +2 -0
  8. package/package.json +3 -3
  9. package/readme.md +49 -1
  10. package/ts/00_commitinfo_data.ts +1 -1
  11. package/ts/data/gitmanager.ts +105 -0
  12. package/ts/data/index.ts +1 -0
  13. package/ts/data/runner.ts +225 -0
package/changelog.md CHANGED
@@ -1,5 +1,27 @@
1
1
  # Changelog
2
2
 
3
+ ## 2026-07-20 - 0.4.0
4
+
5
+ ### Features
6
+
7
+ - add runner protocol and CI control-plane contracts (ci)
8
+ - Define protocol versioning, runner registration, sessions, heartbeats, job leasing, fencing, logs, completion, abandonment, and recovery DTOs.
9
+ - Define CI job enqueue, status, log page, cancellation, and runner drain DTOs.
10
+ - Describe OCI runner capabilities including the initial archive, artifact, cache, service-container, and network support boundaries.
11
+
12
+ ### Maintenance
13
+
14
+ - update the repository package manager and development tooling patch versions (tooling)
15
+
16
+ ## 2026-06-23 - 0.3.0
17
+
18
+ ### Features
19
+
20
+ - add GitManager read contract interfaces (gitmanager)
21
+ - Added commit detail, diff, and tag contract interfaces for GitManager reads.
22
+ - Added diff status and line kind union types for structured diff data.
23
+ - Added tests covering the exported GitManager read contract shapes.
24
+
3
25
  ## 2026-06-22 - 0.2.0
4
26
 
5
27
  ### Features
package/dist_ts/00_commitinfo_data.js CHANGED
@@ -3,7 +3,7 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@foss.global/interfaces',
6
- version: '0.2.0',
6
+ version: '0.4.0',
7
7
  description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
8
8
  };
9
9
  //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHFHQUFxRztDQUNuSCxDQUFBIn0=
package/dist_ts/data/gitmanager.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  export type TGitManagerRefType = 'branch' | 'tag' | 'other';
2
2
  export type TGitManagerObjectType = 'blob' | 'tree' | 'commit' | 'tag' | 'other';
3
3
  export type TGitManagerTreeEntryType = 'file' | 'dir' | 'symlink' | 'submodule' | 'other';
4
+ export type TGitManagerDiffFileStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'copied' | 'typechange' | 'unmerged' | 'unknown';
5
+ export type TGitManagerDiffLineKind = 'add' | 'del' | 'context';
4
6
  export interface IGitManagerRepositorySelector {
5
7
  org: string;
6
8
  repo: string;
@@ -64,3 +66,83 @@ export interface IGitManagerCommitSummary extends IGitManagerRepositorySelector
64
66
  authorEmail: string;
65
67
  subject: string;
66
68
  }
69
+ export interface IGitManagerCommitRequest extends IGitManagerRepositorySelector {
70
+ ref: string;
71
+ }
72
+ export interface IGitManagerCommitParent {
73
+ sha: string;
74
+ shortSha: string;
75
+ }
76
+ export interface IGitManagerCommitActor {
77
+ name: string;
78
+ email: string;
79
+ date: string;
80
+ }
81
+ export interface IGitManagerDiffStats {
82
+ filesChanged: number;
83
+ additions: number;
84
+ deletions: number;
85
+ }
86
+ export interface IGitManagerCommitDetail extends IGitManagerCommitSummary {
87
+ message: string;
88
+ body: string;
89
+ treeId: string;
90
+ parents: IGitManagerCommitParent[];
91
+ author: IGitManagerCommitActor;
92
+ committer: IGitManagerCommitActor;
93
+ stats: IGitManagerDiffStats;
94
+ }
95
+ export interface IGitManagerDiffRequest extends IGitManagerRepositorySelector {
96
+ headRef: string;
97
+ baseRef?: string;
98
+ path?: string;
99
+ contextLines?: number;
100
+ }
101
+ export interface IGitManagerDiffLine {
102
+ kind: TGitManagerDiffLineKind;
103
+ content: string;
104
+ oldNumber: number | null;
105
+ newNumber: number | null;
106
+ }
107
+ export interface IGitManagerDiffHunk {
108
+ header: string;
109
+ oldStart: number;
110
+ oldLines: number;
111
+ newStart: number;
112
+ newLines: number;
113
+ lines: IGitManagerDiffLine[];
114
+ }
115
+ export interface IGitManagerDiffFile {
116
+ oldPath: string;
117
+ newPath: string;
118
+ status: TGitManagerDiffFileStatus;
119
+ additions: number;
120
+ deletions: number;
121
+ isBinary: boolean;
122
+ hunks: IGitManagerDiffHunk[];
123
+ }
124
+ export interface IGitManagerDiff extends IGitManagerRepositorySelector, IGitManagerDiffStats {
125
+ baseRef: string;
126
+ headRef: string;
127
+ files: IGitManagerDiffFile[];
128
+ truncated: boolean;
129
+ }
130
+ export interface IGitManagerListTagsRequest extends IGitManagerRepositorySelector {
131
+ pattern?: string;
132
+ limit?: number;
133
+ }
134
+ export interface IGitManagerTagRequest extends IGitManagerRepositorySelector {
135
+ tag: string;
136
+ }
137
+ export interface IGitManagerTag extends IGitManagerRepositorySelector {
138
+ name: string;
139
+ objectId: string;
140
+ targetObjectId: string;
141
+ targetObjectType: TGitManagerObjectType;
142
+ isAnnotated: boolean;
143
+ taggerName: string;
144
+ taggerEmail: string;
145
+ taggedAt: string;
146
+ subject: string;
147
+ message: string;
148
+ }
package/dist_ts/data/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export * from './codefeed.js';
2
2
  export * from './gitmanager.js';
3
3
  export * from './public.js';
4
+ export * from './runner.js';
package/dist_ts/data/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from './codefeed.js';
2
2
  export * from './gitmanager.js';
3
3
  export * from './public.js';
4
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxhQUFhLENBQUMifQ==
4
+ export * from './runner.js';
5
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUMifQ==
package/dist_ts/data/runner.d.ts ADDED
@@ -0,0 +1,189 @@
1
+ export declare const runnerProtocolVersion: "1";
2
+ export type TRunnerProtocolVersion = typeof runnerProtocolVersion;
3
+ export type TOciRuntime = 'docker' | 'podman';
4
+ export type TJobNetwork = 'none' | 'bridge';
5
+ export type TLogStream = 'stdout' | 'stderr' | 'runner';
6
+ export type TJobCompletionStatus = 'succeeded' | 'failed' | 'canceled' | 'timed_out' | 'system_error';
7
+ export type TCiJobState = 'queued' | 'running' | TJobCompletionStatus;
8
+ export interface IRunnerCredential {
9
+ runnerId: string;
10
+ runnerToken: string;
11
+ runnerTokenExpiresAt: string;
12
+ }
13
+ export interface IRunnerCapabilities {
14
+ executor: 'oci';
15
+ runtime: TOciRuntime;
16
+ networks: TJobNetwork[];
17
+ sourceArchives: ['tar.gz'];
18
+ artifacts: false;
19
+ caches: false;
20
+ serviceContainers: false;
21
+ }
22
+ export interface IRegisterRunnerRequest {
23
+ registrationRequestId: string;
24
+ protocolVersion: string;
25
+ runnerVersion: string;
26
+ name: string;
27
+ labels: string[];
28
+ capabilities: IRunnerCapabilities;
29
+ }
30
+ export interface IRegisterRunnerResponse extends IRunnerCredential {
31
+ protocolVersion: string;
32
+ serverTime: string;
33
+ }
34
+ export interface IStartSessionRequest {
35
+ sessionRequestId: string;
36
+ runnerId: string;
37
+ protocolVersion: string;
38
+ runnerVersion: string;
39
+ capabilities: IRunnerCapabilities;
40
+ }
41
+ export interface IStartSessionResponse {
42
+ sessionId: string;
43
+ protocolVersion: string;
44
+ serverTime: string;
45
+ credential?: IRunnerCredential;
46
+ }
47
+ export interface IRunnerHeartbeatRequest {
48
+ runnerId: string;
49
+ sessionId: string;
50
+ }
51
+ export interface IRunnerHeartbeatResponse {
52
+ serverTime: string;
53
+ drainRequested: boolean;
54
+ credential?: IRunnerCredential;
55
+ }
56
+ export interface IJobResources {
57
+ memoryBytes?: number;
58
+ cpus?: number;
59
+ pids?: number;
60
+ }
61
+ export interface IJobSourceArchive {
62
+ format: 'tar.gz';
63
+ url: string;
64
+ sha256: string;
65
+ }
66
+ export interface IJobSpec {
67
+ image: string;
68
+ command: string[];
69
+ environment?: Record<string, string>;
70
+ secrets?: Record<string, string>;
71
+ network?: TJobNetwork;
72
+ timeoutMs?: number;
73
+ resources?: IJobResources;
74
+ source?: IJobSourceArchive;
75
+ }
76
+ export interface IJobLease {
77
+ jobId: string;
78
+ attemptId: string;
79
+ leaseId: string;
80
+ fencingToken: string;
81
+ leaseExpiresAt: string;
82
+ job: IJobSpec;
83
+ }
84
+ export interface IClaimJobRequest {
85
+ claimRequestId: string;
86
+ runnerId: string;
87
+ sessionId: string;
88
+ labels: string[];
89
+ }
90
+ export interface IClaimJobResponse {
91
+ serverTime: string;
92
+ retryAfterMs?: number;
93
+ lease: IJobLease | null;
94
+ }
95
+ export interface IJobMutationIdentity {
96
+ runnerId: string;
97
+ sessionId: string;
98
+ jobId: string;
99
+ attemptId: string;
100
+ leaseId: string;
101
+ fencingToken: string;
102
+ }
103
+ export interface IJobHeartbeatResponse {
104
+ serverTime: string;
105
+ leaseExpiresAt: string;
106
+ cancelRequested: boolean;
107
+ }
108
+ export interface ILogChunk extends IJobMutationIdentity {
109
+ sequence: number;
110
+ stream: TLogStream;
111
+ data: string;
112
+ timestamp: string;
113
+ }
114
+ export interface ILogAcknowledgement {
115
+ serverTime: string;
116
+ nextSequence: number;
117
+ }
118
+ export interface ICompleteJobRequest extends IJobMutationIdentity {
119
+ status: TJobCompletionStatus;
120
+ exitCode: number | null;
121
+ startedAt: string;
122
+ completedAt: string;
123
+ error?: string;
124
+ }
125
+ export interface ICompleteJobResponse {
126
+ serverTime: string;
127
+ accepted: boolean;
128
+ }
129
+ export interface IAbandonJobRequest extends IJobMutationIdentity {
130
+ reason: 'runner_shutdown' | 'runner_error';
131
+ }
132
+ export interface IRecoverAttemptRequest extends IJobMutationIdentity {
133
+ currentSessionId: string;
134
+ reason: 'runner_restarted';
135
+ }
136
+ export interface ICiEnqueueJobRequest {
137
+ idempotencyKey: string;
138
+ tenantId: string;
139
+ repositoryId: string;
140
+ requiredLabels: string[];
141
+ job: IJobSpec;
142
+ }
143
+ export interface ICiEnqueueJobResponse {
144
+ jobId: string;
145
+ state: TCiJobState;
146
+ createdAt: string;
147
+ duplicate: boolean;
148
+ }
149
+ export interface ICiJobSummary {
150
+ jobId: string;
151
+ tenantId: string;
152
+ repositoryId: string;
153
+ state: TCiJobState;
154
+ image: string;
155
+ requiredLabels: string[];
156
+ attemptNumber: number;
157
+ cancelRequested: boolean;
158
+ createdAt: string;
159
+ updatedAt: string;
160
+ startedAt?: string;
161
+ completedAt?: string;
162
+ completionStatus?: TJobCompletionStatus;
163
+ exitCode?: number | null;
164
+ error?: string;
165
+ }
166
+ export interface ICiLogEntry {
167
+ sequence: number;
168
+ stream: TLogStream;
169
+ data: string;
170
+ timestamp: string;
171
+ }
172
+ export interface ICiLogPage {
173
+ jobId: string;
174
+ attemptId: string;
175
+ entries: ICiLogEntry[];
176
+ nextSequence: number | null;
177
+ }
178
+ export interface ICiCancelJobResponse {
179
+ jobId: string;
180
+ state: TCiJobState;
181
+ cancelRequested: boolean;
182
+ }
183
+ export interface ICiSetRunnerDrainRequest {
184
+ drainRequested: boolean;
185
+ }
186
+ export interface ICiSetRunnerDrainResponse {
187
+ runnerId: string;
188
+ drainRequested: boolean;
189
+ }
package/dist_ts/data/runner.js ADDED
@@ -0,0 +1,2 @@
1
+ export const runnerProtocolVersion = '1';
2
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVubmVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9ydW5uZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQUcsR0FBWSxDQUFDIn0=
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@foss.global/interfaces",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "private": false,
5
5
  "description": "Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.",
6
6
  "exports": {
@@ -15,9 +15,9 @@
15
15
  "devDependencies": {
16
16
  "@git.zone/tsbuild": "^4.4.2",
17
17
  "@git.zone/tsdoc": "^2.1.1",
18
- "@git.zone/tsrun": "^2.0.4",
18
+ "@git.zone/tsrun": "^2.0.5",
19
19
  "@git.zone/tstest": "^3.6.6",
20
- "@types/node": "^26.0.0"
20
+ "@types/node": "^26.1.1"
21
21
  },
22
22
  "files": [
23
23
  "ts/**/*",
package/readme.md CHANGED
@@ -47,9 +47,57 @@ const repo: data.IPublicRepo = {
47
47
  type PublicOverviewRequest = requests.IReq_PublicOverview;
48
48
  ```
49
49
 
50
+ ### Runner and CI contracts
51
+
52
+ Runner protocol v1 is exposed through `runnerProtocolVersion`. The package root and the `data` namespace both export the complete runner and CI DTO set:
53
+
54
+ ```ts
55
+ import {
56
+ runnerProtocolVersion,
57
+ type IClaimJobResponse,
58
+ type ICiEnqueueJobRequest,
59
+ type IRegisterRunnerRequest,
60
+ } from '@foss.global/interfaces';
61
+
62
+ const registration: IRegisterRunnerRequest = {
63
+ registrationRequestId: 'registration-1',
64
+ protocolVersion: runnerProtocolVersion,
65
+ runnerVersion: '0.1.0',
66
+ name: 'linux-amd64-1',
67
+ labels: ['linux', 'amd64'],
68
+ capabilities: {
69
+ executor: 'oci',
70
+ runtime: 'docker',
71
+ networks: ['none', 'bridge'],
72
+ sourceArchives: ['tar.gz'],
73
+ artifacts: false,
74
+ caches: false,
75
+ serviceContainers: false,
76
+ },
77
+ };
78
+
79
+ const enqueue: ICiEnqueueJobRequest = {
80
+ idempotencyKey: 'build-main-1',
81
+ tenantId: 'foss.global',
82
+ repositoryId: 'foss.global/interfaces',
83
+ requiredLabels: ['linux', 'amd64'],
84
+ job: {
85
+ image: 'node:24',
86
+ command: ['pnpm', 'test'],
87
+ network: 'none',
88
+ },
89
+ };
90
+
91
+ type ClaimedJob = IClaimJobResponse;
92
+ ```
93
+
94
+ The runner lifecycle contracts cover registration, sessions, runner and job heartbeats, claim/lease identity, fencing tokens, ordered log chunks, completion, abandonment, and recovery. The CI control-plane contracts cover job enqueue and summaries, log pages, cancellation, and runner drain state.
95
+
96
+ Protocol v1 describes OCI execution with Docker or Podman and `tar.gz` source archives. Artifacts, caches, and service containers are explicitly unsupported in the v1 capability shape. Supported job network modes are `none` and `bridge`; the execution service remains responsible for enforcing the advertised capability.
97
+
50
98
  ## Exports
51
99
 
52
- - `data`: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, activity, news, stats, codefeed commit results, and GitManager repository/read API results.
100
+ - `data`: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, activity, news, stats, codefeed commit results, GitManager repository/read API results, and runner/CI contracts.
53
101
  - `requests`: TypedRequest contracts for `codefeed`, `publicOverview`, `publicOrg`, `publicRepo`, `publicFile`, and `publicCommits`.
54
102
  - Barrel exports: all public data and request interfaces are also exported from the package root.
55
103
 
package/ts/00_commitinfo_data.ts CHANGED
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@foss.global/interfaces',
6
- version: '0.2.0',
6
+ version: '0.4.0',
7
7
  description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
8
8
  }
package/ts/data/gitmanager.ts CHANGED
@@ -4,6 +4,18 @@ export type TGitManagerObjectType = 'blob' | 'tree' | 'commit' | 'tag' | 'other'
4
4
 
5
5
  export type TGitManagerTreeEntryType = 'file' | 'dir' | 'symlink' | 'submodule' | 'other';
6
6
 
7
+ export type TGitManagerDiffFileStatus =
8
+ | 'added'
9
+ | 'modified'
10
+ | 'deleted'
11
+ | 'renamed'
12
+ | 'copied'
13
+ | 'typechange'
14
+ | 'unmerged'
15
+ | 'unknown';
16
+
17
+ export type TGitManagerDiffLineKind = 'add' | 'del' | 'context';
18
+
7
19
  export interface IGitManagerRepositorySelector {
8
20
  org: string;
9
21
  repo: string;
@@ -77,3 +89,96 @@ export interface IGitManagerCommitSummary extends IGitManagerRepositorySelector
77
89
  authorEmail: string;
78
90
  subject: string;
79
91
  }
92
+
93
+ export interface IGitManagerCommitRequest extends IGitManagerRepositorySelector {
94
+ ref: string;
95
+ }
96
+
97
+ export interface IGitManagerCommitParent {
98
+ sha: string;
99
+ shortSha: string;
100
+ }
101
+
102
+ export interface IGitManagerCommitActor {
103
+ name: string;
104
+ email: string;
105
+ date: string;
106
+ }
107
+
108
+ export interface IGitManagerDiffStats {
109
+ filesChanged: number;
110
+ additions: number;
111
+ deletions: number;
112
+ }
113
+
114
+ export interface IGitManagerCommitDetail extends IGitManagerCommitSummary {
115
+ message: string;
116
+ body: string;
117
+ treeId: string;
118
+ parents: IGitManagerCommitParent[];
119
+ author: IGitManagerCommitActor;
120
+ committer: IGitManagerCommitActor;
121
+ stats: IGitManagerDiffStats;
122
+ }
123
+
124
+ export interface IGitManagerDiffRequest extends IGitManagerRepositorySelector {
125
+ headRef: string;
126
+ baseRef?: string;
127
+ path?: string;
128
+ contextLines?: number;
129
+ }
130
+
131
+ export interface IGitManagerDiffLine {
132
+ kind: TGitManagerDiffLineKind;
133
+ content: string;
134
+ oldNumber: number | null;
135
+ newNumber: number | null;
136
+ }
137
+
138
+ export interface IGitManagerDiffHunk {
139
+ header: string;
140
+ oldStart: number;
141
+ oldLines: number;
142
+ newStart: number;
143
+ newLines: number;
144
+ lines: IGitManagerDiffLine[];
145
+ }
146
+
147
+ export interface IGitManagerDiffFile {
148
+ oldPath: string;
149
+ newPath: string;
150
+ status: TGitManagerDiffFileStatus;
151
+ additions: number;
152
+ deletions: number;
153
+ isBinary: boolean;
154
+ hunks: IGitManagerDiffHunk[];
155
+ }
156
+
157
+ export interface IGitManagerDiff extends IGitManagerRepositorySelector, IGitManagerDiffStats {
158
+ baseRef: string;
159
+ headRef: string;
160
+ files: IGitManagerDiffFile[];
161
+ truncated: boolean;
162
+ }
163
+
164
+ export interface IGitManagerListTagsRequest extends IGitManagerRepositorySelector {
165
+ pattern?: string;
166
+ limit?: number;
167
+ }
168
+
169
+ export interface IGitManagerTagRequest extends IGitManagerRepositorySelector {
170
+ tag: string;
171
+ }
172
+
173
+ export interface IGitManagerTag extends IGitManagerRepositorySelector {
174
+ name: string;
175
+ objectId: string;
176
+ targetObjectId: string;
177
+ targetObjectType: TGitManagerObjectType;
178
+ isAnnotated: boolean;
179
+ taggerName: string;
180
+ taggerEmail: string;
181
+ taggedAt: string;
182
+ subject: string;
183
+ message: string;
184
+ }
package/ts/data/index.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export * from './codefeed.js';
2
2
  export * from './gitmanager.js';
3
3
  export * from './public.js';
4
+ export * from './runner.js';
package/ts/data/runner.ts ADDED
@@ -0,0 +1,225 @@
1
+ export const runnerProtocolVersion = '1' as const;
2
+
3
+ export type TRunnerProtocolVersion = typeof runnerProtocolVersion;
4
+ export type TOciRuntime = 'docker' | 'podman';
5
+ export type TJobNetwork = 'none' | 'bridge';
6
+ export type TLogStream = 'stdout' | 'stderr' | 'runner';
7
+ export type TJobCompletionStatus =
8
+ | 'succeeded'
9
+ | 'failed'
10
+ | 'canceled'
11
+ | 'timed_out'
12
+ | 'system_error';
13
+ export type TCiJobState = 'queued' | 'running' | TJobCompletionStatus;
14
+
15
+ export interface IRunnerCredential {
16
+ runnerId: string;
17
+ runnerToken: string;
18
+ runnerTokenExpiresAt: string;
19
+ }
20
+
21
+ export interface IRunnerCapabilities {
22
+ executor: 'oci';
23
+ runtime: TOciRuntime;
24
+ networks: TJobNetwork[];
25
+ sourceArchives: ['tar.gz'];
26
+ artifacts: false;
27
+ caches: false;
28
+ serviceContainers: false;
29
+ }
30
+
31
+ export interface IRegisterRunnerRequest {
32
+ registrationRequestId: string;
33
+ protocolVersion: string;
34
+ runnerVersion: string;
35
+ name: string;
36
+ labels: string[];
37
+ capabilities: IRunnerCapabilities;
38
+ }
39
+
40
+ export interface IRegisterRunnerResponse extends IRunnerCredential {
41
+ protocolVersion: string;
42
+ serverTime: string;
43
+ }
44
+
45
+ export interface IStartSessionRequest {
46
+ sessionRequestId: string;
47
+ runnerId: string;
48
+ protocolVersion: string;
49
+ runnerVersion: string;
50
+ capabilities: IRunnerCapabilities;
51
+ }
52
+
53
+ export interface IStartSessionResponse {
54
+ sessionId: string;
55
+ protocolVersion: string;
56
+ serverTime: string;
57
+ credential?: IRunnerCredential;
58
+ }
59
+
60
+ export interface IRunnerHeartbeatRequest {
61
+ runnerId: string;
62
+ sessionId: string;
63
+ }
64
+
65
+ export interface IRunnerHeartbeatResponse {
66
+ serverTime: string;
67
+ drainRequested: boolean;
68
+ credential?: IRunnerCredential;
69
+ }
70
+
71
+ export interface IJobResources {
72
+ memoryBytes?: number;
73
+ cpus?: number;
74
+ pids?: number;
75
+ }
76
+
77
+ export interface IJobSourceArchive {
78
+ format: 'tar.gz';
79
+ url: string;
80
+ sha256: string;
81
+ }
82
+
83
+ export interface IJobSpec {
84
+ image: string;
85
+ command: string[];
86
+ environment?: Record<string, string>;
87
+ secrets?: Record<string, string>;
88
+ network?: TJobNetwork;
89
+ timeoutMs?: number;
90
+ resources?: IJobResources;
91
+ source?: IJobSourceArchive;
92
+ }
93
+
94
+ export interface IJobLease {
95
+ jobId: string;
96
+ attemptId: string;
97
+ leaseId: string;
98
+ fencingToken: string;
99
+ leaseExpiresAt: string;
100
+ job: IJobSpec;
101
+ }
102
+
103
+ export interface IClaimJobRequest {
104
+ claimRequestId: string;
105
+ runnerId: string;
106
+ sessionId: string;
107
+ labels: string[];
108
+ }
109
+
110
+ export interface IClaimJobResponse {
111
+ serverTime: string;
112
+ retryAfterMs?: number;
113
+ lease: IJobLease | null;
114
+ }
115
+
116
+ export interface IJobMutationIdentity {
117
+ runnerId: string;
118
+ sessionId: string;
119
+ jobId: string;
120
+ attemptId: string;
121
+ leaseId: string;
122
+ fencingToken: string;
123
+ }
124
+
125
+ export interface IJobHeartbeatResponse {
126
+ serverTime: string;
127
+ leaseExpiresAt: string;
128
+ cancelRequested: boolean;
129
+ }
130
+
131
+ export interface ILogChunk extends IJobMutationIdentity {
132
+ sequence: number;
133
+ stream: TLogStream;
134
+ data: string;
135
+ timestamp: string;
136
+ }
137
+
138
+ export interface ILogAcknowledgement {
139
+ serverTime: string;
140
+ nextSequence: number;
141
+ }
142
+
143
+ export interface ICompleteJobRequest extends IJobMutationIdentity {
144
+ status: TJobCompletionStatus;
145
+ exitCode: number | null;
146
+ startedAt: string;
147
+ completedAt: string;
148
+ error?: string;
149
+ }
150
+
151
+ export interface ICompleteJobResponse {
152
+ serverTime: string;
153
+ accepted: boolean;
154
+ }
155
+
156
+ export interface IAbandonJobRequest extends IJobMutationIdentity {
157
+ reason: 'runner_shutdown' | 'runner_error';
158
+ }
159
+
160
+ export interface IRecoverAttemptRequest extends IJobMutationIdentity {
161
+ currentSessionId: string;
162
+ reason: 'runner_restarted';
163
+ }
164
+
165
+ export interface ICiEnqueueJobRequest {
166
+ idempotencyKey: string;
167
+ tenantId: string;
168
+ repositoryId: string;
169
+ requiredLabels: string[];
170
+ job: IJobSpec;
171
+ }
172
+
173
+ export interface ICiEnqueueJobResponse {
174
+ jobId: string;
175
+ state: TCiJobState;
176
+ createdAt: string;
177
+ duplicate: boolean;
178
+ }
179
+
180
+ export interface ICiJobSummary {
181
+ jobId: string;
182
+ tenantId: string;
183
+ repositoryId: string;
184
+ state: TCiJobState;
185
+ image: string;
186
+ requiredLabels: string[];
187
+ attemptNumber: number;
188
+ cancelRequested: boolean;
189
+ createdAt: string;
190
+ updatedAt: string;
191
+ startedAt?: string;
192
+ completedAt?: string;
193
+ completionStatus?: TJobCompletionStatus;
194
+ exitCode?: number | null;
195
+ error?: string;
196
+ }
197
+
198
+ export interface ICiLogEntry {
199
+ sequence: number;
200
+ stream: TLogStream;
201
+ data: string;
202
+ timestamp: string;
203
+ }
204
+
205
+ export interface ICiLogPage {
206
+ jobId: string;
207
+ attemptId: string;
208
+ entries: ICiLogEntry[];
209
+ nextSequence: number | null;
210
+ }
211
+
212
+ export interface ICiCancelJobResponse {
213
+ jobId: string;
214
+ state: TCiJobState;
215
+ cancelRequested: boolean;
216
+ }
217
+
218
+ export interface ICiSetRunnerDrainRequest {
219
+ drainRequested: boolean;
220
+ }
221
+
222
+ export interface ICiSetRunnerDrainResponse {
223
+ runnerId: string;
224
+ drainRequested: boolean;
225
+ }