local-serverless-stack 1.0.0 → 1.1.0

package/bin/cli.js

@@ -51,19 +51,25 @@ function runtimePaths() {
 /**
  * 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.
+ *
+ * A missing or unparseable explicit file is a hard error (exit 1), for every
+ * command. It used to warn and fall back to the cwd/home search — and that
+ * search resolves to whatever instance the default config describes, so a typo
+ * in `lss stop --config ./wrong.json` stopped a DIFFERENT running stack. Naming
+ * a file is a statement about which instance you mean; guessing another one is
+ * never the safe default.
  */
 function loadConfig() {
   if (EXPLICIT_CONFIG) {
-    if (fs.existsSync(EXPLICIT_CONFIG)) {
-      try {
-        return JSON.parse(fs.readFileSync(EXPLICIT_CONFIG, 'utf-8'));
-      } catch (error) {
-        console.warn(t('config.parseFailed', { path: EXPLICIT_CONFIG }));
-      }
-    } else {
-      console.warn(t('config.notFound', { path: EXPLICIT_CONFIG }));
+    if (!fs.existsSync(EXPLICIT_CONFIG)) {
+      console.error(t('config.explicitNotFound', { path: EXPLICIT_CONFIG }));
+      process.exit(1);
+    }
+    try {
+      return JSON.parse(fs.readFileSync(EXPLICIT_CONFIG, 'utf-8'));
+    } catch (error) {
+      console.error(t('config.explicitParseFailed', { path: EXPLICIT_CONFIG, error: formatError(error) }));
+      process.exit(1);
     }
   }
 
@@ -106,8 +112,9 @@ function envPort(name) {
  * documented workflow (docs/CONFIGURATION.md), so it has to agree end to end.
  */
 function getConfig(config) {
+  const serverPort = envPort('LSS_DASHBOARD_PORT') || envPort('PORT') || config.serverPort || DEFAULT_PORT;
   return {
-    serverPort: envPort('LSS_DASHBOARD_PORT') || envPort('PORT') || config.serverPort || DEFAULT_PORT,
+    serverPort,
     enableDynamoProxy: process.env.LSS_ENABLE_DYNAMO_PROXY
       ? process.env.LSS_ENABLE_DYNAMO_PROXY === 'true' || process.env.LSS_ENABLE_DYNAMO_PROXY === '1'
       : config.enableDynamoProxy || false,
@@ -115,7 +122,9 @@ function getConfig(config) {
     mode: config.mode || 'managed',
     stateDir: config.stateDir,
     engine: config.engine,
-    selfEnginePort: envPort('LSS_ENGINE_PORT') || (config.selfEngine && config.selfEngine.port) || DEFAULT_PORT,
+    // Follows serverPort unless set explicitly, exactly like the server
+    // (ConfigManager.getSelfEnginePort): one port for the whole stack.
+    selfEnginePort: envPort('LSS_ENGINE_PORT') || (config.selfEngine && config.selfEngine.port) || serverPort,
   };
 }
 
@@ -159,7 +168,47 @@ function getOrchestratorPath() {
   return null;
 }
 
-function startOrchestrator() {
+/**
+ * Who is answering on our serverPort, if anyone: the `projectRoot` reported by
+ * `GET /api/config`. Under `--net=host` the port belongs to the whole machine,
+ * so "someone answers but it is not us" is a routine outcome — and the one the
+ * old `NOT RUNNING` turned into a wild goose chase. Returns null when nothing
+ * answers (or answers something else), because this only ever adds detail to a
+ * message; it must never become a reason to fail.
+ */
+async function probePortOwner() {
+  try {
+    const config = await getJson('/api/config');
+    return typeof config?.projectRoot === 'string' ? config.projectRoot : null;
+  } catch {
+    return null;
+  }
+}
+
+// The last `lines` lines of the orchestrator log — where the reason a boot died
+// (EADDRINUSE, a bad config) is written, seconds before the CLI notices.
+function tailLog(logFile, lines = 15) {
+  try {
+    const content = fs.readFileSync(logFile, 'utf8');
+    return content.split('\n').filter(Boolean).slice(-lines).join('\n');
+  } catch {
+    return '';
+  }
+}
+
+// Report a port held by a different project's orchestrator. Returns true when
+// it printed something, so callers can skip their own vaguer message.
+function reportPortOwner(owner, port, log = console.log) {
+  if (!owner) return false;
+  const here = process.cwd();
+  const mine = owner === here || here.startsWith(`${owner}${path.sep}`);
+  log(mine
+    ? t('status.portAnsweringHere', { port })
+    : t('status.portOwnedByOther', { port, root: owner }));
+  return true;
+}
+
+async function startOrchestrator() {
   // Before anything else — including the already-running short-circuit — so a
   // stale 0.x flag or config value always fails loudly instead of looking like
   // a successful no-op.
@@ -243,17 +292,88 @@ function startOrchestrator() {
   }
   console.log(t('start.logs', { path: logFile }));
 
-  setTimeout(() => {
+  // `--wait` blocks until the orchestrator actually answers, which is what a
+  // sequential chain (a VS Code task, a CI step, a boot script) needs: without
+  // it the next step's `register` fails fifteen times for a reason that is not
+  // the cause — the cause is in the first line of the log, minutes earlier.
+  if (process.argv.includes('--wait') || getArgValue('--wait') !== undefined) {
+    const seconds = Number.parseInt(getArgValue('--wait') || '', 10);
+    return waitForHealthy(child.pid, pidFile, logFile, Number.isInteger(seconds) && seconds > 0 ? seconds : 30);
+  }
+
+  // Without --wait the CLI still has to answer honestly. Daemonizing means the
+  // child discovers a busy port AFTER this process has printed a PID, so the
+  // liveness check below is the only place a non-zero exit can come from — and
+  // it used to print the failure and exit 0 anyway, making a dead orchestrator
+  // count as a successful step.
+  return scheduleLivenessCheck(child.pid, pidFile, logFile);
+}
+
+// Two seconds later: is the child still there? Resolves when it is, exits
+// non-zero when it is not. Returned as a promise so the caller (and the tests)
+// can observe the outcome instead of it happening in a detached timer.
+function scheduleLivenessCheck(pid, pidFile, logFile) {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      try {
+        process.kill(pid, 0);
+      } catch (e) {
+        // process.exit never returns in production; under test it throws, and
+        // the rejection is how a test asserts the exit code.
+        reportStartFailure(pidFile, logFile).then(() => process.exit(1)).then(resolve, reject);
+        return;
+      }
+      console.log(t('start.running'));
+      resolve();
+    }, 2000);
+  });
+}
+
+// Everything known about a boot that did not survive: the log tail, and whether
+// the port it wanted is held by another project's orchestrator.
+async function reportStartFailure(pidFile, logFile) {
+  console.error(t('start.failed', { path: logFile }));
+  if (fs.existsSync(pidFile)) {
+    fs.unlinkSync(pidFile);
+  }
+  const tail = tailLog(logFile);
+  if (tail) {
+    console.error(t('start.logTail'));
+    console.error(tail);
+  }
+  reportPortOwner(await probePortOwner(), getServerPort(), console.error);
+}
+
+/**
+ * Poll `GET /api/health` until the orchestrator answers, the child dies, or the
+ * deadline passes. Resolves on success; exits non-zero (after printing the log
+ * tail) on either failure — a `lss start --wait` that returns 0 means the stack
+ * is up and can be registered against.
+ */
+async function waitForHealthy(pid, pidFile, logFile, timeoutSeconds) {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  console.log(t('start.waiting', { seconds: timeoutSeconds }));
+  for (;;) {
+    try {
+      process.kill(pid, 0);
+    } catch {
+      await reportStartFailure(pidFile, logFile);
+      process.exit(1);
+    }
     try {
-      process.kill(child.pid, 0);
+      await getJson('/api/health');
       console.log(t('start.running'));
-    } catch (e) {
-      console.error(t('start.failed', { path: logFile }));
-      if (fs.existsSync(pidFile)) {
-        fs.unlinkSync(pidFile);
-      }
+      return;
+    } catch {
+      // Not up yet — the connection is refused until the listener binds.
+    }
+    if (Date.now() >= deadline) {
+      console.error(t('start.waitTimeout', { seconds: timeoutSeconds }));
+      await reportStartFailure(pidFile, logFile);
+      process.exit(1);
     }
-  }, 2000);
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
 }
 
 // Poll kill(pid, 0) until the process is gone. SIGTERM alone isn't enough to
@@ -317,10 +437,23 @@ async function stopOrchestrator() {
   }
 }
 
-function showStatus() {
+/**
+ * `lss status` — is THIS project's orchestrator running?
+ *
+ * The pid file answers that, and it used to answer nothing else: with
+ * `--net=host` the port belongs to the whole machine, so another project's
+ * orchestrator holding it produced `NOT RUNNING` from a port that answers 200 —
+ * a status that is not merely unhelpful but points the operator at the wrong
+ * place. Every "no" is now followed by asking WHO is on the port, which
+ * `GET /api/config` answers exactly (`projectRoot`).
+ */
+async function showStatus() {
   const { pidFile, logFile } = runtimePaths();
+  const cfg = getConfig(loadConfig());
   if (!fs.existsSync(pidFile)) {
-    console.log(t('status.notRunning'));
+    if (!reportPortOwner(await probePortOwner(), cfg.serverPort)) {
+      console.log(t('status.notRunning'));
+    }
     return;
   }
 
@@ -328,8 +461,6 @@ function showStatus() {
 
   try {
     process.kill(pid, 0);
-    const config = loadConfig();
-    const cfg = getConfig(config);
     console.log(t('status.running', { pid }));
     console.log(t('status.server', { url: `http://localhost:${cfg.serverPort}` }));
     console.log(t('status.engine', { url: `http://localhost:${cfg.selfEnginePort}` }));
@@ -340,6 +471,7 @@ function showStatus() {
   } catch (e) {
     console.log(t('status.stale'));
     fs.unlinkSync(pidFile);
+    reportPortOwner(await probePortOwner(), cfg.serverPort);
   }
 }
 
@@ -374,19 +506,23 @@ function buildHttpError(res, data) {
   return new Error(snippet ? `HTTP ${statusText}: ${snippet}` : t('error.httpNoBody', { status: statusText }));
 }
 
-function postJson(path, body) {
+// `options.port` / `options.headers` address the engine's own listener when it
+// is split from the orchestrator (`lss reset`); everything else talks to the
+// orchestrator API on serverPort.
+function postJson(path, body, options = {}) {
   return new Promise((resolve, reject) => {
     const http = require('http');
     const payload = JSON.stringify(body || {});
     const req = http.request(
       {
         hostname: 'localhost',
-        port: getServerPort(),
+        port: options.port || getServerPort(),
         path,
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
           'Content-Length': Buffer.byteLength(payload),
+          ...options.headers,
         },
       },
       res => {
@@ -617,6 +753,47 @@ async function clearSeed(tableName) {
   }
 }
 
+/**
+ * `lss reset` — wipe every emulator's state (tables, queues, buckets, topics,
+ * rules, secrets, collections…) in the running engine, without restarting it.
+ *
+ * Talks to the engine's own `POST /_lss/reset`, on selfEnginePort: that is the
+ * shared port by default, and the engine's separate listener when the two are
+ * split. Registered services stay registered — `lss register` re-provisions
+ * their resources. Asks for the same `confirmar` token as seed:clear.
+ */
+async function resetEngine() {
+  ensureRunningOrExit();
+  const cfg = getConfig(loadConfig());
+  const engineUrl = `http://localhost:${cfg.selfEnginePort}`;
+  console.log(t('clear.warning'));
+  console.log(t('reset.target'));
+  console.log(t('clear.engine', { url: engineUrl }));
+  console.log(t('clear.noAws'));
+  console.log('');
+
+  if (process.argv.includes('--yes') || process.argv.includes('-y')) {
+    console.log(t('clear.skipPrompt'));
+  } else {
+    const ok = await promptConfirmation('confirmar');
+    if (!ok) {
+      console.log(t('seed.aborted'));
+      return;
+    }
+  }
+
+  try {
+    const res = await postJson('/_lss/reset', {}, {
+      port: cfg.selfEnginePort,
+      headers: { 'x-lss-confirm-reset': 'true' },
+    });
+    console.log(t(res.persistence ? 'reset.donePersistent' : 'reset.done'));
+  } catch (e) {
+    console.error(t('reset.failed'), formatError(e));
+    process.exit(1);
+  }
+}
+
 /**
  * `lss mcp` — run the Model Context Protocol server on stdio.
  *
@@ -636,6 +813,10 @@ async function clearSeed(tableName) {
 async function registerServices(paths) {
   ensureRunningOrExit();
   const targets = paths.length > 0 ? paths : ['.'];
+  // `autoPackage` only packages when the template is MISSING, so on a service
+  // already packaged once `register` faithfully re-registers whatever is on
+  // disk. `--repackage` is how the operator says "build first, then register".
+  const repackage = process.argv.includes('--repackage');
   let failed = 0;
   for (const target of targets) {
     const servicePath = path.resolve(target);
@@ -645,7 +826,7 @@ async function registerServices(paths) {
       continue;
     }
     try {
-      const result = await postJson('/api/services/register', { servicePath });
+      const result = await postJson('/api/services/register', { servicePath, repackage });
       console.log(t('register.ok', {
         name: result.serviceName,
         resources: result.resourcesCount,
@@ -804,18 +985,22 @@ function showHelp() {
     cmd('scan', 'help.cmd.scan'),
     cmd('register [path...]', 'help.cmd.register'),
     cmd('seed:clear [table]', 'help.cmd.seedClear'),
+    cmd('reset', 'help.cmd.reset'),
     cmd('mcp', 'help.cmd.mcp'),
     cmd('help', 'help.cmd.help'),
     '',
     t('help.options'),
     opt('--config <path>', 'help.opt.config'),
     opt('--enable-dynamo-proxy', 'help.opt.dynamoProxy'),
+    opt('--repackage', 'help.opt.repackage'),
+    opt('--wait[=<seconds>]', 'help.opt.wait'),
     opt('--yes, -y', 'help.opt.yes'),
     '',
     t('help.environment'),
     opt('LSS_DASHBOARD_PORT', 'help.env.dashboardPort'),
     opt('LSS_ENGINE_PORT', 'help.env.enginePort'),
     opt('LSS_ENGINE_DATA_DIR', 'help.env.engineDataDir'),
+    opt('LSS_FALLBACK_ENDPOINT', 'help.env.fallbackEndpoint'),
     opt('AWS_REGION', 'help.env.awsRegion'),
     opt('LSS_LANG', 'help.env.lang'),
     '',
@@ -849,6 +1034,7 @@ function showHelp() {
     helpExample('npx lss seed users', t('help.ex.seedTable')),
     helpExample('npx lss seed:clear users', t('help.ex.seedClear')),
     helpExample('npx lss seed:clear users --yes', t('help.ex.seedClearYes')),
+    helpExample('npx lss reset --yes', t('help.ex.reset')),
     '',
   ].join('\n'));
 }
@@ -925,6 +1111,7 @@ module.exports = {
   showLogs,
   runSeed,
   clearSeed,
+  resetEngine,
   showHelp,
 };
 
@@ -950,6 +1137,9 @@ if (require.main === module) {
     case 'seed:clear':
       clearSeed(firstPositional());
       break;
+    case 'reset':
+      resetEngine();
+      break;
     case 'register':
       registerServices(allPositionals());
       break;

package/bin/i18n.js

@@ -43,13 +43,18 @@ function detectLocale(env = process.env) {
 const MESSAGES = {
   en: {
     'scan.warning.not-installed': 'dependencies not installed — packaging needs an install first',
+    // Two codes for one fact, because the fact depends on `autoPackage`: the
+    // single string that promised packaging was read as a promise by operators
+    // whose config had it off, and registering answered 400 instead.
     'scan.warning.not-packaged': 'not packaged yet — registering packages it for you (autoPackage)',
+    'scan.warning.not-packaged-manual': 'not packaged yet — autoPackage is off, so run `serverless package` before registering',
     'scan.warning.ts-config': 'TypeScript service config — name, region and ports resolve at packaging time',
     'scan.warning.unreadable-config': 'could not read {file}',
     'scan.warning.invalid-json': 'serverless.json is not valid JSON',
     // --- config discovery --------------------------------------------------
     'config.parseFailed': '⚠️  Failed to parse config file {path}',
-    'config.notFound': '⚠️  Config file not found: {path}',
+    'config.explicitNotFound': '❌ Config file not found: {path} (given by --config / LSS_CONFIG). Not falling back to the default config search — it could address a different instance.',
+    'config.explicitParseFailed': '❌ Could not parse config file {path} (given by --config / LSS_CONFIG): {error}',
 
     // --- lifecycle ---------------------------------------------------------
     'start.already': '⚠️  LSS Orchestrator is already running (PID: {pid})',
@@ -61,6 +66,9 @@ const MESSAGES = {
     'start.logs': '📝 Logs: {path}',
     'start.running': '✅ Service is running',
     'start.failed': '❌ Service failed to start. Check logs: {path}',
+    'start.waiting': '⏳ Waiting for the orchestrator to answer (up to {seconds}s)...',
+    'start.waitTimeout': '❌ The orchestrator did not answer within {seconds}s',
+    'start.logTail': '--- last lines of the log ---',
     'start.notBuilt': '❌ Orchestrator not found or not built.',
     'start.notBuiltDev': 'If you are developing LSS, run:',
     'start.notBuiltBug': 'If you installed via npm, please report this as a bug.',
@@ -75,6 +83,11 @@ const MESSAGES = {
     'status.engine': '   Self Engine: {url}',
     'status.dynamoProxy': '   DynamoDB Proxy: {url}',
     'status.logs': '   Logs: {path}',
+    // A port answering from another checkout is the routine outcome under
+    // `--net=host`, and reporting it as NOT RUNNING sent people looking in the
+    // wrong place. `projectRoot` comes from GET /api/config on that port.
+    'status.portOwnedByOther': '🔶 Port {port} is in use by the orchestrator of {root}',
+    'status.portAnsweringHere': '🔶 Port {port} answers for this project, but no PID file is registered here (started from another shell?)',
     'logs.missing': '⚠️  No log file at {path}',
     'logs.from': '📝 Logs from: {path}',
 
@@ -142,6 +155,10 @@ const MESSAGES = {
     'clear.skipPrompt': '↳ --yes given, skipping the interactive confirmation.',
     'clear.listFailed': '❌ Could not list the tables before clearing:',
     'clear.failed': '❌ Clear failed:',
+    'reset.target': '   Target:    ALL engine state — tables, queues, buckets, topics, rules, secrets, collections',
+    'reset.done': '✅ Engine reset: every emulator is empty. Run `lss register` to re-provision your services\' resources.',
+    'reset.donePersistent': '✅ Engine reset: every emulator is empty and its data directory was wiped. Run `lss register` to re-provision your services\' resources.',
+    'reset.failed': '❌ Reset failed:',
 
     // --- mcp ---------------------------------------------------------------
     'mcp.missing': '❌ MCP server build not found. Run `npm run build` first.',
@@ -165,14 +182,18 @@ const MESSAGES = {
     'help.cmd.scan': 'List every Serverless/osls service found under the project root (registered/installed/packaged flags, ports and package command)',
     'help.cmd.register': 'Register services with the running orchestrator (defaults to the current directory; packaging runs on demand via autoPackage)',
     'help.cmd.seedClear': 'Delete every item from the given table (or from every table that has a seed file). Asks for interactive confirmation (type "confirmar") before any write.',
+    'help.cmd.reset': 'Wipe ALL engine state (every table, queue, bucket, topic, rule, secret and collection) without restarting. Asks for interactive confirmation (type "confirmar").',
     'help.cmd.mcp': 'Run the Model Context Protocol server on stdio, so an MCP client can drive this stack with tools. Requires a running orchestrator; see docs/MCP.md.',
     'help.cmd.help': 'Show this help message',
     'help.opt.config': '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.',
     'help.opt.dynamoProxy': 'Enable the DynamoDB proxy on port 8000 (for the start command)',
+    'help.opt.repackage': 'On register, run the service packaging command before reading the artifacts, even when they already exist. autoPackage only covers the missing-template case, so this is what loads code you just edited. Without it, register warns when the package predates the sources but still registers what is on disk.',
+    'help.opt.wait': 'On start, block until the orchestrator answers GET /api/health (default 30s) and exit non-zero — with the log tail — if it never does. What a sequential chain needs so the next step is not run against a stack that is not up.',
     'help.opt.yes': 'Skip the interactive confirmation on seed:clear (use only in CI)',
     'help.env.dashboardPort': 'Orchestrator port (overrides serverPort)',
     'help.env.enginePort': 'Self engine port (overrides selfEngine.port)',
     'help.env.engineDataDir': 'Self engine state directory (overrides selfEngine.dataDir)',
+    'help.env.fallbackEndpoint': 'Forward AWS services the engine does not emulate to this endpoint (overrides selfEngine.fallbackEndpoint)',
     'help.env.awsRegion': 'Default region for provisioning and the explorers',
     'help.env.lang': 'CLI language: en, pt-BR or es (falls back to LC_ALL/LC_MESSAGES/LANG)',
     'help.config.intro': 'Create a lss.config.json or .lssrc file in your project root to customize:',
@@ -190,16 +211,19 @@ const MESSAGES = {
     'help.ex.seedTable': 'Seed only the "users" table',
     'help.ex.seedClear': 'Delete every item from "users" (with confirmation)',
     'help.ex.seedClearYes': 'Same thing, without the prompt (CI)',
+    'help.ex.reset': 'Empty every emulator, without the prompt (CI)',
   },
 
   'pt-BR': {
     'scan.warning.not-installed': 'dependências não instaladas — empacotar exige instalar antes',
     'scan.warning.not-packaged': 'ainda não empacotado — registrar empacota para você (autoPackage)',
+    'scan.warning.not-packaged-manual': 'ainda não empacotado — autoPackage está desligado, rode `serverless package` antes de registrar',
     'scan.warning.ts-config': 'config em TypeScript — nome, região e portas só resolvem no empacotamento',
     'scan.warning.unreadable-config': 'não consegui ler {file}',
     'scan.warning.invalid-json': 'serverless.json não é um JSON válido',
     'config.parseFailed': '⚠️  Não consegui ler o arquivo de config {path}',
-    'config.notFound': '⚠️  Arquivo de config não encontrado: {path}',
+    'config.explicitNotFound': '❌ Arquivo de config não encontrado: {path} (informado por --config / LSS_CONFIG). Sem fallback para a busca padrão de config — ela poderia apontar para outra instância.',
+    'config.explicitParseFailed': '❌ Não consegui ler o arquivo de config {path} (informado por --config / LSS_CONFIG): {error}',
 
     'start.already': '⚠️  O orquestrador LSS já está rodando (PID: {pid})',
     'start.starting': '🚀 Iniciando o orquestrador LSS...',
@@ -210,6 +234,9 @@ const MESSAGES = {
     'start.logs': '📝 Logs: {path}',
     'start.running': '✅ Serviço no ar',
     'start.failed': '❌ O serviço não subiu. Veja os logs: {path}',
+    'start.waiting': '⏳ Esperando o orquestrador responder (até {seconds}s)...',
+    'start.waitTimeout': '❌ O orquestrador não respondeu em {seconds}s',
+    'start.logTail': '--- últimas linhas do log ---',
     'start.notBuilt': '❌ Orquestrador não encontrado ou sem build.',
     'start.notBuiltDev': 'Se você está desenvolvendo o LSS, rode:',
     'start.notBuiltBug': 'Se você instalou via npm, por favor abra um bug.',
@@ -224,6 +251,8 @@ const MESSAGES = {
     'status.engine': '   Self Engine: {url}',
     'status.dynamoProxy': '   Proxy DynamoDB: {url}',
     'status.logs': '   Logs: {path}',
+    'status.portOwnedByOther': '🔶 A porta {port} está em uso pelo orquestrador de {root}',
+    'status.portAnsweringHere': '🔶 A porta {port} responde por este projeto, mas não há arquivo de PID registrado aqui (subiu de outro shell?)',
     'logs.missing': '⚠️  Nenhum arquivo de log em {path}',
     'logs.from': '📝 Logs de: {path}',
 
@@ -285,6 +314,10 @@ const MESSAGES = {
     'clear.skipPrompt': '↳ --yes informado, pulando a confirmação interativa.',
     'clear.listFailed': '❌ Não consegui listar as tabelas antes de limpar:',
     'clear.failed': '❌ A limpeza falhou:',
+    'reset.target': '   Alvo:      TODO o estado do engine — tabelas, filas, buckets, tópicos, regras, secrets, coleções',
+    'reset.done': '✅ Engine resetado: todos os emuladores estão vazios. Rode `lss register` para reprovisionar os recursos dos seus serviços.',
+    'reset.donePersistent': '✅ Engine resetado: todos os emuladores estão vazios e o diretório de dados foi apagado. Rode `lss register` para reprovisionar os recursos dos seus serviços.',
+    'reset.failed': '❌ O reset falhou:',
 
     'mcp.missing': '❌ Build do servidor MCP não encontrado. Rode `npm run build` antes.',
     'mcp.startFailed': '❌ Não consegui subir o servidor MCP:',
@@ -304,14 +337,18 @@ const MESSAGES = {
     'help.cmd.scan': 'Lista todo serviço Serverless/osls encontrado sob a raiz do projeto (flags registrado/instalado/empacotado, portas e comando de package)',
     'help.cmd.register': 'Registra serviços no orquestrador que está rodando (usa o diretório atual por padrão; o empacotamento roda sob demanda via autoPackage)',
     'help.cmd.seedClear': 'Apaga todos os itens da tabela informada (ou de todas as tabelas com arquivo de seed). Pede confirmação interativa (digitar "confirmar") antes de qualquer escrita.',
+    'help.cmd.reset': 'Apaga TODO o estado do engine (todas as tabelas, filas, buckets, tópicos, regras, secrets e coleções) sem reiniciar. Pede confirmação interativa (digitar "confirmar").',
     'help.cmd.mcp': 'Roda o servidor Model Context Protocol no stdio, para um cliente MCP dirigir esta stack com tools. Precisa do orquestrador rodando; veja docs/MCP.md.',
     'help.cmd.help': 'Mostra esta ajuda',
     'help.opt.config': 'Carrega a config deste arquivo (tem precedência sobre a busca em cwd/home). Vale para start/stop/status/logs, então dá para endereçar uma instância isolada sem entrar na pasta dela.',
     'help.opt.dynamoProxy': 'Liga o proxy DynamoDB na porta 8000 (para o comando start)',
+    'help.opt.repackage': 'No register, roda o comando de empacotamento do serviço antes de ler os artefatos, mesmo que eles já existam. O autoPackage só cobre o caso de template ausente, então é isto que carrega o código que você acabou de editar. Sem a flag, o register avisa quando o pacote é anterior às fontes, mas registra o que está no disco.',
+    'help.opt.wait': 'No start, bloqueia até o orquestrador responder GET /api/health (padrão 30s) e sai com código diferente de zero — mostrando o fim do log — se ele não responder. É o que uma cadeia sequencial precisa para não rodar o passo seguinte contra um stack que não subiu.',
     'help.opt.yes': 'Pula a confirmação interativa do seed:clear (use só em CI)',
     'help.env.dashboardPort': 'Porta do orquestrador (sobrepõe serverPort)',
     'help.env.enginePort': 'Porta do self engine (sobrepõe selfEngine.port)',
     'help.env.engineDataDir': 'Diretório de estado do self engine (sobrepõe selfEngine.dataDir)',
+    'help.env.fallbackEndpoint': 'Encaminha para este endpoint os serviços AWS que o engine não emula (sobrepõe selfEngine.fallbackEndpoint)',
     'help.env.awsRegion': 'Região padrão para o provisionamento e para os explorers',
     'help.env.lang': 'Idioma da CLI: en, pt-BR ou es (cai para LC_ALL/LC_MESSAGES/LANG)',
     'help.config.intro': 'Crie um lss.config.json ou .lssrc na raiz do projeto para customizar:',
@@ -329,16 +366,19 @@ const MESSAGES = {
     'help.ex.seedTable': 'Semeia só a tabela "users"',
     'help.ex.seedClear': 'Apaga todos os itens de "users" (com confirmação)',
     'help.ex.seedClearYes': 'Mesma coisa, sem prompt (CI)',
+    'help.ex.reset': 'Esvazia todos os emuladores, sem prompt (CI)',
   },
 
   es: {
     'scan.warning.not-installed': 'dependencias sin instalar — empaquetar requiere instalarlas antes',
     'scan.warning.not-packaged': 'aún sin empaquetar — registrar lo empaqueta por ti (autoPackage)',
+    'scan.warning.not-packaged-manual': 'aún sin empaquetar — autoPackage está desactivado, ejecuta `serverless package` antes de registrar',
     'scan.warning.ts-config': 'config en TypeScript — nombre, región y puertos se resuelven al empaquetar',
     'scan.warning.unreadable-config': 'no se pudo leer {file}',
     'scan.warning.invalid-json': 'serverless.json no es un JSON válido',
     'config.parseFailed': '⚠️  No se pudo leer el archivo de configuración {path}',
-    'config.notFound': '⚠️  Archivo de configuración no encontrado: {path}',
+    'config.explicitNotFound': '❌ Archivo de configuración no encontrado: {path} (indicado por --config / LSS_CONFIG). Sin recurrir a la búsqueda de configuración por defecto — podría apuntar a otra instancia.',
+    'config.explicitParseFailed': '❌ No se pudo leer el archivo de configuración {path} (indicado por --config / LSS_CONFIG): {error}',
 
     'start.already': '⚠️  El orquestador LSS ya está en marcha (PID: {pid})',
     'start.starting': '🚀 Iniciando el orquestador LSS...',
@@ -349,6 +389,9 @@ const MESSAGES = {
     'start.logs': '📝 Registros: {path}',
     'start.running': '✅ El servicio está en marcha',
     'start.failed': '❌ El servicio no arrancó. Revisa los registros: {path}',
+    'start.waiting': '⏳ Esperando a que el orquestador responda (hasta {seconds}s)...',
+    'start.waitTimeout': '❌ El orquestador no respondió en {seconds}s',
+    'start.logTail': '--- últimas líneas del registro ---',
     'start.notBuilt': '❌ Orquestador no encontrado o sin compilar.',
     'start.notBuiltDev': 'Si estás desarrollando LSS, ejecuta:',
     'start.notBuiltBug': 'Si lo instalaste con npm, por favor repórtalo como un bug.',
@@ -363,6 +406,8 @@ const MESSAGES = {
     'status.engine': '   Self Engine: {url}',
     'status.dynamoProxy': '   Proxy de DynamoDB: {url}',
     'status.logs': '   Registros: {path}',
+    'status.portOwnedByOther': '🔶 El puerto {port} lo ocupa el orquestador de {root}',
+    'status.portAnsweringHere': '🔶 El puerto {port} responde por este proyecto, pero no hay archivo PID registrado aquí (¿arrancó desde otra terminal?)',
     'logs.missing': '⚠️  No hay archivo de registro en {path}',
     'logs.from': '📝 Registros de: {path}',
 
@@ -424,6 +469,10 @@ const MESSAGES = {
     'clear.skipPrompt': '↳ --yes indicado, saltando la confirmación interactiva.',
     'clear.listFailed': '❌ No se pudieron listar las tablas antes de vaciar:',
     'clear.failed': '❌ El vaciado falló:',
+    'reset.target': '   Objetivo:  TODO el estado del engine — tablas, colas, buckets, tópicos, reglas, secrets, colecciones',
+    'reset.done': '✅ Engine reiniciado: todos los emuladores están vacíos. Ejecuta `lss register` para reaprovisionar los recursos de tus servicios.',
+    'reset.donePersistent': '✅ Engine reiniciado: todos los emuladores están vacíos y su directorio de datos se borró. Ejecuta `lss register` para reaprovisionar los recursos de tus servicios.',
+    'reset.failed': '❌ El reinicio falló:',
 
     'mcp.missing': '❌ No se encontró el build del servidor MCP. Ejecuta `npm run build` primero.',
     'mcp.startFailed': '❌ No se pudo iniciar el servidor MCP:',
@@ -443,14 +492,18 @@ const MESSAGES = {
     'help.cmd.scan': 'Lista cada servicio Serverless/osls encontrado bajo la raíz del proyecto (banderas registrado/instalado/empaquetado, puertos y comando de package)',
     'help.cmd.register': 'Registra servicios en el orquestador en marcha (usa el directorio actual por defecto; el empaquetado corre a demanda con autoPackage)',
     'help.cmd.seedClear': 'Elimina todos los ítems de la tabla indicada (o de todas las tablas con archivo de seed). Pide confirmación interactiva (escribir "confirmar") antes de cualquier escritura.',
+    'help.cmd.reset': 'Borra TODO el estado del engine (todas las tablas, colas, buckets, tópicos, reglas, secrets y colecciones) sin reiniciar. Pide confirmación interactiva (escribir "confirmar").',
     'help.cmd.mcp': 'Ejecuta el servidor Model Context Protocol en stdio, para que un cliente MCP maneje este stack con tools. Requiere el orquestador en marcha; mira docs/MCP.md.',
     'help.cmd.help': 'Muestra esta ayuda',
     'help.opt.config': 'Carga la configuración de este archivo (tiene precedencia sobre la búsqueda en cwd/home). Aplica a start/stop/status/logs, así una instancia aislada se puede direccionar sin entrar a su carpeta.',
     'help.opt.dynamoProxy': 'Habilita el proxy de DynamoDB en el puerto 8000 (para el comando start)',
+    'help.opt.repackage': 'En register, ejecuta el comando de empaquetado del servicio antes de leer los artefactos, aunque ya existan. autoPackage sólo cubre el caso de plantilla ausente, así que esto es lo que carga el código que acabas de editar. Sin la bandera, register avisa cuando el paquete es anterior a las fuentes, pero registra lo que está en el disco.',
+    'help.opt.wait': 'En start, bloquea hasta que el orquestador responda GET /api/health (30s por defecto) y sale con código distinto de cero — mostrando el final del registro — si no responde. Es lo que necesita una cadena secuencial para no ejecutar el paso siguiente contra un stack que no arrancó.',
     'help.opt.yes': 'Salta la confirmación interactiva de seed:clear (úsalo solo en CI)',
     'help.env.dashboardPort': 'Puerto del orquestador (sobrescribe serverPort)',
     'help.env.enginePort': 'Puerto del self engine (sobrescribe selfEngine.port)',
     'help.env.engineDataDir': 'Directorio de estado del self engine (sobrescribe selfEngine.dataDir)',
+    'help.env.fallbackEndpoint': 'Redirige a este endpoint los servicios AWS que el engine no emula (sobrescribe selfEngine.fallbackEndpoint)',
     'help.env.awsRegion': 'Región por defecto para el aprovisionamiento y los exploradores',
     'help.env.lang': 'Idioma de la CLI: en, pt-BR o es (cae a LC_ALL/LC_MESSAGES/LANG)',
     'help.config.intro': 'Crea un lss.config.json o .lssrc en la raíz del proyecto para personalizar:',
@@ -468,6 +521,7 @@ const MESSAGES = {
     'help.ex.seedTable': 'Siembra solo la tabla "users"',
     'help.ex.seedClear': 'Elimina todos los ítems de "users" (con confirmación)',
     'help.ex.seedClearYes': 'Lo mismo, sin prompt (CI)',
+    'help.ex.reset': 'Vacía todos los emuladores, sin prompt (CI)',
   },
 };
 

package/dist/client/index.d.ts

@@ -41,7 +41,7 @@ export type { ConfigApi } from './namespaces/config';
 export type { HealthApi } from './namespaces/health';
 export type { LambdasApi, LambdaSummary, LambdaDetail, InvokeLambdaInput, InvokeLambdaResult, LambdaInvocationRecord, } from './namespaces/lambdas';
 export type { ApisApi, ServiceApiInfo, ApiRouteInfo, ApiAuthorizerInfo, GatewayListenerStatus, } from './namespaces/apis';
-export type { ServiceRuntimeStatus } from './namespaces/services';
+export type { ServiceRuntimeStatus, ServiceGraph, ServiceGraphNode, ServiceGraphEdge, ServiceGraphNodeKind, ServiceGraphEdgeKind, } from './namespaces/services';
 export type { LifecycleApi, StartOptions, StartResult, StopResult, StatusResult, LogsResult, WaitUntilReadyOptions, } from './lifecycle';
 export type * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}