@aws-blocks/core 0.1.0

package/src/telemetry/consent-commands.test.ts

@@ -0,0 +1,196 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { getTelemetryStatus, getGlobalConfigPath, getProjectConfigPath } from './consent.js';
+import { writeConfigTelemetry } from './config-writer.js';
+
+describe('getTelemetryStatus', () => {
+  const originalEnv = { ...process.env };
+  const originalCwd = process.cwd();
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+    process.chdir(originalCwd);
+  });
+
+  function clearCIVars(): void {
+    delete process.env.CI;
+    delete process.env.CONTINUOUS_INTEGRATION;
+    delete process.env.BUILD_NUMBER;
+    delete process.env.CODEBUILD_BUILD_ID;
+    delete process.env.GITHUB_ACTIONS;
+    delete process.env.GITLAB_CI;
+    delete process.env.CIRCLECI;
+    delete process.env.JENKINS_URL;
+    delete process.env.TF_BUILD;
+    delete process.env.BITBUCKET_BUILD_NUMBER;
+    delete process.env.BUILDKITE;
+  }
+
+  it('returns enabled=true when no config exists and not in CI', () => {
+    delete process.env.AWS_BLOCKS_DISABLE_TELEMETRY;
+    clearCIVars();
+    const tmp = join(tmpdir(), `blocks-status-test-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    process.chdir(tmp);
+
+    const status = getTelemetryStatus();
+    assert.strictEqual(status.enabled, true);
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('returns enabled=false when AWS_BLOCKS_DISABLE_TELEMETRY=1', () => {
+    process.env.AWS_BLOCKS_DISABLE_TELEMETRY = '1';
+    const tmp = join(tmpdir(), `blocks-status-test-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    process.chdir(tmp);
+
+    const status = getTelemetryStatus();
+    assert.strictEqual(status.enabled, false);
+    assert.strictEqual(status.envVar, '1');
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('returns enabled=false when project config disables', () => {
+    delete process.env.AWS_BLOCKS_DISABLE_TELEMETRY;
+    clearCIVars();
+    const tmp = join(tmpdir(), `blocks-status-test-${Date.now()}`);
+    mkdirSync(join(tmp, '.blocks'), { recursive: true });
+    writeFileSync(join(tmp, '.blocks', 'config.json'), JSON.stringify({ telemetry: { enabled: false } }));
+    process.chdir(tmp);
+
+    const status = getTelemetryStatus();
+    assert.strictEqual(status.enabled, false);
+    assert.strictEqual(status.projectConfig, false);
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('any disable wins — global disabled even if project enables', () => {
+    delete process.env.AWS_BLOCKS_DISABLE_TELEMETRY;
+    clearCIVars();
+    const tmp = join(tmpdir(), `blocks-status-test-${Date.now()}`);
+    mkdirSync(join(tmp, '.blocks'), { recursive: true });
+    writeFileSync(join(tmp, '.blocks', 'config.json'), JSON.stringify({ telemetry: { enabled: true } }));
+    process.chdir(tmp);
+
+    // Simulate global config disabling (via projectRoot override for global path won't work here,
+    // but we can test that project enabled=true alone is fine)
+    const status = getTelemetryStatus();
+    assert.strictEqual(status.enabled, true);
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('env var disables even when project config enables', () => {
+    process.env.AWS_BLOCKS_DISABLE_TELEMETRY = '1';
+    const tmp = join(tmpdir(), `blocks-status-test-${Date.now()}`);
+    mkdirSync(join(tmp, '.blocks'), { recursive: true });
+    writeFileSync(join(tmp, '.blocks', 'config.json'), JSON.stringify({ telemetry: { enabled: true } }));
+    process.chdir(tmp);
+
+    const status = getTelemetryStatus();
+    assert.strictEqual(status.enabled, false);
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('returns enabled=true in CI environment (CI does not suppress telemetry)', () => {
+    delete process.env.AWS_BLOCKS_DISABLE_TELEMETRY;
+    process.env.CI = 'true';
+    const tmp = join(tmpdir(), `blocks-status-test-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    process.chdir(tmp);
+
+    const status = getTelemetryStatus();
+    assert.strictEqual(status.enabled, true);
+    rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+describe('writeConfigTelemetry', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = join(tmpdir(), `blocks-writer-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(tmpDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('creates a new config file with telemetry.enabled', () => {
+    const configPath = join(tmpDir, '.blocks', 'config.json');
+    writeConfigTelemetry(configPath, true);
+
+    assert.ok(existsSync(configPath));
+    const content = JSON.parse(readFileSync(configPath, 'utf-8'));
+    assert.strictEqual(content.telemetry.enabled, true);
+  });
+
+  it('writes telemetry.enabled=false', () => {
+    const configPath = join(tmpDir, '.blocks', 'config.json');
+    writeConfigTelemetry(configPath, false);
+
+    const content = JSON.parse(readFileSync(configPath, 'utf-8'));
+    assert.strictEqual(content.telemetry.enabled, false);
+  });
+
+  it('preserves existing keys when writing', () => {
+    const configPath = join(tmpDir, 'config.json');
+    writeFileSync(configPath, JSON.stringify({ telemetry: { projectId: 'abc-123' }, other: 'data' }, null, 2));
+
+    writeConfigTelemetry(configPath, false);
+
+    const content = JSON.parse(readFileSync(configPath, 'utf-8'));
+    assert.strictEqual(content.telemetry.enabled, false);
+    assert.strictEqual(content.telemetry.projectId, 'abc-123');
+    assert.strictEqual(content.other, 'data');
+  });
+
+  it('creates parent directories if they do not exist', () => {
+    const configPath = join(tmpDir, 'deep', 'nested', 'config.json');
+    writeConfigTelemetry(configPath, true);
+
+    assert.ok(existsSync(configPath));
+    const content = JSON.parse(readFileSync(configPath, 'utf-8'));
+    assert.strictEqual(content.telemetry.enabled, true);
+  });
+
+  it('overwrites telemetry.enabled without affecting other telemetry keys', () => {
+    const configPath = join(tmpDir, 'config.json');
+    writeFileSync(configPath, JSON.stringify({ telemetry: { enabled: true, projectId: 'xyz' } }));
+
+    writeConfigTelemetry(configPath, false);
+
+    const content = JSON.parse(readFileSync(configPath, 'utf-8'));
+    assert.strictEqual(content.telemetry.enabled, false);
+    assert.strictEqual(content.telemetry.projectId, 'xyz');
+  });
+});
+
+describe('getProjectConfigPath', () => {
+  it('uses cwd by default', () => {
+    const result = getProjectConfigPath();
+    assert.ok(result.endsWith('.blocks/config.json'));
+    assert.ok(result.startsWith(process.cwd()));
+  });
+
+  it('accepts a custom project root', () => {
+    const custom = '/some/custom/path';
+    const result = getProjectConfigPath(custom);
+    assert.ok(result.startsWith(custom));
+    assert.ok(result.endsWith('.blocks/config.json'));
+  });
+});
+
+describe('getGlobalConfigPath', () => {
+  it('uses homedir', () => {
+    const result = getGlobalConfigPath();
+    assert.ok(result.endsWith('.blocks/config.json'));
+  });
+});

package/src/telemetry/consent.ts

@@ -0,0 +1,154 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const ENV_VAR = 'AWS_BLOCKS_DISABLE_TELEMETRY';
+
+interface BlocksConfig {
+  telemetry?: { enabled?: boolean };
+  [key: string]: unknown;
+}
+
+/**
+ * Read and parse a Blocks config file, returning null if it doesn't exist or is invalid.
+ */
+export function readConfigFile(configPath: string): BlocksConfig | null {
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    return JSON.parse(content) as BlocksConfig;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the path to the global Blocks config file (~/.blocks/config.json).
+ */
+export function getGlobalConfigPath(): string {
+  return join(homedir(), '.blocks', 'config.json');
+}
+
+/**
+ * Get the path to the project-level Blocks config file (.blocks/config.json).
+ *
+ * @param projectRoot - Optional project root directory (defaults to process.cwd())
+ */
+export function getProjectConfigPath(projectRoot?: string): string {
+  return join(projectRoot ?? process.cwd(), '.blocks', 'config.json');
+}
+
+/**
+ * Result of a detailed telemetry status check.
+ */
+export interface TelemetryStatus {
+  /** Whether telemetry is currently enabled (final resolved value). */
+  enabled: boolean;
+  /** Value of AWS_BLOCKS_DISABLE_TELEMETRY env var if set. */
+  envVar?: string;
+  /** Value from global config if present. */
+  globalConfig?: boolean;
+  /** Value from project config if present. */
+  projectConfig?: boolean;
+}
+
+/**
+ * Get detailed telemetry status showing all mechanism values and the final result.
+ *
+ * Telemetry is enabled by default. If any mechanism disables it, telemetry is off:
+ * - `AWS_BLOCKS_DISABLE_TELEMETRY=1` env var
+ * - `.blocks/config.json` → `telemetry.enabled: false` (per-project)
+ * - `~/.blocks/config.json` → `telemetry.enabled: false` (global)
+ *
+ * @param projectRoot - Optional project root directory (defaults to process.cwd())
+ */
+export function getTelemetryStatus(projectRoot?: string): TelemetryStatus {
+  const envValue = process.env[ENV_VAR];
+  const globalConfig = readConfigFile(getGlobalConfigPath());
+  const projectConfig = readConfigFile(getProjectConfigPath(projectRoot));
+
+  const globalEnabled = globalConfig?.telemetry?.enabled;
+  const projectEnabled = projectConfig?.telemetry?.enabled;
+
+  const status: TelemetryStatus = {
+    enabled: true,
+  };
+
+  if (envValue !== undefined && envValue !== '') {
+    status.envVar = envValue;
+  }
+  if (typeof globalEnabled === 'boolean') {
+    status.globalConfig = globalEnabled;
+  }
+  if (typeof projectEnabled === 'boolean') {
+    status.projectConfig = projectEnabled;
+  }
+
+  if (envValue === '1') {
+    status.enabled = false;
+    return status;
+  }
+
+  if (status.projectConfig === false) {
+    status.enabled = false;
+    return status;
+  }
+
+  if (status.globalConfig === false) {
+    status.enabled = false;
+    return status;
+  }
+
+  return status;
+}
+
+/**
+ * Determine whether telemetry collection is enabled.
+ *
+ * Disable mechanisms (any one disables telemetry):
+ * - `AWS_BLOCKS_DISABLE_TELEMETRY=1` env var
+ * - `.blocks/config.json` → `telemetry.enabled: false` (per-project)
+ * - `~/.blocks/config.json` → `telemetry.enabled: false` (global)
+ *
+ * Default: enabled (if no disable mechanism is active)
+ *
+ * Note: CI environments do NOT suppress telemetry. CI detection is used
+ * only as metadata in the telemetry payload (environment.ci field).
+ */
+export function isTelemetryEnabled(): boolean {
+  if (process.env[ENV_VAR] === '1') {
+    return false;
+  }
+
+  // Per-project config
+  try {
+    const projectConfigPath = join(process.cwd(), '.blocks', 'config.json');
+    const content = readFileSync(projectConfigPath, 'utf-8');
+    const config: BlocksConfig = JSON.parse(content);
+    if (config.telemetry?.enabled === false) {
+      return false;
+    }
+    if (config.telemetry?.enabled === true) {
+      return true;
+    }
+  } catch {
+    // No project config or invalid JSON
+  }
+
+  // Global config
+  try {
+    const globalConfigPath = join(homedir(), '.blocks', 'config.json');
+    const content = readFileSync(globalConfigPath, 'utf-8');
+    const config: BlocksConfig = JSON.parse(content);
+    if (config.telemetry?.enabled === false) {
+      return false;
+    }
+    if (config.telemetry?.enabled === true) {
+      return true;
+    }
+  } catch {
+    // No global config or invalid JSON
+  }
+
+  // Default: enabled
+  return true;
+}

package/src/telemetry/environment.ts

@@ -0,0 +1,100 @@
+import { platform } from 'node:os';
+
+/**
+ * Detect the OS platform.
+ */
+export function detectOS(): 'linux' | 'darwin' | 'win32' {
+  return platform() as 'linux' | 'darwin' | 'win32';
+}
+
+/**
+ * Detect the Node.js version string (without the leading 'v').
+ */
+export function detectNodeVersion(): string {
+  return process.versions.node;
+}
+
+/**
+ * Detect whether the current process is running inside a CI/CD environment.
+ */
+export function isCI(): boolean {
+  return !!(
+    process.env.CI ||
+    process.env.CONTINUOUS_INTEGRATION ||
+    process.env.BUILD_NUMBER ||
+    process.env.CODEBUILD_BUILD_ID ||
+    process.env.GITHUB_ACTIONS ||
+    process.env.GITLAB_CI ||
+    process.env.CIRCLECI ||
+    process.env.JENKINS_URL ||
+    process.env.TF_BUILD ||
+    process.env.BITBUCKET_BUILD_NUMBER ||
+    process.env.BUILDKITE
+  );
+}
+
+/**
+ * Detect the package manager from npm_config_user_agent.
+ * Returns the raw user agent string (e.g., "npm/10.2.0 node/v22.0.0").
+ */
+export function detectPackageManager(): string | undefined {
+  return process.env.npm_config_user_agent || undefined;
+}
+
+/**
+ * Detect if the current execution is driven by an AI agent.
+ * Uses the "am-i-vibing" pattern and checks known environment variables.
+ */
+export function detectAgent(): string | undefined {
+  if (process.env.CLAUDECODE) return 'claude-code';
+  if (process.env.CURSOR_TRACE_ID) return 'cursor';
+  if (process.env.CODEX_CLI_VERSION || process.env.CODEX_SESSION_ID) return 'codex';
+  if (process.env.CLINE_TASK_ID || process.env.CLINE_SESSION_ID) return 'cline';
+  if (process.env.CODEIUM_EDITOR_APP_ROOT || process.env.WINDSURF_SESSION_ID) return 'windsurf';
+  if (process.env.GEMINI_CLI) return 'gemini-cli';
+  if (process.env.REPL_ID && process.env.REPL_OWNER) return 'replit-agent';
+  if (process.env.AIDER_MODEL || process.env.AIDER_SESSION) return 'aider';
+  if (process.env.CONTINUE_GLOBAL_DIR) return 'continue';
+  if (process.env.ROOCODE_SESSION_ID || process.env.ROO_SESSION_ID) return 'roo-code';
+
+  const awsExecEnv = process.env.AWS_EXECUTION_ENV || '';
+  if (awsExecEnv.toLowerCase().includes('amazonq')) return 'amazon-q';
+  if (awsExecEnv.toLowerCase().includes('kiro')) return 'kiro';
+
+  return undefined;
+}
+
+/**
+ * Collect all environment information needed for a telemetry event.
+ */
+export function collectEnvironment(): {
+  os: 'linux' | 'darwin' | 'win32';
+  nodeVersion: string;
+  ci: boolean;
+  packageManager?: string;
+  agent?: string;
+} {
+  const env: {
+    os: 'linux' | 'darwin' | 'win32';
+    nodeVersion: string;
+    ci: boolean;
+    packageManager?: string;
+    agent?: string;
+  } = {
+    os: detectOS(),
+    nodeVersion: detectNodeVersion(),
+    ci: isCI(),
+  };
+
+  const packageManager = detectPackageManager();
+  if (packageManager) {
+    env.packageManager = packageManager;
+  }
+
+  const agent = detectAgent();
+  if (agent) {
+    env.agent = agent;
+  }
+
+  return env;
+}

package/src/telemetry/identifiers.ts

@@ -0,0 +1,94 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+const FIRST_RUN_NOTICE = `
+AWS Blocks collects anonymous usage data to improve the product.
+No customer content or PII is collected.
+To disable: npx blocks-telemetry --disable (or export AWS_BLOCKS_DISABLE_TELEMETRY=1)
+`;
+
+interface BlocksConfig {
+  telemetry?: { enabled?: boolean; projectId?: string };
+  [key: string]: unknown;
+}
+
+/**
+ * Get or create a persistent installation ID.
+ * Stored at `~/.blocks/telemetry/installation-id`.
+ * Generated as UUID v4 on first use.
+ *
+ * On first creation, prints a one-time notice to stderr informing
+ * the user about telemetry collection.
+ */
+export function getInstallationId(): string {
+  const filePath = join(homedir(), '.blocks', 'telemetry', 'installation-id');
+
+  try {
+    const existing = readFileSync(filePath, 'utf-8').trim();
+    if (existing) return existing;
+  } catch {
+    // File doesn't exist yet
+  }
+
+  const id = randomUUID();
+  try {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filePath, id, 'utf-8');
+  } catch {
+    // If we can't persist, still return the generated ID for this session
+  }
+  process.stderr.write(FIRST_RUN_NOTICE + '\n');
+  return id;
+}
+
+/**
+ * Get or create a persistent project ID.
+ * Stored in `.blocks/config.json` under `telemetry.projectId` in the project root (cwd).
+ * Generated as UUID v4 on first use.
+ */
+export function getProjectId(): string {
+  const configPath = join(process.cwd(), '.blocks', 'config.json');
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const config: BlocksConfig = JSON.parse(content);
+    if (config.telemetry?.projectId) return config.telemetry.projectId;
+  } catch {
+    // File doesn't exist or invalid JSON
+  }
+
+  const id = randomUUID();
+  try {
+    const dir = dirname(configPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // Preserve existing config if present
+    let config: BlocksConfig = {};
+    try {
+      const existing = readFileSync(configPath, 'utf-8');
+      config = JSON.parse(existing);
+    } catch {
+      // No existing config
+    }
+
+    config.telemetry = { ...config.telemetry, projectId: id };
+    writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+  } catch {
+    // If we can't persist, still return the generated ID for this session
+  }
+  return id;
+}
+
+/**
+ * Generate a fresh UUID v4 event ID.
+ */
+export function generateEventId(): string {
+  return randomUUID();
+}

package/src/telemetry/index.ts

@@ -0,0 +1,11 @@
+export { trackCommand, classifyError } from './trackCommand.js';
+export { buildAndSendEvent, buildEvent } from './client.js';
+export type { CommandName, CommandState, BuildAndSendEventOptions } from './types.js';
+export {
+  isTelemetryEnabled,
+  getTelemetryStatus,
+  getGlobalConfigPath,
+  getProjectConfigPath,
+  type TelemetryStatus,
+} from './consent.js';
+export { writeConfigTelemetry } from './config-writer.js';