@miphamai/cli 0.81.5 → 0.81.7

package/src/telemetry/crash.ts

@@ -0,0 +1,197 @@
+import { randomUUID } from 'node:crypto'
+import { PACKAGE_VERSION } from '../shared/package-info'
+import type { QueuedEvent } from './queue'
+import { hashMessage, redactStack, runtimeTag } from './redact'
+import { SCHEMA_VERSION } from './payload'
+
+/**
+ * Crash capture.
+ *
+ * Installing `uncaughtException` / `unhandledRejection` listeners is a
+ * **dangerous act**, not a bookkeeping one: once a listener exists, Node no
+ * longer applies its own default handling. The default is "print the error,
+ * exit 1". A handler that merely records the error would therefore turn every
+ * crash into a **silent hang** — the process keeps running with a broken
+ * state and no diagnostic.
+ *
+ * So the contract enforced below, and locked by tests, is:
+ *   1. write the original stack to stderr — the user must still see the crash;
+ *   2. record a redacted copy for the payload;
+ *   3. terminate with a non-zero code, so exit paths (`process.on('exit')`)
+ *      run and the session is reported as crashed.
+ *
+ * There were no such listeners anywhere in the repo before this module.
+ */
+
+export type CrashOrigin = 'uncaughtException' | 'unhandledRejection' | 'render'
+
+export interface CrashRecord {
+  errorName: string
+  messageHash: string
+  /**
+   * Redacted frames, **local to this process** — never on the wire.
+   *
+   * Until schema v2 the payload carried these; the collector discarded them on
+   * arrival (a frame string has nowhere to live in dimensional aggregates), so
+   * v2 stopped sending them. They are still redacted here rather than dropped
+   * raw: this record is what a local diagnostic reads, and the redaction
+   * guarantee must not depend on which consumer is asking.
+   */
+  stackFrames: string[]
+  frameCount: number
+  origin: CrashOrigin
+  occurredAt: string
+}
+
+/** Sinks, injected so tests can observe termination without killing the runner. */
+export interface CrashSinks {
+  writeStderr: (text: string) => void
+  exit: (code: number) => void
+}
+
+const defaultSinks: CrashSinks = {
+  writeStderr: (text) => {
+    process.stderr.write(text)
+  },
+  exit: (code) => {
+    process.exit(code)
+  },
+}
+
+let lastCrash: CrashRecord | null = null
+let installed = false
+
+/**
+ * Our own listeners, kept by reference.
+ *
+ * `resetCrashState` must remove exactly these — `removeAllListeners` would also
+ * tear out the test runner's own handlers, which is how a test seam turns into
+ * a silent loss of crash reporting everywhere else.
+ */
+let onUncaught: ((err: unknown) => void) | null = null
+let onRejection: ((reason: unknown) => void) | null = null
+
+/** Normalise anything thrown into an Error, without ever throwing itself. */
+function toError(thrown: unknown): Error {
+  if (thrown instanceof Error) return thrown
+  if (typeof thrown === 'string') return new Error(thrown)
+  try {
+    return new Error(JSON.stringify(thrown))
+  } catch {
+    return new Error(String(thrown))
+  }
+}
+
+/**
+ * Record a crash without terminating.
+ *
+ * Split out from `handleFatal` for the one caller that must survive the error:
+ * React's error boundary catches a render failure and keeps the app running, so
+ * there is nothing to terminate. Failures here are swallowed — a diagnostic
+ * must never be more fragile than the code it is diagnosing.
+ */
+export function recordCrash(thrown: unknown, origin: CrashOrigin, now: Date = new Date()): void {
+  try {
+    const error = toError(thrown)
+    const { frames, frameCount } = redactStack(error.stack ?? '')
+    lastCrash = {
+      errorName: error.name,
+      messageHash: hashMessage(error.message),
+      stackFrames: frames,
+      frameCount,
+      origin,
+      occurredAt: now.toISOString(),
+    }
+  } catch {
+    /* capture is best-effort */
+  }
+}
+
+/**
+ * Record and terminate. Exported so the test can drive it directly — a test
+ * that had to trigger a real uncaught exception would take the runner down
+ * with it.
+ */
+export function handleFatal(
+  thrown: unknown,
+  origin: CrashOrigin,
+  sinks: CrashSinks = defaultSinks,
+  now: Date = new Date(),
+): void {
+  const error = toError(thrown)
+
+  // 1. Preserve the observable default behaviour: the user sees the crash.
+  //    Written verbatim — this goes to the user's terminal, not the wire.
+  try {
+    sinks.writeStderr(`\n${error.stack ?? `${error.name}: ${error.message}`}\n`)
+  } catch {
+    /* a broken stderr must not block termination */
+  }
+
+  // 2. Record the redacted copy that may leave the machine.
+  recordCrash(error, origin, now)
+
+  // 3. Terminate. Never fall through — that is the silent-hang bug.
+  sinks.exit(1)
+}
+
+/**
+ * Install the listeners once. Idempotent: a second call is a no-op, so a
+ * double `initTelemetry()` cannot stack two handlers that each call `exit`.
+ */
+export function installCrashHandlers(sinks: CrashSinks = defaultSinks): void {
+  if (installed) return
+  installed = true
+
+  onUncaught = (err: unknown) => handleFatal(err, 'uncaughtException', sinks)
+  onRejection = (reason: unknown) => handleFatal(reason, 'unhandledRejection', sinks)
+
+  process.on('uncaughtException', onUncaught)
+  process.on('unhandledRejection', onRejection)
+}
+
+/** Whether this session crashed — reported in the session payload. */
+export function hasCrashed(): boolean {
+  return lastCrash !== null
+}
+
+export function getLastCrash(): CrashRecord | null {
+  return lastCrash
+}
+
+/** Test seam: clear recorded state and allow re-installation. */
+export function resetCrashState(): void {
+  lastCrash = null
+  installed = false
+  if (onUncaught) process.off('uncaughtException', onUncaught)
+  if (onRejection) process.off('unhandledRejection', onRejection)
+  onUncaught = null
+  onRejection = null
+}
+
+/**
+ * The `crash` event. Holds a message *digest*, never the message text: error
+ * messages routinely embed paths and user data.
+ *
+ * No `stackFrames` since schema v2 — see `SCHEMA_VERSION` in `payload.ts` and
+ * the `stackFrames` note on `CrashRecord`.
+ */
+export function buildCrashEvent(installId: string): QueuedEvent | null {
+  if (!lastCrash) return null
+  return {
+    id: randomUUID(),
+    kind: 'crash',
+    payload: {
+      installId,
+      schemaVersion: SCHEMA_VERSION,
+      occurredAt: lastCrash.occurredAt,
+      appVersion: PACKAGE_VERSION,
+      runtime: runtimeTag(),
+      platform: `${process.platform}/${process.arch}`,
+      errorName: lastCrash.errorName,
+      messageHash: lastCrash.messageHash,
+      frameCount: lastCrash.frameCount,
+      origin: lastCrash.origin,
+    },
+  }
+}

package/src/telemetry/endpoint.ts

@@ -0,0 +1,82 @@
+/**
+ * Where telemetry is sent.
+ *
+ * This module is the source of truth for the *destination contract*: the path
+ * below has to match the `location =` block in
+ * `apps/telemetry/deploy/nginx/log.onemipham.com.conf`. A drift between the two
+ * is not a loud failure — every event gets a 404, the client treats 4xx as
+ * "permanently unacceptable" and deletes it, and telemetry quietly becomes a
+ * no-op for everyone. `apps/cli/test/integrity/telemetry-contract.test.ts` is
+ * the mechanical defence against that, which is why the constant lives in a
+ * module of its own: the test needs to import exactly one file.
+ */
+
+/**
+ * The hosted receiver. Public, write-only, unauthenticated: the CLI cannot hold
+ * a secret (it ships to npm as Apache-2.0 source), so this address is designed
+ * to be useless to anyone who finds it — aggregate dimensions only, no readback.
+ */
+export const OFFICIAL_TELEMETRY_ENDPOINT = 'https://log.onemipham.com/v1/events'
+
+/**
+ * Opt in *and* send nowhere.
+ *
+ * Without this there is no way to express that state. Resolution is
+ * `env || user || default` and an empty string is falsy, so `endpoint: ""`
+ * falls *through* to the next tier instead of clearing the destination. Before
+ * T1b the default was empty and the two were indistinguishable; now the default
+ * is a real URL, so an empty override would silently start sending. `none`
+ * keeps the capability: self-hosted installs and internal-network audits that
+ * want telemetry recorded locally but nothing leaving the machine.
+ *
+ * Exact match only, the same rule as `MIPHAM_TELEMETRY=off`.
+ */
+export const NO_ENDPOINT = 'none'
+
+/**
+ * Which tier supplied the destination.
+ *
+ * `off` is not in this union: it is not a destination that was resolved at all,
+ * it is the hard kill switch firing before resolution. `TelemetryConsent`
+ * widens the type for that case.
+ */
+export type EndpointSource = 'env' | 'user' | 'default'
+
+export interface ResolvedEndpoint {
+  /** Destination. Empty means nothing is ever sent. */
+  endpoint: string
+  source: EndpointSource
+}
+
+/**
+ * Resolve the destination, first match wins:
+ *
+ *   1. `MIPHAM_TELEMETRY_ENDPOINT`
+ *   2. user `settings.json` → `telemetry.endpoint`
+ *   3. {@link OFFICIAL_TELEMETRY_ENDPOINT}
+ *
+ * {@link NO_ENDPOINT} at any winning tier resolves to an empty destination, and
+ * still reports the tier that supplied it — "which tier decided" and "did it
+ * decide to send" are separate questions, and `/telemetry status` answers both.
+ */
+export function resolveEndpoint(
+  userEndpoint: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedEndpoint {
+  const fromEnv = env.MIPHAM_TELEMETRY_ENDPOINT
+  const raw = fromEnv || userEndpoint || OFFICIAL_TELEMETRY_ENDPOINT
+  return {
+    endpoint: raw === NO_ENDPOINT ? '' : raw,
+    source: fromEnv ? 'env' : userEndpoint ? 'user' : 'default',
+  }
+}
+
+/**
+ * Host of the official receiver, for user-facing copy.
+ *
+ * Derived rather than retyped: the first-run prompt names the destination, and
+ * a hard-coded second copy of it would keep naming the old host after a move.
+ */
+export function officialEndpointHost(): string {
+  return new URL(OFFICIAL_TELEMETRY_ENDPOINT).host
+}

package/src/telemetry/index.ts

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto'
+import { getMetrics } from '../core/metrics'
+import { resolveTelemetry, getOrCreateInstallId, type TelemetryConsent } from './consent'
+import { enqueueSync } from './queue'
+import { buildSessionEvent } from './payload'
+import { buildCrashEvent, hasCrashed, installCrashHandlers } from './crash'
+import { flushQueueInBackground } from './transport'
+
+/**
+ * Telemetry facade.
+ *
+ * Data flow — collecting and sending are deliberately decoupled, because
+ * `process.on('exit')` cannot await async work:
+ *
+ *   during a session   counters accumulate in memory (`getMetrics()`); zero I/O
+ *   at exit            synchronous: whitelist snapshot + session metadata → queue
+ *   next startup       async, fire-and-forget: drain queue → POST → ack or keep
+ *
+ * Nothing here is a parallel counting system. `getMetrics()` already exists and
+ * is the single source for what actually got used; telemetry only *reads* it,
+ * and only for the whitelisted families (`payload.ts`).
+ */
+
+interface TelemetryState {
+  consent: TelemetryConsent
+  installId: string
+  startedAt: number
+  /** Guards against a double flush when both SIGINT and a normal exit fire. */
+  flushed: boolean
+}
+
+let state: TelemetryState | null = null
+
+/**
+ * The exit flush, kept by reference so `resetTelemetryState` can remove
+ * exactly this one — `removeAllListeners('exit')` would detach the runner's
+ * own teardown and every other exit path in the process.
+ */
+let onExit: (() => void) | null = null
+
+/**
+ * Start telemetry for this process.
+ *
+ * Safe to call once at startup. Returns the resolved consent so callers (and
+ * `/telemetry status`) can report why telemetry is on or off.
+ */
+export function initTelemetry(cwd: string = process.cwd()): TelemetryConsent {
+  const consent = resolveTelemetry(cwd)
+  const installId = consent.enabled ? getOrCreateInstallId(cwd) : ''
+
+  state = { consent, installId, startedAt: Date.now(), flushed: false }
+
+  // Crash capture is installed unconditionally, even when telemetry is off:
+  // it is what keeps a crash from becoming a silent hang. When telemetry is
+  // off the record is simply never uploaded.
+  installCrashHandlers()
+
+  // Likewise unconditional. The flush has to be registered while telemetry is
+  // still off, because the user can turn it on mid-session (`/telemetry on` →
+  // `enableTelemetryNow`) and that session must still be reported. Registering
+  // it here rather than in the TUI's own `process.on('exit')` also means the
+  // remote-attach and non-interactive paths are covered, not just the one that
+  // reaches the TUI setup.
+  if (!onExit) {
+    onExit = () => shutdownTelemetry()
+    process.on('exit', onExit)
+  }
+
+  if (consent.enabled) flushQueueInBackground(consent.endpoint)
+
+  return consent
+}
+
+/**
+ * Record a slash-command invocation.
+ *
+ * Unconditional, like every other counter in the registry — `getMetrics()` is
+ * a metrics registry used by the artifact server too, not a telemetry buffer.
+ * Whether the snapshot ever leaves the machine is decided at exit.
+ */
+export function recordCommand(name: string): void {
+  getMetrics().commandCalls.inc({ command_name: name })
+}
+
+/** Record a tool invocation that bypassed the engine's `executeTool` funnel. */
+export function recordToolCall(name: string): void {
+  getMetrics().toolCalls.inc({ tool_name: name })
+}
+
+export function isTelemetryEnabled(): boolean {
+  return state?.consent.enabled === true
+}
+
+export function getTelemetryConsent(): TelemetryConsent | null {
+  return state?.consent ?? null
+}
+
+/**
+ * Form and queue the session payload. **Synchronous by requirement** — this is
+ * called from inside `process.on('exit')`, where an await would never settle.
+ *
+ * A no-op when telemetry is off, which is what makes "off" mean no collection,
+ * no queue file, and no network.
+ */
+export function shutdownTelemetry(now: Date = new Date()): void {
+  const current = state
+  if (!current || current.flushed) return
+  current.flushed = true
+  if (!current.consent.enabled) return
+
+  try {
+    if (hasCrashed()) {
+      const crash = buildCrashEvent(current.installId)
+      if (crash) enqueueSync(crash)
+    }
+    enqueueSync(
+      buildSessionEvent({
+        installId: current.installId,
+        startedAt: current.startedAt,
+        endedAt: now.getTime(),
+        crashed: hasCrashed(),
+      }),
+    )
+  } catch {
+    // A telemetry write must never break the exit path.
+  }
+}
+
+/** Test seam: drop facade state and unhook the exit flush. */
+export function resetTelemetryState(): void {
+  state = null
+  if (onExit) process.off('exit', onExit)
+  onExit = null
+}
+
+/**
+ * Persist the user's answer and start reporting immediately, so `/telemetry on`
+ * takes effect in the running session rather than at the next launch.
+ */
+export function enableTelemetryNow(cwd: string = process.cwd()): void {
+  const consent = resolveTelemetry(cwd)
+  state = {
+    consent,
+    installId: getOrCreateInstallId(cwd),
+    startedAt: state?.startedAt ?? Date.now(),
+    flushed: false,
+  }
+}
+
+/** A fresh anonymous id, for `/telemetry reset-id`. */
+export function newInstallId(): string {
+  return randomUUID()
+}

package/src/telemetry/payload.ts

@@ -0,0 +1,141 @@
+import { randomUUID } from 'node:crypto'
+import { getMetrics } from '../core/metrics'
+import { PACKAGE_VERSION } from '../shared/package-info'
+import type { QueuedEvent } from './queue'
+import { runtimeTag } from './redact'
+
+/**
+ * Payload construction.
+ *
+ * The counters are a **whitelist, not a whole-registry dump**. A dump would
+ * silently enrol every future counter into the uploaded payload, and a future
+ * counter's labels may well carry PII. A whitelist is explicit, can be written
+ * into the public data dictionary, and can be locked down by a test asserting
+ * the emitted key set is a subset of it.
+ *
+ * See `docs/telemetry.md` for the public data dictionary.
+ */
+
+/**
+ * Bumped whenever the payload shape changes, so the endpoint can evolve.
+ *
+ * v2 (this version) = the crash event no longer carries `stackFrames`.
+ * The collector never kept them — "dimensional aggregates only" leaves a frame
+ * string nowhere to live — so sending them bought ~3 KB per crash of transfer
+ * and a privacy surface in exchange for nothing. The frame *count* stays: it is
+ * what keeps "this stack was short" distinguishable from "this stack was cut",
+ * and it is a single integer.
+ *
+ * The ordering was not optional: the collector had to accept v1 **before** any
+ * client stopped sending frames. Checked in `apps/telemetry/src/schema.ts`,
+ * which lists both versions.
+ */
+export const SCHEMA_VERSION = 2
+
+/**
+ * Counter family names cleared for upload, as they appear in the registry.
+ * Adding to this list is a privacy decision — it must be matched by a
+ * data-dictionary entry in the same commit.
+ */
+export const COUNTER_WHITELIST = [
+  'mipham_code_cli_invocations_total',
+  'mipham_code_command_calls_total',
+  'mipham_code_tool_calls_total',
+  'mipham_code_crsi_rule_applications_total',
+  'mipham_code_sis_interceptions_total',
+] as const
+
+/** Maximum length of a label value kept in the payload. */
+const MAX_LABEL_LENGTH = 64
+
+/** `Counter.toJSON()` reports `object`; this is the shape it actually returns. */
+interface CounterJson {
+  name: string
+  series: { labels: string; value: number }[]
+}
+
+/**
+ * Pull the first `="…"` value out of the registry's formatted label string
+ * (e.g. `{tool_name="Bash"}` → `Bash`). Whitelisted families carry at most one
+ * label, so first-value is the whole story.
+ */
+function firstLabelValue(labels: string): string {
+  const match = /="((?:[^"\\]|\\.)*)"/.exec(labels)
+  if (!match || match[1] === undefined) return ''
+  return match[1]
+    .replace(/\\(.)/g, '$1')
+    .replace(/[^\x20-\x7e]/g, '')
+    .slice(0, MAX_LABEL_LENGTH)
+}
+
+/**
+ * Snapshot the whitelisted counters into a flat `Record<string, number>`.
+ *
+ * Keys are the family name with the `mipham_code_` prefix and `_total` suffix
+ * stripped, plus the label value when there is one:
+ *   `mipham_code_cli_invocations_total`              → `cli_invocations`
+ *   `mipham_code_tool_calls_total{tool_name="Bash"}` → `tool_calls.Bash`
+ *
+ * Label cardinality: `tool_name` is closed by construction — there are only as
+ * many tool names as the registry declares. `command_name` is **not**: it comes
+ * from user input, so the caller is responsible for collapsing unrecognised
+ * names (see `commandLabelFor` in `ui/commands.ts`). `MAX_LABEL_LENGTH` below
+ * truncates a value, it does not bound how many keys there are.
+ */
+export function snapshotCounters(): Record<string, number> {
+  const metrics = getMetrics()
+  const { counters } = metrics.toJSON() as { counters: CounterJson[] }
+  const out: Record<string, number> = {}
+
+  for (const counter of counters) {
+    const family = counter.name
+    if (!(COUNTER_WHITELIST as readonly string[]).includes(family)) continue
+
+    const short = family.replace(/^mipham_code_/, '').replace(/_total$/, '')
+
+    for (const series of counter.series) {
+      const value = firstLabelValue(series.labels)
+      const key = value ? `${short}.${value}` : short
+      out[key] = (out[key] ?? 0) + series.value
+    }
+  }
+
+  return out
+}
+
+/** `darwin/arm64`, `linux/x64`, … — coarse platform identity, no hostname. */
+function platformTag(): string {
+  return `${process.platform}/${process.arch}`
+}
+
+export interface SessionMeta {
+  installId: string
+  startedAt: number
+  endedAt: number
+  crashed: boolean
+}
+
+/**
+ * The `session` event: one per CLI launch, formed at exit.
+ *
+ * Contains counters and coarse environment facts only. It never carries
+ * conversation content, prompts, file contents, paths, user names, hostnames,
+ * API keys, or environment variable values.
+ */
+export function buildSessionEvent(meta: SessionMeta, now: Date = new Date()): QueuedEvent {
+  return {
+    id: randomUUID(),
+    kind: 'session',
+    payload: {
+      installId: meta.installId,
+      schemaVersion: SCHEMA_VERSION,
+      occurredAt: now.toISOString(),
+      appVersion: PACKAGE_VERSION,
+      runtime: runtimeTag(),
+      platform: platformTag(),
+      sessionDurationMs: Math.max(0, meta.endedAt - meta.startedAt),
+      crashed: meta.crashed,
+      counters: snapshotCounters(),
+    },
+  }
+}

package/src/telemetry/queue.ts

@@ -0,0 +1,95 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { atomicWriteFileSync } from '../shared/atomic-write'
+import { telemetryDir } from './consent'
+
+/**
+ * Local queue of telemetry events awaiting upload.
+ *
+ * Every operation here is **synchronous**, and that is a requirement, not a
+ * convenience: the session payload is written from inside
+ * `process.on('exit')`, which cannot await async work. Every other exit-path
+ * write in the repo is synchronous for the same reason (`persistSession` in
+ * `index.tsx`, `EffectivenessTracker.persist()`).
+ *
+ * Sending is therefore decoupled from collecting: events are queued at exit and
+ * uploaded on the *next* startup, where async is allowed.
+ */
+
+/** Entries kept before the oldest are dropped. Bounds disk use on a machine that can never reach an endpoint. */
+export const QUEUE_MAX_ENTRIES = 100
+
+export interface QueuedEvent {
+  /** Stable per-event id, used to acknowledge a successful upload. */
+  id: string
+  kind: 'session' | 'crash'
+  payload: Record<string, unknown>
+}
+
+export function queuePath(): string {
+  return join(telemetryDir(), 'queue.jsonl')
+}
+
+/**
+ * Read the queue. A missing file is an empty queue; an unparsable *line* is
+ * skipped rather than thrown, so one truncated write can never wedge every
+ * future session.
+ */
+export function readQueue(): QueuedEvent[] {
+  const path = queuePath()
+  if (!existsSync(path)) return []
+
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf-8')
+  } catch {
+    return []
+  }
+
+  const events: QueuedEvent[] = []
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    try {
+      const parsed = JSON.parse(trimmed) as QueuedEvent
+      if (parsed && typeof parsed === 'object' && typeof parsed.id === 'string') events.push(parsed)
+    } catch {
+      /* skip the damaged line, keep the rest */
+    }
+  }
+  return events
+}
+
+/**
+ * Replace the queue wholesale, atomically.
+ *
+ * Capacity is enforced by dropping the *oldest* entries — the newest events
+ * describe the current version, which is the version worth hearing about.
+ * Silent: a queue write must never surface as a user-visible error, and must
+ * never take down an exit path.
+ */
+export function writeQueue(events: QueuedEvent[]): void {
+  try {
+    const kept = events.length > QUEUE_MAX_ENTRIES ? events.slice(-QUEUE_MAX_ENTRIES) : events
+    const body = kept.map((e) => JSON.stringify(e)).join('\n')
+    // atomicWriteFileSync does not create parents (same as the settings writer,
+    // which mkdirs first) — without this the queue silently never materialises
+    // on a fresh machine, where ~/.mipham/telemetry/ does not exist yet.
+    mkdirSync(telemetryDir(), { recursive: true })
+    atomicWriteFileSync(queuePath(), body.length > 0 ? body + '\n' : '', { mode: 0o600 })
+  } catch {
+    /* best-effort by design */
+  }
+}
+
+/** Append one event, dropping the oldest if the queue is at capacity. */
+export function enqueueSync(event: QueuedEvent): void {
+  writeQueue([...readQueue(), event])
+}
+
+/** Drop events whose ids are no longer wanted (i.e. they uploaded successfully). */
+export function ackQueue(ids: Iterable<string>): void {
+  const done = new Set(ids)
+  if (done.size === 0) return
+  writeQueue(readQueue().filter((e) => !done.has(e.id)))
+}