sailfork 0.3.6 → 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.
@@ -596,6 +596,63 @@ export type CommentProof = {
596
596
  /** Sailfork ran it itself. */
597
597
  verified: boolean;
598
598
  };
599
+ /** A repository's history, or a path's, newest first. */
600
+ export type CommitLog = CommitRecord[] | CommitPage;
601
+ export type CommitPage = {
602
+ commits: CommitRecord[];
603
+ /** Set when a path's history stopped at the search's step limit: pass it as `cursor` for the commits after these. `null` when the list is whole. */
604
+ cursor: string | null;
605
+ };
606
+ /** A commit as the explorer API sends it: `Commit` plus the author's address. */
607
+ export type CommitRecord = {
608
+ added: number;
609
+ at: string;
610
+ author: string;
611
+ email: string;
612
+ files: number;
613
+ /** In a path's history, where the file was named in this commit. */
614
+ path?: string | null;
615
+ removed: number;
616
+ sha: string;
617
+ short: string;
618
+ subject: string;
619
+ };
620
+ /** What `commit view --json` prints: the server's answer for `GET commits/{sha}`, passed through whole. */
621
+ export type CommitView = {
622
+ body: string;
623
+ child: CommitRecord | null;
624
+ commit: CommitRecord;
625
+ /** The first files in path order; `filesTotal` counts every file the commit changed. */
626
+ files: FileDiff[];
627
+ filesTotal: number;
628
+ parent: CommitRecord | null;
629
+ };
630
+ /** What a comparison answers: the whole diff, or with `from` and `count` one page of its files. */
631
+ export type CompareAnswer = CompareView | CompareFiles;
632
+ /** One page of a comparison's files with their hunks. */
633
+ export type CompareFiles = {
634
+ files: FileDiff[];
635
+ /** The index of the first file in the page. */
636
+ from: number;
637
+ };
638
+ /** `head` against `base`: the commits `head` adds since their merge base and the files it changes. */
639
+ export type CompareView = {
640
+ /** Commits on `head` that `base` lacks. */
641
+ ahead: number;
642
+ /** With `lines`: the two commits compared, which `from` and `count` pages name so every page reads the same diff after a branch moves. */
643
+ base: string | null;
644
+ /** Commits on `base` that `head` lacks. */
645
+ behind: number;
646
+ /** The newest `ahead` commits, newest first. */
647
+ commits: CommitRecord[];
648
+ /** The merge base's tree against `head`'s: the first files in path order. With `lines`, only the leading files carry hunks. */
649
+ files: FileDiff[];
650
+ /** Every file the comparison changes; `files` lists the first of them. */
651
+ filesTotal: number;
652
+ head: string | null;
653
+ /** The commit `files` diff from; absent for unrelated histories, where every file is new. */
654
+ mergeBase: string | null;
655
+ };
599
656
  export type ConflictFile = {
600
657
  /** `None` where the base branch does not have the path. */
601
658
  base: ConflictSide | null;
@@ -658,7 +715,22 @@ export type DeletionScheduled = {
658
715
  blockers: string[];
659
716
  deletionAt: string;
660
717
  };
718
+ export type DiffHunk = {
719
+ header: string;
720
+ lines: DiffLine[];
721
+ };
722
+ export type DiffLine = {
723
+ kind: string;
724
+ new: number | null;
725
+ old: number | null;
726
+ text: string;
727
+ };
661
728
  export type DiffSide = 'old' | 'new';
729
+ export type DiffTotals = {
730
+ added: number;
731
+ files: number;
732
+ removed: number;
733
+ };
662
734
  export type EnvChain = {
663
735
  /** Whether the caller may append entries: an org owner, or the owner of a personal repository. */
664
736
  admin: boolean;
@@ -838,6 +910,16 @@ export type FailedStep = {
838
910
  stepName?: string | null;
839
911
  tail: string[];
840
912
  };
913
+ export type FileDiff = {
914
+ added: number;
915
+ binary: boolean;
916
+ from: string | null;
917
+ hunks: DiffHunk[];
918
+ path: string;
919
+ removed: number;
920
+ status: string;
921
+ truncated: boolean;
922
+ };
841
923
  export type FileHit = {
842
924
  language: string;
843
925
  matchCount: number;
@@ -1433,6 +1515,27 @@ export type PullDetail = {
1433
1515
  /** REST only: the pull request's page. */
1434
1516
  url?: string | null;
1435
1517
  };
1518
+ /** A pull request's diff: an open one's branch against its base as they stand, a merged one's from the merge base and branch tip recorded when it merged. */
1519
+ export type PullDiff = {
1520
+ /** Commits on `head` that `base` lacks. */
1521
+ ahead: number;
1522
+ /** With `lines`: the two commits compared, which `from` and `count` pages name so every page reads the same diff after a branch moves. */
1523
+ base: string | null;
1524
+ /** Commits on `base` that `head` lacks. */
1525
+ behind: number;
1526
+ /** The newest `ahead` commits, newest first. */
1527
+ commits: CommitRecord[];
1528
+ /** The merge base's tree against `head`'s: the first files in path order. With `lines`, only the leading files carry hunks. */
1529
+ files: FileDiff[];
1530
+ /** Every file the comparison changes; `files` lists the first of them. */
1531
+ filesTotal: number;
1532
+ head: string | null;
1533
+ /** The commit `files` diff from; absent for unrelated histories, where every file is new. */
1534
+ mergeBase: string | null;
1535
+ merged: boolean;
1536
+ /** Totals over every file, `files` counting them all. */
1537
+ stats: DiffTotals;
1538
+ };
1436
1539
  export type PullFile = {
1437
1540
  from: string | null;
1438
1541
  hunks: PullHunk[];
@@ -1443,6 +1546,10 @@ export type PullHunk = {
1443
1546
  header: string;
1444
1547
  lines: PullLine[];
1445
1548
  };
1549
+ /** `{ items }`, from `GET pulls/touching` and `GET commit/{sha}/pulls`. */
1550
+ export type PullItems = {
1551
+ items: Pull[];
1552
+ };
1446
1553
  export type PullLine = {
1447
1554
  kind: string;
1448
1555
  new: number | null;
@@ -2184,6 +2291,8 @@ export type TotpSetup = {
2184
2291
  /** The base32 secret, for typing in by hand. */
2185
2292
  secret: string;
2186
2293
  };
2294
+ /** Which pull requests `pulls.touching` searches. */
2295
+ export type TouchingState = 'all' | 'open' | 'merged';
2187
2296
  /** What a review says about the pull request. */
2188
2297
  export type Verdict = 'approve' | 'changes' | 'comment';
2189
2298
  /** Who may read a repository. */
@@ -3967,6 +4076,20 @@ export type PullsAutoMergeEnableInput = {
3967
4076
  stack?: boolean | null;
3968
4077
  };
3969
4078
  export type PullsAutoMergeEnableOutput = AutoMerge;
4079
+ /**
4080
+ * Show the diff of the pull request from a branch: the open one, else the newest closed or merged one.
4081
+ */
4082
+ export type PullsBranchDiffInput = {
4083
+ /** The pull request's head branch. */
4084
+ branch: string;
4085
+ /** Hunks for the leading files only, up to about this many diff lines. */
4086
+ lines?: number | null;
4087
+ /** The repository owner's handle. */
4088
+ owner: string;
4089
+ /** The repository's name. */
4090
+ repo: string;
4091
+ };
4092
+ export type PullsBranchDiffOutput = PullDiff;
3970
4093
  /**
3971
4094
  * Show what a pull request's checks add up to: the CI jobs of the newest run of each workflow on its head, then the latest check run of each name and reporter. `waited` lets the verdict tell a first run that has not started from one that never will.
3972
4095
  */
@@ -4063,6 +4186,20 @@ export type PullsDeleteCommentInput = {
4063
4186
  thread: string;
4064
4187
  };
4065
4188
  export type PullsDeleteCommentOutput = NoContent;
4189
+ /**
4190
+ * Show what a pull request changes: the commits it adds and its diff against the merge base, with totals. A merged one answers the diff it merged. A signed-out visitor sees a public repository's.
4191
+ */
4192
+ export type PullsDiffInput = {
4193
+ /** Hunks for the leading files only, up to about this many diff lines; the answer then names `base` and `head` for `repos.compare` pages of the rest. */
4194
+ lines?: number | null;
4195
+ /** Pull request number. */
4196
+ number: number;
4197
+ /** The repository owner's handle. */
4198
+ owner: string;
4199
+ /** The repository's name. */
4200
+ repo: string;
4201
+ };
4202
+ export type PullsDiffOutput = PullDiff;
4066
4203
  /**
4067
4204
  * Dismiss the reviews that approved or asked for changes on a pull request.
4068
4205
  */
@@ -4095,6 +4232,18 @@ export type PullsEditCommentInput = {
4095
4232
  thread: string;
4096
4233
  };
4097
4234
  export type PullsEditCommentOutput = PullThread;
4235
+ /**
4236
+ * List the pull requests whose commits include a commit, among the newest few hundred of any state.
4237
+ */
4238
+ export type PullsForCommitInput = {
4239
+ /** The repository owner's handle. */
4240
+ owner: string;
4241
+ /** The repository's name. */
4242
+ repo: string;
4243
+ /** Commit sha (or its start), branch or tag. */
4244
+ sha: string;
4245
+ };
4246
+ export type PullsForCommitOutput = PullItems;
4098
4247
  /**
4099
4248
  * Show a pull request with its threads, whether it merges cleanly and the merge rules it does not meet yet.
4100
4249
  */
@@ -4237,6 +4386,21 @@ export type PullsStackInput = {
4237
4386
  repo: string;
4238
4387
  };
4239
4388
  export type PullsStackOutput = StackEntry[];
4389
+ /**
4390
+ * List the pull requests that change a file, or a folder when `path` ends in `/`, newest first. Only the newest few hundred pull requests of the chosen states are searched.
4391
+ */
4392
+ export type PullsTouchingInput = {
4393
+ /** At most this many: 30 by default, at most 100. */
4394
+ limit?: number | null;
4395
+ /** The repository owner's handle. */
4396
+ owner: string;
4397
+ /** File path, or a folder ending in `/`. */
4398
+ path: string;
4399
+ /** The repository's name. */
4400
+ repo: string;
4401
+ state?: TouchingState | null;
4402
+ };
4403
+ export type PullsTouchingOutput = PullItems;
4240
4404
  /**
4241
4405
  * Edit a pull request: its title, description, state (close, reopen, mark ready or back to draft), reviewer, base or lock. Only the fields sent change.
4242
4406
  */
@@ -4273,6 +4437,58 @@ export type PullsUpdateBranchInput = {
4273
4437
  repo: string;
4274
4438
  };
4275
4439
  export type PullsUpdateBranchOutput = BranchUpdated;
4440
+ /**
4441
+ * Show a commit: its message, author, parent and child, and its changes as a diff of the first files in path order.
4442
+ */
4443
+ export type ReposCommitInput = {
4444
+ /** The repository owner's handle. */
4445
+ owner: string;
4446
+ /** The repository's name. */
4447
+ repo: string;
4448
+ /** Commit sha (or its start), branch or tag. */
4449
+ sha: string;
4450
+ };
4451
+ export type ReposCommitOutput = CommitView;
4452
+ /**
4453
+ * List the commits of a branch, tag or commit, newest first, or the history of one path with `path`. A signed-out visitor sees a public repository's.
4454
+ */
4455
+ export type ReposCommitsInput = {
4456
+ /** The `cursor` of an answer that stopped before its page was full: the history goes on from there. */
4457
+ cursor?: string | null;
4458
+ /** `1` answers `{commits, cursor}` instead of the bare list. */
4459
+ envelope?: string | null;
4460
+ /** Commits to answer: 500 by default, at most 1000. */
4461
+ limit?: number | null;
4462
+ /** The repository owner's handle. */
4463
+ owner: string;
4464
+ /** Only commits that changed this file or folder, following a renamed file to its earlier names. */
4465
+ path?: string | null;
4466
+ /** Branch, tag or commit to start from; the default branch when absent. */
4467
+ ref?: string | null;
4468
+ /** The repository's name. */
4469
+ repo: string;
4470
+ /** Newest commits to leave out, to page. */
4471
+ skip?: number | null;
4472
+ };
4473
+ export type ReposCommitsOutput = CommitLog;
4474
+ /**
4475
+ * Compare two branches, tags or commits: the commits `head` adds since their merge base and its diff. `spec` is `{base}...{head}`. A signed-out visitor sees a public repository's.
4476
+ */
4477
+ export type ReposCompareInput = {
4478
+ /** With `from`: how many files the page holds, 1 to 100. */
4479
+ count?: number | null;
4480
+ /** With `count`: the index of the first file of a page of files with their hunks. */
4481
+ from?: number | null;
4482
+ /** Hunks for the leading files only, up to about this many diff lines; the answer then names `base` and `head`. */
4483
+ lines?: number | null;
4484
+ /** The repository owner's handle. */
4485
+ owner: string;
4486
+ /** The repository's name. */
4487
+ repo: string;
4488
+ /** `{base}...{head}`, such as `main...feature/login`. */
4489
+ spec: string;
4490
+ };
4491
+ export type ReposCompareOutput = CompareAnswer;
4276
4492
  /**
4277
4493
  * Create a repository for the caller, or in an org they belong to.
4278
4494
  */
package/llms.txt CHANGED
@@ -171,13 +171,16 @@
171
171
  - `sf.pulls.autoMerge(input)`: Show a pull request's auto-merge: whether it is on, whether it waits in the merge queue and why it has not merged yet.
172
172
  - `sf.pulls.autoMergeDisable(input)`: Turn auto-merge off for a pull request, and take it out of the merge queue.
173
173
  - `sf.pulls.autoMergeEnable(input)`: Turn auto-merge on: the pull request merges, as the caller, once its checks pass and the merge rules allow it, while its branch is still at `expectedHead`. When it can merge at once it does, and the answer says `merged`.
174
+ - `sf.pulls.branchDiff(input)`: Show the diff of the pull request from a branch: the open one, else the newest closed or merged one.
174
175
  - `sf.pulls.checks(input)`: Show what a pull request's checks add up to: the CI jobs of the newest run of each workflow on its head, then the latest check run of each name and reporter. `waited` lets the verdict tell a first run that has not started from one that never will.
175
176
  - `sf.pulls.comment(input)`: Comment on a pull request: reply in a thread, or start one on a line of the diff.
176
177
  - `sf.pulls.conflicts(input)`: The files that keep a pull request's branch from taking its base, at both branches' current tips, each text file with conflict markers around every conflict. `files` is empty when it merges cleanly.
177
178
  - `sf.pulls.create(input)`: Open a pull request from a branch into a base branch. Opening one for a branch that already has an open one answers 409.
178
179
  - `sf.pulls.deleteComment(input)`: Delete a comment on a pull request.
180
+ - `sf.pulls.diff(input)`: Show what a pull request changes: the commits it adds and its diff against the merge base, with totals. A merged one answers the diff it merged. A signed-out visitor sees a public repository's.
179
181
  - `sf.pulls.dismiss(input)`: Dismiss the reviews that approved or asked for changes on a pull request.
180
182
  - `sf.pulls.editComment(input)`: Edit a comment on a pull request. `at` is the comment's timestamp, which keeps an edit from landing on another comment when the thread changed.
183
+ - `sf.pulls.forCommit(input)`: List the pull requests whose commits include a commit, among the newest few hundred of any state.
181
184
  - `sf.pulls.get(input)`: Show a pull request with its threads, whether it merges cleanly and the merge rules it does not meet yet.
182
185
  - `sf.pulls.hideComment(input)`: Hide a comment on a pull request behind a reason, or show it again when no reason is sent.
183
186
  - `sf.pulls.list(input)`: List a repository's pull requests, newest first. A signed-out visitor sees a public repository's.
@@ -186,11 +189,15 @@
186
189
  - `sf.pulls.resolveThread(input)`: Resolve a review thread, or reopen it.
187
190
  - `sf.pulls.review(input)`: Approve a pull request, ask for changes or comment, with line comments that land with it or not at all. Answers 409 when `commit` names a head the branch has moved past.
188
191
  - `sf.pulls.stack(input)`: Show the whole tree of pull requests a pull request belongs to, root first, depth first.
192
+ - `sf.pulls.touching(input)`: List the pull requests that change a file, or a folder when `path` ends in `/`, newest first. Only the newest few hundred pull requests of the chosen states are searched.
189
193
  - `sf.pulls.update(input)`: Edit a pull request: its title, description, state (close, reopen, mark ready or back to draft), reviewer, base or lock. Only the fields sent change.
190
194
  - `sf.pulls.updateBranch(input)`: Merge the base branch into a pull request's branch on the server, for a merge refused as behind. `updated` is false when the branch already had the base.
191
195
 
192
196
  ## repos
193
197
 
198
+ - `sf.repos.commit(input)`: Show a commit: its message, author, parent and child, and its changes as a diff of the first files in path order.
199
+ - `sf.repos.commits(input)`: List the commits of a branch, tag or commit, newest first, or the history of one path with `path`. A signed-out visitor sees a public repository's.
200
+ - `sf.repos.compare(input)`: Compare two branches, tags or commits: the commits `head` adds since their merge base and its diff. `spec` is `{base}...{head}`. A signed-out visitor sees a public repository's.
194
201
  - `sf.repos.create(input)`: Create a repository for the caller, or in an org they belong to.
195
202
  - `sf.repos.get(input)`: Show a repository: description, visibility, default branch, branches, clone URLs and the caller's access (`read`, `write` or `admin`). A signed-out visitor reads a public repository. An old handle of a renamed owner answers 301 with the current address.
196
203
  - `sf.repos.list(input)`: List the repositories the caller can reach, newest first: their own, the ones they collaborate on and their orgs'.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sailfork",
3
- "version": "0.3.6",
3
+ "version": "0.4.0",
4
4
  "description": "Official TypeScript SDK for Sailfork, git hosting built for AI coding agents: a typed API client for repositories, pull requests, code review, issues, CI and sandboxes, with Anthropic and OpenAI tool definitions.",
5
5
  "keywords": [
6
6
  "sailfork",