@aws-blocks/core 0.1.0

package/src/scripts/index.ts

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { startDevServer, type DevServerOptions } from './dev-server.js';
+export { startSandbox, destroySandbox, type SandboxOptions } from './sandbox.js';
+export { generateClientCode, writeClientCode } from './generate-client.js';
+export { generateSpec, writeSpec } from './generate-spec.js';
+export { validateSpec, type SpecValidationError } from './validate-spec.js';
+export { deploy, type DeployOptions } from './deploy.js';
+export { destroy, type DestroyOptions } from './destroy.js';
+export { openConsole, type ConsoleOptions } from './console.js';
+export { ensureSecrets, loadProductionEnv, loadEnvFile } from './ensure-secrets.js';
+export {
+  trackCommand,
+  buildAndSendEvent,
+  classifyError,
+  type CommandName,
+  type CommandState,
+  type BuildAndSendEventOptions,
+} from '../telemetry/index.js';
+export { telemetry, type TelemetryOptions } from './telemetry.js';

package/src/scripts/sandbox.ts

@@ -0,0 +1,230 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { execFileSync, spawn } from "node:child_process";
+import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ensureSecrets, loadEnvFile } from './ensure-secrets.js';
+import { applyExternalMigrations } from './external-migrations-step.js';
+import { trackCommand } from '../telemetry/trackCommand.js';
+import { buildAndSendEvent } from '../telemetry/client.js';
+import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+
+/**
+ * Import the backend definition to populate the Scope BB registry.
+ *
+ * All BB variants set bbName/bbVersion on construction, so importing the
+ * backend is sufficient to register every block. `buildAndSendEvent` then
+ * reads the registry internally — callers don't need to pass block data.
+ * Failures are silently swallowed — telemetry is best-effort.
+ */
+async function importBackendForRegistry(backendPath: string): Promise<void> {
+  try {
+    await import(pathToFileURL(resolve(backendPath)).href);
+  } catch {
+    // best-effort — telemetry never affects the command
+  }
+}
+
+export interface SandboxOptions {
+  backendPath: string;
+  outDir?: string;
+  clientPort?: number;
+  deployOnly?: boolean;
+  /** Custom dev server command. Defaults to 'npx vite'. For Next.js use 'npx next dev'. */
+  devCommand?: string;
+}
+
+export async function startSandbox(options: SandboxOptions) {
+  const { backendPath, outDir = ".blocks-sandbox", clientPort = 3000, deployOnly = false, devCommand } = options;
+  const sandboxStartTime = Date.now();
+
+  // Load .env.local so CDK can read secret ARNs and other config.
+  try { loadEnvFile('.env.local'); } catch (e: any) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  process.env.BLOCKS_STAGE = 'sandbox';
+
+  // Provision connection string to SSM SecureString.
+  // On first deploy, creates the parameter. On subsequent deploys, updates if changed.
+  const secrets = await ensureSecrets('sandbox');
+  if (secrets.created.length > 0) {
+    console.log(`🔐 Created secrets: ${secrets.created.join(', ')}`);
+  }
+  if (secrets.updated.length > 0) {
+    console.log(`🔐 Updated secrets: ${secrets.updated.join(', ')}`);
+  }
+
+  // Apply external-database migrations to the sandbox database before
+  // deploying. No-op unless this app uses an external DB and has ./migrations.
+  await applyExternalMigrations({ stage: 'sandbox' });
+
+  // Import backend to populate Scope BB registry (for telemetry).
+  // Runs before CDK deploy so both success and failure paths include block info.
+  await importBackendForRegistry(backendPath);
+
+  console.log("🚀 Deploying to AWS...");
+  console.log("   (This may take a few minutes on first deploy)");
+
+  try {
+    execFileSync(
+      "npm",
+      [
+        "exec", "cdk", "--", "deploy",
+        "--require-approval", "never",
+        "--outputs-file", `${outDir}/outputs.json`,
+        "--context", `projectRoot=${process.cwd()}`,
+        "--context", "sandboxMode=true",
+        "--app", `npm exec tsx -- -C cdk ${backendPath}`,
+      ],
+      {
+        stdio: "inherit",
+        env: { ...process.env, NODE_OPTIONS: "--conditions=cdk", ...getCdkTelemetryEnv('sandbox') },
+      },
+    );
+  } catch (error) {
+    buildAndSendEvent({
+      command: 'sandbox',
+      state: 'FAIL',
+      duration: Date.now() - sandboxStartTime,
+      error: { code: 'CDK_DEPLOY_FAILED', phase: 'deploy' },
+    });
+    console.error("\n❌ Deployment failed.");
+    throw error;
+  }
+
+  const outputs = JSON.parse(readFileSync(`${outDir}/outputs.json`, "utf-8"));
+  const stackOutputs = Object.values(outputs)[0] as Record<string, string> || {};
+
+  const apiUrl = stackOutputs.ApiUrl;
+  if (!apiUrl) {
+    throw new Error("Could not find API URL in CDK outputs");
+  }
+
+  console.log("\n✅ Sandbox deployed!");
+  console.log(`📡 API URL: ${apiUrl}`);
+
+  buildAndSendEvent({
+    command: 'sandbox',
+    state: 'SUCCESS',
+    duration: Date.now() - sandboxStartTime,
+  });
+
+  // Write config — just apiUrl. Client middleware gets service-specific
+  // config from transferables in API responses, not from static config.
+  const config: Record<string, string> = { apiUrl, environment: 'sandbox' };
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(`${outDir}/config.json`, JSON.stringify(config, null, 2));
+
+  // Generate client code targeting AWS (aws-runtime condition ensures
+  // the backend registers aws-middleware, not mock-middleware).
+  const backendDefPath = resolve(join(dirname(resolve(backendPath)), 'index.ts'));
+  const clientPath = join(dirname(backendDefPath), 'client.js');
+  console.log('📝 Generating client code...');
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const workerPath = join(__dirname, 'generate-client-worker.js');
+  execFileSync('node', ['--conditions=aws-runtime', '--import', 'tsx', workerPath, backendDefPath, clientPath], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_OPTIONS: '' },
+  });
+
+  if (deployOnly) {
+    return apiUrl;
+  }
+
+  console.log("\n👀 Starting CDK watch mode...");
+  console.log("🌐 Starting local dev server (proxying to AWS)...");
+  console.log(`\n   Open http://localhost:${clientPort}\n`);
+
+  const cdkWatch = spawn("npx", [
+    "cdk", "watch", "--hotswap",
+    `--outputs-file`, `${outDir}/outputs.json`,
+    `--context`, `projectRoot=${process.cwd()}`,
+    `--context`, `sandboxMode=true`,
+    `--app`, `npm exec tsx -- -C cdk ${backendPath}`
+  ], {
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, NODE_OPTIONS: "--conditions=cdk", ...getCdkTelemetryEnv('sandbox') },
+  });
+
+  cdkWatch.stdout?.on("data", (data) => {
+    const str = data.toString().trim();
+    if (!str.match(/\[(START|END|REPORT|INIT_START)\s+RequestId:/)) {
+      console.log(`[CDK Watch] ${str}`);
+    }
+  });
+  cdkWatch.stderr?.on("data", (data) => {
+    console.error(`[CDK Watch] ${data.toString().trim()}`);
+  });
+
+  const devServerCmd = devCommand || `npx tsx watch aws-blocks/scripts/server.ts`;
+  const [cmd, ...args] = devServerCmd.split(' ');
+  
+  const devServer = spawn(cmd, args, {
+    stdio: "inherit",
+    shell: true,
+    env: { 
+      ...process.env,
+      NODE_OPTIONS: '',
+      BLOCKS_API_URL: apiUrl,
+    },
+  });
+
+  const cleanup = () => {
+    console.log("\n\n🛑 Stopping local processes...");
+    console.log("   (AWS resources are still running)");
+    console.log("\n   To destroy AWS resources, run: npm run sandbox:destroy\n");
+    cdkWatch.kill();
+    devServer.kill();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+
+  await new Promise(() => {});
+}
+
+export async function destroySandbox(backendPath: string) {
+  return trackCommand('sandbox:destroy', async () => {
+    console.log("🗑️  Destroying sandbox...");
+
+    // Load .env.local so CDK synth can read project refs and other config.
+    try { loadEnvFile('.env.local'); } catch (e: any) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+
+    const cdkArgs = [
+      "exec", "cdk", "--", "destroy",
+      "--force",
+      "--context", "sandboxMode=true",
+      "--app", `npm exec tsx -- -C cdk ${backendPath}`,
+    ];
+    const cdkEnv = { ...process.env, NODE_OPTIONS: "--conditions=cdk", ...getCdkTelemetryEnv('sandbox') };
+    // Retry with backoff for VPC-dependent resources (e.g. Aurora clusters).
+    // CloudFormation deletes the cluster first, but its ENIs take 60-120s to
+    // detach from the VPC subnets asynchronously. The initial destroy fails
+    // because the subnets still have attached ENIs; retrying after the cleanup
+    // window lets the VPC delete succeed.
+    const retryDelays = [60_000, 120_000]; // 1min, then 2min
+
+    for (let attempt = 0; ; attempt++) {
+      try {
+        execFileSync("npm", cdkArgs, { stdio: "inherit", env: cdkEnv });
+        console.log(attempt === 0 ? "\n✅ Sandbox destroyed!" : "\n✅ Sandbox destroyed on retry!");
+        return;
+      } catch (error) {
+        if (attempt < retryDelays.length) {
+          const delaySec = retryDelays[attempt] / 1000;
+          console.log(`\n⏳ Stack deletion failed. Retrying in ${delaySec}s (waiting for resource cleanup)...`);
+          await new Promise(r => setTimeout(r, retryDelays[attempt]));
+        } else {
+          console.error("\n❌ Destroy failed after retries.");
+          throw error;
+        }
+      }
+    }
+  });
+}

package/src/scripts/telemetry-cli.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { telemetry } from './telemetry.js';
+
+telemetry().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/scripts/telemetry.test.ts

@@ -0,0 +1,239 @@
+// 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 { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_SCRIPT = join(__dirname, 'telemetry-cli.js');
+
+/** Env overrides that clear CI detection so tests see "default enabled" state. */
+const NO_CI_ENV: Record<string, string> = {
+  CI: '',
+  CONTINUOUS_INTEGRATION: '',
+  BUILD_NUMBER: '',
+  CODEBUILD_BUILD_ID: '',
+  GITHUB_ACTIONS: '',
+  GITLAB_CI: '',
+  CIRCLECI: '',
+  JENKINS_URL: '',
+  TF_BUILD: '',
+  BITBUCKET_BUILD_NUMBER: '',
+  BUILDKITE: '',
+  AWS_BLOCKS_DISABLE_TELEMETRY: '',
+};
+
+function createTmpDir(): string {
+  const dir = join(tmpdir(), `blocks-telemetry-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function runCli(args: string[], options?: { cwd?: string; env?: Record<string, string> }): { stdout: string; stderr: string; exitCode: number } {
+  const result = spawnSync('node', [CLI_SCRIPT, ...args], {
+    cwd: options?.cwd ?? process.cwd(),
+    encoding: 'utf-8',
+    env: { ...process.env, ...options?.env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  return {
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    exitCode: result.status ?? 1,
+  };
+}
+
+describe('telemetry CLI', () => {
+  let tmpHome: string;
+  let tmpProject: string;
+
+  beforeEach(() => {
+    tmpHome = createTmpDir();
+    tmpProject = createTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(tmpHome, { recursive: true, force: true });
+    rmSync(tmpProject, { recursive: true, force: true });
+  });
+
+  describe('help', () => {
+    it('--help shows usage', () => {
+      const result = runCli(['--help'], { cwd: tmpProject, env: { HOME: tmpHome } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('--enable'));
+      assert.ok(result.stdout.includes('--disable'));
+      assert.ok(result.stdout.includes('--global'));
+    });
+
+    it('-h shows usage', () => {
+      const result = runCli(['-h'], { cwd: tmpProject, env: { HOME: tmpHome } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('--enable'));
+    });
+  });
+
+  describe('bare command (shows help)', () => {
+    it('shows usage when invoked with no arguments', () => {
+      const result = runCli([], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('Usage:'));
+      assert.ok(result.stdout.includes('--enable'));
+      assert.ok(result.stdout.includes('--disable'));
+      assert.ok(result.stdout.includes('--status'));
+    });
+  });
+
+  describe('--enable (project-level default)', () => {
+    it('creates .blocks/config.json with telemetry.enabled=true', () => {
+      const result = runCli(['--enable'], { cwd: tmpProject, env: { HOME: tmpHome } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('enabled for this project'));
+
+      const configPath = join(tmpProject, '.blocks', 'config.json');
+      assert.ok(existsSync(configPath));
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      assert.strictEqual(config.telemetry.enabled, true);
+    });
+  });
+
+  describe('--disable (project-level default)', () => {
+    it('creates .blocks/config.json with telemetry.enabled=false', () => {
+      const result = runCli(['--disable'], { cwd: tmpProject, env: { HOME: tmpHome } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('disabled for this project'));
+
+      const configPath = join(tmpProject, '.blocks', 'config.json');
+      assert.ok(existsSync(configPath));
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      assert.strictEqual(config.telemetry.enabled, false);
+    });
+  });
+
+  describe('--enable --global', () => {
+    it('creates ~/.blocks/config.json with telemetry.enabled=true', () => {
+      const result = runCli(['--enable', '--global'], { cwd: tmpProject, env: { HOME: tmpHome } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('enabled globally'));
+
+      const configPath = join(tmpHome, '.blocks', 'config.json');
+      assert.ok(existsSync(configPath));
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      assert.strictEqual(config.telemetry.enabled, true);
+    });
+
+    it('preserves existing keys in global config', () => {
+      const configDir = join(tmpHome, '.blocks');
+      mkdirSync(configDir, { recursive: true });
+      writeFileSync(join(configDir, 'config.json'), JSON.stringify({ telemetry: { projectId: 'xyz' }, someKey: 'value' }, null, 2));
+
+      const result = runCli(['--enable', '--global'], { cwd: tmpProject, env: { HOME: tmpHome } });
+      assert.strictEqual(result.exitCode, 0);
+
+      const config = JSON.parse(readFileSync(join(configDir, 'config.json'), 'utf-8'));
+      assert.strictEqual(config.telemetry.enabled, true);
+      assert.strictEqual(config.telemetry.projectId, 'xyz');
+      assert.strictEqual(config.someKey, 'value');
+    });
+  });
+
+  describe('--disable --global', () => {
+    it('creates ~/.blocks/config.json with telemetry.enabled=false', () => {
+      const result = runCli(['--disable', '--global'], { cwd: tmpProject, env: { HOME: tmpHome } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('disabled globally'));
+
+      const configPath = join(tmpHome, '.blocks', 'config.json');
+      assert.ok(existsSync(configPath));
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      assert.strictEqual(config.telemetry.enabled, false);
+    });
+  });
+
+  describe('--status (shows status)', () => {
+    it('shows enabled by default when no config exists', () => {
+      const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('Telemetry:'));
+      assert.ok(result.stdout.includes('Enabled'));
+    });
+
+    it('shows disabled when global config disables telemetry', () => {
+      const configDir = join(tmpHome, '.blocks');
+      mkdirSync(configDir, { recursive: true });
+      writeFileSync(join(configDir, 'config.json'), JSON.stringify({ telemetry: { enabled: false } }));
+
+      const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('Disabled'));
+      assert.ok(result.stdout.includes('Global config'));
+    });
+
+    it('shows disabled when env var is set to 1', () => {
+      const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV, AWS_BLOCKS_DISABLE_TELEMETRY: '1' } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('Disabled'));
+      assert.ok(result.stdout.includes('AWS_BLOCKS_DISABLE_TELEMETRY'));
+    });
+
+    it('any disable wins — project disabled even if global enabled', () => {
+      const globalConfigDir = join(tmpHome, '.blocks');
+      mkdirSync(globalConfigDir, { recursive: true });
+      writeFileSync(join(globalConfigDir, 'config.json'), JSON.stringify({ telemetry: { enabled: true } }));
+
+      const projectConfigDir = join(tmpProject, '.blocks');
+      mkdirSync(projectConfigDir, { recursive: true });
+      writeFileSync(join(projectConfigDir, 'config.json'), JSON.stringify({ telemetry: { enabled: false } }));
+
+      const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('Disabled'));
+    });
+
+    it('any disable wins — global disabled even if project enabled', () => {
+      const globalConfigDir = join(tmpHome, '.blocks');
+      mkdirSync(globalConfigDir, { recursive: true });
+      writeFileSync(join(globalConfigDir, 'config.json'), JSON.stringify({ telemetry: { enabled: false } }));
+
+      const projectConfigDir = join(tmpProject, '.blocks');
+      mkdirSync(projectConfigDir, { recursive: true });
+      writeFileSync(join(projectConfigDir, 'config.json'), JSON.stringify({ telemetry: { enabled: true } }));
+
+      const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stdout.includes('Disabled'));
+    });
+  });
+
+  describe('error handling', () => {
+    it('--enable and --disable together exits with error', () => {
+      const result = runCli(['--enable', '--disable'], { cwd: tmpProject, env: { HOME: tmpHome } });
+      assert.notStrictEqual(result.exitCode, 0);
+      assert.ok(result.stderr.includes('mutually exclusive'));
+    });
+  });
+
+  describe('unknown flags', () => {
+    it('warns about unrecognized flags but still exits 0', () => {
+      const result = runCli(['--statu'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stderr.includes('Unknown option') || result.stdout.includes('Unknown option'));
+      assert.ok(result.stderr.includes('--statu') || result.stdout.includes('--statu'));
+    });
+
+    it('recognized action still runs when unknown flags are present', () => {
+      const result = runCli(['--enable', '--typo'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+      assert.strictEqual(result.exitCode, 0);
+      assert.ok(result.stderr.includes('Unknown option') || result.stdout.includes('Unknown option'));
+      assert.ok(result.stderr.includes('--typo') || result.stdout.includes('--typo'));
+      assert.ok(result.stdout.includes('enabled for this project'));
+    });
+  });
+});

package/src/scripts/telemetry.ts

@@ -0,0 +1,173 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { getTelemetryStatus, getGlobalConfigPath, getProjectConfigPath } from '../telemetry/consent.js';
+import { writeConfigTelemetry } from '../telemetry/config-writer.js';
+
+export interface TelemetryOptions {
+  argv?: string[];
+}
+
+interface ParsedFlags {
+  action: 'enable' | 'disable' | 'status' | 'help';
+  global: boolean;
+}
+
+function printUsage(): void {
+  console.log(`Usage: npx blocks-telemetry [options]
+
+Options:
+  --enable           Enable telemetry collection
+  --disable          Disable telemetry collection
+  --status           Show current telemetry status
+  --global           Apply globally (~/.blocks/config.json)
+                     Without this flag, applies to current project (.blocks/config.json)
+  --help, -h         Show this help message
+
+Examples:
+  npx blocks-telemetry --status           # Show current status
+  npx blocks-telemetry --enable           # Enable for current project
+  npx blocks-telemetry --disable          # Disable for current project
+  npx blocks-telemetry --enable --global  # Enable globally
+  npx blocks-telemetry --disable --global # Disable globally
+
+Environment:
+  AWS_BLOCKS_DISABLE_TELEMETRY=1              Disables telemetry (overrides config files)
+`);
+}
+
+const KNOWN_FLAGS = ['--enable', '--disable', '--status', '--global', '--help', '-h'];
+
+function parseFlags(argv: string[]): ParsedFlags {
+  const args = argv.slice(2);
+
+  const unknownFlags = args.filter(a => a.startsWith('-') && !KNOWN_FLAGS.includes(a));
+  if (unknownFlags.length > 0) {
+    console.warn(`Unknown option(s): ${unknownFlags.join(', ')}. These will be ignored. Run 'npx blocks-telemetry --help' to see available options.`);
+  }
+
+  const help = args.includes('--help') || args.includes('-h');
+  const enable = args.includes('--enable');
+  const disable = args.includes('--disable');
+  const statusFlag = args.includes('--status');
+  const global = args.includes('--global');
+
+  if (enable && disable) {
+    console.error('Error: --enable and --disable are mutually exclusive.');
+    console.error('Run with --help for usage information.');
+    process.exit(1);
+  }
+
+  let action: 'enable' | 'disable' | 'status' | 'help' = 'help';
+  if (statusFlag) action = 'status';
+  if (enable) action = 'enable';
+  if (disable) action = 'disable';
+  if (help) action = 'help';
+
+  return { action, global };
+}
+
+function handleEnable(global: boolean): void {
+  const configPath = global ? getGlobalConfigPath() : getProjectConfigPath();
+
+  try {
+    writeConfigTelemetry(configPath, true);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`❌ Failed to write config: ${message}`);
+    process.exit(1);
+  }
+
+  if (global) {
+    console.log('✅ Telemetry enabled globally.');
+    console.log(`   Config: ${configPath}`);
+  } else {
+    console.log('✅ Telemetry enabled for this project.');
+    console.log(`   Config: ${configPath}`);
+  }
+}
+
+function handleDisable(global: boolean): void {
+  const configPath = global ? getGlobalConfigPath() : getProjectConfigPath();
+
+  try {
+    writeConfigTelemetry(configPath, false);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`❌ Failed to write config: ${message}`);
+    process.exit(1);
+  }
+
+  if (global) {
+    console.log('✅ Telemetry disabled globally.');
+    console.log(`   Config: ${configPath}`);
+  } else {
+    console.log('✅ Telemetry disabled for this project.');
+    console.log(`   Config: ${configPath}`);
+  }
+}
+
+function handleStatus(): void {
+  const status = getTelemetryStatus();
+
+  console.log('');
+  console.log(`  Telemetry: ${status.enabled ? '✅ Enabled' : '❌ Disabled'}`);
+  console.log('');
+
+  const globalConfigPath = getGlobalConfigPath();
+  const projectConfigPath = getProjectConfigPath();
+
+  console.log('  Mechanisms:');
+
+  if (status.envVar !== undefined) {
+    console.log(`    AWS_BLOCKS_DISABLE_TELEMETRY = "${status.envVar}"`);
+  } else {
+    console.log(`    AWS_BLOCKS_DISABLE_TELEMETRY = (not set)`);
+  }
+
+  if (status.projectConfig !== undefined) {
+    console.log(`    Project config (${projectConfigPath}): telemetry.enabled = ${status.projectConfig}`);
+  } else {
+    console.log(`    Project config (${projectConfigPath}): (not configured)`);
+  }
+
+  if (status.globalConfig !== undefined) {
+    console.log(`    Global config (${globalConfigPath}): telemetry.enabled = ${status.globalConfig}`);
+  } else {
+    console.log(`    Global config (${globalConfigPath}): (not configured)`);
+  }
+
+  console.log('');
+}
+
+/**
+ * Manage Blocks telemetry consent settings.
+ *
+ * Parses CLI flags from `process.argv` (or custom argv) and performs the
+ * requested action:
+ *
+ * - `--enable` / `--disable` — toggle telemetry (project-level by default, `--global` for global)
+ * - `--status` — display current telemetry status and mechanism values
+ * - bare invocation (no flags) — prints help/usage text
+ *
+ * @param options.argv - Custom argv array (defaults to process.argv)
+ */
+export async function telemetry(options?: TelemetryOptions): Promise<void> {
+  const argv = options?.argv ?? process.argv;
+  const flags = parseFlags(argv);
+
+  switch (flags.action) {
+    case 'enable':
+      handleEnable(flags.global);
+      break;
+    case 'disable':
+      handleDisable(flags.global);
+      break;
+    case 'status':
+      handleStatus();
+      break;
+    case 'help':
+      printUsage();
+      break;
+  }
+}