@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 +104 -2
- package/dist/ScriptRepo.d.ts +409 -0
- package/dist/ScriptRepo.js +699 -0
- package/dist/ScriptRepo.js.map +1 -0
- package/dist/bufferShim.d.ts +1 -0
- package/dist/bufferShim.js +15 -0
- package/dist/bufferShim.js.map +1 -0
- package/dist/buildManifest.d.ts +98 -0
- package/dist/buildManifest.js +251 -0
- package/dist/buildManifest.js.map +1 -0
- package/dist/csrf.d.ts +37 -0
- package/dist/csrf.js +88 -0
- package/dist/csrf.js.map +1 -0
- package/dist/errors.d.ts +207 -0
- package/dist/errors.js +291 -0
- package/dist/errors.js.map +1 -0
- package/dist/http.d.ts +32 -0
- package/dist/http.js +129 -0
- package/dist/http.js.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +58 -0
- package/dist/index.js.map +1 -0
- package/dist/legacy.d.ts +128 -0
- package/dist/legacy.js +180 -0
- package/dist/legacy.js.map +1 -0
- package/dist/scriptKey.d.ts +61 -0
- package/dist/scriptKey.js +65 -0
- package/dist/scriptKey.js.map +1 -0
- package/package.json +42 -4
package/README.md
CHANGED
|
@@ -1,3 +1,105 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @bluestep-systems/b6p-core-bsjs-git
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
}
|