hyperframes/packages/cli/src/telemetry/canary.ts

/**
 * CLI binding for the canary registry.
 *
 * `@hyperframes/core` owns the decision (pure, browser-safe, caller supplies
 * everything). This file supplies the three things only the CLI knows: the
 * install's stable id, the env override, and whether we're on CI.
 *
 * Using one, from anywhere in the CLI / producer call path:
 *
 * ```ts
 * import { isCanaryEnabled } from "../telemetry/canary.js";
 * if (isCanaryEnabled("your-feature")) { ...ramped path... }
 * ```
 *
 * That is the whole API. Percentage lives in the registry, not at the call
 * site, so ramping is a one-line edit in a patch release and never touches
 * the feature's own code.
 */

// Leaf subpath imports, not the "@hyperframes/core" barrel: this resolves on
// the CLI startup path, and the barrel pulls the whole core surface. Same
// reason the producer is lazily loaded.
import {
  canaryFeatureProperties,
  evaluateCanary,
  parseCanaryOverride,
  type CanaryDecision,
} from "@hyperframes/core/canary";
import { CANARIES, canaryEnvVar, findCanary } from "@hyperframes/core/canary-registry";
import { readConfig } from "./config.js";
import { telemetryRuntimeOverride } from "./policy.js";
import { getSystemMeta } from "./system.js";

/**
 * Opting out of telemetry opts you out of canaries.
 *
 * A canary is a measured rollout: we enrol a slice precisely so we can compare
 * it against everyone else. An install that sends nothing can't be compared,
 * so enrolling it buys no signal — it only changes that user's code path, on
 * an experimental feature, without their knowledge and with no way for us to
 * see the result. That is the wrong side of an opt-out.
 *
 * Deliberately mirrors `shouldTrack()` rather than importing it: client.ts
 * already imports this module for `canaryEventProperties`, so depending on it
 * here would be a cycle. Both read the same two inputs (`policy.ts`'s runtime
 * override, then the persisted preference), so they cannot disagree.
 */
function telemetryActive(): boolean {
  if (telemetryRuntimeOverride() !== null) return false;
  return readConfig().telemetryEnabled;
}

/**
 * Decisions are memoized per process: a `--batch` run asks the same question
 * once per row, and a canary must not change its mind mid-process — a render
 * that starts enrolled has to finish enrolled, and its telemetry has to agree
 * with what actually ran.
 */
const decisions = new Map<string, CanaryDecision>();

// The memo is scoped to a telemetry posture, not to the process. Within one
// render nothing may change (a render that starts enrolled must finish
// enrolled), but `hyperframes preview` is a long-lived server that re-serves
// decisions on every page load — and it used to keep serving pre-opt-out
// decisions for hours after `hyperframes telemetry disable`, which is exactly
// what the docs promise cannot happen.
let decisionsTelemetryPosture: boolean | undefined;

/** Test-only: drop memoized decisions so cases don't leak into each other. */
export function __resetCanaryCacheForTests(): void {
  decisions.clear();
  decisionsTelemetryPosture = undefined;
}

/** The uncached decision. Split out so `resolveCanary` is purely the memo. */
function decideCanary(name: string): CanaryDecision {
  const definition = findCanary(name);
  if (!definition) return { enabled: false, reason: "out_of_cohort" };

  const override = parseCanaryOverride(process.env[canaryEnvVar(definition.name)]);

  // Resolved ahead of evaluate so an opted-out install is never bucketed at
  // all. An explicit HF_CANARY_* override still wins: that is a deliberate
  // local choice (support session, bisect, developer testing), not silent
  // enrolment, and it stays the way to exercise a canary with telemetry off.
  if (override === undefined && !telemetryActive()) {
    return { enabled: false, reason: "telemetry_opt_out" };
  }

  const config = readConfig();
  return evaluateCanary({
    feature: definition.name,
    // The bucket seed, NOT the anonymousId: the seed is inherited across
    // config.json re-mints via the install-state file, so cohorts hold when
    // the telemetry id re-rolls. Both files live in ~/.hyperframes, so
    // deleting that directory clears the cohort too — intentional. Fallback
    // covers only a failed backfill write on a legacy config.
    unitId: config.bucketSeed ?? config.anonymousId,
    percentage: definition.percentage,
    override,
    // CI installs regenerate their config per run, so their ids are
    // ephemeral — they would hop cohorts between runs, adding noise to the
    // rollout signal while saying nothing about real users. An explicit
    // override still gets through, which is how you test a canary in CI.
    exclude: getSystemMeta().is_ci,
  });
}

/**
 * Full decision for a registered canary, including the reason — use this when
 * you want to record WHY, not just whether.
 *
 * An unregistered name resolves to off rather than throwing: a canary is a
 * rollout control, and a typo in one must never take down a render.
 */
export function resolveCanary(name: string): CanaryDecision {
  const posture = telemetryActive();
  if (decisionsTelemetryPosture !== posture) {
    decisions.clear();
    decisionsTelemetryPosture = posture;
  }
  const cached = decisions.get(name);
  if (cached) return cached;

  const decision = decideCanary(name);
  decisions.set(name, decision);
  return decision;
}

/** Is this canary on for this install? The everyday call. */
export function isCanaryEnabled(name: string): boolean {
  return resolveCanary(name).enabled;
}

/**
 * One canary's outcome as handed to Studio: the answer, plus whether it came
 * from an explicit override rather than a percentage roll.
 */
export interface CliCanaryDecision {
  enabled: boolean;
  forced: boolean;
}

/**
 * Every registered canary's resolved on/off for this process, for handing to
 * a CLI-launched Studio.
 *
 * Studio adopts these wholesale instead of re-deriving, because re-deriving
 * cannot agree in three cases:
 *
 *   - **Telemetry off.** The CLI resolves `telemetry_opt_out`; Studio's own
 *     opt-out is a separate localStorage flag on a different machine-level
 *     switch, so it would evaluate normally and could enrol.
 *   - **`HF_CANARY_*` override.** Env vars do not cross into the browser at
 *     all — Studio only reads its URL param / sessionStorage — so a support
 *     session forcing a canary on got the CLI forced and Studio guessing.
 *   - **No seed injected.** Whenever the seed is withheld Studio falls back
 *     to a different unit id, i.e. a different bucket.
 *
 * Shipping the decision rather than the inputs makes divergence structurally
 * impossible: one evaluation, two surfaces. It is also strictly less to
 * expose — booleans about features, not the seed the buckets derive from.
 */
export function canaryDecisionsForStudio(): Record<string, CliCanaryDecision> {
  const out: Record<string, CliCanaryDecision> = {};
  for (const canary of CANARIES) {
    const { enabled, reason } = resolveCanary(canary.name);
    out[canary.name] = {
      enabled,
      // Provenance, not decoration. Studio has its own telemetry opt-out that
      // the CLI cannot see, and it must be able to refuse ordinary cohort
      // enrolment while still honouring a deliberate `HF_CANARY_*` override.
      // A bare boolean cannot express that difference, so Studio would have
      // had to either ignore its own opt-out or drop the override.
      forced: reason === "forced_on" || reason === "forced_off",
    };
  }
  return out;
}

/**
 * Canary assignments as PostHog flag properties — `$feature/canary-<name>`
 * set to `"true"` / `"false"` for every registered canary, each paired with a
 * `canary_reason_<name>`. Spread onto every event so any metric can be broken
 * down by cohort using PostHog's native flag tooling, with nothing configured
 * server-side. See `canaryFeatureProperties` for why non-enrolled canaries are
 * emitted too, and why the reason has to ride along.
 *
 * The reason is what makes a cohort flip attributable. `resolveCanary` has
 * computed it all along and this function used to drop it, so an install
 * reporting both values looked identical whether a developer had toggled
 * `HF_CANARY_*` or the bucketer had genuinely disagreed with itself.
 */
export function canaryEventProperties(): Record<string, string> {
  return canaryFeatureProperties(
    CANARIES.map((c) => {
      const { enabled, reason } = resolveCanary(c.name);
      return { name: c.name, enabled, reason };
    }),
  );
}