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
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Process adapter for the AwsLogin port: runs the `aws` CLI with the
3
+ * terminal attached (stdio inherited, no shell) so its browser or device-code
4
+ * sign-in reaches the operator. A missing binary is reported as
5
+ * `not-installed`; any other launch failure is raised with the command.
6
+ */
7
+ import type { AwsLogin } from '../ports.js';
8
+ /** The slice of a child process the adapter listens to. */
9
+ interface LaunchedProcess {
10
+ once(event: 'error', listener: (err: NodeJS.ErrnoException) => void): unknown;
11
+ once(event: 'exit', listener: (code: number | null) => void): unknown;
12
+ }
13
+ /** Starts `aws`; injectable so a test can drive the adapter without spawning. */
14
+ export type LaunchAws = (command: string, args: string[], options: {
15
+ stdio: 'inherit';
16
+ shell: false;
17
+ }) => LaunchedProcess;
18
+ export declare function createProcessAwsLogin(launch?: LaunchAws): AwsLogin;
19
+ export {};
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Process adapter for the AwsLogin port: runs the `aws` CLI with the
3
+ * terminal attached (stdio inherited, no shell) so its browser or device-code
4
+ * sign-in reaches the operator. A missing binary is reported as
5
+ * `not-installed`; any other launch failure is raised with the command.
6
+ */
7
+ import { spawn } from 'node:child_process';
8
+ /** Exit code reported for a sign-in killed by a signal, which has no numeric code. */
9
+ const SIGNALLED_EXIT_CODE = 1;
10
+ export function createProcessAwsLogin(launch = spawn) {
11
+ return {
12
+ run: (args) => new Promise((resolve, reject) => {
13
+ const child = launch('aws', [...args], { stdio: 'inherit', shell: false });
14
+ child.once('error', (err) => {
15
+ if (err.code === 'ENOENT')
16
+ resolve({ ok: false, reason: 'not-installed' });
17
+ else
18
+ reject(new Error(`could not run aws ${args.join(' ')}: ${err.message}`, { cause: err }));
19
+ });
20
+ child.once('exit', (code) => {
21
+ if (code === 0)
22
+ resolve({ ok: true });
23
+ else
24
+ resolve({ ok: false, reason: 'exit', code: code ?? SIGNALLED_EXIT_CODE });
25
+ });
26
+ }),
27
+ };
28
+ }
@@ -4,8 +4,7 @@
4
4
  * artifacts through the FileSystem port from the composition-root-resolved
5
5
  * `ctx.agentDir`; this module touches no Node API directly.
6
6
  */
7
- import { REPRODUCIBLE_ZIP_MTIME } from 'blogwright-core';
8
- import { zipSync } from 'fflate';
7
+ import { createZip, REPRODUCIBLE_ZIP_MTIME } from 'blogwright-core';
9
8
  const IMAGE_PACKAGE_JSON = JSON.stringify({
10
9
  name: 'site-builder',
11
10
  private: true,
@@ -42,7 +41,7 @@ export async function packageAndUploadAgent(ctx) {
42
41
  'server.js': server,
43
42
  'package.json': new TextEncoder().encode(IMAGE_PACKAGE_JSON),
44
43
  };
45
- const zip = zipSync(entries, { level: 6, mtime: REPRODUCIBLE_ZIP_MTIME });
44
+ const zip = createZip(entries, { mtime: REPRODUCIBLE_ZIP_MTIME });
46
45
  const key = `build/agent/agent-${hash}.zip`;
47
46
  await ctx.clients.s3.putObject(ctx.names.bucket, key, zip, 'application/zip');
48
47
  return { key, hash };
@@ -0,0 +1,73 @@
1
+ /**
2
+ * The CLI's side of the artifact manifest. Every static build is asked to
3
+ * record its manifest at a key of its own, `build/artifacts/<hash>/<buildId>.json`,
4
+ * so finding it there proves that build wrote it. A deploy then keeps the
5
+ * first manifest recorded for a revision, write-once, as its original at
6
+ * `build/artifacts/<hash>.json`: no later build of the same revision - a
7
+ * redeploy or a rollback's rebuild - can replace the record a review covered.
8
+ *
9
+ * A staged release is bound to the manifest of the build that staged it,
10
+ * copied by the CLI to `build/releases/<hash>.json`: that, not the original,
11
+ * is what `promote` checks the staged and the promoted bytes against, so a
12
+ * revision first deployed with other bytes can still be staged and promoted.
13
+ */
14
+ import { type ArtifactManifest } from 'blogwright-core';
15
+ import type { OpsContext } from './context.js';
16
+ /**
17
+ * A new build's manifest key. The id sorts by start time and is unique by its
18
+ * random suffix, so no other build can have written the object.
19
+ */
20
+ export declare function newArtifactBuildManifestKey(hash: string, now?: Date): string;
21
+ /**
22
+ * A revision's original artifact manifest (`build/artifacts/<hash>.json`), or
23
+ * undefined when none was recorded: a build from before artifact manifests, or
24
+ * one whose builder was denied the write.
25
+ */
26
+ export declare function readArtifactManifest(ctx: OpsContext, hash: string): Promise<ArtifactManifest | undefined>;
27
+ /** A hash's artifact manifest, refusing a hash that has none. */
28
+ export declare function requireArtifactManifest(ctx: OpsContext, hash: string): Promise<ArtifactManifest>;
29
+ /** One line naming a release: identity, size and aggregate hash. */
30
+ export declare function describeRelease(manifest: ArtifactManifest): string;
31
+ /**
32
+ * The manifest a build recorded at its own `key`, logged as this build's
33
+ * release - or a warning when it recorded none. Never throws.
34
+ */
35
+ export declare function readBuildArtifact(ctx: OpsContext, hash: string, key: string): Promise<ArtifactManifest | undefined>;
36
+ /**
37
+ * After a deploy's build: read the manifest it recorded at `key` and keep it
38
+ * as the revision's original when it is the first. Never throws.
39
+ */
40
+ export declare function recordDeployArtifact(ctx: OpsContext, hash: string, key: string): Promise<ArtifactManifest | undefined>;
41
+ /**
42
+ * The manifest a staged release is bound to, or undefined when the hash has
43
+ * no staged release. A corrupt record, or one for another revision, throws.
44
+ */
45
+ export declare function readStagedReleaseManifest(ctx: OpsContext, hash: string): Promise<ArtifactManifest | undefined>;
46
+ /** The manifest a staged release is bound to, refusing a hash that has no staged release. */
47
+ export declare function requireStagedReleaseManifest(ctx: OpsContext, hash: string): Promise<ArtifactManifest>;
48
+ /** Drop a hash's staged-release binding, before its staged bytes are replaced. */
49
+ export declare function forgetStagedRelease(ctx: OpsContext, hash: string): Promise<void>;
50
+ /**
51
+ * Bind a staged release to the manifest its bytes were checked against, then
52
+ * keep that manifest as the revision's original when it has none - so the
53
+ * usual stage, promote, `verify <hash>` sequence checks one record. A
54
+ * revision whose original is another build keeps that original, and is told
55
+ * what `verify <hash>` will then report. Throws when the binding cannot be
56
+ * written: without it there is nothing to promote.
57
+ */
58
+ export declare function recordStagedRelease(ctx: OpsContext, manifest: ArtifactManifest): Promise<void>;
59
+ /**
60
+ * The original manifest recorded for a hash, read before a rebuild:
61
+ * `unreadable` when one exists but cannot be read. A rollback is a recovery
62
+ * path, so an unreadable record is reported once, here, and does not block
63
+ * it - but it is never reported as absent.
64
+ */
65
+ export declare function readRecordedBeforeRebuild(ctx: OpsContext, hash: string): Promise<ArtifactManifest | 'unreadable' | undefined>;
66
+ /**
67
+ * Report whether a rebuild reproduced the recorded artifact. Two builds of the
68
+ * same source are not guaranteed byte-identical (builder image, dependency
69
+ * resolution, toolchain), so a difference is a warning naming both hashes. A
70
+ * rebuild that recorded no manifest of its own cannot be checked, and is never
71
+ * reported as identical.
72
+ */
73
+ export declare function logRebuildComparison(ctx: OpsContext, recorded: ArtifactManifest | 'unreadable' | undefined, rebuilt: ArtifactManifest | undefined): void;
@@ -0,0 +1,218 @@
1
+ /**
2
+ * The CLI's side of the artifact manifest. Every static build is asked to
3
+ * record its manifest at a key of its own, `build/artifacts/<hash>/<buildId>.json`,
4
+ * so finding it there proves that build wrote it. A deploy then keeps the
5
+ * first manifest recorded for a revision, write-once, as its original at
6
+ * `build/artifacts/<hash>.json`: no later build of the same revision - a
7
+ * redeploy or a rollback's rebuild - can replace the record a review covered.
8
+ *
9
+ * A staged release is bound to the manifest of the build that staged it,
10
+ * copied by the CLI to `build/releases/<hash>.json`: that, not the original,
11
+ * is what `promote` checks the staged and the promoted bytes against, so a
12
+ * revision first deployed with other bytes can still be staged and promoted.
13
+ */
14
+ import { randomUUID } from 'node:crypto';
15
+ import { artifactBuildManifestKey, artifactManifestKey, parseArtifactManifest, serializeArtifactManifest, stagedReleaseManifestKey, } from 'blogwright-core';
16
+ /**
17
+ * A new build's manifest key. The id sorts by start time and is unique by its
18
+ * random suffix, so no other build can have written the object.
19
+ */
20
+ export function newArtifactBuildManifestKey(hash, now = new Date()) {
21
+ const stamp = now
22
+ .toISOString()
23
+ .replace(/[-:]/g, '')
24
+ .replace(/\.\d+Z$/, 'Z');
25
+ return artifactBuildManifestKey(hash, `${stamp}-${randomUUID().slice(0, 8)}`);
26
+ }
27
+ /**
28
+ * The manifest at `key`, or undefined when there is none. A manifest that
29
+ * does not validate, or that records a different revision than `hash`, is an
30
+ * error, never read as absent.
31
+ */
32
+ async function readArtifactManifestAt(ctx, hash, key) {
33
+ const text = await ctx.clients.s3.getObjectText(ctx.names.bucket, key);
34
+ if (text === undefined)
35
+ return undefined;
36
+ const source = `s3://${ctx.names.bucket}/${key}`;
37
+ const manifest = parseArtifactManifest(text, source);
38
+ if (manifest.hash !== hash) {
39
+ throw new Error(`${source} records revision ${manifest.hash}, not ${hash}`);
40
+ }
41
+ return manifest;
42
+ }
43
+ /**
44
+ * A revision's original artifact manifest (`build/artifacts/<hash>.json`), or
45
+ * undefined when none was recorded: a build from before artifact manifests, or
46
+ * one whose builder was denied the write.
47
+ */
48
+ export async function readArtifactManifest(ctx, hash) {
49
+ return readArtifactManifestAt(ctx, hash, artifactManifestKey(hash));
50
+ }
51
+ /**
52
+ * Read a manifest after the site is already live: a read failure or a corrupt
53
+ * record is reported and treated as absent, because nothing it could say
54
+ * should stop the rest of a deploy or rollback.
55
+ */
56
+ async function readOrWarn(ctx, hash, key, what) {
57
+ try {
58
+ return await readArtifactManifestAt(ctx, hash, key);
59
+ }
60
+ catch (err) {
61
+ ctx.logger.warn(`ignoring the ${what}: ${err.message}`);
62
+ return undefined;
63
+ }
64
+ }
65
+ /** A hash's artifact manifest, refusing a hash that has none. */
66
+ export async function requireArtifactManifest(ctx, hash) {
67
+ const manifest = await readArtifactManifest(ctx, hash);
68
+ if (manifest)
69
+ return manifest;
70
+ throw new Error(`no artifact manifest is recorded for ${hash} at s3://${ctx.names.bucket}/` +
71
+ `${artifactManifestKey(hash)} - only static builds made since artifact manifests ` +
72
+ 'were introduced have one (see `blogwright history` for hashes)');
73
+ }
74
+ /** One line naming a release: identity, size and aggregate hash. */
75
+ export function describeRelease(manifest) {
76
+ const kib = (manifest.totalBytes / 1024).toFixed(0);
77
+ return `${manifest.release} (${manifest.fileCount} files, ${kib} KiB, sha256 ${manifest.releaseHash})`;
78
+ }
79
+ /**
80
+ * The manifest a build recorded at its own `key`, logged as this build's
81
+ * release - or a warning when it recorded none. Never throws.
82
+ */
83
+ export async function readBuildArtifact(ctx, hash, key) {
84
+ const manifest = await readOrWarn(ctx, hash, key, "build's artifact manifest");
85
+ if (manifest) {
86
+ ctx.logger.ok(`release ${describeRelease(manifest)}`);
87
+ ctx.logger.info(` artifact manifest s3://${ctx.names.bucket}/${key}`);
88
+ return manifest;
89
+ }
90
+ ctx.logger.warn(`the builder recorded no artifact manifest at ${key} - a stack bootstrapped before ` +
91
+ `artifact manifests needs \`blogwright bootstrap ${ctx.env}\` to grant the builder write ` +
92
+ 'access to build/artifacts/, and a builder image older than this blogwright records ' +
93
+ 'none until the next deploy rebuilds it');
94
+ return undefined;
95
+ }
96
+ async function recordOriginalArtifact(ctx, manifest) {
97
+ const key = artifactManifestKey(manifest.hash);
98
+ const location = `s3://${ctx.names.bucket}/${key}`;
99
+ let created;
100
+ try {
101
+ created = await ctx.clients.s3.putObjectIfAbsent(ctx.names.bucket, key, serializeArtifactManifest(manifest), 'application/json');
102
+ }
103
+ catch (err) {
104
+ ctx.logger.warn(`could not record the original artifact manifest at ${location}: ${err.message}`);
105
+ return 'unknown';
106
+ }
107
+ if (created) {
108
+ ctx.logger.info(` recorded as the original release of ${manifest.hash} at ${location}`);
109
+ return 'created';
110
+ }
111
+ const original = await readOrWarn(ctx, manifest.hash, key, 'original artifact manifest');
112
+ if (!original)
113
+ return 'unknown';
114
+ if (original.releaseHash === manifest.releaseHash) {
115
+ ctx.logger.info(` matches the original release of ${manifest.hash} recorded at ${location}`);
116
+ return 'matches';
117
+ }
118
+ ctx.logger.warn(`this build of ${manifest.hash} is not byte-identical to its original release ` +
119
+ `${original.release} (sha256 ${original.releaseHash}); the original record at ` +
120
+ `${location} is kept unchanged`);
121
+ return 'differs';
122
+ }
123
+ /**
124
+ * After a deploy's build: read the manifest it recorded at `key` and keep it
125
+ * as the revision's original when it is the first. Never throws.
126
+ */
127
+ export async function recordDeployArtifact(ctx, hash, key) {
128
+ const manifest = await readBuildArtifact(ctx, hash, key);
129
+ if (manifest)
130
+ await recordOriginalArtifact(ctx, manifest);
131
+ return manifest;
132
+ }
133
+ /**
134
+ * The manifest a staged release is bound to, or undefined when the hash has
135
+ * no staged release. A corrupt record, or one for another revision, throws.
136
+ */
137
+ export async function readStagedReleaseManifest(ctx, hash) {
138
+ return readArtifactManifestAt(ctx, hash, stagedReleaseManifestKey(hash));
139
+ }
140
+ /** The manifest a staged release is bound to, refusing a hash that has no staged release. */
141
+ export async function requireStagedReleaseManifest(ctx, hash) {
142
+ const manifest = await readStagedReleaseManifest(ctx, hash);
143
+ if (manifest)
144
+ return manifest;
145
+ throw new Error(`${hash} is not staged: there is no staged release record at s3://${ctx.names.bucket}/` +
146
+ `${stagedReleaseManifestKey(hash)}. Stage it first with \`blogwright stage ${ctx.env}\` ` +
147
+ `from a checkout of ${hash}.`);
148
+ }
149
+ /** Drop a hash's staged-release binding, before its staged bytes are replaced. */
150
+ export async function forgetStagedRelease(ctx, hash) {
151
+ await ctx.clients.s3.deleteObject(ctx.names.bucket, stagedReleaseManifestKey(hash));
152
+ }
153
+ /**
154
+ * Bind a staged release to the manifest its bytes were checked against, then
155
+ * keep that manifest as the revision's original when it has none - so the
156
+ * usual stage, promote, `verify <hash>` sequence checks one record. A
157
+ * revision whose original is another build keeps that original, and is told
158
+ * what `verify <hash>` will then report. Throws when the binding cannot be
159
+ * written: without it there is nothing to promote.
160
+ */
161
+ export async function recordStagedRelease(ctx, manifest) {
162
+ const key = stagedReleaseManifestKey(manifest.hash);
163
+ await ctx.clients.s3.putObject(ctx.names.bucket, key, serializeArtifactManifest(manifest), 'application/json');
164
+ ctx.logger.info(` staged release recorded at s3://${ctx.names.bucket}/${key}`);
165
+ if ((await recordOriginalArtifact(ctx, manifest)) === 'differs') {
166
+ ctx.logger.warn(`promote publishes and checks this staged release; \`blogwright verify ${manifest.hash}\` ` +
167
+ "checks site/ against the revision's original release, so after promotion it reports " +
168
+ 'the differences - `blogwright verify ' +
169
+ `${manifest.hash} --staged\` checks the staged copy`);
170
+ }
171
+ }
172
+ /**
173
+ * The original manifest recorded for a hash, read before a rebuild:
174
+ * `unreadable` when one exists but cannot be read. A rollback is a recovery
175
+ * path, so an unreadable record is reported once, here, and does not block
176
+ * it - but it is never reported as absent.
177
+ */
178
+ export async function readRecordedBeforeRebuild(ctx, hash) {
179
+ try {
180
+ return await readArtifactManifest(ctx, hash);
181
+ }
182
+ catch (err) {
183
+ ctx.logger.warn(`ignoring the recorded artifact manifest: ${err.message}`);
184
+ return 'unreadable';
185
+ }
186
+ }
187
+ /**
188
+ * Report whether a rebuild reproduced the recorded artifact. Two builds of the
189
+ * same source are not guaranteed byte-identical (builder image, dependency
190
+ * resolution, toolchain), so a difference is a warning naming both hashes. A
191
+ * rebuild that recorded no manifest of its own cannot be checked, and is never
192
+ * reported as identical.
193
+ */
194
+ export function logRebuildComparison(ctx, recorded, rebuilt) {
195
+ if (recorded === 'unreadable') {
196
+ ctx.logger.warn('the original artifact manifest could not be read (see above), so the rebuild cannot be ' +
197
+ 'checked against it - treat the live site as unverified');
198
+ return;
199
+ }
200
+ if (!recorded) {
201
+ ctx.logger.info(` no artifact manifest was recorded before this rebuild`);
202
+ return;
203
+ }
204
+ ctx.logger.info(` recorded release sha256 ${recorded.releaseHash} (${recorded.release})`);
205
+ if (!rebuilt) {
206
+ ctx.logger.warn('the rebuild recorded no artifact manifest, so it cannot be checked against the recorded ' +
207
+ 'release - treat the live site as unverified');
208
+ return;
209
+ }
210
+ ctx.logger.info(` rebuilt release sha256 ${rebuilt.releaseHash} (${rebuilt.release})`);
211
+ if (recorded.releaseHash === rebuilt.releaseHash) {
212
+ ctx.logger.ok('the rebuild is byte-identical to the recorded artifact');
213
+ }
214
+ else {
215
+ ctx.logger.warn('the rebuild is NOT byte-identical to the recorded artifact - the live site now serves ' +
216
+ 'the rebuilt bytes, which no review covered');
217
+ }
218
+ }
@@ -0,0 +1,118 @@
1
+ import { type AccountPinStatus, type AwsClients, type AwsConfig, type CallerIdentity, type ClientBundleOptions, type FileSystem, type ProfileStyle, type Terminal } from 'blogwright-core';
2
+ import type { Logger } from './logger.js';
3
+ import type { AwsLogin } from './ports.js';
4
+ /** Which precedence row chose the credentials. */
5
+ export type AwsProfileSource = 'flag' | 'env' | 'env-keys' | 'config' | 'default';
6
+ /** A profile chosen by name: by `--profile`, `AWS_PROFILE` or the config's `aws.profile`. */
7
+ export interface NamedAwsProfile {
8
+ source: 'flag' | 'env' | 'config';
9
+ name: string;
10
+ }
11
+ /** No profile named: the exported environment credentials, or the default chain. */
12
+ interface UnnamedAwsProfile {
13
+ source: 'env-keys' | 'default';
14
+ }
15
+ /** The outcome of profile resolution; only the named rows carry a profile name. */
16
+ export type ResolvedAwsProfile = NamedAwsProfile | UnnamedAwsProfile;
17
+ /** True when a precedence row named a profile. */
18
+ export declare function isNamedProfile(profile: ResolvedAwsProfile): profile is NamedAwsProfile;
19
+ /** The parts of the operator's machine AWS resolution reads, injected by the composition root. */
20
+ export interface AwsHost {
21
+ processEnv: NodeJS.ProcessEnv;
22
+ home: string;
23
+ platform: NodeJS.Platform;
24
+ /** Working directory the repository root is searched from. */
25
+ cwd: string;
26
+ /** Builds the AWS clients; defaults to core's `createClients`. Tests substitute it. */
27
+ createClients?: ((opts: ClientBundleOptions) => AwsClients) | undefined;
28
+ }
29
+ export interface AwsSessionOptions {
30
+ /** Region STS (and every client) signs in. */
31
+ region: string;
32
+ /** `--endpoint`; `AWS_ENDPOINT_URL` from the host applies when absent. */
33
+ endpointOverride?: string | undefined;
34
+ /** `--profile` - row 1 of the precedence. */
35
+ flag?: string | undefined;
36
+ /** The environment config's `aws` block, when there is a config. */
37
+ aws?: AwsConfig | undefined;
38
+ /** How messages name the config file, e.g. `config/production.jsonc`. */
39
+ configLabel: string;
40
+ host: AwsHost;
41
+ ports: {
42
+ fs: FileSystem;
43
+ terminal: Terminal;
44
+ awsLogin: AwsLogin;
45
+ };
46
+ logger: Logger;
47
+ }
48
+ export interface AwsSession {
49
+ profile: ResolvedAwsProfile;
50
+ clients: AwsClients;
51
+ identity: CallerIdentity;
52
+ pin: AccountPinStatus;
53
+ }
54
+ /**
55
+ * The profile precedence; the first matching row wins: `--profile`,
56
+ * `AWS_PROFILE`, exported environment credentials (no name), the config's
57
+ * `aws.profile`, then the default chain (no name). Exported credentials beat
58
+ * the config's profile so a committed `aws.profile` cannot break CI.
59
+ */
60
+ export declare function resolveAwsProfile(input: {
61
+ flag?: string | undefined;
62
+ processEnv: NodeJS.ProcessEnv;
63
+ config?: AwsConfig | undefined;
64
+ }): ResolvedAwsProfile;
65
+ /**
66
+ * True when a browser cannot be opened for sign-in: `BLOGWRIGHT_HEADLESS=1`,
67
+ * an SSH session, or Linux with no display. `BLOGWRIGHT_HEADLESS=0` forces
68
+ * the browser flow.
69
+ */
70
+ export declare function isHeadless(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): boolean;
71
+ /**
72
+ * True when a `GetCallerIdentity` failure is about the credentials - the
73
+ * provider failed, or STS rejected them - rather than the network, endpoint
74
+ * or region, which propagate unchanged.
75
+ */
76
+ export declare function isCredentialFailure(err: unknown): boolean;
77
+ /** How an operator names a precedence row: `--profile`, `AWS_PROFILE`, `config`, ... */
78
+ export declare function profileSourceLabel(source: AwsProfileSource): string;
79
+ /** One sign-in command the login offer can run. */
80
+ interface LoginChoice {
81
+ /** argv for the AWS CLI, without the leading `aws`. */
82
+ args: string[];
83
+ hint: string;
84
+ }
85
+ /** Both sign-in commands, `aws sso login` first, and which one is the default. */
86
+ export interface LoginMenu {
87
+ choices: [LoginChoice, LoginChoice];
88
+ /** Index into `choices`. */
89
+ defaultIndex: 0 | 1;
90
+ }
91
+ /**
92
+ * The two sign-in commands for a profile. The default follows the style: SSO
93
+ * profiles default to `aws sso login`, console and unconfigured ones to
94
+ * `aws login`. Headless hosts get each command's browserless flag. The
95
+ * profile is the one whose settings decided the style - for a
96
+ * `source_profile` chain, its source, whose login repairs the chain - and is
97
+ * always passed, `default` included, so the AWS CLI cannot fall back to an
98
+ * inherited `AWS_PROFILE` this session ignored.
99
+ */
100
+ export declare function buildLoginChoices(profileName: string, style: ProfileStyle, headless: boolean): LoginMenu;
101
+ /**
102
+ * Resolve the profile, confirm it exists, build the clients, learn whose
103
+ * credentials they are, and enforce the account pin - in that order, so a
104
+ * mismatched account never reaches `StateStore.load`. A credential failure
105
+ * goes to the login offer, which retries `GetCallerIdentity` once after a
106
+ * successful sign-in; a second failure is reported, never offered again.
107
+ */
108
+ export declare function resolveAwsSession(opts: AwsSessionOptions): Promise<AwsSession>;
109
+ /** `aws 123456789012 · AdminRole · profile mysite-prod (config) · pinned` */
110
+ export declare function formatIdentityLine(session: Pick<AwsSession, 'identity' | 'profile' | 'pin'>): string;
111
+ /**
112
+ * Emit a session line - the identity line, or a notice such as `account pin
113
+ * skipped`. Interactive sessions get it through the logger; otherwise
114
+ * (`--plain`, piped output, CI) it goes to stderr, so the non-interactive
115
+ * stdout of `history`, `status` and `whoami` stays byte-identical.
116
+ */
117
+ export declare function emitSessionLine(line: string, terminal: Terminal, logger: Logger): void;
118
+ export {};