Repository navigation
Docs: one command line reference for the Darling service (#6413) - #6699
Conversation
Adds docs/darling/cli.md with one row per verb, the exit codes in one format, and a section for each verb that needs more than a row. The Quick Start exit code paragraphs in Darling/README.md now link to it. Two tests that pinned the removed paragraphs' wording lose those assertions.
There was a problem hiding this comment.
Verdict: LGTM
Claims
- VERIFIED — "New
docs/darling/cli.md: one table row per verb ... a legend for the columns, one exit code section ... a short section for each verb that needs more than a row" — the file is added exactly this way (docs/darling/cli.md, new file in the diff). - VERIFIED — "
Darling/README.md: the four exit-code paragraphs ... are now one line each that link to the new page" — confirmed in the diff (three link lines replacing the--check-settings, collector-verb, "every other verb", and--diagnostics-bundleparagraphs). - VERIFIED — "
docs/darling/README.md: the index lists the page" — item 5 added in the diff. - VERIFIED — "Two tests pinned the wording ... assertions were deleted" —
DarlingCollectorToggleExitCodeTests.csandDropXeSessionsVerbTests.csdiffs drop exactly the assertions that quoted the now-removed README prose, and no stale copy of that prose remains anywhere in the tree (grepped for the removed strings). - VERIFIED — "The README says
--diagnostics-bundlemust run elevated. The code has no check." —DiagnosticsBundleAsync(DarlingCliCommands.cs:977) has noIsElevated()call; everyIsElevated()call site (lines 1494, 1523, 3389, 4211, 4891, 5467) is elsewhere. - VERIFIED — "The README said
--backfill-rollups'runs while the service is up'. The code does not require it" —BackfillRollupsAsync(DarlingCliCommands.cs:9059) opens its own store connection and has no service-running gate. - VERIFIED — line citations for
CollectorToggleExitCode(7865),DiagnosticsBundleExitCode(951),CheckSettingsExitCode(1168),DropXeSessionsExitCode(8649) — all exact. - UNVERIFIED — "Built
Darling.Tests(0 errors) and ran ... Total: 139, Failed: 0" — a live build/test run; not checkable from a read-only tree. - UNVERIFIED — "Link check: a script resolved every relative link ... (all resolve)" — a live script run against the rendered docs; not checkable from a read-only tree, though a manual spot-check of the
#exit-codesanchor and thedocs/darling/README.mdindex entry found them consistent.
Riskiest lines
docs/darling/cli.mdexit-code tables (the three-number and six-number tables under "Exit codes") — these replace prose that scripts and operators gate on; a wrong number here is a silent behavior-doc regression. Spot-checked againstCollectorToggleExitCode,DropXeSessionsExitCode,DiagnosticsBundleExitCode,CheckSettingsExitCodeandInvestigationExportCancelledExitCodeinDarlingCliCommands.cs— all matched. UNCOVERED by any test (deliberately, per the PR body's "Considered, not added" section, which cites #5833's ban on source-text/census tests); no behaviour test fails if a number here drifts from the code.Darling/README.md's three new link lines (exit codes now live only indocs/darling/cli.md#exit-codes) — if the anchor or file ever moves, the README silently points nowhere useful. UNCOVERED (the removed assertions were exactly the kind of source-text pin #5833 forbids re-adding); the PR body's "Link check" claim (unverified here) is the closest thing to coverage.Darling/Darling.Tests/DarlingCollectorToggleExitCodeTests.cs's surviving assertions (the "wrong password exits 2" and "does not tell its own mistake from a store that is down" checks) — still pin exact README wording for the three exit-code numbers themselves (not the removed paragraphs), so a future drift in those numbers is still caught byTheExitCodes_AreTheDocumentedNumbers. Covered by that existing test.
Traps near this diff
- Tests and censuses ruling (#5833): "never add one, and never answer a trap with a test that reads source text or asserts how code is spelled" — does not apply: this PR deletes stale source-text assertions in
DarlingCollectorToggleExitCodeTests.csandDropXeSessionsVerbTests.csrather than adding new ones, and adds no new test forcli.md's content (the PR body's "Considered, not added" section explicitly declines a table-vs-code test for this reason). - Lite/Darling parity (CONTRIBUTING's two-store rule) — does not apply:
docs/darling/cli.mddocuments Darling-only CLI verbs that have no Lite counterpart; this is additive documentation for an existing Darling-only surface, not a behavior change needing a Lite-side counterpart.
Divergence (blind read vs PR body)
None — the body's account matches the diff on every claim graded above, including the two "code and docs disagree" notes, which the body itself surfaces rather than glossing over.
Reviewer checklist
- Run the link-checker script (or click through manually) to confirm every relative link and the
#exit-codesanchor indocs/darling/cli.mdandDarling/README.mdresolve on the rendered GitHub page. - Run
Darling.Tests(DarlingCollectorToggleExitCodeTests,DropXeSessionsVerbTests, and the full suite) to confirm the claimed 139/0 result.
# Conflicts: # docs/darling/README.md
# Conflicts: # docs/darling/README.md
|
Follow-up pass, range This range is a single commit: The one place both sides touched the same lines is
No new public signature, SQL statement, or behavior was introduced by this range, so the CALLERS RULE and the traps file have nothing new to apply to beyond the doc-list merge above, which isn't a code or SQL shape any trap covers. |
There was a problem hiding this comment.
Verdict: LGTM
Claims
No new claims: the PR body is unchanged from the prior review pass (head b476eb32), and this range's only commit is a merge of origin/dev into the branch, not a new author commit with new claims about the code. The prior review already graded every body claim; those grades stand and are not re-litigated here.
Riskiest lines
docs/darling/README.md(the numbered index, item 5/6) — both sides of the merge added a5.entry (this PR'scli.md, dev'sadmin.md); the resolution renumbers this PR's entry to6and keeps both links, verified against the merged file and confirming bothadmin.mdandcli.mdexist on disk — UNCOVERED (a doc-index link isn't something a behaviour test asserts; not needed here since the file was read directly).
No other lines qualify: the merge introduced no other overlapping edits, no new public signature, SQL, or behavior change of its own — everything else in the range's diff isdev's own already-merged work (#6698, #6669, #6680, #6673, #6615, #6663), out of scope per the follow-up instructions.
Traps near this diff
- None apply: the only new content this range's own commit contributes is a markdown list-item renumbering during merge conflict resolution, which doesn't match the shape of any SQL, collector, analysis, alerting, storage/MCP, test-census, CI, or repository-mechanics trap in
.github/REVIEW-TRAPS.md.
Divergence (blind read vs PR body)
None — the PR body makes no claims about this range's commit (the merge), so there is nothing to diverge from.
Reviewer checklist
- Confirm the auto-merge (squash) picks up the resolved
docs/darling/README.mdlist correctly and renders with bothadmin.md(5) andcli.md(6) entries on GitHub.
Claude posting for Erik Darling.
Fixes #6413.
Why
The service exe has about 35 verbs. Each was explained only where its feature is explained, and the exit codes sat in long paragraphs in the Quick Start. There was no one list with the purpose, elevation, service state and exit codes of every verb.
What changes
docs/darling/cli.md: one table row per verb (verb, what it does, needs elevation, service running, exit codes, link), a legend for the columns, one exit code section in one format (a table per verb family), and a short section for each verb that needs more than a row (arguments, example command lines).Darling/README.md: the four exit-code paragraphs (--check-settings,--enable-collector/--disable-collector, the "every other verb" paragraph,--diagnostics-bundle) are now one line each that links to the new page. The links go to the page's#exit-codessection, because the paragraphs they replace were about exit codes and a table row has no anchor.docs/darling/README.md: the index lists the page.DarlingCollectorToggleExitCodeTests.TheExitCodes_AreTheDocumentedNumbers(kept the number pins and the other README assertions) andDropXeSessionsVerbTests(dropped the "every other verb that opens the store" assertion). The rule behind them was spelling, so those assertions were deleted, as the lane rules say. Nothing else changed in the tests.Where each fact comes from (all in
Darling/PerformanceMonitor.Darling.Service/)DarlingCliCommands.csIsKnownVerb(line 379) and theIs...Verbmethods (lines 69-370).--helptext:UsageText()(line 465).-?and/?are help (line 372).-vis version (line 364). Unknown option exits 1:Program.csline 40.OperatingSystem.IsWindows()guards inProgram.cs(--encrypt-passwordline 54,--print-viewer-connection121,--configure-network193,--configure-firewall211,--harden-files229,--export-viewer-config166, enable/disable mcp/web 257-300, print tokens 136-155).--add-server,--drop-xe-sessions, the three rollup verbs and the collector verbs have no guard (Program.cscomments at lines 306, 424, 440).PrintEndpointToken(line 1553, both token verbs),ConfigureFirewallAsync(line 5467),HardenTlsKeyFilesOnly(line 4899), andIsElevated()for the firewall step of the enable/disable verbs (line 4211) and the service control in--configure-network(line 3389).--harden-filesand--diagnostics-bundlesay "run elevated" inUsageText(). No other verb checks.DiagnosticsBundleExitCode(line 951),CheckSettingsExitCode(1168),CollectorToggleExitCode(7865, also used by the alert-source verbs at 7184-7472,--reset-password-keyat 300-340, andDarlingCliCommands.ExportInvestigations.cslines 225-302 with the cancel code 130 at line 216),DropXeSessionsExitCode(8649),HardenTlsKeyFilesOnly(lines 4900-4945, 2 only when it could not run). Thereturn 0/1sites of every other verb (lines 535-6520 andGrantScript.cs167-228).DarlingCliCommands.csline 4368: "the store is unreadable because the service is stopped"). So the store verbs are "either (1)" with the footnote.--enable-collectoris run in-process, not queued, for that reason (line 7897).Program.csdispatch for each verb (args[1]);--backfill-rollupsand--collapse-legacy-slicestake any non---dry-runargument as the path (lines 449-490);ParseRecompressArgs(line 6124).Code and docs disagree
--diagnostics-bundlemust run elevated. The code has no check. The page marks it "yes on the store host" because the README andUsageText()both say so and a managed store's credential file is not readable to other accounts, but it is not enforced.--backfill-rollups"runs while the service is up". The code does not require it, so the page marks it "either (1)".Considered, not added
UsageText(). The lane brief rules this out (Tests that assert spelling, not behavior: cap them, stop the review asking for pins, delete the shape ones #5833: no new census, roster or source-text test). The issue asked to "generate or test" the table. Neither was done. The table is hand-written. A verb added later needs a row by hand.--helptext is not generated from the table or the other way round, for the same reason.Test plan
docs/darling/cli.mdand every anchor inDarling/README.mdthat the new page targets (all resolve).docs/darling/cli.md: kept 1 long sentence (a list of causes in a table cell), the "could not" modals (real inability), and the word "print" (the verb's action).Darling.Tests(0 errors) and ranDarlingCollectorToggleExitCodeTestsandDropXeSessionsVerbTests: Total: 139, Failed: 0.CHANGELOG
Added a command line reference for the Darling service (
docs/darling/cli.md). It lists every verb with what it does, whether it needs elevation, whether the service must be running, and its exit codes. The Quick Start now links to it instead of repeating the exit codes.Seat corrections
Edits to
docs/darling/cli.md, fromDarling/PerformanceMonitor.Darling.Service/DarlingCliCommands.csunless noted. The README text they restore is onorigin/devinDarling/README.md: the paragraphs on--check-settings, the collector verbs and "every other verb that opens the store".2: now says the store cannot be reached, refuses the login (a wrong password is the store's answer, so2), or refuses the change, and that a failed read-back after the write counts too (CollectorToggleExitCode.StoreUnavailable,:7860-7875; the catches around the connection and the write at:331-334,:7131-7135and:7971-7975file every store exception, login refusal included, under it). For--drop-xe-sessions,2is only the monitored server (DropXeSessionsExitCode.TargetUnavailable,:8649-8661, catch at:8925-8929), so the row says the store is not part of that number.1: now names a connection string that cannot be used and a managed store credential that cannot be read (TryCreateCollectorStoreDataSource,:7991-8045, used by the collector verbs:7943,--reset-password-key:307-314, the alert source verbs:7107-7110and--export-investigationsDarlingCliCommands.ExportInvestigations.cs:150-152).--drop-xe-sessionsuses1for an invalid config or a store setting that cannot be used (:8863-8879).1: a managed credential that was never stored (the verbs that shareTryCreateCollectorStoreDataSource; not--drop-xe-sessions, which does not call it); a store not yet upgraded (RunTimeTableMissingMessagefor--set-collector-run-at,:8641-8644;NoTablesfor the alert source verbs,:7193-7195and:7443-7448); an invalid, taken or unknown alert source name (:7190-7207); an output file that cannot be written or exists without--force(DarlingCliCommands.ExportInvestigations.cs:156-212,:289-292).--export-investigationsreturns2when the store cannot be read (:266,:299-302).--check-settings(CheckSettingsExitCode,:1168-1174);--diagnostics-bundle(DiagnosticsBundleExitCode,:951-969); the--harden-filesparagraph (:4880-4890, returns at:4900-4945and:5193-5226).Darling/README.mdanchor#run-on-linux-docker-compose-or-systemd-1804was wrong. An explicit<a id>with that name sits above the Linux heading (Darling/README.md:182). Removed from the Test plan.