@mostra/cli 0.0.0-stage → 0.2.0

package/src/telemetry/flush.ts

@@ -0,0 +1,143 @@
+/**
+ * Sending the queue (D140 item 6): a detached process the CLI starts after a command, at most one
+ * at a time and at most once a minute. It reads the decision again before it sends, so consent
+ * withdrawn in between drops the events; it posts at most 100 events per request with no header
+ * but `Content-Type`, `User-Agent` and the ones HTTP itself needs, and keeps what a failed
+ * attempt couldn't send for the next flush.
+ */
+import { spawn } from "node:child_process";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { join } from "node:path";
+import type { Environment } from "../home.ts";
+import { cliVersion, fromSource, packageRoot } from "../version.ts";
+import { buildEndpoint, decide } from "./decision.ts";
+import { TelemetryEvent } from "./events.ts";
+import { QUEUE_MAX_EVENTS, type TelemetryStore } from "./store.ts";
+
+/** At most this many events per request. */
+export const BATCH = 100;
+/** A flush starts at most this often. */
+export const FLUSH_INTERVAL_MS = 60_000;
+/** The flush interval; `MOSTRA_TEST_FLUSH_INTERVAL_MS` shortens it, for tests only. */
+function flushInterval(env: Environment): number {
+  const test = Number(env["MOSTRA_TEST_FLUSH_INTERVAL_MS"]);
+  return Number.isInteger(test) && test >= 0 && test < FLUSH_INTERVAL_MS ? test : FLUSH_INTERVAL_MS;
+}
+
+/** One request's limit. */
+const REQUEST_TIMEOUT_MS = 5000;
+
+/** Posts one batch; resolves with whether the collector took it (any 2xx). */
+export function post(endpoint: string, body: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const url = new URL(endpoint);
+    const send = url.protocol === "https:" ? httpsRequest : httpRequest;
+    const req = send(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": `mostra-cli/${cliVersion()}`,
+          "Content-Length": Buffer.byteLength(body),
+        },
+        timeout: REQUEST_TIMEOUT_MS,
+      },
+      (response) => {
+        response.resume();
+        response.on("end", () =>
+          resolve((response.statusCode ?? 0) >= 200 && (response.statusCode ?? 0) < 300),
+        );
+        response.on("error", () => resolve(false));
+      },
+    );
+    req.on("timeout", () => req.destroy());
+    req.on("error", () => resolve(false));
+    req.end(body);
+  });
+}
+
+/**
+ * Sends the queue: the decision again, then batches until one fails. Events the schema refuses
+ * never leave the machine.
+ */
+export async function flush(
+  store: TelemetryStore,
+  env: Environment,
+  now: () => number,
+): Promise<void> {
+  const settings = store.read();
+  // The queue holds only events of uses that aren't embedded; the rest of the order applies again.
+  const decision = decide({
+    env,
+    buildEndpoint: buildEndpoint(),
+    embedded: false,
+    settings,
+    askFirst: false,
+  });
+  if (!decision.enabled || decision.endpoint === undefined) {
+    // Consent withdrawn (or never given) since the events were queued: they go unsent.
+    if (decision.reason !== "no-collector" && settings.ok) store.drop(store.queued(now()), now());
+    return;
+  }
+  // The queue holds at most QUEUE_MAX_EVENTS, so a flush needs at most this many batches.
+  for (let round = 0; round <= Math.ceil(QUEUE_MAX_EVENTS / BATCH); round += 1) {
+    const lines = store.queued(now()).slice(0, BATCH);
+    if (lines.length === 0) return;
+    const events: unknown[] = [];
+    for (const line of lines) {
+      try {
+        const parsed = TelemetryEvent.safeParse(JSON.parse(line));
+        if (parsed.success) events.push(parsed.data);
+      } catch {
+        // Not an event: dropped with the batch.
+      }
+    }
+    const sent = events.length === 0 || (await post(decision.endpoint, JSON.stringify({ events })));
+    if (!sent) return;
+    // Nothing removed (another process changed the queue, or the lock was out of reach): stop
+    // rather than send the same batch again.
+    if (store.drop(lines, now()) === 0) return;
+  }
+}
+
+/** The flusher's entry in the CLI's package. */
+function flusherEntry(): { readonly entry: string; readonly nodeArgs: readonly string[] } {
+  const root = packageRoot();
+  return fromSource()
+    ? {
+        entry: join(root, "src", "telemetry", "flush-main.ts"),
+        nodeArgs: ["--conditions=@mostra/source"],
+      }
+    : { entry: join(root, "dist", "telemetry", "flush-main.js"), nodeArgs: [] };
+}
+
+/**
+ * Starts a flusher when the queue has events and no flush started in the last minute, fully
+ * detached: no stdio, its own process group, never waited for, so `mostra … | jq` and every
+ * harness reading to end of file finish when the command does.
+ */
+export function startFlusher(store: TelemetryStore, env: Environment, now: number): void {
+  if (store.queued(now).length === 0) return;
+  let due = false;
+  store.update((current) => {
+    const last = current.lastFlushAt === undefined ? 0 : Date.parse(current.lastFlushAt);
+    if (Number.isFinite(last) && now - last < flushInterval(env)) return current;
+    due = true;
+    return { ...current, lastFlushAt: new Date(now).toISOString() };
+  });
+  if (!due) return;
+  const { entry, nodeArgs } = flusherEntry();
+  try {
+    const child = spawn(process.execPath, [...nodeArgs, entry, store.dir], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, ...env } as NodeJS.ProcessEnv,
+    });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // Telemetry never changes a command's outcome.
+  }
+}

package/src/telemetry/harness.ts

@@ -0,0 +1,39 @@
+/**
+ * Which agent ran the CLI (D140 item 9), from environment markers each agent documents or sets in
+ * its source (VERIFIED_FACTS, WP-10). Only the agent's ID is ever sent, never a marker's value.
+ */
+import type { Environment } from "../home.ts";
+
+/** The agents Mostra recognizes, in the order their markers are checked. */
+export const HARNESSES = ["claude-code", "codex", "gemini-cli", "opencode", "cursor"] as const;
+
+/** A recognized agent, `other` for an agent Mostra doesn't know, `none` for no agent at all. */
+export type Harness = (typeof HARNESSES)[number] | "other" | "none";
+
+/** Each agent's own marker. */
+const MARKERS: Readonly<Record<(typeof HARNESSES)[number], string>> = {
+  "claude-code": "CLAUDECODE",
+  codex: "CODEX_THREAD_ID",
+  "gemini-cli": "GEMINI_CLI",
+  opencode: "OPENCODE",
+  cursor: "CURSOR_AGENT",
+};
+
+const set = (value: string | undefined): boolean => value !== undefined && value !== "";
+
+/**
+ * The agent that ran this process: `AI_AGENT` when it starts with a known ID (the convention
+ * `@vercel/detect-agent` reads), else the first agent whose own marker is set, else `other` when
+ * `AI_AGENT` or `AGENT` names something else, else `none`. Cursor's editor terminal sets
+ * `CURSOR_TRACE_ID` without `CURSOR_AGENT`: that is a person, so it isn't `cursor`.
+ */
+export function detectHarness(env: Environment): Harness {
+  const declared = env["AI_AGENT"];
+  if (set(declared)) {
+    const known = HARNESSES.find((id) => declared?.startsWith(id));
+    if (known) return known;
+  }
+  for (const id of HARNESSES) if (set(env[MARKERS[id]])) return id;
+  if (set(declared) || set(env["AGENT"])) return "other";
+  return "none";
+}

package/src/telemetry/index.ts

@@ -0,0 +1,318 @@
+/**
+ * The standalone CLI's telemetry (D119, D140): the only code in Mostra that can send an event, and
+ * only `@mostra/cli` may import it (a dependency-cruiser rule). The runner calls {@link begin}
+ * before a command's work and {@link end} after it; everything else here is the decision, the
+ * words, the schema, the store and the flusher.
+ */
+import { type DiagnosticCode, diagnosticCatalog } from "@mostra/protocol";
+import type { Environment } from "../home.ts";
+import { cliVersion } from "../version.ts";
+import { buildEndpoint, decide, type TelemetryDecision, truthy } from "./decision.ts";
+import {
+  type CommonFields,
+  catalogCodes,
+  durationBucket,
+  minute,
+  SCHEMA,
+  TelemetryEvent,
+} from "./events.ts";
+import { startFlusher } from "./flush.ts";
+import { detectHarness } from "./harness.ts";
+import { TelemetryStore } from "./store.ts";
+import { asksFirst, type ZoneSources } from "./timezone.ts";
+import { ANSWER, NOTICE_ASK_FIRST, NOTICE_DEFAULT, QUESTION, statusLine } from "./words.ts";
+
+export { TelemetryStore } from "./store.ts";
+export { TURNED } from "./words.ts";
+
+/** The catalog's codes: only these leave the machine in `error` and `codes`. */
+const CATALOG = new Set(Object.keys(diagnosticCatalog));
+
+/** Variables CI services set; any of them means `ci: true`, and the question is never asked. */
+const CI_MARKERS = [
+  "CI",
+  "CONTINUOUS_INTEGRATION",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "BUILDKITE",
+  "CIRCLECI",
+  "TRAVIS",
+  "TF_BUILD",
+  "JENKINS_URL",
+  "TEAMCITY_VERSION",
+  "BITBUCKET_BUILD_NUMBER",
+  "CODEBUILD_BUILD_ID",
+];
+
+/** Whether this process runs in CI. */
+export function inCi(env: Environment): boolean {
+  return CI_MARKERS.some((name) => truthy(env[name]));
+}
+
+/** What a session of one command needs. */
+export interface TelemetryOptions {
+  readonly env: Environment;
+  readonly configDir: string;
+  /** The command's path from the definitions (`daemon install`), or `unknown`. */
+  readonly command: string;
+  readonly json: boolean;
+  readonly tty: { readonly stdin: boolean; readonly stderr: boolean };
+  /** The command reads stdin, so the question would take its input. */
+  readonly readsStdin: boolean;
+  /** `telemetry`, `docs`, `--help`, `--version`: no notice, no question, no event. */
+  readonly quiet: boolean;
+  /** Whether the home is a host's (its `config.json` mark, or a file that can't be read). */
+  readonly hostHome: boolean;
+  /** Writes to stderr. */
+  readonly stderr: (text: string) => void;
+  /** Asks one line on stderr and reads the answer, `undefined` for none within `timeoutMs`. */
+  readonly ask: (question: string, timeoutMs: number) => Promise<string | undefined | "interrupt">;
+  /** The clock; tests move it. */
+  readonly now?: () => number;
+  /** The build's endpoint; tests pass their own. Default {@link buildEndpoint}. */
+  readonly buildEndpoint?: string;
+  /** Where the zone names come from; tests replace `/etc/localtime` and `Intl`. */
+  readonly zones?: Omit<ZoneSources, "env">;
+  /** Starts the flusher after queueing; tests of the queue turn it off. Default true. */
+  readonly flush?: boolean;
+}
+
+/** How long the question waits for an answer. */
+export const QUESTION_TIMEOUT_MS = 60_000;
+
+/** One command's telemetry. */
+export interface TelemetrySession {
+  /** Before the command's work: the notice, or the question. Resolves `false` when Ctrl-C ended it. */
+  begin(): Promise<boolean>;
+  /** Records an event of the command (`verify.result`, `publish.done`). */
+  record(event: {
+    readonly event: "verify.result" | "publish.done";
+    readonly fields: Readonly<Record<string, unknown>>;
+  }): void;
+  /** After the command: queues its events and starts the flusher, when telemetry allows. */
+  end(outcome: {
+    readonly exit: number;
+    readonly durationMs: number;
+    readonly error?: string;
+    /** The instance was host-spawned. */
+    readonly hostInstance: boolean;
+  }): void;
+}
+
+/** The current decision, for `telemetry status` and the session. */
+export function currentDecision(options: {
+  readonly env: Environment;
+  readonly store: TelemetryStore;
+  readonly embedded: boolean;
+  readonly buildEndpoint?: string;
+  readonly zones?: Omit<ZoneSources, "env">;
+}): TelemetryDecision {
+  return decide({
+    env: options.env,
+    buildEndpoint: options.buildEndpoint ?? buildEndpoint(),
+    embedded: options.embedded,
+    settings: options.store.read(),
+    askFirst: asksFirst({ ...options.zones, env: options.env }),
+  });
+}
+
+/** Starts one command's telemetry. */
+export function telemetrySession(options: TelemetryOptions): TelemetrySession {
+  const now = options.now ?? Date.now;
+  const store = new TelemetryStore(options.configDir);
+  const pending: {
+    event: "verify.result" | "publish.done";
+    fields: Readonly<Record<string, unknown>>;
+  }[] = [];
+  const decision = (embedded: boolean): TelemetryDecision =>
+    currentDecision({
+      env: options.env,
+      store,
+      embedded,
+      ...(options.buildEndpoint !== undefined ? { buildEndpoint: options.buildEndpoint } : {}),
+      ...(options.zones !== undefined ? { zones: options.zones } : {}),
+    });
+  const shown = (): boolean => {
+    const read = store.read();
+    return read.ok && read.settings.noticeShownAt !== undefined;
+  };
+  /** Records that the notice was shown; `false` when the store can't be written. */
+  const markShown = (): boolean =>
+    store.update((current) => ({ ...current, noticeShownAt: new Date(now()).toISOString() })) !==
+    undefined;
+  const harness = detectHarness(options.env);
+  const ci = inCi(options.env);
+
+  return {
+    async begin() {
+      if (options.quiet) return true;
+      const current = decision(options.hostHome);
+      // No collector, a host's home, or a person who said no: nothing to say (D140 item 7).
+      if (current.reason === "no-collector" || current.reason === "embedded") return true;
+      // The notice is recorded before it is printed: a store that can't record it (a directory
+      // that can't be written) means no notice, and so nothing ever sent.
+      if (current.enabled) {
+        if (!shown() && markShown()) options.stderr(NOTICE_DEFAULT);
+        return true;
+      }
+      if (current.reason !== "default" || !current.askFirst) return true;
+      const canAsk =
+        options.tty.stdin &&
+        options.tty.stderr &&
+        !options.json &&
+        !ci &&
+        harness === "none" &&
+        !options.readsStdin;
+      if (!canAsk) {
+        // Once, and on its own record: it never stands for the default notice.
+        const read = store.read();
+        if (read.ok && read.settings.askFirstNoticeShownAt === undefined) {
+          const marked = store.update((settings) => ({
+            ...settings,
+            askFirstNoticeShownAt: new Date(now()).toISOString(),
+          }));
+          if (marked !== undefined) options.stderr(NOTICE_ASK_FIRST);
+        }
+        return true;
+      }
+      // A person who can answer and never did is asked, whatever notices they saw before.
+      const answer = await options.ask(QUESTION, QUESTION_TIMEOUT_MS);
+      const yes = typeof answer === "string" && /^\s*y(es)?\s*$/i.test(answer);
+      const stored = store.update((settings) => ({
+        ...settings,
+        choice: yes ? "on" : "off",
+        noticeShownAt: new Date(now()).toISOString(),
+      }));
+      options.stderr(
+        stored === undefined
+          ? `${statusLine({ enabled: false, reason: "unreadable", askFirst: true, settingsFile: store.settingsFile })}\n`
+          : yes
+            ? ANSWER.yes
+            : answer === undefined
+              ? ANSWER.timeout
+              : ANSWER.no,
+      );
+      return answer !== "interrupt";
+    },
+
+    record(event) {
+      pending.push({ event: event.event, fields: event.fields });
+    },
+
+    end(outcome) {
+      if (options.quiet) return;
+      const current = decision(options.hostHome || outcome.hostInstance);
+      if (!current.enabled || current.consent === undefined || !shown()) return;
+      const id = store.installId();
+      if (!id) return;
+      const common: CommonFields = {
+        schema: SCHEMA,
+        at: minute(new Date(now())),
+        installId: id.id,
+        version: cliVersion(),
+        os: process.platform === "darwin" ? "darwin" : "linux",
+        arch: process.arch,
+        node: Number(process.versions.node.split(".")[0]),
+        harness,
+        ci,
+        consent: current.consent,
+      };
+      const events: unknown[] = [];
+      if (id.created) events.push({ ...common, event: "cli.first_run" });
+      for (const item of pending) {
+        const fields =
+          item.event === "verify.result"
+            ? {
+                status: item.fields["status"],
+                ...catalogCodes((item.fields["codes"] as string[] | undefined) ?? [], CATALOG),
+              }
+            : item.fields;
+        events.push({ ...common, ...fields, event: item.event });
+      }
+      events.push({
+        ...common,
+        event: "cli.command",
+        command: options.command,
+        exit: outcome.exit,
+        duration: durationBucket(outcome.durationMs),
+        json: options.json,
+        ...(outcome.error !== undefined && CATALOG.has(outcome.error as DiagnosticCode)
+          ? { error: outcome.error }
+          : {}),
+      });
+      const lines: string[] = [];
+      for (const event of events) {
+        const parsed = TelemetryEvent.safeParse(event);
+        if (parsed.success) lines.push(JSON.stringify(parsed.data));
+      }
+      if (truthy(options.env["MOSTRA_TELEMETRY_DEBUG"])) {
+        // Exactly what would be sent, and nothing sent.
+        for (const line of lines) options.stderr(`mostra telemetry (debug, not sent): ${line}\n`);
+        return;
+      }
+      store.append(lines, now());
+      if (options.flush !== false) startFlusher(store, options.env, now());
+    },
+  };
+}
+
+/** `mostra telemetry status`'s result. */
+export interface TelemetryStatus {
+  readonly enabled: boolean;
+  readonly reason: TelemetryDecision["reason"];
+  readonly askFirst: boolean;
+  readonly installId?: string;
+  readonly endpoint?: string;
+  readonly queued: number;
+  readonly noticeShownAt?: string;
+  readonly settingsFile: string;
+  /** With reason `unreadable`: the file that can't be read (the home's `config.json`, or this). */
+  readonly unreadableFile?: string;
+}
+
+/** `mostra telemetry status`: the decision, the install ID and the queue. */
+export function telemetryStatus(options: {
+  readonly env: Environment;
+  readonly configDir: string;
+  readonly embedded: boolean;
+  /**
+   * The home's `config.json` when it can't be read: the runner sends nothing then, as for a
+   * host's home, and status says so (Opus review finding 6).
+   */
+  readonly homeConfigUnreadable?: string;
+  readonly now?: number;
+}): { readonly status: TelemetryStatus; readonly text: string } {
+  const store = new TelemetryStore(options.configDir);
+  const decided = currentDecision({ env: options.env, store, embedded: options.embedded });
+  const homeBlocks =
+    options.homeConfigUnreadable !== undefined && decided.reason !== "no-collector";
+  const decision = homeBlocks
+    ? { ...decided, enabled: false, reason: "unreadable" as const }
+    : decided;
+  const unreadableFile = homeBlocks
+    ? options.homeConfigUnreadable
+    : decision.reason === "unreadable"
+      ? store.settingsFile
+      : undefined;
+  const read = store.read();
+  const settings = read.ok ? read.settings : {};
+  const queued = read.ok ? store.queued(options.now ?? Date.now()).length : 0;
+  const status: TelemetryStatus = {
+    enabled: decision.enabled,
+    reason: decision.reason,
+    askFirst: decision.askFirst,
+    ...(settings.installId !== undefined ? { installId: settings.installId } : {}),
+    ...(decision.endpoint !== undefined ? { endpoint: decision.endpoint } : {}),
+    queued,
+    ...(settings.noticeShownAt !== undefined ? { noticeShownAt: settings.noticeShownAt } : {}),
+    settingsFile: store.settingsFile,
+    ...(unreadableFile !== undefined ? { unreadableFile } : {}),
+  };
+  const lines = [
+    statusLine({ ...decision, settingsFile: unreadableFile ?? store.settingsFile }),
+    ...(status.installId !== undefined ? [`Install ID: ${status.installId}`] : []),
+    `Queued events: ${queued}`,
+    `Settings: ${store.settingsFile}`,
+  ];
+  return { status, text: lines.join("\n") };
+}