@aws/nx-plugin 1.0.0-rc.8 → 1.0.0-rc.80

package/src/ts/dynamodb/__snapshots__/generator.spec.ts.snap

@@ -1,267 +1,30 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`ts#dynamodb generator > should generate scripts for finch engine > packages/my-table/scripts/create-local-table.ts 1`] = `
-"import {
-  CreateTableCommand,
-  DescribeTableCommand,
-  DynamoDBClient,
-  GlobalSecondaryIndexDescription,
-  ResourceInUseException,
-  UpdateTableCommand,
-} from '@aws-sdk/client-dynamodb';
-import { GLOBAL_SECONDARY_INDEXES } from '../src/gsi.js';
-
-const [tableName, port] = process.argv.slice(2);
-const endpoint = \`http://localhost:\${port}\`;
-
-const REQUEST_TIMEOUT_MS = 10_000;
-const timeoutSignal = () => AbortSignal.timeout(REQUEST_TIMEOUT_MS);
-
-const client = new DynamoDBClient({
-  endpoint,
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'accessKeyId',
-    secretAccessKey: 'secretAccessKey',
+exports[`ts#dynamodb generator > should generate scripts for finch engine 1`] = `
+"{
+  "runtimeConfigKey": "MyTable",
+  "localDev": {
+    "port": 8000,
+    "tableName": "proj-my-table",
+    "image": "public.ecr.aws/aws-dynamodb-local/aws-dynamodb-local:latest",
+    "containerName": "proj-dynamodb",
+    "containerEngine": "finch"
   },
-});
-
-const waitForTableActive = async (
-  waitClient: DynamoDBClient,
-  waitTableName: string,
-): Promise<void> => {
-  for (;;) {
-    const { Table } = await waitClient.send(
-      new DescribeTableCommand({ TableName: waitTableName }),
-      { abortSignal: timeoutSignal() },
-    );
-    const allActive =
-      Table?.TableStatus === 'ACTIVE' &&
-      (Table?.GlobalSecondaryIndexes ?? []).every(
-        (g: GlobalSecondaryIndexDescription) => g.IndexStatus === 'ACTIVE',
-      );
-    if (allActive) return;
-    await new Promise((resolve) => setTimeout(resolve, 500));
-  }
-};
-
-const ensureTable = async (
-  tblClient: DynamoDBClient,
-  tblName: string,
-  gsIs: { indexName: string; partitionKey: string; sortKey: string }[],
-): Promise<void> => {
-  const gsiAttributeDefinitions = gsIs.flatMap((gsi) => [
-    { AttributeName: gsi.partitionKey, AttributeType: 'S' as const },
-    { AttributeName: gsi.sortKey, AttributeType: 'S' as const },
-  ]);
-  const attributeDefinitions = [
-    { AttributeName: 'pk', AttributeType: 'S' as const },
-    { AttributeName: 'sk', AttributeType: 'S' as const },
-    ...gsiAttributeDefinitions.filter(
-      (a, i, arr) =>
-        arr.findIndex((b) => b.AttributeName === a.AttributeName) === i,
-    ),
-  ];
-  const globalSecondaryIndexes = gsIs.map((gsi) => ({
-    IndexName: gsi.indexName,
-    KeySchema: [
-      { AttributeName: gsi.partitionKey, KeyType: 'HASH' as const },
-      { AttributeName: gsi.sortKey, KeyType: 'RANGE' as const },
-    ],
-    Projection: { ProjectionType: 'ALL' as const },
-  }));
-
-  for (let attempt = 0; attempt < 30; attempt++) {
-    try {
-      // New table: create with all GSIs in one shot.
-      await tblClient.send(
-        new CreateTableCommand({
-          TableName: tblName,
-          AttributeDefinitions: attributeDefinitions,
-          KeySchema: [
-            { AttributeName: 'pk', KeyType: 'HASH' },
-            { AttributeName: 'sk', KeyType: 'RANGE' },
-          ],
-          BillingMode: 'PAY_PER_REQUEST',
-          ...(globalSecondaryIndexes.length > 0 && {
-            GlobalSecondaryIndexes: globalSecondaryIndexes,
-          }),
-        }),
-        { abortSignal: timeoutSignal() },
-      );
-      console.log(\`Created table: \${tblName}\`);
-      for (const gsi of globalSecondaryIndexes) {
-        console.log(\`Created GSI: \${gsi.IndexName}\`);
-      }
-      return;
-    } catch (e) {
-      // Table already exists: sync GSIs to match desired state.
-      if (e instanceof ResourceInUseException) {
-        const { Table } = await tblClient.send(
-          new DescribeTableCommand({ TableName: tblName }),
-          { abortSignal: timeoutSignal() },
-        );
-        const existingGSIs = Table?.GlobalSecondaryIndexes ?? [];
-        const existingNames = new Set(
-          existingGSIs.map(
-            (g: GlobalSecondaryIndexDescription) => g.IndexName ?? '',
-          ),
-        );
-        const desiredNames = new Set(gsIs.map((g) => g.indexName));
-
-        // DynamoDB Local only allows one GSI to be created or deleted at a time.
-        for (const existing of existingGSIs) {
-          if (!existing.IndexName || desiredNames.has(existing.IndexName))
-            continue;
-          await tblClient.send(
-            new UpdateTableCommand({
-              TableName: tblName,
-              GlobalSecondaryIndexUpdates: [
-                { Delete: { IndexName: existing.IndexName } },
-              ],
-            }),
-            { abortSignal: timeoutSignal() },
-          );
-          console.log(\`Deleted GSI: \${existing.IndexName}\`);
-          await waitForTableActive(tblClient, tblName);
-        }
-
-        for (const gsi of gsIs) {
-          if (existingNames.has(gsi.indexName)) continue;
-          await tblClient.send(
-            new UpdateTableCommand({
-              TableName: tblName,
-              AttributeDefinitions: [
-                { AttributeName: gsi.partitionKey, AttributeType: 'S' },
-                { AttributeName: gsi.sortKey, AttributeType: 'S' },
-              ],
-              GlobalSecondaryIndexUpdates: [
-                {
-                  Create: {
-                    IndexName: gsi.indexName,
-                    KeySchema: [
-                      { AttributeName: gsi.partitionKey, KeyType: 'HASH' },
-                      { AttributeName: gsi.sortKey, KeyType: 'RANGE' },
-                    ],
-                    Projection: { ProjectionType: 'ALL' },
-                  },
-                },
-              ],
-            }),
-            { abortSignal: timeoutSignal() },
-          );
-          console.log(\`Created GSI: \${gsi.indexName}\`);
-          await waitForTableActive(tblClient, tblName);
-        }
-        return;
+  "tableConfig": {
+    "globalSecondaryIndexes": [
+      {
+        "indexName": "gsi1pk-gsi1sk-index",
+        "partitionKey": "gsi1pk",
+        "sortKey": "gsi1sk"
+      },
+      {
+        "indexName": "gsi2pk-gsi2sk-index",
+        "partitionKey": "gsi2pk",
+        "sortKey": "gsi2sk"
       }
-      if (attempt === 29) throw e;
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-    }
-  }
-};
-
-await ensureTable(client, tableName, GLOBAL_SECONDARY_INDEXES);
-"
-`;
-
-exports[`ts#dynamodb generator > should generate scripts for finch engine > packages/my-table/scripts/pull-image.ts 1`] = `
-"import { spawnSync } from 'child_process';
-
-const ENGINE = 'finch';
-const image = process.argv[2];
-
-const inspect = spawnSync(ENGINE, ['image', 'inspect', image], {
-  stdio: 'ignore',
-});
-
-if (inspect.status !== 0) {
-  const pull = spawnSync(ENGINE, ['pull', image], { stdio: 'inherit' });
-  if (pull.status !== 0) {
-    process.exit(pull.status ?? 1);
-  }
-}
-"
-`;
-
-exports[`ts#dynamodb generator > should generate scripts for finch engine > packages/my-table/scripts/start-container.ts 1`] = `
-"import { spawn, spawnSync } from 'child_process';
-
-const ENGINE = 'finch';
-
-const [containerName, image, hostPort] = process.argv.slice(2);
-
-const containerExists = (): boolean =>
-  spawnSync(ENGINE, ['container', 'inspect', containerName], {
-    stdio: 'ignore',
-  }).status === 0;
-
-const isRunning = (): boolean => {
-  const result = spawnSync(
-    ENGINE,
-    ['container', 'inspect', '-f', '{{.State.Running}}', containerName],
-    { encoding: 'utf-8' },
-  );
-  return result.status === 0 && result.stdout.trim() === 'true';
-};
-
-// Multiple dynamo table packages run serve-local in parallel sharing the same
-// container. All processes stream logs, but only the one that created the
-// container stops it on exit — others just detach.
-let created = false;
-let runRetries = 0;
-
-for (;;) {
-  if (containerExists()) {
-    if (!isRunning()) {
-      // Another process may have started it between our inspect and start — container engine start
-      // exits 0 even if the container is already running, so no special-casing needed.
-      const start = spawnSync(ENGINE, ['start', containerName], {
-        stdio: 'inherit',
-      });
-      if (start.status !== 0) process.exit(start.status ?? 1);
-    }
-    break;
-  }
-  const runArgs = (
-    \`run --name \${containerName} -u root -w /home/dynamodblocal\` +
-    \` -p \${hostPort}:\${hostPort} -v \${containerName}-data:/home/dynamodblocal/data\` +
-    \` -d \${image} -jar DynamoDBLocal.jar -sharedDb -dbPath ./data -port \${hostPort} -optimizeDbBeforeStartup\`
-  ).split(' ');
-  const create = spawnSync(ENGINE, runArgs, { stdio: 'pipe' });
-  if (create.status === 0) {
-    created = true;
-    break;
-  }
-  if (!containerExists() && ++runRetries > 3) {
-    process.stderr.write(create.stderr);
-    process.exit(create.status ?? 1);
+    ]
   }
 }
-
-const logs = spawn(ENGINE, ['logs', '-f', containerName], {
-  stdio: ['ignore', 'inherit', 'inherit'],
-});
-
-let exiting = false;
-
-const cleanup = () => {
-  if (exiting) return;
-  exiting = true;
-  if (created) {
-    spawnSync(ENGINE, ['rm', '-f', containerName], { stdio: 'ignore' });
-  }
-  logs.kill();
-  process.exit(0);
-};
-
-process.on('SIGTERM', cleanup);
-process.on('SIGINT', cleanup);
-process.on('SIGHUP', cleanup);
-
-logs.on('exit', (code) => {
-  if (!exiting) process.exit(code ?? 0);
-});
 "
 `;
 
@@ -272,7 +35,7 @@ exports[`ts#dynamodb generator > should generate terraform modules when iac is t
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = "~> 6.0"
+      version = "6.60.0"
     }
   }
 }
@@ -300,8 +63,31 @@ variable "deletion_protection_enabled" {
   default     = true
 }
 
+variable "encryption" {
+  description = "Server-side encryption for the table. One of CUSTOMER_MANAGED, AWS_MANAGED or DEFAULT (the AWS owned key, at no cost and with no key to manage). Changing this on an already-deployed table away from CUSTOMER_MANAGED requires a manual step first - see the ts#dynamodb generator's docs."
+  type        = string
+  default     = "CUSTOMER_MANAGED"
+
+  validation {
+    condition     = contains(["CUSTOMER_MANAGED", "AWS_MANAGED", "DEFAULT"], var.encryption)
+    error_message = "encryption must be one of CUSTOMER_MANAGED, AWS_MANAGED or DEFAULT."
+  }
+}
+
+variable "kms_key_arn" {
+  description = "ARN of an existing KMS key used to encrypt the table when encryption is CUSTOMER_MANAGED. When not provided and create_kms_key is true, a new key is created. Note that a customer-supplied key must already grant the DynamoDB service the necessary permissions in its own key policy."
+  type        = string
+  default     = null
+}
+
+variable "create_kms_key" {
+  description = "Whether to create a KMS key for the table. Only applies when encryption is CUSTOMER_MANAGED. Set to false when supplying kms_key_arn."
+  type        = bool
+  default     = true
+}
+
 variable "enable_key_rotation" {
-  description = "Whether to enable automatic key rotation on the KMS key used to encrypt the table."
+  description = "Whether to enable automatic key rotation on the KMS key used to encrypt the table. Only applies when encryption is CUSTOMER_MANAGED and create_kms_key is true."
   type        = bool
   default     = true
 }
@@ -321,12 +107,22 @@ locals {
   gsi_attribute_names = distinct(flatten([
     for gsi in var.global_secondary_indexes : [gsi.hash_key, gsi.range_key]
   ]))
+
+  create_table_key = var.encryption == "CUSTOMER_MANAGED" && var.create_kms_key
+  table_kms_key_arn = (
+    var.encryption == "CUSTOMER_MANAGED" ? (local.create_table_key ? aws_kms_key.table[0].arn : var.kms_key_arn) :
+    var.encryption == "AWS_MANAGED" ? "arn:\${data.aws_partition.current.partition}:kms:\${data.aws_region.current.region}:\${data.aws_caller_identity.current.account_id}:alias/aws/dynamodb" :
+    null
+  )
 }
 
 data "aws_caller_identity" "current" {}
 data "aws_partition" "current" {}
+data "aws_region" "current" {}
 
 resource "aws_kms_key" "table" {
+  count = local.create_table_key ? 1 : 0
+
   description         = "KMS key for DynamoDB table \${var.name}"
   enable_key_rotation = var.enable_key_rotation
 
@@ -363,6 +159,7 @@ resource "aws_kms_key" "table" {
 }
 
 resource "aws_dynamodb_table" "table" {
+  #checkov:skip=CKV_AWS_119:Encryption is configurable via var.encryption; checkov cannot resolve the conditional server_side_encryption.enabled expression
   name                        = var.name
   billing_mode                = var.billing_mode
   hash_key                    = "pk"
@@ -402,8 +199,8 @@ resource "aws_dynamodb_table" "table" {
   }
 
   server_side_encryption {
-    enabled     = true
-    kms_key_arn = aws_kms_key.table.arn
+    enabled     = var.encryption != "DEFAULT"
+    kms_key_arn = local.table_kms_key_arn
   }
 }
 
@@ -418,8 +215,8 @@ output "table_arn" {
 }
 
 output "kms_key_arn" {
-  description = "ARN of the KMS key used to encrypt the DynamoDB table."
-  value       = aws_kms_key.table.arn
+  description = "ARN of the KMS key used to encrypt the DynamoDB table, or null when using the AWS owned key (encryption = DEFAULT)."
+  value       = local.table_kms_key_arn
 }
 "
 `;
@@ -429,7 +226,11 @@ exports[`ts#dynamodb generator > should generate terraform modules when iac is t
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = "~> 6.0"
+      version = "6.60.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "3.9.0"
     }
   }
 }
@@ -452,40 +253,69 @@ variable "deletion_protection_enabled" {
   default     = true
 }
 
+variable "encryption" {
+  description = "Server-side encryption for the table. One of CUSTOMER_MANAGED, AWS_MANAGED or DEFAULT (the AWS owned key, at no cost and with no key to manage). Changing this on an already-deployed table away from CUSTOMER_MANAGED requires a manual step first - see the ts#dynamodb generator's docs."
+  type        = string
+  default     = "CUSTOMER_MANAGED"
+
+  validation {
+    condition     = contains(["CUSTOMER_MANAGED", "AWS_MANAGED", "DEFAULT"], var.encryption)
+    error_message = "encryption must be one of CUSTOMER_MANAGED, AWS_MANAGED or DEFAULT."
+  }
+}
+
+variable "kms_key_arn" {
+  description = "ARN of an existing KMS key used to encrypt the table when encryption is CUSTOMER_MANAGED. When not provided and create_kms_key is true, a new key is created. Note that a customer-supplied key must already grant the DynamoDB service the necessary permissions in its own key policy."
+  type        = string
+  default     = null
+}
+
+variable "create_kms_key" {
+  description = "Whether to create a KMS key for the table. Only applies when encryption is CUSTOMER_MANAGED. Set to false when supplying kms_key_arn."
+  type        = bool
+  default     = true
+}
+
 variable "enable_key_rotation" {
-  description = "Whether to enable automatic key rotation on the KMS key used to encrypt the table."
+  description = "Whether to enable automatic key rotation on the KMS key used to encrypt the table. Only applies when encryption is CUSTOMER_MANAGED and create_kms_key is true."
   type        = bool
   default     = true
 }
 
+resource "random_string" "suffix" {
+  length  = 8
+  special = false
+  upper   = false
+}
+
+locals {
+  dynamodb_config = jsondecode(file("\${path.module}/../../../../../../../packages/my-table/config.json"))
+  global_secondary_indexes = [for gsi in local.dynamodb_config.tableConfig.globalSecondaryIndexes : {
+    name            = gsi.indexName
+    hash_key        = gsi.partitionKey
+    range_key       = try(gsi.sortKey, null)
+    projection_type = "ALL"
+  }]
+}
+
 module "dynamodb_table" {
   source                         = "../../../core/dynamodb"
-  name                           = "proj-my-table"
+  name                           = "proj-my-table-\${random_string.suffix.result}"
   billing_mode                   = var.billing_mode
   point_in_time_recovery_enabled = var.point_in_time_recovery_enabled
   deletion_protection_enabled    = var.deletion_protection_enabled
+  encryption                     = var.encryption
+  kms_key_arn                    = var.kms_key_arn
+  create_kms_key                 = var.create_kms_key
   enable_key_rotation            = var.enable_key_rotation
-  global_secondary_indexes = [
-    {
-      name            = "gsi1pk-gsi1sk-index"
-      hash_key        = "gsi1pk"
-      range_key       = "gsi1sk"
-      projection_type = "ALL"
-    },
-    {
-      name            = "gsi2pk-gsi2sk-index"
-      hash_key        = "gsi2pk"
-      range_key       = "gsi2sk"
-      projection_type = "ALL"
-    },
-  ]
+  global_secondary_indexes       = local.global_secondary_indexes
 }
 
 module "add_to_runtime_config" {
   source = "../../../core/runtime-config/entry"
 
   namespace = "dynamodb"
-  key       = "MyTable"
+  key       = local.dynamodb_config.runtimeConfigKey
   value = {
     tableName = module.dynamodb_table.table_name
   }
@@ -493,30 +323,43 @@ module "add_to_runtime_config" {
 "
 `;
 
-exports[`ts#dynamodb generator > should generate the dynamodb project > packages/my-table/scripts/create-local-table.ts 1`] = `
+exports[`ts#dynamodb generator > should generate the dynamodb project > packages/common/scripts/src/dynamodb/create-local-table.ts 1`] = `
 "import {
+  BillingMode,
   CreateTableCommand,
   DescribeTableCommand,
   DynamoDBClient,
   GlobalSecondaryIndexDescription,
+  IndexStatus,
+  KeyType,
+  ProjectionType,
   ResourceInUseException,
+  ScalarAttributeType,
+  TableStatus,
   UpdateTableCommand,
 } from '@aws-sdk/client-dynamodb';
-import { GLOBAL_SECONDARY_INDEXES } from '../src/gsi.js';
-
-const [tableName, port] = process.argv.slice(2);
-const endpoint = \`http://localhost:\${port}\`;
+import { readFileSync } from 'fs';
+
+const {
+  localDev: { port, tableName },
+  tableConfig: { globalSecondaryIndexes },
+} = JSON.parse(readFileSync('config.json', 'utf-8')) as {
+  localDev: { port: number; tableName: string };
+  tableConfig: {
+    globalSecondaryIndexes: {
+      indexName: string;
+      partitionKey: string;
+      sortKey?: string;
+    }[];
+  };
+};
 
-const REQUEST_TIMEOUT_MS = 10_000;
-const timeoutSignal = () => AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+const timeoutSignal = () => AbortSignal.timeout(10000);
 
 const client = new DynamoDBClient({
-  endpoint,
+  endpoint: \`http://localhost:\${port}\`,
   region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'accessKeyId',
-    secretAccessKey: 'secretAccessKey',
-  },
+  credentials: { accessKeyId: 'UNUSED', secretAccessKey: 'UNUSED' },
 });
 
 const waitForTableActive = async (
@@ -529,9 +372,10 @@ const waitForTableActive = async (
       { abortSignal: timeoutSignal() },
     );
     const allActive =
-      Table?.TableStatus === 'ACTIVE' &&
+      Table?.TableStatus === TableStatus.ACTIVE &&
       (Table?.GlobalSecondaryIndexes ?? []).every(
-        (g: GlobalSecondaryIndexDescription) => g.IndexStatus === 'ACTIVE',
+        (g: GlobalSecondaryIndexDescription) =>
+          g.IndexStatus === IndexStatus.ACTIVE,
       );
     if (allActive) return;
     await new Promise((resolve) => setTimeout(resolve, 500));
@@ -541,15 +385,17 @@ const waitForTableActive = async (
 const ensureTable = async (
   tblClient: DynamoDBClient,
   tblName: string,
-  gsIs: { indexName: string; partitionKey: string; sortKey: string }[],
+  gsIs: { indexName: string; partitionKey: string; sortKey?: string }[],
 ): Promise<void> => {
   const gsiAttributeDefinitions = gsIs.flatMap((gsi) => [
-    { AttributeName: gsi.partitionKey, AttributeType: 'S' as const },
-    { AttributeName: gsi.sortKey, AttributeType: 'S' as const },
+    { AttributeName: gsi.partitionKey, AttributeType: ScalarAttributeType.S },
+    ...(gsi.sortKey
+      ? [{ AttributeName: gsi.sortKey, AttributeType: ScalarAttributeType.S }]
+      : []),
   ]);
   const attributeDefinitions = [
-    { AttributeName: 'pk', AttributeType: 'S' as const },
-    { AttributeName: 'sk', AttributeType: 'S' as const },
+    { AttributeName: 'pk', AttributeType: ScalarAttributeType.S },
+    { AttributeName: 'sk', AttributeType: ScalarAttributeType.S },
     ...gsiAttributeDefinitions.filter(
       (a, i, arr) =>
         arr.findIndex((b) => b.AttributeName === a.AttributeName) === i,
@@ -558,10 +404,12 @@ const ensureTable = async (
   const globalSecondaryIndexes = gsIs.map((gsi) => ({
     IndexName: gsi.indexName,
     KeySchema: [
-      { AttributeName: gsi.partitionKey, KeyType: 'HASH' as const },
-      { AttributeName: gsi.sortKey, KeyType: 'RANGE' as const },
+      { AttributeName: gsi.partitionKey, KeyType: KeyType.HASH },
+      ...(gsi.sortKey
+        ? [{ AttributeName: gsi.sortKey, KeyType: KeyType.RANGE }]
+        : []),
     ],
-    Projection: { ProjectionType: 'ALL' as const },
+    Projection: { ProjectionType: ProjectionType.ALL },
   }));
 
   for (let attempt = 0; attempt < 30; attempt++) {
@@ -572,10 +420,10 @@ const ensureTable = async (
           TableName: tblName,
           AttributeDefinitions: attributeDefinitions,
           KeySchema: [
-            { AttributeName: 'pk', KeyType: 'HASH' },
-            { AttributeName: 'sk', KeyType: 'RANGE' },
+            { AttributeName: 'pk', KeyType: KeyType.HASH },
+            { AttributeName: 'sk', KeyType: KeyType.RANGE },
           ],
-          BillingMode: 'PAY_PER_REQUEST',
+          BillingMode: BillingMode.PAY_PER_REQUEST,
           ...(globalSecondaryIndexes.length > 0 && {
             GlobalSecondaryIndexes: globalSecondaryIndexes,
           }),
@@ -625,18 +473,38 @@ const ensureTable = async (
             new UpdateTableCommand({
               TableName: tblName,
               AttributeDefinitions: [
-                { AttributeName: gsi.partitionKey, AttributeType: 'S' },
-                { AttributeName: gsi.sortKey, AttributeType: 'S' },
+                {
+                  AttributeName: gsi.partitionKey,
+                  AttributeType: ScalarAttributeType.S,
+                },
+                ...(gsi.sortKey
+                  ? [
+                      {
+                        AttributeName: gsi.sortKey,
+                        AttributeType: ScalarAttributeType.S,
+                      },
+                    ]
+                  : []),
               ],
               GlobalSecondaryIndexUpdates: [
                 {
                   Create: {
                     IndexName: gsi.indexName,
                     KeySchema: [
-                      { AttributeName: gsi.partitionKey, KeyType: 'HASH' },
-                      { AttributeName: gsi.sortKey, KeyType: 'RANGE' },
+                      {
+                        AttributeName: gsi.partitionKey,
+                        KeyType: KeyType.HASH,
+                      },
+                      ...(gsi.sortKey
+                        ? [
+                            {
+                              AttributeName: gsi.sortKey,
+                              KeyType: KeyType.RANGE,
+                            },
+                          ]
+                        : []),
                     ],
-                    Projection: { ProjectionType: 'ALL' },
+                    Projection: { ProjectionType: ProjectionType.ALL },
                   },
                 },
               ],
@@ -654,22 +522,25 @@ const ensureTable = async (
   }
 };
 
-await ensureTable(client, tableName, GLOBAL_SECONDARY_INDEXES);
+await ensureTable(client, tableName, globalSecondaryIndexes);
 "
 `;
 
-exports[`ts#dynamodb generator > should generate the dynamodb project > packages/my-table/scripts/pull-image.ts 1`] = `
+exports[`ts#dynamodb generator > should generate the dynamodb project > packages/common/scripts/src/dynamodb/pull-image.ts 1`] = `
 "import { spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
 
-const ENGINE = 'docker';
-const image = process.argv[2];
+const { containerEngine, image } = JSON.parse(
+  readFileSync('config.json', 'utf-8'),
+).localDev;
 
-const inspect = spawnSync(ENGINE, ['image', 'inspect', image], {
+const inspect = spawnSync(containerEngine, ['image', 'inspect', image], {
   stdio: 'ignore',
 });
-
 if (inspect.status !== 0) {
-  const pull = spawnSync(ENGINE, ['pull', image], { stdio: 'inherit' });
+  const pull = spawnSync(containerEngine, ['pull', image], {
+    stdio: 'inherit',
+  });
   if (pull.status !== 0) {
     process.exit(pull.status ?? 1);
   }
@@ -677,51 +548,85 @@ if (inspect.status !== 0) {
 "
 `;
 
-exports[`ts#dynamodb generator > should generate the dynamodb project > packages/my-table/scripts/start-container.ts 1`] = `
+exports[`ts#dynamodb generator > should generate the dynamodb project > packages/common/scripts/src/dynamodb/start-container.ts 1`] = `
 "import { spawn, spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
 
-const ENGINE = 'docker';
-
-const [containerName, image, hostPort] = process.argv.slice(2);
+const { containerEngine, containerName, image, port } = JSON.parse(
+  readFileSync('config.json', 'utf-8'),
+).localDev;
 
 const containerExists = (): boolean =>
-  spawnSync(ENGINE, ['container', 'inspect', containerName], {
+  spawnSync(containerEngine, ['container', 'inspect', containerName], {
     stdio: 'ignore',
   }).status === 0;
 
 const isRunning = (): boolean => {
   const result = spawnSync(
-    ENGINE,
+    containerEngine,
     ['container', 'inspect', '-f', '{{.State.Running}}', containerName],
     { encoding: 'utf-8' },
   );
   return result.status === 0 && result.stdout.trim() === 'true';
 };
 
-// Multiple dynamo table packages run serve-local in parallel sharing the same
+// Ensure the image is available locally before starting the container.
+const ensureImage = (): void => {
+  const inspect = spawnSync(containerEngine, ['image', 'inspect', image], {
+    stdio: 'ignore',
+  });
+  if (inspect.status !== 0) {
+    const pull = spawnSync(containerEngine, ['pull', image], {
+      stdio: 'inherit',
+    });
+    if (pull.status !== 0) process.exit(pull.status ?? 1);
+  }
+};
+
+// Multiple dynamo table packages run dev in parallel sharing the same
 // container. All processes stream logs, but only the one that created the
 // container stops it on exit — others just detach.
 let created = false;
 let runRetries = 0;
 
+ensureImage();
+
 for (;;) {
   if (containerExists()) {
     if (!isRunning()) {
       // Another process may have started it between our inspect and start — container engine start
       // exits 0 even if the container is already running, so no special-casing needed.
-      const start = spawnSync(ENGINE, ['start', containerName], {
+      const start = spawnSync(containerEngine, ['start', containerName], {
         stdio: 'inherit',
       });
       if (start.status !== 0) process.exit(start.status ?? 1);
     }
     break;
   }
-  const runArgs = (
-    \`run --rm --name \${containerName} -u root -w /home/dynamodblocal\` +
-    \` -p \${hostPort}:\${hostPort} -v \${containerName}-data:/home/dynamodblocal/data\` +
-    \` -d \${image} -jar DynamoDBLocal.jar -sharedDb -dbPath ./data -port \${hostPort} -optimizeDbBeforeStartup\`
-  ).split(' ');
-  const create = spawnSync(ENGINE, runArgs, { stdio: 'pipe' });
+  const runArgs = [
+    'run',
+    ...(containerEngine === 'docker' ? ['--rm'] : []),
+    '--name',
+    containerName,
+    '-u',
+    'root',
+    '-w',
+    '/home/dynamodblocal',
+    \`-p\`,
+    \`\${port}:\${port}\`,
+    '-v',
+    \`\${containerName}-data:/home/dynamodblocal/data\`,
+    '-d',
+    image,
+    '-jar',
+    'DynamoDBLocal.jar',
+    '-sharedDb',
+    '-dbPath',
+    './data',
+    '-port',
+    \`\${port}\`,
+  ];
+  const create = spawnSync(containerEngine, runArgs, { stdio: 'pipe' });
   if (create.status === 0) {
     created = true;
     break;
@@ -732,7 +637,7 @@ for (;;) {
   }
 }
 
-const logs = spawn(ENGINE, ['logs', '-f', containerName], {
+const logs = spawn(containerEngine, ['logs', '-f', containerName], {
   stdio: ['ignore', 'inherit', 'inherit'],
 });
 
@@ -742,7 +647,13 @@ const cleanup = () => {
   if (exiting) return;
   exiting = true;
   if (created) {
-    spawnSync(ENGINE, ['stop', containerName], { stdio: 'ignore' });
+    if (containerEngine === 'docker') {
+      spawnSync(containerEngine, ['stop', containerName], { stdio: 'ignore' });
+    } else {
+      spawnSync(containerEngine, ['rm', '-f', containerName], {
+        stdio: 'ignore',
+      });
+    }
   }
   logs.kill();
   process.exit(0);
@@ -752,38 +663,40 @@ process.on('SIGTERM', cleanup);
 process.on('SIGINT', cleanup);
 process.on('SIGHUP', cleanup);
 
-logs.on('exit', (code) => {
-  if (!exiting) process.exit(code ?? 0);
-});
+logs.on('exit', cleanup);
 "
 `;
 
 exports[`ts#dynamodb generator > should generate the dynamodb project > packages/my-table/src/client.ts 1`] = `
 "import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
-import {
-  PACKAGE_NAME,
-  LOCAL_ACCESS_KEY_ID,
-  LOCAL_ENDPOINT,
-  LOCAL_REGION,
-  LOCAL_SECRET_ACCESS_KEY,
-  LOCAL_TABLE_NAME,
-} from './constants.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// Generated: must match runtimeConfigKey in config.json
+const runtimeConfigKey = 'MyTable';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// config.json is only present in local dev (not included in the deployed bundle); guard with LOCAL_DEV check
+const localDev = () =>
+  JSON.parse(readFileSync(join(__dirname, '../config.json'), 'utf-8')).localDev;
 
 let _client: DynamoDBClient | undefined;
 
 export const getDynamoDBClient = (): DynamoDBClient => {
-  _client ??=
-    process.env.SERVE_LOCAL === 'true'
-      ? new DynamoDBClient({
-          endpoint: LOCAL_ENDPOINT,
-          region: LOCAL_REGION,
-          credentials: {
-            accessKeyId: LOCAL_ACCESS_KEY_ID,
-            secretAccessKey: LOCAL_SECRET_ACCESS_KEY,
-          },
-        })
-      : new DynamoDBClient({});
+  if (!_client) {
+    if (process.env.LOCAL_DEV === 'true') {
+      const { port } = localDev();
+      _client = new DynamoDBClient({
+        endpoint: \`http://localhost:\${port}\`,
+        region: 'us-east-1',
+        credentials: { accessKeyId: 'UNUSED', secretAccessKey: 'UNUSED' },
+      });
+    } else {
+      _client = new DynamoDBClient({});
+    }
+  }
   return _client;
 };
 
@@ -794,8 +707,9 @@ type DynamoDBConfig = {
 let _tableName: string | undefined;
 
 export const resolveTableName = async (): Promise<string> => {
-  if (process.env.SERVE_LOCAL === 'true') {
-    return LOCAL_TABLE_NAME;
+  if (process.env.LOCAL_DEV === 'true') {
+    const { tableName } = localDev();
+    return tableName;
   }
   if (_tableName === undefined) {
     const appId = process.env.RUNTIME_CONFIG_APP_ID;
@@ -809,7 +723,7 @@ export const resolveTableName = async (): Promise<string> => {
       environment: 'default',
       transform: 'json',
     });
-    const tableName = config?.[PACKAGE_NAME]?.tableName;
+    const tableName = config?.[runtimeConfigKey]?.tableName;
     if (!tableName) {
       throw new Error('Could not resolve table name from runtime config');
     }
@@ -820,19 +734,6 @@ export const resolveTableName = async (): Promise<string> => {
 "
 `;
 
-exports[`ts#dynamodb generator > should generate the dynamodb project > packages/my-table/src/constants.ts 1`] = `
-"export const PACKAGE_NAME = 'MyTable';
-
-// Local development connection details (used when SERVE_LOCAL=true, see serve-local Nx target)
-export const LOCAL_PORT = 8000;
-export const LOCAL_REGION = 'us-east-1';
-export const LOCAL_ACCESS_KEY_ID = 'accessKeyId';
-export const LOCAL_SECRET_ACCESS_KEY = 'secretAccessKey';
-export const LOCAL_ENDPOINT = \`http://localhost:\${LOCAL_PORT}\`;
-export const LOCAL_TABLE_NAME = 'proj-my-table';
-"
-`;
-
 exports[`ts#dynamodb generator > should generate the dynamodb project > packages/my-table/src/entities/example.ts 1`] = `
 "import { Entity } from 'electrodb';
 import { getDynamoDBClient, resolveTableName } from '../client.js';
@@ -889,35 +790,8 @@ exports[`ts#dynamodb generator > should generate the dynamodb project > packages
 "
 `;
 
-exports[`ts#dynamodb generator > should generate the dynamodb project > packages/my-table/src/gsi.ts 1`] = `
-"// GSIs to synchronize on the local table at startup and provision in infrastructure.
-// ElectroDB names GSI keys gsi{n}pk / gsi{n}sk — add one entry per index defined in your entities.
-export const GLOBAL_SECONDARY_INDEXES = [
-  {
-    indexName: 'gsi1pk-gsi1sk-index',
-    partitionKey: 'gsi1pk',
-    sortKey: 'gsi1sk',
-  },
-  {
-    indexName: 'gsi2pk-gsi2sk-index',
-    partitionKey: 'gsi2pk',
-    sortKey: 'gsi2sk',
-  },
-];
-"
-`;
-
 exports[`ts#dynamodb generator > should generate the dynamodb project > packages/my-table/src/index.ts 1`] = `
-"export {
-  PACKAGE_NAME,
-  LOCAL_ACCESS_KEY_ID,
-  LOCAL_ENDPOINT,
-  LOCAL_REGION,
-  LOCAL_SECRET_ACCESS_KEY,
-  LOCAL_TABLE_NAME,
-} from './constants.js';
-export { getDynamoDBClient, resolveTableName } from './client.js';
-export { GLOBAL_SECONDARY_INDEXES } from './gsi.js';
+"export { getDynamoDBClient, resolveTableName } from './client.js';
 export * from './entities/index.js';
 "
 `;
@@ -933,7 +807,7 @@ import {
 } from 'aws-cdk-lib/aws-dynamodb';
 import { RemovalPolicy } from 'aws-cdk-lib';
 import { Grant, IGrantable } from 'aws-cdk-lib/aws-iam';
-import { Key } from 'aws-cdk-lib/aws-kms';
+import { IKey, Key } from 'aws-cdk-lib/aws-kms';
 import { RuntimeConfig } from './runtime-config.js';
 
 type _DynamoDBTableProps = Omit<
@@ -953,8 +827,23 @@ export interface DynamoDBTableProps extends _DynamoDBTableProps {
    */
   readonly runtimeConfigKey: string;
 
+  /**
+   * Server-side encryption for the table.
+   *
+   * @default TableEncryption.CUSTOMER_MANAGED
+   */
+  readonly encryption?: TableEncryption;
+
+  /**
+   * KMS key used to encrypt the table. Only used when \`encryption\` is
+   * \`TableEncryption.CUSTOMER_MANAGED\`. When not provided, a new key is created.
+   */
+  readonly encryptionKey?: IKey;
+
   /**
    * Whether to enable automatic key rotation on the KMS key used to encrypt the table.
+   * Only applies when \`encryption\` is \`TableEncryption.CUSTOMER_MANAGED\` and no
+   * \`encryptionKey\` is supplied.
    *
    * @default true
    */
@@ -974,13 +863,19 @@ export abstract class DynamoDBTable extends Construct {
       pointInTimeRecoverySpecification = { pointInTimeRecoveryEnabled: true },
       deletionProtection = true,
       removalPolicy = RemovalPolicy.RETAIN,
+      encryption = TableEncryption.CUSTOMER_MANAGED,
+      encryptionKey,
       enableKeyRotation = true,
       ...rest
     }: DynamoDBTableProps,
   ) {
     super(scope, id);
 
-    const key = new Key(this, 'EncryptionKey', { enableKeyRotation });
+    const key: IKey | undefined =
+      encryption === TableEncryption.CUSTOMER_MANAGED
+        ? (encryptionKey ??
+          new Key(this, 'EncryptionKey', { enableKeyRotation }))
+        : undefined;
 
     this.table = new Table(this, runtimeConfigKey, {
       ...rest,
@@ -991,7 +886,7 @@ export abstract class DynamoDBTable extends Construct {
       pointInTimeRecoverySpecification,
       deletionProtection,
       encryptionKey: key,
-      encryption: TableEncryption.CUSTOMER_MANAGED,
+      encryption,
       removalPolicy,
     });
 
@@ -1036,9 +931,31 @@ export abstract class DynamoDBTable extends Construct {
 
 exports[`ts#dynamodb generator > should generate the dynamodb project 2`] = `
 "import { Construct } from 'constructs';
-import { PACKAGE_NAME, GLOBAL_SECONDARY_INDEXES } from ':proj/my-table';
 import { AttributeType, ProjectionType } from 'aws-cdk-lib/aws-dynamodb';
 import { DynamoDBTable, DynamoDBTableProps } from '../../core/dynamodb.js';
+import { findWorkspaceRoot } from '../../core/workspace.js';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+
+const { runtimeConfigKey, tableConfig } = JSON.parse(
+  readFileSync(
+    join(
+      findWorkspaceRoot(fileURLToPath(new URL(import.meta.url))),
+      'packages/my-table/config.json',
+    ),
+    'utf-8',
+  ),
+) as {
+  runtimeConfigKey: string;
+  tableConfig: {
+    globalSecondaryIndexes: {
+      indexName: string;
+      partitionKey: string;
+      sortKey?: string;
+    }[];
+  };
+};
 
 export type MyTableProps = Omit<DynamoDBTableProps, 'runtimeConfigKey'>;
 
@@ -1046,14 +963,16 @@ export class MyTable extends DynamoDBTable {
   constructor(scope: Construct, id: string, props?: MyTableProps) {
     super(scope, id, {
       ...props,
-      runtimeConfigKey: PACKAGE_NAME,
+      runtimeConfigKey,
     });
 
-    for (const gsi of GLOBAL_SECONDARY_INDEXES) {
+    for (const gsi of tableConfig.globalSecondaryIndexes) {
       this.table.addGlobalSecondaryIndex({
         indexName: gsi.indexName,
         partitionKey: { name: gsi.partitionKey, type: AttributeType.STRING },
-        sortKey: { name: gsi.sortKey, type: AttributeType.STRING },
+        ...(gsi.sortKey && {
+          sortKey: { name: gsi.sortKey, type: AttributeType.STRING },
+        }),
         projectionType: ProjectionType.ALL,
       });
     }
@@ -1072,30 +991,43 @@ exports[`ts#dynamodb generator > should generate the dynamodb project 4`] = `
 "
 `;
 
-exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my-table/scripts/create-local-table.ts 1`] = `
+exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/common/scripts/src/dynamodb/create-local-table.ts 1`] = `
 "import {
+  BillingMode,
   CreateTableCommand,
   DescribeTableCommand,
   DynamoDBClient,
   GlobalSecondaryIndexDescription,
+  IndexStatus,
+  KeyType,
+  ProjectionType,
   ResourceInUseException,
+  ScalarAttributeType,
+  TableStatus,
   UpdateTableCommand,
 } from '@aws-sdk/client-dynamodb';
-import { GLOBAL_SECONDARY_INDEXES } from '../src/gsi.js';
-
-const [tableName, port] = process.argv.slice(2);
-const endpoint = \`http://localhost:\${port}\`;
+import { readFileSync } from 'fs';
+
+const {
+  localDev: { port, tableName },
+  tableConfig: { globalSecondaryIndexes },
+} = JSON.parse(readFileSync('config.json', 'utf-8')) as {
+  localDev: { port: number; tableName: string };
+  tableConfig: {
+    globalSecondaryIndexes: {
+      indexName: string;
+      partitionKey: string;
+      sortKey?: string;
+    }[];
+  };
+};
 
-const REQUEST_TIMEOUT_MS = 10_000;
-const timeoutSignal = () => AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+const timeoutSignal = () => AbortSignal.timeout(10000);
 
 const client = new DynamoDBClient({
-  endpoint,
+  endpoint: \`http://localhost:\${port}\`,
   region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'accessKeyId',
-    secretAccessKey: 'secretAccessKey',
-  },
+  credentials: { accessKeyId: 'UNUSED', secretAccessKey: 'UNUSED' },
 });
 
 const waitForTableActive = async (
@@ -1108,9 +1040,10 @@ const waitForTableActive = async (
       { abortSignal: timeoutSignal() },
     );
     const allActive =
-      Table?.TableStatus === 'ACTIVE' &&
+      Table?.TableStatus === TableStatus.ACTIVE &&
       (Table?.GlobalSecondaryIndexes ?? []).every(
-        (g: GlobalSecondaryIndexDescription) => g.IndexStatus === 'ACTIVE',
+        (g: GlobalSecondaryIndexDescription) =>
+          g.IndexStatus === IndexStatus.ACTIVE,
       );
     if (allActive) return;
     await new Promise((resolve) => setTimeout(resolve, 500));
@@ -1120,15 +1053,17 @@ const waitForTableActive = async (
 const ensureTable = async (
   tblClient: DynamoDBClient,
   tblName: string,
-  gsIs: { indexName: string; partitionKey: string; sortKey: string }[],
+  gsIs: { indexName: string; partitionKey: string; sortKey?: string }[],
 ): Promise<void> => {
   const gsiAttributeDefinitions = gsIs.flatMap((gsi) => [
-    { AttributeName: gsi.partitionKey, AttributeType: 'S' as const },
-    { AttributeName: gsi.sortKey, AttributeType: 'S' as const },
+    { AttributeName: gsi.partitionKey, AttributeType: ScalarAttributeType.S },
+    ...(gsi.sortKey
+      ? [{ AttributeName: gsi.sortKey, AttributeType: ScalarAttributeType.S }]
+      : []),
   ]);
   const attributeDefinitions = [
-    { AttributeName: 'pk', AttributeType: 'S' as const },
-    { AttributeName: 'sk', AttributeType: 'S' as const },
+    { AttributeName: 'pk', AttributeType: ScalarAttributeType.S },
+    { AttributeName: 'sk', AttributeType: ScalarAttributeType.S },
     ...gsiAttributeDefinitions.filter(
       (a, i, arr) =>
         arr.findIndex((b) => b.AttributeName === a.AttributeName) === i,
@@ -1137,10 +1072,12 @@ const ensureTable = async (
   const globalSecondaryIndexes = gsIs.map((gsi) => ({
     IndexName: gsi.indexName,
     KeySchema: [
-      { AttributeName: gsi.partitionKey, KeyType: 'HASH' as const },
-      { AttributeName: gsi.sortKey, KeyType: 'RANGE' as const },
+      { AttributeName: gsi.partitionKey, KeyType: KeyType.HASH },
+      ...(gsi.sortKey
+        ? [{ AttributeName: gsi.sortKey, KeyType: KeyType.RANGE }]
+        : []),
     ],
-    Projection: { ProjectionType: 'ALL' as const },
+    Projection: { ProjectionType: ProjectionType.ALL },
   }));
 
   for (let attempt = 0; attempt < 30; attempt++) {
@@ -1151,10 +1088,10 @@ const ensureTable = async (
           TableName: tblName,
           AttributeDefinitions: attributeDefinitions,
           KeySchema: [
-            { AttributeName: 'pk', KeyType: 'HASH' },
-            { AttributeName: 'sk', KeyType: 'RANGE' },
+            { AttributeName: 'pk', KeyType: KeyType.HASH },
+            { AttributeName: 'sk', KeyType: KeyType.RANGE },
           ],
-          BillingMode: 'PAY_PER_REQUEST',
+          BillingMode: BillingMode.PAY_PER_REQUEST,
           ...(globalSecondaryIndexes.length > 0 && {
             GlobalSecondaryIndexes: globalSecondaryIndexes,
           }),
@@ -1204,18 +1141,38 @@ const ensureTable = async (
             new UpdateTableCommand({
               TableName: tblName,
               AttributeDefinitions: [
-                { AttributeName: gsi.partitionKey, AttributeType: 'S' },
-                { AttributeName: gsi.sortKey, AttributeType: 'S' },
+                {
+                  AttributeName: gsi.partitionKey,
+                  AttributeType: ScalarAttributeType.S,
+                },
+                ...(gsi.sortKey
+                  ? [
+                      {
+                        AttributeName: gsi.sortKey,
+                        AttributeType: ScalarAttributeType.S,
+                      },
+                    ]
+                  : []),
               ],
               GlobalSecondaryIndexUpdates: [
                 {
                   Create: {
                     IndexName: gsi.indexName,
                     KeySchema: [
-                      { AttributeName: gsi.partitionKey, KeyType: 'HASH' },
-                      { AttributeName: gsi.sortKey, KeyType: 'RANGE' },
+                      {
+                        AttributeName: gsi.partitionKey,
+                        KeyType: KeyType.HASH,
+                      },
+                      ...(gsi.sortKey
+                        ? [
+                            {
+                              AttributeName: gsi.sortKey,
+                              KeyType: KeyType.RANGE,
+                            },
+                          ]
+                        : []),
                     ],
-                    Projection: { ProjectionType: 'ALL' },
+                    Projection: { ProjectionType: ProjectionType.ALL },
                   },
                 },
               ],
@@ -1233,22 +1190,25 @@ const ensureTable = async (
   }
 };
 
-await ensureTable(client, tableName, GLOBAL_SECONDARY_INDEXES);
+await ensureTable(client, tableName, globalSecondaryIndexes);
 "
 `;
 
-exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my-table/scripts/pull-image.ts 1`] = `
+exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/common/scripts/src/dynamodb/pull-image.ts 1`] = `
 "import { spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
 
-const ENGINE = 'docker';
-const image = process.argv[2];
+const { containerEngine, image } = JSON.parse(
+  readFileSync('config.json', 'utf-8'),
+).localDev;
 
-const inspect = spawnSync(ENGINE, ['image', 'inspect', image], {
+const inspect = spawnSync(containerEngine, ['image', 'inspect', image], {
   stdio: 'ignore',
 });
-
 if (inspect.status !== 0) {
-  const pull = spawnSync(ENGINE, ['pull', image], { stdio: 'inherit' });
+  const pull = spawnSync(containerEngine, ['pull', image], {
+    stdio: 'inherit',
+  });
   if (pull.status !== 0) {
     process.exit(pull.status ?? 1);
   }
@@ -1256,51 +1216,85 @@ if (inspect.status !== 0) {
 "
 `;
 
-exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my-table/scripts/start-container.ts 1`] = `
+exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/common/scripts/src/dynamodb/start-container.ts 1`] = `
 "import { spawn, spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
 
-const ENGINE = 'docker';
-
-const [containerName, image, hostPort] = process.argv.slice(2);
+const { containerEngine, containerName, image, port } = JSON.parse(
+  readFileSync('config.json', 'utf-8'),
+).localDev;
 
 const containerExists = (): boolean =>
-  spawnSync(ENGINE, ['container', 'inspect', containerName], {
+  spawnSync(containerEngine, ['container', 'inspect', containerName], {
     stdio: 'ignore',
   }).status === 0;
 
 const isRunning = (): boolean => {
   const result = spawnSync(
-    ENGINE,
+    containerEngine,
     ['container', 'inspect', '-f', '{{.State.Running}}', containerName],
     { encoding: 'utf-8' },
   );
   return result.status === 0 && result.stdout.trim() === 'true';
 };
 
-// Multiple dynamo table packages run serve-local in parallel sharing the same
+// Ensure the image is available locally before starting the container.
+const ensureImage = (): void => {
+  const inspect = spawnSync(containerEngine, ['image', 'inspect', image], {
+    stdio: 'ignore',
+  });
+  if (inspect.status !== 0) {
+    const pull = spawnSync(containerEngine, ['pull', image], {
+      stdio: 'inherit',
+    });
+    if (pull.status !== 0) process.exit(pull.status ?? 1);
+  }
+};
+
+// Multiple dynamo table packages run dev in parallel sharing the same
 // container. All processes stream logs, but only the one that created the
 // container stops it on exit — others just detach.
 let created = false;
 let runRetries = 0;
 
+ensureImage();
+
 for (;;) {
   if (containerExists()) {
     if (!isRunning()) {
       // Another process may have started it between our inspect and start — container engine start
       // exits 0 even if the container is already running, so no special-casing needed.
-      const start = spawnSync(ENGINE, ['start', containerName], {
+      const start = spawnSync(containerEngine, ['start', containerName], {
         stdio: 'inherit',
       });
       if (start.status !== 0) process.exit(start.status ?? 1);
     }
     break;
   }
-  const runArgs = (
-    \`run --rm --name \${containerName} -u root -w /home/dynamodblocal\` +
-    \` -p \${hostPort}:\${hostPort} -v \${containerName}-data:/home/dynamodblocal/data\` +
-    \` -d \${image} -jar DynamoDBLocal.jar -sharedDb -dbPath ./data -port \${hostPort} -optimizeDbBeforeStartup\`
-  ).split(' ');
-  const create = spawnSync(ENGINE, runArgs, { stdio: 'pipe' });
+  const runArgs = [
+    'run',
+    ...(containerEngine === 'docker' ? ['--rm'] : []),
+    '--name',
+    containerName,
+    '-u',
+    'root',
+    '-w',
+    '/home/dynamodblocal',
+    \`-p\`,
+    \`\${port}:\${port}\`,
+    '-v',
+    \`\${containerName}-data:/home/dynamodblocal/data\`,
+    '-d',
+    image,
+    '-jar',
+    'DynamoDBLocal.jar',
+    '-sharedDb',
+    '-dbPath',
+    './data',
+    '-port',
+    \`\${port}\`,
+  ];
+  const create = spawnSync(containerEngine, runArgs, { stdio: 'pipe' });
   if (create.status === 0) {
     created = true;
     break;
@@ -1311,7 +1305,7 @@ for (;;) {
   }
 }
 
-const logs = spawn(ENGINE, ['logs', '-f', containerName], {
+const logs = spawn(containerEngine, ['logs', '-f', containerName], {
   stdio: ['ignore', 'inherit', 'inherit'],
 });
 
@@ -1321,7 +1315,13 @@ const cleanup = () => {
   if (exiting) return;
   exiting = true;
   if (created) {
-    spawnSync(ENGINE, ['stop', containerName], { stdio: 'ignore' });
+    if (containerEngine === 'docker') {
+      spawnSync(containerEngine, ['stop', containerName], { stdio: 'ignore' });
+    } else {
+      spawnSync(containerEngine, ['rm', '-f', containerName], {
+        stdio: 'ignore',
+      });
+    }
   }
   logs.kill();
   process.exit(0);
@@ -1331,38 +1331,40 @@ process.on('SIGTERM', cleanup);
 process.on('SIGINT', cleanup);
 process.on('SIGHUP', cleanup);
 
-logs.on('exit', (code) => {
-  if (!exiting) process.exit(code ?? 0);
-});
+logs.on('exit', cleanup);
 "
 `;
 
 exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my-table/src/client.ts 1`] = `
 "import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
-import {
-  PACKAGE_NAME,
-  LOCAL_ACCESS_KEY_ID,
-  LOCAL_ENDPOINT,
-  LOCAL_REGION,
-  LOCAL_SECRET_ACCESS_KEY,
-  LOCAL_TABLE_NAME,
-} from './constants.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// Generated: must match runtimeConfigKey in config.json
+const runtimeConfigKey = 'MyTable';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// config.json is only present in local dev (not included in the deployed bundle); guard with LOCAL_DEV check
+const localDev = () =>
+  JSON.parse(readFileSync(join(__dirname, '../config.json'), 'utf-8')).localDev;
 
 let _client: DynamoDBClient | undefined;
 
 export const getDynamoDBClient = (): DynamoDBClient => {
-  _client ??=
-    process.env.SERVE_LOCAL === 'true'
-      ? new DynamoDBClient({
-          endpoint: LOCAL_ENDPOINT,
-          region: LOCAL_REGION,
-          credentials: {
-            accessKeyId: LOCAL_ACCESS_KEY_ID,
-            secretAccessKey: LOCAL_SECRET_ACCESS_KEY,
-          },
-        })
-      : new DynamoDBClient({});
+  if (!_client) {
+    if (process.env.LOCAL_DEV === 'true') {
+      const { port } = localDev();
+      _client = new DynamoDBClient({
+        endpoint: \`http://localhost:\${port}\`,
+        region: 'us-east-1',
+        credentials: { accessKeyId: 'UNUSED', secretAccessKey: 'UNUSED' },
+      });
+    } else {
+      _client = new DynamoDBClient({});
+    }
+  }
   return _client;
 };
 
@@ -1373,8 +1375,9 @@ type DynamoDBConfig = {
 let _tableName: string | undefined;
 
 export const resolveTableName = async (): Promise<string> => {
-  if (process.env.SERVE_LOCAL === 'true') {
-    return LOCAL_TABLE_NAME;
+  if (process.env.LOCAL_DEV === 'true') {
+    const { tableName } = localDev();
+    return tableName;
   }
   if (_tableName === undefined) {
     const appId = process.env.RUNTIME_CONFIG_APP_ID;
@@ -1388,7 +1391,7 @@ export const resolveTableName = async (): Promise<string> => {
       environment: 'default',
       transform: 'json',
     });
-    const tableName = config?.[PACKAGE_NAME]?.tableName;
+    const tableName = config?.[runtimeConfigKey]?.tableName;
     if (!tableName) {
       throw new Error('Could not resolve table name from runtime config');
     }
@@ -1399,19 +1402,6 @@ export const resolveTableName = async (): Promise<string> => {
 "
 `;
 
-exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my-table/src/constants.ts 1`] = `
-"export const PACKAGE_NAME = 'MyTable';
-
-// Local development connection details (used when SERVE_LOCAL=true, see serve-local Nx target)
-export const LOCAL_PORT = 8000;
-export const LOCAL_REGION = 'us-east-1';
-export const LOCAL_ACCESS_KEY_ID = 'accessKeyId';
-export const LOCAL_SECRET_ACCESS_KEY = 'secretAccessKey';
-export const LOCAL_ENDPOINT = \`http://localhost:\${LOCAL_PORT}\`;
-export const LOCAL_TABLE_NAME = 'proj-my-table';
-"
-`;
-
 exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my-table/src/entities/example.ts 1`] = `
 "import { Entity } from 'electrodb';
 import { getDynamoDBClient, resolveTableName } from '../client.js';
@@ -1468,35 +1458,8 @@ exports[`ts#dynamodb generator > should generate with infra=none then upgrade to
 "
 `;
 
-exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my-table/src/gsi.ts 1`] = `
-"// GSIs to synchronize on the local table at startup and provision in infrastructure.
-// ElectroDB names GSI keys gsi{n}pk / gsi{n}sk — add one entry per index defined in your entities.
-export const GLOBAL_SECONDARY_INDEXES = [
-  {
-    indexName: 'gsi1pk-gsi1sk-index',
-    partitionKey: 'gsi1pk',
-    sortKey: 'gsi1sk',
-  },
-  {
-    indexName: 'gsi2pk-gsi2sk-index',
-    partitionKey: 'gsi2pk',
-    sortKey: 'gsi2sk',
-  },
-];
-"
-`;
-
 exports[`ts#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my-table/src/index.ts 1`] = `
-"export {
-  PACKAGE_NAME,
-  LOCAL_ACCESS_KEY_ID,
-  LOCAL_ENDPOINT,
-  LOCAL_REGION,
-  LOCAL_SECRET_ACCESS_KEY,
-  LOCAL_TABLE_NAME,
-} from './constants.js';
-export { getDynamoDBClient, resolveTableName } from './client.js';
-export { GLOBAL_SECONDARY_INDEXES } from './gsi.js';
+"export { getDynamoDBClient, resolveTableName } from './client.js';
 export * from './entities/index.js';
 "
 `;