docs: bring the README, quick start and security policy up to v0.3.0 - #148
Merged
Conversation
The README and the quick start still said v0.1.1 was the release and that Homebrew installed 0.1.0. Both have been wrong since v0.2.0, and the tap now pins v0.3.0: origin/main of ArangoGutierrez/homebrew-coffee-bar is a0f403a, whose formula fetches tags/v0.3.0.tar.gz. The status claim stays in the two places the README's own comment reserves for it, and gains the one caveat a reader needs at the point of choosing an install: a source build is ad-hoc signed, so it cannot register the privileged helper and reaches lid-closed mode by the command route. That is not a second status claim, it is the consequence of the install the sentence just named. SECURITY.md's supported-versions table said v0.1.x and that the tap installed from v0.1.0. A security policy that names the wrong supported line tells a reporter to test a version nobody is fixing. Nothing here touches the egress history at SECURITY.md:195-208 or the v0.1/v0.2 promise records below it, which are deliberate and correct. Signed-off-by: Carlos Eduardo Arango Gutierrez <eduardoa@nvidia.com>
The feature list stopped at v0.1. v0.3.0 also asks its three questions on first
run, opens at login on request, reports a newer version, and answers /status on
the ingest socket, and the front page said none of it.
The outbound request is the omission that mattered. The site discloses it
prominently and the README was silent, so the two documents disagreed about
whether the app talks to anything. One paragraph now states it in the terms
SECURITY.md already uses: once a day at most, at start and on Check now, no
identifier, no query string, no setting to turn it off. Sources: UpdateCheck
interval 24 * 60 * 60, main.swift checkForUpdatesIfDue at launch, PanelView and
PreferencesView checkForUpdates on the button, UpdateChecker.sessionConfiguration
for the cookie and cache seams, and no settings key that disables it.
Two corrections in the lid-closed section, neither of them to the root-scope
claim, which is true: every privileged probe verb (ProbeVerb.requiresRoot) serves
that one hold, and LoginItemInstaller documents itself as needing no root because
it writes the user's LaunchAgents rather than /Library/LaunchDaemons.
1. The section led with "no password, at any point", which holds for the button
on a signed build and not for `sudo coffee-bar-probe arm`. That command is
the only route a Homebrew install has, so the reader most likely to need a
password was the one being told there was never one. Both routes are now
named where the claim is made.
2. The first click on the button cannot succeed: PrivilegedHelperClient.outcome
returns approvalGuidance because macOS moves the job to requiresApproval in
the same breath as refusing it, and "Every new user's first click lands
here". A reader who was not told to press it again reads the refusal as a
failure.
The hold length is a v0.3.0 setting with a ceiling worth stating, so
JournalRecord.maxTTLSeconds joins productConstants in DocsClaims_test.swift.
Keyed by its qualified name, which is how SECURITY.md writes it, so the guard
now also reads the two live sentences pairing that symbol with 24 hours instead
of matching nothing.
Signed-off-by: Carlos Eduardo Arango Gutierrez <eduardoa@nvidia.com>
"Claude Code, which is the agent v0.1 supports" reads as stale on a v0.3.0 repo, and it was never the claim the paragraph needed: the two sentences after it already say that Codex and Cursor have adapters in the code and no documented wiring here. What the sentence is actually about is which agent THIS PAGE documents, so it says that instead. Kept out of the release-status commit deliberately. The README comment reserves status claims for two lines, and this is not one of them: it removes a version reference rather than adding one, and can be dropped on its own if the maintainer would rather keep the v0.1 phrasing. Signed-off-by: Carlos Eduardo Arango Gutierrez <eduardoa@nvidia.com>
PR #141 banned the absolute no-egress claims on the site and its own report flagged README, SECURITY and docs as unswept. That left the repository's front page free to claim exactly what the site was forbidden to claim, which is the wrong way round: a stranger following a link reads README.md before any page under site/. The sweep is now every documented surface minus a named exclusion map, rather than a list of pages. A list fails open the moment somebody adds a document and forgets a line, which is the hole discoveredSitePages() was already written to close for the site half. Two surfaces are excluded, and neither is a hole in the patterns: SECURITY.md quotes both retired false claims while recording when each became false. That paragraph is the policy keeping its promise to say so the day an outbound request existed, so the ban fires on the prose documenting the ban's own subject. Three patterns match there. docs/QUICKSTART.md:208 says an unrecognised --tool name "posts nothing rather than guessing", which is true of the shim: CoffeeBarShim/main.swift:98-102 refuses an unknown name with "Nothing was posted." The subject is a local unix-socket post and not the app's egress, and the ban reads phrasing rather than subjects. Narrowing "posts nothing" to admit that sentence would blind the ban to "It posts nothing anywhere.", which is in its own banned fixture list and is one of the phrasings the false site copy used. The gap is stated instead, in the map, where the next person to widen the sweep will read it. theEgressSweepReachesTheReadmeAndExcludesOnlyRealDocuments is the anti-vacuity half: an argument list that filtered down to nothing would switch the ban off and report success, and an exclusion naming a document that does not exist would read like a deliberate gap while excluding nothing. Mutation proof, planting "coffee-bar makes no network requests at all." in README.md: the guard fails with README.md carries the absolute claim "makes no network requests", quoting the surrounding sentence. Restored with git checkout and green. Signed-off-by: Carlos Eduardo Arango Gutierrez <eduardoa@nvidia.com>
The first full run of the suite went red on three checks, each of them right. noPublishedSurfacePromisesNoRootWhileTheProbeShipsARootVerb: both new install sentences said "it cannot register the privileged helper" with no qualifier naming who the claim is about, while five probe verbs need uid 0. Says "the app" now, which is both the qualifier the guard asks for and the accurate subject: it is the bundle that carries no team identifier, so it is the app that cannot register a helper. everyTeachingSurfaceNamesTheButtonBeforeTheSudoRoute: naming the two routes in the opening paragraph put "coffee-bar-probe arm" 206 bytes ahead of the first mention of the button, which reads as presenting the root command as the way to arm the mode. The sentence names the Arm lid-closed mode button first. Measured after the fix: button at 3855, command at 3913. noSourceCitesADocumentByLineNumberAndEveryAnchorResolves: the new productConstants comment cited SECURITY.md by line number, which rots on the next edit above it. It quotes anchor text instead, and the same treatment is applied to the two egress exclusion reasons, which were carrying line numbers into a failure message a reader would follow months from now. Signed-off-by: Carlos Eduardo Arango Gutierrez <eduardoa@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The repository's own front page still announced v0.1.1, three releases after it.
README.mdanddocs/QUICKSTART.mdboth said "Homebrew still builds from source and installs 0.1.0", which the tap bump to v0.3.0 made false, andSECURITY.md's supported-versions table still listed onlyv0.1.x.Nothing swept those files, which is exactly how a status line survived three releases. The egress ban added in #141 covered
site/only, and its own report flagged the Markdown as unswept.Approach
Status corrected on all three surfaces, in the single place the README's own comment reserves for it. The feature list now covers what v0.3.0 actually ships, including the first-run quick start, open-at-login, the update check and the
/statusendpoint, and one paragraph discloses the single outbound request in the termsSECURITY.mdalready uses.The privilege section previously led with "no password, at any point". That holds for the button on a signed build and not for
sudo coffee-bar-probe arm, which is the only route a Homebrew install has. Both routes are now named, and the first-run second click is stated:PrivilegedHelperClientreturnsapprovalGuidanceon the first attempt, so a reader who was not told to press again reads the refusal as a failure.The egress sweep now covers
README.md,CHANGELOG.mdanddocs/BUILDING.md.docs/QUICKSTART.mdandSECURITY.mdare excluded with reasons recorded in code and held against rot by an anti-vacuity test: QUICKSTART's "posts nothing" is true of the shim, and narrowing the pattern to admit it would blind the ban to "It posts nothing anywhere".Testing done
swift testrc=0, 1236 tests in 12 suites, one pre-existing known issue. Verified independently on a clean scratch path, not taken from the implementer's report.The app itself sends nothing.inREADME.mddrives rc=1 with a message naming the file and the exact phrase, and fails only that file. Restored withgit checkout --, tree clean.origin/mainafter a fetch. The local clone sat on a stale branch, and two earlier reads would each have justified a false sentence here.Breaking changes
None. Documentation and one widened guard.