blogwright 0.4.0-beta.5 → 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/cli.js CHANGED
@@ -5,8 +5,11 @@ import { cliPackageDir, cliVersion } from './context.js';
5
5
  import { initSite } from './init.js';
6
6
  import { KNOWN_COMMANDS } from './known-commands.js';
7
7
  import { createLogger } from './logger.js';
8
- import { genericLifecycleActions, runPlugin, runPluginNamespace } from './plugin-commands.js';
8
+ import { genericLifecycleActions, runAfterDeployHooks, runPlugin, runPluginNamespace, } from './plugin-commands.js';
9
9
  import { discover } from './plugins.js';
10
+ import { promote, stage } from './releases.js';
11
+ import { verify } from './verify.js';
12
+ import { whoami } from './whoami.js';
10
13
  const USAGE = `blogwright - full operations for a blog site on AWS (S3 + CloudFront, MicroVM builds)
11
14
 
12
15
  Usage:
@@ -18,12 +21,23 @@ Commands:
18
21
  (--switch-mode: move a bootstrapped stack
19
22
  between static and SSR serving)
20
23
  deploy [env] Zip the repo, build in a MicroVM, publish to site/
21
- rollback <hash> [env] Re-deploy an existing build by hash
24
+ stage [env] Build like deploy, but publish to releases/<hash>/
25
+ (not served) for a later promote
26
+ promote <hash> [env] Copy a staged release into site/ without
27
+ rebuilding, invalidate, and verify it
28
+ rollback <hash> [env] Republish a staged release (verified, no
29
+ rebuild), else rebuild the hash's archived source
30
+ (--rebuild: always rebuild)
22
31
  delete [env] Empty the live site/ prefix
23
32
  destroy [env] --yes Tear down all infrastructure
24
33
  history [env] List deployment history
25
34
  logs <hash> [env] Show CloudWatch build logs for a hash
26
35
  status [env] Show planned graph vs. live state
36
+ verify <hash> [env] Check the live site/ (or, with --staged, the
37
+ staged copy) byte for byte against the artifact
38
+ manifest recorded for a hash
39
+ whoami [env] Show the AWS account, identity and profile in
40
+ use, and whether the account pin accepts them
27
41
 
28
42
  preview bootstrap Provision the shared preview stack
29
43
  preview deploy <id> Build + publish a PR preview (id like pr-42)
@@ -43,17 +57,27 @@ Options:
43
57
  --domain <fqdn> Custom domain (ACM cert + CloudFront alias)
44
58
  --config <path> Path to a JSONC config file
45
59
  --endpoint <url> AWS endpoint override (e.g. http://localhost:4566 for floci)
60
+ --profile <name> AWS profile from the shared AWS files (beats AWS_PROFILE,
61
+ exported credentials and the config's aws.profile)
46
62
  --id <preview> Preview id for preview deploy/destroy (also accepted positionally)
47
63
  --plain Minimal machine-friendly output (no colour, no live status,
48
64
  no prompts) - for CI systems and agents; also automatic when
49
65
  output is piped. NO_COLOR disables colour only.
50
- --refresh Re-upload every file on deploy, even unchanged ones, so
51
- metadata fixes (content types, object tags) reach live
52
- objects the ETag comparison would otherwise skip.
66
+ --refresh Re-upload every file on deploy, rollback or stage (copy
67
+ every file on promote), even unchanged ones, so metadata
68
+ fixes (content types, object tags) reach objects the
69
+ ETag comparison would otherwise skip.
70
+ --force-unlock Replace the environment lock a deploy, rollback, stage,
71
+ promote or delete left behind when it stopped; only once
72
+ that command is known to be no longer running
53
73
  --switch-mode Allow bootstrap to change a bootstrapped stack between
54
74
  static and SSR serving. Without it that cutover is
55
75
  refused, because the distribution moves before a deploy
56
76
  in the new mode exists.
77
+ --staged verify the release staged under releases/<hash>/ instead
78
+ of the live site/
79
+ --rebuild rollback: rebuild from the archived source even when the
80
+ hash has a staged release
57
81
  --yes Confirm destructive operations
58
82
  --help Show this help
59
83
  `;
@@ -199,8 +223,34 @@ async function helpText(ports) {
199
223
  }
200
224
  return buildHelp(USAGE, discovered);
201
225
  }
202
- const HASH_COMMANDS = new Set(['rollback', 'logs']);
203
- export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts, makePackages) {
226
+ const HASH_COMMANDS = new Set(['rollback', 'logs', 'verify', 'promote']);
227
+ /**
228
+ * The `<hash> [env]` arguments of a hash-first command. Without `--hash` the
229
+ * first positional is the hash and the second the environment; with it, the
230
+ * hash is taken and the first positional is the environment. A hash given both
231
+ * ways is refused rather than guessed at, and so is a missing one.
232
+ */
233
+ /** What a revision hash may contain: jj and git print short hex ids. */
234
+ const REVISION_HASH = /^[0-9A-Za-z]{1,64}$/;
235
+ function hashArguments(command, flagHash, positionals) {
236
+ const [, first, second] = positionals;
237
+ if (flagHash !== undefined && second !== undefined) {
238
+ throw new Error(`${command} was given --hash ${flagHash} and two positionals ("${first}", "${second}"): ` +
239
+ `with --hash, the only positional is the environment - \`blogwright ${command} ` +
240
+ `--hash ${flagHash} <env>\``);
241
+ }
242
+ const hash = flagHash ?? first;
243
+ if (!hash)
244
+ throw new Error(`${command} requires a <hash>`);
245
+ // The hash names S3 keys (build/<hash>.zip, releases/<hash>/), so only the
246
+ // characters jj and git print are accepted - never a "/" or "..".
247
+ if (!REVISION_HASH.test(hash)) {
248
+ throw new Error(`${command} needs a revision hash of letters and digits (as \`blogwright history\` ` +
249
+ `lists them), got "${hash}"`);
250
+ }
251
+ return { hash, envPositional: flagHash === undefined ? second : first };
252
+ }
253
+ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts, makePackages, makeAwsAccess) {
204
254
  const { values, positionals } = parseArgs({
205
255
  args: argv,
206
256
  allowPositionals: true,
@@ -209,6 +259,7 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
209
259
  domain: { type: 'string' },
210
260
  config: { type: 'string' },
211
261
  endpoint: { type: 'string' },
262
+ profile: { type: 'string' },
212
263
  hash: { type: 'string' },
213
264
  id: { type: 'string' },
214
265
  // Declared here even though no built-in command reads it. `main`
@@ -229,6 +280,9 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
229
280
  // is declared kebab-case and read back the same way, because the camel
230
281
  // form would reject the flag the usage text and docs advertise.
231
282
  'switch-mode': { type: 'boolean', default: false },
283
+ 'force-unlock': { type: 'boolean', default: false },
284
+ staged: { type: 'boolean', default: false },
285
+ rebuild: { type: 'boolean', default: false },
232
286
  yes: { type: 'boolean', default: false },
233
287
  help: { type: 'boolean', default: false },
234
288
  },
@@ -250,7 +304,9 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
250
304
  // importing - every installed plugin's module for a command that was
251
305
  // always going to decline; `makeDiscoveryPorts()` above is cheap
252
306
  // (adapter construction only, no I/O), unlike `discover` itself.
253
- return initSite(discoveryPorts.fs, terminal, logger, []);
307
+ return initSite(discoveryPorts.fs, terminal, logger, [], {
308
+ aws: { profile: values.profile, ...makeAwsAccess() },
309
+ });
254
310
  }
255
311
  // Runs before any context exists - there is no config to load yet.
256
312
  // `init` is one of the four discovery-running paths `DiscoveryPortsFactory`
@@ -286,13 +342,28 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
286
342
  throw err;
287
343
  logger.warn(`${err.message} - continuing with no plugins discovered`);
288
344
  }
289
- return initSite(discoveryPorts.fs, terminal, logger, plugins, repoRoot);
345
+ return initSite(discoveryPorts.fs, terminal, logger, plugins, {
346
+ root: repoRoot,
347
+ aws: { profile: values.profile, ...makeAwsAccess() },
348
+ });
349
+ }
350
+ if (command === 'whoami') {
351
+ // Dispatched beside `init`, before the `makeContext` call below: it
352
+ // resolves the same AWS session but loads no state, and it must work
353
+ // before the repo has a config at all.
354
+ const { host, awsLogin } = makeAwsAccess();
355
+ return whoami({
356
+ env: values.env ?? positionals[1] ?? 'production',
357
+ configPath: values.config,
358
+ profile: values.profile,
359
+ endpointOverride: values.endpoint,
360
+ }, { fs: makeDiscoveryPorts().fs, terminal, logger, awsLogin, host });
290
361
  }
291
362
  if (command === 'plugin') {
292
363
  // Dispatched HERE, beside `init` and ahead of the built-in switch, and
293
364
  // never from the switch itself: the switch runs past the `makeContext`
294
365
  // call below, which loads the environment's config and calls
295
- // `sts.getAccountId()`. `blogwright plugin list` and `plugin add` are what
366
+ // `sts:GetCallerIdentity`. `blogwright plugin list` and `plugin add` are what
296
367
  // an operator runs BEFORE the repo is configured, so dispatching them
297
368
  // after that build would answer both with `no config found for
298
369
  // environment "production"` on exactly the repo they exist to serve -
@@ -324,24 +395,22 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
324
395
  //
325
396
  // TASK 29 - this is now the ONLY route into a plugin's namespace. The
326
397
  // hardcoded branch that used to sit immediately above this membership
327
- // test, ahead of it precisely so it would win, is gone: the bundled
328
- // plugin the CLI ships in its own `dependencies` is discovered and
329
- // dispatched here exactly like an installed one, which is why the name
330
- // it claims stays out of `RESERVED_COMMANDS` (`known-commands.ts`).
398
+ // test, ahead of it precisely so it would win, is gone: the pds plugin a
399
+ // site installs is discovered and dispatched here exactly like any
400
+ // other, which is why the name it claims stays out of
401
+ // `RESERVED_COMMANDS` (`known-commands.ts`).
331
402
  // This module knows no namespace by name any more, and adding one back
332
403
  // would re-open the split where `--help` advertised verbs the
333
404
  // hand-rolled branch refused.
334
405
  return runPlugin(command, positionals.slice(1), values, terminal, logger, makeContext, makeDiscoveryPorts());
335
406
  }
336
- // Positional layout: rollback/logs take <hash> first, then optional env.
337
- let hash;
338
- let envPositional;
407
+ // Positional layout: rollback/logs/verify/promote take <hash> first, then optional
408
+ // env. Their hash is checked here, before any context is built; the other
409
+ // commands never read `hash`.
410
+ let hash = '';
411
+ let envPositional = positionals[1];
339
412
  if (HASH_COMMANDS.has(command)) {
340
- hash = values.hash ?? positionals[1];
341
- envPositional = positionals[2];
342
- }
343
- else {
344
- envPositional = positionals[1];
413
+ ({ hash, envPositional } = hashArguments(command, values.hash, positionals));
345
414
  }
346
415
  const env = values.env ?? envPositional ?? 'production';
347
416
  const ctx = await makeContext({
@@ -349,6 +418,7 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
349
418
  configPath: values.config,
350
419
  domain: values.domain,
351
420
  endpointOverride: values.endpoint,
421
+ profile: values.profile,
352
422
  ports: { terminal },
353
423
  });
354
424
  switch (command) {
@@ -356,33 +426,53 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
356
426
  await commands.bootstrap(ctx, undefined, { switchMode: values['switch-mode'] });
357
427
  break;
358
428
  case 'deploy':
359
- await commands.deploy(ctx, { refresh: values.refresh });
429
+ // Discovery runs only once the site is live, through the same factory
430
+ // plugin dispatch uses - a deploy that fails never loads a plugin.
431
+ await commands.deploy(ctx, {
432
+ refresh: values.refresh,
433
+ forceUnlock: values['force-unlock'],
434
+ afterDeploy: (deployed) => runAfterDeployHooks(deployed, makeDiscoveryPorts()),
435
+ });
436
+ break;
437
+ case 'stage':
438
+ await stage(ctx, { refresh: values.refresh, forceUnlock: values['force-unlock'] });
439
+ break;
440
+ case 'promote':
441
+ await promote(ctx, hash, {
442
+ refresh: values.refresh,
443
+ forceUnlock: values['force-unlock'],
444
+ afterDeploy: (promoted) => runAfterDeployHooks(promoted, makeDiscoveryPorts()),
445
+ });
360
446
  break;
361
447
  case 'rollback':
362
- if (!hash)
363
- throw new Error('rollback requires a <hash>');
364
- await commands.rollback(ctx, hash, { refresh: values.refresh });
448
+ await commands.rollback(ctx, hash, {
449
+ refresh: values.refresh,
450
+ rebuild: values.rebuild,
451
+ forceUnlock: values['force-unlock'],
452
+ afterDeploy: (rolledBack) => runAfterDeployHooks(rolledBack, makeDiscoveryPorts()),
453
+ });
365
454
  break;
366
455
  case 'delete':
367
- await commands.deleteSite(ctx);
456
+ await commands.deleteSite(ctx, { forceUnlock: values['force-unlock'] });
368
457
  break;
369
458
  case 'destroy':
370
- await commands.destroy(ctx, { yes: values.yes });
459
+ await commands.destroy(ctx, { yes: values.yes, forceUnlock: values['force-unlock'] });
371
460
  break;
372
461
  case 'history':
373
462
  await commands.history(ctx);
374
463
  break;
375
464
  case 'logs':
376
- if (!hash)
377
- throw new Error('logs requires a <hash>');
378
465
  await commands.logs(ctx, hash);
379
466
  break;
380
467
  case 'status':
381
468
  await commands.status(ctx);
382
469
  break;
470
+ case 'verify':
471
+ await verify(ctx, hash, values.staged ? 'staged' : 'live');
472
+ break;
383
473
  default:
384
474
  // Unreachable: past the `KNOWN_COMMANDS` membership test above,
385
- // `command` is one of the nine names in that set, and the `plugin`
475
+ // `command` is one of the names in that set, and the `plugin`
386
476
  // branch has already claimed the only one without a case here. Kept
387
477
  // wired to the same help text as every other USAGE print site - like
388
478
  // `runPreview`'s own unreachable default below - so it stays correct
@@ -409,6 +499,7 @@ async function runPreview(positionals, values, terminal, logger, makeContext, ma
409
499
  configPath: values.config,
410
500
  domain: values.domain,
411
501
  endpointOverride: values.endpoint,
502
+ profile: values.profile,
412
503
  ports: { terminal },
413
504
  });
414
505
  switch (action) {
@@ -1,6 +1,8 @@
1
1
  import { type ResourceNode } from 'blogwright-core';
2
2
  import type { OpsContext } from './context.js';
3
+ import { type AfterDeploy } from './deploy.js';
3
4
  import { type GraphContext } from './graph.js';
5
+ import { type LockOptions } from './lock.js';
4
6
  import { type StatusEntry } from './render.js';
5
7
  /**
6
8
  * Refuse a silent serving-mode switch on a bootstrapped stack unless
@@ -65,15 +67,45 @@ export declare function assertNoScopedState(ctx: OpsContext): Promise<void>;
65
67
  /** Destroy the full infrastructure graph. */
66
68
  export declare function destroy(ctx: OpsContext, opts: {
67
69
  yes: boolean;
68
- }): Promise<void>;
69
- /** Zip the repo, upload it, run the builder MicroVM, and invalidate the cache. */
70
- export declare function deploy(ctx: OpsContext, opts?: {
71
- refresh?: boolean;
72
- }): Promise<void>;
73
- /** Re-run the builder against an existing source zip for the given hash. */
74
- export declare function rollback(ctx: OpsContext, hash: string, opts?: {
70
+ } & LockOptions): Promise<void>;
71
+ export type { AfterDeploy } from './deploy.js';
72
+ export interface DeployOptions extends LockOptions {
75
73
  refresh?: boolean;
76
- }): Promise<void>;
74
+ /**
75
+ * Runs once the site is published and the cache invalidated: `cli.ts`
76
+ * passes `runAfterDeployHooks` (`plugin-commands.ts`), which runs every
77
+ * installed plugin's `afterDeploy` hook. Injected rather than imported
78
+ * because plugin dispatch already imports this module, and required so the
79
+ * one production caller cannot silently drop the hooks. It must not throw
80
+ * for a plugin's sake - the deploy has already succeeded.
81
+ */
82
+ afterDeploy: AfterDeploy;
83
+ }
84
+ /** Zip the repo, upload it, run the builder MicroVM, and invalidate the cache. */
85
+ export declare function deploy(ctx: OpsContext, opts: DeployOptions): Promise<void>;
86
+ export interface RollbackOptions extends LockOptions {
87
+ /** Re-upload (or, republishing, copy) every file, even unchanged ones. */
88
+ refresh?: boolean | undefined;
89
+ /**
90
+ * Static environments: rebuild from the archived source even when the hash
91
+ * has a staged release - the way out when its staged copy can no longer be
92
+ * republished.
93
+ */
94
+ rebuild?: boolean | undefined;
95
+ /**
96
+ * The post-deploy plugin steps, run only when the working copy is the
97
+ * rolled-back revision - the same rule as `promote`; see
98
+ * {@link runAfterPublish}.
99
+ */
100
+ afterDeploy: AfterDeploy;
101
+ }
102
+ /**
103
+ * Roll back to a hash. In a static environment a hash with a staged release
104
+ * is republished from its stored bytes, and any other - or any, with
105
+ * `--rebuild` - is rebuilt from its archived source zip; an SSR environment
106
+ * reproduces the recorded revision.
107
+ */
108
+ export declare function rollback(ctx: OpsContext, hash: string, opts: RollbackOptions): Promise<void>;
77
109
  /** Provision the shared preview stack (one CloudFront distribution + host router + OIDC role). */
78
110
  export declare function previewBootstrap(ctx: OpsContext): Promise<void>;
79
111
  /** Build the current repo and publish it to this PR's preview prefix. Prints the URL. */
@@ -89,7 +121,7 @@ export declare function previewTeardown(ctx: OpsContext, opts: {
89
121
  yes: boolean;
90
122
  }): Promise<void>;
91
123
  /** Empty the live site/ prefix (leaves infra and build history intact). */
92
- export declare function deleteSite(ctx: OpsContext): Promise<void>;
124
+ export declare function deleteSite(ctx: OpsContext, opts?: LockOptions): Promise<void>;
93
125
  /** List deployment history from build manifests. */
94
126
  export declare function history(ctx: OpsContext): Promise<void>;
95
127
  /** Show CloudWatch build logs for a given hash. */