@aws-blocks/core 0.1.0

package/dist/scripts/generate-spec.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Integration test for `generateSpec`. Builds a tiny backend file with one
+ * normal method and one `@blocksSkipCodegen`-tagged method, runs the spec
+ * emitter, and asserts the tagged method is dropped from the OpenRPC
+ * document.
+ *
+ * Uses a `.js` foundation file so plain `node --test dist/...` can run the
+ * test without a TypeScript loader. The TS compiler still parses JSDoc on
+ * the `.js` file when `allowJs` is enabled in the synthetic tsconfig.
+ */
+export {};
+//# sourceMappingURL=generate-spec.test.d.ts.map

package/dist/scripts/generate-spec.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-spec.test.d.ts","sourceRoot":"","sources":["../../src/scripts/generate-spec.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/scripts/generate-spec.test.js

@@ -0,0 +1,88 @@
+/**
+ * Integration test for `generateSpec`. Builds a tiny backend file with one
+ * normal method and one `@blocksSkipCodegen`-tagged method, runs the spec
+ * emitter, and asserts the tagged method is dropped from the OpenRPC
+ * document.
+ *
+ * Uses a `.js` foundation file so plain `node --test dist/...` can run the
+ * test without a TypeScript loader. The TS compiler still parses JSDoc on
+ * the `.js` file when `allowJs` is enabled in the synthetic tsconfig.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { tmpdir } from 'os';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { generateSpec } from './generate-spec.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// `import.meta.url` lives in dist/scripts/, so `..` is dist/ and the built
+// `api.js` is next to it. Re-using the real ApiNamespace ensures the marker
+// symbol matches what `generateSpec` discovers.
+const builtApiUrl = pathToFileURL(join(__dirname, '..', 'api.js')).href;
+function writeTsconfig(dir) {
+    writeFileSync(join(dir, 'tsconfig.json'), JSON.stringify({
+        compilerOptions: {
+            target: 'ESNext',
+            module: 'ESNext',
+            moduleResolution: 'bundler',
+            allowJs: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+    }));
+}
+describe('generateSpec — @blocksSkipCodegen', () => {
+    it('drops methods carrying @blocksSkipCodegen from the OpenRPC document', async () => {
+        const dir = join(tmpdir(), `blocks-spec-test-${Date.now()}-skip`);
+        mkdirSync(dir, { recursive: true });
+        writeTsconfig(dir);
+        writeFileSync(join(dir, 'index.js'), `
+			import { ApiNamespace } from ${JSON.stringify(builtApiUrl)};
+
+			export const api = new ApiNamespace(null, 'api', (context) => ({
+				async normalMethod(name) {
+					return { greeting: 'hi ' + name };
+				},
+
+				/**
+				 * Mock-only helper.
+				 * @blocksSkipCodegen
+				 */
+				async getLastCode() {
+					return null;
+				},
+			}));
+		`);
+        try {
+            const doc = await generateSpec(join(dir, 'index.js'));
+            const methodNames = doc.methods.map((m) => m.name).sort();
+            assert.deepStrictEqual(methodNames, ['api.normalMethod'], 'getLastCode should be omitted; only normalMethod should remain');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('keeps methods that do not carry the tag', async () => {
+        const dir = join(tmpdir(), `blocks-spec-test-${Date.now()}-keep`);
+        mkdirSync(dir, { recursive: true });
+        writeTsconfig(dir);
+        writeFileSync(join(dir, 'index.js'), `
+			import { ApiNamespace } from ${JSON.stringify(builtApiUrl)};
+
+			export const api = new ApiNamespace(null, 'api', (context) => ({
+				/** Plain JSDoc with no special tag. */
+				async ping() { return { ok: true }; },
+				async echo(s) { return s; },
+			}));
+		`);
+        try {
+            const doc = await generateSpec(join(dir, 'index.js'));
+            const methodNames = doc.methods.map((m) => m.name).sort();
+            assert.deepStrictEqual(methodNames, ['api.echo', 'api.ping']);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/scripts/index.d.ts

@@ -0,0 +1,12 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/scripts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/scripts/index.js

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

package/dist/scripts/sandbox.d.ts

@@ -0,0 +1,11 @@
+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 declare function startSandbox(options: SandboxOptions): Promise<string | undefined>;
+export declare function destroySandbox(backendPath: string): Promise<void>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/scripts/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/scripts/sandbox.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,+BAqJzD;AAED,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,iBAwCvD"}

package/dist/scripts/sandbox.js

@@ -0,0 +1,200 @@
+// 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) {
+    try {
+        await import(pathToFileURL(resolve(backendPath)).href);
+    }
+    catch {
+        // best-effort — telemetry never affects the command
+    }
+}
+export async function startSandbox(options) {
+    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) {
+        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] || {};
+    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 = { 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) {
+    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) {
+            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/dist/scripts/telemetry-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=telemetry-cli.d.ts.map

package/dist/scripts/telemetry-cli.d.ts.map

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

package/dist/scripts/telemetry-cli.js

@@ -0,0 +1,8 @@
+#!/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/dist/scripts/telemetry.d.ts

@@ -0,0 +1,17 @@
+export interface TelemetryOptions {
+    argv?: string[];
+}
+/**
+ * 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 declare function telemetry(options?: TelemetryOptions): Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/scripts/telemetry.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAsID;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBzE"}

package/dist/scripts/telemetry.js

@@ -0,0 +1,150 @@
+// 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';
+function printUsage() {
+    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) {
+    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 = 'help';
+    if (statusFlag)
+        action = 'status';
+    if (enable)
+        action = 'enable';
+    if (disable)
+        action = 'disable';
+    if (help)
+        action = 'help';
+    return { action, global };
+}
+function handleEnable(global) {
+    const configPath = global ? getGlobalConfigPath() : getProjectConfigPath();
+    try {
+        writeConfigTelemetry(configPath, true);
+    }
+    catch (error) {
+        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) {
+    const configPath = global ? getGlobalConfigPath() : getProjectConfigPath();
+    try {
+        writeConfigTelemetry(configPath, false);
+    }
+    catch (error) {
+        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() {
+    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) {
+    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;
+    }
+}

package/dist/scripts/telemetry.test.d.ts

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

package/dist/scripts/telemetry.test.d.ts.map

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