local-web-services-javascript-sdk 0.1.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "local-web-services-javascript-sdk",
+  "version": "0.1.0",
+  "description": "JavaScript testing SDK for local-web-services — subprocess-based AWS service fixtures for testing",
+  "main": "src/index.js",
+  "files": [
+    "src/**/*"
+  ],
+  "scripts": {
+    "test": "jest --forceExit",
+    "lint": "eslint src tests"
+  },
+  "keywords": [
+    "aws",
+    "testing",
+    "jest",
+    "dynamodb",
+    "sqs",
+    "s3",
+    "local",
+    "mocking"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/local-web-services/local-web-services-javascript-sdk"
+  },
+  "homepage": "https://github.com/local-web-services/local-web-services-javascript-sdk#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.600.0",
+    "@aws-sdk/client-s3": "^3.600.0",
+    "@aws-sdk/client-sqs": "^3.600.0",
+    "@aws-sdk/client-sns": "^3.600.0",
+    "@aws-sdk/client-ssm": "^3.600.0",
+    "@aws-sdk/client-secrets-manager": "^3.600.0",
+    "@aws-sdk/client-sfn": "^3.600.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/tests/**/*.test.js"
+    ],
+    "testTimeout": 60000
+  }
+}

package/src/builders/chaos.js

@@ -0,0 +1,50 @@
+"use strict";
+
+class ChaosBuilder {
+  constructor(service, mgmtPort) {
+    this.service = service;
+    this.mgmtPort = mgmtPort;
+    this.config = { enabled: true };
+  }
+
+  errorRate(rate) {
+    this.config.error_rate = rate;
+    return this;
+  }
+
+  latency(minMs, maxMs) {
+    this.config.latency_min_ms = minMs;
+    this.config.latency_max_ms = maxMs;
+    return this;
+  }
+
+  connectionResetRate(rate) {
+    this.config.connection_reset_rate = rate;
+    return this;
+  }
+
+  timeoutRate(rate) {
+    this.config.timeout_rate = rate;
+    return this;
+  }
+
+  async apply() {
+    await fetch(`http://127.0.0.1:${this.mgmtPort}/_ldk/chaos`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ [this.service]: this.config }),
+    });
+  }
+
+  async clear() {
+    await fetch(`http://127.0.0.1:${this.mgmtPort}/_ldk/chaos`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        [this.service]: { enabled: false, error_rate: 0.0 },
+      }),
+    });
+  }
+}
+
+module.exports = { ChaosBuilder };

package/src/builders/iam.js

@@ -0,0 +1,81 @@
+"use strict";
+
+class IamBuilder {
+  constructor(mgmtPort) {
+    this.mgmtPort = mgmtPort;
+    this.updates = {};
+    this.identities = {};
+  }
+
+  mode(mode) {
+    this.updates.mode = mode;
+    return this;
+  }
+
+  defaultIdentity(name) {
+    this.updates.default_identity = name;
+    return this;
+  }
+
+  identity(name) {
+    return new IdentityBuilder(this, name);
+  }
+
+  _registerIdentity(name, config) {
+    this.identities[name] = config;
+  }
+
+  async apply() {
+    const payload = { ...this.updates };
+    if (Object.keys(this.identities).length > 0) {
+      payload.identities = this.identities;
+    }
+    await fetch(`http://127.0.0.1:${this.mgmtPort}/_ldk/iam-auth`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    this.updates = {};
+    this.identities = {};
+  }
+}
+
+class IdentityBuilder {
+  constructor(parent, name) {
+    this.parent = parent;
+    this.name = name;
+    this.inlinePolicies = [];
+    this.boundary = undefined;
+  }
+
+  allow(actions, resource = "*") {
+    this.inlinePolicies.push({
+      name: `inline-${this.inlinePolicies.length}`,
+      document: {
+        Version: "2012-10-17",
+        Statement: [{ Effect: "Allow", Action: actions, Resource: resource }],
+      },
+    });
+    return this;
+  }
+
+  deny(actions, resource = "*") {
+    this.inlinePolicies.push({
+      name: `inline-deny-${this.inlinePolicies.length}`,
+      document: {
+        Version: "2012-10-17",
+        Statement: [{ Effect: "Deny", Action: actions, Resource: resource }],
+      },
+    });
+    return this;
+  }
+
+  apply() {
+    const config = { inline_policies: this.inlinePolicies };
+    if (this.boundary) config.boundary_policy = this.boundary;
+    this.parent._registerIdentity(this.name, config);
+    return this.parent;
+  }
+}
+
+module.exports = { IamBuilder, IdentityBuilder };

package/src/builders/mock.js

@@ -0,0 +1,74 @@
+"use strict";
+
+class MockBuilder {
+  constructor(service, mgmtPort) {
+    this.service = service;
+    this.mgmtPort = mgmtPort;
+    this.rules = [];
+  }
+
+  operation(operationName) {
+    return new MockRuleBuilder(this, operationName);
+  }
+
+  async _addRule(rule) {
+    this.rules.push(rule);
+    await this._apply();
+  }
+
+  async _apply() {
+    await fetch(`http://127.0.0.1:${this.mgmtPort}/_ldk/aws-mock`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ [this.service]: { enabled: true, rules: this.rules } }),
+    });
+  }
+
+  async clear() {
+    this.rules = [];
+    await fetch(`http://127.0.0.1:${this.mgmtPort}/_ldk/aws-mock`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ [this.service]: { enabled: false, rules: [] } }),
+    });
+  }
+}
+
+class MockRuleBuilder {
+  constructor(parent, operation) {
+    this.parent = parent;
+    this.operation = operation;
+    this.matchHeaders = {};
+  }
+
+  withHeader(name, value) {
+    this.matchHeaders[name] = value;
+    return this;
+  }
+
+  async respond(opts) {
+    const body =
+      typeof opts.body === "object" ? JSON.stringify(opts.body) : opts.body ?? "";
+    const rule = {
+      operation: this.operation,
+      match_headers: this.matchHeaders,
+      response: {
+        status: opts.status ?? 200,
+        content_type: opts.contentType ?? "application/json",
+        delay_ms: opts.delayMs ?? 0,
+        body,
+      },
+    };
+    await this.parent._addRule(rule);
+    return this.parent;
+  }
+
+  async error(errorType, message = "", status = 400) {
+    return this.respond({
+      status,
+      body: JSON.stringify({ __type: errorType, message }),
+    });
+  }
+}
+
+module.exports = { MockBuilder, MockRuleBuilder };

package/src/index.js

@@ -0,0 +1,23 @@
+"use strict";
+
+const { LwsSession } = require("./session");
+const { DynamoDBHelper } = require("./resources/dynamodb");
+const { SQSHelper } = require("./resources/sqs");
+const { S3Helper } = require("./resources/s3");
+const { MockBuilder, MockRuleBuilder } = require("./builders/mock");
+const { ChaosBuilder } = require("./builders/chaos");
+const { IamBuilder, IdentityBuilder } = require("./builders/iam");
+const { LogCapture } = require("./logs");
+
+module.exports = {
+  LwsSession,
+  DynamoDBHelper,
+  SQSHelper,
+  S3Helper,
+  MockBuilder,
+  MockRuleBuilder,
+  ChaosBuilder,
+  IamBuilder,
+  IdentityBuilder,
+  LogCapture,
+};

package/src/logs.js

@@ -0,0 +1,76 @@
+"use strict";
+
+class LogCapture {
+  constructor(mgmtPort) {
+    this.mgmtPort = mgmtPort;
+    this.entries = [];
+  }
+
+  start() {
+    this.entries = [];
+  }
+
+  async stop() {
+    try {
+      const res = await fetch(`http://127.0.0.1:${this.mgmtPort}/_ldk/status`);
+      if (res.ok) {
+        // Logs collected via WebSocket during the test.
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  get all() {
+    return [...this.entries];
+  }
+
+  forService(service) {
+    return this.entries.filter(
+      (e) => (e.service ?? "").toLowerCase() === service.toLowerCase()
+    );
+  }
+
+  forOperation(operation) {
+    return this.entries.filter((e) => e.operation === operation);
+  }
+
+  assertCalled(service, operation) {
+    const matching = this.entries.filter(
+      (e) =>
+        (e.service ?? "").toLowerCase() === service.toLowerCase() &&
+        e.operation === operation
+    );
+    if (matching.length === 0) {
+      throw new Error(
+        `Expected ${service}.${operation} to have been called, ` +
+          `but no matching log entry was found. Captured: ${JSON.stringify(this.entries)}`
+      );
+    }
+  }
+
+  assertNotCalled(service, operation) {
+    const matching = this.entries.filter(
+      (e) =>
+        (e.service ?? "").toLowerCase() === service.toLowerCase() &&
+        e.operation === operation
+    );
+    if (matching.length > 0) {
+      throw new Error(
+        `Expected ${service}.${operation} NOT to have been called, ` +
+          `but found ${matching.length} matching log entry/entries.`
+      );
+    }
+  }
+
+  assertNoErrors() {
+    const errors = this.entries.filter((e) => e.level === "ERROR");
+    if (errors.length > 0) {
+      throw new Error(
+        `Expected no ERROR log entries, but found ${errors.length}: ${JSON.stringify(errors)}`
+      );
+    }
+  }
+}
+
+module.exports = { LogCapture };

package/src/resources/dynamodb.js

@@ -0,0 +1,72 @@
+"use strict";
+
+const {
+  DynamoDBClient,
+  PutItemCommand,
+  GetItemCommand,
+  DeleteItemCommand,
+  ScanCommand,
+} = require("@aws-sdk/client-dynamodb");
+
+class DynamoDBHelper {
+  constructor(tableName, client) {
+    this.tableName = tableName;
+    this.client = client;
+  }
+
+  async put(item) {
+    await this.client.send(new PutItemCommand({ TableName: this.tableName, Item: item }));
+  }
+
+  async get(key) {
+    const response = await this.client.send(
+      new GetItemCommand({ TableName: this.tableName, Key: key })
+    );
+    return response.Item;
+  }
+
+  async delete(key) {
+    await this.client.send(
+      new DeleteItemCommand({ TableName: this.tableName, Key: key })
+    );
+  }
+
+  async scan() {
+    const items = [];
+    let lastKey;
+    do {
+      const result = await this.client.send(
+        new ScanCommand({
+          TableName: this.tableName,
+          ...(lastKey ? { ExclusiveStartKey: lastKey } : {}),
+        })
+      );
+      items.push(...(result.Items ?? []));
+      lastKey = result.LastEvaluatedKey;
+    } while (lastKey);
+    return items;
+  }
+
+  async assertItemExists(key) {
+    const item = await this.get(key);
+    if (!item) {
+      throw new Error(
+        `Expected item with key ${JSON.stringify(key)} to exist in table "${this.tableName}", but it was not found.`
+      );
+    }
+    return item;
+  }
+
+  async assertItemCount(expectedCount) {
+    const items = await this.scan();
+    if (items.length !== expectedCount) {
+      throw new Error(
+        `Expected ${expectedCount} item(s) in table "${this.tableName}", but found ${items.length}.`
+      );
+    }
+  }
+}
+
+void DynamoDBClient;
+
+module.exports = { DynamoDBHelper };

package/src/resources/s3.js

@@ -0,0 +1,90 @@
+"use strict";
+
+const {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  DeleteObjectCommand,
+  ListObjectsV2Command,
+} = require("@aws-sdk/client-s3");
+
+class S3Helper {
+  constructor(bucketName, client) {
+    this.bucketName = bucketName;
+    this.client = client;
+  }
+
+  async put(key, body, contentType) {
+    await this.client.send(
+      new PutObjectCommand({
+        Bucket: this.bucketName,
+        Key: key,
+        Body: typeof body === "string" ? Buffer.from(body) : body,
+        ...(contentType ? { ContentType: contentType } : {}),
+      })
+    );
+  }
+
+  async get(key) {
+    const result = await this.client.send(
+      new GetObjectCommand({ Bucket: this.bucketName, Key: key })
+    );
+    const chunks = [];
+    for await (const chunk of result.Body) {
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+
+  async getText(key, encoding = "utf-8") {
+    return (await this.get(key)).toString(encoding);
+  }
+
+  async delete(key) {
+    await this.client.send(
+      new DeleteObjectCommand({ Bucket: this.bucketName, Key: key })
+    );
+  }
+
+  async listKeys(prefix) {
+    const keys = [];
+    let token;
+    do {
+      const result = await this.client.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucketName,
+          ...(prefix ? { Prefix: prefix } : {}),
+          ...(token ? { ContinuationToken: token } : {}),
+        })
+      );
+      keys.push(...(result.Contents ?? []).map((obj) => obj.Key));
+      token = result.NextContinuationToken;
+    } while (token);
+    return keys;
+  }
+
+  async assertObjectExists(key) {
+    const keys = await this.listKeys();
+    if (!keys.includes(key)) {
+      throw new Error(
+        `Expected object "${key}" to exist in bucket "${this.bucketName}", ` +
+          `but it was not found. Existing keys: ${JSON.stringify(keys)}`
+      );
+    }
+  }
+
+  async assertObjectCount(expectedCount, prefix) {
+    const keys = await this.listKeys(prefix);
+    if (keys.length !== expectedCount) {
+      throw new Error(
+        `Expected ${expectedCount} object(s) in bucket "${this.bucketName}"` +
+          (prefix ? ` with prefix "${prefix}"` : "") +
+          `, but found ${keys.length}.`
+      );
+    }
+  }
+}
+
+void S3Client;
+
+module.exports = { S3Helper };

package/src/resources/sqs.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const {
+  SQSClient,
+  SendMessageCommand,
+  ReceiveMessageCommand,
+  PurgeQueueCommand,
+  GetQueueAttributesCommand,
+} = require("@aws-sdk/client-sqs");
+
+class SQSHelper {
+  constructor(queueName, client, port) {
+    this.queueName = queueName;
+    this.client = client;
+    this.queueUrl = `http://127.0.0.1:${port}/000000000000/${queueName}`;
+  }
+
+  get url() {
+    return this.queueUrl;
+  }
+
+  async send(body, opts = {}) {
+    const messageBody = typeof body === "string" ? body : JSON.stringify(body);
+    const result = await this.client.send(
+      new SendMessageCommand({
+        QueueUrl: this.queueUrl,
+        MessageBody: messageBody,
+        ...(opts.messageGroupId ? { MessageGroupId: opts.messageGroupId } : {}),
+      })
+    );
+    return result.MessageId ?? "";
+  }
+
+  async receive(maxMessages = 10, waitSeconds = 0) {
+    const result = await this.client.send(
+      new ReceiveMessageCommand({
+        QueueUrl: this.queueUrl,
+        MaxNumberOfMessages: Math.min(maxMessages, 10),
+        WaitTimeSeconds: waitSeconds,
+      })
+    );
+    return result.Messages ?? [];
+  }
+
+  async purge() {
+    await this.client.send(new PurgeQueueCommand({ QueueUrl: this.queueUrl }));
+  }
+
+  async assertMessageCount(expectedCount) {
+    const result = await this.client.send(
+      new GetQueueAttributesCommand({
+        QueueUrl: this.queueUrl,
+        AttributeNames: ["ApproximateNumberOfMessages"],
+      })
+    );
+    const actualCount = parseInt(
+      result.Attributes?.ApproximateNumberOfMessages ?? "0",
+      10
+    );
+    if (actualCount !== expectedCount) {
+      throw new Error(
+        `Expected ${expectedCount} message(s) in queue "${this.queueName}", but found approximately ${actualCount}.`
+      );
+    }
+  }
+}
+
+void SQSClient;
+
+module.exports = { SQSHelper };

package/src/session.js

@@ -0,0 +1,455 @@
+"use strict";
+
+/**
+ * LwsSession — main entry point for the lws JavaScript testing SDK.
+ *
+ * Spawns `ldk dev` in a background process and provides pre-configured
+ * AWS SDK v3 clients pointing at the local services.
+ */
+
+const { spawn } = require("child_process");
+const fs = require("fs/promises");
+const net = require("net");
+const os = require("os");
+const path = require("path");
+
+const { DynamoDBHelper } = require("./resources/dynamodb");
+const { SQSHelper } = require("./resources/sqs");
+const { S3Helper } = require("./resources/s3");
+const { MockBuilder } = require("./builders/mock");
+const { ChaosBuilder } = require("./builders/chaos");
+const { IamBuilder } = require("./builders/iam");
+const { LogCapture } = require("./logs");
+
+// Port offsets relative to the base port (matches ldk.py _create_providers)
+const SERVICE_OFFSETS = {
+  dynamodb: 1,
+  sqs: 2,
+  s3: 3,
+  sns: 4,
+  eventbridge: 5,
+  stepfunctions: 6,
+  ssm: 12,
+  secretsmanager: 13,
+};
+
+// Maps service name → AWS SDK v3 endpoint URL env var.
+// Note: AWS SDK v3 uses "STATES" for Step Functions and "SECRETS_MANAGER"
+// (with underscore) for Secrets Manager — different from boto3's names.
+const SERVICE_ENV_VARS = {
+  dynamodb: "AWS_ENDPOINT_URL_DYNAMODB",
+  sqs: "AWS_ENDPOINT_URL_SQS",
+  s3: "AWS_ENDPOINT_URL_S3",
+  sns: "AWS_ENDPOINT_URL_SNS",
+  stepfunctions: "AWS_ENDPOINT_URL_STATES",
+  ssm: "AWS_ENDPOINT_URL_SSM",
+  secretsmanager: "AWS_ENDPOINT_URL_SECRETS_MANAGER",
+};
+
+const TEST_CREDENTIALS = {
+  AWS_ACCESS_KEY_ID: "test",
+  AWS_SECRET_ACCESS_KEY: "test",
+  AWS_DEFAULT_REGION: "us-east-1",
+};
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      server.close(() => resolve(addr.port));
+    });
+    server.on("error", reject);
+  });
+}
+
+async function waitForReady(managementUrl, timeoutMs = 30000, intervalMs = 200) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${managementUrl}/_ldk/status`);
+      if (res.ok) return;
+    } catch {
+      // not ready yet
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(
+    `ldk dev did not become ready within ${timeoutMs}ms. ` +
+      "Check that local-web-services is installed (pip install local-web-services)."
+  );
+}
+
+async function generateTerraformConfig(dir, spec) {
+  const lines = [];
+
+  for (const tableSpec of spec.tables ?? []) {
+    const name = typeof tableSpec === "string" ? tableSpec : tableSpec.name;
+    const pk = typeof tableSpec === "string" ? "id" : tableSpec.partitionKey;
+    const sk = typeof tableSpec === "string" ? undefined : tableSpec.sortKey;
+    const logicalId = name.toLowerCase().replace(/[^a-z0-9]/g, "_");
+
+    lines.push(`resource "aws_dynamodb_table" "${logicalId}" {`);
+    lines.push(`  name         = "${name}"`);
+    lines.push(`  hash_key     = "${pk}"`);
+    lines.push(`  billing_mode = "PAY_PER_REQUEST"`);
+    lines.push(`  attribute { name = "${pk}" type = "S" }`);
+    if (sk) {
+      lines.push(`  range_key = "${sk}"`);
+      lines.push(`  attribute { name = "${sk}" type = "S" }`);
+    }
+    lines.push(`}`);
+    lines.push("");
+  }
+
+  for (const queueSpec of spec.queues ?? []) {
+    const name = typeof queueSpec === "string" ? queueSpec : queueSpec.name;
+    const isFifo = typeof queueSpec !== "string" && queueSpec.isFifo;
+    const logicalId = name.toLowerCase().replace(/[^a-z0-9]/g, "_");
+    lines.push(`resource "aws_sqs_queue" "${logicalId}" {`);
+    lines.push(`  name = "${name}"`);
+    if (isFifo) lines.push(`  fifo_queue = true`);
+    lines.push(`}`);
+    lines.push("");
+  }
+
+  for (const bucketSpec of spec.buckets ?? []) {
+    const name = typeof bucketSpec === "string" ? bucketSpec : bucketSpec.name;
+    const logicalId = name.toLowerCase().replace(/[^a-z0-9]/g, "_");
+    lines.push(`resource "aws_s3_bucket" "${logicalId}" {`);
+    lines.push(`  bucket = "${name}"`);
+    lines.push(`}`);
+    lines.push("");
+  }
+
+  for (const topicSpec of spec.topics ?? []) {
+    const name = typeof topicSpec === "string" ? topicSpec : topicSpec.name;
+    const logicalId = name.toLowerCase().replace(/[^a-z0-9]/g, "_");
+    lines.push(`resource "aws_sns_topic" "${logicalId}" {`);
+    lines.push(`  name = "${name}"`);
+    lines.push(`}`);
+    lines.push("");
+  }
+
+  await fs.writeFile(path.join(dir, "main.tf"), lines.join("\n"), "utf8");
+}
+
+class LwsSession {
+  constructor(basePort, projectDir, spec) {
+    this._basePort = basePort;
+    this._projectDir = projectDir;
+    this._spec = spec;
+    this._process = null;
+    this._tempDir = null;
+    this._savedEnv = {};
+  }
+
+  // ── Constructors ────────────────────────────────────────────────────────────
+
+  /**
+   * Create a session from an explicit resource specification.
+   *
+   * Generates a temporary Terraform project from the spec and starts `ldk dev`.
+   *
+   * @param {object} [spec={}]
+   * @returns {Promise<LwsSession>}
+   */
+  static async create(spec = {}) {
+    const basePort = await freePort();
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "lws-testing-"));
+    await generateTerraformConfig(tempDir, spec);
+
+    const session = new LwsSession(basePort, tempDir, spec);
+    session._tempDir = tempDir;
+    await session._start();
+    return session;
+  }
+
+  /**
+   * Create a session by discovering resources from a CDK project.
+   *
+   * @param {string} [projectDir="."]
+   * @returns {Promise<LwsSession>}
+   */
+  static async fromCdk(projectDir = ".") {
+    const basePort = await freePort();
+    const session = new LwsSession(basePort, projectDir, {});
+    await session._start("cdk");
+    return session;
+  }
+
+  /**
+   * Create a session by discovering resources from a Terraform / HCL project.
+   *
+   * @param {string} [projectDir="."]
+   * @returns {Promise<LwsSession>}
+   */
+  static async fromHcl(projectDir = ".") {
+    const basePort = await freePort();
+    const session = new LwsSession(basePort, projectDir, {});
+    await session._start("terraform");
+    return session;
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────────
+
+  async _start(mode) {
+    const args = ["dev", "--project-dir", this._projectDir, "--port", String(this._basePort)];
+    if (mode) {
+      args.push("--mode", mode);
+    }
+
+    this._process = spawn("ldk", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+    });
+
+    this._process.on("error", (err) => {
+      throw new Error(
+        `Failed to start ldk: ${err.message}. ` +
+          "Ensure local-web-services is installed: pip install local-web-services"
+      );
+    });
+
+    const managementUrl = `http://127.0.0.1:${this._basePort}`;
+    await waitForReady(managementUrl);
+    this._patchEnv();
+  }
+
+  /** Stop the ldk dev process and clean up any temporary files. */
+  async close() {
+    this._restoreEnv();
+
+    if (this._process) {
+      this._process.kill("SIGTERM");
+      await new Promise((resolve) => {
+        this._process.once("exit", () => resolve());
+        setTimeout(resolve, 5000);
+      });
+      this._process = null;
+    }
+    if (this._tempDir) {
+      await fs.rm(this._tempDir, { recursive: true, force: true });
+      this._tempDir = null;
+    }
+  }
+
+  // ── Environment patching ────────────────────────────────────────────────────
+
+  /**
+   * Set AWS SDK v3 endpoint env vars so any client created in this process
+   * hits the local LWS services — no production-code changes required.
+   */
+  _patchEnv() {
+    for (const [service, envVar] of Object.entries(SERVICE_ENV_VARS)) {
+      const offset = SERVICE_OFFSETS[service];
+      if (offset === undefined) continue;
+      this._savedEnv[envVar] = process.env[envVar];
+      process.env[envVar] = `http://127.0.0.1:${this._basePort + offset}`;
+    }
+    for (const [key, val] of Object.entries(TEST_CREDENTIALS)) {
+      this._savedEnv[key] = process.env[key];
+      process.env[key] = val;
+    }
+  }
+
+  /** Restore all env vars overridden by _patchEnv. */
+  _restoreEnv() {
+    for (const [key, savedVal] of Object.entries(this._savedEnv)) {
+      if (savedVal === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = savedVal;
+      }
+    }
+    this._savedEnv = {};
+  }
+
+  /**
+   * Return the local SQS URL for queueName.
+   *
+   * @param {string} queueName
+   * @returns {string}
+   */
+  queueUrl(queueName) {
+    return `http://127.0.0.1:${this._basePort + SERVICE_OFFSETS.sqs}/000000000000/${queueName}`;
+  }
+
+  // ── AWS client factory ──────────────────────────────────────────────────────
+
+  /**
+   * Return a pre-configured AWS SDK v3 client pointing at the local service.
+   *
+   * @param {string} service  e.g. "dynamodb", "s3", "sqs"
+   * @returns {object}
+   */
+  client(service) {
+    const offset = SERVICE_OFFSETS[service.toLowerCase()];
+    if (offset === undefined) {
+      throw new Error(
+        `Service "${service}" is not supported. Available: ${Object.keys(SERVICE_OFFSETS).join(", ")}`
+      );
+    }
+    const port = this._basePort + offset;
+    const endpointUrl = `http://127.0.0.1:${port}`;
+    const credentials = { accessKeyId: "test", secretAccessKey: "test" };
+    const region = "us-east-1";
+
+    switch (service.toLowerCase()) {
+      case "dynamodb": {
+        const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
+        return new DynamoDBClient({ endpoint: endpointUrl, credentials, region });
+      }
+      case "s3": {
+        const { S3Client } = require("@aws-sdk/client-s3");
+        return new S3Client({ endpoint: endpointUrl, credentials, region, forcePathStyle: true });
+      }
+      case "sqs": {
+        const { SQSClient } = require("@aws-sdk/client-sqs");
+        return new SQSClient({ endpoint: endpointUrl, credentials, region });
+      }
+      case "sns": {
+        const { SNSClient } = require("@aws-sdk/client-sns");
+        return new SNSClient({ endpoint: endpointUrl, credentials, region });
+      }
+      case "ssm": {
+        const { SSMClient } = require("@aws-sdk/client-ssm");
+        return new SSMClient({ endpoint: endpointUrl, credentials, region });
+      }
+      case "secretsmanager": {
+        const { SecretsManagerClient } = require("@aws-sdk/client-secrets-manager");
+        return new SecretsManagerClient({ endpoint: endpointUrl, credentials, region });
+      }
+      case "stepfunctions": {
+        const { SFNClient } = require("@aws-sdk/client-sfn");
+        return new SFNClient({ endpoint: endpointUrl, credentials, region });
+      }
+      default:
+        throw new Error(`No SDK client implementation for service "${service}"`);
+    }
+  }
+
+  // ── State management ────────────────────────────────────────────────────────
+
+  /** Clear all in-memory state. Call between tests for isolation. */
+  async reset() {
+    await this._resetDynamoDB();
+    await this._resetSqs();
+    await this._resetS3();
+  }
+
+  async _resetDynamoDB() {
+    const { DynamoDBClient, ScanCommand, DeleteItemCommand } = require("@aws-sdk/client-dynamodb");
+    const dynamo = this.client("dynamodb");
+    for (const tableSpec of this._spec.tables ?? []) {
+      const name = typeof tableSpec === "string" ? tableSpec : tableSpec.name;
+      const partitionKey = typeof tableSpec === "string" ? "id" : tableSpec.partitionKey;
+      const sortKey = typeof tableSpec === "string" ? undefined : tableSpec.sortKey;
+      const keyNames = [partitionKey, ...(sortKey ? [sortKey] : [])];
+      const projection = keyNames.map((k, i) => `#k${i}`).join(", ");
+      const exprNames = Object.fromEntries(keyNames.map((k, i) => [`#k${i}`, k]));
+
+      let lastKey;
+      do {
+        const scanInput = {
+          TableName: name,
+          ProjectionExpression: projection,
+          ExpressionAttributeNames: exprNames,
+        };
+        if (lastKey) scanInput.ExclusiveStartKey = lastKey;
+
+        const result = await dynamo.send(new ScanCommand(scanInput));
+        for (const item of result.Items ?? []) {
+          const key = Object.fromEntries(keyNames.map((k) => [k, item[k]]));
+          await dynamo.send(new DeleteItemCommand({ TableName: name, Key: key }));
+        }
+        lastKey = result.LastEvaluatedKey;
+      } while (lastKey);
+    }
+    void DynamoDBClient;
+  }
+
+  async _resetSqs() {
+    const { SQSClient, PurgeQueueCommand } = require("@aws-sdk/client-sqs");
+    const sqs = this.client("sqs");
+    const port = this._basePort + SERVICE_OFFSETS.sqs;
+    for (const queueSpec of this._spec.queues ?? []) {
+      const name = typeof queueSpec === "string" ? queueSpec : queueSpec.name;
+      const queueUrl = `http://127.0.0.1:${port}/000000000000/${name}`;
+      try {
+        await sqs.send(new PurgeQueueCommand({ QueueUrl: queueUrl }));
+      } catch {
+        // ignore if queue doesn't exist
+      }
+    }
+    void SQSClient;
+  }
+
+  async _resetS3() {
+    const { S3Client, ListObjectsV2Command, DeleteObjectCommand } = require("@aws-sdk/client-s3");
+    const s3 = this.client("s3");
+    for (const bucketSpec of this._spec.buckets ?? []) {
+      const name = typeof bucketSpec === "string" ? bucketSpec : bucketSpec.name;
+      let token;
+      do {
+        const listInput = { Bucket: name };
+        if (token) listInput.ContinuationToken = token;
+        const result = await s3.send(new ListObjectsV2Command(listInput));
+        for (const obj of result.Contents ?? []) {
+          await s3.send(new DeleteObjectCommand({ Bucket: name, Key: obj.Key }));
+        }
+        token = result.NextContinuationToken;
+      } while (token);
+    }
+    void S3Client;
+  }
+
+  // ── Resource helpers ────────────────────────────────────────────────────────
+
+  dynamodb(tableName) {
+    return new DynamoDBHelper(tableName, this.client("dynamodb"));
+  }
+
+  sqs(queueName) {
+    const port = this._basePort + SERVICE_OFFSETS.sqs;
+    return new SQSHelper(queueName, this.client("sqs"), port);
+  }
+
+  s3(bucketName) {
+    return new S3Helper(bucketName, this.client("s3"));
+  }
+
+  // ── Mock / chaos / IAM builders ─────────────────────────────────────────────
+
+  mock(service) {
+    return new MockBuilder(service, this._basePort);
+  }
+
+  chaos(service) {
+    return new ChaosBuilder(service, this._basePort);
+  }
+
+  get iam() {
+    return new IamBuilder(this._basePort);
+  }
+
+  // ── Log capture ─────────────────────────────────────────────────────────────
+
+  captureLogsStart() {
+    const capture = new LogCapture(this._basePort);
+    capture.start();
+    return capture;
+  }
+
+  // ── Port info ───────────────────────────────────────────────────────────────
+
+  portFor(service) {
+    const offset = SERVICE_OFFSETS[service.toLowerCase()];
+    if (offset === undefined) {
+      throw new Error(`Unknown service: ${service}`);
+    }
+    return this._basePort + offset;
+  }
+}
+
+module.exports = { LwsSession };