What Is Missing
host-setup/linux/install-tools.sh --report emits a column-aligned human table
(TOOL INSTALLED AVAILABLE SOURCE STATUS) followed by a free-text Notes: section. There is no
--json, no --porcelain, and no other stable output contract, so the only way for a program to
learn that a tool is trailing is to parse that table.
Why It Matters
The script is reachable from any host with no checkout at all: a downstream repository's thin wrapper
resolves HUB_REF to a commit, fetches this script to a temp file, and runs it. That makes it the
natural authority for "what does the fleet manage, and is this host current?", which is exactly the
question a scheduled reporter on a downstream host wants to ask before it says anything at login or
in a summary mail.
Screen-scraping the table breaks on changes that are otherwise free: widening a column when a version
string grows, adding a tool whose name exceeds the current field width, rewording a note, introducing
a status word. None of those are breaking changes to a human reader, and every one of them is a
breaking change to a parser. A downstream consumer built on the table would therefore convert routine
edits here into silent breakage there, which is the opposite of what a reporter is for.
Suggested Shape
A --json action alongside --report, carrying the same data, with the human table suppressed:
{
"tools": [
{
"tool": "<name>",
"installed": "<version, or null>",
"available": "<version, or null>",
"source": "<distro, an apt repository host, a GitHub owner/repo, ...>",
"mechanism": "apt | binary",
"status": "current | outdated | missing | unmanaged | unknown",
"notes": ["<one string per note line this tool produced>"]
}
]
}mechanism is worth emitting even though --report does not print it today, because it is the field
that decides whether an OS package upgrade moves a tool at all. The jq | uv | git-restore-mtime arm
installs binaries into $BIN_DIR, and nothing but this script ever moves those, while the
apt-sourced tools ride along with any ordinary apt-get upgrade. A caller reporting drift has to
tell those two apart to say anything useful about what the operator should do next, and today it can
only infer it from the SOURCE string.
Worth settling at the same time whether install-tools.ps1 emits the same schema, since a fleet
reporter that works on one platform only is half a feature.
Not In Scope
What --report prints for a human, and what --install and --upgrade do.
What Is Missing
host-setup/linux/install-tools.sh --reportemits a column-aligned human table(
TOOL INSTALLED AVAILABLE SOURCE STATUS) followed by a free-textNotes:section. There is no--json, no--porcelain, and no other stable output contract, so the only way for a program tolearn that a tool is trailing is to parse that table.
Why It Matters
The script is reachable from any host with no checkout at all: a downstream repository's thin wrapper
resolves
HUB_REFto a commit, fetches this script to a temp file, and runs it. That makes it thenatural authority for "what does the fleet manage, and is this host current?", which is exactly the
question a scheduled reporter on a downstream host wants to ask before it says anything at login or
in a summary mail.
Screen-scraping the table breaks on changes that are otherwise free: widening a column when a version
string grows, adding a tool whose name exceeds the current field width, rewording a note, introducing
a status word. None of those are breaking changes to a human reader, and every one of them is a
breaking change to a parser. A downstream consumer built on the table would therefore convert routine
edits here into silent breakage there, which is the opposite of what a reporter is for.
Suggested Shape
A
--jsonaction alongside--report, carrying the same data, with the human table suppressed:{ "tools": [ { "tool": "<name>", "installed": "<version, or null>", "available": "<version, or null>", "source": "<distro, an apt repository host, a GitHub owner/repo, ...>", "mechanism": "apt | binary", "status": "current | outdated | missing | unmanaged | unknown", "notes": ["<one string per note line this tool produced>"] } ] }mechanismis worth emitting even though--reportdoes not print it today, because it is the fieldthat decides whether an OS package upgrade moves a tool at all. The
jq | uv | git-restore-mtimearminstalls binaries into
$BIN_DIR, and nothing but this script ever moves those, while theapt-sourced tools ride along with any ordinary
apt-get upgrade. A caller reporting drift has totell those two apart to say anything useful about what the operator should do next, and today it can
only infer it from the
SOURCEstring.Worth settling at the same time whether
install-tools.ps1emits the same schema, since a fleetreporter that works on one platform only is half a feature.
Not In Scope
What
--reportprints for a human, and what--installand--upgradedo.