local-serverless-stack 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-06-04
+
+Testability features for downstream e2e suites: an isolated test instance and a deterministic queue-drain wait. Plugin `serverless-lss` bumped to `0.1.0` (it gained `LSS_DASHBOARD_PORT` support — install both).
+
+### Added
+- **`--config <path>` flag for `start|stop|status|logs`**: loads config from the given file, taking precedence over the cwd/home search (`lss.config.json` / `.lssrc`). A missing or unparseable explicit file warns and falls back to the search rather than hard-exiting, so `stop`/`status`/`logs` never orphan a running instance. `bin/cli.js` resolves the path to absolute once per invocation (also accepted via the `LSS_CONFIG` env var) and hands it to the spawned server as `LSS_CONFIG_PATH`, so the orchestrator's `ConfigManager` reads the identical file — keeping the two config loaders in agreement on port/seedsDir/region/mode.
+- **`stateDir` config field**: directory where an instance keeps its PID/log (the PID file doubles as the lock). When set (e.g. `".lss-e2e"`), `runtimePaths()` places state there so an isolated instance — typically an e2e test stack started with `--config` — can be started and stopped without ever touching the dev instance. When omitted, behavior is unchanged: PID/log live in the OS temp dir scoped by `serverPort`. `ConfigManager` gained the field plus a `getStateDir()` getter (resolved relative to the working directory).
+- **`POST /api/queues/:name/await-idle`**: blocking endpoint that polls a queue's counters (forcing a fresh read every ~250 ms rather than waiting on the 5 s background poller) and resolves `200 { queue, available, inFlight, processed, drained: true }` once the queue is idle (`available === 0 && inFlight === 0`, and `processed >= sinceProcessed` when that body field is supplied), or `408 { …, drained: false }` on timeout. Body: `{ timeoutMs?: number = 15000 (clamped 100–120000), sinceProcessed?: number }`. Lets a test deterministically wait for an SQS consumer to drain before asserting persistence. Accepts the logical queue name (e.g. `activity-save.fifo`).
+- **Queue hold/intercept primitives** (`POST /api/queues/:name/hold`, `GET /api/queues/:name/captured`, `POST /api/queues/:name/release`): `hold` disables the queue's consumer event source mapping(s) (`UpdateEventSourceMapping Enabled: false`) and starts capturing; `captured` drains the queue into an in-memory buffer and returns `[{ messageId, body, attributes, messageAttributes, receivedAt }]`; `release` re-enables the mapping(s) and re-dispatches the captured messages. Lets a test assert a producer's enqueued payload without running the consumer. Best-effort: hold state is in-memory (lost on restart), messages already consumed before hold can't be recalled, and LocalStack applies the `Enabled` toggle asynchronously.
+
+### Changed
+- **`serverless-lss` plugin honors `LSS_DASHBOARD_PORT`**: when set (and `ORCHESTRATOR_URL` is not), the plugin registers the service at `http://localhost:${LSS_DASHBOARD_PORT}`. Precedence is `ORCHESTRATOR_URL` (full URL) > `LSS_DASHBOARD_PORT` (port) > `custom.orchestrator.orchestratorUrl` > default `http://localhost:3100`. This lets the same `serverless.yml` register against an isolated test orchestrator at runtime without editing the file.
+
+### Tests
+- **Two separated test types**: `npm run test:unit` (default `npm test`) is hermetic, runs in CI, and enforces a **100% coverage gate** (statements/branches/functions/lines) over the unit-testable server code — `src/server/services/**` (except the Docker-driven `localstack-manager.ts`), `src/server/routes/**`, `src/server/dev/**`, `packages/serverless-plugin/src/**` and `bin/cli.js` (`index.ts` is excluded as it bootstraps the server at import). `npm run test:integration` boots a real isolated LSS + LocalStack and validates the promised features end-to-end. Added `aws-sdk-client-mock` + `supertest` as dev deps; split `tests/setup.ts` into shared matchers + per-type setup; `bin/cli.js` now guards its dispatch behind `require.main === module` and exports its helpers for in-process testing. ~750 unit tests.
+- **`docs/FEATURES.md`**: a single inventory of the project's promised features (CLI, HTTP API, resource provisioning, plugin, seeds, queue primitives, config/isolation), doubling as the integration suite's checklist. The integration suite provisions `examples/sample-microservice` and asserts each capability; it runs locally and in a CI job gated on a `LOCALSTACK_AUTH_TOKEN` secret.
+
+## [0.1.2] - 2026-05-26
+
+### Added
+- **`npx lss seed:clear` now requires interactive confirmation**: before issuing any `DeleteRequest`, the CLI lists the exact LocalStack tables it would wipe, prints the LocalStack URL, makes the "this never touches AWS" guarantee explicit, and waits for the user to type `confirmar` (case-sensitive, exact match after trim). Anything else cancels with `🚫 Cancelado — nenhuma alteração feita.` and no clear call is made. `--yes` / `-y` skips the prompt for CI use.
+- **Defensive endpoint guard in `SeedManager`**: `clearTable` and `clearAllSeeded` now refuse to run unless the resolved DynamoDB endpoint hostname is on a hardcoded local allowlist (`localhost`, `127.0.0.1`, `::1`, `0.0.0.0`, `host.docker.internal`, `localstack`, `lss-localstack`, `lss-localstack-<port>`, `*.localhost`). If a future refactor ever pointed `LocalStackManager.getConfig()` at a real AWS endpoint, the guard would throw `Refusing destructive operation: endpoint "..." is not a recognized local LocalStack host. seed:clear may ONLY run against LocalStack — never against AWS.` before any AWS SDK call. Architecture already pinned writes to LocalStack via fake credentials; this is belt-and-braces.
+- **Seed/clear mismatch diagnostic**: `GET /api/seeds` now also returns `liveTables: string[]` (every DynamoDB table currently in LocalStack). When `npx lss seed` skips tables or `npx lss seed:clear` finds no live targets, the CLI prints a two-column diagnostic — seed files inspected on one side, live LocalStack tables on the other — with the hint "Os nomes dos arquivos de seed precisam bater EXATAMENTE com o `TableName` no CloudFormation." This makes seed-name/table-name typos obvious instead of "nothing happened, why?". When the live-tables list is empty, the CLI falls back to the older "run `npx lss start` + `npx serverless deploy` first" hint.
+- **Test infrastructure**: new `tests/unit/seed-manager-guard.test.ts` (27 tests covering the endpoint allowlist matrix, IPv6 bracket handling, malformed URLs, and that `clearTable`/`clearAllSeeded` invoke the guard) and `tests/unit/cli-seed.test.ts` (21 tests spawning `bin/cli.js` against an in-process HTTP stub of the orchestrator — covers confirmation flow, `--yes`/`-y` bypass, "no live tables" diagnostic, name-mismatch diagnostic, and `formatError` robustness against 500-with-empty-body / 500-with-non-JSON / `{error: ""}` responses).
+
+### Changed
+- **`bin/cli.js` error handling never leaves the user with an empty message**: new `formatError(e)` and `buildHttpError(res, data)` helpers walk a fallback chain (`e.message` → `e.code` → `e.name` → body snippet → HTTP status text → "erro desconhecido (sem detalhes)") so a response 500 with no body, a socket reset during orchestrator startup, or an `Error` with empty `.message` all produce a useful CLI line instead of `❌ Não consegui listar as tabelas antes de limpar:` with a blank suffix. Applied to every `console.error` path in `seed`, `seed:clear`, and the underlying `getJson`/`postJson` helpers.
+- **`npx lss seed` hint when tables are missing in LocalStack**: previously printed a generic "tabelas foram puladas" footer. Now it fetches `liveTables` and shows the same mismatch diagnostic as `seed:clear`, so the user sees whether the cause is "I haven't deployed yet" (no live tables) or "my seed file name is wrong" (live tables exist but don't match).
+- **`firstPositional()` arg parser in the CLI**: commands that accept an optional table name (`seed`, `seed:clear`) now skip args starting with `-`. Without this, `npx lss seed:clear --yes` was interpreting `--yes` as the table name.
+- **`SeedManager.assertLocalEndpoint` normalizes IPv6 brackets** so URLs like `http://[::1]:4566` (which `new URL().hostname` reports as `[::1]`) match the `::1` entry in the allowlist instead of being rejected as non-local.
+- **`jest.config.js` `moduleNameMapper`**: strips `.js` from relative imports during tests so the server's NodeNext-style ESM imports (`import { Foo } from './foo.js'`) resolve to TypeScript sources under ts-jest. Without this, no unit test could import from `src/server/`.
+
+### Fixed
+- **`examples/pro-sample-microservice/seeds/`**: renamed `sample-microservice-Users.json` → `pro-sample-microservice-Users.json` and `sample-microservice-Orders.json` → `pro-sample-microservice-Orders.json` (via `git mv` to preserve history). The files had been copied from `sample-microservice` but never renamed, so the seed prefix didn't match the example's actual `${self:service}-*` `TableName`s in `serverless.yml` — `npx lss seed` and `npx lss seed:clear` always found `tableExists: false` and silently did nothing.
+
 ## [0.1.1] - 2026-05-21
 
 ### Added
@@ -310,7 +345,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Requires Docker for LocalStack
 - Tested on Linux (Ubuntu/Debian)
 - Node.js >= 18 required
-- Serverless Framework >= 3.0 required
+- Serverless Framework 3.40.0 required
 
 ### Breaking Changes
 None (initial release)

package/README.md

@@ -17,6 +17,8 @@ LSS provides a unified local development environment for serverless microservice
 - **Process management**: Start/stop microservices from the orchestrator
 - **CLI Tool**: Simple commands to manage the orchestrator (start/stop/status/logs)
 
+See [docs/FEATURES.md](docs/FEATURES.md) for the complete feature inventory and how each capability is tested.
+
 ## Architecture
 
 ```
@@ -50,7 +52,7 @@ local-serverless-stack/
 
 - Node.js >= 18
 - Docker (for LocalStack)
-- Serverless Framework >= 3.0
+- Serverless Framework 3.40.0
 
 ### Installation
 
@@ -74,7 +76,7 @@ The `npm link` command makes the `lss` CLI available globally via `npx`.
 To automatically register your microservices with LSS, install the Serverless plugin:
 
 ```bash
-npm install --save-dev lss-serverless-plugin
+npm install --save-dev serverless-lss
 ```
 
 See the [plugin documentation](packages/serverless-plugin/README.md) for configuration details.
@@ -146,7 +148,7 @@ npm link local-serverless-stack
 In each microservice directory:
 
 ```bash
-npm link lss-serverless-plugin
+npm link serverless-lss
 ```
 
 ### 3. Configure serverless.yml
@@ -159,7 +161,7 @@ plugins:
   - serverless-esbuild
   - serverless-offline
   - serverless-localstack
-  - lss-serverless-plugin  # Add this line
+  - serverless-lss  # Add this line
 
 custom:
   orchestrator:

package/bin/cli.js

@@ -11,10 +11,24 @@ const os = require('os');
 const DEFAULT_PID_FILE = path.join(os.tmpdir(), 'lss-orchestrator.pid');
 const DEFAULT_LOG_FILE = path.join(os.tmpdir(), 'lss-orchestrator.log');
 
-// PID/log file paths scoped to the cwd's serverPort. Multiple examples sitting
-// in different folders no longer trample each other.
+// PID/log file paths for the instance addressed by this invocation.
+//   - When the config provides a `stateDir`, PID/log live inside it. This gives
+//     an explicitly isolated instance (e.g. an e2e test stack) its own state so
+//     `lss stop --config <path>` targets it and never the dev instance.
+//   - Otherwise the paths are scoped to the cwd's serverPort, so multiple
+//     examples sitting in different folders don't trample each other.
 function runtimePaths() {
   const cfg = getConfig(loadConfig());
+
+  if (cfg.stateDir) {
+    const dir = path.resolve(process.cwd(), cfg.stateDir);
+    fs.mkdirSync(dir, { recursive: true });
+    return {
+      pidFile: path.join(dir, 'orchestrator.pid'),
+      logFile: path.join(dir, 'orchestrator.log'),
+    };
+  }
+
   const port = cfg.serverPort;
   // Keep the legacy global path when the default port is in use so existing
   // installations don't lose their running process across an upgrade.
@@ -28,9 +42,24 @@ function runtimePaths() {
 }
 
 /**
- * Load configuration from lss.config.json or .lssrc
+ * Load configuration. An explicit `--config <path>` (or LSS_CONFIG env) wins over
+ * the cwd/home search so an isolated instance can point at its own config file.
+ * A missing or unparseable explicit file warns and falls back to the search,
+ * rather than hard-exiting, so stop/status/logs never orphan a running instance.
  */
 function loadConfig() {
+  if (EXPLICIT_CONFIG) {
+    if (fs.existsSync(EXPLICIT_CONFIG)) {
+      try {
+        return JSON.parse(fs.readFileSync(EXPLICIT_CONFIG, 'utf-8'));
+      } catch (error) {
+        console.warn(`⚠️  Failed to parse config file ${EXPLICIT_CONFIG}`);
+      }
+    } else {
+      console.warn(`⚠️  Config file not found: ${EXPLICIT_CONFIG}`);
+    }
+  }
+
   const candidates = [
     path.join(process.cwd(), 'lss.config.json'),
     path.join(process.cwd(), '.lssrc'),
@@ -66,6 +95,7 @@ function getConfig(config) {
     localstackVersion: config.localstackVersion || 'latest',
     localstackImage: config.localstackImage,
     localstackAuthToken: config.localstackAuthToken,
+    stateDir: config.stateDir,
   };
 }
 
@@ -79,6 +109,15 @@ function getArgValue(name) {
   return inline ? inline.slice(prefix.length) : undefined;
 }
 
+// Resolved once per invocation: an explicit config file from `--config <path>`
+// (or the LSS_CONFIG env var), resolved to an absolute path so it's found
+// regardless of cwd. Every argument-less loadConfig() call honors it because
+// process.argv is fixed for the lifetime of the invocation.
+const EXPLICIT_CONFIG = (() => {
+  const v = getArgValue('--config') || process.env.LSS_CONFIG;
+  return v ? path.resolve(v) : undefined;
+})();
+
 // Resolve orchestrator path - works both in development and when installed via npm
 function getOrchestratorPath() {
   // Try to find the orchestrator relative to this script
@@ -151,24 +190,30 @@ function startOrchestrator() {
 
   // Build environment variables from config
   const env = { ...process.env };
+  /* istanbul ignore else: getConfig() always defaults serverPort to 3100, so the else is unreachable */
   if (cfg.serverPort) {
     env.PORT = cfg.serverPort;
   }
+  /* istanbul ignore else: getConfig() always defaults localstackPort to 4566, so the else is unreachable */
   if (cfg.localstackPort) {
     env.LSS_LOCALSTACK_PORT = cfg.localstackPort;
   }
   if (enableDynamoProxy) {
     env.LSS_ENABLE_DYNAMO_PROXY = 'true';
   }
+  /* istanbul ignore else: getConfig() always defaults dynamoProxyPort to 8000, so the else is unreachable */
   if (cfg.dynamoProxyPort) {
     env.LSS_DYNAMO_PROXY_PORT = cfg.dynamoProxyPort;
   }
+  /* istanbul ignore else: mode resolves to cfg.mode which getConfig() defaults to 'managed', so the else is unreachable */
   if (mode) {
     env.LSS_LOCALSTACK_MODE = mode;
   }
+  /* istanbul ignore else: edition resolves to localstackEdition which getConfig() defaults to 'community', so the else is unreachable */
   if (edition) {
     env.LSS_LOCALSTACK_EDITION = edition;
   }
+  /* istanbul ignore else: getConfig() always defaults localstackVersion to 'latest', so the else is unreachable */
   if (cfg.localstackVersion) {
     env.LSS_LOCALSTACK_VERSION = cfg.localstackVersion;
   }
@@ -178,7 +223,13 @@ function startOrchestrator() {
   if (authToken) {
     env.LOCALSTACK_AUTH_TOKEN = authToken;
   }
-  
+  // Hand the same config file to the server so its ConfigManager reads the
+  // identical serverPort/localstackPort/seedsDir/region/mode (not just the
+  // hand-translated subset above). Keeps the two config loaders in agreement.
+  if (EXPLICIT_CONFIG) {
+    env.LSS_CONFIG_PATH = EXPLICIT_CONFIG;
+  }
+
   const child = spawn('node', [orchestratorPath], {
     detached: true,
     stdio: ['ignore', logFd, logFd],
@@ -263,6 +314,30 @@ function getServerPort() {
   return cfg.serverPort;
 }
 
+// Produce a usable error string for the user. Errors from the http stack
+// occasionally carry an empty `.message` (e.g. socket resets during the
+// orchestrator startup window) — fall back through every signal we have so
+// `formatError` is guaranteed not to return an empty string.
+function formatError(e) {
+  if (!e) return 'erro desconhecido (sem detalhes)';
+  if (typeof e === 'string') return e.trim() || 'erro desconhecido (sem detalhes)';
+  if (e.message && String(e.message).trim()) return String(e.message).trim();
+  if (e.code) return `erro de I/O (${e.code})`;
+  if (e.name) return e.name;
+  const s = String(e);
+  return s && s !== '[object Object]' ? s : 'erro desconhecido (sem detalhes)';
+}
+
+function buildHttpError(res, data) {
+  let parsed;
+  try { parsed = data ? JSON.parse(data) : {}; } catch { parsed = null; }
+  const fromBody = parsed && (parsed.error || parsed.message);
+  if (fromBody && String(fromBody).trim()) return new Error(String(fromBody).trim());
+  const snippet = data && data.length < 300 ? data.trim() : '';
+  const statusText = res.statusMessage ? `${res.statusCode} ${res.statusMessage}` : `${res.statusCode}`;
+  return new Error(snippet ? `HTTP ${statusText}: ${snippet}` : `HTTP ${statusText} (sem corpo de erro)`);
+}
+
 function postJson(path, body) {
   return new Promise((resolve, reject) => {
     const http = require('http');
@@ -282,17 +357,17 @@ function postJson(path, body) {
         let data = '';
         res.on('data', chunk => (data += chunk));
         res.on('end', () => {
-          let parsed;
-          try { parsed = data ? JSON.parse(data) : {}; } catch { parsed = { raw: data }; }
           if (res.statusCode >= 200 && res.statusCode < 300) {
+            let parsed;
+            try { parsed = data ? JSON.parse(data) : {}; } catch { parsed = { raw: data }; }
             resolve(parsed);
           } else {
-            reject(new Error(parsed.error || `HTTP ${res.statusCode}`));
+            reject(buildHttpError(res, data));
           }
         });
       },
     );
-    req.on('error', reject);
+    req.on('error', err => reject(err && err.message ? err : new Error(`falha na conexão HTTP com o orchestrator: ${formatError(err)}`)));
     req.write(payload);
     req.end();
   });
@@ -307,13 +382,53 @@ function ensureRunningOrExit() {
 }
 
 function printSeedRunResults(results) {
+  let missingTables = 0;
   for (const r of results) {
     if (r.skipped) {
       console.log(`  ⚠ ${r.tableName}: skipped (${r.reason})`);
+      if (r.reason && r.reason.includes('does not exist in LocalStack')) {
+        missingTables++;
+      }
     } else {
       console.log(`  ✓ ${r.tableName}: ${r.inserted} item(s) inserted`);
     }
   }
+  return { missingTables };
+}
+
+// Show the user both sides of the comparison: the seed files we found, and
+// the DynamoDB tables actually living in LocalStack. This is the difference
+// between "I didn't deploy yet" (no live tables at all) and "my seed file
+// name doesn't match the CFN TableName" (live tables exist, just not those).
+function printSeedMismatchDiagnostic({ entries, liveTables, focusTable }) {
+  const seedNames = entries.map(e => e.tableName);
+  const focusList = focusTable ? [focusTable] : seedNames;
+
+  console.log('');
+  if (focusTable) {
+    console.log(`📂 Arquivo de seed inspecionado: ${focusTable}.json`);
+  } else if (focusList.length > 0) {
+    console.log('📂 Arquivos de seed inspecionados (tabela esperada):');
+    for (const name of focusList) console.log(`     - ${name}`);
+  } else {
+    console.log('📂 Nenhum arquivo *.json encontrado no seedsDir.');
+  }
+
+  if (liveTables && liveTables.length > 0) {
+    console.log('');
+    console.log(`🗂️  Tabelas vivas no LocalStack (${liveTables.length}):`);
+    for (const name of liveTables) console.log(`     - ${name}`);
+    console.log('');
+    console.log('💡 Os nomes dos arquivos de seed precisam bater EXATAMENTE com o `TableName` no CloudFormation.');
+    console.log('   Confira se há prefixo/sufixo divergente entre o arquivo e a tabela.');
+  } else {
+    console.log('');
+    console.log('🗂️  Nenhuma tabela viva no LocalStack ainda.');
+    console.log('💡 Provavelmente o stack ainda não foi provisionado. Tente:');
+    console.log('     npx lss start                # garante LocalStack rodando');
+    console.log('     npx serverless deploy        # cria as tabelas');
+    console.log('   E rode `npx lss seed` novamente.');
+  }
 }
 
 function printSeedClearResults(results) {
@@ -331,21 +446,130 @@ async function runSeed(tableName) {
   try {
     console.log(tableName ? `🌱 Seeding ${tableName}...` : '🌱 Seeding all tables with seed files...');
     const res = await postJson('/api/seeds/run', tableName ? { tableName } : {});
-    printSeedRunResults(res.results || []);
+    const { missingTables } = printSeedRunResults(res.results || []);
+    if (missingTables > 0) {
+      try {
+        const list = await getJson('/api/seeds');
+        printSeedMismatchDiagnostic({
+          entries: (list.entries || []).filter(e => !e.tableExists),
+          liveTables: list.liveTables || [],
+          focusTable: tableName,
+        });
+      } catch (diagErr) {
+        // Diagnostic is best-effort; don't fail the seed because the hint failed.
+        console.log(`(não consegui detalhar tabelas vivas: ${formatError(diagErr)})`);
+      }
+    }
   } catch (e) {
-    console.error('❌ Seed failed:', e.message);
+    console.error('❌ Seed failed:', formatError(e));
     process.exit(1);
   }
 }
 
+function getJson(path) {
+  return new Promise((resolve, reject) => {
+    const http = require('http');
+    const req = http.request(
+      {
+        hostname: 'localhost',
+        port: getServerPort(),
+        path,
+        method: 'GET',
+      },
+      res => {
+        let data = '';
+        res.on('data', chunk => (data += chunk));
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            let parsed;
+            try { parsed = data ? JSON.parse(data) : {}; } catch { parsed = { raw: data }; }
+            resolve(parsed);
+          } else {
+            reject(buildHttpError(res, data));
+          }
+        });
+      },
+    );
+    req.on('error', err => reject(err && err.message ? err : new Error(`falha na conexão HTTP com o orchestrator: ${formatError(err)}`)));
+    req.end();
+  });
+}
+
+function promptConfirmation(expectedWord) {
+  return new Promise(resolve => {
+    const readline = require('readline');
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(`Digite "${expectedWord}" para prosseguir (ou qualquer outra coisa para cancelar): `, answer => {
+      rl.close();
+      resolve(answer.trim() === expectedWord);
+    });
+  });
+}
+
 async function clearSeed(tableName) {
   ensureRunningOrExit();
+
+  const skipConfirm = process.argv.includes('--yes') || process.argv.includes('-y');
+  const cfg = getConfig(loadConfig());
+
+  // Show the user exactly what's about to be wiped before they confirm.
+  // Hitting the orchestrator's GET /api/seeds also implicitly proves we're
+  // talking to LocalStack and not AWS — the orchestrator only ever connects
+  // to the configured local LocalStack endpoint.
+  let scopeDescription;
+  try {
+    const list = await getJson('/api/seeds');
+    const entries = list.entries || [];
+    const liveTables = list.liveTables || [];
+    const targets = tableName ? entries.filter(e => e.tableName === tableName) : entries;
+    const liveTargets = targets.filter(e => e.tableExists);
+
+    if (liveTargets.length === 0) {
+      if (tableName) {
+        console.log(`⚠️  Nenhuma tabela "${tableName}" existente no LocalStack para limpar.`);
+      } else if (entries.length === 0) {
+        console.log('⚠️  Nenhum arquivo de seed (*.json) encontrado no seedsDir — nada para limpar.');
+      } else {
+        console.log(`⚠️  ${entries.length} arquivo(s) de seed encontrados, mas NENHUMA das tabelas correspondentes existe no LocalStack.`);
+      }
+      printSeedMismatchDiagnostic({ entries, liveTables, focusTable: tableName });
+      return;
+    }
+
+    scopeDescription = tableName
+      ? `a tabela "${tableName}"`
+      : `${liveTargets.length} tabela(s): ${liveTargets.map(e => e.tableName).join(', ')}`;
+
+    console.log('');
+    console.log('⚠️  ATENÇÃO: operação destrutiva');
+    console.log(`   Alvo:      ${scopeDescription}`);
+    console.log(`   LocalStack: http://localhost:${cfg.localstackPort}`);
+    console.log('   Esta ação NÃO toca em nenhuma conta AWS — apenas o LocalStack acima.');
+    console.log('');
+  } catch (e) {
+    console.error('❌ Não consegui listar as tabelas antes de limpar:', formatError(e));
+    process.exit(1);
+  }
+
+  if (!skipConfirm) {
+    const ok = await promptConfirmation('confirmar');
+    if (!ok) {
+      console.log('🚫 Cancelado — nenhuma alteração feita.');
+      return;
+    }
+  } else {
+    console.log('↳ --yes informado, pulando confirmação interativa.');
+  }
+
   try {
     console.log(tableName ? `🧹 Clearing ${tableName}...` : '🧹 Clearing all seeded tables...');
     const res = await postJson('/api/seeds/clear', tableName ? { tableName } : {});
     printSeedClearResults(res.results || []);
   } catch (e) {
-    console.error('❌ Clear failed:', e.message);
+    console.error('❌ Clear failed:', formatError(e));
     process.exit(1);
   }
 }
@@ -364,14 +588,20 @@ Commands:
   seed [table]       Apply seed file(s) from seedsDir into DynamoDB
                      (no args = all matching tables)
   seed:clear [table] Delete all items from the given table (or all
-                     tables with a seed file when no arg is given)
+                     tables with a seed file when no arg is given).
+                     Pede confirmação interativa (digitar "confirmar")
+                     antes de qualquer escrita.
   help               Show this help message
 
 Options:
+  --config <path>              Load config from this file (precedes the cwd/home search).
+                               Applies to start/stop/status/logs so an isolated instance
+                               can be addressed without cd-ing into its folder.
   --enable-dynamo-proxy        Enable DynamoDB proxy on port 8000 (for start command)
   --external                   Connect to a LocalStack already running, do not spawn a container
   --pro                        Use the LocalStack Pro image (requires LOCALSTACK_AUTH_TOKEN)
   --localstack-token <token>   Pass a LOCALSTACK_AUTH_TOKEN to the container
+  --yes, -y                    Skip interactive confirmation on seed:clear (use only in CI)
 
 Environment:
   LOCALSTACK_AUTH_TOKEN        Token forwarded to LocalStack (Pro and >=2026.5 community)
@@ -391,9 +621,14 @@ Configuration:
     "region": "us-east-1",
     "services": ["dynamodb", "sqs", "sns", "lambda"],
     "persistence": true,
-    "debug": false
+    "debug": false,
+    "stateDir": ".lss"
   }
 
+  stateDir (optional): directory for this instance's PID/log files. Set it (e.g.
+  ".lss-e2e") together with --config to run a fully isolated instance alongside
+  the dev one. When omitted, PID/log live in the OS temp dir scoped by serverPort.
+
   For the Serverless Plugin, add to serverless.yml:
   custom:
     orchestrator:
@@ -411,7 +646,8 @@ Examples:
   npx lss logs                               # View logs
   npx lss seed                               # Seed every table that has a {name}.json file
   npx lss seed users                         # Seed only the "users" table
-  npx lss seed:clear users                   # Delete all items from "users"
+  npx lss seed:clear users                   # Delete all items from "users" (com confirmação)
+  npx lss seed:clear users --yes             # Mesma coisa, sem prompt (CI)
 `);
 }
 
@@ -430,34 +666,77 @@ function showLogs() {
   console.log(lastLines);
 }
 
-const command = process.argv[2];
-
-switch (command) {
-  case 'start':
-    startOrchestrator();
-    break;
-  case 'stop':
-    stopOrchestrator();
-    break;
-  case 'status':
-    showStatus();
-    break;
-  case 'logs':
-    showLogs();
-    break;
-  case 'seed':
-    runSeed(process.argv[3]);
-    break;
-  case 'seed:clear':
-    clearSeed(process.argv[3]);
-    break;
-  case 'help':
-  case '--help':
-  case '-h':
-    showHelp();
-    break;
-  default:
-    console.log('❌ Unknown command:', command);
-    showHelp();
-    process.exit(1);
+// First positional arg after the command (e.g. table name for `seed`/`seed:clear`).
+// Skip anything that looks like a flag so `seed:clear --yes` doesn't pass
+// "--yes" as the table name.
+function firstPositional() {
+  for (let i = 3; i < process.argv.length; i++) {
+    const arg = process.argv[i];
+    if (!arg.startsWith('-')) return arg;
+  }
+  return undefined;
+}
+
+// Exported so the pure/in-process helpers can be unit-tested by requiring this
+// module. The command dispatch below only runs when the file is executed
+// directly (the `lss` bin), never when required, so requiring it has no side
+// effects.
+module.exports = {
+  loadConfig,
+  getConfig,
+  getArgValue,
+  runtimePaths,
+  getOrchestratorPath,
+  formatError,
+  buildHttpError,
+  firstPositional,
+  getServerPort,
+  printSeedRunResults,
+  printSeedMismatchDiagnostic,
+  printSeedClearResults,
+  getJson,
+  postJson,
+  ensureRunningOrExit,
+  promptConfirmation,
+  startOrchestrator,
+  stopOrchestrator,
+  showStatus,
+  showLogs,
+  runSeed,
+  clearSeed,
+  showHelp,
+};
+
+/* istanbul ignore next: CLI dispatch runs only when executed directly, not when required in tests */
+if (require.main === module) {
+  const command = process.argv[2];
+  switch (command) {
+    case 'start':
+      startOrchestrator();
+      break;
+    case 'stop':
+      stopOrchestrator();
+      break;
+    case 'status':
+      showStatus();
+      break;
+    case 'logs':
+      showLogs();
+      break;
+    case 'seed':
+      runSeed(firstPositional());
+      break;
+    case 'seed:clear':
+      clearSeed(firstPositional());
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+      showHelp();
+      break;
+    default:
+      console.log('❌ Unknown command:', command);
+      showHelp();
+      process.exit(1);
+  }
 }

package/dist/server/dev/dynamo-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamo-proxy.d.ts","sourceRoot":"","sources":["../../../src/server/dev/dynamo-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAIxB,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,SAAO,wEAwCnE"}
+{"version":3,"file":"dynamo-proxy.d.ts","sourceRoot":"","sources":["../../../src/server/dev/dynamo-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAIxB,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,SAAO,wEA4CnE"}

package/dist/server/dev/dynamo-proxy.js

@@ -4,23 +4,27 @@ import http from 'http';
 export function startDynamoProxy(targetEndpoint, port = 8000) {
     const targetBase = targetEndpoint.replace(/\/$/, '');
     const server = http.createServer((req, res) => {
+        /* istanbul ignore next: Node's http server always populates req.url; defensive guard only */
         if (!req.url) {
             res.statusCode = 400;
             res.end('Bad Request');
             return;
         }
         const url = `${targetBase}${req.url}`;
+        /* istanbul ignore next: req.headers is always populated by Node's http server */
         const headers = { ...(req.headers || {}) };
         delete headers['host'];
         const upstream = http.request(url, {
             method: req.method,
             headers,
         }, upstreamRes => {
+            /* istanbul ignore next: a real upstream response always carries a statusCode */
             res.writeHead(upstreamRes.statusCode || 502, upstreamRes.headers);
             upstreamRes.pipe(res);
         });
         upstream.on('error', err => {
             console.error('Proxy error:', err);
+            /* istanbul ignore next: headers are not yet sent when the upstream connection fails */
             if (!res.headersSent)
                 res.writeHead(502);
             res.end('Bad Gateway');

package/dist/server/dev/dynamo-proxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"dynamo-proxy.js","sourceRoot":"","sources":["../../../src/server/dev/dynamo-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,uGAAuG;AACvG,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,cAAsB,EAAE,IAAI,GAAG,IAAI;IAClE,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAErD,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC5C,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;YACrB,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YACvB,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAA8B,CAAC;QACvE,OAAQ,OAAe,CAAC,MAAM,CAAC,CAAC;QAEhC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAC3B,GAAG,EACH;YACE,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,OAAO;SACR,EACD,WAAW,CAAC,EAAE;YACZ,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,UAAU,IAAI,GAAG,EAAE,WAAW,CAAC,OAAmC,CAAC,CAAC;YAC9F,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC,CACF,CAAC;QAEF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE;YACzB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;YACnC,IAAI,CAAC,GAAG,CAAC,WAAW;gBAAE,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YACzC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;QACvB,OAAO,CAAC,GAAG,CAAC,kDAAkD,IAAI,OAAO,UAAU,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"dynamo-proxy.js","sourceRoot":"","sources":["../../../src/server/dev/dynamo-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,uGAAuG;AACvG,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,cAAsB,EAAE,IAAI,GAAG,IAAI;IAClE,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAErD,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC5C,6FAA6F;QAC7F,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;YACrB,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YACvB,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC;QACtC,iFAAiF;QACjF,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAA8B,CAAC;QACvE,OAAQ,OAAe,CAAC,MAAM,CAAC,CAAC;QAEhC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAC3B,GAAG,EACH;YACE,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,OAAO;SACR,EACD,WAAW,CAAC,EAAE;YACZ,gFAAgF;YAChF,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,UAAU,IAAI,GAAG,EAAE,WAAW,CAAC,OAAmC,CAAC,CAAC;YAC9F,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC,CACF,CAAC;QAEF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE;YACzB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;YACnC,uFAAuF;YACvF,IAAI,CAAC,GAAG,CAAC,WAAW;gBAAE,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YACzC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;QACvB,OAAO,CAAC,GAAG,CAAC,kDAAkD,IAAI,OAAO,UAAU,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/server/routes/queues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queues.d.ts","sourceRoot":"","sources":["../../../src/server/routes/queues.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,MAAM,4CAAW,CAAC;AAyHxB,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,CAAC"}
+{"version":3,"file":"queues.d.ts","sourceRoot":"","sources":["../../../src/server/routes/queues.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,MAAM,4CAAW,CAAC;AAwMxB,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,CAAC"}