@frontera-sdk/cli 1.53.20 → 1.53.22

package/src/telemetry/recorder.ts

@@ -0,0 +1,114 @@
+import { flatAttributes, type OutboxRecord, type RecordAttributes, type Resource, type TelemetryEvent } from './events'
+import type { TelemetryMode } from './enabled'
+import { deviceIdentity, freshIdentity, saltedHash, type DeviceIdentity } from './device'
+import { OUTBOX_LIMITS, outboxWriter, type OutboxWriter } from './outbox'
+
+type Env = Record<string, string | undefined>
+
+/**
+ * Records events for one process. Off, it does nothing; in log mode it prints
+ * each event to stderr; sending, it appends each to this process's own outbox
+ * file, closed every minute and when the process exits.
+ *
+ * It never throws and never touches the network: a write that fails is
+ * dropped, so telemetry can neither fail nor slow the work it describes.
+ */
+export interface Recorder {
+  readonly mode: TelemetryMode
+  readonly deviceId: string
+  record(event: TelemetryEvent): void
+  /** Append a record another program made, already kept by the rules (the agents' relay in Forge); only while sending. */
+  write(record: OutboxRecord): void
+  /** Close the open outbox file now, so the sender can take it. */
+  roll(): void
+  /** Roll, and stop the timer and exit hook of a recorder that is being replaced. */
+  close(): void
+  /** A salted hash, for a project id or an item: never the name itself. */
+  hash(...parts: string[]): string
+}
+
+/** `os.type`, `host.arch` and `frontera.wsl` of this machine, as OpenTelemetry's resource conventions name them. */
+export function hostResource(env: Env = process.env, platform: string = process.platform, arch: string = process.arch): Pick<Resource, 'os.type' | 'host.arch' | 'frontera.wsl'> {
+  const os: Record<string, string> = { win32: 'windows' }
+  const archs: Record<string, string> = { x64: 'amd64', ia32: 'x86', arm: 'arm32' }
+  return { 'os.type': os[platform] ?? platform, 'host.arch': archs[arch] ?? arch, 'frontera.wsl': platform === 'linux' && !!(env.WSL_DISTRO_NAME || env.WSL_INTEROP) }
+}
+
+export function createRecorder(opts: {
+  mode: TelemetryMode
+  resource: Omit<Resource, 'frontera.device.id'>
+  context?: RecordAttributes
+  /** Where log mode prints; stderr by default. */
+  print?: (line: string) => void
+  now?: () => number
+  rollMs?: number
+}): Recorder {
+  const { mode } = opts
+  const now = opts.now ?? Date.now
+  let identity: DeviceIdentity
+  try {
+    identity = mode.mode === 'send' ? deviceIdentity(mode.outbox) : freshIdentity()
+  } catch {
+    identity = freshIdentity()
+  }
+  const resource: Resource = { ...opts.resource, 'frontera.device.id': identity.id }
+  const print = opts.print ?? ((line: string) => process.stderr.write(`${line}\n`))
+  let writer: OutboxWriter | null = null
+  let unhook = () => {}
+
+  const open = (outbox: string): OutboxWriter => {
+    const made = outboxWriter(outbox, { now })
+    const timer = setInterval(() => made.roll(), opts.rollMs ?? OUTBOX_LIMITS.rollMs)
+    timer.unref()
+    const onExit = () => made.roll()
+    process.once('exit', onExit)
+    unhook = () => {
+      clearInterval(timer)
+      process.off('exit', onExit)
+    }
+    return made
+  }
+
+  const roll = () => {
+    try {
+      writer?.roll()
+    } catch {
+      // Telemetry never fails the work it records.
+    }
+  }
+
+  const write = (record: OutboxRecord) => {
+    if (mode.mode !== 'send') return
+    try {
+      writer ??= open(mode.outbox)
+      writer.append(JSON.stringify(record))
+    } catch {
+      // Telemetry never fails the work it records.
+    }
+  }
+
+  return {
+    mode,
+    deviceId: identity.id,
+    record(event) {
+      if (mode.mode === 'off') return
+      try {
+        const attributes = flatAttributes(event, opts.context)
+        if (mode.mode === 'log') {
+          print(`[telemetry] ${event.name} ${event.severity} ${JSON.stringify(attributes)}`)
+          return
+        }
+        write({ resource, name: event.name, severity: event.severity, time: now(), attributes })
+      } catch {
+        // Telemetry never fails the work it records.
+      }
+    },
+    write,
+    roll,
+    close() {
+      roll()
+      unhook()
+    },
+    hash: (...parts) => saltedHash(identity.salt, ...parts),
+  }
+}

package/src/telemetry/redact.ts

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto'
+
+import type { ErrorFields } from './events'
+
+const X = '<x>'
+const MAX_TEMPLATE = 300
+const MAX_INPUT = 2_000
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/**
+ * What is replaced by `<x>`, in order. The design's list (quoted and
+ * backticked text, URLs, emails, UUIDs, paths, numbers, and parenthesised
+ * text, which its worked example replaces), plus identifier-shaped words
+ * (kebab-case, snake_case, camelCase): item names are written that way, and
+ * a message names them without quotes as often as with. Dotted host names go
+ * too. Ceiling: a name written as plain words (an organization's display
+ * name, a column called Nasabah) is indistinguishable from the message's own
+ * words and stays.
+ */
+const RULES: readonly RegExp[] = [
+  /`[^`]*`/g,
+  /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'`<>()]+/gi,
+  /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+  // Host names (a customer's platform or registry), which the CLI and the runtime write unquoted.
+  /\b(?:[a-z0-9-]+\.)+[a-z]{2,}\b/gi,
+  /"[^"\n]*"/g,
+  /“[^”\n]*”/g,
+  /(?<!\w)'[^'\n]*'(?!\w)/g,
+  /(?<!\w)‘[^’\n]*’(?!\w)/g,
+  /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi,
+  /[\w.@%+~<>-]*(?:[\\/][\w.@%+~<>-]+)+[\\/]?|[\w.@%+~<>-]+[\\/]/g,
+  /\b\w+(?:[-_]\w+)+\b/g,
+  /\b[a-z]+[A-Z]\w*\b/g,
+  /\b[A-Z][a-z]+[A-Z]\w*\b/g,
+  /[\w:+-]*\d(?:[\w.:+-]*\w)?/g,
+]
+
+const ERROR_LINE = /^error \[[A-Z][A-Z0-9_]*\]:\s*/
+
+/**
+ * An error message as a template: no names, paths, ids or numbers, so the same
+ * failure groups as one row however many times and wherever it happens.
+ * One line only: its `error [CODE]:` line when it has one, else its first.
+ * The lines under it are details (what was refused, a command's output), and
+ * those are where content would be. `names` are strings the caller knows are
+ * names (an item's slug, its file), replaced first wherever they appear.
+ */
+export function errorTemplate(message: string, names: readonly string[] = []): string {
+  const lines = message.split('\n').map((l) => l.trim()).filter(Boolean)
+  // Cut first: the rules backtrack quadratically on a long run of word characters, and a template keeps 300 anyway.
+  let text = (lines.find((l) => ERROR_LINE.test(l)) ?? lines[0] ?? '').replace(ERROR_LINE, '').slice(0, MAX_INPUT)
+  const known = [...new Set(names.map((n) => n.trim()).filter((n) => n.length > 1))].sort((a, b) => b.length - a.length)
+  if (known.length) text = text.replace(new RegExp(`(?<![\\w-])(?:${known.map(escape).join('|')})(?![\\w-])`, 'gi'), X)
+  for (const rule of RULES) text = text.replace(rule, X)
+  text = text
+    .replace(/\([^()]*\)/g, `(${X})`)
+    .replace(/(?:<x>)+/g, X)
+    .replace(/\s+/g, ' ')
+    .trim()
+  return text.length > MAX_TEMPLATE ? text.slice(0, MAX_TEMPLATE).replace(/<x?$/, '').trimEnd() : text
+}
+
+/** The first 16 hex characters of SHA-256 over `code + template`, for grouping. */
+export function errorFingerprint(code: string, template: string): string {
+  return createHash('sha256').update(code + template).digest('hex').slice(0, 16)
+}
+
+const CODE = /^[A-Z][A-Z0-9_]*$/
+
+/** A code as the CLI and the service name them (`RUNTIME_LOCKED`), else `UNCODED`. */
+export function errorCode(code: unknown): string {
+  return typeof code === 'string' && CODE.test(code) ? code : 'UNCODED'
+}
+
+/** The code of a command's output: its `error [CODE]` prefix, else `UNCODED`. */
+export function outputErrorCode(output: string): string {
+  return errorCode(/error \[([A-Z][A-Z0-9_]*)\]/.exec(output)?.[1])
+}
+
+/**
+ * A message that is a JSON error, as a harness passes on a provider's
+ * (`{"type":"error","status":400,"error":{"code":"model_not_found","message":"…"}}`):
+ * its `error.message` or `message`, and its `error.code` or `code`. Null for
+ * any other message.
+ */
+function jsonError(message: string): { message: string | undefined; code: unknown } | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(message)
+  } catch {
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object') return null
+  const top = parsed as { message?: unknown; code?: unknown; error?: unknown }
+  const inner = top.error && typeof top.error === 'object' ? (top.error as { message?: unknown; code?: unknown }) : {}
+  const text = [inner.message, top.message].find((m): m is string => typeof m === 'string' && m.trim() !== '')
+  return { message: text, code: inner.code ?? top.code }
+}
+
+export function errorFields(code: string, message: string, names: readonly string[] = []): ErrorFields {
+  const json = jsonError(message)
+  const template = errorTemplate(json?.message ?? message, names)
+  let checked = errorCode(code)
+  // The caller's code wins; else the JSON's, in the CLI's case (`model_not_found` is MODEL_NOT_FOUND).
+  if (checked === 'UNCODED' && typeof json?.code === 'string') checked = errorCode(json.code.toUpperCase())
+  return { code: checked, template, fingerprint: errorFingerprint(checked, template) }
+}

package/src/telemetry/send.ts

@@ -0,0 +1,121 @@
+import { readFileSync } from 'node:fs'
+
+import { parseRecord, type OutboxRecord } from './events'
+import { claim, listOutbox, prune, putBack, readPath, recoverStale, remove } from './outbox'
+import { toOtlpLogs } from './otlp'
+
+type Env = Record<string, string | undefined>
+type Fetch = (url: string, init: RequestInit) => Promise<Response>
+
+export const DEFAULT_ENDPOINT = 'https://telemetry.frontera.kata.ai/v1/logs'
+
+/**
+ * The public write key: what a build without a key of its own (a checkout)
+ * sends with. Anyone can read it here, as with Next.js's or PostHog's public
+ * keys; the collector's filters and allowlists and the edge's rate limit
+ * protect the store, not its secrecy. `telemetry.sh` keeps it on the
+ * collector's token list (`PUBLIC_TOKEN` there, which a test holds equal).
+ */
+export const PUBLIC_TOKEN = 'ftt_2ff4debb87da5d9d0571629af15ff328fde0ae07c38d99ea'
+
+/** The collector's cap on one request (`max_request_body_size`). */
+export const MAX_BODY_BYTES = 1024 * 1024
+export const SEND_TIMEOUT_MS = 5_000
+
+/**
+ * How long the sender waits before its next pass, by how many passes in a row
+ * have failed: 30 seconds normally, doubling after each failure up to 10 minutes.
+ */
+export const SEND_BACKOFF_MS = [30_000, 60_000, 120_000, 240_000, 480_000, 600_000] as const
+
+export function sendDelayMs(consecutiveFailures: number): number {
+  return SEND_BACKOFF_MS[Math.min(Math.max(0, consecutiveFailures), SEND_BACKOFF_MS.length - 1)]!
+}
+
+/**
+ * Where to send and with which token: `FRONTERA_TELEMETRY_TOKEN`, else the
+ * release build's own key (one per release line, so one line can be revoked
+ * alone), else the public key. The overrides are for testing against a local
+ * collector.
+ */
+export function senderConfig(env: Env, builtInToken: string | undefined): { endpoint: string; token: string } {
+  return { endpoint: env.FRONTERA_TELEMETRY_ENDPOINT?.trim() || DEFAULT_ENDPOINT, token: env.FRONTERA_TELEMETRY_TOKEN?.trim() || builtInToken?.trim() || PUBLIC_TOKEN }
+}
+
+export type SendResult =
+  /** Nothing closed to send. */
+  | { outcome: 'idle' }
+  /** Taken by the collector, and deleted: the records it took. `more`: closed files are still waiting, so send again now. */
+  | { outcome: 'sent'; files: number; records: OutboxRecord[]; more: boolean }
+  /** Refused as malformed or too large (400, 413): deleted, since sending it again can never succeed. */
+  | { outcome: 'dropped'; files: number; records: OutboxRecord[]; status: number }
+  /** Not taken (no answer, a timeout, 401, 429, 5xx): put back, to try after `sendDelayMs`. */
+  | { outcome: 'failed'; files: number; status: number | null; error: string | null }
+
+const records = (text: string): OutboxRecord[] => text.split('\n').flatMap((line) => (line.trim() ? (parseRecord(line) ?? []) : []))
+
+const bodyBytes = (batch: readonly OutboxRecord[], now: number) => Buffer.byteLength(JSON.stringify(toOtlpLogs(batch, now)))
+
+/**
+ * One pass of the sender, run by Forge's server at start and then after each
+ * `sendDelayMs`. Puts back what a crashed pass left claimed, drops what is past
+ * the outbox's age and size limits, claims the oldest closed files that fit in
+ * one request, posts them, and deletes them on a 2xx or puts them back.
+ */
+export async function sendPass(opts: { dir: string; endpoint: string; token: string; fetch?: Fetch; now?: () => number; timeoutMs?: number }): Promise<SendResult> {
+  const now = opts.now ?? Date.now
+  const { dir } = opts
+  recoverStale(dir, now())
+  prune(dir, now())
+
+  const claimed: string[] = []
+  const batch: OutboxRecord[] = []
+  let bytes = 0
+  const closed = listOutbox(dir).filter((f) => f.state === 'closed')
+  for (const file of closed) {
+    let found: OutboxRecord[]
+    try {
+      found = records(readFileSync(readPath(dir, file), 'utf8'))
+    } catch {
+      continue
+    }
+    // Each file's size as a request of its own: the batch, merging shared resources, is never larger than their sum.
+    const size = bodyBytes(found, now())
+    // The first file always goes: a writer closes its file well under the cap.
+    if (claimed.length && bytes + size > MAX_BODY_BYTES) break
+    if (!claim(dir, file.id, now())) continue
+    claimed.push(file.id)
+    batch.push(...found)
+    bytes += size
+  }
+  if (!claimed.length) return { outcome: 'idle' }
+  const more = closed.length > claimed.length
+  if (!batch.length) {
+    for (const id of claimed) remove(dir, id)
+    return { outcome: 'sent', files: claimed.length, records: [], more }
+  }
+
+  let status: number | null = null
+  let error: string | null = null
+  try {
+    const res = await (opts.fetch ?? fetch)(opts.endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${opts.token}` },
+      body: JSON.stringify(toOtlpLogs(batch, now())),
+      signal: AbortSignal.timeout(opts.timeoutMs ?? SEND_TIMEOUT_MS),
+    })
+    status = res.status
+  } catch (err) {
+    error = (err as Error).name === 'TimeoutError' ? 'timed out' : (err as Error).message
+  }
+  if (status !== null && status >= 200 && status < 300) {
+    for (const id of claimed) remove(dir, id)
+    return { outcome: 'sent', files: claimed.length, records: batch, more }
+  }
+  if (status === 400 || status === 413) {
+    for (const id of claimed) remove(dir, id)
+    return { outcome: 'dropped', files: claimed.length, records: batch, status }
+  }
+  for (const id of claimed) putBack(dir, id)
+  return { outcome: 'failed', files: claimed.length, status, error }
+}