@niwa-labs/forge 0.0.0-stage → 0.0.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.
- package/LICENSE +21 -0
- package/README.md +52 -2
- package/package.json +30 -4
- package/src/actions.ts +389 -0
- package/src/cockpit/actions.ts +94 -0
- package/src/cockpit/index.tsx +19 -0
- package/src/cockpit/page.tsx +158 -0
- package/src/cockpit/pulls.ts +103 -0
- package/src/flow.ts +232 -0
- package/src/gitlab.ts +263 -0
- package/src/index.ts +765 -0
- package/src/merge.ts +309 -0
- package/src/normalize.ts +186 -0
- package/src/observe.ts +464 -0
- package/src/prs.ts +122 -0
- package/src/queries.ts +152 -0
- package/src/record-types.ts +353 -0
- package/src/records.ts +8 -0
- package/src/secrets.ts +40 -0
- package/src/servers.ts +121 -0
- package/src/targets.ts +82 -0
- package/src/workflows/push-reaction.ts +59 -0
- package/test/actions.test.ts +235 -0
- package/test/cockpit-actions.test.ts +55 -0
- package/test/cockpit-pulls.test.ts +58 -0
- package/test/fake-gitlab.ts +452 -0
- package/test/flow.test.ts +239 -0
- package/test/gitlab.test.ts +91 -0
- package/test/merge.test.ts +251 -0
- package/test/observe.test.ts +454 -0
- package/test/prs.test.ts +125 -0
- package/test/push-reaction.test.ts +92 -0
- package/test/queries.test.ts +144 -0
- package/test/script-surface.test.ts +185 -0
- package/test/support.ts +109 -0
- package/test/targets.test.ts +42 -0
- package/tsconfig.json +15 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niwa Labs contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,53 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/forge
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A plugin for GitLab servers, in the words of pull requests: merge requests,
|
|
4
|
+
pipelines, jobs, checks and comments, observed as records and changed through
|
|
5
|
+
actions.
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { forge, secret } from "@niwa-labs/forge";
|
|
9
|
+
|
|
10
|
+
host.use(forge({ servers: [{ host: "gitlab.example.com", token: secret("GITLAB_TOKEN") }] }));
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The token is a secret reference. The host resolves it from
|
|
14
|
+
`<home>/secrets/GITLAB_TOKEN` (mode 0600) or `NIWA_SECRET_GITLAB_TOKEN`, and the
|
|
15
|
+
value never reaches the journal. `fetch` may be passed to speak to a fake server.
|
|
16
|
+
|
|
17
|
+
- Targets: `<host>/<path>` for reads, `<host>/<path>/pr/<n>` for pull request
|
|
18
|
+
writes and merges, `<host>/<path>/ref/<ref>` for pipelines and jobs. A run
|
|
19
|
+
fills a template such as `forge.pr.merge@{repo.host}/{repo.path}/pr/*`.
|
|
20
|
+
- `forge.pr.merge.started` and `forge.pr.merge.cancel.started` claim a pull request before the external write. Recovery reads GitLab to settle an interrupted operation. An inconclusive response keeps the claim open.
|
|
21
|
+
- `forge.pr.merge` is irreversible. A merge the server takes for later is
|
|
22
|
+
listed by `forge.pr.merge.pending`, with the action that calls it off; the
|
|
23
|
+
module checks it against the server whether or not the repository is watched,
|
|
24
|
+
and records the end as `forge.pr.merge.settled` when nobody watching saw it.
|
|
25
|
+
- `forge.pr.list` lists the pull requests the module observed (open ones first) with the checks of each head and
|
|
26
|
+
its latest pipelines; it reads what was recorded and asks the server nothing.
|
|
27
|
+
- `forge.repo.watch` records a repository; the module then polls it. Events of
|
|
28
|
+
the server's log are recorded under their event ids; changes of pull
|
|
29
|
+
requests, pipelines, jobs and checks as numbered observations with the state
|
|
30
|
+
before them. A transition of a pull request (opened, reopened, merged, closed)
|
|
31
|
+
is one record whether the log or a look at the server tells it first.
|
|
32
|
+
- `forge.repo.status` says, per watched repository since the host started, when
|
|
33
|
+
it was last polled, what the last poll failed with and whether the event log
|
|
34
|
+
was read back far enough.
|
|
35
|
+
- `/records`: record types, action references, target helpers and the query
|
|
36
|
+
builders of the records: `prHead(pr)`, `prMerged(pr)`, `prClosed(pr)`,
|
|
37
|
+
`prChecks(pr)`, `pipelineOf({ repo, sha, kind? })`, `pipelinesOfPr(pr)`,
|
|
38
|
+
`jobsOf({ repo, pipeline })`, `pushed(repo, ref?)` and the rest of the pull
|
|
39
|
+
request's records. A script waits for or reads them with the data typed
|
|
40
|
+
(`await wait(prMerged(pr), { timeout: "2h" })`,
|
|
41
|
+
`await read.records(pipelineOf({ repo, sha }))`), and a handler subscribes to
|
|
42
|
+
them. A pull request is `{ repo: { host, path }, number }`; a record's own
|
|
43
|
+
`pr` is accepted as it is.
|
|
44
|
+
- `/flow`: `untilPipeline`, `land`, `untilPrEnded` and `untilHeadMoved` for
|
|
45
|
+
workflow scripts, built on those queries. `land` with `auto`
|
|
46
|
+
reads the pull request between its waits, so a script that uses it lists
|
|
47
|
+
`forge.pr.read` on the repository next to `forge.pr.merge`.
|
|
48
|
+
- `pushReaction`: a built-in workflow that, on a push to a branch, names the
|
|
49
|
+
git worktrees made from it, found by the remote their base pushes to;
|
|
50
|
+
`checkouts` adds local clones the git module cannot verify.
|
|
51
|
+
|
|
52
|
+
`./cockpit` is the plugin's page: the watched repositories, the merges the server holds for later with a button that calls
|
|
53
|
+
each off, and the observed pull requests with the checks of their heads and their latest pipelines.
|
package/package.json
CHANGED
|
@@ -1,6 +1,32 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/forge",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts",
|
|
8
|
+
"./records": "./src/records.ts",
|
|
9
|
+
"./flow": "./src/flow.ts",
|
|
10
|
+
"./cockpit": "./src/cockpit/index.tsx"
|
|
11
|
+
},
|
|
12
|
+
"dependencies": {
|
|
13
|
+
"@niwa-labs/cockpit-sdk": "*",
|
|
14
|
+
"@niwa-labs/core": "*",
|
|
15
|
+
"@niwa-labs/plugin": "*",
|
|
16
|
+
"@niwa-labs/ui-kit": "*",
|
|
17
|
+
"zod": "^4.6.7"
|
|
18
|
+
},
|
|
19
|
+
"devDependencies": {
|
|
20
|
+
"@niwa-labs/testing": "*",
|
|
21
|
+
"@tanstack/react-query": "^5.108.2",
|
|
22
|
+
"@types/react": "^19.3.0",
|
|
23
|
+
"@types/react-dom": "^19.3.0",
|
|
24
|
+
"react": "^19.3.1",
|
|
25
|
+
"react-dom": "^19.3.1"
|
|
26
|
+
},
|
|
27
|
+
"peerDependencies": {
|
|
28
|
+
"@tanstack/react-query": "^5.108.2",
|
|
29
|
+
"react": "^19.3.1",
|
|
30
|
+
"react-dom": "^19.3.1"
|
|
31
|
+
}
|
|
32
|
+
}
|
package/src/actions.ts
ADDED
|
@@ -0,0 +1,389 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The actions of the forge module, as typed references with the targets their rules name.
|
|
3
|
+
*
|
|
4
|
+
* The module builds its real actions from the same references, so the schemas here are the ones
|
|
5
|
+
* the host checks against. Every action that touches a repository takes it as `repo: { host, path }`,
|
|
6
|
+
* which is what a target template fills: `forge.pr.merge@{repo.host}/{repo.path}/pr/*`.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { actionRef } from "@niwa-labs/core";
|
|
10
|
+
import { z } from "zod";
|
|
11
|
+
|
|
12
|
+
import { ChecksState, MergeMethod, MergeWhen, Pipeline, PipelineKind, PrRef, Repo, RunState, Sha } from "./record-types.ts";
|
|
13
|
+
import { RefName, RepoName, prTarget, refTarget, repoTarget } from "./targets.ts";
|
|
14
|
+
|
|
15
|
+
/** The name of a secret: letters, digits and underscores, as the host's secrets are named. */
|
|
16
|
+
export const SecretName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "a secret name is letters, digits and underscores");
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* A reference to a secret. The value is the owner's: the host resolves it where the call runs, from
|
|
20
|
+
* `<home>/secrets/<name>` (mode 0600) or the variable `NIWA_SECRET_<name>`, and it is never written down.
|
|
21
|
+
*/
|
|
22
|
+
export const SecretRef = z.strictObject({ secret: SecretName });
|
|
23
|
+
export type SecretRef = z.infer<typeof SecretRef>;
|
|
24
|
+
|
|
25
|
+
/** The reference to the secret called `name`. */
|
|
26
|
+
export function secret(name: string): SecretRef {
|
|
27
|
+
return SecretRef.parse({ secret: name });
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
const Number_ = z.number().int().positive();
|
|
31
|
+
|
|
32
|
+
/** A pull request as `forge.pr.read` answers it. */
|
|
33
|
+
export const PullRequest = z.strictObject({
|
|
34
|
+
pr: PrRef,
|
|
35
|
+
state: z.enum(["open", "merged", "closed", "locked"]),
|
|
36
|
+
title: z.string(),
|
|
37
|
+
branch: z.string().min(1),
|
|
38
|
+
base: z.string().min(1),
|
|
39
|
+
head: Sha,
|
|
40
|
+
/** Live target tip and latest MR-specific head and merged-result pipelines when requested. */
|
|
41
|
+
landing: z.strictObject({ targetSha: Sha, pipelines: z.array(Pipeline), conditionalMerge: z.boolean() }).optional(),
|
|
42
|
+
draft: z.boolean(),
|
|
43
|
+
author: z.string().optional(),
|
|
44
|
+
/** The commit the merge made, for a merged pull request. */
|
|
45
|
+
mergeSha: Sha.optional(),
|
|
46
|
+
/** A merge the server will make by itself when the pipeline succeeds. */
|
|
47
|
+
autoMerge: z.boolean(),
|
|
48
|
+
webUrl: z.string().optional(),
|
|
49
|
+
});
|
|
50
|
+
export type PullRequest = z.infer<typeof PullRequest>;
|
|
51
|
+
|
|
52
|
+
// --- Repositories -------------------------------------------------------------------------------
|
|
53
|
+
|
|
54
|
+
export const forgeRepoWatch = actionRef("forge.repo.watch", {
|
|
55
|
+
description:
|
|
56
|
+
"Watch a repository of a configured GitLab server: the module looks up its project, records it, and from then on " +
|
|
57
|
+
"polls it and records pushes, pull requests, pipelines, jobs and checks. Watching a watched repository changes nothing.",
|
|
58
|
+
input: z.strictObject({ repo: RepoName }),
|
|
59
|
+
output: Repo,
|
|
60
|
+
target: (input) => repoTarget(input.repo),
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
export const forgeRepoUnwatch = actionRef("forge.repo.unwatch", {
|
|
64
|
+
description: "Stop watching a repository. Its records stay. Unwatching a repository that is not watched changes nothing.",
|
|
65
|
+
input: z.strictObject({ repo: RepoName }),
|
|
66
|
+
output: z.strictObject({ unwatched: z.boolean() }),
|
|
67
|
+
target: (input) => repoTarget(input.repo),
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
export const forgeRepoList = actionRef("forge.repo.list", {
|
|
71
|
+
description: "The repositories the module watches.",
|
|
72
|
+
input: z.strictObject({}),
|
|
73
|
+
output: z.strictObject({ items: z.array(Repo) }),
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
export const forgeRepoSync = actionRef("forge.repo.sync", {
|
|
77
|
+
description:
|
|
78
|
+
"Poll a watched repository now, as the module does on its own timer, and record what changed: events of the server's " +
|
|
79
|
+
"event log, heads of pull requests, pipelines, jobs and checks. Answers how many records it wrote.",
|
|
80
|
+
input: z.strictObject({ repo: RepoName }),
|
|
81
|
+
output: z.strictObject({ written: z.number().int().nonnegative() }),
|
|
82
|
+
target: (input) => repoTarget(input.repo),
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
/** How the polls of one watched repository have gone since the host started. */
|
|
86
|
+
export const RepoStatus = z.strictObject({
|
|
87
|
+
repo: Repo,
|
|
88
|
+
/** When the last pass ended, in milliseconds since the epoch; absent before the first pass. */
|
|
89
|
+
lastPassAt: z.number().int().nonnegative().optional(),
|
|
90
|
+
/** When a pass last ended without an error: a pass that found nothing new counts. */
|
|
91
|
+
lastOkAt: z.number().int().nonnegative().optional(),
|
|
92
|
+
/** What the last pass failed with, while it did: a lost token, a spent limit, a server that is down. */
|
|
93
|
+
lastError: z.string().optional(),
|
|
94
|
+
/** True when the last pass could not read the event log back to the last event it had: older events were not seen. */
|
|
95
|
+
eventsMissed: z.boolean().optional(),
|
|
96
|
+
});
|
|
97
|
+
export type RepoStatus = z.infer<typeof RepoStatus>;
|
|
98
|
+
|
|
99
|
+
export const forgeRepoStatus = actionRef("forge.repo.status", {
|
|
100
|
+
description:
|
|
101
|
+
"How the polls of the watched repositories have gone since the host started: when the last pass ended, when one last " +
|
|
102
|
+
"ended without an error, what the last one failed with, and whether the event log was read back far enough. " +
|
|
103
|
+
"Silence from a repository means nothing happened there only while `lastError` is absent.",
|
|
104
|
+
input: z.strictObject({ repo: RepoName.optional() }),
|
|
105
|
+
output: z.strictObject({ items: z.array(RepoStatus) }),
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
// --- Reads --------------------------------------------------------------------------------------
|
|
109
|
+
|
|
110
|
+
export const forgePrRead = actionRef("forge.pr.read", {
|
|
111
|
+
description: "Read a pull request (a GitLab merge request) by its number: state, title, branches, head, draft, merge.",
|
|
112
|
+
input: z.strictObject({ repo: RepoName, number: Number_, landing: z.boolean().optional() }),
|
|
113
|
+
output: PullRequest,
|
|
114
|
+
target: (input) => repoTarget(input.repo),
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
/** A pull request as the module observed it: where it stands and the pipelines seen for it. */
|
|
118
|
+
export const PrState = z.enum(["open", "merged", "closed"]);
|
|
119
|
+
export type PrState = z.infer<typeof PrState>;
|
|
120
|
+
|
|
121
|
+
/** A pipeline of a pull request, in the state the module last saw it. */
|
|
122
|
+
export const PrPipeline = z.strictObject({
|
|
123
|
+
pipeline: Number_,
|
|
124
|
+
kind: PipelineKind,
|
|
125
|
+
state: RunState,
|
|
126
|
+
sourceSha: Sha,
|
|
127
|
+
targetSha: Sha.optional(),
|
|
128
|
+
mergeSha: Sha.optional(),
|
|
129
|
+
});
|
|
130
|
+
export type PrPipeline = z.infer<typeof PrPipeline>;
|
|
131
|
+
|
|
132
|
+
export const ObservedPr = z.strictObject({
|
|
133
|
+
pr: PrRef,
|
|
134
|
+
state: PrState,
|
|
135
|
+
title: z.string(),
|
|
136
|
+
branch: z.string().min(1),
|
|
137
|
+
base: z.string().min(1),
|
|
138
|
+
draft: z.boolean(),
|
|
139
|
+
author: z.string().optional(),
|
|
140
|
+
/** The head last seen; absent while no observation of it was written. */
|
|
141
|
+
head: Sha.optional(),
|
|
142
|
+
/** What the pipelines of the head say, as of the last check the module made. */
|
|
143
|
+
checks: ChecksState,
|
|
144
|
+
/** The latest pipelines of the pull request, newest first. */
|
|
145
|
+
pipelines: z.array(PrPipeline),
|
|
146
|
+
});
|
|
147
|
+
export type ObservedPr = z.infer<typeof ObservedPr>;
|
|
148
|
+
|
|
149
|
+
export const forgePrList = actionRef("forge.pr.list", {
|
|
150
|
+
description:
|
|
151
|
+
"List the pull requests the module observed in the repositories it watches, the open ones first and the latest changed first: " +
|
|
152
|
+
"title, branches, state, head, what the pipelines of the head say, and the latest pipelines of each. It reads what was recorded " +
|
|
153
|
+
"and asks the server nothing; `forge.pr.read` asks the server. `repo` keeps one repository, `state` those in one state.",
|
|
154
|
+
input: z.strictObject({ repo: RepoName.optional(), state: PrState.optional() }),
|
|
155
|
+
output: z.strictObject({ items: z.array(ObservedPr) }),
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
export const forgeChecksRead = actionRef("forge.checks.read", {
|
|
159
|
+
description:
|
|
160
|
+
"What the pipelines of the head of a pull request say: none, pending, green or red, from its latest pipeline on that head.",
|
|
161
|
+
input: z.strictObject({ repo: RepoName, number: Number_ }),
|
|
162
|
+
output: z.strictObject({ pr: PrRef, head: Sha, state: ChecksState, pipeline: Number_.optional() }),
|
|
163
|
+
target: (input) => repoTarget(input.repo),
|
|
164
|
+
});
|
|
165
|
+
|
|
166
|
+
export const forgePipelineRead = actionRef("forge.pipeline.read", {
|
|
167
|
+
description:
|
|
168
|
+
"Read pipelines: one by its number, or the pipelines that ran on a commit, newest first, optionally of one kind " +
|
|
169
|
+
"(head, merge-result, train, branch, tag, schedule). A merge result carries the pair of commits it was made of.",
|
|
170
|
+
input: z.strictObject({
|
|
171
|
+
repo: RepoName,
|
|
172
|
+
pipeline: Number_.optional(),
|
|
173
|
+
sha: Sha.optional(),
|
|
174
|
+
kind: PipelineKind.optional(),
|
|
175
|
+
}),
|
|
176
|
+
output: z.strictObject({ items: z.array(Pipeline) }),
|
|
177
|
+
target: (input) => repoTarget(input.repo),
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
const Job = z.strictObject({
|
|
181
|
+
job: Number_,
|
|
182
|
+
pipeline: Number_,
|
|
183
|
+
name: z.string(),
|
|
184
|
+
stage: z.string(),
|
|
185
|
+
ref: z.string(),
|
|
186
|
+
state: RunState,
|
|
187
|
+
manual: z.boolean(),
|
|
188
|
+
});
|
|
189
|
+
|
|
190
|
+
export const forgeJobRead = actionRef("forge.job.read", {
|
|
191
|
+
description: "Read the jobs of a pipeline, or one job by its number.",
|
|
192
|
+
input: z.strictObject({ repo: RepoName, pipeline: Number_.optional(), job: Number_.optional() }),
|
|
193
|
+
output: z.strictObject({ items: z.array(Job) }),
|
|
194
|
+
target: (input) => repoTarget(input.repo),
|
|
195
|
+
});
|
|
196
|
+
|
|
197
|
+
export const forgeJobLog = actionRef("forge.job.log", {
|
|
198
|
+
description: "Read the end of the log of a job, at most `bytes` of it (default and most: 64 KiB). The text is the step's outcome.",
|
|
199
|
+
input: z.strictObject({ repo: RepoName, job: Number_, bytes: z.number().int().min(1).max(65_536).optional() }),
|
|
200
|
+
output: z.strictObject({ job: Number_, log: z.string(), size: z.number().int().nonnegative(), truncated: z.boolean() }),
|
|
201
|
+
target: (input) => repoTarget(input.repo),
|
|
202
|
+
});
|
|
203
|
+
|
|
204
|
+
const Comment = z.strictObject({
|
|
205
|
+
comment: Number_,
|
|
206
|
+
discussion: z.string(),
|
|
207
|
+
author: z.string(),
|
|
208
|
+
body: z.string(),
|
|
209
|
+
resolvable: z.boolean(),
|
|
210
|
+
resolved: z.boolean(),
|
|
211
|
+
system: z.boolean(),
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
export const forgeCommentRead = actionRef("forge.comment.read", {
|
|
215
|
+
description: "Read the comments of a pull request with their text, grouped by the discussion each belongs to.",
|
|
216
|
+
input: z.strictObject({ repo: RepoName, number: Number_ }),
|
|
217
|
+
output: z.strictObject({ items: z.array(Comment) }),
|
|
218
|
+
target: (input) => repoTarget(input.repo),
|
|
219
|
+
});
|
|
220
|
+
|
|
221
|
+
// --- Writes on a pull request -------------------------------------------------------------------
|
|
222
|
+
|
|
223
|
+
export const forgePrEnsure = actionRef("forge.pr.ensure", {
|
|
224
|
+
description:
|
|
225
|
+
"Make sure a pull request from `branch` into `base` is open, with this title and description: an open one of the branch " +
|
|
226
|
+
"is updated, else one is opened. With `number`, that pull request is updated, and reopened if it is closed; one that is " +
|
|
227
|
+
"merged or locked is refused. Its target is the pull request named by `number`, or `pr/new` without one.",
|
|
228
|
+
input: z.strictObject({
|
|
229
|
+
repo: RepoName,
|
|
230
|
+
number: Number_.optional(),
|
|
231
|
+
branch: RefName,
|
|
232
|
+
base: RefName,
|
|
233
|
+
title: z.string().min(1),
|
|
234
|
+
description: z.string().optional(),
|
|
235
|
+
draft: z.boolean().optional(),
|
|
236
|
+
}),
|
|
237
|
+
output: z.strictObject({ pr: PrRef, created: z.boolean(), head: Sha }),
|
|
238
|
+
target: (input) => prTarget(input.repo, input.number ?? "new"),
|
|
239
|
+
});
|
|
240
|
+
|
|
241
|
+
export const forgePrRetarget = actionRef("forge.pr.retarget", {
|
|
242
|
+
description: "Change the branch a pull request is to be merged into.",
|
|
243
|
+
input: z.strictObject({ repo: RepoName, number: Number_, base: RefName }),
|
|
244
|
+
output: z.strictObject({ pr: PrRef, base: z.string() }),
|
|
245
|
+
target: (input) => prTarget(input.repo, input.number),
|
|
246
|
+
});
|
|
247
|
+
|
|
248
|
+
export const forgePrClose = actionRef("forge.pr.close", {
|
|
249
|
+
description: "Close a pull request without merging it. Closing a closed one changes nothing.",
|
|
250
|
+
input: z.strictObject({ repo: RepoName, number: Number_ }),
|
|
251
|
+
output: z.strictObject({ pr: PrRef, closed: z.boolean() }),
|
|
252
|
+
target: (input) => prTarget(input.repo, input.number),
|
|
253
|
+
});
|
|
254
|
+
|
|
255
|
+
export const forgeCommentCreate = actionRef("forge.comment.create", {
|
|
256
|
+
description: "Comment on a pull request. Two calls make two comments.",
|
|
257
|
+
input: z.strictObject({ repo: RepoName, number: Number_, body: z.string().min(1) }),
|
|
258
|
+
output: z.strictObject({ comment: Number_, discussion: z.string() }),
|
|
259
|
+
target: (input) => prTarget(input.repo, input.number),
|
|
260
|
+
});
|
|
261
|
+
|
|
262
|
+
export const forgeCommentReply = actionRef("forge.comment.reply", {
|
|
263
|
+
description: "Reply in a discussion of a pull request. Two calls make two replies.",
|
|
264
|
+
input: z.strictObject({ repo: RepoName, number: Number_, discussion: z.string().min(1), body: z.string().min(1) }),
|
|
265
|
+
output: z.strictObject({ comment: Number_, discussion: z.string() }),
|
|
266
|
+
target: (input) => prTarget(input.repo, input.number),
|
|
267
|
+
});
|
|
268
|
+
|
|
269
|
+
export const forgeCommentResolve = actionRef("forge.comment.resolve", {
|
|
270
|
+
description: "Resolve a discussion of a pull request, or reopen it with `resolved: false`.",
|
|
271
|
+
input: z.strictObject({ repo: RepoName, number: Number_, discussion: z.string().min(1), resolved: z.boolean().optional() }),
|
|
272
|
+
output: z.strictObject({ discussion: z.string(), resolved: z.boolean() }),
|
|
273
|
+
target: (input) => prTarget(input.repo, input.number),
|
|
274
|
+
});
|
|
275
|
+
|
|
276
|
+
/** How a merge went: merged now, taken by a merge train, armed to merge when the pipeline succeeds, or refused. */
|
|
277
|
+
export const MergeOutcome = z.discriminatedUnion("outcome", [
|
|
278
|
+
z.strictObject({ outcome: z.literal("merged"), sha: Sha, externalId: z.string() }),
|
|
279
|
+
z.strictObject({ outcome: z.literal("queued"), externalId: z.string(), cancel: z.string() }),
|
|
280
|
+
z.strictObject({ outcome: z.literal("armed"), externalId: z.string(), cancel: z.string() }),
|
|
281
|
+
z.strictObject({ outcome: z.literal("refused"), why: z.string() }),
|
|
282
|
+
]);
|
|
283
|
+
export type MergeOutcome = z.infer<typeof MergeOutcome>;
|
|
284
|
+
|
|
285
|
+
export const forgePrMerge = actionRef("forge.pr.merge", {
|
|
286
|
+
description:
|
|
287
|
+
"Merge a pull request, only if its head is still `expectHead`. `method: squash` squashes its commits; `merge` and `rebase` " +
|
|
288
|
+
"land them by the project's own merge method. `when: now` merges at once; `pipeline` arms the server to merge " +
|
|
289
|
+
"when the pipeline succeeds; `train` puts it in the merge train. Answers merged (with the commit), armed or queued (with the " +
|
|
290
|
+
"server's id and the action that calls it off), or refused with the server's reason, such as a head that moved. " +
|
|
291
|
+
"Irreversible and external: a grant names it.",
|
|
292
|
+
input: z.strictObject({
|
|
293
|
+
repo: RepoName,
|
|
294
|
+
number: Number_,
|
|
295
|
+
expectHead: Sha,
|
|
296
|
+
/** Refuse unless the server can atomically compare the target SHA too. */
|
|
297
|
+
expectTarget: Sha.optional(),
|
|
298
|
+
method: MergeMethod,
|
|
299
|
+
when: MergeWhen.optional(),
|
|
300
|
+
}),
|
|
301
|
+
output: MergeOutcome,
|
|
302
|
+
target: (input) => prTarget(input.repo, input.number),
|
|
303
|
+
});
|
|
304
|
+
|
|
305
|
+
export const forgePrMergeCancel = actionRef("forge.pr.merge.cancel", {
|
|
306
|
+
description:
|
|
307
|
+
"Call off a merge the server took for later: the automatic merge when the pipeline succeeds, or the place in the merge train.",
|
|
308
|
+
input: z.strictObject({ repo: RepoName, number: Number_ }),
|
|
309
|
+
output: z.strictObject({ cancelled: z.boolean() }),
|
|
310
|
+
target: (input) => prTarget(input.repo, input.number),
|
|
311
|
+
});
|
|
312
|
+
|
|
313
|
+
/** A merge the server took and has not made or dropped yet, as niwa recorded it. */
|
|
314
|
+
export const PendingMerge = z.strictObject({
|
|
315
|
+
pr: PrRef,
|
|
316
|
+
mode: z.enum(["auto-merge", "train"]),
|
|
317
|
+
externalId: z.string(),
|
|
318
|
+
expectHead: Sha,
|
|
319
|
+
/** The action that calls it off, and its input. */
|
|
320
|
+
cancel: z.strictObject({ action: z.string(), input: z.strictObject({ repo: RepoName, number: Number_ }) }),
|
|
321
|
+
});
|
|
322
|
+
export type PendingMerge = z.infer<typeof PendingMerge>;
|
|
323
|
+
|
|
324
|
+
export const forgePrMergePending = actionRef("forge.pr.merge.pending", {
|
|
325
|
+
description:
|
|
326
|
+
"The merges the server took for later and has not made yet, each with its external id and the action that calls it off. " +
|
|
327
|
+
"A hold of niwa cannot stop them: the server has them.",
|
|
328
|
+
input: z.strictObject({}),
|
|
329
|
+
output: z.strictObject({ items: z.array(PendingMerge) }),
|
|
330
|
+
});
|
|
331
|
+
|
|
332
|
+
// --- Pipelines and jobs -------------------------------------------------------------------------
|
|
333
|
+
|
|
334
|
+
/** A variable of a pipeline: text, or a secret the host resolves when the call runs. */
|
|
335
|
+
export const PipelineVariable = z.union([z.string(), SecretRef]);
|
|
336
|
+
|
|
337
|
+
export const forgePipelineTrigger = actionRef("forge.pipeline.trigger", {
|
|
338
|
+
description:
|
|
339
|
+
"Run a new pipeline on a branch or a tag. `variables` are text or a secret reference, `secret(\"name\")`, resolved by the host " +
|
|
340
|
+
"and never written down. A pipeline may publish, so this is irreversible: a grant names it.",
|
|
341
|
+
input: z.strictObject({ repo: RepoName, ref: RefName, variables: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), PipelineVariable).optional() }),
|
|
342
|
+
output: z.strictObject({ pipeline: Number_, ref: z.string(), sha: Sha, state: RunState }),
|
|
343
|
+
target: (input) => refTarget(input.repo, input.ref),
|
|
344
|
+
});
|
|
345
|
+
|
|
346
|
+
const OnRef = { repo: RepoName, ref: RefName };
|
|
347
|
+
|
|
348
|
+
export const forgePipelineRetry = actionRef("forge.pipeline.retry", {
|
|
349
|
+
description: "Retry the failed jobs of a pipeline. `ref` is the branch or tag it ran on; a pipeline of another ref is refused.",
|
|
350
|
+
input: z.strictObject({ ...OnRef, pipeline: Number_ }),
|
|
351
|
+
output: z.strictObject({ pipeline: Number_, state: RunState }),
|
|
352
|
+
target: (input) => refTarget(input.repo, input.ref),
|
|
353
|
+
});
|
|
354
|
+
|
|
355
|
+
export const forgePipelineCancel = actionRef("forge.pipeline.cancel", {
|
|
356
|
+
description: "Cancel the running jobs of a pipeline. `ref` is the branch or tag it ran on; a pipeline of another ref is refused.",
|
|
357
|
+
input: z.strictObject({ ...OnRef, pipeline: Number_ }),
|
|
358
|
+
output: z.strictObject({ pipeline: Number_, state: RunState }),
|
|
359
|
+
target: (input) => refTarget(input.repo, input.ref),
|
|
360
|
+
});
|
|
361
|
+
|
|
362
|
+
export const forgeJobRetry = actionRef("forge.job.retry", {
|
|
363
|
+
description: "Run a job again, as a new job. `ref` is the branch or tag it ran on; a job of another ref is refused.",
|
|
364
|
+
input: z.strictObject({ ...OnRef, job: Number_ }),
|
|
365
|
+
output: z.strictObject({ job: Number_, state: RunState }),
|
|
366
|
+
target: (input) => refTarget(input.repo, input.ref),
|
|
367
|
+
});
|
|
368
|
+
|
|
369
|
+
export const forgeJobCancel = actionRef("forge.job.cancel", {
|
|
370
|
+
description: "Cancel a job. `ref` is the branch or tag it ran on; a job of another ref is refused.",
|
|
371
|
+
input: z.strictObject({ ...OnRef, job: Number_ }),
|
|
372
|
+
output: z.strictObject({ job: Number_, state: RunState }),
|
|
373
|
+
target: (input) => refTarget(input.repo, input.ref),
|
|
374
|
+
});
|
|
375
|
+
|
|
376
|
+
export const forgeJobRun = actionRef("forge.job.run", {
|
|
377
|
+
description: "Start a manual job. `ref` is the branch or tag it belongs to; a job of another ref is refused.",
|
|
378
|
+
input: z.strictObject({ ...OnRef, job: Number_ }),
|
|
379
|
+
output: z.strictObject({ job: Number_, state: RunState }),
|
|
380
|
+
target: (input) => refTarget(input.repo, input.ref),
|
|
381
|
+
});
|
|
382
|
+
|
|
383
|
+
// --- The push reaction ---------------------------------------------------------------------------
|
|
384
|
+
|
|
385
|
+
export const forgePushConfig = actionRef("forge.push.config", {
|
|
386
|
+
description: "The local checkouts the owner names for each watched repository, `<host>/<path>` to absolute paths, as the push reaction reads them.",
|
|
387
|
+
input: z.strictObject({}),
|
|
388
|
+
output: z.strictObject({ checkouts: z.record(z.string(), z.array(z.string())) }),
|
|
389
|
+
});
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The forge actions as the cockpit calls them: name and the part of each schema the page reads.
|
|
3
|
+
*
|
|
4
|
+
* The module runs in the browser and cannot import the host-side schemas, which reach for Node. A field the host
|
|
5
|
+
* stopped sending fails the page that reads it, which `test/cockpit-actions.test.ts` checks against the real actions.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { z } from "zod";
|
|
9
|
+
|
|
10
|
+
/** A repository as the host names it: the server and the path of the project. */
|
|
11
|
+
export const Repo = z.object({ host: z.string(), path: z.string(), projectId: z.number() });
|
|
12
|
+
export type Repo = z.infer<typeof Repo>;
|
|
13
|
+
|
|
14
|
+
/** A repository as an action takes it. */
|
|
15
|
+
export const RepoName = z.object({ host: z.string(), path: z.string() });
|
|
16
|
+
export type RepoName = z.infer<typeof RepoName>;
|
|
17
|
+
|
|
18
|
+
export const PrRef = z.object({ repo: Repo, number: z.number() });
|
|
19
|
+
export type PrRef = z.infer<typeof PrRef>;
|
|
20
|
+
|
|
21
|
+
export const repoListAction = {
|
|
22
|
+
name: "forge.repo.list",
|
|
23
|
+
input: z.object({}),
|
|
24
|
+
output: z.object({ items: z.array(Repo) }),
|
|
25
|
+
} as const;
|
|
26
|
+
|
|
27
|
+
export const repoSyncAction = {
|
|
28
|
+
name: "forge.repo.sync",
|
|
29
|
+
input: z.object({ repo: RepoName }),
|
|
30
|
+
output: z.object({ written: z.number() }),
|
|
31
|
+
} as const;
|
|
32
|
+
|
|
33
|
+
export const PrState = z.enum(["open", "merged", "closed"]);
|
|
34
|
+
export type PrState = z.infer<typeof PrState>;
|
|
35
|
+
|
|
36
|
+
export const ChecksState = z.enum(["none", "pending", "green", "red"]);
|
|
37
|
+
export type ChecksState = z.infer<typeof ChecksState>;
|
|
38
|
+
|
|
39
|
+
export const PipelineKind = z.enum(["head", "merge-result", "train", "branch", "tag", "schedule"]);
|
|
40
|
+
export type PipelineKind = z.infer<typeof PipelineKind>;
|
|
41
|
+
|
|
42
|
+
export const RunState = z.enum(["created", "waiting_for_resource", "preparing", "pending", "running", "success", "failed", "canceled", "skipped", "manual", "scheduled"]);
|
|
43
|
+
export type RunState = z.infer<typeof RunState>;
|
|
44
|
+
|
|
45
|
+
export const PrPipeline = z.object({
|
|
46
|
+
pipeline: z.number(),
|
|
47
|
+
kind: PipelineKind,
|
|
48
|
+
state: RunState,
|
|
49
|
+
sourceSha: z.string(),
|
|
50
|
+
targetSha: z.string().optional(),
|
|
51
|
+
mergeSha: z.string().optional(),
|
|
52
|
+
});
|
|
53
|
+
export type PrPipeline = z.infer<typeof PrPipeline>;
|
|
54
|
+
|
|
55
|
+
export const ObservedPr = z.object({
|
|
56
|
+
pr: PrRef,
|
|
57
|
+
state: PrState,
|
|
58
|
+
title: z.string(),
|
|
59
|
+
branch: z.string(),
|
|
60
|
+
base: z.string(),
|
|
61
|
+
draft: z.boolean(),
|
|
62
|
+
author: z.string().optional(),
|
|
63
|
+
head: z.string().optional(),
|
|
64
|
+
checks: ChecksState,
|
|
65
|
+
pipelines: z.array(PrPipeline),
|
|
66
|
+
});
|
|
67
|
+
export type ObservedPr = z.infer<typeof ObservedPr>;
|
|
68
|
+
|
|
69
|
+
export const prListAction = {
|
|
70
|
+
name: "forge.pr.list",
|
|
71
|
+
input: z.object({ repo: RepoName.optional(), state: PrState.optional() }),
|
|
72
|
+
output: z.object({ items: z.array(ObservedPr) }),
|
|
73
|
+
} as const;
|
|
74
|
+
|
|
75
|
+
export const PendingMerge = z.object({
|
|
76
|
+
pr: PrRef,
|
|
77
|
+
mode: z.enum(["auto-merge", "train"]),
|
|
78
|
+
externalId: z.string(),
|
|
79
|
+
expectHead: z.string(),
|
|
80
|
+
cancel: z.object({ action: z.string(), input: z.object({ repo: RepoName, number: z.number() }) }),
|
|
81
|
+
});
|
|
82
|
+
export type PendingMerge = z.infer<typeof PendingMerge>;
|
|
83
|
+
|
|
84
|
+
export const pendingAction = {
|
|
85
|
+
name: "forge.pr.merge.pending",
|
|
86
|
+
input: z.object({}),
|
|
87
|
+
output: z.object({ items: z.array(PendingMerge) }),
|
|
88
|
+
} as const;
|
|
89
|
+
|
|
90
|
+
export const cancelMergeAction = {
|
|
91
|
+
name: "forge.pr.merge.cancel",
|
|
92
|
+
input: z.object({ repo: RepoName, number: z.number() }),
|
|
93
|
+
output: z.object({ cancelled: z.boolean() }),
|
|
94
|
+
} as const;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** The cockpit module of the forge plugin: watched repositories, pull requests with their pipelines, and armed merges. */
|
|
2
|
+
|
|
3
|
+
import { definePlugin } from "@niwa-labs/cockpit-sdk";
|
|
4
|
+
|
|
5
|
+
import { ForgePage } from "./page.tsx";
|
|
6
|
+
|
|
7
|
+
export default definePlugin({
|
|
8
|
+
id: "forge",
|
|
9
|
+
setup(ctx) {
|
|
10
|
+
ctx.pages.add({
|
|
11
|
+
path: "/forge",
|
|
12
|
+
title: "Запросы на слияние",
|
|
13
|
+
commandHeading: true,
|
|
14
|
+
nav: { order: 60 },
|
|
15
|
+
commands: [{ action: "forge.repo.watch", label: "Подключить репозиторий" }],
|
|
16
|
+
component: ForgePage,
|
|
17
|
+
});
|
|
18
|
+
},
|
|
19
|
+
});
|