@bluestep-systems/b6p-core-bsjs-git 0.2.0 → 0.3.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 +65 -12
- package/dist/ScriptRepo.d.ts +132 -10
- package/dist/ScriptRepo.js +355 -44
- package/dist/ScriptRepo.js.map +1 -1
- package/dist/buildManifest.d.ts +21 -36
- package/dist/buildManifest.js +44 -49
- package/dist/buildManifest.js.map +1 -1
- package/dist/csrf.js.map +1 -1
- package/dist/errors.d.ts +85 -1
- package/dist/errors.js +114 -1
- package/dist/errors.js.map +1 -1
- package/dist/http.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.js +14 -5
- package/dist/index.js.map +1 -1
- package/dist/legacy.js.map +1 -1
- package/dist/scriptKey.js.map +1 -1
- package/dist/serverBuild.d.ts +190 -0
- package/dist/serverBuild.js +221 -0
- package/dist/serverBuild.js.map +1 -0
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Browser- and Node-safe git client for BlueStep BSJS scripts. It edits a script's **draft** branch with
|
|
4
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
|
|
6
|
-
the file system is injected, HTTP is `fetch
|
|
5
|
+
asks the platform to build it, publishes it, reads git history, and reads the legacy (pre-git) history archive. No
|
|
6
|
+
WebDAV, no Node built-in imports, no compiler: the file system is injected, HTTP is `fetch`, and the platform compiles.
|
|
7
7
|
|
|
8
8
|
Used by [`@bluestep-systems/b6p-core`](../../README.md) (re-exported as `bsjsGit`) and by the BSJS editor.
|
|
9
9
|
|
|
@@ -28,7 +28,9 @@ await repo.commit("Edit main"); // stages every working-tree change
|
|
|
28
28
|
// commit(msg, author, { parents }) makes a (merge) commit over the given parents even with nothing staged
|
|
29
29
|
await repo.push(); // the draft branch
|
|
30
30
|
// commit(msg, author, { force: [".build/app.js"] }) stages those paths even when .gitignore matches them
|
|
31
|
-
const
|
|
31
|
+
const build = await repo.compileDraft(); // the platform builds the pushed draft; the local draft moves to its build commit
|
|
32
|
+
// { compile, buildCommitSha, vouched, head, fastForward }
|
|
33
|
+
const { publishedSha, refreshed } = await repo.publish(); // the platform promotes draft (the build commit) to master
|
|
32
34
|
|
|
33
35
|
await repo.sha("origin/draft"); // a branch or sha as a commit sha
|
|
34
36
|
await repo.isAncestor(a, b); // whether a is b or one of its ancestors
|
|
@@ -52,7 +54,8 @@ Every refusal is a typed `BsjsGitError` with a `code`: `GitAuthError` (401), `Gi
|
|
|
52
54
|
publishes over WebDAV, so its repo is read-only), `GitCodeLockedError`, `GitPermissionError` (other 403),
|
|
53
55
|
`GitRepoNotFoundError` (404: no repo, not visible, or git integration off), `GitPushRejectedError` (the forge refused
|
|
54
56
|
the ref; `protectedBranch` for master), `GitNotFastForwardError`, `PublishRefusedError` (`reason` is the server's
|
|
55
|
-
`PUBLISH_REFUSED` reason), `
|
|
57
|
+
`PUBLISH_REFUSED` reason), `DraftBuildFailedError` / `DraftBuildMovedError` (the build), `GitBuildFastForwardBlockedError` (`paths`), `GitUnpushedChangesError`,
|
|
58
|
+
`GitIdentityError`, `GitTransportError`.
|
|
56
59
|
|
|
57
60
|
## Auth modes
|
|
58
61
|
|
|
@@ -68,8 +71,57 @@ and a refused one retried once. Session mode relies on the platform's git proxy
|
|
|
68
71
|
`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
72
|
The mode is read with a real query, `remoteObject(id: "<classid>___<seqnum>") { ... on ScriptFormula|ScriptMergeReport|ScriptEndpoint { gitPublishing gitCloneUrl } }`, not a write.
|
|
70
73
|
|
|
74
|
+
## Build
|
|
75
|
+
|
|
76
|
+
Nothing compiles in this package or in the editor: `compileDraft()` asks the platform to build the draft it holds. The
|
|
77
|
+
local draft must already be pushed (`GitUnpushedChangesError` otherwise). It sends the script's update mutation with
|
|
78
|
+
`compileDraft: true` and `expectedDraftSha` (the pushed head) on `/gql`; the platform compiles the draft branch at that
|
|
79
|
+
commit against its siblings' snapshots and commits the output and stale-output deletes, plus the build manifest only when
|
|
80
|
+
it vouches for the build (every project's output written, no blocking error; a type-checker finding is a warning), as one
|
|
81
|
+
build commit authored by the caller. The answer's `extensions.bluestepCompile[0]` is the compile (`status`, counts,
|
|
82
|
+
`diagnostics`, `gate`; `parseDraftCompileOutcome`) and `extensions.bluestepBuild[0]` the build commit (`{ commit,
|
|
83
|
+
vouched }` of `{ script, draftSha, commit, built, vouched, status }`; `parseDraftBuildCommit`; `vouched` is also true
|
|
84
|
+
for a draft that needs no manifest). The local draft is then moved exactly to the build commit by
|
|
85
|
+
`fastForwardToBuild(sha)`: the working tree and index first, for exactly the paths the build changed (straight into the
|
|
86
|
+
index, whatever `.gitignore` says), the branch last. A path whose local copy matches neither the pushed commit nor the
|
|
87
|
+
build (a local edit, an untracked or ignored file) stops it before anything is touched; other local edits are kept. The
|
|
88
|
+
outcome is `fastForward: { state, blockedPaths, error }` (`fast-forwarded`, `unchanged`, `blocked`, `failed`), never a
|
|
89
|
+
build failure. `isBuildCommitOf(candidate, base)` says whether a commit is the platform's build of exactly the source `base`, or a
|
|
90
|
+
rebuild chain of it: each commit carries the trailer `Bluestep-Build-Of: <base>` (`buildSourceOf`, `BUILD_OF_TRAILER`),
|
|
91
|
+
has one parent and changes only paths under the output folder of some build project at the parent: each
|
|
92
|
+
`tsconfig.json` at any depth gives `<its dir>/` + its `buildOutputFolder`, plus the root `jsconfig.json` when there is
|
|
93
|
+
no root `tsconfig.json`; a project whose folder is empty or leaves the tree gives none, and with none at all nothing is
|
|
94
|
+
a build (`buildConfigPaths`, `buildOutputFolders`, `changesOnlyBuildOutput`: the one resolver web and the BSJS editor
|
|
95
|
+
use too). A chain is at most 16 build commits deep. The subject never counts. This is
|
|
96
|
+
web's rule (`docs/bsjs-git-snapshot-design.md`, "Build commits"), the trailer parsed as there: CRLF as LF, trailing
|
|
97
|
+
whitespace dropped, the last paragraph (after the last blank or whitespace-only line, or the whole message), exactly one
|
|
98
|
+
line `Bluestep-Build-Of: <40/64 hex>`. Rule 3 compares complete tree entries (mode and id, gitlinks included), so a
|
|
99
|
+
mode-only or submodule change outside `F/` is not a build.
|
|
100
|
+
|
|
101
|
+
A refusal with reason `BUILD_OUTCOME_UNKNOWN` (the platform could not confirm its build push) is never retried, since a repeat could build twice: `compileDraft` reads the draft back and returns
|
|
102
|
+
`outcomeUnknown: { buildFound }`, moving the local draft to the head when that is a build of the push. `compile` is
|
|
103
|
+
then `UNKNOWN` and `vouched` false. It is for taking
|
|
104
|
+
in a build whose answer was lost. An unclean build deletes the manifest, and the fast-forward deletes it here too.
|
|
105
|
+
|
|
106
|
+
It resolves to `{ compile, buildCommitSha, vouched, head, fastForward }`: `buildCommitSha` is `null` when the build made no commit
|
|
107
|
+
(already built at that commit, nothing to build). An unclean build (`vouched: false`) still commits its output, without
|
|
108
|
+
a manifest, so `publish()` is refused until a clean build. `BUSY` is retried 3 times 5 s apart, `INPUT_INCOMPLETE` 3
|
|
109
|
+
times 2 s apart, `COMPILER_UNAVAILABLE` and a failed request once (`COMPILE_RETRY`; `options.sleep` replaces the
|
|
110
|
+
timer). A tripped gate or withheld emit is a result (`compile.status`; `compileAllowsPublish` says whether to publish).
|
|
111
|
+
A draft that moved since the push is `DraftBuildMovedError` (`DRAFT_MOVED`); any other failure is
|
|
112
|
+
`DraftBuildFailedError` (`messages`, `networkFailure`).
|
|
113
|
+
|
|
71
114
|
## Publish
|
|
72
115
|
|
|
116
|
+
`publish({ at })` pins the publish to the commit that was built and checked (the build commit, or the pushed commit
|
|
117
|
+
when there was none): the local draft must be that commit or a build of it (`isBuildCommitOf`), else
|
|
118
|
+
`PublishPinMismatchError` (`at`, `local`) is thrown with nothing sent, so a later save cannot be published under an
|
|
119
|
+
earlier build's result. b6p-core always pins.
|
|
120
|
+
|
|
121
|
+
Build refusals are `DraftBuildFailedError` with a typed `reason` (`DRAFT_BUILD_REFUSAL_REASONS`: `DRAFT_MOVED`,
|
|
122
|
+
`BUILD_OUTCOME_UNKNOWN`, `DRAFT_TOO_LARGE`, `REPO_MISSING`, `DRAFT_BRANCH_MISSING`; `rawReason` keeps a newer one) and
|
|
123
|
+
are never retried.
|
|
124
|
+
|
|
73
125
|
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
126
|
|
|
75
127
|
`publish()` sends the platform's existing publish: a GraphQL `updateScript<Type>` mutation with `takeSnapshot: true`
|
|
@@ -95,11 +147,12 @@ package with esbuild (`platform: "browser"`, no plugins) to keep that true.
|
|
|
95
147
|
|
|
96
148
|
A git script publishes `draft` exactly as committed, so the server refuses a draft whose sources no longer match the
|
|
97
149
|
build manifest (`<outDir>/.b6p-build.json`, contract v1): the git blob SHA-1 of every source file the build was made
|
|
98
|
-
from.
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
`
|
|
104
|
-
(`BUILD_STALE`), `PublishBuildManifestMissingError` (`BUILD_MANIFEST_MISSING`) or
|
|
105
|
-
(`BUILD_MANIFEST_INVALID`), each with `withheld` (the stale paths, or the
|
|
150
|
+
from. The platform writes it in its build commit (see Build), only for a clean build; no client writes one, and this
|
|
151
|
+
package has no manifest writer (0.3.0 removed `commit({ buildManifest })`, `planBuildManifest`, `formatBuildManifest`,
|
|
152
|
+
`gitBlobSha1` and `BUILD_MANIFEST_BUILDER`). None is needed for an externally built script, a tree with no
|
|
153
|
+
`tsconfig.json`, or a draft with no TypeScript source outside the output folder (`isTypeScriptSource`: `ts tsx mts
|
|
154
|
+
cts`, never a `*.d.*` declaration). The layout helpers (`buildOutputFolder`, `buildManifestPath`, `isBuildSource`,
|
|
155
|
+
`isTypeScriptSource`, `hasNoTsconfig`, `parseJsonc`) stay exported for reading. A refused publish is
|
|
156
|
+
`PublishBuildStaleError` (`BUILD_STALE`), `PublishBuildManifestMissingError` (`BUILD_MANIFEST_MISSING`) or
|
|
157
|
+
`PublishBuildManifestInvalidError` (`BUILD_MANIFEST_INVALID`), each with `withheld` (the stale paths, or the
|
|
158
|
+
manifest's path).
|
package/dist/ScriptRepo.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import "./bufferShim";
|
|
2
2
|
import { type PromiseFsClient } from "isomorphic-git";
|
|
3
3
|
import { type ScriptAuth } from "./csrf";
|
|
4
|
+
import { type DraftCompileOutcome } from "./serverBuild";
|
|
4
5
|
import { type FetchLike } from "./http";
|
|
5
6
|
import { type ScriptRef } from "./scriptKey";
|
|
6
7
|
/**
|
|
@@ -161,10 +162,6 @@ export interface CommitOptions {
|
|
|
161
162
|
readonly parents?: readonly string[];
|
|
162
163
|
/** Stage these paths even when .gitignore matches them. */
|
|
163
164
|
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
165
|
}
|
|
169
166
|
/**
|
|
170
167
|
* Options of {@link ScriptRepo.clone}.
|
|
@@ -189,6 +186,95 @@ export interface LogPage {
|
|
|
189
186
|
/** The history loaded here ends before the page did: deepen the clone and ask again. */
|
|
190
187
|
readonly shallowBoundary: boolean;
|
|
191
188
|
}
|
|
189
|
+
/**
|
|
190
|
+
* What {@link ScriptRepo.compileDraft} did.
|
|
191
|
+
* @lastreviewed null
|
|
192
|
+
*/
|
|
193
|
+
export interface DraftBuildResult {
|
|
194
|
+
/**
|
|
195
|
+
* The platform's compile of the draft: status, counts and diagnostics.
|
|
196
|
+
* @lastreviewed null
|
|
197
|
+
*/
|
|
198
|
+
readonly compile: DraftCompileOutcome;
|
|
199
|
+
/**
|
|
200
|
+
* The build commit the platform made on the draft branch, now also the local draft's head. `null` when the build
|
|
201
|
+
* made none (the draft was already built at the pushed commit, nothing needed building, or the compile did not run).
|
|
202
|
+
* @lastreviewed null
|
|
203
|
+
*/
|
|
204
|
+
readonly buildCommitSha: string | null;
|
|
205
|
+
/**
|
|
206
|
+
* Whether the platform vouched for the build, so the build manifest is in the draft and it can publish. False after
|
|
207
|
+
* an unclean build: its output is committed without a manifest, and a publish is refused until a clean build.
|
|
208
|
+
* @lastreviewed null
|
|
209
|
+
*/
|
|
210
|
+
readonly vouched: boolean;
|
|
211
|
+
/**
|
|
212
|
+
* The local draft's head after the build: `buildCommitSha`, or the pushed commit when there was no build commit.
|
|
213
|
+
* @lastreviewed null
|
|
214
|
+
*/
|
|
215
|
+
readonly head: string;
|
|
216
|
+
/**
|
|
217
|
+
* How the local draft was moved to `buildCommitSha` ({@link ScriptRepo.fastForwardToBuild}); `unchanged` when there
|
|
218
|
+
* is no build commit.
|
|
219
|
+
* @lastreviewed null
|
|
220
|
+
*/
|
|
221
|
+
readonly fastForward: BuildFastForward;
|
|
222
|
+
/**
|
|
223
|
+
* Set when the platform could not tell whether its build landed ({@link BUILD_OUTCOME_UNKNOWN_REASON}): the draft
|
|
224
|
+
* was then read back, and `buildFound` says whether its head is a build of the pushed commit (by the build-commit
|
|
225
|
+
* rule, {@link ScriptRepo.isBuildCommitOf}). When it is, the local draft was moved to it as after any build. `compile`
|
|
226
|
+
* is then `UNKNOWN` (raw status the refusal code) and `vouched` false: nothing says how the build went. `null` when
|
|
227
|
+
* the platform answered.
|
|
228
|
+
* @lastreviewed null
|
|
229
|
+
*/
|
|
230
|
+
readonly outcomeUnknown: {
|
|
231
|
+
readonly buildFound: boolean;
|
|
232
|
+
} | null;
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* How {@link ScriptRepo.fastForwardToBuild} went:
|
|
236
|
+
* - `fast-forwarded`: the working tree, index and local draft branch are at the build commit.
|
|
237
|
+
* - `unchanged`: the local draft was there already, or there was nothing to move to.
|
|
238
|
+
* - `blocked`: local files the build changes are in the way (`blockedPaths`); nothing was changed.
|
|
239
|
+
* - `failed`: the move could not be done (`error`); the local draft branch was not moved.
|
|
240
|
+
* @lastreviewed null
|
|
241
|
+
*/
|
|
242
|
+
export type BuildFastForwardState = "fast-forwarded" | "unchanged" | "blocked" | "failed";
|
|
243
|
+
/**
|
|
244
|
+
* What {@link ScriptRepo.fastForwardToBuild} did.
|
|
245
|
+
* @lastreviewed null
|
|
246
|
+
*/
|
|
247
|
+
export interface BuildFastForward {
|
|
248
|
+
/** See {@link BuildFastForwardState}. @lastreviewed null */
|
|
249
|
+
readonly state: BuildFastForwardState;
|
|
250
|
+
/**
|
|
251
|
+
* When `blocked`: the paths the build changes whose local copy matches neither the local draft's commit nor the
|
|
252
|
+
* build (a local edit, or an untracked or ignored file), sorted. Empty otherwise.
|
|
253
|
+
* @lastreviewed null
|
|
254
|
+
*/
|
|
255
|
+
readonly blockedPaths: readonly string[];
|
|
256
|
+
/** When `failed`: why. `null` otherwise. @lastreviewed null */
|
|
257
|
+
readonly error: string | null;
|
|
258
|
+
}
|
|
259
|
+
/**
|
|
260
|
+
* Options of {@link ScriptRepo.publish}.
|
|
261
|
+
* @lastreviewed null
|
|
262
|
+
*/
|
|
263
|
+
export interface PublishOptions {
|
|
264
|
+
/** The commit the publish is pinned to; see {@link ScriptRepo.publish}. @lastreviewed null */
|
|
265
|
+
readonly at?: string;
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* Options of {@link ScriptRepo.compileDraft}.
|
|
269
|
+
* @lastreviewed null
|
|
270
|
+
*/
|
|
271
|
+
export interface CompileDraftOptions {
|
|
272
|
+
/**
|
|
273
|
+
* Waits between retries. Defaults to a real timer; tests pass a recorder.
|
|
274
|
+
* @lastreviewed null
|
|
275
|
+
*/
|
|
276
|
+
readonly sleep?: (ms: number) => Promise<void>;
|
|
277
|
+
}
|
|
192
278
|
/**
|
|
193
279
|
* What {@link ScriptRepo.publish} did.
|
|
194
280
|
* @lastreviewed null
|
|
@@ -283,11 +369,6 @@ export declare class ScriptRepo {
|
|
|
283
369
|
* @param author overrides the constructor's author.
|
|
284
370
|
* @param options `parents` makes the commit over exactly those parents (a merge when there are two) and commits even
|
|
285
371
|
* 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
372
|
* @returns the new commit's sha, or `undefined` when nothing changed.
|
|
292
373
|
* @throws {GitIdentityError} when there is no author.
|
|
293
374
|
* @lastreviewed null
|
|
@@ -362,17 +443,58 @@ export declare class ScriptRepo {
|
|
|
362
443
|
readonly cloneUrl: string;
|
|
363
444
|
readonly switched: boolean;
|
|
364
445
|
}>;
|
|
446
|
+
/**
|
|
447
|
+
* Asks the platform to build the pushed draft (GraphQL `compileDraft`, pinned with `expectedDraftSha` to the commit
|
|
448
|
+
* this client pushed), then fast-forwards the local draft and working tree to the build commit the platform made.
|
|
449
|
+
* The platform compiles the draft branch against its siblings' snapshots and commits the output, plus the build
|
|
450
|
+
* manifest when it vouches for the build, as one commit authored by the caller. No compiler runs here.
|
|
451
|
+
*
|
|
452
|
+
* Retries `BUSY`, `INPUT_INCOMPLETE` and `COMPILER_UNAVAILABLE` outcomes and a failed request by
|
|
453
|
+
* {@link COMPILE_RETRY}; when the retries run out the last outcome is returned. A tripped gate, a withheld emit or
|
|
454
|
+
* an unclean build is a result, not an error.
|
|
455
|
+
* @throws {GitUnpushedChangesError} when the local draft is not what the platform holds.
|
|
456
|
+
* @throws {DraftBuildMovedError} when the platform's draft moved since the push (`DRAFT_MOVED`); nothing was built.
|
|
457
|
+
* @throws {DraftBuildFailedError} on any other GraphQL error, an unreadable answer, or a request that failed twice.
|
|
458
|
+
* @lastreviewed null
|
|
459
|
+
*/
|
|
460
|
+
compileDraft(options?: CompileDraftOptions): Promise<DraftBuildResult>;
|
|
461
|
+
/**
|
|
462
|
+
* Moves the local draft to `buildSha`, the platform's build commit of it (output and manifest only), without losing a
|
|
463
|
+
* local edit. The working tree and index are brought to the build first, for exactly the paths the build changes
|
|
464
|
+
* relative to the local draft's commit, and the draft branch is moved only once that succeeded. A path whose local
|
|
465
|
+
* copy matches neither side (a local edit, or an untracked or ignored file) stops it before anything is touched
|
|
466
|
+
* (`blocked`, with the paths); a local copy that already matches the build is fine. Other local edits are kept.
|
|
467
|
+
* Exactly to `buildSha`, not to whatever the draft is now: a push landing after the build is not taken in.
|
|
468
|
+
* @param buildSha A commit that has the local draft as an ancestor, already fetched
|
|
469
|
+
* @lastreviewed null
|
|
470
|
+
*/
|
|
471
|
+
fastForwardToBuild(buildSha: string): Promise<BuildFastForward>;
|
|
472
|
+
/**
|
|
473
|
+
* Whether `candidate` is the platform's build of the source commit `base`, after any chain of rebuilds of it. Every
|
|
474
|
+
* commit from `candidate` down to `base` must be a build commit by the web rule (`bsjs-git-snapshot-design.md`):
|
|
475
|
+
* its trailer names `base` ({@link buildSourceOf}), it has exactly one parent, and relative to that parent it changes
|
|
476
|
+
* only paths under the output folder ({@link changesOnlyBuildOutput}). The subject counts for nothing. Checking each
|
|
477
|
+
* link, not just the head, is stricter than the server's retry match, and only refuses chains the server never makes. An edit made on the platform
|
|
478
|
+
* fails at least one of these, so it is never taken for a build. The commits must be fetched.
|
|
479
|
+
* @lastreviewed null
|
|
480
|
+
*/
|
|
481
|
+
isBuildCommitOf(candidate: string, base: string): Promise<boolean>;
|
|
365
482
|
/**
|
|
366
483
|
* Publishes the draft: asks the platform to promote the pushed draft to the published branch (the same publish
|
|
367
484
|
* the platform runs for any script, a `takeSnapshot` update) and returns the commit it published.
|
|
368
485
|
*
|
|
369
486
|
* @returns the published sha (`config.publishedSha`). The publish has happened once this resolves; `refreshed` says
|
|
370
487
|
* whether the follow-up fetch that brings `origin/master` up to date also succeeded (`refreshError` if not).
|
|
488
|
+
* @param options.at Pin the publish: the commit that was built and checked (the build commit from
|
|
489
|
+
* {@link compileDraft}, or the pushed commit when there was none). The local draft must be that commit or a
|
|
490
|
+
* build of it ({@link isBuildCommitOf}), else nothing is sent; the platform is then asked to publish exactly
|
|
491
|
+
* the local draft (`expectedDraftSha`), so a later save cannot slip in under a build's result.
|
|
371
492
|
* @throws {GitUnpushedChangesError} when the local draft is not what the platform holds.
|
|
493
|
+
* @throws {PublishPinMismatchError} when `at` is given and the local draft is neither it nor a build of it.
|
|
372
494
|
* @throws {PublishRefusedError} when the platform refuses (nothing is written); `reason` says why.
|
|
373
495
|
* @lastreviewed null
|
|
374
496
|
*/
|
|
375
|
-
publish(): Promise<PublishResult>;
|
|
497
|
+
publish(options?: PublishOptions): Promise<PublishResult>;
|
|
376
498
|
/**
|
|
377
499
|
* Commits on a branch or from a sha, newest first.
|
|
378
500
|
* @param options paging: `limit` and `before` (the last sha of the previous page; the walk still starts at `rev`).
|