saaslayer 0.4.2 → 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 (62) hide show
  1. package/bin/saaslayer.js +23 -11
  2. package/package.json +7 -7
  3. package/src/cdn-aws.js +67 -0
  4. package/src/cdn-publication.js +146 -0
  5. package/src/cdn-publisher.js +166 -0
  6. package/src/commands/cdn.js +66 -0
  7. package/src/commands/deploy.js +4 -3
  8. package/src/commands/lifecycle.js +20 -2
  9. package/src/commands/operations.js +8 -3
  10. package/src/commands/stacks.js +2 -0
  11. package/src/commands/users-management.js +2 -2
  12. package/src/deployments.js +5 -2
  13. package/src/module-catalog.js +15 -5
  14. package/src/sms/scope.js +4 -2
  15. package/src/source-branch.js +36 -0
  16. package/src/users-import/ids.js +1 -1
  17. package/templates/saaslayer-foundation.yml +215 -281
  18. package/vendor/config/login-domain.js +213 -0
  19. package/vendor/discovery/index.d.mts +109 -0
  20. package/vendor/discovery/index.mjs +409 -0
  21. package/vendor/ids/index.d.ts +21 -0
  22. package/vendor/ids/index.js +237 -0
  23. package/vendor/migrations/backups.js +118 -0
  24. package/vendor/migrations/child.js +78 -0
  25. package/vendor/migrations/credentials.js +103 -0
  26. package/vendor/migrations/errors.js +30 -0
  27. package/vendor/migrations/exec-child.js +78 -0
  28. package/vendor/migrations/gate.js +51 -0
  29. package/vendor/migrations/index.js +30 -0
  30. package/vendor/migrations/inventory.js +92 -0
  31. package/vendor/migrations/log.js +14 -0
  32. package/vendor/migrations/release.js +45 -0
  33. package/vendor/migrations/report.js +129 -0
  34. package/vendor/migrations/rules.js +104 -0
  35. package/vendor/migrations/run.js +311 -0
  36. package/vendor/migrations/session-policy.js +37 -0
  37. package/vendor/migrations/step-guard.js +82 -0
  38. package/vendor/operations/activity.d.ts +21 -0
  39. package/vendor/operations/activity.js +126 -0
  40. package/vendor/operations/index.d.ts +72 -0
  41. package/vendor/operations/index.js +510 -0
  42. package/vendor/permissions-engine-core/account-status.js +270 -0
  43. package/vendor/permissions-engine-core/delegation.js +174 -0
  44. package/vendor/permissions-engine-core/direct-mode-contract.js +237 -0
  45. package/vendor/permissions-engine-core/sso-claims.js +206 -0
  46. package/vendor/user-management/cognito/emails/token-registry.js +48 -0
  47. package/vendor/user-management/email/validate.js +207 -0
  48. package/vendor/user-management/extensibility/hook-contract.js +720 -0
  49. package/vendor/user-management/extensibility/safe-webhook.js +85 -0
  50. package/vendor/user-management/identity/admission.js +215 -0
  51. package/vendor/user-management/identity/attr.js +27 -0
  52. package/vendor/user-management/identity/attribute-registry.js +115 -0
  53. package/vendor/user-management/identity/email.js +25 -0
  54. package/vendor/user-management/identity/ensure-suid.js +74 -0
  55. package/vendor/user-management/identity/pointers.js +192 -0
  56. package/vendor/user-management/identity/stitch-provider.js +275 -0
  57. package/vendor/user-management/management/apply-request.js +227 -0
  58. package/vendor/user-management/management/core-profile.js +110 -0
  59. package/vendor/user-management/management/index.js +23 -0
  60. package/vendor/user-management/management/purposes.js +94 -0
  61. package/vendor/user-management/management/registry.js +569 -0
  62. package/vendor/user-management/store/table.js +332 -0
@@ -0,0 +1,510 @@
1
+ // The operation resource shared by the control plane, deployed services, CLI and console: durable id, kind,
2
+ // status (pending|running|succeeded|failed|partial), per-component outcomes, idempotency, redaction and watch.
3
+ 'use strict'
4
+
5
+ /** @typedef {'pending'|'running'|'succeeded'|'failed'|'partial'|'superseded'} OperationStatus */
6
+ /** @typedef {'pending'|'running'|'succeeded'|'failed'|'skipped'|'unknown'} ComponentStatus */
7
+ /** @typedef {{ code?: string|null, message?: string|null }} OperationError */
8
+ /**
9
+ * @typedef {object} OperationComponent
10
+ * @property {string} name
11
+ * @property {ComponentStatus} status
12
+ * @property {'external'} [delivery] an external delivery (email, webhook) whose outcome may stay unknown
13
+ * @property {OperationError} [error]
14
+ * @property {string} [nextAction] the next supported command for this component
15
+ * @property {Record<string, unknown>} [detail] the component's own reported state (redacted), e.g. a bootstrap's step
16
+ * @property {FunctionCode} [functionCode] after a code-only update stopped partway: which functions run which code
17
+ * @property {Strategy} [strategy] how the deployment plan chose to apply this component
18
+ * @property {string} [strategyReason] why the plan chose that strategy (redacted)
19
+ */
20
+ /** @typedef {'unchanged'|'fullDeploy'|'codeDeploy'} Strategy */
21
+ /**
22
+ * @typedef {object} FunctionCode
23
+ * @property {string[]} updated functions running the requested code
24
+ * @property {string[]} old functions provably still running the previous code
25
+ * @property {string[]} unknown functions whose code could not be determined
26
+ */
27
+ /**
28
+ * @typedef {object} Operation
29
+ * @property {string} id
30
+ * @property {string} kind
31
+ * @property {OperationStatus} status
32
+ * @property {OperationComponent[]} components
33
+ * @property {string|null} createdAt
34
+ * @property {string|null} updatedAt
35
+ * @property {string|null} requestKey
36
+ * @property {string} [deploymentId]
37
+ * @property {OperationError} [error]
38
+ * @property {string} [nextAction]
39
+ * @property {Record<string, unknown>} [purgeResult] a delete destroy's or purge's report: complete, pending or incomplete
40
+ */
41
+
42
+ const OPERATION_STATUSES = ['pending', 'running', 'succeeded', 'failed', 'partial', 'superseded']
43
+ const COMPONENT_STATUSES = ['pending', 'running', 'succeeded', 'failed', 'skipped', 'unknown']
44
+ /** The plan strategies a component reports; any other planned value is left out. */
45
+ const STRATEGIES = ['unchanged', 'fullDeploy', 'codeDeploy']
46
+ const EXTERNAL_DELIVERY_STATUSES = ['pending', 'running', 'succeeded', 'failed', 'unknown']
47
+ // superseded: a waiting request replaced by a newer one before it started; it never ran
48
+ const TERMINAL_STATUSES = ['succeeded', 'failed', 'partial', 'superseded']
49
+
50
+ // How long a request key (and the operation it names) is replayable: 7 days. After that the key may be reused.
51
+ const IDEMPOTENCY_RETENTION_SECONDS = 7 * 24 * 60 * 60
52
+
53
+ /** @type {Record<string, OperationStatus[]>} */
54
+ const ALLOWED_TRANSITIONS = {
55
+ pending: ['running', 'succeeded', 'failed', 'partial', 'superseded'],
56
+ running: ['succeeded', 'failed', 'partial'],
57
+ succeeded: [],
58
+ failed: [],
59
+ partial: [],
60
+ superseded: [],
61
+ }
62
+
63
+ /** @param {string} status */
64
+ function isTerminal(status) {
65
+ return TERMINAL_STATUSES.includes(status)
66
+ }
67
+
68
+ /**
69
+ * @param {{ id: string, kind: string, requestKey?: string|null, components?: Array<string|{ name: string, delivery?: 'external' }>, now: string }} input
70
+ * @returns {Operation}
71
+ */
72
+ function createOperation({ id, kind, requestKey = null, components = [], now }) {
73
+ if (!id || !kind) throw new Error('createOperation: id and kind are required')
74
+ return {
75
+ id,
76
+ kind,
77
+ status: 'pending',
78
+ components: components.map((c) => {
79
+ const spec = typeof c === 'string' ? { name: c } : c
80
+ return { name: spec.name, status: 'pending', ...(spec.delivery === 'external' ? { delivery: 'external' } : {}) }
81
+ }),
82
+ createdAt: now,
83
+ updatedAt: now,
84
+ requestKey,
85
+ }
86
+ }
87
+
88
+ /**
89
+ * Move an operation to a new status. Same-state is a no-op; leaving a terminal state throws.
90
+ * @param {Operation} op
91
+ * @param {string} next
92
+ * @param {string} now
93
+ * @returns {Operation}
94
+ */
95
+ function transition(op, next, now) {
96
+ if (!OPERATION_STATUSES.includes(next)) throw new Error(`unknown operation status "${next}"`)
97
+ if (op.status === next) return op
98
+ if (!ALLOWED_TRANSITIONS[op.status].includes(/** @type {OperationStatus} */ (next))) {
99
+ throw new Error(`illegal operation transition ${op.status} -> ${next}`)
100
+ }
101
+ return { ...op, status: /** @type {OperationStatus} */ (next), updatedAt: now }
102
+ }
103
+
104
+ /**
105
+ * The operation status implied by its components: all pending = pending; any pending/running = running; else
106
+ * no failure = succeeded (an external delivery's unknown is not a failure), failures plus successes = partial,
107
+ * only failures = failed.
108
+ * @param {OperationComponent[]} components
109
+ * @returns {OperationStatus}
110
+ */
111
+ function rollupStatus(components) {
112
+ if (components.length === 0) return 'pending'
113
+ if (components.every((c) => c.status === 'pending')) return 'pending'
114
+ if (components.some((c) => c.status === 'pending' || c.status === 'running')) return 'running'
115
+ const failed = components.filter((c) => c.status === 'failed').length
116
+ if (failed === 0) return 'succeeded'
117
+ return components.some((c) => c.status === 'succeeded' || c.status === 'unknown') ? 'partial' : 'failed'
118
+ }
119
+
120
+ /**
121
+ * Record one component's outcome and roll the operation status up from its components.
122
+ * @param {Operation} op
123
+ * @param {string} name
124
+ * @param {{ status: string, error?: OperationError, nextAction?: string }} patch
125
+ * @param {string} now
126
+ * @returns {Operation}
127
+ */
128
+ function updateComponent(op, name, patch, now) {
129
+ const index = op.components.findIndex((c) => c.name === name)
130
+ if (index < 0) throw new Error(`no component "${name}" on operation ${op.id}`)
131
+ if (!COMPONENT_STATUSES.includes(patch.status)) throw new Error(`unknown component status "${patch.status}"`)
132
+ const current = op.components[index]
133
+ if (current.delivery === 'external' && !EXTERNAL_DELIVERY_STATUSES.includes(patch.status)) {
134
+ throw new Error(`external delivery component "${name}" reports succeeded|failed|unknown`)
135
+ }
136
+ const component = {
137
+ ...current,
138
+ status: /** @type {ComponentStatus} */ (patch.status),
139
+ ...(patch.error ? { error: redact(patch.error) } : {}),
140
+ ...(patch.nextAction ? { nextAction: patch.nextAction } : {}),
141
+ }
142
+ const components = op.components.map((c, i) => (i === index ? component : c))
143
+ return transition({ ...op, components, updatedAt: now }, rollupStatus(components), now)
144
+ }
145
+
146
+ // ---- Idempotency -------------------------------------------------------------------------------------
147
+
148
+ /** @param {unknown} value @returns {unknown} */
149
+ function canonical(value) {
150
+ if (Array.isArray(value)) return value.map(canonical)
151
+ if (value && typeof value === 'object') {
152
+ return Object.keys(value).sort().reduce((acc, key) => {
153
+ acc[key] = canonical(/** @type {Record<string, unknown>} */ (value)[key])
154
+ return acc
155
+ }, /** @type {Record<string, unknown>} */ ({}))
156
+ }
157
+ return value
158
+ }
159
+
160
+ /**
161
+ * The payload fingerprint a request key is bound to (sha256 of the key-sorted JSON).
162
+ * @param {unknown} payload
163
+ */
164
+ function fingerprint(payload) {
165
+ // Required here, not at module load: browser bundles import this module for redaction and rendering only.
166
+ const { createHash } = require('node:crypto')
167
+ return createHash('sha256').update(JSON.stringify(canonical(payload === undefined ? null : payload))).digest('hex')
168
+ }
169
+
170
+ /**
171
+ * A request key scoped by its scope (a deployment id) and operation kind, so one key can't collide across them.
172
+ * @param {{ scope: string, kind: string, requestKey: string }} input
173
+ */
174
+ function idempotencyScopeKey({ scope, kind, requestKey }) {
175
+ if (!scope || !kind || !requestKey) throw new Error('idempotencyScopeKey: scope, kind and requestKey are required')
176
+ return `${scope}#${kind}#${requestKey}`
177
+ }
178
+
179
+ /**
180
+ * The DynamoDB ttl (epoch seconds) for a request key recorded at nowMs.
181
+ * @param {number} nowMs
182
+ */
183
+ function idempotencyExpiry(nowMs) {
184
+ return Math.floor(nowMs / 1000) + IDEMPOTENCY_RETENTION_SECONDS
185
+ }
186
+
187
+ /**
188
+ * Decide what a request with this key + payload does against the stored key record: 'new' (no live record),
189
+ * 'replay' (same payload — return the same operation) or 'conflict' (different payload — 409). A record past
190
+ * its ttl (or, without one, past createdAt + retention) is expired and treated as absent.
191
+ * @param {{ record: { requestHash?: unknown, runId?: unknown, operationId?: unknown, ttl?: unknown, createdAt?: unknown } | null | undefined, fingerprint: string, nowMs: number }} input
192
+ * @returns {{ action: 'new' } | { action: 'replay', operationId: string|null } | { action: 'conflict', statusCode: 409, code: 'IDEMPOTENCY_KEY_REUSED', error: string }}
193
+ */
194
+ function resolveIdempotency({ record, fingerprint: requestFingerprint, nowMs }) {
195
+ if (!record) return { action: 'new' }
196
+ const expiresAtSeconds = typeof record.ttl === 'number'
197
+ ? record.ttl
198
+ : typeof record.createdAt === 'string' ? Math.floor(Date.parse(record.createdAt) / 1000) + IDEMPOTENCY_RETENTION_SECONDS : null
199
+ if (expiresAtSeconds !== null && expiresAtSeconds * 1000 < nowMs) return { action: 'new' }
200
+ if (record.requestHash !== requestFingerprint) {
201
+ return { action: 'conflict', statusCode: 409, code: 'IDEMPOTENCY_KEY_REUSED', error: 'Idempotency-Key was already used with a different request body' }
202
+ }
203
+ const operationId = record.operationId || record.runId
204
+ return { action: 'replay', operationId: typeof operationId === 'string' ? operationId : null }
205
+ }
206
+
207
+ // ---- Deployer runs as operations ---------------------------------------------------------------------
208
+
209
+ /** @type {Record<string, string>} */
210
+ const KIND_BY_RUN_TYPE = {
211
+ CREATE: 'deployment.create',
212
+ UPDATE: 'deployment.update',
213
+ DESTROY: 'deployment.destroy',
214
+ PURGE: 'deployment.purge',
215
+ MIGRATE: 'deployment.migrate',
216
+ ADD_SERVICE: 'service.add',
217
+ REMOVE_SERVICE: 'service.remove',
218
+ }
219
+
220
+ /** @param {unknown} customDomain the custom domain a run carries @returns {string|null} its operation kind */
221
+ function customDomainKind(customDomain) {
222
+ const action = customDomain && typeof customDomain === 'object' ? /** @type {{ action?: unknown }} */ (customDomain).action : null
223
+ return action === 'attach' || action === 'remove' ? `service.custom-domain.${action}` : null
224
+ }
225
+
226
+ // The login-domain actions a dedicated UPDATE run carries (run.loginDomain.action): kind service.login-domain.<action>.
227
+ const LOGIN_DOMAIN_ACTIONS = ['provision', 'activate', 'deactivate', 'remove']
228
+
229
+ /**
230
+ * The login-domain action a run was started for, or null.
231
+ * @param {Record<string, unknown>} run
232
+ * @returns {string|null}
233
+ */
234
+ function loginDomainAction(run) {
235
+ const action = run.loginDomain && typeof run.loginDomain === 'object' ? /** @type {{ action?: unknown }} */ (run.loginDomain).action : null
236
+ return typeof action === 'string' && LOGIN_DOMAIN_ACTIONS.includes(action) ? action : null
237
+ }
238
+
239
+ /**
240
+ * A module result's per-function code report, or undefined when absent or malformed.
241
+ * @param {unknown} value
242
+ * @returns {FunctionCode|undefined}
243
+ */
244
+ function functionCodeOf(value) {
245
+ if (!value || typeof value !== 'object') return undefined
246
+ const v = /** @type {Record<string, unknown>} */ (value)
247
+ const names = (/** @type {unknown} */ x) => Array.isArray(x) && x.every((n) => typeof n === 'string')
248
+ if (!names(v.updated) || !names(v.old) || !names(v.unknown)) return undefined
249
+ return { updated: [.../** @type {string[]} */ (v.updated)], old: [.../** @type {string[]} */ (v.old)], unknown: [.../** @type {string[]} */ (v.unknown)] }
250
+ }
251
+
252
+ /** @param {string|null|undefined} runStatus @returns {OperationStatus} */
253
+ function statusFromRun(runStatus) {
254
+ if (runStatus === 'QUEUED' || runStatus === 'WAITING') return 'pending'
255
+ if (runStatus === 'RUNNING' || runStatus === 'CANCEL_REQUESTED') return 'running'
256
+ if (runStatus === 'SUCCEEDED') return 'succeeded'
257
+ if (runStatus === 'SUPERSEDED') return 'superseded'
258
+ return 'failed'
259
+ }
260
+
261
+ /**
262
+ * The CLI command that retries (or, for a blocked/non-retryable failure, inspects) a failed run.
263
+ * @param {{ kind: string, deploymentId?: string, run: Record<string, unknown>, service?: string, retryable?: unknown, blocked?: unknown }} input
264
+ */
265
+ function nextActionFor({ kind, deploymentId, run, service, retryable, blocked }) {
266
+ if (blocked === true || retryable === false) return 'saaslayer status'
267
+ switch (kind) {
268
+ case 'deployment.create': return 'saaslayer deploy'
269
+ case 'deployment.update': return run.targetCommitSha ? `saaslayer update --commit-sha ${run.targetCommitSha}` : 'saaslayer update'
270
+ case 'deployment.destroy': return 'saaslayer destroy --data-custody delete|retain'
271
+ case 'deployment.purge': return 'saaslayer destroy --purge-retained --reason TEXT'
272
+ case 'deployment.migrate': return `saaslayer migrate status --deployment ${deploymentId}`
273
+ case 'service.add': return `saaslayer service add ${service}`
274
+ case 'service.remove': return `saaslayer service remove ${service} --data-custody delete|retain`
275
+ default:
276
+ // A login-domain run's state (and the next step) is read back with status, whichever action failed.
277
+ if (kind.startsWith('service.login-domain.')) return `saaslayer login-domain status --service ${service}`
278
+ return 'saaslayer status'
279
+ }
280
+ }
281
+
282
+ /** @param {Record<string, unknown>} result @returns {ComponentStatus|null} */
283
+ function componentStatusFromResult(result) {
284
+ // A component a step reports itself (a seed's first-admin bootstrap) carries its own status.
285
+ if (typeof result.componentStatus === 'string' && COMPONENT_STATUSES.includes(result.componentStatus)) return /** @type {ComponentStatus} */ (result.componentStatus)
286
+ const outcomes = [result.deployStatus, result.removeStatus]
287
+ if (outcomes.includes('FAILED')) return 'failed'
288
+ if (outcomes.includes('SUCCEEDED')) return 'succeeded'
289
+ if (outcomes.includes('SKIPPED')) return 'skipped'
290
+ return null
291
+ }
292
+
293
+ /** @param {unknown} code @param {unknown} message @returns {OperationError|undefined} */
294
+ function errorOf(code, message) {
295
+ if (!code && !message) return undefined
296
+ return { code: typeof code === 'string' ? code : null, message: typeof message === 'string' ? redactText(message) : null }
297
+ }
298
+
299
+ /** @param {unknown} v @returns {string[]} */
300
+ function strList(v) {
301
+ return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []
302
+ }
303
+
304
+ /**
305
+ * Project a deployer run (and its per-module results) as an operation. The run id IS the operation id.
306
+ * @param {{ deploymentId?: string, run: Record<string, unknown>, moduleResults?: Array<Record<string, unknown>> }} input
307
+ * @returns {Operation}
308
+ */
309
+ function operationFromRun({ deploymentId, run, moduleResults = [] }) {
310
+ // A run started for an explicit first-admin request (deployer action admin-bootstrap) is that operation; so is a run
311
+ // started to attach or remove a custom domain.
312
+ const kind = run.adminBootstrap ? 'deployment.admin-bootstrap'
313
+ : loginDomainAction(run) ? `service.login-domain.${loginDomainAction(run)}`
314
+ : customDomainKind(run.customDomain) || KIND_BY_RUN_TYPE[String(run.type)] || `deployment.${String(run.type || 'run').toLowerCase()}`
315
+ const runStatus = statusFromRun(/** @type {string|undefined} */ (run.status))
316
+ const requested = strList(run.requestedServices).length ? strList(run.requestedServices) : strList(run.requestedModules)
317
+ const loginDomainService = loginDomainAction(run) ? String(/** @type {{ service?: unknown }} */ (run.loginDomain).service || '') : ''
318
+ const resultByName = new Map(moduleResults.filter((r) => typeof r.moduleName === 'string').map((r) => [String(r.moduleName), r]))
319
+ const names = [...requested, ...[...resultByName.keys()].filter((n) => !requested.includes(n))]
320
+ /** @type {OperationComponent[]} */
321
+ const components = names.map((name) => {
322
+ const result = resultByName.get(name)
323
+ const reported = result ? componentStatusFromResult(result) : null
324
+ /** @type {ComponentStatus} */
325
+ const status = reported || (runStatus === 'succeeded' ? 'succeeded' : runStatus === 'failed' ? 'unknown' : runStatus === 'superseded' ? 'skipped' : 'pending')
326
+ /** @type {OperationComponent} */
327
+ const component = { name: result && typeof result.component === 'string' ? result.component : name, status }
328
+ const error = result ? errorOf(result.errorCode, result.errorMessage) : undefined
329
+ if (error) component.error = error
330
+ if (result && result.detail && typeof result.detail === 'object' && !Array.isArray(result.detail)) {
331
+ component.detail = /** @type {Record<string, unknown>} */ (redact(result.detail))
332
+ }
333
+ const functionCode = result ? functionCodeOf(result.functionCode) : undefined
334
+ if (functionCode) component.functionCode = functionCode
335
+ if (result && typeof result.strategy === 'string' && STRATEGIES.includes(result.strategy)) {
336
+ component.strategy = /** @type {Strategy} */ (result.strategy)
337
+ if (typeof result.strategyReason === 'string' && result.strategyReason) component.strategyReason = redactText(result.strategyReason)
338
+ }
339
+ if (status === 'failed') {
340
+ component.nextAction = nextActionFor({ kind, deploymentId, run, service: name, retryable: result && result.retryable !== undefined ? result.retryable : run.retryable, blocked: run.blocked })
341
+ }
342
+ return component
343
+ })
344
+ const anySucceeded = components.some((c) => c.status === 'succeeded')
345
+ const anyFailed = components.some((c) => c.status === 'failed')
346
+ /** @type {OperationStatus} */
347
+ const status = (runStatus === 'failed' && anySucceeded) || (runStatus === 'succeeded' && anyFailed) ? 'partial' : runStatus
348
+ /** @type {Operation} */
349
+ const op = {
350
+ id: String(run.runId),
351
+ kind,
352
+ status,
353
+ components,
354
+ createdAt: typeof run.createdAt === 'string' ? run.createdAt : null,
355
+ updatedAt: typeof run.updatedAt === 'string' ? run.updatedAt : null,
356
+ requestKey: typeof run.idempotencyKey === 'string' ? run.idempotencyKey : typeof run.requestKey === 'string' ? run.requestKey : null,
357
+ }
358
+ if (deploymentId) op.deploymentId = deploymentId
359
+ // A delete destroy or a purge reports what it removed and what remains (ADR 0006 §5 purgeResult).
360
+ if (run.purgeResult && typeof run.purgeResult === 'object') op.purgeResult = /** @type {Record<string, unknown>} */ (run.purgeResult)
361
+ const error = errorOf(run.errorCode, run.errorMessage)
362
+ if (error) op.error = error
363
+ if (status === 'failed' || status === 'partial') {
364
+ op.nextAction = nextActionFor({ kind, deploymentId, run, service: loginDomainService || requested[0] || names[0], retryable: run.retryable, blocked: run.blocked })
365
+ }
366
+ return op
367
+ }
368
+
369
+ /**
370
+ * A simple synchronous write's response: the result, the request id and the resource's revision (no operation).
371
+ * @param {{ result: unknown, requestId: string, revision: number|string }} input
372
+ */
373
+ function syncWriteResult({ result, requestId, revision }) {
374
+ if (!requestId) throw new Error('syncWriteResult: requestId is required')
375
+ return { result: redact(result), requestId, revision }
376
+ }
377
+
378
+ // ---- Redaction ---------------------------------------------------------------------------------------
379
+
380
+ const REDACTED = '[REDACTED]'
381
+ const SECRET_KEY_RE = /pass(word|code)?$|secret|token|authorization|api[-_]?key|invitation|credential/i
382
+ const SECRET_NAMES = 'password|passcode|secret|clientSecret|token|idToken|accessToken|refreshToken|invitationToken|apiKey|api_key'
383
+
384
+ /**
385
+ * Remove bearer tokens, JWTs and `name=value` / `"name":"value"` secrets from free text.
386
+ * @param {string} text
387
+ */
388
+ function redactText(text) {
389
+ return String(text)
390
+ .replace(/Bearer\s+[^\s"',]+/gi, `Bearer ${REDACTED}`)
391
+ .replace(/eyJ[\w-]+\.[\w-]+\.[\w-]+/g, REDACTED)
392
+ .replace(new RegExp(`"(${SECRET_NAMES})"\\s*:\\s*"[^"]*"`, 'gi'), `"$1":"${REDACTED}"`)
393
+ .replace(new RegExp(`\\b(${SECRET_NAMES})=([^\\s&"',]+)`, 'gi'), `$1=${REDACTED}`)
394
+ }
395
+
396
+ /**
397
+ * Deep-copy a value with secret-named fields replaced and free-text secrets removed from strings.
398
+ * @template T
399
+ * @param {T} value
400
+ * @returns {T}
401
+ */
402
+ function redact(value) {
403
+ if (typeof value === 'string') return /** @type {T} */ (/** @type {unknown} */ (redactText(value)))
404
+ if (Array.isArray(value)) return /** @type {T} */ (/** @type {unknown} */ (value.map(redact)))
405
+ if (value && typeof value === 'object') {
406
+ /** @type {Record<string, unknown>} */
407
+ const out = {}
408
+ for (const [key, v] of Object.entries(value)) out[key] = SECRET_KEY_RE.test(key) && v != null ? REDACTED : redact(v)
409
+ return /** @type {T} */ (/** @type {unknown} */ (out))
410
+ }
411
+ return value
412
+ }
413
+
414
+ // ---- Logs + rendering --------------------------------------------------------------------------------
415
+
416
+ /**
417
+ * The structured log line for an operation (optionally focused on one component): operation {id, kind, status, component}.
418
+ * @param {Operation} op
419
+ * @param {string} [componentName]
420
+ */
421
+ function operationLogLine(op, componentName) {
422
+ /** @type {Record<string, unknown>} */
423
+ const line = { event: 'operation', id: op.id, kind: op.kind, status: op.status }
424
+ if (componentName) {
425
+ const c = op.components.find((x) => x.name === componentName)
426
+ if (c) line.component = { name: c.name, status: c.status, ...(c.error && c.error.code ? { errorCode: c.error.code } : {}) }
427
+ }
428
+ return redactText(JSON.stringify(line))
429
+ }
430
+
431
+ /**
432
+ * Human-readable lines for an operation — the one rendering the CLI and console share.
433
+ * @param {Operation} op
434
+ * @returns {string[]}
435
+ */
436
+ function formatOperation(op) {
437
+ const lines = [`operation ${op.id} (${op.kind}): ${op.status}`]
438
+ const width = Math.max(0, ...op.components.map((c) => c.name.length))
439
+ for (const c of op.components) {
440
+ const err = c.error ? ` ${[c.error.code, c.error.message].filter(Boolean).join(': ')}` : ''
441
+ const strategy = c.strategy ? ` ${[c.strategy, c.strategyReason].filter(Boolean).join(': ')}` : ''
442
+ lines.push(` ${c.name.padEnd(width)} ${c.status}${strategy}${err}`)
443
+ if (c.functionCode) {
444
+ const list = (/** @type {string[]} */ xs) => (xs.length ? xs.join(', ') : 'none')
445
+ lines.push(` ${''.padEnd(width)} functions updated: ${list(c.functionCode.updated)}; old: ${list(c.functionCode.old)}; unknown: ${list(c.functionCode.unknown)}`)
446
+ }
447
+ }
448
+ if (op.error && !op.components.some((c) => c.error)) lines.push(` error: ${[op.error.code, op.error.message].filter(Boolean).join(': ')}`)
449
+ const next = [...new Set([op.nextAction, ...op.components.map((c) => c.nextAction)].filter(Boolean))]
450
+ for (const n of next) lines.push(` next: ${n}`)
451
+ return lines
452
+ }
453
+
454
+ /**
455
+ * Poll an operation until it is terminal. Transient fetch errors (a dropped connection) are retried; after
456
+ * maxConsecutiveErrors in a row it gives up with an OPERATION_CONNECTION_LOST error naming the resume command. An
457
+ * error marked `fatal` (a 4xx such as a missing operation) is rethrown at once.
458
+ * @param {{ id: string, fetchOperation: () => Promise<Operation>, sleep?: (ms: number) => Promise<void>, intervalMs?: number, maxConsecutiveErrors?: number, onUpdate?: (op: Operation) => void, resumeCommand?: string }} input
459
+ * @returns {Promise<Operation>}
460
+ */
461
+ async function watchOperation({ id, fetchOperation, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), intervalMs = 5000, maxConsecutiveErrors = 5, onUpdate, resumeCommand }) {
462
+ let errors = 0
463
+ let lastSignature = ''
464
+ for (;;) {
465
+ try {
466
+ const op = await fetchOperation()
467
+ errors = 0
468
+ const signature = JSON.stringify([op.status, op.components])
469
+ if (signature !== lastSignature) {
470
+ lastSignature = signature
471
+ if (onUpdate) onUpdate(op)
472
+ }
473
+ if (isTerminal(op.status)) return op
474
+ } catch (err) {
475
+ if (err && /** @type {{ fatal?: boolean }} */ (err).fatal) throw err
476
+ errors++
477
+ if (errors >= maxConsecutiveErrors) {
478
+ const reason = err && /** @type {Error} */ (err).message ? /** @type {Error} */ (err).message : String(err)
479
+ const lost = /** @type {Error & { code?: string, operationId?: string }} */ (new Error(`lost connection while watching operation ${id} (${redactText(reason)})${resumeCommand ? ` — resume with: ${resumeCommand}` : ''}`))
480
+ lost.code = 'OPERATION_CONNECTION_LOST'
481
+ lost.operationId = id
482
+ throw lost
483
+ }
484
+ }
485
+ await sleep(intervalMs)
486
+ }
487
+ }
488
+
489
+ module.exports = {
490
+ OPERATION_STATUSES,
491
+ COMPONENT_STATUSES,
492
+ TERMINAL_STATUSES,
493
+ IDEMPOTENCY_RETENTION_SECONDS,
494
+ isTerminal,
495
+ createOperation,
496
+ transition,
497
+ rollupStatus,
498
+ updateComponent,
499
+ fingerprint,
500
+ idempotencyScopeKey,
501
+ idempotencyExpiry,
502
+ resolveIdempotency,
503
+ operationFromRun,
504
+ syncWriteResult,
505
+ redact,
506
+ redactText,
507
+ operationLogLine,
508
+ formatOperation,
509
+ watchOperation,
510
+ }