@aws-blocks/core 0.1.0

package/src/rpc.test.ts

@@ -0,0 +1,73 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { parseRpcRequest, RpcErrorCode } from './rpc.js';
+
+describe('-32600 Invalid Request error shape', () => {
+  it('returns proper JSON-RPC 2.0 envelope with error code', () => {
+    const result = parseRpcRequest(JSON.stringify({ method: 'ns.method', id: 1 }));
+    assert.strictEqual(result.ok, false);
+    if (!result.ok) {
+      const parsed = JSON.parse(result.response);
+      assert.strictEqual(parsed.jsonrpc, '2.0');
+      assert.strictEqual(parsed.error.code, RpcErrorCode.InvalidRequest);
+      assert.strictEqual(parsed.id, 1);
+    }
+  });
+
+  it('includes descriptive message with expected JSON-RPC 2.0 shape', () => {
+    const result = parseRpcRequest(JSON.stringify({ method: 'test', id: 1 }));
+    assert.strictEqual(result.ok, false);
+    if (!result.ok) {
+      const parsed = JSON.parse(result.response);
+      assert.ok(
+        parsed.error.message.includes('expected JSON-RPC 2.0'),
+        `message should describe the expected format, got: ${parsed.error.message}`,
+      );
+      assert.ok(
+        parsed.error.message.includes('"jsonrpc":"2.0"'),
+        `message should echo the expected envelope shape`,
+      );
+    }
+  });
+
+  it('includes data.name per D-003 convention', () => {
+    const result = parseRpcRequest(JSON.stringify({ method: 'test', id: 1 }));
+    assert.strictEqual(result.ok, false);
+    if (!result.ok) {
+      const parsed = JSON.parse(result.response);
+      assert.strictEqual(parsed.error.data.name, 'InvalidRequest');
+    }
+  });
+
+  it('preserves the caller id in the error response', () => {
+    const result = parseRpcRequest(JSON.stringify({ id: 'abc-123' }));
+    assert.strictEqual(result.ok, false);
+    if (!result.ok) {
+      const parsed = JSON.parse(result.response);
+      assert.strictEqual(parsed.id, 'abc-123');
+    }
+  });
+
+  it('uses null id when request omits id', () => {
+    const result = parseRpcRequest(JSON.stringify({ jsonrpc: '1.0', method: 123 }));
+    assert.strictEqual(result.ok, false);
+    if (!result.ok) {
+      const parsed = JSON.parse(result.response);
+      assert.strictEqual(parsed.id, null);
+    }
+  });
+
+  it('includes data.name when method lacks namespace dot separator', () => {
+    const result = parseRpcRequest(JSON.stringify({ jsonrpc: '2.0', method: 'noNamespace', id: 7 }));
+    assert.strictEqual(result.ok, false);
+    if (!result.ok) {
+      const parsed = JSON.parse(result.response);
+      assert.strictEqual(parsed.error.code, RpcErrorCode.InvalidRequest);
+      assert.strictEqual(parsed.error.data.name, 'InvalidRequest');
+      assert.strictEqual(parsed.id, 7);
+    }
+  });
+});

package/src/rpc.ts

@@ -0,0 +1,174 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * JSON-RPC 2.0 wire format — single source of truth.
+ *
+ * All encoding/decoding of the Blocks RPC protocol lives here so that the
+ * client, Lambda handler, and dev server never deal with the spec directly.
+ *
+ * @see https://www.jsonrpc.org/specification
+ */
+
+import { ApiError } from './errors.js';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** The pieces every server-side handler needs after parsing a request. */
+export interface RpcParsedRequest {
+  apiNamespace: string;
+  method: string;
+  /** Positional args — from array params directly, or Object.values() of named params. */
+  args: unknown[];
+  id: string | number | null;
+}
+
+/** Discriminated union returned by `parseRpcRequest`. */
+export type RpcParseResult =
+  | { ok: true; request: RpcParsedRequest }
+  | { ok: false; response: string };
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+const VERSION = '2.0' as const;
+
+/** Reserved JSON-RPC error codes. */
+export const RpcErrorCode = {
+  ParseError:     -32700,
+  InvalidRequest: -32600,
+  MethodNotFound: -32601,
+  InvalidParams:  -32602,
+  InternalError:  -32603,
+} as const;
+
+// ── Client helpers (encode request, decode response) ────────────────────────
+
+let _nextId = 1;
+
+/** Build a JSON-RPC 2.0 request body string ready to POST. */
+export function encodeRpcRequest(apiNamespace: string, method: string, args: unknown[]): string {
+  return JSON.stringify({
+    jsonrpc: VERSION,
+    method: `${apiNamespace}.${method}`,
+    params: args,
+    id: _nextId++,
+  });
+}
+
+/**
+ * Decode a JSON-RPC 2.0 response body.
+ *
+ * Returns the `result` on success, or throws an `ApiError` on error.
+ */
+export function decodeRpcResponse(body: unknown): unknown {
+  const rpc = body as any;
+  if (rpc.error) {
+    const { code, message, data } = rpc.error;
+    // Application error codes use the HTTP status directly (e.g. 409).
+    // Reserved JSON-RPC codes (-32xxx) map to 500.
+    const status = code > 0 ? code : 500;
+    throw new ApiError(
+      message,
+      status,
+      {
+        ...(data?.name ? { name: data.name } : {}),
+        ...(data?.retriable === true ? { retriable: true } : {}),
+      },
+    );
+  }
+  return rpc.result;
+}
+
+// ── Server helpers (parse request, encode response) ─────────────────────────
+
+/**
+ * Parse a raw body string into a validated `RpcParsedRequest`.
+ *
+ * Returns `{ ok: false, response }` with a ready-to-send JSON string when
+ * the request is malformed, so callers can short-circuit without knowing
+ * anything about the JSON-RPC spec.
+ */
+export function parseRpcRequest(bodyText: string): RpcParseResult {
+  let parsed: any;
+  try {
+    parsed = JSON.parse(bodyText || '{}');
+  } catch {
+    return { ok: false, response: errorResponse(RpcErrorCode.ParseError, 'Parse error', null) };
+  }
+
+  const id = parsed.id ?? null;
+
+  if (parsed.jsonrpc !== VERSION || typeof parsed.method !== 'string') {
+    return {
+      ok: false,
+      response: errorResponse(
+        RpcErrorCode.InvalidRequest,
+        'Invalid Request: expected JSON-RPC 2.0 — {"jsonrpc":"2.0","method":"namespace.method","params":[...],"id":1}',
+        id,
+        { name: 'InvalidRequest' },
+      ),
+    };
+  }
+
+  const dotIndex = parsed.method.indexOf('.');
+  if (dotIndex === -1) {
+    return {
+      ok: false,
+      response: errorResponse(RpcErrorCode.InvalidRequest, 'Invalid Request: method must be "namespace.method"', id, { name: 'InvalidRequest' }),
+    };
+  }
+
+  return {
+    ok: true,
+    request: {
+      apiNamespace: parsed.method.substring(0, dotIndex),
+      method: parsed.method.substring(dotIndex + 1),
+      // JSON-RPC 2.0 §4.2: params may be an array (positional) or object (named).
+      args: Array.isArray(parsed.params)
+        ? parsed.params
+        : Object.values(parsed.params ?? {}),
+      id,
+    },
+  };
+}
+
+/** Encode a successful result as a JSON-RPC 2.0 response string. */
+export function successResponse(result: unknown, id: string | number | null): string {
+  return JSON.stringify({ jsonrpc: VERSION, result, id });
+}
+
+/**
+ * Encode an error as a JSON-RPC 2.0 response string.
+ *
+ * For `ApiError` instances the HTTP status becomes the error code (positive
+ * integers never collide with the reserved -32xxx range). Generic errors
+ * use code 500.
+ */
+export function errorResponseFromCatch(error: unknown, id: string | number | null): string {
+  const code = error instanceof ApiError ? error.status : 500;
+  const message = error instanceof Error ? error.message : String(error);
+  const data: Record<string, unknown> = {};
+  if (error instanceof Error && error.name && error.name !== 'Error') data.name = error.name;
+  if (error instanceof ApiError && error.retriable) data.retriable = true;
+  return errorResponse(code, message, id, Object.keys(data).length > 0 ? data : undefined);
+}
+
+/** Encode a "method not found" error. */
+export function methodNotFoundResponse(detail: string, id: string | number | null): string {
+  return errorResponse(RpcErrorCode.MethodNotFound, `Method not found: ${detail}`, id);
+}
+
+// ── Internal ────────────────────────────────────────────────────────────────
+
+export function errorResponse(
+  code: number,
+  message: string,
+  id: string | number | null,
+  data?: Record<string, unknown>,
+): string {
+  return JSON.stringify({
+    jsonrpc: VERSION,
+    error: { code, message, ...(data ? { data } : {}) },
+    id,
+  });
+}

package/src/scripts/cdk-telemetry-env.test.ts

@@ -0,0 +1,75 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+
+describe('getCdkTelemetryEnv', () => {
+  const originalEnv = { ...process.env };
+  const originalCwd = process.cwd();
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+    process.chdir(originalCwd);
+  });
+
+  it('returns CDK_CLI_USERAGENT when telemetry is enabled', () => {
+    delete process.env.AWS_BLOCKS_DISABLE_TELEMETRY;
+    // chdir to a temp dir with no .blocks/config.json so defaults apply
+    const tmp = join(tmpdir(), `cdk-telemetry-test-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    process.chdir(tmp);
+
+    const env = getCdkTelemetryEnv('sandbox');
+
+    assert.ok('CDK_CLI_USERAGENT' in env, 'should have CDK_CLI_USERAGENT');
+    assert.ok(!('CDK_DISABLE_CLI_TELEMETRY' in env), 'should NOT have CDK_DISABLE_CLI_TELEMETRY');
+    assert.match(env.CDK_CLI_USERAGENT, /^aws-blocks\/.*\/sandbox$/);
+
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('returns CDK_DISABLE_CLI_TELEMETRY when env var disables telemetry', () => {
+    process.env.AWS_BLOCKS_DISABLE_TELEMETRY = '1';
+
+    const env = getCdkTelemetryEnv('production');
+
+    assert.deepStrictEqual(env, { CDK_DISABLE_CLI_TELEMETRY: '1' });
+    assert.ok(!('CDK_CLI_USERAGENT' in env), 'should NOT have CDK_CLI_USERAGENT');
+  });
+
+  it('returns CDK_DISABLE_CLI_TELEMETRY when project config disables telemetry', () => {
+    delete process.env.AWS_BLOCKS_DISABLE_TELEMETRY;
+    const tmp = join(tmpdir(), `cdk-telemetry-test-${Date.now()}`);
+    mkdirSync(join(tmp, '.blocks'), { recursive: true });
+    writeFileSync(join(tmp, '.blocks', 'config.json'), JSON.stringify({ telemetry: { enabled: false } }));
+    process.chdir(tmp);
+
+    const env = getCdkTelemetryEnv('sandbox');
+
+    assert.deepStrictEqual(env, { CDK_DISABLE_CLI_TELEMETRY: '1' });
+    assert.ok(!('CDK_CLI_USERAGENT' in env), 'should NOT have CDK_CLI_USERAGENT');
+
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('includes the command name in the user-agent string', () => {
+    delete process.env.AWS_BLOCKS_DISABLE_TELEMETRY;
+    const tmp = join(tmpdir(), `cdk-telemetry-test-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    process.chdir(tmp);
+
+    const sandboxEnv = getCdkTelemetryEnv('sandbox');
+    const prodEnv = getCdkTelemetryEnv('production');
+
+    assert.ok(sandboxEnv.CDK_CLI_USERAGENT.endsWith('/sandbox'));
+    assert.ok(prodEnv.CDK_CLI_USERAGENT.endsWith('/production'));
+
+    rmSync(tmp, { recursive: true, force: true });
+  });
+});

package/src/scripts/cdk-telemetry-env.ts

@@ -0,0 +1,23 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isTelemetryEnabled } from '../telemetry/consent.js';
+import { CORE_VERSION } from '../version.js';
+
+/**
+ * Build CDK CLI telemetry-related environment variables.
+ *
+ * When Blocks telemetry is enabled, sets `CDK_CLI_USERAGENT` so the CDK CLI
+ * attributes usage back to Blocks. When telemetry is disabled (user opted out),
+ * sets `CDK_DISABLE_CLI_TELEMETRY=1` to suppress CDK's own telemetry collection
+ * and omits the user-agent string.
+ *
+ * @param command - The Blocks command context (e.g. "sandbox", "production")
+ * @returns An object to spread into the child process `env`
+ */
+export function getCdkTelemetryEnv(command: string): Record<string, string> {
+  if (!isTelemetryEnabled()) {
+    return { CDK_DISABLE_CLI_TELEMETRY: '1' };
+  }
+  return { CDK_CLI_USERAGENT: `aws-blocks/${CORE_VERSION}/${command}` };
+}

package/src/scripts/cleanup.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { execSync } from 'node:child_process';
+import { trackCommand } from '../telemetry/trackCommand.js';
+
+export async function cleanup() {
+  return trackCommand('cleanup', async () => {
+    console.log('🧹 Cleaning up Blocks processes...');
+
+    // Find and kill processes on common Blocks ports
+    const ports = [3000, 3001, 3002, 3003];
+
+    for (const port of ports) {
+      try {
+        const result = execSync(`lsof -ti:${port}`, { encoding: 'utf-8' }).trim();
+        if (result) {
+          const pids = result.split('\n');
+          for (const pid of pids) {
+            try {
+              execSync(`kill ${pid}`);
+              console.log(`✓ Killed process ${pid} on port ${port}`);
+            } catch {}
+          }
+        }
+      } catch {
+        // No process on this port
+      }
+    }
+
+    console.log('✓ Cleanup complete');
+  });
+}
+
+cleanup().catch((error) => {
+  console.error('Error during cleanup:', error);
+  process.exit(1);
+});

package/src/scripts/console.ts

@@ -0,0 +1,34 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { trackCommand } from '../telemetry/trackCommand.js';
+
+export interface ConsoleOptions {
+  stackId?: string;
+  outputsFile?: string;
+}
+
+export async function openConsole(options: ConsoleOptions) {
+  return trackCommand('console', async () => {
+    let stackName: string;
+
+    if (options.stackId) {
+      stackName = options.stackId;
+    } else if (options.outputsFile) {
+      const outputs = JSON.parse(readFileSync(options.outputsFile, 'utf-8'));
+      stackName = Object.keys(outputs)[0];
+    } else {
+      throw new Error('Must provide either stackId or outputsFile');
+    }
+
+    const region = execFileSync('aws', ['configure', 'get', 'region'], { encoding: 'utf-8' }).trim() || 'us-east-1';
+    const stackUrl = `https://${region}.console.aws.amazon.com/cloudformation/home?region=${region}#/stacks?filteringText=${encodeURIComponent(stackName)}`;
+
+    console.log('Opening AWS Console...');
+    console.log(stackUrl);
+
+    execFileSync('open', [stackUrl], { stdio: 'inherit' });
+  });
+}

package/src/scripts/deploy.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ensureSecrets, loadProductionEnv } from './ensure-secrets.js';
+import { applyExternalMigrations } from './external-migrations-step.js';
+import { trackCommand } from '../telemetry/trackCommand.js';
+import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+
+export interface DeployOptions {
+  cdkAppPath: string;
+  projectRoot: string;
+}
+
+export async function deploy(options: DeployOptions) {
+  return trackCommand('deploy', async () => {
+    console.log('🏗️  Preparing deployment...');
+
+    // Load production environment (from .env.production or CI env vars)
+    loadProductionEnv();
+
+    process.env.BLOCKS_STAGE = 'production';
+
+    // Provision secrets for production
+    const secrets = await ensureSecrets('production');
+    if (secrets.created.length > 0 || secrets.updated.length > 0) {
+      console.log(`🔐 Secrets provisioned: ${[...secrets.created, ...secrets.updated].join(', ')}`);
+    }
+
+    // Apply external-database migrations to the production database before
+    // deploying. No-op unless this app uses an external DB and has ./migrations.
+    await applyExternalMigrations({ stage: 'production' });
+    
+    // Import backend to populate BB registry for telemetry
+    const foundationPath = resolve(options.projectRoot, 'aws-blocks/index.ts');
+    try {
+      await import(pathToFileURL(foundationPath).href);
+    } catch { /* ignore import errors */ }
+
+    // Generate client code FIRST (before cdk deploy triggers the Vite build)
+    const clientPath = join(dirname(foundationPath), '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, foundationPath, clientPath], {
+      stdio: 'inherit',
+      env: { ...process.env, NODE_OPTIONS: '' },
+    });
+
+    console.log('🚀 Deploying to AWS...');
+    console.log('   (This may take a few minutes on first deploy)');
+    console.log('   - Backend API (Lambda + API Gateway)');
+    console.log('   - Frontend hosting (S3 + CloudFront)');
+    
+    try {
+      execFileSync(
+        "npx",
+        [
+          "cdk", "deploy",
+          "--require-approval", "never",
+          "--outputs-file", ".blocks-sandbox/outputs.json",
+          "--context", `projectRoot=${options.projectRoot}`,
+        ],
+        {
+          stdio: 'inherit',
+          cwd: options.projectRoot,
+          env: {
+            ...process.env,
+            NODE_OPTIONS: '--conditions=cdk',
+            ...getCdkTelemetryEnv('production')
+          }
+        }
+      );
+    } catch (error) {
+      console.error('\n❌ Deployment failed.');
+      throw error;
+    }
+    
+    const outputs = JSON.parse(readFileSync(join(options.projectRoot, '.blocks-sandbox', 'outputs.json'), 'utf-8'));
+    const stackOutputs = Object.values(outputs)[0] as Record<string, string>;
+    const apiUrl = stackOutputs.ApiUrl;
+    
+    const hostingUrl = Object.entries(stackOutputs).find(([key]) => 
+      key.includes('Hosting') && key.includes('Url')
+    )?.[1];
+    
+    if (!apiUrl) {
+      throw new Error('Could not find API URL in CDK outputs');
+    }
+    
+    // Write config.json with API endpoint
+    const config: Record<string, string> = { apiUrl, environment: 'production' };
+    const outDir = join(options.projectRoot, '.blocks-sandbox');
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(join(outDir, 'config.json'), JSON.stringify(config, null, 2));
+
+    console.log('\n✅ Deployment complete!');
+    console.log(`\n📡 API URL: ${apiUrl}`);
+    if (hostingUrl) {
+      console.log(`🌐 Frontend URL: ${hostingUrl}`);
+    }
+  });
+}

package/src/scripts/destroy.ts

@@ -0,0 +1,42 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { execFileSync } from 'node:child_process';
+import { trackCommand } from '../telemetry/trackCommand.js';
+import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+
+export interface DestroyOptions {
+  cdkAppPath: string;
+  projectRoot: string;
+}
+
+export async function destroy(options: DestroyOptions) {
+  return trackCommand('destroy', async () => {
+    console.log('🗑️  Destroying production stack...');
+
+    try {
+      execFileSync(
+        "npx",
+        [
+          "cdk", "destroy",
+          "--force",
+          "--context", `projectRoot=${options.projectRoot}`,
+        ],
+        {
+          stdio: 'inherit',
+          cwd: options.projectRoot,
+          env: {
+            ...process.env,
+            NODE_OPTIONS: '--conditions=cdk',
+            ...getCdkTelemetryEnv('production')
+          }
+        }
+      );
+    } catch (error) {
+      console.error('\n❌ Destroy failed.');
+      throw error;
+    }
+
+    console.log('\n✅ Production stack destroyed!');
+  });
+}

package/src/scripts/dev-server-cors.test.ts

@@ -0,0 +1,28 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { resolveDevCorsOrigin, LOCALHOST_PATTERN } from './dev-server.js';
+
+describe('resolveDevCorsOrigin — dev server CORS', () => {
+  it('reflects localhost origin back as-is', () => {
+    assert.strictEqual(resolveDevCorsOrigin('http://localhost:3000'), 'http://localhost:3000');
+  });
+
+  it('reflects 127.0.0.1 origin back as-is', () => {
+    assert.strictEqual(resolveDevCorsOrigin('http://127.0.0.1:3000'), 'http://127.0.0.1:3000');
+  });
+
+  it('returns fallback http://localhost:3000 for non-localhost origin', () => {
+    assert.strictEqual(resolveDevCorsOrigin('https://evil.com'), 'http://localhost:3000');
+  });
+
+  it('returns fallback http://localhost:3000 when origin is empty', () => {
+    assert.strictEqual(resolveDevCorsOrigin(''), 'http://localhost:3000');
+  });
+
+  it('rejects subdomain impersonation (evil.localhost)', () => {
+    assert.strictEqual(LOCALHOST_PATTERN.test('http://localhost.evil.com'), false);
+    assert.strictEqual(resolveDevCorsOrigin('http://localhost.evil.com'), 'http://localhost:3000');
+  });
+});