@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 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 WebDAV, no Node built-in imports:
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 { publishedSha, refreshed } = await repo.publish(); // the platform promotes draft to master
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), `GitUnpushedChangesError`, `GitIdentityError`, `GitTransportError`.
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. 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).
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).
@@ -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`).