The best way to control Claude Code, Codex and more from any computer or phone

main
ts 134 lines 4.26 KB
Raw
1 /**
2 * The `pulls` group: pull-request lifecycle + merge (DESIGN.md §5).
3 *
4 * PRs are same-repo branch PRs (no cross-fork), tracking **live** branches
5 * by ref name: diff and mergeability are computed on read from current ref
6 * tips. Merging fast-forwards when possible; otherwise it creates a merge
7 * commit iff the three-way tree merge is trivial (no path touched on both
8 * sides relative to the merge base) — a conflicting PR is a typed 409, the
9 * server never writes conflict markers.
10 */
11 import * as HttpApiEndpoint from "effect/http-api/HttpApiEndpoint";
12 import * as HttpApiGroup from "effect/http-api/HttpApiGroup";
13 import * as Schema from "effect/Schema";
14 import {
15 BranchMissing,
16 MergeConflict,
17 MergeResult,
18 NothingToMerge,
19 Oid,
20 OwnerName,
21 Paginated,
22 Pull,
23 PullDetail,
24 PullExists,
25 PullNotFound,
26 PullStateConflict,
27 ReadOnlyRepo,
28 RefConflict,
29 RepoName,
30 RepoNotFound,
31 RepoPath,
32 ValidationError,
33 PushDenied,
34 } from "./Schema.ts";
35
36 /** `(owner, repo, number)` path segments for single-PR endpoints. */
37 export const PullPath = Schema.Struct({
38 owner: OwnerName,
39 repo: RepoName,
40 /** The PR number (path segment; decoded from its string form). */
41 number: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
42 });
43
44 /**
45 * Opens a PR. `base`/`head` accept short (`main`) or full
46 * (`refs/heads/main`) branch names — only branches are legal (no tags).
47 */
48 export const CreatePull = HttpApiEndpoint.post("create", "/repos/:owner/:repo/pulls", {
49 params: RepoPath,
50 payload: Schema.Struct({
51 title: Schema.String.check(Schema.isMinLength(1)),
52 body: Schema.optional(Schema.String),
53 /** Target branch, short or full name. */
54 base: Schema.String,
55 /** Source branch, short or full name. Must differ from `base`. */
56 head: Schema.String,
57 }),
58 success: Pull,
59 error: [RepoNotFound, BranchMissing, PullExists, ValidationError],
60 });
61
62 /** Lists PRs, newest first. `state` defaults to `open`. Anonymous on public repos. */
63 export const ListPulls = HttpApiEndpoint.get("list", "/repos/:owner/:repo/pulls", {
64 params: RepoPath,
65 query: Schema.Struct({
66 /** Filter by lifecycle state. @default open */
67 state: Schema.optional(Schema.Literals(["open", "closed", "merged", "all"])),
68 cursor: Schema.optional(Schema.String),
69 limit: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 }))),
70 }),
71 success: Paginated(Pull),
72 error: [RepoNotFound],
73 });
74
75 /** Reads one PR with live compare fields (aheadBy/behindBy/mergeable). */
76 export const GetPull = HttpApiEndpoint.get("get", "/repos/:owner/:repo/pulls/:number", {
77 params: PullPath,
78 success: PullDetail,
79 error: [RepoNotFound, PullNotFound],
80 });
81
82 /** Patches title/body, or closes/reopens via `state`. */
83 export const UpdatePull = HttpApiEndpoint.patch("update", "/repos/:owner/:repo/pulls/:number", {
84 params: PullPath,
85 payload: Schema.Struct({
86 title: Schema.optional(Schema.String.check(Schema.isMinLength(1))),
87 /** `null` clears the body. */
88 body: Schema.String.pipe(Schema.NullOr, Schema.optional),
89 /**
90 * `closed` closes an open PR; `open` reopens a closed one. Merged
91 * PRs reject both (409).
92 */
93 state: Schema.optional(Schema.Literals(["open", "closed"])),
94 }),
95 success: Pull,
96 error: [RepoNotFound, PullNotFound, PullStateConflict],
97 });
98
99 /**
100 * Merges an open PR: fast-forward when possible, else a merge commit iff
101 * the three-way tree merge is trivial.
102 */
103 export const MergePull = HttpApiEndpoint.post("merge", "/repos/:owner/:repo/pulls/:number/merge", {
104 params: PullPath,
105 payload: Schema.Struct({
106 /**
107 * Merge-commit message; defaults to
108 * `Merge pull request #N from <head>`. Ignored on fast-forward.
109 */
110 message: Schema.optional(Schema.String),
111 /**
112 * Race guard: fail RefConflict if the head tip moved (force-push)
113 * since the caller inspected it.
114 */
115 expectedHeadOid: Schema.optional(Oid),
116 }),
117 success: MergeResult,
118 error: [
119 PushDenied,
120 RepoNotFound,
121 PullNotFound,
122 PullStateConflict,
123 BranchMissing,
124 NothingToMerge,
125 MergeConflict,
126 RefConflict,
127 ReadOnlyRepo,
128 ],
129 });
130
131 /** The `pulls` group, mounted at `/api/v1`. */
132 export class Pulls extends HttpApiGroup.make("pulls")
133 .add(CreatePull, ListPulls, GetPull, UpdatePull, MergePull)
134 .prefix("/api/v1") {}