blogwright 0.4.0 → 0.6.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 (56) 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/node-dns.d.ts +20 -0
  5. package/dist/adapters/node-dns.js +49 -0
  6. package/dist/adapters/process-aws-login.d.ts +19 -0
  7. package/dist/adapters/process-aws-login.js +28 -0
  8. package/dist/agent-package.js +2 -3
  9. package/dist/artifacts.d.ts +73 -0
  10. package/dist/artifacts.js +218 -0
  11. package/dist/aws-session.d.ts +118 -0
  12. package/dist/aws-session.js +360 -0
  13. package/dist/bin.js +6 -2
  14. package/dist/cache-control.d.ts +66 -0
  15. package/dist/cache-control.js +176 -0
  16. package/dist/cli.d.ts +22 -3
  17. package/dist/cli.js +128 -31
  18. package/dist/commands.d.ts +41 -9
  19. package/dist/commands.js +135 -126
  20. package/dist/context.d.ts +42 -5
  21. package/dist/context.js +81 -19
  22. package/dist/deploy.d.ts +78 -6
  23. package/dist/deploy.js +136 -52
  24. package/dist/domains.d.ts +46 -0
  25. package/dist/domains.js +125 -0
  26. package/dist/init.d.ts +14 -2
  27. package/dist/init.js +145 -4
  28. package/dist/known-commands.d.ts +11 -9
  29. package/dist/known-commands.js +15 -9
  30. package/dist/live-release.d.ts +78 -0
  31. package/dist/live-release.js +159 -0
  32. package/dist/lock.d.ts +50 -0
  33. package/dist/lock.js +120 -0
  34. package/dist/nodes.d.ts +18 -0
  35. package/dist/nodes.js +721 -76
  36. package/dist/plugin-commands.d.ts +21 -0
  37. package/dist/plugin-commands.js +54 -3
  38. package/dist/plugins.d.ts +11 -9
  39. package/dist/plugins.js +29 -16
  40. package/dist/ports.d.ts +37 -1
  41. package/dist/releases.d.ts +54 -0
  42. package/dist/releases.js +527 -0
  43. package/dist/render.d.ts +18 -1
  44. package/dist/render.js +38 -6
  45. package/dist/repo.js +2 -3
  46. package/dist/rkey.d.ts +4 -3
  47. package/dist/rkey.js +4 -3
  48. package/dist/router-function.d.ts +24 -0
  49. package/dist/router-function.js +71 -0
  50. package/dist/serving.d.ts +28 -0
  51. package/dist/serving.js +47 -0
  52. package/dist/verify.d.ts +45 -0
  53. package/dist/verify.js +183 -0
  54. package/dist/whoami.d.ts +23 -0
  55. package/dist/whoami.js +88 -0
  56. 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,31 @@ 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
73
+ --prune-aliases With bootstrap: detach attached CloudFront aliases that
74
+ the config does not name. Without it they are reported
75
+ and left attached, so a config edit never drops a
76
+ live hostname.
53
77
  --switch-mode Allow bootstrap to change a bootstrapped stack between
54
78
  static and SSR serving. Without it that cutover is
55
79
  refused, because the distribution moves before a deploy
56
80
  in the new mode exists.
81
+ --staged verify the release staged under releases/<hash>/ instead
82
+ of the live site/
83
+ --rebuild rollback: rebuild from the archived source even when the
84
+ hash has a staged release
57
85
  --yes Confirm destructive operations
58
86
  --help Show this help
59
87
  `;
@@ -199,8 +227,34 @@ async function helpText(ports) {
199
227
  }
200
228
  return buildHelp(USAGE, discovered);
201
229
  }
202
- const HASH_COMMANDS = new Set(['rollback', 'logs']);
203
- export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts, makePackages) {
230
+ const HASH_COMMANDS = new Set(['rollback', 'logs', 'verify', 'promote']);
231
+ /**
232
+ * The `<hash> [env]` arguments of a hash-first command. Without `--hash` the
233
+ * first positional is the hash and the second the environment; with it, the
234
+ * hash is taken and the first positional is the environment. A hash given both
235
+ * ways is refused rather than guessed at, and so is a missing one.
236
+ */
237
+ /** What a revision hash may contain: jj and git print short hex ids. */
238
+ const REVISION_HASH = /^[0-9A-Za-z]{1,64}$/;
239
+ function hashArguments(command, flagHash, positionals) {
240
+ const [, first, second] = positionals;
241
+ if (flagHash !== undefined && second !== undefined) {
242
+ throw new Error(`${command} was given --hash ${flagHash} and two positionals ("${first}", "${second}"): ` +
243
+ `with --hash, the only positional is the environment - \`blogwright ${command} ` +
244
+ `--hash ${flagHash} <env>\``);
245
+ }
246
+ const hash = flagHash ?? first;
247
+ if (!hash)
248
+ throw new Error(`${command} requires a <hash>`);
249
+ // The hash names S3 keys (build/<hash>.zip, releases/<hash>/), so only the
250
+ // characters jj and git print are accepted - never a "/" or "..".
251
+ if (!REVISION_HASH.test(hash)) {
252
+ throw new Error(`${command} needs a revision hash of letters and digits (as \`blogwright history\` ` +
253
+ `lists them), got "${hash}"`);
254
+ }
255
+ return { hash, envPositional: flagHash === undefined ? second : first };
256
+ }
257
+ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts, makePackages, makeAwsAccess) {
204
258
  const { values, positionals } = parseArgs({
205
259
  args: argv,
206
260
  allowPositionals: true,
@@ -209,6 +263,7 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
209
263
  domain: { type: 'string' },
210
264
  config: { type: 'string' },
211
265
  endpoint: { type: 'string' },
266
+ profile: { type: 'string' },
212
267
  hash: { type: 'string' },
213
268
  id: { type: 'string' },
214
269
  // Declared here even though no built-in command reads it. `main`
@@ -229,6 +284,10 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
229
284
  // is declared kebab-case and read back the same way, because the camel
230
285
  // form would reject the flag the usage text and docs advertise.
231
286
  'switch-mode': { type: 'boolean', default: false },
287
+ 'force-unlock': { type: 'boolean', default: false },
288
+ 'prune-aliases': { type: 'boolean', default: false },
289
+ staged: { type: 'boolean', default: false },
290
+ rebuild: { type: 'boolean', default: false },
232
291
  yes: { type: 'boolean', default: false },
233
292
  help: { type: 'boolean', default: false },
234
293
  },
@@ -250,7 +309,9 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
250
309
  // importing - every installed plugin's module for a command that was
251
310
  // always going to decline; `makeDiscoveryPorts()` above is cheap
252
311
  // (adapter construction only, no I/O), unlike `discover` itself.
253
- return initSite(discoveryPorts.fs, terminal, logger, []);
312
+ return initSite(discoveryPorts.fs, terminal, logger, [], {
313
+ aws: { profile: values.profile, ...makeAwsAccess() },
314
+ });
254
315
  }
255
316
  // Runs before any context exists - there is no config to load yet.
256
317
  // `init` is one of the four discovery-running paths `DiscoveryPortsFactory`
@@ -286,13 +347,28 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
286
347
  throw err;
287
348
  logger.warn(`${err.message} - continuing with no plugins discovered`);
288
349
  }
289
- return initSite(discoveryPorts.fs, terminal, logger, plugins, repoRoot);
350
+ return initSite(discoveryPorts.fs, terminal, logger, plugins, {
351
+ root: repoRoot,
352
+ aws: { profile: values.profile, ...makeAwsAccess() },
353
+ });
354
+ }
355
+ if (command === 'whoami') {
356
+ // Dispatched beside `init`, before the `makeContext` call below: it
357
+ // resolves the same AWS session but loads no state, and it must work
358
+ // before the repo has a config at all.
359
+ const { host, awsLogin } = makeAwsAccess();
360
+ return whoami({
361
+ env: values.env ?? positionals[1] ?? 'production',
362
+ configPath: values.config,
363
+ profile: values.profile,
364
+ endpointOverride: values.endpoint,
365
+ }, { fs: makeDiscoveryPorts().fs, terminal, logger, awsLogin, host });
290
366
  }
291
367
  if (command === 'plugin') {
292
368
  // Dispatched HERE, beside `init` and ahead of the built-in switch, and
293
369
  // never from the switch itself: the switch runs past the `makeContext`
294
370
  // call below, which loads the environment's config and calls
295
- // `sts.getAccountId()`. `blogwright plugin list` and `plugin add` are what
371
+ // `sts:GetCallerIdentity`. `blogwright plugin list` and `plugin add` are what
296
372
  // an operator runs BEFORE the repo is configured, so dispatching them
297
373
  // after that build would answer both with `no config found for
298
374
  // environment "production"` on exactly the repo they exist to serve -
@@ -324,24 +400,22 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
324
400
  //
325
401
  // TASK 29 - this is now the ONLY route into a plugin's namespace. The
326
402
  // 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`).
403
+ // test, ahead of it precisely so it would win, is gone: the pds plugin a
404
+ // site installs is discovered and dispatched here exactly like any
405
+ // other, which is why the name it claims stays out of
406
+ // `RESERVED_COMMANDS` (`known-commands.ts`).
331
407
  // This module knows no namespace by name any more, and adding one back
332
408
  // would re-open the split where `--help` advertised verbs the
333
409
  // hand-rolled branch refused.
334
410
  return runPlugin(command, positionals.slice(1), values, terminal, logger, makeContext, makeDiscoveryPorts());
335
411
  }
336
- // Positional layout: rollback/logs take <hash> first, then optional env.
337
- let hash;
338
- let envPositional;
412
+ // Positional layout: rollback/logs/verify/promote take <hash> first, then optional
413
+ // env. Their hash is checked here, before any context is built; the other
414
+ // commands never read `hash`.
415
+ let hash = '';
416
+ let envPositional = positionals[1];
339
417
  if (HASH_COMMANDS.has(command)) {
340
- hash = values.hash ?? positionals[1];
341
- envPositional = positionals[2];
342
- }
343
- else {
344
- envPositional = positionals[1];
418
+ ({ hash, envPositional } = hashArguments(command, values.hash, positionals));
345
419
  }
346
420
  const env = values.env ?? envPositional ?? 'production';
347
421
  const ctx = await makeContext({
@@ -349,6 +423,8 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
349
423
  configPath: values.config,
350
424
  domain: values.domain,
351
425
  endpointOverride: values.endpoint,
426
+ profile: values.profile,
427
+ pruneAliases: command === 'bootstrap' && values['prune-aliases'],
352
428
  ports: { terminal },
353
429
  });
354
430
  switch (command) {
@@ -356,33 +432,53 @@ export async function main(argv, makeTerminal, makeContext, makeDiscoveryPorts,
356
432
  await commands.bootstrap(ctx, undefined, { switchMode: values['switch-mode'] });
357
433
  break;
358
434
  case 'deploy':
359
- await commands.deploy(ctx, { refresh: values.refresh });
435
+ // Discovery runs only once the site is live, through the same factory
436
+ // plugin dispatch uses - a deploy that fails never loads a plugin.
437
+ await commands.deploy(ctx, {
438
+ refresh: values.refresh,
439
+ forceUnlock: values['force-unlock'],
440
+ afterDeploy: (deployed) => runAfterDeployHooks(deployed, makeDiscoveryPorts()),
441
+ });
442
+ break;
443
+ case 'stage':
444
+ await stage(ctx, { refresh: values.refresh, forceUnlock: values['force-unlock'] });
445
+ break;
446
+ case 'promote':
447
+ await promote(ctx, hash, {
448
+ refresh: values.refresh,
449
+ forceUnlock: values['force-unlock'],
450
+ afterDeploy: (promoted) => runAfterDeployHooks(promoted, makeDiscoveryPorts()),
451
+ });
360
452
  break;
361
453
  case 'rollback':
362
- if (!hash)
363
- throw new Error('rollback requires a <hash>');
364
- await commands.rollback(ctx, hash, { refresh: values.refresh });
454
+ await commands.rollback(ctx, hash, {
455
+ refresh: values.refresh,
456
+ rebuild: values.rebuild,
457
+ forceUnlock: values['force-unlock'],
458
+ afterDeploy: (rolledBack) => runAfterDeployHooks(rolledBack, makeDiscoveryPorts()),
459
+ });
365
460
  break;
366
461
  case 'delete':
367
- await commands.deleteSite(ctx);
462
+ await commands.deleteSite(ctx, { forceUnlock: values['force-unlock'] });
368
463
  break;
369
464
  case 'destroy':
370
- await commands.destroy(ctx, { yes: values.yes });
465
+ await commands.destroy(ctx, { yes: values.yes, forceUnlock: values['force-unlock'] });
371
466
  break;
372
467
  case 'history':
373
468
  await commands.history(ctx);
374
469
  break;
375
470
  case 'logs':
376
- if (!hash)
377
- throw new Error('logs requires a <hash>');
378
471
  await commands.logs(ctx, hash);
379
472
  break;
380
473
  case 'status':
381
474
  await commands.status(ctx);
382
475
  break;
476
+ case 'verify':
477
+ await verify(ctx, hash, values.staged ? 'staged' : 'live');
478
+ break;
383
479
  default:
384
480
  // Unreachable: past the `KNOWN_COMMANDS` membership test above,
385
- // `command` is one of the nine names in that set, and the `plugin`
481
+ // `command` is one of the names in that set, and the `plugin`
386
482
  // branch has already claimed the only one without a case here. Kept
387
483
  // wired to the same help text as every other USAGE print site - like
388
484
  // `runPreview`'s own unreachable default below - so it stays correct
@@ -409,6 +505,7 @@ async function runPreview(positionals, values, terminal, logger, makeContext, ma
409
505
  configPath: values.config,
410
506
  domain: values.domain,
411
507
  endpointOverride: values.endpoint,
508
+ profile: values.profile,
412
509
  ports: { terminal },
413
510
  });
414
511
  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. */