From 6ab7c3a65ace85c76090575a4edfb993bb132721 Mon Sep 17 00:00:00 2001 From: Codechu Date: Sat, 29 Aug 2026 18:17:51 +0300 Subject: [PATCH] Write down what a tool owes at its prompt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Seven things were missing from a shipped Codechu tool, and each was found by running it rather than by reading it: `--version` did not exist; four flags had no help; there was no way to drop the chrome for a pipe or a CI log; the banner box had been one character wider than its border in every release; the banner appeared on one long command and not the other; a second tool had no entry point at all, only module paths; and its help printed the interpreter's name because `prog` was unset. None of them are hard, and none of them would have been noticed by reading the source. They are written down so the next tool starts with them rather than discovering them one release at a time — two of the seven are testable, and the section says to bind them. --- project-type/TOOL.md | 45 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/project-type/TOOL.md b/project-type/TOOL.md index e4314c9..6f2c272 100644 --- a/project-type/TOOL.md +++ b/project-type/TOOL.md @@ -92,7 +92,50 @@ filter line-by-line. - No update mechanism, no telemetry, no first-run wizard. If a tool wants any of those, ask first whether it is really an application. -## 8. README is the vitrine — tool skeleton +## 8. The command-line experience + +A tool is met at its prompt, and these were each missing from a shipped +Codechu tool before they were written down. + +**`--version` answers, and without a subcommand.** *Incident: a tool whose +whole discipline is that every artefact carries a version stamp could not +be asked its own — `--version` failed with "the following arguments are +required: cmd".* + +**Every flag explains itself, and a test says so.** A flag with no help is +a flag only its author can use, and argument parsers print the blank line +without complaint — nothing fails when someone adds one. Walk the parser +in a test and fail on a flag with empty help. *Incident: four naked flags +had shipped, `--endpoint` among them; the test found two more the moment +it ran.* + +**Chrome is optional; results are not.** A tool that takes minutes may +print a product mark and progress. It must offer one flag that drops them +— `-q` / `--quiet` — and that flag must never suppress results, warnings +or errors. A quiet flag that can hide a failure is a footgun, not an +option. + +**Draw the mark from its content, not from literals.** *Incident: a +four-line banner box whose content line was one character wider than its +border, in every release since it was written — the first thing a user +sees, and nobody had looked at it.* Build the box from the strings it +contains and hold the shape with a test across several version strings. + +**The mark is consistent across commands.** If one long-running command +prints it, the others do too. *Incident: the banner appeared on `run` and +not on `qualify`, which takes just as long.* + +**One entry point, named after the tool.** `tool `, not +`python -m package.module`. *Incident: a line published as a tool required +the reader to know four separate module paths, none of them discoverable +from the others.* + +**Set the program name.** Parsers default to the interpreter's path, so +help reads `usage: python3.14 -m package.module` — a different string on +every machine, and not a command anyone would type. Set `prog` to the +command name. + +## 9. README is the vitrine — tool skeleton The vitrine principle from [STANDARDS §7.1](../STANDARDS.md#71-readme-is-the-vitrine) applies with