Skip to content

fix(infra): boot-diag empty-bucket guidance and boot.log selection - #1049

Merged
flipvh merged 1 commit into
mainfrom
fix/boot-diag-empty-bucket
Aug 14, 2026
Merged

fix(infra): boot-diag empty-bucket guidance and boot.log selection#1049
flipvh merged 1 commit into
mainfrom
fix/boot-diag-empty-bucket

Conversation

@flipvh

@flipvh flipvh commented Aug 13, 2026

Copy link
Copy Markdown
Member

Adopts raak's boot-diag improvements upstream (cellajs/raak#125, merged there), from a production incident where every deploy failed at cutover and pnpm --filter infra diag gave no useful signal.

What

  • Empty boot-diag prefix explains instead of aborting. aws s3 ls on a zero-object prefix exits 1 with no stdout and no stderr; createAwsReader.list() treated that as a fatal listing failure. New isEmptyPrefixLs() classifies it (exit 1 + empty stdout + empty stderr only, so AccessDenied / bad endpoint / bad bucket still abort), list() returns '' for it, and emptyBootDiagGuidance() prints the two known causes: the boot runner never ran (check serial console for ::<slug>:: markers and "BOOT FAILED"), or uploads are denied because the boot principal predates the IAM v2 model (Scaleway does not honor bucket-policy-only grants). Every boot uploads a transcript, success or failure (boot.ts finally), so an empty prefix is a finding, not an error.
  • selectDiagnostics picks the actual transcript. The sibling <svc>-<stamp>-events.jsonl sorts after <svc>-<stamp>-boot.log, so .at(-1) returned raw OTLP records instead of the readable transcript. latestFull is now pinned to -boot.log keys.
  • renderDiagnostics prints a single "nothing was ever uploaded" line when a service owns zero objects, instead of misleading per-section noise.
  • diag.ts threads appConfig.slug into the guidance and prints it when parseKeys yields nothing (except under --replay).

Delta from the raak original

raak's guidance pointed at the infra CLI "Migrate IAM model" flow, which no longer exists: the IAM migration machinery was deleted in #1024 (IAM v2 only). The guidance (and its test) now points at the "Stack setup" apply, which is what provisions the current boot principal (ObjectStorageObjectsWrite via BOOT_PROJECT_PERMISSION_SETS).

Not adopted: raak's cella/migrations/manifest.json roots tweak for 20260730T0858-frontend-module-placements. That migration precedes 20260730T1258-cella-config-into-cella-folder in replay order, so cella.config.ts is still at the repo root at that point in the sequence; the existing value is correct.

Verification

  • pnpm --filter infra exec vitest run: 78 files, 665 passed (includes new coverage for isEmptyPrefixLs, empty-prefix listing, boot.log-over-events selection, and the single no-diagnostics line)
  • pnpm check: clean
  • Not sync-breaking, no migration needed; behavior-only improvement to a diagnostic tool. raak converges on its next pnpm cella sync. projectcampus's copies are byte-identical to current main, so it inherits conflict-free.

🤖 Generated with Claude Code

Adopted from raak (cellajs/raak#125), which debugged a production incident
where every deploy failed at cutover and diag gave no signal.

- aws s3 ls on a zero-object prefix exits 1 with no output; treat that as a
  finding (nothing was ever uploaded) instead of a fatal listing error, and
  print actionable guidance naming the two known causes (boot runner never
  ran, or uploads denied by a pre-v2 boot principal). Real failures still
  abort: they carry stderr.
- selectDiagnostics pinned latestFull to -boot.log keys; the sibling
  -events.jsonl sorted after it and won .at(-1), replacing the readable
  transcript with raw OTLP records.
- renderDiagnostics prints a single no-diagnostics line when a service owns
  zero objects instead of misleading per-section noise.

One delta from the raak original: its guidance pointed at the infra CLI
"Migrate IAM model" flow, which was deleted in #1024 (IAM v2 only); the
guidance now points at the "Stack setup" apply, which provisions the
current boot principal.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@flipvh
flipvh merged commit c73c84b into main Aug 14, 2026
9 checks passed
@flipvh
flipvh deleted the fix/boot-diag-empty-bucket branch August 14, 2026 08:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant