feat(scan): brotli-compress .socket.facts.json on upload (port of #1291)

[John-David Dalton (jdalton)]

Summary

Port of Benjamin Barslev Nielsen (@barslev)'s PR #1291 from v1.x to main. v1.x lives on a flat src/ layout; main has the monorepo packages/cli/src/ layout and uses @socketsecurity/lib instead of @socketsecurity/registry. Behaviour is identical to the original.

• New helper packages/cli/src/utils/coana/compress-facts.mts exporting compressSocketFactsForUpload(scanPaths). For each .socket.facts.json in scanPaths, it stream-brotli-compresses a sibling .socket.facts.json.br next to the source file and swaps the path. Returns { paths, cleanup }.
• handleCreateNewScan calls the helper just before fetchCreateOrgFullScan and runs cleanup() in finally so the sibling .br files are removed whether the upload succeeded or threw.
• Sibling-write (rather than OS tmp dir) keeps the multipart entry name inside cwd — depscan's addStreamEntry rejects entries with .. traversal segments because the SDK computes the entry name via path.relative(cwd, brPath). depscan's api-v0 multipart boundary streams brotli decode based on the .br filename suffix, so on-the-wire is brotli while coana keeps writing plain JSON on disk (existing readers extractTier1ReachabilityScanId etc. stay correct).

Translation notes (v1.x → main)

v1.x	main
src/utils/coana.mts (single file with all helpers)	packages/cli/src/utils/coana/{extract-scan-id,spawn,compress-facts}.mts (split per-helper)
@socketsecurity/registry/lib/fs	@socketsecurity/lib/fs
import { rm } from 'node:fs/promises' + rm(path, { force: true })	safeDelete(paths, { force: true }) from @socketsecurity/lib/fs (fleet-wide rule — never call fs.rm directly)
import constants from '../../constants.mts' then constants.DOT_SOCKET_DOT_FACTS_JSON	named import import { DOT_SOCKET_DOT_FACTS_JSON } from '../../constants.mts' (canonical export shape on main)
Tests in src/utils/coana.test.mts covering scan-id, errors, and compress-facts	scan-id tests already live in test/unit/utils/coana/extract-scan-id.test.mts; main has no extractReachabilityErrors yet; new tests for the brotli helper land at test/unit/utils/coana/compress-facts.test.mts (5 tests)

Test plan

• pnpm --filter @socketsecurity/cli run type (tsc --noEmit) — passes
• pnpm --filter @socketsecurity/cli run lint (oxlint) — passes
• Targeted vitest:
  • test/unit/utils/coana/compress-facts.test.mts — 5/5 (writes brotli sibling, leaves non-facts paths alone, leaves missing paths alone, mixes correctly, cleanup is idempotent)
  • test/unit/utils/coana/extract-scan-id.test.mts — 9/9 (untouched, regression check)
  • test/unit/utils/coana/spawn.test.mts — 8/8 (untouched, regression check)
  • test/unit/commands/scan/handle-create-new-scan.test.mts — 10/10 (helper is called for real on path arrays of non-facts files; passes through unchanged)

Total: 32/32 tests pass on the touched code paths.

Credit

Original implementation by Benjamin Barslev Nielsen (@barslev) in #1291 against v1.x. The v1.x PR can be closed once this lands on main.

---

Note

Medium Risk
Moderate risk because it changes the set of files uploaded for scans and introduces temporary sibling .br artifacts that must be reliably cleaned up, which could affect scan creation if compression or cleanup fails.

Overview
Scan creation now Brotli-compresses any .socket.facts.json files right before upload by swapping them to sibling .socket.facts.json.br paths, then always deleting those .br files in a finally block after fetchCreateOrgFullScan completes.

This adds a new compressSocketFactsForUpload() helper (with unit tests) that streams compression to avoid blocking the CLI and leaves non-facts or missing paths unchanged.

^{Reviewed by Cursor Bugbot for commit 4aef3ec. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 4aef3ec. Configure here.}

[cursor]

Test file uses rmSync instead of safeDelete

Low Severity

The new test file imports and uses rmSync from node:fs five times for directory cleanup. The project convention (explicitly noted in fs.test.mts as "NEVER fs.rm/rmSync") requires using safeDelete from @socketsecurity/lib/fs. Since all test callbacks here are async, safeDelete is the correct choice. Other test files like config.test.mts follow this pattern correctly.

Additional Locations (1)

• packages/cli/test/unit/utils/coana/compress-facts.test.mts#L53-L54

 

^{Triggered by learned rule: No raw fs.rm or rm -rf — use safeDelete from @socketsecurity/lib/fs}

^{Reviewed by Cursor Bugbot for commit 4aef3ec. Configure here.}

[cursor]

Orphaned .br files on compression failure

Low Severity

If pipeline throws for any .socket.facts.json entry (e.g., disk-full, I/O error), the Promise.all rejects and compressSocketFactsForUpload throws before returning the cleanup callback. Any .br files already created by completed sibling pipelines, or partially written by the failing createWriteStream, are orphaned on disk with no cleanup path available to the caller.

 

^{Reviewed by Cursor Bugbot for commit 4aef3ec. Configure here.}