@aws-blocks/core 0.1.7 → 0.1.10

package/src/hosting.ts

@@ -26,6 +26,7 @@ import {
 import {
   detectFramework,
   getAdapter,
+  normalizeBasePath,
   type FrameworkAdapterFn,
 } from '@aws-blocks/hosting/adapters';
 import type {
@@ -150,6 +151,27 @@ export interface HostingProps {
   /** Supply a custom adapter when using an unsupported framework. */
   customAdapter?: FrameworkAdapterFn;
 
+  /**
+   * URL prefix the whole site is served under (Next.js `basePath`, Astro
+   * `base`, Nuxt `app.baseURL`). When set, CloudFront behaviors are prefixed
+   * with it and the bare root issues a 308 redirect to `/<basePath>/`.
+   *
+   * Declaring it here is the recommended source of truth: the value is
+   * caller-provided rather than reverse-engineered from build output, so it
+   * can't drift with framework/bundler internals. When omitted, the adapter
+   * falls back to detecting the framework's own base-path config from the
+   * build output.
+   *
+   * Format: leading slash, no trailing slash (e.g. `'/app'`). A trailing
+   * slash or bare `'/'` is normalized/ignored.
+   *
+   * @example
+   * ```ts
+   * new Hosting(stack, 'Web', { root, framework: 'nuxt', basePath: '/app' });
+   * ```
+   */
+  basePath?: string;
+
   // ── Blocks backend integration ────────────────────────────────────
   /**
    * The Blocks backend stack (or any object with `apiUrl`).
@@ -204,6 +226,36 @@ export interface HostingProps {
     countries: string[];
   };
 
+  /**
+   * Overrides for the adjustable AWS Service Quotas the CloudFront
+   * distribution draws on. Each field maps to a named AWS quota you can
+   * request an increase on:
+   *
+   *   - `cacheBehaviors` — "Cache behaviors per distribution" (default 25).
+   *     Consumed by routed paths, prerendered pages, per-pattern header
+   *     rules, assetPrefix, and the error-page behavior.
+   *   - `edgeFunctions` — Lambda@Edge associations per distribution
+   *     (default 25). Consumed by `runtime: 'edge'` routes.
+   *   - `headerPolicies` — "Response headers policies per AWS account"
+   *     (default 20, account-wide).
+   *
+   * Omitted fields use the AWS default. Set a field ONLY to match a quota
+   * increase AWS has actually granted — synth cannot verify your real quota,
+   * so an over-set value does not raise the AWS ceiling; it just moves the
+   * failure from a clear synth error to an opaque CloudFormation rollback.
+   *
+   * @example
+   * ```ts
+   * // After AWS grants "Cache behaviors per distribution" = 50:
+   * new Hosting(stack, 'Web', { root, quotas: { cacheBehaviors: 50 } });
+   * ```
+   */
+  quotas?: {
+    cacheBehaviors?: number;
+    edgeFunctions?: number;
+    headerPolicies?: number;
+  };
+
   /**
    * Build cache configuration. When enabled, provisions an S3 bucket for
    * framework build caches (e.g. Next.js .next/cache) and exports the bucket
@@ -401,6 +453,23 @@ export class Hosting extends Construct {
       manifest.buildId = generateBuildId();
     }
 
+    // ── 4b'. basePath: prop is the source of truth ───────────────
+    //    A caller-declared `basePath` overrides whatever the adapter
+    //    detected from build output. This is the robust path: the value
+    //    is provided rather than reverse-engineered from framework/bundler
+    //    internals (which drift across versions). When the prop is omitted,
+    //    the adapter's detected `manifest.basePath` (if any) stands.
+    if (props.basePath !== undefined) {
+      const normalized = normalizeBasePath(props.basePath);
+      if (normalized) {
+        manifest.basePath = normalized;
+      } else {
+        // Explicit '/' (or empty) means "no base path" — clear any value
+        // the adapter may have detected so the prop genuinely wins.
+        delete manifest.basePath;
+      }
+    }
+
     // ── 4c. Prevent duplicate error pages ────────────────────────
     //    The adapter may auto-detect error pages (e.g. SPA adapter finds
     //    404.html in build output and sets manifest.errorPages). When the
@@ -470,11 +539,12 @@ export class Hosting extends Construct {
       storage: props.retainOnDelete != null
         ? { retainOnDelete: props.retainOnDelete }
         : undefined,
-      cdn: (props.contentSecurityPolicy || props.priceClass || props.geoRestriction)
+      cdn: (props.contentSecurityPolicy || props.priceClass || props.geoRestriction || props.quotas)
         ? {
             contentSecurityPolicy: props.contentSecurityPolicy,
             priceClass: props.priceClass,
             geoRestriction: props.geoRestriction,
+            quotas: props.quotas,
           }
         : undefined,
       logging: props.logging,
@@ -492,17 +562,26 @@ export class Hosting extends Construct {
     }
 
     // ── 7a. Inject Blocks env vars into compute functions ───────────
-    const primaryFunction = hosting.computeFunctions.values().next().value as cdk.aws_lambda.Function | undefined;
+    // Lambda@Edge functions (edge-runtime routes) do NOT support environment
+    // variables — they surface in computeFunctions as EdgeFunction/IVersion
+    // without an `addEnvironment` method. Skip any function that can't take
+    // env vars instead of crashing (`fn.addEnvironment is not a function`).
+    const canAddEnv = (
+      fn: unknown,
+    ): fn is cdk.aws_lambda.Function =>
+      typeof (fn as { addEnvironment?: unknown })?.addEnvironment === 'function';
+
+    const primaryFunction = [...hosting.computeFunctions.values()].find(
+      canAddEnv,
+    );
 
     for (const [, fn] of hosting.computeFunctions) {
+      if (!canAddEnv(fn)) continue; // Lambda@Edge: no env var support
       if (props.api) {
-        (fn as cdk.aws_lambda.Function).addEnvironment('BLOCKS_API_URL', props.api.apiUrl);
+        fn.addEnvironment('BLOCKS_API_URL', props.api.apiUrl);
       }
       if (props.backendConfig) {
-        (fn as cdk.aws_lambda.Function).addEnvironment(
-          'BLOCKS_CONFIG',
-          JSON.stringify(props.backendConfig),
-        );
+        fn.addEnvironment('BLOCKS_CONFIG', JSON.stringify(props.backendConfig));
       }
     }
 
@@ -521,11 +600,25 @@ export class Hosting extends Construct {
         cacheControl: [s3deploy.CacheControl.fromString('public, max-age=60, must-revalidate')],
       });
 
-      // Ensure config deployment runs after the hosting construct's
-      // asset deployment so the resolved config.json is not overwritten.
-      const assetDeployment = hosting.node.tryFindChild('AssetDeployment') as Construct | undefined;
-      if (assetDeployment) {
-        configDeployment.node.addDependency(assetDeployment);
+      // Ensure the config deployment runs AFTER the hosting construct's
+      // asset deployments. Those deployments upload the whole static dir —
+      // which includes the *placeholder* `.blocks-sandbox/config.json`
+      // (`{_placeholder:true}`) written during synth — to the same
+      // `builds/<id>/.blocks-sandbox/config.json` key this deployment writes
+      // the resolved config to. Without an ordering dependency the
+      // placeholder can land last and clobber the real config.
+      //
+      // We depend on EVERY BucketDeployment under the hosting construct
+      // rather than a single hard-coded child id: the real children are
+      // `AssetDeploymentImmutable` / `AssetDeploymentHtml` / `...Mutable`
+      // (and vary by deploy shape), so the previous
+      // `tryFindChild('AssetDeployment')` never matched and the dependency
+      // was silently never wired.
+      const assetDeployments = hosting.node
+        .findAll()
+        .filter((c): c is s3deploy.BucketDeployment => c instanceof s3deploy.BucketDeployment);
+      for (const dep of assetDeployments) {
+        configDeployment.node.addDependency(dep);
       }
     }
 

package/src/scripts/deploy.ts

@@ -25,8 +25,10 @@ export async function deploy(options: DeployOptions) {
 
     process.env.BLOCKS_STAGE = 'production';
 
-    // Provision secrets for production
-    const secrets = await ensureSecrets('production');
+    // Provision secrets for production. projectRoot must match the root cdk
+    // synth uses (passed as --context below) so the written parameter name
+    // equals the one the app resolves at synth.
+    const secrets = await ensureSecrets('production', options.projectRoot);
     if (secrets.created.length > 0 || secrets.updated.length > 0) {
       console.log(`🔐 Secrets provisioned: ${[...secrets.created, ...secrets.updated].join(', ')}`);
     }

package/src/scripts/ensure-secrets.ts

@@ -4,15 +4,20 @@
 /**
  * Pre-deploy secret provisioning.
  *
- * Writes the connection string to an SSM SecureString parameter.
- * Parameter name includes the stage to prevent sandbox/prod collision:
- *   /blocks/{stage}/db-connection-string
+ * Writes the connection string to an SSM SecureString parameter. The parameter
+ * name is stack-scoped (`/<stackName>-db-url` via `dbConnectionParameterName`),
+ * so two Blocks apps in the same account/region/stage never collide. The synth
+ * step names the parameter with the same function and the same inputs
+ * (`projectRoot` + stage), so the value written here is read back under the
+ * identical name — which is why this must be given the same `projectRoot` the
+ * deploy command passes to synth.
  *
  * On first deploy: creates the parameter.
  * On subsequent deploys: updates if value changed, no-op otherwise.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { dbConnectionParameterName } from '../db-naming.js';
+import { getStackName } from './stack-id.js';
 
 const CONNECTION_STRING_PATTERN = /_(DB_URL|CONNECTION_STRING)$/;
 
@@ -32,9 +37,15 @@ export function findConnectionString(): { name: string; value: string } | null {
 }
 
 /**
- * Ensure the connection string is stored in SSM for the current stage.
+ * Ensure the connection string is stored in SSM under this app's stack-scoped
+ * parameter name. `projectRoot` locates the committed `.blocks/config.json`
+ * that defines the stack name; it must match the root used at synth (the deploy
+ * commands pass it explicitly) so the written name equals the name the app reads.
  */
-export async function ensureSecrets(stage?: 'sandbox' | 'production'): Promise<EnsureSecretsResult> {
+export async function ensureSecrets(
+  stage?: string,
+  projectRoot?: string,
+): Promise<EnsureSecretsResult> {
   const result: EnsureSecretsResult = { created: [], updated: [], unchanged: [] };
 
   const conn = findConnectionString();
@@ -46,7 +57,7 @@ export async function ensureSecrets(stage?: 'sandbox' | 'production'): Promise<E
     await import('@aws-sdk/client-ssm');
 
   const client = new SSMClient();
-  const parameterName = dbConnectionParameterName(resolvedStage);
+  const parameterName = dbConnectionParameterName(getStackName({ sandbox: resolvedStage !== 'production', projectRoot }));
 
   let isNew = false;
   try {

package/src/scripts/external-migrations-step.ts

@@ -27,6 +27,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { findConnectionString } from './ensure-secrets.js';
 import { extractDbRef, dbConnectionParameterName } from '../db-naming.js';
+import { getStackName } from './stack-id.js';
 import { runSync } from './run-command.js';
 
 const DEFAULT_MIGRATIONS_DIR = './migrations';
@@ -170,7 +171,10 @@ async function productionRefs(devRef: string): Promise<Set<string>> {
   try {
     const { SSMClient, GetParameterCommand } = await import('@aws-sdk/client-ssm');
     const res = await new SSMClient().send(
-      new GetParameterCommand({ Name: dbConnectionParameterName('production'), WithDecryption: true }),
+      new GetParameterCommand({
+        Name: dbConnectionParameterName(getStackName({ sandbox: false })),
+        WithDecryption: true,
+      }),
     );
     const v = res.Parameter?.Value;
     const r = v ? safeRef(v) : null;

package/src/scripts/index.ts

@@ -19,4 +19,4 @@ export {
   type BuildAndSendEventOptions,
 } from '../telemetry/index.js';
 export { telemetry, type TelemetryOptions } from './telemetry.js';
-export { getStackId, getSandboxId } from './stack-id.js';
+export { getStackId, getSandboxId, getStackName } from './stack-id.js';

package/src/scripts/sandbox.ts

@@ -51,7 +51,9 @@ export async function startSandbox(options: SandboxOptions) {
 
   // Provision connection string to SSM SecureString.
   // On first deploy, creates the parameter. On subsequent deploys, updates if changed.
-  const secrets = await ensureSecrets('sandbox');
+  // projectRoot is process.cwd() — the same value passed to cdk as --context
+  // projectRoot below — so the written name matches the name resolved at synth.
+  const secrets = await ensureSecrets('sandbox', process.cwd());
   if (secrets.created.length > 0) {
     console.log(`🔐 Created secrets: ${secrets.created.join(', ')}`);
   }
@@ -75,6 +77,13 @@ export async function startSandbox(options: SandboxOptions) {
       "npm",
       [
         "exec", "cdk", "--", "deploy",
+        // `--all`: an app that uses Lambda@Edge (e.g. a Next.js route with
+        // `export const runtime = 'edge'`) synthesizes a SECOND stack
+        // (`edge-lambda-stack-*`, region us-east-1) in addition to the main
+        // hosting stack. Without `--all`, CDK refuses with "specify which
+        // stacks to use". Deploying every stack in a sandbox app is the
+        // intended behavior, so select them all.
+        "--all",
         "--require-approval", "never",
         "--outputs-file", `${outDir}/outputs.json`,
         "--context", `projectRoot=${process.cwd()}`,

package/src/scripts/stack-id.test.ts

@@ -7,7 +7,7 @@ import { mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
-import { getStackId, getSandboxId } from './stack-id.js';
+import { getStackId, getSandboxId, getStackName } from './stack-id.js';
 
 describe('getStackId', () => {
   let tmpDir: string;
@@ -61,3 +61,63 @@ describe('getSandboxId', () => {
     assert.strictEqual(getSandboxId(tmpDir), 'alice-abc123');
   });
 });
+
+describe('getStackName', () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('production is <stackId>-prod', () => {
+    tmpDir = join(tmpdir(), `stack-name-prod-${Date.now()}`);
+    mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'my-app-k7x2mf' }));
+    assert.strictEqual(getStackName({ sandbox: false, projectRoot: tmpDir }), 'my-app-k7x2mf-prod');
+  });
+
+  it('sandbox is <stackId>-<sandboxId>', () => {
+    tmpDir = join(tmpdir(), `stack-name-sbx-${Date.now()}`);
+    mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'my-app-k7x2mf' }));
+    mkdirSync(join(tmpDir, '.blocks-sandbox'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks-sandbox', 'sandbox-id.txt'), 'alice-0d7e1c');
+    assert.strictEqual(getStackName({ sandbox: true, projectRoot: tmpDir }), 'my-app-k7x2mf-alice-0d7e1c');
+  });
+
+  it('throws actionable error when config is missing (fail fast, no silent fallback)', () => {
+    tmpDir = join(tmpdir(), `stack-name-missing-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    assert.throws(() => getStackName({ sandbox: false, projectRoot: tmpDir }), /\.blocks\/config\.json not found/);
+  });
+});
+
+describe('getStackName sandbox id (get-or-create)', () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('creates and persists sandbox-id.txt on first call when missing', () => {
+    tmpDir = join(tmpdir(), `stack-name-getorcreate-${Date.now()}`);
+    mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'test-app' }));
+    // No .blocks-sandbox dir yet — getStackName creates the id rather than throwing.
+    const name = getStackName({ sandbox: true, projectRoot: tmpDir });
+    assert.match(name, /^test-app-[a-z0-9]+-[a-f0-9]{6}$/);
+    // Persisted so later callers/processes resolve the identical name.
+    const stored = readFileSync(join(tmpDir, '.blocks-sandbox', 'sandbox-id.txt'), 'utf-8').trim();
+    assert.strictEqual(name, `test-app-${stored}`);
+  });
+
+  it('reuses the same id across calls', () => {
+    tmpDir = join(tmpdir(), `stack-name-getorcreate-idem-${Date.now()}`);
+    mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'test-app' }));
+    assert.strictEqual(
+      getStackName({ sandbox: true, projectRoot: tmpDir }),
+      getStackName({ sandbox: true, projectRoot: tmpDir }),
+    );
+  });
+});

package/src/scripts/stack-id.ts

@@ -38,6 +38,11 @@ export function getStackId(projectRoot?: string): string {
  * Get or create a per-machine sandbox identifier.
  * Stored in `.blocks-sandbox/sandbox-id.txt` (gitignored).
  * Format: `<username(8)>-<random(6)>` — identifies the developer's sandbox.
+ *
+ * Get-or-create (lazy init): returns the existing id, or generates and persists
+ * one on first call. The file is the shared sync point — once written, every
+ * later caller and every process reads the same id, so the secret writer
+ * (`ensureSecrets`) and synth derive identical names.
  */
 export function getSandboxId(projectRoot?: string): string {
   const root = projectRoot || process.cwd();
@@ -52,6 +57,27 @@ export function getSandboxId(projectRoot?: string): string {
   return id;
 }
 
+/**
+ * The full CloudFormation stack name for a deployment.
+ *
+ * Single source of truth for the stack-name scheme (D-012): production is
+ * `<stackId>-prod`; a sandbox is `<stackId>-<sandboxId>`. The CDK templates name
+ * the stack with this function, and the external-DB connection-string parameter
+ * name (`dbConnectionParameterName`) is derived from it — so a deployed stack and
+ * the parameter holding its database credentials can never use divergent names.
+ *
+ * This function reads committed config (`.blocks/config.json`, throws if absent
+ * — D-012) and resolves the sandbox id via {@link getSandboxId} (get-or-create):
+ * the first caller materializes `.blocks-sandbox/sandbox-id.txt`, every later
+ * caller reads the same value. Because that file persists and is shared across
+ * processes, the secret writer (`ensureSecrets`) and synth resolve identical
+ * names. Production does not use the sandbox id.
+ */
+export function getStackName(opts: { sandbox: boolean; projectRoot?: string }): string {
+  const base = getStackId(opts.projectRoot);
+  return opts.sandbox ? `${base}-${getSandboxId(opts.projectRoot)}` : `${base}-prod`;
+}
+
 function getUsername(): string {
   try {
     return execSync('git config user.name', { encoding: 'utf-8' }).trim();

package/src/telemetry/client.ts

@@ -1,7 +1,7 @@
-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 { spawn } from 'node:child_process';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { debuglog } from 'node:util';
 import { CORE_VERSION } from '../version.js';
 import { Scope } from '../common/index.js';
@@ -14,7 +14,6 @@ import type { BlocksTelemetryEvent, BuildAndSendEventOptions } from './types.js'
 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(): string {
@@ -179,7 +178,9 @@ export function buildAndSendEvent(opts: BuildAndSendEventOptions): void {
 /**
  * Send a pre-built telemetry event to the collection endpoint.
  *
- * Fire-and-forget: no retry, 500ms timeout, all errors silently swallowed.
+ * Spawns a detached subprocess that performs the HTTPS POST independently of
+ * the parent CLI process. This ensures the request completes even when the
+ * parent exits on failure paths before an in-process request would flush.
  * Debug output available via `NODE_DEBUG=blocks-telemetry`.
  */
 export function sendEvent(event: BlocksTelemetryEvent): void {
@@ -194,32 +195,23 @@ export function sendEvent(event: BlocksTelemetryEvent): void {
 
     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();
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const workerPath = path.join(dir, 'telemetry-send-worker.js');
+    const child = spawn(process.execPath, [workerPath, endpoint], {
+      detached: true,
+      stdio: ['pipe', 'ignore', 'ignore'],
+      // Clear NODE_OPTIONS so inherited flags (e.g. --conditions=cdk) don't interfere
+      env: { ...process.env, NODE_OPTIONS: '' },
+    });
+
+    child.stdin!.on('error', (err) => { debug('stdin write failed: %s', err.message); });
+    // Payload is small (<1KB JSON) so it fits in the kernel pipe buffer (~64KB)
+    // and survives the parent closing its fd on exit.
+    child.stdin!.write(payload);
+    child.stdin!.end();
+    child.on('error', (err) => { debug('spawn failed: %s', err.message); });
+    child.unref();
+    debug('spawned telemetry subprocess (pid=%d)', child.pid);
   } catch {
     // Telemetry must never throw or affect the user's command
   }

package/src/telemetry/telemetry-send-worker.ts

@@ -0,0 +1,60 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Telemetry send worker — spawned as a detached subprocess.
+ * Reads JSON payload from stdin, POSTs it to the endpoint (argv[2]).
+ *
+ * Uses only Node built-ins — no project imports — so the compiled .js
+ * runs with bare `node` (no tsx needed).
+ */
+
+import { request as httpsRequest } from 'node:https';
+import { request as httpRequest } from 'node:http';
+
+const TIMEOUT_MS = 500;
+const debug = (process.env.NODE_DEBUG || '').includes('blocks-telemetry');
+
+const endpoint = process.argv[2];
+if (!endpoint) process.exit(1);
+
+let payload = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk: string) => { payload += chunk; });
+process.stdin.on('end', () => {
+  try {
+    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) => {
+      res.resume();
+      if (debug) process.stderr.write(`BLOCKS-TELEMETRY: sent (status=${res.statusCode})\n`);
+      process.exit(0);
+    });
+
+    req.on('error', (e) => {
+      if (debug) process.stderr.write(`BLOCKS-TELEMETRY: error: ${(e as Error).message}\n`);
+      process.exit(1);
+    });
+    req.on('timeout', () => {
+      if (debug) process.stderr.write(`BLOCKS-TELEMETRY: timed out\n`);
+      req.destroy();
+      process.exit(1);
+    });
+    req.write(payload);
+    req.end();
+  } catch {
+    process.exit(1);
+  }
+});

package/src/telemetry/telemetry.test.ts

@@ -11,7 +11,7 @@ import { isCI, detectOS, detectNodeVersion, detectPackageManager, detectAgent, c
 import { trackCommand, classifyError } from './trackCommand.js';
 import { buildAndSendEvent, buildEvent, sendEvent, getTelemetryFilePath } from './client.js';
 import { getInstallationId, getProjectId, generateEventId } from './identifiers.js';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, spawn as spawnChild } from 'node:child_process';
 import type { BlocksTelemetryEvent } from './types.js';
 import { Scope, OFFICIAL_BB_NAMES } from '../common/index.js';
 import type { ScopeParent } from '../common/index.js';
@@ -533,6 +533,96 @@ describe('telemetry/client', () => {
   });
 });
 
+describe('telemetry/send-worker', () => {
+  it('worker POSTs payload from stdin to endpoint', async () => {
+    const received: string[] = [];
+
+    const server: Server = await new Promise((resolve) => {
+      const s = createServer((req, res) => {
+        let body = '';
+        req.on('data', (chunk) => { body += chunk; });
+        req.on('end', () => {
+          received.push(body);
+          res.writeHead(200);
+          res.end();
+        });
+      });
+      s.listen(0, '127.0.0.1', () => resolve(s));
+    });
+
+    const addr = server.address() as { port: number };
+    const endpoint = `http://127.0.0.1:${addr.port}/collect`;
+    const payload = JSON.stringify({ test: true, command: 'dev' });
+    const workerPath = join(__dirname, 'telemetry-send-worker.js');
+
+    const exitCode = await new Promise<number | null>((resolve) => {
+      const proc = spawnChild(process.execPath, [workerPath, endpoint], {
+        stdio: ['pipe', 'ignore', 'ignore'],
+        env: { ...process.env, NODE_OPTIONS: '' },
+      });
+      proc.stdin!.write(payload);
+      proc.stdin!.end();
+      proc.on('close', (code) => resolve(code));
+    });
+
+    assert.strictEqual(exitCode, 0);
+    assert.strictEqual(received.length, 1);
+    assert.deepStrictEqual(JSON.parse(received[0]), { test: true, command: 'dev' });
+
+    server.close();
+  });
+
+  it('worker exits with 1 on unreachable endpoint', async () => {
+    const payload = JSON.stringify({ test: true });
+    const workerPath = join(__dirname, 'telemetry-send-worker.js');
+
+    const exitCode = await new Promise<number | null>((resolve) => {
+      const proc = spawnChild(process.execPath, [workerPath, 'http://127.0.0.1:1/unreachable'], {
+        stdio: ['pipe', 'ignore', 'ignore'],
+        env: { ...process.env, NODE_OPTIONS: '' },
+      });
+      proc.stdin!.write(payload);
+      proc.stdin!.end();
+      proc.on('close', (code) => resolve(code));
+    });
+
+    assert.strictEqual(exitCode, 1);
+  });
+
+  it('worker writes debug output to stderr when NODE_DEBUG is set', async () => {
+    const server: Server = await new Promise((resolve) => {
+      const s = createServer((req, res) => {
+        let body = '';
+        req.on('data', (chunk) => { body += chunk; });
+        req.on('end', () => { res.writeHead(200); res.end(); });
+      });
+      s.listen(0, '127.0.0.1', () => resolve(s));
+    });
+
+    const addr = server.address() as { port: number };
+    const endpoint = `http://127.0.0.1:${addr.port}/collect`;
+    const payload = JSON.stringify({ test: true });
+    const workerPath = join(__dirname, 'telemetry-send-worker.js');
+
+    const result = await new Promise<{ code: number | null; stderr: string }>((resolve) => {
+      const proc = spawnChild(process.execPath, [workerPath, endpoint], {
+        stdio: ['pipe', 'ignore', 'pipe'],
+        env: { ...process.env, NODE_OPTIONS: '', NODE_DEBUG: 'blocks-telemetry' },
+      });
+      let stderr = '';
+      proc.stderr!.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+      proc.stdin!.write(payload);
+      proc.stdin!.end();
+      proc.on('close', (code) => resolve({ code, stderr }));
+    });
+
+    assert.strictEqual(result.code, 0);
+    assert.ok(result.stderr.includes('BLOCKS-TELEMETRY: sent (status=200)'), `Expected debug output, got: ${result.stderr}`);
+
+    server.close();
+  });
+});
+
 describe('telemetry/trackCommand integration', () => {
   const originalEnv = { ...process.env };