@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/src/stored-document-migration.ts

@@ -0,0 +1,151 @@
+import { type JsonValue, isJsonObject } from "@dev.fast/review-protocol";
+import { z } from "zod";
+
+import { migrateDiffSelections } from "./diff-selection-migration.js";
+import { formatAnchor } from "./lens-selection.js";
+import { label } from "./review-api/blocks/definition.js";
+import { type Lens, lensTargetsSchema } from "./review-api/diff-lenses.js";
+
+/** Upgrade a saved or shared Review document to the current block schema at the
+ * read/import boundary. New edits use the strict schema and never accept these
+ * retired forms. */
+// This is the decoder boundary for stored documents in retired wire formats.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+export function migrateStoredDocument(input: unknown): JsonValue {
+  return anchorStrings(dropSectionStatus(migrateDiffSelections(input)));
+}
+
+/** Lenses saved before ranges were anchor strings. */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Decoder boundary for stored lenses in retired formats.
+export function migrateStoredLenses(input: unknown): JsonValue {
+  return anchorStrings(migrateDiffSelections(input));
+}
+
+const ANCHOR_KEYS = ["source", "sources", "callSite", "contextSources"];
+
+const selectionObjectSchema = z.object({
+  file: z.string(),
+  start: z.object({ side: z.enum(["base", "head"]), line: z.number() }),
+  end: z.object({ side: z.enum(["base", "head"]), line: z.number() }),
+  pins: z.json().optional(),
+});
+
+/**
+ * Anchors were once selection objects, each with its own pins. They are now
+ * strings, and pins sit on whatever holds them (a code peek, step, frame,
+ * attachment or operation) when they differ from the enclosing block's. No
+ * stored element mixed pins across its anchors. Lens ranges read at the
+ * review's pins and never carried others.
+ */
+export function anchorStrings(
+  value: JsonValue,
+  blockPins?: JsonValue,
+): JsonValue {
+  if (Array.isArray(value))
+    return value.map((child) => anchorStrings(child, blockPins));
+
+  if (!isJsonObject(value)) return value;
+
+  const inherited = value.pins ?? blockPins;
+  let pins: JsonValue | undefined;
+
+  const convert = (anchor: JsonValue): JsonValue => {
+    const selection = selectionObjectSchema.safeParse(anchor);
+
+    if (!selection.success) return anchor;
+
+    const { pins: own, ...anchorAt } = selection.data;
+
+    if (own) pins = own;
+
+    return formatAnchor(anchorAt);
+  };
+
+  const migrated = Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      ANCHOR_KEYS.includes(key)
+        ? Array.isArray(child)
+          ? child.map(convert)
+          : convert(child)
+        : anchorStrings(child, inherited),
+    ]),
+  );
+
+  if (
+    pins !== undefined &&
+    value.kind !== "ranges" &&
+    JSON.stringify(pins) !== JSON.stringify(blockPins)
+  )
+    migrated.pins = pins;
+
+  return migrated;
+}
+
+/** Sections once carried an optional `status` (pending, in_progress or
+ * complete). The authoring lease is now the only signal of work in progress,
+ * so versions saved before it was retired drop the field when read. */
+function dropSectionStatus(value: JsonValue): JsonValue {
+  if (Array.isArray(value)) return value.map(dropSectionStatus);
+
+  if (!isJsonObject(value)) return value;
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => !(value.type === "section" && key === "status"))
+      .map(([key, child]) => [key, dropSectionStatus(child)]),
+  );
+}
+
+/** A saved `file_lens` block, from before lenses left the document. */
+const legacyFileLensSchema = z.object({
+  type: z.literal("file_lens"),
+  id: label,
+  title: label,
+  targets: lensTargetsSchema.optional(),
+  patterns: z.array(label).min(1).optional(),
+});
+
+export interface LiftedLenses {
+  document: JsonValue;
+  lenses: Lens[];
+}
+
+/** Versions saved before lenses moved out of the document hold them as
+ * `file_lens` blocks, possibly inside sections. Lift them out of a migrated
+ * document, in document order, keeping each id, title and scope (legacy
+ * `patterns` become a files target). Viewed state is per file, so it needs
+ * no rewrite. */
+export function liftFileLenses(document: JsonValue): LiftedLenses {
+  const lenses: Lens[] = [];
+
+  const visit = (value: JsonValue): JsonValue => {
+    if (Array.isArray(value))
+      return value.flatMap((item) => {
+        if (!isJsonObject(item) || item.type !== "file_lens")
+          return [visit(item)];
+
+        const legacy = legacyFileLensSchema.safeParse(item);
+
+        // A malformed legacy lens is dropped rather than failing the read.
+        if (legacy.success && (legacy.data.targets ?? legacy.data.patterns))
+          lenses.push({
+            id: legacy.data.id,
+            title: legacy.data.title,
+            targets: legacy.data.targets ?? [
+              { kind: "files", patterns: legacy.data.patterns! },
+            ],
+          });
+
+        return [];
+      });
+
+    if (!isJsonObject(value)) return value;
+
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [key, visit(child)]),
+    );
+  };
+
+  return { document: visit(document), lenses };
+}

package/src/telemetry-clean-text.ts

@@ -0,0 +1,257 @@
+// Cleans a free-text telemetry value: replaces paths, web addresses, e-mail
+// addresses, and known secret formats with labelled markers.
+//
+// PROVENANCE. This is a port of Microsoft's implementation in VS Code, which
+// this product is a fork of. Source:
+//   apps/review-desktop/code-oss/src/vs/platform/telemetry/common/telemetryUtils.ts
+//   (`anonymizeFilePaths`, `userDataRegexes`, `redactIfPossibleUserInfo`,
+//    `removePropertiesWithPossibleUserInfo`)
+// Licensed under the MIT License, Copyright (c) Microsoft Corporation.
+//
+// It lives here rather than being imported because the local Review server and
+// the canvas both need it and neither can reach into the vendored VS Code tree.
+// Keep it a FAITHFUL copy: upstream comments and expressions are preserved
+// verbatim so a later reader can diff this file against upstream and see at a
+// glance whether it has drifted. Behaviour changes belong in the caller.
+//
+// The functions are pure and free of Node imports, so the browser-safe event
+// allowlist can share the expression list for its own independent re-check.
+//
+// DEVIATIONS FROM UPSTREAM, and only these:
+//  - Upstream keeps the tail of a `.vscode*/extensions/…` path so a stack stays
+//    attributable to an extension. Review reports no extension-host errors and
+//    cleans a message rather than a stack, so that branch is dropped and such a
+//    path is replaced whole. The `node_modules` branch is kept: a message can
+//    name a module usefully.
+//  - `cleanData`, upstream's object walker, is not ported. Review cleans two
+//    known strings, so walking an arbitrary object is not needed, and not
+//    having it means there is no path by which an unreviewed property could be
+//    cleaned-and-forwarded.
+
+export const USER_DATA_REGEXES = [
+  { label: "URL", regex: /[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s]*/ },
+  { label: "Google API Key", regex: /AIza[A-Za-z0-9_\\\-]{35}/ },
+  {
+    label: "JWT",
+    regex:
+      /eyJ[0eXAiOiJKV1Qi|hbGci|a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+/,
+  },
+  { label: "Slack Token", regex: /xox[pbar]\-[A-Za-z0-9]/ },
+  {
+    label: "GitHub Token",
+    regex:
+      /(gh[psuro]_[a-zA-Z0-9]{36}|github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59})/,
+  },
+  {
+    label: "Generic Secret",
+    regex:
+      /(key|token|sig|secret|signature|password|passwd|pwd|android:value)[^a-zA-Z0-9]/i,
+  },
+  {
+    label: "CLI Credentials",
+    regex:
+      /((login|psexec|(certutil|psexec)\.exe).{1,50}(\s-u(ser(name)?)?\s+.{3,100})?\s-(admin|user|vm|root)?p(ass(word)?)?\s+["']?[^$\-\/\s]|(^|[\s\r\n\\])net(\.exe)?.{1,5}(user\s+|share\s+\/user:| user -? secrets ? set) \s + [^ $\s \/])/,
+  },
+  {
+    label: "Microsoft Entra ID",
+    regex: /eyJ(?:0eXAiOiJKV1Qi|hbGci|[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.)/,
+  },
+  { label: "Email", regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/ },
+] as const;
+
+const REDACTED_PATH_MARKER = "<REDACTED: user-file-path>";
+
+/**
+ * The path shape the cleaner replaces: one or more `segment/` runs, with an
+ * optional drive letter, UNC, or `file://` root. Upstream keeps this inline in
+ * `anonymizeFilePaths`; it is named here so the allowlist can assert that no
+ * path shape survived cleaning.
+ */
+const FILE_PATH_PATTERN =
+  /(file:\/\/)?([a-zA-Z]:(\\\\|\\|\/)|(\\\\|\\|\/))?([\w\-\._@]+(\\\\|\\|\/))+[\w\-\._@]*/;
+
+/**
+ * True when the value still holds something path-shaped. Deliberately the same
+ * definition the cleaner uses: the point of re-testing is not a second opinion
+ * on what a path looks like, it is to catch the cleaner failing to apply its own
+ * rule — wrong patterns, wrong order, or an exception swallowed on the way.
+ */
+export function containsFilePath(value: string): boolean {
+  return FILE_PATH_PATTERN.test(value);
+}
+
+/**
+ * True when the value still holds something the cleaner should have replaced.
+ * The event allowlist calls this as its own second check, so it must not depend
+ * on the cleaner having run.
+ */
+export function hasPossibleUserInfo(value: string): boolean {
+  return USER_DATA_REGEXES.some((entry) => entry.regex.test(value));
+}
+
+/**
+ * Cleans a given stack of possible paths
+ * @param stack The stack to sanitize
+ * @param cleanupPatterns Cleanup patterns to remove from the stack
+ * @returns The cleaned stack
+ */
+export function anonymizeFilePaths(
+  stack: string,
+  cleanupPatterns: RegExp[],
+): string {
+  // Fast check to see if it is a file path to avoid doing unnecessary heavy regex work
+  if (!stack || (!stack.includes("/") && !stack.includes("\\"))) {
+    return stack;
+  }
+
+  let updatedStack = stack;
+
+  const cleanUpIndexes: [number, number][] = [];
+
+  for (const regexp of cleanupPatterns) {
+    while (true) {
+      const result = regexp.exec(stack);
+
+      if (!result) {
+        break;
+      }
+
+      cleanUpIndexes.push([result.index, regexp.lastIndex]);
+    }
+  }
+
+  // Match node_modules or node_modules.asar at any position in the path, capturing the node_modules/... suffix
+  const nodeModulesRegex =
+    /(?:^|[\\\/])((node_modules|node_modules\.asar)[\\\/].*)$/;
+
+  const fileRegex =
+    /(file:\/\/)?([a-zA-Z]:(\\\\|\\|\/)|(\\\\|\\|\/))?([\w\-\._@]+(\\\\|\\|\/))+[\w\-\._@]*/g;
+
+  let lastIndex = 0;
+  updatedStack = "";
+
+  while (true) {
+    const result = fileRegex.exec(stack);
+
+    if (!result) {
+      break;
+    }
+
+    // Check to see if the any cleanupIndexes partially overlap with this match
+    const overlappingRange = cleanUpIndexes.some(
+      ([start, end]) => result.index < end && start < fileRegex.lastIndex,
+    );
+
+    // anoynimize user file paths that do not need to be retained or cleaned up.
+    if (!overlappingRange) {
+      // Check if node_modules appears in the path — preserve node_modules/... suffix
+      const nodeModulesMatch = nodeModulesRegex.exec(result[0]);
+
+      if (nodeModulesMatch) {
+        updatedStack +=
+          stack.substring(lastIndex, result.index) +
+          `${REDACTED_PATH_MARKER}/` +
+          nodeModulesMatch[1];
+      } else {
+        updatedStack +=
+          stack.substring(lastIndex, result.index) + REDACTED_PATH_MARKER;
+      }
+
+      lastIndex = fileRegex.lastIndex;
+    }
+  }
+
+  if (lastIndex < stack.length) {
+    updatedStack += stack.substring(lastIndex);
+  }
+
+  return updatedStack;
+}
+
+/**
+ * Redacts a value if it contains commonly leaked PII.
+ * @param value The value returned (as-is) when no PII is detected
+ * @param probe The string actually matched against the PII heuristics. Defaults
+ * to `value`; callers may pass a value that includes a trailing delimiter (e.g. a
+ * newline) so that heuristics relying on a non-alphanumeric boundary match the
+ * same way they would against the original whole string.
+ * @returns A `<REDACTED: ...>` marker if the probe matched, otherwise `value`
+ */
+function redactIfPossibleUserInfo(
+  value: string,
+  probe: string = value,
+): string {
+  for (const secretRegex of USER_DATA_REGEXES) {
+    if (secretRegex.regex.test(probe)) {
+      return `<REDACTED: ${secretRegex.label}>`;
+    }
+  }
+
+  return value;
+}
+
+/**
+ * Attempts to remove commonly leaked PII.
+ *
+ * When a match is found the check is applied per line so that a single suspicious
+ * frame (e.g. a stack frame containing a function name such as `getStorageKey`
+ * which matches the broad `Generic Secret` heuristic) only redacts that line —
+ * replacing it with a `<REDACTED: ...>` marker — instead of wiping the entire
+ * multi-line value such as a whole callstack.
+ * @param property The property whose offending lines will be replaced with a redaction marker if they contain user data
+ * @returns The new value for the property
+ */
+export function removePropertiesWithPossibleUserInfo(property: string): string {
+  // If for some reason it is undefined we skip it (this shouldn't be possible);
+  if (!property) {
+    return property;
+  }
+
+  // Fast path: if nothing matches we return the value untouched without
+  // allocating.
+  if (!hasPossibleUserInfo(property)) {
+    return property;
+  }
+
+  // Single line values keep the original behavior of redacting the whole value.
+  if (!property.includes("\n")) {
+    return redactIfPossibleUserInfo(property);
+  }
+
+  // Multi-line values (e.g. callstacks) are redacted line-by-line so we only
+  // drop the offending lines and preserve the rest of the information.
+  const lines = property.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const probe = i < lines.length - 1 ? lines[i] + "\n" : lines[i];
+    lines[i] = redactIfPossibleUserInfo(lines[i], probe);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * The whole pipeline for one free-text value, in VS Code's order: replace
+ * path-shaped runs, delete the known local directories outright, then replace
+ * any line holding a secret or address shape.
+ */
+export function cleanTelemetryText(
+  value: string,
+  cleanupPatterns: RegExp[],
+): string {
+  let updated = value.replaceAll("%20", " ");
+  updated = anonymizeFilePaths(updated, cleanupPatterns);
+
+  for (const regexp of cleanupPatterns) {
+    updated = updated.replace(regexp, "");
+  }
+
+  return removePropertiesWithPossibleUserInfo(updated);
+}
+
+// `cleanupPatterns` above is the list of directories to delete outright rather
+// than replace with a marker. Upstream builds it from five known directories;
+// Review always passes an empty list, so what remains is the overlap check
+// inherited from upstream. See NO_DELETED_DIRECTORIES in error-telemetry.ts for
+// why. Should Review ever need the list, upstream builds it inline in
+// telemetryService.ts with escaped, case-insensitive, global patterns.

package/src/telemetry-config.ts

@@ -0,0 +1,298 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import type { JsonValue } from "@dev.fast/review-protocol";
+import { z } from "zod";
+
+import { findReviewPackageRoot } from "./package-paths";
+import { DEV_REVIEW_HOME_ENV, devReviewHome } from "./review-home-paths";
+
+export interface ReviewTelemetryInstallConfig {
+  installationId: string;
+  /**
+   * When this install was created, ISO 8601. A config written before the
+   * field existed gets the first time a later version read it.
+   */
+  createdAt: string;
+  installationCreatedSent: boolean;
+  firstReviewPresentedSent: boolean;
+  enabled: boolean;
+  internal: boolean;
+  /** `gh_` + keyed hash of the signed-in account id; absent until a login. */
+  accountAlias?: string;
+}
+
+export type ReviewTelemetryChannel = "stable" | "preview" | "dev";
+
+export type ReviewTelemetryEnvironment =
+  | "production"
+  | "ci"
+  | "internal"
+  | "e2e"
+  | "smoke";
+
+export type ReviewTelemetrySurface =
+  | "desktop"
+  | "cli"
+  | "headless"
+  | "mcp"
+  | "api";
+
+/** Set by Electron main from product.json `quality`; `dev` for an unpackaged run. */
+export const REVIEW_CHANNEL_ENV = "DEV_FAST_REVIEW_CHANNEL";
+
+/** Set by the e2e harness (`e2e`) and the packaged smoke scripts (`smoke`). */
+export const REVIEW_TELEMETRY_ENV_ENV = "DEV_FAST_REVIEW_TELEMETRY_ENV";
+
+const CHANNELS: readonly ReviewTelemetryChannel[] = [
+  "stable",
+  "preview",
+  "dev",
+];
+
+/**
+ * PostHog groups events into sessions by `$session_id` and accepts only a
+ * UUIDv7 there, so only a v7 app session id doubles as one.
+ */
+export const uuidV7Schema = z
+  .string()
+  .regex(
+    /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+  );
+
+export function isUuidV7(value: unknown): value is string {
+  return uuidV7Schema.safeParse(value).success;
+}
+
+export function reviewTelemetryChannel(
+  env: NodeJS.ProcessEnv,
+): ReviewTelemetryChannel {
+  // SAFETY: the cast is provisional; CHANNELS.includes(value) below checks
+  // membership before the value is ever returned, falling back to "stable".
+  const value = env[REVIEW_CHANNEL_ENV]?.trim() as ReviewTelemetryChannel;
+
+  return CHANNELS.includes(value) ? value : "stable";
+}
+
+/**
+ * First match wins: a harness declares itself, then CI, then a dev.fast
+ * checkout or a persisted internal marker, else a real user.
+ */
+export function reviewTelemetryEnvironment(
+  env: NodeJS.ProcessEnv,
+  config?: Pick<ReviewTelemetryInstallConfig, "internal">,
+): ReviewTelemetryEnvironment {
+  const harness = env[REVIEW_TELEMETRY_ENV_ENV]?.trim();
+
+  if (harness === "e2e" || harness === "smoke") return harness;
+
+  if (env.CI) return "ci";
+
+  if (isInternalTelemetry(env, config)) return "internal";
+
+  return "production";
+}
+
+const TELEMETRY_CONFIG_RELATIVE_PATH = path.join(
+  "telemetry",
+  "progressive-review.json",
+);
+
+const PREVIEW_TELEMETRY_CONFIG_RELATIVE_PATH = path.join(
+  "telemetry",
+  "progressive-review.preview.json",
+);
+
+const LEGACY_APP_TELEMETRY_CONFIG_RELATIVE_PATH = path.join(
+  "telemetry",
+  "install.json",
+);
+
+export function reviewTelemetryConfigPath(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(
+    devReviewHome(env),
+    reviewTelemetryChannel(env) === "preview"
+      ? PREVIEW_TELEMETRY_CONFIG_RELATIVE_PATH
+      : TELEMETRY_CONFIG_RELATIVE_PATH,
+  );
+}
+
+export function legacyAppTelemetryConfigPath(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(
+    devReviewHome(env),
+    LEGACY_APP_TELEMETRY_CONFIG_RELATIVE_PATH,
+  );
+}
+
+export function isTelemetryOptedOut(
+  env: NodeJS.ProcessEnv,
+  config?: Pick<ReviewTelemetryInstallConfig, "enabled">,
+): boolean {
+  // Test runners must never emit real telemetry: every vitest/node-test run
+  // with a temp DEV_REVIEW_HOME mints a fresh installation id and floods the
+  // installation and command metrics. Telemetry's own unit tests inject fake
+  // capture clients, so they are unaffected by this guard.
+  if (isEnabledEnvValue(env.VITEST) || env.NODE_ENV === "test") return true;
+
+  if (config?.enabled === false) return true;
+
+  // Keep every historical spelling so existing shell and CI configurations
+  // continue to disable telemetry after package and product renames.
+  return [
+    env.DO_NOT_TRACK,
+    env.DNT,
+    env.PROGRESSIVE_REVIEW_TELEMETRY_DISABLED,
+    env.DEV_FAST_TELEMETRY_DISABLED,
+    env.DEV_FAST_PROGRESSIVE_REVIEW_TELEMETRY_DISABLED,
+    env.DEV_FAST_REVIEW_TELEMETRY_DISABLED,
+  ].some(isEnabledEnvValue);
+}
+
+/**
+ * The on-disk install config as a hand-edited or older file may hold it: only
+ * the installation id is required, and a malformed optional field reads as
+ * absent.
+ */
+const storedTelemetryInstallConfigSchema = z.looseObject({
+  installationId: z.string().min(1),
+  createdAt: z.iso.datetime({ offset: true }).optional().catch(undefined),
+  installationCreatedSent: z.boolean().optional().catch(undefined),
+  firstReviewPresentedSent: z.boolean().optional().catch(undefined),
+  enabled: z.boolean().optional().catch(undefined),
+  internal: z.boolean().optional().catch(undefined),
+  accountAlias: z.string().min(1).optional().catch(undefined),
+});
+
+export function normalizeTelemetryInstallConfig(
+  parsed: JsonValue,
+  now: () => Date,
+): ReviewTelemetryInstallConfig | undefined {
+  const stored = storedTelemetryInstallConfigSchema.safeParse(parsed);
+
+  if (!stored.success) return undefined;
+
+  const config: ReviewTelemetryInstallConfig = {
+    installationId: stored.data.installationId,
+    createdAt: stored.data.createdAt ?? now().toISOString(),
+    installationCreatedSent: stored.data.installationCreatedSent === true,
+    firstReviewPresentedSent: stored.data.firstReviewPresentedSent === true,
+    enabled: stored.data.enabled !== false,
+    internal: stored.data.internal === true,
+  };
+
+  if (stored.data.accountAlias) config.accountAlias = stored.data.accountAlias;
+
+  return config;
+}
+
+/**
+ * Whether normalizing changed a field an older or hand-edited file lacked, so
+ * the config must be written back once: a backfilled `createdAt` has to stay
+ * the first-seen time rather than move with every read.
+ */
+export function telemetryInstallConfigNeedsWrite(
+  parsed: JsonValue,
+  config: ReviewTelemetryInstallConfig,
+): boolean {
+  const stored = storedTelemetryInstallConfigSchema.safeParse(parsed).data;
+
+  return (
+    stored?.internal !== config.internal ||
+    stored?.createdAt !== config.createdAt
+  );
+}
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+
+/** Whole days since the install was created; 0 for a clock set back. */
+export function installAgeDays(
+  config: Pick<ReviewTelemetryInstallConfig, "createdAt">,
+  now: Date,
+): number {
+  const createdAt = Date.parse(config.createdAt);
+
+  if (Number.isNaN(createdAt)) return 0;
+
+  return Math.max(0, Math.floor((now.getTime() - createdAt) / DAY_MS));
+}
+
+export function createTelemetryInstallConfig(
+  installationId: string,
+  now: () => Date,
+): ReviewTelemetryInstallConfig {
+  return {
+    installationId,
+    createdAt: now().toISOString(),
+    installationCreatedSent: false,
+    firstReviewPresentedSent: false,
+    enabled: true,
+    internal: false,
+  };
+}
+
+function isEnabledEnvValue(value: string | undefined): boolean {
+  return value === "1" || value?.toLowerCase() === "true";
+}
+
+let cachedWorkspaceCheckout: boolean | undefined;
+
+// Running from a workspace checkout (the dev.fast monorepo or any pnpm
+// workspace clone) means the traffic is ours, not a customer's. A published
+// npm install always lives under node_modules and has no workspace manifest
+// above it.
+function isWorkspaceCheckout(): boolean {
+  if (cachedWorkspaceCheckout !== undefined) return cachedWorkspaceCheckout;
+
+  try {
+    const packageRoot = findReviewPackageRoot();
+
+    if (packageRoot.split(path.sep).includes("node_modules")) {
+      cachedWorkspaceCheckout = false;
+
+      return cachedWorkspaceCheckout;
+    }
+
+    let dir = packageRoot;
+
+    while (true) {
+      if (existsSync(path.join(dir, "pnpm-workspace.yaml"))) {
+        cachedWorkspaceCheckout = true;
+
+        return cachedWorkspaceCheckout;
+      }
+
+      const parent = path.dirname(dir);
+
+      if (parent === dir) break;
+      dir = parent;
+    }
+
+    cachedWorkspaceCheckout = false;
+  } catch {
+    cachedWorkspaceCheckout = false;
+  }
+
+  return cachedWorkspaceCheckout;
+}
+
+/**
+ * Whether telemetry from this process should carry `internal: true` so
+ * partner-facing dashboards can exclude it. The environment overrides a
+ * stored true marker, which overrides workspace detection.
+ */
+export function isInternalTelemetry(
+  env: NodeJS.ProcessEnv,
+  config?: Pick<ReviewTelemetryInstallConfig, "internal">,
+): boolean {
+  if (env.PROGRESSIVE_REVIEW_TELEMETRY_INTERNAL === "1") return true;
+
+  if (env.PROGRESSIVE_REVIEW_TELEMETRY_INTERNAL === "0") return false;
+
+  if (config?.internal === true) return true;
+
+  return isWorkspaceCheckout();
+}