What it does for you
Small public repositories fail on simple things: a missing license, a README that does not say what the tool does, a credential-shaped string left in a note. Public Surface Sweeper checks those quickly and the same way every time, scores the repository, lists what to fix, and can scan every GitHub-facing repository in a workspace at once.
- Required filesA license, a README, a changelog and the other files a visitor expects.
- Secret shapesValues shaped like cloud keys and tokens are reported with the file and line.
- A score and a statusErrors block, warnings are counted, and the run exits 1 on errors by default.
- A workspace matrix
--workspacesweeps every repository with a GitHub remote, with no network calls and no writes.
Source: README.md at 51eccfb (version 0.1.3)
Watch
No concept film fits this tool closely yet. The walkthrough below covers it in text, with real commands and output.
Video walkthrough: coming with the next release.
How it works, one step at a time
Scroll, or use the step buttons. The panel uses the bundled examples/clean-repo and a copy of it with two problems added. Every line is output from public-surface-sweeper at commit 51eccfb.
- 01
A clean repository
The bundled fixture has the files a public repository should carry: a license, a README, a usage guide, a changelog, contributing notes, an authors file, agent instructions and a CI folder. The sweep finds nothing, scores 100 and reports ready.
Source: examples/clean-repo; README.md, "Try it"
- 02
Break it twice
Copy the fixture, delete its LICENSE, and add a note holding a value shaped like an AWS access key: AKIA followed by sixteen capitals. Sweep again. Both are errors, each with where it is.
Source: src/public_surface_sweeper/sweeper.py, src/public_surface_sweeper/text_hygiene.py
- 03
A score and a list of fixes
--summaryturns the findings into a score, a status and one action item per finding. Two errors take the score to 50 and the status to blocked. - 04
Evidence for the next tool
--proof-packetwrites a proof-surface packet. Its claims carry the counts behind each check: one required-file finding, one secret-shaped finding, no em-dash findings, no delivery findings. The check reads fail at score 50. - 05
Choose what fails the run
By default the run exits 1 on errors.
--fail-on warningfails on warnings too, and--fail-on noneprints findings and always exits 0. In workspace mode, a discovery that finds no repositories also fails, so an empty matrix never passes as a clean one.Source: README.md, "Usage"
Walkthrough
Install it, run it once, then use the main feature. Each command below is real, and so is its output.
Install
Install from a checkout. Python 3.10 or newer.
$ git clone https://github.com/HarperZ9/public-surface-sweeper && cd public-surface-sweeper $ python -m pip install -e ".[test]"First run: a clean repository
Sweep the bundled clean example.
$ public-surface-sweeper examples/clean-repo --summary score: 100 status: ready total_findings: 0 errors: 0 warnings: 0 action_items: - noneA repository with a problem
Sweep a repository that carries a finding. The sweep blocks it.
$ public-surface-sweeper ./repo ERROR LICENSE required-file: missing required file: LICENSE ERROR notes.txt:1 aws-access-key: AWS access key shaped valueA proof packet
Write the result as a packet another tool can check.
$ public-surface-sweeper ./repo --proof-packet "surface": "repo public release surface" "status": "blocked" Required public release files are visible. required-file findings=1 Secret-shaped values are surfaced before publication. secret-shaped findings=1 Public text hygiene is checkable. em-dash findings=0 Public and developer delivery are inspectable. delivery findings=0 check: public-surface-sweeper fail score=50, findings=2
Output from public-surface-sweeper at 51eccfb on Windows with Python 3.12. The broken copy deletes LICENSE and adds one note.
What it does not do
- It is a release-hygiene gate. It is not a full security scanner or a certification.
- Secret detection is by shape. A credential that does not look like one is not found.
- Workspace mode reads local Git metadata only and makes no network call.
Source: README.md at 51eccfb, "Current status" and "Usage"
Check what stuck
Answer each one in your head before you open it.
What two findings did the broken copy get?
A missing LICENSE and an AWS-access-key-shaped value in notes.txt, line 1.
What score and status follow from two errors?
50 and blocked.
Why does an empty workspace discovery fail?
So a matrix of zero repositories never passes as a clean portfolio.