feat: add telemetry notice and preference management

Author: Hweinstock

src/cli/__tests__/global-config.test.ts

@@ -0,0 +1,99 @@
+import { getOrCreateInstallationId, readGlobalConfig, updateGlobalConfig } from '../global-config';
+import { createTempConfig } from './helpers/temp-config';
+import { readFile, writeFile } from 'fs/promises';
+import { afterAll, beforeEach, describe, expect, it } from 'vitest';
+
+const tmp = createTempConfig('gc');
+
+describe('global-config', () => {
+  beforeEach(() => tmp.setup());
+  afterAll(() => tmp.cleanup());
+
+  describe('readGlobalConfig', () => {
+    it('returns parsed config when file exists', async () => {
+      await writeFile(tmp.configFile, JSON.stringify({ telemetry: { enabled: false } }));
+
+      const config = await readGlobalConfig(tmp.configFile);
+
+      expect(config).toEqual({ telemetry: { enabled: false } });
+    });
+
+    it('returns empty object when file is missing or invalid', async () => {
+      expect(await readGlobalConfig(tmp.testDir + '/nonexistent.json')).toEqual({});
+
+      await writeFile(tmp.configFile, JSON.stringify({ telemetry: { enabled: 'false' } }));
+      expect(await readGlobalConfig(tmp.configFile)).toEqual({});
+    });
+
+    it('preserves unknown fields via passthrough', async () => {
+      const full = {
+        installationId: 'abc-123',
+        telemetry: { enabled: true, endpoint: 'https://example.com', audit: false },
+        futureField: 'hello',
+      };
+      await writeFile(tmp.configFile, JSON.stringify(full));
+
+      const config = await readGlobalConfig(tmp.configFile);
+
+      expect(config).toEqual(full);
+    });
+  });
+
+  describe('updateGlobalConfig', () => {
+    it('creates directory and writes config when none exists', async () => {
+      const fresh = createTempConfig('gc-fresh');
+
+      const ok = await updateGlobalConfig({ telemetry: { enabled: false } }, fresh.configDir, fresh.configFile);
+
+      expect(ok).toBe(true);
+      const written = JSON.parse(await readFile(fresh.configFile, 'utf-8'));
+      expect(written).toEqual({ telemetry: { enabled: false } });
+
+      await fresh.cleanup();
+    });
+
+    it('deep-merges telemetry sub-object with existing config', async () => {
+      await writeFile(
+        tmp.configFile,
+        JSON.stringify({ installationId: 'keep-me', telemetry: { enabled: true, endpoint: 'https://x.com' } })
+      );
+
+      await updateGlobalConfig({ telemetry: { enabled: false } }, tmp.configDir, tmp.configFile);
+
+      const written = JSON.parse(await readFile(tmp.configFile, 'utf-8'));
+      expect(written).toEqual({
+        installationId: 'keep-me',
+        telemetry: { enabled: false, endpoint: 'https://x.com' },
+      });
+    });
+
+    it('returns false on write failures', async () => {
+      const ok = await updateGlobalConfig(
+        { telemetry: { enabled: true } },
+        tmp.testDir + '/\0invalid',
+        tmp.testDir + '/\0invalid/config.json'
+      );
+
+      expect(ok).toBe(false);
+    });
+  });
+
+  describe('getOrCreateInstallationId', () => {
+    it('generates installationId on first run and returns created: true', async () => {
+      const result = await getOrCreateInstallationId(tmp.configDir, tmp.configFile);
+
+      expect(result.created).toBe(true);
+      expect(result.id).toMatch(/^[0-9a-f-]{36}$/);
+      const config = await readGlobalConfig(tmp.configFile);
+      expect(config.installationId).toBe(result.id);
+    });
+
+    it('returns existing id with created: false', async () => {
+      await writeFile(tmp.configFile, JSON.stringify({ installationId: 'existing-id' }));
+
+      const result = await getOrCreateInstallationId(tmp.configDir, tmp.configFile);
+
+      expect(result).toEqual({ id: 'existing-id', created: false });
+    });
+  });
+});

src/cli/__tests__/helpers/temp-config.ts

@@ -0,0 +1,28 @@
+import { mkdir, rm } from 'fs/promises';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export interface TempConfigPaths {
+  testDir: string;
+  configDir: string;
+  configFile: string;
+  setup: () => Promise<void>;
+  cleanup: () => Promise<void>;
+}
+
+export function createTempConfig(label: string): TempConfigPaths {
+  const testDir = join(tmpdir(), `agentcore-${label}-${randomUUID()}`);
+  const configDir = join(testDir, '.agentcore');
+  const configFile = join(configDir, 'config.json');
+  return {
+    testDir,
+    configDir,
+    configFile,
+    setup: async () => {
+      await rm(testDir, { recursive: true, force: true });
+      await mkdir(configDir, { recursive: true });
+    },
+    cleanup: () => rm(testDir, { recursive: true, force: true }),
+  };
+}

src/cli/ansi.ts

@@ -0,0 +1,9 @@
+/** ANSI escape codes for console output. */
+export const ANSI = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m',
+} as const;

src/cli/cli.ts

@@ -1,3 +1,4 @@
+import { ANSI } from './ansi';
 import { registerAdd } from './commands/add';
 import { registerCreate } from './commands/create';
 import { registerDeploy } from './commands/deploy';
@@ -14,10 +15,12 @@ import { registerRemove } from './commands/remove';
 import { registerResume } from './commands/resume';
 import { registerRun } from './commands/run';
 import { registerStatus } from './commands/status';
+import { registerTelemetry } from './commands/telemetry';
 import { registerTraces } from './commands/traces';
 import { registerUpdate } from './commands/update';
 import { registerValidate } from './commands/validate';
 import { PACKAGE_VERSION } from './constants';
+import { getOrCreateInstallationId } from './global-config';
 import { ALL_PRIMITIVES } from './primitives';
 import { App } from './tui/App';
 import { LayoutProvider } from './tui/context';
@@ -61,10 +64,24 @@ function setupGlobalCleanup() {
   });
 }
 
+function printTelemetryNotice(): void {
+  process.stderr.write(
+    [
+      '',
+      `${ANSI.yellow}The AgentCore CLI will soon begin collecting aggregated, anonymous usage`,
+      'analytics to help improve the tool.',
+      'To opt out:          agentcore telemetry disable',
+      `To learn more:       agentcore telemetry --help${ANSI.reset}`,
+      '',
+      '',
+    ].join('\n')
+  );
+}
+
 /**
  * Render the TUI in alternate screen buffer mode.
  */
-function renderTUI(updateCheck: Promise<UpdateCheckResult | null>) {
+function renderTUI(updateCheck: Promise<UpdateCheckResult | null>, isFirstRun: boolean) {
   inAltScreen = true;
   process.stdout.write(ENTER_ALT_SCREEN);
 
@@ -82,6 +99,10 @@ function renderTUI(updateCheck: Promise<UpdateCheckResult | null>) {
       clearExitMessage();
     }
 
+    if (isFirstRun) {
+      printTelemetryNotice();
+    }
+
     // Print update notification after TUI exits
     const result = await updateCheck;
     if (result?.updateAvailable) {
@@ -148,6 +169,7 @@ export function registerCommands(program: Command) {
   registerResume(program);
   registerRun(program);
   registerStatus(program);
+  registerTelemetry(program);
   registerTraces(program);
   registerUpdate(program);
   registerValidate(program);
@@ -162,6 +184,9 @@ export const main = async (argv: string[]) => {
   // Register global cleanup handlers once at startup
   setupGlobalCleanup();
 
+  // Generate installationId on first run and show telemetry notice
+  const { created: isFirstRun } = await getOrCreateInstallationId();
+
   const program = createProgram();
 
   const args = argv.slice(2);
@@ -172,10 +197,14 @@ export const main = async (argv: string[]) => {
 
   // Show TUI for no arguments, commander handles --help via configureHelp()
   if (args.length === 0) {
-    renderTUI(updateCheck);
+    renderTUI(updateCheck, isFirstRun);
     return;
   }
 
+  if (isFirstRun) {
+    printTelemetryNotice();
+  }
+
   await program.parseAsync(argv);
 
   // Print notification after command finishes

src/cli/commands/import/constants.ts

@@ -2,14 +2,7 @@
 export const NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_]{0,47}$/;
 
 /** ANSI escape codes for console output. */
-export const ANSI = {
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  cyan: '\x1b[36m',
-  dim: '\x1b[2m',
-  reset: '\x1b[0m',
-} as const;
+export { ANSI } from '../../ansi.js';
 
 /**
  * CloudFormation resource type to identifier key mapping for IMPORT.

src/cli/commands/telemetry/__tests__/telemetry.test.ts

@@ -0,0 +1,70 @@
+import { createTempConfig } from '../../../__tests__/helpers/temp-config';
+import { handleTelemetryDisable, handleTelemetryEnable, handleTelemetryStatus } from '../actions';
+import { chmod, mkdir, rm, writeFile } from 'fs/promises';
+import { afterAll, beforeEach, describe, expect, it } from 'vitest';
+
+const tmp = createTempConfig('actions');
+
+describe('telemetry actions', () => {
+  beforeEach(() => tmp.setup());
+  afterAll(() => tmp.cleanup());
+
+  describe('handleTelemetryDisable', () => {
+    it('writes disabled config and returns confirmation', async () => {
+      const msg = await handleTelemetryDisable(tmp.configDir, tmp.configFile);
+
+      expect(msg).toBe('Telemetry has been disabled.');
+    });
+
+    it('returns warning when config write fails', async () => {
+      await rm(tmp.testDir, { recursive: true, force: true });
+      await mkdir(tmp.testDir, { recursive: true });
+      await chmod(tmp.testDir, 0o444);
+
+      const msg = await handleTelemetryDisable(tmp.configDir, tmp.configFile);
+
+      expect(msg).toBe(`Warning: could not write config to ${tmp.configFile}`);
+
+      await chmod(tmp.testDir, 0o755);
+    });
+  });
+
+  describe('handleTelemetryEnable', () => {
+    it('writes enabled config and returns confirmation', async () => {
+      const msg = await handleTelemetryEnable(tmp.configDir, tmp.configFile);
+
+      expect(msg).toBe('Telemetry has been enabled.');
+    });
+  });
+
+  describe('handleTelemetryStatus', () => {
+    it('returns enabled status with default source', async () => {
+      const lines = await handleTelemetryStatus(tmp.configFile);
+
+      expect(lines).toContain('Telemetry: Enabled');
+      expect(lines).toContain('Source: default');
+    });
+
+    it('returns disabled status with global-config source', async () => {
+      await writeFile(tmp.configFile, JSON.stringify({ telemetry: { enabled: false } }));
+
+      const lines = await handleTelemetryStatus(tmp.configFile);
+
+      expect(lines).toContain('Telemetry: Disabled');
+      expect(lines).toContain(`Source: global config (${tmp.configFile})`);
+    });
+
+    it('includes env var note when source is environment', async () => {
+      const originalEnv = process.env;
+      process.env = { ...originalEnv, AGENTCORE_TELEMETRY_DISABLED: 'true' };
+
+      const lines = await handleTelemetryStatus(tmp.configFile);
+
+      expect(lines).toContain('Telemetry: Disabled');
+      expect(lines).toContain('Source: environment variable');
+      expect(lines).toContain('\nNote: AGENTCORE_TELEMETRY_DISABLED=true is set in your environment.');
+
+      process.env = originalEnv;
+    });
+  });
+});

src/cli/commands/telemetry/actions.ts

@@ -0,0 +1,40 @@
+import { GLOBAL_CONFIG_DIR, GLOBAL_CONFIG_FILE, updateGlobalConfig } from '../../global-config.js';
+import { resolveTelemetryPreference } from '../../telemetry/resolve.js';
+
+export async function handleTelemetryDisable(
+  configDir = GLOBAL_CONFIG_DIR,
+  configFile = GLOBAL_CONFIG_FILE
+): Promise<string> {
+  const ok = await updateGlobalConfig({ telemetry: { enabled: false } }, configDir, configFile);
+  return ok ? 'Telemetry has been disabled.' : `Warning: could not write config to ${configFile}`;
+}
+
+export async function handleTelemetryEnable(
+  configDir = GLOBAL_CONFIG_DIR,
+  configFile = GLOBAL_CONFIG_FILE
+): Promise<string> {
+  const ok = await updateGlobalConfig({ telemetry: { enabled: true } }, configDir, configFile);
+  return ok ? 'Telemetry has been enabled.' : `Warning: could not write config to ${configFile}`;
+}
+
+export async function handleTelemetryStatus(configFile = GLOBAL_CONFIG_FILE): Promise<string[]> {
+  const pref = await resolveTelemetryPreference(configFile);
+
+  const status = pref.enabled ? 'Enabled' : 'Disabled';
+  const sourceLabel =
+    pref.source === 'environment'
+      ? 'environment variable'
+      : pref.source === 'global-config'
+        ? `global config (${configFile})`
+        : 'default';
+
+  const lines = [`Telemetry: ${status}`, `Source: ${sourceLabel}`];
+
+  if (pref.source === 'environment') {
+    lines.push(
+      `\nNote: AGENTCORE_TELEMETRY_DISABLED=${process.env.AGENTCORE_TELEMETRY_DISABLED} is set in your environment.`
+    );
+  }
+
+  return lines;
+}

src/cli/commands/telemetry/command.ts

@@ -0,0 +1,35 @@
+import { COMMAND_DESCRIPTIONS } from '../../tui/copy.js';
+import { handleTelemetryDisable, handleTelemetryEnable, handleTelemetryStatus } from './actions.js';
+import type { Command } from '@commander-js/extra-typings';
+
+export function registerTelemetry(program: Command) {
+  const telemetry = program
+    .command('telemetry')
+    .description(COMMAND_DESCRIPTIONS.telemetry)
+    .action(() => {
+      telemetry.outputHelp();
+    });
+
+  telemetry
+    .command('disable')
+    .description('Disable anonymous usage analytics')
+    .action(async () => {
+      console.log(await handleTelemetryDisable());
+    });
+
+  telemetry
+    .command('enable')
+    .description('Enable anonymous usage analytics')
+    .action(async () => {
+      console.log(await handleTelemetryEnable());
+    });
+
+  telemetry
+    .command('status')
+    .description('Show current telemetry preference and source')
+    .action(async () => {
+      for (const line of await handleTelemetryStatus()) {
+        console.log(line);
+      }
+    });
+}

src/cli/commands/telemetry/index.ts

@@ -0,0 +1 @@
+export { registerTelemetry } from './command.js';