blogwright 0.4.0 → 0.5.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.
Files changed (50) hide show
  1. package/README.md +4 -1
  2. package/agent/agent-manifest.json +1 -1
  3. package/agent/server.js +2610 -616
  4. package/dist/adapters/process-aws-login.d.ts +19 -0
  5. package/dist/adapters/process-aws-login.js +28 -0
  6. package/dist/agent-package.js +2 -3
  7. package/dist/artifacts.d.ts +73 -0
  8. package/dist/artifacts.js +218 -0
  9. package/dist/aws-session.d.ts +118 -0
  10. package/dist/aws-session.js +360 -0
  11. package/dist/bin.js +6 -2
  12. package/dist/cache-control.d.ts +66 -0
  13. package/dist/cache-control.js +176 -0
  14. package/dist/cli.d.ts +22 -3
  15. package/dist/cli.js +122 -31
  16. package/dist/commands.d.ts +41 -9
  17. package/dist/commands.js +135 -126
  18. package/dist/context.d.ts +27 -5
  19. package/dist/context.js +59 -19
  20. package/dist/deploy.d.ts +78 -6
  21. package/dist/deploy.js +136 -52
  22. package/dist/init.d.ts +14 -2
  23. package/dist/init.js +145 -4
  24. package/dist/known-commands.d.ts +11 -9
  25. package/dist/known-commands.js +15 -9
  26. package/dist/live-release.d.ts +78 -0
  27. package/dist/live-release.js +159 -0
  28. package/dist/lock.d.ts +50 -0
  29. package/dist/lock.js +120 -0
  30. package/dist/nodes.d.ts +18 -0
  31. package/dist/nodes.js +405 -30
  32. package/dist/plugin-commands.d.ts +21 -0
  33. package/dist/plugin-commands.js +54 -3
  34. package/dist/plugins.d.ts +11 -9
  35. package/dist/plugins.js +29 -16
  36. package/dist/ports.d.ts +22 -1
  37. package/dist/releases.d.ts +54 -0
  38. package/dist/releases.js +527 -0
  39. package/dist/render.d.ts +18 -1
  40. package/dist/render.js +38 -6
  41. package/dist/repo.js +2 -3
  42. package/dist/rkey.d.ts +4 -3
  43. package/dist/rkey.js +4 -3
  44. package/dist/serving.d.ts +28 -0
  45. package/dist/serving.js +47 -0
  46. package/dist/verify.d.ts +45 -0
  47. package/dist/verify.js +183 -0
  48. package/dist/whoami.d.ts +23 -0
  49. package/dist/whoami.js +88 -0
  50. package/package.json +8 -8
package/dist/init.js CHANGED
@@ -11,8 +11,10 @@
11
11
  * plugins as a plain array, never a `ModuleLoader`, so this stays a domain
12
12
  * module.
13
13
  */
14
- import { colors, findRepoRoot, parseConfig, WEB_FUNCTION_REGIONS, } from 'blogwright-core';
14
+ import { colors, findRepoRoot, parseConfig, readAwsProfiles, shortIdentity, WEB_FUNCTION_REGIONS, } from 'blogwright-core';
15
+ import { resolveAwsProfile, resolveAwsSession } from './aws-session.js';
15
16
  import { renderConfigBlock } from './config-block.js';
17
+ import { confirm } from './logger.js';
16
18
  const SITE_NAME_PATTERN = /^[a-z0-9-]+$/;
17
19
  const GITHUB_REPO_PATTERN = /^[\w.-]+\/[\w.-]+$/;
18
20
  const MAX_ATTEMPTS = 3;
@@ -223,6 +225,135 @@ async function askSsrFramework(terminal, logger) {
223
225
  });
224
226
  return SSR_FRAMEWORKS[choice.toLowerCase()];
225
227
  }
228
+ /** Where the wizard writes, relative to the repo root - also how AWS messages name it. */
229
+ const INIT_CONFIG_FILE = 'config/production.jsonc';
230
+ /** The answer that chooses default credentials when the profile question has a default. */
231
+ const NO_PROFILE_ANSWER = 'none';
232
+ /** The profile `--profile`, then `AWS_PROFILE`, suggests - with which of the two it came from. */
233
+ function suggestedProfile(aws) {
234
+ const flag = aws.profile?.trim();
235
+ if (flag)
236
+ return { name: flag, source: '--profile' };
237
+ const env = aws.host.processEnv.AWS_PROFILE?.trim();
238
+ return env ? { name: env, source: 'AWS_PROFILE' } : undefined;
239
+ }
240
+ /**
241
+ * Ask which named profile this environment uses - only when the shared AWS
242
+ * files define at least one. Defaults to `--profile`, then `AWS_PROFILE`,
243
+ * but only when the files define it: a stale suggestion is dropped with a
244
+ * warning (even when nothing is asked) rather than offered as an answer that can never validate. Blank
245
+ * means default credentials when there is no default; with a default, blank
246
+ * takes it and `none` chooses default credentials. A nonblank answer must be
247
+ * a listed profile. Undefined means default credentials.
248
+ */
249
+ async function askAwsProfile(fs, terminal, logger, aws) {
250
+ const profiles = await readAwsProfiles(fs, aws.host.processEnv, aws.host.home);
251
+ const suggested = suggestedProfile(aws);
252
+ const asked = profiles.names.length > 0;
253
+ if (suggested && !profiles.has(suggested.name)) {
254
+ logger.warn(`profile "${suggested.name}" from ${suggested.source} is not in your AWS config files - ` +
255
+ (asked ? 'not offering it as the default' : 'ignoring it'));
256
+ }
257
+ if (!asked)
258
+ return undefined;
259
+ const defaultValue = suggested && profiles.has(suggested.name) ? suggested.name : undefined;
260
+ const choice = defaultValue
261
+ ? `"${NO_PROFILE_ANSWER}" for default credentials`
262
+ : 'blank for default credentials';
263
+ const answer = await ask(terminal, logger, {
264
+ prompt: `AWS profile for this environment (${choice})`,
265
+ defaultValue,
266
+ validate: (v) => profiles.has(v) || v === NO_PROFILE_ANSWER
267
+ ? undefined
268
+ : `no profile "${v}" - expected one of ${profiles.names.join(', ')}, or "${NO_PROFILE_ANSWER}"`,
269
+ });
270
+ return answer === NO_PROFILE_ANSWER && !profiles.has(answer) ? undefined : answer;
271
+ }
272
+ /**
273
+ * Warn when this shell would override what the config is about to say: the
274
+ * pin is detected for the config's credentials, so a command run here under
275
+ * a different `AWS_PROFILE` or exported credentials could be refused.
276
+ */
277
+ function warnShellOverride(logger, processEnv, profile) {
278
+ const shell = resolveAwsProfile({ processEnv, config: { profile } });
279
+ const advice = 'unset it before running blogwright in this shell';
280
+ if (shell.source === 'env' && shell.name !== profile) {
281
+ const saved = profile === undefined ? 'is not saved to the config' : 'overrides aws.profile';
282
+ logger.warn(`AWS_PROFILE=${shell.name} is set in this shell and ${saved} - ${advice}`);
283
+ }
284
+ else if (shell.source === 'env-keys' && profile !== undefined) {
285
+ logger.warn('AWS credentials exported in this shell override aws.profile - unset them first');
286
+ }
287
+ }
288
+ /** The environment without `AWS_PROFILE`, so detection sees what a config with no profile uses. */
289
+ function withoutAwsProfile(processEnv) {
290
+ const { AWS_PROFILE: _ignored, ...rest } = processEnv;
291
+ return rest;
292
+ }
293
+ /**
294
+ * Offer to detect the account the chosen credentials belong to and pin it.
295
+ * The credentials are the ones the written config selects: the chosen
296
+ * profile, or - with none - exported credentials or the default chain, never
297
+ * this shell's `AWS_PROFILE`, which the config does not record. A shell that
298
+ * would override the config is warned about. Runs the same session
299
+ * resolution every command does - login offer included - against real AWS,
300
+ * so the pin is a real account. With `AWS_ENDPOINT_URL`
301
+ * exported it is not offered at all: the SDK's own SSO and STS clients that
302
+ * resolve a profile read that variable too, so detection would ask the
303
+ * emulator. An AWS failure never fails `init`: every error the session
304
+ * raises is an AWS or sign-in failure, so it warns and leaves the account
305
+ * unpinned.
306
+ */
307
+ async function askAccountPin(fs, terminal, logger, opts) {
308
+ if (opts.aws.host.processEnv.AWS_ENDPOINT_URL?.trim()) {
309
+ logger.warn('AWS_ENDPOINT_URL is set, so the AWS account cannot be detected');
310
+ logger.warn(ACCOUNT_NOT_PINNED);
311
+ return undefined;
312
+ }
313
+ if (!(await confirm(terminal, 'Detect the AWS account and pin it to this config?'))) {
314
+ return undefined;
315
+ }
316
+ const { host } = opts.aws;
317
+ warnShellOverride(logger, host.processEnv, opts.profile);
318
+ try {
319
+ const session = await resolveAwsSession({
320
+ region: opts.region,
321
+ endpointOverride: undefined,
322
+ flag: opts.profile,
323
+ configLabel: INIT_CONFIG_FILE,
324
+ host: opts.profile === undefined
325
+ ? { ...host, processEnv: withoutAwsProfile(host.processEnv) }
326
+ : host,
327
+ ports: { fs, terminal, awsLogin: opts.aws.awsLogin },
328
+ logger,
329
+ });
330
+ const { account, arn } = session.identity;
331
+ logger.ok(`AWS account ${account} (${shortIdentity(arn)}) - pinned as aws.accountId`);
332
+ return account;
333
+ }
334
+ catch (err) {
335
+ logger.warn(err instanceof Error ? err.message : String(err));
336
+ logger.warn(ACCOUNT_NOT_PINNED);
337
+ return undefined;
338
+ }
339
+ }
340
+ const ACCOUNT_NOT_PINNED = 'account not pinned - add aws.accountId later';
341
+ /**
342
+ * The `aws` block, or undefined when there is nothing to write. Rendered in
343
+ * `renderConfigBlock`'s style; the pin carries its own explanatory comment.
344
+ */
345
+ function renderAwsBlock(aws) {
346
+ const entries = [];
347
+ if (aws.profile)
348
+ entries.push({ prop: `"profile": ${JSON.stringify(aws.profile)}` });
349
+ if (aws.accountId) {
350
+ entries.push({
351
+ prop: `"accountId": "${aws.accountId}"`,
352
+ comment: 'deploys refuse credentials for any other account',
353
+ });
354
+ }
355
+ return entries.length > 0 ? renderConfigBlock('aws', entries) : undefined;
356
+ }
226
357
  /** Render one top-level item with its own trailing comma, or none when it is last. */
227
358
  function renderTopLevelItem(item, last) {
228
359
  const comma = last ? '' : ',';
@@ -258,6 +389,9 @@ function renderConfig(opts) {
258
389
  }
259
390
  if (opts.ssr)
260
391
  items.push({ block: renderConfigBlock('ssr', opts.ssr.entries) });
392
+ const awsBlock = opts.aws ? renderAwsBlock(opts.aws) : undefined;
393
+ if (awsBlock)
394
+ items.push({ block: awsBlock });
261
395
  for (const block of opts.pluginBlocks)
262
396
  items.push({ block });
263
397
  const body = items.map((item, i) => renderTopLevelItem(item, i === items.length - 1));
@@ -273,14 +407,14 @@ function renderConfig(opts) {
273
407
  * single `fs.writeText` below ever runs, so the config file stays exactly
274
408
  * what it was - absent, on this path - rather than a partial write.
275
409
  */
276
- export async function initSite(fs, terminal, logger, plugins, root) {
410
+ export async function initSite(fs, terminal, logger, plugins, options) {
277
411
  if (!terminal.isInteractive) {
278
412
  logger.error('init is an interactive wizard; in CI or plain mode create config/production.jsonc ' +
279
413
  'by hand instead (see README - only "region" and "siteName" are required)');
280
414
  return 1;
281
415
  }
282
- const repoRoot = root ?? (await findRepoRoot(fs).catch(() => process.cwd()));
283
- const configPath = `${repoRoot}/config/production.jsonc`;
416
+ const repoRoot = options.root ?? (await findRepoRoot(fs).catch(() => process.cwd()));
417
+ const configPath = `${repoRoot}/${INIT_CONFIG_FILE}`;
284
418
  if (await fs.exists(configPath)) {
285
419
  logger.error(`${configPath} already exists - edit it directly, or pass --config elsewhere`);
286
420
  return 1;
@@ -314,6 +448,12 @@ export async function initSite(fs, terminal, logger, plugins, root) {
314
448
  validate: (v) => (WEB_FUNCTION_REGIONS.includes(v) ? undefined : `expected ${regions}`),
315
449
  });
316
450
  }
451
+ const profile = await askAwsProfile(fs, terminal, logger, options.aws);
452
+ const accountId = await askAccountPin(fs, terminal, logger, {
453
+ region: region,
454
+ profile,
455
+ aws: options.aws,
456
+ });
317
457
  const pluginBlocks = await collectPluginBlocks(plugins, terminal, logger);
318
458
  const rendered = renderConfig({
319
459
  region: region,
@@ -321,6 +461,7 @@ export async function initSite(fs, terminal, logger, plugins, root) {
321
461
  domain,
322
462
  githubRepo,
323
463
  ssr,
464
+ aws: { profile, accountId },
324
465
  pluginBlocks,
325
466
  });
326
467
  // Re-parsed before it is trusted onto disk, mirroring `plugin-commands.ts`'s
@@ -15,9 +15,8 @@
15
15
  /**
16
16
  * The CLI's command-name registries, isolated in their own leaf module with
17
17
  * no imports of its own. Both `cli.ts` (the dispatcher - it pulls in every
18
- * built-in command implementation, and since task 29 no plugin package by
19
- * name: `blogwright-pds` reaches it only transitively, through the
20
- * post-deploy sync `commands.ts` imports) and
18
+ * built-in command implementation, and no plugin package by name - pds
19
+ * reaches `deploy` only through its `afterDeploy` hook) and
21
20
  * `plugins.ts` (a domain module that must stay inside the port boundary -
22
21
  * see DEVELOPMENT.md §Hexagonal architecture) need to read the same set of
23
22
  * reserved names, and neither may import the other: `plugins.ts` importing
@@ -27,10 +26,10 @@
27
26
  * other to finish initialising before either can run. This module gives
28
27
  * both callers a shared, dependency-free home instead.
29
28
  *
30
- * `KNOWN_COMMANDS` is the eight names `cli.ts`'s `main` dispatches through
31
- * its `switch`, after the `KNOWN_COMMANDS.has(command)` membership test:
32
- * `bootstrap`, `deploy`, `rollback`, `delete`, `destroy`, `history`, `logs`,
33
- * `status`.
29
+ * `KNOWN_COMMANDS` is the names `cli.ts`'s `main` dispatches through its
30
+ * `switch`, after the `KNOWN_COMMANDS.has(command)` membership test:
31
+ * `bootstrap`, `deploy`, `stage`, `promote`, `rollback`, `delete`, `destroy`,
32
+ * `history`, `logs`, `status`, `verify` - plus `plugin`, which `main` claims before the switch.
34
33
  *
35
34
  * `RESERVED_COMMANDS` is every name a plugin may never claim as its own -
36
35
  * see `discover`'s namespace-collision check in `plugins.ts`. It is
@@ -43,12 +42,15 @@
43
42
  * `KNOWN_COMMANDS`), but the name is reserved from the moment any plugin
44
43
  * could collide with it, and the union keeps this set correct both before
45
44
  * and after that command exists - no second edit required either way.
45
+ * `whoami` is named explicitly too: like `init` it is dispatched ahead of the
46
+ * membership test, because it builds no context.
46
47
  *
47
48
  * `pds` is deliberately absent from `RESERVED_COMMANDS`, and adding it here
48
49
  * would break `blogwright pds` outright. There is no built-in `pds` command:
49
50
  * task 29 deleted `cli.ts`'s hardcoded `command === 'pds'` branch, and the
50
- * namespace is now served by the bundled `blogwright-pds` package, which
51
- * declares the plugin name `pds` and is discovered like any other plugin.
51
+ * namespace is now served by the `blogwright-pds` package a site installs
52
+ * (`blogwright plugin add pds`), which declares the plugin name `pds` and is
53
+ * discovered like any other plugin.
52
54
  * Reserving the name would make `discover`'s reserved-name check
53
55
  * (`plugins.ts`) reject that package - a load `failures` entry, never an
54
56
  * installed plugin - so `blogwright pds <action>` would exit 1 with `no
@@ -15,9 +15,8 @@
15
15
  /**
16
16
  * The CLI's command-name registries, isolated in their own leaf module with
17
17
  * no imports of its own. Both `cli.ts` (the dispatcher - it pulls in every
18
- * built-in command implementation, and since task 29 no plugin package by
19
- * name: `blogwright-pds` reaches it only transitively, through the
20
- * post-deploy sync `commands.ts` imports) and
18
+ * built-in command implementation, and no plugin package by name - pds
19
+ * reaches `deploy` only through its `afterDeploy` hook) and
21
20
  * `plugins.ts` (a domain module that must stay inside the port boundary -
22
21
  * see DEVELOPMENT.md §Hexagonal architecture) need to read the same set of
23
22
  * reserved names, and neither may import the other: `plugins.ts` importing
@@ -27,10 +26,10 @@
27
26
  * other to finish initialising before either can run. This module gives
28
27
  * both callers a shared, dependency-free home instead.
29
28
  *
30
- * `KNOWN_COMMANDS` is the eight names `cli.ts`'s `main` dispatches through
31
- * its `switch`, after the `KNOWN_COMMANDS.has(command)` membership test:
32
- * `bootstrap`, `deploy`, `rollback`, `delete`, `destroy`, `history`, `logs`,
33
- * `status`.
29
+ * `KNOWN_COMMANDS` is the names `cli.ts`'s `main` dispatches through its
30
+ * `switch`, after the `KNOWN_COMMANDS.has(command)` membership test:
31
+ * `bootstrap`, `deploy`, `stage`, `promote`, `rollback`, `delete`, `destroy`,
32
+ * `history`, `logs`, `status`, `verify` - plus `plugin`, which `main` claims before the switch.
34
33
  *
35
34
  * `RESERVED_COMMANDS` is every name a plugin may never claim as its own -
36
35
  * see `discover`'s namespace-collision check in `plugins.ts`. It is
@@ -43,12 +42,15 @@
43
42
  * `KNOWN_COMMANDS`), but the name is reserved from the moment any plugin
44
43
  * could collide with it, and the union keeps this set correct both before
45
44
  * and after that command exists - no second edit required either way.
45
+ * `whoami` is named explicitly too: like `init` it is dispatched ahead of the
46
+ * membership test, because it builds no context.
46
47
  *
47
48
  * `pds` is deliberately absent from `RESERVED_COMMANDS`, and adding it here
48
49
  * would break `blogwright pds` outright. There is no built-in `pds` command:
49
50
  * task 29 deleted `cli.ts`'s hardcoded `command === 'pds'` branch, and the
50
- * namespace is now served by the bundled `blogwright-pds` package, which
51
- * declares the plugin name `pds` and is discovered like any other plugin.
51
+ * namespace is now served by the `blogwright-pds` package a site installs
52
+ * (`blogwright plugin add pds`), which declares the plugin name `pds` and is
53
+ * discovered like any other plugin.
52
54
  * Reserving the name would make `discover`'s reserved-name check
53
55
  * (`plugins.ts`) reject that package - a load `failures` entry, never an
54
56
  * installed plugin - so `blogwright pds <action>` would exit 1 with `no
@@ -62,12 +64,15 @@
62
64
  export const KNOWN_COMMANDS = new Set([
63
65
  'bootstrap',
64
66
  'deploy',
67
+ 'stage',
68
+ 'promote',
65
69
  'rollback',
66
70
  'delete',
67
71
  'destroy',
68
72
  'history',
69
73
  'logs',
70
74
  'status',
75
+ 'verify',
71
76
  'plugin',
72
77
  ]);
73
78
  export const RESERVED_COMMANDS = new Set([
@@ -75,4 +80,5 @@ export const RESERVED_COMMANDS = new Set([
75
80
  'init',
76
81
  'preview',
77
82
  'plugin',
83
+ 'whoami',
78
84
  ]);
@@ -0,0 +1,78 @@
1
+ /**
2
+ * The live-release record (`build/live-release.json`): which recorded release
3
+ * the last deploy, promote or rollback published to `site/`, so the next
4
+ * promotion can name the release it replaces. It records what blogwright did,
5
+ * not what S3 holds - `blogwright verify` is the reading of S3.
6
+ *
7
+ * Before a command starts changing `site/` it marks the record `publishing`,
8
+ * keeping the release it replaces as `previous`, and only a command that
9
+ * finished turns it back into a live release. A command that stops partway
10
+ * therefore leaves "a publish of X stopped partway", never the old release's
11
+ * name over a `site/` that no longer holds it.
12
+ */
13
+ import type { ArtifactManifest } from 'blogwright-core';
14
+ import type { OpsContext } from './context.js';
15
+ export declare const LIVE_RELEASE_KEY = "build/live-release.json";
16
+ /** The command that published a live release, or emptied `site/`. */
17
+ export type LiveReleaseSource = 'deploy' | 'promote' | 'rollback' | 'delete';
18
+ /** A release a command finished publishing to `site/`. */
19
+ interface LiveRelease {
20
+ hash: string;
21
+ release: string;
22
+ releaseHash: string;
23
+ publishedAt: string;
24
+ via: LiveReleaseSource;
25
+ }
26
+ /**
27
+ * A command is changing `site/`, or stopped partway through changing it: what
28
+ * `site/` holds is unknown until a command finishes.
29
+ */
30
+ interface PublishingLiveRelease {
31
+ status: 'publishing';
32
+ /** The revision being published; absent when `site/` is being emptied. */
33
+ hash?: string | undefined;
34
+ via: LiveReleaseSource;
35
+ startedAt: string;
36
+ /** The last release a command finished publishing before this one began. */
37
+ previous?: LiveRelease | undefined;
38
+ }
39
+ export type LiveReleaseRecord = LiveRelease | PublishingLiveRelease;
40
+ /** Whether a record names a release a command finished publishing. */
41
+ export declare function isSettledLiveRelease(record: LiveReleaseRecord | undefined): record is LiveRelease;
42
+ /**
43
+ * The live-release record, or undefined when none is recorded. The record is
44
+ * informational, so an unreadable one is reported and treated as absent
45
+ * rather than failing the command that wanted to name it.
46
+ */
47
+ export declare function readLiveRelease(ctx: OpsContext): Promise<LiveReleaseRecord | undefined>;
48
+ /**
49
+ * Mark `site/` as changing before a command touches it. The release it
50
+ * replaces is kept as `previous` - carried over from an earlier publish that
51
+ * stopped partway, so it always names the last release a command finished.
52
+ */
53
+ export declare function markLiveReleasePublishing(ctx: OpsContext, hash: string | undefined, via: LiveReleaseSource): Promise<void>;
54
+ /** Record that `manifest`'s release is now what `site/` holds. */
55
+ export declare function recordLiveRelease(ctx: OpsContext, manifest: ArtifactManifest, via: LiveReleaseSource): Promise<void>;
56
+ /** Drop the record when `site/` changed in a way no artifact manifest describes. */
57
+ export declare function forgetLiveRelease(ctx: OpsContext): Promise<void>;
58
+ /** One line naming the live release, for a before/after report. */
59
+ export declare function describeLiveRelease(live: LiveReleaseRecord | undefined): string;
60
+ /** How many publications a revision's record keeps - the newest ones. */
61
+ export declare const PUBLISHED_RELEASES_KEPT = 50;
62
+ /** One publication of a staged release into `site/`. */
63
+ export interface ReleasePublication {
64
+ release: string;
65
+ releaseHash: string;
66
+ via: Extract<LiveReleaseSource, 'promote' | 'rollback'>;
67
+ publishedAt: string;
68
+ }
69
+ export declare function publishedReleasesKey(hash: string): string;
70
+ /**
71
+ * A revision's publications, oldest first; empty when none is recorded. Like
72
+ * the live-release record it is informational, so an unreadable one is
73
+ * reported and read as empty.
74
+ */
75
+ export declare function readPublications(ctx: OpsContext, hash: string): Promise<ReleasePublication[]>;
76
+ /** Append a publication of `manifest`'s release to its revision's record. */
77
+ export declare function recordPublication(ctx: OpsContext, manifest: ArtifactManifest, via: ReleasePublication['via']): Promise<void>;
78
+ export {};
@@ -0,0 +1,159 @@
1
+ /**
2
+ * The live-release record (`build/live-release.json`): which recorded release
3
+ * the last deploy, promote or rollback published to `site/`, so the next
4
+ * promotion can name the release it replaces. It records what blogwright did,
5
+ * not what S3 holds - `blogwright verify` is the reading of S3.
6
+ *
7
+ * Before a command starts changing `site/` it marks the record `publishing`,
8
+ * keeping the release it replaces as `previous`, and only a command that
9
+ * finished turns it back into a live release. A command that stops partway
10
+ * therefore leaves "a publish of X stopped partway", never the old release's
11
+ * name over a `site/` that no longer holds it.
12
+ */
13
+ export const LIVE_RELEASE_KEY = 'build/live-release.json';
14
+ function isRecordObject(value) {
15
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
16
+ }
17
+ function isLiveRelease(value) {
18
+ if (!isRecordObject(value) || value.status !== undefined)
19
+ return false;
20
+ return ['hash', 'release', 'releaseHash', 'publishedAt', 'via'].every((field) => typeof value[field] === 'string');
21
+ }
22
+ function isPublishing(value) {
23
+ if (!isRecordObject(value) || value.status !== 'publishing')
24
+ return false;
25
+ return (typeof value.via === 'string' &&
26
+ typeof value.startedAt === 'string' &&
27
+ (value.hash === undefined || typeof value.hash === 'string') &&
28
+ (value.previous === undefined || isLiveRelease(value.previous)));
29
+ }
30
+ /** Whether a record names a release a command finished publishing. */
31
+ export function isSettledLiveRelease(record) {
32
+ return record !== undefined && !('status' in record);
33
+ }
34
+ /**
35
+ * The live-release record, or undefined when none is recorded. The record is
36
+ * informational, so an unreadable one is reported and treated as absent
37
+ * rather than failing the command that wanted to name it.
38
+ */
39
+ export async function readLiveRelease(ctx) {
40
+ const text = await ctx.clients.s3.getObjectText(ctx.names.bucket, LIVE_RELEASE_KEY);
41
+ if (text === undefined)
42
+ return undefined;
43
+ let parsed;
44
+ try {
45
+ parsed = JSON.parse(text);
46
+ }
47
+ catch {
48
+ parsed = undefined;
49
+ }
50
+ if (isLiveRelease(parsed) || isPublishing(parsed))
51
+ return parsed;
52
+ ctx.logger.warn(`ignoring unreadable live-release record s3://${ctx.names.bucket}/${LIVE_RELEASE_KEY}`);
53
+ return undefined;
54
+ }
55
+ async function writeLiveRelease(ctx, record) {
56
+ await ctx.clients.s3.putObject(ctx.names.bucket, LIVE_RELEASE_KEY, JSON.stringify(record, null, 2), 'application/json');
57
+ }
58
+ /**
59
+ * Mark `site/` as changing before a command touches it. The release it
60
+ * replaces is kept as `previous` - carried over from an earlier publish that
61
+ * stopped partway, so it always names the last release a command finished.
62
+ */
63
+ export async function markLiveReleasePublishing(ctx, hash, via) {
64
+ const current = await readLiveRelease(ctx);
65
+ const previous = isSettledLiveRelease(current) ? current : current?.previous;
66
+ await writeLiveRelease(ctx, {
67
+ status: 'publishing',
68
+ ...(hash ? { hash } : {}),
69
+ via,
70
+ startedAt: new Date().toISOString(),
71
+ ...(previous ? { previous } : {}),
72
+ });
73
+ }
74
+ /** Record that `manifest`'s release is now what `site/` holds. */
75
+ export async function recordLiveRelease(ctx, manifest, via) {
76
+ await writeLiveRelease(ctx, {
77
+ hash: manifest.hash,
78
+ release: manifest.release,
79
+ releaseHash: manifest.releaseHash,
80
+ publishedAt: new Date().toISOString(),
81
+ via,
82
+ });
83
+ }
84
+ /** Drop the record when `site/` changed in a way no artifact manifest describes. */
85
+ export async function forgetLiveRelease(ctx) {
86
+ await ctx.clients.s3.deleteObject(ctx.names.bucket, LIVE_RELEASE_KEY);
87
+ }
88
+ /** One line naming the live release, for a before/after report. */
89
+ export function describeLiveRelease(live) {
90
+ if (live === undefined) {
91
+ return ('unknown - no live-release record: site/ was last published before blogwright ' +
92
+ 'recorded releases, by a build that recorded no artifact manifest, or not at all');
93
+ }
94
+ if (isSettledLiveRelease(live))
95
+ return `${live.release} (sha256 ${live.releaseHash})`;
96
+ const what = live.hash ? `a ${live.via} of ${live.hash}` : `a ${live.via}`;
97
+ const before = live.previous
98
+ ? `; the last completed release was ${live.previous.release} (sha256 ${live.previous.releaseHash})`
99
+ : '';
100
+ return `unknown (${what} started ${live.startedAt} did not finish${before})`;
101
+ }
102
+ /**
103
+ * Every staged release a `promote` or a republishing `rollback` published for
104
+ * a revision (`build/published/<hash>.json`), oldest first. `stage` never
105
+ * writes it, so it outlives a re-stage of the same revision: the record of
106
+ * what was actually live is kept even after the staged bytes are replaced.
107
+ */
108
+ const PUBLISHED_RELEASES_PREFIX = 'build/published/';
109
+ /** How many publications a revision's record keeps - the newest ones. */
110
+ export const PUBLISHED_RELEASES_KEPT = 50;
111
+ export function publishedReleasesKey(hash) {
112
+ return `${PUBLISHED_RELEASES_PREFIX}${hash}.json`;
113
+ }
114
+ function isPublication(value) {
115
+ return (isRecordObject(value) &&
116
+ ['release', 'releaseHash', 'via', 'publishedAt'].every((field) => typeof value[field] === 'string'));
117
+ }
118
+ function isPublishedReleases(value) {
119
+ return (isRecordObject(value) &&
120
+ typeof value.hash === 'string' &&
121
+ Array.isArray(value.publications) &&
122
+ value.publications.every(isPublication));
123
+ }
124
+ /**
125
+ * A revision's publications, oldest first; empty when none is recorded. Like
126
+ * the live-release record it is informational, so an unreadable one is
127
+ * reported and read as empty.
128
+ */
129
+ export async function readPublications(ctx, hash) {
130
+ const key = publishedReleasesKey(hash);
131
+ const text = await ctx.clients.s3.getObjectText(ctx.names.bucket, key);
132
+ if (text === undefined)
133
+ return [];
134
+ let parsed;
135
+ try {
136
+ parsed = JSON.parse(text);
137
+ }
138
+ catch {
139
+ parsed = undefined;
140
+ }
141
+ if (isPublishedReleases(parsed) && parsed.hash === hash)
142
+ return parsed.publications;
143
+ ctx.logger.warn(`ignoring unreadable publication record s3://${ctx.names.bucket}/${key}`);
144
+ return [];
145
+ }
146
+ /** Append a publication of `manifest`'s release to its revision's record. */
147
+ export async function recordPublication(ctx, manifest, via) {
148
+ const publications = [
149
+ ...(await readPublications(ctx, manifest.hash)),
150
+ {
151
+ release: manifest.release,
152
+ releaseHash: manifest.releaseHash,
153
+ via,
154
+ publishedAt: new Date().toISOString(),
155
+ },
156
+ ].slice(-PUBLISHED_RELEASES_KEPT);
157
+ const record = { hash: manifest.hash, publications };
158
+ await ctx.clients.s3.putObject(ctx.names.bucket, publishedReleasesKey(manifest.hash), JSON.stringify(record, null, 2), 'application/json');
159
+ }
package/dist/lock.d.ts ADDED
@@ -0,0 +1,50 @@
1
+ /**
2
+ * The environment lock (`build/lock.json`): one command at a time may write
3
+ * an environment's live `site/` or its live-release record. `deploy`,
4
+ * `rollback`, `stage`, `promote` and `delete` take it before they change
5
+ * anything and release it when they finish, failed or not, so two of them can
6
+ * never interleave their writes - a deploy's builder listing `site/` while a
7
+ * promotion copies into it, or two deploys racing for the same objects.
8
+ *
9
+ * The lock is a conditional PUT (`If-None-Match: *`), so exactly one caller
10
+ * creates it. A command that dies without releasing it - a killed CI job, a
11
+ * closed laptop - leaves it behind; the next command refuses, naming who held
12
+ * it, for what and since when, and `--force-unlock` replaces it once that
13
+ * holder is known to be gone. Nothing expires it on a timer: a long build is
14
+ * indistinguishable from a dead one, and guessing wrong would re-open the race.
15
+ */
16
+ import type { OpsContext } from './context.js';
17
+ /** Where an environment's lock lives - outside every builder grant. */
18
+ export declare const ENV_LOCK_KEY = "build/lock.json";
19
+ /** Who holds an environment's lock, and for what. */
20
+ export interface EnvLock {
21
+ /** Unique per acquisition: release deletes the lock only while it is still this one. */
22
+ id: string;
23
+ /** The AWS identity (`sts:GetCallerIdentity` ARN) that took it. */
24
+ holder: string;
25
+ /** The command that took it, e.g. `promote`. */
26
+ command: string;
27
+ /** The revision the command is publishing, when it has one. */
28
+ hash?: string | undefined;
29
+ /** When it was taken (ISO-8601). */
30
+ startedAt: string;
31
+ }
32
+ export interface LockOptions {
33
+ /** Replace a lock left behind by a command that is no longer running. */
34
+ forceUnlock?: boolean | undefined;
35
+ }
36
+ /**
37
+ * Take the environment's lock for `command`, or throw naming whoever holds
38
+ * it. With `forceUnlock`, a held lock is first removed, with a warning.
39
+ */
40
+ export declare function acquireEnvLock(ctx: OpsContext, command: string, hash: string | undefined, opts?: LockOptions): Promise<EnvLock>;
41
+ /**
42
+ * Release `lock` if it is still the one held. A lock replaced by
43
+ * `--force-unlock` belongs to someone else now and is left alone. Never
44
+ * throws: the command's own outcome must not be masked by its cleanup.
45
+ */
46
+ export declare function releaseEnvLock(ctx: OpsContext, lock: EnvLock): Promise<void>;
47
+ /** Run `fn` holding the environment's lock, releasing it however `fn` ends. */
48
+ export declare function withEnvLock<T>(ctx: OpsContext, command: string, hash: string | undefined, opts: LockOptions, fn: () => Promise<T>): Promise<T>;
49
+ /** Refuse when the environment is locked - for `destroy`, which removes the lock with the bucket. */
50
+ export declare function assertEnvUnlocked(ctx: OpsContext, command: string, opts?: LockOptions): Promise<void>;