Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
11.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file The recorded event shape, and the environment snapshot attached to it.
 *
 * One invocation produces exactly one event. That keeps the log trivially
 * queryable — `SELECT command, outcome, count(*) FROM events GROUP BY 1, 2`
 * works with no joins — and keeps the write path to a single append.
 *
 * The shape is versioned by {@link SCHEMA_VERSION}. Treat it as an append-only
 * contract: add fields freely, never repurpose or remove one, and bump the
 * version when an existing field changes meaning, so a consumer reading a
 * mixed-version table can branch on it.
 *
 * @input  command identity, argv/options, an outcome, and process context
 * @output a flat, JSON-serializable record ready for a sink
 * @position packages/cli/foundation/debug — event shape
 */

import * as crypto from 'node:crypto';
import {isCliOneOff, detectPackageManager} from '../env/package-manager.mjs';

/**
 * Version of the recorded event shape. Bump on any breaking field change,
 * widening {@link DebugSchemaVersion} in the published type at the same time.
 *
 * v2 retired the raw `env.agentSessionId`: it is always null now, and
 * `agentSessionIdHash` is the join key. A consumer that grouped runs by the
 * raw value would otherwise have started grouping every run under `null`
 * without a single compile error, which is exactly what the version exists to
 * prevent.
 *
 * v3 made every command report its result, which changed what an ABSENT one
 * means: `output.resultKind` is null only when the run never reached an
 * answer, and a command with no result set now says `none`. The values did not
 * move, but the null did — a consumer counting nulls as "commands with nothing
 * to report" would silently start counting failures instead, and no widened
 * union catches a branch on null.
 *
 * @type {import('../../authoring/debug/type').DebugSchemaVersion}
 */
export const SCHEMA_VERSION = 3;

/**
 * The recorded shape is PUBLISHED — a project sets `debug` in `astryx.config`
 * to a function, and that function receives these. So the definition lives in
 * `authoring/debug/type.ts` alongside the other public contracts, and this
 * module re-uses it rather than keeping a second copy that could drift. A
 * sealed zod schema in `authoring/debug/parse.mjs` is drift-locked to it.
 *
 * @typedef {import('../../authoring/debug/type').DebugEvent} DebugEvent
 * @typedef {import('../../authoring/debug/type').DebugOutcome} Outcome
 * @typedef {import('../../authoring/debug/type').DebugEventError} DebugEventError
 */

/**
 * An event still being filled in. Timing is only knowable once the run ends
 * and the environment probe is deferred until there is a handler to deliver
 * to, so those fields are absent or null until {@link finish} seals the
 * record — every PERSISTED event has them.
 *
 * @typedef {Omit<DebugEvent, 'endedAt' | 'durationMs' | 'env'> &
 *   {endedAt?: string, durationMs?: number,
 *    env: DebugEvent['env'] | null}} InFlightEvent
 */

/**
 * CI providers worth naming, matched by a single env var each. Order matters
 * only for the name we report; `ci` is true if any of them (or the generic
 * `CI` flag) is present.
 */
const CI_PROVIDERS = [
  ['GITHUB_ACTIONS', 'github-actions'],
  ['GITLAB_CI', 'gitlab-ci'],
  ['CIRCLECI', 'circleci'],
  ['BUILDKITE', 'buildkite'],
  ['TRAVIS', 'travis'],
  ['JENKINS_URL', 'jenkins'],
  ['TEAMCITY_VERSION', 'teamcity'],
  ['TF_BUILD', 'azure-pipelines'],
  ['BITBUCKET_BUILD_NUMBER', 'bitbucket'],
  ['CODEBUILD_BUILD_ID', 'aws-codebuild'],
  ['DRONE', 'drone'],
  ['VERCEL', 'vercel'],
  ['NETLIFY', 'netlify'],
];

/**
 * Coding-agent signals. The first six are positive evidence of an AI agent.
 * The final two are retained only by the legacy `agent` field because they can
 * also describe a human development environment.
 */
const AGENT_SIGNALS = [
  ['CURSOR_TRACE_ID', 'cursor'],
  ['CURSOR_AGENT', 'cursor'],
  ['CLAUDECODE', 'claude-code'],
  ['CLAUDE_CODE', 'claude-code'],
  ['AIDER_MODEL', 'aider'],
  ['GITHUB_COPILOT_AGENT', 'copilot'],
  ['REPLIT_USER', 'replit'],
  ['CODESPACES', 'codespaces'],
];
const POSITIVE_AGENT_SIGNAL_COUNT = 6;

/** @returns {{ci: boolean, ciName: string | null}} */
function detectCi() {
  for (const [key, name] of CI_PROVIDERS) {
    if (process.env[key]) return {ci: true, ciName: name};
  }
  const generic =
    process.env.CI != null &&
    process.env.CI !== '' &&
    process.env.CI !== '0' &&
    process.env.CI !== 'false';
  return {ci: generic, ciName: generic ? 'unknown' : null};
}

/** @param {unknown} value @returns {string | null} */
function nonEmptyString(value) {
  if (value == null) return null;
  const text = String(value).trim();
  return text || null;
}

/**
 * Agent identity: the generic AGENT variable, else the first positive
 * coding-agent signal. ASTRYX_AGENT_ID and ASTRYX_AGENT_METADATA are not read
 * (spec:AST-017 FR14), and no replacement metadata variable is introduced.
 * @returns {string | null}
 */
function detectAgentIdentity() {
  const genericAgent = nonEmptyString(process.env.AGENT);
  if (genericAgent) return genericAgent.toLowerCase();

  for (const [key, name] of AGENT_SIGNALS.slice(
    0,
    POSITIVE_AGENT_SIGNAL_COUNT,
  )) {
    if (process.env[key]) return name;
  }
  return null;
}

/** @param {string | null} identity @returns {string | null} */
function detectAgent(identity) {
  if (identity) return identity;
  for (const [key, name] of AGENT_SIGNALS) {
    if (process.env[key]) return name;
  }
  const termProgram = process.env.TERM_PROGRAM;
  if (termProgram === 'vscode') return 'vscode';
  return null;
}

/**
 * Agent session: the generic AGENT_SESSION_ID variable. ASTRYX_AGENT_SESSION_ID
 * and ASTRYX_AGENT_METADATA are not read (spec:AST-017 FR14).
 * @returns {{id: string | null, source: string | null}}
 */
function detectAgentSession() {
  const id = nonEmptyString(process.env.AGENT_SESSION_ID);
  return id ? {id, source: 'AGENT_SESSION_ID'} : {id: null, source: null};
}

/** @param {string | null} id @returns {string | null} */
function hashAgentSessionId(id) {
  return id == null
    ? null
    : crypto.createHash('sha256').update(id, 'utf8').digest('hex');
}

/**
 * @param {{agentIdentity: string | null, agentSessionId: string | null, ci: boolean}} facts
 * @returns {import('../../authoring/debug/type').DebugInvocationSource}
 */
function detectInvocationSource({agentIdentity, agentSessionId, ci}) {
  if (agentIdentity || agentSessionId) return 'ai';
  if (ci) return 'automation';
  if (process.stdout.isTTY) return 'human';
  return 'unknown';
}

/**
 * Snapshot the machine, runtime, and invocation attribution. There is no
 * hostname, username, or network identity, and no raw agent session id — the
 * privacy contract is on `DebugEventEnv` in `authoring/debug/type.ts`. Agent
 * session values come only from explicit environment signals supplied by the
 * invoking tool.
 *
 * @param {{cliVersion?: string}} [options]
 * @returns {import('../../authoring/debug/type').DebugEventEnv}
 */
export function captureEnv({cliVersion} = {}) {
  const {ci, ciName} = detectCi();
  const agentIdentity = detectAgentIdentity();
  const agentSession = detectAgentSession();
  return {
    cliVersion: cliVersion ?? null,
    nodeVersion: process.versions.node,
    platform: process.platform,
    arch: process.arch,
    ci,
    ciName,
    agent: detectAgent(agentIdentity),
    agentIdentity,
    // Never the raw value. A session id is a stable identifier that follows a
    // person across every run they make, and nothing here needs it: the hash
    // joins those runs just as well, and a handler that forwards the record
    // somewhere less private cannot un-forward an identifier we handed it.
    // Kept as an always-null field rather than dropped, so a consumer reading
    // schema-v1 records alongside these sees one stable shape.
    agentSessionId: null,
    agentSessionIdHash: hashAgentSessionId(agentSession.id),
    agentSessionIdSource: agentSession.source,
    invocationSource: detectInvocationSource({
      agentIdentity,
      agentSessionId: agentSession.id,
      ci,
    }),
    oneOff: safe(() => isCliOneOff(), false),
    packageManager: safe(() => detectPackageManager(), null),
    tty: Boolean(process.stdout.isTTY),
    locale: safe(() => Intl.DateTimeFormat().resolvedOptions().locale, null),
    timezone: safe(
      () => Intl.DateTimeFormat().resolvedOptions().timeZone,
      null,
    ),
  };
}

/**
 * Snapshot the project the command ran against. Names of a user's private
 * packages are identifying, so this records only shape: whether a project is
 * present, whether it is configured, and how many integrations it loads.
 *
 * @param {{hasConfig?: boolean, initialized?: boolean, integrationCount?: number, inProject?: boolean}} [facts]
 * @returns {import('../../authoring/debug/type').DebugEventProject}
 */
export function captureProject(facts = {}) {
  return {
    inProject: facts.inProject ?? null,
    hasConfig: facts.hasConfig ?? null,
    initialized: facts.initialized ?? null,
    integrationCount: facts.integrationCount ?? null,
  };
}

/**
 * A blank event, ready to accumulate into.
 *
 * Deliberately cheap: allocation only. `env` is left null and filled in by
 * {@link finish} once there is a handler to deliver to — probing it here would
 * charge every run for something most runs never use. It is not a small
 * charge: the first `Intl.DateTimeFormat().resolvedOptions()` initialises ICU,
 * and with `detectPackageManager` and `isCliOneOff` alongside it the probe
 * dominated `begin()` and put ~9% on the CLI's startup for everyone.
 *
 * @param {object} [init]
 * @param {string} [init.command]
 * @param {string[]} [init.argv]
 * @returns {InFlightEvent}
 */
export function createEvent({command = '', argv = []} = {}) {
  return {
    schemaVersion: SCHEMA_VERSION,
    id: crypto.randomUUID(),
    startedAt: new Date().toISOString(),
    command,
    commandPath: command ? command.split(' ') : [],
    argv,
    args: {},
    options: {},
    optionSources: {},
    globalOptions: {},
    outcome: 'incomplete',
    exitCode: null,
    signal: null,
    error: null,
    output: {
      jsonMode: false,
      envelopeTypes: [],
      handled: false,
      helpDisplayed: false,
      resultCount: null,
      emptyResult: null,
      resultKind: null,
      directMatch: null,
      stdout: '',
      stderr: '',
      stdoutBytes: 0,
      stderrBytes: 0,
      truncated: false,
    },
    env: null,
    project: captureProject(),
    // FALSE, and true only on the sealed copy `finish()` delivers. Nothing has
    // been through the scrubbing pass yet, and a record that claims otherwise
    // while still holding verbatim values is worse than one that admits it.
    redacted: false,
  };
}

/**
 * Normalize a thrown value into the event's error shape.
 * @param {unknown} err
 * @returns {DebugEventError | null}
 */
export function toEventError(err) {
  if (err == null) return null;
  if (err instanceof Error) {
    return {
      name: err.name,
      message: err.message,
      code:
        typeof (/** @type {any} */ (err).code) === 'string'
          ? /** @type {any} */ (err).code
          : null,
      stack: err.stack ?? null,
    };
  }
  return {
    name: typeof err,
    message: typeof err === 'string' ? err : safeStringify(err),
    code: null,
    stack: null,
  };
}

/**
 * Run `fn`, returning `fallback` if it throws. Environment probes touch the
 * filesystem and Intl, both of which can fail in a locked-down sandbox.
 * @template T
 * @param {() => T} fn
 * @param {T} fallback
 * @returns {T}
 */
function safe(fn, fallback) {
  try {
    return fn();
  } catch {
    return fallback;
  }
}

/** @param {unknown} value @returns {string} */
function safeStringify(value) {
  try {
    return JSON.stringify(value) ?? String(value);
  } catch {
    return String(value);
  }
}