feat(scripts): DX-001 debug bundle CLI [Story-817]

Story 817Epic None20 files · +2112/−46

PR #178 · pramaan-io/pramaan-app · merged 2026-05-23

How it flows

sequenceDiagram
  autonumber
  participant dev as Developer
  participant cli as Debug CLI
  participant aws as AWS
  dev->>cli: pnpm debug 
  cli->>cli: validate UUIDv4
  cli->>aws: fetch CloudWatch (app-api, authorizer, Vercel)
  cli->>aws: pull Lambda metadata
  cli->>cli: apply env allowlist
  cli->>cli: render markdown
  cli->>dev: stdout + .debug-bundles/.md

pnpm-lock.yaml · +631 — new methods

Method	in → out	what it does
`CliError`	`(message)`

What changed, file by file

scripts/debug/index.ts+233

Entry point that validates the UUID, orchestrates the CloudWatch fetchers and Lambda metadata pull, renders markdown, and sanitizes provider errors.

new class	signature
`CliError`	`(message)`

What doesn't break

non-UUID input
missing AWS creds
missing log group
empty source
raw credentials in error

exits before AWS calls

suggests `aws sso login` or AWS_PROFILE

renders ERROR, no crash

shows EMPTY or 'no events found'

keys redacted before printing

bundles stay local — .debug-bundles/ is gitignored

raw appendix can carry operational payloads

Files changed (20)

File	±
`.gitignore`	+1
`docs/walkthroughs/story-817-walkthrough.html`	+128
`package.json`	+5
`pnpm-lock.yaml` ★	+631 −46
`scripts/debug/README.md`	+38
`scripts/debug/config.ts`	+20
`scripts/debug/index.ts` ★	+233
`scripts/debug/renderer/bundle.ts`	+81
`scripts/debug/renderer/code-refs.ts`	+110
`scripts/debug/renderer/error-index.ts`	+25
`scripts/debug/renderer/evidence-map.ts`	+68
`scripts/debug/renderer/metadata.ts`	+117
`scripts/debug/renderer/timeline.ts`	+22
`scripts/debug/runtime/allowlist.ts`	+9
`scripts/debug/runtime/lambda-metadata.ts`	+75
`scripts/debug/sources/cloudwatch-app-api.ts`	+70
`scripts/debug/sources/cloudwatch-authorizer.ts`	+75
`scripts/debug/sources/cloudwatch-vercel.ts`	+79
`scripts/debug/sources/shared.ts` ★	+200
`scripts/debug/types.ts`	+125