@aws-blocks/core 0.1.0

package/dist/telemetry/client.js

@@ -0,0 +1,215 @@
+import { request as httpsRequest } from 'node:https';
+import { request as httpRequest } from 'node:http';
+import { existsSync, readFileSync, mkdirSync, openSync, writeSync, closeSync, writeFileSync, constants } from 'node:fs';
+import path from 'node:path';
+import { debuglog } from 'node:util';
+import { CORE_VERSION } from '../version.js';
+import { Scope } from '../common/index.js';
+import { isTelemetryEnabled } from './consent.js';
+import { collectEnvironment } from './environment.js';
+import { getInstallationId, getProjectId, generateEventId } from './identifiers.js';
+// Debug log: writes to stderr via NODE_DEBUG=blocks-telemetry (developer-facing, for troubleshooting)
+const debug = debuglog('blocks-telemetry');
+const DEFAULT_ENDPOINT = 'https://blocks-telemetry.us-east-1.api.aws/metrics';
+const TIMEOUT_MS = 500;
+const TELEMETRY_VERSION = '1.0.0';
+function getEndpoint() {
+    return process.env.BLOCKS_TELEMETRY_ENDPOINT || DEFAULT_ENDPOINT;
+}
+/**
+ * Parse `--telemetry-file=/path/to/file.json` from process.argv.
+ *
+ * Supports both `--telemetry-file=path` and `--telemetry-file path` forms.
+ *
+ * @returns The file path if the flag is present, undefined otherwise.
+ *
+ * @example
+ * // Capture telemetry to file (also sends HTTP when enabled):
+ * // npx tsx aws-blocks/scripts/server.ts --telemetry-file=/tmp/events.json
+ *
+ * // Capture WITHOUT sending (disable HTTP, file still writes):
+ * // AWS_BLOCKS_DISABLE_TELEMETRY=1 npx tsx aws-blocks/scripts/server.ts --telemetry-file=/tmp/events.json
+ */
+export function getTelemetryFilePath() {
+    const arg = process.argv.find(a => a.startsWith('--telemetry-file='));
+    if (arg) {
+        const p = arg.slice('--telemetry-file='.length);
+        return p.trim() === '' ? undefined : p;
+    }
+    const idx = process.argv.indexOf('--telemetry-file');
+    if (idx !== -1 && process.argv[idx + 1] && !process.argv[idx + 1].startsWith('-')) {
+        return process.argv[idx + 1];
+    }
+    return undefined;
+}
+// File sink: writes to --telemetry-file path (user-facing, for debugging/testing)
+function writeToTelemetryFile(event) {
+    const filePath = getTelemetryFilePath();
+    if (!filePath)
+        return; // getTelemetryFilePath already rejects empty/whitespace
+    try {
+        const dir = path.dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        // O_CREAT | O_EXCL: atomic create — fails with EEXIST if file already exists
+        const fd = openSync(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+        const content = JSON.stringify([event], null, 2);
+        writeSync(fd, content);
+        closeSync(fd);
+    }
+    catch (err) {
+        // EEXIST = file already existed → skip (protects user data)
+        // All other errors silently ignored — telemetry must never affect commands
+    }
+}
+/**
+ * Constructs a telemetry event without sending it.
+ * Useful for testing event structure without I/O side effects.
+ * @internal
+ */
+export function buildEvent(opts) {
+    const { blocks, totalCount, customBlocksCount } = Scope.getRegisteredBlocks();
+    let templateName = opts.product?.template;
+    let templateVersion = opts.product?.templateVersion;
+    try {
+        const pkgPath = path.resolve(process.cwd(), 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            if (pkg.blocksTemplate)
+                templateName = templateName || pkg.blocksTemplate;
+            if (pkg.blocksTemplateVersion)
+                templateVersion = templateVersion || pkg.blocksTemplateVersion;
+        }
+    }
+    catch {
+        // template info is best-effort
+    }
+    const buildingBlocks = blocks;
+    return {
+        telemetryVersion: TELEMETRY_VERSION,
+        identifiers: {
+            installationId: getInstallationId(),
+            projectId: getProjectId(),
+            eventId: generateEventId(),
+            timestamp: new Date().toISOString(),
+        },
+        event: {
+            command: opts.command,
+            state: opts.state,
+            duration: opts.duration,
+            ...(opts.error && { error: opts.error }),
+        },
+        environment: collectEnvironment(),
+        product: {
+            blocksVersion: CORE_VERSION,
+            ...(opts.product?.cdkVersion && { cdkVersion: opts.product.cdkVersion }),
+            ...(opts.product?.framework && { framework: opts.product.framework }),
+            ...(templateName && {
+                template: {
+                    name: templateName,
+                    ...(templateVersion && { version: templateVersion }),
+                },
+            }),
+            ...(buildingBlocks.length > 0 && { buildingBlocks }),
+        },
+        ...(opts.counters || totalCount > 0 || customBlocksCount > 0
+            ? {
+                counters: {
+                    blocksCount: opts.counters?.blocksCount ?? totalCount,
+                    ...(opts.counters?.customBuildingBlocks !== undefined
+                        ? { customBuildingBlocks: opts.counters.customBuildingBlocks }
+                        : customBlocksCount > 0 ? { customBuildingBlocks: customBlocksCount } : undefined),
+                },
+            }
+            : undefined),
+    };
+}
+/**
+ * Build a complete telemetry event and send it to the collection endpoint.
+ *
+ * This is the single entry point for all telemetry emission. It handles:
+ * 1. Early exit — if telemetry is disabled AND no `--telemetry-file` is set,
+ *    returns immediately with no side effects (no IDs persisted, no notice)
+ * 2. Full payload construction (identifiers, environment, product info)
+ * 3. File sink — writes to the file specified by `--telemetry-file` (if set),
+ *    regardless of opt-out status (inspired by CDK CLI's --telemetry-file)
+ * 4. Privacy filtering — custom BB names are NEVER sent, only counted
+ * 5. HTTP sink — fire-and-forget POST (only when telemetry is enabled)
+ *
+ * The file sink fires unconditionally when `--telemetry-file` is set.
+ * The HTTP sink only fires when telemetry is enabled. Callers never need to
+ * import consent, identifier, or environment utilities directly.
+ *
+ * @param opts - Event metadata (command, state, duration, optional error/product/counters)
+ *
+ * @example
+ * ```ts
+ * buildAndSendEvent({
+ *   command: 'deploy',
+ *   state: 'SUCCESS',
+ *   duration: 4500,
+ *   product: { cdkVersion: '2.150.0' },
+ * });
+ * ```
+ */
+export function buildAndSendEvent(opts) {
+    try {
+        const filePath = getTelemetryFilePath();
+        const enabled = isTelemetryEnabled();
+        if (!filePath && !enabled)
+            return;
+        const event = buildEvent(opts);
+        if (filePath)
+            writeToTelemetryFile(event);
+        if (enabled)
+            sendEvent(event);
+    }
+    catch {
+        // Telemetry must never throw or affect the user's command
+    }
+}
+/**
+ * Send a pre-built telemetry event to the collection endpoint.
+ *
+ * Fire-and-forget: no retry, 500ms timeout, all errors silently swallowed.
+ * Debug output available via `NODE_DEBUG=blocks-telemetry`.
+ */
+export function sendEvent(event) {
+    try {
+        const endpoint = getEndpoint();
+        const payload = JSON.stringify(event);
+        // E2E test sink: writes to BLOCKS_TELEMETRY_FILE env path (test-facing, for assertions)
+        if (process.env.BLOCKS_TELEMETRY_FILE) {
+            try {
+                writeFileSync(process.env.BLOCKS_TELEMETRY_FILE, payload);
+            }
+            catch { }
+        }
+        debug('sending event to %s (%d bytes)', endpoint, Buffer.byteLength(payload));
+        const url = new URL(endpoint);
+        const isHttps = url.protocol === 'https:';
+        const requestFn = isHttps ? httpsRequest : httpRequest;
+        const req = requestFn({
+            hostname: url.hostname,
+            port: url.port || (isHttps ? '443' : '80'),
+            path: url.pathname + url.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(payload),
+            },
+            timeout: TIMEOUT_MS,
+        }, (res) => {
+            debug('event sent (status=%d)', res.statusCode);
+            res.resume();
+        });
+        req.on('error', (err) => { debug('send failed: %s', err.message); });
+        req.on('timeout', () => { debug('send timed out'); req.destroy(); });
+        req.write(payload);
+        req.end();
+    }
+    catch {
+        // Telemetry must never throw or affect the user's command
+    }
+}

package/dist/telemetry/config-writer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Read an existing config file, merge the telemetry.enabled setting, and write it back.
+ * Creates the file and parent directories if they don't exist.
+ * Preserves all other keys in the config file and in the telemetry object
+ * (e.g., projectId).
+ *
+ * Config format:
+ * ```json
+ * { "telemetry": { "enabled": true, "projectId": "..." } }
+ * ```
+ *
+ * @param configPath - Absolute path to the config file
+ * @param telemetryEnabled - Whether telemetry should be enabled
+ */
+export declare function writeConfigTelemetry(configPath: string, telemetryEnabled: boolean): void;
+//# sourceMappingURL=config-writer.d.ts.map

package/dist/telemetry/config-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-writer.d.ts","sourceRoot":"","sources":["../../src/telemetry/config-writer.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAoBxF"}

package/dist/telemetry/config-writer.js

@@ -0,0 +1,36 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Read an existing config file, merge the telemetry.enabled setting, and write it back.
+ * Creates the file and parent directories if they don't exist.
+ * Preserves all other keys in the config file and in the telemetry object
+ * (e.g., projectId).
+ *
+ * Config format:
+ * ```json
+ * { "telemetry": { "enabled": true, "projectId": "..." } }
+ * ```
+ *
+ * @param configPath - Absolute path to the config file
+ * @param telemetryEnabled - Whether telemetry should be enabled
+ */
+export function writeConfigTelemetry(configPath, telemetryEnabled) {
+    let existing = {};
+    try {
+        const content = readFileSync(configPath, 'utf-8');
+        existing = JSON.parse(content);
+    }
+    catch {
+        // File doesn't exist or is invalid — start fresh
+    }
+    const telemetry = (existing.telemetry && typeof existing.telemetry === 'object')
+        ? { ...existing.telemetry }
+        : {};
+    telemetry.enabled = telemetryEnabled;
+    existing.telemetry = telemetry;
+    const dir = dirname(configPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+}

package/dist/telemetry/consent-commands.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=consent-commands.test.d.ts.map

package/dist/telemetry/consent-commands.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-commands.test.d.ts","sourceRoot":"","sources":["../../src/telemetry/consent-commands.test.ts"],"names":[],"mappings":""}

package/dist/telemetry/consent-commands.test.js

@@ -0,0 +1,161 @@
+// 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() {
+        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;
+    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/dist/telemetry/consent.d.ts

@@ -0,0 +1,60 @@
+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 declare function readConfigFile(configPath: string): BlocksConfig | null;
+/**
+ * Get the path to the global Blocks config file (~/.blocks/config.json).
+ */
+export declare function getGlobalConfigPath(): string;
+/**
+ * Get the path to the project-level Blocks config file (.blocks/config.json).
+ *
+ * @param projectRoot - Optional project root directory (defaults to process.cwd())
+ */
+export declare function getProjectConfigPath(projectRoot?: string): string;
+/**
+ * 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 declare function getTelemetryStatus(projectRoot?: string): TelemetryStatus;
+/**
+ * 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 declare function isTelemetryEnabled(): boolean;
+export {};
+//# sourceMappingURL=consent.d.ts.map

package/dist/telemetry/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/telemetry/consent.ts"],"names":[],"mappings":"AAMA,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAOtE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,eAAe,CAsCxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAqC5C"}

package/dist/telemetry/consent.js

@@ -0,0 +1,122 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const ENV_VAR = 'AWS_BLOCKS_DISABLE_TELEMETRY';
+/**
+ * Read and parse a Blocks config file, returning null if it doesn't exist or is invalid.
+ */
+export function readConfigFile(configPath) {
+    try {
+        const content = readFileSync(configPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the path to the global Blocks config file (~/.blocks/config.json).
+ */
+export function getGlobalConfigPath() {
+    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) {
+    return join(projectRoot ?? process.cwd(), '.blocks', 'config.json');
+}
+/**
+ * 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) {
+    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 = {
+        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() {
+    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 = 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 = 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/dist/telemetry/environment.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Detect the OS platform.
+ */
+export declare function detectOS(): 'linux' | 'darwin' | 'win32';
+/**
+ * Detect the Node.js version string (without the leading 'v').
+ */
+export declare function detectNodeVersion(): string;
+/**
+ * Detect whether the current process is running inside a CI/CD environment.
+ */
+export declare function isCI(): boolean;
+/**
+ * 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 declare function detectPackageManager(): string | undefined;
+/**
+ * Detect if the current execution is driven by an AI agent.
+ * Uses the "am-i-vibing" pattern and checks known environment variables.
+ */
+export declare function detectAgent(): string | undefined;
+/**
+ * Collect all environment information needed for a telemetry event.
+ */
+export declare function collectEnvironment(): {
+    os: 'linux' | 'darwin' | 'win32';
+    nodeVersion: string;
+    ci: boolean;
+    packageManager?: string;
+    agent?: string;
+};
+//# sourceMappingURL=environment.d.ts.map

package/dist/telemetry/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/telemetry/environment.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,QAAQ,IAAI,OAAO,GAAG,QAAQ,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAc9B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAEzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,GAAG,SAAS,CAiBhD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,EAAE,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAwBA"}