@bluestep-systems/b6p-core-bsjs-git 0.0.0-stage → 0.2.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/README.md CHANGED
@@ -1,3 +1,105 @@
1
- # Temporary Holding Version
1
+ # @bluestep-systems/b6p-core-bsjs-git
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Browser- and Node-safe git client for BlueStep BSJS scripts. It edits a script's **draft** branch with
4
+ [isomorphic-git](https://isomorphic-git.org/) through the platform's git proxy (`<org>/git/<classid>___<seqnum>`),
5
+ publishes it, reads git history, and reads the legacy (pre-git) history archive. No WebDAV, no Node built-in imports:
6
+ the file system is injected, HTTP is `fetch`.
7
+
8
+ Used by [`@bluestep-systems/b6p-core`](../../README.md) (re-exported as `bsjsGit`) and by the BSJS editor.
9
+
10
+ ```ts
11
+ import { ScriptRepo, LegacyHistoryClient, parseCompoundId } from "@bluestep-systems/b6p-core-bsjs-git";
12
+
13
+ const repo = new ScriptRepo({
14
+ fs, // Node's `fs`, or a browser one such as LightningFS (needs `.promises`)
15
+ dir: "/work/654015___1001",
16
+ script: parseCompoundId("654015___1001"),
17
+ baseUrl: "https://org.bluestep.net/",
18
+ auth: { kind: "token", token }, // a b6pt_ token; or { kind: "session" } in a signed-in browser
19
+ author: { name: "Ada", email: "ada@example.com" }, // always the caller's; there is no default identity
20
+ });
21
+
22
+ await repo.ensureGitMode(); // WEBDAV script -> git (one-way); no-op when already git. Returns the clone URL
23
+ await repo.clone(); // every branch; draft checked out (or clone({ ensureGit: true }) for both)
24
+ // clone({ depth: 50, singleBranch: true }): a bounded clone (plus master's head at the same depth);
25
+ // repo.deepen(50) loads older history; repo.logPage(...).shallowBoundary says when to
26
+ await repo.writeFile("main.ts", "export {};\n");
27
+ await repo.commit("Edit main"); // stages every working-tree change
28
+ // commit(msg, author, { parents }) makes a (merge) commit over the given parents even with nothing staged
29
+ await repo.push(); // the draft branch
30
+ // commit(msg, author, { force: [".build/app.js"] }) stages those paths even when .gitignore matches them
31
+ const { publishedSha, refreshed } = await repo.publish(); // the platform promotes draft to master
32
+
33
+ await repo.sha("origin/draft"); // a branch or sha as a commit sha
34
+ await repo.isAncestor(a, b); // whether a is b or one of its ancestors
35
+ await repo.resetDraft(sha); // move the local draft and its working tree to a commit
36
+
37
+ await repo.log({ rev: "master", limit: 20 }); // CommitInfo[], newest first; page with `before`
38
+ await repo.listTree(publishedSha); // files at a revision
39
+ await repo.readText(publishedSha, "main.ts");
40
+ await repo.diff(a, b); // FileChange[] between two revisions
41
+
42
+ const legacy = new LegacyHistoryClient({ baseUrl, auth: { kind: "token", token } });
43
+ const entries = await legacy.list("654015___1001", { limit: 50 }); // newest first
44
+ const tree = await legacy.get("654015___1001", entries[0].id); // saveState v1 or v0, one tree type
45
+ ```
46
+
47
+ Paths are `/`-separated and stay inside the working tree: a backslash, `..` or a `.git` segment is refused.
48
+
49
+ ## Refusals
50
+
51
+ Every refusal is a typed `BsjsGitError` with a `code`: `GitAuthError` (401), `GitPushNotEnabledError` (the script
52
+ publishes over WebDAV, so its repo is read-only), `GitCodeLockedError`, `GitPermissionError` (other 403),
53
+ `GitRepoNotFoundError` (404: no repo, not visible, or git integration off), `GitPushRejectedError` (the forge refused
54
+ the ref; `protectedBranch` for master), `GitNotFastForwardError`, `PublishRefusedError` (`reason` is the server's
55
+ `PUBLISH_REFUSED` reason), `GitUnpushedChangesError`, `GitIdentityError`, `GitTransportError`.
56
+
57
+ ## Auth modes
58
+
59
+ `auth: { kind: "token", token }` sends the `b6pt_` token (Basic to the git proxy, Bearer to `/gql` and REST). `auth:
60
+ { kind: "session" }` is for a browser already signed in: no `Authorization` header, `credentials: "include"`, and the
61
+ `B6P-CSRF-TOKEN` from `/csrf-token` on every request (git smart-HTTP, `/gql`, legacy history), refreshed tokens adopted
62
+ and a refused one retried once. Session mode relies on the platform's git proxy accepting the session (web item W6).
63
+
64
+ ## Switching a script to git
65
+
66
+ `ensureGitMode()` reads the script's `gitPublishing` / `gitCloneUrl` and, only if it is not in GIT mode, runs
67
+ `enableGitPublishing: true` on the script's update mutation (synchronous, creates and seeds the repo, **one-way**).
68
+ `ensureGitModeResult()` is the same, also saying whether this call did the switch. `clone({ ensureGit: true })` does it first; a plain `clone()` never flips a script.
69
+ The mode is read with a real query, `remoteObject(id: "<classid>___<seqnum>") { ... on ScriptFormula|ScriptMergeReport|ScriptEndpoint { gitPublishing gitCloneUrl } }`, not a write.
70
+
71
+ ## Publish
72
+
73
+ The mutation carries `expectedDraftSha`: the local draft head `publish()` verified equals the platform's. If the platform's draft moved since (someone pushed in between), it refuses with reason `DRAFT_MOVED`, thrown as `PublishDraftMovedError` (a `PublishRefusedError`), and publishes nothing. `gitMode()` reads the mode without switching anything.
74
+
75
+ `publish()` sends the platform's existing publish: a GraphQL `updateScript<Type>` mutation with `takeSnapshot: true`
76
+ on `/gql`, reading `config.publishedSha` from the answer. The local draft must already be pushed. `/gql` enforces
77
+ the CSRF token on every call, bearer included, so the call mirrors `b6p-core`'s `csrfFetch`: the bearer opens a session,
78
+ the token is read from `/csrf-token` and sent as `B6P-CSRF-TOKEN` with the session cookie (kept in a small jar in Node;
79
+ a browser keeps its own), and a refused token is retried once. It resolves to `{ publishedSha, refreshed, refreshError? }`:
80
+ the publish has happened once it resolves, and `refreshed: false` only means the follow-up fetch of `origin/master` failed.
81
+
82
+ ## Bundling for a browser
83
+
84
+ isomorphic-git needs a global `Buffer`, and its `safe-buffer` dependency requires `"buffer"`. This package depends on the
85
+ npm `buffer` package (pinned) and installs it as `globalThis.Buffer` when none exists (the first thing its entry does),
86
+ so a bundler resolves `"buffer"` to it with no polyfill plugin and no alias. `test/BrowserBundle.test.js` bundles the
87
+ package with esbuild (`platform: "browser"`, no plugins) to keep that true.
88
+
89
+ ## Tests
90
+
91
+ `npm test -w @bluestep-systems/b6p-core-bsjs-git`. The round-trip spec serves a real bare repo over HTTP by running
92
+ `git http-backend` behind `node:http` (see `test/support/GitProxyStub.js`), so `git` must be on the PATH.
93
+
94
+ ## Build manifest
95
+
96
+ A git script publishes `draft` exactly as committed, so the server refuses a draft whose sources no longer match the
97
+ build manifest (`<outDir>/.b6p-build.json`, contract v1): the git blob SHA-1 of every source file the build was made
98
+ from. Whoever builds writes it in the same commit as the output: `commit(msg, author, { buildManifest: {} })` stages the
99
+ tree, computes the manifest over what the commit will hold and commits it with it. Pass the option only after a build that
100
+ succeeded and emitted everything; after a failed or partial build omit it, which leaves any existing manifest as it is
101
+ (so a publish refuses it). `{ buildManifest: { externallyBuilt: true } }` writes none, and none is written for a tree
102
+ with no `tsconfig.json`, nor for a draft with no TypeScript source outside the output folder (`isTypeScriptSource`: `ts tsx mts cts`, never a `*.d.*` declaration; declarations are still listed in `sources` when a manifest is written). The pure helpers (`buildOutputFolder`, `buildManifestPath`, `isBuildSource`, `gitBlobSha1`,
103
+ `planBuildManifest`, `formatBuildManifest`) are exported. A refused publish is `PublishBuildStaleError`
104
+ (`BUILD_STALE`), `PublishBuildManifestMissingError` (`BUILD_MANIFEST_MISSING`) or `PublishBuildManifestInvalidError`
105
+ (`BUILD_MANIFEST_INVALID`), each with `withheld` (the stale paths, or the manifest's path).
@@ -0,0 +1,409 @@
1
+ import "./bufferShim";
2
+ import { type PromiseFsClient } from "isomorphic-git";
3
+ import { type ScriptAuth } from "./csrf";
4
+ import { type FetchLike } from "./http";
5
+ import { type ScriptRef } from "./scriptKey";
6
+ /**
7
+ * The script's editable branch.
8
+ * @lastreviewed null
9
+ */
10
+ export declare const DRAFT_BRANCH = "draft";
11
+ /**
12
+ * The script's published branch; only a publish moves it.
13
+ * @lastreviewed null
14
+ */
15
+ export declare const PUBLISHED_BRANCH = "master";
16
+ /**
17
+ * Who a commit is by. Always supplied by the caller: this package never invents an identity.
18
+ * @lastreviewed null
19
+ */
20
+ export interface GitIdentity {
21
+ readonly name: string;
22
+ readonly email: string;
23
+ }
24
+ /**
25
+ * Everything a {@link ScriptRepo} needs, with the platform and the file system injected.
26
+ * @lastreviewed null
27
+ */
28
+ export interface ScriptRepoOptions {
29
+ /**
30
+ * The file system the working tree and `.git` live on: Node's `fs`, or a browser one such as LightningFS. Injected so
31
+ * this package imports nothing node-only.
32
+ * @lastreviewed null
33
+ */
34
+ readonly fs: PromiseFsClient;
35
+ /**
36
+ * The working tree's directory on `fs` (the repo's `.git` is inside it).
37
+ * @lastreviewed null
38
+ */
39
+ readonly dir: string;
40
+ /**
41
+ * The script.
42
+ * @lastreviewed null
43
+ */
44
+ readonly script: ScriptRef;
45
+ /**
46
+ * The organization's base URL, such as `https://org.bluestep.net/`.
47
+ * @lastreviewed null
48
+ */
49
+ readonly baseUrl: string | URL;
50
+ /**
51
+ * Who is calling: a `b6pt_` token, or the signed-in browser session (see {@link ScriptAuth}).
52
+ * @lastreviewed null
53
+ */
54
+ readonly auth: ScriptAuth;
55
+ /**
56
+ * The default commit author. Optional here; a commit without one passed to {@link ScriptRepo.commit} throws.
57
+ * @lastreviewed null
58
+ */
59
+ readonly author?: GitIdentity;
60
+ /**
61
+ * Overrides the global `fetch` (tests, or a runtime that needs a custom one).
62
+ * @lastreviewed null
63
+ */
64
+ readonly fetch?: FetchLike;
65
+ }
66
+ /**
67
+ * One commit, newest first in listings.
68
+ * @lastreviewed null
69
+ */
70
+ export interface CommitInfo {
71
+ readonly sha: string;
72
+ readonly author: GitIdentity;
73
+ /**
74
+ * ISO 8601, UTC.
75
+ * @lastreviewed null
76
+ */
77
+ readonly timestamp: string;
78
+ readonly message: string;
79
+ }
80
+ /**
81
+ * One file in a tree at a revision.
82
+ * @lastreviewed null
83
+ */
84
+ export interface TreeFile {
85
+ /**
86
+ * Path from the repo root, without a leading slash.
87
+ * @lastreviewed null
88
+ */
89
+ readonly path: string;
90
+ /**
91
+ * The blob's object id.
92
+ * @lastreviewed null
93
+ */
94
+ readonly oid: string;
95
+ }
96
+ /**
97
+ * One file that differs between two revisions.
98
+ * @lastreviewed null
99
+ */
100
+ export interface FileChange {
101
+ readonly path: string;
102
+ readonly status: "added" | "modified" | "deleted";
103
+ /**
104
+ * Blob id at the first revision; absent when added.
105
+ * @lastreviewed null
106
+ */
107
+ readonly oldOid?: string;
108
+ /**
109
+ * Blob id at the second revision; absent when deleted.
110
+ * @lastreviewed null
111
+ */
112
+ readonly newOid?: string;
113
+ }
114
+ /**
115
+ * A working-tree file that differs from the last commit.
116
+ * @lastreviewed null
117
+ */
118
+ export interface WorkingChange {
119
+ readonly path: string;
120
+ readonly status: "added" | "modified" | "deleted";
121
+ }
122
+ /**
123
+ * What a push did.
124
+ * @lastreviewed null
125
+ */
126
+ export interface PushOutcome {
127
+ readonly ref: string;
128
+ /**
129
+ * The commit the remote branch now points at.
130
+ * @lastreviewed null
131
+ */
132
+ readonly sha: string;
133
+ }
134
+ /**
135
+ * Paging for {@link ScriptRepo.log}.
136
+ * @lastreviewed null
137
+ */
138
+ export interface LogOptions {
139
+ /**
140
+ * A branch name or commit sha. Default: the draft branch.
141
+ * @lastreviewed null
142
+ */
143
+ readonly rev?: string;
144
+ /**
145
+ * At most this many commits. Default 50.
146
+ * @lastreviewed null
147
+ */
148
+ readonly limit?: number;
149
+ /**
150
+ * A commit sha to continue after (exclusive): pass the last sha of the previous page.
151
+ * @lastreviewed null
152
+ */
153
+ readonly before?: string;
154
+ }
155
+ /**
156
+ * Options of {@link ScriptRepo.commit}.
157
+ * @lastreviewed null
158
+ */
159
+ export interface CommitOptions {
160
+ /** Commit over exactly these parents (a merge with two), even with nothing staged. */
161
+ readonly parents?: readonly string[];
162
+ /** Stage these paths even when .gitignore matches them. */
163
+ readonly force?: readonly string[];
164
+ /** Write the build manifest in this commit; see {@link ScriptRepo.commit}. */
165
+ readonly buildManifest?: {
166
+ readonly externallyBuilt?: boolean;
167
+ };
168
+ }
169
+ /**
170
+ * Options of {@link ScriptRepo.clone}.
171
+ * @lastreviewed null
172
+ */
173
+ export interface CloneOptions {
174
+ /** First run {@link ScriptRepo.ensureGitMode}. Off by default: a read-only clone must not flip a script. */
175
+ readonly ensureGit?: boolean;
176
+ /** Only this many commits of history (a shallow clone); more with {@link ScriptRepo.deepen}. Default: all. */
177
+ readonly depth?: number;
178
+ /** Fetch only `ref` (and the published branch, at the same depth) instead of every branch. Default false. */
179
+ readonly singleBranch?: boolean;
180
+ /** The branch to check out; default the draft branch. */
181
+ readonly ref?: string;
182
+ }
183
+ /**
184
+ * One page of {@link ScriptRepo.logPage}.
185
+ * @lastreviewed null
186
+ */
187
+ export interface LogPage {
188
+ readonly commits: CommitInfo[];
189
+ /** The history loaded here ends before the page did: deepen the clone and ask again. */
190
+ readonly shallowBoundary: boolean;
191
+ }
192
+ /**
193
+ * What {@link ScriptRepo.publish} did.
194
+ * @lastreviewed null
195
+ */
196
+ export interface PublishResult {
197
+ /** The commit the platform promoted to the published branch. */
198
+ readonly publishedSha: string;
199
+ /** Whether the follow-up fetch that updates the local `origin/master` succeeded. The publish happened either way. */
200
+ readonly refreshed: boolean;
201
+ /** Why the follow-up fetch failed, when `refreshed` is false. */
202
+ readonly refreshError?: unknown;
203
+ }
204
+ /**
205
+ * The decoded `Uint8Array` of a blob as text.
206
+ * @lastreviewed null
207
+ */
208
+ export declare function decodeText(bytes: Uint8Array): string;
209
+ /**
210
+ * A script's git repo on the platform: clone, edit, commit and push the **draft** branch through the platform's
211
+ * git proxy, publish it, and read history. Browser and Node alike; the file system is injected.
212
+ *
213
+ * Only the draft branch is pushed by default. The platform's forge refuses any proxied push to the published branch,
214
+ * and a script is pushable only in GIT publish mode; both arrive as typed {@link BsjsGitError}s.
215
+ * @lastreviewed null
216
+ */
217
+ export declare class ScriptRepo {
218
+ #private;
219
+ readonly dir: string;
220
+ readonly script: ScriptRef;
221
+ /**
222
+ * The proxy URL of the script's repo.
223
+ * @lastreviewed null
224
+ */
225
+ readonly url: string;
226
+ constructor(options: ScriptRepoOptions);
227
+ /**
228
+ * Clones every branch of the script's repo into {@link dir} and checks out the draft branch.
229
+ *
230
+ * @param options `ensureGit: true` first runs {@link ensureGitMode}, so a script still publishing over WebDAV is
231
+ * switched to git (one-way, irreversible on the platform) and gets its repo. Off by default: a read-only
232
+ * clone must not flip a script.
233
+ * @throws {GitRepoNotFoundError} when the script has no repo or is not visible.
234
+ * @lastreviewed null
235
+ */
236
+ clone(options?: CloneOptions): Promise<void>;
237
+ /**
238
+ * Fetches more history into a shallow clone: `depth` further commits past what is loaded, on the draft and published
239
+ * branches. A no-op on a clone with full history.
240
+ * @lastreviewed null
241
+ */
242
+ deepen(depth: number): Promise<void>;
243
+ /**
244
+ * Whether this clone has a history boundary (it was cloned with a depth and not fully deepened).
245
+ * @lastreviewed null
246
+ */
247
+ isShallow(): Promise<boolean>;
248
+ /**
249
+ * Fetches every branch from the platform, updating the remote-tracking branches (`origin/draft`, `origin/master`).
250
+ * @lastreviewed null
251
+ */
252
+ fetch(): Promise<void>;
253
+ /**
254
+ * Fetches, then fast-forwards the local draft to the platform's. A local draft with commits of its own is not
255
+ * merged; that is the caller's decision.
256
+ * @throws {GitNotFastForwardError} when the branches have diverged.
257
+ * @lastreviewed null
258
+ */
259
+ pull(): Promise<void>;
260
+ /**
261
+ * Checks out a branch (or sha), overwriting working-tree files when `force` is set.
262
+ * @lastreviewed null
263
+ */
264
+ checkout(ref?: string, force?: boolean): Promise<void>;
265
+ /**
266
+ * Writes a file into the working tree (creating folders); stage and commit with {@link commit}.
267
+ * @lastreviewed null
268
+ */
269
+ writeFile(path: string, data: string | Uint8Array): Promise<void>;
270
+ /**
271
+ * Removes a file from the working tree; stage and commit with {@link commit}.
272
+ * @lastreviewed null
273
+ */
274
+ removeFile(path: string): Promise<void>;
275
+ /**
276
+ * The working-tree files that differ from the last commit.
277
+ * @lastreviewed null
278
+ */
279
+ status(): Promise<WorkingChange[]>;
280
+ /**
281
+ * Stages every working-tree change and commits it to the current branch.
282
+ * @param message the commit message.
283
+ * @param author overrides the constructor's author.
284
+ * @param options `parents` makes the commit over exactly those parents (a merge when there are two) and commits even
285
+ * with nothing staged: the tree is whatever is staged now.
286
+ * @param options `buildManifest` writes the build manifest ({@link planBuildManifest}) for the tree this commit will
287
+ * hold, outputs included, and commits it with them. Pass it only after a build that succeeded and emitted
288
+ * everything; after a failed or partial build omit it, which leaves any existing manifest as it is (stale,
289
+ * so a publish refuses it). No manifest is written for an externally built script or a tree with no
290
+ * `tsconfig.json`.
291
+ * @returns the new commit's sha, or `undefined` when nothing changed.
292
+ * @throws {GitIdentityError} when there is no author.
293
+ * @lastreviewed null
294
+ */
295
+ commit(message: string, author?: GitIdentity, options?: CommitOptions): Promise<string | undefined>;
296
+ /**
297
+ * A branch name or sha as a commit sha; a branch prefers the local ref, then the platform's
298
+ * (`origin/<branch>`).
299
+ * @throws {BsjsGitError} (`REPO_NOT_FOUND`) when the local repo has no such branch or commit.
300
+ * @lastreviewed null
301
+ */
302
+ sha(rev: string): Promise<string>;
303
+ /**
304
+ * Whether `ancestor` is `descendant` or one of its ancestors (both branch names or shas).
305
+ * @lastreviewed null
306
+ */
307
+ isAncestor(ancestor: string, descendant: string): Promise<boolean>;
308
+ /**
309
+ * Points the local draft branch at `rev` and checks it out, overwriting working-tree files (the caller keeps
310
+ * whatever local edits it wants to survive and writes them back afterwards).
311
+ * @lastreviewed null
312
+ */
313
+ resetDraft(rev: string): Promise<void>;
314
+ /**
315
+ * Pushes a branch (the draft by default) to the platform.
316
+ * @throws {GitPushNotEnabledError} when the script is not in GIT publish mode.
317
+ * @throws {GitPushRejectedError} when the forge refuses the ref update (the published branch is protected).
318
+ * @throws {GitNotFastForwardError} when the remote branch has commits the local one lacks.
319
+ * @lastreviewed null
320
+ */
321
+ push(ref?: string, force?: boolean): Promise<PushOutcome>;
322
+ /**
323
+ * Makes sure the script publishes over git. Reads the script's `gitPublishing` and `gitCloneUrl` with a real query
324
+ * (`remoteObject(id)`, no write) and, only when it is not already in GIT mode, runs the platform's own switch (`enableGitPublishing: true` on the script's update
325
+ * mutation: synchronous, creates the repo and seeds `master` and `draft` from the WebDAV copy, and **one-way**).
326
+ * Uses the same CSRF-carrying path as {@link publish}.
327
+ *
328
+ * @returns the script's clone URL as the platform reports it.
329
+ * @throws {GitModeError} when the platform refuses or does not answer with a clone URL.
330
+ * @lastreviewed null
331
+ */
332
+ ensureGitMode(): Promise<string>;
333
+ /**
334
+ * Whether the script publishes over git, read with a query (no write, nothing is switched).
335
+ * @returns `gitPublishing` and, when it is, the clone URL as the platform reports it.
336
+ * @throws {GitModeError} when the platform does not answer.
337
+ * @lastreviewed null
338
+ */
339
+ gitMode(): Promise<{
340
+ readonly gitPublishing: boolean;
341
+ readonly cloneUrl: string | null;
342
+ }>;
343
+ /**
344
+ * The branch the working tree has checked out, or `undefined` when HEAD is detached.
345
+ * @lastreviewed null
346
+ */
347
+ currentBranch(): Promise<string | undefined>;
348
+ /**
349
+ * Paths whose staged content differs from both the last commit and the working-tree file: changes that exist only in
350
+ * the index, which a checkout would discard.
351
+ * @lastreviewed null
352
+ */
353
+ stagedOnlyChanges(): Promise<string[]>;
354
+ /**
355
+ * {@link ensureGitMode}, also saying whether this call is the one that switched the script.
356
+ * @returns `cloneUrl` as the platform reports it; `switched` is true when the script was in WEBDAV mode and this
357
+ * call turned git on (one-way).
358
+ * @throws {GitModeError} as {@link ensureGitMode}.
359
+ * @lastreviewed null
360
+ */
361
+ ensureGitModeResult(): Promise<{
362
+ readonly cloneUrl: string;
363
+ readonly switched: boolean;
364
+ }>;
365
+ /**
366
+ * Publishes the draft: asks the platform to promote the pushed draft to the published branch (the same publish
367
+ * the platform runs for any script, a `takeSnapshot` update) and returns the commit it published.
368
+ *
369
+ * @returns the published sha (`config.publishedSha`). The publish has happened once this resolves; `refreshed` says
370
+ * whether the follow-up fetch that brings `origin/master` up to date also succeeded (`refreshError` if not).
371
+ * @throws {GitUnpushedChangesError} when the local draft is not what the platform holds.
372
+ * @throws {PublishRefusedError} when the platform refuses (nothing is written); `reason` says why.
373
+ * @lastreviewed null
374
+ */
375
+ publish(): Promise<PublishResult>;
376
+ /**
377
+ * Commits on a branch or from a sha, newest first.
378
+ * @param options paging: `limit` and `before` (the last sha of the previous page; the walk still starts at `rev`).
379
+ * @lastreviewed null
380
+ */
381
+ log(options?: LogOptions): Promise<CommitInfo[]>;
382
+ /**
383
+ * {@link log}, also saying whether the walk stopped at the shallow boundary of a bounded clone: `shallowBoundary` is
384
+ * true when fewer commits than asked for came back because the history loaded here ends, not because the repo's does.
385
+ * The caller then calls {@link deepen} and asks again from the same cursor.
386
+ * @lastreviewed null
387
+ */
388
+ logPage(options?: LogOptions): Promise<LogPage>;
389
+ /**
390
+ * The files of the tree at a branch or sha.
391
+ * @lastreviewed null
392
+ */
393
+ listTree(rev?: string): Promise<TreeFile[]>;
394
+ /**
395
+ * A file's bytes at a branch or sha.
396
+ * @lastreviewed null
397
+ */
398
+ readFile(rev: string, path: string): Promise<Uint8Array>;
399
+ /**
400
+ * A file's text at a branch or sha.
401
+ * @lastreviewed null
402
+ */
403
+ readText(rev: string, path: string): Promise<string>;
404
+ /**
405
+ * The files that differ between two branches or shas, sorted by path.
406
+ * @lastreviewed null
407
+ */
408
+ diff(from: string, to: string): Promise<FileChange[]>;
409
+ }