Record one cli.command telemetry event per run

Built from the run_record the foundation change already collects, so no
call site changes here: telemetry_event chooses each field from the
record under its privacy rules, and telemetry_sink delivers the line (to
a local file for now, through dated_jsonl). run_record::finish hands the
record to telemetry.

Author: zmofei

CHANGELOG.md

@@ -19,6 +19,13 @@ that may never merge. They are not releases and are not listed here.
 
 ## Unreleased
 
+- Each run records one `cli.command` telemetry event, appended to
+  `~/.mapbox/.telemetry/<date>.jsonl` and kept for 7 days. Nothing is sent
+  anywhere by default. It never touches stdout, the exit code or how long a
+  command takes, so a script sees no difference; a CI job does find a
+  `.mapbox/.telemetry` directory it didn't before. `MAPBOX_CLI_NO_TELEMETRY=1`
+  turns it off.
+
 - `MAPBOX_CLI_EXTRA_QUERY` appends raw query parameters to every request, in
   the same `k1=v1&k2=v2` shape as a URL's own query string — for an API
   parameter this CLI's specs don't declare a flag for.

README.md

@@ -204,6 +204,12 @@ Every request sends `User-Agent: mapbox-cli/<version>` and nothing else
 about you or your machine. `MAPBOX_CLI_NO_TELEMETRY=1` keeps even future markers
 out of that header.
 
+Each run also appends one event to `~/.mapbox/.telemetry/<date>.jsonl`
+(kept for 7 days): the command's name, its options (a value only when it
+comes from a fixed list, otherwise just its length or size), how it ended,
+and how long it took — never a token, a file path or free text you typed.
+It stays on this machine. `MAPBOX_CLI_NO_TELEMETRY=1` turns it off.
+
 ### Agent skills
 
 ```sh

src/main.rs

@@ -33,6 +33,8 @@ mod schema;
 mod skill_dest;
 mod spec;
 mod telemetry;
+mod telemetry_event;
+mod telemetry_sink;
 mod tilesets_cli;
 mod uninstall;
 mod update_check;

src/run_record.rs

@@ -4,9 +4,9 @@
 //! the bytes on stdout, the error — and `main` calls [`finish`] once on the
 //! way out. `set_*` functions overwrite a field, last call wins; `add_*`
 //! functions accumulate. Nothing is written before [`finish`], which hands
-//! the finished [`Record`] to each consumer. There are none yet: command
-//! history and the telemetry event are built from it in the changes stacked
-//! on this one, so that neither has to touch a call site.
+//! the finished [`Record`] to each consumer: [`crate::telemetry_event`].
+//! Consumers are built from the record rather than from call sites of their
+//! own, so adding one touches no call site.
 //!
 //! The record holds raw facts — the command line, URLs, error messages —
 //! because a local diagnostic log wants them. It never leaves this process. A consumer
@@ -18,7 +18,8 @@
 //! nothing here can change a command's output, its exit code, or how long
 //! it takes to return.
 
-// Read by the consumers stacked on this change; nothing reads the record yet.
+// Some facts are read only by consumers not in this tree yet (command
+// history, a diagnostic log).
 #![allow(dead_code)]
 
 use std::ffi::OsString;
@@ -29,7 +30,7 @@ use clap::parser::ValueSource;
 use clap::{ArgMatches, Command};
 
 use crate::spec::ServiceSpec;
-use crate::{auth, completion, confirm, executor, http, output, tilesets_cli};
+use crate::{auth, completion, confirm, executor, http, output, telemetry_event, tilesets_cli};
 
 const TILESETS: &str = tilesets_cli::COMMAND;
 
@@ -348,6 +349,7 @@ fn finish_locked(record: &mut Record, exit_code: Option<u32>) {
     record.finished = true;
     record.duration = STARTED.get().map_or(Duration::ZERO, Instant::elapsed);
     record.exit_code = exit_code;
+    telemetry_event::deliver(record);
 }
 
 fn uuid_v4(mut bytes: [u8; 16]) -> String {

src/telemetry.rs

@@ -51,6 +51,21 @@ fn arch_marker() -> String {
     format!("arch/{}", spelled_arch(std::env::consts::ARCH))
 }
 
+/// The CPU architecture as the event's `env.arch` spells it.
+pub(crate) fn arch() -> &'static str {
+    spelled_arch(std::env::consts::ARCH)
+}
+
+/// Whether this run is in CI, by the same rule as the `env/ci` marker.
+pub(crate) fn in_ci() -> bool {
+    ci_marker().is_some()
+}
+
+/// For `crate::telemetry_event`, which may not reach for stdout itself.
+pub(crate) fn stdout_is_terminal() -> bool {
+    std::io::stdout().is_terminal()
+}
+
 fn spelled_arch(arch: &str) -> &str {
     match arch {
         "aarch64" => "arm64",