sharpit 0.1.0__tar.gz → 0.2.0__tar.gz

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 (253) hide show
  1. {sharpit-0.1.0 → sharpit-0.2.0}/.gitignore +4 -0
  2. sharpit-0.2.0/CHANGELOG.md +94 -0
  3. sharpit-0.2.0/PKG-INFO +149 -0
  4. sharpit-0.2.0/README.md +101 -0
  5. {sharpit-0.1.0 → sharpit-0.2.0}/docs/README.md +1 -0
  6. sharpit-0.2.0/docs/development/overhead-budgets.md +57 -0
  7. {sharpit-0.1.0 → sharpit-0.2.0}/docs/development/workflow.md +4 -4
  8. {sharpit-0.1.0 → sharpit-0.2.0}/docs/reference/BOOTUI-PYTHON-MAPPING.md +19 -0
  9. sharpit-0.2.0/examples/fastapi_sqla/__init__.py +7 -0
  10. sharpit-0.2.0/examples/fastapi_sqla/alembic.ini +27 -0
  11. sharpit-0.2.0/examples/fastapi_sqla/app.py +228 -0
  12. sharpit-0.2.0/examples/fastapi_sqla/migrations/env.py +53 -0
  13. sharpit-0.2.0/examples/fastapi_sqla/migrations/script.py.mako +28 -0
  14. sharpit-0.2.0/examples/fastapi_sqla/migrations/versions/0001_owners.py +32 -0
  15. sharpit-0.2.0/examples/fastapi_sqla/migrations/versions/0002_pets.py +33 -0
  16. sharpit-0.2.0/examples/fastapi_sqla/migrations/versions/0003_visits.py +33 -0
  17. {sharpit-0.1.0 → sharpit-0.2.0}/pyproject.toml +20 -3
  18. sharpit-0.2.0/sonar-baseline.txt +1 -0
  19. sharpit-0.2.0/sonar-project.properties +19 -0
  20. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/__init__.py +1 -1
  21. sharpit-0.2.0/src/sharpit/engine/advisors/__init__.py +1 -0
  22. {sharpit-0.1.0/src/sharpit/engine/collectors/vulns → sharpit-0.2.0/src/sharpit/engine/advisors}/dismissals.py +17 -4
  23. sharpit-0.2.0/src/sharpit/engine/advisors/report.py +62 -0
  24. sharpit-0.2.0/src/sharpit/engine/advisors/retention.py +117 -0
  25. sharpit-0.2.0/src/sharpit/engine/advisors/rules.py +70 -0
  26. sharpit-0.2.0/src/sharpit/engine/capture/__init__.py +52 -0
  27. sharpit-0.2.0/src/sharpit/engine/capture/activity.py +314 -0
  28. sharpit-0.2.0/src/sharpit/engine/capture/correlation.py +38 -0
  29. sharpit-0.2.0/src/sharpit/engine/capture/exceptions.py +374 -0
  30. sharpit-0.2.0/src/sharpit/engine/capture/exchanges.py +191 -0
  31. sharpit-0.2.0/src/sharpit/engine/capture/frames.py +28 -0
  32. sharpit-0.2.0/src/sharpit/engine/capture/logtail.py +176 -0
  33. sharpit-0.2.0/src/sharpit/engine/capture/sqltrace.py +626 -0
  34. sharpit-0.2.0/src/sharpit/engine/capture/streams.py +228 -0
  35. sharpit-0.2.0/src/sharpit/engine/collectors/alembic.py +429 -0
  36. sharpit-0.2.0/src/sharpit/engine/collectors/health.py +257 -0
  37. sharpit-0.2.0/src/sharpit/engine/collectors/pools.py +83 -0
  38. sharpit-0.2.0/src/sharpit/engine/collectors/restapi/__init__.py +1 -0
  39. sharpit-0.2.0/src/sharpit/engine/collectors/restapi/report.py +81 -0
  40. sharpit-0.2.0/src/sharpit/engine/collectors/restapi/rules.py +724 -0
  41. sharpit-0.2.0/src/sharpit/engine/collectors/restapi/service.py +108 -0
  42. sharpit-0.2.0/src/sharpit/engine/collectors/threads.py +210 -0
  43. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/vulns/service.py +9 -10
  44. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/context.py +15 -2
  45. sharpit-0.2.0/src/sharpit/engine/daemon_executor.py +36 -0
  46. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/guard.py +21 -0
  47. sharpit-0.2.0/src/sharpit/engine/masking.py +229 -0
  48. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/panels.py +12 -0
  49. sharpit-0.2.0/src/sharpit/engine/probe.py +362 -0
  50. sharpit-0.2.0/src/sharpit/engine/singleflight.py +80 -0
  51. sharpit-0.2.0/src/sharpit/engine/spi.py +69 -0
  52. sharpit-0.2.0/src/sharpit/engine/sqla.py +418 -0
  53. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/tools.py +368 -9
  54. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/fastapi/adapter.py +369 -36
  55. sharpit-0.2.0/src/sharpit/fastapi/capture.py +389 -0
  56. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/fastapi/introspector.py +75 -3
  57. sharpit-0.2.0/src/sharpit/fastapi/sse.py +77 -0
  58. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/settings.py +64 -1
  59. sharpit-0.2.0/src/sharpit/ui/static/assets/index-Buho1zW1.js +14 -0
  60. sharpit-0.2.0/src/sharpit/ui/static/assets/index-DuLAbl33.css +1 -0
  61. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/ui/static/index.html +2 -2
  62. sharpit-0.2.0/tests/complexity_baseline.json +17 -0
  63. {sharpit-0.1.0 → sharpit-0.2.0}/tests/conftest.py +99 -4
  64. sharpit-0.2.0/tests/engine/advisors/test_advisor_report.py +83 -0
  65. sharpit-0.2.0/tests/engine/advisors/test_advisor_rules.py +55 -0
  66. {sharpit-0.1.0/tests/engine/vulns → sharpit-0.2.0/tests/engine/advisors}/test_dismissals.py +54 -4
  67. sharpit-0.2.0/tests/engine/advisors/test_retention.py +135 -0
  68. sharpit-0.2.0/tests/engine/capture/test_activity.py +402 -0
  69. sharpit-0.2.0/tests/engine/capture/test_correlation.py +145 -0
  70. sharpit-0.2.0/tests/engine/capture/test_exceptions.py +565 -0
  71. sharpit-0.2.0/tests/engine/capture/test_exchanges.py +218 -0
  72. sharpit-0.2.0/tests/engine/capture/test_logtail.py +267 -0
  73. sharpit-0.2.0/tests/engine/capture/test_sqltrace.py +579 -0
  74. sharpit-0.2.0/tests/engine/capture/test_streams.py +240 -0
  75. sharpit-0.2.0/tests/engine/restapi/test_restapi_registry.py +103 -0
  76. sharpit-0.2.0/tests/engine/restapi/test_restapi_report.py +245 -0
  77. sharpit-0.2.0/tests/engine/restapi/test_restapi_rules.py +203 -0
  78. sharpit-0.2.0/tests/engine/test_alembic.py +191 -0
  79. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_beans.py +5 -2
  80. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_context.py +20 -0
  81. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_guard.py +20 -5
  82. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_headers.py +4 -2
  83. sharpit-0.2.0/tests/engine/test_health.py +354 -0
  84. sharpit-0.2.0/tests/engine/test_import_boundary.py +160 -0
  85. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_loggers.py +6 -3
  86. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_mappings.py +2 -1
  87. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_masking.py +110 -0
  88. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_mcp.py +24 -5
  89. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_paging.py +5 -2
  90. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_panels.py +19 -1
  91. sharpit-0.2.0/tests/engine/test_pools.py +144 -0
  92. sharpit-0.2.0/tests/engine/test_probe.py +117 -0
  93. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_singleflight.py +46 -1
  94. sharpit-0.2.0/tests/engine/test_sqla.py +386 -0
  95. sharpit-0.2.0/tests/engine/test_threads.py +418 -0
  96. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_tools.py +128 -6
  97. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/vulns/test_interpreter.py +4 -2
  98. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/vulns/test_service.py +9 -4
  99. sharpit-0.2.0/tests/fastapi/test_activity_api.py +184 -0
  100. sharpit-0.2.0/tests/fastapi/test_alembic_api.py +191 -0
  101. sharpit-0.2.0/tests/fastapi/test_capture_hooks.py +81 -0
  102. sharpit-0.2.0/tests/fastapi/test_capture_overhead.py +80 -0
  103. sharpit-0.2.0/tests/fastapi/test_capture_wiring.py +491 -0
  104. sharpit-0.2.0/tests/fastapi/test_change_streams.py +132 -0
  105. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_cli_api.py +21 -2
  106. sharpit-0.2.0/tests/fastapi/test_dismissed_rules_api.py +86 -0
  107. sharpit-0.2.0/tests/fastapi/test_exceptions_api.py +489 -0
  108. sharpit-0.2.0/tests/fastapi/test_health_api.py +68 -0
  109. sharpit-0.2.0/tests/fastapi/test_http_exchanges_api.py +85 -0
  110. sharpit-0.2.0/tests/fastapi/test_http_probe_api.py +644 -0
  111. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_install.py +25 -1
  112. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_introspector_providers.py +13 -6
  113. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_introspector_routes.py +9 -6
  114. sharpit-0.2.0/tests/fastapi/test_log_tail_api.py +406 -0
  115. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_loggers_api.py +2 -1
  116. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_mcp_api.py +5 -1
  117. sharpit-0.2.0/tests/fastapi/test_panel_availability.py +77 -0
  118. sharpit-0.2.0/tests/fastapi/test_pools_api.py +49 -0
  119. sharpit-0.2.0/tests/fastapi/test_rest_api_api.py +222 -0
  120. sharpit-0.2.0/tests/fastapi/test_sql_trace_api.py +390 -0
  121. sharpit-0.2.0/tests/fastapi/test_sql_trace_overhead.py +66 -0
  122. sharpit-0.2.0/tests/fastapi/test_sqla_absent.py +153 -0
  123. sharpit-0.2.0/tests/fastapi/test_stream_lifetime.py +56 -0
  124. sharpit-0.2.0/tests/fastapi/test_threads_api.py +90 -0
  125. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_vulns_api.py +7 -4
  126. sharpit-0.2.0/tests/fixtures/alembic/branch_merge/alembic.ini +2 -0
  127. sharpit-0.2.0/tests/fixtures/alembic/branch_merge/migrations/versions/base.py +4 -0
  128. sharpit-0.2.0/tests/fixtures/alembic/branch_merge/migrations/versions/left.py +4 -0
  129. sharpit-0.2.0/tests/fixtures/alembic/branch_merge/migrations/versions/merge.py +4 -0
  130. sharpit-0.2.0/tests/fixtures/alembic/branch_merge/migrations/versions/right.py +4 -0
  131. sharpit-0.2.0/tests/fixtures/alembic/branch_merge/migrations/versions/side.py +4 -0
  132. sharpit-0.2.0/tests/fixtures/alembic/branch_merge/migrations/versions/tip.py +4 -0
  133. sharpit-0.2.0/tests/fixtures/alembic/broken/alembic.ini +2 -0
  134. sharpit-0.2.0/tests/fixtures/alembic/broken/migrations/versions/not_a_revision.py +3 -0
  135. sharpit-0.2.0/tests/fixtures/alembic/broken/migrations/versions/ok1_fine.py +4 -0
  136. sharpit-0.2.0/tests/fixtures/alembic/linear/alembic.ini +6 -0
  137. sharpit-0.2.0/tests/fixtures/alembic/linear/migrations/env.py +3 -0
  138. sharpit-0.2.0/tests/fixtures/alembic/linear/migrations/versions/a1_create_owners.py +15 -0
  139. sharpit-0.2.0/tests/fixtures/alembic/linear/migrations/versions/b2_add_pets.py +14 -0
  140. sharpit-0.2.0/tests/fixtures/alembic/linear/migrations/versions/c3_add_visits.py +12 -0
  141. sharpit-0.2.0/tests/fixtures/alembic/modern_template/alembic.ini +4 -0
  142. sharpit-0.2.0/tests/fixtures/alembic/modern_template/migrations/versions/1f2e3d4c5b6a_initial.py +18 -0
  143. sharpit-0.2.0/tests/fixtures/alembic/modern_template/migrations/versions/9a8b7c6d5e4f_add_index.py +12 -0
  144. sharpit-0.2.0/tests/fixtures/alembic/package_dir/alembic.ini +2 -0
  145. sharpit-0.2.0/tests/fixtures/alembic/package_dir/sharpit_alembic_fixture_pkg/__init__.py +3 -0
  146. sharpit-0.2.0/tests/fixtures/alembic/package_dir/sharpit_alembic_fixture_pkg/migrations/versions/p1_first.py +4 -0
  147. sharpit-0.2.0/tests/fixtures/bootui_tools_0_2_0.json +211 -0
  148. sharpit-0.2.0/tests/fixtures/restapi/rest_api_check_ids.txt +58 -0
  149. sharpit-0.2.0/tests/overhead.py +80 -0
  150. sharpit-0.2.0/tests/test_code_shape.py +74 -0
  151. sharpit-0.2.0/tests/test_dogfood_sqla.py +112 -0
  152. {sharpit-0.1.0 → sharpit-0.2.0}/tests/test_fixtures.py +7 -1
  153. sharpit-0.2.0/tests/test_masking_corpus.py +605 -0
  154. sharpit-0.2.0/tests/test_overhead_check.py +44 -0
  155. sharpit-0.2.0/tests/test_overhead_harness.py +121 -0
  156. {sharpit-0.1.0 → sharpit-0.2.0}/tests/test_packaging.py +6 -0
  157. sharpit-0.2.0/tests/test_pytest_speed_check.py +5 -0
  158. {sharpit-0.1.0 → sharpit-0.2.0}/tests/test_release_workflow.py +29 -0
  159. sharpit-0.2.0/tests/test_safety_matrix.py +692 -0
  160. sharpit-0.2.0/tests/test_sanitize_golden.py +16 -0
  161. {sharpit-0.1.0 → sharpit-0.2.0}/tests/test_settings.py +143 -0
  162. sharpit-0.2.0/tests/test_sonar_ratchet.py +18 -0
  163. sharpit-0.2.0/tests/test_sqla_sample_smoke.py +138 -0
  164. sharpit-0.2.0/website/docs/activation.md +19 -0
  165. sharpit-0.2.0/website/docs/deviations.md +5 -0
  166. sharpit-0.2.0/website/docs/how-it-works.md +186 -0
  167. sharpit-0.2.0/website/docs/index.md +24 -0
  168. sharpit-0.2.0/website/docs/installation.md +16 -0
  169. sharpit-0.2.0/website/docs/mcp.md +64 -0
  170. sharpit-0.2.0/website/docs/panels.md +27 -0
  171. sharpit-0.2.0/website/docs/quickstart.md +36 -0
  172. sharpit-0.2.0/website/docs/safety.md +39 -0
  173. sharpit-0.2.0/website/docs/settings.md +76 -0
  174. sharpit-0.2.0/website/mkdocs.yml +82 -0
  175. sharpit-0.2.0/website/requirements.in +3 -0
  176. sharpit-0.2.0/website/requirements.txt +570 -0
  177. sharpit-0.1.0/CHANGELOG.md +0 -61
  178. sharpit-0.1.0/PKG-INFO +0 -247
  179. sharpit-0.1.0/README.md +0 -204
  180. sharpit-0.1.0/docs/how-it-works.md +0 -108
  181. sharpit-0.1.0/src/sharpit/engine/masking.py +0 -106
  182. sharpit-0.1.0/src/sharpit/engine/singleflight.py +0 -37
  183. sharpit-0.1.0/src/sharpit/engine/spi.py +0 -44
  184. sharpit-0.1.0/src/sharpit/ui/static/assets/index-B35rjvFd.css +0 -1
  185. sharpit-0.1.0/src/sharpit/ui/static/assets/index-BuJxUNPy.js +0 -6
  186. sharpit-0.1.0/tests/test_masking_corpus.py +0 -297
  187. sharpit-0.1.0/tests/test_safety_matrix.py +0 -404
  188. {sharpit-0.1.0 → sharpit-0.2.0}/.gitattributes +0 -0
  189. {sharpit-0.1.0 → sharpit-0.2.0}/LICENSE +0 -0
  190. {sharpit-0.1.0 → sharpit-0.2.0}/NOTICE +0 -0
  191. {sharpit-0.1.0 → sharpit-0.2.0}/docs/reference/BOOTUI-CONTRACT-MVP.md +0 -0
  192. {sharpit-0.1.0 → sharpit-0.2.0}/docs/reports/2026-10-31-dogfood-klipermedia.md +0 -0
  193. {sharpit-0.1.0 → sharpit-0.2.0}/docs/reports/2026-10-31-mvp-retrospective.md +0 -0
  194. {sharpit-0.1.0 → sharpit-0.2.0}/docs/reports/2026-10-31-mvp-summary.md +0 -0
  195. {sharpit-0.1.0 → sharpit-0.2.0}/examples/fastapi_sample/app.py +0 -0
  196. {sharpit-0.1.0 → sharpit-0.2.0}/examples/fastapi_sample/static/hello.txt +0 -0
  197. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/__init__.py +0 -0
  198. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/activation.py +0 -0
  199. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/__init__.py +0 -0
  200. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/beans.py +0 -0
  201. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/config/__init__.py +0 -0
  202. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/config/getenv_scan.py +0 -0
  203. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/config/settings_source.py +0 -0
  204. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/loggers.py +0 -0
  205. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/mappings.py +0 -0
  206. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/overview.py +0 -0
  207. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/vulns/__init__.py +0 -0
  208. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/vulns/cvss.py +0 -0
  209. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/vulns/epss.py +0 -0
  210. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/vulns/interpreter.py +0 -0
  211. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/vulns/inventory.py +0 -0
  212. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/collectors/vulns/osv.py +0 -0
  213. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/headers.py +0 -0
  214. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/mcp.py +0 -0
  215. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/paging.py +0 -0
  216. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/engine/relaxed.py +0 -0
  217. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/fastapi/__init__.py +0 -0
  218. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/fastapi/http.py +0 -0
  219. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/fastapi/signals.py +0 -0
  220. {sharpit-0.1.0 → sharpit-0.2.0}/src/sharpit/py.typed +0 -0
  221. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/config/test_config_report.py +0 -0
  222. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/config/test_getenv_scan.py +0 -0
  223. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/config/test_settings_source.py +0 -0
  224. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_activation.py +0 -0
  225. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_overview.py +0 -0
  226. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/test_relaxed.py +0 -0
  227. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/vulns/test_cvss.py +0 -0
  228. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/vulns/test_epss.py +0 -0
  229. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/vulns/test_inventory.py +0 -0
  230. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/vulns/test_osv.py +0 -0
  231. {sharpit-0.1.0 → sharpit-0.2.0}/tests/engine/vulns/vulnfakes.py +0 -0
  232. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_concurrency.py +0 -0
  233. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fastapi/test_signals.py +0 -0
  234. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/beans.json +0 -0
  235. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/config.json +0 -0
  236. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/health.json +0 -0
  237. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/loggers.json +0 -0
  238. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/mappings.json +0 -0
  239. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/meta.json +0 -0
  240. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/overview.json +0 -0
  241. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/panels.json +0 -0
  242. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/bootui/vulnerabilities.json +0 -0
  243. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/epss/CVE-2024-34064.json +0 -0
  244. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/getenv_corpus/pkg/__init__.py +0 -0
  245. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/getenv_corpus/pkg/forms.py +0 -0
  246. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/osv/GHSA-h75v-3vvj-5mfj.json +0 -0
  247. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/osv/PYSEC-2017-9999.json +0 -0
  248. {sharpit-0.1.0 → sharpit-0.2.0}/tests/fixtures/osv/querybatch.json +0 -0
  249. {sharpit-0.1.0 → sharpit-0.2.0}/tests/pytest_speed_exceptions.json +0 -0
  250. {sharpit-0.1.0 → sharpit-0.2.0}/tests/test_conformance.py +0 -0
  251. {sharpit-0.1.0 → sharpit-0.2.0}/tests/test_durations.json +0 -0
  252. {sharpit-0.1.0 → sharpit-0.2.0}/tests/test_durations.meta.json +0 -0
  253. {sharpit-0.1.0 → sharpit-0.2.0}/tests/test_example_app.py +0 -0
@@ -20,3 +20,7 @@ ui/playwright-report/
20
20
  .serena/
21
21
  *.egg-info/
22
22
  .env
23
+
24
+ # sample app database (examples/fastapi_sqla)
25
+ examples/fastapi_sqla/sample.db
26
+ website/site/
@@ -0,0 +1,94 @@
1
+ # Changelog
2
+
3
+ All notable changes to sharpit are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
4
+ and the project uses [Semantic Versioning](https://semver.org/).
5
+
6
+ ## [Unreleased]
7
+
8
+ ## [0.2.0] - 2026-10-31
9
+
10
+ ### Added
11
+
12
+ - F1 (HTTP Exchanges): `http-exchanges` panel and endpoint with a ring buffer of recent HTTP requests, duration, headers, status code, and path masking.
13
+ - F2 (Exceptions): `exceptions` panel and endpoints capturing unhandled errors from middleware, wrapped handlers, and log records, grouped by class and innermost application frame.
14
+ - F3 (SQL Trace): `sql-trace` panel, endpoints, and live SSE stream capturing SQLAlchemy queries via class-level events with statement categorization, normalized SQL, and slow query alerts.
15
+ - F4 (Live Activity): `activity` panel and live SSE stream correlating HTTP requests, SQL queries, and exceptions with N+1 query detection.
16
+ - F5 (Log Tail): `log-tail` panel, endpoints, and live SSE stream buffering recent logs with a 1 MiB memory cap and resume token support.
17
+ - F6 (Migrations): `alembic` panel inspecting Alembic migrations in Flyway-compatible format, with database versions read on POST `alembic/refresh`.
18
+ - F7 (Database Connection Pools): `database-connection-pools` panel and endpoint reporting SQLAlchemy pool sizes, active checkouts, and overflow status.
19
+ - F8 (Health): `health` panel and endpoint checking registered database engines via dialect ping and running custom checks on POST `health/check`.
20
+ - F9 (Threads and asyncio tasks): `threads` panel and endpoint dumping active threads and running asyncio tasks with request correlation.
21
+ - F10 (REST API advisor): `rest-api` advisor panel and endpoints running static analysis checks over FastAPI routes with severity scoring and violation paging.
22
+ - F11 (Shared advisor plumbing): shared rule definitions, single-flight scans, violation retention endpoint, and per-panel dismissal gates.
23
+ - F12 (HTTP Probe): `http-probe` panel and endpoint executing in-process ASGI calls against local routes with loopback protection and response masking.
24
+ - MCP and CLI tools for the new panels: `get_http_exchanges`, `get_exceptions`, `get_exception_detail`, `get_sql_traces`,
25
+ `get_live_activity`, `get_log_tail`, `get_alembic_migrations`, `get_database_connection_pools`, `get_health`, `get_threads`,
26
+ `get_rest_api_report`, `get_rest_api_rule_violations`.
27
+ - Documentation site (MkDocs Material) published to GitHub Pages; the README links to it.
28
+ - `fastapi_sqla` sample app for trying the SQL panels against a real FastAPI app.
29
+
30
+ ### Changed
31
+
32
+ - Rule dismissals now check the owning panel's enabled and read-only state (`RAPI-` for `rest-api`, `::pypi:` for `vulnerabilities`), returning 403 when the panel is read-only or disabled.
33
+ - Client disconnect before response completion records status 499 in HTTP exchanges.
34
+ - Exception fingerprints group by exception class and innermost application frame rather than top stack frames.
35
+ - SQL trace uses SQLAlchemy class-level listeners rather than JDBC proxies; SQL literals are normalized and masked when parameter capture is disabled.
36
+ - Live streams (SSE) close every 3 seconds (`SHARPIT_STREAM_MAX_SECONDS`) with a retry hint to prevent blocking uvicorn reload or lifespan shutdown.
37
+ - Total concurrent live streams across all panels are capped at 20, returning HTTP 503 when full.
38
+ - Alembic database-version reads and database health checks run on POST requests (`alembic/refresh`, `health/check`) and serve cached results on GET to ensure GET requests have no side effects.
39
+ - Database connection pool reports strip query strings from database connection URLs (emitted in `jdbcUrl` for BootUI parity) to prevent secret leakage.
40
+ - Threads panel includes asyncio tasks with request correlation; OS thread states are inferred as RUNNABLE or WAITING without JVM CPU or lock metrics.
41
+ - HTTP probe executes directly via in-process ASGI calls without opening network sockets, refusing paths under the sharpit mount.
42
+ - Release workflow uploads only `.whl` and `.tar.gz` assets to GitHub Releases.
43
+ - The default branch is `main` (was `master`); CI, docs, skills and badges point at it.
44
+
45
+ ## [0.1.0] - 2026-10-31
46
+
47
+ First release: an embedded, local-only developer console for FastAPI apps, ported from
48
+ [BootUI](https://github.com/jdubois/boot-ui) (Julien Dubois, Apache-2.0).
49
+
50
+ ### Added
51
+
52
+ - `sharpit.install(app, settings=..., **options)` mounts the console at `/sharpit` and a BootUI-compatible JSON API at
53
+ `/sharpit/api`. `settings=` takes pydantic-settings instances so the Config panel can show each value's source.
54
+ - Panels: Overview, Configuration (environment, `.env`, pydantic-settings and `os.getenv` keys, masked), Mappings,
55
+ Loggers (runtime level changes), Beans (dependency providers, middleware, lifespan), Vulnerabilities (OSV scan with
56
+ EPSS scores, on explicit request; dismissable rules in `.sharpit/sharpit.yml`), MCP Server and CLI.
57
+ - Read-only MCP endpoint (`POST /sharpit/api/mcp`, off by default; `SHARPIT_MCP_ENABLED=ON`) with the tools
58
+ `get_overview`, `get_config`, `get_mappings`, `get_loggers`, `get_beans` and `get_vulnerabilities_report`; the CLI
59
+ HTTP endpoint (`/sharpit/api/cli`) offers the same catalogue plus the vulnerability scan.
60
+ - Configuration through `SHARPIT_*` environment variables and `install()` keywords; the environment wins. Invalid values
61
+ fall back to a fail-safe value and record a warning.
62
+ - Fail-closed activation: on for `SHARPIT_ENABLED=ON`, a dev profile, `uvicorn --reload` or `fastapi dev`; a `prod`
63
+ profile switches it off unless `SHARPIT_ENABLED=ON` forces it. When off, the mount stays in place (as in BootUI) and
64
+ every path under it answers a plain 404 from the host's 404 handler; a host with a catch-all or authenticate-first
65
+ route answers those paths differently, so the mount can be told apart. `path="/"` and a trailing slash are refused.
66
+ - Request guard: loopback-only by default, `Host` allow-list, full-origin (API paths) and `Sec-Fetch-Site` cross-site checks on
67
+ every method, bearer token with `HttpOnly` session cookie for untrusted sources.
68
+ - Secret masking of values, defaults and suggestions in API, MCP and CLI output, including pydantic `SecretStr` and any URL with userinfo.
69
+ - Extras `sharpit[fastapi]` and `sharpit[settings]`; typed package (`py.typed`); prebuilt UI in the wheel, so end users
70
+ never need Node.
71
+
72
+ ### Deviations from BootUI
73
+
74
+ Listed in section 14 of the design spec. The main ones:
75
+
76
+ - FastAPI only; Django and Flask are out of scope.
77
+ - A new Svelte UI instead of BootUI's Vue UI, over the same JSON contract.
78
+ - Activation uses profile variables and a dev-server signal read from the command line (no DevTools equivalent);
79
+ `uvicorn.run(..., reload=True)` from a script is not detected.
80
+ - The cross-site check applies to every method, compares the full origin on API paths, and any forwarded header makes a caller
81
+ untrusted unless a trusted proxy is configured.
82
+ - `defaultValue` is masked as well, because Python defaults come from code.
83
+ - Beans are dependency providers, middleware and lifespan rather than an IoC container.
84
+ - Deferred: config overrides, health, profile diff and the `sharpit` command-line client (the HTTP endpoint ships).
85
+
86
+ ### Known limitations
87
+
88
+ - State (token, MCP switch, logger levels, scan cache) is per process under `--workers` and `--reload`.
89
+ - Behind a TLS-terminating proxy, uvicorn needs `--proxy-headers` for the Origin check to pass.
90
+ - Masking is name- and shape-based: vendor-prefixed tokens under harmless names (`sk_live_...`, `ghp_...`) can show.
91
+
92
+ [Unreleased]: https://github.com/ffroliva/sharpit/compare/v0.2.0...HEAD
93
+ [0.2.0]: https://github.com/ffroliva/sharpit/releases/tag/v0.2.0
94
+ [0.1.0]: https://github.com/ffroliva/sharpit/releases/tag/v0.1.0
sharpit-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,149 @@
1
+ Metadata-Version: 2.5
2
+ Name: sharpit
3
+ Version: 0.2.0
4
+ Summary: Embedded, local-only developer console for Python apps (a port of BootUI).
5
+ Project-URL: Homepage, https://github.com/ffroliva/sharpit
6
+ Project-URL: Source, https://github.com/ffroliva/sharpit
7
+ Project-URL: Issues, https://github.com/ffroliva/sharpit/issues
8
+ Project-URL: Changelog, https://github.com/ffroliva/sharpit/blob/main/CHANGELOG.md
9
+ Author: Flavio Oliva
10
+ License-Expression: Apache-2.0
11
+ License-File: LICENSE
12
+ License-File: NOTICE
13
+ Keywords: bootui,debugging,developer-tools,devtools,fastapi,introspection,mcp,starlette
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Environment :: Web Environment
16
+ Classifier: Framework :: FastAPI
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: License :: OSI Approved :: Apache Software License
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3 :: Only
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: Python :: 3.14
25
+ Classifier: Topic :: Software Development :: Debuggers
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: >=3.12
28
+ Requires-Dist: packaging>=23
29
+ Requires-Dist: starlette>=0.44
30
+ Provides-Extra: fastapi
31
+ Requires-Dist: fastapi>=0.115; extra == 'fastapi'
32
+ Provides-Extra: settings
33
+ Requires-Dist: pydantic-settings>=2.4; extra == 'settings'
34
+ Provides-Extra: test
35
+ Requires-Dist: aiosqlite>=0.20; extra == 'test'
36
+ Requires-Dist: alembic>=1.13; extra == 'test'
37
+ Requires-Dist: fastapi>=0.115; extra == 'test'
38
+ Requires-Dist: httpx>=0.27; extra == 'test'
39
+ Requires-Dist: pydantic-settings>=2.4; extra == 'test'
40
+ Requires-Dist: pytest-cov>=5; extra == 'test'
41
+ Requires-Dist: pytest-timeout>=2.3; extra == 'test'
42
+ Requires-Dist: pytest-xdist>=3.6; extra == 'test'
43
+ Requires-Dist: pytest>=8; extra == 'test'
44
+ Requires-Dist: python-multipart>=0.0.9; extra == 'test'
45
+ Requires-Dist: sqlalchemy[asyncio]>=2.0.38; extra == 'test'
46
+ Requires-Dist: uvicorn>=0.30; extra == 'test'
47
+ Description-Content-Type: text/markdown
48
+
49
+ # sharpit
50
+
51
+ [![CI](https://github.com/ffroliva/sharpit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ffroliva/sharpit/actions/workflows/ci.yml)
52
+ [![Release](https://github.com/ffroliva/sharpit/actions/workflows/release.yml/badge.svg)](https://github.com/ffroliva/sharpit/actions/workflows/release.yml)
53
+ [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=alert_status&branch=main)](https://sonarcloud.io/summary/overall?id=ffroliva_sharpit&branch=main)
54
+ [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=coverage&branch=main)](https://sonarcloud.io/component_measures?id=ffroliva_sharpit&metric=coverage&branch=main)
55
+
56
+ [![Reliability](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=reliability_rating&branch=main)](https://sonarcloud.io/summary/overall?id=ffroliva_sharpit&branch=main)
57
+ [![Security](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=security_rating&branch=main)](https://sonarcloud.io/summary/overall?id=ffroliva_sharpit&branch=main)
58
+ [![Maintainability](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=sqale_rating&branch=main)](https://sonarcloud.io/summary/overall?id=ffroliva_sharpit&branch=main)
59
+ [![Duplication](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=duplicated_lines_density&branch=main)](https://sonarcloud.io/component_measures?id=ffroliva_sharpit&metric=duplicated_lines_density&branch=main)
60
+
61
+ [![Python 3.12 | 3.13 | 3.14](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://github.com/ffroliva/sharpit/blob/main/pyproject.toml)
62
+ [![Licence: Apache-2.0](https://img.shields.io/github/license/ffroliva/sharpit)](https://github.com/ffroliva/sharpit/blob/main/LICENSE)
63
+ [![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](https://github.com/ffroliva/sharpit/blob/main/CHANGELOG.md)
64
+ [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
65
+ [![Type checked: pyright](https://img.shields.io/badge/type%20checked-pyright-blue.svg)](https://github.com/microsoft/pyright)
66
+
67
+ <!-- CI and SonarCloud badges are live and pinned to main. Add the PyPI version badge with the first PyPI release. -->
68
+
69
+ An embedded, local-only developer console for FastAPI apps. One call mounts a web console at `/sharpit` and a
70
+ JSON API at `/sharpit/api` inside your own app, so a running service becomes understandable in minutes: its
71
+ configuration and where each value came from, every route, the dependency providers, loggers you can retune live,
72
+ and a vulnerability scan of the installed packages.
73
+
74
+ sharpit is a Python/FastAPI port of [BootUI](https://github.com/jdubois/boot-ui) by Julien Dubois (Apache-2.0), the
75
+ Spring Boot developer console. It ports BootUI's design goals, JSON contract and test cases; the UI is new.
76
+
77
+ ![sharpit overview](https://raw.githubusercontent.com/ffroliva/sharpit/main/ui/tests/e2e/screenshots/overview-light.png)
78
+
79
+ > **Status: alpha (0.2.0, FastAPI only).** Django and Flask are not supported. See [CHANGELOG.md](https://github.com/ffroliva/sharpit/blob/main/CHANGELOG.md).
80
+
81
+ ## Install
82
+
83
+ sharpit is not on PyPI yet. Install it from git:
84
+
85
+ ```bash
86
+ pip install "sharpit @ git+https://github.com/ffroliva/sharpit.git"
87
+ # or
88
+ uv add "sharpit @ git+https://github.com/ffroliva/sharpit.git"
89
+ ```
90
+
91
+ Python 3.12+. Runtime dependencies are only `starlette>=0.44` and `packaging>=23`. Optional extras:
92
+
93
+ | Extra | Adds | Why |
94
+ |---|---|---|
95
+ | `sharpit[fastapi]` | `fastapi>=0.115` | the supported host |
96
+ | `sharpit[settings]` | `pydantic-settings>=2.4` | the Config panel shows which source each value came from |
97
+
98
+ ## Quickstart
99
+
100
+ ```python
101
+ from fastapi import FastAPI
102
+ import sharpit
103
+
104
+ app = FastAPI()
105
+
106
+ # Register your application's middleware first:
107
+ # app.add_middleware(...)
108
+
109
+ # Install sharpit after your app's middleware:
110
+ sharpit.install(app) # mounts /sharpit and /sharpit/api
111
+ ```
112
+
113
+ Call `sharpit.install(app)` after adding your own middleware. Starlette builds middleware from the outside in, so
114
+ calling `install()` last ensures sharpit's capture middleware sits outside your application middleware. This lets sharpit
115
+ measure total request durations and record unhandled errors correctly.
116
+
117
+ Run it **with a dev signal** and open <http://127.0.0.1:8000/sharpit/>:
118
+
119
+ ```bash
120
+ fastapi dev app.py # or: uvicorn app:app --reload
121
+ ```
122
+
123
+ Keyword arguments for `sharpit.install()`:
124
+
125
+ - `engines`: optional sequence of SQLAlchemy `Engine` or `AsyncEngine` instances to monitor in connection pools and
126
+ health checks (e.g. `engines=[engine]`). If omitted, engines are discovered automatically on first connection.
127
+ - `health_checks`: optional mapping of check names to zero-argument callables (e.g. `health_checks={"cache": ping_cache}`).
128
+ - `alembic_config`: optional path to `alembic.ini` (default `"alembic.ini"`).
129
+ - `settings`: optional pydantic-settings instance or sequence of instances to show configuration provenance.
130
+
131
+ Other options are keyword arguments or environment variables, see [Settings](https://ffroliva.github.io/sharpit/settings/).
132
+
133
+ If `/sharpit` answers 404, read [Activation](https://ffroliva.github.io/sharpit/activation/): sharpit stays off unless a dev signal turns it on.
134
+
135
+ ## Documentation
136
+
137
+ The full documentation is at **<https://ffroliva.github.io/sharpit/>**:
138
+
139
+ - [Activation](https://ffroliva.github.io/sharpit/activation/): when sharpit turns on, and why a plain `uvicorn app:app` gives 404
140
+ - [Panels](https://ffroliva.github.io/sharpit/panels/): what each panel shows
141
+ - [MCP for AI agents](https://ffroliva.github.io/sharpit/mcp/): the read-only MCP endpoint and its 18 tools
142
+ - [Settings](https://ffroliva.github.io/sharpit/settings/): every environment variable and `install()` keyword
143
+ - [Safety model](https://ffroliva.github.io/sharpit/safety/): local-only guard, tokens, masking, proxies and workers
144
+ - [How it works](https://ffroliva.github.io/sharpit/how-it-works/) and [Deviations from BootUI](https://ffroliva.github.io/sharpit/deviations/)
145
+
146
+ ## License
147
+
148
+ Apache License 2.0. See [LICENSE](https://github.com/ffroliva/sharpit/blob/main/LICENSE) and [NOTICE](https://github.com/ffroliva/sharpit/blob/main/NOTICE). sharpit is derived from
149
+ [BootUI](https://github.com/jdubois/boot-ui), Copyright Julien Dubois.
@@ -0,0 +1,101 @@
1
+ # sharpit
2
+
3
+ [![CI](https://github.com/ffroliva/sharpit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ffroliva/sharpit/actions/workflows/ci.yml)
4
+ [![Release](https://github.com/ffroliva/sharpit/actions/workflows/release.yml/badge.svg)](https://github.com/ffroliva/sharpit/actions/workflows/release.yml)
5
+ [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=alert_status&branch=main)](https://sonarcloud.io/summary/overall?id=ffroliva_sharpit&branch=main)
6
+ [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=coverage&branch=main)](https://sonarcloud.io/component_measures?id=ffroliva_sharpit&metric=coverage&branch=main)
7
+
8
+ [![Reliability](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=reliability_rating&branch=main)](https://sonarcloud.io/summary/overall?id=ffroliva_sharpit&branch=main)
9
+ [![Security](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=security_rating&branch=main)](https://sonarcloud.io/summary/overall?id=ffroliva_sharpit&branch=main)
10
+ [![Maintainability](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=sqale_rating&branch=main)](https://sonarcloud.io/summary/overall?id=ffroliva_sharpit&branch=main)
11
+ [![Duplication](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_sharpit&metric=duplicated_lines_density&branch=main)](https://sonarcloud.io/component_measures?id=ffroliva_sharpit&metric=duplicated_lines_density&branch=main)
12
+
13
+ [![Python 3.12 | 3.13 | 3.14](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://github.com/ffroliva/sharpit/blob/main/pyproject.toml)
14
+ [![Licence: Apache-2.0](https://img.shields.io/github/license/ffroliva/sharpit)](https://github.com/ffroliva/sharpit/blob/main/LICENSE)
15
+ [![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](https://github.com/ffroliva/sharpit/blob/main/CHANGELOG.md)
16
+ [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
17
+ [![Type checked: pyright](https://img.shields.io/badge/type%20checked-pyright-blue.svg)](https://github.com/microsoft/pyright)
18
+
19
+ <!-- CI and SonarCloud badges are live and pinned to main. Add the PyPI version badge with the first PyPI release. -->
20
+
21
+ An embedded, local-only developer console for FastAPI apps. One call mounts a web console at `/sharpit` and a
22
+ JSON API at `/sharpit/api` inside your own app, so a running service becomes understandable in minutes: its
23
+ configuration and where each value came from, every route, the dependency providers, loggers you can retune live,
24
+ and a vulnerability scan of the installed packages.
25
+
26
+ sharpit is a Python/FastAPI port of [BootUI](https://github.com/jdubois/boot-ui) by Julien Dubois (Apache-2.0), the
27
+ Spring Boot developer console. It ports BootUI's design goals, JSON contract and test cases; the UI is new.
28
+
29
+ ![sharpit overview](https://raw.githubusercontent.com/ffroliva/sharpit/main/ui/tests/e2e/screenshots/overview-light.png)
30
+
31
+ > **Status: alpha (0.2.0, FastAPI only).** Django and Flask are not supported. See [CHANGELOG.md](https://github.com/ffroliva/sharpit/blob/main/CHANGELOG.md).
32
+
33
+ ## Install
34
+
35
+ sharpit is not on PyPI yet. Install it from git:
36
+
37
+ ```bash
38
+ pip install "sharpit @ git+https://github.com/ffroliva/sharpit.git"
39
+ # or
40
+ uv add "sharpit @ git+https://github.com/ffroliva/sharpit.git"
41
+ ```
42
+
43
+ Python 3.12+. Runtime dependencies are only `starlette>=0.44` and `packaging>=23`. Optional extras:
44
+
45
+ | Extra | Adds | Why |
46
+ |---|---|---|
47
+ | `sharpit[fastapi]` | `fastapi>=0.115` | the supported host |
48
+ | `sharpit[settings]` | `pydantic-settings>=2.4` | the Config panel shows which source each value came from |
49
+
50
+ ## Quickstart
51
+
52
+ ```python
53
+ from fastapi import FastAPI
54
+ import sharpit
55
+
56
+ app = FastAPI()
57
+
58
+ # Register your application's middleware first:
59
+ # app.add_middleware(...)
60
+
61
+ # Install sharpit after your app's middleware:
62
+ sharpit.install(app) # mounts /sharpit and /sharpit/api
63
+ ```
64
+
65
+ Call `sharpit.install(app)` after adding your own middleware. Starlette builds middleware from the outside in, so
66
+ calling `install()` last ensures sharpit's capture middleware sits outside your application middleware. This lets sharpit
67
+ measure total request durations and record unhandled errors correctly.
68
+
69
+ Run it **with a dev signal** and open <http://127.0.0.1:8000/sharpit/>:
70
+
71
+ ```bash
72
+ fastapi dev app.py # or: uvicorn app:app --reload
73
+ ```
74
+
75
+ Keyword arguments for `sharpit.install()`:
76
+
77
+ - `engines`: optional sequence of SQLAlchemy `Engine` or `AsyncEngine` instances to monitor in connection pools and
78
+ health checks (e.g. `engines=[engine]`). If omitted, engines are discovered automatically on first connection.
79
+ - `health_checks`: optional mapping of check names to zero-argument callables (e.g. `health_checks={"cache": ping_cache}`).
80
+ - `alembic_config`: optional path to `alembic.ini` (default `"alembic.ini"`).
81
+ - `settings`: optional pydantic-settings instance or sequence of instances to show configuration provenance.
82
+
83
+ Other options are keyword arguments or environment variables, see [Settings](https://ffroliva.github.io/sharpit/settings/).
84
+
85
+ If `/sharpit` answers 404, read [Activation](https://ffroliva.github.io/sharpit/activation/): sharpit stays off unless a dev signal turns it on.
86
+
87
+ ## Documentation
88
+
89
+ The full documentation is at **<https://ffroliva.github.io/sharpit/>**:
90
+
91
+ - [Activation](https://ffroliva.github.io/sharpit/activation/): when sharpit turns on, and why a plain `uvicorn app:app` gives 404
92
+ - [Panels](https://ffroliva.github.io/sharpit/panels/): what each panel shows
93
+ - [MCP for AI agents](https://ffroliva.github.io/sharpit/mcp/): the read-only MCP endpoint and its 18 tools
94
+ - [Settings](https://ffroliva.github.io/sharpit/settings/): every environment variable and `install()` keyword
95
+ - [Safety model](https://ffroliva.github.io/sharpit/safety/): local-only guard, tokens, masking, proxies and workers
96
+ - [How it works](https://ffroliva.github.io/sharpit/how-it-works/) and [Deviations from BootUI](https://ffroliva.github.io/sharpit/deviations/)
97
+
98
+ ## License
99
+
100
+ Apache License 2.0. See [LICENSE](https://github.com/ffroliva/sharpit/blob/main/LICENSE) and [NOTICE](https://github.com/ffroliva/sharpit/blob/main/NOTICE). sharpit is derived from
101
+ [BootUI](https://github.com/jdubois/boot-ui), Copyright Julien Dubois.
@@ -2,6 +2,7 @@
2
2
 
3
3
  | Path | What it is |
4
4
  |---|---|
5
+ | [../website/docs/how-it-works.md](../website/docs/how-it-works.md) | How sharpit works; published with the rest of the user docs at https://ffroliva.github.io/sharpit/ |
5
6
  | [development/workflow.md](development/workflow.md) | How a change goes from idea to release with the `/sharpit:*` skills |
6
7
  | [reference/BOOTUI-CONTRACT-MVP.md](reference/BOOTUI-CONTRACT-MVP.md) | The BootUI HTTP contract the MVP must match: DTOs, error strings, activation reasons |
7
8
  | [reference/BOOTUI-PYTHON-MAPPING.md](reference/BOOTUI-PYTHON-MAPPING.md) | How BootUI's Spring concepts map to Python/FastAPI |
@@ -0,0 +1,57 @@
1
+ # Overhead budgets
2
+
3
+ How sharpit measures its performance impact, how to read a budget failure, and how to tell a busy machine from a slower sharpit.
4
+
5
+ ## What the budget tests guard
6
+
7
+ sharpit runs inside someone else's app, so what counts is the time it adds. Two budget tests guard the hot paths:
8
+
9
+ - `tests/fastapi/test_capture_overhead.py`: capture middleware, 0.2 ms per request.
10
+ - `tests/fastapi/test_sql_trace_overhead.py`: SQL listener, 50 µs per statement.
11
+
12
+ CI's coverage job deselects them because coverage tracing distorts timing. Every other test job runs them.
13
+
14
+ ## How they measure
15
+
16
+ Each test runs the same workload with the hook on and off, in one process. Rounds alternate on/off and the side that goes first swaps every round (`tests/overhead.py`). The fastest round of each side is kept, because contention only adds time.
17
+
18
+ Both rules exist to prevent machine noise from distorting the measurement:
19
+
20
+ - **Alternating on and off.** A runner can slow down for seconds at a time. Timing all off rounds before all on rounds puts that slowdown on on, reporting 60 for a true cost of 10 in `tests/test_overhead_harness.py`.
21
+ - **Swapping which side goes first.** The first round after a switch pays for a cold cache. Always running off first charges that penalty to off and hides overhead, reporting -40 for a true cost of 10 in `tests/test_overhead_harness.py`.
22
+
23
+ ## Reading a failure
24
+
25
+ The failure message prints overhead, noise, and min/median/max per side.
26
+
27
+ Noise is how far a typical round sits above the fastest, measured as the median minus the min on the noisier side. If the overshoot (overhead minus budget) is within the noise, the message says so: suspect the machine.
28
+
29
+ ## Is it a false positive? A checklist
30
+
31
+ Follow these steps when a budget test fails:
32
+
33
+ 1. **Read the noise in the message.** Check if the overshoot sits within the reported noise.
34
+ 2. **Run the check script locally.** Run `uv run python -m scripts.dev.overhead_check <test> --runs 10` locally; then with `--load` to see how it behaves on a busy machine.
35
+ 3. **Compare against main.** Run the same on a clean worktree of `origin/main`. If main fails the same way, it is not your change.
36
+ 4. **Evaluate the result.** Only a failure larger than its noise, that also does not happen on main, is a regression.
37
+
38
+ ## Watching the trend
39
+
40
+ Every CI run appends a row per budget test to the job summary (overhead, budget, noise). Compare runs there before deciding a number moved.
41
+
42
+ ## What never to do
43
+
44
+ - Raise a budget to pass.
45
+ - Mark a budget test slow, skip or deselect it.
46
+ - Retry until green.
47
+ - Change the harness without a separate PR and a test seen red first.
48
+
49
+ Moving a budget is a product decision for the owner, with the measurements in the PR.
50
+
51
+ ## Known numbers (2026-10-31)
52
+
53
+ Capture overhead measured 0.12 to 0.18 ms per request.
54
+
55
+ Under bursty load (every core busy 0.7 s, idle 0.7 s) the old sequential harness failed 3 of 12 runs (0.530, 0.244 and 0.259 ms against a 0.2 ms budget). On a quiet machine it passed 10 of 10 runs.
56
+
57
+ After the alternating harness, on the same machine and load: 0 of 12 runs failed under load (overhead 0.119 to 0.191 ms, median noise 0.044 ms) and 0 of 10 quiet (0.117 to 0.160 ms, median noise 0.024 ms). The worst loaded run is still close to the budget, so a rare failure on a very busy runner remains possible; the noise in the message tells it apart.
@@ -1,7 +1,7 @@
1
1
  # Development workflow
2
2
 
3
3
  How a change to sharpit goes from idea to release. Rules (worktrees, TDD, commits, no AI attribution, never push
4
- `master` or publish) are in [AGENTS.md](../../AGENTS.md); this page is the order of the steps and when to use each.
4
+ `main` or publish) are in [AGENTS.md](../../AGENTS.md); this page is the order of the steps and when to use each.
5
5
  Every `/sharpit:<name>` step is `skills/<name>/SKILL.md`, readable by any agent.
6
6
 
7
7
  ```
@@ -31,7 +31,7 @@ A task-by-task TDD plan at `docs/superpowers/plans/<date>-<slug>.md`, contract f
31
31
 
32
32
  ## 4. Execute: subagent-driven
33
33
 
34
- In a worktree from `origin/master`, one task at a time with `superpowers:subagent-driven-development`: a fresh subagent
34
+ In a worktree from `origin/main`, one task at a time with `superpowers:subagent-driven-development`: a fresh subagent
35
35
  per task, red test first, review between tasks. Before touching activation, the guard, masking, introspection or
36
36
  OSV, read **`/sharpit:known-issues`**. Delegated agents get the background-command rule in their brief.
37
37
 
@@ -50,7 +50,7 @@ marks slow or weakens a test.
50
50
  | Step | When |
51
51
  |---|---|
52
52
  | `/sharpit:doc-review` | The branch changes anything a doc describes |
53
- | `/sharpit:branch-review` | Before opening the PR: the council on the local branch (base `origin/master`) |
53
+ | `/sharpit:branch-review` | Before opening the PR: the council on the local branch (base `origin/main`) |
54
54
  | `/sharpit:pr-council-review <N>` | On the open PR; posts only when asked |
55
55
  | `/sharpit:llm-council` | Activation, guard, masking, settings parsing or a release: adds Codex and Antigravity |
56
56
 
@@ -59,7 +59,7 @@ The owner merges. Agents never merge.
59
59
  ## 7. Release: `/sharpit:release`
60
60
 
61
61
  Only when the owner asks. A version bump in `src/sharpit/__init__.py` and the changelog go through a
62
- `chore/release-<version>` PR; after the merge, a signed tag `v<version>` on `master` is the release. Pushing that tag
62
+ `chore/release-<version>` PR; after the merge, a signed tag `v<version>` on `main` is the release. Pushing that tag
63
63
  runs `.github/workflows/release.yml`, which publishes to PyPI with Trusted Publishing and creates the GitHub Release.
64
64
  Nobody uploads by hand, and the tag is only pushed after the owner says go.
65
65
 
@@ -104,3 +104,22 @@ Portability: **P** = ports directly · **A** = needs an adapter per framework ·
104
104
  Spring's "everything registered in one place" model than FastAPI is.
105
105
  5. gflow-cli has no long-running server. It would need a "run and report" mode (wrap a run, collect the same
106
106
  data, write a report) rather than an embedded console.
107
+
108
+ ## 0.2.0 Parity notes
109
+
110
+ Each row documents a panel added in 0.2.0 and its deliberate deviations from BootUI (spec §17).
111
+
112
+ | Panel | BootUI counterpart | Python source / implementation | Spec §17 deviations |
113
+ |---|---|---|---|
114
+ | `http-exchanges` | Actuator `HttpExchangeRepository` | `CaptureMiddleware` ASGI ring buffer | Custom ASGI middleware instead of Actuator. Status 499 when client disconnects before response. `sessionId` is always null (Starlette uses signed cookies). |
115
+ | `exceptions` | `HandlerExceptionResolver` / `ExceptionStore` | ASGI middleware + wrapped exception handlers + `SharpitLogHandler` `exc_info` | Captured across three Python paths and deduped. Grouping fingerprint uses exception class and innermost application frame instead of class and top 5 frames. `errorContract` cross-link is always null. |
116
+ | `sql-trace` | JDBC proxy `DataSource` | SQLAlchemy class-level event listeners | SQLAlchemy class-level cursor listeners instead of JDBC proxy. SQL literals are normalized and masked when parameter capture is disabled. `/sql-trace/insights` route not built. SSE stream closes every 3 s. |
117
+ | `activity` | `LiveActivityController` | `ContextVar` request correlation and event ring buffer | Parameters `until`, `cursor`, and `pageSize` not accepted (no persistence). Event types limited to REQUEST, SQL, and EXCEPTION. KPIs heap/cache/REST client are null. SSE stream closes every 3 s. |
118
+ | `log-tail` | Logback appender / `LogTailBuffer` | `SharpitLogHandler` stdlib logging ring buffer | Uses stdlib `logging.Handler` on root and non-propagating loggers. Memory capped at 1 MiB by default (`max-bytes` must be > 0). Stream limit returns HTTP 503 across all streams. SSE `id` formatted as `<bootNonce>-<seq>`. SSE stream closes every 3 s. |
119
+ | `alembic` | Flyway / Liquibase panels | Alembic environment and script directory | Alembic panel outputs Flyway-shaped JSON with `alembicPresent`, `configPath`, `heads`, `checkedAt`, and `unavailableReason`. Read-only (`migrateEnabled` and `cleanEnabled` false). DB state refreshed on POST `alembic/refresh` only (no socket on GET). MCP tool `get_alembic_migrations`. |
120
+ | `database-connection-pools` | HikariCP pool metrics | SQLAlchemy engine pool inspection | Inspects SQLAlchemy engine pools instead of HikariCP. Unknown fields and `pending` are null. Query strings stripped from database connection URLs (emitted in `jdbcUrl` for BootUI parity) to prevent secret leakage. |
121
+ | `health` | Spring Boot Health contributors | Dialect ping on engines + user callables | Health checks run on POST `health/check`, cached on GET (no socket or user code on GET). Panel marked action-capable. Database health check runs dialect ping (`validationQuery` `"dialect ping"`). |
122
+ | `threads` | JVM ThreadDump | `threading.enumerate()` + `asyncio.all_tasks()` | Adds `tasks`, `taskCount`, and `warnings` for running asyncio tasks with request correlation. Thread states inferred as RUNNABLE or WAITING without JVM CPU or lock metrics. `POST /threads/download` dropped. |
123
+ | `rest-api` | Spring REST controller rules | Static analysis over FastAPI route objects | Rules inspect FastAPI route definitions rather than Spring annotations. Spring-only and retired rules skipped. `/rest-api/error-contract` not built. Dismissal IDs use `[A-Za-z0-9._:-]{1,200}` with per-panel dismissal gates. |
124
+ | `http-probe` | Loopback socket HTTP client | In-process ASGI call with caller client | In-process ASGI call without loopback socket. Refuses tagged probe scopes and paths under the sharpit mount. Response body and location header masked through `mask_text`. Bounded to 4 concurrent probes. |
125
+
@@ -0,0 +1,7 @@
1
+ """examples.fastapi_sqla: FastAPI + SQLAlchemy dogfood sample app."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from examples.fastapi_sqla.app import create_app
6
+
7
+ __all__ = ["create_app"]
@@ -0,0 +1,27 @@
1
+ [alembic]
2
+ script_location = %(here)s/migrations
3
+ sqlalchemy.url = sqlite:///%(here)s/sample.db
4
+
5
+ [loggers]
6
+ keys = root
7
+
8
+ [handlers]
9
+ keys = console
10
+
11
+ [formatters]
12
+ keys = generic
13
+
14
+ [logger_root]
15
+ level = WARN
16
+ handlers = console
17
+ qualname =
18
+
19
+ [handler_console]
20
+ class = StreamHandler
21
+ args = (sys.stderr,)
22
+ level = NOTSET
23
+ formatter = generic
24
+
25
+ [formatter_generic]
26
+ format = %(levelname)-5.5s [%(name)s] %(message)s
27
+ datefmt = %H:%M:%S