rnxsim 0.1.313 → 0.1.314

package/cli/run-registry.ts

@@ -0,0 +1,226 @@
+// shared test-run registration for both runners (Maestro / Detox). posts a
+// `sootRun` row to /api/sootsim/test-runs so the org
+// dashboard and PR comments get a pass/fail list with git provenance and a
+// link into the hosted replay (the uploaded preview share).
+//
+// registration policy: a run registers when it produced a hosted share
+// (--preview) or when it runs in CI (github-token / actions env) — local
+// iteration without --preview stays local. registration failures warn and
+// never change the run's exit code; the test result is the playback result.
+
+import { execSync } from 'child_process'
+import { authHeaderValue, resolveCliAuth, type CliAuth } from './auth'
+import type { SootSimFlowTraceStep } from './bridge-flow-runner'
+
+export type RunKind = 'maestro' | 'detox'
+
+export type RunProvenance = {
+  owner: string | null
+  repo: string | null
+  branch: string | null
+  commitSha: string | null
+  githubUsername: string | null
+  pullRequestNumber: number | null
+  pullRequestTitle: string | null
+  githubRunId: string | null
+  source: 'cli' | 'ci'
+}
+
+function gitOutput(command: string): string | null {
+  try {
+    const out = execSync(command, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 3000,
+      encoding: 'utf8',
+    }).trim()
+    return out || null
+  } catch {
+    return null
+  }
+}
+
+function parsePositiveInt(value: string | undefined): number | null {
+  const trimmed = value?.trim()
+  if (!trimmed || !/^\d+$/.test(trimmed)) return null
+  return Number(trimmed)
+}
+
+// owner/repo from the checkout's github remote, for local runs with no
+// CONTRAST_REPO/GITHUB_REPOSITORY env. runs are repo-scoped on the dashboard
+// (/org/<owner>/<repo>/runs), so a repo-less registration has no home — the
+// server 400s it. handles ssh (git@github.com:o/r.git) and https
+// (https://github.com/o/r(.git)) remote shapes.
+function ownerRepoFromGitRemote(): { owner: string; repo: string } | null {
+  const url = gitOutput('git remote get-url origin')
+  if (!url) return null
+  const match = url.match(/github\.com[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i)
+  if (!match) return null
+  return { owner: match[1], repo: match[2] }
+}
+
+// git provenance for the current run. in GitHub Actions the CONTRAST_*/GITHUB_*
+// env is authoritative (the checkout can be a detached merge ref); locally
+// we ask git itself.
+export function resolveRunProvenance(): RunProvenance {
+  const isActions = process.env.GITHUB_ACTIONS === 'true'
+  const contrastBranch = process.env.CONTRAST_BRANCH?.trim() || null
+  const contrastSha = process.env.CONTRAST_SHA?.trim() || null
+  const pullRequestTitle = process.env.CONTRAST_PR_TITLE?.trim() || null
+  const repoSlug = (
+    process.env.CONTRAST_REPO ||
+    process.env.GITHUB_REPOSITORY ||
+    ''
+  ).trim()
+  const [envOwner, envRepo] = repoSlug.includes('/')
+    ? repoSlug.split('/', 2)
+    : [null, null]
+
+  if (isActions) {
+    // pull_request events: GITHUB_HEAD_REF is the PR head branch and
+    // GITHUB_REF looks like refs/pull/<n>/merge. push events: GITHUB_REF_NAME.
+    const prFromRef = process.env.GITHUB_REF?.match(/^refs\/pull\/(\d+)\//)?.[1]
+    return {
+      owner: envOwner,
+      repo: envRepo,
+      branch:
+        contrastBranch ||
+        process.env.GITHUB_HEAD_REF?.trim() ||
+        process.env.GITHUB_REF_NAME?.trim() ||
+        null,
+      commitSha: contrastSha || process.env.GITHUB_SHA?.trim() || null,
+      githubUsername: process.env.GITHUB_ACTOR?.trim() || null,
+      pullRequestNumber:
+        parsePositiveInt(process.env.CONTRAST_PR_NUMBER) ?? parsePositiveInt(prFromRef),
+      pullRequestTitle,
+      githubRunId: process.env.GITHUB_RUN_ID?.trim() || null,
+      source: 'ci',
+    }
+  }
+
+  const branch = contrastBranch ?? gitOutput('git rev-parse --abbrev-ref HEAD')
+  // env slug wins when present; otherwise infer from the github remote so a
+  // a plain local `sootsim maestro test --preview` still lands on its repo's dashboard.
+  const remote = envOwner ? null : ownerRepoFromGitRemote()
+  return {
+    owner: envOwner ?? remote?.owner ?? null,
+    repo: envRepo ?? remote?.repo ?? null,
+    branch: branch === 'HEAD' ? null : branch,
+    commitSha: contrastSha ?? gitOutput('git rev-parse HEAD'),
+    githubUsername: null,
+    pullRequestNumber: parsePositiveInt(process.env.CONTRAST_PR_NUMBER),
+    pullRequestTitle,
+    githubRunId: null,
+    source: 'cli',
+  }
+}
+
+export function stepSummaryFromTrace(steps: SootSimFlowTraceStep[]): {
+  stepCount: number | null
+  failedStepIndex: number | null
+} {
+  if (steps.length === 0) return { stepCount: null, failedStepIndex: null }
+  const failed = steps.find((step) => step.status === 'failure')
+  return {
+    stepCount: steps.length,
+    failedStepIndex: failed ? failed.stepIndex : null,
+  }
+}
+
+// whether this run should register at all — see the policy note at the top.
+export function shouldRegisterRun(args: {
+  uploadedShare: boolean
+  auth: CliAuth | null
+}): boolean {
+  if (!args.auth) return false
+  if (args.uploadedShare) return true
+  return args.auth.kind === 'github' || process.env.GITHUB_ACTIONS === 'true'
+}
+
+export type RegisterRunArgs = {
+  origin: string
+  kind: RunKind
+  status: 'passed' | 'failed'
+  name?: string | null
+  prompt?: string | null
+  summary?: string | null
+  failureMessage?: string | null
+  previewShareId?: string | null
+  // explicit --owner/--repo flags override env/git detection
+  owner?: string | null
+  repo?: string | null
+  durationMs?: number | null
+  flowYamlSizeBytes?: number | null
+  stepCount?: number | null
+  failedStepIndex?: number | null
+  auth?: CliAuth | null
+}
+
+export type RegisteredRun = {
+  id: string
+  previewUrl: string | null
+  traceUrl: string | null
+}
+
+export async function registerRun(args: RegisterRunArgs): Promise<RegisteredRun | null> {
+  const auth = args.auth ?? resolveCliAuth()
+  if (!auth) return null
+  const provenance = resolveRunProvenance()
+  const owner =
+    args.owner ?? (auth.kind === 'github' ? auth.owner : null) ?? provenance.owner
+  const repo = args.repo ?? (auth.kind === 'github' ? auth.repo : null) ?? provenance.repo
+
+  try {
+    const res = await fetch(`${args.origin.replace(/\/$/, '')}/api/sootsim/test-runs`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: authHeaderValue(auth),
+      },
+      body: JSON.stringify({
+        kind: args.kind,
+        source: provenance.source,
+        name: args.name ?? undefined,
+        prompt: args.prompt ?? undefined,
+        summary: args.summary ?? undefined,
+        status: args.status,
+        failureMessage: args.failureMessage ?? undefined,
+        previewShareId: args.previewShareId ?? undefined,
+        owner: owner ?? undefined,
+        repo: repo ?? undefined,
+        branch: provenance.branch ?? undefined,
+        commitSha: provenance.commitSha ?? undefined,
+        githubUsername: provenance.githubUsername ?? undefined,
+        pullRequestNumber: provenance.pullRequestNumber ?? undefined,
+        githubRunId: provenance.githubRunId ?? undefined,
+        stepCount: args.stepCount ?? undefined,
+        failedStepIndex: args.failedStepIndex ?? undefined,
+        durationMs: args.durationMs ?? undefined,
+        flowYamlSizeBytes: args.flowYamlSizeBytes ?? undefined,
+      }),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      console.warn(
+        `  warn: run registration failed: /api/sootsim/test-runs ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`,
+      )
+      return null
+    }
+    const body = (await res.json()) as {
+      run?: { id?: string; traceUrl?: string | null; previewUrl?: string | null }
+    }
+    if (!body.run?.id) {
+      console.warn('  warn: run registration returned no id')
+      return null
+    }
+    return {
+      id: body.run.id,
+      previewUrl: body.run.previewUrl ?? null,
+      traceUrl: body.run.traceUrl ?? null,
+    }
+  } catch (err) {
+    console.warn(
+      `  warn: run registration failed: ${err instanceof Error ? err.message : String(err)}`,
+    )
+    return null
+  }
+}

package/cli/runtime-notes.ts

@@ -0,0 +1,66 @@
+import { SOOTSIM_CHANGELOG_API_URL, SOOTSIM_CHANGELOG_URL } from '../src/runtime-delivery'
+import type { ChangelogEntry } from '../../../scripts/changelog/types'
+
+function isChangelogEntry(value: unknown): value is ChangelogEntry {
+  if (!value || typeof value !== 'object') return false
+  const sections = Reflect.get(value, 'sections')
+  return (
+    typeof Reflect.get(value, 'title') === 'string' &&
+    Array.isArray(sections) &&
+    sections.every(
+      (section) =>
+        section &&
+        typeof section === 'object' &&
+        typeof Reflect.get(section, 'title') === 'string' &&
+        Array.isArray(Reflect.get(section, 'items')) &&
+        Reflect.get(section, 'items').every(
+          (item: unknown) =>
+            item &&
+            typeof item === 'object' &&
+            typeof Reflect.get(item, 'summary') === 'string' &&
+            typeof Reflect.get(item, 'hash') === 'string',
+        ),
+    )
+  )
+}
+
+export async function fetchRuntimeReleaseNotes(
+  version: string,
+  request: typeof fetch = fetch,
+): Promise<ChangelogEntry | null> {
+  try {
+    const url = new URL(SOOTSIM_CHANGELOG_API_URL)
+    url.searchParams.set('version', version)
+    const response = await request(url, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(5000),
+    })
+    if (!response.ok) return null
+    const payload: unknown = await response.json()
+    if (!payload || typeof payload !== 'object') return null
+    const entries = Reflect.get(payload, 'entries')
+    if (!Array.isArray(entries) || !isChangelogEntry(entries[0])) return null
+    return entries[0]
+  } catch {
+    return null
+  }
+}
+
+export function formatRuntimeReleaseNotes(
+  version: string,
+  entry: ChangelogEntry | null,
+): string {
+  const lines = [`what's new in rnx engine v${version}:`]
+  if (!entry || entry.sections.length === 0) {
+    lines.push(`  release notes are not available yet`)
+  } else {
+    for (const section of entry.sections) {
+      lines.push(`  ${section.title}:`)
+      for (const item of section.items) {
+        lines.push(`    • ${item.summary}`)
+      }
+    }
+  }
+  lines.push(`  full changelog: ${SOOTSIM_CHANGELOG_URL}`)
+  return lines.join('\n')
+}

package/cli/runtime-summary.ts

@@ -0,0 +1,25 @@
+import { readActiveRuntime, shouldSkipPersistentDaemon } from '../src/home-paths'
+import { resolveBridgeWorld } from './ws-bridge'
+
+export type RuntimeSummary = {
+  primary: string
+  installedRuntime: string | null
+  isDevBridge: boolean
+}
+
+export function getRuntimeSummary(): RuntimeSummary {
+  const active = readActiveRuntime()
+  const dev = shouldSkipPersistentDaemon() ? resolveBridgeWorld() : null
+  if (dev?.source === 'dev-bridge') {
+    return {
+      primary: `engine dev source (:${dev.bridgePort})`,
+      installedRuntime: active ? `installed runtime v${active}` : null,
+      isDevBridge: true,
+    }
+  }
+  return {
+    primary: active ? `runtime v${active}` : 'runtime not installed',
+    installedRuntime: null,
+    isDevBridge: false,
+  }
+}

package/cli/setup-repository.ts

@@ -0,0 +1,187 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { rnxPublicBrand } from '../src/public-brand'
+
+export type SetupPackageManager = 'bun' | 'pnpm' | 'npm'
+
+export interface RepositoryOperation {
+  command: string
+  args: string[]
+  description: string
+}
+
+export interface RepositorySetupPlan {
+  appDir: string
+  packageManager: SetupPackageManager
+  operations: RepositoryOperation[]
+}
+
+interface PackageManifest {
+  scripts?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+export function findPackageRoot(startDir: string): string | null {
+  let current = path.resolve(startDir)
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json'))) return current
+    const parent = path.dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+export function detectPreferredPackageManager(startDir: string): SetupPackageManager {
+  let current = path.resolve(startDir)
+  while (true) {
+    if (fs.existsSync(path.join(current, 'bun.lock'))) return 'bun'
+    if (fs.existsSync(path.join(current, 'bun.lockb'))) return 'bun'
+    if (fs.existsSync(path.join(current, 'pnpm-lock.yaml'))) return 'pnpm'
+    if (fs.existsSync(path.join(current, 'package-lock.json'))) return 'npm'
+    const parent = path.dirname(current)
+    if (parent === current) return 'npm'
+    current = parent
+  }
+}
+
+export function planRepositorySetup(input: {
+  appDir: string
+  cliVersion: string
+}): RepositorySetupPlan {
+  const appDir = path.resolve(input.appDir)
+  const manifest = readManifest(path.join(appDir, 'package.json'))
+  const expectedScript = `${rnxPublicBrand.commandName} open`
+  const existingScript = manifest.scripts?.[rnxPublicBrand.commandName]
+  if (existingScript && existingScript !== expectedScript) {
+    throw new Error(
+      `package.json already defines scripts.${rnxPublicBrand.commandName} as ${JSON.stringify(existingScript)}; resolve that conflict before setup`,
+    )
+  }
+
+  const packageManager = detectPreferredPackageManager(appDir)
+  const operations: RepositoryOperation[] = []
+  if (manifest.devDependencies?.[rnxPublicBrand.packageName] !== input.cliVersion) {
+    operations.push(addDependencyOperation(packageManager, input.cliVersion))
+  }
+  if (existingScript !== expectedScript) {
+    operations.push(scriptOperation(packageManager))
+  }
+  return {
+    appDir,
+    packageManager,
+    operations,
+  }
+}
+
+export async function applyRepositorySetup(
+  plan: RepositorySetupPlan,
+  options: { dryRun: boolean; json: boolean },
+): Promise<void> {
+  for (const operation of plan.operations) {
+    if (options.dryRun) continue
+    await runOperation(operation, plan.appDir, options.json)
+  }
+}
+
+export function formatRepositoryOperations(plan: RepositorySetupPlan): string[] {
+  return plan.operations.map(
+    (operation) => `${operation.command} ${operation.args.map(quoteArg).join(' ')}`,
+  )
+}
+
+function readManifest(packagePath: string): PackageManifest {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(fs.readFileSync(packagePath, 'utf8'))
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`could not read ${packagePath}: ${message}`)
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${packagePath} must contain a JSON object`)
+  }
+  const scripts = readStringRecord(Reflect.get(parsed, 'scripts'))
+  const devDependencies = readStringRecord(Reflect.get(parsed, 'devDependencies'))
+  return {
+    ...(scripts ? { scripts } : {}),
+    ...(devDependencies ? { devDependencies } : {}),
+  }
+}
+
+function readStringRecord(value: unknown): Record<string, string> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const entries = Object.entries(value).filter(
+    (entry): entry is [string, string] => typeof entry[1] === 'string',
+  )
+  return Object.fromEntries(entries)
+}
+
+function addDependencyOperation(
+  packageManager: SetupPackageManager,
+  version: string,
+): RepositoryOperation {
+  const spec = `${rnxPublicBrand.packageName}@${version}`
+  switch (packageManager) {
+    case 'bun':
+      return {
+        command: 'bun',
+        args: ['add', '--dev', '--exact', spec],
+        description: `install ${spec} as an exact dev dependency`,
+      }
+    case 'pnpm':
+      return {
+        command: 'pnpm',
+        args: ['add', '--save-dev', '--save-exact', spec],
+        description: `install ${spec} as an exact dev dependency`,
+      }
+    case 'npm':
+      return {
+        command: 'npm',
+        args: ['install', '--save-dev', '--save-exact', spec],
+        description: `install ${spec} as an exact dev dependency`,
+      }
+  }
+}
+
+function quoteArg(value: string): string {
+  return /^[a-zA-Z0-9_./@=-]+$/.test(value) ? value : JSON.stringify(value)
+}
+
+function runOperation(
+  operation: RepositoryOperation,
+  cwd: string,
+  json: boolean,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(operation.command, operation.args, {
+      cwd,
+      stdio: json ? ['ignore', 2, 'inherit'] : 'inherit',
+    })
+    child.once('error', reject)
+    child.once('exit', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`${operation.command} exited with code ${code ?? 'unknown'}`))
+    })
+  })
+}
+
+function scriptOperation(packageManager: SetupPackageManager): RepositoryOperation {
+  return {
+    command: packageManager,
+    args:
+      packageManager === 'bun'
+        ? [
+            'pm',
+            'pkg',
+            'set',
+            `scripts.${rnxPublicBrand.commandName}=${rnxPublicBrand.commandName} open`,
+          ]
+        : [
+            'pkg',
+            'set',
+            `scripts.${rnxPublicBrand.commandName}=${rnxPublicBrand.commandName} open`,
+          ],
+    description: `add the \`${rnxPublicBrand.commandName}\` package script`,
+  }
+}

package/cli/telemetry.ts

@@ -0,0 +1,187 @@
+// cli-side telemetry. fire-and-forget posthog events tagged with
+// source='cli' plus whatever identity is available from the local shared
+// desktop auth session.
+//
+// this file is intentionally self-contained — no imports from Contrast `src/`
+// or other in-monorepo packages — so the sootsim npm package stays small
+// and doesn't drag app code into the distributed cli.
+//
+// scope: only emit at cli boundaries that matter for product metering
+// (e.g. upload command start/completion). authoritative metering for
+// uploads lives on the server; the cli event is there so we can observe
+// cli invocation volume even when the request never reaches the server.
+
+import { isValidTeamMachineSessionId } from '../src/agent-identity'
+import { readSharedDesktopAuthSession } from '../src/auth/shared-session'
+import { readOrCreateAnonymousId, readPrivacyPreferences } from '../src/home-paths'
+
+type Plan = 'free' | 'pro' | 'enterprise'
+type Source = 'cli' | 'browser' | 'electron' | 'github-app' | 'server'
+
+type Identity = {
+  userId?: string | null
+  repoId?: string | null
+  installationId?: string | number | null
+  shareId?: string | null
+  plan?: Plan | null
+  source?: Source
+}
+
+export type CliTelemetryEvent = {
+  event: string
+  identity?: Identity
+  properties?: Record<string, unknown>
+}
+
+type Config = { apiKey: string; host: string }
+
+function isOptedOut(): boolean {
+  // standard cross-tool opt-out signal. honored by npm, homebrew, supabase,
+  // turbo, etc. — set DO_NOT_TRACK=1 to silence telemetry across the board.
+  const v = process.env.DO_NOT_TRACK
+  if (v === '1' || v === 'true') return true
+  // shared user preference written from the electron splash screen and any
+  // future cli `sootsim config telemetry off` command. false in config.json wins
+  // over an absent env var; missing/default means opted in.
+  if (!readPrivacyPreferences().productAnalytics) return true
+  return false
+}
+
+function loadConfig(): Config | null {
+  if (isOptedOut()) return null
+  // env var precedence: explicit SootSim CLI override → vite-mirrored value.
+  // the published cli bakes CONTRAST_POSTHOG_API_KEY in at build time (see
+  // scripts/build-cli.ts); a keyless build silently no-ops, keeping the
+  // beta plan's "cli remains ungated" rule.
+  const apiKey =
+    process.env.CONTRAST_POSTHOG_API_KEY || process.env.VITE_POSTHOG_API_KEY || ''
+  if (!apiKey) return null
+  const host =
+    process.env.CONTRAST_POSTHOG_HOST ||
+    process.env.VITE_POSTHOG_HOST ||
+    'https://us.i.posthog.com'
+  return { apiKey, host: host.replace(/\/+$/, '') }
+}
+
+function anonymousDistinctId(): string {
+  // per-machine persisted id. the old literal 'anonymous-cli' merged every
+  // signed-out user into one posthog person, hiding individual first-run
+  // journeys (like a login that hung). never let telemetry throw.
+  try {
+    return readOrCreateAnonymousId()
+  } catch {
+    return 'anonymous-cli'
+  }
+}
+
+function resolveDistinctId(identity: Identity | undefined): string {
+  if (!identity) return anonymousDistinctId()
+  if (identity.userId) return identity.userId
+  if (identity.installationId != null) return `install:${identity.installationId}`
+  if (identity.repoId) return `repo:${identity.repoId}`
+  if (identity.shareId) return `share:${identity.shareId}`
+  return anonymousDistinctId()
+}
+
+function toPosthog(event: CliTelemetryEvent) {
+  const identity = event.identity ?? {}
+  const agentSession = process.env.TM_SESSION
+  const automationSource =
+    agentSession && isValidTeamMachineSessionId(agentSession)
+      ? 'team-machine'
+      : process.env.CI === '1' ||
+          process.env.CI === 'true' ||
+          process.env.GITHUB_ACTIONS === 'true'
+        ? 'ci'
+        : null
+  const properties: Record<string, unknown> = {
+    $lib: 'sootsim-cli',
+    source: identity.source ?? 'cli',
+    ...event.properties,
+    traffic_type: automationSource ? 'automated' : 'human',
+    is_automated: automationSource !== null,
+    ...(automationSource ? { automation_source: automationSource } : {}),
+  }
+  if (identity.userId) properties.userId = identity.userId
+  if (identity.repoId) properties.repoId = identity.repoId
+  if (identity.installationId != null) {
+    properties.installationId = String(identity.installationId)
+  }
+  if (identity.shareId) properties.shareId = identity.shareId
+  if (identity.plan) properties.plan = identity.plan
+
+  return {
+    event: event.event,
+    distinct_id: resolveDistinctId(identity),
+    properties,
+    timestamp: new Date().toISOString(),
+  }
+}
+
+const queue: CliTelemetryEvent[] = []
+let exitHooksInstalled = false
+
+async function drain(): Promise<void> {
+  if (queue.length === 0) return
+  const cfg = loadConfig()
+  if (!cfg) {
+    // silently drop — the cli shouldn't die because telemetry isn't
+    // configured on this machine.
+    queue.length = 0
+    return
+  }
+  const batch = queue.splice(0, queue.length).map(toPosthog)
+  try {
+    // hard timeout: a hung posthog endpoint must never block a cli
+    // command. 2s is well under any user's patience threshold and gives
+    // a healthy posthog plenty of time to ack the batch.
+    await fetch(`${cfg.host}/batch/`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ api_key: cfg.apiKey, batch }),
+      signal: AbortSignal.timeout(2000),
+    })
+  } catch {
+    // swallow — never fail a cli command because of telemetry.
+  }
+}
+
+function installExitHooks() {
+  if (exitHooksInstalled) return
+  exitHooksInstalled = true
+  // best-effort: beforeExit/exit handlers can't await async work, so
+  // process.exit() paths drop in-flight events. call flushCliTelemetry()
+  // explicitly before `process.exit()` at sites that enqueued events.
+  process.on('beforeExit', () => void drain())
+  process.on('exit', () => void drain())
+}
+
+// enrich + enqueue a cli event. reads the shared desktop session once per
+// call so logout between events is reflected. source defaults to 'cli'.
+export function trackCliEvent(event: CliTelemetryEvent): void {
+  if (isOptedOut()) return
+  installExitHooks()
+
+  let userId: string | null = null
+  try {
+    userId = readSharedDesktopAuthSession()?.user?.id ?? null
+  } catch {
+    userId = null
+  }
+
+  queue.push({
+    ...event,
+    identity: {
+      source: 'cli',
+      userId,
+      ...event.identity,
+    },
+  })
+}
+
+// explicit flush — use before a process.exit() call that won't give the
+// beforeExit hook time to complete its fetch. idempotent: safe to call
+// multiple times; drains whatever is currently queued.
+export async function flushCliTelemetry(): Promise<void> {
+  await drain()
+}