feat(telemetry): add option to opt-in to telemetry

This is opt-in for now whilst we set up and test integration with a
backend server (mostly with our own projects) but will be an opt-out
option in a future (non-breaking) version.

Author: ivomurrell

core/cli/src/index.ts

@@ -3,6 +3,8 @@ import type { Logger } from 'winston'
 import util from 'util'
 import { formatPluginTree } from './messages'
 import { loadHookInstallations } from './install'
+import { enableTelemetry } from './telemetry'
+import type { RootOptions } from '@dotcom-tool-kit/plugin/src/root-schema'
 import { TelemetryRecorder } from '@dotcom-tool-kit/telemetry'
 
 export { runCommands } from './tasks'
@@ -25,6 +27,7 @@ export async function printConfig(logger: Logger): Promise<void> {
 
 export async function printMergedOptions(logger: Logger, metrics: TelemetryRecorder): Promise<void> {
   const config = await loadConfig(logger, { validate: true, root: process.cwd() })
+  enableTelemetry(metrics, config.pluginOptions['app root'].options as RootOptions)
   const hookInstallations = (await loadHookInstallations(logger, metrics, config)).unwrap('invalid hooks')
 
   const mergedOptions = {

core/cli/src/install.ts

@@ -7,13 +7,15 @@ import { loadConfig } from './config'
 import { hasConfigChanged, updateHashes } from './config/hash'
 import type { ValidConfig } from '@dotcom-tool-kit/config'
 import { Hook, HookClass } from '@dotcom-tool-kit/base'
+import type { RootOptions } from '@dotcom-tool-kit/plugin/src/root-schema'
 import { Validated, invalid, reduceValidated, valid } from '@dotcom-tool-kit/validated'
 import { HookModule, reducePluginHookInstallations } from './plugin/reduce-installations'
 import { findConflicts, withoutConflicts } from '@dotcom-tool-kit/conflict'
 import { formatUninstalledHooks } from './messages'
 import { importEntryPoint } from './plugin/entry-point'
 import { runInit } from './init'
 import { guessSystemCode } from './systemCode'
+import { enableTelemetry } from './telemetry'
 import { TelemetryRecorder } from '@dotcom-tool-kit/telemetry'
 
 // implementation of the Array#every method that supports asynchronous predicates
@@ -125,6 +127,7 @@ export async function checkInstall(
 
 export default async function installHooks(logger: Logger, metrics: TelemetryRecorder): Promise<ValidConfig> {
   const config = await loadConfig(logger, { root: process.cwd() })
+  enableTelemetry(metrics, config.pluginOptions['app root'].options as RootOptions)
 
   await runInit(logger, config)
 

core/cli/src/tasks.ts

@@ -11,6 +11,7 @@ import { shouldDisableNativeFetch } from './fetch'
 import { runInit } from './init'
 import { formatInvalidOption } from './messages'
 import { guessSystemCode } from './systemCode'
+import { enableTelemetry } from './telemetry'
 import { type TaskOptions, TaskSchemas } from '@dotcom-tool-kit/schemas'
 import { OptionsForTask } from '@dotcom-tool-kit/plugin'
 import type { RootOptions } from '@dotcom-tool-kit/plugin/src/root-schema'
@@ -168,6 +169,7 @@ export async function runCommands(
   files?: string[]
 ): Promise<void> {
   const config = await loadConfig(logger, { root: process.cwd() })
+  enableTelemetry(metrics, config.pluginOptions['app root'].options as RootOptions)
 
   const systemCode = await guessSystemCode(config)
   let scoped = metrics

core/cli/src/telemetry.ts

@@ -0,0 +1,11 @@
+import type { RootOptions } from '@dotcom-tool-kit/plugin/src/root-schema'
+import type { TelemetryProcess, TelemetryRecorder } from '@dotcom-tool-kit/telemetry'
+
+// TODO:IM:20260113 in the future this type signature could be changed to allow
+// enabling telemetry even without a valid config (and the root options derived
+// from it,) so that we can track metrics related to invalid configurations.
+export function enableTelemetry(metrics: TelemetryProcess | TelemetryRecorder, options: RootOptions) {
+  if (options.enableTelemetry) {
+    metrics.enable()
+  }
+}

lib/plugin/src/root-schema.ts

@@ -2,6 +2,12 @@ import * as z from 'zod'
 
 export const RootSchema = z.object({
   allowNativeFetch: z.boolean().default(false),
+  enableTelemetry: z
+    .boolean()
+    .default(false)
+    .describe(
+      'Opt-in to send telemetry on your Tool Kit usage so we can track user patterns and friction points. This will be opt-out in a future version once the telemetry API has stabilised.'
+    ),
   // TODO:IM:20251112 require this option in a future major version
   systemCode: z
     .string()