@mostra/cli 0.0.0-stage → 0.2.0

package/src/telemetry/store.ts

@@ -0,0 +1,379 @@
+/**
+ * Telemetry's files in the CLI's config directory (D140 item 5): `telemetry.json` (the choice,
+ * when the notice was shown, when a flush last started), `telemetry-id` (the random install ID)
+ * and `telemetry-queue.ndjson` (events waiting to be sent). The directory is 0700 and the files
+ * 0600; `telemetry.json` and the queue are written by rename. The install ID is made by an
+ * exclusive create (a hard link that fails when the file exists), so processes on a first run
+ * agree on one ID whatever happens to the lock. Every other change goes through one lock file,
+ * owned by a token and taken over only when its holder has died, so a flusher never loses an
+ * event appended while it sends.
+ */
+import { randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  fstatSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+/** What `telemetry.json` holds. */
+export interface TelemetrySettings {
+  /** The person's choice: `mostra telemetry on|off`, or their answer to the question. */
+  readonly choice?: "on" | "off";
+  /**
+   * The random install ID, made on the first run that sends; deleted when telemetry turns off.
+   * Read from `telemetry-id`, never written into `telemetry.json`.
+   */
+  readonly installId?: string;
+  /**
+   * When the notice of what is sent was shown where sending follows: the default notice, the
+   * question, or `mostra telemetry on`'s. A `default`-consent event needs it (Opus review
+   * finding 3).
+   */
+  readonly noticeShownAt?: string;
+  /**
+   * When the ask-first notice ("Nothing is sent unless you run: mostra telemetry on") was
+   * shown. It never stands for the default notice: a later run where telemetry is on by default
+   * still shows that one before anything is sent.
+   */
+  readonly askFirstNoticeShownAt?: string;
+  /** When a flush last started. */
+  readonly lastFlushAt?: string;
+}
+
+/** The settings, or why they can't be read (which means off, D140 item 5). */
+export type ReadSettings =
+  | { readonly ok: true; readonly settings: TelemetrySettings }
+  | { readonly ok: false; readonly file: string };
+
+/** A lock older than this whose owner no longer runs is taken over as stale. */
+const STALE_LOCK_MS = 10_000;
+/**
+ * A lock older than this is taken over whoever it names: a held section takes milliseconds, and
+ * a PID can name an unrelated live process once the owner died (in a container, PID 1 always
+ * runs), which would otherwise hold every later command up forever (Opus review finding 5).
+ */
+const DEAD_LOCK_MS = 60_000;
+/** The queue's bounds (D140 item 6). */
+export const QUEUE_MAX_EVENTS = 1000;
+export const QUEUE_MAX_AGE_MS: number = 7 * 24 * 60 * 60 * 1000;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** Telemetry's files in one config directory. */
+export class TelemetryStore {
+  readonly dir: string;
+  readonly settingsFile: string;
+  readonly queueFile: string;
+  readonly idFile: string;
+  readonly #lockFile: string;
+
+  constructor(dir: string) {
+    this.dir = dir;
+    this.settingsFile = join(dir, "telemetry.json");
+    this.queueFile = join(dir, "telemetry-queue.ndjson");
+    this.idFile = join(dir, "telemetry-id");
+    this.#lockFile = join(dir, "telemetry.lock");
+  }
+
+  /** The settings; a file that isn't telemetry settings is unreadable, never guessed at. */
+  read(): ReadSettings {
+    const id = this.#readId();
+    if (id === null) return { ok: false, file: this.idFile };
+    let text: string;
+    try {
+      text = readFileSync(this.settingsFile, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT")
+        return { ok: true, settings: id !== undefined ? { installId: id } : {} };
+      return { ok: false, file: this.settingsFile };
+    }
+    try {
+      const data = JSON.parse(text) as Record<string, unknown>;
+      if (typeof data !== "object" || data === null || Array.isArray(data)) throw new Error();
+      const { choice, noticeShownAt, askFirstNoticeShownAt, lastFlushAt } = data;
+      const installId = id;
+      if (choice !== undefined && choice !== "on" && choice !== "off") throw new Error();
+      // An install ID belongs in `telemetry-id`; one here is a file Mostra didn't write.
+      if (data["installId"] !== undefined) throw new Error();
+      if (noticeShownAt !== undefined && typeof noticeShownAt !== "string") throw new Error();
+      if (askFirstNoticeShownAt !== undefined && typeof askFirstNoticeShownAt !== "string")
+        throw new Error();
+      if (lastFlushAt !== undefined && typeof lastFlushAt !== "string") throw new Error();
+      return {
+        ok: true,
+        settings: {
+          ...(choice !== undefined ? { choice } : {}),
+          ...(installId !== undefined ? { installId } : {}),
+          ...(noticeShownAt !== undefined ? { noticeShownAt } : {}),
+          ...(askFirstNoticeShownAt !== undefined ? { askFirstNoticeShownAt } : {}),
+          ...(lastFlushAt !== undefined ? { lastFlushAt } : {}),
+        },
+      };
+    } catch {
+      return { ok: false, file: this.settingsFile };
+    }
+  }
+
+  /**
+   * Changes the settings under the lock and returns what they became; `undefined` when the file
+   * can't be read (nothing is written over it).
+   */
+  update(change: (current: TelemetrySettings) => TelemetrySettings): TelemetrySettings | undefined {
+    return this.locked(() => {
+      const current = this.read();
+      if (!current.ok) return undefined;
+      const next = change(current.settings);
+      this.#write(next);
+      return next;
+    });
+  }
+
+  /**
+   * The install ID, made when there is none yet. A new ID is written to a file of this process's
+   * own, then hard-linked to `telemetry-id`, which fails when the file exists: of any processes
+   * making one at once exactly one wins, and the others read the winner's. `undefined` when the
+   * settings can't be read.
+   */
+  installId(): { readonly id: string; readonly created: boolean } | undefined {
+    const current = this.read();
+    if (!current.ok) return undefined;
+    if (current.settings.installId !== undefined)
+      return { id: current.settings.installId, created: false };
+    const candidate = `${this.idFile}.${process.pid}.${randomUUID()}.tmp`;
+    const id = randomUUID();
+    try {
+      this.#prepareDir();
+      writeFileSync(candidate, `${id}\n`, { mode: 0o600 });
+      linkSync(candidate, this.idFile);
+      return { id, created: true };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") return undefined;
+      const winner = this.#readId();
+      return winner ? { id: winner, created: false } : undefined;
+    } finally {
+      rmSync(candidate, { force: true });
+    }
+  }
+
+  /** The install ID in `telemetry-id`: `undefined` when there is none, `null` when it's damaged. */
+  #readId(): string | undefined | null {
+    let text: string;
+    try {
+      text = readFileSync(this.idFile, "utf8");
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === "ENOENT" ? undefined : null;
+    }
+    const id = text.trim();
+    return UUID.test(id) ? id : null;
+  }
+
+  /**
+   * Replaces a file that can't be read with these settings; only `telemetry on|off` do, as the
+   * person's explicit choice. Call it holding the lock.
+   */
+  reset(settings: TelemetrySettings): TelemetrySettings {
+    const { installId: _id, ...rest } = settings;
+    this.#write(rest);
+    // A damaged install ID goes too; `on` makes a new one on its first send.
+    rmSync(this.idFile, { force: true });
+    if (settings.choice === "off") rmSync(this.queueFile, { force: true });
+    return rest;
+  }
+
+  /** Turns telemetry off: the choice, and the install ID and the queue deleted at once. */
+  turnOff(): boolean {
+    return (
+      this.locked(() => {
+        const current = this.read();
+        if (!current.ok) return false;
+        const { installId: _id, ...rest } = current.settings;
+        this.#write({ ...rest, choice: "off" });
+        rmSync(this.idFile, { force: true });
+        rmSync(this.queueFile, { force: true });
+        return true;
+      }) ?? false
+    );
+  }
+
+  /** Appends events to the queue, keeping its bounds. */
+  append(lines: readonly string[], now: number): void {
+    if (lines.length === 0) return;
+    this.locked(() => {
+      const kept = bounded([...this.#queued(), ...lines], now);
+      this.#writeQueue(kept);
+    });
+  }
+
+  /** The queued events, within their bounds. */
+  queued(now: number): string[] {
+    return bounded(this.#queued(), now);
+  }
+
+  /**
+   * Removes the lines a flush sent from the head of the queue, after pruning what expired or
+   * fell outside the bounds, as {@link queued} did; how many sent lines were removed (0 when the
+   * lock can't be had). A flusher stops when this is 0, so it never sends a batch twice.
+   */
+  drop(sent: readonly string[], now: number): number {
+    return (
+      this.locked(() => {
+        const queued = bounded(this.#queued(), now);
+        let index = 0;
+        while (index < sent.length && queued[index] === sent[index]) index += 1;
+        this.#writeQueue(queued.slice(index));
+        return index;
+      }) ?? 0
+    );
+  }
+
+  #queued(): string[] {
+    try {
+      return readFileSync(this.queueFile, "utf8")
+        .split("\n")
+        .filter((line) => line.length > 0);
+    } catch {
+      return [];
+    }
+  }
+
+  #writeQueue(lines: readonly string[]): void {
+    if (lines.length === 0) {
+      rmSync(this.queueFile, { force: true });
+      return;
+    }
+    const temporary = `${this.queueFile}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${lines.join("\n")}\n`, { mode: 0o600 });
+    renameSync(temporary, this.queueFile);
+  }
+
+  #write(settings: TelemetrySettings): void {
+    const { installId: _id, ...stored } = settings;
+    const temporary = `${this.settingsFile}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, this.settingsFile);
+  }
+
+  #prepareDir(): void {
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    try {
+      chmodSync(this.dir, 0o700);
+    } catch {
+      // A directory someone else owns: the files below fail or succeed on their own terms.
+    }
+  }
+
+  /**
+   * Runs `fn` holding the lock file; `undefined` when the lock can't be had within 2 s, or the
+   * directory or a file in it can't be written (a full disk, a directory someone else owns):
+   * telemetry never stops a command (D140 item 5). The lock
+   * holds its owner's PID and a token of its own, is released only by its owner, and is taken
+   * over when it is older than 10 s and its owner is no longer running (a crash), or older than
+   * 60 s whoever it names.
+   */
+  locked<T>(fn: () => T): T | undefined {
+    try {
+      this.#prepareDir();
+    } catch {
+      return undefined;
+    }
+    const token = `${process.pid} ${randomUUID()}`;
+    const deadline = Date.now() + 2000;
+    for (;;) {
+      try {
+        writeFileSync(this.#lockFile, token, { flag: "wx", mode: 0o600 });
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") return undefined;
+        if (this.#breakStale()) continue;
+        if (Date.now() > deadline) return undefined;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+      }
+    }
+    try {
+      return fn();
+    } catch {
+      return undefined;
+    } finally {
+      this.#release(token);
+    }
+  }
+
+  /** Removes the lock when it is still this owner's. */
+  #release(token: string): void {
+    try {
+      if (readFileSync(this.#lockFile, "utf8") === token) rmSync(this.#lockFile, { force: true });
+    } catch {
+      // Gone already.
+    }
+  }
+
+  /**
+   * Takes a crashed owner's lock away; `true` when the caller should try again at once. The lock
+   * is moved aside under a name of this process's own (a rename is atomic, so of two processes
+   * breaking it one gets it), and a lock that turns out to be another, live owner's goes back.
+   */
+  #breakStale(): boolean {
+    // One descriptor for the age and the contents, so both describe the same file.
+    let seen: string;
+    let age: number;
+    let handle: number | undefined;
+    try {
+      handle = openSync(this.#lockFile, "r");
+      age = Date.now() - fstatSync(handle).mtimeMs;
+      if (age <= STALE_LOCK_MS) return false;
+      seen = readFileSync(handle, "utf8");
+    } catch {
+      return true;
+    } finally {
+      if (handle !== undefined) closeSync(handle);
+    }
+    if (age <= DEAD_LOCK_MS && ownerAlive(seen)) return false;
+    const aside = `${this.#lockFile}.${process.pid}.${randomUUID()}.stale`;
+    try {
+      renameSync(this.#lockFile, aside);
+    } catch {
+      return true;
+    }
+    try {
+      if (readFileSync(aside, "utf8") !== seen) linkSync(aside, this.#lockFile);
+    } catch {
+      // Another process holds a new lock already; ours goes, and the caller waits for theirs.
+    } finally {
+      rmSync(aside, { force: true });
+    }
+    return true;
+  }
+}
+
+/** Whether the process a lock names still runs; a lock whose owner can't be read counts as live. */
+function ownerAlive(lock: string): boolean {
+  const pid = Number(lock.split(" ")[0]);
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** The newest events within 1,000, none older than 7 days; lines that aren't JSON go. */
+function bounded(lines: readonly string[], now: number): string[] {
+  const fresh = lines.filter((line) => {
+    try {
+      const at = Date.parse((JSON.parse(line) as { at?: string }).at ?? "");
+      return Number.isFinite(at) && now - at <= QUEUE_MAX_AGE_MS;
+    } catch {
+      return false;
+    }
+  });
+  return fresh.slice(-QUEUE_MAX_EVENTS);
+}

package/src/telemetry/timezone.ts

@@ -0,0 +1,72 @@
+/**
+ * Whether this machine's time zone asks first (D140 items 2 and 10). The zone is read here, on
+ * this machine, and never sent. Every candidate name counts, as given: `TZ` (a leading `:`
+ * removed), the target of `/etc/localtime`, and `Intl`'s zone. A machine asks first when any of
+ * them is an ask-first zone, or none is a zone tzdata knows (missing, empty, `Etc/Unknown`, a
+ * POSIX rule, a typo). Names are never canonicalized: tzdata links `Europe/Zagreb` to
+ * `Europe/Belgrade` and `Indian/Reunion` to `Asia/Dubai`, and ICU builds differ in what they
+ * resolve.
+ */
+import { readlinkSync } from "node:fs";
+import type { Environment } from "../home.ts";
+import { ASK_FIRST_ZONES, KNOWN_ZONES } from "./zones.generated.ts";
+
+const ASK_FIRST = new Set(ASK_FIRST_ZONES);
+const KNOWN = new Set(KNOWN_ZONES);
+
+/** Where the zone names come from; tests replace each. */
+export interface ZoneSources {
+  readonly env: Environment;
+  /** The target of `/etc/localtime`, or `undefined`. */
+  readonly localtime?: () => string | undefined;
+  /** `Intl.DateTimeFormat().resolvedOptions().timeZone`, which can be `undefined`. */
+  readonly intl?: () => string | undefined;
+}
+
+/** The target of `/etc/localtime` after `zoneinfo/`, when it is a symbolic link. */
+function localtimeLink(): string | undefined {
+  try {
+    const target = readlinkSync("/etc/localtime");
+    const at = target.lastIndexOf("zoneinfo/");
+    return at === -1 ? undefined : target.slice(at + "zoneinfo/".length);
+  } catch {
+    return undefined;
+  }
+}
+
+function intlZone(): string | undefined {
+  try {
+    const zone: unknown = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return typeof zone === "string" ? zone : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The candidate zone names, as given (empty and missing ones dropped). */
+export function zoneCandidates(sources: ZoneSources): string[] {
+  const tz = sources.env["TZ"];
+  const fromTz = tz === undefined ? undefined : tz.startsWith(":") ? tz.slice(1) : tz;
+  // Tests of the real binary name the machine's zone (`/etc/localtime`) with
+  // MOSTRA_TEST_LOCALTIME, empty for none, as the runtime's MOSTRA_TEST_* hooks do; nothing else
+  // reads it.
+  const testLocaltime = sources.env["MOSTRA_TEST_LOCALTIME"];
+  const localtime =
+    sources.localtime ??
+    (testLocaltime !== undefined
+      ? () => (testLocaltime === "" ? undefined : testLocaltime)
+      : localtimeLink);
+  const names = [fromTz, localtime(), (sources.intl ?? intlZone)()];
+  return names.filter((name): name is string => typeof name === "string" && name.length > 0);
+}
+
+/** Whether telemetry asks first on this machine. */
+export function asksFirst(sources: ZoneSources): boolean {
+  const candidates = zoneCandidates(sources);
+  if (candidates.some((name) => ASK_FIRST.has(name))) return true;
+  // TZ, when set, is the zone the process runs in: an empty one (UTC under POSIX), a POSIX rule
+  // or a name tzdata doesn't know is an unknown zone, so ask first.
+  const tz = sources.env["TZ"];
+  if (tz !== undefined && !KNOWN.has(tz.startsWith(":") ? tz.slice(1) : tz)) return true;
+  return !candidates.some((name) => KNOWN.has(name) && name !== "Etc/Unknown");
+}

package/src/telemetry/words.ts

@@ -0,0 +1,87 @@
+/**
+ * Telemetry's words to people (D140 item 11): the notice, the question, its answers and the
+ * `status` lines, exactly as Mirza approved them (M28). `<docs>` is `DEFAULT_DOCS_BASE` (D37).
+ */
+import { DEFAULT_DOCS_BASE } from "@mostra/protocol";
+
+const DOCS = `${DEFAULT_DOCS_BASE}/telemetry`;
+
+/** The notice where telemetry is on by default: stderr, once, before the first event. */
+export const NOTICE_DEFAULT: string = `Mostra sends anonymous usage data to improve the CLI: the command, its
+outcome, the version, the platform, which agent ran it, and a random
+install ID. Never content, paths, tokens or personal data.
+Details: ${DOCS}
+Turn it off: mostra telemetry off, or set DO_NOT_TRACK=1.
+`;
+
+/** The question in the ask-first zones, when it may be asked. */
+export const QUESTION: string = `Mostra can send anonymous usage data to improve the CLI: the command,
+its outcome, the version, the platform, which agent ran it, and a random
+install ID. Never content, paths, tokens or personal data.
+Details: ${DOCS}
+Send anonymous usage data? [y/N] `;
+
+/** The answers to the question. */
+export const ANSWER = {
+  yes: "Telemetry is on. Turn it off any time: mostra telemetry off\n",
+  no: "Telemetry stays off. Turn it on any time: mostra telemetry on\n",
+  timeout: "No answer, so telemetry stays off. Turn it on any time: mostra telemetry on\n",
+} as const;
+
+/** The notice in the ask-first zones when the question can't be asked: stderr, once. */
+export const NOTICE_ASK_FIRST: string = `Mostra can send anonymous usage data to improve the CLI: the command,
+its outcome, the version, the platform, which agent ran it, and a random
+install ID. Never content, paths, tokens or personal data.
+Details: ${DOCS}
+Nothing is sent unless you run: mostra telemetry on
+An agent should ask its user before turning it on.
+`;
+
+/** `mostra telemetry on` and `off`. */
+export const TURNED = {
+  on: "Telemetry is on. Turn it off any time: mostra telemetry off",
+  off: "Telemetry is off. Your install ID and any unsent events were deleted.",
+} as const;
+
+/** Why telemetry is on or off: the decision order's reasons (D140 item 3). */
+export type TelemetryReason =
+  | "no-collector"
+  | "embedded"
+  | "do-not-track"
+  | "variable"
+  | "variable-invalid"
+  | "setting"
+  | "default"
+  | "unreadable";
+
+/** The first line of `mostra telemetry status`. */
+export function statusLine(input: {
+  readonly enabled: boolean;
+  readonly reason: TelemetryReason;
+  readonly askFirst: boolean;
+  readonly settingsFile: string;
+}): string {
+  if (input.enabled) {
+    if (input.reason === "setting") return "Telemetry is on: you turned it on.";
+    if (input.reason === "variable") return "Telemetry is on: MOSTRA_TELEMETRY=1 is set.";
+    return "Telemetry is on by default here. Turn it off: mostra telemetry off";
+  }
+  switch (input.reason) {
+    case "setting":
+      return "Telemetry is off: you turned it off.";
+    case "do-not-track":
+      return "Telemetry is off: DO_NOT_TRACK is set.";
+    case "variable":
+      return "Telemetry is off: MOSTRA_TELEMETRY=0 is set.";
+    case "variable-invalid":
+      return "Telemetry is off: MOSTRA_TELEMETRY has a value Mostra doesn't recognize, so nothing is sent.";
+    case "embedded":
+      return "Telemetry is off: a host configures this home, and hosts never send telemetry.";
+    case "no-collector":
+      return "Telemetry is off: this build has no telemetry endpoint.";
+    case "unreadable":
+      return `Telemetry is off: ${input.settingsFile} can't be read, so nothing is sent.`;
+    case "default":
+      return "Telemetry is off until you turn it on: mostra telemetry on";
+  }
+}