[ENG-3564] map: upload the attack surface to Pulse behind an explicit --upload flag

[patchstackdave]

Closes the loop between two halves that already existed: map described the app's surface, the server can receive one, nothing sent it.

patchstack-connect map --upload
  → POST monitor/pulse/input-map/<site uuid>
  → "uploaded the attack surface (revision 1)" / "unchanged since revision 1" / a reported failure

Design calls

Opt-in, never implied. This is the only path that transmits anything derived from source code, so it takes an explicit flag rather than firing because a site UUID happens to exist. With the flag the document goes to Patchstack instead of stdout.

Fail-open by construction. Every path returns an outcome rather than throwing — this runs inside someone's build. A 422 is reported as a schema mismatch by version ("update @patchstack/connect") rather than retried or coerced: it means the two sides implement different map schemas, and guessing at compatibility is exactly how a consumer misreads a document. unchanged is a first-class result, not a failure.

Disclosure — the part that must not lag the code

README and AGENT-INSTALL both said map "transmits nothing". That becomes false the moment this ships, so both now state exactly what --upload sends (route paths, parameter names, the dependency behind each sink, file/line locations) and what it does not (no source code, no file contents, no env values).

⚠️ Same file and bullet as #133 (the tier-wording fix), so whichever lands second needs a trivial rebase. Both are field-test gated and travel with the package, so the --persona hostile run belongs against the published tarball at release.

Verified end to end, not just with mocks

Against a local Pulse server, with a real project:

upload #1                    → uploaded the attack surface (revision 1)
upload #2 (same surface)     → unchanged since revision 1 — nothing to store
upload #3 (endpoint added)   → uploaded the attack surface (revision 2)
generate                     → pinned post.sql (/report) + post.q (/export), exact-local
GET /monitor/pulse/rules/…   → both served, dry-run enforcement

That run also found a bug the server-side tests could not: the ingest path was missing from the CSRF exemption list, so a real client got 419 while every feature test passed (postJson bypasses CSRF). Fixed on the saas branch.

12 upload tests, 940 total, typecheck clean.

[coderbuds]

Implements a clear opt-in --upload flag with comprehensive coverage tests.

🎯 Quality: 100% Elite · 📦 Size: Medium

📈 This month: Your 67th PR — above team average · Averaging Excellent

_{See how your team is trending →}

[patchstackdave]

/review